diff --git a/codex-rs/agent-graph-store/src/error.rs b/codex-rs/agent-graph-store/src/error.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ddd8eeef380d4446baf8dd430ec1f984cc3e1ddd
--- /dev/null
+++ b/codex-rs/agent-graph-store/src/error.rs
@@ -0,0 +1,20 @@
+/// Result type returned by agent graph store operations.
+pub type AgentGraphStoreResult<T> = Result<T, AgentGraphStoreError>;
+
+/// Error type shared by agent graph store implementations.
+#[derive(Debug, thiserror::Error)]
+pub enum AgentGraphStoreError {
+    /// The caller supplied invalid request data.
+    #[error("invalid agent graph store request: {message}")]
+    InvalidRequest {
+        /// User-facing explanation of the invalid request.
+        message: String,
+    },
+
+    /// Catch-all for implementation failures that do not fit a more specific category.
+    #[error("agent graph store internal error: {message}")]
+    Internal {
+        /// User-facing explanation of the implementation failure.
+        message: String,
+    },
+}
diff --git a/codex-rs/agent-graph-store/src/lib.rs b/codex-rs/agent-graph-store/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d5f40331b255f509349a13e8e70e8ccfa1ebf5bf
--- /dev/null
+++ b/codex-rs/agent-graph-store/src/lib.rs
@@ -0,0 +1,13 @@
+//! Storage-neutral parent/child topology for thread-spawned agents.
+
+mod error;
+mod local;
+mod store;
+mod types;
+
+pub use error::AgentGraphStoreError;
+pub use error::AgentGraphStoreResult;
+pub use local::LocalAgentGraphStore;
+pub use store::AgentGraphStore;
+pub use store::AgentGraphStoreFuture;
+pub use types::ThreadSpawnEdgeStatus;
diff --git a/codex-rs/agent-graph-store/src/local.rs b/codex-rs/agent-graph-store/src/local.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a7c1fd4a3395e9070f65cf7cbeff45f402c0f255
--- /dev/null
+++ b/codex-rs/agent-graph-store/src/local.rs
@@ -0,0 +1,344 @@
+use codex_protocol::ThreadId;
+use codex_state::StateRuntime;
+use std::sync::Arc;
+
+use crate::AgentGraphStore;
+use crate::AgentGraphStoreError;
+use crate::AgentGraphStoreFuture;
+use crate::ThreadSpawnEdgeStatus;
+
+/// SQLite-backed implementation of [`AgentGraphStore`] using an existing state runtime.
+#[derive(Clone)]
+pub struct LocalAgentGraphStore {
+    state_db: Arc<StateRuntime>,
+}
+
+impl std::fmt::Debug for LocalAgentGraphStore {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LocalAgentGraphStore")
+            .field("sqlite", self.state_db.sqlite())
+            .finish_non_exhaustive()
+    }
+}
+
+impl LocalAgentGraphStore {
+    /// Create a local graph store from an already-initialized state runtime.
+    pub fn new(state_db: Arc<StateRuntime>) -> Self {
+        Self { state_db }
+    }
+}
+
+impl AgentGraphStore for LocalAgentGraphStore {
+    fn upsert_thread_spawn_edge(
+        &self,
+        parent_thread_id: ThreadId,
+        child_thread_id: ThreadId,
+        status: ThreadSpawnEdgeStatus,
+    ) -> AgentGraphStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state_db
+                .upsert_thread_spawn_edge(
+                    parent_thread_id,
+                    child_thread_id,
+                    to_state_status(status),
+                )
+                .await
+                .map_err(internal_error)
+        })
+    }
+
+    fn set_thread_spawn_edge_status(
+        &self,
+        child_thread_id: ThreadId,
+        status: ThreadSpawnEdgeStatus,
+    ) -> AgentGraphStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state_db
+                .set_thread_spawn_edge_status(child_thread_id, to_state_status(status))
+                .await
+                .map_err(internal_error)
+        })
+    }
+
+    fn list_thread_spawn_children(
+        &self,
+        parent_thread_id: ThreadId,
+        status_filter: Option<ThreadSpawnEdgeStatus>,
+    ) -> AgentGraphStoreFuture<'_, Vec<ThreadId>> {
+        Box::pin(async move {
+            if let Some(status) = status_filter {
+                return self
+                    .state_db
+                    .list_thread_spawn_children_with_status(
+                        parent_thread_id,
+                        to_state_status(status),
+                    )
+                    .await
+                    .map_err(internal_error);
+            }
+
+            self.state_db
+                .list_thread_spawn_children(parent_thread_id)
+                .await
+                .map_err(internal_error)
+        })
+    }
+
+    fn list_thread_spawn_descendants(
+        &self,
+        root_thread_id: ThreadId,
+        status_filter: Option<ThreadSpawnEdgeStatus>,
+    ) -> AgentGraphStoreFuture<'_, Vec<ThreadId>> {
+        Box::pin(async move {
+            match status_filter {
+                Some(status) => self
+                    .state_db
+                    .list_thread_spawn_descendants_with_status(
+                        root_thread_id,
+                        to_state_status(status),
+                    )
+                    .await
+                    .map_err(internal_error),
+                None => self
+                    .state_db
+                    .list_thread_spawn_descendants(root_thread_id)
+                    .await
+                    .map_err(internal_error),
+            }
+        })
+    }
+}
+
+fn to_state_status(status: ThreadSpawnEdgeStatus) -> codex_state::DirectionalThreadSpawnEdgeStatus {
+    match status {
+        ThreadSpawnEdgeStatus::Open => codex_state::DirectionalThreadSpawnEdgeStatus::Open,
+        ThreadSpawnEdgeStatus::Closed => codex_state::DirectionalThreadSpawnEdgeStatus::Closed,
+    }
+}
+
+fn internal_error(err: impl std::fmt::Display) -> AgentGraphStoreError {
+    AgentGraphStoreError::Internal {
+        message: err.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_state::DirectionalThreadSpawnEdgeStatus;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+
+    struct TestRuntime {
+        state_db: Arc<StateRuntime>,
+        _codex_home: TempDir,
+    }
+
+    fn thread_id(suffix: u128) -> ThreadId {
+        ThreadId::from_string(&format!("00000000-0000-0000-0000-{suffix:012}"))
+            .expect("valid thread id")
+    }
+
+    async fn state_runtime() -> TestRuntime {
+        let codex_home = TempDir::new().expect("tempdir should be created");
+        let state_db = StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(codex_home.path().abs()),
+            "test-provider".to_string(),
+        )
+        .await
+        .expect("state db should initialize");
+        TestRuntime {
+            state_db,
+            _codex_home: codex_home,
+        }
+    }
+
+    #[tokio::test]
+    async fn local_store_upserts_and_lists_direct_children_with_status_filters() {
+        let fixture = state_runtime().await;
+        let state_db = fixture.state_db;
+        let store = LocalAgentGraphStore::new(state_db.clone());
+        let parent_thread_id = thread_id(/*suffix*/ 1);
+        let first_child_thread_id = thread_id(/*suffix*/ 2);
+        let second_child_thread_id = thread_id(/*suffix*/ 3);
+
+        store
+            .upsert_thread_spawn_edge(
+                parent_thread_id,
+                second_child_thread_id,
+                ThreadSpawnEdgeStatus::Closed,
+            )
+            .await
+            .expect("closed child edge should insert");
+        store
+            .upsert_thread_spawn_edge(
+                parent_thread_id,
+                first_child_thread_id,
+                ThreadSpawnEdgeStatus::Open,
+            )
+            .await
+            .expect("open child edge should insert");
+
+        let all_children = store
+            .list_thread_spawn_children(parent_thread_id, /*status_filter*/ None)
+            .await
+            .expect("all children should load");
+        assert_eq!(
+            all_children,
+            vec![first_child_thread_id, second_child_thread_id]
+        );
+
+        let open_children = store
+            .list_thread_spawn_children(parent_thread_id, Some(ThreadSpawnEdgeStatus::Open))
+            .await
+            .expect("open children should load");
+        let state_open_children = state_db
+            .list_thread_spawn_children_with_status(
+                parent_thread_id,
+                DirectionalThreadSpawnEdgeStatus::Open,
+            )
+            .await
+            .expect("state open children should load");
+        assert_eq!(open_children, state_open_children);
+        assert_eq!(open_children, vec![first_child_thread_id]);
+
+        let closed_children = store
+            .list_thread_spawn_children(parent_thread_id, Some(ThreadSpawnEdgeStatus::Closed))
+            .await
+            .expect("closed children should load");
+        assert_eq!(closed_children, vec![second_child_thread_id]);
+    }
+
+    #[tokio::test]
+    async fn local_store_updates_edge_status() {
+        let fixture = state_runtime().await;
+        let state_db = fixture.state_db;
+        let store = LocalAgentGraphStore::new(state_db);
+        let parent_thread_id = thread_id(/*suffix*/ 10);
+        let child_thread_id = thread_id(/*suffix*/ 11);
+
+        store
+            .upsert_thread_spawn_edge(
+                parent_thread_id,
+                child_thread_id,
+                ThreadSpawnEdgeStatus::Open,
+            )
+            .await
+            .expect("child edge should insert");
+        store
+            .set_thread_spawn_edge_status(child_thread_id, ThreadSpawnEdgeStatus::Closed)
+            .await
+            .expect("child edge should close");
+
+        let open_children = store
+            .list_thread_spawn_children(parent_thread_id, Some(ThreadSpawnEdgeStatus::Open))
+            .await
+            .expect("open children should load");
+        assert_eq!(open_children, Vec::<ThreadId>::new());
+
+        let closed_children = store
+            .list_thread_spawn_children(parent_thread_id, Some(ThreadSpawnEdgeStatus::Closed))
+            .await
+            .expect("closed children should load");
+        assert_eq!(closed_children, vec![child_thread_id]);
+    }
+
+    #[tokio::test]
+    async fn local_store_lists_descendants_breadth_first_with_status_filters() {
+        let fixture = state_runtime().await;
+        let state_db = fixture.state_db;
+        let store = LocalAgentGraphStore::new(state_db.clone());
+        let root_thread_id = thread_id(/*suffix*/ 20);
+        let later_child_thread_id = thread_id(/*suffix*/ 22);
+        let earlier_child_thread_id = thread_id(/*suffix*/ 21);
+        let closed_grandchild_thread_id = thread_id(/*suffix*/ 23);
+        let open_grandchild_thread_id = thread_id(/*suffix*/ 24);
+        let closed_child_thread_id = thread_id(/*suffix*/ 25);
+        let closed_great_grandchild_thread_id = thread_id(/*suffix*/ 26);
+
+        for (parent_thread_id, child_thread_id, status) in [
+            (
+                root_thread_id,
+                later_child_thread_id,
+                ThreadSpawnEdgeStatus::Open,
+            ),
+            (
+                root_thread_id,
+                earlier_child_thread_id,
+                ThreadSpawnEdgeStatus::Open,
+            ),
+            (
+                earlier_child_thread_id,
+                open_grandchild_thread_id,
+                ThreadSpawnEdgeStatus::Open,
+            ),
+            (
+                later_child_thread_id,
+                closed_grandchild_thread_id,
+                ThreadSpawnEdgeStatus::Closed,
+            ),
+            (
+                root_thread_id,
+                closed_child_thread_id,
+                ThreadSpawnEdgeStatus::Closed,
+            ),
+            (
+                closed_child_thread_id,
+                closed_great_grandchild_thread_id,
+                ThreadSpawnEdgeStatus::Closed,
+            ),
+        ] {
+            store
+                .upsert_thread_spawn_edge(parent_thread_id, child_thread_id, status)
+                .await
+                .expect("edge should insert");
+        }
+
+        let all_descendants = store
+            .list_thread_spawn_descendants(root_thread_id, /*status_filter*/ None)
+            .await
+            .expect("all descendants should load");
+        assert_eq!(
+            all_descendants,
+            vec![
+                earlier_child_thread_id,
+                later_child_thread_id,
+                closed_child_thread_id,
+                closed_grandchild_thread_id,
+                open_grandchild_thread_id,
+                closed_great_grandchild_thread_id,
+            ]
+        );
+
+        let open_descendants = store
+            .list_thread_spawn_descendants(root_thread_id, Some(ThreadSpawnEdgeStatus::Open))
+            .await
+            .expect("open descendants should load");
+        let state_open_descendants = state_db
+            .list_thread_spawn_descendants_with_status(
+                root_thread_id,
+                DirectionalThreadSpawnEdgeStatus::Open,
+            )
+            .await
+            .expect("state open descendants should load");
+        assert_eq!(open_descendants, state_open_descendants);
+        assert_eq!(
+            open_descendants,
+            vec![
+                earlier_child_thread_id,
+                later_child_thread_id,
+                open_grandchild_thread_id,
+            ]
+        );
+
+        let closed_descendants = store
+            .list_thread_spawn_descendants(root_thread_id, Some(ThreadSpawnEdgeStatus::Closed))
+            .await
+            .expect("closed descendants should load");
+        assert_eq!(
+            closed_descendants,
+            vec![closed_child_thread_id, closed_great_grandchild_thread_id]
+        );
+    }
+}
diff --git a/codex-rs/agent-graph-store/src/store.rs b/codex-rs/agent-graph-store/src/store.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0760cb15d4ac94cddc58c765d70961e7c46d931c
--- /dev/null
+++ b/codex-rs/agent-graph-store/src/store.rs
@@ -0,0 +1,60 @@
+use std::future::Future;
+use std::pin::Pin;
+
+use codex_protocol::ThreadId;
+
+use crate::AgentGraphStoreResult;
+use crate::ThreadSpawnEdgeStatus;
+
+/// Future returned by [`AgentGraphStore`] operations.
+pub type AgentGraphStoreFuture<'a, T> =
+    Pin<Box<dyn Future<Output = AgentGraphStoreResult<T>> + Send + 'a>>;
+
+/// Storage-neutral boundary for persisted thread-spawn parent/child topology.
+///
+/// Implementations are expected to return stable ordering for list methods so callers can merge
+/// persisted graph state with live in-memory state without introducing nondeterministic output.
+pub trait AgentGraphStore: Send + Sync {
+    /// Insert or replace the directional parent/child edge for a spawned thread.
+    ///
+    /// `child_thread_id` has at most one persisted parent. Re-inserting the same child should
+    /// update both the parent and status to match the supplied values.
+    fn upsert_thread_spawn_edge(
+        &self,
+        parent_thread_id: ThreadId,
+        child_thread_id: ThreadId,
+        status: ThreadSpawnEdgeStatus,
+    ) -> AgentGraphStoreFuture<'_, ()>;
+
+    /// Update the persisted lifecycle status of a spawned thread's incoming edge.
+    ///
+    /// Implementations should treat missing children as a successful no-op.
+    fn set_thread_spawn_edge_status(
+        &self,
+        child_thread_id: ThreadId,
+        status: ThreadSpawnEdgeStatus,
+    ) -> AgentGraphStoreFuture<'_, ()>;
+
+    /// List direct spawned children of a parent thread.
+    ///
+    /// When `status_filter` is `Some`, only child edges with that exact status are returned. When
+    /// it is `None`, all direct child edges are returned regardless of status, including statuses
+    /// that may be added by a future store implementation.
+    fn list_thread_spawn_children(
+        &self,
+        parent_thread_id: ThreadId,
+        status_filter: Option<ThreadSpawnEdgeStatus>,
+    ) -> AgentGraphStoreFuture<'_, Vec<ThreadId>>;
+
+    /// List spawned descendants breadth-first by depth, then by thread id.
+    ///
+    /// `status_filter` is applied to every traversed edge, not just to the returned descendants.
+    /// For example, `Some(Open)` walks only open edges, so descendants under a closed edge are not
+    /// included even if their own incoming edge is open. `None` walks and returns every persisted
+    /// edge regardless of status.
+    fn list_thread_spawn_descendants(
+        &self,
+        root_thread_id: ThreadId,
+        status_filter: Option<ThreadSpawnEdgeStatus>,
+    ) -> AgentGraphStoreFuture<'_, Vec<ThreadId>>;
+}
diff --git a/codex-rs/agent-graph-store/src/types.rs b/codex-rs/agent-graph-store/src/types.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2a9f6caedb6c4e3ba3d07f5bce50c14085db3164
--- /dev/null
+++ b/codex-rs/agent-graph-store/src/types.rs
@@ -0,0 +1,42 @@
+use serde::Deserialize;
+use serde::Serialize;
+
+/// Lifecycle status attached to a directional thread-spawn edge.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ThreadSpawnEdgeStatus {
+    /// The child thread is still live or resumable as an open spawned agent.
+    Open,
+    /// The child thread has been closed from the parent/child graph's perspective.
+    Closed,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn thread_spawn_edge_status_serializes_as_snake_case() {
+        assert_eq!(
+            serde_json::to_string(&ThreadSpawnEdgeStatus::Open)
+                .expect("open status should serialize"),
+            "\"open\""
+        );
+        assert_eq!(
+            serde_json::to_string(&ThreadSpawnEdgeStatus::Closed)
+                .expect("closed status should serialize"),
+            "\"closed\""
+        );
+        assert_eq!(
+            serde_json::from_str::<ThreadSpawnEdgeStatus>("\"open\"")
+                .expect("open status should deserialize"),
+            ThreadSpawnEdgeStatus::Open
+        );
+        assert_eq!(
+            serde_json::from_str::<ThreadSpawnEdgeStatus>("\"closed\"")
+                .expect("closed status should deserialize"),
+            ThreadSpawnEdgeStatus::Closed
+        );
+    }
+}
diff --git a/codex-rs/apply-patch/src/file_update.rs b/codex-rs/apply-patch/src/file_update.rs
new file mode 100644
index 0000000000000000000000000000000000000000..08bb0ebefe2197388562153db4888a89cefe2a53
--- /dev/null
+++ b/codex-rs/apply-patch/src/file_update.rs
@@ -0,0 +1,335 @@
+use codex_exec_server::ExecutorFileSystem;
+use codex_exec_server::FileSystemSandboxContext;
+use codex_exec_server::ReadFileOptions;
+use codex_utils_path_uri::PathUri;
+use similar::TextDiff;
+
+use crate::ApplyPatchError;
+use crate::ApplyPatchFileUpdateMode;
+use crate::IoError;
+use crate::UpdateFileChunk;
+use crate::seek_sequence;
+use crate::text_file::Replacement;
+use crate::text_file::SourceFile;
+
+#[cfg(test)]
+#[path = "file_update_tests.rs"]
+mod tests;
+
+pub(crate) struct AppliedPatch {
+    pub(crate) original_contents: String,
+    pub(crate) new_contents: String,
+}
+
+/// Return *only* the new file contents (joined into a single `String`) after
+/// applying the chunks to the file at `path`.
+pub(crate) async fn derive_new_contents_from_chunks(
+    path: &PathUri,
+    chunks: &[UpdateFileChunk],
+    update_file_mode: ApplyPatchFileUpdateMode,
+    fs: &dyn ExecutorFileSystem,
+    follow_symlinks: bool,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> std::result::Result<AppliedPatch, ApplyPatchError> {
+    let original_contents = fs
+        .read_file_text(path, ReadFileOptions { follow_symlinks }, sandbox)
+        .await
+        .map_err(|err| {
+            ApplyPatchError::IoError(IoError {
+                context: format!(
+                    "Failed to read file to update {}",
+                    path.inferred_native_path_string()
+                ),
+                source: err,
+            })
+        })?;
+
+    let path_text = path.inferred_native_path_string();
+    let new_contents = match update_file_mode {
+        ApplyPatchFileUpdateMode::NormalizeToLf => {
+            let mut original_lines = original_contents
+                .split('\n')
+                .map(String::from)
+                .collect::<Vec<_>>();
+
+            // Drop the trailing empty element that results from the final newline so
+            // that line counts match the behaviour of standard `diff`.
+            if original_lines.last().is_some_and(String::is_empty) {
+                original_lines.pop();
+            }
+
+            let replacements =
+                compute_replacements(&original_lines, &path_text, chunks, update_file_mode)?;
+            let mut new_lines = apply_replacements(original_lines, &replacements);
+            if !new_lines.last().is_some_and(String::is_empty) {
+                new_lines.push(String::new());
+            }
+            new_lines.join("\n")
+        }
+        ApplyPatchFileUpdateMode::PreserveLineEndings => {
+            let mut source_file = SourceFile::parse(&original_contents);
+            let original_lines = source_file.line_texts();
+            let replacements =
+                compute_replacements(&original_lines, &path_text, chunks, update_file_mode)?;
+            source_file.apply_replacements(&replacements);
+            source_file.into_contents()
+        }
+    };
+    Ok(AppliedPatch {
+        original_contents,
+        new_contents,
+    })
+}
+
+/// Compute a list of replacements needed to transform `original_lines` into the
+/// new lines, given the patch `chunks`. Each replacement is returned as
+/// `(start_index, old_len, new_lines)`.
+fn compute_replacements(
+    original_lines: &[String],
+    path: &str,
+    chunks: &[UpdateFileChunk],
+    update_file_mode: ApplyPatchFileUpdateMode,
+) -> std::result::Result<Vec<Replacement>, ApplyPatchError> {
+    let mut replacements: Vec<Replacement> = Vec::new();
+    let mut line_index: usize = 0;
+
+    for chunk in chunks {
+        // If a chunk has a `change_context`, we use seek_sequence to find it, then
+        // adjust our `line_index` to continue from there.
+        if let Some(ctx_line) = &chunk.change_context {
+            if let Some(idx) = seek_sequence::seek_sequence(
+                original_lines,
+                std::slice::from_ref(ctx_line),
+                line_index,
+                /*eof*/ false,
+                update_file_mode,
+            ) {
+                line_index = idx + 1;
+            } else {
+                return Err(ApplyPatchError::ComputeReplacements(format!(
+                    "Failed to find context '{ctx_line}' in {path}"
+                )));
+            }
+        }
+
+        if chunk.old_lines.is_empty() {
+            // Preserve the legacy split representation's handling of a final
+            // empty line. `SourceFile` only exposes real source lines, so its
+            // insertion point is always after the final line.
+            let insertion_idx = match update_file_mode {
+                ApplyPatchFileUpdateMode::NormalizeToLf => {
+                    if original_lines.last().is_some_and(String::is_empty) {
+                        original_lines.len() - 1
+                    } else {
+                        original_lines.len()
+                    }
+                }
+                ApplyPatchFileUpdateMode::PreserveLineEndings => original_lines.len(),
+            };
+            replacements.push((insertion_idx, 0, chunk.new_lines.clone()));
+            continue;
+        }
+
+        // Otherwise, try to match the existing lines in the file with the old lines
+        // from the chunk. If found, schedule that region for replacement.
+        // Attempt to locate the `old_lines` verbatim within the file.  In many
+        // real‑world diffs the last element of `old_lines` is an *empty* string
+        // representing the terminating newline of the region being replaced.
+        // This sentinel is not present in `original_lines` because `SourceFile`
+        // stores the terminator on the preceding line rather than as an extra
+        // trailing element. If a direct search fails and the pattern ends with
+        // an empty string, retry without that final element so modifications
+        // touching the end‑of‑file can be located reliably.
+
+        let mut pattern: &[String] = &chunk.old_lines;
+        let mut found = seek_sequence::seek_sequence(
+            original_lines,
+            pattern,
+            line_index,
+            chunk.is_end_of_file,
+            update_file_mode,
+        );
+
+        let mut new_slice: &[String] = &chunk.new_lines;
+
+        if found.is_none() && pattern.last().is_some_and(String::is_empty) {
+            // Retry without the trailing empty line which represents the final
+            // newline in the file.
+            pattern = &pattern[..pattern.len() - 1];
+            if new_slice.last().is_some_and(String::is_empty) {
+                new_slice = &new_slice[..new_slice.len() - 1];
+            }
+
+            found = seek_sequence::seek_sequence(
+                original_lines,
+                pattern,
+                line_index,
+                chunk.is_end_of_file,
+                update_file_mode,
+            );
+        }
+
+        if let Some(start_idx) = found {
+            match update_file_mode {
+                ApplyPatchFileUpdateMode::NormalizeToLf => {
+                    replacements.push((start_idx, pattern.len(), new_slice.to_vec()));
+                }
+                ApplyPatchFileUpdateMode::PreserveLineEndings => {
+                    // Context lines occur in both sides of a patch chunk. Keep those
+                    // original lines in place so their exact contents and terminators
+                    // survive, especially when the file has mixed line endings.
+                    let mut old_start = 0;
+                    let mut new_start = 0;
+                    for &(old_context, new_context) in &chunk.context_line_indices {
+                        // A trailing empty context line can be removed from `pattern`
+                        // and `new_slice` above when it represents the final newline.
+                        if old_context >= pattern.len() || new_context >= new_slice.len() {
+                            break;
+                        }
+                        if old_start != old_context || new_start != new_context {
+                            replacements.push((
+                                start_idx + old_start,
+                                old_context - old_start,
+                                new_slice[new_start..new_context].to_vec(),
+                            ));
+                        }
+                        old_start = old_context + 1;
+                        new_start = new_context + 1;
+                    }
+                    if old_start != pattern.len() || new_start != new_slice.len() {
+                        replacements.push((
+                            start_idx + old_start,
+                            pattern.len() - old_start,
+                            new_slice[new_start..].to_vec(),
+                        ));
+                    }
+                }
+            }
+            line_index = start_idx + pattern.len();
+        } else {
+            return Err(ApplyPatchError::ComputeReplacements(format!(
+                "Failed to find expected lines in {}:\n{}",
+                path,
+                chunk.old_lines.join("\n"),
+            )));
+        }
+    }
+
+    replacements.sort_by_key(|(index, _, _)| *index);
+
+    Ok(replacements)
+}
+
+/// Apply the `(start_index, old_len, new_lines)` replacements to `original_lines`,
+/// returning the modified file contents as a vector of lines.
+fn apply_replacements(mut lines: Vec<String>, replacements: &[Replacement]) -> Vec<String> {
+    // We must apply replacements in descending order so that earlier replacements
+    // don't shift the positions of later ones.
+    for (start_idx, old_len, new_segment) in replacements.iter().rev() {
+        let start_idx = *start_idx;
+        let old_len = *old_len;
+
+        // Remove old lines.
+        for _ in 0..old_len {
+            if start_idx < lines.len() {
+                lines.remove(start_idx);
+            }
+        }
+
+        // Insert new lines.
+        for (offset, new_line) in new_segment.iter().enumerate() {
+            lines.insert(start_idx + offset, new_line.clone());
+        }
+    }
+
+    lines
+}
+
+/// Intended result of a file update for apply_patch.
+#[derive(Debug, Eq, PartialEq)]
+pub struct ApplyPatchFileUpdate {
+    pub(crate) unified_diff: String,
+    pub(crate) original_content: String,
+    pub(crate) content: String,
+}
+
+pub async fn unified_diff_from_chunks(
+    path: &PathUri,
+    chunks: &[UpdateFileChunk],
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> std::result::Result<ApplyPatchFileUpdate, ApplyPatchError> {
+    unified_diff_from_chunks_with_mode(
+        path,
+        chunks,
+        ApplyPatchFileUpdateMode::default(),
+        fs,
+        sandbox,
+    )
+    .await
+}
+
+pub(crate) async fn unified_diff_from_chunks_with_mode(
+    path: &PathUri,
+    chunks: &[UpdateFileChunk],
+    update_file_mode: ApplyPatchFileUpdateMode,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> std::result::Result<ApplyPatchFileUpdate, ApplyPatchError> {
+    unified_diff_from_chunks_with_context_and_mode(
+        path,
+        chunks,
+        /*context*/ 1,
+        update_file_mode,
+        fs,
+        sandbox,
+    )
+    .await
+}
+
+pub async fn unified_diff_from_chunks_with_context(
+    path: &PathUri,
+    chunks: &[UpdateFileChunk],
+    context: usize,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> std::result::Result<ApplyPatchFileUpdate, ApplyPatchError> {
+    unified_diff_from_chunks_with_context_and_mode(
+        path,
+        chunks,
+        context,
+        ApplyPatchFileUpdateMode::default(),
+        fs,
+        sandbox,
+    )
+    .await
+}
+
+async fn unified_diff_from_chunks_with_context_and_mode(
+    path: &PathUri,
+    chunks: &[UpdateFileChunk],
+    context: usize,
+    update_file_mode: ApplyPatchFileUpdateMode,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> std::result::Result<ApplyPatchFileUpdate, ApplyPatchError> {
+    let AppliedPatch {
+        original_contents,
+        new_contents,
+    } = derive_new_contents_from_chunks(
+        path,
+        chunks,
+        update_file_mode,
+        fs,
+        /*follow_symlinks*/ true,
+        sandbox,
+    )
+    .await?;
+    let text_diff = TextDiff::from_lines(&original_contents, &new_contents);
+    let unified_diff = text_diff.unified_diff().context_radius(context).to_string();
+    Ok(ApplyPatchFileUpdate {
+        unified_diff,
+        original_content: original_contents,
+        content: new_contents,
+    })
+}
diff --git a/codex-rs/apply-patch/src/file_update_tests.rs b/codex-rs/apply-patch/src/file_update_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..968082e26d64acb9ee4a9feea468763971cb2d4f
--- /dev/null
+++ b/codex-rs/apply-patch/src/file_update_tests.rs
@@ -0,0 +1,278 @@
+use super::*;
+use crate::Hunk;
+use crate::apply_patch;
+use crate::parse_patch;
+use codex_exec_server::LOCAL_FS;
+use codex_utils_path_uri::PathUri;
+use pretty_assertions::assert_eq;
+use std::fs;
+use tempfile::tempdir;
+
+fn wrap_patch(body: &str) -> String {
+    format!("*** Begin Patch\n{body}\n*** End Patch")
+}
+
+#[tokio::test]
+async fn test_unified_diff() {
+    // Start with a file containing four lines.
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("multi.txt");
+    fs::write(&path, "foo\nbar\nbaz\nqux\n").unwrap();
+    let patch = wrap_patch(&format!(
+        r#"*** Update File: {}
+@@
+ foo
+-bar
++BAR
+@@
+ baz
+-qux
++QUX"#,
+        path.display()
+    ));
+    let patch = parse_patch(&patch).unwrap();
+
+    let update_file_chunks = match patch.hunks.as_slice() {
+        [Hunk::UpdateFile { chunks, .. }] => chunks,
+        _ => panic!("Expected a single UpdateFile hunk"),
+    };
+    let path_uri = PathUri::from_host_native_path(&path).expect("absolute test path");
+    let diff = unified_diff_from_chunks(
+        &path_uri,
+        update_file_chunks,
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await
+    .unwrap();
+    let expected_diff = r#"@@ -1,4 +1,4 @@
+ foo
+-bar
++BAR
+ baz
+-qux
++QUX
+"#;
+    let expected = ApplyPatchFileUpdate {
+        unified_diff: expected_diff.to_string(),
+        original_content: "foo\nbar\nbaz\nqux\n".to_string(),
+        content: "foo\nBAR\nbaz\nQUX\n".to_string(),
+    };
+    assert_eq!(expected, diff);
+}
+
+#[tokio::test]
+async fn test_unified_diff_first_line_replacement() {
+    // Replace the very first line of the file.
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("first.txt");
+    fs::write(&path, "foo\nbar\nbaz\n").unwrap();
+
+    let patch = wrap_patch(&format!(
+        r#"*** Update File: {}
+@@
+-foo
++FOO
+ bar
+"#,
+        path.display()
+    ));
+
+    let patch = parse_patch(&patch).unwrap();
+    let chunks = match patch.hunks.as_slice() {
+        [Hunk::UpdateFile { chunks, .. }] => chunks,
+        _ => panic!("Expected a single UpdateFile hunk"),
+    };
+
+    let resolved_path = PathUri::from_host_native_path(&path).expect("absolute test path");
+    let diff = unified_diff_from_chunks(
+        &resolved_path,
+        chunks,
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await
+    .unwrap();
+    let expected_diff = r#"@@ -1,2 +1,2 @@
+-foo
++FOO
+ bar
+"#;
+    let expected = ApplyPatchFileUpdate {
+        unified_diff: expected_diff.to_string(),
+        original_content: "foo\nbar\nbaz\n".to_string(),
+        content: "FOO\nbar\nbaz\n".to_string(),
+    };
+    assert_eq!(expected, diff);
+}
+
+#[tokio::test]
+async fn test_unified_diff_last_line_replacement() {
+    // Replace the very last line of the file.
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("last.txt");
+    fs::write(&path, "foo\nbar\nbaz\n").unwrap();
+
+    let patch = wrap_patch(&format!(
+        r#"*** Update File: {}
+@@
+ foo
+ bar
+-baz
++BAZ
+"#,
+        path.display()
+    ));
+
+    let patch = parse_patch(&patch).unwrap();
+    let chunks = match patch.hunks.as_slice() {
+        [Hunk::UpdateFile { chunks, .. }] => chunks,
+        _ => panic!("Expected a single UpdateFile hunk"),
+    };
+
+    let resolved_path = PathUri::from_host_native_path(&path).expect("absolute test path");
+    let diff = unified_diff_from_chunks(
+        &resolved_path,
+        chunks,
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await
+    .unwrap();
+    let expected_diff = r#"@@ -2,2 +2,2 @@
+ bar
+-baz
++BAZ
+"#;
+    let expected = ApplyPatchFileUpdate {
+        unified_diff: expected_diff.to_string(),
+        original_content: "foo\nbar\nbaz\n".to_string(),
+        content: "foo\nbar\nBAZ\n".to_string(),
+    };
+    assert_eq!(expected, diff);
+}
+
+#[tokio::test]
+async fn test_unified_diff_insert_at_eof() {
+    // Insert a new line at end-of-file.
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("insert.txt");
+    fs::write(&path, "foo\nbar\nbaz\n").unwrap();
+
+    let patch = wrap_patch(&format!(
+        r#"*** Update File: {}
+@@
++quux
+*** End of File
+"#,
+        path.display()
+    ));
+
+    let patch = parse_patch(&patch).unwrap();
+    let chunks = match patch.hunks.as_slice() {
+        [Hunk::UpdateFile { chunks, .. }] => chunks,
+        _ => panic!("Expected a single UpdateFile hunk"),
+    };
+
+    let path_uri = PathUri::from_host_native_path(&path).expect("absolute test path");
+    let diff =
+        unified_diff_from_chunks(&path_uri, chunks, LOCAL_FS.as_ref(), /*sandbox*/ None)
+            .await
+            .unwrap();
+    let expected_diff = r#"@@ -3 +3,2 @@
+ baz
++quux
+"#;
+    let expected = ApplyPatchFileUpdate {
+        unified_diff: expected_diff.to_string(),
+        original_content: "foo\nbar\nbaz\n".to_string(),
+        content: "foo\nbar\nbaz\nquux\n".to_string(),
+    };
+    assert_eq!(expected, diff);
+}
+
+#[tokio::test]
+async fn test_unified_diff_interleaved_changes() {
+    // Original file with six lines.
+    let dir = tempdir().unwrap();
+    let path = dir.path().join("interleaved.txt");
+    fs::write(&path, "a\nb\nc\nd\ne\nf\n").unwrap();
+
+    // Patch replaces two separate lines and appends a new one at EOF using
+    // three distinct chunks.
+    let patch_body = format!(
+        r#"*** Update File: {}
+@@
+ a
+-b
++B
+@@
+ d
+-e
++E
+@@
+ f
++g
+*** End of File"#,
+        path.display()
+    );
+    let patch = wrap_patch(&patch_body);
+
+    // Extract chunks then build the unified diff.
+    let parsed = parse_patch(&patch).unwrap();
+    let chunks = match parsed.hunks.as_slice() {
+        [Hunk::UpdateFile { chunks, .. }] => chunks,
+        _ => panic!("Expected a single UpdateFile hunk"),
+    };
+
+    let path_uri = PathUri::from_host_native_path(&path).expect("absolute test path");
+    let diff =
+        unified_diff_from_chunks(&path_uri, chunks, LOCAL_FS.as_ref(), /*sandbox*/ None)
+            .await
+            .unwrap();
+
+    let expected_diff = r#"@@ -1,6 +1,7 @@
+ a
+-b
++B
+ c
+ d
+-e
++E
+ f
++g
+"#;
+
+    let expected = ApplyPatchFileUpdate {
+        unified_diff: expected_diff.to_string(),
+        original_content: "a\nb\nc\nd\ne\nf\n".to_string(),
+        content: "a\nB\nc\nd\nE\nf\ng\n".to_string(),
+    };
+
+    assert_eq!(expected, diff);
+
+    let mut stdout = Vec::new();
+    let mut stderr = Vec::new();
+    apply_patch(
+        &patch,
+        &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+        &mut stdout,
+        &mut stderr,
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await
+    .unwrap();
+    let contents = fs::read_to_string(path).unwrap();
+    assert_eq!(
+        contents,
+        r#"a
+B
+c
+d
+E
+f
+g
+"#
+    );
+}
diff --git a/codex-rs/apply-patch/src/invocation.rs b/codex-rs/apply-patch/src/invocation.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5b805c30c69e208725fd069a51ab31236629af9b
--- /dev/null
+++ b/codex-rs/apply-patch/src/invocation.rs
@@ -0,0 +1,1036 @@
+use std::collections::HashMap;
+use std::sync::LazyLock;
+
+use codex_exec_server::ExecutorFileSystem;
+use tree_sitter::Parser;
+use tree_sitter::Query;
+use tree_sitter::QueryCursor;
+use tree_sitter::StreamingIterator;
+use tree_sitter_bash::LANGUAGE as BASH;
+
+use crate::ApplyPatchAction;
+use crate::ApplyPatchArgs;
+use crate::ApplyPatchError;
+use crate::ApplyPatchFileChange;
+use crate::ApplyPatchFileUpdate;
+use crate::ApplyPatchFileUpdateMode;
+use crate::IoError;
+use crate::MaybeApplyPatchVerified;
+use crate::parser::Hunk;
+use crate::parser::ParseError;
+use crate::parser::parse_patch;
+use crate::unified_diff_from_chunks_with_mode;
+use codex_utils_path_uri::PathConvention;
+use codex_utils_path_uri::PathUri;
+use std::str::Utf8Error;
+use tree_sitter::LanguageError;
+
+const APPLY_PATCH_COMMANDS: [&str; 2] = ["apply_patch", "applypatch"];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ApplyPatchShell {
+    Unix,
+    PowerShell,
+    Cmd,
+}
+
+#[derive(Debug, PartialEq)]
+pub enum MaybeApplyPatch {
+    Body(ApplyPatchArgs),
+    ShellParseError(ExtractHeredocError),
+    PatchParseError(ParseError),
+    NotApplyPatch,
+}
+
+#[derive(Debug, PartialEq)]
+pub enum ExtractHeredocError {
+    CommandDidNotStartWithApplyPatch,
+    FailedToLoadBashGrammar(LanguageError),
+    HeredocNotUtf8(Utf8Error),
+    FailedToParsePatchIntoAst,
+    FailedToFindHeredocBody,
+}
+
+fn classify_shell_name(shell: &str, convention: PathConvention) -> Option<String> {
+    let basename = convention.path_segments(shell).next_back()?;
+    let stem = basename
+        .rsplit_once('.')
+        .and_then(|(stem, _extension)| (!stem.is_empty()).then_some(stem))
+        .unwrap_or(basename);
+    Some(stem.to_ascii_lowercase())
+}
+
+fn classify_shell(shell: &str, flag: &str, convention: PathConvention) -> Option<ApplyPatchShell> {
+    classify_shell_name(shell, convention).and_then(|name| match name.as_str() {
+        "bash" | "zsh" | "sh" if matches!(flag, "-lc" | "-c") => Some(ApplyPatchShell::Unix),
+        "pwsh" | "powershell" if flag.eq_ignore_ascii_case("-command") => {
+            Some(ApplyPatchShell::PowerShell)
+        }
+        "cmd" if flag.eq_ignore_ascii_case("/c") => Some(ApplyPatchShell::Cmd),
+        _ => None,
+    })
+}
+
+fn can_skip_flag(shell: &str, flag: &str, convention: PathConvention) -> bool {
+    classify_shell_name(shell, convention).is_some_and(|name| {
+        matches!(name.as_str(), "pwsh" | "powershell") && flag.eq_ignore_ascii_case("-noprofile")
+    })
+}
+
+fn parse_shell_script<'a>(argv: &'a [String], cwd: &PathUri) -> Option<(ApplyPatchShell, &'a str)> {
+    let convention = cwd.infer_path_convention()?;
+    match argv {
+        [shell, flag, script] => classify_shell(shell, flag, convention).map(|shell_type| {
+            let script = script.as_str();
+            (shell_type, script)
+        }),
+        [shell, skip_flag, flag, script] => {
+            if !can_skip_flag(shell, skip_flag, convention) {
+                return None;
+            }
+            classify_shell(shell, flag, convention).map(|shell_type| {
+                let script = script.as_str();
+                (shell_type, script)
+            })
+        }
+        _ => None,
+    }
+}
+
+fn extract_apply_patch_from_shell(
+    shell: ApplyPatchShell,
+    script: &str,
+) -> std::result::Result<(String, Option<String>), ExtractHeredocError> {
+    match shell {
+        ApplyPatchShell::Unix | ApplyPatchShell::PowerShell | ApplyPatchShell::Cmd => {
+            extract_apply_patch_from_bash(script)
+        }
+    }
+}
+
+// TODO: make private once we remove tests in lib.rs
+/// `cwd` supplies the path convention used to interpret the shell executable in `argv`.
+pub fn maybe_parse_apply_patch(argv: &[String], cwd: &PathUri) -> MaybeApplyPatch {
+    match argv {
+        // Direct invocation: apply_patch <patch>
+        [cmd, body] if APPLY_PATCH_COMMANDS.contains(&cmd.as_str()) => match parse_patch(body) {
+            Ok(source) => MaybeApplyPatch::Body(source),
+            Err(e) => MaybeApplyPatch::PatchParseError(e),
+        },
+        // Shell heredoc form: (optional `cd <path> &&`) apply_patch <<'EOF' ...
+        _ => match parse_shell_script(argv, cwd) {
+            Some((shell, script)) => match extract_apply_patch_from_shell(shell, script) {
+                Ok((body, workdir)) => match parse_patch(&body) {
+                    Ok(mut source) => {
+                        source.workdir = workdir;
+                        MaybeApplyPatch::Body(source)
+                    }
+                    Err(e) => MaybeApplyPatch::PatchParseError(e),
+                },
+                Err(ExtractHeredocError::CommandDidNotStartWithApplyPatch) => {
+                    MaybeApplyPatch::NotApplyPatch
+                }
+                Err(e) => MaybeApplyPatch::ShellParseError(e),
+            },
+            None => MaybeApplyPatch::NotApplyPatch,
+        },
+    }
+}
+
+/// `cwd` must identify an absolute environment-native path so relative patch paths can be
+/// resolved without projecting them onto the app-server or exec-server host.
+pub async fn maybe_parse_apply_patch_verified(
+    argv: &[String],
+    cwd: &PathUri,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&codex_exec_server::FileSystemSandboxContext>,
+) -> MaybeApplyPatchVerified {
+    maybe_parse_apply_patch_verified_with_mode(
+        argv,
+        cwd,
+        ApplyPatchFileUpdateMode::default(),
+        fs,
+        sandbox,
+    )
+    .await
+}
+
+/// Parses and verifies an `apply_patch` invocation using the selected
+/// file-update mode.
+pub async fn maybe_parse_apply_patch_verified_with_mode(
+    argv: &[String],
+    cwd: &PathUri,
+    update_file_mode: ApplyPatchFileUpdateMode,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&codex_exec_server::FileSystemSandboxContext>,
+) -> MaybeApplyPatchVerified {
+    // Detect a raw patch body passed directly as the command or as the body of a shell
+    // script. In these cases, report an explicit error rather than applying the patch.
+    if let [body] = argv
+        && parse_patch(body).is_ok()
+    {
+        return MaybeApplyPatchVerified::CorrectnessError(ApplyPatchError::ImplicitInvocation);
+    }
+    if let Some((_, script)) = parse_shell_script(argv, cwd)
+        && parse_patch(script).is_ok()
+    {
+        return MaybeApplyPatchVerified::CorrectnessError(ApplyPatchError::ImplicitInvocation);
+    }
+
+    match maybe_parse_apply_patch(argv, cwd) {
+        MaybeApplyPatch::Body(args) => {
+            verify_apply_patch_args_with_mode(args, cwd, update_file_mode, fs, sandbox).await
+        }
+        MaybeApplyPatch::ShellParseError(e) => MaybeApplyPatchVerified::ShellParseError(e),
+        MaybeApplyPatch::PatchParseError(e) => MaybeApplyPatchVerified::CorrectnessError(e.into()),
+        MaybeApplyPatch::NotApplyPatch => MaybeApplyPatchVerified::NotApplyPatch,
+    }
+}
+
+pub async fn verify_apply_patch_args(
+    args: ApplyPatchArgs,
+    cwd: &PathUri,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&codex_exec_server::FileSystemSandboxContext>,
+) -> MaybeApplyPatchVerified {
+    verify_apply_patch_args_with_mode(args, cwd, ApplyPatchFileUpdateMode::default(), fs, sandbox)
+        .await
+}
+
+/// Verifies parsed patch arguments using the selected file-update mode.
+pub async fn verify_apply_patch_args_with_mode(
+    args: ApplyPatchArgs,
+    cwd: &PathUri,
+    update_file_mode: ApplyPatchFileUpdateMode,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&codex_exec_server::FileSystemSandboxContext>,
+) -> MaybeApplyPatchVerified {
+    match try_verify_apply_patch_args(args, cwd, update_file_mode, fs, sandbox).await {
+        Ok(action) => MaybeApplyPatchVerified::Body(action),
+        Err(err) => MaybeApplyPatchVerified::CorrectnessError(err),
+    }
+}
+
+async fn try_verify_apply_patch_args(
+    args: ApplyPatchArgs,
+    cwd: &PathUri,
+    update_file_mode: ApplyPatchFileUpdateMode,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&codex_exec_server::FileSystemSandboxContext>,
+) -> Result<ApplyPatchAction, ApplyPatchError> {
+    let ApplyPatchArgs {
+        patch,
+        hunks,
+        workdir,
+        ..
+    } = args;
+    let effective_cwd = workdir
+        .as_ref()
+        .map(|dir| cwd.join(dir))
+        .transpose()?
+        .unwrap_or_else(|| cwd.clone());
+    let mut changes = HashMap::new();
+    for hunk in hunks {
+        let path = hunk.resolve_path(&effective_cwd)?;
+        if changes.contains_key(&path) {
+            return Err(ParseError::InvalidPatchError(format!(
+                "multiple operations target {}",
+                path.inferred_native_path_string()
+            ))
+            .into());
+        }
+        match hunk {
+            Hunk::AddFile { contents, .. } => {
+                changes.insert(path, ApplyPatchFileChange::Add { content: contents });
+            }
+            Hunk::DeleteFile { .. } => {
+                let content = fs
+                    .read_file_text(&path, Default::default(), sandbox)
+                    .await
+                    .map_err(|source| {
+                        ApplyPatchError::IoError(IoError {
+                            context: format!(
+                                "Failed to read {}",
+                                path.inferred_native_path_string()
+                            ),
+                            source,
+                        })
+                    })?;
+                changes.insert(path, ApplyPatchFileChange::Delete { content });
+            }
+            Hunk::UpdateFile {
+                move_path, chunks, ..
+            } => {
+                let ApplyPatchFileUpdate {
+                    unified_diff,
+                    content: contents,
+                    ..
+                } = unified_diff_from_chunks_with_mode(
+                    &path,
+                    &chunks,
+                    update_file_mode,
+                    fs,
+                    sandbox,
+                )
+                .await?;
+                changes.insert(
+                    path,
+                    ApplyPatchFileChange::Update {
+                        unified_diff,
+                        move_path: move_path
+                            .map(|path| effective_cwd.join(&path.to_string_lossy()))
+                            .transpose()?,
+                        new_content: contents,
+                    },
+                );
+            }
+        }
+    }
+    Ok(ApplyPatchAction {
+        changes,
+        update_file_mode,
+        patch,
+        cwd: effective_cwd,
+    })
+}
+
+/// Extract the heredoc body (and optional `cd` workdir) from a `bash -lc` script
+/// that invokes the apply_patch tool using a heredoc.
+///
+/// Supported top‑level forms (must be the only top‑level statement):
+/// - `apply_patch <<'EOF'\n...\nEOF`
+/// - `cd <path> && apply_patch <<'EOF'\n...\nEOF`
+///
+/// Notes about matching:
+/// - Parsed with Tree‑sitter Bash and a strict query that uses anchors so the
+///   heredoc‑redirected statement is the only top‑level statement.
+/// - The connector between `cd` and `apply_patch` must be `&&` (not `|` or `||`).
+/// - Exactly one positional `word` argument is allowed for `cd` (no flags, no quoted
+///   strings, no second argument).
+/// - The apply command is validated in‑query via `#any-of?` to allow `apply_patch`
+///   or `applypatch`.
+/// - Preceding or trailing commands (e.g., `echo ...;` or `... && echo done`) do not match.
+///
+/// Returns `(heredoc_body, Some(path))` when the `cd` variant matches, or
+/// `(heredoc_body, None)` for the direct form. Errors are returned if the script
+/// cannot be parsed or does not match the allowed patterns.
+fn extract_apply_patch_from_bash(
+    src: &str,
+) -> std::result::Result<(String, Option<String>), ExtractHeredocError> {
+    // This function uses a Tree-sitter query to recognize one of two
+    // whole-script forms, each expressed as a single top-level statement:
+    //
+    // 1. apply_patch <<'EOF'\n...\nEOF
+    // 2. cd <path> && apply_patch <<'EOF'\n...\nEOF
+    //
+    // Key ideas when reading the query:
+    // - dots (`.`) between named nodes enforces adjacency among named children and
+    //   anchor to the start/end of the expression.
+    // - we match a single redirected_statement directly under program with leading
+    //   and trailing anchors (`.`). This ensures it is the only top-level statement
+    //   (so prefixes like `echo ...;` or suffixes like `... && echo done` do not match).
+    //
+    // Overall, we want to be conservative and only match the intended forms, as other
+    // forms are likely to be model errors, or incorrectly interpreted by later code.
+    //
+    // If you're editing this query, it's helpful to start by creating a debugging binary
+    // which will let you see the AST of an arbitrary bash script passed in, and optionally
+    // also run an arbitrary query against the AST. This is useful for understanding
+    // how tree-sitter parses the script and whether the query syntax is correct. Be sure
+    // to test both positive and negative cases.
+    static APPLY_PATCH_QUERY: LazyLock<Query> = LazyLock::new(|| {
+        let language = BASH.into();
+        #[expect(clippy::expect_used)]
+        Query::new(
+            &language,
+            r#"
+            (
+              program
+                . (redirected_statement
+                    body: (command
+                            name: (command_name (word) @apply_name) .)
+                    (#any-of? @apply_name "apply_patch" "applypatch")
+                    redirect: (heredoc_redirect
+                                . (heredoc_start)
+                                . (heredoc_body) @heredoc
+                                . (heredoc_end)
+                                .))
+                .)
+
+            (
+              program
+                . (redirected_statement
+                    body: (list
+                            . (command
+                                name: (command_name (word) @cd_name) .
+                                argument: [
+                                  (word) @cd_path
+                                  (string (string_content) @cd_path)
+                                  (raw_string) @cd_raw_string
+                                ] .)
+                            "&&"
+                            . (command
+                                name: (command_name (word) @apply_name))
+                            .)
+                    (#eq? @cd_name "cd")
+                    (#any-of? @apply_name "apply_patch" "applypatch")
+                    redirect: (heredoc_redirect
+                                . (heredoc_start)
+                                . (heredoc_body) @heredoc
+                                . (heredoc_end)
+                                .))
+                .)
+            "#,
+        )
+        .expect("valid bash query")
+    });
+
+    let lang = BASH.into();
+    let mut parser = Parser::new();
+    parser
+        .set_language(&lang)
+        .map_err(ExtractHeredocError::FailedToLoadBashGrammar)?;
+    let tree = parser
+        .parse(src, None)
+        .ok_or(ExtractHeredocError::FailedToParsePatchIntoAst)?;
+
+    let bytes = src.as_bytes();
+    let root = tree.root_node();
+
+    let mut cursor = QueryCursor::new();
+    let mut matches = cursor.matches(&APPLY_PATCH_QUERY, root, bytes);
+    while let Some(m) = matches.next() {
+        let mut heredoc_text: Option<String> = None;
+        let mut cd_path: Option<String> = None;
+
+        for capture in m.captures.iter() {
+            let name = APPLY_PATCH_QUERY.capture_names()[capture.index as usize];
+            match name {
+                "heredoc" => {
+                    let text = capture
+                        .node
+                        .utf8_text(bytes)
+                        .map_err(ExtractHeredocError::HeredocNotUtf8)?
+                        .trim_end_matches('\n')
+                        .to_string();
+                    heredoc_text = Some(text);
+                }
+                "cd_path" => {
+                    let text = capture
+                        .node
+                        .utf8_text(bytes)
+                        .map_err(ExtractHeredocError::HeredocNotUtf8)?
+                        .to_string();
+                    cd_path = Some(text);
+                }
+                "cd_raw_string" => {
+                    let raw = capture
+                        .node
+                        .utf8_text(bytes)
+                        .map_err(ExtractHeredocError::HeredocNotUtf8)?;
+                    let trimmed = raw
+                        .strip_prefix('\'')
+                        .and_then(|s| s.strip_suffix('\''))
+                        .unwrap_or(raw);
+                    cd_path = Some(trimmed.to_string());
+                }
+                _ => {}
+            }
+        }
+
+        if let Some(heredoc) = heredoc_text {
+            return Ok((heredoc, cd_path));
+        }
+    }
+
+    Err(ExtractHeredocError::CommandDidNotStartWithApplyPatch)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::unified_diff_from_chunks;
+    use assert_matches::assert_matches;
+    use codex_exec_server::LOCAL_FS;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use std::path::PathBuf;
+    use std::string::ToString;
+    use tempfile::tempdir;
+
+    /// Helper to construct a patch with the given body.
+    fn wrap_patch(body: &str) -> String {
+        format!("*** Begin Patch\n{body}\n*** End Patch")
+    }
+
+    fn strs_to_strings(strs: &[&str]) -> Vec<String> {
+        strs.iter().map(ToString::to_string).collect()
+    }
+
+    // Test helpers to reduce repetition when building bash -lc heredoc scripts
+    fn args_bash(script: &str) -> Vec<String> {
+        strs_to_strings(&["bash", "-lc", script])
+    }
+
+    fn args_powershell(script: &str) -> Vec<String> {
+        strs_to_strings(&["powershell.exe", "-Command", script])
+    }
+
+    fn args_powershell_no_profile(script: &str) -> Vec<String> {
+        strs_to_strings(&["powershell.exe", "-NoProfile", "-Command", script])
+    }
+
+    fn args_pwsh(script: &str) -> Vec<String> {
+        strs_to_strings(&["pwsh", "-NoProfile", "-Command", script])
+    }
+
+    fn args_cmd(script: &str) -> Vec<String> {
+        strs_to_strings(&["cmd.exe", "/c", script])
+    }
+
+    fn heredoc_script(prefix: &str) -> String {
+        format!(
+            "{prefix}apply_patch <<'PATCH'\n*** Begin Patch\n*** Add File: foo\n+hi\n*** End Patch\nPATCH"
+        )
+    }
+
+    fn heredoc_script_ps(prefix: &str, suffix: &str) -> String {
+        format!(
+            "{prefix}apply_patch <<'PATCH'\n*** Begin Patch\n*** Add File: foo\n+hi\n*** End Patch\nPATCH{suffix}"
+        )
+    }
+
+    fn expected_single_add() -> Vec<Hunk> {
+        vec![Hunk::AddFile {
+            path: PathBuf::from("foo"),
+            contents: "hi\n".to_string(),
+        }]
+    }
+
+    #[track_caller]
+    fn assert_match_args(args: Vec<String>, expected_workdir: Option<&str>) {
+        assert_match_args_with_cwd(
+            args,
+            &PathUri::parse("file:///workspace").expect("valid POSIX test cwd"),
+            expected_workdir,
+        );
+    }
+
+    #[track_caller]
+    fn assert_match_args_with_cwd(
+        args: Vec<String>,
+        cwd: &PathUri,
+        expected_workdir: Option<&str>,
+    ) {
+        match maybe_parse_apply_patch(&args, cwd) {
+            MaybeApplyPatch::Body(ApplyPatchArgs { hunks, workdir, .. }) => {
+                assert_eq!(workdir.as_deref(), expected_workdir);
+                assert_eq!(hunks, expected_single_add());
+            }
+            result => panic!("expected MaybeApplyPatch::Body got {result:?}"),
+        }
+    }
+
+    #[track_caller]
+    fn assert_match(script: &str, expected_workdir: Option<&str>) {
+        let args = args_bash(script);
+        assert_match_args(args, expected_workdir);
+    }
+
+    fn assert_not_match(script: &str) {
+        let args = args_bash(script);
+        assert_matches!(
+            maybe_parse_apply_patch(
+                &args,
+                &PathUri::parse("file:///workspace").expect("valid POSIX test cwd"),
+            ),
+            MaybeApplyPatch::NotApplyPatch
+        );
+    }
+
+    #[tokio::test]
+    async fn test_implicit_patch_single_arg_is_error() {
+        let patch = "*** Begin Patch\n*** Add File: foo\n+hi\n*** End Patch".to_string();
+        let args = vec![patch];
+        let dir = tempdir().unwrap();
+        assert_matches!(
+            maybe_parse_apply_patch_verified(
+                &args,
+                &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+                LOCAL_FS.as_ref(),
+                /*sandbox*/ None,
+            )
+            .await,
+            MaybeApplyPatchVerified::CorrectnessError(ApplyPatchError::ImplicitInvocation)
+        );
+    }
+
+    #[tokio::test]
+    async fn test_implicit_patch_bash_script_is_error() {
+        let script = "*** Begin Patch\n*** Add File: foo\n+hi\n*** End Patch";
+        let args = args_bash(script);
+        let dir = tempdir().unwrap();
+        assert_matches!(
+            maybe_parse_apply_patch_verified(
+                &args,
+                &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+                LOCAL_FS.as_ref(),
+                /*sandbox*/ None,
+            )
+            .await,
+            MaybeApplyPatchVerified::CorrectnessError(ApplyPatchError::ImplicitInvocation)
+        );
+    }
+
+    #[tokio::test]
+    async fn test_literal() {
+        let args = strs_to_strings(&[
+            "apply_patch",
+            r#"*** Begin Patch
+*** Add File: foo
++hi
+*** End Patch
+"#,
+        ]);
+
+        match maybe_parse_apply_patch(
+            &args,
+            &PathUri::parse("file:///workspace").expect("valid POSIX test cwd"),
+        ) {
+            MaybeApplyPatch::Body(ApplyPatchArgs { hunks, .. }) => {
+                assert_eq!(
+                    hunks,
+                    vec![Hunk::AddFile {
+                        path: PathBuf::from("foo"),
+                        contents: "hi\n".to_string()
+                    }]
+                );
+            }
+            result => panic!("expected MaybeApplyPatch::Body got {result:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_literal_applypatch() {
+        let args = strs_to_strings(&[
+            "applypatch",
+            r#"*** Begin Patch
+*** Add File: foo
++hi
+*** End Patch
+"#,
+        ]);
+
+        match maybe_parse_apply_patch(
+            &args,
+            &PathUri::parse("file:///workspace").expect("valid POSIX test cwd"),
+        ) {
+            MaybeApplyPatch::Body(ApplyPatchArgs { hunks, .. }) => {
+                assert_eq!(
+                    hunks,
+                    vec![Hunk::AddFile {
+                        path: PathBuf::from("foo"),
+                        contents: "hi\n".to_string()
+                    }]
+                );
+            }
+            result => panic!("expected MaybeApplyPatch::Body got {result:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_heredoc() {
+        assert_match(&heredoc_script(""), /*expected_workdir*/ None);
+    }
+
+    #[tokio::test]
+    async fn test_heredoc_non_login_shell() {
+        let script = heredoc_script("");
+        let args = strs_to_strings(&["bash", "-c", &script]);
+        assert_match_args(args, /*expected_workdir*/ None);
+    }
+
+    #[tokio::test]
+    async fn test_heredoc_applypatch() {
+        let args = strs_to_strings(&[
+            "bash",
+            "-lc",
+            r#"applypatch <<'PATCH'
+*** Begin Patch
+*** Add File: foo
++hi
+*** End Patch
+PATCH"#,
+        ]);
+
+        match maybe_parse_apply_patch(
+            &args,
+            &PathUri::parse("file:///workspace").expect("valid POSIX test cwd"),
+        ) {
+            MaybeApplyPatch::Body(ApplyPatchArgs { hunks, workdir, .. }) => {
+                assert_eq!(workdir, None);
+                assert_eq!(
+                    hunks,
+                    vec![Hunk::AddFile {
+                        path: PathBuf::from("foo"),
+                        contents: "hi\n".to_string()
+                    }]
+                );
+            }
+            result => panic!("expected MaybeApplyPatch::Body got {result:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_powershell_heredoc() {
+        let script = heredoc_script("");
+        assert_match_args(args_powershell(&script), /*expected_workdir*/ None);
+    }
+    #[tokio::test]
+    async fn test_powershell_heredoc_no_profile() {
+        let script = heredoc_script("");
+        assert_match_args(
+            args_powershell_no_profile(&script),
+            /*expected_workdir*/ None,
+        );
+    }
+    #[tokio::test]
+    async fn test_pwsh_heredoc() {
+        let script = heredoc_script("");
+        assert_match_args(args_pwsh(&script), /*expected_workdir*/ None);
+    }
+
+    #[tokio::test]
+    async fn test_apply_patch_interception_uses_cwd_convention_for_windows_pwsh_path() {
+        let script = heredoc_script("");
+        assert_match_args_with_cwd(
+            strs_to_strings(&[
+                r"C:\Program Files\PowerShell\7\pwsh.exe",
+                "-NoProfile",
+                "-Command",
+                &script,
+            ]),
+            &PathUri::parse("file:///C:/windows").expect("valid Windows test cwd"),
+            /*expected_workdir*/ None,
+        );
+    }
+
+    #[tokio::test]
+    async fn test_cmd_heredoc_with_cd() {
+        let script = heredoc_script("cd foo && ");
+        assert_match_args(args_cmd(&script), Some("foo"));
+    }
+
+    #[tokio::test]
+    async fn test_heredoc_with_leading_cd() {
+        assert_match(&heredoc_script("cd foo && "), Some("foo"));
+    }
+
+    #[tokio::test]
+    async fn test_cd_with_semicolon_is_ignored() {
+        assert_not_match(&heredoc_script("cd foo; "));
+    }
+
+    #[tokio::test]
+    async fn test_cd_or_apply_patch_is_ignored() {
+        assert_not_match(&heredoc_script("cd bar || "));
+    }
+
+    #[tokio::test]
+    async fn test_cd_pipe_apply_patch_is_ignored() {
+        assert_not_match(&heredoc_script("cd bar | "));
+    }
+
+    #[tokio::test]
+    async fn test_cd_single_quoted_path_with_spaces() {
+        assert_match(&heredoc_script("cd 'foo bar' && "), Some("foo bar"));
+    }
+
+    #[tokio::test]
+    async fn test_cd_double_quoted_path_with_spaces() {
+        assert_match(&heredoc_script("cd \"foo bar\" && "), Some("foo bar"));
+    }
+
+    #[tokio::test]
+    async fn test_echo_and_apply_patch_is_ignored() {
+        assert_not_match(&heredoc_script("echo foo && "));
+    }
+
+    #[tokio::test]
+    async fn test_apply_patch_with_arg_is_ignored() {
+        let script = "apply_patch foo <<'PATCH'\n*** Begin Patch\n*** Add File: foo\n+hi\n*** End Patch\nPATCH";
+        assert_not_match(script);
+    }
+
+    #[tokio::test]
+    async fn test_double_cd_then_apply_patch_is_ignored() {
+        assert_not_match(&heredoc_script("cd foo && cd bar && "));
+    }
+
+    #[tokio::test]
+    async fn test_cd_two_args_is_ignored() {
+        assert_not_match(&heredoc_script("cd foo bar && "));
+    }
+
+    #[tokio::test]
+    async fn test_cd_then_apply_patch_then_extra_is_ignored() {
+        let script = heredoc_script_ps("cd bar && ", " && echo done");
+        assert_not_match(&script);
+    }
+
+    #[tokio::test]
+    async fn test_echo_then_cd_and_apply_patch_is_ignored() {
+        // Ensure preceding commands before the `cd && apply_patch <<...` sequence do not match.
+        assert_not_match(&heredoc_script("echo foo; cd bar && "));
+    }
+
+    #[tokio::test]
+    async fn test_unified_diff_last_line_replacement() {
+        // Replace the very last line of the file.
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("last.txt");
+        fs::write(&path, "foo\nbar\nbaz\n").unwrap();
+
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
+ foo
+ bar
+-baz
++BAZ
+"#,
+            path.display()
+        ));
+
+        let patch = parse_patch(&patch).unwrap();
+        let chunks = match patch.hunks.as_slice() {
+            [Hunk::UpdateFile { chunks, .. }] => chunks,
+            _ => panic!("Expected a single UpdateFile hunk"),
+        };
+
+        let path_uri = PathUri::from_host_native_path(&path).expect("absolute test path");
+        let diff =
+            unified_diff_from_chunks(&path_uri, chunks, LOCAL_FS.as_ref(), /*sandbox*/ None)
+                .await
+                .unwrap();
+        let expected_diff = r#"@@ -2,2 +2,2 @@
+ bar
+-baz
++BAZ
+"#;
+        let expected = ApplyPatchFileUpdate {
+            unified_diff: expected_diff.to_string(),
+            original_content: "foo\nbar\nbaz\n".to_string(),
+            content: "foo\nbar\nBAZ\n".to_string(),
+        };
+        assert_eq!(expected, diff);
+    }
+
+    #[tokio::test]
+    async fn test_unified_diff_insert_at_eof() {
+        // Insert a new line at end‑of‑file.
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("insert.txt");
+        fs::write(&path, "foo\nbar\nbaz\n").unwrap();
+
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
++quux
+*** End of File
+"#,
+            path.display()
+        ));
+
+        let patch = parse_patch(&patch).unwrap();
+        let chunks = match patch.hunks.as_slice() {
+            [Hunk::UpdateFile { chunks, .. }] => chunks,
+            _ => panic!("Expected a single UpdateFile hunk"),
+        };
+
+        let path_uri = PathUri::from_host_native_path(&path).expect("absolute test path");
+        let diff =
+            unified_diff_from_chunks(&path_uri, chunks, LOCAL_FS.as_ref(), /*sandbox*/ None)
+                .await
+                .unwrap();
+        let expected_diff = r#"@@ -3 +3,2 @@
+ baz
++quux
+"#;
+        let expected = ApplyPatchFileUpdate {
+            unified_diff: expected_diff.to_string(),
+            original_content: "foo\nbar\nbaz\n".to_string(),
+            content: "foo\nbar\nbaz\nquux\n".to_string(),
+        };
+        assert_eq!(expected, diff);
+    }
+
+    #[tokio::test]
+    async fn test_apply_patch_should_resolve_absolute_paths_in_cwd() {
+        let session_dir = tempdir().unwrap();
+        let relative_path = "source.txt";
+
+        // Note that we need this file to exist for the patch to be "verified"
+        // and parsed correctly.
+        let session_file_path = session_dir.path().join(relative_path);
+        fs::write(&session_file_path, "session directory content\n").unwrap();
+
+        let argv = vec![
+            "apply_patch".to_string(),
+            r#"*** Begin Patch
+*** Update File: source.txt
+@@
+-session directory content
++updated session directory content
+*** End Patch"#
+                .to_string(),
+        ];
+
+        let result = maybe_parse_apply_patch_verified(
+            &argv,
+            &PathUri::from_host_native_path(session_dir.path()).expect("absolute test path"),
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await;
+
+        // Verify the patch contents - as otherwise we may have pulled contents
+        // from the wrong file (as we're using relative paths)
+        assert_eq!(
+            result,
+            MaybeApplyPatchVerified::Body(ApplyPatchAction {
+                changes: HashMap::from([(
+                    PathUri::from_host_native_path(session_dir.path().join(relative_path))
+                        .expect("absolute test path"),
+                    ApplyPatchFileChange::Update {
+                        unified_diff: r#"@@ -1 +1 @@
+-session directory content
++updated session directory content
+"#
+                        .to_string(),
+                        move_path: None,
+                        new_content: "updated session directory content\n".to_string(),
+                    },
+                )]),
+                update_file_mode: ApplyPatchFileUpdateMode::default(),
+                patch: argv[1].clone(),
+                cwd: PathUri::from_host_native_path(session_dir.path())
+                    .expect("absolute test path"),
+            })
+        );
+    }
+
+    #[tokio::test]
+    async fn test_apply_patch_resolves_move_path_with_effective_cwd() {
+        let session_dir = tempdir().unwrap();
+        let worktree_rel = "alt";
+        let worktree_dir = session_dir.path().join(worktree_rel);
+        fs::create_dir_all(&worktree_dir).unwrap();
+
+        let source_name = "old.txt";
+        let dest_name = "renamed.txt";
+        let source_path = worktree_dir.join(source_name);
+        fs::write(&source_path, "before\n").unwrap();
+
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {source_name}
+*** Move to: {dest_name}
+@@
+-before
++after"#
+        ));
+
+        let shell_script = format!("cd {worktree_rel} && apply_patch <<'PATCH'\n{patch}\nPATCH");
+        let argv = vec!["bash".into(), "-lc".into(), shell_script];
+
+        let result = maybe_parse_apply_patch_verified(
+            &argv,
+            &PathUri::from_host_native_path(session_dir.path()).expect("absolute test path"),
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await;
+        let action = match result {
+            MaybeApplyPatchVerified::Body(action) => action,
+            other => panic!("expected verified body, got {other:?}"),
+        };
+
+        assert_eq!(
+            action.cwd.to_abs_path().unwrap().as_path(),
+            worktree_dir.as_path()
+        );
+
+        let source_path = PathUri::from_host_native_path(worktree_dir.join(source_name))
+            .expect("absolute test path");
+        let change = action
+            .changes()
+            .get(&source_path)
+            .expect("source file change present");
+
+        match change {
+            ApplyPatchFileChange::Update { move_path, .. } => {
+                let expected_move_path =
+                    PathUri::from_host_native_path(worktree_dir.join(dest_name))
+                        .expect("absolute test path");
+                assert_eq!(move_path.as_ref(), Some(&expected_move_path));
+            }
+            other => panic!("expected update change, got {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn test_unreadable_destinations_still_verify() {
+        let session_dir = tempdir().unwrap();
+        fs::write(session_dir.path().join("binary.dat"), [0xff, 0xfe, 0xfd]).unwrap();
+        let cwd = PathUri::from_host_native_path(session_dir.path()).expect("absolute test path");
+        let add_argv = vec![
+            "apply_patch".to_string(),
+            "*** Begin Patch\n*** Add File: binary.dat\n+text\n*** End Patch".to_string(),
+        ];
+        fs::write(session_dir.path().join("source.txt"), "before\n").unwrap();
+        let move_argv = vec![
+            "apply_patch".to_string(),
+            "*** Begin Patch\n*** Update File: source.txt\n*** Move to: binary.dat\n@@\n-before\n+after\n*** End Patch".to_string(),
+        ];
+
+        for argv in [add_argv, move_argv] {
+            let result = maybe_parse_apply_patch_verified(
+                &argv,
+                &cwd,
+                LOCAL_FS.as_ref(),
+                /*sandbox*/ None,
+            )
+            .await;
+
+            assert!(matches!(result, MaybeApplyPatchVerified::Body(_)));
+        }
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn test_delete_symlink_still_verifies() {
+        use std::os::unix::fs::symlink;
+
+        let session_dir = tempdir().unwrap();
+        fs::write(session_dir.path().join("target.txt"), "target\n").unwrap();
+        symlink(
+            session_dir.path().join("target.txt"),
+            session_dir.path().join("link.txt"),
+        )
+        .unwrap();
+        let argv = vec![
+            "apply_patch".to_string(),
+            "*** Begin Patch\n*** Delete File: link.txt\n*** End Patch".to_string(),
+        ];
+
+        let result = maybe_parse_apply_patch_verified(
+            &argv,
+            &PathUri::from_host_native_path(session_dir.path()).expect("absolute test path"),
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await;
+
+        assert!(matches!(result, MaybeApplyPatchVerified::Body(_)));
+    }
+}
diff --git a/codex-rs/apply-patch/src/lib.rs b/codex-rs/apply-patch/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0ee7a4e7ec811751c68984b7e05a0d969d7ae089
--- /dev/null
+++ b/codex-rs/apply-patch/src/lib.rs
@@ -0,0 +1,1444 @@
+mod file_update;
+mod invocation;
+mod parser;
+mod seek_sequence;
+mod standalone_executable;
+mod streaming_parser;
+mod text_file;
+
+use std::collections::HashMap;
+use std::io;
+use std::path::PathBuf;
+
+use anyhow::Context;
+use anyhow::Result;
+use codex_exec_server::CreateDirectoryOptions;
+use codex_exec_server::ExecutorFileSystem;
+use codex_exec_server::FileSystemSandboxContext;
+use codex_exec_server::GetMetadataOptions;
+use codex_exec_server::ReadFileOptions;
+use codex_exec_server::RemoveOptions;
+use codex_exec_server::WriteFileOptions;
+use codex_utils_path_uri::PathUri;
+use codex_utils_path_uri::PathUriParseError;
+pub use parser::Hunk;
+pub use parser::ParseError;
+use parser::ParseError::*;
+pub use parser::UpdateFileChunk;
+pub use parser::parse_patch;
+pub use streaming_parser::StreamingPatchParser;
+use thiserror::Error;
+
+use file_update::AppliedPatch;
+pub use file_update::ApplyPatchFileUpdate;
+use file_update::derive_new_contents_from_chunks;
+pub use file_update::unified_diff_from_chunks;
+pub use file_update::unified_diff_from_chunks_with_context;
+pub(crate) use file_update::unified_diff_from_chunks_with_mode;
+pub use invocation::MaybeApplyPatch;
+pub use invocation::maybe_parse_apply_patch;
+pub use invocation::maybe_parse_apply_patch_verified;
+pub use invocation::maybe_parse_apply_patch_verified_with_mode;
+pub use invocation::verify_apply_patch_args;
+pub use invocation::verify_apply_patch_args_with_mode;
+pub use standalone_executable::main;
+
+use crate::invocation::ExtractHeredocError;
+
+/// Special argv[1] flag used when the Codex executable self-invokes to run the
+/// internal `apply_patch` path.
+///
+/// Although this constant lives in `codex-apply-patch` (to avoid forcing
+/// `codex-arg0` to depend on `codex-core`), it remains part of the "codex core"
+/// process-invocation contract for the standalone `apply_patch` command
+/// surface.
+pub const CODEX_CORE_APPLY_PATCH_ARG1: &str = "--codex-run-as-apply-patch";
+
+/// Internal environment variable used to carry the selected update mode
+/// through the arg0-dispatched standalone executable.
+pub const CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR: &str =
+    "CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS";
+
+/// Controls how updates reconstruct the target file after matching a patch.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum ApplyPatchFileUpdateMode {
+    /// Preserve the historical behavior of normalizing updated files to LF.
+    #[default]
+    NormalizeToLf,
+    /// Preserve existing line endings and use the file's preferred ending for new lines.
+    PreserveLineEndings,
+}
+
+/// Policy for one patch application. Standalone callers follow symlinks by default.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ApplyPatchOptions {
+    pub update_file_mode: ApplyPatchFileUpdateMode,
+    /// Whether filesystem operations may resolve symlinks in any path component.
+    pub follow_symlinks: bool,
+}
+
+impl Default for ApplyPatchOptions {
+    fn default() -> Self {
+        Self {
+            update_file_mode: ApplyPatchFileUpdateMode::default(),
+            follow_symlinks: true,
+        }
+    }
+}
+
+/// Reads the update mode selected for an arg0-dispatched `apply_patch` process.
+#[doc(hidden)]
+pub fn apply_patch_file_update_mode_from_env() -> ApplyPatchFileUpdateMode {
+    match std::env::var(CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR).as_deref() {
+        Ok("1") => ApplyPatchFileUpdateMode::PreserveLineEndings,
+        _ => ApplyPatchFileUpdateMode::NormalizeToLf,
+    }
+}
+
+#[derive(Debug, Error, PartialEq)]
+pub enum ApplyPatchError {
+    #[error(transparent)]
+    ParseError(#[from] ParseError),
+    #[error(transparent)]
+    IoError(#[from] IoError),
+    /// Error that occurs while computing replacements when applying patch chunks
+    #[error("{0}")]
+    ComputeReplacements(String),
+    /// A patch path could not be resolved as a path URI.
+    #[error(transparent)]
+    PathUri(#[from] PathUriParseError),
+    /// A raw patch body was provided without an explicit `apply_patch` invocation.
+    #[error(
+        "patch detected without explicit call to apply_patch. Rerun as [\"apply_patch\", \"<patch>\"]"
+    )]
+    ImplicitInvocation,
+}
+
+impl From<std::io::Error> for ApplyPatchError {
+    fn from(err: std::io::Error) -> Self {
+        ApplyPatchError::IoError(IoError {
+            context: "I/O error".to_string(),
+            source: err,
+        })
+    }
+}
+
+impl From<&std::io::Error> for ApplyPatchError {
+    fn from(err: &std::io::Error) -> Self {
+        ApplyPatchError::IoError(IoError {
+            context: "I/O error".to_string(),
+            source: std::io::Error::new(err.kind(), err.to_string()),
+        })
+    }
+}
+
+#[derive(Debug, Error)]
+#[error("{context}: {source}")]
+pub struct IoError {
+    context: String,
+    #[source]
+    source: std::io::Error,
+}
+
+impl PartialEq for IoError {
+    fn eq(&self, other: &Self) -> bool {
+        self.context == other.context && self.source.to_string() == other.source.to_string()
+    }
+}
+
+/// Both the raw PATCH argument to `apply_patch` as well as the PATCH argument
+/// parsed into hunks.
+#[derive(Debug, PartialEq)]
+pub struct ApplyPatchArgs {
+    pub patch: String,
+    pub hunks: Vec<Hunk>,
+    pub workdir: Option<String>,
+    pub environment_id: Option<String>,
+}
+
+#[derive(Debug, PartialEq)]
+pub enum ApplyPatchFileChange {
+    Add {
+        content: String,
+    },
+    Delete {
+        content: String,
+    },
+    Update {
+        unified_diff: String,
+        move_path: Option<PathUri>,
+        /// new_content that will result after the unified_diff is applied.
+        new_content: String,
+    },
+}
+
+#[derive(Debug, PartialEq)]
+pub enum MaybeApplyPatchVerified {
+    /// `argv` corresponded to an `apply_patch` invocation, and these are the
+    /// resulting proposed file changes.
+    Body(ApplyPatchAction),
+    /// `argv` could not be parsed to determine whether it corresponds to an
+    /// `apply_patch` invocation.
+    ShellParseError(ExtractHeredocError),
+    /// `argv` corresponded to an `apply_patch` invocation, but it could not
+    /// be fulfilled due to the specified error.
+    CorrectnessError(ApplyPatchError),
+    /// `argv` decidedly did not correspond to an `apply_patch` invocation.
+    NotApplyPatch,
+}
+
+/// ApplyPatchAction is the result of parsing an `apply_patch` command. By
+/// construction, all paths should be absolute paths.
+#[derive(Debug, PartialEq)]
+pub struct ApplyPatchAction {
+    changes: HashMap<PathUri, ApplyPatchFileChange>,
+
+    update_file_mode: ApplyPatchFileUpdateMode,
+
+    /// The raw patch argument that can be used to apply the patch. i.e., if the
+    /// original arg was parsed in "lenient" mode with a
+    /// heredoc, this should be the value without the heredoc wrapper.
+    pub patch: String,
+
+    /// The working directory that was used to resolve relative paths in the patch.
+    pub cwd: PathUri,
+}
+
+impl ApplyPatchAction {
+    pub fn is_empty(&self) -> bool {
+        self.changes.is_empty()
+    }
+
+    /// Returns the changes that would be made by applying the patch.
+    pub fn changes(&self) -> &HashMap<PathUri, ApplyPatchFileChange> {
+        &self.changes
+    }
+
+    /// Returns the update mode selected while the patch was verified.
+    pub fn update_file_mode(&self) -> ApplyPatchFileUpdateMode {
+        self.update_file_mode
+    }
+
+    /// Should be used exclusively for testing. (Not worth the overhead of
+    /// creating a feature flag for this.)
+    pub fn new_add_for_test(path: &PathUri, content: String) -> Self {
+        #[expect(clippy::expect_used)]
+        let filename = path.basename().expect("path should not be empty");
+        let patch = format!(
+            r#"*** Begin Patch
+*** Update File: {filename}
+@@
++ {content}
+*** End Patch"#,
+        );
+        let changes = HashMap::from([(path.clone(), ApplyPatchFileChange::Add { content })]);
+        #[expect(clippy::expect_used)]
+        Self {
+            changes,
+            update_file_mode: ApplyPatchFileUpdateMode::default(),
+            cwd: path.parent().expect("path should have parent"),
+            patch,
+        }
+    }
+}
+
+/// Textual file changes that were actually committed while applying a patch.
+#[derive(Clone, Debug, PartialEq)]
+pub struct AppliedPatchDelta {
+    changes: Vec<AppliedPatchChange>,
+    exact: bool,
+}
+
+impl AppliedPatchDelta {
+    fn new(changes: Vec<AppliedPatchChange>, exact: bool) -> Self {
+        Self { changes, exact }
+    }
+
+    fn empty() -> Self {
+        Self::new(Vec::new(), /*exact*/ true)
+    }
+
+    pub fn changes(&self) -> &[AppliedPatchChange] {
+        &self.changes
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.changes.is_empty()
+    }
+
+    pub fn is_exact(&self) -> bool {
+        self.exact
+    }
+
+    /// Appends a later committed prefix while preserving the aggregate exactness.
+    pub fn append(&mut self, other: Self) {
+        self.changes.extend(other.changes);
+        self.exact &= other.exact;
+    }
+}
+
+impl Default for AppliedPatchDelta {
+    fn default() -> Self {
+        Self::empty()
+    }
+}
+
+/// A committed file change, preserved in the order it was applied.
+#[derive(Clone, Debug, PartialEq)]
+pub struct AppliedPatchChange {
+    pub path: PathUri,
+    pub change: AppliedPatchFileChange,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum AppliedPatchFileChange {
+    Add {
+        content: String,
+        overwritten_content: Option<String>,
+    },
+    Delete {
+        content: String,
+    },
+    Update {
+        move_path: Option<PathUri>,
+        old_content: String,
+        overwritten_move_content: Option<String>,
+        new_content: String,
+    },
+}
+
+/// A failed patch application together with the textual mutations that were
+/// definitely committed before the failure was observed.
+#[derive(Debug, Error)]
+#[error("{error}")]
+pub struct ApplyPatchFailure {
+    #[source]
+    error: ApplyPatchError,
+    delta: AppliedPatchDelta,
+}
+
+impl ApplyPatchFailure {
+    fn new(error: ApplyPatchError, delta: AppliedPatchDelta) -> Self {
+        Self { error, delta }
+    }
+
+    fn without_delta(error: ApplyPatchError) -> Self {
+        Self::new(error, AppliedPatchDelta::empty())
+    }
+
+    pub fn delta(&self) -> &AppliedPatchDelta {
+        &self.delta
+    }
+
+    pub fn into_parts(self) -> (ApplyPatchError, AppliedPatchDelta) {
+        (self.error, self.delta)
+    }
+}
+
+/// Applies the patch and prints the result to stdout/stderr.
+pub async fn apply_patch(
+    patch: &str,
+    cwd: &PathUri,
+    stdout: &mut impl std::io::Write,
+    stderr: &mut impl std::io::Write,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> Result<AppliedPatchDelta, ApplyPatchFailure> {
+    apply_patch_with_options(
+        patch,
+        ApplyPatchOptions::default(),
+        cwd,
+        stdout,
+        stderr,
+        fs,
+        sandbox,
+    )
+    .await
+}
+
+/// Applies the patch using the selected options and prints the result
+/// to stdout/stderr.
+pub async fn apply_patch_with_options(
+    patch: &str,
+    options: ApplyPatchOptions,
+    cwd: &PathUri,
+    stdout: &mut impl std::io::Write,
+    stderr: &mut impl std::io::Write,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> Result<AppliedPatchDelta, ApplyPatchFailure> {
+    let hunks = match parse_patch(patch) {
+        Ok(source) => source.hunks,
+        Err(e) => {
+            match &e {
+                InvalidPatchError(message) => {
+                    writeln!(stderr, "Invalid patch: {message}")
+                        .map_err(ApplyPatchError::from)
+                        .map_err(ApplyPatchFailure::without_delta)?;
+                }
+                InvalidHunkError {
+                    message,
+                    line_number,
+                } => {
+                    writeln!(
+                        stderr,
+                        "Invalid patch hunk on line {line_number}: {message}"
+                    )
+                    .map_err(ApplyPatchError::from)
+                    .map_err(ApplyPatchFailure::without_delta)?;
+                }
+            }
+            return Err(ApplyPatchFailure::without_delta(
+                ApplyPatchError::ParseError(e),
+            ));
+        }
+    };
+
+    apply_hunks_with_options(&hunks, options, cwd, stdout, stderr, fs, sandbox).await
+}
+
+/// Applies hunks and continues to update stdout/stderr
+pub async fn apply_hunks(
+    hunks: &[Hunk],
+    cwd: &PathUri,
+    stdout: &mut impl std::io::Write,
+    stderr: &mut impl std::io::Write,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> Result<AppliedPatchDelta, ApplyPatchFailure> {
+    apply_hunks_with_options(
+        hunks,
+        ApplyPatchOptions::default(),
+        cwd,
+        stdout,
+        stderr,
+        fs,
+        sandbox,
+    )
+    .await
+}
+
+/// Applies hunks using the selected file-update mode and continues to update
+/// stdout/stderr.
+async fn apply_hunks_with_options(
+    hunks: &[Hunk],
+    options: ApplyPatchOptions,
+    cwd: &PathUri,
+    stdout: &mut impl std::io::Write,
+    stderr: &mut impl std::io::Write,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> Result<AppliedPatchDelta, ApplyPatchFailure> {
+    let mut delta = AppliedPatchDelta::empty();
+    match apply_hunks_to_files(hunks, options, cwd, fs, sandbox, &mut delta).await {
+        Ok(affected_paths) => {
+            print_summary(&affected_paths, stdout).map_err(|error| {
+                ApplyPatchFailure::new(ApplyPatchError::from(error), delta.clone())
+            })?;
+            Ok(delta)
+        }
+        Err(error) => {
+            let msg = error.to_string();
+            writeln!(stderr, "{msg}").map_err(|error| {
+                ApplyPatchFailure::new(ApplyPatchError::from(error), delta.clone())
+            })?;
+            let error = if let Some(io) = error.downcast_ref::<std::io::Error>() {
+                ApplyPatchError::from(io)
+            } else {
+                ApplyPatchError::IoError(IoError {
+                    context: msg,
+                    source: std::io::Error::other(error),
+                })
+            };
+            Err(ApplyPatchFailure::new(error, delta))
+        }
+    }
+}
+
+/// Applies each parsed patch hunk to the filesystem.
+/// Returns an error if any of the changes could not be applied.
+/// Tracks file paths affected by applying a patch, preserving the path spelling
+/// from the patch for user-facing summaries.
+pub struct AffectedPaths {
+    pub added: Vec<PathBuf>,
+    pub modified: Vec<PathBuf>,
+    pub deleted: Vec<PathBuf>,
+}
+
+/// Apply the hunks to the filesystem, returning which files were added, modified, or deleted.
+/// Returns an error if the patch could not be applied.
+async fn apply_hunks_to_files(
+    hunks: &[Hunk],
+    options: ApplyPatchOptions,
+    cwd: &PathUri,
+    fs: &dyn ExecutorFileSystem,
+    sandbox: Option<&FileSystemSandboxContext>,
+    delta: &mut AppliedPatchDelta,
+) -> anyhow::Result<AffectedPaths> {
+    let ApplyPatchOptions {
+        update_file_mode,
+        follow_symlinks,
+    } = options;
+    if hunks.is_empty() {
+        anyhow::bail!("No files were modified.");
+    }
+
+    let mut added: Vec<PathBuf> = Vec::new();
+    let mut modified: Vec<PathBuf> = Vec::new();
+    let mut deleted: Vec<PathBuf> = Vec::new();
+    // A failed write can still have modified the target before surfacing an
+    // error (for example by truncating before ENOSPC), so the accumulated
+    // delta is no longer exact when a write fails.
+    macro_rules! try_write {
+        ($result:expr) => {
+            match $result {
+                Ok(value) => value,
+                Err(error) => {
+                    delta.exact = false;
+                    return Err(anyhow::Error::from(error));
+                }
+            }
+        };
+    }
+
+    for hunk in hunks {
+        let affected_path = hunk.path().to_path_buf();
+        let path_uri = hunk.resolve_path(cwd)?;
+        match hunk {
+            Hunk::AddFile { contents, .. } => {
+                let overwritten_content = read_optional_file_text_for_delta(
+                    &path_uri,
+                    fs,
+                    follow_symlinks,
+                    sandbox,
+                    &mut delta.exact,
+                )
+                .await;
+                try_write!(
+                    write_file_with_missing_parent_retry(
+                        fs,
+                        &path_uri,
+                        contents.clone().into_bytes(),
+                        follow_symlinks,
+                        sandbox,
+                    )
+                    .await
+                );
+                delta.changes.push(AppliedPatchChange {
+                    path: path_uri,
+                    change: AppliedPatchFileChange::Add {
+                        content: contents.clone(),
+                        overwritten_content,
+                    },
+                });
+                added.push(affected_path);
+            }
+            Hunk::DeleteFile { .. } => {
+                note_existing_path_delta_support(
+                    &path_uri,
+                    fs,
+                    follow_symlinks,
+                    sandbox,
+                    &mut delta.exact,
+                )
+                .await;
+                let deleted_content = fs
+                    .read_file_text(&path_uri, ReadFileOptions { follow_symlinks }, sandbox)
+                    .await
+                    .ok();
+                if deleted_content.is_none() {
+                    delta.exact = false;
+                }
+                ensure_not_directory(&path_uri, fs, follow_symlinks, sandbox)
+                    .await
+                    .with_context(|| {
+                        format!(
+                            "Failed to delete file {}",
+                            path_uri.inferred_native_path_string()
+                        )
+                    })?;
+                if let Err(error) = fs
+                    .remove(
+                        &path_uri,
+                        RemoveOptions {
+                            recursive: false,
+                            force: false,
+                            follow_symlinks,
+                        },
+                        sandbox,
+                    )
+                    .await
+                    .with_context(|| {
+                        format!(
+                            "Failed to delete file {}",
+                            path_uri.inferred_native_path_string()
+                        )
+                    })
+                {
+                    delta.exact &= remove_failure_was_side_effect_free(
+                        &path_uri,
+                        deleted_content.as_deref(),
+                        fs,
+                        follow_symlinks,
+                        sandbox,
+                    )
+                    .await;
+                    return Err(error);
+                }
+                if let Some(content) = deleted_content {
+                    delta.changes.push(AppliedPatchChange {
+                        path: path_uri,
+                        change: AppliedPatchFileChange::Delete { content },
+                    });
+                }
+                deleted.push(affected_path);
+            }
+            Hunk::UpdateFile {
+                move_path, chunks, ..
+            } => {
+                note_existing_path_delta_support(
+                    &path_uri,
+                    fs,
+                    follow_symlinks,
+                    sandbox,
+                    &mut delta.exact,
+                )
+                .await;
+                let AppliedPatch {
+                    original_contents,
+                    new_contents,
+                } = derive_new_contents_from_chunks(
+                    &path_uri,
+                    chunks,
+                    update_file_mode,
+                    fs,
+                    follow_symlinks,
+                    sandbox,
+                )
+                .await?;
+                if let Some(dest) = move_path {
+                    let dest_uri = cwd.join(&dest.to_string_lossy())?;
+                    let overwritten_move_content = read_optional_file_text_for_delta(
+                        &dest_uri,
+                        fs,
+                        follow_symlinks,
+                        sandbox,
+                        &mut delta.exact,
+                    )
+                    .await;
+                    try_write!(
+                        write_file_with_missing_parent_retry(
+                            fs,
+                            &dest_uri,
+                            new_contents.clone().into_bytes(),
+                            follow_symlinks,
+                            sandbox,
+                        )
+                        .await
+                    );
+                    let dest_write_change_index = delta.changes.len();
+                    delta.changes.push(AppliedPatchChange {
+                        path: dest_uri.clone(),
+                        change: AppliedPatchFileChange::Add {
+                            content: new_contents.clone(),
+                            overwritten_content: overwritten_move_content.clone(),
+                        },
+                    });
+                    ensure_not_directory(&path_uri, fs, follow_symlinks, sandbox)
+                        .await
+                        .with_context(|| {
+                            format!(
+                                "Failed to remove original {}",
+                                path_uri.inferred_native_path_string()
+                            )
+                        })?;
+                    if let Err(error) = fs
+                        .remove(
+                            &path_uri,
+                            RemoveOptions {
+                                recursive: false,
+                                force: false,
+                                follow_symlinks,
+                            },
+                            sandbox,
+                        )
+                        .await
+                        .with_context(|| {
+                            format!(
+                                "Failed to remove original {}",
+                                path_uri.inferred_native_path_string()
+                            )
+                        })
+                    {
+                        delta.exact &= remove_failure_was_side_effect_free(
+                            &path_uri,
+                            Some(&original_contents),
+                            fs,
+                            follow_symlinks,
+                            sandbox,
+                        )
+                        .await;
+                        return Err(error);
+                    }
+                    delta.changes[dest_write_change_index] = AppliedPatchChange {
+                        path: path_uri,
+                        change: AppliedPatchFileChange::Update {
+                            move_path: Some(dest_uri),
+                            old_content: original_contents,
+                            overwritten_move_content,
+                            new_content: new_contents,
+                        },
+                    };
+                    modified.push(affected_path);
+                } else {
+                    try_write!(
+                        fs.write_file(
+                            &path_uri,
+                            new_contents.clone().into_bytes(),
+                            WriteFileOptions { follow_symlinks },
+                            sandbox,
+                        )
+                        .await
+                        .with_context(|| format!(
+                            "Failed to write file {}",
+                            path_uri.inferred_native_path_string()
+                        ))
+                    );
+                    delta.changes.push(AppliedPatchChange {
+                        path: path_uri,
+                        change: AppliedPatchFileChange::Update {
+                            move_path: None,
+                            old_content: original_contents,
+                            overwritten_move_content: None,
+                            new_content: new_contents,
+                        },
+                    });
+                    modified.push(affected_path);
+                }
+            }
+        }
+    }
+    Ok(AffectedPaths {
+        added,
+        modified,
+        deleted,
+    })
+}
+
+async fn ensure_not_directory(
+    path: &PathUri,
+    fs: &dyn ExecutorFileSystem,
+    follow_symlinks: bool,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> io::Result<()> {
+    let metadata = fs
+        .get_metadata(path, GetMetadataOptions { follow_symlinks }, sandbox)
+        .await?;
+    if metadata.is_directory {
+        return Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "path is a directory",
+        ));
+    }
+    Ok(())
+}
+
+async fn remove_failure_was_side_effect_free(
+    path: &PathUri,
+    expected_content: Option<&str>,
+    fs: &dyn ExecutorFileSystem,
+    follow_symlinks: bool,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> bool {
+    match expected_content {
+        Some(expected_content) => fs
+            .read_file_text(path, ReadFileOptions { follow_symlinks }, sandbox)
+            .await
+            .is_ok_and(|content| content == expected_content),
+        None => false,
+    }
+}
+
+async fn read_optional_file_text_for_delta(
+    path: &PathUri,
+    fs: &dyn ExecutorFileSystem,
+    follow_symlinks: bool,
+    sandbox: Option<&FileSystemSandboxContext>,
+    exact: &mut bool,
+) -> Option<String> {
+    note_existing_path_delta_support(path, fs, follow_symlinks, sandbox, exact).await;
+    match fs
+        .read_file_text(path, ReadFileOptions { follow_symlinks }, sandbox)
+        .await
+    {
+        Ok(content) => Some(content),
+        Err(source) if source.kind() == io::ErrorKind::NotFound => None,
+        Err(_) => {
+            *exact = false;
+            None
+        }
+    }
+}
+
+async fn note_existing_path_delta_support(
+    path: &PathUri,
+    fs: &dyn ExecutorFileSystem,
+    follow_symlinks: bool,
+    sandbox: Option<&FileSystemSandboxContext>,
+    exact: &mut bool,
+) {
+    match fs
+        .get_metadata(path, GetMetadataOptions { follow_symlinks }, sandbox)
+        .await
+    {
+        Ok(metadata) if metadata.is_file && !metadata.is_symlink => {}
+        Ok(_) => *exact = false,
+        Err(source) if source.kind() == io::ErrorKind::NotFound => {}
+        Err(_) => *exact = false,
+    }
+}
+
+async fn write_file_with_missing_parent_retry(
+    fs: &dyn ExecutorFileSystem,
+    path: &PathUri,
+    contents: Vec<u8>,
+    follow_symlinks: bool,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> anyhow::Result<()> {
+    match fs
+        .write_file(
+            path,
+            contents.clone(),
+            WriteFileOptions { follow_symlinks },
+            sandbox,
+        )
+        .await
+    {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == io::ErrorKind::NotFound => {
+            if let Some(parent) = path.parent() {
+                fs.create_directory(
+                    &parent,
+                    CreateDirectoryOptions {
+                        recursive: true,
+                        follow_symlinks,
+                    },
+                    sandbox,
+                )
+                .await
+                .with_context(|| {
+                    format!(
+                        "Failed to create parent directories for {}",
+                        path.inferred_native_path_string()
+                    )
+                })?;
+            }
+            fs.write_file(
+                path,
+                contents,
+                WriteFileOptions { follow_symlinks },
+                sandbox,
+            )
+            .await
+            .with_context(|| {
+                format!(
+                    "Failed to write file {}",
+                    path.inferred_native_path_string()
+                )
+            })?;
+            Ok(())
+        }
+        Err(err) => Err(err).with_context(|| {
+            format!(
+                "Failed to write file {}",
+                path.inferred_native_path_string()
+            )
+        }),
+    }
+}
+
+/// Print the summary of changes in git-style format.
+/// Write a summary of changes to the given writer.
+pub fn print_summary(
+    affected: &AffectedPaths,
+    out: &mut impl std::io::Write,
+) -> std::io::Result<()> {
+    writeln!(out, "Success. Updated the following files:")?;
+    for path in &affected.added {
+        writeln!(out, "A {}", path.display())?;
+    }
+    for path in &affected.modified {
+        writeln!(out, "M {}", path.display())?;
+    }
+    for path in &affected.deleted {
+        writeln!(out, "D {}", path.display())?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_exec_server::LOCAL_FS;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use tempfile::tempdir;
+
+    /// Helper to construct a patch with the given body.
+    fn wrap_patch(body: &str) -> String {
+        format!("*** Begin Patch\n{body}\n*** End Patch")
+    }
+
+    #[tokio::test]
+    async fn test_add_file_hunk_creates_file_with_contents() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("add.txt");
+        let patch = wrap_patch(&format!(
+            r#"*** Add File: {}
++ab
++cd"#,
+            path.display()
+        ));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+        // Verify expected stdout and stderr outputs.
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let stderr_str = String::from_utf8(stderr).unwrap();
+        let expected_out = format!(
+            "Success. Updated the following files:\nA {}\n",
+            path.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+        assert_eq!(stderr_str, "");
+        let contents = fs::read_to_string(path).unwrap();
+        assert_eq!(contents, "ab\ncd\n");
+    }
+
+    #[tokio::test]
+    async fn test_apply_patch_hunks_accept_relative_and_absolute_paths() {
+        let dir = tempdir().unwrap();
+        let cwd = PathUri::from_host_native_path(dir.path()).expect("absolute test path");
+        let relative_add = dir.path().join("relative-add.txt");
+        let absolute_add = dir.path().join("absolute-add.txt");
+        let relative_delete = dir.path().join("relative-delete.txt");
+        let absolute_delete = dir.path().join("absolute-delete.txt");
+        let relative_update = dir.path().join("relative-update.txt");
+        let absolute_update = dir.path().join("absolute-update.txt");
+        fs::write(&relative_delete, "delete relative\n").unwrap();
+        fs::write(&absolute_delete, "delete absolute\n").unwrap();
+        fs::write(&relative_update, "relative old\n").unwrap();
+        fs::write(&absolute_update, "absolute old\n").unwrap();
+
+        let patch = wrap_patch(&format!(
+            r#"*** Add File: relative-add.txt
++relative add
+*** Add File: {}
++absolute add
+*** Delete File: relative-delete.txt
+*** Delete File: {}
+*** Update File: relative-update.txt
+@@
+-relative old
++relative new
+*** Update File: {}
+@@
+-absolute old
++absolute new"#,
+            absolute_add.display(),
+            absolute_delete.display(),
+            absolute_update.display(),
+        ));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+
+        apply_patch(
+            &patch,
+            &cwd,
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+
+        assert_eq!(fs::read_to_string(&relative_add).unwrap(), "relative add\n");
+        assert_eq!(fs::read_to_string(&absolute_add).unwrap(), "absolute add\n");
+        assert!(!relative_delete.exists());
+        assert!(!absolute_delete.exists());
+        assert_eq!(
+            fs::read_to_string(&relative_update).unwrap(),
+            "relative new\n"
+        );
+        assert_eq!(
+            fs::read_to_string(&absolute_update).unwrap(),
+            "absolute new\n"
+        );
+        assert_eq!(String::from_utf8(stderr).unwrap(), "");
+        assert_eq!(
+            String::from_utf8(stdout).unwrap(),
+            format!(
+                "Success. Updated the following files:\nA relative-add.txt\nA {}\nM relative-update.txt\nM {}\nD relative-delete.txt\nD {}\n",
+                absolute_add.display(),
+                absolute_update.display(),
+                absolute_delete.display(),
+            )
+        );
+    }
+
+    #[tokio::test]
+    async fn test_delete_file_hunk_removes_file() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("del.txt");
+        fs::write(&path, "x").unwrap();
+        let patch = wrap_patch(&format!("*** Delete File: {}", path.display()));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let stderr_str = String::from_utf8(stderr).unwrap();
+        let expected_out = format!(
+            "Success. Updated the following files:\nD {}\n",
+            path.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+        assert_eq!(stderr_str, "");
+        assert!(!path.exists());
+    }
+
+    #[tokio::test]
+    async fn test_update_file_hunk_modifies_content() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("update.txt");
+        fs::write(&path, "foo\nbar\n").unwrap();
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
+ foo
+-bar
++baz"#,
+            path.display()
+        ));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+        // Validate modified file contents and expected stdout/stderr.
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let stderr_str = String::from_utf8(stderr).unwrap();
+        let expected_out = format!(
+            "Success. Updated the following files:\nM {}\n",
+            path.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+        assert_eq!(stderr_str, "");
+        let contents = fs::read_to_string(&path).unwrap();
+        assert_eq!(contents, "foo\nbaz\n");
+    }
+
+    #[tokio::test]
+    async fn test_update_file_hunk_can_move_file() {
+        let dir = tempdir().unwrap();
+        let src = dir.path().join("src.txt");
+        let dest = dir.path().join("dst.txt");
+        fs::write(&src, "line\n").unwrap();
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+*** Move to: {}
+@@
+-line
++line2"#,
+            src.display(),
+            dest.display()
+        ));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+        // Validate move semantics and expected stdout/stderr.
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let stderr_str = String::from_utf8(stderr).unwrap();
+        let expected_out = format!(
+            "Success. Updated the following files:\nM {}\n",
+            dest.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+        assert_eq!(stderr_str, "");
+        assert!(!src.exists());
+        let contents = fs::read_to_string(&dest).unwrap();
+        assert_eq!(contents, "line2\n");
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn test_failed_move_returns_committed_destination_delta() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = tempdir().unwrap();
+        let source_dir = dir.path().join("locked");
+        let dest_dir = dir.path().join("out");
+        fs::create_dir(&source_dir).unwrap();
+        fs::create_dir(&dest_dir).unwrap();
+        let src = source_dir.join("src.txt");
+        let dest = dest_dir.join("dst.txt");
+        fs::write(&src, "line\n").unwrap();
+        fs::set_permissions(&source_dir, fs::Permissions::from_mode(0o555)).unwrap();
+
+        let patch = wrap_patch(
+            "*** Update File: locked/src.txt\n*** Move to: out/dst.txt\n@@\n-line\n+line2",
+        );
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let failure = apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .expect_err("source removal should fail after destination write");
+
+        fs::set_permissions(&source_dir, fs::Permissions::from_mode(0o755)).unwrap();
+
+        assert!(
+            String::from_utf8(stderr)
+                .unwrap()
+                .contains(&format!("Failed to remove original {}", src.display()))
+        );
+        assert_eq!(
+            failure.delta(),
+            &AppliedPatchDelta::new(
+                vec![AppliedPatchChange {
+                    path: PathUri::from_host_native_path(&dest).expect("absolute destination path"),
+                    change: AppliedPatchFileChange::Add {
+                        content: "line2\n".to_string(),
+                        overwritten_content: None,
+                    },
+                }],
+                /*exact*/ true,
+            )
+        );
+        assert_eq!(fs::read_to_string(src).unwrap(), "line\n");
+        assert_eq!(fs::read_to_string(dest).unwrap(), "line2\n");
+    }
+
+    /// Verify that a single `Update File` hunk with multiple change chunks can update different
+    /// parts of a file and that the file is listed only once in the summary.
+    #[tokio::test]
+    async fn test_multiple_update_chunks_apply_to_single_file() {
+        // Start with a file containing four lines.
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("multi.txt");
+        fs::write(&path, "foo\nbar\nbaz\nqux\n").unwrap();
+        // Construct an update patch with two separate change chunks.
+        // The first chunk uses the line `foo` as context and transforms `bar` into `BAR`.
+        // The second chunk uses `baz` as context and transforms `qux` into `QUX`.
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
+ foo
+-bar
++BAR
+@@
+ baz
+-qux
++QUX"#,
+            path.display()
+        ));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let stderr_str = String::from_utf8(stderr).unwrap();
+        let expected_out = format!(
+            "Success. Updated the following files:\nM {}\n",
+            path.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+        assert_eq!(stderr_str, "");
+        let contents = fs::read_to_string(&path).unwrap();
+        assert_eq!(contents, "foo\nBAR\nbaz\nQUX\n");
+    }
+
+    /// A more involved `Update File` hunk that exercises additions, deletions and
+    /// replacements in separate chunks that appear in non‑adjacent parts of the
+    /// file.  Verifies that all edits are applied and that the summary lists the
+    /// file only once.
+    #[tokio::test]
+    async fn test_update_file_hunk_interleaved_changes() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("interleaved.txt");
+
+        // Original file: six numbered lines.
+        fs::write(&path, "a\nb\nc\nd\ne\nf\n").unwrap();
+
+        // Patch performs:
+        //  • Replace `b` → `B`
+        //  • Replace `e` → `E` (using surrounding context)
+        //  • Append new line `g` at the end‑of‑file
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
+ a
+-b
++B
+@@
+ c
+ d
+-e
++E
+@@
+ f
++g
+*** End of File"#,
+            path.display()
+        ));
+
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let stderr_str = String::from_utf8(stderr).unwrap();
+
+        let expected_out = format!(
+            "Success. Updated the following files:\nM {}\n",
+            path.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+        assert_eq!(stderr_str, "");
+
+        let contents = fs::read_to_string(&path).unwrap();
+        assert_eq!(contents, "a\nB\nc\nd\nE\nf\ng\n");
+    }
+
+    #[tokio::test]
+    async fn test_pure_addition_chunk_followed_by_removal() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("panic.txt");
+        fs::write(&path, "line1\nline2\nline3\n").unwrap();
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
++after-context
++second-line
+@@
+ line1
+-line2
+-line3
++line2-replacement"#,
+            path.display()
+        ));
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+        let contents = fs::read_to_string(path).unwrap();
+        assert_eq!(
+            contents,
+            "line1\nline2-replacement\nafter-context\nsecond-line\n"
+        );
+    }
+
+    /// Ensure that patches authored with ASCII characters can update lines that
+    /// contain typographic Unicode punctuation (e.g. EN DASH, NON-BREAKING
+    /// HYPHEN). Historically `git apply` succeeds in such scenarios but our
+    /// internal matcher failed requiring an exact byte-for-byte match.  The
+    /// fuzzy-matching pass that normalises common punctuation should now bridge
+    /// the gap.
+    #[tokio::test]
+    async fn test_update_line_with_unicode_dash() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("unicode.py");
+
+        // Original line contains EN DASH (\u{2013}) and NON-BREAKING HYPHEN (\u{2011}).
+        let original = "import asyncio  # local import \u{2013} avoids top\u{2011}level dep\n";
+        std::fs::write(&path, original).unwrap();
+
+        // Patch uses plain ASCII dash / hyphen.
+        let patch = wrap_patch(&format!(
+            r#"*** Update File: {}
+@@
+-import asyncio  # local import - avoids top-level dep
++import asyncio  # HELLO"#,
+            path.display()
+        ));
+
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+
+        // File should now contain the replaced comment.
+        let expected = "import asyncio  # HELLO\n";
+        let contents = std::fs::read_to_string(&path).unwrap();
+        assert_eq!(contents, expected);
+
+        // Ensure success summary lists the file as modified.
+        let stdout_str = String::from_utf8(stdout).unwrap();
+        let expected_out = format!(
+            "Success. Updated the following files:\nM {}\n",
+            path.display()
+        );
+        assert_eq!(stdout_str, expected_out);
+
+        // No stderr expected.
+        assert_eq!(String::from_utf8(stderr).unwrap(), "");
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn test_apply_patch_fails_on_write_error() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = tempdir().unwrap();
+        let locked_dir = dir.path().join("locked");
+        fs::create_dir(&locked_dir).unwrap();
+        fs::set_permissions(&locked_dir, fs::Permissions::from_mode(0o555)).unwrap();
+
+        let patch = wrap_patch("*** Add File: locked/new.txt\n+after");
+
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let result = apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await;
+        let failure = result.expect_err("write should fail");
+
+        fs::set_permissions(&locked_dir, fs::Permissions::from_mode(0o755)).unwrap();
+
+        assert!(!failure.delta().is_exact());
+    }
+
+    #[tokio::test]
+    async fn test_unreadable_destinations_return_inexact_delta() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("binary.dat");
+        fs::write(dir.path().join("source.txt"), "before\n").unwrap();
+        let cwd = PathUri::from_host_native_path(dir.path()).expect("absolute test path");
+
+        for patch in [
+            wrap_patch("*** Add File: binary.dat\n+text"),
+            wrap_patch("*** Update File: source.txt\n*** Move to: binary.dat\n@@\n-before\n+after"),
+        ] {
+            fs::write(&path, [0xff, 0xfe, 0xfd]).unwrap();
+            let mut stdout = Vec::new();
+            let mut stderr = Vec::new();
+            let delta = apply_patch(
+                &patch,
+                &cwd,
+                &mut stdout,
+                &mut stderr,
+                LOCAL_FS.as_ref(),
+                /*sandbox*/ None,
+            )
+            .await
+            .unwrap();
+
+            assert!(!delta.is_exact());
+        }
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn test_delete_symlink_returns_inexact_delta() {
+        use std::os::unix::fs::symlink;
+
+        let dir = tempdir().unwrap();
+        fs::write(dir.path().join("target.txt"), "target\n").unwrap();
+        symlink(dir.path().join("target.txt"), dir.path().join("link.txt")).unwrap();
+        let patch = wrap_patch("*** Delete File: link.txt");
+
+        let mut stdout = Vec::new();
+        let mut stderr = Vec::new();
+        let delta = apply_patch(
+            &patch,
+            &PathUri::from_host_native_path(dir.path()).expect("absolute test path"),
+            &mut stdout,
+            &mut stderr,
+            LOCAL_FS.as_ref(),
+            /*sandbox*/ None,
+        )
+        .await
+        .unwrap();
+
+        assert!(!delta.is_exact());
+    }
+}
diff --git a/codex-rs/apply-patch/src/main.rs b/codex-rs/apply-patch/src/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9d3ed03361f94f22049e1e2c8b52c39c2a0b541e
--- /dev/null
+++ b/codex-rs/apply-patch/src/main.rs
@@ -0,0 +1,3 @@
+pub fn main() -> ! {
+    codex_apply_patch::main()
+}
diff --git a/codex-rs/apply-patch/src/parser.rs b/codex-rs/apply-patch/src/parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c400d075a684fda29c10269aef1958a27faf90aa
--- /dev/null
+++ b/codex-rs/apply-patch/src/parser.rs
@@ -0,0 +1,682 @@
+//! This module is responsible for parsing & validating a patch into a list of "hunks".
+//! (It does not attempt to actually check that the patch can be applied to the filesystem.)
+//!
+//! The official Lark grammar for the apply-patch format is:
+//!
+//! start: begin_patch environment_id? hunk+ end_patch
+//! begin_patch: "*** Begin Patch" LF
+//! environment_id: "*** Environment ID: " filename LF
+//! end_patch: "*** End Patch" LF?
+//!
+//! hunk: add_hunk | delete_hunk | update_hunk
+//! add_hunk: "*** Add File: " filename LF add_line+
+//! delete_hunk: "*** Delete File: " filename LF
+//! update_hunk: "*** Update File: " filename LF change_move? change?
+//! filename: /(.+)/
+//! add_line: "+" /(.+)/ LF -> line
+//!
+//! change_move: "*** Move to: " filename LF
+//! change: (change_context | change_line)+ eof_line?
+//! change_context: ("@@" | "@@ " /(.+)/) LF
+//! change_line: ("+" | "-" | " ") /(.+)/ LF
+//! eof_line: "*** End of File" LF
+//!
+//! The parser below is a little more lenient than the explicit spec and allows for
+//! leading/trailing whitespace around patch markers.
+use crate::ApplyPatchArgs;
+use crate::streaming_parser::StreamingPatchParser;
+#[cfg(test)]
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_path_uri::PathUri;
+use codex_utils_path_uri::PathUriParseError;
+use std::path::Path;
+use std::path::PathBuf;
+
+use thiserror::Error;
+
+pub(crate) const BEGIN_PATCH_MARKER: &str = "*** Begin Patch";
+pub(crate) const END_PATCH_MARKER: &str = "*** End Patch";
+pub(crate) const ADD_FILE_MARKER: &str = "*** Add File: ";
+pub(crate) const DELETE_FILE_MARKER: &str = "*** Delete File: ";
+pub(crate) const UPDATE_FILE_MARKER: &str = "*** Update File: ";
+pub(crate) const MOVE_TO_MARKER: &str = "*** Move to: ";
+pub(crate) const EOF_MARKER: &str = "*** End of File";
+pub(crate) const CHANGE_CONTEXT_MARKER: &str = "@@ ";
+pub(crate) const EMPTY_CHANGE_CONTEXT_MARKER: &str = "@@";
+
+/// Currently, the only OpenAI model that knowingly requires lenient parsing is
+/// gpt-4.1. While we could try to require everyone to pass in a strictness
+/// param when invoking apply_patch, it is a pain to thread it through all of
+/// the call sites, so we resign ourselves allowing lenient parsing for all
+/// models. See [`ParseMode::Lenient`] for details on the exceptions we make for
+/// gpt-4.1.
+const PARSE_IN_STRICT_MODE: bool = false;
+
+#[derive(Debug, PartialEq, Error, Clone)]
+pub enum ParseError {
+    #[error("invalid patch: {0}")]
+    InvalidPatchError(String),
+    #[error("invalid hunk at line {line_number}, {message}")]
+    InvalidHunkError { message: String, line_number: usize },
+}
+use ParseError::*;
+
+#[derive(Debug, PartialEq, Clone)]
+#[allow(clippy::enum_variant_names)]
+pub enum Hunk {
+    AddFile {
+        path: PathBuf,
+        contents: String,
+    },
+    DeleteFile {
+        path: PathBuf,
+    },
+    UpdateFile {
+        path: PathBuf,
+        move_path: Option<PathBuf>,
+
+        /// Chunks should be in order, i.e. the `change_context` of one chunk
+        /// should occur later in the file than the previous chunk.
+        chunks: Vec<UpdateFileChunk>,
+    },
+}
+
+impl Hunk {
+    pub fn resolve_path(&self, cwd: &PathUri) -> Result<PathUri, PathUriParseError> {
+        let path = match self {
+            Hunk::UpdateFile { path, .. } => path,
+            Hunk::AddFile { .. } | Hunk::DeleteFile { .. } => self.path(),
+        };
+        cwd.join(&path.to_string_lossy())
+    }
+
+    /// Returns the path affected by this hunk, using the move destination for rename hunks.
+    pub fn path(&self) -> &Path {
+        match self {
+            Hunk::AddFile { path, .. } => path,
+            Hunk::DeleteFile { path } => path,
+            Hunk::UpdateFile {
+                move_path: Some(path),
+                ..
+            } => path,
+            Hunk::UpdateFile {
+                path,
+                move_path: None,
+                ..
+            } => path,
+        }
+    }
+}
+
+#[cfg(test)]
+use Hunk::*;
+
+#[derive(Debug, Default, PartialEq, Clone)]
+pub struct UpdateFileChunk {
+    /// A single line of context used to narrow down the position of the chunk
+    /// (this is usually a class, method, or function definition.)
+    pub change_context: Option<String>,
+
+    /// A contiguous block of lines that should be replaced with `new_lines`.
+    /// `old_lines` must occur strictly after `change_context`.
+    pub old_lines: Vec<String>,
+    pub new_lines: Vec<String>,
+
+    /// Pairs of indices into `old_lines` and `new_lines` that identify lines
+    /// parsed as context rather than inferred to be equal by their contents.
+    pub context_line_indices: Vec<(usize, usize)>,
+
+    /// If set to true, `old_lines` must occur at the end of the source file.
+    /// (Tolerance around trailing newlines should be encouraged.)
+    pub is_end_of_file: bool,
+}
+
+impl UpdateFileChunk {
+    /// Adds a context line to both sides while recording its corresponding
+    /// indices so it remains distinguishable from identical changed lines.
+    pub(crate) fn push_context_line(&mut self, line: String) {
+        self.context_line_indices
+            .push((self.old_lines.len(), self.new_lines.len()));
+        self.old_lines.push(line.clone());
+        self.new_lines.push(line);
+    }
+}
+
+pub fn parse_patch(patch: &str) -> Result<ApplyPatchArgs, ParseError> {
+    let mode = if PARSE_IN_STRICT_MODE {
+        ParseMode::Strict
+    } else {
+        ParseMode::Lenient
+    };
+    parse_patch_text(patch, mode)
+}
+
+enum ParseMode {
+    /// Parse the patch text argument as is.
+    Strict,
+
+    /// GPT-4.1 is known to formulate the `command` array for the `local_shell`
+    /// tool call for `apply_patch` call using something like the following:
+    ///
+    /// ```json
+    /// [
+    ///   "apply_patch",
+    ///   "<<'EOF'\n*** Begin Patch\n*** Update File: README.md\n@@...\n*** End Patch\nEOF\n",
+    /// ]
+    /// ```
+    ///
+    /// This is a problem because `local_shell` is a bit of a misnomer: the
+    /// `command` is not invoked by passing the arguments to a shell like Bash,
+    /// but are invoked using something akin to `execvpe(3)`.
+    ///
+    /// This is significant in this case because where a shell would interpret
+    /// `<<'EOF'...` as a heredoc and pass the contents via stdin (which is
+    /// fine, as `apply_patch` is specified to read from stdin if no argument is
+    /// passed), `execvpe(3)` interprets the heredoc as a literal string. To get
+    /// the `local_shell` tool to run a command the way shell would, the
+    /// `command` array must be something like:
+    ///
+    /// ```json
+    /// [
+    ///   "bash",
+    ///   "-lc",
+    ///   "apply_patch <<'EOF'\n*** Begin Patch\n*** Update File: README.md\n@@...\n*** End Patch\nEOF\n",
+    /// ]
+    /// ```
+    ///
+    /// In lenient mode, we check if the argument to `apply_patch` starts with
+    /// `<<'EOF'` and ends with `EOF\n`. If so, we strip off these markers,
+    /// trim() the result, and treat what is left as the patch text.
+    Lenient,
+}
+
+fn parse_patch_text(patch: &str, mode: ParseMode) -> Result<ApplyPatchArgs, ParseError> {
+    let lines: Vec<&str> = patch.trim().lines().collect();
+    let patch_lines = match mode {
+        ParseMode::Strict => check_patch_boundaries_strict(&lines)?,
+        ParseMode::Lenient => check_patch_boundaries_lenient(&lines)?,
+    };
+
+    let patch = patch_lines.join("\n");
+    let mut parser = StreamingPatchParser::default();
+    parser.push_delta(&patch)?;
+    let hunks = parser.finish()?;
+    let environment_id = parser.environment_id().map(str::to_owned);
+    Ok(ApplyPatchArgs {
+        hunks,
+        patch,
+        workdir: None,
+        environment_id,
+    })
+}
+
+/// Checks the start and end lines of the patch text for `apply_patch`,
+/// returning an error if they do not match the expected markers.
+fn check_patch_boundaries_strict<'a>(lines: &'a [&'a str]) -> Result<&'a [&'a str], ParseError> {
+    let (first_line, last_line) = match lines {
+        [] => (None, None),
+        [first] => (Some(first), Some(first)),
+        [first, .., last] => (Some(first), Some(last)),
+    };
+    check_start_and_end_lines_strict(first_line, last_line)?;
+    Ok(lines)
+}
+
+/// If we are in lenient mode, we check if the first line starts with `<<EOF`
+/// (possibly quoted) and the last line ends with `EOF`. There must be at least
+/// 4 lines total because the heredoc markers take up 2 lines and the patch text
+/// must have at least 2 lines.
+///
+/// If successful, returns the lines of the patch text that contain the patch
+/// contents, excluding the heredoc markers.
+fn check_patch_boundaries_lenient<'a>(
+    original_lines: &'a [&'a str],
+) -> Result<&'a [&'a str], ParseError> {
+    let original_parse_error = match check_patch_boundaries_strict(original_lines) {
+        Ok(lines) => return Ok(lines),
+        Err(e) => e,
+    };
+
+    match original_lines {
+        [first, .., last] => {
+            if (first == &"<<EOF" || first == &"<<'EOF'" || first == &"<<\"EOF\"")
+                && last.ends_with("EOF")
+                && original_lines.len() >= 4
+            {
+                let inner_lines = &original_lines[1..original_lines.len() - 1];
+                check_patch_boundaries_strict(inner_lines)
+            } else {
+                Err(original_parse_error)
+            }
+        }
+        _ => Err(original_parse_error),
+    }
+}
+
+fn check_start_and_end_lines_strict(
+    first_line: Option<&&str>,
+    last_line: Option<&&str>,
+) -> Result<(), ParseError> {
+    let first_line = first_line.map(|line| line.trim());
+    let last_line = last_line.map(|line| line.trim());
+
+    match (first_line, last_line) {
+        (Some(first), Some(last)) if first == BEGIN_PATCH_MARKER && last == END_PATCH_MARKER => {
+            Ok(())
+        }
+        (Some(first), _) if first != BEGIN_PATCH_MARKER => Err(InvalidPatchError(String::from(
+            "The first line of the patch must be '*** Begin Patch'",
+        ))),
+        _ => Err(InvalidPatchError(String::from(
+            "The last line of the patch must be '*** End Patch'",
+        ))),
+    }
+}
+
+#[test]
+fn test_parse_patch() {
+    assert_eq!(
+        parse_patch_text("bad", ParseMode::Strict),
+        Err(InvalidPatchError(
+            "The first line of the patch must be '*** Begin Patch'".to_string()
+        ))
+    );
+    assert_eq!(
+        parse_patch_text("*** Begin Patch\nbad", ParseMode::Strict),
+        Err(InvalidPatchError(
+            "The last line of the patch must be '*** End Patch'".to_string()
+        ))
+    );
+
+    assert_eq!(
+        parse_patch_text(
+            concat!(
+                "*** Begin Patch",
+                " ",
+                "\n*** Add File: foo\n+hi\n",
+                " ",
+                "*** End Patch"
+            ),
+            ParseMode::Strict
+        )
+        .unwrap()
+        .hunks,
+        vec![AddFile {
+            path: PathBuf::from("foo"),
+            contents: "hi\n".to_string()
+        }]
+    );
+    assert_eq!(
+        parse_patch_text(
+            "*** Begin Patch\n\
+             *** Update File: test.py\n\
+             *** End Patch",
+            ParseMode::Strict
+        ),
+        Err(InvalidHunkError {
+            message: "Update file hunk for path 'test.py' is empty".to_string(),
+            line_number: 2,
+        })
+    );
+    assert_eq!(
+        parse_patch_text(
+            "*** Begin Patch\n\
+             *** End Patch",
+            ParseMode::Strict
+        )
+        .unwrap()
+        .hunks,
+        Vec::new()
+    );
+    assert_eq!(
+        parse_patch_text(
+            "*** Begin Patch\n\
+             *** Add File: path/add.py\n\
+             +abc\n\
+             +def\n\
+             *** Delete File: path/delete.py\n\
+             *** Update File: path/update.py\n\
+             *** Move to: path/update2.py\n\
+             @@ def f():\n\
+             -    pass\n\
+             +    return 123\n\
+             *** End Patch",
+            ParseMode::Strict
+        )
+        .unwrap()
+        .hunks,
+        vec![
+            AddFile {
+                path: PathBuf::from("path/add.py"),
+                contents: "abc\ndef\n".to_string()
+            },
+            DeleteFile {
+                path: PathBuf::from("path/delete.py")
+            },
+            UpdateFile {
+                path: PathBuf::from("path/update.py"),
+                move_path: Some(PathBuf::from("path/update2.py")),
+                chunks: vec![UpdateFileChunk {
+                    change_context: Some("def f():".to_string()),
+                    old_lines: vec!["    pass".to_string()],
+                    new_lines: vec!["    return 123".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false
+                }]
+            }
+        ]
+    );
+    // Update hunk followed by another hunk (Add File).
+    assert_eq!(
+        parse_patch_text(
+            "*** Begin Patch\n\
+             *** Update File: file.py\n\
+             @@\n\
+             +line\n\
+             *** Add File: other.py\n\
+             +content\n\
+             *** End Patch",
+            ParseMode::Strict
+        )
+        .unwrap()
+        .hunks,
+        vec![
+            UpdateFile {
+                path: PathBuf::from("file.py"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec![],
+                    new_lines: vec!["line".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false
+                }],
+            },
+            AddFile {
+                path: PathBuf::from("other.py"),
+                contents: "content\n".to_string()
+            }
+        ]
+    );
+
+    // Update hunk without an explicit @@ header for the first chunk should parse.
+    // Use a raw string to preserve the leading space diff marker on the context line.
+    assert_eq!(
+        parse_patch_text(
+            r#"*** Begin Patch
+*** Update File: file2.py
+ import foo
++bar
+*** End Patch"#,
+            ParseMode::Strict
+        )
+        .unwrap()
+        .hunks,
+        vec![UpdateFile {
+            path: PathBuf::from("file2.py"),
+            move_path: None,
+            chunks: vec![UpdateFileChunk {
+                change_context: None,
+                old_lines: vec!["import foo".to_string()],
+                new_lines: vec!["import foo".to_string(), "bar".to_string()],
+                context_line_indices: vec![(0, 0)],
+                is_end_of_file: false,
+            }],
+        }]
+    );
+}
+
+#[test]
+fn test_parse_patch_preserves_end_of_file_marker() {
+    let patch =
+        "*** Begin Patch\n*** Update File: file.txt\n@@\n+quux\n*** End of File\n\n*** End Patch";
+    assert_eq!(
+        parse_patch(patch),
+        Ok(ApplyPatchArgs {
+            hunks: vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: Vec::new(),
+                    new_lines: vec!["quux".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: true,
+                }],
+            }],
+            patch: patch.to_string(),
+            workdir: None,
+            environment_id: None,
+        })
+    );
+}
+
+#[test]
+fn test_parse_patch_accepts_relative_and_absolute_hunk_paths() {
+    let dir = tempfile::tempdir().unwrap();
+    let absolute_delete = dir.path().join("absolute-delete.py").abs();
+    let absolute_update = dir.path().join("absolute-update.py").abs();
+    let patch_text = format!(
+        r#"*** Begin Patch
+*** Add File: relative-add.py
++content
+*** Delete File: {}
+*** Update File: {}
+@@
+-old
++new
+*** End Patch"#,
+        absolute_delete.display(),
+        absolute_update.display()
+    );
+
+    assert_eq!(
+        parse_patch_text(&patch_text, ParseMode::Strict)
+            .unwrap()
+            .hunks,
+        vec![
+            AddFile {
+                path: PathBuf::from("relative-add.py"),
+                contents: "content\n".to_string()
+            },
+            DeleteFile {
+                path: absolute_delete.to_path_buf()
+            },
+            UpdateFile {
+                path: absolute_update.to_path_buf(),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec!["old".to_string()],
+                    new_lines: vec!["new".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false
+                }]
+            },
+        ]
+    );
+}
+
+#[test]
+fn test_hunk_resolve_path_accepts_relative_and_absolute_paths() {
+    let cwd_dir = tempfile::tempdir().unwrap();
+    let cwd = PathUri::from_host_native_path(cwd_dir.path()).unwrap();
+    let absolute_dir = tempfile::tempdir().unwrap();
+    let absolute_add = absolute_dir.path().join("absolute-add.py").abs();
+    let absolute_delete = absolute_dir.path().join("absolute-delete.py").abs();
+    let absolute_update = absolute_dir.path().join("absolute-update.py").abs();
+
+    for (hunk, expected_path) in [
+        (
+            AddFile {
+                path: PathBuf::from("relative-add.py"),
+                contents: String::new(),
+            },
+            cwd.join("relative-add.py").unwrap(),
+        ),
+        (
+            DeleteFile {
+                path: PathBuf::from("relative-delete.py"),
+            },
+            cwd.join("relative-delete.py").unwrap(),
+        ),
+        (
+            UpdateFile {
+                path: PathBuf::from("relative-update.py"),
+                move_path: None,
+                chunks: Vec::new(),
+            },
+            cwd.join("relative-update.py").unwrap(),
+        ),
+        (
+            AddFile {
+                path: absolute_add.to_path_buf(),
+                contents: String::new(),
+            },
+            PathUri::from_abs_path(&absolute_add),
+        ),
+        (
+            DeleteFile {
+                path: absolute_delete.to_path_buf(),
+            },
+            PathUri::from_abs_path(&absolute_delete),
+        ),
+        (
+            UpdateFile {
+                path: absolute_update.to_path_buf(),
+                move_path: None,
+                chunks: Vec::new(),
+            },
+            PathUri::from_abs_path(&absolute_update),
+        ),
+    ] {
+        assert_eq!(hunk.resolve_path(&cwd), Ok(expected_path));
+    }
+}
+
+#[test]
+fn test_parse_patch_lenient() {
+    let patch_text = r#"*** Begin Patch
+*** Update File: file2.py
+ import foo
++bar
+*** End Patch"#;
+    let expected_patch = vec![UpdateFile {
+        path: PathBuf::from("file2.py"),
+        move_path: None,
+        chunks: vec![UpdateFileChunk {
+            change_context: None,
+            old_lines: vec!["import foo".to_string()],
+            new_lines: vec!["import foo".to_string(), "bar".to_string()],
+            context_line_indices: vec![(0, 0)],
+            is_end_of_file: false,
+        }],
+    }];
+    let expected_error =
+        InvalidPatchError("The first line of the patch must be '*** Begin Patch'".to_string());
+
+    let patch_text_in_heredoc = format!("<<EOF\n{patch_text}\nEOF\n");
+    assert_eq!(
+        parse_patch_text(&patch_text_in_heredoc, ParseMode::Strict),
+        Err(expected_error.clone())
+    );
+    assert_eq!(
+        parse_patch_text(&patch_text_in_heredoc, ParseMode::Lenient),
+        Ok(ApplyPatchArgs {
+            hunks: expected_patch.clone(),
+            patch: patch_text.to_string(),
+            workdir: None,
+            environment_id: None,
+        })
+    );
+
+    let patch_text_in_single_quoted_heredoc = format!("<<'EOF'\n{patch_text}\nEOF\n");
+    assert_eq!(
+        parse_patch_text(&patch_text_in_single_quoted_heredoc, ParseMode::Strict),
+        Err(expected_error.clone())
+    );
+    assert_eq!(
+        parse_patch_text(&patch_text_in_single_quoted_heredoc, ParseMode::Lenient),
+        Ok(ApplyPatchArgs {
+            hunks: expected_patch.clone(),
+            patch: patch_text.to_string(),
+            workdir: None,
+            environment_id: None,
+        })
+    );
+
+    let patch_text_in_double_quoted_heredoc = format!("<<\"EOF\"\n{patch_text}\nEOF\n");
+    assert_eq!(
+        parse_patch_text(&patch_text_in_double_quoted_heredoc, ParseMode::Strict),
+        Err(expected_error.clone())
+    );
+    assert_eq!(
+        parse_patch_text(&patch_text_in_double_quoted_heredoc, ParseMode::Lenient),
+        Ok(ApplyPatchArgs {
+            hunks: expected_patch,
+            patch: patch_text.to_string(),
+            workdir: None,
+            environment_id: None,
+        })
+    );
+
+    let patch_text_in_mismatched_quotes_heredoc = format!("<<\"EOF'\n{patch_text}\nEOF\n");
+    assert_eq!(
+        parse_patch_text(&patch_text_in_mismatched_quotes_heredoc, ParseMode::Strict),
+        Err(expected_error.clone())
+    );
+    assert_eq!(
+        parse_patch_text(&patch_text_in_mismatched_quotes_heredoc, ParseMode::Lenient),
+        Err(expected_error.clone())
+    );
+
+    let patch_text_with_missing_closing_heredoc =
+        "<<EOF\n*** Begin Patch\n*** Update File: file2.py\nEOF\n".to_string();
+    assert_eq!(
+        parse_patch_text(&patch_text_with_missing_closing_heredoc, ParseMode::Strict),
+        Err(expected_error)
+    );
+    assert_eq!(
+        parse_patch_text(&patch_text_with_missing_closing_heredoc, ParseMode::Lenient),
+        Err(InvalidPatchError(
+            "The last line of the patch must be '*** End Patch'".to_string()
+        ))
+    );
+}
+
+#[test]
+fn test_parse_patch_environment_id_preamble() {
+    assert_eq!(
+        parse_patch_text(
+            "*** Begin Patch\n\
+             *** Environment ID: remote\n\
+             *** Add File: hello.txt\n\
+             +hello\n\
+             *** End Patch",
+            ParseMode::Strict
+        ),
+        Ok(ApplyPatchArgs {
+            hunks: vec![AddFile {
+                path: PathBuf::from("hello.txt"),
+                contents: "hello\n".to_string(),
+            }],
+            patch: "*** Begin Patch\n*** Environment ID: remote\n*** Add File: hello.txt\n+hello\n*** End Patch".to_string(),
+            workdir: None,
+            environment_id: Some("remote".to_string()),
+        })
+    );
+
+    assert_eq!(
+        parse_patch_text(
+            "*** Begin Patch\n\
+             *** Environment ID:   \n\
+             *** Add File: hello.txt\n\
+             +hello\n\
+             *** End Patch",
+            ParseMode::Strict
+        ),
+        Err(InvalidPatchError(
+            "apply_patch environment_id cannot be empty".to_string()
+        ))
+    );
+}
diff --git a/codex-rs/apply-patch/src/seek_sequence.rs b/codex-rs/apply-patch/src/seek_sequence.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9934fa55e767cacf85db7e459a913e72c9d828a0
--- /dev/null
+++ b/codex-rs/apply-patch/src/seek_sequence.rs
@@ -0,0 +1,193 @@
+/// Attempt to find the sequence of `pattern` lines within `lines` beginning at or after `start`.
+/// Returns the starting index of the match or `None` if not found. Matches are attempted with
+/// decreasing strictness: exact match, then ignoring trailing whitespace, then ignoring leading
+/// and trailing whitespace. When `eof` is true, we first try starting at the end-of-file (so that
+/// patterns intended to match file endings are applied at the end), and fall back to searching
+/// from `start` if needed.
+///
+/// Special cases handled defensively:
+///  • Empty `pattern` → returns `Some(start)` (no-op match)
+///  • `pattern.len() > lines.len()` → returns `None` (cannot match, avoids
+///    out‑of‑bounds panic that occurred pre‑2025‑04‑12)
+pub(crate) fn seek_sequence(
+    lines: &[String],
+    pattern: &[String],
+    start: usize,
+    eof: bool,
+    update_file_mode: crate::ApplyPatchFileUpdateMode,
+) -> Option<usize> {
+    if pattern.is_empty() {
+        return Some(start);
+    }
+
+    // When the pattern is longer than the available input there is no possible
+    // match. Early‑return to avoid the out‑of‑bounds slice that would occur in
+    // the search loops below (previously caused a panic when
+    // `pattern.len() > lines.len()`).
+    if pattern.len() > lines.len() {
+        return None;
+    }
+    let search_start = if eof && lines.len() >= pattern.len() {
+        let eof_start = lines.len() - pattern.len();
+        match update_file_mode {
+            crate::ApplyPatchFileUpdateMode::NormalizeToLf => eof_start,
+            crate::ApplyPatchFileUpdateMode::PreserveLineEndings => eof_start.max(start),
+        }
+    } else {
+        start
+    };
+    // Exact match first.
+    for i in search_start..=lines.len().saturating_sub(pattern.len()) {
+        if lines[i..i + pattern.len()] == *pattern {
+            return Some(i);
+        }
+    }
+    // Then rstrip match.
+    for i in search_start..=lines.len().saturating_sub(pattern.len()) {
+        let mut ok = true;
+        for (p_idx, pat) in pattern.iter().enumerate() {
+            if lines[i + p_idx].trim_end() != pat.trim_end() {
+                ok = false;
+                break;
+            }
+        }
+        if ok {
+            return Some(i);
+        }
+    }
+    // Finally, trim both sides to allow more lenience.
+    for i in search_start..=lines.len().saturating_sub(pattern.len()) {
+        let mut ok = true;
+        for (p_idx, pat) in pattern.iter().enumerate() {
+            if lines[i + p_idx].trim() != pat.trim() {
+                ok = false;
+                break;
+            }
+        }
+        if ok {
+            return Some(i);
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Final, most permissive pass – attempt to match after *normalising*
+    // common Unicode punctuation to their ASCII equivalents so that diffs
+    // authored with plain ASCII characters can still be applied to source
+    // files that contain typographic dashes / quotes, etc.  This mirrors the
+    // fuzzy behaviour of `git apply` which ignores minor byte-level
+    // differences when locating context lines.
+    // ------------------------------------------------------------------
+
+    fn normalise(s: &str) -> String {
+        s.trim()
+            .chars()
+            .map(|c| match c {
+                // Various dash / hyphen code-points → ASCII '-'
+                '\u{2010}' | '\u{2011}' | '\u{2012}' | '\u{2013}' | '\u{2014}' | '\u{2015}'
+                | '\u{2212}' => '-',
+                // Fancy single quotes → '\''
+                '\u{2018}' | '\u{2019}' | '\u{201A}' | '\u{201B}' => '\'',
+                // Fancy double quotes → '"'
+                '\u{201C}' | '\u{201D}' | '\u{201E}' | '\u{201F}' => '"',
+                // Non-breaking space and other odd spaces → normal space
+                '\u{00A0}' | '\u{2002}' | '\u{2003}' | '\u{2004}' | '\u{2005}' | '\u{2006}'
+                | '\u{2007}' | '\u{2008}' | '\u{2009}' | '\u{200A}' | '\u{202F}' | '\u{205F}'
+                | '\u{3000}' => ' ',
+                other => other,
+            })
+            .collect::<String>()
+    }
+
+    for i in search_start..=lines.len().saturating_sub(pattern.len()) {
+        let mut ok = true;
+        for (p_idx, pat) in pattern.iter().enumerate() {
+            if normalise(&lines[i + p_idx]) != normalise(pat) {
+                ok = false;
+                break;
+            }
+        }
+        if ok {
+            return Some(i);
+        }
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::seek_sequence;
+    use crate::ApplyPatchFileUpdateMode;
+    use std::string::ToString;
+
+    fn to_vec(strings: &[&str]) -> Vec<String> {
+        strings.iter().map(ToString::to_string).collect()
+    }
+
+    #[test]
+    fn test_exact_match_finds_sequence() {
+        let lines = to_vec(&["foo", "bar", "baz"]);
+        let pattern = to_vec(&["bar", "baz"]);
+        assert_eq!(
+            seek_sequence(
+                &lines,
+                &pattern,
+                /*start*/ 0,
+                /*eof*/ false,
+                ApplyPatchFileUpdateMode::NormalizeToLf,
+            ),
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn test_rstrip_match_ignores_trailing_whitespace() {
+        let lines = to_vec(&["foo   ", "bar\t\t"]);
+        // Pattern omits trailing whitespace.
+        let pattern = to_vec(&["foo", "bar"]);
+        assert_eq!(
+            seek_sequence(
+                &lines,
+                &pattern,
+                /*start*/ 0,
+                /*eof*/ false,
+                ApplyPatchFileUpdateMode::NormalizeToLf,
+            ),
+            Some(0)
+        );
+    }
+
+    #[test]
+    fn test_trim_match_ignores_leading_and_trailing_whitespace() {
+        let lines = to_vec(&["    foo   ", "   bar\t"]);
+        // Pattern omits any additional whitespace.
+        let pattern = to_vec(&["foo", "bar"]);
+        assert_eq!(
+            seek_sequence(
+                &lines,
+                &pattern,
+                /*start*/ 0,
+                /*eof*/ false,
+                ApplyPatchFileUpdateMode::NormalizeToLf,
+            ),
+            Some(0)
+        );
+    }
+
+    #[test]
+    fn test_pattern_longer_than_input_returns_none() {
+        let lines = to_vec(&["just one line"]);
+        let pattern = to_vec(&["too", "many", "lines"]);
+        // Should not panic – must return None when pattern cannot possibly fit.
+        assert_eq!(
+            seek_sequence(
+                &lines,
+                &pattern,
+                /*start*/ 0,
+                /*eof*/ false,
+                ApplyPatchFileUpdateMode::NormalizeToLf,
+            ),
+            None
+        );
+    }
+}
diff --git a/codex-rs/apply-patch/src/standalone_executable.rs b/codex-rs/apply-patch/src/standalone_executable.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7f2627beca0c2d0c18c09ab02988f0d872a74adc
--- /dev/null
+++ b/codex-rs/apply-patch/src/standalone_executable.rs
@@ -0,0 +1,90 @@
+use std::io::Read;
+use std::io::Write;
+
+pub fn main() -> ! {
+    let exit_code = run_main();
+    std::process::exit(exit_code);
+}
+
+/// We would prefer to return `std::process::ExitCode`, but its `exit_process()`
+/// method is still a nightly API and we want main() to return !.
+pub fn run_main() -> i32 {
+    // Expect either one argument (the full apply_patch payload) or read it from stdin.
+    let mut args = std::env::args_os();
+    let _argv0 = args.next();
+
+    let patch_arg = match args.next() {
+        Some(arg) => match arg.into_string() {
+            Ok(s) => s,
+            Err(_) => {
+                eprintln!("Error: apply_patch requires a UTF-8 PATCH argument.");
+                return 1;
+            }
+        },
+        None => {
+            // No argument provided; attempt to read the patch from stdin.
+            let mut buf = String::new();
+            match std::io::stdin().read_to_string(&mut buf) {
+                Ok(_) => {
+                    if buf.is_empty() {
+                        eprintln!("Usage: apply_patch 'PATCH'\n       echo 'PATCH' | apply_patch");
+                        return 2;
+                    }
+                    buf
+                }
+                Err(err) => {
+                    eprintln!("Error: Failed to read PATCH from stdin.\n{err}");
+                    return 1;
+                }
+            }
+        }
+    };
+
+    // Refuse extra args to avoid ambiguity.
+    if args.next().is_some() {
+        eprintln!("Error: apply_patch accepts exactly one argument.");
+        return 2;
+    }
+
+    let mut stdout = std::io::stdout();
+    let mut stderr = std::io::stderr();
+    let cwd = match codex_utils_absolute_path::AbsolutePathBuf::current_dir() {
+        Ok(cwd) => cwd,
+        Err(err) => {
+            eprintln!("Error: Failed to determine current directory.\n{err}");
+            return 1;
+        }
+    };
+    let runtime = match tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+    {
+        Ok(runtime) => runtime,
+        Err(err) => {
+            eprintln!("Error: Failed to initialize runtime.\n{err}");
+            return 1;
+        }
+    };
+    // TODO(anp): Discover the standalone executable cwd as PathUri directly.
+    let cwd = codex_utils_path_uri::PathUri::from_abs_path(&cwd);
+    let update_file_mode = crate::apply_patch_file_update_mode_from_env();
+    match runtime.block_on(crate::apply_patch_with_options(
+        &patch_arg,
+        crate::ApplyPatchOptions {
+            update_file_mode,
+            ..Default::default()
+        },
+        &cwd,
+        &mut stdout,
+        &mut stderr,
+        codex_exec_server::LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )) {
+        Ok(_) => {
+            // Flush to ensure output ordering when used in pipelines.
+            let _ = stdout.flush();
+            0
+        }
+        Err(_) => 1,
+    }
+}
diff --git a/codex-rs/apply-patch/src/streaming_parser.rs b/codex-rs/apply-patch/src/streaming_parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ff1b2f82feec7bdf454f6cba61ad5f15611f5573
--- /dev/null
+++ b/codex-rs/apply-patch/src/streaming_parser.rs
@@ -0,0 +1,924 @@
+use std::path::PathBuf;
+
+use crate::parser::ADD_FILE_MARKER;
+use crate::parser::BEGIN_PATCH_MARKER;
+use crate::parser::CHANGE_CONTEXT_MARKER;
+use crate::parser::DELETE_FILE_MARKER;
+use crate::parser::EMPTY_CHANGE_CONTEXT_MARKER;
+use crate::parser::END_PATCH_MARKER;
+use crate::parser::EOF_MARKER;
+use crate::parser::Hunk;
+use crate::parser::MOVE_TO_MARKER;
+use crate::parser::ParseError;
+use crate::parser::UPDATE_FILE_MARKER;
+use crate::parser::UpdateFileChunk;
+
+use Hunk::*;
+use ParseError::*;
+
+const ENVIRONMENT_ID_MARKER: &str = "*** Environment ID:";
+
+#[derive(Debug, Default, Clone)]
+pub struct StreamingPatchParser {
+    line_buffer: String,
+    state: StreamingParserState,
+    line_number: usize,
+}
+
+#[derive(Debug, Default, Clone)]
+struct StreamingParserState {
+    mode: StreamingParserMode,
+    hunks: Vec<Hunk>,
+    environment_id: Option<String>,
+}
+
+#[derive(Debug, Default, Clone, Copy)]
+enum StreamingParserMode {
+    #[default]
+    NotStarted,
+    StartedPatch,
+    AddFile,
+    DeleteFile,
+    UpdateFile {
+        hunk_line_number: usize,
+    },
+    EndedPatch,
+}
+
+impl StreamingPatchParser {
+    pub fn environment_id(&self) -> Option<&str> {
+        self.state.environment_id.as_deref()
+    }
+
+    fn ensure_update_hunk_is_not_empty(&self, line: &str) -> Result<(), ParseError> {
+        if let Some(UpdateFile { path, chunks, .. }) = self.state.hunks.last() {
+            if chunks.is_empty()
+                && let StreamingParserMode::UpdateFile { hunk_line_number } = self.state.mode
+            {
+                return Err(InvalidHunkError {
+                    message: format!("Update file hunk for path '{}' is empty", path.display()),
+                    line_number: hunk_line_number,
+                });
+            }
+            if chunks
+                .last()
+                .is_some_and(|chunk| chunk.old_lines.is_empty() && chunk.new_lines.is_empty())
+            {
+                if line == END_PATCH_MARKER {
+                    return Err(InvalidHunkError {
+                        message: "Update hunk does not contain any lines".to_string(),
+                        line_number: self.line_number,
+                    });
+                }
+                return Err(InvalidHunkError {
+                    message: format!(
+                        "Unexpected line found in update hunk: '{line}'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)"
+                    ),
+                    line_number: self.line_number,
+                });
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_hunk_headers_and_end_patch(&mut self, trimmed: &str) -> Result<bool, ParseError> {
+        if matches!(self.state.mode, StreamingParserMode::StartedPatch)
+            && let Some(environment_id) = trimmed.strip_prefix(ENVIRONMENT_ID_MARKER)
+        {
+            if self.state.environment_id.is_some() {
+                return Err(InvalidPatchError(
+                    "apply_patch environment_id cannot be specified more than once".to_string(),
+                ));
+            }
+            let environment_id = environment_id.trim();
+            if environment_id.is_empty() {
+                return Err(InvalidPatchError(
+                    "apply_patch environment_id cannot be empty".to_string(),
+                ));
+            }
+            self.state.environment_id = Some(environment_id.to_string());
+            return Ok(true);
+        }
+        if trimmed == END_PATCH_MARKER {
+            self.ensure_update_hunk_is_not_empty(trimmed)?;
+            self.state.mode = StreamingParserMode::EndedPatch;
+            return Ok(true);
+        }
+        if let Some(path) = trimmed.strip_prefix(ADD_FILE_MARKER) {
+            self.ensure_update_hunk_is_not_empty(trimmed)?;
+            self.state.hunks.push(AddFile {
+                path: PathBuf::from(path),
+                contents: String::new(),
+            });
+            self.state.mode = StreamingParserMode::AddFile;
+            return Ok(true);
+        }
+        if let Some(path) = trimmed.strip_prefix(DELETE_FILE_MARKER) {
+            self.ensure_update_hunk_is_not_empty(trimmed)?;
+            self.state.hunks.push(DeleteFile {
+                path: PathBuf::from(path),
+            });
+            self.state.mode = StreamingParserMode::DeleteFile;
+            return Ok(true);
+        }
+        if let Some(path) = trimmed.strip_prefix(UPDATE_FILE_MARKER) {
+            self.ensure_update_hunk_is_not_empty(trimmed)?;
+            self.state.hunks.push(UpdateFile {
+                path: PathBuf::from(path),
+                move_path: None,
+                chunks: Vec::new(),
+            });
+            self.state.mode = StreamingParserMode::UpdateFile {
+                hunk_line_number: self.line_number,
+            };
+            return Ok(true);
+        }
+        Ok(false)
+    }
+
+    pub fn push_delta(&mut self, delta: &str) -> Result<Vec<Hunk>, ParseError> {
+        for ch in delta.chars() {
+            if ch == '\n' {
+                let mut line = std::mem::take(&mut self.line_buffer);
+                line.truncate(line.strip_suffix('\r').map_or(line.len(), str::len));
+                self.line_number += 1;
+                self.process_line(&line)?;
+            } else {
+                self.line_buffer.push(ch);
+            }
+        }
+
+        Ok(self.state.hunks.clone())
+    }
+
+    pub fn finish(&mut self) -> Result<Vec<Hunk>, ParseError> {
+        if !self.line_buffer.is_empty() {
+            let line = std::mem::take(&mut self.line_buffer);
+            self.line_number += 1;
+            if line.trim() == END_PATCH_MARKER {
+                self.ensure_update_hunk_is_not_empty(line.trim())?;
+                self.state.mode = StreamingParserMode::EndedPatch;
+            } else {
+                self.process_line(&line)?;
+            }
+        }
+
+        if !matches!(self.state.mode, StreamingParserMode::EndedPatch) {
+            return Err(InvalidPatchError(
+                "The last line of the patch must be '*** End Patch'".to_string(),
+            ));
+        }
+
+        Ok(self.state.hunks.clone())
+    }
+
+    fn process_line(&mut self, line: &str) -> Result<(), ParseError> {
+        let trimmed = line.trim();
+        match self.state.mode {
+            StreamingParserMode::NotStarted => {
+                if trimmed == BEGIN_PATCH_MARKER {
+                    self.state.mode = StreamingParserMode::StartedPatch;
+                    return Ok(());
+                }
+                Err(InvalidPatchError(
+                    "The first line of the patch must be '*** Begin Patch'".to_string(),
+                ))
+            }
+            StreamingParserMode::StartedPatch => {
+                if self.handle_hunk_headers_and_end_patch(trimmed)? {
+                    return Ok(());
+                }
+                Err(InvalidHunkError {
+                    message: format!(
+                        "'{trimmed}' is not a valid hunk header. Valid hunk headers: '*** Add File: {{path}}', '*** Delete File: {{path}}', '*** Update File: {{path}}'"
+                    ),
+                    line_number: self.line_number,
+                })
+            }
+            StreamingParserMode::AddFile => {
+                if self.handle_hunk_headers_and_end_patch(trimmed)? {
+                    return Ok(());
+                }
+                if let Some(line_to_add) = line.strip_prefix('+')
+                    && let Some(AddFile { contents, .. }) = self.state.hunks.last_mut()
+                {
+                    contents.push_str(line_to_add);
+                    contents.push('\n');
+                    return Ok(());
+                }
+                Err(InvalidHunkError {
+                    message: format!(
+                        "'{trimmed}' is not a valid hunk header. Valid hunk headers: '*** Add File: {{path}}', '*** Delete File: {{path}}', '*** Update File: {{path}}'"
+                    ),
+                    line_number: self.line_number,
+                })
+            }
+            StreamingParserMode::DeleteFile => {
+                if self.handle_hunk_headers_and_end_patch(trimmed)? {
+                    return Ok(());
+                }
+                Err(InvalidHunkError {
+                    message: format!(
+                        "'{trimmed}' is not a valid hunk header. Valid hunk headers: '*** Add File: {{path}}', '*** Delete File: {{path}}', '*** Update File: {{path}}'"
+                    ),
+                    line_number: self.line_number,
+                })
+            }
+            StreamingParserMode::UpdateFile { hunk_line_number } => {
+                let update_line = line.trim_end();
+                if self.handle_hunk_headers_and_end_patch(update_line)? {
+                    return Ok(());
+                }
+
+                if let Some(UpdateFile {
+                    move_path, chunks, ..
+                }) = self.state.hunks.last_mut()
+                {
+                    if chunks.last().is_some_and(|chunk| chunk.is_end_of_file) {
+                        if update_line.is_empty() {
+                            return Ok(());
+                        }
+                        if update_line != EMPTY_CHANGE_CONTEXT_MARKER
+                            && !update_line.starts_with(CHANGE_CONTEXT_MARKER)
+                        {
+                            return Err(InvalidHunkError {
+                                message: format!(
+                                    "Expected update hunk to start with a @@ context marker, got: '{line}'"
+                                ),
+                                line_number: self.line_number,
+                            });
+                        }
+                    }
+
+                    if chunks.is_empty()
+                        && move_path.is_none()
+                        && let Some(move_to_path) = update_line.strip_prefix(MOVE_TO_MARKER)
+                    {
+                        *move_path = Some(PathBuf::from(move_to_path));
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if (update_line == EMPTY_CHANGE_CONTEXT_MARKER
+                        || update_line.starts_with(CHANGE_CONTEXT_MARKER))
+                        && chunks.last().is_some_and(|chunk| {
+                            chunk.old_lines.is_empty() && chunk.new_lines.is_empty()
+                        })
+                    {
+                        return Err(InvalidHunkError {
+                            message: format!(
+                                "Unexpected line found in update hunk: '{line}'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)"
+                            ),
+                            line_number: self.line_number,
+                        });
+                    }
+
+                    if update_line == EMPTY_CHANGE_CONTEXT_MARKER {
+                        chunks.push(UpdateFileChunk::default());
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if let Some(change_context) = update_line.strip_prefix(CHANGE_CONTEXT_MARKER) {
+                        chunks.push(UpdateFileChunk {
+                            change_context: Some(change_context.to_string()),
+                            ..UpdateFileChunk::default()
+                        });
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if update_line == EOF_MARKER {
+                        if chunks.last().is_some_and(|chunk| {
+                            chunk.old_lines.is_empty() && chunk.new_lines.is_empty()
+                        }) {
+                            return Err(InvalidHunkError {
+                                message: "Update hunk does not contain any lines".to_string(),
+                                line_number: self.line_number,
+                            });
+                        }
+                        if let Some(chunk) = chunks.last_mut() {
+                            chunk.is_end_of_file = true;
+                        }
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if line.is_empty() {
+                        if chunks.is_empty() {
+                            chunks.push(UpdateFileChunk::default());
+                        }
+                        if let Some(chunk) = chunks.last_mut() {
+                            chunk.push_context_line(String::new());
+                        }
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if let Some(line_to_add) = line.strip_prefix(' ') {
+                        if chunks.is_empty() {
+                            chunks.push(UpdateFileChunk::default());
+                        }
+                        if let Some(chunk) = chunks.last_mut() {
+                            chunk.push_context_line(line_to_add.to_string());
+                        }
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if let Some(line_to_add) = line.strip_prefix('+') {
+                        if chunks.is_empty() {
+                            chunks.push(UpdateFileChunk::default());
+                        }
+                        if let Some(chunk) = chunks.last_mut() {
+                            chunk.new_lines.push(line_to_add.to_string());
+                        }
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if let Some(line_to_remove) = line.strip_prefix('-') {
+                        if chunks.is_empty() {
+                            chunks.push(UpdateFileChunk::default());
+                        }
+                        if let Some(chunk) = chunks.last_mut() {
+                            chunk.old_lines.push(line_to_remove.to_string());
+                        }
+                        self.state.mode = StreamingParserMode::UpdateFile { hunk_line_number };
+                        return Ok(());
+                    }
+
+                    if chunks.last().is_some_and(|chunk| {
+                        !chunk.old_lines.is_empty() || !chunk.new_lines.is_empty()
+                    }) {
+                        return Err(InvalidHunkError {
+                            message: format!(
+                                "Expected update hunk to start with a @@ context marker, got: '{line}'"
+                            ),
+                            line_number: self.line_number,
+                        });
+                    }
+                }
+                Err(InvalidHunkError {
+                    message: format!(
+                        "Unexpected line found in update hunk: '{line}'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)"
+                    ),
+                    line_number: self.line_number,
+                })
+            }
+            StreamingParserMode::EndedPatch => {
+                if trimmed.is_empty() {
+                    Ok(())
+                } else {
+                    Err(InvalidPatchError(
+                        "The last line of the patch must be '*** End Patch'".to_string(),
+                    ))
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use std::path::PathBuf;
+
+    use super::*;
+
+    #[test]
+    fn test_streaming_patch_parser_streams_complete_lines_before_end_patch() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Add File: src/hello.txt\n+hello\n+wor"),
+            Ok(vec![AddFile {
+                path: PathBuf::from("src/hello.txt"),
+                contents: "hello\n".to_string(),
+            }])
+        );
+        assert_eq!(
+            parser.push_delta("ld\n"),
+            Ok(vec![AddFile {
+                path: PathBuf::from("src/hello.txt"),
+                contents: "hello\nworld\n".to_string(),
+            }])
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Update File: src/old.rs\n*** Move to: src/new.rs\n@@\n-old\n+new\n",
+            ),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("src/old.rs"),
+                move_path: Some(PathBuf::from("src/new.rs")),
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec!["old".to_string()],
+                    new_lines: vec!["new".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false,
+                }],
+            }])
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Delete File: gone.txt"),
+            Ok(Vec::new())
+        );
+        assert_eq!(
+            parser.push_delta("\n"),
+            Ok(vec![DeleteFile {
+                path: PathBuf::from("gone.txt"),
+            }])
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Add File: src/one.txt\n+one\n*** Delete File: src/two.txt\n",
+            ),
+            Ok(vec![
+                AddFile {
+                    path: PathBuf::from("src/one.txt"),
+                    contents: "one\n".to_string(),
+                },
+                DeleteFile {
+                    path: PathBuf::from("src/two.txt"),
+                },
+            ])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_environment_id_mode() {
+        let patch = "\
+*** Begin Patch
+*** Environment ID: remote
+*** Add File: src/hello.txt
++hello
+*** End Patch
+";
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(patch),
+            Ok(vec![AddFile {
+                path: PathBuf::from("src/hello.txt"),
+                contents: "hello\n".to_string(),
+            }])
+        );
+        assert_eq!(parser.environment_id(), Some("remote"));
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Environment ID: first\n*** Environment ID: second\n",
+            ),
+            Err(InvalidPatchError(
+                "apply_patch environment_id cannot be specified more than once".to_string(),
+            ))
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Environment ID:   \n"),
+            Err(InvalidPatchError(
+                "apply_patch environment_id cannot be empty".to_string(),
+            ))
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_large_patch_split_by_character() {
+        let patch = "\
+*** Begin Patch
+*** Add File: docs/release-notes.md
++# Release notes
++
++## CLI
++- Surface apply_patch progress while arguments stream.
++- Keep final patch application gated on the completed tool call.
++- Include file summaries in the progress event payload.
+*** Update File: src/config.rs
+@@ impl Config
+-    pub apply_patch_progress: bool,
++    pub stream_apply_patch_progress: bool,
+     pub include_diagnostics: bool,
+@@ fn default_progress_interval()
+-    Duration::from_millis(500)
++    Duration::from_millis(250)
+*** Delete File: src/legacy_patch_progress.rs
+*** Update File: crates/cli/src/main.rs
+*** Move to: crates/cli/src/bin/codex.rs
+@@ fn run()
+-    let args = Args::parse();
+-    dispatch(args)
++    let cli = Cli::parse();
++    dispatch(cli)
+*** Add File: tests/fixtures/apply_patch_progress.json
++{
++  \"type\": \"apply_patch_progress\",
++  \"hunks\": [
++    { \"operation\": \"add\", \"path\": \"docs/release-notes.md\" },
++    { \"operation\": \"update\", \"path\": \"src/config.rs\" }
++  ]
++}
+*** Update File: README.md
+@@ Development workflow
+ Build the Rust workspace before opening a pull request.
++When touching streamed tool calls, include parser coverage for partial input.
++Prefer tests that exercise the exact event payload shape.
+*** Delete File: docs/old-apply-patch-progress.md
+*** End Patch";
+
+        let mut parser = StreamingPatchParser::default();
+        let mut max_hunk_count = 0;
+        let mut saw_hunk_counts = Vec::new();
+        let mut hunks = Vec::new();
+        for ch in patch.chars() {
+            let updated_hunks = parser.push_delta(&ch.to_string()).unwrap();
+            if !updated_hunks.is_empty() {
+                let hunk_count = updated_hunks.len();
+                assert!(
+                    hunk_count >= max_hunk_count,
+                    "hunk count should never decrease while streaming: {hunk_count} < {max_hunk_count}",
+                );
+                if hunk_count > max_hunk_count {
+                    saw_hunk_counts.push(hunk_count);
+                    max_hunk_count = hunk_count;
+                }
+                hunks = updated_hunks;
+            }
+        }
+
+        assert_eq!(saw_hunk_counts, vec![1, 2, 3, 4, 5, 6, 7]);
+        assert_eq!(hunks.len(), 7);
+        assert_eq!(
+            hunks
+                .iter()
+                .map(|hunk| match hunk {
+                    AddFile { .. } => "add",
+                    DeleteFile { .. } => "delete",
+                    UpdateFile {
+                        move_path: Some(_), ..
+                    } => "move-update",
+                    UpdateFile {
+                        move_path: None, ..
+                    } => "update",
+                })
+                .collect::<Vec<_>>(),
+            vec![
+                "add",
+                "update",
+                "delete",
+                "move-update",
+                "add",
+                "update",
+                "delete"
+            ]
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_keeps_indented_update_markers_as_context_lines() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "\
+*** Begin Patch
+*** Update File: a.txt
+@@
+-old a
++new a
+ *** Update File: b.txt
+@@
+-old b
++new b
+*** End Patch
+",
+            ),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("a.txt"),
+                move_path: None,
+                chunks: vec![
+                    UpdateFileChunk {
+                        change_context: None,
+                        old_lines: vec!["old a".to_string(), "*** Update File: b.txt".to_string()],
+                        new_lines: vec!["new a".to_string(), "*** Update File: b.txt".to_string()],
+                        context_line_indices: vec![(1, 1)],
+                        is_end_of_file: false,
+                    },
+                    UpdateFileChunk {
+                        change_context: None,
+                        old_lines: vec!["old b".to_string()],
+                        new_lines: vec!["new b".to_string()],
+                        context_line_indices: vec![],
+                        is_end_of_file: false,
+                    },
+                ],
+            }])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_preserves_bare_empty_update_lines() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "\
+*** Begin Patch
+*** Update File: file.txt
+@@
+ context before
+
+ context after
+*** End Patch
+",
+            ),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    // The normal parser treats a bare empty line in an update hunk as an
+                    // empty context line. Preserve that leniency in the streaming parser.
+                    old_lines: vec![
+                        "context before".to_string(),
+                        String::new(),
+                        "context after".to_string(),
+                    ],
+                    new_lines: vec![
+                        "context before".to_string(),
+                        String::new(),
+                        "context after".to_string(),
+                    ],
+                    context_line_indices: vec![(0, 0), (1, 1), (2, 2)],
+                    is_end_of_file: false,
+                }],
+            }])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_ignores_empty_lines_after_end_of_file() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Update File: file.txt\n@@\n+quux\n*** End of File\n\n*** End Patch\n",
+            ),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: Vec::new(),
+                    new_lines: vec!["quux".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: true,
+                }],
+            }])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_matches_line_ending_behavior() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\r\n*** Update File: file.txt\r\n@@\r\n-old\r\n+new\r\n*** End Patch\r\n"),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec!["old".to_string()],
+                    new_lines: vec!["new".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false,
+                }],
+            }])
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\r\n*** Update File: file.txt\r\n@@\r\n-old\r\r\n+new\r\n*** End Patch\r\n"),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec!["old\r".to_string()],
+                    new_lines: vec!["new".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false,
+                }],
+            }])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_finish_processes_final_line_without_newline() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Add File: file.txt\n+hello\n*** End Patch"),
+            Ok(vec![AddFile {
+                path: PathBuf::from("file.txt"),
+                contents: "hello\n".to_string(),
+            }])
+        );
+        assert_eq!(
+            parser.finish(),
+            Ok(vec![AddFile {
+                path: PathBuf::from("file.txt"),
+                contents: "hello\n".to_string(),
+            }])
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Update File: file.txt\n@@\n-old\n+new\n *** End Patch",
+            ),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec!["old".to_string()],
+                    new_lines: vec!["new".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false,
+                }],
+            }])
+        );
+        assert_eq!(
+            parser.finish(),
+            Ok(vec![UpdateFile {
+                path: PathBuf::from("file.txt"),
+                move_path: None,
+                chunks: vec![UpdateFileChunk {
+                    change_context: None,
+                    old_lines: vec!["old".to_string()],
+                    new_lines: vec!["new".to_string()],
+                    context_line_indices: vec![],
+                    is_end_of_file: false,
+                }],
+            }])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_finish_requires_end_patch() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Add File: file.txt\n+hello\n"),
+            Ok(vec![AddFile {
+                path: PathBuf::from("file.txt"),
+                contents: "hello\n".to_string(),
+            }])
+        );
+        assert_eq!(
+            parser.finish(),
+            Err(InvalidPatchError(
+                "The last line of the patch must be '*** End Patch'".to_string(),
+            ))
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_rejects_content_after_end_patch() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Add File: file.txt\n+hello\n*** End Patch\nextra\n",
+            ),
+            Err(InvalidPatchError(
+                "The last line of the patch must be '*** End Patch'".to_string(),
+            ))
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Add File: file.txt\n+hello\n*** End Patch\n \t\n",
+            ),
+            Ok(vec![AddFile {
+                path: PathBuf::from("file.txt"),
+                contents: "hello\n".to_string(),
+            }])
+        );
+    }
+
+    #[test]
+    fn test_streaming_patch_parser_returns_errors() {
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("bad\n"),
+            Err(InvalidPatchError(
+                "The first line of the patch must be '*** Begin Patch'".to_string(),
+            ))
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(parser.push_delta("*** Begin Patch\n"), Ok(Vec::new()));
+        assert_eq!(
+            parser.push_delta("bad\n"),
+            Err(InvalidHunkError {
+                message: "'bad' is not a valid hunk header. Valid hunk headers: '*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'"
+                    .to_string(),
+                line_number: 2,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Add File: file.txt\nbad\n"),
+            Err(InvalidHunkError {
+                message: "'bad' is not a valid hunk header. Valid hunk headers: '*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'"
+                    .to_string(),
+                line_number: 3,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Delete File: file.txt\nbad\n"),
+            Err(InvalidHunkError {
+                message: "'bad' is not a valid hunk header. Valid hunk headers: '*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'"
+                    .to_string(),
+                line_number: 3,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Update File: file.txt\n*** End Patch\n"),
+            Err(InvalidHunkError {
+                message: "Update file hunk for path 'file.txt' is empty".to_string(),
+                line_number: 2,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Update File: old.txt\n*** Move to: new.txt\n*** Delete File: other.txt\n",
+            ),
+            Err(InvalidHunkError {
+                message: "Update file hunk for path 'old.txt' is empty".to_string(),
+                line_number: 2,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Update File: file.txt\n@@\n*** End Patch\n"),
+            Err(InvalidHunkError {
+                message: "Update hunk does not contain any lines".to_string(),
+                line_number: 4,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Update File: file.txt\n@@\n*** End of File\n"),
+            Err(InvalidHunkError {
+                message: "Update hunk does not contain any lines".to_string(),
+                line_number: 4,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Update File: file.txt\n@@\n@@\n"),
+            Err(InvalidHunkError {
+                message: "Unexpected line found in update hunk: '@@'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)"
+                    .to_string(),
+                line_number: 4,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta("*** Begin Patch\n*** Update File: file.txt\n@@\n-old\nbad\n"),
+            Err(InvalidHunkError {
+                message: "Expected update hunk to start with a @@ context marker, got: 'bad'"
+                    .to_string(),
+                line_number: 5,
+            })
+        );
+
+        let mut parser = StreamingPatchParser::default();
+        assert_eq!(
+            parser.push_delta(
+                "*** Begin Patch\n*** Update File: file.txt\n@@\n*** Update File: other.txt\n",
+            ),
+            Err(InvalidHunkError {
+                message: "Unexpected line found in update hunk: '*** Update File: other.txt'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)"
+                    .to_string(),
+                line_number: 4,
+            })
+        );
+    }
+}
diff --git a/codex-rs/apply-patch/src/text_file.rs b/codex-rs/apply-patch/src/text_file.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b7d598ca973ec73f0ed064d2360f4d218e2a792d
--- /dev/null
+++ b/codex-rs/apply-patch/src/text_file.rs
@@ -0,0 +1,121 @@
+pub(super) type Replacement = (usize, usize, Vec<String>);
+
+#[derive(Clone, Copy)]
+enum LineEnding {
+    Lf,
+    CrLf,
+    Cr,
+}
+
+impl LineEnding {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::Lf => "\n",
+            Self::CrLf => "\r\n",
+            Self::Cr => "\r",
+        }
+    }
+}
+
+struct SourceLine {
+    text: String,
+    ending: Option<LineEnding>,
+}
+
+pub(super) struct SourceFile {
+    lines: Vec<SourceLine>,
+    preferred_ending: LineEnding,
+}
+
+impl SourceFile {
+    /// Splits contents into logical lines while retaining each line ending.
+    ///
+    /// The first existing ending becomes the preferred style for inserted
+    /// lines; files without an ending default to LF.
+    pub(super) fn parse(contents: &str) -> Self {
+        let mut lines = Vec::new();
+        let mut preferred_ending = None;
+        let mut line_start = 0;
+        let mut cursor = 0;
+
+        while cursor < contents.len() {
+            let (ending, ending_len) = match contents.as_bytes()[cursor] {
+                b'\r' if contents.as_bytes().get(cursor + 1) == Some(&b'\n') => {
+                    (LineEnding::CrLf, 2)
+                }
+                b'\r' => (LineEnding::Cr, 1),
+                b'\n' => (LineEnding::Lf, 1),
+                _ => {
+                    cursor += 1;
+                    continue;
+                }
+            };
+            preferred_ending.get_or_insert(ending);
+            lines.push(SourceLine {
+                text: contents[line_start..cursor].to_string(),
+                ending: Some(ending),
+            });
+            cursor += ending_len;
+            line_start = cursor;
+        }
+
+        if line_start < contents.len() {
+            lines.push(SourceLine {
+                text: contents[line_start..].to_string(),
+                ending: None,
+            });
+        }
+
+        Self {
+            lines,
+            preferred_ending: preferred_ending.unwrap_or(LineEnding::Lf),
+        }
+    }
+
+    pub(super) fn line_texts(&self) -> Vec<String> {
+        self.lines.iter().map(|line| line.text.clone()).collect()
+    }
+
+    /// Rebuilds the file from source-ordered, non-overlapping replacements.
+    ///
+    /// Unchanged lines retain their original endings, inserted lines use the
+    /// preferred ending, and every resulting line receives an ending to match
+    /// apply-patch's historical trailing-newline behavior.
+    pub(super) fn apply_replacements(&mut self, replacements: &[Replacement]) {
+        let mut source_lines = std::mem::take(&mut self.lines).into_iter();
+        let mut new_lines = Vec::new();
+        let mut source_index = 0;
+
+        for (start_idx, old_len, new_segment) in replacements {
+            debug_assert!(*start_idx >= source_index);
+            for line in source_lines.by_ref().take(*start_idx - source_index) {
+                new_lines.push(line);
+            }
+            for _ in source_lines.by_ref().take(*old_len) {}
+            new_lines.extend(new_segment.iter().map(|text| SourceLine {
+                text: text.clone(),
+                ending: Some(self.preferred_ending),
+            }));
+            source_index = start_idx + old_len;
+        }
+        new_lines.extend(source_lines);
+        self.lines = new_lines;
+
+        // Updates have historically added a trailing newline. This also gives
+        // an unterminated last line an ending if an insertion moved it inward.
+        for line in &mut self.lines {
+            line.ending.get_or_insert(self.preferred_ending);
+        }
+    }
+
+    pub(super) fn into_contents(self) -> String {
+        let mut contents = String::new();
+        for line in self.lines {
+            contents.push_str(&line.text);
+            if let Some(ending) = line.ending {
+                contents.push_str(ending.as_str());
+            }
+        }
+        contents
+    }
+}
diff --git a/codex-rs/apply-patch/tests/all.rs b/codex-rs/apply-patch/tests/all.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7e136e4cce2a99915ff1b487d1f2b61c500f133a
--- /dev/null
+++ b/codex-rs/apply-patch/tests/all.rs
@@ -0,0 +1,3 @@
+// Single integration test binary that aggregates all test modules.
+// The submodules live in `tests/suite/`.
+mod suite;
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/.gitattributes b/codex-rs/apply-patch/tests/fixtures/scenarios/.gitattributes
new file mode 100644
index 0000000000000000000000000000000000000000..3961a5e66a7496e08ef82295e353acca0d0b5a8d
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/.gitattributes
@@ -0,0 +1,5 @@
+** text eol=lf
+023_preserves_crlf_line_endings/input/*.txt -diff -text
+023_preserves_crlf_line_endings/expected/*.txt -diff -text
+024_preserves_mixed_line_endings/input/*.txt -diff -text
+024_preserves_mixed_line_endings/expected/*.txt -diff -text
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/001_add_file/expected/bar.md b/codex-rs/apply-patch/tests/fixtures/scenarios/001_add_file/expected/bar.md
new file mode 100644
index 0000000000000000000000000000000000000000..6dfa057f0d4a43d5a3025a9c14dea607de9e1dbb
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/001_add_file/expected/bar.md
@@ -0,0 +1 @@
+This is a new file
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/001_add_file/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/001_add_file/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..37735b2a465d5534d403d6e0eba62d4e857973f7
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/001_add_file/patch.txt
@@ -0,0 +1,4 @@
+*** Begin Patch
+*** Add File: bar.md
++This is a new file
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/expected/modify.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/expected/modify.txt
new file mode 100644
index 0000000000000000000000000000000000000000..1b2ee3e56691c2207698ae92e6d33129e40cbbfe
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/expected/modify.txt
@@ -0,0 +1,2 @@
+line1
+changed
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/expected/nested/new.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/expected/nested/new.txt
new file mode 100644
index 0000000000000000000000000000000000000000..3151666398e7951f81d58893dc687970599625ab
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/expected/nested/new.txt
@@ -0,0 +1 @@
+created
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/input/delete.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/input/delete.txt
new file mode 100644
index 0000000000000000000000000000000000000000..6e263abce10f69a67055f355ff61e4d51f66962d
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/input/delete.txt
@@ -0,0 +1 @@
+obsolete
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/input/modify.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/input/modify.txt
new file mode 100644
index 0000000000000000000000000000000000000000..c0d0fb45c382919737f8d0c20aaf57cf89b74af8
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/input/modify.txt
@@ -0,0 +1,2 @@
+line1
+line2
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..673dec2f78dd6ba4d1dd73824d72aa1ba8294aef
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/002_multiple_operations/patch.txt
@@ -0,0 +1,9 @@
+*** Begin Patch
+*** Add File: nested/new.txt
++created
+*** Delete File: delete.txt
+*** Update File: modify.txt
+@@
+-line2
++changed
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/expected/multi.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/expected/multi.txt
new file mode 100644
index 0000000000000000000000000000000000000000..9054a72916ae61725d3cdb02d8eab81e14cb6e4f
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/expected/multi.txt
@@ -0,0 +1,4 @@
+line1
+changed2
+line3
+changed4
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/input/multi.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/input/multi.txt
new file mode 100644
index 0000000000000000000000000000000000000000..84275f9939456e87efd6932bdf7fe01d52a53116
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/input/multi.txt
@@ -0,0 +1,4 @@
+line1
+line2
+line3
+line4
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..45733c714bb6bbbc3d455798cf1f16ceba947d5f
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/003_multiple_chunks/patch.txt
@@ -0,0 +1,9 @@
+*** Begin Patch
+*** Update File: multi.txt
+@@
+-line2
++changed2
+@@
+-line4
++changed4
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/expected/old/other.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/expected/old/other.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b61039d3df8a5590e91871eb6f131eaa5b0e1dae
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/expected/old/other.txt
@@ -0,0 +1 @@
+unrelated file
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/expected/renamed/dir/name.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/expected/renamed/dir/name.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b66ba06d315d46280bb09d54614cc52d1677809f
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/expected/renamed/dir/name.txt
@@ -0,0 +1 @@
+new content
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/input/old/name.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/input/old/name.txt
new file mode 100644
index 0000000000000000000000000000000000000000..33194a0a6f3f99e366d606c24d9b1ab0e0086e69
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/input/old/name.txt
@@ -0,0 +1 @@
+old content
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/input/old/other.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/input/old/other.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b61039d3df8a5590e91871eb6f131eaa5b0e1dae
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/input/old/other.txt
@@ -0,0 +1 @@
+unrelated file
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5e2d723a2b429040b300283402bff3491e97dc88
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/004_move_to_new_directory/patch.txt
@@ -0,0 +1,7 @@
+*** Begin Patch
+*** Update File: old/name.txt
+*** Move to: renamed/dir/name.txt
+@@
+-old content
++new content
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/expected/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/input/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..4fcfecbbc779ed8f085bdd8247c64fd66ffcbdca
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/005_rejects_empty_patch/patch.txt
@@ -0,0 +1,2 @@
+*** Begin Patch
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/expected/modify.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/expected/modify.txt
new file mode 100644
index 0000000000000000000000000000000000000000..c0d0fb45c382919737f8d0c20aaf57cf89b74af8
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/expected/modify.txt
@@ -0,0 +1,2 @@
+line1
+line2
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/input/modify.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/input/modify.txt
new file mode 100644
index 0000000000000000000000000000000000000000..c0d0fb45c382919737f8d0c20aaf57cf89b74af8
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/input/modify.txt
@@ -0,0 +1,2 @@
+line1
+line2
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..488438b12b0652752cdf69e071405756d4cb010a
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/006_rejects_missing_context/patch.txt
@@ -0,0 +1,6 @@
+*** Begin Patch
+*** Update File: modify.txt
+@@
+-missing
++changed
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/expected/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/input/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..6f95531db3612e28cf116e6cdc8942c110eb7039
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/007_rejects_missing_file_delete/patch.txt
@@ -0,0 +1,3 @@
+*** Begin Patch
+*** Delete File: missing.txt
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/expected/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/input/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d7596a362be7e943804d8e9a9ff4045a5104ddfc
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/008_rejects_empty_update_hunk/patch.txt
@@ -0,0 +1,3 @@
+*** Begin Patch
+*** Update File: foo.txt
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/expected/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/input/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..a7de4f24c57886b3d43f5f50620e84359a849940
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/009_requires_existing_file_for_update/patch.txt
@@ -0,0 +1,6 @@
+*** Begin Patch
+*** Update File: missing.txt
+@@
+-old
++new
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/expected/old/other.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/expected/old/other.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b61039d3df8a5590e91871eb6f131eaa5b0e1dae
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/expected/old/other.txt
@@ -0,0 +1 @@
+unrelated file
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/expected/renamed/dir/name.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/expected/renamed/dir/name.txt
new file mode 100644
index 0000000000000000000000000000000000000000..3e757656cf36eca53338e520d134963a44f793f8
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/expected/renamed/dir/name.txt
@@ -0,0 +1 @@
+new
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/old/name.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/old/name.txt
new file mode 100644
index 0000000000000000000000000000000000000000..3940df7cd8791c48c101a7543b3a9fd7ef930e78
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/old/name.txt
@@ -0,0 +1 @@
+from
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/old/other.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/old/other.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b61039d3df8a5590e91871eb6f131eaa5b0e1dae
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/old/other.txt
@@ -0,0 +1 @@
+unrelated file
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/renamed/dir/name.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/renamed/dir/name.txt
new file mode 100644
index 0000000000000000000000000000000000000000..cbaf024e5e7fa87bdd8ad76b1393d9973585bc97
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/input/renamed/dir/name.txt
@@ -0,0 +1 @@
+existing
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..c45ce6d7826992507b6e612b49b1724749876c80
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/010_move_overwrites_existing_destination/patch.txt
@@ -0,0 +1,7 @@
+*** Begin Patch
+*** Update File: old/name.txt
+*** Move to: renamed/dir/name.txt
+@@
+-from
++new
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/expected/duplicate.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/expected/duplicate.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b66ba06d315d46280bb09d54614cc52d1677809f
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/expected/duplicate.txt
@@ -0,0 +1 @@
+new content
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/input/duplicate.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/input/duplicate.txt
new file mode 100644
index 0000000000000000000000000000000000000000..33194a0a6f3f99e366d606c24d9b1ab0e0086e69
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/input/duplicate.txt
@@ -0,0 +1 @@
+old content
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..bad9cf3fded135bc7e758b5f15bbd018af114efd
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/011_add_overwrites_existing_file/patch.txt
@@ -0,0 +1,4 @@
+*** Begin Patch
+*** Add File: duplicate.txt
++new content
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/expected/dir/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/expected/dir/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/expected/dir/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/input/dir/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/input/dir/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/input/dir/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..a10bcd9ea9c7d89e5f7eafb9b8595b2cd7dd5a33
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/012_delete_directory_fails/patch.txt
@@ -0,0 +1,3 @@
+*** Begin Patch
+*** Delete File: dir
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/expected/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2bf5ad0447d3370461c6f32a0a5bc8a3177376aa
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/input/foo.txt
@@ -0,0 +1 @@
+stable
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b35d7207d758490ff7495c4d7aa63375b6562b5a
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/013_rejects_invalid_hunk_header/patch.txt
@@ -0,0 +1,3 @@
+*** Begin Patch
+*** Frobnicate File: foo
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/expected/no_newline.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/expected/no_newline.txt
new file mode 100644
index 0000000000000000000000000000000000000000..06fcdd77c9348567c50638b30d406500f521c304
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/expected/no_newline.txt
@@ -0,0 +1,2 @@
+first line
+second line
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/input/no_newline.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/input/no_newline.txt
new file mode 100644
index 0000000000000000000000000000000000000000..a6e09874b5f93972808f3494a8ee14d4d948fc35
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/input/no_newline.txt
@@ -0,0 +1 @@
+no newline at end
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..4ed5818eb1cb134ce7539c9ecfcda7a6346698d6
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/014_update_file_appends_trailing_newline/patch.txt
@@ -0,0 +1,7 @@
+*** Begin Patch
+*** Update File: no_newline.txt
+@@
+-no newline at end
++first line
++second line
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/015_failure_after_partial_success_leaves_changes/expected/created.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/015_failure_after_partial_success_leaves_changes/expected/created.txt
new file mode 100644
index 0000000000000000000000000000000000000000..ce013625030ba8dba906f756967f9e9ca394464a
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/015_failure_after_partial_success_leaves_changes/expected/created.txt
@@ -0,0 +1 @@
+hello
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/015_failure_after_partial_success_leaves_changes/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/015_failure_after_partial_success_leaves_changes/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..a6e9709d1f6af0058a709aa758c12e4b94f3cc3b
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/015_failure_after_partial_success_leaves_changes/patch.txt
@@ -0,0 +1,8 @@
+*** Begin Patch
+*** Add File: created.txt
++hello
+*** Update File: missing.txt
+@@
+-old
++new
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/expected/input.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/expected/input.txt
new file mode 100644
index 0000000000000000000000000000000000000000..f6d6f0bef856b102699aa7acd595fbff9aed34ee
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/expected/input.txt
@@ -0,0 +1,4 @@
+line1
+line2
+added line 1
+added line 2
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/input/input.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/input/input.txt
new file mode 100644
index 0000000000000000000000000000000000000000..c0d0fb45c382919737f8d0c20aaf57cf89b74af8
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/input/input.txt
@@ -0,0 +1,2 @@
+line1
+line2
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..56337549f9ffe1115f00b3fcf5037dee31cdeda9
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/016_pure_addition_update_chunk/patch.txt
@@ -0,0 +1,6 @@
+*** Begin Patch
+*** Update File: input.txt
+@@
++added line 1
++added line 2
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..3e757656cf36eca53338e520d134963a44f793f8
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/expected/foo.txt
@@ -0,0 +1 @@
+new
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..3367afdbbf91e638efe983616377c60477cc6612
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/input/foo.txt
@@ -0,0 +1 @@
+old
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..21e6c1958d8c834b899243c6309b862b78aa91b1
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/017_whitespace_padded_hunk_header/patch.txt
@@ -0,0 +1,6 @@
+*** Begin Patch
+  *** Update File: foo.txt
+@@
+-old
++new
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/expected/file.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/expected/file.txt
new file mode 100644
index 0000000000000000000000000000000000000000..f719efd430d52bcfc8566a43b2eb655688d38871
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/expected/file.txt
@@ -0,0 +1 @@
+two
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/input/file.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/input/file.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5626abf0f72e58d7a153368ba57db4c673c0e171
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/input/file.txt
@@ -0,0 +1 @@
+one
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2648721797e8017ab4ab561d082e93c08c571e33
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/018_whitespace_padded_patch_markers/patch.txt
@@ -0,0 +1,6 @@
+ *** Begin Patch
+*** Update File: file.txt
+@@
+-one
++two
+*** End Patch 
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/expected/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/expected/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..99d5a6e9c2f45d932e02f40796d655bf13fd513b
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/expected/foo.txt
@@ -0,0 +1,3 @@
+line1
+naïve café ✅
+line3
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/input/foo.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/input/foo.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b17094871378284e284c29384e0384a7f96268fe
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/input/foo.txt
@@ -0,0 +1,3 @@
+line1
+naïve café
+line3
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..9514207fdeacc7fad3b12192ecedb521a5458128
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/019_unicode_simple/patch.txt
@@ -0,0 +1,7 @@
+*** Begin Patch
+*** Update File: foo.txt
+@@
+ line1
+-naïve café
++naïve café ✅
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/expected/keep.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/expected/keep.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2fa992c0b8b5c6acd2bdd4fa31de29d29799bdd5
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/expected/keep.txt
@@ -0,0 +1 @@
+keep
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/input/keep.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/input/keep.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2fa992c0b8b5c6acd2bdd4fa31de29d29799bdd5
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/input/keep.txt
@@ -0,0 +1 @@
+keep
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/input/obsolete.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/input/obsolete.txt
new file mode 100644
index 0000000000000000000000000000000000000000..6e263abce10f69a67055f355ff61e4d51f66962d
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/input/obsolete.txt
@@ -0,0 +1 @@
+obsolete
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5978f73889453c2659941c191713c4c440633c6b
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_delete_file_success/patch.txt
@@ -0,0 +1,3 @@
+*** Begin Patch
+*** Delete File: obsolete.txt
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/expected/file.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/expected/file.txt
new file mode 100644
index 0000000000000000000000000000000000000000..f719efd430d52bcfc8566a43b2eb655688d38871
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/expected/file.txt
@@ -0,0 +1 @@
+two
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/input/file.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/input/file.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5626abf0f72e58d7a153368ba57db4c673c0e171
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/input/file.txt
@@ -0,0 +1 @@
+one
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..3d2a1dbe5ec3c5860a614ad8f6174d2f28c8e312
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/020_whitespace_padded_patch_marker_lines/patch.txt
@@ -0,0 +1,6 @@
+*** Begin Patch 
+*** Update File: file.txt
+@@
+-one
++two
+ *** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/expected/lines.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/expected/lines.txt
new file mode 100644
index 0000000000000000000000000000000000000000..8129d305c8e06efd4a0e742b2aab8d0958a2bc0f
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/expected/lines.txt
@@ -0,0 +1,2 @@
+line1
+line3
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/input/lines.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/input/lines.txt
new file mode 100644
index 0000000000000000000000000000000000000000..83db48f84ec878fbfb30b46d16630e944e34f205
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/input/lines.txt
@@ -0,0 +1,3 @@
+line1
+line2
+line3
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..860c6c9a9902885b5ab3c5a4a403a0827b0e793a
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/021_update_file_deletion_only/patch.txt
@@ -0,0 +1,7 @@
+*** Begin Patch
+*** Update File: lines.txt
+@@
+ line1
+-line2
+ line3
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/expected/tail.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/expected/tail.txt
new file mode 100644
index 0000000000000000000000000000000000000000..87463f92d717a4901543a4058f9c930203e51997
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/expected/tail.txt
@@ -0,0 +1,2 @@
+first
+second updated
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/input/tail.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/input/tail.txt
new file mode 100644
index 0000000000000000000000000000000000000000..66a52ee7a1d803dc57859c3e95ac9dcdc87c0164
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/input/tail.txt
@@ -0,0 +1,2 @@
+first
+second
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..8b16b5bd9ee31912d1e91dec35b38678f508c87e
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/022_update_file_end_of_file_marker/patch.txt
@@ -0,0 +1,8 @@
+*** Begin Patch
+*** Update File: tail.txt
+@@
+ first
+-second
++second updated
+*** End of File
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/expected/lines.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/expected/lines.txt
new file mode 100644
index 0000000000000000000000000000000000000000..43321636e611bea29569e72f60494ae3c6226ae2
Binary files /dev/null and b/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/expected/lines.txt differ
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/input/lines.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/input/lines.txt
new file mode 100644
index 0000000000000000000000000000000000000000..e1587ff9ea6ced3af32e07e4b6b68d21374907ec
Binary files /dev/null and b/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/input/lines.txt differ
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..6df72a09cfead674e32edbf76a1509e656031c22
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/023_preserves_crlf_line_endings/patch.txt
@@ -0,0 +1,9 @@
+*** Begin Patch
+*** Update File: lines.txt
+@@
+-one
++ONE
+ two
++between
+ three
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/expected/lines.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/expected/lines.txt
new file mode 100644
index 0000000000000000000000000000000000000000..967a20a3a7f3da2cbe11f49a82d07de06c7dae58
Binary files /dev/null and b/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/expected/lines.txt differ
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/input/lines.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/input/lines.txt
new file mode 100644
index 0000000000000000000000000000000000000000..92a67d3b1cf355f3828c2cbf19a35b73e1a575ef
Binary files /dev/null and b/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/input/lines.txt differ
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/patch.txt b/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/patch.txt
new file mode 100644
index 0000000000000000000000000000000000000000..a97b2f35a4b0de0ccbf352dcc548cace7b088bbf
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/024_preserves_mixed_line_endings/patch.txt
@@ -0,0 +1,9 @@
+*** Begin Patch
+*** Update File: lines.txt
+@@
+ one
+ two
+-three
++THREE
+ four
+*** End Patch
diff --git a/codex-rs/apply-patch/tests/fixtures/scenarios/README.md b/codex-rs/apply-patch/tests/fixtures/scenarios/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..65d1fbe2e4bbf48e8797deda2974a33b9460a7a9
--- /dev/null
+++ b/codex-rs/apply-patch/tests/fixtures/scenarios/README.md
@@ -0,0 +1,18 @@
+# Overview
+This directory is a collection of end to end tests for the apply-patch specification, meant to be easily portable to other languages or platforms.
+
+
+# Specification
+Each test case is one directory, composed of input state (input/), the patch operation (patch.txt), and the expected final state (expected/). This structure is designed to keep tests simple (i.e. test exactly one patch at a time) while still providing enough flexibility to test any given operation across files.
+
+Here's what this would look like for a simple test apply-patch test case to create a new file:
+
+```
+001_add/
+  input/
+    foo.md
+  expected/
+    foo.md
+    bar.md
+  patch.txt
+```
diff --git a/codex-rs/apply-patch/tests/suite/cli.rs b/codex-rs/apply-patch/tests/suite/cli.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c982c7aa864ffe80ba8f797439379ada50a20ad2
--- /dev/null
+++ b/codex-rs/apply-patch/tests/suite/cli.rs
@@ -0,0 +1,91 @@
+use assert_cmd::Command;
+use std::fs;
+use tempfile::tempdir;
+
+fn apply_patch_command() -> anyhow::Result<Command> {
+    Ok(Command::new(codex_utils_cargo_bin::cargo_bin(
+        "apply_patch",
+    )?))
+}
+
+#[test]
+fn test_apply_patch_cli_add_and_update() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let file = "cli_test.txt";
+    let absolute_path = tmp.path().join(file);
+
+    // 1) Add a file
+    let add_patch = format!(
+        r#"*** Begin Patch
+*** Add File: {file}
++hello
+*** End Patch"#
+    );
+    apply_patch_command()?
+        .arg(add_patch)
+        .current_dir(tmp.path())
+        .assert()
+        .success()
+        .stdout(format!("Success. Updated the following files:\nA {file}\n"));
+    assert_eq!(fs::read_to_string(&absolute_path)?, "hello\n");
+
+    // 2) Update the file
+    let update_patch = format!(
+        r#"*** Begin Patch
+*** Update File: {file}
+@@
+-hello
++world
+*** End Patch"#
+    );
+    apply_patch_command()?
+        .arg(update_patch)
+        .current_dir(tmp.path())
+        .assert()
+        .success()
+        .stdout(format!("Success. Updated the following files:\nM {file}\n"));
+    assert_eq!(fs::read_to_string(&absolute_path)?, "world\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_stdin_add_and_update() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let file = "cli_test_stdin.txt";
+    let absolute_path = tmp.path().join(file);
+
+    // 1) Add a file via stdin
+    let add_patch = format!(
+        r#"*** Begin Patch
+*** Add File: {file}
++hello
+*** End Patch"#
+    );
+    apply_patch_command()?
+        .current_dir(tmp.path())
+        .write_stdin(add_patch)
+        .assert()
+        .success()
+        .stdout(format!("Success. Updated the following files:\nA {file}\n"));
+    assert_eq!(fs::read_to_string(&absolute_path)?, "hello\n");
+
+    // 2) Update the file via stdin
+    let update_patch = format!(
+        r#"*** Begin Patch
+*** Update File: {file}
+@@
+-hello
++world
+*** End Patch"#
+    );
+    apply_patch_command()?
+        .current_dir(tmp.path())
+        .write_stdin(update_patch)
+        .assert()
+        .success()
+        .stdout(format!("Success. Updated the following files:\nM {file}\n"));
+    assert_eq!(fs::read_to_string(&absolute_path)?, "world\n");
+
+    Ok(())
+}
diff --git a/codex-rs/apply-patch/tests/suite/mod.rs b/codex-rs/apply-patch/tests/suite/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6c827e70b388df45eb0994d67aff6743db207e33
--- /dev/null
+++ b/codex-rs/apply-patch/tests/suite/mod.rs
@@ -0,0 +1,6 @@
+mod cli;
+#[cfg(unix)]
+mod no_follow;
+mod scenarios;
+#[cfg(not(target_os = "windows"))]
+mod tool;
diff --git a/codex-rs/apply-patch/tests/suite/no_follow.rs b/codex-rs/apply-patch/tests/suite/no_follow.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d2b05bfe1ee87529a36d9fb591f5cfd3e95f0a19
--- /dev/null
+++ b/codex-rs/apply-patch/tests/suite/no_follow.rs
@@ -0,0 +1,153 @@
+use codex_apply_patch::ApplyPatchOptions;
+use codex_apply_patch::MaybeApplyPatchVerified;
+use codex_apply_patch::apply_patch_with_options;
+use codex_apply_patch::parse_patch;
+use codex_apply_patch::verify_apply_patch_args;
+use codex_exec_server::LOCAL_FS;
+use codex_utils_path_uri::PathUri;
+use pretty_assertions::assert_eq;
+use std::fs;
+use std::os::unix::fs::symlink;
+
+#[tokio::test]
+async fn no_follow_rejects_leaf_and_ancestor_links_for_every_patch_operation() -> anyhow::Result<()>
+{
+    for path in ["link.txt", "linked/victim.txt"] {
+        for body in [
+            format!("*** Add File: {path}\n+changed"),
+            format!("*** Update File: {path}\n@@\n-original\n+changed"),
+            format!("*** Delete File: {path}"),
+            format!("*** Update File: {path}\n*** Move to: moved.txt\n@@\n-original\n+changed"),
+            format!("*** Update File: source.txt\n*** Move to: {path}\n@@\n-original\n+changed"),
+            "*** Add File: linked/new/nested.txt\n+changed".to_string(),
+            "*** Update File: source.txt\n*** Move to: linked/new/nested.txt\n@@\n-original\n+changed".to_string(),
+        ] {
+            let temp = tempfile::tempdir()?;
+            // macOS's temporary directory can itself contain a /var symlink.
+            let root = temp.path().canonicalize()?;
+            let work = root.join("work");
+            let outside = root.join("outside");
+            fs::create_dir(&work)?;
+            fs::create_dir(&outside)?;
+            fs::write(outside.join("victim.txt"), "original\n")?;
+            fs::write(work.join("source.txt"), "original\n")?;
+            symlink(outside.join("victim.txt"), work.join("link.txt"))?;
+            symlink(&outside, work.join("linked"))?;
+
+            let patch = format!("*** Begin Patch\n{body}\n*** End Patch");
+            let failure = apply_patch_with_options(
+                &patch,
+                ApplyPatchOptions {
+                    follow_symlinks: false,
+                    ..Default::default()
+                },
+                &PathUri::from_host_native_path(&work)?,
+                &mut Vec::new(),
+                &mut Vec::new(),
+                LOCAL_FS.as_ref(),
+                /*sandbox*/ None,
+            )
+            .await
+            .expect_err(&body);
+
+            assert!(failure.delta().is_empty(), "{body}");
+            assert_eq!(fs::read_to_string(outside.join("victim.txt"))?, "original\n");
+            assert_eq!(fs::read_to_string(work.join("source.txt"))?, "original\n");
+            assert!(!outside.join("new").exists(), "{body}");
+            assert!(!work.join("moved.txt").exists(), "{body}");
+            assert!(fs::symlink_metadata(work.join("link.txt"))?.is_symlink());
+        }
+    }
+    Ok(())
+}
+
+#[tokio::test]
+async fn no_follow_rechecks_paths_after_verification() -> anyhow::Result<()> {
+    let temp = tempfile::tempdir()?;
+    let root = temp.path().canonicalize()?;
+    fs::create_dir(root.join("approved"))?;
+    fs::create_dir(root.join("outside"))?;
+    fs::write(root.join("approved/file.txt"), "original\n")?;
+    fs::write(root.join("outside/file.txt"), "original\n")?;
+    let cwd = PathUri::from_host_native_path(&root)?;
+    let patch = "*** Begin Patch\n*** Update File: approved/file.txt\n@@\n-original\n+changed\n*** End Patch";
+    let MaybeApplyPatchVerified::Body(action) = verify_apply_patch_args(
+        parse_patch(patch)?,
+        &cwd,
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await
+    else {
+        panic!("regular-file patch should verify");
+    };
+    fs::rename(root.join("approved"), root.join("original"))?;
+    symlink(root.join("outside"), root.join("approved"))?;
+
+    apply_patch_with_options(
+        &action.patch,
+        ApplyPatchOptions {
+            follow_symlinks: false,
+            ..Default::default()
+        },
+        &cwd,
+        &mut Vec::new(),
+        &mut Vec::new(),
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await
+    .expect_err("swapped ancestor must not be followed");
+    assert_eq!(
+        fs::read_to_string(root.join("outside/file.txt"))?,
+        "original\n"
+    );
+    assert_eq!(
+        fs::read_to_string(root.join("original/file.txt"))?,
+        "original\n"
+    );
+    Ok(())
+}
+
+#[tokio::test]
+async fn no_follow_applies_regular_files_and_default_still_follows_links() -> anyhow::Result<()> {
+    let temp = tempfile::tempdir()?;
+    let root = temp.path().canonicalize()?;
+    let cwd = PathUri::from_host_native_path(&root)?;
+    let patch = "*** Begin Patch\n*** Add File: new/file.txt\n+original\n*** Update File: new/file.txt\n*** Move to: moved/file.txt\n@@\n-original\n+changed\n*** Add File: remove.txt\n+remove\n*** Delete File: remove.txt\n*** End Patch";
+    apply_patch_with_options(
+        patch,
+        ApplyPatchOptions {
+            follow_symlinks: false,
+            ..Default::default()
+        },
+        &cwd,
+        &mut Vec::new(),
+        &mut Vec::new(),
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await?;
+    assert_eq!(
+        fs::read_to_string(root.join("moved/file.txt"))?,
+        "changed\n"
+    );
+    assert!(!root.join("new/file.txt").exists());
+    assert!(!root.join("remove.txt").exists());
+
+    symlink(root.join("moved/file.txt"), root.join("link.txt"))?;
+    codex_apply_patch::apply_patch(
+        "*** Begin Patch\n*** Update File: link.txt\n@@\n-changed\n+followed\n*** End Patch",
+        &cwd,
+        &mut Vec::new(),
+        &mut Vec::new(),
+        LOCAL_FS.as_ref(),
+        /*sandbox*/ None,
+    )
+    .await?;
+    assert_eq!(
+        fs::read_to_string(root.join("moved/file.txt"))?,
+        "followed\n"
+    );
+    Ok(())
+}
diff --git a/codex-rs/apply-patch/tests/suite/scenarios.rs b/codex-rs/apply-patch/tests/suite/scenarios.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ed8d6a37a44db9952aab2f9bd2ff72bbd13b1f63
--- /dev/null
+++ b/codex-rs/apply-patch/tests/suite/scenarios.rs
@@ -0,0 +1,133 @@
+use anyhow::Context;
+use codex_apply_patch::CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR;
+use codex_utils_cargo_bin::find_resource;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command;
+use tempfile::tempdir;
+
+#[test]
+fn test_apply_patch_scenarios() -> anyhow::Result<()> {
+    let scenarios_marker = find_resource!("tests/fixtures/scenarios/.gitattributes")?;
+    let scenarios_dir = scenarios_marker
+        .parent()
+        .context("scenario marker should have a parent directory")?;
+    for scenario in fs::read_dir(scenarios_dir)
+        .with_context(|| format!("failed to read {}", scenarios_dir.display()))?
+    {
+        let scenario = scenario?;
+        let path = scenario.path();
+        if path.is_dir() {
+            run_apply_patch_scenario(&path)
+                .with_context(|| format!("failed to run scenario {}", path.display()))?;
+        }
+    }
+    Ok(())
+}
+
+/// Reads a scenario directory, copies the input files to a temporary directory, runs apply-patch,
+/// and asserts that the final state matches the expected state exactly.
+fn run_apply_patch_scenario(dir: &Path) -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+
+    // Copy the input files to the temporary directory
+    let input_dir = dir.join("input");
+    if input_dir.is_dir() {
+        copy_dir_recursive(&input_dir, tmp.path())?;
+    }
+
+    // Read the patch.txt file
+    let patch_path = dir.join("patch.txt");
+    let patch = fs::read_to_string(&patch_path)
+        .with_context(|| format!("failed to read {}", patch_path.display()))?;
+
+    // Run apply_patch in the temporary directory. We intentionally do not assert
+    // on the exit status here; the scenarios are specified purely in terms of
+    // final filesystem state, which we compare below.
+    Command::new(codex_utils_cargo_bin::cargo_bin("apply_patch")?)
+        .arg(patch)
+        .env(CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR, "1")
+        .current_dir(tmp.path())
+        .output()
+        .with_context(|| format!("failed to run scenario {}", dir.display()))?;
+
+    // Assert that the final state matches the expected state exactly
+    let expected_dir = dir.join("expected");
+    let expected_snapshot = snapshot_dir(&expected_dir)?;
+    let actual_snapshot = snapshot_dir(tmp.path())?;
+
+    assert_eq!(
+        actual_snapshot,
+        expected_snapshot,
+        "Scenario {} did not match expected final state",
+        dir.display()
+    );
+
+    Ok(())
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Entry {
+    File(Vec<u8>),
+    Dir,
+}
+
+fn snapshot_dir(root: &Path) -> anyhow::Result<BTreeMap<PathBuf, Entry>> {
+    let mut entries = BTreeMap::new();
+    if root.is_dir() {
+        snapshot_dir_recursive(root, root, &mut entries)?;
+    }
+    Ok(entries)
+}
+
+fn snapshot_dir_recursive(
+    base: &Path,
+    dir: &Path,
+    entries: &mut BTreeMap<PathBuf, Entry>,
+) -> anyhow::Result<()> {
+    for entry in fs::read_dir(dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        let Some(stripped) = path.strip_prefix(base).ok() else {
+            continue;
+        };
+        let rel = stripped.to_path_buf();
+
+        // Under Buck2, files in `__srcs` are often materialized as symlinks.
+        // Use `metadata()` (follows symlinks) so our fixture snapshots work
+        // under both Cargo and Buck2.
+        let metadata = fs::metadata(&path)?;
+        if metadata.is_dir() {
+            entries.insert(rel.clone(), Entry::Dir);
+            snapshot_dir_recursive(base, &path, entries)?;
+        } else if metadata.is_file() {
+            let contents = fs::read(&path)?;
+            entries.insert(rel, Entry::File(contents));
+        }
+    }
+    Ok(())
+}
+
+fn copy_dir_recursive(src: &Path, dst: &Path) -> anyhow::Result<()> {
+    for entry in fs::read_dir(src)? {
+        let entry = entry?;
+        let path = entry.path();
+        let dest_path = dst.join(entry.file_name());
+
+        // See note in `snapshot_dir_recursive` about Buck2 symlink trees.
+        let metadata = fs::metadata(&path)?;
+        if metadata.is_dir() {
+            fs::create_dir_all(&dest_path)?;
+            copy_dir_recursive(&path, &dest_path)?;
+        } else if metadata.is_file() {
+            if let Some(parent) = dest_path.parent() {
+                fs::create_dir_all(parent)?;
+            }
+            fs::copy(&path, &dest_path)?;
+        }
+    }
+    Ok(())
+}
diff --git a/codex-rs/apply-patch/tests/suite/tool.rs b/codex-rs/apply-patch/tests/suite/tool.rs
new file mode 100644
index 0000000000000000000000000000000000000000..36d37efe1c648854815cdbcd6531c0d9a524b064
--- /dev/null
+++ b/codex-rs/apply-patch/tests/suite/tool.rs
@@ -0,0 +1,437 @@
+use assert_cmd::Command;
+use codex_apply_patch::CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR;
+use pretty_assertions::assert_eq;
+use std::fs;
+use std::path::Path;
+use std::path::PathBuf;
+use tempfile::tempdir;
+
+fn run_apply_patch_in_dir(dir: &Path, patch: &str) -> anyhow::Result<assert_cmd::assert::Assert> {
+    let mut cmd = Command::new(codex_utils_cargo_bin::cargo_bin("apply_patch")?);
+    cmd.env(CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR, "1");
+    cmd.current_dir(dir);
+    Ok(cmd.arg(patch).assert())
+}
+
+fn assert_apply_patch_updates_file(
+    file_name: &str,
+    original: &[u8],
+    patch: &str,
+    expected: &[u8],
+) -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join(file_name);
+    fs::write(&target_path, original)?;
+
+    run_apply_patch_in_dir(tmp.path(), patch)?
+        .success()
+        .stdout(format!(
+            "Success. Updated the following files:\nM {file_name}\n"
+        ));
+
+    assert_eq!(fs::read(target_path)?, expected);
+    Ok(())
+}
+
+fn apply_patch_command(dir: &Path) -> anyhow::Result<Command> {
+    let mut cmd = Command::new(codex_utils_cargo_bin::cargo_bin("apply_patch")?);
+    cmd.env(CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR, "1");
+    cmd.current_dir(dir);
+    Ok(cmd)
+}
+
+fn resolved_under(root: &Path, path: &str) -> anyhow::Result<PathBuf> {
+    Ok(root.canonicalize()?.join(path))
+}
+
+#[test]
+fn test_apply_patch_cli_applies_multiple_operations() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let add_path = tmp.path().join("nested/new.txt");
+    let modify_path = tmp.path().join("modify.txt");
+    let delete_path = tmp.path().join("delete.txt");
+
+    fs::write(&modify_path, "line1\nline2\n")?;
+    fs::write(&delete_path, "obsolete\n")?;
+
+    let patch = "*** Begin Patch\n*** Add File: nested/new.txt\n+created\n*** Delete File: delete.txt\n*** Update File: modify.txt\n@@\n-line2\n+changed\n*** End Patch";
+
+    run_apply_patch_in_dir(tmp.path(), patch)?.success().stdout(
+        "Success. Updated the following files:\nA nested/new.txt\nM modify.txt\nD delete.txt\n",
+    );
+
+    assert_eq!(fs::read_to_string(add_path)?, "created\n");
+    assert_eq!(fs::read_to_string(&modify_path)?, "line1\nchanged\n");
+    assert!(!delete_path.exists());
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_applies_multiple_chunks() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join("multi.txt");
+    fs::write(&target_path, "line1\nline2\nline3\nline4\n")?;
+
+    let patch = "*** Begin Patch\n*** Update File: multi.txt\n@@\n-line2\n+changed2\n@@\n-line4\n+changed4\n*** End Patch";
+
+    run_apply_patch_in_dir(tmp.path(), patch)?
+        .success()
+        .stdout("Success. Updated the following files:\nM multi.txt\n");
+
+    assert_eq!(
+        fs::read_to_string(&target_path)?,
+        "line1\nchanged2\nline3\nchanged4\n"
+    );
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_rejects_overlapping_end_of_file_chunks() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join("overlapping.txt");
+    let expected_target_path = resolved_under(tmp.path(), "overlapping.txt")?;
+    fs::write(&target_path, "one\n")?;
+
+    let patch = "*** Begin Patch\n*** Update File: overlapping.txt\n@@\n-one\n+first\n@@\n-one\n+second\n*** End of File\n*** End Patch";
+
+    run_apply_patch_in_dir(tmp.path(), patch)?
+        .failure()
+        .stderr(format!(
+            "Failed to find expected lines in {}:\none\n",
+            expected_target_path.display()
+        ));
+
+    assert_eq!(fs::read_to_string(target_path)?, "one\n");
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_allows_overlapping_eof_chunks_in_legacy_mode() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join("overlapping.txt");
+    fs::write(&target_path, "one\n")?;
+
+    let patch = "*** Begin Patch\n*** Update File: overlapping.txt\n@@\n-one\n+first\n@@\n-one\n+second\n*** End of File\n*** End Patch";
+
+    Command::new(codex_utils_cargo_bin::cargo_bin("apply_patch")?)
+        .env_remove(CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR)
+        .arg(patch)
+        .current_dir(tmp.path())
+        .assert()
+        .success()
+        .stdout("Success. Updated the following files:\nM overlapping.txt\n");
+
+    assert_eq!(fs::read_to_string(target_path)?, "first\n");
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_preserves_crlf_from_target_file() -> anyhow::Result<()> {
+    let patch = "*** Begin Patch\n*** Update File: crlf.txt\n@@\n-one\n+uno\n@@\n two\n+\n+between\n three\n*** End Patch";
+
+    assert_apply_patch_updates_file(
+        "crlf.txt",
+        b"one\r\ntwo\r\nthree\r\n",
+        patch,
+        b"uno\r\ntwo\r\n\r\nbetween\r\nthree\r\n",
+    )
+}
+
+#[test]
+fn test_apply_patch_cli_appends_after_trailing_blank_crlf_line() -> anyhow::Result<()> {
+    let patch = "*** Begin Patch\n*** Update File: trailing_blank.txt\n@@\n+new\n*** End Patch";
+
+    assert_apply_patch_updates_file(
+        "trailing_blank.txt",
+        b"a\r\n\r\n",
+        patch,
+        b"a\r\n\r\nnew\r\n",
+    )
+}
+
+#[test]
+fn test_apply_patch_cli_uses_legacy_line_handling_without_rollout_env() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join("crlf.txt");
+    fs::write(&target_path, b"one\r\n")?;
+    let patch = "*** Begin Patch\n*** Update File: crlf.txt\n@@\n-one\n+uno\n*** End Patch";
+
+    Command::new(codex_utils_cargo_bin::cargo_bin("apply_patch")?)
+        .env_remove(CODEX_APPLY_PATCH_PRESERVE_LINE_ENDINGS_ENV_VAR)
+        .arg(patch)
+        .current_dir(tmp.path())
+        .assert()
+        .success();
+
+    assert_eq!(fs::read(target_path)?, b"uno\n");
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_preserves_cr_from_target_file() -> anyhow::Result<()> {
+    let patch = "*** Begin Patch\n*** Update File: cr.txt\n@@\n-one\n+uno\n@@\n two\n+\n+between\n three\n*** End Patch";
+
+    assert_apply_patch_updates_file(
+        "cr.txt",
+        b"one\rtwo\rthree\r",
+        patch,
+        b"uno\rtwo\r\rbetween\rthree\r",
+    )
+}
+
+#[test]
+fn test_apply_patch_cli_preserves_change_order_with_repeated_lines() -> anyhow::Result<()> {
+    let patch =
+        "*** Begin Patch\n*** Update File: repeated.txt\n@@\n-a\n-b\n+b\n+b\n+a\n*** End Patch";
+
+    assert_apply_patch_updates_file("repeated.txt", b"a\nb\n", patch, b"b\nb\na\n")
+}
+
+#[test]
+fn test_apply_patch_cli_preserves_repeated_context_line_ending() -> anyhow::Result<()> {
+    let patch =
+        "*** Begin Patch\n*** Update File: repeated_context.txt\n@@\n-same\n same\n*** End Patch";
+
+    assert_apply_patch_updates_file("repeated_context.txt", b"same\r\nsame\n", patch, b"same\n")
+}
+
+#[test]
+fn test_apply_patch_cli_preserves_untouched_mixed_line_endings() -> anyhow::Result<()> {
+    let patch = "*** Begin Patch\n*** Update File: mixed.txt\n@@\n one\n two\n-three\n+THREE\n four\n*** End Patch";
+
+    assert_apply_patch_updates_file(
+        "mixed.txt",
+        b"one\r\ntwo\rthree\nfour\r\n",
+        patch,
+        b"one\r\ntwo\rTHREE\r\nfour\r\n",
+    )
+}
+
+#[test]
+fn test_apply_patch_cli_uses_crlf_for_new_trailing_newline() -> anyhow::Result<()> {
+    let patch =
+        "*** Begin Patch\n*** Update File: no_trailing_newline.txt\n@@\n-one\n+ONE\n*** End Patch";
+
+    assert_apply_patch_updates_file(
+        "no_trailing_newline.txt",
+        b"one\r\ntwo",
+        patch,
+        b"ONE\r\ntwo\r\n",
+    )
+}
+
+#[test]
+fn test_apply_patch_cli_moves_file_to_new_directory() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let original_path = tmp.path().join("old/name.txt");
+    let new_path = tmp.path().join("renamed/dir/name.txt");
+    fs::create_dir_all(original_path.parent().expect("parent should exist"))?;
+    fs::write(&original_path, "old content\n")?;
+
+    let patch = "*** Begin Patch\n*** Update File: old/name.txt\n*** Move to: renamed/dir/name.txt\n@@\n-old content\n+new content\n*** End Patch";
+
+    run_apply_patch_in_dir(tmp.path(), patch)?
+        .success()
+        .stdout("Success. Updated the following files:\nM renamed/dir/name.txt\n");
+
+    assert!(!original_path.exists());
+    assert_eq!(fs::read_to_string(&new_path)?, "new content\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_rejects_empty_patch() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr("No files were modified.\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_reports_missing_context() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join("modify.txt");
+    let expected_target_path = resolved_under(tmp.path(), "modify.txt")?;
+    fs::write(&target_path, "line1\nline2\n")?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Update File: modify.txt\n@@\n-missing\n+changed\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr(format!(
+            "Failed to find expected lines in {}:\nmissing\n",
+            expected_target_path.display()
+        ));
+    assert_eq!(fs::read_to_string(&target_path)?, "line1\nline2\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_rejects_missing_file_delete() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let missing_path = resolved_under(tmp.path(), "missing.txt")?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Delete File: missing.txt\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr(format!(
+            "Failed to delete file {}\n",
+            missing_path.display()
+        ));
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_rejects_empty_update_hunk() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Update File: foo.txt\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr("Invalid patch hunk on line 2: Update file hunk for path 'foo.txt' is empty\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_requires_existing_file_for_update() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let missing_path = resolved_under(tmp.path(), "missing.txt")?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Update File: missing.txt\n@@\n-old\n+new\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr(format!(
+            "Failed to read file to update {}: No such file or directory (os error 2)\n",
+            missing_path.display()
+        ));
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_move_overwrites_existing_destination() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let original_path = tmp.path().join("old/name.txt");
+    let destination = tmp.path().join("renamed/dir/name.txt");
+    fs::create_dir_all(original_path.parent().expect("parent should exist"))?;
+    fs::create_dir_all(destination.parent().expect("parent should exist"))?;
+    fs::write(&original_path, "from\n")?;
+    fs::write(&destination, "existing\n")?;
+
+    run_apply_patch_in_dir(
+        tmp.path(),
+        "*** Begin Patch\n*** Update File: old/name.txt\n*** Move to: renamed/dir/name.txt\n@@\n-from\n+new\n*** End Patch",
+    )?
+    .success()
+    .stdout("Success. Updated the following files:\nM renamed/dir/name.txt\n");
+
+    assert!(!original_path.exists());
+    assert_eq!(fs::read_to_string(&destination)?, "new\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_add_overwrites_existing_file() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let path = tmp.path().join("duplicate.txt");
+    fs::write(&path, "old content\n")?;
+
+    run_apply_patch_in_dir(
+        tmp.path(),
+        "*** Begin Patch\n*** Add File: duplicate.txt\n+new content\n*** End Patch",
+    )?
+    .success()
+    .stdout("Success. Updated the following files:\nA duplicate.txt\n");
+
+    assert_eq!(fs::read_to_string(&path)?, "new content\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_delete_directory_fails() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let dir = tmp.path().join("dir");
+    let expected_dir = resolved_under(tmp.path(), "dir")?;
+    fs::create_dir(&dir)?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Delete File: dir\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr(format!(
+            "Failed to delete file {}\n",
+            expected_dir.display()
+        ));
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_rejects_invalid_hunk_header() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Frobnicate File: foo\n*** End Patch")
+        .assert()
+        .failure()
+        .stderr("Invalid patch hunk on line 2: '*** Frobnicate File: foo' is not a valid hunk header. Valid hunk headers: '*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_updates_file_appends_trailing_newline() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let target_path = tmp.path().join("no_newline.txt");
+    fs::write(&target_path, "no newline at end")?;
+
+    run_apply_patch_in_dir(
+        tmp.path(),
+        "*** Begin Patch\n*** Update File: no_newline.txt\n@@\n-no newline at end\n+first line\n+second line\n*** End Patch",
+    )?
+    .success()
+    .stdout("Success. Updated the following files:\nM no_newline.txt\n");
+
+    let contents = fs::read_to_string(&target_path)?;
+    assert!(contents.ends_with('\n'));
+    assert_eq!(contents, "first line\nsecond line\n");
+
+    Ok(())
+}
+
+#[test]
+fn test_apply_patch_cli_failure_after_partial_success_leaves_changes() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let new_file = tmp.path().join("created.txt");
+    let missing_file = resolved_under(tmp.path(), "missing.txt")?;
+
+    apply_patch_command(tmp.path())?
+        .arg("*** Begin Patch\n*** Add File: created.txt\n+hello\n*** Update File: missing.txt\n@@\n-old\n+new\n*** End Patch")
+        .assert()
+        .failure()
+        .stdout("")
+        .stderr(format!(
+            "Failed to read file to update {}: No such file or directory (os error 2)\n",
+            missing_file.display()
+        ));
+
+    assert_eq!(fs::read_to_string(&new_file)?, "hello\n");
+
+    Ok(())
+}
diff --git a/codex-rs/arg0/src/lib.rs b/codex-rs/arg0/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6b0d99a4372414409e2cdfd220c944b8190e51cc
--- /dev/null
+++ b/codex-rs/arg0/src/lib.rs
@@ -0,0 +1,813 @@
+use std::ffi::OsString;
+use std::fs::File;
+use std::future::Future;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_apply_patch::CODEX_CORE_APPLY_PATCH_ARG1;
+use codex_async_utils::THREAD_STACK_SIZE_BYTES;
+#[cfg(unix)]
+use codex_exec_server::CODEX_ARG0_EXEC_HELPER_ARG1;
+use codex_exec_server::CODEX_FS_HELPER_ARG1;
+use codex_install_context::InstallContext;
+use codex_sandboxing::landlock::CODEX_LINUX_SANDBOX_ARG0;
+use codex_utils_home_dir::find_codex_home;
+#[cfg(target_os = "windows")]
+use codex_windows_sandbox::CODEX_WINDOWS_SANDBOX_ARG1;
+#[cfg(unix)]
+use std::os::unix::fs::symlink;
+use tempfile::TempDir;
+
+const APPLY_PATCH_ARG0: &str = "apply_patch";
+const MISSPELLED_APPLY_PATCH_ARG0: &str = "applypatch";
+#[cfg(unix)]
+const EXECVE_WRAPPER_ARG0: &str = "codex-execve-wrapper";
+const LOCK_FILENAME: &str = ".lock";
+
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct Arg0DispatchPaths {
+    /// Stable path to the current Codex executable for child re-execs.
+    ///
+    /// Prefer this over [`std::env::current_exe()`] in code that may run under
+    /// a test harness, where `current_exe()` can point at the harness binary
+    /// instead of the real Codex CLI.
+    pub codex_self_exe: Option<PathBuf>,
+    pub codex_linux_sandbox_exe: Option<PathBuf>,
+    pub main_execve_wrapper_exe: Option<PathBuf>,
+}
+
+/// Keeps the per-session PATH entry alive and locked for the process lifetime.
+pub struct Arg0PathEntryGuard {
+    _temp_dir: TempDir,
+    _lock_file: File,
+    paths: Arg0DispatchPaths,
+}
+
+impl Arg0PathEntryGuard {
+    fn new(temp_dir: TempDir, lock_file: File, paths: Arg0DispatchPaths) -> Self {
+        Self {
+            _temp_dir: temp_dir,
+            _lock_file: lock_file,
+            paths,
+        }
+    }
+
+    pub fn paths(&self) -> &Arg0DispatchPaths {
+        &self.paths
+    }
+}
+
+pub fn arg0_dispatch() -> Option<Arg0PathEntryGuard> {
+    // Determine if we were invoked via the special alias.
+    let mut args = std::env::args_os();
+    let argv0 = args.next().unwrap_or_default();
+    let exe_name = Path::new(&argv0)
+        .file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or("");
+
+    #[cfg(unix)]
+    if exe_name == EXECVE_WRAPPER_ARG0 {
+        let mut args = std::env::args();
+        let _ = args.next();
+        let file = match args.next() {
+            Some(file) => file,
+            None => std::process::exit(1),
+        };
+        let argv = args.collect::<Vec<_>>();
+
+        let runtime = match tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+        {
+            Ok(runtime) => runtime,
+            Err(_) => std::process::exit(1),
+        };
+        let exit_code = runtime.block_on(
+            codex_shell_escalation::run_shell_escalation_execve_wrapper(file, argv),
+        );
+        match exit_code {
+            Ok(exit_code) => std::process::exit(exit_code),
+            Err(_) => std::process::exit(1),
+        }
+    }
+
+    if exe_name == CODEX_LINUX_SANDBOX_ARG0 {
+        // Safety: [`run_main`] never returns.
+        codex_linux_sandbox::run_main();
+    } else if exe_name == APPLY_PATCH_ARG0 || exe_name == MISSPELLED_APPLY_PATCH_ARG0 {
+        codex_apply_patch::main();
+    }
+
+    let argv1 = args.next().unwrap_or_default();
+    if argv1 == codex_sandboxing::CODEX_WINDOWS_MXC_ARG1 {
+        codex_sandboxing::run_windows_mxc_main();
+    }
+    #[cfg(unix)]
+    if argv1 == CODEX_ARG0_EXEC_HELPER_ARG1 {
+        codex_exec_server::run_arg0_exec_helper_main();
+    }
+    if argv1 == CODEX_FS_HELPER_ARG1 {
+        codex_exec_server::run_fs_helper_main();
+    }
+    #[cfg(target_os = "windows")]
+    if argv1 == CODEX_WINDOWS_SANDBOX_ARG1 {
+        codex_windows_sandbox::run_windows_sandbox_wrapper_main();
+    }
+    if argv1 == CODEX_CORE_APPLY_PATCH_ARG1 {
+        let patch_arg = args.next().and_then(|s| s.to_str().map(str::to_owned));
+        let exit_code = match patch_arg {
+            Some(patch_arg) => {
+                let mut stdout = std::io::stdout();
+                let mut stderr = std::io::stderr();
+                let cwd = match codex_utils_absolute_path::AbsolutePathBuf::current_dir() {
+                    Ok(cwd) => cwd,
+                    Err(_) => std::process::exit(1),
+                };
+                let runtime = match tokio::runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                {
+                    Ok(runtime) => runtime,
+                    Err(_) => std::process::exit(1),
+                };
+                let cwd = cwd.into();
+                let update_file_mode = codex_apply_patch::apply_patch_file_update_mode_from_env();
+                match runtime.block_on(codex_apply_patch::apply_patch_with_options(
+                    &patch_arg,
+                    codex_apply_patch::ApplyPatchOptions {
+                        update_file_mode,
+                        ..Default::default()
+                    },
+                    &cwd,
+                    &mut stdout,
+                    &mut stderr,
+                    codex_exec_server::LOCAL_FS.as_ref(),
+                    /*sandbox*/ None,
+                )) {
+                    Ok(_) => 0,
+                    Err(_) => 1,
+                }
+            }
+            None => {
+                eprintln!("Error: {CODEX_CORE_APPLY_PATCH_ARG1} requires a UTF-8 PATCH argument.");
+                1
+            }
+        };
+        std::process::exit(exit_code);
+    }
+
+    // This modifies the environment, which is not thread-safe, so do this
+    // before creating any threads/the Tokio runtime.
+    load_dotenv();
+
+    let (path_entry_guard, updated_path_env_var) = prepare_path_env_var_with_aliases(
+        InstallContext::current(),
+        std::env::var_os("PATH"),
+        prepare_path_entry_for_codex_aliases,
+    );
+    if let Some(updated_path_env_var) = updated_path_env_var {
+        // It is safe to call set_var() because our process is single-threaded at
+        // this point in its execution.
+        unsafe {
+            std::env::set_var("PATH", updated_path_env_var);
+        }
+    }
+    path_entry_guard
+}
+
+fn prepare_path_env_var_with_aliases(
+    install_context: &InstallContext,
+    existing_path: Option<OsString>,
+    prepare_aliases: impl FnOnce(Option<OsString>) -> std::io::Result<(Arg0PathEntryGuard, OsString)>,
+) -> (Option<Arg0PathEntryGuard>, Option<OsString>) {
+    let package_path = path_env_with_package_path_dir(install_context, existing_path.clone());
+    let path_for_aliases = package_path.clone().or(existing_path);
+
+    match prepare_aliases(path_for_aliases) {
+        Ok((path_entry, updated_path_env_var)) => (Some(path_entry), Some(updated_path_env_var)),
+        Err(err) => {
+            // It is possible that Codex will proceed successfully even if
+            // creating helper aliases fails, so warn the user and move on.
+            eprintln!("WARNING: proceeding, even though we could not create PATH aliases: {err}");
+            (None, package_path)
+        }
+    }
+}
+
+/// While we want to deploy the Codex CLI as a single executable for simplicity,
+/// we also want to expose some of its functionality as distinct CLIs, so we use
+/// the "arg0 trick" to determine which CLI to dispatch. This effectively allows
+/// us to simulate deploying multiple executables as a single binary on Mac and
+/// Linux (but not Windows).
+///
+/// When the current executable is invoked through the hard-link or alias named
+/// `codex-linux-sandbox` we *directly* execute
+/// [`codex_linux_sandbox::run_main`] (which never returns). Otherwise we:
+///
+/// 1.  Load `.env` values from `~/.codex/.env` before creating any threads.
+/// 2.  Spawn a main runtime thread with a controlled stack size.
+/// 3.  Construct a Tokio multi-thread runtime.
+/// 4.  Capture the current executable path and derive the
+///     `codex-linux-sandbox` helper path (falling back to the current
+///     executable if needed) so children can re-invoke the sandbox when running
+///     on Linux.
+/// 5.  Execute the provided async `main_fn` inside that runtime, forwarding any
+///     error. Note that `main_fn` receives [`Arg0DispatchPaths`], which
+///     contains the helper executable paths needed to construct
+///     [`codex_core::config::Config`].
+///
+/// This function should be used to wrap any `main()` function in binary crates
+/// in this workspace that depends on these helper CLIs.
+pub fn arg0_dispatch_or_else<F, Fut>(main_fn: F) -> anyhow::Result<()>
+where
+    F: FnOnce(Arg0DispatchPaths) -> Fut + Send + 'static,
+    Fut: Future<Output = anyhow::Result<()>>,
+{
+    // Retain the TempDir so it exists for the lifetime of the invocation of
+    // this executable. Admittedly, we could invoke `keep()` on it, but it
+    // would be nice to avoid leaving temporary directories behind, if possible.
+    let path_entry_guard = arg0_dispatch();
+    let current_exe = std::env::current_exe().ok();
+
+    // Regular invocation. Run the async entry point on a thread with the same
+    // stack budget as Tokio workers; `Runtime::block_on` otherwise runs the
+    // top-level future on the caller's OS stack.
+    let handle = std::thread::Builder::new()
+        .name("codex-main".to_string())
+        .stack_size(THREAD_STACK_SIZE_BYTES)
+        .spawn(move || {
+            let runtime = build_runtime()?;
+            runtime.block_on(run_main_with_arg0_guard(
+                path_entry_guard,
+                current_exe,
+                main_fn,
+            ))
+        })?;
+    match handle.join() {
+        Ok(result) => result,
+        Err(payload) => std::panic::resume_unwind(payload),
+    }
+}
+
+async fn run_main_with_arg0_guard<F, Fut>(
+    path_entry_guard: Option<Arg0PathEntryGuard>,
+    current_exe: Option<PathBuf>,
+    main_fn: F,
+) -> anyhow::Result<()>
+where
+    F: FnOnce(Arg0DispatchPaths) -> Fut,
+    Fut: Future<Output = anyhow::Result<()>>,
+{
+    let paths = Arg0DispatchPaths {
+        codex_self_exe: current_exe.clone(),
+        codex_linux_sandbox_exe: if cfg!(target_os = "linux") {
+            linux_sandbox_exe_path(path_entry_guard.as_ref(), current_exe)
+        } else {
+            None
+        },
+        main_execve_wrapper_exe: path_entry_guard
+            .as_ref()
+            .and_then(|path_entry| path_entry.paths().main_execve_wrapper_exe.clone()),
+    };
+
+    let result = main_fn(paths).await;
+    // Keep the arg0 tempdir guard alive until the async entry point finishes;
+    // runtime paths above can point at aliases inside that directory.
+    drop(path_entry_guard);
+    result
+}
+
+fn linux_sandbox_exe_path(
+    path_entry_guard: Option<&Arg0PathEntryGuard>,
+    current_exe: Option<PathBuf>,
+) -> Option<PathBuf> {
+    // Prefer the `codex-linux-sandbox` alias when available so callers can
+    // re-exec through a path whose basename still triggers arg0 dispatch on
+    // bubblewrap builds that do not support `--argv0`.
+    path_entry_guard
+        .and_then(|path_entry| path_entry.paths().codex_linux_sandbox_exe.clone())
+        .or(current_exe)
+}
+
+fn build_runtime() -> anyhow::Result<tokio::runtime::Runtime> {
+    let mut builder = tokio::runtime::Builder::new_multi_thread();
+    builder.enable_all();
+    builder.thread_stack_size(THREAD_STACK_SIZE_BYTES);
+    Ok(builder.build()?)
+}
+
+const ILLEGAL_ENV_VAR_PREFIX: &str = "CODEX_";
+
+/// Load env vars from ~/.codex/.env.
+///
+/// Security: Do not allow `.env` files to create or modify any variables
+/// with names starting with `CODEX_`.
+fn load_dotenv() {
+    if let Ok(codex_home) = find_codex_home()
+        && let Ok(iter) = dotenvy::from_path_iter(codex_home.join(".env"))
+    {
+        set_filtered(iter);
+    }
+}
+
+/// Helper to set vars from a dotenvy iterator while filtering out `CODEX_` keys.
+fn set_filtered<I>(iter: I)
+where
+    I: IntoIterator<Item = Result<(String, String), dotenvy::Error>>,
+{
+    for (key, value) in iter.into_iter().flatten() {
+        if !key.to_ascii_uppercase().starts_with(ILLEGAL_ENV_VAR_PREFIX) {
+            // It is safe to call set_var() because our process is
+            // single-threaded at this point in its execution.
+            unsafe { std::env::set_var(&key, &value) };
+        }
+    }
+}
+
+/// Creates a temporary directory with either:
+///
+/// - UNIX: `apply_patch` symlink to the current executable
+/// - WINDOWS: `apply_patch.bat` batch script to invoke the current executable
+///   with the hidden `--codex-run-as-apply-patch` flag.
+///
+/// Returns the temporary directory guard and the PATH value that prepends the
+/// temporary directory so `apply_patch` can be on the PATH without requiring the
+/// user to install a separate executable, simplifying the deployment of Codex
+/// CLI.
+/// Note: In debug builds the temp-dir guard is disabled to ease local testing.
+///
+/// IMPORTANT: Callers must update PATH before multiple threads are spawned.
+fn prepare_path_entry_for_codex_aliases(
+    existing_path: Option<OsString>,
+) -> std::io::Result<(Arg0PathEntryGuard, OsString)> {
+    let codex_home = find_codex_home()?;
+    #[cfg(not(debug_assertions))]
+    {
+        // Guard against placing helpers in system temp directories outside debug builds.
+        let temp_root = std::env::temp_dir();
+        if codex_home.starts_with(&temp_root) {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                format!(
+                    "Refusing to create helper binaries under temporary dir {temp_root:?} (codex_home: {codex_home:?})"
+                ),
+            ));
+        }
+    }
+
+    std::fs::create_dir_all(&codex_home)?;
+    // Use a CODEX_HOME-scoped temp root to avoid cluttering the top-level directory.
+    let temp_root = codex_home.join("tmp").join("arg0");
+    std::fs::create_dir_all(&temp_root)?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+
+        // Ensure only the current user can access the temp directory.
+        std::fs::set_permissions(&temp_root, std::fs::Permissions::from_mode(0o700))?;
+    }
+
+    // Best-effort cleanup of stale per-session dirs. Ignore failures so startup proceeds.
+    if let Err(err) = janitor_cleanup(&temp_root) {
+        eprintln!("WARNING: failed to clean up stale arg0 temp dirs: {err}");
+    }
+
+    let temp_dir = tempfile::Builder::new()
+        .prefix("codex-arg0")
+        .tempdir_in(&temp_root)?;
+    let path = temp_dir.path();
+
+    let lock_path = path.join(LOCK_FILENAME);
+    let lock_file = File::options()
+        .read(true)
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .open(&lock_path)?;
+    lock_file.try_lock()?;
+
+    for filename in &[
+        APPLY_PATCH_ARG0,
+        MISSPELLED_APPLY_PATCH_ARG0,
+        #[cfg(target_os = "linux")]
+        CODEX_LINUX_SANDBOX_ARG0,
+        #[cfg(unix)]
+        EXECVE_WRAPPER_ARG0,
+    ] {
+        let exe = std::env::current_exe()?;
+
+        #[cfg(unix)]
+        {
+            let link = path.join(filename);
+            symlink(&exe, &link)?;
+        }
+
+        #[cfg(windows)]
+        {
+            let batch_script = path.join(format!("{filename}.bat"));
+            let exe = windows_batch_executable_path(&exe, path);
+            std::fs::write(
+                &batch_script,
+                format!(
+                    r#"@echo off
+"{exe}" {CODEX_CORE_APPLY_PATCH_ARG1} %*
+"#,
+                ),
+            )?;
+        }
+    }
+
+    let updated_path_env_var = path_env_with_entry(path, existing_path);
+
+    let paths = Arg0DispatchPaths {
+        codex_self_exe: std::env::current_exe().ok(),
+        codex_linux_sandbox_exe: {
+            #[cfg(target_os = "linux")]
+            {
+                Some(path.join(CODEX_LINUX_SANDBOX_ARG0))
+            }
+            #[cfg(not(target_os = "linux"))]
+            {
+                None
+            }
+        },
+        main_execve_wrapper_exe: {
+            #[cfg(unix)]
+            {
+                Some(path.join(EXECVE_WRAPPER_ARG0))
+            }
+            #[cfg(not(unix))]
+            {
+                None
+            }
+        },
+    };
+
+    Ok((
+        Arg0PathEntryGuard::new(temp_dir, lock_file, paths),
+        updated_path_env_var,
+    ))
+}
+
+#[cfg(windows)]
+fn windows_batch_executable_path(executable: &Path, alias_directory: &Path) -> String {
+    pathdiff::diff_paths(executable, alias_directory)
+        .filter(|relative_path| relative_path.is_relative())
+        .map(|relative_path| format!("%~dp0{}", relative_path.display()))
+        .unwrap_or_else(|| executable.display().to_string())
+}
+
+fn path_env_with_package_path_dir(
+    install_context: &InstallContext,
+    existing_path: Option<OsString>,
+) -> Option<OsString> {
+    let path_dir = install_context
+        .package_layout
+        .as_ref()
+        .and_then(|package_layout| package_layout.path_dir.as_ref())?;
+    Some(path_env_with_entry(path_dir.as_path(), existing_path))
+}
+
+fn path_env_with_entry(path_entry: &Path, existing_path: Option<OsString>) -> OsString {
+    #[cfg(unix)]
+    const PATH_SEPARATOR: &str = ":";
+
+    #[cfg(windows)]
+    const PATH_SEPARATOR: &str = ";";
+
+    let capacity = path_entry.as_os_str().len()
+        + existing_path
+            .as_ref()
+            .map_or(0, |existing_path| 1 + existing_path.len());
+    let mut path_env_var = OsString::with_capacity(capacity);
+    path_env_var.push(path_entry);
+    if let Some(existing_path) = existing_path {
+        path_env_var.push(PATH_SEPARATOR);
+        path_env_var.push(existing_path);
+    }
+    path_env_var
+}
+
+fn janitor_cleanup(temp_root: &Path) -> std::io::Result<()> {
+    let entries = match std::fs::read_dir(temp_root) {
+        Ok(entries) => entries,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(err) => return Err(err),
+    };
+
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if !path.is_dir() {
+            continue;
+        }
+
+        // Skip the directory if locking fails or the lock is currently held.
+        let Some(_lock_file) = try_lock_dir(&path)? else {
+            continue;
+        };
+
+        match std::fs::remove_dir_all(&path) {
+            Ok(()) => {}
+            // Expected TOCTOU race: directory can disappear after read_dir/lock checks.
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(err) => return Err(err),
+        }
+    }
+
+    Ok(())
+}
+
+fn try_lock_dir(dir: &Path) -> std::io::Result<Option<File>> {
+    let lock_path = dir.join(LOCK_FILENAME);
+    let lock_file = match File::options().read(true).write(true).open(&lock_path) {
+        Ok(file) => file,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(err) => return Err(err),
+    };
+
+    match lock_file.try_lock() {
+        Ok(()) => Ok(Some(lock_file)),
+        Err(std::fs::TryLockError::WouldBlock) => Ok(None),
+        Err(err) => Err(err.into()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::Arg0DispatchPaths;
+    use super::Arg0PathEntryGuard;
+    use super::LOCK_FILENAME;
+    use super::janitor_cleanup;
+    use super::linux_sandbox_exe_path;
+    #[cfg(unix)]
+    use super::run_main_with_arg0_guard;
+    #[cfg(unix)]
+    use anyhow::ensure;
+    use codex_install_context::CodexPackageLayout;
+    use codex_install_context::InstallContext;
+    use codex_install_context::InstallMethod;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use std::fs::File;
+    #[cfg(windows)]
+    use std::os::windows::process::CommandExt;
+    use std::path::Path;
+    use std::path::PathBuf;
+    use tempfile::TempDir;
+
+    struct PackagePathTestFixture {
+        _temp_dir: TempDir,
+        arg0_dir: PathBuf,
+        existing_dir: PathBuf,
+        install_context: InstallContext,
+        path_dir: AbsolutePathBuf,
+    }
+
+    fn create_lock(dir: &Path) -> std::io::Result<File> {
+        let lock_path = dir.join(LOCK_FILENAME);
+        File::options()
+            .read(true)
+            .write(true)
+            .create(true)
+            .truncate(false)
+            .open(lock_path)
+    }
+
+    fn package_path_test_fixture() -> anyhow::Result<PackagePathTestFixture> {
+        let temp_dir = TempDir::new()?;
+        let arg0_dir = temp_dir.path().join("arg0");
+        let package_dir = temp_dir.path().join("package");
+        let bin_dir = package_dir.join("bin");
+        let path_dir = package_dir.join("codex-path");
+        let existing_dir = temp_dir.path().join("existing-bin");
+        fs::create_dir_all(&arg0_dir)?;
+        fs::create_dir_all(&bin_dir)?;
+        fs::create_dir_all(&path_dir)?;
+        fs::create_dir_all(&existing_dir)?;
+        let path_dir = AbsolutePathBuf::from_absolute_path(path_dir.canonicalize()?)?;
+        let install_context = InstallContext {
+            method: InstallMethod::Other,
+            package_layout: Some(CodexPackageLayout {
+                package_dir: AbsolutePathBuf::from_absolute_path(package_dir.canonicalize()?)?,
+                bin_dir: AbsolutePathBuf::from_absolute_path(bin_dir.canonicalize()?)?,
+                resources_dir: None,
+                path_dir: Some(path_dir.clone()),
+            }),
+        };
+
+        Ok(PackagePathTestFixture {
+            _temp_dir: temp_dir,
+            arg0_dir,
+            existing_dir,
+            install_context,
+            path_dir,
+        })
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_batch_alias_preserves_unicode_executable_paths() -> anyhow::Result<()> {
+        let root = TempDir::new()?;
+        let profile = root.path().join("用户");
+        let alias_directory = profile.join(".codex").join("tmp").join("arg0");
+        let executable_directory = profile.join("bin");
+        fs::create_dir_all(&alias_directory)?;
+        fs::create_dir_all(&executable_directory)?;
+
+        let system_root = std::env::var_os("SystemRoot")
+            .ok_or_else(|| anyhow::anyhow!("missing Windows system root"))?;
+        let command_shell = PathBuf::from(system_root).join("System32").join("cmd.exe");
+        let executable = executable_directory.join("cmd.exe");
+        fs::copy(&command_shell, &executable)?;
+
+        let batch_path = alias_directory.join("apply_patch.bat");
+        let executable_path = super::windows_batch_executable_path(&executable, &alias_directory);
+        fs::write(
+            &batch_path,
+            format!("@echo off\r\n\"{executable_path}\" /d /c exit 37\r\n"),
+        )?;
+
+        let output = std::process::Command::new(command_shell)
+            .args(["/d", "/c"])
+            .raw_arg(format!("chcp 437>nul & call \"{}\"", batch_path.display()))
+            .output()?;
+
+        assert_eq!(output.status.code(), Some(37));
+        Ok(())
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_batch_alias_preserves_cross_volume_executable_paths() {
+        assert_eq!(
+            super::windows_batch_executable_path(
+                Path::new(r"D:\Tools\codex.exe"),
+                Path::new(r"C:\Users\person\.codex\tmp\arg0"),
+            ),
+            r"D:\Tools\codex.exe",
+        );
+    }
+
+    #[test]
+    fn linux_sandbox_exe_path_prefers_codex_linux_sandbox_alias() -> std::io::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let lock_file = create_lock(temp_dir.path())?;
+        let alias_path = temp_dir.path().join("codex-linux-sandbox");
+        let path_entry = Arg0PathEntryGuard::new(
+            temp_dir,
+            lock_file,
+            Arg0DispatchPaths {
+                codex_self_exe: Some(PathBuf::from("/usr/bin/codex")),
+                codex_linux_sandbox_exe: Some(alias_path.clone()),
+                main_execve_wrapper_exe: None,
+            },
+        );
+
+        assert_eq!(
+            linux_sandbox_exe_path(Some(&path_entry), Some(PathBuf::from("/usr/bin/codex"))),
+            Some(alias_path),
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn path_env_can_prepend_package_path_before_arg0_alias_dir() -> anyhow::Result<()> {
+        let fixture = package_path_test_fixture()?;
+
+        let package_path = super::path_env_with_package_path_dir(
+            &fixture.install_context,
+            Some(fixture.existing_dir.as_os_str().to_owned()),
+        )
+        .expect("package path dir should update PATH");
+        let updated_path = super::path_env_with_entry(&fixture.arg0_dir, Some(package_path));
+
+        assert_eq!(
+            std::env::split_paths(&updated_path).collect::<Vec<_>>(),
+            vec![
+                fixture.arg0_dir,
+                fixture.path_dir.as_path().to_path_buf(),
+                fixture.existing_dir
+            ],
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn package_path_survives_arg0_alias_setup_failure() -> anyhow::Result<()> {
+        let fixture = package_path_test_fixture()?;
+
+        let (path_entry_guard, updated_path_env_var) = super::prepare_path_env_var_with_aliases(
+            &fixture.install_context,
+            Some(fixture.existing_dir.as_os_str().to_owned()),
+            |path_for_aliases| {
+                assert_eq!(
+                    std::env::split_paths(
+                        &path_for_aliases.expect("package PATH should be passed to alias setup")
+                    )
+                    .collect::<Vec<_>>(),
+                    vec![
+                        fixture.path_dir.as_path().to_path_buf(),
+                        fixture.existing_dir.clone()
+                    ],
+                );
+                Err(std::io::Error::other("alias setup failed"))
+            },
+        );
+
+        assert!(path_entry_guard.is_none());
+        let updated_path_env_var =
+            updated_path_env_var.expect("package PATH should survive alias setup failure");
+        assert_eq!(
+            std::env::split_paths(&updated_path_env_var).collect::<Vec<_>>(),
+            vec![
+                fixture.path_dir.as_path().to_path_buf(),
+                fixture.existing_dir
+            ],
+        );
+        Ok(())
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn run_main_with_arg0_guard_keeps_aliases_alive_until_main_returns() -> anyhow::Result<()> {
+        let temp_dir = TempDir::new()?;
+        let alias_path = temp_dir.path().join("codex-helper-alias");
+        fs::write(&alias_path, b"")?;
+        let lock_file = create_lock(temp_dir.path())?;
+        let path_entry = Arg0PathEntryGuard::new(
+            temp_dir,
+            lock_file,
+            Arg0DispatchPaths {
+                codex_self_exe: Some(PathBuf::from("/usr/bin/codex")),
+                codex_linux_sandbox_exe: Some(alias_path.clone()),
+                main_execve_wrapper_exe: Some(alias_path),
+            },
+        );
+
+        super::build_runtime()?.block_on(run_main_with_arg0_guard(
+            /*path_entry_guard*/ Some(path_entry),
+            Some(PathBuf::from("/usr/bin/codex")),
+            |paths| async move {
+                let alias_path = paths
+                    .codex_linux_sandbox_exe
+                    .or(paths.main_execve_wrapper_exe)
+                    .expect("unix dispatch should create at least one alias path");
+                ensure!(
+                    alias_path.exists(),
+                    "alias path disappeared before main future was polled: {}",
+                    alias_path.display()
+                );
+
+                tokio::task::yield_now().await;
+
+                ensure!(
+                    alias_path.exists(),
+                    "alias path disappeared while main future was running: {}",
+                    alias_path.display()
+                );
+                Ok(())
+            },
+        ))
+    }
+
+    #[test]
+    fn janitor_skips_dirs_without_lock_file() -> std::io::Result<()> {
+        let root = tempfile::tempdir()?;
+        let dir = root.path().join("no-lock");
+        fs::create_dir(&dir)?;
+
+        janitor_cleanup(root.path())?;
+
+        assert!(dir.exists());
+        Ok(())
+    }
+
+    #[test]
+    fn janitor_skips_dirs_with_held_lock() -> std::io::Result<()> {
+        let root = tempfile::tempdir()?;
+        let dir = root.path().join("locked");
+        fs::create_dir(&dir)?;
+        let lock_file = create_lock(&dir)?;
+        lock_file.try_lock()?;
+
+        janitor_cleanup(root.path())?;
+
+        assert!(dir.exists());
+        Ok(())
+    }
+
+    #[test]
+    fn janitor_removes_dirs_with_unlocked_lock() -> std::io::Result<()> {
+        let root = tempfile::tempdir()?;
+        let dir = root.path().join("stale");
+        fs::create_dir(&dir)?;
+        create_lock(&dir)?;
+
+        janitor_cleanup(root.path())?;
+
+        assert!(!dir.exists());
+        Ok(())
+    }
+}
diff --git a/codex-rs/async-utils/src/lib.rs b/codex-rs/async-utils/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..16a86229ee73b63f8fc0b74e0700c2f0104d57c9
--- /dev/null
+++ b/codex-rs/async-utils/src/lib.rs
@@ -0,0 +1,89 @@
+use std::future::Future;
+use tokio_util::sync::CancellationToken;
+
+/// Stack budget for threads that poll Codex async work.
+pub const THREAD_STACK_SIZE_BYTES: usize = 16 * 1024 * 1024;
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum CancelErr {
+    Cancelled,
+}
+
+pub trait OrCancelExt: Sized {
+    type Output;
+
+    fn or_cancel(
+        self,
+        token: &CancellationToken,
+    ) -> impl Future<Output = Result<Self::Output, CancelErr>> + Send;
+}
+
+impl<F> OrCancelExt for F
+where
+    F: Future + Send,
+    F::Output: Send,
+{
+    type Output = F::Output;
+
+    async fn or_cancel(self, token: &CancellationToken) -> Result<Self::Output, CancelErr> {
+        tokio::select! {
+            _ = token.cancelled() => Err(CancelErr::Cancelled),
+            res = self => Ok(res),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use std::time::Duration;
+    use tokio::task;
+    use tokio::time::sleep;
+
+    #[tokio::test]
+    async fn returns_ok_when_future_completes_first() {
+        let token = CancellationToken::new();
+        let value = async { 42 };
+
+        let result = value.or_cancel(&token).await;
+
+        assert_eq!(Ok(42), result);
+    }
+
+    #[tokio::test]
+    async fn returns_err_when_token_cancelled_first() {
+        let token = CancellationToken::new();
+        let token_clone = token.clone();
+
+        let cancel_handle = task::spawn(async move {
+            sleep(Duration::from_millis(10)).await;
+            token_clone.cancel();
+        });
+
+        let result = async {
+            sleep(Duration::from_millis(100)).await;
+            7
+        }
+        .or_cancel(&token)
+        .await;
+
+        cancel_handle.await.expect("cancel task panicked");
+        assert_eq!(Err(CancelErr::Cancelled), result);
+    }
+
+    #[tokio::test]
+    async fn returns_err_when_token_already_cancelled() {
+        let token = CancellationToken::new();
+        token.cancel();
+
+        let result = async {
+            sleep(Duration::from_millis(50)).await;
+            5
+        }
+        .or_cancel(&token)
+        .await;
+
+        assert_eq!(Err(CancelErr::Cancelled), result);
+    }
+}
diff --git a/codex-rs/chatgpt/src/apply_command.rs b/codex-rs/chatgpt/src/apply_command.rs
new file mode 100644
index 0000000000000000000000000000000000000000..70fe4481db70c4bb0f71a89daff499ca5c7bb27b
--- /dev/null
+++ b/codex-rs/chatgpt/src/apply_command.rs
@@ -0,0 +1,77 @@
+use std::path::PathBuf;
+
+use clap::Parser;
+use codex_core::config::Config;
+use codex_git_utils::ApplyGitRequest;
+use codex_git_utils::apply_git_patch;
+use codex_utils_cli::CliConfigOverrides;
+
+use crate::get_task::GetTaskResponse;
+use crate::get_task::OutputItem;
+use crate::get_task::PrOutputItem;
+use crate::get_task::get_task;
+
+/// Applies the latest diff from a Codex agent task.
+#[derive(Debug, Parser)]
+pub struct ApplyCommand {
+    pub task_id: String,
+
+    #[clap(flatten)]
+    pub config_overrides: CliConfigOverrides,
+}
+pub async fn run_apply_command(
+    apply_cli: ApplyCommand,
+    cwd: Option<PathBuf>,
+) -> anyhow::Result<()> {
+    let config = Config::load_with_cli_overrides(
+        apply_cli
+            .config_overrides
+            .parse_overrides()
+            .map_err(anyhow::Error::msg)?,
+    )
+    .await?;
+
+    let task_response = get_task(&config, apply_cli.task_id).await?;
+    apply_diff_from_task(task_response, cwd).await
+}
+
+pub async fn apply_diff_from_task(
+    task_response: GetTaskResponse,
+    cwd: Option<PathBuf>,
+) -> anyhow::Result<()> {
+    let diff_turn = match task_response.current_diff_task_turn {
+        Some(turn) => turn,
+        None => anyhow::bail!("No diff turn found"),
+    };
+    let output_diff = diff_turn.output_items.iter().find_map(|item| match item {
+        OutputItem::Pr(PrOutputItem { output_diff }) => Some(output_diff),
+        _ => None,
+    });
+    match output_diff {
+        Some(output_diff) => apply_diff(&output_diff.diff, cwd).await,
+        None => anyhow::bail!("No PR output item found"),
+    }
+}
+
+async fn apply_diff(diff: &str, cwd: Option<PathBuf>) -> anyhow::Result<()> {
+    let cwd = cwd.unwrap_or(std::env::current_dir().unwrap_or_else(|_| std::env::temp_dir()));
+    let req = ApplyGitRequest {
+        cwd,
+        diff: diff.to_string(),
+        revert: false,
+        preflight: false,
+    };
+    let res = apply_git_patch(&req)?;
+    if res.exit_code != 0 {
+        anyhow::bail!(
+            "Git apply failed (applied={}, skipped={}, conflicts={})\nstdout:\n{}\nstderr:\n{}",
+            res.applied_paths.len(),
+            res.skipped_paths.len(),
+            res.conflicted_paths.len(),
+            res.stdout,
+            res.stderr
+        );
+    }
+    println!("Successfully applied diff");
+    Ok(())
+}
diff --git a/codex-rs/chatgpt/src/chatgpt_client.rs b/codex-rs/chatgpt/src/chatgpt_client.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2e6feb8256e29d85f3ed24b643a7d081321e270f
--- /dev/null
+++ b/codex-rs/chatgpt/src/chatgpt_client.rs
@@ -0,0 +1,176 @@
+use codex_core::config::Config;
+use codex_http_client::HttpClient;
+use codex_http_client::HttpClientFactory;
+use codex_login::AuthManager;
+use codex_login::CodexAuth;
+use codex_login::default_client::RESIDENCY_HEADER_NAME;
+use codex_login::default_client::create_client;
+use codex_login::default_client::create_client_with_chatgpt_cookies;
+use codex_login::default_client::default_headers;
+
+use anyhow::Context;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use std::sync::LazyLock;
+use std::sync::Mutex;
+use std::time::Duration;
+
+const OAI_PRODUCT_SKU_HEADER: &str = "OAI-Product-Sku";
+const CODEX_PRODUCT_SKU: &str = "codex";
+
+struct CachedChatGptClient {
+    factory: HttpClientFactory,
+    residency: Option<Vec<u8>>,
+    client: HttpClient,
+}
+
+static PSP_CHATGPT_CLIENT: LazyLock<Mutex<Option<CachedChatGptClient>>> =
+    LazyLock::new(|| Mutex::new(None));
+
+/// Reuse the default client while retaining its configured ChatGPT cookies.
+fn psp_chatgpt_client(factory: HttpClientFactory) -> HttpClient {
+    let residency = default_headers()
+        .get(RESIDENCY_HEADER_NAME)
+        .map(|value| value.as_bytes().to_vec());
+    let mut cached = PSP_CHATGPT_CLIENT
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    if let Some(cached_client) = cached.as_ref()
+        && cached_client.factory == factory
+        && cached_client.residency == residency
+    {
+        return cached_client.client.clone();
+    }
+
+    let client = create_client_with_chatgpt_cookies(&factory);
+    *cached = Some(CachedChatGptClient {
+        factory,
+        residency,
+        client: client.clone(),
+    });
+    client
+}
+
+/// Make a GET request to the ChatGPT backend API.
+pub(crate) async fn chatgpt_get_request<T: DeserializeOwned>(
+    config: &Config,
+    path: String,
+) -> anyhow::Result<T> {
+    chatgpt_get_request_with_timeout(config, path, /*timeout*/ None).await
+}
+
+pub(crate) async fn chatgpt_get_request_with_timeout<T: DeserializeOwned>(
+    config: &Config,
+    path: String,
+    timeout: Option<Duration>,
+) -> anyhow::Result<T> {
+    let chatgpt_base_url = &config.chatgpt_base_url;
+    let auth_manager =
+        AuthManager::shared_from_config(config, /*enable_codex_api_key_env*/ false).await?;
+    let auth = auth_manager
+        .auth()
+        .await
+        .ok_or_else(|| anyhow::anyhow!("ChatGPT auth not available"))?;
+    anyhow::ensure!(
+        auth.uses_codex_backend(),
+        "ChatGPT backend requests require Codex backend auth"
+    );
+    anyhow::ensure!(
+        auth.get_account_id().is_some(),
+        "ChatGPT account ID not available, please re-run `codex login`"
+    );
+
+    let url = format!(
+        "{}/{}",
+        chatgpt_base_url.trim_end_matches('/'),
+        path.trim_start_matches('/')
+    );
+
+    let http_client_factory = config.http_client_factory();
+    let client = if http_client_factory.has_chatgpt_cookies() {
+        psp_chatgpt_client(http_client_factory)
+    } else {
+        create_client()
+    };
+    let mut request = client
+        .get(&url)
+        .headers(default_headers())
+        .headers(codex_model_provider::auth_provider_from_auth(&auth).to_auth_headers())
+        .header(OAI_PRODUCT_SKU_HEADER, CODEX_PRODUCT_SKU)
+        .header("Content-Type", "application/json");
+    if let Some(timeout) = timeout {
+        request = request.timeout(timeout);
+    }
+    let response = request.send().await.context("Failed to send request")?;
+
+    if response.status().is_success() {
+        let result: T = response
+            .json()
+            .await
+            .context("Failed to parse JSON response")?;
+        Ok(result)
+    } else {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        anyhow::bail!("Request failed with status {status}: {body}")
+    }
+}
+
+/// Make a POST request to the ChatGPT backend API with an already-captured auth identity.
+///
+/// Callers that bind other state to the auth snapshot should pass that same snapshot here rather
+/// than reacquiring auth while the request is in flight.
+pub(crate) async fn chatgpt_post_request_with_timeout<
+    TResponse: DeserializeOwned,
+    TRequest: Serialize + ?Sized,
+>(
+    config: &Config,
+    auth: &CodexAuth,
+    path: String,
+    body: &TRequest,
+    timeout: Duration,
+    product_sku: &str,
+) -> anyhow::Result<TResponse> {
+    anyhow::ensure!(
+        auth.uses_codex_backend(),
+        "ChatGPT backend requests require Codex backend auth"
+    );
+    anyhow::ensure!(
+        auth.get_account_id().is_some(),
+        "ChatGPT account ID not available, please re-run codex login"
+    );
+
+    let url = format!(
+        "{}/{}",
+        config.chatgpt_base_url.trim_end_matches('/'),
+        path.trim_start_matches('/')
+    );
+    let http_client_factory = config.http_client_factory();
+    let client = if http_client_factory.has_chatgpt_cookies() {
+        psp_chatgpt_client(http_client_factory)
+    } else {
+        create_client()
+    };
+    let response = client
+        .post(&url)
+        .headers(default_headers())
+        .headers(codex_model_provider::auth_provider_from_auth(auth).to_auth_headers())
+        .header(OAI_PRODUCT_SKU_HEADER, product_sku)
+        .header("Content-Type", "application/json")
+        .timeout(timeout)
+        .json(body)
+        .send()
+        .await
+        .context("Failed to send request")?;
+
+    if response.status().is_success() {
+        response
+            .json()
+            .await
+            .context("Failed to parse JSON response")
+    } else {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        anyhow::bail!("Request failed with status {status}: {body}")
+    }
+}
diff --git a/codex-rs/chatgpt/src/connectors.rs b/codex-rs/chatgpt/src/connectors.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ae6cbce5c8110a4bab6b0dd807ff39d02e43a048
--- /dev/null
+++ b/codex-rs/chatgpt/src/connectors.rs
@@ -0,0 +1,505 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::time::Duration;
+
+use crate::chatgpt_client::chatgpt_get_request_with_timeout;
+use crate::chatgpt_client::chatgpt_post_request_with_timeout;
+
+use codex_connectors::AppInfo;
+use codex_connectors::AppToolPolicyEvaluator;
+use codex_connectors::ConnectorDirectoryCacheContext;
+use codex_connectors::ConnectorDirectoryCacheKey;
+use codex_connectors::ConnectorMetadata;
+use codex_connectors::ConnectorMetadataStore;
+use codex_connectors::ConnectorToolSummary;
+use codex_connectors::DirectoryListResponse;
+use codex_connectors::merge::merge_connectors;
+use codex_connectors::merge::merge_plugin_connectors;
+use codex_core::config::Config;
+pub use codex_core::connectors::list_accessible_connectors_from_mcp_tools;
+pub use codex_core::connectors::list_accessible_connectors_from_mcp_tools_with_environment_manager;
+pub use codex_core::connectors::list_accessible_connectors_from_mcp_tools_with_mcp_manager;
+pub use codex_core::connectors::list_accessible_connectors_from_mcp_tools_with_options;
+pub use codex_core::connectors::list_accessible_connectors_from_mcp_tools_with_options_and_status;
+pub use codex_core::connectors::list_cached_accessible_connectors_from_mcp_tools;
+use codex_login::AuthManager;
+use codex_login::CodexAuth;
+use codex_plugin::AppConnectorId;
+use serde::Deserialize;
+use serde::Serialize;
+
+const DIRECTORY_CONNECTORS_TIMEOUT: Duration = Duration::from_secs(60);
+const CONNECTOR_METADATA_TIMEOUT: Duration = Duration::from_secs(60);
+const DEFAULT_APPS_PRODUCT_SKU: &str = "codex";
+
+async fn apps_enabled(config: &Config) -> anyhow::Result<bool> {
+    let auth_manager =
+        AuthManager::shared_from_config(config, /*enable_codex_api_key_env*/ false).await?;
+    let auth = auth_manager.auth().await;
+    Ok(config
+        .features
+        .apps_enabled_for_auth(auth.as_ref().is_some_and(CodexAuth::uses_codex_backend)))
+}
+
+async fn connector_auth(config: &Config) -> anyhow::Result<CodexAuth> {
+    let auth_manager =
+        AuthManager::shared_from_config(config, /*enable_codex_api_key_env*/ false).await?;
+    let auth = auth_manager
+        .auth()
+        .await
+        .ok_or_else(|| anyhow::anyhow!("ChatGPT auth not available"))?;
+    anyhow::ensure!(
+        auth.uses_codex_backend(),
+        "ChatGPT connectors require Codex backend auth"
+    );
+    Ok(auth)
+}
+
+pub async fn list_connectors(config: &Config) -> anyhow::Result<Vec<AppInfo>> {
+    if !apps_enabled(config).await? {
+        return Ok(Vec::new());
+    }
+    let (connectors_result, accessible_result) = tokio::join!(
+        list_all_connectors(config),
+        list_accessible_connectors_from_mcp_tools(config),
+    );
+    let connectors = connectors_result?;
+    let accessible = accessible_result?;
+    Ok(
+        AppToolPolicyEvaluator::new(&config.config_layer_stack).apply_app_enabled_state(
+            merge_connectors_with_accessible(
+                connectors, accessible, /*all_connectors_loaded*/ true,
+            ),
+        ),
+    )
+}
+
+pub async fn list_all_connectors(config: &Config) -> anyhow::Result<Vec<AppInfo>> {
+    list_all_connectors_with_options(config, /*force_refetch*/ false, &[]).await
+}
+
+pub async fn list_cached_all_connectors(
+    config: &Config,
+    plugin_apps: &[AppConnectorId],
+) -> Option<Vec<AppInfo>> {
+    if !apps_enabled(config).await.ok()? {
+        return Some(Vec::new());
+    }
+
+    let auth = connector_auth(config).await.ok()?;
+    let cache_context = connector_directory_cache_context(config, &auth);
+    let connectors = codex_connectors::cached_directory_connectors(&cache_context)?;
+    Some(merge_directory_and_plugin_connectors(
+        connectors,
+        plugin_apps,
+    ))
+}
+
+pub async fn list_all_connectors_with_options(
+    config: &Config,
+    force_refetch: bool,
+    plugin_apps: &[AppConnectorId],
+) -> anyhow::Result<Vec<AppInfo>> {
+    if !apps_enabled(config).await? {
+        return Ok(Vec::new());
+    }
+    let auth = connector_auth(config).await?;
+    let cache_context = connector_directory_cache_context(config, &auth);
+    let connectors = codex_connectors::list_all_connectors_with_options(
+        cache_context,
+        auth.is_workspace_account(),
+        force_refetch,
+        |path| async move {
+            chatgpt_get_request_with_timeout::<DirectoryListResponse>(
+                config,
+                path,
+                Some(DIRECTORY_CONNECTORS_TIMEOUT),
+            )
+            .await
+        },
+    )
+    .await?;
+    Ok(merge_directory_and_plugin_connectors(
+        connectors,
+        plugin_apps,
+    ))
+}
+
+pub struct ConnectorMetadataReadResult {
+    pub apps: Vec<ConnectorMetadata>,
+    pub missing_app_ids: Vec<String>,
+}
+
+/// Reads display metadata without loading MCP connector tools or runtime state.
+///
+/// The store is created before awaiting the backend request, so a response that arrives after an
+/// account or backend change can only commit to the scope under which it was requested.
+pub async fn read_connector_metadata(
+    config: &Config,
+    auth: &CodexAuth,
+    app_ids: &[String],
+    include_tools: bool,
+) -> anyhow::Result<ConnectorMetadataReadResult> {
+    anyhow::ensure!(
+        auth.uses_codex_backend(),
+        "ChatGPT backend requests require Codex backend auth"
+    );
+    anyhow::ensure!(
+        auth.get_account_id().is_some(),
+        "ChatGPT account ID not available, please re-run codex login"
+    );
+
+    let store = ConnectorMetadataStore::new(
+        config.chatgpt_base_url.clone(),
+        auth.get_account_id(),
+        auth.get_chatgpt_user_id(),
+        auth.is_workspace_account(),
+    );
+    let mut metadata_by_id = store.fresh_records(app_ids, include_tools);
+    let missing_ids = app_ids
+        .iter()
+        .filter(|app_id| !metadata_by_id.contains_key(app_id.as_str()))
+        .cloned()
+        .collect::<Vec<_>>();
+
+    if !missing_ids.is_empty() {
+        let product_sku = config
+            .apps_mcp_product_sku
+            .as_deref()
+            .unwrap_or(DEFAULT_APPS_PRODUCT_SKU);
+        let response: GetAppsResponse = chatgpt_post_request_with_timeout(
+            config,
+            auth,
+            "/ps/apps/batch".to_string(),
+            &GetAppsRequest {
+                app_ids: &missing_ids,
+                include_tools,
+            },
+            CONNECTOR_METADATA_TIMEOUT,
+            product_sku,
+        )
+        .await?;
+        let mut requested_ids = missing_ids.iter().cloned().collect::<HashSet<_>>();
+        let fetched = response
+            .apps
+            .into_iter()
+            .map(batch_app_to_metadata)
+            .filter(|metadata| requested_ids.remove(&metadata.id))
+            .collect::<Vec<_>>();
+        store.commit(&fetched);
+        metadata_by_id.extend(
+            fetched
+                .into_iter()
+                .map(|metadata| (metadata.id.clone(), metadata)),
+        );
+    }
+
+    let mut apps = Vec::new();
+    let mut missing_app_ids = Vec::new();
+    for app_id in app_ids {
+        if let Some(mut metadata) = metadata_by_id.remove(app_id) {
+            if !include_tools {
+                metadata.tool_summaries = None;
+            }
+            apps.push(metadata);
+        } else {
+            missing_app_ids.push(app_id.clone());
+        }
+    }
+
+    Ok(ConnectorMetadataReadResult {
+        apps,
+        missing_app_ids,
+    })
+}
+
+#[derive(Serialize)]
+struct GetAppsRequest<'a> {
+    app_ids: &'a [String],
+    include_tools: bool,
+}
+
+#[derive(Deserialize)]
+struct GetAppsResponse {
+    apps: Vec<BatchApp>,
+}
+
+/// The explicit metadata-only projection of Plugin Service's public app response.
+///
+/// Serde ignores all other backend fields, including full actions, model descriptions, and
+/// runtime state.
+#[derive(Deserialize)]
+struct BatchApp {
+    id: String,
+    name: String,
+    description: Option<String>,
+    icon_url: Option<String>,
+    #[serde(default, rename = "icon_dark_url", alias = "icon_url_dark")]
+    icon_url_dark: Option<String>,
+    #[serde(default)]
+    distribution_channel: Option<String>,
+    #[serde(default)]
+    tools: Option<Vec<BatchAppToolSummary>>,
+}
+
+#[derive(Deserialize)]
+struct BatchAppToolSummary {
+    name: String,
+    title: Option<String>,
+    description: String,
+    #[serde(default)]
+    is_enabled: Option<bool>,
+    #[serde(default)]
+    disabled_reason: Option<String>,
+    #[serde(default)]
+    is_read_only: bool,
+}
+
+fn batch_app_to_metadata(app: BatchApp) -> ConnectorMetadata {
+    let BatchApp {
+        id,
+        name,
+        description,
+        icon_url,
+        icon_url_dark,
+        distribution_channel,
+        tools,
+    } = app;
+    ConnectorMetadata {
+        id,
+        name,
+        description,
+        icon_url,
+        icon_url_dark,
+        distribution_channel,
+        tool_summaries: tools.map(|tools| {
+            tools
+                .into_iter()
+                .map(|tool| {
+                    let BatchAppToolSummary {
+                        name,
+                        title,
+                        description,
+                        is_enabled,
+                        disabled_reason,
+                        is_read_only,
+                    } = tool;
+                    ConnectorToolSummary {
+                        name,
+                        title,
+                        description,
+                        is_enabled: is_enabled.unwrap_or(true),
+                        disabled_reason,
+                        is_read_only,
+                    }
+                })
+                .collect()
+        }),
+    }
+}
+
+fn connector_directory_cache_context(
+    config: &Config,
+    auth: &CodexAuth,
+) -> ConnectorDirectoryCacheContext {
+    ConnectorDirectoryCacheContext::new(
+        config.codex_home.to_path_buf(),
+        ConnectorDirectoryCacheKey::new(
+            config.chatgpt_base_url.clone(),
+            auth.get_account_id(),
+            auth.get_chatgpt_user_id(),
+            auth.is_workspace_account(),
+        ),
+    )
+}
+
+fn merge_directory_and_plugin_connectors(
+    connectors: Vec<AppInfo>,
+    plugin_apps: &[AppConnectorId],
+) -> Vec<AppInfo> {
+    merge_plugin_connectors(
+        connectors,
+        plugin_apps
+            .iter()
+            .map(|connector_id| connector_id.0.clone()),
+    )
+}
+
+pub fn connectors_for_plugin_apps(
+    connectors: Vec<AppInfo>,
+    plugin_apps: &[AppConnectorId],
+) -> Vec<AppInfo> {
+    let connectors = merge_plugin_connectors(
+        connectors,
+        plugin_apps
+            .iter()
+            .map(|connector_id| connector_id.0.clone()),
+    );
+    let mut connectors_by_id = connectors
+        .into_iter()
+        .map(|connector| (connector.id.clone(), connector))
+        .collect::<HashMap<_, _>>();
+
+    plugin_apps
+        .iter()
+        .filter_map(|connector_id| connectors_by_id.remove(connector_id.0.as_str()))
+        .collect()
+}
+
+pub fn merge_connectors_with_accessible(
+    connectors: Vec<AppInfo>,
+    accessible_connectors: Vec<AppInfo>,
+    all_connectors_loaded: bool,
+) -> Vec<AppInfo> {
+    let accessible_connectors = if all_connectors_loaded {
+        let connector_ids: HashSet<&str> = connectors
+            .iter()
+            .map(|connector| connector.id.as_str())
+            .collect();
+        accessible_connectors
+            .into_iter()
+            .filter(|connector| connector_ids.contains(connector.id.as_str()))
+            .collect()
+    } else {
+        accessible_connectors
+    };
+    merge_connectors(connectors, accessible_connectors)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_connectors::metadata::connector_install_url;
+    use codex_plugin::AppConnectorId;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    #[test]
+    fn batch_app_accepts_missing_optional_metadata() {
+        let app = serde_json::from_value::<BatchApp>(json!({
+            "id": "alpha",
+            "name": "Alpha",
+            "description": "Alpha description",
+            "icon_url": null,
+            "tools": [{
+                "name": "search",
+                "title": "Search",
+                "description": "Search Alpha",
+            }],
+        }))
+        .expect("valid legacy batch app");
+
+        assert_eq!(
+            batch_app_to_metadata(app),
+            ConnectorMetadata {
+                id: "alpha".to_string(),
+                name: "Alpha".to_string(),
+                description: Some("Alpha description".to_string()),
+                icon_url: None,
+                icon_url_dark: None,
+                distribution_channel: None,
+                tool_summaries: Some(vec![ConnectorToolSummary {
+                    name: "search".to_string(),
+                    title: Some("Search".to_string()),
+                    description: "Search Alpha".to_string(),
+                    is_enabled: true,
+                    disabled_reason: None,
+                    is_read_only: false,
+                }]),
+            }
+        );
+    }
+
+    fn app(id: &str) -> AppInfo {
+        AppInfo {
+            id: id.to_string(),
+            name: id.to_string(),
+            description: None,
+            logo_url: None,
+            logo_url_dark: None,
+            icon_assets: None,
+            icon_dark_assets: None,
+            distribution_channel: None,
+            branding: None,
+            app_metadata: None,
+            labels: None,
+            install_url: None,
+            is_accessible: false,
+            is_enabled: true,
+            plugin_display_names: Vec::new(),
+        }
+    }
+
+    fn merged_app(id: &str, is_accessible: bool) -> AppInfo {
+        AppInfo {
+            id: id.to_string(),
+            name: id.to_string(),
+            description: None,
+            logo_url: None,
+            logo_url_dark: None,
+            icon_assets: None,
+            icon_dark_assets: None,
+            distribution_channel: None,
+            branding: None,
+            app_metadata: None,
+            labels: None,
+            install_url: Some(connector_install_url(id, id)),
+            is_accessible,
+            is_enabled: true,
+            plugin_display_names: Vec::new(),
+        }
+    }
+
+    #[test]
+    fn excludes_accessible_connectors_not_in_all_when_all_loaded() {
+        let merged = merge_connectors_with_accessible(
+            vec![app("alpha")],
+            vec![app("alpha"), app("beta")],
+            /*all_connectors_loaded*/ true,
+        );
+        assert_eq!(merged, vec![merged_app("alpha", /*is_accessible*/ true)]);
+    }
+
+    #[test]
+    fn keeps_accessible_connectors_not_in_all_while_all_loading() {
+        let merged = merge_connectors_with_accessible(
+            vec![app("alpha")],
+            vec![app("alpha"), app("beta")],
+            /*all_connectors_loaded*/ false,
+        );
+        assert_eq!(
+            merged,
+            vec![
+                merged_app("alpha", /*is_accessible*/ true),
+                merged_app("beta", /*is_accessible*/ true)
+            ]
+        );
+    }
+
+    #[test]
+    fn connectors_for_plugin_apps_returns_only_requested_plugin_apps() {
+        let connectors = connectors_for_plugin_apps(
+            vec![app("alpha"), app("beta")],
+            &[
+                AppConnectorId("gmail".to_string()),
+                AppConnectorId("alpha".to_string()),
+                AppConnectorId("gmail".to_string()),
+            ],
+        );
+        assert_eq!(
+            connectors,
+            vec![merged_app("gmail", /*is_accessible*/ false), app("alpha")]
+        );
+    }
+
+    #[test]
+    fn connectors_for_plugin_apps_preserves_formerly_disallowed_plugin_apps() {
+        let connector_id = "asdk_app_6938a94a61d881918ef32cb999ff937c";
+        let connectors =
+            connectors_for_plugin_apps(Vec::new(), &[AppConnectorId(connector_id.to_string())]);
+        assert_eq!(
+            connectors,
+            vec![merged_app(connector_id, /*is_accessible*/ false)]
+        );
+    }
+}
diff --git a/codex-rs/chatgpt/src/get_task.rs b/codex-rs/chatgpt/src/get_task.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9301ffc38d32fe6d67089534ef775597167fffeb
--- /dev/null
+++ b/codex-rs/chatgpt/src/get_task.rs
@@ -0,0 +1,40 @@
+use codex_core::config::Config;
+use serde::Deserialize;
+
+use crate::chatgpt_client::chatgpt_get_request;
+
+#[derive(Debug, Deserialize)]
+pub struct GetTaskResponse {
+    pub current_diff_task_turn: Option<AssistantTurn>,
+}
+
+// Only relevant fields for our extraction
+#[derive(Debug, Deserialize)]
+pub struct AssistantTurn {
+    pub output_items: Vec<OutputItem>,
+}
+
+#[derive(Debug, Deserialize)]
+#[serde(tag = "type")]
+pub enum OutputItem {
+    #[serde(rename = "pr")]
+    Pr(PrOutputItem),
+
+    #[serde(other)]
+    Other,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct PrOutputItem {
+    pub output_diff: OutputDiff,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct OutputDiff {
+    pub diff: String,
+}
+
+pub(crate) async fn get_task(config: &Config, task_id: String) -> anyhow::Result<GetTaskResponse> {
+    let path = format!("/wham/tasks/{task_id}");
+    chatgpt_get_request(config, path).await
+}
diff --git a/codex-rs/chatgpt/src/lib.rs b/codex-rs/chatgpt/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..057478db1856c84a88eff8353d652be7280b8ae3
--- /dev/null
+++ b/codex-rs/chatgpt/src/lib.rs
@@ -0,0 +1,4 @@
+pub mod apply_command;
+mod chatgpt_client;
+pub mod connectors;
+pub mod get_task;
diff --git a/codex-rs/chatgpt/tests/all.rs b/codex-rs/chatgpt/tests/all.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7e136e4cce2a99915ff1b487d1f2b61c500f133a
--- /dev/null
+++ b/codex-rs/chatgpt/tests/all.rs
@@ -0,0 +1,3 @@
+// Single integration test binary that aggregates all test modules.
+// The submodules live in `tests/suite/`.
+mod suite;
diff --git a/codex-rs/chatgpt/tests/suite/apply_command_e2e.rs b/codex-rs/chatgpt/tests/suite/apply_command_e2e.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c2d570528ce87db7cacca9f17e4ad4d16e8f40ff
--- /dev/null
+++ b/codex-rs/chatgpt/tests/suite/apply_command_e2e.rs
@@ -0,0 +1,188 @@
+use codex_chatgpt::apply_command::apply_diff_from_task;
+use codex_chatgpt::get_task::GetTaskResponse;
+use codex_utils_cargo_bin::find_resource;
+use tempfile::TempDir;
+use tokio::process::Command;
+
+/// Creates a temporary git repository with initial commit
+async fn create_temp_git_repo() -> anyhow::Result<TempDir> {
+    let temp_dir = TempDir::new()?;
+    let repo_path = temp_dir.path();
+    let envs = vec![
+        ("GIT_CONFIG_GLOBAL", "/dev/null"),
+        ("GIT_CONFIG_NOSYSTEM", "1"),
+    ];
+
+    let output = Command::new("git")
+        .envs(envs.clone())
+        .args(["init"])
+        .current_dir(repo_path)
+        .output()
+        .await?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "Failed to initialize git repo: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    Command::new("git")
+        .envs(envs.clone())
+        .args(["config", "user.email", "test@example.com"])
+        .current_dir(repo_path)
+        .output()
+        .await?;
+
+    Command::new("git")
+        .envs(envs.clone())
+        .args(["config", "user.name", "Test User"])
+        .current_dir(repo_path)
+        .output()
+        .await?;
+
+    std::fs::write(repo_path.join("README.md"), "# Test Repo\n")?;
+
+    Command::new("git")
+        .envs(envs.clone())
+        .args(["add", "README.md"])
+        .current_dir(repo_path)
+        .output()
+        .await?;
+
+    let output = Command::new("git")
+        .envs(envs.clone())
+        .args(["commit", "-m", "Initial commit"])
+        .current_dir(repo_path)
+        .output()
+        .await?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "Failed to create initial commit: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    Ok(temp_dir)
+}
+
+async fn mock_get_task_with_fixture() -> anyhow::Result<GetTaskResponse> {
+    let fixture_path = find_resource!("tests/task_turn_fixture.json")?;
+    let fixture_content = tokio::fs::read_to_string(fixture_path).await?;
+    let response: GetTaskResponse = serde_json::from_str(&fixture_content)?;
+    Ok(response)
+}
+
+#[tokio::test]
+async fn test_apply_command_creates_fibonacci_file() {
+    let temp_repo = create_temp_git_repo()
+        .await
+        .expect("Failed to create temp git repo");
+    let repo_path = temp_repo.path();
+
+    let task_response = mock_get_task_with_fixture()
+        .await
+        .expect("Failed to load fixture");
+
+    apply_diff_from_task(task_response, Some(repo_path.to_path_buf()))
+        .await
+        .expect("Failed to apply diff from task");
+
+    // Assert that fibonacci.js was created in scripts/ directory
+    let fibonacci_path = repo_path.join("scripts/fibonacci.js");
+    assert!(fibonacci_path.exists(), "fibonacci.js was not created");
+
+    // Verify the file contents match expected
+    let contents = std::fs::read_to_string(&fibonacci_path).expect("Failed to read fibonacci.js");
+    assert!(
+        contents.contains("function fibonacci(n)"),
+        "fibonacci.js doesn't contain expected function"
+    );
+    assert!(
+        contents.contains("#!/usr/bin/env node"),
+        "fibonacci.js doesn't have shebang"
+    );
+    assert!(
+        contents.contains("module.exports = fibonacci;"),
+        "fibonacci.js doesn't export function"
+    );
+
+    // Verify file has correct number of lines (31 as specified in fixture)
+    let line_count = contents.lines().count();
+    assert_eq!(
+        line_count, 31,
+        "fibonacci.js should have 31 lines, got {line_count}",
+    );
+}
+
+#[tokio::test]
+async fn test_apply_command_with_merge_conflicts() {
+    let temp_repo = create_temp_git_repo()
+        .await
+        .expect("Failed to create temp git repo");
+    let repo_path = temp_repo.path();
+
+    // Create conflicting fibonacci.js file first
+    let scripts_dir = repo_path.join("scripts");
+    std::fs::create_dir_all(&scripts_dir).expect("Failed to create scripts directory");
+
+    let conflicting_content = r#"#!/usr/bin/env node
+
+// This is a different fibonacci implementation
+function fib(num) {
+  if (num <= 1) return num;
+  return fib(num - 1) + fib(num - 2);
+}
+
+console.log("Running fibonacci...");
+console.log(fib(10));
+"#;
+
+    let fibonacci_path = scripts_dir.join("fibonacci.js");
+    std::fs::write(&fibonacci_path, conflicting_content).expect("Failed to write conflicting file");
+
+    Command::new("git")
+        .args(["add", "scripts/fibonacci.js"])
+        .current_dir(repo_path)
+        .output()
+        .await
+        .expect("Failed to add fibonacci.js");
+
+    Command::new("git")
+        .args(["commit", "-m", "Add conflicting fibonacci implementation"])
+        .current_dir(repo_path)
+        .output()
+        .await
+        .expect("Failed to commit conflicting file");
+
+    let original_dir = std::env::current_dir().expect("Failed to get current dir");
+    std::env::set_current_dir(repo_path).expect("Failed to change directory");
+    struct DirGuard(std::path::PathBuf);
+    impl Drop for DirGuard {
+        fn drop(&mut self) {
+            let _ = std::env::set_current_dir(&self.0);
+        }
+    }
+    let _guard = DirGuard(original_dir);
+
+    let task_response = mock_get_task_with_fixture()
+        .await
+        .expect("Failed to load fixture");
+
+    let apply_result = apply_diff_from_task(task_response, Some(repo_path.to_path_buf())).await;
+
+    assert!(
+        apply_result.is_err(),
+        "Expected apply to fail due to merge conflicts"
+    );
+
+    let contents = std::fs::read_to_string(&fibonacci_path).expect("Failed to read fibonacci.js");
+
+    assert!(
+        contents.contains("<<<<<<< HEAD")
+            || contents.contains("=======")
+            || contents.contains(">>>>>>> "),
+        "fibonacci.js should contain merge conflict markers, got: {contents}",
+    );
+}
diff --git a/codex-rs/chatgpt/tests/suite/mod.rs b/codex-rs/chatgpt/tests/suite/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..40b4a59a0d19c2b38e4cf3cab2bf02818a281a6b
--- /dev/null
+++ b/codex-rs/chatgpt/tests/suite/mod.rs
@@ -0,0 +1,2 @@
+// Aggregates all former standalone integration tests as modules.
+mod apply_command_e2e;
diff --git a/codex-rs/chatgpt/tests/task_turn_fixture.json b/codex-rs/chatgpt/tests/task_turn_fixture.json
new file mode 100644
index 0000000000000000000000000000000000000000..3750f550395aaea491f3d2287e1a18002820876e
--- /dev/null
+++ b/codex-rs/chatgpt/tests/task_turn_fixture.json
@@ -0,0 +1,65 @@
+{
+    "current_diff_task_turn": {
+        "output_items": [
+            {
+                "type": "pr",
+                "pr_title": "Add fibonacci script",
+                "pr_message": "## Summary\n- add a basic Fibonacci script under `scripts/`\n\n## Testing\n- `node scripts/fibonacci.js 10`\n- `npm run lint` *(fails: next not found)*",
+                "output_diff": {
+                    "type": "output_diff",
+                    "repo_id": "/workspace/rddit-vercel",
+                    "base_commit_sha": "1a2e9baf2ce2fdd0c126b47b1bcfd512de2a9f7b",
+                    "diff": "diff --git a/scripts/fibonacci.js b/scripts/fibonacci.js\nnew file mode 100644\nindex 0000000000000000000000000000000000000000..6c9fdfdbf8669b7968936411050525b995d0a9a6\n--- /dev/null\n+++ b/scripts/fibonacci.js\n@@ -0,0 +1,31 @@\n+#!/usr/bin/env node\n+\n+function fibonacci(n) {\n+  if (n < 0) {\n+    throw new Error(\"n must be non-negative\");\n+  }\n+  let a = 0;\n+  let b = 1;\n+  for (let i = 0; i < n; i++) {\n+    const next = a + b;\n+    a = b;\n+    b = next;\n+  }\n+  return a;\n+}\n+\n+function printUsage() {\n+  console.log(\"Usage: node scripts/fibonacci.js <n>\");\n+}\n+\n+if (require.main === module) {\n+  const arg = process.argv[2];\n+  if (arg === undefined || isNaN(Number(arg))) {\n+    printUsage();\n+    process.exit(1);\n+  }\n+  const n = Number(arg);\n+  console.log(fibonacci(n));\n+}\n+\n+module.exports = fibonacci;\n",
+                    "external_storage_diff": {
+                        "file_id": "file_00000000114c61f786900f8c2130ace7",
+                        "ttl": null
+                    },
+                    "files_modified": 1,
+                    "lines_added": 31,
+                    "lines_removed": 0,
+                    "commit_message": "Add fibonacci script"
+                }
+            },
+            {
+                "type": "message",
+                "role": "assistant",
+                "content": [
+                    {
+                        "content_type": "text",
+                        "text": "**Summary**\n\n- Created a command-line Fibonacci script that validates input and prints the result when executed with Node"
+                    },
+                    {
+                        "content_type": "repo_file_citation",
+                        "path": "scripts/fibonacci.js",
+                        "line_range_start": 1,
+                        "line_range_end": 31
+                    },
+                    {
+                        "content_type": "text",
+                        "text": "\n\n**Testing**\n\n- ❌ `npm run lint` (failed to run `next lint`)"
+                    },
+                    {
+                        "content_type": "terminal_chunk_citation",
+                        "terminal_chunk_id": "7dd543",
+                        "line_range_start": 1,
+                        "line_range_end": 5
+                    },
+                    {
+                        "content_type": "text",
+                        "text": "\n- ✅ `node scripts/fibonacci.js 10` produced “55”"
+                    },
+                    {
+                        "content_type": "terminal_chunk_citation",
+                        "terminal_chunk_id": "6ee559",
+                        "line_range_start": 1,
+                        "line_range_end": 3
+                    },
+                    {
+                        "content_type": "text",
+                        "text": "\n\nCodex couldn't run certain commands due to environment limitations. Consider configuring a setup script or internet access in your Codex environment to install dependencies."
+                    }
+                ]
+            }
+        ]
+    }
+}
diff --git a/codex-rs/codex-client/src/lib.rs b/codex-rs/codex-client/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..60b8d0006394e456754d06c214ed90a2c55ee5e9
--- /dev/null
+++ b/codex-rs/codex-client/src/lib.rs
@@ -0,0 +1,14 @@
+mod retry;
+mod sse;
+mod telemetry;
+
+pub use crate::retry::RetryOn;
+pub use crate::retry::RetryOperation;
+pub use crate::retry::RetryPolicy;
+pub use crate::retry::backoff;
+pub use crate::retry::run_with_retry;
+pub use crate::sse::sse_stream;
+pub use crate::telemetry::RequestTelemetry;
+pub use codex_http_client::HttpClient as CodexHttpClient;
+pub use codex_http_client::RequestBuilder as CodexRequestBuilder;
+pub use codex_http_client::*;
diff --git a/codex-rs/codex-client/src/retry.rs b/codex-rs/codex-client/src/retry.rs
new file mode 100644
index 0000000000000000000000000000000000000000..86071851f61094a595af5024bbbb047f29275255
--- /dev/null
+++ b/codex-rs/codex-client/src/retry.rs
@@ -0,0 +1,109 @@
+use codex_http_client::Request;
+use codex_http_client::TransportError;
+use rand::Rng;
+use std::future::Future;
+use std::time::Duration;
+
+#[derive(Debug, Clone)]
+pub struct RetryPolicy {
+    pub max_attempts: u64,
+    pub base_delay: Duration,
+    pub retry_on: RetryOn,
+}
+
+#[derive(Debug, Clone)]
+pub struct RetryOn {
+    pub retry_429: bool,
+    pub retry_5xx: bool,
+    pub retry_transport: bool,
+}
+
+impl RetryOn {
+    pub fn should_retry(&self, err: &TransportError, attempt: u64, max_attempts: u64) -> bool {
+        if attempt >= max_attempts {
+            return false;
+        }
+        match err {
+            TransportError::Http { status, .. } => {
+                (self.retry_429 && status.as_u16() == 429)
+                    || (self.retry_5xx && status.is_server_error())
+            }
+            TransportError::Timeout
+            | TransportError::Connection(_)
+            | TransportError::Network(_) => self.retry_transport,
+            TransportError::Build(_)
+            | TransportError::RetryLimit
+            | TransportError::ResponseTooLarge { .. } => false,
+        }
+    }
+}
+
+pub fn backoff(base: Duration, attempt: u64) -> Duration {
+    if attempt == 0 {
+        return base;
+    }
+    let exp = 2u64.saturating_pow(attempt as u32 - 1);
+    let millis = base.as_millis() as u64;
+    let raw = millis.saturating_mul(exp);
+    let jitter: f64 = rand::rng().random_range(0.9..1.1);
+    Duration::from_millis((raw as f64 * jitter) as u64)
+}
+
+/// Identifies a retry path and its associated trace-event layer.
+#[derive(Debug, Clone, Copy)]
+pub enum RetryOperation {
+    HttpRequest,
+    Sampling,
+    RemoteCompactionV2,
+}
+
+/// Emits retry telemetry at the caller's source location without adding it to normal OTEL logs.
+#[macro_export]
+macro_rules! record_retry {
+    ($attempt:expr, $delay:expr, $operation:expr $(,)?) => {{
+        let (layer, operation) = match $operation {
+            $crate::RetryOperation::HttpRequest => ("http", "request"),
+            $crate::RetryOperation::Sampling => ("stream", "sampling"),
+            $crate::RetryOperation::RemoteCompactionV2 => ("stream", "remote_compaction_v2"),
+        };
+
+        ::tracing::event!(
+            target: "codex_otel.trace_safe",
+            ::tracing::Level::TRACE,
+            event.name = "codex.retry",
+            retry.attempt = $attempt,
+            retry.delay_ms = ($delay).as_millis() as u64,
+            retry.layer = layer,
+            retry.operation = operation,
+        );
+    }};
+}
+
+pub async fn run_with_retry<T, F, Fut>(
+    policy: RetryPolicy,
+    mut make_req: impl FnMut() -> Request,
+    op: F,
+) -> Result<T, TransportError>
+where
+    F: Fn(Request, u64) -> Fut,
+    Fut: Future<Output = Result<T, TransportError>>,
+{
+    for attempt in 0..=policy.max_attempts {
+        let req = make_req();
+        match op(req, attempt).await {
+            Ok(resp) => return Ok(resp),
+            Err(err)
+                if policy
+                    .retry_on
+                    .should_retry(&err, attempt, policy.max_attempts) =>
+            {
+                let retry_attempt = attempt + 1;
+                let delay = backoff(policy.base_delay, retry_attempt);
+                crate::record_retry!(retry_attempt, delay, RetryOperation::HttpRequest);
+                tokio::time::sleep(delay).await;
+            }
+            Err(err) => return Err(err),
+        }
+    }
+    Err(TransportError::RetryLimit)
+}
diff --git a/codex-rs/codex-client/src/sse.rs b/codex-rs/codex-client/src/sse.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ed1591f6de4bf4c7d7cef3ecbba8e52d07d2571c
--- /dev/null
+++ b/codex-rs/codex-client/src/sse.rs
@@ -0,0 +1,48 @@
+use codex_http_client::ByteStream;
+use codex_http_client::StreamError;
+use eventsource_stream::Eventsource;
+use futures::StreamExt;
+use tokio::sync::mpsc;
+use tokio::time::Duration;
+use tokio::time::timeout;
+
+/// Minimal SSE helper that forwards raw `data:` frames as UTF-8 strings.
+///
+/// Errors and idle timeouts are sent as `Err(StreamError)` before the task exits.
+pub fn sse_stream(
+    stream: ByteStream,
+    idle_timeout: Duration,
+    tx: mpsc::Sender<Result<String, StreamError>>,
+) {
+    tokio::spawn(async move {
+        let mut stream = stream
+            .map(|res| res.map_err(|e| StreamError::Stream(e.to_string())))
+            .eventsource();
+
+        loop {
+            match timeout(idle_timeout, stream.next()).await {
+                Ok(Some(Ok(ev))) => {
+                    if tx.send(Ok(ev.data.clone())).await.is_err() {
+                        return;
+                    }
+                }
+                Ok(Some(Err(e))) => {
+                    let _ = tx.send(Err(StreamError::Stream(e.to_string()))).await;
+                    return;
+                }
+                Ok(None) => {
+                    let _ = tx
+                        .send(Err(StreamError::Stream(
+                            "stream closed before completion".into(),
+                        )))
+                        .await;
+                    return;
+                }
+                Err(_) => {
+                    let _ = tx.send(Err(StreamError::Timeout)).await;
+                    return;
+                }
+            }
+        }
+    });
+}
diff --git a/codex-rs/codex-client/src/telemetry.rs b/codex-rs/codex-client/src/telemetry.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b856414d3332b25f88982dce9c97d3f5be3caa04
--- /dev/null
+++ b/codex-rs/codex-client/src/telemetry.rs
@@ -0,0 +1,14 @@
+use codex_http_client::TransportError;
+use http::StatusCode;
+use std::time::Duration;
+
+/// API specific telemetry.
+pub trait RequestTelemetry: Send + Sync {
+    fn on_request(
+        &self,
+        attempt: u64,
+        status: Option<StatusCode>,
+        error: Option<&TransportError>,
+        duration: Duration,
+    );
+}
diff --git a/codex-rs/core-api/src/lib.rs b/codex-rs/core-api/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a8facc3ae11fe761edd260ed51f187ded6491482
--- /dev/null
+++ b/codex-rs/core-api/src/lib.rs
@@ -0,0 +1,137 @@
+//! Public facade for thread management APIs built on `codex-core`.
+
+#![deny(private_bounds, private_interfaces, unreachable_pub)]
+
+pub use codex_analytics::AnalyticsEventsClient;
+pub use codex_app_server_protocol::ServerNotification;
+pub use codex_app_server_protocol::item_event_to_server_notification;
+pub use codex_arg0::Arg0DispatchPaths;
+pub use codex_arg0::arg0_dispatch_or_else;
+pub use codex_config::ConfigLayerStack;
+pub use codex_config::config_toml::ProjectConfig;
+pub use codex_config::config_toml::RealtimeAudioConfig;
+pub use codex_config::config_toml::RealtimeConfig;
+pub use codex_config::types::AuthCredentialsStoreMode;
+pub use codex_config::types::AuthKeyringBackendKind;
+pub use codex_config::types::History;
+pub use codex_config::types::MemoriesConfig;
+pub use codex_config::types::ModelAvailabilityNuxConfig;
+pub use codex_config::types::Notice;
+pub use codex_config::types::OAuthCredentialsStoreMode;
+pub use codex_config::types::OtelConfig;
+pub use codex_config::types::SessionPickerViewMode;
+pub use codex_config::types::ToolSuggestConfig;
+pub use codex_config::types::TuiKeymap;
+pub use codex_config::types::TuiNotificationSettings;
+pub use codex_config::types::TuiPetAnchor;
+pub use codex_config::types::UriBasedFileOpener;
+pub use codex_core::CodexAppsToolsCache;
+pub use codex_core::CodexThread;
+pub use codex_core::CodexThreadSettingsOverrides;
+pub use codex_core::EnvironmentConfig;
+pub use codex_core::EnvironmentMcpPolicy;
+pub use codex_core::EnvironmentNetworkPolicy;
+pub use codex_core::ForkSnapshot;
+pub use codex_core::LoadedAgentsMd;
+pub use codex_core::McpManager;
+pub use codex_core::NetworkDomainPermission;
+pub use codex_core::NetworkDomainPermissionEntry;
+pub use codex_core::NetworkDomainPermissions;
+pub use codex_core::NetworkUnixSocketPermission;
+pub use codex_core::NetworkUnixSocketPermissions;
+pub use codex_core::NewThread;
+pub use codex_core::NotSubmittedReason;
+pub use codex_core::RecoverTurnRequest;
+pub use codex_core::StartIfIdleSubmission;
+pub use codex_core::StartThreadOptions;
+pub use codex_core::StateDbHandle;
+pub use codex_core::SteerSubmission;
+pub use codex_core::SuspendTurnOutcome;
+pub use codex_core::ThreadManager;
+pub use codex_core::ThreadShutdownReport;
+pub use codex_core::TurnInput;
+pub use codex_core::TurnInputRequest;
+pub use codex_core::TurnInputSubmission;
+pub use codex_core::TurnStartOptions;
+pub use codex_core::WaitForEnvironmentToolConfig;
+pub use codex_core::build_models_manager;
+pub use codex_core::config::Config;
+pub use codex_core::config::Constrained;
+pub use codex_core::config::ExtraConfig;
+pub use codex_core::config::GhostSnapshotConfig;
+pub use codex_core::config::MultiAgentV2Config;
+pub use codex_core::config::NetworkProxySpec;
+pub use codex_core::config::Permissions;
+pub use codex_core::config::TerminalResizeReflowConfig;
+pub use codex_core::config::ThreadStoreConfig;
+pub use codex_core::config::find_codex_home;
+pub use codex_core::init_state_db;
+pub use codex_core::local_agent_graph_store_from_state_db;
+pub use codex_core::passthrough_image_store;
+pub use codex_core::resolve_installation_id;
+pub use codex_core::thread_store_from_config;
+pub use codex_exec_server::EnvironmentManager;
+pub use codex_exec_server::EnvironmentRegistryConnectRequest;
+pub use codex_exec_server::EnvironmentRegistryConnectResponse;
+pub use codex_exec_server::EnvironmentRegistryHarnessKeyValidationRequest;
+pub use codex_exec_server::EnvironmentRegistryHarnessKeyValidationResponse;
+pub use codex_exec_server::EnvironmentRegistryRegistrationRequest;
+pub use codex_exec_server::EnvironmentRegistryRegistrationResponse;
+pub use codex_exec_server::ExecServerError;
+pub use codex_exec_server::ExecServerRuntimePaths;
+pub use codex_exec_server::NoiseChannelIdentity;
+pub use codex_exec_server::NoiseChannelPublicKey;
+pub use codex_exec_server::NoiseRendezvousConnectBundle;
+pub use codex_exec_server::NoiseRendezvousConnectProvider;
+pub use codex_extension_api::ExtensionRegistryBuilder;
+pub use codex_extension_api::Instructions;
+pub use codex_extension_api::LoadInstructionsFuture;
+pub use codex_extension_api::LoadedUserInstructions;
+pub use codex_extension_api::ThreadInstructionsProvider;
+pub use codex_extension_api::UserInstructionsProvider;
+pub use codex_extension_api::empty_extension_registry;
+pub use codex_features::Feature;
+pub use codex_features::Features;
+pub use codex_history::InitialHistory;
+pub use codex_home::CodexHomeUserInstructionsProvider;
+pub use codex_image_generation_extension::install as install_image_generation_extension;
+pub use codex_login::AuthHeaders;
+pub use codex_login::AuthManager;
+pub use codex_login::CodexAuth;
+pub use codex_login::ExternalAuth;
+pub use codex_login::ExternalAuthFuture;
+pub use codex_login::ExternalAuthRefreshContext;
+pub use codex_login::ExternalAuthRefreshReason;
+pub use codex_login::default_client::set_default_originator;
+pub use codex_model_provider_info::OPENAI_PROVIDER_ID;
+pub use codex_model_provider_info::built_in_model_providers;
+pub use codex_models_manager::manager::RefreshStrategy;
+pub use codex_models_manager::manager::SharedModelsManager;
+pub use codex_protocol::ThreadId;
+pub use codex_protocol::capabilities::CapabilityRootLocation;
+pub use codex_protocol::capabilities::SelectedCapabilityRoot;
+pub use codex_protocol::config_types::AltScreenMode;
+pub use codex_protocol::config_types::ApprovalsReviewer;
+pub use codex_protocol::config_types::AutoCompactTokenLimitScope;
+pub use codex_protocol::config_types::CollaborationModeMask;
+pub use codex_protocol::config_types::ShellEnvironmentPolicy;
+pub use codex_protocol::config_types::WebSearchMode;
+pub use codex_protocol::dynamic_tools::DynamicToolFunctionSpec;
+pub use codex_protocol::dynamic_tools::DynamicToolNamespaceSpec;
+pub use codex_protocol::dynamic_tools::DynamicToolNamespaceTool;
+pub use codex_protocol::dynamic_tools::DynamicToolSpec;
+pub use codex_protocol::error::Result as CodexResult;
+pub use codex_protocol::models::PermissionProfile;
+pub use codex_protocol::models::PermissionProfileSnapshot;
+pub use codex_protocol::openai_models::ModelPreset;
+pub use codex_protocol::protocol::AskForApproval;
+pub use codex_protocol::protocol::EnvironmentConfigState;
+pub use codex_protocol::protocol::EventMsg;
+pub use codex_protocol::protocol::Op;
+pub use codex_protocol::protocol::SessionConfiguredEvent;
+pub use codex_protocol::protocol::SessionSource;
+pub use codex_protocol::protocol::TurnEnvironmentSelection;
+pub use codex_protocol::protocol::W3cTraceContext;
+pub use codex_protocol::user_input::UserInput;
+pub use codex_state::SqliteConfig;
+pub use codex_utils_absolute_path::AbsolutePathBuf;
diff --git a/codex-rs/diagnostics/src/lib.rs b/codex-rs/diagnostics/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a966e4aee546e586d141ee5b7f70bc82d377911f
--- /dev/null
+++ b/codex-rs/diagnostics/src/lib.rs
@@ -0,0 +1,210 @@
+use std::sync::Mutex;
+use std::sync::Once;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+
+static GAUGES: Mutex<Vec<&'static Gauge>> = Mutex::new(Vec::new());
+
+/// A process-wide gauge that registers itself the first time it is used.
+pub struct Gauge {
+    name: &'static str,
+    value: AtomicU64,
+    registered: Once,
+}
+
+impl Gauge {
+    /// Creates a gauge suitable for use in a `static` declaration.
+    pub const fn new(name: &'static str) -> Self {
+        Self {
+            name,
+            value: AtomicU64::new(0),
+            registered: Once::new(),
+        }
+    }
+
+    /// Increments the gauge and registers it if needed.
+    pub fn increment(&'static self) {
+        self.register();
+        self.value.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Decrements the gauge without allowing an underflow.
+    pub fn decrement(&self) {
+        let _ = self
+            .value
+            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
+                Some(value.saturating_sub(1))
+            });
+    }
+
+    /// Increments the gauge for the lifetime of the returned guard.
+    pub fn track(&'static self) -> GaugeGuard {
+        self.increment();
+        GaugeGuard { gauge: self }
+    }
+
+    fn register(&'static self) {
+        self.registered.call_once(|| {
+            GAUGES
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .push(self);
+        });
+    }
+}
+
+/// Decrements its gauge when the measured object is dropped.
+pub struct GaugeGuard {
+    gauge: &'static Gauge,
+}
+
+impl Drop for GaugeGuard {
+    fn drop(&mut self) {
+        self.gauge.decrement();
+    }
+}
+
+/// The current value of one registered diagnostic gauge.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct GaugeSnapshot {
+    pub name: &'static str,
+    pub value: u64,
+}
+
+/// Best-effort operating-system measurements for the current process.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ProcessSnapshot {
+    pub id: u32,
+    pub resident_memory_bytes: Option<u64>,
+    pub physical_footprint_bytes: Option<u64>,
+}
+
+/// Content-free diagnostic values contributed by this process.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct DiagnosticsSnapshot {
+    pub process: ProcessSnapshot,
+    pub gauges: Vec<GaugeSnapshot>,
+}
+
+/// Collects built-in process measurements and every registered gauge.
+pub fn snapshot() -> DiagnosticsSnapshot {
+    let mut gauges = GAUGES
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner)
+        .iter()
+        .map(|gauge| GaugeSnapshot {
+            name: gauge.name,
+            value: gauge.value.load(Ordering::Relaxed),
+        })
+        .collect::<Vec<_>>();
+    gauges.sort_unstable_by_key(|gauge| gauge.name);
+
+    DiagnosticsSnapshot {
+        process: process_snapshot(),
+        gauges,
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn process_snapshot() -> ProcessSnapshot {
+    let usage = unsafe {
+        let mut usage = std::mem::MaybeUninit::<libc::rusage_info_v0>::zeroed();
+        // SAFETY: the kernel initializes this correctly sized buffer on success.
+        if libc::proc_pid_rusage(
+            libc::getpid(),
+            libc::RUSAGE_INFO_V0,
+            usage.as_mut_ptr().cast(),
+        ) != 0
+        {
+            return empty_process_snapshot();
+        }
+        usage.assume_init()
+    };
+
+    ProcessSnapshot {
+        id: std::process::id(),
+        resident_memory_bytes: Some(usage.ri_resident_size),
+        physical_footprint_bytes: Some(usage.ri_phys_footprint),
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn process_snapshot() -> ProcessSnapshot {
+    // SAFETY: querying the system page size does not access caller-owned memory.
+    let page_size = u64::try_from(unsafe { libc::sysconf(libc::_SC_PAGESIZE) })
+        .ok()
+        .filter(|page_size| *page_size > 0);
+    let resident_pages = std::fs::read_to_string("/proc/self/statm")
+        .ok()
+        .and_then(|statm| statm.split_whitespace().nth(1)?.parse::<u64>().ok());
+
+    ProcessSnapshot {
+        id: std::process::id(),
+        resident_memory_bytes: resident_pages
+            .zip(page_size)
+            .map(|(pages, page_size)| pages.saturating_mul(page_size)),
+        physical_footprint_bytes: None,
+    }
+}
+
+#[cfg(target_os = "windows")]
+fn process_snapshot() -> ProcessSnapshot {
+    #[repr(C)]
+    struct ProcessMemoryCounters {
+        size: u32,
+        page_fault_count: u32,
+        peak_working_set_size: usize,
+        working_set_size: usize,
+        quota_peak_paged_pool_usage: usize,
+        quota_paged_pool_usage: usize,
+        quota_peak_non_paged_pool_usage: usize,
+        quota_non_paged_pool_usage: usize,
+        pagefile_usage: usize,
+        peak_pagefile_usage: usize,
+    }
+
+    #[link(name = "kernel32")]
+    unsafe extern "system" {
+        fn GetCurrentProcess() -> *mut std::ffi::c_void;
+        fn K32GetProcessMemoryInfo(
+            process: *mut std::ffi::c_void,
+            counters: *mut ProcessMemoryCounters,
+            size: u32,
+        ) -> i32;
+    }
+
+    let counters = unsafe {
+        let mut counters = std::mem::MaybeUninit::<ProcessMemoryCounters>::zeroed();
+        let size = u32::try_from(std::mem::size_of::<ProcessMemoryCounters>()).unwrap_or(u32::MAX);
+        // SAFETY: the pseudo-handle is valid and the kernel initializes this
+        // correctly sized writable buffer on success.
+        if K32GetProcessMemoryInfo(GetCurrentProcess(), counters.as_mut_ptr(), size) == 0 {
+            return empty_process_snapshot();
+        }
+        counters.assume_init()
+    };
+
+    ProcessSnapshot {
+        id: std::process::id(),
+        resident_memory_bytes: u64::try_from(counters.working_set_size).ok(),
+        physical_footprint_bytes: None,
+    }
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
+fn process_snapshot() -> ProcessSnapshot {
+    empty_process_snapshot()
+}
+
+#[cfg(not(target_os = "linux"))]
+fn empty_process_snapshot() -> ProcessSnapshot {
+    ProcessSnapshot {
+        id: std::process::id(),
+        resident_memory_bytes: None,
+        physical_footprint_bytes: None,
+    }
+}
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;
diff --git a/codex-rs/diagnostics/src/tests.rs b/codex-rs/diagnostics/src/tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d5ac2f2a5acbabe1b5e65e8bf6e29f57e5e10c50
--- /dev/null
+++ b/codex-rs/diagnostics/src/tests.rs
@@ -0,0 +1,58 @@
+use super::Gauge;
+use super::snapshot;
+use pretty_assertions::assert_eq;
+
+static GUARD_GAUGE: Gauge = Gauge::new("diagnostics.tests.guard");
+static REGISTERED_GAUGE: Gauge = Gauge::new("diagnostics.tests.registered");
+
+#[test]
+fn gauge_guards_follow_the_measured_lifetime() {
+    let first = GUARD_GAUGE.track();
+    let second = GUARD_GAUGE.track();
+    let value = || {
+        snapshot()
+            .gauges
+            .into_iter()
+            .find(|gauge| gauge.name == "diagnostics.tests.guard")
+            .expect("used gauge should be registered")
+            .value
+    };
+
+    assert_eq!(value(), 2);
+    drop(first);
+    assert_eq!(value(), 1);
+    drop(second);
+    assert_eq!(value(), 0);
+}
+
+#[test]
+fn snapshot_includes_process_memory_and_registers_gauges_once() {
+    REGISTERED_GAUGE.increment();
+    REGISTERED_GAUGE.increment();
+    let diagnostics = snapshot();
+    let registered = diagnostics
+        .gauges
+        .iter()
+        .filter(|gauge| gauge.name == "diagnostics.tests.registered")
+        .collect::<Vec<_>>();
+
+    assert_eq!(diagnostics.process.id, std::process::id());
+    assert_eq!(registered.len(), 1);
+    assert_eq!(registered[0].value, 2);
+    #[cfg(any(target_os = "macos", target_os = "linux", target_os = "windows"))]
+    assert!(
+        diagnostics
+            .process
+            .resident_memory_bytes
+            .is_some_and(|bytes| bytes > 0)
+    );
+    #[cfg(target_os = "macos")]
+    assert!(
+        diagnostics
+            .process
+            .physical_footprint_bytes
+            .is_some_and(|bytes| bytes > 0)
+    );
+    #[cfg(not(target_os = "macos"))]
+    assert_eq!(diagnostics.process.physical_footprint_bytes, None);
+}
diff --git a/codex-rs/exec/src/cli.rs b/codex-rs/exec/src/cli.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0ef0be6af9cc177e86da68e9fa20df05f9ac813c
--- /dev/null
+++ b/codex-rs/exec/src/cli.rs
@@ -0,0 +1,319 @@
+use clap::Args;
+use clap::FromArgMatches;
+use clap::Parser;
+use clap::ValueEnum;
+use codex_protocol::protocol::ThreadSource;
+use codex_utils_cli::CliConfigOverrides;
+use codex_utils_cli::SharedCliOptions;
+use std::path::PathBuf;
+
+#[derive(Parser, Debug)]
+#[command(
+    version,
+    override_usage = "codex exec [OPTIONS] [PROMPT]\n       codex exec [OPTIONS] <COMMAND> [ARGS]"
+)]
+pub struct Cli {
+    /// Action to perform. If omitted, runs a new non-interactive session.
+    #[command(subcommand)]
+    pub command: Option<Command>,
+
+    /// Error out when config.toml contains fields that are not recognized by this version of Codex.
+    #[arg(long = "strict-config", global = true, default_value_t = false)]
+    pub strict_config: bool,
+
+    #[clap(flatten)]
+    pub shared: ExecSharedCliOptions,
+
+    /// Source classification for newly created or forked threads.
+    #[arg(long = "thread-source", value_name = "SOURCE", global = true)]
+    pub thread_source: Option<ThreadSource>,
+
+    /// Allow running Codex outside a Git repository.
+    #[arg(long = "skip-git-repo-check", global = true, default_value_t = false)]
+    pub skip_git_repo_check: bool,
+
+    /// Run without persisting session files to disk.
+    #[arg(long = "ephemeral", global = true, default_value_t = false)]
+    pub ephemeral: bool,
+
+    /// Do not load `$CODEX_HOME/config.toml`; auth still uses `CODEX_HOME`.
+    #[arg(long = "ignore-user-config", global = true, default_value_t = false)]
+    pub ignore_user_config: bool,
+
+    /// Do not load user or project execpolicy `.rules` files.
+    #[arg(long = "ignore-rules", global = true, default_value_t = false)]
+    pub ignore_rules: bool,
+
+    /// Path to a JSON Schema file describing the model's final response shape.
+    #[arg(long = "output-schema", value_name = "FILE", global = true)]
+    pub output_schema: Option<PathBuf>,
+
+    #[clap(skip)]
+    pub config_overrides: CliConfigOverrides,
+
+    /// Specifies color settings for use in the output.
+    #[arg(long = "color", value_enum, default_value_t = Color::Auto)]
+    pub color: Color,
+
+    /// Print events to stdout as JSONL.
+    #[arg(
+        long = "json",
+        alias = "experimental-json",
+        default_value_t = false,
+        global = true
+    )]
+    pub json: bool,
+
+    /// Specifies file where the last message from the agent should be written.
+    #[arg(
+        long = "output-last-message",
+        short = 'o',
+        value_name = "FILE",
+        global = true
+    )]
+    pub last_message_file: Option<PathBuf>,
+
+    /// Initial instructions for the agent. If not provided as an argument (or
+    /// if `-` is used), instructions are read from stdin. If stdin is piped and
+    /// a prompt is also provided, stdin is appended as a `<stdin>` block.
+    #[arg(value_name = "PROMPT", value_hint = clap::ValueHint::Other)]
+    pub prompt: Option<String>,
+}
+
+impl std::ops::Deref for Cli {
+    type Target = SharedCliOptions;
+
+    fn deref(&self) -> &Self::Target {
+        &self.shared.0
+    }
+}
+
+impl std::ops::DerefMut for Cli {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.shared.0
+    }
+}
+
+#[derive(Debug, Default)]
+pub struct ExecSharedCliOptions(SharedCliOptions);
+
+impl ExecSharedCliOptions {
+    pub fn into_inner(self) -> SharedCliOptions {
+        self.0
+    }
+}
+
+impl std::ops::Deref for ExecSharedCliOptions {
+    type Target = SharedCliOptions;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl std::ops::DerefMut for ExecSharedCliOptions {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}
+
+impl Args for ExecSharedCliOptions {
+    fn augment_args(cmd: clap::Command) -> clap::Command {
+        mark_exec_global_args(SharedCliOptions::augment_args(cmd))
+    }
+
+    fn augment_args_for_update(cmd: clap::Command) -> clap::Command {
+        mark_exec_global_args(SharedCliOptions::augment_args_for_update(cmd))
+    }
+}
+
+impl FromArgMatches for ExecSharedCliOptions {
+    fn from_arg_matches(matches: &clap::ArgMatches) -> Result<Self, clap::Error> {
+        SharedCliOptions::from_arg_matches(matches).map(Self)
+    }
+
+    fn update_from_arg_matches(&mut self, matches: &clap::ArgMatches) -> Result<(), clap::Error> {
+        self.0.update_from_arg_matches(matches)
+    }
+}
+
+fn mark_exec_global_args(cmd: clap::Command) -> clap::Command {
+    cmd.mut_arg("model", |arg| arg.global(true))
+        .mut_arg("dangerously_bypass_approvals_and_sandbox", |arg| {
+            arg.global(true)
+        })
+        .mut_arg("bypass_hook_trust", |arg| arg.global(true))
+        .mut_arg("worktree", |arg| arg.global(true))
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub enum Command {
+    /// Resume a previous session by id or pick the most recent with --last.
+    Resume(ResumeArgs),
+
+    /// Fork a previous session by id into a new session.
+    Fork(ForkArgs),
+
+    /// Run a code review against the current repository.
+    Review(ReviewArgs),
+}
+
+#[derive(Args, Debug)]
+pub struct ForkArgs {
+    /// Conversation/session id (UUID) or thread name to fork.
+    #[arg(value_name = "SESSION_ID")]
+    pub session_id: String,
+
+    /// Optional image(s) to attach to the prompt sent after forking.
+    #[arg(
+        long = "image",
+        short = 'i',
+        value_name = "FILE",
+        value_delimiter = ',',
+        num_args = 1
+    )]
+    pub images: Vec<PathBuf>,
+
+    /// Optional prompt to send after forking. If `-` is used, read from stdin.
+    #[arg(value_name = "PROMPT", value_hint = clap::ValueHint::Other)]
+    pub prompt: Option<String>,
+}
+
+#[derive(Args, Debug)]
+struct ResumeArgsRaw {
+    // Note: This is the direct clap shape. We reinterpret the positional when --last is set
+    // so "codex resume --last <prompt>" treats the positional as a prompt, not a session id.
+    /// Conversation/session id (UUID) or thread name. UUIDs take precedence if it parses.
+    /// If omitted, use --last to pick the most recent recorded session.
+    #[arg(value_name = "SESSION_ID")]
+    session_id: Option<String>,
+
+    /// Resume the most recent recorded session (newest) without specifying an id.
+    #[arg(long = "last", default_value_t = false)]
+    last: bool,
+
+    /// Show all sessions (disables cwd filtering).
+    #[arg(long = "all", default_value_t = false)]
+    all: bool,
+
+    /// Optional image(s) to attach to the prompt sent after resuming.
+    #[arg(
+        long = "image",
+        short = 'i',
+        value_name = "FILE",
+        value_delimiter = ',',
+        num_args = 1
+    )]
+    images: Vec<PathBuf>,
+
+    /// Prompt to send after resuming the session. If `-` is used, read from stdin.
+    #[arg(value_name = "PROMPT", value_hint = clap::ValueHint::Other)]
+    prompt: Option<String>,
+}
+
+#[derive(Debug)]
+pub struct ResumeArgs {
+    /// Conversation/session id (UUID) or thread name. UUIDs take precedence if it parses.
+    /// If omitted, use --last to pick the most recent recorded session.
+    pub session_id: Option<String>,
+
+    /// Resume the most recent recorded session (newest) without specifying an id.
+    pub last: bool,
+
+    /// Show all sessions (disables cwd filtering).
+    pub all: bool,
+
+    /// Optional image(s) to attach to the prompt sent after resuming.
+    pub images: Vec<PathBuf>,
+
+    /// Prompt to send after resuming the session. If `-` is used, read from stdin.
+    pub prompt: Option<String>,
+}
+
+impl From<ResumeArgsRaw> for ResumeArgs {
+    fn from(raw: ResumeArgsRaw) -> Self {
+        // When --last is used without an explicit prompt, treat the positional as the prompt
+        // (clap can’t express this conditional positional meaning cleanly).
+        let (session_id, prompt) = if raw.last && raw.prompt.is_none() {
+            (None, raw.session_id)
+        } else {
+            (raw.session_id, raw.prompt)
+        };
+        Self {
+            session_id,
+            last: raw.last,
+            all: raw.all,
+            images: raw.images,
+            prompt,
+        }
+    }
+}
+
+impl Args for ResumeArgs {
+    fn augment_args(cmd: clap::Command) -> clap::Command {
+        ResumeArgsRaw::augment_args(cmd)
+    }
+
+    fn augment_args_for_update(cmd: clap::Command) -> clap::Command {
+        ResumeArgsRaw::augment_args_for_update(cmd)
+    }
+}
+
+impl FromArgMatches for ResumeArgs {
+    fn from_arg_matches(matches: &clap::ArgMatches) -> Result<Self, clap::Error> {
+        ResumeArgsRaw::from_arg_matches(matches).map(Self::from)
+    }
+
+    fn update_from_arg_matches(&mut self, matches: &clap::ArgMatches) -> Result<(), clap::Error> {
+        *self = ResumeArgsRaw::from_arg_matches(matches).map(Self::from)?;
+        Ok(())
+    }
+}
+
+#[derive(Args, Debug)]
+pub struct ReviewArgs {
+    /// Review staged, unstaged, and untracked changes.
+    #[arg(
+        long = "uncommitted",
+        default_value_t = false,
+        conflicts_with_all = ["base", "commit", "prompt"]
+    )]
+    pub uncommitted: bool,
+
+    /// Review changes against the given base branch.
+    #[arg(
+        long = "base",
+        value_name = "BRANCH",
+        conflicts_with_all = ["uncommitted", "commit", "prompt"]
+    )]
+    pub base: Option<String>,
+
+    /// Review the changes introduced by a commit.
+    #[arg(
+        long = "commit",
+        value_name = "SHA",
+        conflicts_with_all = ["uncommitted", "base", "prompt"]
+    )]
+    pub commit: Option<String>,
+
+    /// Optional commit title to display in the review summary.
+    #[arg(long = "title", value_name = "TITLE", requires = "commit")]
+    pub commit_title: Option<String>,
+
+    /// Custom review instructions. If `-` is used, read from stdin.
+    #[arg(value_name = "PROMPT", value_hint = clap::ValueHint::Other)]
+    pub prompt: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, ValueEnum)]
+#[value(rename_all = "kebab-case")]
+pub enum Color {
+    Always,
+    Never,
+    #[default]
+    Auto,
+}
+
+#[cfg(test)]
+#[path = "cli_tests.rs"]
+mod tests;
diff --git a/codex-rs/exec/src/cli_tests.rs b/codex-rs/exec/src/cli_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..423935904acf25d95a348ef26334d161089b492f
--- /dev/null
+++ b/codex-rs/exec/src/cli_tests.rs
@@ -0,0 +1,147 @@
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn resume_parses_prompt_after_global_flags() {
+    const PROMPT: &str = "echo resume-with-global-flags-after-subcommand";
+    let cli = Cli::parse_from([
+        "codex-exec",
+        "resume",
+        "--last",
+        "--json",
+        "--model",
+        "gpt-5.2-codex",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--skip-git-repo-check",
+        "--ephemeral",
+        "--ignore-user-config",
+        "--ignore-rules",
+        PROMPT,
+    ]);
+
+    assert!(cli.ephemeral);
+    assert!(cli.ignore_user_config);
+    assert!(cli.ignore_rules);
+    let Some(Command::Resume(args)) = cli.command else {
+        panic!("expected resume command");
+    };
+    let effective_prompt = args.prompt.clone().or_else(|| {
+        if args.last {
+            args.session_id.clone()
+        } else {
+            None
+        }
+    });
+    assert_eq!(effective_prompt.as_deref(), Some(PROMPT));
+}
+
+#[test]
+fn resume_accepts_output_flags_after_subcommand() {
+    const PROMPT: &str = "echo resume-with-output-file";
+    let cli = Cli::parse_from([
+        "codex-exec",
+        "resume",
+        "session-123",
+        "-o",
+        "/tmp/resume-output.md",
+        "--output-schema",
+        "/tmp/schema.json",
+        PROMPT,
+    ]);
+
+    assert_eq!(
+        cli.last_message_file,
+        Some(PathBuf::from("/tmp/resume-output.md"))
+    );
+    assert_eq!(cli.output_schema, Some(PathBuf::from("/tmp/schema.json")));
+    let Some(Command::Resume(args)) = cli.command else {
+        panic!("expected resume command");
+    };
+    assert_eq!(args.session_id.as_deref(), Some("session-123"));
+    assert_eq!(args.prompt.as_deref(), Some(PROMPT));
+}
+
+#[test]
+fn fork_parses_prompt_after_global_flags() {
+    const PROMPT: &str = "continue on the fork";
+    let cli = Cli::parse_from([
+        "codex-exec",
+        "fork",
+        "session-123",
+        "--json",
+        "--model",
+        "gpt-5.2-codex",
+        "--thread-source",
+        "automated_review",
+        "--skip-git-repo-check",
+        "--ephemeral",
+        PROMPT,
+    ]);
+
+    assert!(cli.json);
+    assert!(cli.ephemeral);
+    assert_eq!(
+        cli.thread_source,
+        Some(ThreadSource::Feature("automated_review".to_string()))
+    );
+    let Some(Command::Fork(args)) = cli.command else {
+        panic!("expected fork command");
+    };
+    assert_eq!(args.session_id, "session-123");
+    assert_eq!(args.prompt.as_deref(), Some(PROMPT));
+}
+
+#[test]
+fn parses_config_isolation_flags() {
+    let cli = Cli::parse_from([
+        "codex-exec",
+        "--ignore-user-config",
+        "--ignore-rules",
+        "summarize",
+    ]);
+
+    assert!(cli.ignore_user_config);
+    assert!(cli.ignore_rules);
+}
+
+#[test]
+fn approve_for_me_flag_applies_to_resume_when_passed_at_exec_root() {
+    for flag in ["--approve-for-me", "--not-so-yolo"] {
+        let cli = Cli::parse_from(["codex-exec", flag, "resume", "--last"]);
+
+        assert!(cli.auto_review);
+    }
+}
+
+#[test]
+fn approve_for_me_flag_conflicts_with_other_sandbox_modes() {
+    for conflicting_args in [
+        vec!["--sandbox", "read-only"],
+        vec!["--dangerously-bypass-approvals-and-sandbox"],
+    ] {
+        let mut args = vec!["codex-exec", "--approve-for-me"];
+        args.extend(conflicting_args);
+        args.push("summarize");
+
+        let error = Cli::try_parse_from(args).expect_err("flags should conflict");
+        assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict);
+    }
+}
+
+#[test]
+fn worktree_flag_is_accepted_after_fork_subcommand() {
+    let cli = Cli::try_parse_from(["codex-exec", "fork", "session-id", "--worktree"])
+        .expect("worktree should be a global exec argument");
+
+    assert!(cli.worktree);
+    assert!(matches!(cli.command, Some(Command::Fork(_))));
+}
+
+#[test]
+fn worktree_flag_is_accepted_before_fork_subcommand() {
+    let cli = Cli::try_parse_from(["codex-exec", "--worktree", "fork", "session-id"])
+        .expect("worktree should be accepted before the fork subcommand");
+
+    assert!(cli.worktree);
+    assert!(matches!(cli.command, Some(Command::Fork(_))));
+}
diff --git a/codex-rs/exec/src/event_processor.rs b/codex-rs/exec/src/event_processor.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4d1da09001261651a550e36cf2ceaf1d6235c83c
--- /dev/null
+++ b/codex-rs/exec/src/event_processor.rs
@@ -0,0 +1,48 @@
+use std::path::Path;
+
+use codex_app_server_protocol::ServerNotification;
+use codex_core::config::Config;
+use codex_protocol::protocol::SessionConfiguredEvent;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CodexStatus {
+    Running,
+    InitiateShutdown,
+}
+
+pub(crate) trait EventProcessor {
+    /// Print summary of effective configuration and user prompt.
+    fn print_config_summary(
+        &mut self,
+        config: &Config,
+        prompt: &str,
+        session_configured: &SessionConfiguredEvent,
+    );
+
+    /// Handle a single typed app-server notification emitted by the agent.
+    fn process_server_notification(&mut self, notification: ServerNotification) -> CodexStatus;
+
+    /// Handle a local exec warning that is not represented as an app-server notification.
+    fn process_warning(&mut self, message: String) -> CodexStatus;
+
+    fn print_final_output(&mut self) {}
+}
+
+pub(crate) fn handle_last_message(last_agent_message: Option<&str>, output_file: &Path) {
+    let message = last_agent_message.unwrap_or_default();
+    write_last_message_file(message, Some(output_file));
+    if last_agent_message.is_none() {
+        eprintln!(
+            "Warning: no last agent message; wrote empty content to {}",
+            output_file.display()
+        );
+    }
+}
+
+fn write_last_message_file(contents: &str, last_message_path: Option<&Path>) {
+    if let Some(path) = last_message_path
+        && let Err(e) = std::fs::write(path, contents)
+    {
+        eprintln!("Failed to write last message file {path:?}: {e}");
+    }
+}
diff --git a/codex-rs/exec/src/event_processor_with_human_output.rs b/codex-rs/exec/src/event_processor_with_human_output.rs
new file mode 100644
index 0000000000000000000000000000000000000000..222bc485ab425ea4ad0bad8107cc5e2303bd20d9
--- /dev/null
+++ b/codex-rs/exec/src/event_processor_with_human_output.rs
@@ -0,0 +1,535 @@
+use std::io::IsTerminal;
+use std::path::PathBuf;
+
+use codex_app_server_protocol::CommandExecutionStatus;
+use codex_app_server_protocol::McpToolCallStatus;
+use codex_app_server_protocol::PatchApplyStatus;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::ThreadTokenUsage;
+use codex_app_server_protocol::TurnStatus;
+use codex_core::config::Config;
+use codex_model_provider_info::WireApi;
+use codex_protocol::num_format::format_with_separators;
+use codex_protocol::protocol::SessionConfiguredEvent;
+use codex_utils_path_uri::PathUri;
+use codex_utils_sandbox_summary::summarize_permission_profile;
+use owo_colors::OwoColorize;
+use owo_colors::Style;
+
+use crate::event_processor::CodexStatus;
+use crate::event_processor::EventProcessor;
+use crate::event_processor::handle_last_message;
+
+pub(crate) struct EventProcessorWithHumanOutput {
+    bold: Style,
+    cyan: Style,
+    dimmed: Style,
+    green: Style,
+    italic: Style,
+    magenta: Style,
+    red: Style,
+    yellow: Style,
+    show_agent_reasoning: bool,
+    show_raw_agent_reasoning: bool,
+    last_message_path: Option<PathBuf>,
+    final_message: Option<String>,
+    final_message_rendered: bool,
+    emit_final_message_on_shutdown: bool,
+    last_total_token_usage: Option<ThreadTokenUsage>,
+}
+
+impl EventProcessorWithHumanOutput {
+    pub(crate) fn create_with_ansi(
+        with_ansi: bool,
+        config: &Config,
+        last_message_path: Option<PathBuf>,
+    ) -> Self {
+        let style = |styled: Style, plain: Style| if with_ansi { styled } else { plain };
+        Self {
+            bold: style(Style::new().bold(), Style::new()),
+            cyan: style(Style::new().cyan(), Style::new()),
+            dimmed: style(Style::new().dimmed(), Style::new()),
+            green: style(Style::new().green(), Style::new()),
+            italic: style(Style::new().italic(), Style::new()),
+            magenta: style(Style::new().magenta(), Style::new()),
+            red: style(Style::new().red(), Style::new()),
+            yellow: style(Style::new().yellow(), Style::new()),
+            show_agent_reasoning: !config.hide_agent_reasoning,
+            show_raw_agent_reasoning: config.show_raw_agent_reasoning,
+            last_message_path,
+            final_message: None,
+            final_message_rendered: false,
+            emit_final_message_on_shutdown: false,
+            last_total_token_usage: None,
+        }
+    }
+
+    fn render_item_started(&self, item: &ThreadItem) {
+        match item {
+            ThreadItem::CommandExecution { command, cwd, .. } => {
+                eprintln!(
+                    "{}\n{} in {cwd}",
+                    "exec".style(self.italic).style(self.magenta),
+                    command.style(self.bold),
+                );
+            }
+            ThreadItem::McpToolCall { server, tool, .. } => {
+                eprintln!(
+                    "{} {} {}",
+                    "mcp:".style(self.bold),
+                    format!("{server}/{tool}").style(self.cyan),
+                    "started".style(self.dimmed)
+                );
+            }
+            ThreadItem::WebSearch(item) => {
+                eprintln!("{} {}", "web search:".style(self.bold), item.query);
+            }
+            ThreadItem::FileChange { .. } => {
+                eprintln!("{}", "apply patch".style(self.bold));
+            }
+            ThreadItem::CollabAgentToolCall { tool, .. } => {
+                eprintln!("{} {:?}", "collab:".style(self.bold), tool);
+            }
+            _ => {}
+        }
+    }
+
+    fn render_item_completed(&mut self, item: ThreadItem) {
+        match item {
+            ThreadItem::AgentMessage { text, .. } => {
+                eprintln!(
+                    "{}\n{}",
+                    "codex".style(self.italic).style(self.magenta),
+                    text
+                );
+                self.final_message = Some(text);
+                self.final_message_rendered = true;
+            }
+            ThreadItem::Reasoning {
+                summary, content, ..
+            } => {
+                if self.show_agent_reasoning
+                    && let Some(text) =
+                        reasoning_text(&summary, &content, self.show_raw_agent_reasoning)
+                    && !text.trim().is_empty()
+                {
+                    eprintln!("{}", text.style(self.dimmed));
+                }
+            }
+            ThreadItem::CommandExecution {
+                command: _,
+                aggregated_output,
+                exit_code,
+                status,
+                duration_ms,
+                ..
+            } => {
+                let duration_suffix = duration_ms
+                    .map(|duration_ms| format!(" in {duration_ms}ms"))
+                    .unwrap_or_default();
+                match status {
+                    CommandExecutionStatus::Completed => {
+                        eprintln!(
+                            "{}",
+                            format!(" succeeded{duration_suffix}:").style(self.green)
+                        );
+                    }
+                    CommandExecutionStatus::Failed => {
+                        let exit_code = exit_code.unwrap_or(1);
+                        eprintln!(
+                            "{}",
+                            format!(" exited {exit_code}{duration_suffix}:").style(self.red)
+                        );
+                    }
+                    CommandExecutionStatus::Declined => {
+                        eprintln!(
+                            "{}",
+                            format!(" declined{duration_suffix}:").style(self.yellow)
+                        );
+                    }
+                    CommandExecutionStatus::InProgress => {
+                        eprintln!(
+                            "{}",
+                            format!(" in progress{duration_suffix}:").style(self.dimmed)
+                        );
+                    }
+                }
+                if let Some(output) = aggregated_output
+                    && !output.trim().is_empty()
+                {
+                    eprintln!("{output}");
+                }
+            }
+            ThreadItem::FileChange {
+                changes, status, ..
+            } => {
+                let status_text = match status {
+                    PatchApplyStatus::Completed => "completed",
+                    PatchApplyStatus::Failed => "failed",
+                    PatchApplyStatus::Declined => "declined",
+                    PatchApplyStatus::InProgress => "in_progress",
+                };
+                eprintln!("{} {}", "patch:".style(self.bold), status_text);
+                for change in changes {
+                    eprintln!("{}", change.path.style(self.dimmed));
+                }
+            }
+            ThreadItem::McpToolCall {
+                server,
+                tool,
+                status,
+                error,
+                ..
+            } => {
+                let status_text = match status {
+                    McpToolCallStatus::Completed => "completed".style(self.green),
+                    McpToolCallStatus::Failed => "failed".style(self.red),
+                    McpToolCallStatus::InProgress => "in_progress".style(self.dimmed),
+                };
+                eprintln!(
+                    "{} {} {}",
+                    "mcp:".style(self.bold),
+                    format!("{server}/{tool}").style(self.cyan),
+                    format!("({status_text})").style(self.dimmed)
+                );
+                if let Some(error) = error {
+                    eprintln!("{}", error.message.style(self.red));
+                }
+            }
+            ThreadItem::WebSearch(item) => {
+                eprintln!("{} {}", "web search:".style(self.bold), item.query);
+            }
+            ThreadItem::ContextCompaction { .. } => {
+                eprintln!("{}", "context compacted".style(self.dimmed));
+            }
+            _ => {}
+        }
+    }
+}
+
+impl EventProcessor for EventProcessorWithHumanOutput {
+    fn print_config_summary(
+        &mut self,
+        config: &Config,
+        prompt: &str,
+        session_configured_event: &SessionConfiguredEvent,
+    ) {
+        const VERSION: &str = env!("CARGO_PKG_VERSION");
+        eprintln!("OpenAI Codex v{VERSION}\n--------");
+        for (key, value) in config_summary_entries(config, session_configured_event) {
+            eprintln!("{} {}", format!("{key}:").style(self.bold), value);
+        }
+        eprintln!("--------");
+        eprintln!("{}\n{}", "user".style(self.cyan), prompt);
+    }
+
+    fn process_server_notification(&mut self, notification: ServerNotification) -> CodexStatus {
+        match notification {
+            ServerNotification::ConfigWarning(notification) => {
+                let details = notification
+                    .details
+                    .map(|details| format!(" ({details})"))
+                    .unwrap_or_default();
+                eprintln!(
+                    "{} {}{}",
+                    "warning:".style(self.yellow).style(self.bold),
+                    notification.summary,
+                    details
+                );
+                CodexStatus::Running
+            }
+            ServerNotification::Warning(notification) => self.process_warning(notification.message),
+            ServerNotification::AuthRecoveryStarted(notification) => {
+                eprintln!("{}", notification.message);
+                CodexStatus::Running
+            }
+            ServerNotification::AuthRecoveryCompleted(notification) => {
+                eprintln!("{}", notification.message.style(self.green));
+                CodexStatus::Running
+            }
+            ServerNotification::Error(notification) => {
+                eprintln!(
+                    "{} {}",
+                    "ERROR:".style(self.red).style(self.bold),
+                    notification.error
+                );
+                CodexStatus::Running
+            }
+            ServerNotification::DeprecationNotice(notification) => {
+                eprintln!(
+                    "{} {}",
+                    "deprecated:".style(self.yellow).style(self.bold),
+                    notification.summary
+                );
+                if let Some(details) = notification.details {
+                    eprintln!("{}", details.style(self.dimmed));
+                }
+                CodexStatus::Running
+            }
+            ServerNotification::HookStarted(notification) => {
+                eprintln!(
+                    "{} {}",
+                    "hook:".style(self.bold),
+                    format!("{:?}", notification.run.event_name).style(self.dimmed)
+                );
+                CodexStatus::Running
+            }
+            ServerNotification::HookCompleted(notification) => {
+                eprintln!(
+                    "{} {} {:?}",
+                    "hook:".style(self.bold),
+                    format!("{:?}", notification.run.event_name).style(self.dimmed),
+                    notification.run.status
+                );
+                CodexStatus::Running
+            }
+            ServerNotification::ItemStarted(notification) => {
+                self.render_item_started(&notification.item);
+                CodexStatus::Running
+            }
+            ServerNotification::ItemCompleted(notification) => {
+                self.render_item_completed(notification.item);
+                CodexStatus::Running
+            }
+            ServerNotification::ModelRerouted(notification) => {
+                eprintln!(
+                    "{} {} -> {}",
+                    "model rerouted:".style(self.yellow).style(self.bold),
+                    notification.from_model,
+                    notification.to_model
+                );
+                CodexStatus::Running
+            }
+            ServerNotification::ModelVerification(_) => CodexStatus::Running,
+            ServerNotification::ThreadTokenUsageUpdated(notification) => {
+                self.last_total_token_usage = Some(notification.token_usage);
+                CodexStatus::Running
+            }
+            ServerNotification::TurnCompleted(notification) => match notification.turn.status {
+                TurnStatus::Completed => {
+                    let rendered_message = self
+                        .final_message_rendered
+                        .then(|| self.final_message.clone())
+                        .flatten();
+                    if let Some(final_message) =
+                        final_message_from_turn_items(notification.turn.items.as_slice())
+                    {
+                        self.final_message_rendered =
+                            rendered_message.as_deref() == Some(final_message.as_str());
+                        self.final_message = Some(final_message);
+                    }
+                    self.emit_final_message_on_shutdown = true;
+                    CodexStatus::InitiateShutdown
+                }
+                TurnStatus::Failed => {
+                    self.final_message = None;
+                    self.final_message_rendered = false;
+                    self.emit_final_message_on_shutdown = false;
+                    if let Some(error) = notification.turn.error {
+                        eprintln!("{} {}", "ERROR:".style(self.red).style(self.bold), error);
+                    }
+                    CodexStatus::InitiateShutdown
+                }
+                TurnStatus::Interrupted => {
+                    self.final_message = None;
+                    self.final_message_rendered = false;
+                    self.emit_final_message_on_shutdown = false;
+                    eprintln!("{}", "turn interrupted".style(self.dimmed));
+                    CodexStatus::InitiateShutdown
+                }
+                TurnStatus::InProgress => CodexStatus::Running,
+            },
+            ServerNotification::TurnDiffUpdated(notification) => {
+                if !notification.diff.trim().is_empty() {
+                    eprintln!("{}", notification.diff);
+                }
+                CodexStatus::Running
+            }
+            ServerNotification::TurnPlanUpdated(notification) => {
+                if let Some(explanation) = notification.explanation {
+                    eprintln!("{}", explanation.style(self.italic));
+                }
+                for step in notification.plan {
+                    match step.status {
+                        codex_app_server_protocol::TurnPlanStepStatus::Completed => {
+                            eprintln!("  {} {}", "✓".style(self.green), step.step);
+                        }
+                        codex_app_server_protocol::TurnPlanStepStatus::InProgress => {
+                            eprintln!("  {} {}", "→".style(self.cyan), step.step);
+                        }
+                        codex_app_server_protocol::TurnPlanStepStatus::Pending => {
+                            eprintln!(
+                                "  {} {}",
+                                "•".style(self.dimmed),
+                                step.step.style(self.dimmed)
+                            );
+                        }
+                    }
+                }
+                CodexStatus::Running
+            }
+            ServerNotification::TurnStarted(_) => CodexStatus::Running,
+            _ => CodexStatus::Running,
+        }
+    }
+
+    fn process_warning(&mut self, message: String) -> CodexStatus {
+        eprintln!(
+            "{} {message}",
+            "warning:".style(self.yellow).style(self.bold)
+        );
+        CodexStatus::Running
+    }
+
+    fn print_final_output(&mut self) {
+        if self.emit_final_message_on_shutdown
+            && let Some(path) = self.last_message_path.as_deref()
+        {
+            handle_last_message(self.final_message.as_deref(), path);
+        }
+
+        if let Some(usage) = &self.last_total_token_usage {
+            eprintln!(
+                "{}\n{}",
+                "tokens used".style(self.dimmed),
+                format_with_separators(blended_total(usage))
+            );
+        }
+
+        #[allow(clippy::print_stdout)]
+        if should_print_final_message_to_stdout(
+            self.emit_final_message_on_shutdown
+                .then_some(self.final_message.as_deref())
+                .flatten(),
+            std::io::stdout().is_terminal(),
+            std::io::stderr().is_terminal(),
+        ) && let Some(message) = self.final_message.as_deref()
+        {
+            println!("{message}");
+        } else if should_print_final_message_to_tty(
+            self.emit_final_message_on_shutdown
+                .then_some(self.final_message.as_deref())
+                .flatten(),
+            self.final_message_rendered,
+            std::io::stdout().is_terminal(),
+            std::io::stderr().is_terminal(),
+        ) && let Some(message) = self.final_message.as_deref()
+        {
+            eprintln!(
+                "{}\n{}",
+                "codex".style(self.italic).style(self.magenta),
+                message
+            );
+        }
+    }
+}
+
+fn config_summary_entries(
+    config: &Config,
+    session_configured_event: &SessionConfiguredEvent,
+) -> Vec<(&'static str, String)> {
+    let permission_profile = config.permissions.effective_permission_profile();
+    let mut entries = vec![
+        ("workdir", config.cwd.display().to_string()),
+        ("model", session_configured_event.model.clone()),
+        (
+            "provider",
+            session_configured_event.model_provider_id.clone(),
+        ),
+        (
+            "approval",
+            config.permissions.approval_policy.value().to_string(),
+        ),
+        (
+            "sandbox",
+            summarize_permission_profile(
+                &permission_profile,
+                &PathUri::from_abs_path(&config.cwd),
+                &config.effective_workspace_roots(),
+            ),
+        ),
+    ];
+    if config.model_provider.wire_api == WireApi::Responses {
+        entries.push((
+            "reasoning effort",
+            config
+                .model_reasoning_effort
+                .as_ref()
+                .map(std::string::ToString::to_string)
+                .unwrap_or_else(|| "none".to_string()),
+        ));
+        entries.push((
+            "reasoning summaries",
+            config
+                .model_reasoning_summary
+                .map(|summary| summary.to_string())
+                .unwrap_or_else(|| "none".to_string()),
+        ));
+    }
+    entries.push((
+        "session id",
+        session_configured_event.session_id.to_string(),
+    ));
+    entries
+}
+
+fn reasoning_text(
+    summary: &[String],
+    content: &[String],
+    show_raw_agent_reasoning: bool,
+) -> Option<String> {
+    let entries = if show_raw_agent_reasoning && !content.is_empty() {
+        content
+    } else {
+        summary
+    };
+    if entries.is_empty() {
+        None
+    } else {
+        Some(entries.join("\n"))
+    }
+}
+
+fn final_message_from_turn_items(items: &[ThreadItem]) -> Option<String> {
+    items
+        .iter()
+        .rev()
+        .find_map(|item| match item {
+            ThreadItem::AgentMessage { text, .. } => Some(text.clone()),
+            _ => None,
+        })
+        .or_else(|| {
+            items.iter().rev().find_map(|item| match item {
+                ThreadItem::Plan { text, .. } => Some(text.clone()),
+                _ => None,
+            })
+        })
+}
+
+fn blended_total(usage: &ThreadTokenUsage) -> i64 {
+    let cached_input = usage.total.cached_input_tokens.max(0);
+    let non_cached_input = (usage.total.input_tokens - cached_input).max(0);
+    (non_cached_input + usage.total.output_tokens.max(0)).max(0)
+}
+
+fn should_print_final_message_to_stdout(
+    final_message: Option<&str>,
+    stdout_is_terminal: bool,
+    stderr_is_terminal: bool,
+) -> bool {
+    final_message.is_some() && !(stdout_is_terminal && stderr_is_terminal)
+}
+
+fn should_print_final_message_to_tty(
+    final_message: Option<&str>,
+    final_message_rendered: bool,
+    stdout_is_terminal: bool,
+    stderr_is_terminal: bool,
+) -> bool {
+    final_message.is_some() && !final_message_rendered && stdout_is_terminal && stderr_is_terminal
+}
+
+#[cfg(test)]
+#[path = "event_processor_with_human_output_tests.rs"]
+mod tests;
diff --git a/codex-rs/exec/src/event_processor_with_human_output_tests.rs b/codex-rs/exec/src/event_processor_with_human_output_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..594e2d3bb6aac3dd7088ab644bbc776e1fd2934f
--- /dev/null
+++ b/codex-rs/exec/src/event_processor_with_human_output_tests.rs
@@ -0,0 +1,532 @@
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::Turn;
+use codex_app_server_protocol::TurnStatus;
+use codex_core::config::ConfigBuilder;
+use codex_protocol::SessionId;
+use codex_protocol::ThreadId;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::SessionConfiguredEvent;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use codex_utils_path_uri::PathUri;
+use codex_utils_sandbox_summary::summarize_permission_profile;
+use owo_colors::Style;
+use pretty_assertions::assert_eq;
+
+use super::EventProcessorWithHumanOutput;
+use super::config_summary_entries;
+use super::final_message_from_turn_items;
+use super::reasoning_text;
+use super::should_print_final_message_to_stdout;
+use super::should_print_final_message_to_tty;
+use crate::event_processor::EventProcessor;
+
+#[test]
+fn suppresses_final_stdout_message_when_both_streams_are_terminals() {
+    assert!(!should_print_final_message_to_stdout(
+        Some("hello"),
+        /*stdout_is_terminal*/ true,
+        /*stderr_is_terminal*/ true
+    ));
+}
+
+#[test]
+fn prints_final_stdout_message_when_stdout_is_not_terminal() {
+    assert!(should_print_final_message_to_stdout(
+        Some("hello"),
+        /*stdout_is_terminal*/ false,
+        /*stderr_is_terminal*/ true
+    ));
+}
+
+#[test]
+fn prints_final_stdout_message_when_stderr_is_not_terminal() {
+    assert!(should_print_final_message_to_stdout(
+        Some("hello"),
+        /*stdout_is_terminal*/ true,
+        /*stderr_is_terminal*/ false
+    ));
+}
+
+#[test]
+fn suppresses_final_stdout_message_when_missing() {
+    assert!(!should_print_final_message_to_stdout(
+        /*final_message*/ None, /*stdout_is_terminal*/ false,
+        /*stderr_is_terminal*/ false
+    ));
+}
+
+#[test]
+fn prints_final_tty_message_when_not_yet_rendered() {
+    assert!(should_print_final_message_to_tty(
+        Some("hello"),
+        /*final_message_rendered*/ false,
+        /*stdout_is_terminal*/ true,
+        /*stderr_is_terminal*/ true
+    ));
+}
+
+#[test]
+fn suppresses_final_tty_message_when_already_rendered() {
+    assert!(!should_print_final_message_to_tty(
+        Some("hello"),
+        /*final_message_rendered*/ true,
+        /*stdout_is_terminal*/ true,
+        /*stderr_is_terminal*/ true
+    ));
+}
+
+#[test]
+fn reasoning_text_prefers_summary_when_raw_reasoning_is_hidden() {
+    let text = reasoning_text(
+        &["summary".to_string()],
+        &["raw".to_string()],
+        /*show_raw_agent_reasoning*/ false,
+    );
+
+    assert_eq!(text.as_deref(), Some("summary"));
+}
+
+#[test]
+fn reasoning_text_uses_raw_content_when_enabled() {
+    let text = reasoning_text(
+        &["summary".to_string()],
+        &["raw".to_string()],
+        /*show_raw_agent_reasoning*/ true,
+    );
+
+    assert_eq!(text.as_deref(), Some("raw"));
+}
+
+#[test]
+fn summarizes_disabled_permission_profile_as_danger_full_access() {
+    let cwd = PathUri::from_abs_path(&test_path_buf("/tmp").abs());
+
+    assert_eq!(
+        summarize_permission_profile(
+            &PermissionProfile::Disabled,
+            &cwd,
+            std::slice::from_ref(&cwd),
+        ),
+        "danger-full-access"
+    );
+}
+
+#[test]
+fn summarizes_external_permission_profile() {
+    let cwd = PathUri::from_abs_path(&test_path_buf("/tmp").abs());
+
+    assert_eq!(
+        summarize_permission_profile(
+            &PermissionProfile::External {
+                network: NetworkSandboxPolicy::Enabled,
+            },
+            &cwd,
+            std::slice::from_ref(&cwd),
+        ),
+        "external-sandbox (network access enabled)"
+    );
+}
+
+#[test]
+fn summarizes_managed_workspace_write_permission_profile() {
+    let cwd = test_path_buf("/tmp/project").abs();
+    let cache_root = test_path_buf("/tmp/cache").abs();
+    let profile = PermissionProfile::from_runtime_permissions(
+        &FileSystemSandboxPolicy::restricted(vec![
+            FileSystemSandboxEntry {
+                path: cwd.clone().into(),
+                access: FileSystemAccessMode::Write,
+                missing_path_behavior: None,
+            },
+            FileSystemSandboxEntry {
+                path: FileSystemPath::Path {
+                    path: cache_root.clone().into(),
+                },
+                access: FileSystemAccessMode::Write,
+                missing_path_behavior: None,
+            },
+        ]),
+        NetworkSandboxPolicy::Restricted,
+    );
+
+    assert_eq!(
+        summarize_permission_profile(
+            &profile,
+            &PathUri::from_abs_path(&cwd),
+            &[cwd.clone().into(), cache_root.clone().into()],
+        ),
+        format!("workspace-write [workdir, {}]", cache_root.display())
+    );
+}
+
+#[test]
+fn summarizes_managed_read_only_permission_profile() {
+    let cwd = PathUri::from_abs_path(&test_path_buf("/tmp/project").abs());
+    let profile = PermissionProfile::from_runtime_permissions(
+        &FileSystemSandboxPolicy::restricted(Vec::new()),
+        NetworkSandboxPolicy::Restricted,
+    );
+
+    assert_eq!(
+        summarize_permission_profile(&profile, &cwd, std::slice::from_ref(&cwd)),
+        "read-only"
+    );
+}
+
+#[tokio::test]
+async fn config_summary_entries_include_runtime_workspace_roots() {
+    let codex_home = tempfile::tempdir().expect("create codex home");
+    let cwd = tempfile::tempdir().expect("create cwd");
+    let extra_root = tempfile::tempdir().expect("create extra root");
+    let mut config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build default config");
+    let cwd = cwd.path().to_path_buf().abs();
+    let extra_root = extra_root.path().to_path_buf().abs();
+    let expected_extra_root_name = extra_root
+        .file_name()
+        .expect("extra root should have file name")
+        .to_string_lossy()
+        .to_string();
+    config.cwd = cwd.clone();
+    config.workspace_roots = vec![cwd.clone(), extra_root];
+    config
+        .permissions
+        .set_workspace_roots(config.workspace_roots.clone());
+    config
+        .permissions
+        .set_permission_profile(PermissionProfile::workspace_write_with(
+            &[],
+            NetworkSandboxPolicy::Restricted,
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        ))
+        .expect("set permission profile");
+
+    let session_configured_event = SessionConfiguredEvent {
+        session_id: SessionId::new(),
+        thread_id: ThreadId::new(),
+        forked_from_id: None,
+        parent_thread_id: None,
+        thread_source: None,
+        thread_name: None,
+        model: "gpt-5.4".to_string(),
+        model_provider_id: config.model_provider_id.clone(),
+        service_tier: None,
+        approval_policy: AskForApproval::Never,
+        approvals_reviewer: config.approvals_reviewer,
+        permission_profile: config.permissions.effective_permission_profile(),
+        active_permission_profile: None,
+        cwd,
+        reasoning_effort: None,
+        initial_messages: None,
+        network_proxy: None,
+        rollout_path: None,
+    };
+
+    let summary_entries = config_summary_entries(&config, &session_configured_event);
+    let sandbox_summary = summary_entries
+        .iter()
+        .find_map(|(key, value)| (*key == "sandbox").then_some(value))
+        .expect("sandbox summary entry");
+    assert!(
+        sandbox_summary.starts_with("workspace-write [workdir, ")
+            && sandbox_summary.contains(&expected_extra_root_name),
+        "expected runtime workspace root in sandbox summary: {summary_entries:?}"
+    );
+}
+
+#[test]
+fn final_message_from_turn_items_uses_latest_agent_message() {
+    let message = final_message_from_turn_items(&[
+        ThreadItem::AgentMessage {
+            id: "msg-1".to_string(),
+            text: "first".to_string(),
+            phase: None,
+            memory_citation: None,
+            delivery: None,
+            questions: None,
+        },
+        ThreadItem::Plan {
+            id: "plan-1".to_string(),
+            text: "plan".to_string(),
+        },
+        ThreadItem::AgentMessage {
+            id: "msg-2".to_string(),
+            text: "second".to_string(),
+            phase: None,
+            memory_citation: None,
+            delivery: None,
+            questions: None,
+        },
+    ]);
+
+    assert_eq!(message.as_deref(), Some("second"));
+}
+
+#[test]
+fn final_message_from_turn_items_falls_back_to_latest_plan() {
+    let message = final_message_from_turn_items(&[
+        ThreadItem::Reasoning {
+            id: "reasoning-1".to_string(),
+            summary: vec!["inspect".to_string()],
+            content: Vec::new(),
+        },
+        ThreadItem::Plan {
+            id: "plan-1".to_string(),
+            text: "first plan".to_string(),
+        },
+        ThreadItem::Plan {
+            id: "plan-2".to_string(),
+            text: "final plan".to_string(),
+        },
+    ]);
+
+    assert_eq!(message.as_deref(), Some("final plan"));
+}
+
+#[test]
+fn turn_completed_recovers_final_message_from_turn_items() {
+    let mut processor = EventProcessorWithHumanOutput {
+        bold: Style::new(),
+        cyan: Style::new(),
+        dimmed: Style::new(),
+        green: Style::new(),
+        italic: Style::new(),
+        magenta: Style::new(),
+        red: Style::new(),
+        yellow: Style::new(),
+        show_agent_reasoning: true,
+        show_raw_agent_reasoning: false,
+        last_message_path: None,
+        final_message: None,
+        final_message_rendered: false,
+        emit_final_message_on_shutdown: false,
+        last_total_token_usage: None,
+    };
+
+    let status = processor.process_server_notification(ServerNotification::TurnCompleted(
+        codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![ThreadItem::AgentMessage {
+                    id: "msg-1".to_string(),
+                    text: "final answer".to_string(),
+                    phase: None,
+                    memory_citation: None,
+                    delivery: None,
+                    questions: None,
+                }],
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        status,
+        crate::event_processor::CodexStatus::InitiateShutdown
+    );
+    assert_eq!(processor.final_message.as_deref(), Some("final answer"));
+}
+
+#[test]
+fn turn_completed_overwrites_stale_final_message_from_turn_items() {
+    let mut processor = EventProcessorWithHumanOutput {
+        bold: Style::new(),
+        cyan: Style::new(),
+        dimmed: Style::new(),
+        green: Style::new(),
+        italic: Style::new(),
+        magenta: Style::new(),
+        red: Style::new(),
+        yellow: Style::new(),
+        show_agent_reasoning: true,
+        show_raw_agent_reasoning: false,
+        last_message_path: None,
+        final_message: Some("stale answer".to_string()),
+        final_message_rendered: true,
+        emit_final_message_on_shutdown: false,
+        last_total_token_usage: None,
+    };
+
+    let status = processor.process_server_notification(ServerNotification::TurnCompleted(
+        codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![ThreadItem::AgentMessage {
+                    id: "msg-1".to_string(),
+                    text: "final answer".to_string(),
+                    phase: None,
+                    memory_citation: None,
+                    delivery: None,
+                    questions: None,
+                }],
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        status,
+        crate::event_processor::CodexStatus::InitiateShutdown
+    );
+    assert_eq!(processor.final_message.as_deref(), Some("final answer"));
+    assert!(!processor.final_message_rendered);
+}
+
+#[test]
+fn turn_completed_preserves_streamed_final_message_when_turn_items_are_empty() {
+    let mut processor = EventProcessorWithHumanOutput {
+        bold: Style::new(),
+        cyan: Style::new(),
+        dimmed: Style::new(),
+        green: Style::new(),
+        italic: Style::new(),
+        magenta: Style::new(),
+        red: Style::new(),
+        yellow: Style::new(),
+        show_agent_reasoning: true,
+        show_raw_agent_reasoning: false,
+        last_message_path: None,
+        final_message: Some("streamed answer".to_string()),
+        final_message_rendered: false,
+        emit_final_message_on_shutdown: false,
+        last_total_token_usage: None,
+    };
+
+    let status = processor.process_server_notification(ServerNotification::TurnCompleted(
+        codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        status,
+        crate::event_processor::CodexStatus::InitiateShutdown
+    );
+    assert_eq!(processor.final_message.as_deref(), Some("streamed answer"));
+    assert!(processor.emit_final_message_on_shutdown);
+}
+
+#[test]
+fn turn_failed_clears_stale_final_message() {
+    let mut processor = EventProcessorWithHumanOutput {
+        bold: Style::new(),
+        cyan: Style::new(),
+        dimmed: Style::new(),
+        green: Style::new(),
+        italic: Style::new(),
+        magenta: Style::new(),
+        red: Style::new(),
+        yellow: Style::new(),
+        show_agent_reasoning: true,
+        show_raw_agent_reasoning: false,
+        last_message_path: None,
+        final_message: Some("partial answer".to_string()),
+        final_message_rendered: true,
+        emit_final_message_on_shutdown: true,
+        last_total_token_usage: None,
+    };
+
+    let status = processor.process_server_notification(ServerNotification::TurnCompleted(
+        codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Failed,
+                error: None,
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        status,
+        crate::event_processor::CodexStatus::InitiateShutdown
+    );
+    assert_eq!(processor.final_message, None);
+    assert!(!processor.final_message_rendered);
+    assert!(!processor.emit_final_message_on_shutdown);
+}
+
+#[test]
+fn turn_interrupted_clears_stale_final_message() {
+    let mut processor = EventProcessorWithHumanOutput {
+        bold: Style::new(),
+        cyan: Style::new(),
+        dimmed: Style::new(),
+        green: Style::new(),
+        italic: Style::new(),
+        magenta: Style::new(),
+        red: Style::new(),
+        yellow: Style::new(),
+        show_agent_reasoning: true,
+        show_raw_agent_reasoning: false,
+        last_message_path: None,
+        final_message: Some("partial answer".to_string()),
+        final_message_rendered: true,
+        emit_final_message_on_shutdown: true,
+        last_total_token_usage: None,
+    };
+
+    let status = processor.process_server_notification(ServerNotification::TurnCompleted(
+        codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Interrupted,
+                error: None,
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        status,
+        crate::event_processor::CodexStatus::InitiateShutdown
+    );
+    assert_eq!(processor.final_message, None);
+    assert!(!processor.final_message_rendered);
+    assert!(!processor.emit_final_message_on_shutdown);
+}
diff --git a/codex-rs/exec/src/event_processor_with_jsonl_output.rs b/codex-rs/exec/src/event_processor_with_jsonl_output.rs
new file mode 100644
index 0000000000000000000000000000000000000000..488cbc52e9ca31cea1203fb8ba923af50e2b39df
--- /dev/null
+++ b/codex-rs/exec/src/event_processor_with_jsonl_output.rs
@@ -0,0 +1,635 @@
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+
+use codex_app_server_protocol::CollabAgentTool;
+use codex_app_server_protocol::CollabAgentToolCallStatus;
+use codex_app_server_protocol::CommandExecutionStatus;
+use codex_app_server_protocol::McpToolCallStatus;
+use codex_app_server_protocol::PatchApplyStatus;
+use codex_app_server_protocol::PatchChangeKind;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::ThreadTokenUsage;
+use codex_app_server_protocol::TurnStatus;
+use codex_core::config::Config;
+use codex_protocol::models::WebSearchAction;
+use codex_protocol::protocol::SessionConfiguredEvent;
+use serde_json::json;
+
+pub use crate::event_processor::CodexStatus;
+use crate::event_processor::EventProcessor;
+use crate::event_processor::handle_last_message;
+use crate::exec_events::AgentMessageItem;
+use crate::exec_events::CollabAgentState;
+use crate::exec_events::CollabAgentStatus;
+use crate::exec_events::CollabTool;
+use crate::exec_events::CollabToolCallItem;
+use crate::exec_events::CollabToolCallStatus;
+use crate::exec_events::CommandExecutionItem;
+use crate::exec_events::CommandExecutionStatus as ExecCommandExecutionStatus;
+use crate::exec_events::ErrorItem;
+use crate::exec_events::FileChangeItem;
+use crate::exec_events::FileUpdateChange;
+use crate::exec_events::ItemCompletedEvent;
+use crate::exec_events::ItemStartedEvent;
+use crate::exec_events::ItemUpdatedEvent;
+use crate::exec_events::McpToolCallItem;
+use crate::exec_events::McpToolCallItemError;
+use crate::exec_events::McpToolCallItemResult;
+use crate::exec_events::McpToolCallStatus as ExecMcpToolCallStatus;
+use crate::exec_events::PatchApplyStatus as ExecPatchApplyStatus;
+use crate::exec_events::PatchChangeKind as ExecPatchChangeKind;
+use crate::exec_events::ReasoningItem;
+use crate::exec_events::ThreadErrorEvent;
+use crate::exec_events::ThreadEvent;
+use crate::exec_events::ThreadItem as ExecThreadItem;
+use crate::exec_events::ThreadItemDetails;
+use crate::exec_events::ThreadStartedEvent;
+use crate::exec_events::TodoItem;
+use crate::exec_events::TodoListItem;
+use crate::exec_events::TurnCompletedEvent;
+use crate::exec_events::TurnFailedEvent;
+use crate::exec_events::TurnStartedEvent;
+use crate::exec_events::Usage;
+use crate::exec_events::WebSearchItem;
+
+pub struct EventProcessorWithJsonOutput {
+    last_message_path: Option<PathBuf>,
+    next_item_id: AtomicU64,
+    raw_to_exec_item_id: HashMap<String, String>,
+    running_todo_list: Option<RunningTodoList>,
+    last_total_token_usage: Option<ThreadTokenUsage>,
+    last_critical_error: Option<ThreadErrorEvent>,
+    final_message: Option<String>,
+    emit_final_message_on_shutdown: bool,
+}
+
+#[derive(Debug, Clone)]
+struct RunningTodoList {
+    item_id: String,
+    items: Vec<TodoItem>,
+}
+
+#[derive(Debug, PartialEq)]
+pub struct CollectedThreadEvents {
+    pub events: Vec<ThreadEvent>,
+    pub status: CodexStatus,
+}
+
+impl EventProcessorWithJsonOutput {
+    pub fn new(last_message_path: Option<PathBuf>) -> Self {
+        Self {
+            last_message_path,
+            next_item_id: AtomicU64::new(0),
+            raw_to_exec_item_id: HashMap::new(),
+            running_todo_list: None,
+            last_total_token_usage: None,
+            last_critical_error: None,
+            final_message: None,
+            emit_final_message_on_shutdown: false,
+        }
+    }
+
+    pub fn final_message(&self) -> Option<&str> {
+        self.final_message.as_deref()
+    }
+
+    fn next_item_id(&self) -> String {
+        format!("item_{}", self.next_item_id.fetch_add(1, Ordering::SeqCst))
+    }
+
+    #[allow(clippy::print_stdout)]
+    fn emit(&self, event: ThreadEvent) {
+        println!(
+            "{}",
+            serde_json::to_string(&event).unwrap_or_else(|err| {
+                json!({
+                    "type": "error",
+                    "message": format!("failed to serialize exec json event: {err}"),
+                })
+                .to_string()
+            })
+        );
+    }
+
+    fn usage_from_last_total(&self) -> Usage {
+        let Some(usage) = self.last_total_token_usage.as_ref() else {
+            return Usage::default();
+        };
+        Usage {
+            input_tokens: usage.total.input_tokens,
+            cached_input_tokens: usage.total.cached_input_tokens,
+            cache_write_input_tokens: usage.total.cache_write_input_tokens,
+            output_tokens: usage.total.output_tokens,
+            reasoning_output_tokens: usage.total.reasoning_output_tokens,
+        }
+    }
+
+    pub fn map_todo_items(plan: &[codex_app_server_protocol::TurnPlanStep]) -> Vec<TodoItem> {
+        plan.iter()
+            .map(|step| TodoItem {
+                text: step.step.clone(),
+                completed: matches!(
+                    step.status,
+                    codex_app_server_protocol::TurnPlanStepStatus::Completed
+                ),
+            })
+            .collect()
+    }
+
+    fn map_item_with_id(
+        item: ThreadItem,
+        make_id: impl FnOnce() -> String,
+    ) -> Option<ExecThreadItem> {
+        match item {
+            ThreadItem::AgentMessage { text, .. } => Some(ExecThreadItem {
+                id: make_id(),
+                details: ThreadItemDetails::AgentMessage(AgentMessageItem { text }),
+            }),
+            ThreadItem::Reasoning { summary, .. } => {
+                let text = summary.join("\n");
+                if text.trim().is_empty() {
+                    return None;
+                }
+                Some(ExecThreadItem {
+                    id: make_id(),
+                    details: ThreadItemDetails::Reasoning(ReasoningItem { text }),
+                })
+            }
+            ThreadItem::CommandExecution {
+                command,
+                aggregated_output,
+                exit_code,
+                status,
+                ..
+            } => Some(ExecThreadItem {
+                id: make_id(),
+                details: ThreadItemDetails::CommandExecution(CommandExecutionItem {
+                    command,
+                    aggregated_output: aggregated_output.unwrap_or_default(),
+                    exit_code,
+                    status: match status {
+                        CommandExecutionStatus::InProgress => ExecCommandExecutionStatus::InProgress,
+                        CommandExecutionStatus::Completed => ExecCommandExecutionStatus::Completed,
+                        CommandExecutionStatus::Failed => ExecCommandExecutionStatus::Failed,
+                        CommandExecutionStatus::Declined => ExecCommandExecutionStatus::Declined,
+                    },
+                }),
+            }),
+            ThreadItem::FileChange {
+                changes, status, ..
+            } => Some(ExecThreadItem {
+                id: make_id(),
+                details: ThreadItemDetails::FileChange(FileChangeItem {
+                    changes: changes
+                        .into_iter()
+                        .map(|change| FileUpdateChange {
+                            path: change.path,
+                            kind: match change.kind {
+                                PatchChangeKind::Add => ExecPatchChangeKind::Add,
+                                PatchChangeKind::Delete => ExecPatchChangeKind::Delete,
+                                PatchChangeKind::Update { .. } => ExecPatchChangeKind::Update,
+                            },
+                        })
+                        .collect(),
+                    status: match status {
+                        PatchApplyStatus::InProgress => ExecPatchApplyStatus::InProgress,
+                        PatchApplyStatus::Completed => ExecPatchApplyStatus::Completed,
+                        PatchApplyStatus::Failed | PatchApplyStatus::Declined => {
+                            ExecPatchApplyStatus::Failed
+                        }
+                    },
+                }),
+            }),
+            ThreadItem::McpToolCall {
+                server,
+                tool,
+                status,
+                arguments,
+                result,
+                error,
+                ..
+            } => Some(ExecThreadItem {
+                id: make_id(),
+                details: ThreadItemDetails::McpToolCall(McpToolCallItem {
+                    server,
+                    tool,
+                    status: match status {
+                        McpToolCallStatus::InProgress => ExecMcpToolCallStatus::InProgress,
+                        McpToolCallStatus::Completed => ExecMcpToolCallStatus::Completed,
+                        McpToolCallStatus::Failed => ExecMcpToolCallStatus::Failed,
+                    },
+                    arguments,
+                    result: result.map(|result| McpToolCallItemResult {
+                        content: result.content,
+                        meta: result.meta,
+                        structured_content: result.structured_content,
+                    }),
+                    error: error.map(|error| McpToolCallItemError {
+                        message: error.message,
+                    }),
+                }),
+            }),
+            ThreadItem::CollabAgentToolCall {
+                tool,
+                sender_thread_id,
+                receiver_thread_ids,
+                prompt,
+                agents_states,
+                status,
+                ..
+            } => Some(ExecThreadItem {
+                id: make_id(),
+                details: ThreadItemDetails::CollabToolCall(CollabToolCallItem {
+                    tool: match tool {
+                        CollabAgentTool::SendMessage
+                        | CollabAgentTool::FollowupTask
+                        | CollabAgentTool::InterruptAgent
+                        | CollabAgentTool::ListAgents => return None,
+                        CollabAgentTool::SpawnAgent => CollabTool::SpawnAgent,
+                        CollabAgentTool::SendInput => CollabTool::SendInput,
+                        CollabAgentTool::ResumeAgent => CollabTool::Wait,
+                        CollabAgentTool::Wait => CollabTool::Wait,
+                        CollabAgentTool::CloseAgent => CollabTool::CloseAgent,
+                    },
+                    sender_thread_id,
+                    receiver_thread_ids,
+                    prompt,
+                    agents_states: agents_states
+                        .into_iter()
+                        .map(|(thread_id, state)| {
+                            (
+                                thread_id,
+                                CollabAgentState {
+                                    status: match state.status {
+                                        codex_app_server_protocol::CollabAgentStatus::PendingInit => {
+                                            CollabAgentStatus::PendingInit
+                                        }
+                                        codex_app_server_protocol::CollabAgentStatus::Running => {
+                                            CollabAgentStatus::Running
+                                        }
+                                        codex_app_server_protocol::CollabAgentStatus::Interrupted => {
+                                            CollabAgentStatus::Interrupted
+                                        }
+                                        codex_app_server_protocol::CollabAgentStatus::Completed => {
+                                            CollabAgentStatus::Completed
+                                        }
+                                        codex_app_server_protocol::CollabAgentStatus::Errored => {
+                                            CollabAgentStatus::Errored
+                                        }
+                                        codex_app_server_protocol::CollabAgentStatus::Shutdown => {
+                                            CollabAgentStatus::Shutdown
+                                        }
+                                        codex_app_server_protocol::CollabAgentStatus::NotFound => {
+                                            CollabAgentStatus::NotFound
+                                        }
+                                    },
+                                    message: state.message,
+                                },
+                            )
+                        })
+                        .collect(),
+                    status: match status {
+                        CollabAgentToolCallStatus::InProgress => CollabToolCallStatus::InProgress,
+                        CollabAgentToolCallStatus::Completed => CollabToolCallStatus::Completed,
+                        CollabAgentToolCallStatus::Failed => CollabToolCallStatus::Failed,
+                        CollabAgentToolCallStatus::Interrupted => return None,
+                    },
+                }),
+            }),
+            ThreadItem::WebSearch(item) => Some(ExecThreadItem {
+                id: make_id(),
+                details: ThreadItemDetails::WebSearch(WebSearchItem {
+                    id: item.id,
+                    query: item.query,
+                    action: match item.action {
+                        Some(action) => serde_json::from_value(
+                            serde_json::to_value(action).unwrap_or_else(|_| json!("other")),
+                        )
+                        .unwrap_or(WebSearchAction::Other),
+                        None => WebSearchAction::Other,
+                    },
+                }),
+            }),
+            _ => None,
+        }
+    }
+
+    fn started_item_id(&mut self, raw_id: &str) -> String {
+        if let Some(existing) = self.raw_to_exec_item_id.get(raw_id) {
+            return existing.clone();
+        }
+        let exec_id = self.next_item_id();
+        self.raw_to_exec_item_id
+            .insert(raw_id.to_string(), exec_id.clone());
+        exec_id
+    }
+
+    fn completed_item_id(&mut self, raw_id: &str) -> String {
+        self.raw_to_exec_item_id
+            .remove(raw_id)
+            .unwrap_or_else(|| self.next_item_id())
+    }
+
+    fn map_started_item(&mut self, item: ThreadItem) -> Option<ExecThreadItem> {
+        match item {
+            ThreadItem::AgentMessage { .. } | ThreadItem::Reasoning { .. } => None,
+            other => {
+                let raw_id = other.id().to_string();
+                Self::map_item_with_id(other, || self.started_item_id(&raw_id))
+            }
+        }
+    }
+
+    fn map_completed_item_mut(&mut self, item: ThreadItem) -> Option<ExecThreadItem> {
+        if let ThreadItem::Reasoning { summary, .. } = &item
+            && summary.join("\n").trim().is_empty()
+        {
+            return None;
+        }
+        match &item {
+            ThreadItem::AgentMessage { .. } | ThreadItem::Reasoning { .. } => {
+                Self::map_item_with_id(item, || self.next_item_id())
+            }
+            other => {
+                let raw_id = other.id().to_string();
+                Self::map_item_with_id(item, || self.completed_item_id(&raw_id))
+            }
+        }
+    }
+
+    fn reconcile_unfinished_started_items(
+        &mut self,
+        turn_items: &[ThreadItem],
+    ) -> Vec<ThreadEvent> {
+        turn_items
+            .iter()
+            .filter_map(|item| {
+                let raw_id = item.id().to_string();
+                if !self.raw_to_exec_item_id.contains_key(&raw_id) {
+                    return None;
+                }
+                self.map_completed_item_mut(item.clone())
+                    .map(|item| ThreadEvent::ItemCompleted(ItemCompletedEvent { item }))
+            })
+            .collect()
+    }
+
+    fn final_message_from_turn_items(items: &[ThreadItem]) -> Option<String> {
+        items
+            .iter()
+            .rev()
+            .find_map(|item| match item {
+                ThreadItem::AgentMessage { text, .. } => Some(text.clone()),
+                _ => None,
+            })
+            .or_else(|| {
+                items.iter().rev().find_map(|item| match item {
+                    ThreadItem::Plan { text, .. } => Some(text.clone()),
+                    _ => None,
+                })
+            })
+    }
+
+    pub fn thread_started_event(session_configured: &SessionConfiguredEvent) -> ThreadEvent {
+        ThreadEvent::ThreadStarted(ThreadStartedEvent {
+            thread_id: session_configured.thread_id.to_string(),
+        })
+    }
+
+    pub fn collect_warning(&mut self, message: String) -> CollectedThreadEvents {
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: self.next_item_id(),
+                    details: ThreadItemDetails::Error(ErrorItem { message }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    }
+
+    pub fn collect_thread_events(
+        &mut self,
+        notification: ServerNotification,
+    ) -> CollectedThreadEvents {
+        let mut events = Vec::new();
+        let status = match notification {
+            ServerNotification::ConfigWarning(notification) => {
+                let message = match notification.details {
+                    Some(details) if !details.is_empty() => {
+                        format!("{} ({details})", notification.summary)
+                    }
+                    _ => notification.summary,
+                };
+                events.push(ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                    item: ExecThreadItem {
+                        id: self.next_item_id(),
+                        details: ThreadItemDetails::Error(ErrorItem { message }),
+                    },
+                }));
+                CodexStatus::Running
+            }
+            ServerNotification::Warning(notification) => {
+                let warning = self.collect_warning(notification.message);
+                events.extend(warning.events);
+                warning.status
+            }
+            ServerNotification::Error(notification) => {
+                let message = match notification.error.additional_details {
+                    Some(details) if !details.is_empty() => {
+                        format!("{} ({details})", notification.error.message)
+                    }
+                    _ => notification.error.message,
+                };
+                let error = ThreadErrorEvent { message };
+                self.last_critical_error = Some(error.clone());
+                events.push(ThreadEvent::Error(error));
+                CodexStatus::Running
+            }
+            ServerNotification::DeprecationNotice(notification) => {
+                let message = match notification.details {
+                    Some(details) if !details.is_empty() => {
+                        format!("{} ({details})", notification.summary)
+                    }
+                    _ => notification.summary,
+                };
+                events.push(ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                    item: ExecThreadItem {
+                        id: self.next_item_id(),
+                        details: ThreadItemDetails::Error(ErrorItem { message }),
+                    },
+                }));
+                CodexStatus::Running
+            }
+            ServerNotification::HookStarted(_) | ServerNotification::HookCompleted(_) => {
+                CodexStatus::Running
+            }
+            ServerNotification::ItemStarted(notification) => {
+                if let Some(item) = self.map_started_item(notification.item) {
+                    events.push(ThreadEvent::ItemStarted(ItemStartedEvent { item }));
+                }
+                CodexStatus::Running
+            }
+            ServerNotification::ItemCompleted(notification) => {
+                if let Some(item) = self.map_completed_item_mut(notification.item) {
+                    if let ThreadItemDetails::AgentMessage(AgentMessageItem { text }) =
+                        &item.details
+                    {
+                        self.final_message = Some(text.clone());
+                    }
+                    events.push(ThreadEvent::ItemCompleted(ItemCompletedEvent { item }));
+                }
+                CodexStatus::Running
+            }
+            ServerNotification::ModelRerouted(notification) => {
+                events.push(ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                    item: ExecThreadItem {
+                        id: self.next_item_id(),
+                        details: ThreadItemDetails::Error(ErrorItem {
+                            message: format!(
+                                "model rerouted: {} -> {} ({:?})",
+                                notification.from_model, notification.to_model, notification.reason
+                            ),
+                        }),
+                    },
+                }));
+                CodexStatus::Running
+            }
+            ServerNotification::ModelVerification(_) => CodexStatus::Running,
+            ServerNotification::ThreadTokenUsageUpdated(notification) => {
+                self.last_total_token_usage = Some(notification.token_usage);
+                CodexStatus::Running
+            }
+            ServerNotification::TurnCompleted(notification) => {
+                if let Some(running) = self.running_todo_list.take() {
+                    events.push(ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                        item: ExecThreadItem {
+                            id: running.item_id,
+                            details: ThreadItemDetails::TodoList(TodoListItem {
+                                items: running.items,
+                            }),
+                        },
+                    }));
+                }
+                events.extend(self.reconcile_unfinished_started_items(&notification.turn.items));
+                match notification.turn.status {
+                    TurnStatus::Completed => {
+                        if let Some(final_message) =
+                            Self::final_message_from_turn_items(notification.turn.items.as_slice())
+                        {
+                            self.final_message = Some(final_message);
+                        }
+                        self.emit_final_message_on_shutdown = true;
+                        events.push(ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                            usage: self.usage_from_last_total(),
+                        }));
+                        CodexStatus::InitiateShutdown
+                    }
+                    TurnStatus::Failed => {
+                        self.final_message = None;
+                        self.emit_final_message_on_shutdown = false;
+                        let error = notification
+                            .turn
+                            .error
+                            .map(|error| ThreadErrorEvent {
+                                message: match error.additional_details {
+                                    Some(details) if !details.is_empty() => {
+                                        format!("{} ({details})", error.message)
+                                    }
+                                    _ => error.message,
+                                },
+                            })
+                            .or_else(|| self.last_critical_error.clone())
+                            .unwrap_or_else(|| ThreadErrorEvent {
+                                message: "turn failed".to_string(),
+                            });
+                        events.push(ThreadEvent::TurnFailed(TurnFailedEvent { error }));
+                        CodexStatus::InitiateShutdown
+                    }
+                    TurnStatus::Interrupted => {
+                        self.final_message = None;
+                        self.emit_final_message_on_shutdown = false;
+                        CodexStatus::InitiateShutdown
+                    }
+                    TurnStatus::InProgress => CodexStatus::Running,
+                }
+            }
+            ServerNotification::TurnDiffUpdated(_) => CodexStatus::Running,
+            ServerNotification::TurnPlanUpdated(notification) => {
+                let items = Self::map_todo_items(&notification.plan);
+                if let Some(running) = self.running_todo_list.as_mut() {
+                    running.items = items.clone();
+                    let item_id = running.item_id.clone();
+                    events.push(ThreadEvent::ItemUpdated(ItemUpdatedEvent {
+                        item: ExecThreadItem {
+                            id: item_id,
+                            details: ThreadItemDetails::TodoList(TodoListItem { items }),
+                        },
+                    }));
+                } else {
+                    let item_id = self.next_item_id();
+                    self.running_todo_list = Some(RunningTodoList {
+                        item_id: item_id.clone(),
+                        items: items.clone(),
+                    });
+                    events.push(ThreadEvent::ItemStarted(ItemStartedEvent {
+                        item: ExecThreadItem {
+                            id: item_id,
+                            details: ThreadItemDetails::TodoList(TodoListItem { items }),
+                        },
+                    }));
+                }
+                CodexStatus::Running
+            }
+            ServerNotification::TurnStarted(_) => {
+                events.push(ThreadEvent::TurnStarted(TurnStartedEvent {}));
+                CodexStatus::Running
+            }
+            _ => CodexStatus::Running,
+        };
+
+        CollectedThreadEvents { events, status }
+    }
+}
+
+impl EventProcessor for EventProcessorWithJsonOutput {
+    fn print_config_summary(
+        &mut self,
+        _: &Config,
+        _: &str,
+        session_configured: &SessionConfiguredEvent,
+    ) {
+        self.emit(Self::thread_started_event(session_configured));
+    }
+
+    fn process_server_notification(&mut self, notification: ServerNotification) -> CodexStatus {
+        let collected = self.collect_thread_events(notification);
+        for event in collected.events {
+            self.emit(event);
+        }
+        collected.status
+    }
+
+    fn process_warning(&mut self, message: String) -> CodexStatus {
+        let collected = self.collect_warning(message);
+        for event in collected.events {
+            self.emit(event);
+        }
+        collected.status
+    }
+
+    fn print_final_output(&mut self) {
+        if self.emit_final_message_on_shutdown
+            && let Some(path) = self.last_message_path.as_deref()
+        {
+            handle_last_message(self.final_message.as_deref(), path);
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "event_processor_with_jsonl_output_tests.rs"]
+mod tests;
diff --git a/codex-rs/exec/src/event_processor_with_jsonl_output_tests.rs b/codex-rs/exec/src/event_processor_with_jsonl_output_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5109848a6ed1c4de6524b9327f2efca5ef83328d
--- /dev/null
+++ b/codex-rs/exec/src/event_processor_with_jsonl_output_tests.rs
@@ -0,0 +1,144 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use tempfile::tempdir;
+
+#[test]
+fn failed_turn_does_not_overwrite_output_last_message_file() {
+    let tempdir = tempdir().expect("create tempdir");
+    let output_path = tempdir.path().join("last-message.txt");
+    std::fs::write(&output_path, "keep existing contents").expect("seed output file");
+
+    let mut processor = EventProcessorWithJsonOutput::new(Some(output_path.clone()));
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        codex_app_server_protocol::ItemCompletedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "msg-1".to_string(),
+                text: "partial answer".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(collected.status, CodexStatus::Running);
+    assert_eq!(processor.final_message(), Some("partial answer"));
+
+    let status = processor.process_server_notification(ServerNotification::TurnCompleted(
+        codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: codex_app_server_protocol::Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Failed,
+                error: Some(codex_app_server_protocol::TurnError {
+                    misalignment: None,
+                    message: "turn failed".to_string(),
+                    additional_details: None,
+                    codex_error_info: None,
+                }),
+                started_at: None,
+                completed_at: Some(0),
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(status, CodexStatus::InitiateShutdown);
+    assert_eq!(processor.final_message(), None);
+
+    EventProcessor::print_final_output(&mut processor);
+
+    assert_eq!(
+        std::fs::read_to_string(&output_path).expect("read output file"),
+        "keep existing contents"
+    );
+}
+
+#[test]
+fn runtime_warning_emits_a_non_fatal_error_item() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::Warning(
+        codex_app_server_protocol::WarningNotification {
+            thread_id: Some("thread-1".to_string()),
+            message: "invalid global instructions".to_string(),
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::Error(ErrorItem {
+                        message: "invalid global instructions".to_string(),
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn mcp_tool_call_result_preserves_meta_in_jsonl_event() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        codex_app_server_protocol::ItemCompletedNotification {
+            item: ThreadItem::McpToolCall {
+                id: "mcp-1".to_string(),
+                server: "search service".to_string(),
+                tool: "web_run".to_string(),
+                status: McpToolCallStatus::Completed,
+                arguments: json!({"search_query": [{"q": "OpenAI Codex CLI documentation"}]}),
+                app_context: None,
+                mcp_app_resource_uri: None,
+                mcp_app_ui: None,
+                plugin_id: None,
+                read_only_hint: None,
+                result: Some(Box::new(codex_app_server_protocol::McpToolCallResult {
+                    content: vec![json!({"type": "text", "text": "search result"})],
+                    structured_content: None,
+                    meta: Some(json!({"raw_messages": [{"ref_id": "turn0search0"}]})),
+                })),
+                error: None,
+                duration_ms: Some(42),
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(collected.status, CodexStatus::Running);
+    assert_eq!(collected.events.len(), 1);
+
+    let ThreadEvent::ItemCompleted(ItemCompletedEvent { item }) = &collected.events[0] else {
+        panic!("expected item.completed event");
+    };
+    let ThreadItemDetails::McpToolCall(item) = &item.details else {
+        panic!("expected MCP tool call item");
+    };
+    let result = item.result.as_ref().expect("expected MCP tool result");
+    assert_eq!(
+        result.meta,
+        Some(json!({"raw_messages": [{"ref_id": "turn0search0"}]}))
+    );
+
+    let serialized = serde_json::to_value(&collected.events[0]).expect("serialize event");
+    assert_eq!(
+        serialized["item"]["result"]["_meta"],
+        json!({"raw_messages": [{"ref_id": "turn0search0"}]})
+    );
+    assert!(serialized["item"]["result"].get("meta").is_none());
+}
diff --git a/codex-rs/exec/src/exec_events.rs b/codex-rs/exec/src/exec_events.rs
new file mode 100644
index 0000000000000000000000000000000000000000..30df7f176a02c5283405a70fac2d5ef9acdcb66e
--- /dev/null
+++ b/codex-rs/exec/src/exec_events.rs
@@ -0,0 +1,320 @@
+use codex_protocol::models::WebSearchAction;
+use serde::Deserialize;
+use serde::Serialize;
+use serde_json::Value as JsonValue;
+use std::collections::HashMap;
+use ts_rs::TS;
+
+/// Top-level JSONL events emitted by codex exec
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+#[serde(tag = "type")]
+pub enum ThreadEvent {
+    /// Emitted when a new thread is started as the first event.
+    #[serde(rename = "thread.started")]
+    ThreadStarted(ThreadStartedEvent),
+    /// Emitted when a turn is started by sending a new prompt to the model.
+    /// A turn encompasses all events that happen while agent is processing the prompt.
+    #[serde(rename = "turn.started")]
+    TurnStarted(TurnStartedEvent),
+    /// Emitted when a turn is completed. Typically right after the assistant's response.
+    #[serde(rename = "turn.completed")]
+    TurnCompleted(TurnCompletedEvent),
+    /// Indicates that a turn failed with an error.
+    #[serde(rename = "turn.failed")]
+    TurnFailed(TurnFailedEvent),
+    /// Emitted when a new item is added to the thread. Typically the item will be in an "in progress" state.
+    #[serde(rename = "item.started")]
+    ItemStarted(ItemStartedEvent),
+    /// Emitted when an item is updated.
+    #[serde(rename = "item.updated")]
+    ItemUpdated(ItemUpdatedEvent),
+    /// Signals that an item has reached a terminal state—either success or failure.
+    #[serde(rename = "item.completed")]
+    ItemCompleted(ItemCompletedEvent),
+    /// Represents an unrecoverable error emitted directly by the event stream.
+    #[serde(rename = "error")]
+    Error(ThreadErrorEvent),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ThreadStartedEvent {
+    /// The identified of the new thread. Can be used to resume the thread later.
+    pub thread_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS, Default)]
+
+pub struct TurnStartedEvent {}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct TurnCompletedEvent {
+    pub usage: Usage,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct TurnFailedEvent {
+    pub error: ThreadErrorEvent,
+}
+
+/// Describes the usage of tokens during a turn.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS, Default)]
+pub struct Usage {
+    /// The number of input tokens used during the turn.
+    pub input_tokens: i64,
+    /// The number of cached input tokens used during the turn.
+    pub cached_input_tokens: i64,
+    /// The number of input tokens written to the prompt cache during the turn.
+    #[serde(default)]
+    pub cache_write_input_tokens: i64,
+    /// The number of output tokens used during the turn.
+    pub output_tokens: i64,
+    /// The number of reasoning output tokens used during the turn.
+    pub reasoning_output_tokens: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ItemStartedEvent {
+    pub item: ThreadItem,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ItemCompletedEvent {
+    pub item: ThreadItem,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ItemUpdatedEvent {
+    pub item: ThreadItem,
+}
+
+/// Fatal error emitted by the stream.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ThreadErrorEvent {
+    pub message: String,
+}
+
+/// Canonical representation of a thread item and its domain-specific payload.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ThreadItem {
+    pub id: String,
+    #[serde(flatten)]
+    pub details: ThreadItemDetails,
+}
+
+/// Typed payloads for each supported thread item type.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ThreadItemDetails {
+    /// Response from the agent.
+    /// Either a natural-language response or a JSON string when structured output is requested.
+    AgentMessage(AgentMessageItem),
+    /// Agent's reasoning summary.
+    Reasoning(ReasoningItem),
+    /// Tracks a command executed by the agent. The item starts when the command is
+    /// spawned, and completes when the process exits with an exit code.
+    CommandExecution(CommandExecutionItem),
+    /// Represents a set of file changes by the agent. The item is emitted only as a
+    /// completed event once the patch succeeds or fails.
+    FileChange(FileChangeItem),
+    /// Represents a call to an MCP tool. The item starts when the invocation is
+    /// dispatched and completes when the MCP server reports success or failure.
+    McpToolCall(McpToolCallItem),
+    /// Represents a call to a collab tool. The item starts when the collab tool is
+    /// invoked and completes when the collab tool reports success or failure.
+    CollabToolCall(CollabToolCallItem),
+    /// Captures a web search request. It starts when the search is kicked off
+    /// and completes when results are returned to the agent.
+    WebSearch(WebSearchItem),
+    /// Tracks the agent's running to-do list. It starts when the plan is first
+    /// issued, updates as steps change state, and completes when the turn ends.
+    TodoList(TodoListItem),
+    /// Describes a non-fatal error surfaced as an item.
+    Error(ErrorItem),
+}
+
+/// Response from the agent.
+/// Either a natural-language response or a JSON string when structured output is requested.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct AgentMessageItem {
+    pub text: String,
+}
+
+/// Agent's reasoning summary.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ReasoningItem {
+    pub text: String,
+}
+
+/// The status of a command execution.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum CommandExecutionStatus {
+    #[default]
+    InProgress,
+    Completed,
+    Failed,
+    Declined,
+}
+
+/// A command executed by the agent.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct CommandExecutionItem {
+    pub command: String,
+    pub aggregated_output: String,
+    pub exit_code: Option<i32>,
+    pub status: CommandExecutionStatus,
+}
+
+/// A set of file changes by the agent.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct FileUpdateChange {
+    pub path: String,
+    pub kind: PatchChangeKind,
+}
+
+/// The status of a file change.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum PatchApplyStatus {
+    InProgress,
+    Completed,
+    Failed,
+}
+
+/// A set of file changes by the agent.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct FileChangeItem {
+    pub changes: Vec<FileUpdateChange>,
+    pub status: PatchApplyStatus,
+}
+
+/// Indicates the type of the file change.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum PatchChangeKind {
+    Add,
+    Delete,
+    Update,
+}
+
+/// The status of an MCP tool call.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum McpToolCallStatus {
+    #[default]
+    InProgress,
+    Completed,
+    Failed,
+}
+
+/// The status of a collab tool call.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum CollabToolCallStatus {
+    #[default]
+    InProgress,
+    Completed,
+    Failed,
+}
+
+/// Supported collab tools.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum CollabTool {
+    SpawnAgent,
+    SendInput,
+    Wait,
+    CloseAgent,
+}
+
+/// The status of a collab agent.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
+#[serde(rename_all = "snake_case")]
+pub enum CollabAgentStatus {
+    PendingInit,
+    Running,
+    Interrupted,
+    Completed,
+    Errored,
+    Shutdown,
+    NotFound,
+}
+
+/// Last known state of a collab agent.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, TS)]
+pub struct CollabAgentState {
+    pub status: CollabAgentStatus,
+    pub message: Option<String>,
+}
+
+/// A call to a collab tool.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct CollabToolCallItem {
+    pub tool: CollabTool,
+    pub sender_thread_id: String,
+    pub receiver_thread_ids: Vec<String>,
+    pub prompt: Option<String>,
+    pub agents_states: HashMap<String, CollabAgentState>,
+    pub status: CollabToolCallStatus,
+}
+
+/// Result payload produced by an MCP tool invocation.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct McpToolCallItemResult {
+    // NOTE: `rmcp::model::Content` (and its `RawContent` variants) would be a
+    // more precise Rust representation of MCP content blocks. We intentionally
+    // use `serde_json::Value` here because this crate exports JSON schema + TS
+    // types (`schemars`/`ts-rs`), and the rmcp model types aren't set up to be
+    // schema/TS friendly (and would introduce heavier coupling to rmcp's Rust
+    // representations). Using `JsonValue` keeps the payload wire-shaped and
+    // easy to export.
+    pub content: Vec<JsonValue>,
+    #[serde(rename = "_meta", skip_serializing_if = "Option::is_none")]
+    #[ts(optional)]
+    pub meta: Option<JsonValue>,
+    pub structured_content: Option<JsonValue>,
+}
+
+/// Error details reported by a failed MCP tool invocation.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct McpToolCallItemError {
+    pub message: String,
+}
+
+/// A call to an MCP tool.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct McpToolCallItem {
+    pub server: String,
+    pub tool: String,
+    #[serde(default)]
+    pub arguments: JsonValue,
+    pub result: Option<McpToolCallItemResult>,
+    pub error: Option<McpToolCallItemError>,
+    pub status: McpToolCallStatus,
+}
+
+/// A web search request.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct WebSearchItem {
+    pub id: String,
+    pub query: String,
+    pub action: WebSearchAction,
+}
+
+/// An error notification.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct ErrorItem {
+    pub message: String,
+}
+
+/// An item in agent's to-do list.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct TodoItem {
+    pub text: String,
+    pub completed: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, TS)]
+pub struct TodoListItem {
+    pub items: Vec<TodoItem>,
+}
diff --git a/codex-rs/exec/src/lib.rs b/codex-rs/exec/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b56a56f1ebea4e91b300913af17d6812db35e9f4
--- /dev/null
+++ b/codex-rs/exec/src/lib.rs
@@ -0,0 +1,2337 @@
+// - In the default output mode, it is paramount that the only thing written to
+//   stdout is the final message (if any).
+// - In --json mode, stdout must be valid JSONL, one event per line.
+// For both modes, any other output must be written to stderr.
+#![recursion_limit = "256"]
+#![deny(clippy::print_stdout)]
+
+mod cli;
+mod event_processor;
+mod event_processor_with_human_output;
+pub(crate) mod event_processor_with_jsonl_output;
+pub(crate) mod exec_events;
+mod worktree;
+
+pub use cli::Cli;
+pub use cli::Command;
+pub use cli::ReviewArgs;
+use codex_app_server_client::DEFAULT_IN_PROCESS_CHANNEL_CAPACITY;
+use codex_app_server_client::EnvironmentManager;
+use codex_app_server_client::ExecServerRuntimePaths;
+use codex_app_server_client::InProcessAppServerClient;
+use codex_app_server_client::InProcessClientStartArgs;
+use codex_app_server_client::InProcessServerEvent;
+use codex_app_server_client::TypedRequestError;
+use codex_app_server_protocol::ClientRequest;
+use codex_app_server_protocol::ConfigWarningNotification;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::McpServerElicitationAction;
+use codex_app_server_protocol::McpServerElicitationRequestResponse;
+use codex_app_server_protocol::RequestId;
+use codex_app_server_protocol::ReviewStartParams;
+use codex_app_server_protocol::ReviewStartResponse;
+use codex_app_server_protocol::ReviewTarget as ApiReviewTarget;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ServerRequest;
+use codex_app_server_protocol::Thread as AppServerThread;
+use codex_app_server_protocol::ThreadForkParams;
+use codex_app_server_protocol::ThreadForkResponse;
+use codex_app_server_protocol::ThreadHistoryMode;
+use codex_app_server_protocol::ThreadItem as AppServerThreadItem;
+use codex_app_server_protocol::ThreadListParams;
+use codex_app_server_protocol::ThreadListResponse;
+use codex_app_server_protocol::ThreadReadParams;
+use codex_app_server_protocol::ThreadReadResponse;
+use codex_app_server_protocol::ThreadResumeParams;
+use codex_app_server_protocol::ThreadResumeResponse;
+use codex_app_server_protocol::ThreadSortKey;
+use codex_app_server_protocol::ThreadSource;
+use codex_app_server_protocol::ThreadSourceKind;
+use codex_app_server_protocol::ThreadStartParams;
+use codex_app_server_protocol::ThreadStartResponse;
+use codex_app_server_protocol::ThreadUnsubscribeParams;
+use codex_app_server_protocol::ThreadUnsubscribeResponse;
+use codex_app_server_protocol::TurnInterruptParams;
+use codex_app_server_protocol::TurnInterruptResponse;
+use codex_app_server_protocol::TurnStartParams;
+use codex_app_server_protocol::TurnStartResponse;
+use codex_app_server_protocol::TurnStartedNotification;
+use codex_arg0::Arg0DispatchPaths;
+use codex_cloud_config::cloud_config_bundle_loader_for_storage;
+use codex_config::CloudConfigBundleLoader;
+use codex_config::ConfigLoadError;
+use codex_config::ConfigLoadOptions;
+use codex_config::LoaderOverrides;
+use codex_config::format_config_error_with_source;
+use codex_core::StateDbHandle;
+use codex_core::check_execpolicy_for_warnings;
+use codex_core::config::Config;
+use codex_core::config::ConfigBuilder;
+use codex_core::config::ConfigOverrides;
+use codex_core::config::ConfigTomlLoadResult;
+use codex_core::config::bootstrap_auth_config;
+use codex_core::config::find_codex_home;
+use codex_core::config::load_config_toml_with_layer_stack;
+use codex_core::config::resolve_oss_provider;
+use codex_core::config::resolve_profile_v2_config_path;
+use codex_core::find_thread_meta_by_name_str;
+use codex_core::format_exec_policy_error_with_source;
+use codex_core::path_utils;
+use codex_core::read_session_meta_line;
+use codex_features::Feature;
+use codex_feedback::CodexFeedback;
+use codex_git_utils::get_git_repo_root;
+use codex_history::RolloutItem;
+use codex_history::RolloutLine;
+use codex_login::default_client::set_default_client_residency_requirement;
+use codex_login::default_client::set_default_originator;
+use codex_login::enforce_login_restrictions;
+use codex_login::is_workload_identity_selected;
+use codex_model_provider_info::LMSTUDIO_OSS_PROVIDER_ID;
+use codex_model_provider_info::OLLAMA_OSS_PROVIDER_ID;
+use codex_otel::set_parent_from_context;
+use codex_otel::traceparent_context_from_env;
+use codex_protocol::SessionId;
+use codex_protocol::ThreadId;
+use codex_protocol::config_types::ApprovalsReviewer;
+use codex_protocol::config_types::SandboxMode;
+use codex_protocol::models::ActivePermissionProfile;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::ReviewRequest;
+use codex_protocol::protocol::ReviewTarget;
+use codex_protocol::protocol::SessionConfiguredEvent;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::user_input::UserInput;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::canonicalize_existing_preserving_symlinks;
+use codex_utils_cli::SharedCliOptions;
+use codex_utils_oss::ensure_oss_provider_ready;
+use codex_utils_oss::get_default_model_for_oss_provider;
+use codex_worktree::CreateWorktree;
+use codex_worktree::WorktreeManager;
+use codex_worktree::WorktreeSettings;
+use event_processor_with_human_output::EventProcessorWithHumanOutput;
+pub use event_processor_with_jsonl_output::CodexStatus;
+pub use event_processor_with_jsonl_output::CollectedThreadEvents;
+pub use event_processor_with_jsonl_output::EventProcessorWithJsonOutput;
+pub use exec_events::AgentMessageItem;
+pub use exec_events::CollabAgentState;
+pub use exec_events::CollabAgentStatus;
+pub use exec_events::CollabTool;
+pub use exec_events::CollabToolCallItem;
+pub use exec_events::CollabToolCallStatus;
+pub use exec_events::CommandExecutionItem;
+pub use exec_events::CommandExecutionStatus;
+pub use exec_events::ErrorItem;
+pub use exec_events::FileChangeItem;
+pub use exec_events::FileUpdateChange;
+pub use exec_events::ItemCompletedEvent;
+pub use exec_events::ItemStartedEvent;
+pub use exec_events::ItemUpdatedEvent;
+pub use exec_events::McpToolCallItem;
+pub use exec_events::McpToolCallItemError;
+pub use exec_events::McpToolCallItemResult;
+pub use exec_events::McpToolCallStatus;
+pub use exec_events::PatchApplyStatus;
+pub use exec_events::PatchChangeKind;
+pub use exec_events::ReasoningItem;
+pub use exec_events::ThreadErrorEvent;
+pub use exec_events::ThreadEvent;
+pub use exec_events::ThreadItem as ExecThreadItem;
+pub use exec_events::ThreadItemDetails;
+pub use exec_events::ThreadStartedEvent;
+pub use exec_events::TodoItem;
+pub use exec_events::TodoListItem;
+pub use exec_events::TurnCompletedEvent;
+pub use exec_events::TurnFailedEvent;
+pub use exec_events::TurnStartedEvent;
+pub use exec_events::Usage;
+pub use exec_events::WebSearchItem;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::future::Future;
+use std::io::IsTerminal;
+use std::io::Read;
+use std::path::Path;
+use std::path::PathBuf;
+use supports_color::Stream;
+use tokio::sync::mpsc;
+use tracing::Instrument;
+use tracing::error;
+use tracing::field;
+use tracing::info;
+use tracing::info_span;
+use tracing::warn;
+use tracing_subscriber::EnvFilter;
+use tracing_subscriber::prelude::*;
+use uuid::Uuid;
+
+use crate::cli::Command as ExecCommand;
+use crate::event_processor::EventProcessor;
+
+const DEFAULT_ANALYTICS_ENABLED: bool = true;
+const EXEC_DEFAULT_LOG_FILTER: &str = "error,opentelemetry_sdk=off,opentelemetry_otlp=off";
+
+enum InitialOperation {
+    ForkOnly,
+    UserTurn {
+        items: Vec<UserInput>,
+        output_schema: Option<Value>,
+    },
+    Review {
+        review_request: ReviewRequest,
+    },
+}
+
+enum StdinPromptBehavior {
+    /// Read stdin only when there is no positional prompt, which is the legacy
+    /// `codex exec` behavior for `codex exec` with piped input.
+    RequiredIfPiped,
+    /// Always treat stdin as the prompt, used for the explicit `codex exec -`
+    /// sentinel and similar forced-stdin call sites.
+    Forced,
+    /// If stdin is piped alongside a positional prompt, treat stdin as
+    /// additional context to append rather than as the primary prompt.
+    OptionalAppend,
+}
+
+struct RequestIdSequencer {
+    next: i64,
+}
+
+impl RequestIdSequencer {
+    fn new() -> Self {
+        Self { next: 1 }
+    }
+
+    fn next(&mut self) -> RequestId {
+        let id = self.next;
+        self.next += 1;
+        RequestId::Integer(id)
+    }
+}
+
+struct ExecRunArgs {
+    in_process_start_args: InProcessClientStartArgs,
+    state_db: Option<StateDbHandle>,
+    command: Option<ExecCommand>,
+    config: Config,
+    resume_approvals_reviewer_override: Option<codex_app_server_protocol::ApprovalsReviewer>,
+    dangerously_bypass_approvals_and_sandbox: bool,
+    exec_span: tracing::Span,
+    images: Vec<PathBuf>,
+    json_mode: bool,
+    last_message_file: Option<PathBuf>,
+    model_provider: Option<String>,
+    managed_worktree: Option<ManagedExecWorktree>,
+    oss: bool,
+    output_schema_path: Option<PathBuf>,
+    prompt: Option<String>,
+    skip_git_repo_check: bool,
+    stderr_with_ansi: bool,
+    thread_source: ThreadSource,
+}
+
+struct ManagedExecWorktree {
+    manager: WorktreeManager,
+    checkout: PathBuf,
+    source_cwd: PathBuf,
+}
+
+fn exec_root_span() -> tracing::Span {
+    info_span!(
+        "codex.exec",
+        otel.kind = "internal",
+        thread.id = field::Empty,
+        turn.id = field::Empty,
+    )
+}
+
+fn exec_stderr_env_filter() -> EnvFilter {
+    // OTEL export is best-effort; keep exporter self-diagnostics out of
+    // headless command output unless the caller opts in with RUST_LOG.
+    EnvFilter::try_from_default_env()
+        .or_else(|_| EnvFilter::try_new(EXEC_DEFAULT_LOG_FILTER))
+        .unwrap_or_else(|_| EnvFilter::new("error"))
+}
+
+pub async fn run_main(cli: Cli, arg0_paths: Arg0DispatchPaths) -> anyhow::Result<()> {
+    if let Err(err) = set_default_originator("codex_exec".to_string()) {
+        tracing::warn!(?err, "Failed to set codex exec originator override {err:?}");
+    }
+
+    let Cli {
+        mut command,
+        strict_config,
+        shared,
+        thread_source,
+        skip_git_repo_check,
+        ephemeral,
+        ignore_user_config,
+        ignore_rules,
+        color,
+        last_message_file,
+        json: json_mode,
+        prompt,
+        output_schema: output_schema_path,
+        mut config_overrides,
+    } = cli;
+    let mut shared = shared.into_inner();
+    shared.take_auto_review_config_overrides(&mut config_overrides);
+    let SharedCliOptions {
+        images,
+        model: model_cli_arg,
+        oss,
+        oss_provider,
+        config_profile_v2,
+        sandbox_mode: sandbox_mode_cli_arg,
+        auto_review: _,
+        dangerously_bypass_approvals_and_sandbox,
+        bypass_hook_trust,
+        cwd,
+        mut add_dir,
+        worktree,
+    } = shared;
+
+    if worktree {
+        if ignore_user_config {
+            anyhow::bail!("--worktree cannot be combined with --ignore-user-config");
+        }
+        if ephemeral {
+            anyhow::bail!("--worktree cannot be combined with --ephemeral");
+        }
+        match command.as_ref() {
+            Some(ExecCommand::Resume(_)) => {
+                anyhow::bail!("--worktree is not supported with `codex exec resume`");
+            }
+            Some(ExecCommand::Review(_)) => {
+                anyhow::bail!("--worktree is not supported with `codex exec review`");
+            }
+            Some(ExecCommand::Fork(_)) | None => {}
+        }
+    }
+
+    let (_stdout_with_ansi, stderr_with_ansi) = match color {
+        cli::Color::Always => (true, true),
+        cli::Color::Never => (false, false),
+        cli::Color::Auto => (
+            supports_color::on_cached(Stream::Stdout).is_some(),
+            supports_color::on_cached(Stream::Stderr).is_some(),
+        ),
+    };
+    let fmt_layer = tracing_subscriber::fmt::layer()
+        .with_ansi(stderr_with_ansi)
+        .with_writer(std::io::stderr)
+        .with_filter(exec_stderr_env_filter());
+
+    let sandbox_mode = if dangerously_bypass_approvals_and_sandbox {
+        Some(SandboxMode::DangerFullAccess)
+    } else {
+        sandbox_mode_cli_arg.map(Into::<SandboxMode>::into)
+    };
+
+    // Parse `-c` overrides from the CLI.
+    let cli_kv_overrides = match config_overrides.parse_overrides() {
+        Ok(v) => v,
+        #[allow(clippy::print_stderr)]
+        Err(e) => {
+            eprintln!("Error parsing -c overrides: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    let mut resolved_cwd = cwd.clone();
+    let mut config_cwd = match resolved_cwd.as_deref() {
+        Some(path) => {
+            AbsolutePathBuf::from_absolute_path(canonicalize_existing_preserving_symlinks(path)?)?
+        }
+        None => AbsolutePathBuf::current_dir()?,
+    };
+
+    // we load config.toml here to determine project state.
+    #[allow(clippy::print_stderr)]
+    let codex_home = match find_codex_home() {
+        Ok(codex_home) => codex_home,
+        Err(err) => {
+            eprintln!("Error finding codex home: {err}");
+            std::process::exit(1);
+        }
+    };
+    let user_config_path = config_profile_v2
+        .as_ref()
+        .map(|profile_v2| resolve_profile_v2_config_path(&codex_home, profile_v2));
+    let loader_overrides = LoaderOverrides {
+        user_config_path,
+        user_config_profile: config_profile_v2,
+        ignore_user_config,
+        ignore_user_and_project_exec_policy_rules: ignore_rules,
+        ..Default::default()
+    };
+
+    if worktree
+        && EnvironmentManager::prepare_from_codex_home(&codex_home)
+            .await?
+            .default_environment_is_remote()
+    {
+        anyhow::bail!("--worktree requires local execution");
+    }
+
+    let managed_worktree = if worktree {
+        let gate_bootstrap = load_bootstrap_config_or_exit(
+            &codex_home,
+            /*cwd*/ None,
+            cli_kv_overrides.clone(),
+            loader_overrides.clone(),
+            strict_config,
+            CloudConfigBundleLoader::default(),
+        )
+        .await;
+        let gate_cloud_config = cloud_config_bundle_loader_for_storage(
+            bootstrap_auth_config(&codex_home, &gate_bootstrap)?,
+            /*enable_codex_api_key_env*/ false,
+        )
+        .await?;
+        let gate_config = ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .cli_overrides(cli_kv_overrides.clone())
+            .loader_overrides(LoaderOverrides {
+                ignore_project_config: true,
+                ..loader_overrides.clone()
+            })
+            .fallback_cwd(Some(config_cwd.to_path_buf()))
+            .strict_config(strict_config)
+            .cloud_config_bundle(gate_cloud_config.clone())
+            .build()
+            .await?;
+        if !gate_config.features.enabled(Feature::Worktrees) {
+            anyhow::bail!(
+                "--worktree requires the worktrees feature; enable it with --enable worktrees"
+            );
+        }
+        if let Some(ExecCommand::Fork(args)) = command.as_mut() {
+            let saved_cwd = worktree::fork_source(
+                args,
+                &gate_config,
+                &arg0_paths,
+                &cli_kv_overrides,
+                &loader_overrides,
+                gate_cloud_config.clone(),
+                strict_config,
+            )
+            .await?;
+            if resolved_cwd.is_none() {
+                config_cwd = AbsolutePathBuf::from_absolute_path(saved_cwd)?;
+            }
+        }
+        let source_config = ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .cli_overrides(cli_kv_overrides.clone())
+            .loader_overrides(LoaderOverrides {
+                ignore_project_config: true,
+                ..loader_overrides.clone()
+            })
+            .fallback_cwd(Some(config_cwd.to_path_buf()))
+            .strict_config(strict_config)
+            .cloud_config_bundle(gate_cloud_config)
+            .build()
+            .await?;
+        if source_config.active_project.is_untrusted() {
+            anyhow::bail!("--worktree requires a source that is not explicitly untrusted");
+        }
+        for path in &mut add_dir {
+            if path.is_relative() {
+                *path = std::env::current_dir()?.join(&*path);
+            }
+        }
+        // Allocation belongs to the host, not this session's project, profile, or overrides.
+        let host_config = load_bootstrap_config_or_exit(
+            &codex_home,
+            /*cwd*/ None,
+            Vec::new(),
+            LoaderOverrides::default(),
+            strict_config,
+            CloudConfigBundleLoader::default(),
+        )
+        .await;
+        let settings =
+            WorktreeSettings::for_cli(&codex_home, host_config.config_toml.desktop.as_ref())?;
+        let manager = WorktreeManager::new(settings);
+        let checkout = manager.create(&CreateWorktree {
+            source_cwd: config_cwd.as_path().to_path_buf(),
+            base: None,
+        })?;
+        resolved_cwd = Some(checkout.cwd.clone());
+        config_cwd = AbsolutePathBuf::from_absolute_path(checkout.cwd.clone())?;
+        Some(ManagedExecWorktree {
+            manager,
+            checkout: checkout.root,
+            source_cwd: checkout.source_cwd,
+        })
+    } else {
+        None
+    };
+    let bootstrap_config = load_bootstrap_config_or_exit(
+        &codex_home,
+        Some(&config_cwd),
+        cli_kv_overrides.clone(),
+        loader_overrides.clone(),
+        strict_config,
+        CloudConfigBundleLoader::default(),
+    )
+    .await;
+    let bootstrap_config_toml = &bootstrap_config.config_toml;
+    let bootstrap_auth_config = bootstrap_auth_config(&codex_home, &bootstrap_config)?;
+    // API keys cannot fetch workspace-managed configuration. Preserve the
+    // existing ChatGPT bootstrap identity even when model requests allow
+    // CODEX_API_KEY.
+    let cloud_config_bundle = cloud_config_bundle_loader_for_storage(
+        bootstrap_auth_config,
+        /*enable_codex_api_key_env*/ false,
+    )
+    .await?;
+    if let Some(worktree) = managed_worktree.as_ref() {
+        // Destination auth can fetch source policy that the host bootstrap could not.
+        let source_config = ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .cli_overrides(cli_kv_overrides.clone())
+            .loader_overrides(LoaderOverrides {
+                ignore_project_config: true,
+                ..loader_overrides.clone()
+            })
+            .fallback_cwd(Some(worktree.source_cwd.clone()))
+            .strict_config(strict_config)
+            .cloud_config_bundle(cloud_config_bundle.clone())
+            .build()
+            .await?;
+        if source_config.active_project.is_untrusted() {
+            anyhow::bail!(
+                "--worktree requires a source that is not explicitly untrusted; unused checkout at {} remains. Remove it manually with `git worktree remove` when safe",
+                worktree.checkout.display()
+            );
+        }
+    }
+    let run_cli_overrides = cli_kv_overrides.clone();
+    let run_loader_overrides = loader_overrides.clone();
+    let run_cloud_config_bundle = cloud_config_bundle.clone();
+
+    let model_provider = if oss {
+        let bootstrap_config_with_cloud_config;
+        let config_toml_for_oss = if oss_provider.is_none() {
+            // The first load intentionally skips cloud config so we can read
+            // auth/base-url settings needed to fetch the bundle. If OSS mode
+            // needs a default provider from config, reload with the bundle.
+            bootstrap_config_with_cloud_config = load_bootstrap_config_or_exit(
+                &codex_home,
+                Some(&config_cwd),
+                cli_kv_overrides.clone(),
+                loader_overrides.clone(),
+                strict_config,
+                cloud_config_bundle.clone(),
+            )
+            .await;
+            &bootstrap_config_with_cloud_config.config_toml
+        } else {
+            bootstrap_config_toml
+        };
+
+        let resolved = resolve_oss_provider(oss_provider.as_deref(), config_toml_for_oss);
+
+        if let Some(provider) = resolved {
+            Some(provider)
+        } else {
+            return Err(anyhow::anyhow!(
+                "No default OSS provider configured. Use --local-provider=provider or set oss_provider to one of: {LMSTUDIO_OSS_PROVIDER_ID}, {OLLAMA_OSS_PROVIDER_ID} in config.toml"
+            ));
+        }
+    } else {
+        None // No OSS mode enabled
+    };
+
+    // When using `--oss`, let the bootstrapper pick the model based on selected provider
+    let model = if let Some(model) = model_cli_arg {
+        Some(model)
+    } else if oss {
+        model_provider
+            .as_ref()
+            .and_then(|provider_id| get_default_model_for_oss_provider(provider_id))
+            .map(std::borrow::ToOwned::to_owned)
+    } else {
+        None // No model specified, will use the default.
+    };
+
+    let overrides = ConfigOverrides {
+        model,
+        review_model: None,
+        // Default to never ask for approvals in headless mode. Rebuild below if
+        // the fully resolved reviewer is AutoReview.
+        approval_policy: Some(AskForApproval::Never),
+        approvals_reviewer: None,
+        sandbox_mode,
+        permission_profile: None,
+        default_permissions: None,
+        persisted_permission_profile_id: None,
+        cwd: resolved_cwd,
+        workspace_roots: None,
+        model_provider: model_provider.clone(),
+        service_tier: None,
+        codex_self_exe: arg0_paths.codex_self_exe.clone(),
+        codex_linux_sandbox_exe: arg0_paths.codex_linux_sandbox_exe.clone(),
+        main_execve_wrapper_exe: arg0_paths.main_execve_wrapper_exe.clone(),
+        default_zsh_path: None,
+        base_instructions: None,
+        developer_instructions: None,
+        personality: None,
+        compact_prompt: None,
+        show_raw_agent_reasoning: oss.then_some(true),
+        tools_web_search_request: None,
+        ephemeral: ephemeral.then_some(true),
+        bypass_hook_trust: bypass_hook_trust.then_some(true),
+        additional_writable_roots: add_dir,
+    };
+
+    let build_config = |overrides| {
+        ConfigBuilder::default()
+            .codex_home(codex_home.to_path_buf())
+            .cli_overrides(cli_kv_overrides.clone())
+            .harness_overrides(overrides)
+            .loader_overrides(loader_overrides.clone())
+            .strict_config(strict_config)
+            .cloud_config_bundle(cloud_config_bundle.clone())
+            .build()
+    };
+    let config = build_exec_config(
+        overrides,
+        dangerously_bypass_approvals_and_sandbox,
+        build_config,
+    )
+    .await?;
+    let resume_approvals_reviewer_override = cli_kv_overrides
+        .iter()
+        .any(|(key, _)| key == "approvals_reviewer")
+        .then(|| config.approvals_reviewer.into());
+
+    #[allow(clippy::print_stderr)]
+    match check_execpolicy_for_warnings(&config.config_layer_stack).await {
+        Ok(None) => {}
+        Ok(Some(err)) | Err(err) => {
+            eprintln!(
+                "Error loading rules:\n{}",
+                format_exec_policy_error_with_source(&err)
+            );
+            std::process::exit(1);
+        }
+    }
+
+    set_default_client_residency_requirement(config.enforce_residency.value());
+
+    if !is_workload_identity_selected()
+        && let Err(err) = enforce_login_restrictions(&config.auth_config()).await
+    {
+        eprintln!("{err}");
+        std::process::exit(1);
+    }
+
+    let otel = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        codex_core::otel_init::build_provider(
+            &config,
+            env!("CARGO_PKG_VERSION"),
+            /*service_name_override*/ None,
+            DEFAULT_ANALYTICS_ENABLED,
+        )
+    })) {
+        Ok(Ok(otel)) => otel,
+        Ok(Err(e)) => {
+            eprintln!("Could not create otel exporter: {e}");
+            None
+        }
+        Err(_) => {
+            eprintln!("Could not create otel exporter: panicked during initialization");
+            None
+        }
+    };
+    codex_core::otel_init::record_process_start(otel.as_ref(), "codex_exec");
+    codex_core::otel_init::install_sqlite_telemetry(otel.as_ref(), "codex_exec");
+
+    let otel_logger_layer = otel.as_ref().and_then(|o| o.logger_layer());
+
+    let otel_tracing_layer = otel.as_ref().and_then(|o| o.tracing_layer());
+
+    let _ = tracing_subscriber::registry()
+        .with(fmt_layer)
+        .with(otel_tracing_layer)
+        .with(otel_logger_layer)
+        .try_init();
+
+    let exec_span = exec_root_span();
+    if let Some(context) = traceparent_context_from_env() {
+        set_parent_from_context(&exec_span, context);
+    }
+    let config_warnings: Vec<ConfigWarningNotification> = config
+        .startup_warnings
+        .iter()
+        .map(|warning| ConfigWarningNotification {
+            summary: warning.clone(),
+            details: None,
+            path: None,
+            range: None,
+        })
+        .collect();
+    let local_runtime_paths = ExecServerRuntimePaths::from_optional_paths(
+        arg0_paths.codex_self_exe.clone(),
+        arg0_paths.codex_linux_sandbox_exe.clone(),
+    )?;
+    #[cfg(target_os = "macos")]
+    let local_runtime_paths = local_runtime_paths.with_allowed_symlinked_codex_home(
+        codex_config::allowed_symlinked_codex_home(&config.config_layer_stack, &config.codex_home),
+    );
+    let state_db = codex_core::init_state_db(&config).await;
+    let environment_manager = if run_loader_overrides.ignore_user_config {
+        EnvironmentManager::from_env(Some(local_runtime_paths), config.http_client_factory())
+            .await?
+    } else {
+        EnvironmentManager::from_codex_home(
+            config.codex_home.clone(),
+            Some(local_runtime_paths),
+            config.http_client_factory(),
+        )
+        .await?
+    };
+    let in_process_start_args = InProcessClientStartArgs {
+        arg0_paths,
+        config: std::sync::Arc::new(config.clone()),
+        cli_overrides: run_cli_overrides,
+        loader_overrides: run_loader_overrides,
+        strict_config,
+        cloud_config_bundle: run_cloud_config_bundle,
+        feedback: CodexFeedback::new(),
+        log_db: None,
+        state_db: state_db.clone(),
+        environment_manager: std::sync::Arc::new(environment_manager),
+        config_warnings,
+        session_source: SessionSource::Exec,
+        enable_codex_api_key_env: true,
+        client_name: "codex_exec".to_string(),
+        client_version: env!("CARGO_PKG_VERSION").to_string(),
+        experimental_api: true,
+        mcp_server_openai_form_elicitation: false,
+        opt_out_notification_methods: Vec::new(),
+        channel_capacity: DEFAULT_IN_PROCESS_CHANNEL_CAPACITY,
+    };
+    run_exec_session(ExecRunArgs {
+        in_process_start_args,
+        state_db,
+        command,
+        config,
+        resume_approvals_reviewer_override,
+        dangerously_bypass_approvals_and_sandbox,
+        exec_span: exec_span.clone(),
+        images,
+        json_mode,
+        last_message_file,
+        model_provider,
+        managed_worktree,
+        oss,
+        output_schema_path,
+        prompt,
+        skip_git_repo_check,
+        stderr_with_ansi,
+        thread_source: thread_source.map(Into::into).unwrap_or(ThreadSource::User),
+    })
+    .instrument(exec_span)
+    .await
+}
+
+async fn build_exec_config<BuildConfig, BuildFuture>(
+    overrides: ConfigOverrides,
+    preserve_headless_approval_policy: bool,
+    build_config: BuildConfig,
+) -> std::io::Result<Config>
+where
+    BuildConfig: Fn(ConfigOverrides) -> BuildFuture,
+    BuildFuture: Future<Output = std::io::Result<Config>>,
+{
+    let build_without_headless_approval_policy = || {
+        build_config(ConfigOverrides {
+            approval_policy: None,
+            ..overrides.clone()
+        })
+    };
+    match build_config(overrides.clone()).await {
+        Ok(config)
+            if config.approvals_reviewer == ApprovalsReviewer::AutoReview
+                && !preserve_headless_approval_policy =>
+        {
+            build_without_headless_approval_policy().await
+        }
+        Ok(config) => Ok(config),
+        Err(headless_error) if !preserve_headless_approval_policy => {
+            match build_without_headless_approval_policy().await {
+                Ok(config) if config.approvals_reviewer == ApprovalsReviewer::AutoReview => {
+                    Ok(config)
+                }
+                Ok(_) | Err(_) => Err(headless_error),
+            }
+        }
+        Err(headless_error) => Err(headless_error),
+    }
+}
+
+#[allow(clippy::print_stderr)]
+async fn load_bootstrap_config_or_exit(
+    codex_home: &Path,
+    cwd: Option<&AbsolutePathBuf>,
+    cli_kv_overrides: Vec<(String, codex_config::TomlValue)>,
+    loader_overrides: LoaderOverrides,
+    strict_config: bool,
+    cloud_config_bundle: CloudConfigBundleLoader,
+) -> ConfigTomlLoadResult {
+    match load_config_toml_with_layer_stack(
+        codex_home,
+        cwd,
+        cli_kv_overrides,
+        ConfigLoadOptions {
+            loader_overrides,
+            strict_config,
+            cloud_config_bundle,
+        },
+    )
+    .await
+    {
+        Ok(config_toml) => config_toml,
+        Err(err) => {
+            let config_error = err
+                .get_ref()
+                .and_then(|err| err.downcast_ref::<ConfigLoadError>())
+                .map(ConfigLoadError::config_error);
+            if let Some(config_error) = config_error {
+                eprintln!(
+                    "Error loading config.toml:\n{}",
+                    format_config_error_with_source(config_error)
+                );
+            } else {
+                eprintln!("Error loading config.toml: {err}");
+            }
+            std::process::exit(1);
+        }
+    }
+}
+
+async fn run_exec_session(args: ExecRunArgs) -> anyhow::Result<()> {
+    let ExecRunArgs {
+        in_process_start_args,
+        state_db,
+        command,
+        config,
+        resume_approvals_reviewer_override,
+        dangerously_bypass_approvals_and_sandbox,
+        exec_span,
+        images,
+        json_mode,
+        last_message_file,
+        model_provider,
+        managed_worktree,
+        oss,
+        output_schema_path,
+        prompt,
+        skip_git_repo_check,
+        stderr_with_ansi,
+        thread_source,
+    } = args;
+
+    let mut event_processor: Box<dyn EventProcessor> = match json_mode {
+        true => Box::new(EventProcessorWithJsonOutput::new(last_message_file.clone())),
+        _ => Box::new(EventProcessorWithHumanOutput::create_with_ansi(
+            stderr_with_ansi,
+            &config,
+            last_message_file.clone(),
+        )),
+    };
+    if oss {
+        // We're in the oss section, so provider_id should be Some
+        // Let's handle None case gracefully though just in case
+        let provider_id = match model_provider.as_ref() {
+            Some(id) => id,
+            None => {
+                error!("OSS provider unexpectedly not set when oss flag is used");
+                return Err(anyhow::anyhow!(
+                    "OSS provider not set but oss flag was used"
+                ));
+            }
+        };
+        ensure_oss_provider_ready(provider_id, &config)
+            .await
+            .map_err(|e| anyhow::anyhow!("OSS setup failed: {e}"))?;
+    }
+
+    let default_cwd = config.cwd.to_path_buf();
+    let default_approval_policy = config.permissions.approval_policy.value();
+    let default_effort = config.model_reasoning_effort.clone();
+
+    let (initial_operation, prompt_summary) = match (command.as_ref(), prompt, images) {
+        (Some(ExecCommand::Review(review_cli)), _, _) => {
+            let review_request = build_review_request(review_cli)?;
+            let summary = codex_core::review_prompts::user_facing_hint(&review_request.target);
+            (InitialOperation::Review { review_request }, summary)
+        }
+        (Some(ExecCommand::Resume(args)), root_prompt, imgs) => {
+            let prompt_arg = args
+                .prompt
+                .clone()
+                .or_else(|| {
+                    if args.last {
+                        args.session_id.clone()
+                    } else {
+                        None
+                    }
+                })
+                .or(root_prompt);
+            let prompt_text = resolve_prompt(prompt_arg);
+            let mut items: Vec<UserInput> = imgs
+                .into_iter()
+                .chain(args.images.iter().cloned())
+                .map(|path| UserInput::LocalImage { path, detail: None })
+                .collect();
+            items.push(UserInput::Text {
+                text: prompt_text.clone(),
+                // CLI input doesn't track UI element ranges, so none are available here.
+                text_elements: Vec::new(),
+            });
+            let output_schema = load_output_schema(output_schema_path.clone());
+            (
+                InitialOperation::UserTurn {
+                    items,
+                    output_schema,
+                },
+                prompt_text,
+            )
+        }
+        (Some(ExecCommand::Fork(args)), root_prompt, imgs) => {
+            let prompt_arg = args.prompt.clone().or(root_prompt);
+            if let Some(prompt_arg) = prompt_arg {
+                let prompt_text = resolve_prompt(Some(prompt_arg));
+                let mut items: Vec<UserInput> = imgs
+                    .into_iter()
+                    .chain(args.images.iter().cloned())
+                    .map(|path| UserInput::LocalImage { path, detail: None })
+                    .collect();
+                items.push(UserInput::Text {
+                    text: prompt_text.clone(),
+                    text_elements: Vec::new(),
+                });
+                let output_schema = load_output_schema(output_schema_path);
+                (
+                    InitialOperation::UserTurn {
+                        items,
+                        output_schema,
+                    },
+                    prompt_text,
+                )
+            } else if !imgs.is_empty() || !args.images.is_empty() {
+                anyhow::bail!("Forking with images requires a prompt");
+            } else if output_schema_path.is_some() || last_message_file.is_some() {
+                anyhow::bail!("Forking with output options requires a prompt");
+            } else if config.ephemeral {
+                anyhow::bail!("Ephemeral forks require a prompt");
+            } else {
+                (InitialOperation::ForkOnly, String::new())
+            }
+        }
+        (None, root_prompt, imgs) => {
+            let prompt_text = resolve_root_prompt(root_prompt);
+            let mut items: Vec<UserInput> = imgs
+                .into_iter()
+                .map(|path| UserInput::LocalImage { path, detail: None })
+                .collect();
+            items.push(UserInput::Text {
+                text: prompt_text.clone(),
+                // CLI input doesn't track UI element ranges, so none are available here.
+                text_elements: Vec::new(),
+            });
+            let output_schema = load_output_schema(output_schema_path);
+            (
+                InitialOperation::UserTurn {
+                    items,
+                    output_schema,
+                },
+                prompt_text,
+            )
+        }
+    };
+
+    // When --yolo (dangerously_bypass_approvals_and_sandbox) is set, also skip the git repo check
+    // since the user is explicitly running in an externally sandboxed environment.
+    if !skip_git_repo_check
+        && !dangerously_bypass_approvals_and_sandbox
+        && get_git_repo_root(&default_cwd).is_none()
+    {
+        eprintln!("Not inside a trusted directory and --skip-git-repo-check was not specified.");
+        std::process::exit(1);
+    }
+
+    let mut request_ids = RequestIdSequencer::new();
+    let mut client = InProcessAppServerClient::start(in_process_start_args)
+        .await
+        .map_err(|err| {
+            anyhow::anyhow!("failed to initialize in-process app-server client: {err}")
+        })?;
+
+    // Resolve resume and fork through existing app-server thread lifecycle APIs.
+    let (primary_thread_id, fallback_session_configured) = if let Some(ExecCommand::Resume(args)) =
+        command.as_ref()
+    {
+        if let Some(thread_id) =
+            resolve_resume_thread_id(&client, &config, state_db.as_ref(), args).await?
+        {
+            let response: ThreadResumeResponse = send_request_with_response(
+                &client,
+                ClientRequest::ThreadResume {
+                    request_id: request_ids.next(),
+                    params: thread_resume_params_from_config(
+                        &config,
+                        thread_id,
+                        resume_approvals_reviewer_override,
+                    ),
+                },
+                "thread/resume",
+            )
+            .await
+            .map_err(anyhow::Error::msg)?;
+            let session_configured =
+                session_configured_from_thread_resume_response(&response, &config)
+                    .map_err(anyhow::Error::msg)?;
+            (session_configured.thread_id, session_configured)
+        } else {
+            let response = start_thread(&client, &mut request_ids, &config, &thread_source)
+                .await
+                .map_err(anyhow::Error::msg)?;
+            let session_configured =
+                session_configured_from_thread_start_response(&response, &config)
+                    .map_err(anyhow::Error::msg)?;
+            (session_configured.thread_id, session_configured)
+        }
+    } else if let Some(ExecCommand::Fork(args)) = command.as_ref() {
+        let source_args = crate::cli::ResumeArgs {
+            session_id: Some(args.session_id.clone()),
+            last: false,
+            all: true,
+            images: Vec::new(),
+            prompt: None,
+        };
+        let source_thread_id =
+            resolve_resume_thread_id(&client, &config, state_db.as_ref(), &source_args)
+                .await?
+                .ok_or_else(|| anyhow::anyhow!("Session not found: {}", args.session_id))?;
+        let permissions = permissions_selection_from_config(&config);
+        let sandbox = permissions.is_none().then(|| {
+            sandbox_mode_from_permission_profile(
+                &config.permissions.effective_permission_profile(),
+                config.cwd.as_path(),
+            )
+        });
+        let response: ThreadForkResponse = send_request_with_response(
+            &client,
+            ClientRequest::ThreadFork {
+                request_id: request_ids.next(),
+                params: ThreadForkParams {
+                    thread_id: source_thread_id,
+                    model: config.model.clone(),
+                    model_provider: Some(config.model_provider_id.clone()),
+                    cwd: Some(config.cwd.to_string_lossy().to_string()),
+                    runtime_workspace_roots: Some(config.workspace_roots.clone()),
+                    approval_policy: Some(config.permissions.approval_policy.value().into()),
+                    approvals_reviewer: resume_approvals_reviewer_override,
+                    sandbox: sandbox.flatten(),
+                    permissions,
+                    config: thread_config_overrides_from_config(&config),
+                    ephemeral: config.ephemeral,
+                    thread_source: Some(thread_source.clone()),
+                    exclude_turns: true,
+                    defer_goal_continuation: !config.ephemeral,
+                    ..ThreadForkParams::default()
+                },
+            },
+            "thread/fork",
+        )
+        .await
+        .map_err(anyhow::Error::msg)?;
+        let session_configured = session_configured_from_thread_response(
+            &response.thread.session_id,
+            &response.thread.id,
+            response.thread.forked_from_id.as_deref(),
+            response.thread.parent_thread_id.as_deref(),
+            response.thread.thread_source.clone().map(Into::into),
+            response.thread.name.clone(),
+            response.thread.path.clone(),
+            response.model,
+            response.model_provider,
+            response.service_tier,
+            response.approval_policy.to_core(),
+            response.approvals_reviewer.to_core(),
+            config.permissions.effective_permission_profile(),
+            response.active_permission_profile.map(Into::into),
+            response.cwd,
+            response.reasoning_effort,
+        )
+        .map_err(anyhow::Error::msg)?;
+        (session_configured.thread_id, session_configured)
+    } else {
+        let response = start_thread(&client, &mut request_ids, &config, &thread_source)
+            .await
+            .map_err(anyhow::Error::msg)?;
+        let session_configured = session_configured_from_thread_start_response(&response, &config)
+            .map_err(anyhow::Error::msg)?;
+        (session_configured.thread_id, session_configured)
+    };
+
+    if let Some(worktree) = managed_worktree.as_ref() {
+        worktree
+            .manager
+            .bind_thread(&worktree.checkout, &primary_thread_id.to_string())?;
+    }
+
+    let primary_thread_id_for_span = primary_thread_id.to_string();
+    // Use the start/resume response as the authoritative bootstrap payload.
+    // Waiting for a later streamed `SessionConfigured` event adds up to 10s of
+    // avoidable startup latency on the in-process path.
+    let session_configured = fallback_session_configured;
+
+    exec_span.record("thread.id", primary_thread_id_for_span.as_str());
+
+    // Print the effective configuration and initial request so users can see what Codex
+    // is using.
+    event_processor.print_config_summary(&config, &prompt_summary, &session_configured);
+    if !json_mode
+        && let Some(message) =
+            codex_core::config::system_bwrap_warning(config.permissions.permission_profile())
+    {
+        event_processor.process_warning(message);
+    }
+
+    info!("Codex initialized with event: {session_configured:?}");
+
+    let (interrupt_tx, mut interrupt_rx) = mpsc::unbounded_channel::<()>();
+    tokio::spawn(async move {
+        if tokio::signal::ctrl_c().await.is_ok() {
+            tracing::debug!("Keyboard interrupt");
+            let _ = interrupt_tx.send(());
+        }
+    });
+
+    let task_id = match initial_operation {
+        InitialOperation::ForkOnly => {
+            request_shutdown(&client, &mut request_ids, &primary_thread_id_for_span)
+                .await
+                .map_err(anyhow::Error::msg)?;
+            client
+                .shutdown()
+                .await
+                .map_err(|err| anyhow::anyhow!("in-process app-server shutdown failed: {err}"))?;
+            event_processor.print_final_output();
+            return Ok(());
+        }
+        InitialOperation::UserTurn {
+            items,
+            output_schema,
+        } => {
+            let response: TurnStartResponse = send_request_with_response(
+                &client,
+                ClientRequest::TurnStart {
+                    request_id: request_ids.next(),
+                    params: TurnStartParams {
+                        disabled_plugin_ids: None,
+                        thread_id: primary_thread_id_for_span.clone(),
+                        turn_trigger: None,
+                        client_user_message_id: None,
+                        input: items.into_iter().map(Into::into).collect(),
+                        tool_output: None,
+                        responsesapi_client_metadata: None,
+                        additional_context: None,
+                        environments: None,
+                        cwd: Some(default_cwd),
+                        runtime_workspace_roots: None,
+                        approval_policy: Some(default_approval_policy.into()),
+                        approvals_reviewer: None,
+                        sandbox_policy: None,
+                        permissions: None,
+                        model: None,
+                        service_tier: None,
+                        service_tier_for_turn: None,
+                        effort: default_effort,
+                        summary: None,
+                        personality: None,
+                        output_schema,
+                        collaboration_mode: None,
+                        multi_agent_mode: None,
+                        cyber_access_program: None,
+                    },
+                },
+                "turn/start",
+            )
+            .await
+            .map_err(anyhow::Error::msg)?;
+            let task_id = response.turn.id;
+            info!("Sent prompt with event ID: {task_id}");
+            task_id
+        }
+        InitialOperation::Review { review_request } => {
+            let response: ReviewStartResponse = send_request_with_response(
+                &client,
+                ClientRequest::ReviewStart {
+                    request_id: request_ids.next(),
+                    params: ReviewStartParams {
+                        thread_id: primary_thread_id_for_span.clone(),
+                        target: review_target_to_api(review_request.target),
+                        delivery: None,
+                    },
+                },
+                "review/start",
+            )
+            .await
+            .map_err(anyhow::Error::msg)?;
+            let _ = event_processor.process_server_notification(ServerNotification::TurnStarted(
+                TurnStartedNotification {
+                    thread_id: response.review_thread_id.clone(),
+                    turn: response.turn.clone(),
+                },
+            ));
+            let task_id = response.turn.id;
+            info!("Sent review request with event ID: {task_id}");
+            task_id
+        }
+    };
+    exec_span.record("turn.id", task_id.as_str());
+
+    // Run the loop until the task is complete.
+    // Track whether a fatal error was reported by the server so we can
+    // exit with a non-zero status for automation-friendly signaling.
+    let mut error_seen = false;
+    let mut interrupt_channel_open = true;
+    let primary_thread_id_for_requests = primary_thread_id.to_string();
+    loop {
+        let server_event = tokio::select! {
+            maybe_interrupt = interrupt_rx.recv(), if interrupt_channel_open => {
+                if maybe_interrupt.is_none() {
+                    interrupt_channel_open = false;
+                    continue;
+                }
+                if let Err(err) = send_request_with_response::<TurnInterruptResponse>(
+                    &client,
+                    ClientRequest::TurnInterrupt {
+                        request_id: request_ids.next(),
+                        params: TurnInterruptParams {
+                            thread_id: primary_thread_id_for_requests.clone(),
+                            turn_id: task_id.clone(),
+                        },
+                    },
+                    "turn/interrupt",
+                )
+                .await
+                {
+                    warn!("turn/interrupt failed: {err}");
+                }
+                continue;
+            }
+            maybe_event = client.next_event() => maybe_event,
+        };
+
+        let Some(server_event) = server_event else {
+            break;
+        };
+
+        match server_event {
+            InProcessServerEvent::ServerRequest(request) => {
+                handle_server_request(&client, *request, &mut error_seen).await;
+            }
+            InProcessServerEvent::ServerNotification(notification) => {
+                let mut notification = *notification;
+                if let ServerNotification::Error(payload) = &notification {
+                    if payload.thread_id == primary_thread_id_for_requests
+                        && payload.turn_id == task_id
+                        && !payload.will_retry
+                    {
+                        error_seen = true;
+                    }
+                } else if let ServerNotification::TurnCompleted(payload) = &notification
+                    && payload.thread_id == primary_thread_id_for_requests
+                    && payload.turn.id == task_id
+                    && matches!(
+                        payload.turn.status,
+                        codex_app_server_protocol::TurnStatus::Failed
+                            | codex_app_server_protocol::TurnStatus::Interrupted
+                    )
+                {
+                    error_seen = true;
+                }
+
+                if should_process_notification(
+                    &notification,
+                    &primary_thread_id_for_requests,
+                    &task_id,
+                ) {
+                    maybe_backfill_turn_completed_items(
+                        config.ephemeral,
+                        &client,
+                        &mut request_ids,
+                        &mut notification,
+                    )
+                    .await;
+
+                    match event_processor.process_server_notification(notification) {
+                        CodexStatus::Running => {}
+                        CodexStatus::InitiateShutdown => {
+                            if let Err(err) = request_shutdown(
+                                &client,
+                                &mut request_ids,
+                                &primary_thread_id_for_requests,
+                            )
+                            .await
+                            {
+                                warn!("thread/unsubscribe failed during shutdown: {err}");
+                            }
+                            break;
+                        }
+                    }
+                }
+            }
+            InProcessServerEvent::Lagged { skipped } => {
+                let message = lagged_event_warning_message(skipped);
+                warn!("{message}");
+                event_processor.process_warning(message);
+            }
+        }
+    }
+
+    if let Err(err) = client.shutdown().await {
+        warn!("in-process app-server shutdown failed: {err}");
+    }
+    event_processor.print_final_output();
+    if error_seen {
+        std::process::exit(1);
+    }
+
+    Ok(())
+}
+
+async fn start_thread(
+    client: &InProcessAppServerClient,
+    request_ids: &mut RequestIdSequencer,
+    config: &Config,
+    thread_source: &ThreadSource,
+) -> Result<ThreadStartResponse, String> {
+    let mut params = thread_start_params_from_config(config, thread_source);
+    loop {
+        match client
+            .request_typed(ClientRequest::ThreadStart {
+                request_id: request_ids.next(),
+                params: params.clone(),
+            })
+            .await
+        {
+            Ok(response) => return Ok(response),
+            Err(TypedRequestError::Server { source, .. })
+                if params.history_mode.is_some()
+                    && source.code == -32600
+                    && source.message
+                        == "paginated threads require thread/turns/list and thread/items/list support" =>
+            {
+                params.history_mode = None;
+            }
+            Err(err) => return Err(format!("thread/start: {err}")),
+        }
+    }
+}
+
+fn thread_start_params_from_config(
+    config: &Config,
+    thread_source: &ThreadSource,
+) -> ThreadStartParams {
+    let permissions = permissions_selection_from_config(config);
+    let sandbox = permissions.is_none().then(|| {
+        sandbox_mode_from_permission_profile(
+            &config.permissions.effective_permission_profile(),
+            config.cwd.as_path(),
+        )
+    });
+    ThreadStartParams {
+        model: config.model.clone(),
+        model_provider: Some(config.model_provider_id.clone()),
+        cwd: Some(config.cwd.to_string_lossy().to_string()),
+        runtime_workspace_roots: Some(config.workspace_roots.clone()),
+        approval_policy: Some(config.permissions.approval_policy.value().into()),
+        approvals_reviewer: Some(config.approvals_reviewer.into()),
+        sandbox: sandbox.flatten(),
+        permissions,
+        config: thread_config_overrides_from_config(config),
+        ephemeral: Some(config.ephemeral),
+        history_mode: (!config.ephemeral).then_some(ThreadHistoryMode::Paginated),
+        thread_source: Some(thread_source.clone()),
+        ..ThreadStartParams::default()
+    }
+}
+
+fn thread_resume_params_from_config(
+    config: &Config,
+    thread_id: String,
+    approvals_reviewer_override: Option<codex_app_server_protocol::ApprovalsReviewer>,
+) -> ThreadResumeParams {
+    let permissions = permissions_selection_from_config(config);
+    let sandbox = permissions.is_none().then(|| {
+        sandbox_mode_from_permission_profile(
+            &config.permissions.effective_permission_profile(),
+            config.cwd.as_path(),
+        )
+    });
+    ThreadResumeParams {
+        thread_id,
+        model: config.model.clone(),
+        model_provider: Some(config.model_provider_id.clone()),
+        cwd: Some(config.cwd.to_string_lossy().to_string()),
+        runtime_workspace_roots: Some(config.workspace_roots.clone()),
+        approval_policy: Some(config.permissions.approval_policy.value().into()),
+        approvals_reviewer: approvals_reviewer_override,
+        sandbox: sandbox.flatten(),
+        permissions,
+        config: thread_config_overrides_from_config(config),
+        exclude_turns: true,
+        ..ThreadResumeParams::default()
+    }
+}
+
+fn thread_config_overrides_from_config(config: &Config) -> Option<HashMap<String, Value>> {
+    config
+        .bypass_hook_trust
+        .then(|| HashMap::from([("bypass_hook_trust".to_string(), Value::Bool(true))]))
+}
+
+fn permissions_selection_from_config(config: &Config) -> Option<String> {
+    config
+        .permissions
+        .active_permission_profile()
+        .map(permission_profile_id_from_active_profile)
+}
+
+fn permission_profile_id_from_active_profile(active: ActivePermissionProfile) -> String {
+    active.id
+}
+
+fn sandbox_mode_from_permission_profile(
+    permission_profile: &PermissionProfile,
+    cwd: &Path,
+) -> Option<codex_app_server_protocol::SandboxMode> {
+    match permission_profile {
+        PermissionProfile::Disabled => {
+            Some(codex_app_server_protocol::SandboxMode::DangerFullAccess)
+        }
+        PermissionProfile::External { .. } => None,
+        PermissionProfile::Managed { .. } => {
+            let file_system_policy = permission_profile.file_system_sandbox_policy();
+            if file_system_policy.has_full_disk_write_access() {
+                permission_profile
+                    .network_sandbox_policy()
+                    .is_enabled()
+                    .then_some(codex_app_server_protocol::SandboxMode::DangerFullAccess)
+            } else if file_system_policy.can_write_local_path_with_cwd(cwd, cwd) {
+                Some(codex_app_server_protocol::SandboxMode::WorkspaceWrite)
+            } else {
+                Some(codex_app_server_protocol::SandboxMode::ReadOnly)
+            }
+        }
+    }
+}
+
+async fn send_request_with_response<T>(
+    client: &InProcessAppServerClient,
+    request: ClientRequest,
+    method: &str,
+) -> Result<T, String>
+where
+    T: serde::de::DeserializeOwned,
+{
+    client.request_typed(request).await.map_err(|err| {
+        if method.is_empty() {
+            err.to_string()
+        } else {
+            format!("{method}: {err}")
+        }
+    })
+}
+
+fn session_configured_from_thread_start_response(
+    response: &ThreadStartResponse,
+    config: &Config,
+) -> Result<SessionConfiguredEvent, String> {
+    session_configured_from_thread_response(
+        &response.thread.session_id,
+        &response.thread.id,
+        response.thread.forked_from_id.as_deref(),
+        response.thread.parent_thread_id.as_deref(),
+        response.thread.thread_source.clone().map(Into::into),
+        response.thread.name.clone(),
+        response.thread.path.clone(),
+        response.model.clone(),
+        response.model_provider.clone(),
+        response.service_tier.clone(),
+        response.approval_policy.to_core(),
+        response.approvals_reviewer.to_core(),
+        config.permissions.effective_permission_profile(),
+        response.active_permission_profile.clone().map(Into::into),
+        response.cwd.clone(),
+        response.reasoning_effort.clone(),
+    )
+}
+
+fn session_configured_from_thread_resume_response(
+    response: &ThreadResumeResponse,
+    config: &Config,
+) -> Result<SessionConfiguredEvent, String> {
+    session_configured_from_thread_response(
+        &response.thread.session_id,
+        &response.thread.id,
+        response.thread.forked_from_id.as_deref(),
+        response.thread.parent_thread_id.as_deref(),
+        response.thread.thread_source.clone().map(Into::into),
+        response.thread.name.clone(),
+        response.thread.path.clone(),
+        response.model.clone(),
+        response.model_provider.clone(),
+        response.service_tier.clone(),
+        response.approval_policy.to_core(),
+        response.approvals_reviewer.to_core(),
+        config.permissions.effective_permission_profile(),
+        response.active_permission_profile.clone().map(Into::into),
+        response.cwd.clone(),
+        response.reasoning_effort.clone(),
+    )
+}
+
+fn review_target_to_api(target: ReviewTarget) -> ApiReviewTarget {
+    match target {
+        ReviewTarget::UncommittedChanges => ApiReviewTarget::UncommittedChanges,
+        ReviewTarget::BaseBranch { branch } => ApiReviewTarget::BaseBranch { branch },
+        ReviewTarget::Commit { sha, title } => ApiReviewTarget::Commit { sha, title },
+        ReviewTarget::Custom { instructions } => ApiReviewTarget::Custom { instructions },
+    }
+}
+
+#[expect(
+    clippy::too_many_arguments,
+    reason = "session mapping keeps explicit fields"
+)]
+fn session_configured_from_thread_response(
+    session_id: &str,
+    thread_id: &str,
+    forked_from_id: Option<&str>,
+    parent_thread_id: Option<&str>,
+    thread_source: Option<codex_protocol::protocol::ThreadSource>,
+    thread_name: Option<String>,
+    rollout_path: Option<PathBuf>,
+    model: String,
+    model_provider_id: String,
+    service_tier: Option<String>,
+    approval_policy: AskForApproval,
+    approvals_reviewer: codex_protocol::config_types::ApprovalsReviewer,
+    permission_profile: PermissionProfile,
+    active_permission_profile: Option<codex_protocol::models::ActivePermissionProfile>,
+    cwd: AbsolutePathBuf,
+    reasoning_effort: Option<codex_protocol::openai_models::ReasoningEffort>,
+) -> Result<SessionConfiguredEvent, String> {
+    let session_id = SessionId::from_string(session_id)
+        .map_err(|err| format!("session id `{session_id}` is invalid: {err}"))?;
+    let thread_id = ThreadId::from_string(thread_id)
+        .map_err(|err| format!("thread id `{thread_id}` is invalid: {err}"))?;
+    let forked_from_id = forked_from_id
+        .map(ThreadId::from_string)
+        .transpose()
+        .map_err(|err| format!("forked-from thread id is invalid: {err}"))?;
+    let parent_thread_id = parent_thread_id
+        .map(ThreadId::from_string)
+        .transpose()
+        .map_err(|err| format!("parent thread id is invalid: {err}"))?;
+
+    Ok(SessionConfiguredEvent {
+        session_id,
+        thread_id,
+        forked_from_id,
+        parent_thread_id,
+        thread_source,
+        thread_name,
+        model,
+        model_provider_id,
+        service_tier,
+        approval_policy,
+        approvals_reviewer,
+        permission_profile,
+        active_permission_profile,
+        cwd,
+        reasoning_effort,
+        initial_messages: None,
+        network_proxy: None,
+        rollout_path,
+    })
+}
+
+fn lagged_event_warning_message(skipped: usize) -> String {
+    format!("in-process app-server event stream lagged; dropped {skipped} events")
+}
+
+fn should_process_notification(
+    notification: &ServerNotification,
+    thread_id: &str,
+    turn_id: &str,
+) -> bool {
+    match notification {
+        ServerNotification::ConfigWarning(_) | ServerNotification::DeprecationNotice(_) => true,
+        // TODO(anp) resolve duplicate startup warnings
+        ServerNotification::Warning(notification) => notification
+            .thread_id
+            .as_deref()
+            .is_none_or(|candidate| candidate == thread_id),
+        ServerNotification::AuthRecoveryStarted(notification)
+        | ServerNotification::AuthRecoveryCompleted(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::Error(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::HookCompleted(notification) => {
+            notification.thread_id == thread_id
+                && notification
+                    .turn_id
+                    .as_deref()
+                    .is_none_or(|candidate| candidate == turn_id)
+        }
+        ServerNotification::HookStarted(notification) => {
+            notification.thread_id == thread_id
+                && notification
+                    .turn_id
+                    .as_deref()
+                    .is_none_or(|candidate| candidate == turn_id)
+        }
+        ServerNotification::ItemCompleted(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::ItemStarted(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::ModelRerouted(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::ModelVerification(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::ThreadTokenUsageUpdated(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::TurnCompleted(notification) => {
+            notification.thread_id == thread_id && notification.turn.id == turn_id
+        }
+        ServerNotification::TurnDiffUpdated(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::TurnPlanUpdated(notification) => {
+            notification.thread_id == thread_id && notification.turn_id == turn_id
+        }
+        ServerNotification::TurnStarted(notification) => {
+            notification.thread_id == thread_id && notification.turn.id == turn_id
+        }
+        _ => false,
+    }
+}
+
+async fn maybe_backfill_turn_completed_items(
+    thread_ephemeral: bool,
+    client: &InProcessAppServerClient,
+    request_ids: &mut RequestIdSequencer,
+    notification: &mut ServerNotification,
+) {
+    // In-process delivery may drop non-terminal item notifications under backpressure while still
+    // guaranteeing `turn/completed`. Because app-server currently emits that completion with an
+    // empty `turn.items`, exec does one last `thread/read` here so human/json output can recover
+    // the final message and reconcile any still-running items before shutdown.
+    if !should_backfill_turn_completed_items(thread_ephemeral, notification) {
+        return;
+    }
+
+    let ServerNotification::TurnCompleted(payload) = notification else {
+        return;
+    };
+
+    let response = send_request_with_response::<ThreadReadResponse>(
+        client,
+        ClientRequest::ThreadRead {
+            request_id: request_ids.next(),
+            params: ThreadReadParams {
+                thread_id: payload.thread_id.clone(),
+                include_turns: true,
+            },
+        },
+        "thread/read",
+    )
+    .await;
+
+    match response {
+        Ok(response) => {
+            if let Some(items) = turn_items_for_thread(&response.thread, &payload.turn.id) {
+                payload.turn.items = items;
+            }
+        }
+        Err(err) => {
+            warn!("thread/read failed while backfilling turn items for turn completion: {err}");
+        }
+    }
+}
+
+/// Returns true only when `exec` can safely recover missing turn items from
+/// rollout-backed thread history.
+fn should_backfill_turn_completed_items(
+    thread_ephemeral: bool,
+    notification: &ServerNotification,
+) -> bool {
+    let ServerNotification::TurnCompleted(payload) = notification else {
+        return false;
+    };
+
+    !thread_ephemeral && payload.turn.items_view != codex_app_server_protocol::TurnItemsView::Full
+}
+
+fn turn_items_for_thread(
+    thread: &AppServerThread,
+    turn_id: &str,
+) -> Option<Vec<AppServerThreadItem>> {
+    thread
+        .turns
+        .iter()
+        .find(|turn| turn.id == turn_id)
+        .map(|turn| turn.items.clone())
+}
+
+fn all_thread_source_kinds() -> Vec<ThreadSourceKind> {
+    vec![
+        ThreadSourceKind::Cli,
+        ThreadSourceKind::VsCode,
+        ThreadSourceKind::Exec,
+        ThreadSourceKind::AppServer,
+        ThreadSourceKind::SubAgent,
+        ThreadSourceKind::SubAgentReview,
+        ThreadSourceKind::SubAgentCompact,
+        ThreadSourceKind::SubAgentThreadSpawn,
+        ThreadSourceKind::SubAgentOther,
+        ThreadSourceKind::Unknown,
+    ]
+}
+
+async fn latest_thread_cwd(thread: &AppServerThread) -> PathBuf {
+    if let Some(path) = thread.path.as_deref()
+        && let Some(cwd) = parse_latest_turn_context_cwd(path).await
+    {
+        return cwd;
+    }
+    thread.cwd.to_path_buf()
+}
+
+async fn parse_latest_turn_context_cwd(path: &Path) -> Option<PathBuf> {
+    let path = path.to_path_buf();
+    tokio::task::spawn_blocking(move || {
+        let reader = codex_rollout::open_rollout_seekable_reader(&path).ok()?;
+        let mut scanner = codex_rollout::ReverseJsonlScanner::new(reader).ok()?;
+        while let Some(outcome) = scanner.scan_next_rollout_line().ok()? {
+            if let codex_rollout::ScanOutcome::Parsed(RolloutLine {
+                item: RolloutItem::TurnContext(item),
+                ..
+            }) = outcome
+            {
+                return Some(item.cwd.into_path_buf());
+            }
+        }
+        None
+    })
+    .await
+    .ok()
+    .flatten()
+}
+
+fn cwds_match(current_cwd: &Path, session_cwd: &Path) -> bool {
+    path_utils::paths_match_after_normalization(current_cwd, session_cwd)
+}
+
+async fn resolve_resume_thread_id(
+    client: &InProcessAppServerClient,
+    config: &Config,
+    state_db: Option<&StateDbHandle>,
+    args: &crate::cli::ResumeArgs,
+) -> anyhow::Result<Option<String>> {
+    let model_providers = resume_lookup_model_providers(config, args);
+
+    if args.last {
+        let mut use_state_db_only = state_db.is_some();
+        let mut cursor = None;
+        loop {
+            let response: ThreadListResponse = send_request_with_response(
+                client,
+                ClientRequest::ThreadList {
+                    request_id: RequestId::Integer(0),
+                    params: ThreadListParams {
+                        originators: None,
+                        cursor,
+                        limit: Some(100),
+                        sort_key: Some(ThreadSortKey::UpdatedAt),
+                        sort_direction: None,
+                        model_providers: model_providers.clone(),
+                        source_kinds: Some(all_thread_source_kinds()),
+                        archived: Some(false),
+                        section_id: None,
+                        project_id: None,
+                        parent_thread_id: None,
+                        ancestor_thread_id: None,
+                        cwd: None,
+                        use_state_db_only,
+                        search_term: None,
+                    },
+                },
+                "thread/list",
+            )
+            .await
+            .map_err(anyhow::Error::msg)?;
+            for thread in response.data {
+                if use_state_db_only && let Some(path) = thread.path.as_deref() {
+                    let Ok(session_meta) = read_session_meta_line(path).await else {
+                        continue;
+                    };
+                    if session_meta.meta.id.to_string() != thread.id {
+                        continue;
+                    }
+                }
+                let latest_cwd = latest_thread_cwd(&thread).await;
+                if args.all || cwds_match(config.cwd.as_path(), latest_cwd.as_path()) {
+                    // A usable SQLite candidate is authoritative. Scanning is reserved for a
+                    // complete miss so successful `--last` lookups avoid auditing every rollout.
+                    return Ok(Some(thread.id));
+                }
+            }
+            let Some(next_cursor) = response.next_cursor else {
+                if use_state_db_only {
+                    // Repair from rollouts before giving up on a missing SQLite match.
+                    use_state_db_only = false;
+                    cursor = None;
+                    continue;
+                }
+                return Ok(None);
+            };
+            cursor = Some(next_cursor);
+        }
+    }
+
+    let Some(session_id) = args.session_id.as_deref() else {
+        return Ok(None);
+    };
+    if Uuid::parse_str(session_id).is_ok() {
+        return Ok(Some(session_id.to_string()));
+    }
+    if let Some(state_db) = state_db {
+        let cwd = (!args.all).then_some(config.cwd.as_path());
+        let resolved = state_db
+            .find_thread_by_exact_title(
+                session_id,
+                &[],
+                /*model_providers*/ None,
+                /*archived_only*/ false,
+                cwd,
+            )
+            .await?;
+        if let Some(thread) = resolved {
+            return Ok(Some(thread.id.to_string()));
+        }
+        if let Some((_, session_meta)) =
+            find_thread_meta_by_name_str(&config.codex_home, session_id, Some(state_db.as_ref()))
+                .await?
+            && (args.all || cwds_match(config.cwd.as_path(), &session_meta.meta.cwd))
+        {
+            return Ok(Some(session_meta.meta.id.to_string()));
+        }
+    }
+
+    let mut cursor = None;
+    loop {
+        let response: ThreadListResponse = send_request_with_response(
+            client,
+            ClientRequest::ThreadList {
+                request_id: RequestId::Integer(0),
+                params: ThreadListParams {
+                    originators: None,
+                    cursor,
+                    limit: Some(100),
+                    sort_key: Some(ThreadSortKey::UpdatedAt),
+                    sort_direction: None,
+                    model_providers: model_providers.clone(),
+                    source_kinds: Some(all_thread_source_kinds()),
+                    archived: Some(false),
+                    section_id: None,
+                    project_id: None,
+                    parent_thread_id: None,
+                    ancestor_thread_id: None,
+                    cwd: None,
+                    use_state_db_only: false,
+                    search_term: Some(session_id.to_string()),
+                },
+            },
+            "thread/list",
+        )
+        .await
+        .map_err(anyhow::Error::msg)?;
+        for thread in response.data {
+            if thread.name.as_deref() != Some(session_id) {
+                continue;
+            }
+            let latest_cwd = latest_thread_cwd(&thread).await;
+            if args.all || cwds_match(config.cwd.as_path(), latest_cwd.as_path()) {
+                return Ok(Some(thread.id));
+            }
+        }
+        let Some(next_cursor) = response.next_cursor else {
+            return Ok(None);
+        };
+        cursor = Some(next_cursor);
+    }
+}
+
+fn resume_lookup_model_providers(
+    config: &Config,
+    args: &crate::cli::ResumeArgs,
+) -> Option<Vec<String>> {
+    if args.last {
+        Some(vec![config.model_provider_id.clone()])
+    } else {
+        None
+    }
+}
+
+fn canceled_mcp_server_elicitation_response() -> Result<Value, String> {
+    serde_json::to_value(McpServerElicitationRequestResponse {
+        action: McpServerElicitationAction::Cancel,
+        content: None,
+        meta: None,
+    })
+    .map_err(|err| format!("failed to encode mcp elicitation response: {err}"))
+}
+
+async fn request_shutdown(
+    client: &InProcessAppServerClient,
+    request_ids: &mut RequestIdSequencer,
+    thread_id: &str,
+) -> Result<(), String> {
+    let request = ClientRequest::ThreadUnsubscribe {
+        request_id: request_ids.next(),
+        params: ThreadUnsubscribeParams {
+            thread_id: thread_id.to_string(),
+        },
+    };
+    send_request_with_response::<ThreadUnsubscribeResponse>(client, request, "thread/unsubscribe")
+        .await
+        .map(|_| ())
+}
+
+async fn resolve_server_request(
+    client: &InProcessAppServerClient,
+    request_id: RequestId,
+    value: serde_json::Value,
+    method: &str,
+) -> Result<(), String> {
+    client
+        .resolve_server_request(request_id, value)
+        .await
+        .map_err(|err| format!("failed to resolve `{method}` server request: {err}"))
+}
+
+async fn reject_server_request(
+    client: &InProcessAppServerClient,
+    request_id: RequestId,
+    method: &str,
+    reason: String,
+) -> Result<(), String> {
+    client
+        .reject_server_request(
+            request_id,
+            JSONRPCErrorError {
+                code: -32000,
+                message: reason,
+                data: None,
+            },
+        )
+        .await
+        .map_err(|err| format!("failed to reject `{method}` server request: {err}"))
+}
+
+fn server_request_method_name(request: &ServerRequest) -> String {
+    serde_json::to_value(request)
+        .ok()
+        .and_then(|value| {
+            value
+                .get("method")
+                .and_then(serde_json::Value::as_str)
+                .map(str::to_owned)
+        })
+        .unwrap_or_else(|| "unknown".to_string())
+}
+
+async fn handle_server_request(
+    client: &InProcessAppServerClient,
+    request: ServerRequest,
+    error_seen: &mut bool,
+) {
+    let method = server_request_method_name(&request);
+    let handle_result = match request {
+        ServerRequest::McpServerElicitationRequest { request_id, .. } => {
+            // Exec auto-cancels elicitation instead of surfacing it
+            // interactively. Preserve that behavior for attached subagent
+            // threads too so we do not turn a cancel into a decline/error.
+            match canceled_mcp_server_elicitation_response() {
+                Ok(value) => {
+                    resolve_server_request(
+                        client,
+                        request_id,
+                        value,
+                        "mcpServer/elicitation/request",
+                    )
+                    .await
+                }
+                Err(err) => Err(err),
+            }
+        }
+        ServerRequest::CommandExecutionRequestApproval { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "command execution approval is not supported in exec mode for thread `{}`",
+                    params.thread_id
+                ),
+            )
+            .await
+        }
+        ServerRequest::FileChangeRequestApproval { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "file change approval is not supported in exec mode for thread `{}`",
+                    params.thread_id
+                ),
+            )
+            .await
+        }
+        ServerRequest::ToolRequestUserInput { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "request_user_input is not supported in exec mode for thread `{}`",
+                    params.thread_id
+                ),
+            )
+            .await
+        }
+        ServerRequest::DynamicToolCall { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "dynamic tool calls are not supported in exec mode for thread `{}`",
+                    params.thread_id
+                ),
+            )
+            .await
+        }
+        ServerRequest::ChatgptAuthTokensRefresh { request_id, .. } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                "chatgpt auth token refresh is not supported in exec mode".to_string(),
+            )
+            .await
+        }
+        ServerRequest::AttestationGenerate { request_id, .. } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                "attestation generation is not supported in exec mode".to_string(),
+            )
+            .await
+        }
+        ServerRequest::CurrentTimeRead { request_id, .. } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                "external current time is not supported in exec mode".to_string(),
+            )
+            .await
+        }
+        ServerRequest::ApplyPatchApproval { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "apply_patch approval is not supported in exec mode for thread `{}`",
+                    params.conversation_id
+                ),
+            )
+            .await
+        }
+        ServerRequest::ExecCommandApproval { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "exec command approval is not supported in exec mode for thread `{}`",
+                    params.conversation_id
+                ),
+            )
+            .await
+        }
+        ServerRequest::PermissionsRequestApproval { request_id, params } => {
+            reject_server_request(
+                client,
+                request_id,
+                &method,
+                format!(
+                    "permissions approval is not supported in exec mode for thread `{}`",
+                    params.thread_id
+                ),
+            )
+            .await
+        }
+    };
+
+    if let Err(err) = handle_result {
+        *error_seen = true;
+        warn!("{err}");
+    }
+}
+
+fn load_output_schema(path: Option<PathBuf>) -> Option<Value> {
+    let path = path?;
+
+    let schema_str = match std::fs::read_to_string(&path) {
+        Ok(contents) => contents,
+        Err(err) => {
+            eprintln!(
+                "Failed to read output schema file {}: {err}",
+                path.display()
+            );
+            std::process::exit(1);
+        }
+    };
+
+    match serde_json::from_str::<Value>(&schema_str) {
+        Ok(value) => Some(value),
+        Err(err) => {
+            eprintln!(
+                "Output schema file {} is not valid JSON: {err}",
+                path.display()
+            );
+            std::process::exit(1);
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum PromptDecodeError {
+    InvalidUtf8 { valid_up_to: usize },
+    InvalidUtf16 { encoding: &'static str },
+    UnsupportedBom { encoding: &'static str },
+}
+
+impl std::fmt::Display for PromptDecodeError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            PromptDecodeError::InvalidUtf8 { valid_up_to } => write!(
+                f,
+                "input is not valid UTF-8 (invalid byte at offset {valid_up_to}). Convert it to UTF-8 and retry (e.g., `iconv -f <ENC> -t UTF-8 prompt.txt`)."
+            ),
+            PromptDecodeError::InvalidUtf16 { encoding } => write!(
+                f,
+                "input looked like {encoding} but could not be decoded. Convert it to UTF-8 and retry."
+            ),
+            PromptDecodeError::UnsupportedBom { encoding } => write!(
+                f,
+                "input appears to be {encoding}. Convert it to UTF-8 and retry."
+            ),
+        }
+    }
+}
+
+fn decode_prompt_bytes(input: &[u8]) -> Result<String, PromptDecodeError> {
+    let input = input.strip_prefix(&[0xEF, 0xBB, 0xBF]).unwrap_or(input);
+
+    if input.starts_with(&[0xFF, 0xFE, 0x00, 0x00]) {
+        return Err(PromptDecodeError::UnsupportedBom {
+            encoding: "UTF-32LE",
+        });
+    }
+
+    if input.starts_with(&[0x00, 0x00, 0xFE, 0xFF]) {
+        return Err(PromptDecodeError::UnsupportedBom {
+            encoding: "UTF-32BE",
+        });
+    }
+
+    if let Some(rest) = input.strip_prefix(&[0xFF, 0xFE]) {
+        return decode_utf16(rest, "UTF-16LE", u16::from_le_bytes);
+    }
+
+    if let Some(rest) = input.strip_prefix(&[0xFE, 0xFF]) {
+        return decode_utf16(rest, "UTF-16BE", u16::from_be_bytes);
+    }
+
+    std::str::from_utf8(input)
+        .map(str::to_string)
+        .map_err(|e| PromptDecodeError::InvalidUtf8 {
+            valid_up_to: e.valid_up_to(),
+        })
+}
+
+fn decode_utf16(
+    input: &[u8],
+    encoding: &'static str,
+    decode_unit: fn([u8; 2]) -> u16,
+) -> Result<String, PromptDecodeError> {
+    if !input.len().is_multiple_of(2) {
+        return Err(PromptDecodeError::InvalidUtf16 { encoding });
+    }
+
+    let units: Vec<u16> = input
+        .chunks_exact(2)
+        .map(|chunk| decode_unit([chunk[0], chunk[1]]))
+        .collect();
+
+    String::from_utf16(&units).map_err(|_| PromptDecodeError::InvalidUtf16 { encoding })
+}
+
+fn read_prompt_from_stdin(behavior: StdinPromptBehavior) -> Option<String> {
+    let stdin_is_terminal = std::io::stdin().is_terminal();
+
+    match behavior {
+        StdinPromptBehavior::RequiredIfPiped if stdin_is_terminal => {
+            eprintln!(
+                "No prompt provided. Either specify one as an argument or pipe the prompt into stdin."
+            );
+            std::process::exit(1);
+        }
+        StdinPromptBehavior::RequiredIfPiped => {
+            eprintln!("Reading prompt from stdin...");
+        }
+        StdinPromptBehavior::Forced => {}
+        StdinPromptBehavior::OptionalAppend if stdin_is_terminal => return None,
+        StdinPromptBehavior::OptionalAppend => {
+            eprintln!("Reading additional input from stdin...");
+        }
+    }
+
+    let mut bytes = Vec::new();
+    if let Err(e) = std::io::stdin().read_to_end(&mut bytes) {
+        eprintln!("Failed to read prompt from stdin: {e}");
+        std::process::exit(1);
+    }
+
+    let buffer = match decode_prompt_bytes(&bytes) {
+        Ok(s) => s,
+        Err(e) => {
+            eprintln!("Failed to read prompt from stdin: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    if buffer.trim().is_empty() {
+        match behavior {
+            StdinPromptBehavior::OptionalAppend => None,
+            StdinPromptBehavior::RequiredIfPiped | StdinPromptBehavior::Forced => {
+                eprintln!("No prompt provided via stdin.");
+                std::process::exit(1);
+            }
+        }
+    } else {
+        Some(buffer)
+    }
+}
+
+fn prompt_with_stdin_context(prompt: &str, stdin_text: &str) -> String {
+    let mut combined = format!("{prompt}\n\n<stdin>\n{stdin_text}");
+    if !stdin_text.ends_with('\n') {
+        combined.push('\n');
+    }
+    combined.push_str("</stdin>");
+    combined
+}
+
+fn resolve_prompt(prompt_arg: Option<String>) -> String {
+    match prompt_arg {
+        Some(p) if p != "-" => p,
+        maybe_dash => {
+            let behavior = if matches!(maybe_dash.as_deref(), Some("-")) {
+                StdinPromptBehavior::Forced
+            } else {
+                StdinPromptBehavior::RequiredIfPiped
+            };
+            let Some(prompt) = read_prompt_from_stdin(behavior) else {
+                unreachable!("required stdin prompt should produce content");
+            };
+            prompt
+        }
+    }
+}
+
+fn resolve_root_prompt(prompt_arg: Option<String>) -> String {
+    match prompt_arg {
+        Some(prompt) if prompt != "-" => {
+            if let Some(stdin_text) = read_prompt_from_stdin(StdinPromptBehavior::OptionalAppend) {
+                prompt_with_stdin_context(&prompt, &stdin_text)
+            } else {
+                prompt
+            }
+        }
+        maybe_dash => resolve_prompt(maybe_dash),
+    }
+}
+
+fn build_review_request(args: &ReviewArgs) -> anyhow::Result<ReviewRequest> {
+    let target = if args.uncommitted {
+        ReviewTarget::UncommittedChanges
+    } else if let Some(branch) = args.base.clone() {
+        ReviewTarget::BaseBranch { branch }
+    } else if let Some(sha) = args.commit.clone() {
+        ReviewTarget::Commit {
+            sha,
+            title: args.commit_title.clone(),
+        }
+    } else if let Some(prompt_arg) = args.prompt.clone() {
+        let prompt = resolve_prompt(Some(prompt_arg)).trim().to_string();
+        if prompt.is_empty() {
+            anyhow::bail!("Review prompt cannot be empty");
+        }
+        ReviewTarget::Custom {
+            instructions: prompt,
+        }
+    } else {
+        anyhow::bail!(
+            "Specify --uncommitted, --base, --commit, or provide custom review instructions"
+        );
+    };
+
+    Ok(ReviewRequest {
+        target,
+        user_facing_hint: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "lib_tests.rs"]
+mod tests;
diff --git a/codex-rs/exec/src/lib_tests.rs b/codex-rs/exec/src/lib_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fb79e7b83978ed3a7ed95475c3e016015670ee4f
--- /dev/null
+++ b/codex-rs/exec/src/lib_tests.rs
@@ -0,0 +1,899 @@
+use super::*;
+use codex_app_server_protocol::AuthRecoveryNotification;
+use codex_otel::set_parent_from_w3c_trace_context;
+use codex_protocol::config_types::ApprovalsReviewer;
+use codex_protocol::models::ActivePermissionProfile;
+use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_WORKSPACE;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use opentelemetry::trace::TraceContextExt;
+use opentelemetry::trace::TraceId;
+use opentelemetry::trace::TracerProvider as _;
+use opentelemetry_sdk::trace::SdkTracerProvider;
+use pretty_assertions::assert_eq;
+use std::io;
+use std::io::Write;
+use std::sync::Arc;
+use std::sync::Mutex;
+use tempfile::tempdir;
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+fn test_tracing_subscriber() -> impl tracing::Subscriber + Send + Sync {
+    let provider = SdkTracerProvider::builder().build();
+    let tracer = provider.tracer("codex-exec-tests");
+    tracing_subscriber::registry().with(tracing_opentelemetry::layer().with_tracer(tracer))
+}
+
+#[derive(Clone)]
+struct TestLogWriter {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+struct TestLogSink {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for TestLogWriter {
+    type Writer = TestLogSink;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        TestLogSink {
+            buffer: Arc::clone(&self.buffer),
+        }
+    }
+}
+
+impl Write for TestLogSink {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.buffer.lock().expect("log buffer lock").extend(buf);
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+#[test]
+fn exec_default_stderr_filter_suppresses_otel_self_diagnostics() {
+    let buffer = Arc::new(Mutex::new(Vec::new()));
+    let writer = TestLogWriter {
+        buffer: Arc::clone(&buffer),
+    };
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .with_ansi(false)
+            .with_writer(writer)
+            .with_filter(EnvFilter::try_new(EXEC_DEFAULT_LOG_FILTER).expect("default filter")),
+    );
+
+    tracing::subscriber::with_default(subscriber, || {
+        tracing::error!(target: "opentelemetry_sdk", "telemetry export failed");
+        tracing::error!(target: "opentelemetry_otlp", "telemetry request failed");
+        tracing::error!(target: "codex_exec_test", "real exec error");
+    });
+
+    let logs = String::from_utf8(buffer.lock().expect("log buffer lock").clone()).expect("utf8");
+    assert!(!logs.contains("telemetry export failed"));
+    assert!(!logs.contains("telemetry request failed"));
+    assert!(logs.contains("real exec error"));
+}
+
+#[test]
+fn exec_root_span_can_be_parented_from_trace_context() {
+    let subscriber = test_tracing_subscriber();
+    let _guard = tracing::subscriber::set_default(subscriber);
+
+    let parent = codex_protocol::protocol::W3cTraceContext {
+        traceparent: Some("00-00000000000000000000000000000077-0000000000000088-01".into()),
+        tracestate: Some("vendor=value".into()),
+    };
+    let exec_span = exec_root_span();
+    assert!(set_parent_from_w3c_trace_context(&exec_span, &parent));
+
+    let trace_id = exec_span.context().span().span_context().trace_id();
+    assert_eq!(
+        trace_id,
+        TraceId::from_hex("00000000000000000000000000000077").expect("trace id")
+    );
+}
+
+#[test]
+fn builds_uncommitted_review_request() {
+    let args = ReviewArgs {
+        uncommitted: true,
+        base: None,
+        commit: None,
+        commit_title: None,
+        prompt: None,
+    };
+    let request = build_review_request(&args).expect("builds uncommitted review request");
+
+    let expected = ReviewRequest {
+        target: ReviewTarget::UncommittedChanges,
+        user_facing_hint: None,
+    };
+
+    assert_eq!(request, expected);
+}
+
+#[test]
+fn builds_commit_review_request_with_title() {
+    let args = ReviewArgs {
+        uncommitted: false,
+        base: None,
+        commit: Some("123456789".to_string()),
+        commit_title: Some("Add review command".to_string()),
+        prompt: None,
+    };
+    let request = build_review_request(&args).expect("builds commit review request");
+
+    let expected = ReviewRequest {
+        target: ReviewTarget::Commit {
+            sha: "123456789".to_string(),
+            title: Some("Add review command".to_string()),
+        },
+        user_facing_hint: None,
+    };
+
+    assert_eq!(request, expected);
+}
+
+#[test]
+fn builds_custom_review_request_trims_prompt() {
+    let args = ReviewArgs {
+        uncommitted: false,
+        base: None,
+        commit: None,
+        commit_title: None,
+        prompt: Some("  custom review instructions  ".to_string()),
+    };
+    let request = build_review_request(&args).expect("builds custom review request");
+
+    let expected = ReviewRequest {
+        target: ReviewTarget::Custom {
+            instructions: "custom review instructions".to_string(),
+        },
+        user_facing_hint: None,
+    };
+
+    assert_eq!(request, expected);
+}
+
+#[test]
+fn decode_prompt_bytes_strips_utf8_bom() {
+    let input = [0xEF, 0xBB, 0xBF, b'h', b'i', b'\n'];
+
+    let out = decode_prompt_bytes(&input).expect("decode utf-8 with BOM");
+
+    assert_eq!(out, "hi\n");
+}
+
+#[test]
+fn decode_prompt_bytes_decodes_utf16le_bom() {
+    // UTF-16LE BOM + "hi\n"
+    let input = [0xFF, 0xFE, b'h', 0x00, b'i', 0x00, b'\n', 0x00];
+
+    let out = decode_prompt_bytes(&input).expect("decode utf-16le with BOM");
+
+    assert_eq!(out, "hi\n");
+}
+
+#[test]
+fn decode_prompt_bytes_decodes_utf16be_bom() {
+    // UTF-16BE BOM + "hi\n"
+    let input = [0xFE, 0xFF, 0x00, b'h', 0x00, b'i', 0x00, b'\n'];
+
+    let out = decode_prompt_bytes(&input).expect("decode utf-16be with BOM");
+
+    assert_eq!(out, "hi\n");
+}
+
+#[test]
+fn decode_prompt_bytes_rejects_utf32le_bom() {
+    // UTF-32LE BOM + "hi\n"
+    let input = [
+        0xFF, 0xFE, 0x00, 0x00, b'h', 0x00, 0x00, 0x00, b'i', 0x00, 0x00, 0x00, b'\n', 0x00, 0x00,
+        0x00,
+    ];
+
+    let err = decode_prompt_bytes(&input).expect_err("utf-32le should be rejected");
+
+    assert_eq!(
+        err,
+        PromptDecodeError::UnsupportedBom {
+            encoding: "UTF-32LE"
+        }
+    );
+}
+
+#[test]
+fn decode_prompt_bytes_rejects_utf32be_bom() {
+    // UTF-32BE BOM + "hi\n"
+    let input = [
+        0x00, 0x00, 0xFE, 0xFF, 0x00, 0x00, 0x00, b'h', 0x00, 0x00, 0x00, b'i', 0x00, 0x00, 0x00,
+        b'\n',
+    ];
+
+    let err = decode_prompt_bytes(&input).expect_err("utf-32be should be rejected");
+
+    assert_eq!(
+        err,
+        PromptDecodeError::UnsupportedBom {
+            encoding: "UTF-32BE"
+        }
+    );
+}
+
+#[test]
+fn decode_prompt_bytes_rejects_invalid_utf8() {
+    // Invalid UTF-8 sequence: 0xC3 0x28
+    let input = [0xC3, 0x28];
+
+    let err = decode_prompt_bytes(&input).expect_err("invalid utf-8 should fail");
+
+    assert_eq!(err, PromptDecodeError::InvalidUtf8 { valid_up_to: 0 });
+}
+
+#[test]
+fn prompt_with_stdin_context_wraps_stdin_block() {
+    let combined = prompt_with_stdin_context("Summarize this concisely", "my output");
+
+    assert_eq!(
+        combined,
+        "Summarize this concisely\n\n<stdin>\nmy output\n</stdin>"
+    );
+}
+
+#[test]
+fn prompt_with_stdin_context_preserves_trailing_newline() {
+    let combined = prompt_with_stdin_context("Summarize this concisely", "my output\n");
+
+    assert_eq!(
+        combined,
+        "Summarize this concisely\n\n<stdin>\nmy output\n</stdin>"
+    );
+}
+
+#[test]
+fn lagged_event_warning_message_is_explicit() {
+    assert_eq!(
+        lagged_event_warning_message(/*skipped*/ 7),
+        "in-process app-server event stream lagged; dropped 7 events".to_string()
+    );
+}
+
+#[test]
+fn runtime_warnings_are_filtered_to_the_primary_thread() {
+    let primary_thread_id = "thread-1";
+    let turn_id = "turn-1";
+    let outcomes = [
+        codex_app_server_protocol::WarningNotification {
+            thread_id: None,
+            message: "global warning".to_string(),
+        },
+        codex_app_server_protocol::WarningNotification {
+            thread_id: Some(primary_thread_id.to_string()),
+            message: "primary warning".to_string(),
+        },
+        codex_app_server_protocol::WarningNotification {
+            thread_id: Some("thread-2".to_string()),
+            message: "other warning".to_string(),
+        },
+    ]
+    .map(|warning| {
+        should_process_notification(
+            &ServerNotification::Warning(warning),
+            primary_thread_id,
+            turn_id,
+        )
+    });
+
+    assert_eq!(outcomes, [true, true, false]);
+
+    let recovery = AuthRecoveryNotification {
+        thread_id: primary_thread_id.to_string(),
+        turn_id: turn_id.to_string(),
+        provider: "example".to_string(),
+        message: "Refresh authentication".to_string(),
+    };
+    let outcomes = [
+        ServerNotification::AuthRecoveryStarted(recovery.clone()),
+        ServerNotification::AuthRecoveryCompleted(recovery.clone()),
+        ServerNotification::AuthRecoveryStarted(AuthRecoveryNotification {
+            thread_id: "thread-2".to_string(),
+            ..recovery.clone()
+        }),
+        ServerNotification::AuthRecoveryCompleted(AuthRecoveryNotification {
+            turn_id: "turn-2".to_string(),
+            ..recovery
+        }),
+    ]
+    .map(|notification| should_process_notification(&notification, primary_thread_id, turn_id));
+
+    assert_eq!(outcomes, [true, true, false, false]);
+}
+
+#[tokio::test]
+async fn resume_lookup_model_providers_filters_only_last_lookup() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let mut config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build default config");
+    config.model_provider_id = "test-provider".to_string();
+
+    let last_args = crate::cli::ResumeArgs {
+        session_id: None,
+        last: true,
+        all: false,
+        images: vec![],
+        prompt: None,
+    };
+    let named_args = crate::cli::ResumeArgs {
+        session_id: Some("named-session".to_string()),
+        last: false,
+        all: false,
+        images: vec![],
+        prompt: None,
+    };
+
+    assert_eq!(
+        resume_lookup_model_providers(&config, &last_args),
+        Some(vec!["test-provider".to_string()])
+    );
+    assert_eq!(resume_lookup_model_providers(&config, &named_args), None);
+}
+
+#[test]
+fn turn_items_for_thread_returns_matching_turn_items() {
+    let thread = AppServerThread {
+        environments: None,
+        id: "thread-1".to_string(),
+        extra: None,
+        session_id: "thread-1".to_string(),
+        forked_from_id: None,
+        parent_thread_id: None,
+        preview: String::new(),
+        ephemeral: false,
+        section: None,
+        section_entered_at: None,
+        project_id: None,
+        daybreak_enabled: None,
+        history_mode: Default::default(),
+        model_provider: "openai".to_string(),
+        model: None,
+        reasoning_effort: None,
+        created_at: 0,
+        updated_at: 0,
+        recency_at: Some(0),
+        status: codex_app_server_protocol::ThreadStatus::Idle,
+        path: None,
+        cwd: test_path_buf("/tmp/project").abs(),
+        cli_version: "0.0.0-test".to_string(),
+        originator: None,
+        source: codex_app_server_protocol::SessionSource::Exec,
+        can_accept_direct_input: None,
+        thread_source: None,
+        agent_nickname: None,
+        agent_role: None,
+        git_info: None,
+        name: None,
+        turns: vec![
+            codex_app_server_protocol::Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![AppServerThreadItem::AgentMessage {
+                    id: "msg-1".to_string(),
+                    text: "hello".to_string(),
+                    phase: None,
+                    memory_citation: None,
+                    delivery: None,
+                    questions: None,
+                }],
+                status: codex_app_server_protocol::TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+            codex_app_server_protocol::Turn {
+                id: "turn-2".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![AppServerThreadItem::Plan {
+                    id: "plan-1".to_string(),
+                    text: "ship it".to_string(),
+                }],
+                status: codex_app_server_protocol::TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        ],
+    };
+
+    assert_eq!(
+        turn_items_for_thread(&thread, "turn-1"),
+        Some(vec![AppServerThreadItem::AgentMessage {
+            id: "msg-1".to_string(),
+            text: "hello".to_string(),
+            phase: None,
+            memory_citation: None,
+            delivery: None,
+            questions: None,
+        }])
+    );
+    assert_eq!(turn_items_for_thread(&thread, "missing-turn"), None);
+}
+
+#[test]
+fn should_backfill_turn_completed_items_backfills_persisted_summaries_only() {
+    let notification =
+        ServerNotification::TurnCompleted(codex_app_server_protocol::TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: codex_app_server_protocol::Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Summary,
+                items: Vec::new(),
+                status: codex_app_server_protocol::TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        });
+
+    assert!(!should_backfill_turn_completed_items(
+        /*thread_ephemeral*/ true,
+        &notification
+    ));
+    assert!(should_backfill_turn_completed_items(
+        /*thread_ephemeral*/ false,
+        &notification
+    ));
+}
+
+#[test]
+fn canceled_mcp_server_elicitation_response_uses_cancel_action() {
+    let value = canceled_mcp_server_elicitation_response()
+        .expect("mcp elicitation cancel response should serialize");
+    let response: McpServerElicitationRequestResponse =
+        serde_json::from_value(value).expect("cancel response should deserialize");
+
+    assert_eq!(
+        response,
+        McpServerElicitationRequestResponse {
+            action: McpServerElicitationAction::Cancel,
+            content: None,
+            meta: None,
+        }
+    );
+}
+
+#[tokio::test]
+async fn thread_start_params_include_review_policy_when_review_policy_is_manual_only() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .loader_overrides(LoaderOverrides::without_managed_config_for_tests())
+        .codex_home(codex_home.path().to_path_buf())
+        .harness_overrides(ConfigOverrides {
+            approvals_reviewer: Some(ApprovalsReviewer::User),
+            ..Default::default()
+        })
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config with manual-only review policy");
+
+    let params = thread_start_params_from_config(&config, &ThreadSource::User);
+
+    assert_eq!(
+        params.approvals_reviewer,
+        Some(codex_app_server_protocol::ApprovalsReviewer::User)
+    );
+    assert_eq!(params.sandbox, None);
+    assert_eq!(
+        params.permissions,
+        permissions_selection_from_config(&config)
+    );
+}
+
+#[tokio::test]
+async fn thread_start_params_include_review_policy_when_auto_review_is_enabled() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .harness_overrides(ConfigOverrides {
+            approvals_reviewer: Some(ApprovalsReviewer::AutoReview),
+            ..Default::default()
+        })
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config with guardian review policy");
+
+    let params = thread_start_params_from_config(&config, &ThreadSource::User);
+
+    assert_eq!(
+        params.approvals_reviewer,
+        Some(codex_app_server_protocol::ApprovalsReviewer::AutoReview)
+    );
+}
+
+#[tokio::test]
+async fn thread_resume_params_only_include_explicit_review_policy_override() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .harness_overrides(ConfigOverrides {
+            approvals_reviewer: Some(ApprovalsReviewer::AutoReview),
+            ..Default::default()
+        })
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config with guardian review policy");
+
+    let params_without_override = thread_resume_params_from_config(
+        &config,
+        "thread-id".to_string(),
+        /*approvals_reviewer_override*/ None,
+    );
+    let params_with_override = thread_resume_params_from_config(
+        &config,
+        "thread-id".to_string(),
+        Some(codex_app_server_protocol::ApprovalsReviewer::AutoReview),
+    );
+
+    assert_eq!(params_without_override.approvals_reviewer, None);
+    assert_eq!(
+        params_with_override.approvals_reviewer,
+        Some(codex_app_server_protocol::ApprovalsReviewer::AutoReview)
+    );
+}
+
+#[tokio::test]
+async fn build_exec_config_retries_without_invalid_headless_policy_for_auto_review() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    std::fs::write(
+        codex_home.path().join("config.toml"),
+        r#"
+approval_policy = "on-request"
+approvals_reviewer = "auto_review"
+"#,
+    )
+    .expect("write config");
+    let requirements_path = codex_home.path().join("requirements.toml");
+    std::fs::write(
+        &requirements_path,
+        r#"
+allowed_approval_policies = ["never", "on-request"]
+allowed_sandbox_modes = ["read-only", "workspace-write"]
+"#,
+    )
+    .expect("write requirements");
+    let mut loader_overrides = LoaderOverrides::without_managed_config_for_tests();
+    loader_overrides.system_requirements_path = Some(requirements_path);
+    let overrides = ConfigOverrides {
+        cwd: Some(cwd.path().to_path_buf()),
+        approval_policy: Some(AskForApproval::Never),
+        sandbox_mode: Some(SandboxMode::DangerFullAccess),
+        ..Default::default()
+    };
+    let build_config = |overrides| {
+        ConfigBuilder::default()
+            .codex_home(codex_home.path().to_path_buf())
+            .loader_overrides(loader_overrides.clone())
+            .harness_overrides(overrides)
+            .build()
+    };
+
+    let error = build_config(overrides.clone())
+        .await
+        .expect_err("synthetic headless approval policy should fail");
+    assert!(
+        error
+            .to_string()
+            .contains("`approval_policy = \"never\"` cannot be used")
+    );
+
+    let config = build_exec_config(
+        overrides,
+        /*preserve_headless_approval_policy*/ false,
+        build_config,
+    )
+    .await
+    .expect("auto-review config should retry without the synthetic approval policy");
+
+    assert_eq!(
+        config.permissions.approval_policy.value(),
+        AskForApproval::OnRequest
+    );
+    assert_eq!(config.approvals_reviewer, ApprovalsReviewer::AutoReview);
+}
+
+#[tokio::test]
+async fn build_exec_config_preserves_headless_error_when_retry_fails() {
+    let overrides = ConfigOverrides {
+        approval_policy: Some(AskForApproval::Never),
+        ..Default::default()
+    };
+
+    let error = build_exec_config(
+        overrides,
+        /*preserve_headless_approval_policy*/ false,
+        |overrides| async move {
+            let message = if overrides.approval_policy == Some(AskForApproval::Never) {
+                "headless error"
+            } else {
+                "retry error"
+            };
+            Err(std::io::Error::other(message))
+        },
+    )
+    .await
+    .expect_err("failed speculative retry should preserve the original error");
+
+    assert_eq!(error.to_string(), "headless error");
+}
+
+#[tokio::test]
+async fn thread_start_params_match_history_to_persistence() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let mut config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config");
+
+    let params = thread_start_params_from_config(&config, &ThreadSource::User);
+
+    assert_eq!(
+        params.thread_source,
+        Some(codex_app_server_protocol::ThreadSource::User)
+    );
+    assert_eq!(params.history_mode, Some(ThreadHistoryMode::Paginated));
+
+    let thread_source = ThreadSource::Feature("automated_review".to_string());
+    let params = thread_start_params_from_config(&config, &thread_source);
+    assert_eq!(params.thread_source, Some(thread_source));
+
+    config.ephemeral = true;
+    let params = thread_start_params_from_config(&config, &ThreadSource::User);
+
+    assert_eq!(params.ephemeral, Some(true));
+    assert_eq!(params.history_mode, None);
+}
+
+#[tokio::test]
+async fn thread_lifecycle_params_preserve_hook_trust_bypass() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .harness_overrides(ConfigOverrides {
+            bypass_hook_trust: Some(true),
+            ..Default::default()
+        })
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config with hook trust bypass");
+    let expected_config = Some(HashMap::from([(
+        "bypass_hook_trust".to_string(),
+        serde_json::Value::Bool(true),
+    )]));
+
+    let start_params = thread_start_params_from_config(&config, &ThreadSource::User);
+    let resume_params = thread_resume_params_from_config(
+        &config,
+        "thread-id".to_string(),
+        /*approvals_reviewer_override*/ None,
+    );
+
+    assert_eq!(start_params.config, expected_config);
+    assert_eq!(resume_params.config, expected_config);
+}
+
+#[test]
+fn active_profile_selection_uses_profile_id_only() {
+    let selection = permission_profile_id_from_active_profile(ActivePermissionProfile::new(
+        BUILT_IN_PERMISSION_PROFILE_WORKSPACE,
+    ));
+
+    assert_eq!(selection, BUILT_IN_PERMISSION_PROFILE_WORKSPACE.to_string());
+}
+
+#[tokio::test]
+async fn thread_lifecycle_params_include_legacy_sandbox_when_no_active_profile() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .loader_overrides(LoaderOverrides::without_managed_config_for_tests())
+        .codex_home(codex_home.path().to_path_buf())
+        .harness_overrides(ConfigOverrides {
+            sandbox_mode: Some(SandboxMode::DangerFullAccess),
+            ..Default::default()
+        })
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config with legacy sandbox override");
+
+    let start_params = thread_start_params_from_config(&config, &ThreadSource::User);
+    let resume_params = thread_resume_params_from_config(
+        &config,
+        "thread-id".to_string(),
+        /*approvals_reviewer_override*/ None,
+    );
+
+    assert_eq!(config.permissions.active_permission_profile(), None);
+    assert_eq!(
+        start_params.sandbox,
+        Some(codex_app_server_protocol::SandboxMode::DangerFullAccess)
+    );
+    assert_eq!(start_params.permissions, None);
+    assert_eq!(
+        resume_params.sandbox,
+        Some(codex_app_server_protocol::SandboxMode::DangerFullAccess)
+    );
+    assert_eq!(resume_params.permissions, None);
+}
+
+#[tokio::test]
+async fn session_configured_from_thread_response_uses_review_policy_from_response() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config");
+    let response = sample_thread_start_response();
+
+    let event = session_configured_from_thread_start_response(&response, &config)
+        .expect("build bootstrap session configured event");
+
+    assert_eq!(
+        event.session_id.to_string(),
+        "67e55044-10b1-426f-9247-bb680e5fe0c7"
+    );
+    assert_eq!(
+        event.thread_id.to_string(),
+        "67e55044-10b1-426f-9247-bb680e5fe0c8"
+    );
+    assert_eq!(event.approvals_reviewer, ApprovalsReviewer::AutoReview);
+}
+
+#[tokio::test]
+async fn session_configured_from_thread_response_uses_permission_profile_from_config() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config");
+    let response = sample_thread_start_response();
+
+    let event = session_configured_from_thread_start_response(&response, &config)
+        .expect("build bootstrap session configured event");
+
+    assert_eq!(
+        event.permission_profile,
+        config.permissions.effective_permission_profile()
+    );
+}
+
+#[tokio::test]
+async fn session_configured_from_thread_response_preserves_thread_source() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config");
+    let response = sample_thread_start_response();
+
+    let event = session_configured_from_thread_start_response(&response, &config)
+        .expect("build bootstrap session configured event");
+
+    assert_eq!(
+        event.thread_source,
+        Some(codex_protocol::protocol::ThreadSource::User)
+    );
+}
+
+#[tokio::test]
+async fn session_configured_from_thread_response_preserves_parent_thread_id() {
+    let codex_home = tempdir().expect("create temp codex home");
+    let cwd = tempdir().expect("create temp cwd");
+    let config = ConfigBuilder::default()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(cwd.path().to_path_buf()))
+        .build()
+        .await
+        .expect("build config");
+    let parent_thread_id = ThreadId::new();
+    let forked_from_id = ThreadId::new();
+    let mut response = sample_thread_start_response();
+    response.thread.parent_thread_id = Some(parent_thread_id.to_string());
+    response.thread.forked_from_id = Some(forked_from_id.to_string());
+
+    let event = session_configured_from_thread_start_response(&response, &config)
+        .expect("build bootstrap session configured event");
+
+    assert_eq!(event.parent_thread_id, Some(parent_thread_id));
+    assert_eq!(event.forked_from_id, Some(forked_from_id));
+}
+
+fn sample_thread_start_response() -> ThreadStartResponse {
+    ThreadStartResponse {
+        disabled_plugin_ids: Vec::new(),
+        thread: codex_app_server_protocol::Thread {
+            originator: None,
+            environments: None,
+            id: "67e55044-10b1-426f-9247-bb680e5fe0c8".to_string(),
+            extra: None,
+            session_id: "67e55044-10b1-426f-9247-bb680e5fe0c7".to_string(),
+            forked_from_id: None,
+            parent_thread_id: None,
+            preview: String::new(),
+            ephemeral: false,
+            section: None,
+            section_entered_at: None,
+            project_id: None,
+            daybreak_enabled: None,
+            history_mode: Default::default(),
+            model_provider: "openai".to_string(),
+            model: None,
+            reasoning_effort: None,
+            created_at: 0,
+            updated_at: 0,
+            recency_at: Some(0),
+            status: codex_app_server_protocol::ThreadStatus::Idle,
+            path: Some(PathBuf::from("/tmp/rollout.jsonl")),
+            cwd: test_path_buf("/tmp").abs(),
+            cli_version: "0.0.0".to_string(),
+            source: codex_app_server_protocol::SessionSource::Cli,
+            can_accept_direct_input: None,
+            thread_source: Some(codex_app_server_protocol::ThreadSource::User),
+            agent_nickname: None,
+            agent_role: None,
+            git_info: None,
+            name: Some("thread".to_string()),
+            turns: vec![],
+        },
+        model: "gpt-5.4".to_string(),
+        model_provider: "openai".to_string(),
+        service_tier: None,
+        cwd: test_path_buf("/tmp").abs(),
+        runtime_workspace_roots: Vec::new(),
+        instruction_sources: Vec::new(),
+        approval_policy: codex_app_server_protocol::AskForApproval::OnRequest,
+        approvals_reviewer: codex_app_server_protocol::ApprovalsReviewer::AutoReview,
+        sandbox: codex_app_server_protocol::SandboxPolicy::WorkspaceWrite {
+            writable_roots: vec![],
+            network_access: false,
+            exclude_tmpdir_env_var: false,
+            exclude_slash_tmp: false,
+        },
+        active_permission_profile: None,
+        reasoning_effort: None,
+        multi_agent_mode: Default::default(),
+    }
+}
diff --git a/codex-rs/exec/src/main.rs b/codex-rs/exec/src/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..61eaecdd0a8526c49e798649f3810eec343200e4
--- /dev/null
+++ b/codex-rs/exec/src/main.rs
@@ -0,0 +1,44 @@
+//! Entry-point for the `codex-exec` binary.
+//!
+//! When this CLI is invoked normally, it parses the standard `codex-exec` CLI
+//! options and launches the non-interactive Codex agent. However, if it is
+//! invoked with arg0 as `codex-linux-sandbox`, we instead treat the invocation
+//! as a request to run the logic for the standalone `codex-linux-sandbox`
+//! executable (i.e., parse any -s args and then run a *sandboxed* command under
+//! Landlock + seccomp.
+//!
+//! This allows us to ship a completely separate set of functionality as part
+//! of the `codex-exec` binary.
+use clap::Parser;
+use codex_arg0::Arg0DispatchPaths;
+use codex_arg0::arg0_dispatch_or_else;
+use codex_exec::Cli;
+use codex_exec::run_main;
+use codex_utils_cli::CliConfigOverrides;
+
+#[derive(Parser, Debug)]
+struct TopCli {
+    #[clap(flatten)]
+    config_overrides: CliConfigOverrides,
+
+    #[clap(flatten)]
+    inner: Cli,
+}
+
+fn main() -> anyhow::Result<()> {
+    arg0_dispatch_or_else(|arg0_paths: Arg0DispatchPaths| async move {
+        let top_cli = TopCli::parse();
+        // Merge root-level overrides into inner CLI struct so downstream logic remains unchanged.
+        let mut inner = top_cli.inner;
+        inner
+            .config_overrides
+            .prepend_root_overrides(top_cli.config_overrides);
+
+        run_main(inner, arg0_paths).await?;
+        Ok(())
+    })
+}
+
+#[cfg(test)]
+#[path = "main_tests.rs"]
+mod tests;
diff --git a/codex-rs/exec/src/main_tests.rs b/codex-rs/exec/src/main_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5c0a8a3bfceb1f34be07c894527e301682384894
--- /dev/null
+++ b/codex-rs/exec/src/main_tests.rs
@@ -0,0 +1,43 @@
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn top_cli_parses_resume_prompt_after_config_flag() {
+    const PROMPT: &str = "echo resume-with-global-flags-after-subcommand";
+    let cli = TopCli::parse_from([
+        "codex-exec",
+        "resume",
+        "--strict-config",
+        "--last",
+        "--json",
+        "--model",
+        "gpt-5.2-codex",
+        "--config",
+        "reasoning_level=xhigh",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--skip-git-repo-check",
+        PROMPT,
+    ]);
+    let mut inner = cli.inner;
+    inner
+        .config_overrides
+        .prepend_root_overrides(cli.config_overrides);
+
+    let Some(codex_exec::Command::Resume(args)) = inner.command.as_ref() else {
+        panic!("expected resume command");
+    };
+    let effective_prompt = args.prompt.clone().or_else(|| {
+        if args.last {
+            args.session_id.clone()
+        } else {
+            None
+        }
+    });
+    assert_eq!(effective_prompt.as_deref(), Some(PROMPT));
+    assert_eq!(inner.config_overrides.raw_overrides.len(), 1);
+    assert_eq!(
+        inner.config_overrides.raw_overrides[0],
+        "reasoning_level=xhigh"
+    );
+    assert!(inner.strict_config);
+}
diff --git a/codex-rs/exec/src/worktree.rs b/codex-rs/exec/src/worktree.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d73e3ad639f7260c63a55bdc6f2eee5fe301febd
--- /dev/null
+++ b/codex-rs/exec/src/worktree.rs
@@ -0,0 +1,82 @@
+//! Resolves managed fork sources through the existing name/ID lookup before final configuration.
+//! The temporary app-server never starts a thread or executes a turn.
+
+use super::*;
+
+pub(super) async fn fork_source(
+    args: &mut crate::cli::ForkArgs,
+    config: &Config,
+    arg0_paths: &Arg0DispatchPaths,
+    cli_overrides: &[(String, codex_config::TomlValue)],
+    loader_overrides: &LoaderOverrides,
+    cloud_config_bundle: CloudConfigBundleLoader,
+    strict_config: bool,
+) -> anyhow::Result<std::path::PathBuf> {
+    let state_db = codex_core::init_state_db(config).await;
+    let environment_manager = EnvironmentManager::from_codex_home(
+        config.codex_home.clone(),
+        Some(ExecServerRuntimePaths::from_optional_paths(
+            arg0_paths.codex_self_exe.clone(),
+            arg0_paths.codex_linux_sandbox_exe.clone(),
+        )?),
+        config.http_client_factory(),
+    )
+    .await?;
+    let client = InProcessAppServerClient::start(InProcessClientStartArgs {
+        arg0_paths: arg0_paths.clone(),
+        config: std::sync::Arc::new(config.clone()),
+        cli_overrides: cli_overrides.to_vec(),
+        loader_overrides: LoaderOverrides {
+            ignore_project_config: true,
+            ..loader_overrides.clone()
+        },
+        strict_config,
+        cloud_config_bundle,
+        feedback: CodexFeedback::new(),
+        log_db: None,
+        state_db: state_db.clone(),
+        environment_manager: std::sync::Arc::new(environment_manager),
+        config_warnings: Vec::new(),
+        session_source: SessionSource::Exec,
+        enable_codex_api_key_env: true,
+        client_name: "codex_exec".to_string(),
+        client_version: env!("CARGO_PKG_VERSION").to_string(),
+        experimental_api: true,
+        mcp_server_openai_form_elicitation: false,
+        opt_out_notification_methods: Vec::new(),
+        channel_capacity: DEFAULT_IN_PROCESS_CHANNEL_CAPACITY,
+    })
+    .await?;
+    let result = async {
+        let lookup = crate::cli::ResumeArgs {
+            session_id: Some(args.session_id.clone()),
+            last: false,
+            all: true,
+            images: Vec::new(),
+            prompt: None,
+        };
+        let thread_id = resolve_resume_thread_id(&client, config, state_db.as_ref(), &lookup)
+            .await?
+            .ok_or_else(|| anyhow::anyhow!("Session not found: {}", args.session_id))?;
+        let source: ThreadReadResponse = send_request_with_response(
+            &client,
+            ClientRequest::ThreadRead {
+                request_id: RequestId::Integer(1),
+                params: ThreadReadParams {
+                    thread_id: thread_id.clone(),
+                    include_turns: false,
+                },
+            },
+            "thread/read",
+        )
+        .await
+        .map_err(anyhow::Error::msg)?;
+        args.session_id = thread_id;
+        Ok::<_, anyhow::Error>(latest_thread_cwd(&source.thread).await)
+    }
+    .await;
+    let shutdown = client.shutdown().await;
+    let source_cwd = result?;
+    shutdown?;
+    Ok(source_cwd)
+}
diff --git a/codex-rs/exec/tests/all.rs b/codex-rs/exec/tests/all.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6582e12b2312bce8cfa7eea5d230e54258d37f42
--- /dev/null
+++ b/codex-rs/exec/tests/all.rs
@@ -0,0 +1,7 @@
+#![allow(clippy::expect_used)]
+
+// Single integration test binary that aggregates all test modules.
+// The submodules live in `tests/suite/`.
+mod suite;
+
+mod event_processor_with_json_output;
diff --git a/codex-rs/exec/tests/event_processor_with_json_output.rs b/codex-rs/exec/tests/event_processor_with_json_output.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1586c9303daaab9b12d4cd833f2eb04820fa4824
--- /dev/null
+++ b/codex-rs/exec/tests/event_processor_with_json_output.rs
@@ -0,0 +1,1711 @@
+use codex_app_server_protocol::CollabAgentState as ApiCollabAgentState;
+use codex_app_server_protocol::CollabAgentStatus as ApiCollabAgentStatus;
+use codex_app_server_protocol::CollabAgentTool;
+use codex_app_server_protocol::CollabAgentToolCallStatus as ApiCollabAgentToolCallStatus;
+use codex_app_server_protocol::CommandAction;
+use codex_app_server_protocol::CommandExecutionSource;
+use codex_app_server_protocol::CommandExecutionStatus as ApiCommandExecutionStatus;
+use codex_app_server_protocol::ErrorNotification;
+use codex_app_server_protocol::FileUpdateChange as ApiFileUpdateChange;
+use codex_app_server_protocol::ItemCompletedNotification;
+use codex_app_server_protocol::ItemStartedNotification;
+use codex_app_server_protocol::McpToolCallError;
+use codex_app_server_protocol::McpToolCallResult;
+use codex_app_server_protocol::McpToolCallStatus as ApiMcpToolCallStatus;
+use codex_app_server_protocol::PatchApplyStatus as ApiPatchApplyStatus;
+use codex_app_server_protocol::PatchChangeKind as ApiPatchChangeKind;
+use codex_app_server_protocol::ServerNotification;
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::ThreadTokenUsage;
+use codex_app_server_protocol::TokenUsageBreakdown;
+use codex_app_server_protocol::Turn;
+use codex_app_server_protocol::TurnCompletedNotification;
+use codex_app_server_protocol::TurnError;
+use codex_app_server_protocol::TurnPlanStep;
+use codex_app_server_protocol::TurnPlanStepStatus;
+use codex_app_server_protocol::TurnPlanUpdatedNotification;
+use codex_app_server_protocol::TurnStartedNotification;
+use codex_app_server_protocol::TurnStatus;
+use codex_app_server_protocol::WebSearchAction as ApiWebSearchAction;
+use codex_app_server_protocol::WebSearchItem as ApiWebSearchItem;
+use codex_protocol::SessionId;
+use codex_protocol::ThreadId;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::models::WebSearchAction;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::SessionConfiguredEvent;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+use codex_exec::AgentMessageItem;
+use codex_exec::CodexStatus;
+use codex_exec::CollabAgentState;
+use codex_exec::CollabAgentStatus;
+use codex_exec::CollabTool;
+use codex_exec::CollabToolCallItem;
+use codex_exec::CollabToolCallStatus;
+use codex_exec::CollectedThreadEvents;
+use codex_exec::CommandExecutionItem;
+use codex_exec::CommandExecutionStatus;
+use codex_exec::ErrorItem;
+use codex_exec::EventProcessorWithJsonOutput;
+use codex_exec::ExecThreadItem;
+use codex_exec::FileChangeItem;
+use codex_exec::FileUpdateChange as ExecFileUpdateChange;
+use codex_exec::ItemCompletedEvent;
+use codex_exec::ItemStartedEvent;
+use codex_exec::ItemUpdatedEvent;
+use codex_exec::McpToolCallItem;
+use codex_exec::McpToolCallItemError;
+use codex_exec::McpToolCallItemResult;
+use codex_exec::McpToolCallStatus;
+use codex_exec::PatchApplyStatus;
+use codex_exec::PatchChangeKind;
+use codex_exec::ReasoningItem;
+use codex_exec::ThreadErrorEvent;
+use codex_exec::ThreadEvent;
+use codex_exec::ThreadItemDetails;
+use codex_exec::ThreadStartedEvent;
+use codex_exec::TodoItem;
+use codex_exec::TodoListItem;
+use codex_exec::TurnCompletedEvent;
+use codex_exec::TurnFailedEvent;
+use codex_exec::TurnStartedEvent;
+use codex_exec::Usage;
+use codex_exec::WebSearchItem;
+
+#[test]
+fn map_todo_items_preserves_text_and_completion_state() {
+    let items = EventProcessorWithJsonOutput::map_todo_items(&[
+        TurnPlanStep {
+            step: "inspect bootstrap".to_string(),
+            status: TurnPlanStepStatus::InProgress,
+        },
+        TurnPlanStep {
+            step: "drop legacy notifications".to_string(),
+            status: TurnPlanStepStatus::Completed,
+        },
+    ]);
+
+    assert_eq!(
+        items,
+        vec![
+            TodoItem {
+                text: "inspect bootstrap".to_string(),
+                completed: false,
+            },
+            TodoItem {
+                text: "drop legacy notifications".to_string(),
+                completed: true,
+            },
+        ]
+    );
+}
+
+#[test]
+fn session_configured_produces_thread_started_event() {
+    let thread_id = ThreadId::from_string("67e55044-10b1-426f-9247-bb680e5fe0c8")
+        .expect("thread id should parse");
+    let session_configured = SessionConfiguredEvent {
+        session_id: SessionId::from(thread_id),
+        thread_id,
+        forked_from_id: None,
+        parent_thread_id: None,
+        thread_source: None,
+        thread_name: None,
+        model: "codex-mini-latest".to_string(),
+        model_provider_id: "test-provider".to_string(),
+        service_tier: None,
+        approval_policy: AskForApproval::Never,
+        approvals_reviewer: codex_protocol::config_types::ApprovalsReviewer::User,
+        permission_profile: PermissionProfile::read_only(),
+        active_permission_profile: None,
+        cwd: test_path_buf("/tmp/project").abs(),
+        reasoning_effort: None,
+        initial_messages: None,
+        network_proxy: None,
+        rollout_path: None,
+    };
+
+    assert_eq!(
+        EventProcessorWithJsonOutput::thread_started_event(&session_configured),
+        ThreadEvent::ThreadStarted(ThreadStartedEvent {
+            thread_id: "67e55044-10b1-426f-9247-bb680e5fe0c8".to_string(),
+        })
+    );
+}
+
+#[test]
+fn turn_started_emits_turn_started_event() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected =
+        processor.collect_thread_events(ServerNotification::TurnStarted(TurnStartedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::InProgress,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        }));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnStarted(TurnStartedEvent {})],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn command_execution_started_and_completed_translate_to_thread_events() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+    let command_item = ThreadItem::CommandExecution {
+        model_context: None,
+        id: "cmd-1".to_string(),
+        command: "ls".to_string(),
+        cwd: test_path_buf("/tmp/project").abs().into(),
+        process_id: Some("123".to_string()),
+        plugin_id: None,
+        script_path: None,
+        source: CommandExecutionSource::UserShell,
+        status: ApiCommandExecutionStatus::InProgress,
+        command_actions: Vec::<CommandAction>::new(),
+        aggregated_output: None,
+        exit_code: None,
+        duration_ms: None,
+    };
+
+    let started =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: command_item,
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::CommandExecution(CommandExecutionItem {
+                        command: "ls".to_string(),
+                        aggregated_output: String::new(),
+                        exit_code: None,
+                        status: CommandExecutionStatus::InProgress,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+
+    let completed = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::CommandExecution {
+                model_context: None,
+                id: "cmd-1".to_string(),
+                command: "ls".to_string(),
+                cwd: test_path_buf("/tmp/project").abs().into(),
+                process_id: Some("123".to_string()),
+                plugin_id: None,
+                script_path: None,
+                source: CommandExecutionSource::UserShell,
+                status: ApiCommandExecutionStatus::Completed,
+                command_actions: Vec::<CommandAction>::new(),
+                aggregated_output: Some("a.txt\n".to_string()),
+                exit_code: Some(0),
+                duration_ms: Some(3),
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::CommandExecution(CommandExecutionItem {
+                        command: "ls".to_string(),
+                        aggregated_output: "a.txt\n".to_string(),
+                        exit_code: Some(0),
+                        status: CommandExecutionStatus::Completed,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn empty_reasoning_items_are_ignored() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::Reasoning {
+                id: "reasoning-1".to_string(),
+                summary: Vec::new(),
+                content: vec!["raw reasoning".to_string()],
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: Vec::new(),
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn unsupported_items_do_not_consume_synthetic_ids() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let ignored = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::Plan {
+                id: "plan-1".to_string(),
+                text: "ignored plan".to_string(),
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        ignored,
+        CollectedThreadEvents {
+            events: Vec::new(),
+            status: CodexStatus::Running,
+        }
+    );
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "message-1".to_string(),
+                text: "hello".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::AgentMessage(AgentMessageItem {
+                        text: "hello".to_string(),
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn reasoning_items_emit_summary_not_raw_content() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::Reasoning {
+                id: "reasoning-1".to_string(),
+                summary: vec!["safe summary".to_string()],
+                content: vec!["raw reasoning".to_string()],
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::Reasoning(ReasoningItem {
+                        text: "safe summary".to_string(),
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn web_search_completion_preserves_query_and_action() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::WebSearch(ApiWebSearchItem {
+                id: "search-1".to_string(),
+                query: "rust async await".to_string(),
+                action: Some(ApiWebSearchAction::Search {
+                    query: Some("rust async await".to_string()),
+                    queries: None,
+                }),
+                results: None,
+            }),
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::WebSearch(WebSearchItem {
+                        id: "search-1".to_string(),
+                        query: "rust async await".to_string(),
+                        action: WebSearchAction::Search {
+                            query: Some("rust async await".to_string()),
+                            queries: None,
+                        },
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn web_search_start_and_completion_reuse_item_id() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let started =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: ThreadItem::WebSearch(ApiWebSearchItem {
+                id: "search-1".to_string(),
+                query: String::new(),
+                action: None,
+                results: None,
+            }),
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+
+    let completed = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::WebSearch(ApiWebSearchItem {
+                id: "search-1".to_string(),
+                query: "rust async await".to_string(),
+                action: Some(ApiWebSearchAction::Search {
+                    query: Some("rust async await".to_string()),
+                    queries: None,
+                }),
+                results: None,
+            }),
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::WebSearch(WebSearchItem {
+                        id: "search-1".to_string(),
+                        query: String::new(),
+                        action: WebSearchAction::Other,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::WebSearch(WebSearchItem {
+                        id: "search-1".to_string(),
+                        query: "rust async await".to_string(),
+                        action: WebSearchAction::Search {
+                            query: Some("rust async await".to_string()),
+                            queries: None,
+                        },
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn mcp_tool_call_begin_and_end_emit_item_events() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let started =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: ThreadItem::McpToolCall {
+                id: "mcp-1".to_string(),
+                server: "server_a".to_string(),
+                tool: "tool_x".to_string(),
+                status: ApiMcpToolCallStatus::InProgress,
+                arguments: json!({ "key": "value" }),
+                app_context: None,
+                mcp_app_resource_uri: None,
+                mcp_app_ui: None,
+                plugin_id: None,
+                read_only_hint: None,
+                result: None,
+                error: None,
+                duration_ms: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+    let completed = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::McpToolCall {
+                id: "mcp-1".to_string(),
+                server: "server_a".to_string(),
+                tool: "tool_x".to_string(),
+                status: ApiMcpToolCallStatus::Completed,
+                arguments: json!({ "key": "value" }),
+                app_context: None,
+                mcp_app_resource_uri: None,
+                mcp_app_ui: None,
+                plugin_id: None,
+                read_only_hint: None,
+                result: Some(Box::new(McpToolCallResult {
+                    content: Vec::new(),
+                    structured_content: None,
+                    meta: None,
+                })),
+                error: None,
+                duration_ms: Some(1_000),
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::McpToolCall(McpToolCallItem {
+                        server: "server_a".to_string(),
+                        tool: "tool_x".to_string(),
+                        arguments: json!({ "key": "value" }),
+                        result: None,
+                        error: None,
+                        status: McpToolCallStatus::InProgress,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::McpToolCall(McpToolCallItem {
+                        server: "server_a".to_string(),
+                        tool: "tool_x".to_string(),
+                        arguments: json!({ "key": "value" }),
+                        result: Some(McpToolCallItemResult {
+                            content: Vec::new(),
+                            meta: None,
+                            structured_content: None,
+                        }),
+                        error: None,
+                        status: McpToolCallStatus::Completed,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn mcp_tool_call_failure_sets_failed_status() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::McpToolCall {
+                id: "mcp-2".to_string(),
+                server: "server_b".to_string(),
+                tool: "tool_y".to_string(),
+                status: ApiMcpToolCallStatus::Failed,
+                arguments: json!({ "param": 42 }),
+                app_context: None,
+                mcp_app_resource_uri: None,
+                mcp_app_ui: None,
+                plugin_id: None,
+                read_only_hint: None,
+                result: None,
+                error: Some(McpToolCallError {
+                    message: "tool exploded".to_string(),
+                }),
+                duration_ms: Some(5),
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::McpToolCall(McpToolCallItem {
+                        server: "server_b".to_string(),
+                        tool: "tool_y".to_string(),
+                        arguments: json!({ "param": 42 }),
+                        result: None,
+                        error: Some(McpToolCallItemError {
+                            message: "tool exploded".to_string(),
+                        }),
+                        status: McpToolCallStatus::Failed,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn mcp_tool_call_defaults_arguments_and_preserves_structured_content() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let started =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: ThreadItem::McpToolCall {
+                id: "mcp-3".to_string(),
+                server: "server_c".to_string(),
+                tool: "tool_z".to_string(),
+                status: ApiMcpToolCallStatus::InProgress,
+                arguments: serde_json::Value::Null,
+                app_context: None,
+                mcp_app_resource_uri: None,
+                mcp_app_ui: None,
+                plugin_id: None,
+                read_only_hint: None,
+                result: None,
+                error: None,
+                duration_ms: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+    let completed = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::McpToolCall {
+                id: "mcp-3".to_string(),
+                server: "server_c".to_string(),
+                tool: "tool_z".to_string(),
+                status: ApiMcpToolCallStatus::Completed,
+                arguments: serde_json::Value::Null,
+                app_context: None,
+                mcp_app_resource_uri: None,
+                mcp_app_ui: None,
+                plugin_id: None,
+                read_only_hint: None,
+                result: Some(Box::new(McpToolCallResult {
+                    content: vec![json!({
+                        "type": "text",
+                        "text": "done",
+                    })],
+                    structured_content: Some(json!({ "status": "ok" })),
+                    meta: None,
+                })),
+                error: None,
+                duration_ms: Some(10),
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::McpToolCall(McpToolCallItem {
+                        server: "server_c".to_string(),
+                        tool: "tool_z".to_string(),
+                        arguments: serde_json::Value::Null,
+                        result: None,
+                        error: None,
+                        status: McpToolCallStatus::InProgress,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::McpToolCall(McpToolCallItem {
+                        server: "server_c".to_string(),
+                        tool: "tool_z".to_string(),
+                        arguments: serde_json::Value::Null,
+                        result: Some(McpToolCallItemResult {
+                            content: vec![json!({
+                                "type": "text",
+                                "text": "done",
+                            })],
+                            meta: None,
+                            structured_content: Some(json!({ "status": "ok" })),
+                        }),
+                        error: None,
+                        status: McpToolCallStatus::Completed,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn collab_spawn_begin_and_end_emit_item_events() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let started =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: ThreadItem::CollabAgentToolCall {
+                id: "collab-1".to_string(),
+                tool: CollabAgentTool::SpawnAgent,
+                status: ApiCollabAgentToolCallStatus::InProgress,
+                sender_thread_id: "thread-parent".to_string(),
+                receiver_thread_ids: Vec::new(),
+                prompt: Some("draft a plan".to_string()),
+                model: Some("gpt-5".to_string()),
+                reasoning_effort: None,
+                agents_states: std::collections::HashMap::new(),
+            },
+            thread_id: "thread-parent".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+    let completed = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::CollabAgentToolCall {
+                id: "collab-1".to_string(),
+                tool: CollabAgentTool::SpawnAgent,
+                status: ApiCollabAgentToolCallStatus::Completed,
+                sender_thread_id: "thread-parent".to_string(),
+                receiver_thread_ids: vec!["thread-child".to_string()],
+                prompt: Some("draft a plan".to_string()),
+                model: Some("gpt-5".to_string()),
+                reasoning_effort: None,
+                agents_states: std::collections::HashMap::from([(
+                    "thread-child".to_string(),
+                    ApiCollabAgentState {
+                        status: ApiCollabAgentStatus::Running,
+                        message: None,
+                    },
+                )]),
+            },
+            thread_id: "thread-parent".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::CollabToolCall(CollabToolCallItem {
+                        tool: CollabTool::SpawnAgent,
+                        sender_thread_id: "thread-parent".to_string(),
+                        receiver_thread_ids: Vec::new(),
+                        prompt: Some("draft a plan".to_string()),
+                        agents_states: std::collections::HashMap::new(),
+                        status: CollabToolCallStatus::InProgress,
+                    },),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::CollabToolCall(CollabToolCallItem {
+                        tool: CollabTool::SpawnAgent,
+                        sender_thread_id: "thread-parent".to_string(),
+                        receiver_thread_ids: vec!["thread-child".to_string()],
+                        prompt: Some("draft a plan".to_string()),
+                        agents_states: std::collections::HashMap::from([(
+                            "thread-child".to_string(),
+                            CollabAgentState {
+                                status: CollabAgentStatus::Running,
+                                message: None,
+                            },
+                        )]),
+                        status: CollabToolCallStatus::Completed,
+                    },),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn file_change_completion_maps_change_kinds() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::FileChange {
+                id: "patch-1".to_string(),
+                changes: vec![
+                    ApiFileUpdateChange {
+                        path: "a/added.txt".to_string(),
+                        kind: ApiPatchChangeKind::Add,
+                        diff: String::new(),
+                    },
+                    ApiFileUpdateChange {
+                        path: "b/deleted.txt".to_string(),
+                        kind: ApiPatchChangeKind::Delete,
+                        diff: String::new(),
+                    },
+                    ApiFileUpdateChange {
+                        path: "c/modified.txt".to_string(),
+                        kind: ApiPatchChangeKind::Update { move_path: None },
+                        diff: "@@ -1 +1 @@".to_string(),
+                    },
+                ],
+                status: ApiPatchApplyStatus::Completed,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::FileChange(FileChangeItem {
+                        changes: vec![
+                            ExecFileUpdateChange {
+                                path: "a/added.txt".to_string(),
+                                kind: PatchChangeKind::Add,
+                            },
+                            ExecFileUpdateChange {
+                                path: "b/deleted.txt".to_string(),
+                                kind: PatchChangeKind::Delete,
+                            },
+                            ExecFileUpdateChange {
+                                path: "c/modified.txt".to_string(),
+                                kind: PatchChangeKind::Update,
+                            },
+                        ],
+                        status: PatchApplyStatus::Completed,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn file_change_declined_maps_to_failed_status() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::FileChange {
+                id: "patch-2".to_string(),
+                changes: vec![ApiFileUpdateChange {
+                    path: "file.txt".to_string(),
+                    kind: ApiPatchChangeKind::Update { move_path: None },
+                    diff: "@@ -1 +1 @@".to_string(),
+                }],
+                status: ApiPatchApplyStatus::Declined,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::FileChange(FileChangeItem {
+                        changes: vec![ExecFileUpdateChange {
+                            path: "file.txt".to_string(),
+                            kind: PatchChangeKind::Update,
+                        }],
+                        status: PatchApplyStatus::Failed,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn agent_message_item_updates_final_message() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "msg-1".to_string(),
+                text: "hello".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::AgentMessage(AgentMessageItem {
+                        text: "hello".to_string(),
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+    assert_eq!(processor.final_message(), Some("hello"));
+}
+
+#[test]
+fn agent_message_item_started_is_ignored() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "msg-1".to_string(),
+                text: "hello".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: Vec::new(),
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn reasoning_item_completed_uses_synthetic_id() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::Reasoning {
+                id: "rs-1".to_string(),
+                summary: vec!["thinking...".to_string()],
+                content: vec!["raw".to_string()],
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::Reasoning(ReasoningItem {
+                        text: "thinking...".to_string(),
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn warning_event_produces_error_item() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_warning(
+        "Heads up: Long conversations and multiple compactions can cause the model to be less accurate. Start a new conversation when possible to keep conversations small and targeted.".to_string(),
+    );
+
+    assert_eq!(
+        collected,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::Error(ErrorItem {
+                        message: "Heads up: Long conversations and multiple compactions can cause the model to be less accurate. Start a new conversation when possible to keep conversations small and targeted.".to_string(),
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn plan_update_emits_started_then_updated_then_completed() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let started = processor.collect_thread_events(ServerNotification::TurnPlanUpdated(
+        TurnPlanUpdatedNotification {
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            explanation: None,
+            plan: vec![
+                TurnPlanStep {
+                    step: "step one".to_string(),
+                    status: TurnPlanStepStatus::Pending,
+                },
+                TurnPlanStep {
+                    step: "step two".to_string(),
+                    status: TurnPlanStepStatus::InProgress,
+                },
+            ],
+        },
+    ));
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::TodoList(TodoListItem {
+                        items: vec![
+                            TodoItem {
+                                text: "step one".to_string(),
+                                completed: false,
+                            },
+                            TodoItem {
+                                text: "step two".to_string(),
+                                completed: false,
+                            },
+                        ],
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+
+    let updated = processor.collect_thread_events(ServerNotification::TurnPlanUpdated(
+        TurnPlanUpdatedNotification {
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            explanation: None,
+            plan: vec![
+                TurnPlanStep {
+                    step: "step one".to_string(),
+                    status: TurnPlanStepStatus::Completed,
+                },
+                TurnPlanStep {
+                    step: "step two".to_string(),
+                    status: TurnPlanStepStatus::InProgress,
+                },
+            ],
+        },
+    ));
+    assert_eq!(
+        updated,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemUpdated(ItemUpdatedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::TodoList(TodoListItem {
+                        items: vec![
+                            TodoItem {
+                                text: "step one".to_string(),
+                                completed: true,
+                            },
+                            TodoItem {
+                                text: "step two".to_string(),
+                                completed: false,
+                            },
+                        ],
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![
+                ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                    item: ExecThreadItem {
+                        id: "item_0".to_string(),
+                        details: ThreadItemDetails::TodoList(TodoListItem {
+                            items: vec![
+                                TodoItem {
+                                    text: "step one".to_string(),
+                                    completed: true,
+                                },
+                                TodoItem {
+                                    text: "step two".to_string(),
+                                    completed: false,
+                                },
+                            ],
+                        }),
+                    },
+                }),
+                ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                    usage: Usage::default(),
+                }),
+            ],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+}
+
+#[test]
+fn plan_update_after_completion_starts_new_todo_list_with_new_id() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let _ = processor.collect_thread_events(ServerNotification::TurnPlanUpdated(
+        TurnPlanUpdatedNotification {
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            explanation: None,
+            plan: vec![TurnPlanStep {
+                step: "only".to_string(),
+                status: TurnPlanStepStatus::Pending,
+            }],
+        },
+    ));
+    let _ = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    let restarted = processor.collect_thread_events(ServerNotification::TurnPlanUpdated(
+        TurnPlanUpdatedNotification {
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-2".to_string(),
+            explanation: None,
+            plan: vec![TurnPlanStep {
+                step: "again".to_string(),
+                status: TurnPlanStepStatus::Pending,
+            }],
+        },
+    ));
+
+    assert_eq!(
+        restarted,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_1".to_string(),
+                    details: ThreadItemDetails::TodoList(TodoListItem {
+                        items: vec![TodoItem {
+                            text: "again".to_string(),
+                            completed: false,
+                        }],
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+}
+
+#[test]
+fn token_usage_update_is_emitted_on_turn_completion() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let usage_update =
+        processor.collect_thread_events(ServerNotification::ThreadTokenUsageUpdated(
+            codex_app_server_protocol::ThreadTokenUsageUpdatedNotification {
+                thread_id: "thread-1".to_string(),
+                turn_id: "turn-1".to_string(),
+                token_usage: ThreadTokenUsage {
+                    total: TokenUsageBreakdown {
+                        total_tokens: 42,
+                        input_tokens: 10,
+                        cached_input_tokens: 3,
+                        cache_write_input_tokens: 4,
+                        output_tokens: 29,
+                        reasoning_output_tokens: 7,
+                    },
+                    last: TokenUsageBreakdown {
+                        total_tokens: 42,
+                        input_tokens: 10,
+                        cached_input_tokens: 3,
+                        cache_write_input_tokens: 4,
+                        output_tokens: 29,
+                        reasoning_output_tokens: 7,
+                    },
+                    model_context_window: Some(128_000),
+                },
+            },
+        ));
+    assert_eq!(
+        usage_update,
+        CollectedThreadEvents {
+            events: Vec::new(),
+            status: CodexStatus::Running,
+        }
+    );
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                usage: Usage {
+                    input_tokens: 10,
+                    cached_input_tokens: 3,
+                    cache_write_input_tokens: 4,
+                    output_tokens: 29,
+                    reasoning_output_tokens: 7,
+                },
+            })],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+}
+
+#[test]
+fn turn_completion_recovers_final_message_from_turn_items() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![ThreadItem::AgentMessage {
+                    id: "msg-1".to_string(),
+                    text: "final answer".to_string(),
+                    phase: None,
+                    memory_citation: None,
+                    delivery: None,
+                    questions: None,
+                }],
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                usage: Usage::default(),
+            })],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+    assert_eq!(processor.final_message(), Some("final answer"));
+}
+
+#[test]
+fn turn_completion_reconciles_started_items_from_turn_items() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let started =
+        processor.collect_thread_events(ServerNotification::ItemStarted(ItemStartedNotification {
+            item: ThreadItem::CommandExecution {
+                model_context: None,
+                id: "cmd-1".to_string(),
+                command: "ls".to_string(),
+                cwd: test_path_buf("/tmp/project").abs().into(),
+                process_id: Some("123".to_string()),
+                plugin_id: None,
+                script_path: None,
+                source: CommandExecutionSource::UserShell,
+                status: ApiCommandExecutionStatus::InProgress,
+                command_actions: Vec::<CommandAction>::new(),
+                aggregated_output: None,
+                exit_code: None,
+                duration_ms: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            started_at_ms: 0,
+        }));
+    assert_eq!(
+        started,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::ItemStarted(ItemStartedEvent {
+                item: ExecThreadItem {
+                    id: "item_0".to_string(),
+                    details: ThreadItemDetails::CommandExecution(CommandExecutionItem {
+                        command: "ls".to_string(),
+                        aggregated_output: String::new(),
+                        exit_code: None,
+                        status: CommandExecutionStatus::InProgress,
+                    }),
+                },
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![ThreadItem::CommandExecution {
+                    model_context: None,
+                    id: "cmd-1".to_string(),
+                    command: "ls".to_string(),
+                    cwd: test_path_buf("/tmp/project").abs().into(),
+                    process_id: Some("123".to_string()),
+                    plugin_id: None,
+                    script_path: None,
+                    source: CommandExecutionSource::UserShell,
+                    status: ApiCommandExecutionStatus::Completed,
+                    command_actions: Vec::<CommandAction>::new(),
+                    aggregated_output: Some("a.txt\n".to_string()),
+                    exit_code: Some(0),
+                    duration_ms: Some(3),
+                }],
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![
+                ThreadEvent::ItemCompleted(ItemCompletedEvent {
+                    item: ExecThreadItem {
+                        id: "item_0".to_string(),
+                        details: ThreadItemDetails::CommandExecution(CommandExecutionItem {
+                            command: "ls".to_string(),
+                            aggregated_output: "a.txt\n".to_string(),
+                            exit_code: Some(0),
+                            status: CommandExecutionStatus::Completed,
+                        }),
+                    },
+                }),
+                ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                    usage: Usage::default(),
+                }),
+            ],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+}
+
+#[test]
+fn turn_completion_overwrites_stale_final_message_from_turn_items() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+    let _ = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "msg-stale".to_string(),
+                text: "stale answer".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![ThreadItem::AgentMessage {
+                    id: "msg-1".to_string(),
+                    text: "final answer".to_string(),
+                    phase: None,
+                    memory_citation: None,
+                    delivery: None,
+                    questions: None,
+                }],
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                usage: Usage::default(),
+            })],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+    assert_eq!(processor.final_message(), Some("final answer"));
+}
+
+#[test]
+fn turn_completion_preserves_streamed_final_message_when_turn_items_are_empty() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+    let _ = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "msg-streamed".to_string(),
+                text: "streamed answer".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                usage: Usage::default(),
+            })],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+    assert_eq!(processor.final_message(), Some("streamed answer"));
+}
+
+#[test]
+fn failed_turn_clears_stale_final_message() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ItemCompleted(
+        ItemCompletedNotification {
+            item: ThreadItem::AgentMessage {
+                id: "msg-1".to_string(),
+                text: "partial answer".to_string(),
+                phase: None,
+                memory_citation: None,
+                delivery: None,
+                questions: None,
+            },
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            completed_at_ms: 0,
+        },
+    ));
+
+    assert_eq!(collected.status, CodexStatus::Running);
+    assert_eq!(processor.final_message(), Some("partial answer"));
+
+    let collected = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Failed,
+                error: Some(TurnError {
+                    misalignment: None,
+                    message: "turn failed".to_string(),
+                    additional_details: None,
+                    codex_error_info: None,
+                }),
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(collected.status, CodexStatus::InitiateShutdown);
+    assert_eq!(processor.final_message(), None);
+}
+
+#[test]
+fn turn_completion_falls_back_to_final_plan_text() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let completed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: vec![ThreadItem::Plan {
+                    id: "plan-1".to_string(),
+                    text: "ship the typed adapter".to_string(),
+                }],
+                status: TurnStatus::Completed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+
+    assert_eq!(
+        completed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnCompleted(TurnCompletedEvent {
+                usage: Usage::default(),
+            })],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+    assert_eq!(processor.final_message(), Some("ship the typed adapter"));
+}
+
+#[test]
+fn turn_failure_prefers_structured_error_message() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let error = processor.collect_thread_events(ServerNotification::Error(ErrorNotification {
+        error: TurnError {
+            misalignment: None,
+            message: "backend failed".to_string(),
+            codex_error_info: None,
+            additional_details: Some("request id abc".to_string()),
+        },
+        will_retry: false,
+        thread_id: "thread-1".to_string(),
+        turn_id: "turn-1".to_string(),
+    }));
+    assert_eq!(
+        error,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::Error(ThreadErrorEvent {
+                message: "backend failed (request id abc)".to_string(),
+            })],
+            status: CodexStatus::Running,
+        }
+    );
+
+    let failed = processor.collect_thread_events(ServerNotification::TurnCompleted(
+        TurnCompletedNotification {
+            thread_id: "thread-1".to_string(),
+            turn: Turn {
+                id: "turn-1".to_string(),
+                items_view: codex_app_server_protocol::TurnItemsView::Full,
+                items: Vec::new(),
+                status: TurnStatus::Failed,
+                error: None,
+                started_at: None,
+                completed_at: None,
+                duration_ms: None,
+            },
+        },
+    ));
+    assert_eq!(
+        failed,
+        CollectedThreadEvents {
+            events: vec![ThreadEvent::TurnFailed(TurnFailedEvent {
+                error: ThreadErrorEvent {
+                    message: "backend failed (request id abc)".to_string(),
+                },
+            })],
+            status: CodexStatus::InitiateShutdown,
+        }
+    );
+}
+
+#[test]
+fn model_reroute_surfaces_as_error_item() {
+    let mut processor = EventProcessorWithJsonOutput::new(/*last_message_path*/ None);
+
+    let collected = processor.collect_thread_events(ServerNotification::ModelRerouted(
+        codex_app_server_protocol::ModelReroutedNotification {
+            thread_id: "thread-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            from_model: "gpt-5".to_string(),
+            to_model: "gpt-5-mini".to_string(),
+            reason: codex_app_server_protocol::ModelRerouteReason::HighRiskCyberActivity,
+        },
+    ));
+
+    assert_eq!(collected.status, CodexStatus::Running);
+    assert_eq!(collected.events.len(), 1);
+    let ThreadEvent::ItemCompleted(ItemCompletedEvent { item }) = &collected.events[0] else {
+        panic!("expected ItemCompleted");
+    };
+    assert_eq!(item.id, "item_0");
+    assert_eq!(
+        item.details,
+        ThreadItemDetails::Error(ErrorItem {
+            message: "model rerouted: gpt-5 -> gpt-5-mini (HighRiskCyberActivity)".to_string(),
+        })
+    );
+}
diff --git a/codex-rs/exec/tests/fixtures/apply_patch_freeform_final.txt b/codex-rs/exec/tests/fixtures/apply_patch_freeform_final.txt
new file mode 100644
index 0000000000000000000000000000000000000000..b01923e0e536015143ad914c46a5808daa647f4b
--- /dev/null
+++ b/codex-rs/exec/tests/fixtures/apply_patch_freeform_final.txt
@@ -0,0 +1,4 @@
+class BaseClass:
+  def method():
+
+    return True
diff --git a/codex-rs/exec/tests/suite/add_dir.rs b/codex-rs/exec/tests/suite/add_dir.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f95433d1fbcf341511e2703a3b00c1ab35236620
--- /dev/null
+++ b/codex-rs/exec/tests/suite/add_dir.rs
@@ -0,0 +1,72 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+
+/// Verify that the --add-dir flag is accepted and the command runs successfully.
+/// This test confirms the CLI argument is properly wired up.
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn accepts_add_dir_flag() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("response_1", "Task completed"),
+        responses::ev_completed("response_1"),
+    ]);
+    responses::mount_sse_once(&server, body).await;
+
+    // Create temporary directories to use with --add-dir
+    let temp_dir1 = tempfile::tempdir()?;
+    let temp_dir2 = tempfile::tempdir()?;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--sandbox")
+        .arg("workspace-write")
+        .arg("--add-dir")
+        .arg(temp_dir1.path())
+        .arg("--add-dir")
+        .arg(temp_dir2.path())
+        .arg("test with additional directories")
+        .assert()
+        .code(0);
+
+    Ok(())
+}
+
+/// Verify that multiple --add-dir flags can be specified.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn accepts_multiple_add_dir_flags() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("response_1", "Multiple directories accepted"),
+        responses::ev_completed("response_1"),
+    ]);
+    responses::mount_sse_once(&server, body).await;
+
+    let temp_dir1 = tempfile::tempdir()?;
+    let temp_dir2 = tempfile::tempdir()?;
+    let temp_dir3 = tempfile::tempdir()?;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--sandbox")
+        .arg("workspace-write")
+        .arg("--add-dir")
+        .arg(temp_dir1.path())
+        .arg("--add-dir")
+        .arg(temp_dir2.path())
+        .arg("--add-dir")
+        .arg(temp_dir3.path())
+        .arg("test with three directories")
+        .assert()
+        .code(0);
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/agents_md.rs b/codex-rs/exec/tests/suite/agents_md.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3cc47f095e86945930d7e319885521f38cf70bea
--- /dev/null
+++ b/codex-rs/exec/tests/suite/agents_md.rs
@@ -0,0 +1,74 @@
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_includes_workspace_agents_md_in_request() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    std::fs::write(test.cwd_path().join("AGENTS.md"), "workspace instructions")?;
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("tell me something")
+        .assert()
+        .success();
+
+    let user_messages = response_mock.single_request().message_input_texts("user");
+    assert!(
+        user_messages
+            .iter()
+            .any(|text| text.contains("workspace instructions")),
+        "request should include workspace AGENTS.md instructions: {user_messages:?}"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_prefers_workspace_agents_override_md() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    std::fs::write(test.cwd_path().join("AGENTS.md"), "base instructions")?;
+    std::fs::write(
+        test.cwd_path().join("AGENTS.override.md"),
+        "override instructions",
+    )?;
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("tell me something")
+        .assert()
+        .success();
+
+    let user_messages = response_mock.single_request().message_input_texts("user");
+    assert!(
+        user_messages
+            .iter()
+            .any(|text| text.contains("override instructions")),
+        "request should include AGENTS.override.md instructions: {user_messages:?}"
+    );
+    assert!(
+        user_messages
+            .iter()
+            .all(|text| !text.contains("base instructions")),
+        "request should exclude shadowed AGENTS.md instructions: {user_messages:?}"
+    );
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/apply_patch.rs b/codex-rs/exec/tests/suite/apply_patch.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8376b2e76504be8819848ca2785d21b66550b2bd
--- /dev/null
+++ b/codex-rs/exec/tests/suite/apply_patch.rs
@@ -0,0 +1,313 @@
+#![allow(clippy::unwrap_used, unused_imports)]
+
+use anyhow::Context;
+use assert_cmd::prelude::*;
+use codex_apply_patch::CODEX_CORE_APPLY_PATCH_ARG1;
+use core_test_support::responses::ev_apply_patch_custom_tool_call;
+use core_test_support::responses::ev_completed;
+use core_test_support::responses::mount_sse_sequence;
+use core_test_support::responses::sse;
+use core_test_support::responses::start_mock_server;
+use std::fs;
+use std::process::Command;
+use tempfile::tempdir;
+
+/// While we may add an `apply-patch` subcommand to the `codex` CLI multitool
+/// at some point, we must ensure that the smaller `codex-exec` CLI can still
+/// emulate the `apply_patch` CLI.
+#[test]
+fn test_standalone_exec_cli_can_use_apply_patch() -> anyhow::Result<()> {
+    let tmp = tempdir()?;
+    let relative_path = "source.txt";
+    let absolute_path = tmp.path().join(relative_path);
+    fs::write(&absolute_path, "original content\n")?;
+
+    Command::new(codex_utils_cargo_bin::cargo_bin("codex-exec")?)
+        .arg(CODEX_CORE_APPLY_PATCH_ARG1)
+        .arg(
+            r#"*** Begin Patch
+*** Update File: source.txt
+@@
+-original content
++modified by apply_patch
+*** End Patch"#,
+        )
+        .current_dir(tmp.path())
+        .assert()
+        .success()
+        .stdout("Success. Updated the following files:\nM source.txt\n")
+        .stderr(predicates::str::is_empty());
+    assert_eq!(
+        fs::read_to_string(absolute_path)?,
+        "modified by apply_patch\n"
+    );
+    Ok(())
+}
+
+#[cfg(not(target_os = "windows"))]
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn test_apply_patch_tool() -> anyhow::Result<()> {
+    use core_test_support::skip_if_no_network;
+    use core_test_support::test_codex_exec::test_codex_exec;
+
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let tmp_path = test.cwd_path().to_path_buf();
+    let add_patch = r#"*** Begin Patch
+*** Add File: test.md
++Hello world
+*** End Patch"#;
+    let update_patch = r#"*** Begin Patch
+*** Update File: test.md
+@@
+-Hello world
++Final text
+*** End Patch"#;
+    let response_streams = vec![
+        sse(vec![
+            ev_apply_patch_custom_tool_call("request_0", add_patch),
+            ev_completed("request_0"),
+        ]),
+        sse(vec![
+            ev_apply_patch_custom_tool_call("request_1", update_patch),
+            ev_completed("request_1"),
+        ]),
+        sse(vec![ev_completed("request_2")]),
+    ];
+    let server = start_mock_server().await;
+    mount_sse_sequence(&server, response_streams).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-s")
+        .arg("danger-full-access")
+        .arg("foo")
+        .assert()
+        .success();
+
+    let final_path = tmp_path.join("test.md");
+    let contents = std::fs::read_to_string(&final_path).expect("final file should be readable");
+    assert_eq!(contents, "Final text\n");
+    Ok(())
+}
+
+#[cfg(not(target_os = "windows"))]
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn test_apply_patch_freeform_tool() -> anyhow::Result<()> {
+    use core_test_support::skip_if_no_network;
+    use core_test_support::test_codex_exec::test_codex_exec;
+
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let freeform_add_patch = r#"*** Begin Patch
+*** Add File: app.py
++class BaseClass:
++  def method():
++    return False
+*** End Patch"#;
+    let freeform_update_patch = r#"*** Begin Patch
+*** Update File: app.py
+@@  def method():
+-    return False
++
++    return True
+*** End Patch"#;
+    let response_streams = vec![
+        sse(vec![
+            ev_apply_patch_custom_tool_call("request_0", freeform_add_patch),
+            ev_completed("request_0"),
+        ]),
+        sse(vec![
+            ev_apply_patch_custom_tool_call("request_1", freeform_update_patch),
+            ev_completed("request_1"),
+        ]),
+        sse(vec![ev_completed("request_2")]),
+    ];
+    let server = start_mock_server().await;
+    mount_sse_sequence(&server, response_streams).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-s")
+        .arg("danger-full-access")
+        .arg("foo")
+        .assert()
+        .success();
+
+    // Verify final file contents
+    let final_path = test.cwd_path().join("app.py");
+    let contents = std::fs::read_to_string(&final_path).expect("final file should be readable");
+    assert_eq!(
+        contents,
+        include_str!("../fixtures/apply_patch_freeform_final.txt")
+    );
+    Ok(())
+}
+
+#[cfg(not(target_os = "windows"))]
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn shutdown_flushes_completed_turn_and_file_diff() -> anyhow::Result<()> {
+    use codex_login::AuthDotJson;
+    use codex_login::AuthKeyringBackendKind;
+    use codex_login::TokenData;
+    use codex_login::save_auth;
+    use codex_login::token_data::IdTokenInfo;
+    use codex_protocol::auth::AuthMode;
+    use core_test_support::skip_if_no_network;
+    use core_test_support::test_codex_exec::test_codex_exec;
+    use std::sync::Arc;
+    use std::sync::atomic::AtomicUsize;
+    use std::sync::atomic::Ordering;
+    use std::time::Duration;
+    use wiremock::Mock;
+    use wiremock::ResponseTemplate;
+    use wiremock::matchers::method;
+
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let run_dir = test.cwd_path();
+    assert!(
+        std::process::Command::new("git")
+            .args(["init", "--quiet"])
+            .current_dir(run_dir)
+            .status()
+            .context("initialize test git repository")?
+            .success()
+    );
+    assert!(
+        std::process::Command::new("git")
+            .args([
+                "remote",
+                "add",
+                "origin",
+                "https://github.com/test-org/turn-profile-test.git",
+            ])
+            .current_dir(run_dir)
+            .status()
+            .context("add test git remote")?
+            .success()
+    );
+    save_auth(
+        test.home_path(),
+        &AuthDotJson {
+            auth_mode: Some(AuthMode::Chatgpt),
+            openai_api_key: None,
+            tokens: Some(TokenData {
+                id_token: IdTokenInfo {
+                    raw_jwt: "header.eyJhbGciOiJub25lIn0.eyJzdWIiOiJ1c2VyLTEyMyJ9.".to_string(),
+                    ..Default::default()
+                },
+                access_token: "test-access-token".to_string(),
+                refresh_token: "test-refresh-token".to_string(),
+                account_id: None,
+            }),
+            last_refresh: None,
+            agent_identity: None,
+            personal_access_token: None,
+            bedrock_api_key: None,
+            bedrock_access_keys: None,
+        },
+        codex_login::AuthCredentialsStoreMode::File,
+        AuthKeyringBackendKind::default(),
+    )?;
+
+    let server = start_mock_server().await;
+    let deliveries = Arc::new(AtomicUsize::new(0));
+    let completed_deliveries = Arc::clone(&deliveries);
+    Mock::given(method("POST"))
+        .and(|request: &wiremock::Request| request.url.path().ends_with("events"))
+        .respond_with(move |_request: &wiremock::Request| {
+            // A request is counted only once its delayed handler has completed.
+            std::thread::sleep(Duration::from_millis(750));
+            completed_deliveries.fetch_add(1, Ordering::Release);
+            ResponseTemplate::new(200)
+        })
+        .expect(3..)
+        .mount(&server)
+        .await;
+    mount_sse_sequence(
+        &server,
+        vec![
+            sse(vec![
+                ev_apply_patch_custom_tool_call(
+                    "request_0",
+                    "*** Begin Patch\n*** Add File: flushed.md\n+persist this line\n*** End Patch",
+                ),
+                ev_completed("request_0"),
+            ]),
+            sse(vec![ev_completed("request_1")]),
+        ],
+    )
+    .await;
+
+    test.cmd_with_server(&server)
+        .env_remove("CODEX_API_KEY")
+        .env_remove("CODEX_ANALYTICS_EVENTS_CAPTURE_FILE")
+        .arg("--skip-git-repo-check")
+        .arg("-s")
+        .arg("danger-full-access")
+        .arg("-c")
+        .arg("model_provider=\"test\"")
+        .arg("-c")
+        .arg(format!(
+            "model_providers.test={{name=\"test\",base_url={:?},wire_api=\"responses\",requires_openai_auth=false,supports_websockets=false}}",
+            format!("{}/v1", server.uri())
+        ))
+        .arg("-c")
+        .arg("analytics.enabled=true")
+        .arg("-c")
+        .arg(format!("chatgpt_base_url={}", server.uri()))
+        .arg("write the file")
+        .assert()
+        .success();
+
+    let persisted = std::fs::read_to_string(run_dir.join("flushed.md"))
+        .context("read file written by apply_patch")?;
+    assert_eq!(persisted, "persist this line\n");
+
+    let requests = server
+        .received_requests()
+        .await
+        .context("read analytics requests")?;
+    let request_paths = requests
+        .iter()
+        .map(|request| request.url.path().to_string())
+        .collect::<Vec<_>>();
+    let event_types = requests
+        .iter()
+        .filter(|request| request.url.path().ends_with("events"))
+        .flat_map(|request| {
+            serde_json::from_slice::<serde_json::Value>(&request.body)
+                .ok()
+                .and_then(|body| {
+                    body.get("events")
+                        .and_then(serde_json::Value::as_array)
+                        .cloned()
+                })
+                .unwrap_or_default()
+                .into_iter()
+                .filter_map(|event| event["event_type"].as_str().map(str::to_owned))
+                .collect::<Vec<_>>()
+        })
+        .collect::<Vec<_>>();
+    assert!(
+        deliveries.load(Ordering::Acquire) >= 3,
+        "the runtime exited before the delayed analytics deliveries completed (completed={}, events={event_types:?}, paths={request_paths:?})",
+        deliveries.load(Ordering::Acquire)
+    );
+    assert!(
+        event_types.iter().any(|event| event == "codex_turn_event"),
+        "no completed event was delivered; request paths: {request_paths:?}"
+    );
+    assert!(
+        event_types
+            .iter()
+            .any(|event| event == "codex_accepted_line_fingerprints"),
+        "no accepted-line event was delivered; request paths: {request_paths:?}"
+    );
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/approval_policy.rs b/codex-rs/exec/tests/suite/approval_policy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5efb6d0bdad5a2bd9fdf4f5f3e14587001ad0b16
--- /dev/null
+++ b/codex-rs/exec/tests/suite/approval_policy.rs
@@ -0,0 +1,78 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+
+async fn run_exec_with_config(config_toml: &str, extra_args: &[&str]) -> anyhow::Result<String> {
+    let test = test_codex_exec();
+    std::fs::write(test.home_path().join("config.toml"), config_toml)?;
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("response_1", "done"),
+        responses::ev_completed("response_1"),
+    ]);
+    responses::mount_sse_once(&server, body).await;
+
+    let mut cmd = test.cmd_with_server(&server);
+    let output = cmd
+        .arg("--skip-git-repo-check")
+        .args(extra_args)
+        .arg("check approval mode")
+        .output()?;
+
+    assert!(output.status.success(), "exec run failed: {output:?}");
+
+    Ok(String::from_utf8(output.stderr)?)
+}
+
+async fn run_exec_with_auto_review_config(extra_args: &[&str]) -> anyhow::Result<String> {
+    run_exec_with_config(
+        r#"
+approval_policy = "on-request"
+approvals_reviewer = "auto_review"
+"#,
+        extra_args,
+    )
+    .await
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_preserves_on_request_for_auto_review_config() -> anyhow::Result<()> {
+    let stderr = run_exec_with_auto_review_config(&[]).await?;
+    assert!(
+        stderr.contains("approval: on-request"),
+        "stderr missing preserved auto-review approval mode: {stderr}"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_approve_for_me_flag_sets_approval_mode_and_sandbox() -> anyhow::Result<()> {
+    let stderr = run_exec_with_config("", &["--approve-for-me"]).await?;
+    assert!(
+        stderr.contains("approval: on-request"),
+        "stderr missing --approve-for-me approval mode: {stderr}"
+    );
+    assert!(
+        stderr.contains("sandbox: workspace-write"),
+        "stderr missing --approve-for-me sandbox mode: {stderr}"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_bypass_preserves_never_for_auto_review_config() -> anyhow::Result<()> {
+    let stderr =
+        run_exec_with_auto_review_config(&["--dangerously-bypass-approvals-and-sandbox"]).await?;
+    assert!(
+        stderr.contains("approval: never"),
+        "stderr missing bypass approval mode: {stderr}"
+    );
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/auth_env.rs b/codex-rs/exec/tests/suite/auth_env.rs
new file mode 100644
index 0000000000000000000000000000000000000000..179f40fbd40dd2f2a7a88b1736f19335c382a387
--- /dev/null
+++ b/codex-rs/exec/tests/suite/auth_env.rs
@@ -0,0 +1,31 @@
+#![allow(clippy::unwrap_used)]
+use core_test_support::responses::ev_completed;
+use core_test_support::responses::mount_sse_once_match;
+use core_test_support::responses::sse;
+use core_test_support::responses::start_mock_server;
+use core_test_support::test_codex_exec::test_codex_exec;
+use wiremock::matchers::header;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_uses_codex_api_key_env_var() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let server = start_mock_server().await;
+    let repo_root = codex_utils_cargo_bin::repo_root()?;
+
+    mount_sse_once_match(
+        &server,
+        header("Authorization", "Bearer dummy"),
+        sse(vec![ev_completed("request_0")]),
+    )
+    .await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg("echo testing codex api key")
+        .assert()
+        .success();
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/completion_backfill_tests.rs b/codex-rs/exec/tests/suite/completion_backfill_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..939fb1c69505a87804d0d2434fcbb37724a893bc
--- /dev/null
+++ b/codex-rs/exec/tests/suite/completion_backfill_tests.rs
@@ -0,0 +1,162 @@
+use core_test_support::responses;
+use core_test_support::skip_if_no_network;
+use core_test_support::test_codex_exec::test_codex_exec;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+const PARENT_PROMPT: &str = "spawn a child and wait for it";
+const CHILD_PROMPT: &str = "child: finish first";
+const SPAWN_CALL_ID: &str = "spawn-call";
+const WAIT_CALL_ID: &str = "wait-call";
+
+fn body_contains(request: &wiremock::Request, text: &str) -> bool {
+    std::str::from_utf8(&request.body).is_ok_and(|body| body.contains(text))
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn ignores_unrelated_turn_completion_before_backfilling_primary_turn() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = responses::start_mock_server().await;
+    let spawn_args = json!({
+        "message": CHILD_PROMPT,
+        "task_name": "worker",
+        "fork_turns": "none",
+    })
+    .to_string();
+    let _parent_turn = responses::mount_sse_once_match(
+        &server,
+        |request: &wiremock::Request| body_contains(request, PARENT_PROMPT),
+        responses::sse(vec![
+            responses::ev_response_created("resp-parent-1"),
+            responses::ev_function_call_with_namespace(
+                SPAWN_CALL_ID,
+                "collaboration",
+                "spawn_agent",
+                &spawn_args,
+            ),
+            responses::ev_completed("resp-parent-1"),
+        ]),
+    )
+    .await;
+    let _child_turn = responses::mount_sse_once_match(
+        &server,
+        |request: &wiremock::Request| {
+            body_contains(request, CHILD_PROMPT) && !body_contains(request, SPAWN_CALL_ID)
+        },
+        responses::sse(vec![
+            responses::ev_response_created("resp-child"),
+            responses::ev_assistant_message("msg-child", "child done"),
+            responses::ev_completed("resp-child"),
+        ]),
+    )
+    .await;
+    let _parent_wait = responses::mount_sse_once_match(
+        &server,
+        |request: &wiremock::Request| {
+            body_contains(request, SPAWN_CALL_ID) && !body_contains(request, WAIT_CALL_ID)
+        },
+        responses::sse(vec![
+            responses::ev_response_created("resp-parent-2"),
+            responses::ev_function_call_with_namespace(
+                WAIT_CALL_ID,
+                "collaboration",
+                "wait_agent",
+                "{}",
+            ),
+            responses::ev_completed("resp-parent-2"),
+        ]),
+    )
+    .await;
+    let _parent_completion = responses::mount_sse_once_match(
+        &server,
+        |request: &wiremock::Request| body_contains(request, WAIT_CALL_ID),
+        responses::sse(vec![
+            responses::ev_response_created("resp-parent-3"),
+            responses::ev_assistant_message("msg-parent", "parent done"),
+            responses::ev_completed("resp-parent-3"),
+        ]),
+    )
+    .await;
+
+    let test = test_codex_exec();
+    let mock_provider = format!(
+        "model_providers.mock_provider={{name=\"Mock provider for test\",base_url=\"{}/v1\",wire_api=\"responses\",supports_websockets=false}}",
+        server.uri()
+    );
+    let output = test
+        .cmd()
+        .env(
+            "RUST_LOG",
+            "codex_app_server::message_processor=trace,codex_app_server::outgoing_message=trace",
+        )
+        .arg("--skip-git-repo-check")
+        .arg("--json")
+        .arg("-c")
+        .arg(mock_provider)
+        .args([
+            "-c",
+            "model_provider=\"mock_provider\"",
+            "-c",
+            "features.multi_agent=true",
+            "-c",
+            "features.multi_agent_v2=true",
+            "-c",
+            "features.enable_request_compression=false",
+        ])
+        .arg(PARENT_PROMPT)
+        .output()?;
+    assert!(output.status.success(), "exec run failed: {output:?}");
+
+    let stdout = String::from_utf8(output.stdout)?;
+    assert!(
+        stdout.contains("parent done"),
+        "primary completion was not processed: {stdout}"
+    );
+    let stderr = String::from_utf8(output.stderr)?;
+    let lines = stderr.lines().collect::<Vec<_>>();
+    let turn_completions = lines
+        .iter()
+        .enumerate()
+        .filter_map(|(index, line)| {
+            line.contains("app-server event: turn/completed")
+                .then_some(index)
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(
+        turn_completions.len(),
+        2,
+        "expected the child completion before the primary completion: {stderr}"
+    );
+
+    let [child_completion, primary_completion] = turn_completions.as_slice() else {
+        unreachable!("checked turn/completed count")
+    };
+    assert_eq!(
+        lines[*child_completion + 1..*primary_completion]
+            .iter()
+            .filter(|line| line.contains("app-server typed request"))
+            .count(),
+        0,
+        "the unrelated completion must not issue thread/read: {stderr}"
+    );
+    assert_eq!(
+        lines[*primary_completion + 1..]
+            .iter()
+            .filter(|line| line.contains("app-server typed request"))
+            .count(),
+        2,
+        "the primary completion should issue thread/read and thread/unsubscribe: {stderr}"
+    );
+
+    assert_eq!(
+        lines
+            .iter()
+            .filter(|line| line.contains("app-server typed request"))
+            .count(),
+        5,
+        "only the primary completion should issue an extra request: {stderr}"
+    );
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/ephemeral.rs b/codex-rs/exec/tests/suite/ephemeral.rs
new file mode 100644
index 0000000000000000000000000000000000000000..83522e4bd1572503c361ebb8f13fd04ca8812d0b
--- /dev/null
+++ b/codex-rs/exec/tests/suite/ephemeral.rs
@@ -0,0 +1,67 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::skip_if_no_network;
+use core_test_support::test_codex_exec::test_codex_exec;
+use walkdir::WalkDir;
+use wiremock::MockServer;
+
+fn exec_sse_response() -> String {
+    responses::sse(vec![
+        responses::ev_response_created("resp-ephemeral"),
+        responses::ev_assistant_message("msg-ephemeral", "ephemeral response"),
+        responses::ev_completed("resp-ephemeral"),
+    ])
+}
+
+fn session_rollout_count(home_path: &std::path::Path) -> usize {
+    let sessions_dir = home_path.join("sessions");
+    if !sessions_dir.exists() {
+        return 0;
+    }
+
+    WalkDir::new(sessions_dir)
+        .into_iter()
+        .filter_map(Result::ok)
+        .filter(|entry| entry.file_type().is_file())
+        .filter(|entry| entry.file_name().to_string_lossy().ends_with(".jsonl"))
+        .count()
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn persists_rollout_file_by_default() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = responses::mount_sse_once(&server, exec_sse_response()).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("default persistence behavior")
+        .assert()
+        .code(0);
+
+    assert_eq!(session_rollout_count(test.home_path()), 1);
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn does_not_persist_rollout_file_in_ephemeral_mode() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = responses::mount_sse_once(&server, exec_sse_response()).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--ephemeral")
+        .arg("ephemeral behavior")
+        .assert()
+        .code(0);
+
+    assert_eq!(session_rollout_count(test.home_path()), 0);
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/hooks.rs b/codex-rs/exec/tests/suite/hooks.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7be9480d11db64bf720999a52de70492370fec8b
--- /dev/null
+++ b/codex-rs/exec/tests/suite/hooks.rs
@@ -0,0 +1,43 @@
+#![cfg(not(target_os = "windows"))]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+use serde_json::json;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_hook_trust_bypass_runs_session_start_hook() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let marker_path = test.home_path().join("session-start-ran");
+    let command = format!("touch {}", marker_path.display());
+    std::fs::write(
+        test.home_path().join("hooks.json"),
+        serde_json::to_vec_pretty(&json!({
+            "hooks": {
+                "SessionStart": [{
+                    "hooks": [{
+                        "type": "command",
+                        "command": command,
+                    }],
+                }],
+            },
+        }))?,
+    )?;
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("response_1", "done"),
+        responses::ev_completed("response_1"),
+    ]);
+    responses::mount_sse_once(&server, body).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--dangerously-bypass-hook-trust")
+        .arg("run the session start hook")
+        .assert()
+        .success();
+
+    assert!(marker_path.exists(), "session start hook did not run");
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/mcp_required_exit.rs b/codex-rs/exec/tests/suite/mcp_required_exit.rs
new file mode 100644
index 0000000000000000000000000000000000000000..738dc3a5d4c471545c86e646631558b54db216d6
--- /dev/null
+++ b/codex-rs/exec/tests/suite/mcp_required_exit.rs
@@ -0,0 +1,38 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+use predicates::str::contains;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exits_non_zero_when_required_mcp_server_fails_to_initialize() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    let config_toml = r#"
+        [mcp_servers.required_broken]
+        command = "codex-definitely-not-a-real-binary"
+        required = true
+    "#;
+    std::fs::write(test.home_path().join("config.toml"), config_toml)?;
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp_1"),
+        responses::ev_assistant_message("msg_1", "hello"),
+        responses::ev_completed("resp_1"),
+    ]);
+    responses::mount_sse_once(&server, body).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--experimental-json")
+        .arg("tell me something")
+        .assert()
+        .code(1)
+        .stderr(contains(
+            "required MCP servers failed to initialize: required_broken",
+        ));
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/mod.rs b/codex-rs/exec/tests/suite/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4f7a3ab89fc91ad3c974f58ea8cd84c7ef74baee
--- /dev/null
+++ b/codex-rs/exec/tests/suite/mod.rs
@@ -0,0 +1,20 @@
+// Aggregates all former standalone integration tests as modules.
+mod add_dir;
+mod agents_md;
+mod apply_patch;
+mod approval_policy;
+mod auth_env;
+#[path = "completion_backfill_tests.rs"]
+mod completion_backfill;
+mod ephemeral;
+mod hooks;
+mod mcp_required_exit;
+mod originator;
+mod output_schema;
+mod prompt_stdin;
+mod resume;
+mod sandbox;
+#[cfg(target_os = "macos")]
+mod seatbelt;
+mod server_error_exit;
+mod worktree;
diff --git a/codex-rs/exec/tests/suite/originator.rs b/codex-rs/exec/tests/suite/originator.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d2a1f829f5ce5b1967b5717409980cc5e9bee917
--- /dev/null
+++ b/codex-rs/exec/tests/suite/originator.rs
@@ -0,0 +1,54 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use codex_login::default_client::CODEX_INTERNAL_ORIGINATOR_OVERRIDE_ENV_VAR;
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+use wiremock::matchers::header;
+
+/// Verify that when the server reports an error, `codex-exec` exits with a
+/// non-zero status code so automation can detect failures.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn send_codex_exec_originator() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("response_1", "Hello, world!"),
+        responses::ev_completed("response_1"),
+    ]);
+    responses::mount_sse_once_match(&server, header("Originator", "codex_exec"), body).await;
+
+    test.cmd_with_server(&server)
+        .env_remove(CODEX_INTERNAL_ORIGINATOR_OVERRIDE_ENV_VAR)
+        .arg("--skip-git-repo-check")
+        .arg("tell me something")
+        .assert()
+        .code(0);
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn supports_originator_override() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("response_1", "Hello, world!"),
+        responses::ev_completed("response_1"),
+    ]);
+    responses::mount_sse_once_match(&server, header("Originator", "codex_exec_override"), body)
+        .await;
+
+    test.cmd_with_server(&server)
+        .env("CODEX_INTERNAL_ORIGINATOR_OVERRIDE", "codex_exec_override")
+        .arg("--skip-git-repo-check")
+        .arg("tell me something")
+        .assert()
+        .code(0);
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/output_schema.rs b/codex-rs/exec/tests/suite/output_schema.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bfc9e8e589d5c7a271e2230b4732bdc94ccd4d34
--- /dev/null
+++ b/codex-rs/exec/tests/suite/output_schema.rs
@@ -0,0 +1,62 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+use serde_json::Value;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_includes_output_schema_in_request() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    let schema_contents = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "answer": { "type": "string" }
+        },
+        "required": ["answer"],
+        "additionalProperties": false
+    });
+    let schema_path = test.cwd_path().join("schema.json");
+    std::fs::write(&schema_path, serde_json::to_vec_pretty(&schema_contents)?)?;
+    let expected_schema: Value = schema_contents;
+
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        // keep using -C in the test to exercise the flag as well
+        .arg("-C")
+        .arg(test.cwd_path())
+        .arg("--output-schema")
+        .arg(&schema_path)
+        .arg("-m")
+        .arg("gpt-5.1")
+        .arg("tell me a joke")
+        .assert()
+        .success();
+
+    let request = response_mock.single_request();
+    let payload: Value = request.body_json();
+    let text = payload.get("text").expect("request missing text field");
+    let format = text
+        .get("format")
+        .expect("request missing text.format field");
+    assert_eq!(
+        format,
+        &serde_json::json!({
+            "name": "codex_output_schema",
+            "type": "json_schema",
+            "strict": true,
+            "schema": expected_schema,
+        })
+    );
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/prompt_stdin.rs b/codex-rs/exec/tests/suite/prompt_stdin.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4789fa42aec41d7c808bdd0f286affa33a0f108d
--- /dev/null
+++ b/codex-rs/exec/tests/suite/prompt_stdin.rs
@@ -0,0 +1,171 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+use predicates::str::contains;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_appends_piped_stdin_to_prompt_argument() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    // echo "my output" | codex exec --skip-git-repo-check -C <cwd> -m gpt-5.1 "Summarize this concisely"
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.cwd_path())
+        .arg("-m")
+        .arg("gpt-5.1")
+        .arg("Summarize this concisely")
+        .write_stdin("my output\n")
+        .assert()
+        .success();
+
+    let request = response_mock.single_request();
+    assert!(
+        request.has_message_with_input_texts("user", |texts| {
+            texts == ["Summarize this concisely\n\n<stdin>\nmy output\n</stdin>".to_string()]
+        }),
+        "request should include a user message with the prompt plus piped stdin context"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_ignores_empty_piped_stdin_when_prompt_argument_is_present() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    // printf "" | codex exec --skip-git-repo-check -C <cwd> -m gpt-5.1 "Summarize this concisely"
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.cwd_path())
+        .arg("-m")
+        .arg("gpt-5.1")
+        .arg("Summarize this concisely")
+        .write_stdin("")
+        .assert()
+        .success();
+
+    let request = response_mock.single_request();
+    assert!(
+        request.has_message_with_input_texts("user", |texts| texts
+            == ["Summarize this concisely".to_string()]),
+        "request should preserve the prompt when stdin is empty"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_dash_prompt_reads_stdin_as_the_prompt() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    // echo "prompt from stdin" | codex exec --skip-git-repo-check -C <cwd> -m gpt-5.1 -
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.cwd_path())
+        .arg("-m")
+        .arg("gpt-5.1")
+        .arg("-")
+        .write_stdin("prompt from stdin\n")
+        .assert()
+        .success();
+
+    let request = response_mock.single_request();
+    assert!(
+        request.has_message_with_input_texts("user", |texts| {
+            texts == ["prompt from stdin\n".to_string()]
+        }),
+        "dash prompt should preserve the existing forced-stdin behavior"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_without_prompt_argument_reads_piped_stdin_as_the_prompt() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![
+        responses::ev_response_created("resp1"),
+        responses::ev_assistant_message("m1", "fixture hello"),
+        responses::ev_completed("resp1"),
+    ]);
+    let response_mock = responses::mount_sse_once(&server, body).await;
+
+    // echo "prompt from stdin" | codex exec --skip-git-repo-check -C <cwd> -m gpt-5.1
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.cwd_path())
+        .arg("-m")
+        .arg("gpt-5.1")
+        .write_stdin("prompt from stdin\n")
+        .assert()
+        .success();
+
+    let request = response_mock.single_request();
+    assert!(
+        request.has_message_with_input_texts("user", |texts| {
+            texts == ["prompt from stdin\n".to_string()]
+        }),
+        "missing prompt argument should preserve the existing piped-stdin prompt behavior"
+    );
+
+    Ok(())
+}
+
+#[test]
+fn exec_without_prompt_argument_rejects_empty_piped_stdin() {
+    let test = test_codex_exec();
+
+    // printf "" | codex exec --skip-git-repo-check -C <cwd>
+    test.cmd()
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.cwd_path())
+        .write_stdin("")
+        .assert()
+        .code(1)
+        .stderr(contains("No prompt provided via stdin."));
+}
+
+#[test]
+fn exec_dash_prompt_rejects_empty_piped_stdin() {
+    let test = test_codex_exec();
+
+    // printf "" | codex exec --skip-git-repo-check -C <cwd> -
+    test.cmd()
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.cwd_path())
+        .arg("-")
+        .write_stdin("")
+        .assert()
+        .code(1)
+        .stderr(contains("No prompt provided via stdin."));
+}
diff --git a/codex-rs/exec/tests/suite/resume.rs b/codex-rs/exec/tests/suite/resume.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d318bcf73792b6e85af7852022e9ec87746467df
--- /dev/null
+++ b/codex-rs/exec/tests/suite/resume.rs
@@ -0,0 +1,1054 @@
+#![allow(clippy::unwrap_used)]
+use anyhow::Context;
+use codex_core::config::ConfigBuilder;
+use codex_core::init_state_db;
+use codex_protocol::ThreadId;
+use core_test_support::responses;
+use core_test_support::skip_if_no_network;
+use core_test_support::test_codex_exec::test_codex_exec;
+use pretty_assertions::assert_eq;
+use serde_json::Value;
+use std::process::Stdio;
+use std::string::ToString;
+use std::time::Duration;
+use tempfile::TempDir;
+use uuid::Uuid;
+use walkdir::WalkDir;
+use wiremock::MockServer;
+
+/// Utility: scan the sessions dir for a rollout file that contains `marker`
+/// in any response_item.message.content entry. Returns the absolute path.
+fn find_session_file_containing_marker(
+    sessions_dir: &std::path::Path,
+    marker: &str,
+) -> Option<std::path::PathBuf> {
+    for entry in WalkDir::new(sessions_dir) {
+        let entry = match entry {
+            Ok(e) => e,
+            Err(_) => continue,
+        };
+        if !entry.file_type().is_file() {
+            continue;
+        }
+        if !entry.file_name().to_string_lossy().ends_with(".jsonl") {
+            continue;
+        }
+        let path = entry.path();
+        let Ok(content) = std::fs::read_to_string(path) else {
+            continue;
+        };
+        // Skip the first meta line and scan remaining JSONL entries.
+        let mut lines = content.lines();
+        if lines.next().is_none() {
+            continue;
+        }
+        for line in lines {
+            if line.trim().is_empty() {
+                continue;
+            }
+            let Ok(item): Result<Value, _> = serde_json::from_str(line) else {
+                continue;
+            };
+            if item.get("type").and_then(|t| t.as_str()) == Some("response_item")
+                && let Some(payload) = item.get("payload")
+                && payload.get("type").and_then(|t| t.as_str()) == Some("message")
+                && payload
+                    .get("content")
+                    .map(ToString::to_string)
+                    .unwrap_or_default()
+                    .contains(marker)
+            {
+                return Some(path.to_path_buf());
+            }
+        }
+    }
+    None
+}
+
+/// Extract the conversation UUID from the first SessionMeta line in the rollout file.
+fn extract_conversation_id(path: &std::path::Path) -> String {
+    let content = std::fs::read_to_string(path).unwrap();
+    let mut lines = content.lines();
+    let meta_line = lines.next().expect("missing meta line");
+    let meta: Value = serde_json::from_str(meta_line).expect("invalid meta json");
+    meta.get("payload")
+        .and_then(|p| p.get("id"))
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .to_string()
+}
+
+fn last_user_image_count(path: &std::path::Path) -> usize {
+    let content = std::fs::read_to_string(path).unwrap_or_default();
+    let mut last_count = 0;
+    for line in content.lines() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let Ok(item): Result<Value, _> = serde_json::from_str(line) else {
+            continue;
+        };
+        if item.get("type").and_then(|t| t.as_str()) != Some("response_item") {
+            continue;
+        }
+        let Some(payload) = item.get("payload") else {
+            continue;
+        };
+        if payload.get("type").and_then(|t| t.as_str()) != Some("message") {
+            continue;
+        }
+        if payload.get("role").and_then(|r| r.as_str()) != Some("user") {
+            continue;
+        }
+        let Some(content_items) = payload.get("content").and_then(|v| v.as_array()) else {
+            continue;
+        };
+        last_count = content_items
+            .iter()
+            .filter(|entry| entry.get("type").and_then(|t| t.as_str()) == Some("input_image"))
+            .count();
+    }
+    last_count
+}
+
+fn exec_repo_root() -> anyhow::Result<std::path::PathBuf> {
+    Ok(codex_utils_cargo_bin::repo_root()?)
+}
+
+fn exec_sse_response(index: usize) -> String {
+    let response_id = format!("resp-exec-{index}");
+    let message_id = format!("msg-exec-{index}");
+    responses::sse(vec![
+        responses::ev_response_created(&response_id),
+        responses::ev_assistant_message(&message_id, "exec response"),
+        responses::ev_completed(&response_id),
+    ])
+}
+
+async fn mount_exec_responses(
+    server: &MockServer,
+    count: usize,
+) -> core_test_support::responses::ResponseMock {
+    responses::mount_sse_sequence(server, (0..count).map(exec_sse_response).collect()).await
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_falls_back_to_legacy_history_when_thread_store_cannot_paginate() -> anyhow::Result<()>
+{
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 1).await;
+    let store_id = Uuid::new_v4();
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-c")
+        .arg(format!(
+            "experimental_thread_store={{type=\"in_memory\",id=\"{store_id}\"}}"
+        ))
+        .arg("continue without paginated history")
+        .assert()
+        .success();
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_last_appends_to_existing_file() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let response_mock = responses::mount_sse_sequence(
+        &server,
+        vec![
+            responses::sse(vec![
+                responses::ev_response_created("resp-exec-0"),
+                responses::ev_assistant_message("msg-exec-0", "exec response"),
+                responses::ev_completed_with_tokens("resp-exec-0", /*total_tokens*/ 7),
+            ]),
+            exec_sse_response(/*index*/ 1),
+        ],
+    )
+    .await;
+    let repo_root = exec_repo_root()?;
+
+    // 1) First run: create a session with a unique marker in the content.
+    let marker = format!("resume-last-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    // Find the created session file containing the marker.
+    let sessions_dir = test.home_path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+    let content = std::fs::read_to_string(&path)?;
+    let meta: Value = serde_json::from_str(
+        content
+            .lines()
+            .next()
+            .expect("rollout should contain session metadata"),
+    )?;
+    assert_eq!(meta["payload"]["history_mode"], "paginated");
+    assert_eq!(meta["payload"]["thread_source"], "user");
+
+    // 2) Second run: resume the most recent file with a new marker.
+    let marker2 = format!("resume-last-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    let output = test
+        .cmd_with_server(&server)
+        .env("RUST_LOG", "codex_app_server::outgoing_message=trace")
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt2)
+        .arg("resume")
+        .arg("--last")
+        .output()
+        .context("resume run should succeed")?;
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(output.status.success(), "resume failed: {stderr}");
+    assert_eq!(
+        stderr
+            .matches("app-server event: thread/tokenUsage/updated")
+            .count(),
+        2,
+        "paginated resume should replay restored token usage before the new turn: {stderr}"
+    );
+
+    // Ensure the same file was updated and contains both markers.
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(
+        resumed_path, path,
+        "resume --last should append to existing file"
+    );
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    let requests = response_mock.requests();
+    assert_eq!(requests.len(), 2);
+    let resumed_request = requests[1].body_json().to_string();
+    assert!(resumed_request.contains(&marker));
+    assert!(resumed_request.contains(&marker2));
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_last_repairs_rollout_missing_from_state_db() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+    let repo_root = exec_repo_root()?;
+
+    let marker = format!("resume-last-repair-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(format!("echo {marker}"))
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+    let thread_id = ThreadId::from_string(&extract_conversation_id(&path))?;
+    let config = ConfigBuilder::default()
+        .codex_home(test.home_path().to_path_buf())
+        .build()
+        .await?;
+    let state_db = init_state_db(&config)
+        .await
+        .expect("state DB should initialize");
+    assert_eq!(state_db.delete_thread(thread_id).await?, 1);
+    state_db
+        .mark_backfill_complete(/*last_watermark*/ None)
+        .await?;
+
+    let resumed_marker = format!("resume-last-repaired-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg("resume")
+        .arg("--last")
+        .arg(format!("echo {resumed_marker}"))
+        .assert()
+        .success();
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &resumed_marker)
+        .expect("no resumed session file after SQLite repair");
+    assert_eq!(resumed_path, path);
+    assert!(state_db.get_thread(thread_id).await?.is_some());
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_last_trusts_usable_state_db_candidate() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 3).await;
+    let repo_root = exec_repo_root()?;
+    let sessions_dir = test.home_path().join("sessions");
+
+    let older_marker = format!("resume-last-indexed-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(format!("echo {older_marker}"))
+        .assert()
+        .success();
+    let older_path = find_session_file_containing_marker(&sessions_dir, &older_marker)
+        .expect("no indexed session file after first run");
+
+    let newer_marker = format!("resume-last-unindexed-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(format!("echo {newer_marker}"))
+        .assert()
+        .success();
+    let newer_path = find_session_file_containing_marker(&sessions_dir, &newer_marker)
+        .expect("no unindexed session file after second run");
+    let newer_thread_id = ThreadId::from_string(&extract_conversation_id(&newer_path))?;
+
+    let config = ConfigBuilder::default()
+        .codex_home(test.home_path().to_path_buf())
+        .build()
+        .await?;
+    let state_db = init_state_db(&config)
+        .await
+        .expect("state DB should initialize");
+    assert_eq!(state_db.delete_thread(newer_thread_id).await?, 1);
+    state_db
+        .mark_backfill_complete(/*last_watermark*/ None)
+        .await?;
+
+    let resumed_marker = format!("resume-last-authoritative-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg("resume")
+        .arg("--last")
+        .arg(format!("echo {resumed_marker}"))
+        .assert()
+        .success();
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &resumed_marker)
+        .expect("no resumed session file after SQLite lookup");
+    assert_eq!(
+        (
+            resumed_path,
+            state_db
+                .get_thread(newer_thread_id)
+                .await?
+                .map(|metadata| metadata.id),
+        ),
+        (older_path, None),
+    );
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_last_skips_mismatched_state_db_candidate() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 3).await;
+    let repo_root = exec_repo_root()?;
+    let sessions_dir = test.home_path().join("sessions");
+
+    let older_marker = format!("resume-last-valid-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(format!("echo {older_marker}"))
+        .assert()
+        .success();
+    let older_path = find_session_file_containing_marker(&sessions_dir, &older_marker)
+        .expect("no valid session file after first run");
+
+    let newer_marker = format!("resume-last-mismatched-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(format!("echo {newer_marker}"))
+        .assert()
+        .success();
+    let newer_path = find_session_file_containing_marker(&sessions_dir, &newer_marker)
+        .expect("no mismatched session file after second run");
+    let newer_thread_id = ThreadId::from_string(&extract_conversation_id(&newer_path))?;
+
+    let config = ConfigBuilder::default()
+        .codex_home(test.home_path().to_path_buf())
+        .build()
+        .await?;
+    let state_db = init_state_db(&config)
+        .await
+        .expect("state DB should initialize");
+    let mut mismatched = state_db
+        .get_thread(newer_thread_id)
+        .await?
+        .expect("newer thread should be indexed");
+    mismatched.rollout_path = older_path.clone();
+    state_db.upsert_thread(&mismatched).await?;
+
+    let resumed_marker = format!("resume-last-valid-resumed-{}", Uuid::new_v4());
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg("resume")
+        .arg("--last")
+        .arg(format!("echo {resumed_marker}"))
+        .assert()
+        .success();
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &resumed_marker)
+        .expect("no resumed session file after skipping mismatched SQLite row");
+    assert_eq!(resumed_path, older_path);
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_last_accepts_prompt_after_flag_in_json_mode() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+    let repo_root = exec_repo_root()?;
+
+    // 1) First run: create a session with a unique marker in the content.
+    let marker = format!("resume-last-json-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    // Find the created session file containing the marker.
+    let sessions_dir = test.home_path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+
+    // 2) Second run: resume the most recent file and pass the prompt after --last.
+    let marker2 = format!("resume-last-json-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg("--json")
+        .arg("resume")
+        .arg("--last")
+        .arg(&prompt2)
+        .assert()
+        .success();
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(
+        resumed_path, path,
+        "resume --last should append to existing file"
+    );
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_last_respects_cwd_filter_and_all_flag() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 5).await;
+
+    let dir_a = TempDir::new()?;
+    let dir_b = TempDir::new()?;
+
+    let marker_a = format!("resume-cwd-a-{}", Uuid::new_v4());
+    let prompt_a = format!("echo {marker_a}");
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(dir_a.path())
+        .arg(&prompt_a)
+        .assert()
+        .success();
+
+    let marker_b = format!("resume-cwd-b-{}", Uuid::new_v4());
+    let prompt_b = format!("echo {marker_b}");
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(dir_b.path())
+        .arg(&prompt_b)
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    find_session_file_containing_marker(&sessions_dir, &marker_a)
+        .expect("no session file found for marker_a");
+    let path_b = find_session_file_containing_marker(&sessions_dir, &marker_b)
+        .expect("no session file found for marker_b");
+
+    // `updated_at` is second-granularity, so ensure the touch lands in a later second
+    // than the initial session creation on fast CI (especially Windows).
+    std::thread::sleep(std::time::Duration::from_millis(1100));
+
+    // Make thread B deterministically newest according to rollout metadata.
+    let session_id_b = extract_conversation_id(&path_b);
+    let marker_b_touch = format!("resume-cwd-b-touch-{}", Uuid::new_v4());
+    let prompt_b_touch = format!("echo {marker_b_touch}");
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(dir_b.path())
+        .arg("resume")
+        .arg(&session_id_b)
+        .arg(&prompt_b_touch)
+        .assert()
+        .success();
+
+    // `resume --last` sorts by `updated_at`, which is second-granularity. Sleep so
+    // the upcoming `resume --last --all` write lands in a later second and becomes
+    // deterministically newest (instead of tying and falling back to UUID order).
+    std::thread::sleep(std::time::Duration::from_millis(1100));
+
+    let marker_b2 = format!("resume-cwd-b-2-{}", Uuid::new_v4());
+    let prompt_b2 = format!("echo {marker_b2}");
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(dir_a.path())
+        .arg("resume")
+        .arg("--last")
+        .arg("--all")
+        .arg(&prompt_b2)
+        .assert()
+        .success();
+
+    let resumed_path_all = find_session_file_containing_marker(&sessions_dir, &marker_b2)
+        .expect("no resumed session file containing marker_b2");
+    assert_eq!(
+        resumed_path_all, path_b,
+        "resume --last --all should pick newest session"
+    );
+
+    // Selection must still use the latest turn's cwd when only the compressed rollout exists.
+    zstd::stream::copy_encode(
+        std::fs::File::open(&path_b)?,
+        std::fs::File::create(path_b.with_extension("jsonl.zst"))?,
+        /*level*/ 3,
+    )?;
+    std::fs::remove_file(&path_b)?;
+
+    let marker_a2 = format!("resume-cwd-a-2-{}", Uuid::new_v4());
+    let prompt_a2 = format!("echo {marker_a2}");
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(dir_a.path())
+        .arg("resume")
+        .arg("--last")
+        .arg(&prompt_a2)
+        .assert()
+        .success();
+
+    let resumed_path_cwd = find_session_file_containing_marker(&sessions_dir, &marker_a2)
+        .expect("no resumed session file containing marker_a2");
+    // The `--all` resume above appends a new turn to `path_b` while running from `dir_a`, so the
+    // session's latest cwd now matches `dir_a`. A subsequent `resume --last` should therefore pick
+    // the newest matching session (`path_b`).
+    assert_eq!(
+        resumed_path_cwd, path_b,
+        "resume --last should prefer sessions whose latest turn context matches the current cwd"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_accepts_global_flags_after_subcommand() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+
+    // Seed a session.
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("echo seed-resume-session")
+        .assert()
+        .success();
+
+    // Resume while passing global flags after the subcommand to ensure clap accepts them.
+    let base = format!("{}/v1", server.uri());
+    let base_config = format!("openai_base_url={}", serde_json::to_string(&base)?);
+    test.cmd()
+        .arg("resume")
+        .arg("--last")
+        .arg("--config")
+        .arg(base_config)
+        .arg("--json")
+        .arg("--model")
+        .arg("gpt-5.2-codex")
+        .arg("--config")
+        .arg("reasoning_level=xhigh")
+        .arg("--dangerously-bypass-approvals-and-sandbox")
+        .arg("--skip-git-repo-check")
+        .arg("echo resume-with-global-flags-after-subcommand")
+        .assert()
+        .success();
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_includes_output_schema_in_request() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+
+    let schema_contents = serde_json::json!({
+        "type": "object",
+        "properties": {
+            "answer": { "type": "string" }
+        },
+        "required": ["answer"],
+        "additionalProperties": false
+    });
+    let schema_path = test.cwd_path().join("schema.json");
+    std::fs::write(&schema_path, serde_json::to_vec_pretty(&schema_contents)?)?;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("echo seed-resume-session")
+        .assert()
+        .success();
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("resume")
+        .arg("--last")
+        .arg("--json")
+        .arg("--output-schema")
+        .arg(&schema_path)
+        .arg("echo resume-with-schema")
+        .assert()
+        .success();
+
+    let requests = response_mock.requests();
+    assert_eq!(requests.len(), 2);
+    let payload: Value = requests[1].body_json();
+    let text = payload.get("text").expect("request missing text field");
+    let format = text
+        .get("format")
+        .expect("request missing text.format field");
+    assert_eq!(
+        format,
+        &serde_json::json!({
+            "name": "codex_output_schema",
+            "type": "json_schema",
+            "strict": true,
+            "schema": schema_contents,
+        })
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_by_id_appends_to_existing_file() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+    let repo_root = exec_repo_root()?;
+
+    // 1) First run: create a session
+    let marker = format!("resume-by-id-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+    let session_id = extract_conversation_id(&path);
+    assert!(
+        !session_id.is_empty(),
+        "missing conversation id in meta line"
+    );
+
+    // 2) Resume by id
+    let marker2 = format!("resume-by-id-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt2)
+        .arg("resume")
+        .arg(&session_id)
+        .assert()
+        .success();
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(
+        resumed_path, path,
+        "resume by id should append to existing file"
+    );
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_preserves_cli_configuration_overrides() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+    let repo_root = exec_repo_root()?;
+
+    let marker = format!("resume-config-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--sandbox")
+        .arg("workspace-write")
+        .arg("--model")
+        .arg("gpt-5.1")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    let path = find_session_file_containing_marker(&sessions_dir, &marker)
+        .expect("no session file found after first run");
+
+    let marker2 = format!("resume-config-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+
+    let output = test
+        .cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--sandbox")
+        .arg("workspace-write")
+        .arg("--model")
+        .arg("gpt-5.1-high")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt2)
+        .arg("resume")
+        .arg("--last")
+        .output()
+        .context("resume run should succeed")?;
+
+    assert!(output.status.success(), "resume run failed: {output:?}");
+
+    let stderr = String::from_utf8(output.stderr)?;
+    assert!(
+        stderr.contains("model: gpt-5.1-high"),
+        "stderr missing model override: {stderr}"
+    );
+    if cfg!(target_os = "windows") {
+        assert!(
+            stderr.contains("sandbox: read-only"),
+            "stderr missing downgraded sandbox note: {stderr}"
+        );
+    } else {
+        assert!(
+            stderr.contains("sandbox: workspace-write"),
+            "stderr missing sandbox override: {stderr}"
+        );
+    }
+
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no resumed session file containing marker2");
+    assert_eq!(resumed_path, path, "resume should append to same file");
+
+    let content = std::fs::read_to_string(&resumed_path)?;
+    assert!(content.contains(&marker));
+    assert!(content.contains(&marker2));
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_resume_accepts_images_after_subcommand() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let _response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+    let repo_root = exec_repo_root()?;
+
+    let marker = format!("resume-image-{}", Uuid::new_v4());
+    let prompt = format!("echo {marker}");
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg(&prompt)
+        .assert()
+        .success();
+
+    let image_path = test.cwd_path().join("resume_image.png");
+    let image_path_2 = test.cwd_path().join("resume_image_2.png");
+    let image_bytes: &[u8] = &[
+        0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44,
+        0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1F,
+        0x15, 0xC4, 0x89, 0x00, 0x00, 0x00, 0x0A, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9C, 0x63, 0x00,
+        0x01, 0x00, 0x00, 0x05, 0x00, 0x01, 0x0D, 0x0A, 0x2D, 0xB4, 0x00, 0x00, 0x00, 0x00, 0x49,
+        0x45, 0x4E, 0x44, 0xAE, 0x42, 0x60, 0x82,
+    ];
+    std::fs::write(&image_path, image_bytes)?;
+    std::fs::write(&image_path_2, image_bytes)?;
+
+    let marker2 = format!("resume-image-2-{}", Uuid::new_v4());
+    let prompt2 = format!("echo {marker2}");
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(&repo_root)
+        .arg("resume")
+        .arg("--last")
+        .arg("--image")
+        .arg(&image_path)
+        .arg("--image")
+        .arg(&image_path_2)
+        .arg(&prompt2)
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    let resumed_path = find_session_file_containing_marker(&sessions_dir, &marker2)
+        .expect("no session file found after resume with images");
+    let image_count = last_user_image_count(&resumed_path);
+    assert_eq!(
+        image_count, 2,
+        "resume prompt should include both attached images"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_fork_creates_distinct_threads_with_and_without_a_prompt() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let test = test_codex_exec();
+    let server = MockServer::start().await;
+    let response_mock = mount_exec_responses(&server, /*count*/ 2).await;
+    let source_marker = format!("fork-source-{}", Uuid::new_v4());
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("--thread-source")
+        .arg("source_feature")
+        .arg(format!("echo {source_marker}"))
+        .assert()
+        .success();
+
+    let sessions_dir = test.home_path().join("sessions");
+    let source_path = find_session_file_containing_marker(&sessions_dir, &source_marker)
+        .expect("source thread should have a rollout");
+    let source_id = extract_conversation_id(&source_path);
+    let original_source = std::fs::read_to_string(&source_path)?;
+    let source_meta: Value = serde_json::from_str(
+        original_source
+            .lines()
+            .next()
+            .expect("source rollout should contain session metadata"),
+    )?;
+    assert_eq!(source_meta["payload"]["thread_source"], "source_feature");
+
+    for (args, expected_error) in [
+        (
+            vec!["--image", "unused.png"],
+            "Forking with images requires a prompt",
+        ),
+        (
+            vec!["--output-schema", "unused.json"],
+            "Forking with output options requires a prompt",
+        ),
+        (
+            vec!["--output-last-message", "unused.md"],
+            "Forking with output options requires a prompt",
+        ),
+        (vec!["--ephemeral"], "Ephemeral forks require a prompt"),
+    ] {
+        let output = test
+            .cmd_with_server(&server)
+            .arg("--skip-git-repo-check")
+            .arg("fork")
+            .arg(&source_id)
+            .args(args)
+            .output()?;
+        assert!(!output.status.success());
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains(expected_error),
+            "fork failed without the expected error: {output:?}"
+        );
+    }
+
+    let mut promptless_command = test.cmd_with_server(&server);
+    promptless_command
+        .arg("--skip-git-repo-check")
+        .arg("fork")
+        .arg(&source_id)
+        .arg("--json");
+    let mut child_command = tokio::process::Command::new(promptless_command.get_program());
+    child_command
+        .args(promptless_command.get_args())
+        .envs(
+            promptless_command
+                .get_envs()
+                .filter_map(|(key, value)| value.map(|value| (key, value))),
+        )
+        .current_dir(test.cwd_path())
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true);
+    let mut child = child_command.spawn()?;
+    let _open_stdin = child.stdin.take().expect("stdin should be piped");
+    let promptless_output =
+        tokio::time::timeout(Duration::from_secs(/*secs*/ 10), child.wait_with_output())
+            .await
+            .context("promptless fork should not wait for stdin to close")??;
+    assert!(
+        promptless_output.status.success(),
+        "promptless fork failed: {}",
+        String::from_utf8_lossy(&promptless_output.stderr)
+    );
+    let promptless_events = String::from_utf8(promptless_output.stdout)?
+        .lines()
+        .map(serde_json::from_str::<Value>)
+        .collect::<Result<Vec<_>, _>>()?;
+    assert_eq!(promptless_events.len(), 1);
+    assert_eq!(promptless_events[0]["type"], "thread.started");
+    let promptless_thread_id = promptless_events[0]["thread_id"]
+        .as_str()
+        .expect("promptless fork should emit its new thread id");
+    assert_ne!(promptless_thread_id, source_id);
+    assert_eq!(response_mock.requests().len(), 1);
+
+    let source_name = format!("fork-named-{}", Uuid::new_v4());
+    let config = ConfigBuilder::default()
+        .codex_home(test.home_path().to_path_buf())
+        .build()
+        .await?;
+    let state_db = init_state_db(&config)
+        .await
+        .expect("state DB should initialize");
+    assert!(
+        state_db
+            .update_thread_title(ThreadId::from_string(&source_id)?, &source_name)
+            .await?
+    );
+
+    let fork_marker = format!("fork-prompt-{}", Uuid::new_v4());
+    let fork_output = test
+        .cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("-C")
+        .arg(test.home_path())
+        .arg("fork")
+        .arg(&source_name)
+        .arg("--thread-source")
+        .arg("fork_feature")
+        .arg("--json")
+        .arg("-")
+        .write_stdin(format!("echo {fork_marker}"))
+        .output()?;
+    assert!(
+        fork_output.status.success(),
+        "fork with prompt failed: {}",
+        String::from_utf8_lossy(&fork_output.stderr)
+    );
+    let fork_events = String::from_utf8(fork_output.stdout)?
+        .lines()
+        .map(serde_json::from_str::<Value>)
+        .collect::<Result<Vec<_>, _>>()?;
+    assert_eq!(fork_events[0]["type"], "thread.started");
+    let fork_thread_id = fork_events[0]["thread_id"]
+        .as_str()
+        .expect("fork should emit its new thread id");
+    assert_ne!(fork_thread_id, source_id);
+    assert_ne!(fork_thread_id, promptless_thread_id);
+
+    let fork_path = find_session_file_containing_marker(&sessions_dir, &fork_marker)
+        .expect("forked thread should have a separate rollout");
+    assert_ne!(fork_path, source_path);
+    assert_eq!(extract_conversation_id(&fork_path), fork_thread_id);
+    let fork_contents = std::fs::read_to_string(&fork_path)?;
+    let fork_meta: Value = serde_json::from_str(
+        fork_contents
+            .lines()
+            .next()
+            .expect("fork rollout should contain session metadata"),
+    )?;
+    assert_eq!(fork_meta["payload"]["forked_from_id"], source_id);
+    assert_eq!(fork_meta["payload"]["thread_source"], "fork_feature");
+    assert_eq!(fork_meta["payload"]["history_base"]["thread_id"], source_id);
+    assert!(!fork_contents.contains(&source_marker));
+    assert!(fork_contents.contains(&fork_marker));
+    assert_eq!(std::fs::read_to_string(&source_path)?, original_source);
+
+    let requests = response_mock.requests();
+    assert_eq!(requests.len(), 2);
+    let fork_request = requests[1].body_json().to_string();
+    assert!(fork_request.contains(&source_marker));
+    assert!(fork_request.contains(&fork_marker));
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/sandbox.rs b/codex-rs/exec/tests/suite/sandbox.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1ccaee58497fdcb4ebfc7da6475d58dbd5facab0
--- /dev/null
+++ b/codex-rs/exec/tests/suite/sandbox.rs
@@ -0,0 +1,552 @@
+#![cfg(unix)]
+use codex_core::spawn::StdioPolicy;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_path_uri::PathUri;
+use std::collections::HashMap;
+use std::future::Future;
+use std::io;
+use std::process::ExitStatus;
+use tokio::fs::create_dir_all;
+use tokio::process::Child;
+
+pub(super) async fn spawn_command_under_sandbox(
+    command: Vec<String>,
+    command_cwd: AbsolutePathBuf,
+    permission_profile: &PermissionProfile,
+    sandbox_cwd: &AbsolutePathBuf,
+    stdio_policy: StdioPolicy,
+    env: HashMap<String, String>,
+) -> std::io::Result<Child> {
+    use codex_core::exec::ExecCapturePolicy;
+    use codex_core::exec::ExecParams;
+    use codex_core::exec::build_exec_request;
+    use codex_core::sandboxing::SandboxPermissions;
+    use codex_protocol::config_types::WindowsSandboxLevel;
+    use std::process::Stdio;
+
+    #[cfg(target_os = "linux")]
+    let codex_linux_sandbox_exe = Some(
+        core_test_support::find_codex_linux_sandbox_exe()
+            .map_err(|err| io::Error::new(io::ErrorKind::NotFound, err))?,
+    );
+    #[cfg(target_os = "macos")]
+    let codex_linux_sandbox_exe = None;
+    let exec_request = build_exec_request(
+        ExecParams {
+            command,
+            cwd: command_cwd,
+            expiration: 1000.into(),
+            capture_policy: ExecCapturePolicy::ShellTool,
+            env,
+            network: None,
+            network_environment_id: None,
+            sandbox_permissions: SandboxPermissions::UseDefault,
+            windows_sandbox_level: WindowsSandboxLevel::Disabled,
+            windows_sandbox_private_desktop: false,
+            justification: None,
+            arg0: None,
+        },
+        permission_profile,
+        sandbox_cwd,
+        &[PathUri::from_abs_path(sandbox_cwd)],
+        &codex_linux_sandbox_exe,
+        /*codex_self_exe*/ &None,
+        /*use_legacy_landlock*/ false,
+    )
+    .map_err(|err| io::Error::other(err.to_string()))?;
+
+    let (program, args) = exec_request
+        .command
+        .split_first()
+        .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "command args are empty"))?;
+
+    let mut child = tokio::process::Command::new(program);
+    if let Some(arg0) = exec_request.arg0.as_deref() {
+        child.arg0(arg0);
+    }
+    child.args(args);
+    // TODO(anp): Keep PathUri through the macOS sandbox process launch boundary.
+    let native_cwd = exec_request
+        .cwd
+        .to_abs_path()
+        .map_err(|err| io::Error::other(err.to_string()))?;
+    child.current_dir(native_cwd);
+    child.env_clear();
+    child.envs(exec_request.env);
+
+    match stdio_policy {
+        StdioPolicy::RedirectForShellTool => {
+            child.stdin(Stdio::null());
+            child.stdout(Stdio::piped()).stderr(Stdio::piped());
+        }
+        StdioPolicy::Inherit => {
+            child
+                .stdin(Stdio::inherit())
+                .stdout(Stdio::inherit())
+                .stderr(Stdio::inherit());
+        }
+    }
+
+    child.kill_on_drop(true).spawn()
+}
+
+#[cfg(target_os = "linux")]
+/// Determines whether Linux sandbox tests can run on this host.
+///
+/// These tests require an enforceable filesystem sandbox. We run a tiny command
+/// under the production Landlock path and skip when enforcement is unavailable
+/// (for example on kernels or container profiles where Landlock is not
+/// enforced).
+async fn linux_sandbox_test_env() -> Option<HashMap<String, String>> {
+    let command_cwd = AbsolutePathBuf::current_dir().ok()?;
+    let sandbox_cwd = command_cwd.clone();
+    let permission_profile = PermissionProfile::read_only();
+
+    if can_apply_linux_sandbox_policy(
+        &permission_profile,
+        &command_cwd,
+        &sandbox_cwd,
+        HashMap::new(),
+    )
+    .await
+    {
+        return Some(HashMap::new());
+    }
+
+    eprintln!("Skipping test: Landlock is not enforceable on this host.");
+    None
+}
+
+#[cfg(target_os = "linux")]
+/// Returns whether a minimal command can run successfully with the requested
+/// Linux sandbox policy applied.
+///
+/// This is used as a capability probe so sandbox behavior tests only run when
+/// Landlock enforcement is actually active.
+async fn can_apply_linux_sandbox_policy(
+    permission_profile: &PermissionProfile,
+    command_cwd: &AbsolutePathBuf,
+    sandbox_cwd: &AbsolutePathBuf,
+    env: HashMap<String, String>,
+) -> bool {
+    let spawn_result = spawn_command_under_sandbox(
+        vec!["/usr/bin/true".to_string()],
+        command_cwd.clone(),
+        permission_profile,
+        sandbox_cwd,
+        StdioPolicy::RedirectForShellTool,
+        env,
+    )
+    .await;
+    let Ok(mut child) = spawn_result else {
+        return false;
+    };
+    child
+        .wait()
+        .await
+        .map(|status| status.success())
+        .unwrap_or(false)
+}
+
+#[tokio::test]
+async fn python_multiprocessing_lock_works_under_sandbox() {
+    core_test_support::skip_if_sandbox!();
+    #[cfg(target_os = "linux")]
+    let sandbox_env = match linux_sandbox_test_env().await {
+        Some(env) => env,
+        // Skip on Linux hosts where Landlock cannot actually be enforced.
+        None => return,
+    };
+    #[cfg(not(target_os = "linux"))]
+    let sandbox_env = HashMap::new();
+    #[cfg(target_os = "macos")]
+    let writable_roots = Vec::<AbsolutePathBuf>::new();
+
+    // From https://man7.org/linux/man-pages/man7/sem_overview.7.html
+    //
+    // > On Linux, named semaphores are created in a virtual filesystem,
+    // > normally mounted under /dev/shm.
+    #[cfg(target_os = "linux")]
+    let writable_roots: Vec<AbsolutePathBuf> = vec!["/dev/shm".try_into().unwrap()];
+
+    let permission_profile = PermissionProfile::workspace_write_with(
+        &writable_roots,
+        NetworkSandboxPolicy::Restricted,
+        /*exclude_tmpdir_env_var*/ true,
+        /*exclude_slash_tmp*/ true,
+    );
+
+    let python_code = r#"import multiprocessing
+from multiprocessing import Lock, Process
+
+def f(lock):
+    with lock:
+        print("Lock acquired in child process")
+
+if __name__ == '__main__':
+    lock = Lock()
+    p = Process(target=f, args=(lock,))
+    p.start()
+    p.join()
+"#;
+
+    let command_cwd = AbsolutePathBuf::current_dir().expect("should be able to get current dir");
+    let sandbox_cwd = command_cwd.clone();
+    let mut child = spawn_command_under_sandbox(
+        vec![
+            "python3".to_string(),
+            "-c".to_string(),
+            python_code.to_string(),
+        ],
+        command_cwd,
+        &permission_profile,
+        &sandbox_cwd,
+        StdioPolicy::Inherit,
+        sandbox_env,
+    )
+    .await
+    .expect("should be able to spawn python under sandbox");
+
+    let status = child.wait().await.expect("should wait for child process");
+    assert!(status.success(), "python exited with {status:?}");
+}
+
+#[tokio::test]
+async fn python_getpwuid_works_under_sandbox() {
+    core_test_support::skip_if_sandbox!();
+    #[cfg(target_os = "linux")]
+    let sandbox_env = match linux_sandbox_test_env().await {
+        Some(env) => env,
+        None => return,
+    };
+    #[cfg(not(target_os = "linux"))]
+    let sandbox_env = HashMap::new();
+
+    if std::process::Command::new("python3")
+        .arg("--version")
+        .status()
+        .is_err()
+    {
+        eprintln!("python3 not found in PATH, skipping test.");
+        return;
+    }
+
+    let permission_profile = PermissionProfile::read_only();
+    let command_cwd = AbsolutePathBuf::current_dir().expect("should be able to get current dir");
+    let sandbox_cwd = command_cwd.clone();
+
+    let mut child = spawn_command_under_sandbox(
+        vec![
+            "python3".to_string(),
+            "-c".to_string(),
+            "import pwd, os; print(pwd.getpwuid(os.getuid()))".to_string(),
+        ],
+        command_cwd,
+        &permission_profile,
+        &sandbox_cwd,
+        StdioPolicy::RedirectForShellTool,
+        sandbox_env,
+    )
+    .await
+    .expect("should be able to spawn python under sandbox");
+
+    let status = child
+        .wait()
+        .await
+        .expect("should be able to wait for child process");
+    assert!(status.success(), "python exited with {status:?}");
+}
+
+#[tokio::test]
+async fn sandbox_distinguishes_command_and_policy_cwds() {
+    core_test_support::skip_if_sandbox!();
+    #[cfg(target_os = "linux")]
+    let sandbox_env = match linux_sandbox_test_env().await {
+        Some(env) => env,
+        None => return,
+    };
+    #[cfg(not(target_os = "linux"))]
+    let sandbox_env = HashMap::new();
+    let temp = tempfile::tempdir().expect("should be able to create temp dir");
+    let sandbox_root = temp.path().join("sandbox");
+    let command_root = temp.path().join("command").abs();
+    create_dir_all(&sandbox_root).await.expect("mkdir");
+    create_dir_all(&command_root).await.expect("mkdir");
+    let canonical_sandbox_root = tokio::fs::canonicalize(&sandbox_root)
+        .await
+        .expect("canonicalize sandbox root")
+        .abs();
+    let canonical_allowed_path = canonical_sandbox_root.join("allowed.txt");
+
+    let disallowed_path = command_root.join("forbidden.txt");
+
+    // Note writable_roots is empty: verify that `canonical_allowed_path` is
+    // writable only because it is under the sandbox policy cwd, not because it
+    // is under a writable root.
+    let permission_profile = PermissionProfile::workspace_write_with(
+        &[],
+        NetworkSandboxPolicy::Restricted,
+        /*exclude_tmpdir_env_var*/ true,
+        /*exclude_slash_tmp*/ true,
+    );
+
+    // Attempt to write inside the command cwd, which is outside of the sandbox policy cwd.
+    let mut child = spawn_command_under_sandbox(
+        vec![
+            "bash".to_string(),
+            "-lc".to_string(),
+            "echo forbidden > forbidden.txt".to_string(),
+        ],
+        command_root.clone(),
+        &permission_profile,
+        &canonical_sandbox_root,
+        StdioPolicy::Inherit,
+        sandbox_env.clone(),
+    )
+    .await
+    .expect("should spawn command writing to forbidden path");
+
+    let status = child
+        .wait()
+        .await
+        .expect("should wait for forbidden command");
+    assert!(
+        !status.success(),
+        "sandbox unexpectedly allowed writing to command cwd: {status:?}"
+    );
+    let forbidden_exists = tokio::fs::try_exists(&disallowed_path)
+        .await
+        .expect("try_exists failed");
+    assert!(
+        !forbidden_exists,
+        "forbidden path should not have been created"
+    );
+
+    // Writing to the sandbox policy cwd after changing directories into it should succeed.
+    let mut child = spawn_command_under_sandbox(
+        vec![
+            "/usr/bin/touch".to_string(),
+            canonical_allowed_path.to_string_lossy().into_owned(),
+        ],
+        command_root,
+        &permission_profile,
+        &canonical_sandbox_root,
+        StdioPolicy::Inherit,
+        sandbox_env,
+    )
+    .await
+    .expect("should spawn command writing to sandbox root");
+
+    let status = child.wait().await.expect("should wait for allowed command");
+    assert!(
+        status.success(),
+        "sandbox blocked allowed write: {status:?}"
+    );
+    let allowed_exists = tokio::fs::try_exists(&canonical_allowed_path)
+        .await
+        .expect("try_exists allowed failed");
+    assert!(allowed_exists, "allowed path should exist");
+}
+
+#[tokio::test]
+async fn sandbox_blocks_first_time_dot_codex_creation() {
+    core_test_support::skip_if_sandbox!();
+    #[cfg(target_os = "linux")]
+    let sandbox_env = match linux_sandbox_test_env().await {
+        Some(env) => env,
+        None => return,
+    };
+    #[cfg(not(target_os = "linux"))]
+    let sandbox_env = HashMap::new();
+
+    let temp = tempfile::tempdir().expect("should be able to create temp dir");
+    let repo_root = temp.path().join("repo").abs();
+    create_dir_all(&repo_root).await.expect("mkdir repo");
+    let dot_codex = repo_root.join(".codex");
+    let config_toml = dot_codex.join("config.toml");
+    let permission_profile = PermissionProfile::workspace_write_with(
+        &[],
+        NetworkSandboxPolicy::Restricted,
+        /*exclude_tmpdir_env_var*/ true,
+        /*exclude_slash_tmp*/ true,
+    );
+
+    let mut child = spawn_command_under_sandbox(
+        vec![
+            "bash".to_string(),
+            "-lc".to_string(),
+            "mkdir -p .codex && echo 'sandbox_mode = \"danger-full-access\"' > .codex/config.toml"
+                .to_string(),
+        ],
+        repo_root.clone(),
+        &permission_profile,
+        &repo_root,
+        StdioPolicy::RedirectForShellTool,
+        sandbox_env,
+    )
+    .await
+    .expect("should spawn command creating .codex");
+
+    let status = child.wait().await.expect("should wait for .codex command");
+    assert!(
+        !status.success(),
+        "sandbox unexpectedly allowed first-time .codex creation: {status:?}"
+    );
+    let dot_codex_metadata = tokio::fs::symlink_metadata(&dot_codex).await;
+    if let Ok(metadata) = dot_codex_metadata {
+        assert!(
+            !metadata.is_dir(),
+            "{} should not be creatable as a directory",
+            dot_codex.display()
+        );
+    } else if let Err(err) = &dot_codex_metadata {
+        assert_eq!(
+            err.kind(),
+            io::ErrorKind::NotFound,
+            "unexpected metadata error for {}: {err}",
+            dot_codex.display()
+        );
+    }
+    let config_toml_exists = match tokio::fs::try_exists(&config_toml).await {
+        Ok(exists) => exists,
+        Err(err) if err.kind() == io::ErrorKind::NotADirectory => false,
+        Err(err) => panic!("try_exists {} failed: {err}", config_toml.display()),
+    };
+    assert!(
+        !config_toml_exists,
+        "{} should not have been created",
+        config_toml.display()
+    );
+}
+
+fn unix_sock_body() {
+    unsafe {
+        let mut fds = [0i32; 2];
+        let r = libc::socketpair(libc::AF_UNIX, libc::SOCK_DGRAM, 0, fds.as_mut_ptr());
+        assert_eq!(
+            r,
+            0,
+            "socketpair(AF_UNIX, SOCK_DGRAM) failed: {}",
+            io::Error::last_os_error()
+        );
+
+        let msg = b"hello_unix";
+        // write() from one end (generic write is allowed)
+        let sent = libc::write(fds[0], msg.as_ptr() as *const libc::c_void, msg.len());
+        assert!(sent >= 0, "write() failed: {}", io::Error::last_os_error());
+
+        // recvfrom() on the other end. We don’t need the address for socketpair,
+        // so we pass null pointers for src address.
+        let mut buf = [0u8; 64];
+        let recvd = libc::recvfrom(
+            fds[1],
+            buf.as_mut_ptr() as *mut libc::c_void,
+            buf.len(),
+            0,
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+        );
+        assert!(
+            recvd >= 0,
+            "recvfrom() failed: {}",
+            io::Error::last_os_error()
+        );
+
+        let recvd_slice = &buf[..(recvd as usize)];
+        assert_eq!(
+            recvd_slice,
+            &msg[..],
+            "payload mismatch: sent {} bytes, got {} bytes",
+            msg.len(),
+            recvd
+        );
+
+        // Also exercise AF_UNIX stream socketpair quickly to ensure AF_UNIX in general works.
+        let mut sfds = [0i32; 2];
+        let sr = libc::socketpair(libc::AF_UNIX, libc::SOCK_STREAM, 0, sfds.as_mut_ptr());
+        assert_eq!(
+            sr,
+            0,
+            "socketpair(AF_UNIX, SOCK_STREAM) failed: {}",
+            io::Error::last_os_error()
+        );
+        let snt2 = libc::write(sfds[0], msg.as_ptr() as *const libc::c_void, msg.len());
+        assert!(
+            snt2 >= 0,
+            "write(stream) failed: {}",
+            io::Error::last_os_error()
+        );
+        let mut b2 = [0u8; 64];
+        let rcv2 = libc::recv(sfds[1], b2.as_mut_ptr() as *mut libc::c_void, b2.len(), 0);
+        assert!(
+            rcv2 >= 0,
+            "recv(stream) failed: {}",
+            io::Error::last_os_error()
+        );
+
+        // Clean up
+        let _ = libc::close(sfds[0]);
+        let _ = libc::close(sfds[1]);
+        let _ = libc::close(fds[0]);
+        let _ = libc::close(fds[1]);
+    }
+}
+
+#[tokio::test]
+async fn allow_unix_socketpair_recvfrom() {
+    run_code_under_sandbox(
+        "allow_unix_socketpair_recvfrom",
+        &PermissionProfile::read_only(),
+        || async { unix_sock_body() },
+    )
+    .await
+    .expect("should be able to reexec");
+}
+
+const IN_SANDBOX_ENV_VAR: &str = "IN_SANDBOX";
+
+pub async fn run_code_under_sandbox<F, Fut>(
+    test_selector: &str,
+    permission_profile: &PermissionProfile,
+    child_body: F,
+) -> io::Result<Option<ExitStatus>>
+where
+    F: FnOnce() -> Fut + Send + 'static,
+    Fut: Future<Output = ()> + Send + 'static,
+{
+    if std::env::var(IN_SANDBOX_ENV_VAR).is_err() {
+        let exe = std::env::current_exe()?;
+        let mut cmds = vec![exe.to_string_lossy().into_owned(), "--exact".into()];
+        let mut stdio_policy = StdioPolicy::RedirectForShellTool;
+        // Allow for us to pass forward --nocapture / use the right stdio policy.
+        if std::env::args().any(|a| a == "--nocapture") {
+            cmds.push("--nocapture".into());
+            stdio_policy = StdioPolicy::Inherit;
+        }
+        cmds.push(test_selector.into());
+
+        // Your existing launcher:
+        let command_cwd =
+            AbsolutePathBuf::current_dir().expect("should be able to get current dir");
+        let sandbox_cwd = command_cwd.clone();
+        let mut child = spawn_command_under_sandbox(
+            cmds,
+            command_cwd,
+            permission_profile,
+            &sandbox_cwd,
+            stdio_policy,
+            HashMap::from([("IN_SANDBOX".into(), "1".into())]),
+        )
+        .await?;
+
+        let status = child.wait().await?;
+        Ok(Some(status))
+    } else {
+        // Child branch: run the provided body.
+        child_body().await;
+        Ok(None)
+    }
+}
diff --git a/codex-rs/exec/tests/suite/seatbelt.rs b/codex-rs/exec/tests/suite/seatbelt.rs
new file mode 100644
index 0000000000000000000000000000000000000000..26b287a6259a7f42cf3247e2f3f2a911bae766c9
--- /dev/null
+++ b/codex-rs/exec/tests/suite/seatbelt.rs
@@ -0,0 +1,880 @@
+use super::sandbox::spawn_command_under_sandbox;
+use codex_core::spawn::StdioPolicy;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+use std::fs;
+use std::os::unix::fs::symlink;
+use std::process::Output;
+use std::time::Duration;
+use tempfile::TempDir;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn codex_home_symlink_opt_out_uses_loaded_user_config() -> anyhow::Result<()> {
+    use core_test_support::responses;
+    use core_test_support::test_codex_exec::test_codex_exec;
+    use serde_json::json;
+
+    core_test_support::skip_if_sandbox!(Ok(()));
+    for (home_env, root_alias, enabled, ignore_user_config) in [
+        ("user-home", Some("user-home"), true, false),
+        ("home-link/../.codex", Some(".codex"), false, false),
+        ("home-link/../.codex", None, true, false),
+        ("user-home", Some("user-home"), true, true),
+    ] {
+        let test = test_codex_exec();
+        let home = test.home_path().join(".codex");
+        let project_home = test.cwd_path().join(".codex");
+        let child = test.home_path().join("child");
+        for directory in [&home, &project_home, &child] {
+            fs::create_dir(directory)?;
+        }
+        symlink(&home, test.cwd_path().join("user-home"))?;
+        symlink(&child, test.cwd_path().join("home-link"))?;
+        fs::write(
+            home.join("config.toml"),
+            format!("allow_symlinked_codex_home = {enabled}\n"),
+        )?;
+        // The checkout must not enable the opt-out, even when `..` follows a symlink.
+        fs::write(
+            project_home.join("config.toml"),
+            "allow_symlinked_codex_home = true\n",
+        )?;
+        let target = TempDir::new()?;
+        for root in [&home, &project_home] {
+            symlink(target.path(), root.join("visualizations"))?;
+        }
+        let writable_home =
+            root_alias.map_or_else(|| home.clone(), |alias| test.cwd_path().join(alias));
+        let visualizations = writable_home.join("visualizations");
+        let shell_args = json!({
+            "cmd": "printf shell > shell.txt",
+            "workdir": visualizations,
+            "shell": "/bin/sh",
+            "login": false,
+        })
+        .to_string();
+        let patch = format!(
+            "*** Begin Patch\n*** Add File: {}/patch.txt\n+patched\n*** End Patch",
+            visualizations.display()
+        );
+        let server = responses::start_mock_server().await;
+        let should_run = enabled && !ignore_user_config;
+        let mock = responses::mount_sse_sequence(
+            &server,
+            vec![
+                responses::sse(vec![
+                    responses::ev_function_call("shell", "exec_command", &shell_args),
+                    responses::ev_apply_patch_custom_tool_call("patch", &patch),
+                    responses::ev_completed("response-1"),
+                ]),
+                responses::sse(vec![responses::ev_completed("response-2")]),
+            ],
+        )
+        .await;
+        let mut command = test.cmd_with_server(&server);
+        command
+            .env_remove("CODEX_API_KEY")
+            .env_remove("OPENAI_API_KEY")
+            .env_remove("CODEX_ACCESS_TOKEN")
+            .env("CODEX_HOME", home_env)
+            .args(["--skip-git-repo-check", "--sandbox", "workspace-write", "--add-dir"])
+            .arg(&visualizations)
+            .args(["-c", "approvals_reviewer=\"user\"", "-c", "features.shell_snapshot_v2=false"])
+            // Session overrides cannot authorize the host's exception either.
+            .args(["-c", "allow_symlinked_codex_home=true"])
+            .args(["-c", "model_provider=\"test\"", "-c"])
+            .arg(format!(
+                "model_providers.test={{name=\"test\",base_url={:?},wire_api=\"responses\",requires_openai_auth=false,supports_websockets=false}}",
+                format!("{}/v1", server.uri())
+            ))
+            .arg("write the files");
+        if ignore_user_config {
+            command.arg("--ignore-user-config");
+        }
+        let output = command.output()?;
+        assert!(output.status.success(), "{output:?}");
+        assert_eq!(mock.requests().len(), 2);
+        if should_run {
+            assert_eq!(fs::read(target.path().join("shell.txt"))?, b"shell");
+            assert_eq!(fs::read(target.path().join("patch.txt"))?, b"patched\n");
+        } else {
+            let shell_output = mock
+                .function_call_output_text("shell")
+                .expect("shell tool output");
+            assert!(
+                shell_output.contains("symlinked writable roots are not supported"),
+                "{shell_output}"
+            );
+            assert!(!target.path().join("shell.txt").exists());
+            assert!(!target.path().join("patch.txt").exists());
+        }
+    }
+    Ok(())
+}
+
+fn workspace_fixture() -> (TempDir, AbsolutePathBuf) {
+    let temp_dir = TempDir::new().expect("create temporary directory");
+    let workspace = temp_dir.path().join("workspace");
+    fs::create_dir(&workspace).expect("create workspace");
+    let workspace = AbsolutePathBuf::from_absolute_path(
+        workspace.canonicalize().expect("canonicalize workspace"),
+    )
+    .expect("workspace is absolute");
+    (temp_dir, workspace)
+}
+
+fn permission_profile(
+    workspace: &AbsolutePathBuf,
+    restricted_paths: Vec<(FileSystemPath, FileSystemAccessMode)>,
+) -> PermissionProfile {
+    let mut file_system_policy = FileSystemSandboxPolicy::read_only();
+    file_system_policy.entries.push(FileSystemSandboxEntry::new(
+        workspace.clone().into(),
+        FileSystemAccessMode::Write,
+    ));
+    file_system_policy.entries.extend(
+        restricted_paths
+            .into_iter()
+            .map(|(path, access)| FileSystemSandboxEntry::new(path, access)),
+    );
+
+    PermissionProfile::from_runtime_permissions(
+        &file_system_policy,
+        NetworkSandboxPolicy::Restricted,
+    )
+}
+
+fn denied_glob_profile(workspace: &AbsolutePathBuf, pattern: String) -> PermissionProfile {
+    permission_profile(
+        workspace,
+        vec![(
+            FileSystemPath::GlobPattern { pattern },
+            FileSystemAccessMode::Deny,
+        )],
+    )
+}
+
+async fn run_sandboxed_command(
+    command: Vec<String>,
+    workspace: &AbsolutePathBuf,
+    permission_profile: &PermissionProfile,
+) -> Output {
+    spawn_command_under_sandbox(
+        command,
+        workspace.clone(),
+        permission_profile,
+        workspace,
+        StdioPolicy::RedirectForShellTool,
+        HashMap::new(),
+    )
+    .await
+    .expect("spawn command under production Seatbelt policy")
+    .wait_with_output()
+    .await
+    .expect("wait for sandboxed command")
+}
+
+async fn run_path_command(
+    executable: &str,
+    path: &AbsolutePathBuf,
+    workspace: &AbsolutePathBuf,
+    profile: &PermissionProfile,
+) -> Output {
+    run_sandboxed_command(
+        vec![executable.to_string(), path.display().to_string()],
+        workspace,
+        profile,
+    )
+    .await
+}
+
+async fn assert_denied_read(
+    path: &AbsolutePathBuf,
+    workspace: &AbsolutePathBuf,
+    profile: &PermissionProfile,
+) {
+    let output = run_path_command("/bin/cat", path, workspace, profile).await;
+    assert!(
+        !output.status.success(),
+        "Seatbelt allowed reading {}: {output:?}",
+        path.display()
+    );
+    assert!(output.stdout.is_empty(), "protected contents leaked");
+}
+
+fn assert_file_contents(path: &AbsolutePathBuf, contents: &str) {
+    assert_eq!(fs::read_to_string(path).expect("read fixture"), contents);
+}
+
+async fn run_shell_command(
+    script: &str,
+    path: &AbsolutePathBuf,
+    workspace: &AbsolutePathBuf,
+    profile: &PermissionProfile,
+) -> Output {
+    run_sandboxed_command(
+        vec![
+            "/bin/sh".to_string(),
+            "-c".to_string(),
+            script.to_string(),
+            "sh".to_string(),
+            path.display().to_string(),
+        ],
+        workspace,
+        profile,
+    )
+    .await
+}
+
+async fn run_after_policy_applied(
+    operation: &str,
+    target: &AbsolutePathBuf,
+    extra_args: Vec<String>,
+    workspace: &AbsolutePathBuf,
+    profile: &PermissionProfile,
+    setup: impl FnOnce(),
+) -> Output {
+    let label = target
+        .as_path()
+        .file_name()
+        .expect("filename")
+        .to_string_lossy();
+    let ready = workspace.join(format!("{label}.ready.txt"));
+    let proceed = workspace.join(format!("{label}.proceed.txt"));
+    let script = format!(
+        "printf ready > \"$2\"; while [ ! -e \"$3\" ]; do /bin/sleep 0.01; done; {operation}"
+    );
+    let mut command = vec![
+        "/bin/sh".to_string(),
+        "-c".to_string(),
+        script,
+        "sh".to_string(),
+        target.display().to_string(),
+        ready.display().to_string(),
+        proceed.display().to_string(),
+    ];
+    command.extend(extra_args);
+    let child = spawn_command_under_sandbox(
+        command,
+        workspace.clone(),
+        profile,
+        workspace,
+        StdioPolicy::RedirectForShellTool,
+        HashMap::new(),
+    )
+    .await
+    .expect("spawn command before creating protected fixture");
+
+    tokio::time::timeout(Duration::from_secs(5), async {
+        while !ready.as_path().exists() {
+            tokio::time::sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("sandboxed command did not signal policy application");
+    setup();
+    fs::write(&proceed, "proceed").expect("release sandboxed command");
+    child
+        .wait_with_output()
+        .await
+        .expect("wait for sandboxed command")
+}
+
+#[tokio::test]
+async fn seatbelt_enforces_brace_alternation_and_escaped_deny_globs() {
+    core_test_support::skip_if_sandbox!();
+
+    let (temp_dir, workspace) = workspace_fixture();
+    let dotenv = workspace.join(".env");
+    let secrets = workspace.join("secrets.yml");
+    let escaped = workspace.join("config?.env");
+    let allowed = workspace.join("notes.txt");
+    for path in [&dotenv, &secrets, &escaped] {
+        fs::write(path, "protected contents").expect("write protected fixture");
+    }
+    fs::write(&allowed, "allowed contents").expect("write allowed fixture");
+
+    let config = format!(
+        r#"default_permissions = "test"
+[permissions.test]
+extends = ":read-only"
+[permissions.test.filesystem]
+"{workspace}" = "write"
+"{workspace}/{{.env,secrets.yml}}*" = "deny"
+'{workspace}/config\?.env' = "deny"
+"#,
+        workspace = workspace.display()
+    );
+    fs::write(temp_dir.path().join("config.toml"), config).expect("write permissions config");
+    let profile = core_test_support::load_default_config_for_test(&temp_dir)
+        .await
+        .permissions
+        .effective_permission_profile();
+
+    for denied_path in [&dotenv, &secrets, &escaped] {
+        assert_denied_read(denied_path, &workspace, &profile).await;
+    }
+
+    let output = run_path_command("/bin/cat", &allowed, &workspace, &profile).await;
+    assert!(output.status.success(), "allowed read failed: {output:?}");
+    assert_eq!(output.stdout, b"allowed contents");
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_renaming_ancestors_of_explicit_protected_files() {
+    core_test_support::skip_if_sandbox!();
+
+    for access in [FileSystemAccessMode::Read, FileSystemAccessMode::Deny] {
+        let (_temp_dir, workspace) = workspace_fixture();
+        let private = workspace.join("private");
+        let protected = private.join("secret.env");
+        let renamed = workspace.join("exposed");
+        fs::create_dir(&private).expect("create protected directory");
+        fs::write(&protected, "protected contents").expect("write protected fixture");
+
+        let profile = permission_profile(&workspace, vec![(protected.clone().into(), access)]);
+        let command = vec![
+            "/bin/mv".to_string(),
+            private.display().to_string(),
+            renamed.display().to_string(),
+        ];
+        let output = run_sandboxed_command(command.clone(), &workspace, &profile).await;
+
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed renaming an ancestor of a {access:?} path: {output:?}"
+        );
+        assert_file_contents(&protected, "protected contents");
+        assert!(!renamed.as_path().exists(), "rename unexpectedly succeeded");
+
+        let unprotected = permission_profile(&workspace, Vec::new());
+        let control = run_sandboxed_command(command, &workspace, &unprotected).await;
+        assert!(
+            control.status.success(),
+            "rename without a protected descendant should succeed: {control:?}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_renaming_dynamic_glob_ancestors() {
+    core_test_support::skip_if_sandbox!();
+
+    for component in [".githu?", "{.github,.gitlab}", r".githu\b", "*"] {
+        let (_temp_dir, workspace) = workspace_fixture();
+        let github = workspace.join(".github");
+        let workflows = github.join("workflows");
+        let protected = workflows.join("release.yml");
+        let renamed = workspace.join("exposed");
+        fs::create_dir_all(&workflows).expect("create protected directory");
+        fs::write(&protected, "protected workflow").expect("write protected fixture");
+
+        let profile = denied_glob_profile(
+            &workspace,
+            format!("{}/{component}/workflows/*.yml", workspace.display()),
+        );
+        let command = vec![
+            "/bin/mv".to_string(),
+            github.display().to_string(),
+            renamed.display().to_string(),
+        ];
+        let output = run_sandboxed_command(command.clone(), &workspace, &profile).await;
+
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed renaming ancestor matched by {component:?}: {output:?}"
+        );
+        assert_file_contents(&protected, "protected workflow");
+
+        let unprotected = permission_profile(&workspace, Vec::new());
+        let control = run_sandboxed_command(command, &workspace, &unprotected).await;
+        assert!(
+            control.status.success(),
+            "rename without the deny glob should succeed: {control:?}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_renaming_protected_workspace_into_another_writable_root() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let destination = workspace
+        .parent()
+        .expect("workspace has a parent")
+        .join("destination");
+    let moved_workspace = destination.join("moved");
+    let protected = workspace.join("secret.env");
+    fs::create_dir(&destination).expect("create writable destination");
+    fs::write(&protected, "protected contents").expect("write protected fixture");
+
+    let profile = permission_profile(
+        &workspace,
+        vec![
+            (destination.clone().into(), FileSystemAccessMode::Write),
+            (protected.clone().into(), FileSystemAccessMode::Read),
+        ],
+    );
+    let output = run_sandboxed_command(
+        vec![
+            "/bin/mv".to_string(),
+            workspace.display().to_string(),
+            moved_workspace.display().to_string(),
+        ],
+        &workspace,
+        &profile,
+    )
+    .await;
+
+    assert!(
+        !output.status.success(),
+        "Seatbelt allowed moving the workspace into another writable root: {output:?}"
+    );
+    assert_file_contents(&protected, "protected contents");
+    assert!(
+        !moved_workspace.as_path().exists(),
+        "workspace unexpectedly moved"
+    );
+}
+
+#[tokio::test]
+async fn seatbelt_ancestor_protection_does_not_block_unlinking_regular_files() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let regular_file = workspace.join("regular-file");
+    let hypothetical_descendant = regular_file.join("secret.env");
+    fs::write(&regular_file, "replaceable").expect("write regular file");
+    let profile = permission_profile(
+        &workspace,
+        vec![(hypothetical_descendant.into(), FileSystemAccessMode::Read)],
+    );
+
+    let output = run_path_command("/bin/rm", &regular_file, &workspace, &profile).await;
+
+    assert!(
+        output.status.success(),
+        "directory-only ancestor protection blocked a regular file: {output:?}"
+    );
+    assert!(
+        !regular_file.as_path().exists(),
+        "regular file was not removed"
+    );
+}
+
+#[tokio::test]
+async fn seatbelt_deny_globs_block_writes_to_existing_and_new_files() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let protected = workspace.join("secret.env");
+    let allowed = workspace.join("notes.txt");
+    fs::write(&protected, "original").expect("write protected fixture");
+    let profile = denied_glob_profile(&workspace, format!("{}/*.env", workspace.display()));
+
+    for (operation, script) in [
+        ("overwrite", "printf changed >> \"$1\""),
+        ("truncate", ": > \"$1\""),
+    ] {
+        let output = run_shell_command(script, &protected, &workspace, &profile).await;
+
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed {operation} on a denied file: {output:?}"
+        );
+        assert_file_contents(&protected, "original");
+    }
+
+    let unlink = run_path_command("/bin/rm", &protected, &workspace, &profile).await;
+    assert!(
+        !unlink.status.success(),
+        "Seatbelt unexpectedly allowed unlinking a denied glob: {unlink:?}"
+    );
+    assert_file_contents(&protected, "original");
+
+    for (operation, write_script) in [
+        ("overwrite", "printf changed >> \"$1\""),
+        ("truncate", ": > \"$1\""),
+    ] {
+        let late_protected = workspace.join(format!("late-{operation}.env"));
+        let output = run_after_policy_applied(
+            write_script,
+            &late_protected,
+            Vec::new(),
+            &workspace,
+            &profile,
+            || {
+                fs::write(&late_protected, "created after policy generation")
+                    .expect("create protected fixture after sandbox launch");
+            },
+        )
+        .await;
+
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed {operation} on a file created after policy generation: {output:?}"
+        );
+        assert_file_contents(&late_protected, "created after policy generation");
+    }
+
+    let allowed_write =
+        run_shell_command("printf allowed > \"$1\"", &allowed, &workspace, &profile).await;
+    assert!(
+        allowed_write.status.success(),
+        "unrelated write should remain allowed: {allowed_write:?}"
+    );
+    assert_file_contents(&allowed, "allowed");
+}
+
+#[tokio::test]
+async fn seatbelt_standard_profiles_preserve_expected_filesystem_access() {
+    core_test_support::skip_if_sandbox!();
+    let (_temp_dir, workspace) = workspace_fixture();
+    let inside = workspace.join("notes.txt");
+    let outside = workspace.parent().expect("parent").join("outside.txt");
+    fs::write(&inside, "original").expect("write workspace fixture");
+    let profile = permission_profile(&workspace, Vec::new());
+    let script = "set -e; /bin/cat \"$1\" >/dev/null; printf changed >> \"$1\"; /bin/mkdir \"$1.dir\"; /bin/mv \"$1\" \"$1.dir/moved\"; /bin/rm \"$1.dir/moved\"; /bin/rmdir \"$1.dir\"";
+    let inside_output = run_shell_command(script, &inside, &workspace, &profile).await;
+    assert!(
+        inside_output.status.success(),
+        "ordinary workspace operations failed: {inside_output:?}"
+    );
+
+    let outside_output =
+        run_shell_command("printf denied > \"$1\"", &outside, &workspace, &profile).await;
+    assert!(
+        !outside_output.status.success(),
+        "write outside the workspace unexpectedly succeeded: {outside_output:?}"
+    );
+    assert!(!outside.as_path().exists(), "outside file was created");
+    let readable = workspace.join("readable.txt");
+    fs::write(&readable, "readable contents").expect("write read-only fixture");
+    let profile = PermissionProfile::read_only();
+    let read = run_path_command("/bin/cat", &readable, &workspace, &profile).await;
+    assert!(read.status.success(), "ordinary read failed: {read:?}");
+    assert_eq!(read.stdout, b"readable contents");
+
+    let write = run_shell_command("printf changed > \"$1\"", &readable, &workspace, &profile).await;
+    assert!(
+        !write.status.success(),
+        "read-only write succeeded: {write:?}"
+    );
+    assert_file_contents(&readable, "readable contents");
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_protected_reads_and_writes_through_symlink_aliases() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let private = workspace.join("private");
+    let alias = workspace.join("alias");
+    let protected = private.join("secret.env");
+    let alias_path = alias.join("secret.env");
+    fs::create_dir(&private).expect("create protected directory");
+    fs::write(&protected, "protected contents").expect("write protected fixture");
+    symlink(private.as_path(), alias.as_path()).expect("create directory symlink");
+
+    for (restricted_path, accessed_path) in [
+        (FileSystemPath::from(protected.clone()), alias_path.clone()),
+        (
+            FileSystemPath::GlobPattern {
+                pattern: format!("{}/*.env", private.display()),
+            },
+            alias_path.clone(),
+        ),
+        (
+            FileSystemPath::GlobPattern {
+                pattern: format!("{}/*.env", alias.display()),
+            },
+            protected.clone(),
+        ),
+    ] {
+        let profile = permission_profile(
+            &workspace,
+            vec![(restricted_path, FileSystemAccessMode::Deny)],
+        );
+        assert_denied_read(&accessed_path, &workspace, &profile).await;
+
+        let write = run_shell_command(
+            "printf changed > \"$1\"",
+            &accessed_path,
+            &workspace,
+            &profile,
+        )
+        .await;
+        assert!(
+            !write.status.success(),
+            "Seatbelt allowed writing through protected symlink alias: {write:?}"
+        );
+        assert_file_contents(&protected, "protected contents");
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_globstar_protects_files_and_ancestors_at_every_depth() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let first = workspace.join("first");
+    let second = first.join("second");
+    fs::create_dir_all(&second).expect("create nested fixture directories");
+    let protected_paths = [
+        workspace.join("root.env"),
+        first.join("first.env"),
+        second.join("second.env"),
+    ];
+    for path in &protected_paths {
+        fs::write(path, "protected contents").expect("write protected fixture");
+    }
+    let profile = denied_glob_profile(&workspace, format!("{}/**/*.env", workspace.display()));
+
+    for path in &protected_paths {
+        assert_denied_read(path, &workspace, &profile).await;
+    }
+
+    for ancestor in [&first, &second] {
+        let destination = ancestor.with_extension("renamed");
+        let output = run_sandboxed_command(
+            vec![
+                "/bin/mv".to_string(),
+                ancestor.display().to_string(),
+                destination.display().to_string(),
+            ],
+            &workspace,
+            &profile,
+        )
+        .await;
+        assert!(
+            !output.status.success(),
+            "globstar allowed renaming protected ancestor {}: {output:?}",
+            ancestor.display()
+        );
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_brace_alternatives_with_slashes_protect_each_branch() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let nested = workspace.join("private/nested");
+    let other = workspace.join("other");
+    let allowed = workspace.join("notes.txt");
+    fs::create_dir_all(&nested).expect("create nested protected directory");
+    fs::create_dir(&other).expect("create alternate protected directory");
+    let protected_paths = [nested.join("secret.env"), other.join("secret.env")];
+    for path in &protected_paths {
+        fs::write(path, "protected contents").expect("write protected fixture");
+    }
+    fs::write(&allowed, "allowed contents").expect("write allowed fixture");
+    let profile = denied_glob_profile(
+        &workspace,
+        format!("{}/{{private/nested,other}}/*.env", workspace.display()),
+    );
+
+    for path in &protected_paths {
+        assert_denied_read(path, &workspace, &profile).await;
+    }
+
+    for ancestor in [&workspace.join("private"), &nested, &other] {
+        let destination = ancestor.with_extension("renamed");
+        let output = run_sandboxed_command(
+            vec![
+                "/bin/mv".to_string(),
+                ancestor.display().to_string(),
+                destination.display().to_string(),
+            ],
+            &workspace,
+            &profile,
+        )
+        .await;
+        assert!(
+            !output.status.success(),
+            "brace alternative allowed renaming {}: {output:?}",
+            ancestor.display()
+        );
+    }
+
+    let output = run_path_command("/bin/cat", &allowed, &workspace, &profile).await;
+    assert!(
+        output.status.success(),
+        "brace alternatives produced an invalid or overly broad policy: {output:?}"
+    );
+    assert_eq!(output.stdout, b"allowed contents");
+}
+
+#[tokio::test]
+async fn seatbelt_protects_directory_trees_created_after_policy_application() {
+    core_test_support::skip_if_sandbox!();
+
+    for operation in ["read", "rename"] {
+        let (_temp_dir, workspace) = workspace_fixture();
+        let late_directory = workspace.join("late/deep");
+        let protected = late_directory.join("secret.env");
+        let destination = workspace.join("exposed");
+        let profile = denied_glob_profile(&workspace, format!("{}/**/*.env", workspace.display()));
+        let operation_script = match operation {
+            "read" => "/bin/cat \"$1\"",
+            "rename" => "/bin/mv \"$4\" \"$5\"",
+            _ => unreachable!("unknown operation"),
+        };
+        let output = run_after_policy_applied(
+            operation_script,
+            &protected,
+            vec![
+                workspace.join("late").display().to_string(),
+                destination.display().to_string(),
+            ],
+            &workspace,
+            &profile,
+            || {
+                fs::create_dir_all(&late_directory)
+                    .expect("create protected directory after policy");
+                fs::write(&protected, "protected contents").expect("write protected fixture");
+            },
+        )
+        .await;
+
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed {operation} after protected directory appeared: {output:?}"
+        );
+        assert_file_contents(&protected, "protected contents");
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_atomic_rename_exchange_and_destination_replacement() {
+    core_test_support::skip_if_sandbox!();
+
+    for (operation, flags) in [("exchange", libc::RENAME_SWAP), ("replace", 0)] {
+        let (_temp_dir, workspace) = workspace_fixture();
+        let private = workspace.join("private");
+        let destination = workspace.join("destination");
+        let protected = private.join("secret.env");
+        fs::create_dir(&private).expect("create protected directory");
+        fs::create_dir(&destination).expect("create replacement directory");
+        fs::write(&protected, "protected contents").expect("write protected fixture");
+        let profile = permission_profile(
+            &workspace,
+            vec![(protected.clone().into(), FileSystemAccessMode::Read)],
+        );
+        let script = "import ctypes, os, sys; libc = ctypes.CDLL(None, use_errno=True); result = libc.renameatx_np(-2, os.fsencode(sys.argv[1]), -2, os.fsencode(sys.argv[2]), int(sys.argv[3])); sys.exit(0 if result == 0 else ctypes.get_errno())";
+        let command = vec![
+            "/usr/bin/python3".to_string(),
+            "-c".to_string(),
+            script.to_string(),
+            private.display().to_string(),
+            destination.display().to_string(),
+            flags.to_string(),
+        ];
+        let output = run_sandboxed_command(command.clone(), &workspace, &profile).await;
+
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed atomic {operation} of a protected ancestor: {output:?}"
+        );
+        assert_file_contents(&protected, "protected contents");
+
+        let unprotected = permission_profile(&workspace, Vec::new());
+        let control = run_sandboxed_command(command, &workspace, &unprotected).await;
+        assert!(
+            control.status.success(),
+            "unprotected atomic {operation} should succeed: {control:?}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_protected_ancestor_moves_across_writable_roots() {
+    core_test_support::skip_if_sandbox!();
+
+    for destination_is_nested in [false, true] {
+        for use_glob in [false, true] {
+            let (_temp_dir, workspace) = workspace_fixture();
+            let private = workspace.join("private");
+            let protected = private.join("secret.env");
+            let destination = if destination_is_nested {
+                workspace.join("destination")
+            } else {
+                workspace
+                    .parent()
+                    .expect("workspace has a parent")
+                    .join("destination")
+            };
+            let moved = destination.join("moved");
+            fs::create_dir(&private).expect("create protected directory");
+            fs::create_dir(&destination).expect("create writable destination");
+            fs::write(&protected, "protected contents").expect("write protected fixture");
+            let protected_path = if use_glob {
+                FileSystemPath::GlobPattern {
+                    pattern: format!("{}/*.env", private.display()),
+                }
+            } else {
+                protected.clone().into()
+            };
+            let profile = permission_profile(
+                &workspace,
+                vec![
+                    (destination.clone().into(), FileSystemAccessMode::Write),
+                    (protected_path, FileSystemAccessMode::Deny),
+                ],
+            );
+
+            let output = run_sandboxed_command(
+                vec![
+                    "/bin/mv".to_string(),
+                    private.display().to_string(),
+                    moved.display().to_string(),
+                ],
+                &workspace,
+                &profile,
+            )
+            .await;
+            assert!(
+                !output.status.success(),
+                "protected ancestor crossed writable roots: nested={destination_is_nested}, glob={use_glob}, output={output:?}"
+            );
+            assert_file_contents(&protected, "protected contents");
+            assert!(!moved.as_path().exists(), "protected ancestor was moved");
+        }
+    }
+}
+
+#[tokio::test]
+async fn seatbelt_blocks_creating_files_matched_by_denied_globs() {
+    core_test_support::skip_if_sandbox!();
+
+    let (_temp_dir, workspace) = workspace_fixture();
+    let nested = workspace.join("nested");
+    fs::create_dir(&nested).expect("create nested directory");
+    let profile = denied_glob_profile(&workspace, format!("{}/**/*.env", workspace.display()));
+
+    for path in [workspace.join("created.env"), nested.join("created.env")] {
+        let output =
+            run_shell_command("printf created > \"$1\"", &path, &workspace, &profile).await;
+        assert!(
+            !output.status.success(),
+            "Seatbelt allowed creation at a denied path: {output:?}"
+        );
+        assert!(!path.as_path().exists(), "denied file was created");
+    }
+
+    let allowed = nested.join("created.txt");
+    let output = run_path_command("/usr/bin/touch", &allowed, &workspace, &profile).await;
+    assert!(
+        output.status.success(),
+        "unrelated file creation should succeed: {output:?}"
+    );
+    assert!(allowed.as_path().exists(), "unrelated file was not created");
+}
diff --git a/codex-rs/exec/tests/suite/server_error_exit.rs b/codex-rs/exec/tests/suite/server_error_exit.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bd0fad698758951ea41d233f2580fc9d79a050d0
--- /dev/null
+++ b/codex-rs/exec/tests/suite/server_error_exit.rs
@@ -0,0 +1,33 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+
+/// Verify that when the server reports an error, `codex-exec` exits with a
+/// non-zero status code so automation can detect failures.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exits_non_zero_when_server_reports_error() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+
+    // Mock a simple Responses API SSE stream that immediately reports a
+    // `response.failed` event with an error message.
+    let server = responses::start_mock_server().await;
+    let body = responses::sse(vec![serde_json::json!({
+        "type": "response.failed",
+        "response": {
+            "id": "resp_err_1",
+            "error": {"code": "rate_limit_exceeded", "message": "synthetic server error"}
+        }
+    })]);
+    responses::mount_sse_once(&server, body).await;
+
+    test.cmd_with_server(&server)
+        .arg("--skip-git-repo-check")
+        .arg("tell me something")
+        .arg("--experimental-json")
+        .assert()
+        .code(1);
+
+    Ok(())
+}
diff --git a/codex-rs/exec/tests/suite/worktree.rs b/codex-rs/exec/tests/suite/worktree.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d2c7afd5d9f25837cbe085a68829ebd503d7ba1d
--- /dev/null
+++ b/codex-rs/exec/tests/suite/worktree.rs
@@ -0,0 +1,441 @@
+//! Exercises gated shared-pool execution and preserves existing checkout ownership.
+//! Observe ownership at the first model request, before the process can finish.
+
+use anyhow::Context;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_worktree::CreateWorktree;
+use codex_worktree::WorktreeManager;
+use codex_worktree::WorktreeSettings;
+use core_test_support::responses;
+use core_test_support::test_codex_exec::test_codex_exec;
+use pretty_assertions::assert_eq;
+use serde_json::Value;
+use std::fs;
+use std::path::Path;
+use std::process::Command;
+use std::process::Output;
+use std::sync::Arc;
+use std::sync::Mutex;
+
+fn git(cwd: &Path, args: &[&str]) -> anyhow::Result<()> {
+    let output = Command::new("git")
+        .current_dir(cwd)
+        .args([
+            "-c",
+            "user.name=Worktree Test",
+            "-c",
+            "user.email=test@example.invalid",
+        ])
+        .args(args)
+        .output()?;
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    Ok(())
+}
+
+fn started_thread(output: Output) -> anyhow::Result<String> {
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let events = String::from_utf8(output.stdout)?
+        .lines()
+        .map(serde_json::from_str::<Value>)
+        .collect::<Result<Vec<_>, _>>()?;
+    events
+        .iter()
+        .find(|event| event["type"] == "thread.started")
+        .and_then(|event| event["thread_id"].as_str())
+        .map(str::to_owned)
+        .context("exec should report its thread id")
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn worktree_start_and_fork_use_host_pool_and_preserve_legacy_resume() -> anyhow::Result<()> {
+    let test = test_codex_exec();
+    let home = AbsolutePathBuf::from_absolute_path(test.home_path())?
+        .canonicalize()?
+        .into_path_buf();
+    let source = AbsolutePathBuf::from_absolute_path(test.cwd_path())?
+        .canonicalize()?
+        .into_path_buf();
+    let extra = source.join("extra");
+    fs::create_dir(&extra)?;
+    fs::write(extra.join("tracked.txt"), "tracked")?;
+    fs::write(source.join("AGENTS.md"), "managed checkout instructions")?;
+    git(&source, &["init", "--quiet"])?;
+    git(&source, &["add", "."])?;
+    git(
+        &source,
+        &["commit", "--quiet", "--no-gpg-sign", "-m", "initial"],
+    )?;
+    let pool = home.join("shared-worktrees");
+    let other_pool = serde_json::to_string(&home.join("session-only-pool"))?;
+    fs::write(
+        home.join("config.toml"),
+        format!(
+            "sandbox_mode = \"workspace-write\"\nfeatures.worktrees = true\n[desktop]\ngit-worktree-root = {}\n[projects.{}]\ntrust_level = \"trusted\"\n",
+            serde_json::to_string(&pool)?,
+            serde_json::to_string(&source)?,
+        ),
+    )?;
+    fs::write(
+        home.join("demo.config.toml"),
+        format!("features.worktrees = false\n[desktop]\ngit-worktree-root = {other_pool}\n"),
+    )?;
+    let mut settings = WorktreeSettings::for_cli(&home, /*desktop*/ None)?;
+    settings.root = pool;
+    let legacy_manager = WorktreeManager::new(WorktreeSettings {
+        root: home.join("worktrees-cli"),
+        ..settings.clone()
+    });
+    let legacy = legacy_manager.create(&CreateWorktree {
+        source_cwd: source.clone(),
+        base: None,
+    })?;
+    let manager = WorktreeManager::new(settings);
+    let body = responses::sse(vec![
+        responses::ev_response_created("response_1"),
+        responses::ev_assistant_message("message_1", "done"),
+        responses::ev_completed("response_1"),
+    ]);
+    let server = responses::start_mock_server().await;
+    let seed_mock = responses::mount_sse_once(&server, body.clone()).await;
+    let legacy_id = started_thread(
+        test.cmd_with_server(&server)
+            .current_dir(legacy.cwd.join("extra"))
+            .args(["--json", "legacy seed"])
+            .output()?,
+    )?;
+    seed_mock.single_request();
+    legacy_manager.bind_thread(&legacy.root, &legacy_id)?;
+    fs::write(source.join("AGENTS.md"), "uncommitted source instructions")?;
+    fs::create_dir(source.join(".codex"))?;
+    fs::write(source.join(".codex/config.toml"), "[invalid source config")?;
+
+    let launcher = tempfile::tempdir()?;
+    fs::create_dir(launcher.path().join("extra"))?;
+    let mut known_roots = Vec::new();
+    for (fork, overrides) in [
+        (false, Vec::new()),
+        (
+            true,
+            vec![
+                "--profile".to_owned(),
+                "demo".to_owned(),
+                "-c".to_owned(),
+                "features.worktrees=true".to_owned(),
+                "-c".to_owned(),
+                format!("desktop.git-worktree-root={other_pool}"),
+                "-c".to_owned(),
+                format!("desktop={{git-worktree-root={other_pool}}}"),
+            ],
+        ),
+        (true, vec!["--cd".to_owned(), extra.display().to_string()]),
+    ] {
+        let explicit_cd = overrides.first().is_some_and(|arg| arg == "--cd");
+        let server = responses::start_mock_server().await;
+        let observed_owner = Arc::new(Mutex::<Option<String>>::default());
+        let captured_owner = Arc::clone(&observed_owner);
+        let observed_manager = manager.clone();
+        let observed_source = source.clone();
+        let previous_roots = known_roots.clone();
+        // A matcher is needed here to inspect metadata at request time, not after exit.
+        let response_mock = responses::mount_sse_once_match(
+            &server,
+            move |_: &wiremock::Request| {
+                let owner = observed_manager
+                    .list(&observed_source)
+                    .expect("list shared checkouts")
+                    .into_iter()
+                    .find(|checkout| !previous_roots.contains(&checkout.root))
+                    .and_then(|checkout| {
+                        observed_manager.owner(&checkout.root).expect("read owner")
+                    });
+                *captured_owner.lock().expect("capture request owner") = owner;
+                true
+            },
+            body.clone(),
+        )
+        .await;
+        let mut command = test.cmd_with_server(&server);
+        command
+            .args(["--json", "--worktree", "--add-dir", "extra"])
+            .args(overrides);
+        if fork {
+            command
+                .current_dir(launcher.path())
+                .arg("fork")
+                .arg(&legacy_id);
+        }
+        let thread_id = started_thread(command.arg("describe checkout").output()?)?;
+        assert_eq!(
+            *observed_owner.lock().expect("read captured owner"),
+            Some(thread_id)
+        );
+        let checkout = manager
+            .list(&source)?
+            .into_iter()
+            .find(|checkout| !known_roots.contains(&checkout.root))
+            .context("one new shared checkout")?;
+        let request = response_mock.single_request();
+        let context = request
+            .message_input_texts("user")
+            .into_iter()
+            .chain(request.message_input_texts("developer"))
+            .collect::<Vec<_>>()
+            .join("\n");
+        let checkout_cwd = AbsolutePathBuf::from_absolute_path(if explicit_cd {
+            checkout.root.join("extra")
+        } else {
+            checkout.cwd.clone()
+        })?
+        .canonicalize()?;
+        assert!(
+            context.contains(checkout_cwd.to_string_lossy().as_ref()),
+            "{context}"
+        );
+        assert!(
+            context.contains(
+                if fork {
+                    launcher.path().join("extra")
+                } else {
+                    extra.clone()
+                }
+                .to_string_lossy()
+                .as_ref()
+            ),
+            "{context}"
+        );
+        assert!(
+            context.contains("managed checkout instructions"),
+            "{context}"
+        );
+        assert!(
+            !context.contains("uncommitted source instructions"),
+            "{context}"
+        );
+        known_roots.push(checkout.root);
+    }
+
+    let server = responses::start_mock_server().await;
+    let resume_mock = responses::mount_sse_once(&server, body).await;
+    let resumed_id = started_thread(
+        test.cmd_with_server(&server)
+            .current_dir(legacy.cwd.join("extra"))
+            .args(["--json", "resume", &legacy_id, "continue legacy"])
+            .output()?,
+    )?;
+    assert_eq!(resumed_id, legacy_id);
+    assert_eq!(legacy_manager.owner(&legacy.root)?, Some(legacy_id.clone()));
+    let legacy_cwd =
+        AbsolutePathBuf::from_absolute_path(legacy.cwd.join("extra"))?.canonicalize()?;
+    assert!(
+        resume_mock
+            .single_request()
+            .message_input_texts("user")
+            .iter()
+            .any(|text| text.contains(legacy_cwd.to_string_lossy().as_ref()))
+    );
+    fs::write(
+        home.join("config.toml"),
+        format!(
+            "features.worktrees=true\n[projects.{}]\ntrust_level=\"untrusted\"\n",
+            serde_json::to_string(&source)?,
+        ),
+    )?;
+    for args in [vec!["prompt"], vec!["fork", legacy_id.as_str(), "prompt"]] {
+        let output = test.cmd().arg("--worktree").args(args).output()?;
+        assert!(!output.status.success());
+        assert!(String::from_utf8_lossy(&output.stderr).contains("explicitly untrusted"));
+    }
+    assert!(!home.join("worktrees").exists());
+
+    // Synthetic enterprise claims let the cloud bundle, not a local project entry,
+    // supply the source's distrust decision.
+    fs::write(
+        home.join("auth.json"),
+        serde_json::to_vec(&serde_json::json!({
+            "auth_mode": "chatgpt",
+            "tokens": {
+                "id_token": "e30.eyJodHRwczovL2FwaS5vcGVuYWkuY29tL2F1dGgiOnsiY2hhdGdwdF9wbGFuX3R5cGUiOiJlbnRlcnByaXNlIiwiY2hhdGdwdF9hY2NvdW50X2lkIjoid29ya3NwYWNlLTEyMyIsImNoYXRncHRfdXNlcl9pZCI6InVzZXItMTIzIn19.signature",
+                "access_token": "test-access-token",
+                "refresh_token": "test-refresh-token",
+                "account_id": "workspace-123"
+            }
+        }))?,
+    )?;
+    fs::write(
+        home.join("config.toml"),
+        format!(
+            "features.worktrees=true\ncli_auth_credentials_store=\"file\"\nchatgpt_base_url=\"{}/backend-api\"\n",
+            server.uri(),
+        ),
+    )?;
+    wiremock::Mock::given(wiremock::matchers::method("GET"))
+        .and(wiremock::matchers::path("/backend-api/wham/config/bundle"))
+        .respond_with(
+            wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "config_toml": { "enterprise_managed": [{
+                    "id": "source-trust", "name": "Source trust",
+                    "contents": format!(
+                        "[projects.{}]\ntrust_level=\"untrusted\"\n[projects.{}]\ntrust_level=\"untrusted\"\n",
+                        serde_json::to_string(&source)?,
+                        serde_json::to_string(&legacy.cwd.join("extra"))?,
+                    )
+                }] }
+            })),
+        )
+        .mount(&server)
+        .await;
+    for args in [vec!["prompt"], vec!["fork", legacy_id.as_str(), "prompt"]] {
+        let request_count = if args.first() == Some(&"fork") {
+            // The saved checkout can choose file auth even when the launcher does not.
+            fs::remove_file(source.join(".codex/config.toml"))?;
+            fs::create_dir_all(legacy.cwd.join(".codex"))?;
+            fs::write(
+                legacy.cwd.join(".codex/config.toml"),
+                "cli_auth_credentials_store=\"file\"\n",
+            )?;
+            git(&legacy.cwd, &["add", ".codex/config.toml"])?;
+            git(
+                &legacy.cwd,
+                &["commit", "--quiet", "--no-gpg-sign", "-m", "file auth"],
+            )?;
+            fs::write(
+                home.join("config.toml"),
+                format!(
+                    "features.worktrees=true\ncli_auth_credentials_store=\"ephemeral\"\nchatgpt_base_url=\"{}/backend-api\"\n[projects.{}]\ntrust_level=\"trusted\"\n",
+                    server.uri(),
+                    serde_json::to_string(&source)?,
+                ),
+            )?;
+            let cache = home.join("cloud-config-bundle-cache.json");
+            if cache.exists() {
+                fs::remove_file(&cache)?;
+            }
+            Some(server.received_requests().await.context("requests")?.len())
+        } else {
+            None
+        };
+        let output = test
+            .cmd()
+            .current_dir(if request_count.is_some() {
+                launcher.path()
+            } else {
+                &source
+            })
+            .env_remove("CODEX_API_KEY")
+            .env_remove("OPENAI_API_KEY")
+            .env_remove("CODEX_ACCESS_TOKEN")
+            .args(["--json", "--worktree", "--strict-config"])
+            .args(args)
+            .output()?;
+        assert!(
+            !output.status.success()
+                && String::from_utf8_lossy(&output.stderr).contains("explicitly untrusted"),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        if let Some(request_count) = request_count {
+            assert!(!String::from_utf8_lossy(&output.stdout).contains("thread.started"));
+            let denied_manager =
+                WorktreeManager::new(WorktreeSettings::for_cli(&home, /*desktop*/ None)?);
+            let checkout = denied_manager
+                .list(&legacy.cwd)?
+                .into_iter()
+                .next()
+                .context("denied checkout remains for manual removal")?;
+            assert_eq!(denied_manager.owner(&checkout.root)?, None);
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            assert!(
+                stderr.contains(
+                    checkout
+                        .root
+                        .file_name()
+                        .context("checkout name")?
+                        .to_string_lossy()
+                        .as_ref()
+                )
+            );
+            assert!(stderr.contains("Remove it manually with `git worktree remove`"));
+            assert!(
+                server
+                    .received_requests()
+                    .await
+                    .context("requests")?
+                    .iter()
+                    .skip(request_count)
+                    .any(|request| request.url.path() == "/backend-api/wham/config/bundle")
+            );
+        } else {
+            assert!(!home.join("worktrees").exists());
+        }
+    }
+    Ok(())
+}
+
+#[test]
+fn worktree_rejects_remote_defaults_before_allocation() -> anyhow::Result<()> {
+    for route in ["environment", "file"] {
+        let test = test_codex_exec();
+        let mut command = test.cmd();
+        if route == "environment" {
+            command.env("CODEX_EXEC_SERVER_URL", "ws://127.0.0.1:9");
+        } else {
+            fs::write(
+                test.home_path().join("environments.toml"),
+                "default = 'remote'\n[[environments]]\nid = 'remote'\nurl = 'ws://127.0.0.1:9'\n",
+            )?;
+        }
+        let output = command
+            .args(["--worktree", "-c", "features.worktrees=true", "prompt"])
+            .output()?;
+        assert!(!output.status.success(), "{route}");
+        assert!(
+            String::from_utf8_lossy(&output.stderr).contains("--worktree requires local execution"),
+            "{route}: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        assert!(!test.home_path().join("worktrees").exists(), "{route}");
+    }
+    Ok(())
+}
+
+#[test]
+fn worktree_rejects_disabled_features_and_ignored_config_before_allocation() -> anyhow::Result<()> {
+    for (config, args, expected) in [
+        (
+            "",
+            vec!["--ignore-user-config", "prompt"],
+            "--worktree cannot be combined with --ignore-user-config",
+        ),
+        (
+            "features.worktrees = false",
+            vec!["prompt"],
+            "--enable worktrees",
+        ),
+        (
+            "features.worktrees = false",
+            vec!["fork", "missing"],
+            "--enable worktrees",
+        ),
+        (
+            "features.worktrees = true",
+            vec!["-c", "features.worktrees=false", "prompt"],
+            "--enable worktrees",
+        ),
+    ] {
+        let test = test_codex_exec();
+        fs::write(test.home_path().join("config.toml"), config)?;
+        let output = test.cmd().arg("--worktree").args(args).output()?;
+        assert!(!output.status.success());
+        assert!(String::from_utf8_lossy(&output.stderr).contains(expected));
+        assert!(!test.home_path().join("worktrees").exists());
+    }
+    Ok(())
+}
diff --git a/codex-rs/execpolicy/examples/example.codexpolicy b/codex-rs/execpolicy/examples/example.codexpolicy
new file mode 100644
index 0000000000000000000000000000000000000000..4040f612092ece72676032dcc38b659ee2b4069b
--- /dev/null
+++ b/codex-rs/execpolicy/examples/example.codexpolicy
@@ -0,0 +1,78 @@
+
+# Example policy to illustrate syntax; not comprehensive and not recommended for actual use.
+
+prefix_rule(
+    pattern = ["git", "reset", "--hard"],
+    decision = "forbidden",
+    justification = "destructive operation",
+    match = [
+        ["git", "reset", "--hard"],
+    ],
+    not_match = [
+        ["git", "reset", "--keep"],
+        "git reset --merge",
+    ],
+)
+
+prefix_rule(
+    pattern = ["ls"],
+    match = [
+        ["ls"],
+        ["ls", "-l"],
+        ["ls", "-a", "."],
+    ],
+)
+
+prefix_rule(
+    pattern = ["cat"],
+    match = [
+        ["cat", "file.txt"],
+        ["cat", "-n", "README.md"],
+    ],
+)
+
+prefix_rule(
+    pattern = ["cp"],
+    decision = "prompt",
+    match = [
+        ["cp", "foo", "bar"],
+        "cp -r src dest",
+    ],
+)
+
+prefix_rule(
+    pattern = ["head"],
+    match = [
+        ["head", "README.md"],
+        ["head", "-n", "5", "CHANGELOG.md"],
+    ],
+    not_match = [
+        ["hea", "-n", "1,5p", "CHANGELOG.md"],
+    ],
+)
+
+prefix_rule(
+    pattern = ["printenv"],
+    match = [
+        ["printenv"],
+        ["printenv", "PATH"],
+    ],
+    not_match = [
+        ["print", "-0"],
+    ],
+)
+
+prefix_rule(
+    pattern = ["pwd"],
+    match = [
+        ["pwd"],
+    ],
+)
+
+prefix_rule(
+    pattern = ["which"],
+    match = [
+        ["which", "python3"],
+        ["which", "-a", "python3"],
+    ],
+)
diff --git a/codex-rs/execpolicy/src/amend.rs b/codex-rs/execpolicy/src/amend.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e25fd1bd91440fb349e3979151aba62eb5c16ed8
--- /dev/null
+++ b/codex-rs/execpolicy/src/amend.rs
@@ -0,0 +1,337 @@
+use std::fs::OpenOptions;
+use std::io::Read;
+use std::io::Seek;
+use std::io::SeekFrom;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+
+use crate::decision::Decision;
+use crate::rule::NetworkRuleProtocol;
+use crate::rule::normalize_network_rule_host;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum AmendError {
+    #[error("prefix rule requires at least one token")]
+    EmptyPrefix,
+    #[error("invalid network rule: {0}")]
+    InvalidNetworkRule(String),
+    #[error("policy path has no parent: {path}")]
+    MissingParent { path: PathBuf },
+    #[error("failed to create policy directory {dir}: {source}")]
+    CreatePolicyDir {
+        dir: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("failed to format prefix tokens: {source}")]
+    SerializePrefix { source: serde_json::Error },
+    #[error("failed to serialize network rule field: {source}")]
+    SerializeNetworkRule { source: serde_json::Error },
+    #[error("failed to open policy file {path}: {source}")]
+    OpenPolicyFile {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("failed to write to policy file {path}: {source}")]
+    WritePolicyFile {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("failed to lock policy file {path}: {source}")]
+    LockPolicyFile {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("failed to seek policy file {path}: {source}")]
+    SeekPolicyFile {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("failed to read policy file {path}: {source}")]
+    ReadPolicyFile {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+    #[error("failed to read metadata for policy file {path}: {source}")]
+    PolicyMetadata {
+        path: PathBuf,
+        source: std::io::Error,
+    },
+}
+
+/// Note this thread uses advisory file locking and performs blocking I/O, so it should be used with
+/// [`tokio::task::spawn_blocking`] when called from an async context.
+pub fn blocking_append_allow_prefix_rule(
+    policy_path: &Path,
+    prefix: &[String],
+) -> Result<(), AmendError> {
+    if prefix.is_empty() {
+        return Err(AmendError::EmptyPrefix);
+    }
+
+    let tokens = prefix
+        .iter()
+        .map(serde_json::to_string)
+        .collect::<Result<Vec<_>, _>>()
+        .map_err(|source| AmendError::SerializePrefix { source })?;
+    let pattern = format!("[{}]", tokens.join(", "));
+    let rule = format!(r#"prefix_rule(pattern={pattern}, decision="allow")"#);
+    append_rule_line(policy_path, &rule)
+}
+
+/// Note this function uses advisory file locking and performs blocking I/O, so it should be used
+/// with [`tokio::task::spawn_blocking`] when called from an async context.
+pub fn blocking_append_network_rule(
+    policy_path: &Path,
+    host: &str,
+    protocol: NetworkRuleProtocol,
+    decision: Decision,
+    justification: Option<&str>,
+) -> Result<(), AmendError> {
+    let host = normalize_network_rule_host(host)
+        .map_err(|err| AmendError::InvalidNetworkRule(err.to_string()))?;
+    if let Some(raw) = justification
+        && raw.trim().is_empty()
+    {
+        return Err(AmendError::InvalidNetworkRule(
+            "justification cannot be empty".to_string(),
+        ));
+    }
+
+    let host = serde_json::to_string(&host)
+        .map_err(|source| AmendError::SerializeNetworkRule { source })?;
+    let protocol = serde_json::to_string(protocol.as_policy_string())
+        .map_err(|source| AmendError::SerializeNetworkRule { source })?;
+    let decision = serde_json::to_string(match decision {
+        Decision::Allow => "allow",
+        Decision::Prompt => "prompt",
+        Decision::Forbidden => "deny",
+    })
+    .map_err(|source| AmendError::SerializeNetworkRule { source })?;
+
+    let mut args = vec![
+        format!("host={host}"),
+        format!("protocol={protocol}"),
+        format!("decision={decision}"),
+    ];
+    if let Some(justification) = justification {
+        let justification = serde_json::to_string(justification)
+            .map_err(|source| AmendError::SerializeNetworkRule { source })?;
+        args.push(format!("justification={justification}"));
+    }
+    let rule = format!("network_rule({})", args.join(", "));
+    append_rule_line(policy_path, &rule)
+}
+
+fn append_rule_line(policy_path: &Path, rule: &str) -> Result<(), AmendError> {
+    let dir = policy_path
+        .parent()
+        .ok_or_else(|| AmendError::MissingParent {
+            path: policy_path.to_path_buf(),
+        })?;
+    match std::fs::create_dir(dir) {
+        Ok(()) => {}
+        Err(ref source) if source.kind() == std::io::ErrorKind::AlreadyExists => {}
+        Err(source) => {
+            return Err(AmendError::CreatePolicyDir {
+                dir: dir.to_path_buf(),
+                source,
+            });
+        }
+    }
+
+    append_locked_line(policy_path, rule)
+}
+
+fn append_locked_line(policy_path: &Path, line: &str) -> Result<(), AmendError> {
+    let mut file = OpenOptions::new()
+        .create(true)
+        .read(true)
+        .append(true)
+        .open(policy_path)
+        .map_err(|source| AmendError::OpenPolicyFile {
+            path: policy_path.to_path_buf(),
+            source,
+        })?;
+    file.lock().map_err(|source| AmendError::LockPolicyFile {
+        path: policy_path.to_path_buf(),
+        source,
+    })?;
+
+    file.seek(SeekFrom::Start(0))
+        .map_err(|source| AmendError::SeekPolicyFile {
+            path: policy_path.to_path_buf(),
+            source,
+        })?;
+    let mut contents = String::new();
+    file.read_to_string(&mut contents)
+        .map_err(|source| AmendError::ReadPolicyFile {
+            path: policy_path.to_path_buf(),
+            source,
+        })?;
+
+    if contents.lines().any(|existing| existing == line) {
+        return Ok(());
+    }
+
+    if !contents.is_empty() && !contents.ends_with('\n') {
+        file.write_all(b"\n")
+            .map_err(|source| AmendError::WritePolicyFile {
+                path: policy_path.to_path_buf(),
+                source,
+            })?;
+    }
+
+    file.write_all(format!("{line}\n").as_bytes())
+        .map_err(|source| AmendError::WritePolicyFile {
+            path: policy_path.to_path_buf(),
+            source,
+        })?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use tempfile::tempdir;
+
+    #[test]
+    fn appends_rule_and_creates_directories() {
+        let tmp = tempdir().expect("create temp dir");
+        let policy_path = tmp.path().join("rules").join("default.rules");
+
+        blocking_append_allow_prefix_rule(
+            &policy_path,
+            &[String::from("echo"), String::from("Hello, world!")],
+        )
+        .expect("append rule");
+
+        let contents = std::fs::read_to_string(&policy_path).expect("default.rules should exist");
+        assert_eq!(
+            contents,
+            r#"prefix_rule(pattern=["echo", "Hello, world!"], decision="allow")
+"#
+        );
+    }
+
+    #[test]
+    fn appends_rule_without_duplicate_newline() {
+        let tmp = tempdir().expect("create temp dir");
+        let policy_path = tmp.path().join("rules").join("default.rules");
+        std::fs::create_dir_all(policy_path.parent().unwrap()).expect("create policy dir");
+        std::fs::write(
+            &policy_path,
+            r#"prefix_rule(pattern=["ls"], decision="allow")
+"#,
+        )
+        .expect("write seed rule");
+
+        blocking_append_allow_prefix_rule(
+            &policy_path,
+            &[String::from("echo"), String::from("Hello, world!")],
+        )
+        .expect("append rule");
+
+        let contents = std::fs::read_to_string(&policy_path).expect("read policy");
+        assert_eq!(
+            contents,
+            r#"prefix_rule(pattern=["ls"], decision="allow")
+prefix_rule(pattern=["echo", "Hello, world!"], decision="allow")
+"#
+        );
+    }
+
+    #[test]
+    fn inserts_newline_when_missing_before_append() {
+        let tmp = tempdir().expect("create temp dir");
+        let policy_path = tmp.path().join("rules").join("default.rules");
+        std::fs::create_dir_all(policy_path.parent().unwrap()).expect("create policy dir");
+        std::fs::write(
+            &policy_path,
+            r#"prefix_rule(pattern=["ls"], decision="allow")"#,
+        )
+        .expect("write seed rule without newline");
+
+        blocking_append_allow_prefix_rule(
+            &policy_path,
+            &[String::from("echo"), String::from("Hello, world!")],
+        )
+        .expect("append rule");
+
+        let contents = std::fs::read_to_string(&policy_path).expect("read policy");
+        assert_eq!(
+            contents,
+            r#"prefix_rule(pattern=["ls"], decision="allow")
+prefix_rule(pattern=["echo", "Hello, world!"], decision="allow")
+"#
+        );
+    }
+
+    #[test]
+    fn appends_network_rule() {
+        let tmp = tempdir().expect("create temp dir");
+        let policy_path = tmp.path().join("rules").join("default.rules");
+
+        blocking_append_network_rule(
+            &policy_path,
+            "Api.GitHub.com",
+            NetworkRuleProtocol::Https,
+            Decision::Allow,
+            Some("Allow https_connect access to api.github.com"),
+        )
+        .expect("append network rule");
+
+        let contents = std::fs::read_to_string(&policy_path).expect("read policy");
+        assert_eq!(
+            contents,
+            r#"network_rule(host="api.github.com", protocol="https", decision="allow", justification="Allow https_connect access to api.github.com")
+"#
+        );
+    }
+
+    #[test]
+    fn appends_prefix_and_network_rules() {
+        let tmp = tempdir().expect("create temp dir");
+        let policy_path = tmp.path().join("rules").join("default.rules");
+
+        blocking_append_allow_prefix_rule(&policy_path, &[String::from("curl")])
+            .expect("append prefix rule");
+        blocking_append_network_rule(
+            &policy_path,
+            "api.github.com",
+            NetworkRuleProtocol::Https,
+            Decision::Allow,
+            Some("Allow https_connect access to api.github.com"),
+        )
+        .expect("append network rule");
+
+        let contents = std::fs::read_to_string(&policy_path).expect("read policy");
+        assert_eq!(
+            contents,
+            r#"prefix_rule(pattern=["curl"], decision="allow")
+network_rule(host="api.github.com", protocol="https", decision="allow", justification="Allow https_connect access to api.github.com")
+"#
+        );
+    }
+
+    #[test]
+    fn rejects_wildcard_network_rule_host() {
+        let tmp = tempdir().expect("create temp dir");
+        let policy_path = tmp.path().join("rules").join("default.rules");
+        let err = blocking_append_network_rule(
+            &policy_path,
+            "*.example.com",
+            NetworkRuleProtocol::Https,
+            Decision::Allow,
+            /*justification*/ None,
+        )
+        .expect_err("wildcards should be rejected");
+        assert_eq!(
+            err.to_string(),
+            "invalid network rule: invalid rule: network_rule host must be a specific host; wildcards are not allowed"
+        );
+    }
+}
diff --git a/codex-rs/execpolicy/src/decision.rs b/codex-rs/execpolicy/src/decision.rs
new file mode 100644
index 0000000000000000000000000000000000000000..15dc1f711d7891742576ac000baef756a9342894
--- /dev/null
+++ b/codex-rs/execpolicy/src/decision.rs
@@ -0,0 +1,27 @@
+use serde::Deserialize;
+use serde::Serialize;
+
+use crate::error::Error;
+use crate::error::Result;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum Decision {
+    /// Command may run without further approval.
+    Allow,
+    /// Request explicit user approval; rejected outright when running with `approval_policy="never"`.
+    Prompt,
+    /// Command is blocked without further consideration.
+    Forbidden,
+}
+
+impl Decision {
+    pub fn parse(raw: &str) -> Result<Self> {
+        match raw {
+            "allow" => Ok(Self::Allow),
+            "prompt" => Ok(Self::Prompt),
+            "forbidden" => Ok(Self::Forbidden),
+            other => Err(Error::InvalidDecision(other.to_string())),
+        }
+    }
+}
diff --git a/codex-rs/execpolicy/src/error.rs b/codex-rs/execpolicy/src/error.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0f2be753aa65f18cec7d6a4fabeec8a0fa6d253c
--- /dev/null
+++ b/codex-rs/execpolicy/src/error.rs
@@ -0,0 +1,101 @@
+use starlark::Error as StarlarkError;
+use thiserror::Error;
+
+pub type Result<T> = std::result::Result<T, Error>;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TextPosition {
+    pub line: usize,
+    pub column: usize,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TextRange {
+    pub start: TextPosition,
+    pub end: TextPosition,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ErrorLocation {
+    pub path: String,
+    pub range: TextRange,
+}
+
+#[derive(Debug, Error)]
+pub enum Error {
+    #[error("invalid decision: {0}")]
+    InvalidDecision(String),
+    #[error("invalid pattern element: {0}")]
+    InvalidPattern(String),
+    #[error("invalid example: {0}")]
+    InvalidExample(String),
+    #[error("invalid rule: {0}")]
+    InvalidRule(String),
+    #[error(
+        "expected every example to match at least one rule. rules: {rules:?}; unmatched examples: \
+         {examples:?}"
+    )]
+    ExampleDidNotMatch {
+        rules: Vec<String>,
+        examples: Vec<String>,
+        location: Option<ErrorLocation>,
+    },
+    #[error("expected example to not match rule `{rule}`: {example}")]
+    ExampleDidMatch {
+        rule: String,
+        example: String,
+        location: Option<ErrorLocation>,
+    },
+    #[error("starlark error: {0}")]
+    Starlark(StarlarkError),
+}
+
+impl Error {
+    pub fn with_location(self, location: ErrorLocation) -> Self {
+        match self {
+            Error::ExampleDidNotMatch {
+                rules,
+                examples,
+                location: None,
+            } => Error::ExampleDidNotMatch {
+                rules,
+                examples,
+                location: Some(location),
+            },
+            Error::ExampleDidMatch {
+                rule,
+                example,
+                location: None,
+            } => Error::ExampleDidMatch {
+                rule,
+                example,
+                location: Some(location),
+            },
+            other => other,
+        }
+    }
+
+    pub fn location(&self) -> Option<ErrorLocation> {
+        match self {
+            Error::ExampleDidNotMatch { location, .. }
+            | Error::ExampleDidMatch { location, .. } => location.clone(),
+            Error::Starlark(err) => err.span().map(|span| {
+                let resolved = span.resolve_span();
+                ErrorLocation {
+                    path: span.filename().to_string(),
+                    range: TextRange {
+                        start: TextPosition {
+                            line: resolved.begin.line + 1,
+                            column: resolved.begin.column + 1,
+                        },
+                        end: TextPosition {
+                            line: resolved.end.line + 1,
+                            column: resolved.end.column + 1,
+                        },
+                    },
+                }
+            }),
+            _ => None,
+        }
+    }
+}
diff --git a/codex-rs/execpolicy/src/execpolicycheck.rs b/codex-rs/execpolicy/src/execpolicycheck.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b72995d04b2ecff16f2a39af954a7facadfefe18
--- /dev/null
+++ b/codex-rs/execpolicy/src/execpolicycheck.rs
@@ -0,0 +1,95 @@
+use std::fs;
+use std::path::PathBuf;
+
+use anyhow::Context;
+use anyhow::Result;
+use clap::Parser;
+use serde::Serialize;
+
+use crate::Decision;
+use crate::MatchOptions;
+use crate::Policy;
+use crate::PolicyParser;
+use crate::RuleMatch;
+
+/// Arguments for evaluating a command against one or more execpolicy files.
+#[derive(Debug, Parser, Clone)]
+pub struct ExecPolicyCheckCommand {
+    /// Paths to execpolicy rule files to evaluate (repeatable).
+    #[arg(short = 'r', long = "rules", value_name = "PATH", required = true)]
+    pub rules: Vec<PathBuf>,
+
+    /// Pretty-print the JSON output.
+    #[arg(long)]
+    pub pretty: bool,
+
+    /// Resolve absolute program paths against basename rules, gated by any
+    /// `host_executable()` definitions in the loaded policy files.
+    #[arg(long)]
+    pub resolve_host_executables: bool,
+
+    /// Command tokens to check against the policy.
+    #[arg(
+        value_name = "COMMAND",
+        required = true,
+        trailing_var_arg = true,
+        allow_hyphen_values = true
+    )]
+    pub command: Vec<String>,
+}
+
+impl ExecPolicyCheckCommand {
+    /// Load the policies for this command, evaluate the command, and render JSON output.
+    pub fn run(&self) -> Result<()> {
+        let policy = load_policies(&self.rules)?;
+        let matched_rules = policy.matches_for_command_with_options(
+            &self.command,
+            /*heuristics_fallback*/ None,
+            &MatchOptions {
+                resolve_host_executables: self.resolve_host_executables,
+            },
+        );
+
+        let json = format_matches_json(&matched_rules, self.pretty)?;
+        println!("{json}");
+
+        Ok(())
+    }
+}
+
+pub fn format_matches_json(matched_rules: &[RuleMatch], pretty: bool) -> Result<String> {
+    let output = ExecPolicyCheckOutput {
+        matched_rules,
+        decision: matched_rules.iter().map(RuleMatch::decision).max(),
+    };
+
+    if pretty {
+        serde_json::to_string_pretty(&output).map_err(Into::into)
+    } else {
+        serde_json::to_string(&output).map_err(Into::into)
+    }
+}
+
+pub fn load_policies(policy_paths: &[PathBuf]) -> Result<Policy> {
+    let mut parser = PolicyParser::new();
+
+    for policy_path in policy_paths {
+        let policy_file_contents = fs::read_to_string(policy_path)
+            .with_context(|| format!("failed to read policy at {}", policy_path.display()))?;
+        let policy_identifier = policy_path.to_string_lossy().to_string();
+        parser
+            .parse(&policy_identifier, &policy_file_contents)
+            .with_context(|| format!("failed to parse policy at {}", policy_path.display()))?;
+    }
+
+    Ok(parser.build())
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ExecPolicyCheckOutput<'a> {
+    #[serde(rename = "matchedRules")]
+    matched_rules: &'a [RuleMatch],
+    #[serde(skip_serializing_if = "Option::is_none")]
+    decision: Option<Decision>,
+}
diff --git a/codex-rs/execpolicy/src/executable_name.rs b/codex-rs/execpolicy/src/executable_name.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bb3e8a536c2f246d5dc075817cb8fa737a3cb5e3
--- /dev/null
+++ b/codex-rs/execpolicy/src/executable_name.rs
@@ -0,0 +1,29 @@
+use std::path::Path;
+
+#[cfg(windows)]
+const WINDOWS_EXECUTABLE_SUFFIXES: [&str; 4] = [".exe", ".cmd", ".bat", ".com"];
+
+pub(crate) fn executable_lookup_key(raw: &str) -> String {
+    #[cfg(windows)]
+    {
+        let raw = raw.to_ascii_lowercase();
+        for suffix in WINDOWS_EXECUTABLE_SUFFIXES {
+            if raw.ends_with(suffix) {
+                let stripped_len = raw.len() - suffix.len();
+                return raw[..stripped_len].to_string();
+            }
+        }
+        raw
+    }
+
+    #[cfg(not(windows))]
+    {
+        raw.to_string()
+    }
+}
+
+pub(crate) fn executable_path_lookup_key(path: &Path) -> Option<String> {
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .map(executable_lookup_key)
+}
diff --git a/codex-rs/execpolicy/src/lib.rs b/codex-rs/execpolicy/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..293e2750589dd6046a49ac7561c20c6021799bfd
--- /dev/null
+++ b/codex-rs/execpolicy/src/lib.rs
@@ -0,0 +1,33 @@
+pub(crate) mod amend;
+pub(crate) mod decision;
+pub(crate) mod error;
+pub(crate) mod execpolicycheck;
+mod executable_name;
+pub(crate) mod parser;
+pub(crate) mod policy;
+pub mod rule;
+mod sandbox_migration;
+
+pub use amend::AmendError;
+pub use amend::blocking_append_allow_prefix_rule;
+pub use amend::blocking_append_network_rule;
+pub use decision::Decision;
+pub use error::Error;
+pub use error::ErrorLocation;
+pub use error::Result;
+pub use error::TextPosition;
+pub use error::TextRange;
+pub use execpolicycheck::ExecPolicyCheckCommand;
+pub use parser::PolicyParser;
+pub use policy::Evaluation;
+pub use policy::MatchOptions;
+pub use policy::Policy;
+pub use policy::RequirementsExecPolicy;
+pub use rule::NetworkRuleProtocol;
+pub use rule::PatternToken;
+pub use rule::PrefixPattern;
+pub use rule::PrefixRule;
+pub use rule::Rule;
+pub use rule::RuleMatch;
+pub use rule::RuleRef;
+pub use sandbox_migration::prefix_rule_migration;
diff --git a/codex-rs/execpolicy/src/main.rs b/codex-rs/execpolicy/src/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..82e1bc12c4435ff6dc17526ed6426ce73f9f574a
--- /dev/null
+++ b/codex-rs/execpolicy/src/main.rs
@@ -0,0 +1,18 @@
+use anyhow::Result;
+use clap::Parser;
+use codex_execpolicy::ExecPolicyCheckCommand;
+
+/// CLI for evaluating exec policies
+#[derive(Parser)]
+#[command(name = "codex-execpolicy")]
+enum Cli {
+    /// Evaluate a command against a policy.
+    Check(ExecPolicyCheckCommand),
+}
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+    match cli {
+        Cli::Check(cmd) => cmd.run(),
+    }
+}
diff --git a/codex-rs/execpolicy/src/parser.rs b/codex-rs/execpolicy/src/parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..33262db1b3a8bdff7a0c5ec6d93b58b437eb8166
--- /dev/null
+++ b/codex-rs/execpolicy/src/parser.rs
@@ -0,0 +1,473 @@
+use codex_utils_absolute_path::AbsolutePathBuf;
+use multimap::MultiMap;
+use starlark::any::ProvidesStaticType;
+use starlark::codemap::FileSpan;
+use starlark::environment::GlobalsBuilder;
+use starlark::environment::Module;
+use starlark::eval::Evaluator;
+use starlark::starlark_module;
+use starlark::syntax::AstModule;
+use starlark::syntax::Dialect;
+use starlark::values::Value;
+use starlark::values::list::ListRef;
+use starlark::values::list::UnpackList;
+use starlark::values::none::NoneType;
+use std::cell::RefCell;
+use std::cell::RefMut;
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::Arc;
+
+use crate::decision::Decision;
+use crate::error::Error;
+use crate::error::ErrorLocation;
+use crate::error::Result;
+use crate::error::TextPosition;
+use crate::error::TextRange;
+use crate::executable_name::executable_lookup_key;
+use crate::executable_name::executable_path_lookup_key;
+use crate::rule::NetworkRule;
+use crate::rule::NetworkRuleProtocol;
+use crate::rule::PatternToken;
+use crate::rule::PrefixPattern;
+use crate::rule::PrefixRule;
+use crate::rule::RuleRef;
+use crate::rule::validate_match_examples;
+use crate::rule::validate_not_match_examples;
+
+pub struct PolicyParser {
+    builder: RefCell<PolicyBuilder>,
+}
+
+impl Default for PolicyParser {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl PolicyParser {
+    pub fn new() -> Self {
+        Self {
+            builder: RefCell::new(PolicyBuilder::new()),
+        }
+    }
+
+    /// Parses a policy, tagging parser errors with `policy_identifier` so failures include the
+    /// identifier alongside line numbers.
+    pub fn parse(&mut self, policy_identifier: &str, policy_file_contents: &str) -> Result<()> {
+        let pending_validation_count = self.builder.borrow().pending_example_validations.len();
+        let mut dialect = Dialect::Extended.clone();
+        dialect.enable_f_strings = true;
+        let ast = AstModule::parse(
+            policy_identifier,
+            policy_file_contents.to_string(),
+            &dialect,
+        )
+        .map_err(Error::Starlark)?;
+        let globals = GlobalsBuilder::standard().with(policy_builtins).build();
+        Module::with_temp_heap(|module| {
+            let mut eval = Evaluator::new(&module);
+            eval.extra = Some(&self.builder);
+            eval.eval_module(ast, &globals)
+                .map(|_| ())
+                .map_err(Error::Starlark)
+        })?;
+        self.builder
+            .borrow()
+            .validate_pending_examples_from(pending_validation_count)?;
+        Ok(())
+    }
+
+    pub fn build(self) -> crate::policy::Policy {
+        self.builder.into_inner().build()
+    }
+}
+
+#[derive(Debug, ProvidesStaticType)]
+struct PolicyBuilder {
+    rules_by_program: MultiMap<String, RuleRef>,
+    network_rules: Vec<NetworkRule>,
+    host_executables_by_name: HashMap<String, Arc<[AbsolutePathBuf]>>,
+    pending_example_validations: Vec<PendingExampleValidation>,
+}
+
+impl PolicyBuilder {
+    fn new() -> Self {
+        Self {
+            rules_by_program: MultiMap::new(),
+            network_rules: Vec::new(),
+            host_executables_by_name: HashMap::new(),
+            pending_example_validations: Vec::new(),
+        }
+    }
+
+    fn add_rule(&mut self, rule: RuleRef) {
+        self.rules_by_program
+            .insert(rule.program().to_string(), rule);
+    }
+
+    fn add_network_rule(&mut self, rule: NetworkRule) {
+        self.network_rules.push(rule);
+    }
+
+    fn add_host_executable(&mut self, name: String, paths: Vec<AbsolutePathBuf>) {
+        self.host_executables_by_name.insert(name, paths.into());
+    }
+
+    fn add_pending_example_validation(
+        &mut self,
+        rules: Vec<RuleRef>,
+        matches: Vec<Vec<String>>,
+        not_matches: Vec<Vec<String>>,
+        location: Option<ErrorLocation>,
+    ) {
+        self.pending_example_validations
+            .push(PendingExampleValidation {
+                rules,
+                matches,
+                not_matches,
+                location,
+            });
+    }
+
+    fn validate_pending_examples_from(&self, start: usize) -> Result<()> {
+        for validation in &self.pending_example_validations[start..] {
+            let mut rules_by_program = MultiMap::new();
+            for rule in &validation.rules {
+                rules_by_program.insert(rule.program().to_string(), rule.clone());
+            }
+
+            let policy = crate::policy::Policy::from_parts(
+                rules_by_program,
+                Vec::new(),
+                self.host_executables_by_name.clone(),
+            );
+            validate_not_match_examples(&policy, &validation.rules, &validation.not_matches)
+                .map_err(|error| attach_validation_location(error, validation.location.clone()))?;
+            validate_match_examples(&policy, &validation.rules, &validation.matches)
+                .map_err(|error| attach_validation_location(error, validation.location.clone()))?;
+        }
+
+        Ok(())
+    }
+
+    fn build(self) -> crate::policy::Policy {
+        crate::policy::Policy::from_parts(
+            self.rules_by_program,
+            self.network_rules,
+            self.host_executables_by_name,
+        )
+    }
+}
+
+#[derive(Debug)]
+struct PendingExampleValidation {
+    rules: Vec<RuleRef>,
+    matches: Vec<Vec<String>>,
+    not_matches: Vec<Vec<String>>,
+    location: Option<ErrorLocation>,
+}
+
+fn parse_pattern<'v>(pattern: UnpackList<Value<'v>>) -> Result<Vec<PatternToken>> {
+    let tokens: Vec<PatternToken> = pattern
+        .items
+        .into_iter()
+        .map(parse_pattern_token)
+        .collect::<Result<_>>()?;
+    if tokens.is_empty() {
+        Err(Error::InvalidPattern("pattern cannot be empty".to_string()))
+    } else {
+        Ok(tokens)
+    }
+}
+
+fn parse_pattern_token<'v>(value: Value<'v>) -> Result<PatternToken> {
+    if let Some(s) = value.unpack_str() {
+        Ok(PatternToken::Single(s.to_string()))
+    } else if let Some(list) = ListRef::from_value(value) {
+        let tokens: Vec<String> = list
+            .content()
+            .iter()
+            .map(|value| {
+                value
+                    .unpack_str()
+                    .ok_or_else(|| {
+                        Error::InvalidPattern(format!(
+                            "pattern alternative must be a string (got {})",
+                            value.get_type()
+                        ))
+                    })
+                    .map(str::to_string)
+            })
+            .collect::<Result<_>>()?;
+
+        match tokens.as_slice() {
+            [] => Err(Error::InvalidPattern(
+                "pattern alternatives cannot be empty".to_string(),
+            )),
+            [single] => Ok(PatternToken::Single(single.clone())),
+            _ => Ok(PatternToken::Alts(tokens)),
+        }
+    } else {
+        Err(Error::InvalidPattern(format!(
+            "pattern element must be a string or list of strings (got {})",
+            value.get_type()
+        )))
+    }
+}
+
+fn parse_examples<'v>(examples: UnpackList<Value<'v>>) -> Result<Vec<Vec<String>>> {
+    examples.items.into_iter().map(parse_example).collect()
+}
+
+fn parse_literal_absolute_path(raw: &str) -> Result<AbsolutePathBuf> {
+    if !Path::new(raw).is_absolute() {
+        return Err(Error::InvalidRule(format!(
+            "host_executable paths must be absolute (got {raw})"
+        )));
+    }
+
+    AbsolutePathBuf::try_from(raw.to_string())
+        .map_err(|error| Error::InvalidRule(format!("invalid absolute path `{raw}`: {error}")))
+}
+
+fn validate_host_executable_name(name: &str) -> Result<()> {
+    if name.is_empty() {
+        return Err(Error::InvalidRule(
+            "host_executable name cannot be empty".to_string(),
+        ));
+    }
+
+    let path = Path::new(name);
+    if path.components().count() != 1
+        || path.file_name().and_then(|value| value.to_str()) != Some(name)
+    {
+        return Err(Error::InvalidRule(format!(
+            "host_executable name must be a bare executable name (got {name})"
+        )));
+    }
+
+    Ok(())
+}
+
+fn parse_network_rule_decision(raw: &str) -> Result<Decision> {
+    match raw {
+        "deny" => Ok(Decision::Forbidden),
+        other => Decision::parse(other),
+    }
+}
+
+fn error_location_from_file_span(span: FileSpan) -> ErrorLocation {
+    let resolved = span.resolve_span();
+    ErrorLocation {
+        path: span.filename().to_string(),
+        range: TextRange {
+            start: TextPosition {
+                line: resolved.begin.line + 1,
+                column: resolved.begin.column + 1,
+            },
+            end: TextPosition {
+                line: resolved.end.line + 1,
+                column: resolved.end.column + 1,
+            },
+        },
+    }
+}
+
+fn attach_validation_location(error: Error, location: Option<ErrorLocation>) -> Error {
+    match location {
+        Some(location) => error.with_location(location),
+        None => error,
+    }
+}
+
+fn parse_example<'v>(value: Value<'v>) -> Result<Vec<String>> {
+    if let Some(raw) = value.unpack_str() {
+        parse_string_example(raw)
+    } else if let Some(list) = ListRef::from_value(value) {
+        parse_list_example(list)
+    } else {
+        Err(Error::InvalidExample(format!(
+            "example must be a string or list of strings (got {})",
+            value.get_type()
+        )))
+    }
+}
+
+fn parse_string_example(raw: &str) -> Result<Vec<String>> {
+    let tokens = shlex::split(raw).ok_or_else(|| {
+        Error::InvalidExample("example string has invalid shell syntax".to_string())
+    })?;
+
+    if tokens.is_empty() {
+        Err(Error::InvalidExample(
+            "example cannot be an empty string".to_string(),
+        ))
+    } else {
+        Ok(tokens)
+    }
+}
+
+fn parse_list_example(list: &ListRef) -> Result<Vec<String>> {
+    let tokens: Vec<String> = list
+        .content()
+        .iter()
+        .map(|value| {
+            value
+                .unpack_str()
+                .ok_or_else(|| {
+                    Error::InvalidExample(format!(
+                        "example tokens must be strings (got {})",
+                        value.get_type()
+                    ))
+                })
+                .map(str::to_string)
+        })
+        .collect::<Result<_>>()?;
+
+    if tokens.is_empty() {
+        Err(Error::InvalidExample(
+            "example cannot be an empty list".to_string(),
+        ))
+    } else {
+        Ok(tokens)
+    }
+}
+
+fn policy_builder<'v, 'a>(eval: &Evaluator<'v, 'a, '_>) -> RefMut<'a, PolicyBuilder> {
+    #[expect(clippy::expect_used)]
+    eval.extra
+        .as_ref()
+        .expect("policy_builder requires Evaluator.extra to be populated")
+        .downcast_ref::<RefCell<PolicyBuilder>>()
+        .expect("Evaluator.extra must contain a PolicyBuilder")
+        .borrow_mut()
+}
+
+#[starlark_module]
+fn policy_builtins(builder: &mut GlobalsBuilder) {
+    fn prefix_rule<'v>(
+        pattern: UnpackList<Value<'v>>,
+        decision: Option<&'v str>,
+        r#match: Option<UnpackList<Value<'v>>>,
+        not_match: Option<UnpackList<Value<'v>>>,
+        justification: Option<&'v str>,
+        eval: &mut Evaluator<'v, '_, '_>,
+    ) -> anyhow::Result<NoneType> {
+        let decision = match decision {
+            Some(raw) => Decision::parse(raw)?,
+            None => Decision::Allow,
+        };
+
+        let justification = match justification {
+            Some(raw) if raw.trim().is_empty() => {
+                return Err(Error::InvalidRule("justification cannot be empty".to_string()).into());
+            }
+            Some(raw) => Some(raw.to_string()),
+            None => None,
+        };
+
+        let pattern_tokens = parse_pattern(pattern)?;
+
+        let matches: Vec<Vec<String>> =
+            r#match.map(parse_examples).transpose()?.unwrap_or_default();
+        let not_matches: Vec<Vec<String>> = not_match
+            .map(parse_examples)
+            .transpose()?
+            .unwrap_or_default();
+        let location = eval
+            .call_stack_top_location()
+            .map(error_location_from_file_span);
+
+        let mut builder = policy_builder(eval);
+
+        let (first_token, remaining_tokens) = pattern_tokens
+            .split_first()
+            .ok_or_else(|| Error::InvalidPattern("pattern cannot be empty".to_string()))?;
+
+        let rest: Arc<[PatternToken]> = remaining_tokens.to_vec().into();
+
+        let rules: Vec<RuleRef> = first_token
+            .alternatives()
+            .iter()
+            .map(|head| {
+                Arc::new(PrefixRule {
+                    pattern: PrefixPattern {
+                        first: Arc::from(head.as_str()),
+                        rest: rest.clone(),
+                    },
+                    decision,
+                    justification: justification.clone(),
+                }) as RuleRef
+            })
+            .collect();
+
+        builder.add_pending_example_validation(rules.clone(), matches, not_matches, location);
+        rules.into_iter().for_each(|rule| builder.add_rule(rule));
+        Ok(NoneType)
+    }
+
+    fn network_rule<'v>(
+        host: &'v str,
+        protocol: &'v str,
+        decision: &'v str,
+        justification: Option<&'v str>,
+        eval: &mut Evaluator<'v, '_, '_>,
+    ) -> anyhow::Result<NoneType> {
+        let protocol = NetworkRuleProtocol::parse(protocol)?;
+        let decision = parse_network_rule_decision(decision)?;
+        let justification = match justification {
+            Some(raw) if raw.trim().is_empty() => {
+                return Err(Error::InvalidRule("justification cannot be empty".to_string()).into());
+            }
+            Some(raw) => Some(raw.to_string()),
+            None => None,
+        };
+
+        let mut builder = policy_builder(eval);
+        builder.add_network_rule(NetworkRule {
+            host: crate::rule::normalize_network_rule_host(host)?,
+            protocol,
+            decision,
+            justification,
+        });
+        Ok(NoneType)
+    }
+
+    fn host_executable<'v>(
+        name: &'v str,
+        paths: UnpackList<Value<'v>>,
+        eval: &mut Evaluator<'v, '_, '_>,
+    ) -> anyhow::Result<NoneType> {
+        validate_host_executable_name(name)?;
+
+        let mut parsed_paths = Vec::new();
+        for value in paths.items {
+            let raw = value.unpack_str().ok_or_else(|| {
+                Error::InvalidRule(format!(
+                    "host_executable paths must be strings (got {})",
+                    value.get_type()
+                ))
+            })?;
+            let path = parse_literal_absolute_path(raw)?;
+            let Some(path_name) = executable_path_lookup_key(path.as_path()) else {
+                return Err(Error::InvalidRule(format!(
+                    "host_executable path `{raw}` must have basename `{name}`"
+                ))
+                .into());
+            };
+            if path_name != executable_lookup_key(name) {
+                return Err(Error::InvalidRule(format!(
+                    "host_executable path `{raw}` must have basename `{name}`"
+                ))
+                .into());
+            }
+            if !parsed_paths.iter().any(|existing| existing == &path) {
+                parsed_paths.push(path);
+            }
+        }
+
+        policy_builder(eval).add_host_executable(executable_lookup_key(name), parsed_paths);
+        Ok(NoneType)
+    }
+}
diff --git a/codex-rs/execpolicy/src/policy.rs b/codex-rs/execpolicy/src/policy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..78790517fd2b4bd462b02a304f24e20e6696e796
--- /dev/null
+++ b/codex-rs/execpolicy/src/policy.rs
@@ -0,0 +1,412 @@
+use crate::decision::Decision;
+use crate::error::Error;
+use crate::error::Result;
+use crate::executable_name::executable_path_lookup_key;
+use crate::rule::NetworkRule;
+use crate::rule::NetworkRuleProtocol;
+use crate::rule::PatternToken;
+use crate::rule::PrefixPattern;
+use crate::rule::PrefixRule;
+use crate::rule::RuleMatch;
+use crate::rule::RuleRef;
+use crate::rule::normalize_network_rule_host;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use multimap::MultiMap;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::sync::Arc;
+
+type HeuristicsFallback<'a> = Option<&'a dyn Fn(&[String]) -> Decision>;
+
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct MatchOptions {
+    pub resolve_host_executables: bool,
+}
+
+#[derive(Clone, Debug)]
+pub struct Policy {
+    rules_by_program: MultiMap<String, RuleRef>,
+    network_rules: Vec<NetworkRule>,
+    host_executables_by_name: HashMap<String, Arc<[AbsolutePathBuf]>>,
+}
+
+/// A requirements-owned execution policy with order-independent equality.
+#[derive(Debug, Clone)]
+pub struct RequirementsExecPolicy {
+    policy: Policy,
+}
+
+impl RequirementsExecPolicy {
+    pub fn new(policy: Policy) -> Self {
+        Self { policy }
+    }
+
+    pub fn fingerprint(&self) -> Vec<String> {
+        let mut entries = Vec::new();
+        for (program, rules) in self.policy.rules().iter_all() {
+            for rule in rules {
+                entries.push(format!("{program}:{rule:?}"));
+            }
+        }
+        entries.sort();
+        entries
+    }
+}
+
+impl PartialEq for RequirementsExecPolicy {
+    fn eq(&self, other: &Self) -> bool {
+        self.fingerprint() == other.fingerprint()
+    }
+}
+
+impl Eq for RequirementsExecPolicy {}
+
+impl AsRef<Policy> for RequirementsExecPolicy {
+    fn as_ref(&self) -> &Policy {
+        &self.policy
+    }
+}
+
+impl Policy {
+    pub fn new(rules_by_program: MultiMap<String, RuleRef>) -> Self {
+        Self::from_parts(rules_by_program, Vec::new(), HashMap::new())
+    }
+
+    pub fn from_parts(
+        rules_by_program: MultiMap<String, RuleRef>,
+        network_rules: Vec<NetworkRule>,
+        host_executables_by_name: HashMap<String, Arc<[AbsolutePathBuf]>>,
+    ) -> Self {
+        Self {
+            rules_by_program,
+            network_rules,
+            host_executables_by_name,
+        }
+    }
+
+    pub fn empty() -> Self {
+        Self::new(MultiMap::new())
+    }
+
+    pub fn rules(&self) -> &MultiMap<String, RuleRef> {
+        &self.rules_by_program
+    }
+
+    pub fn network_rules(&self) -> &[NetworkRule] {
+        &self.network_rules
+    }
+
+    pub fn host_executables(&self) -> &HashMap<String, Arc<[AbsolutePathBuf]>> {
+        &self.host_executables_by_name
+    }
+
+    pub fn get_allowed_prefixes(&self) -> Vec<Vec<String>> {
+        let mut prefixes = Vec::new();
+
+        for (_program, rules) in self.rules_by_program.iter_all() {
+            for rule in rules {
+                let Some(prefix_rule) = rule.as_any().downcast_ref::<PrefixRule>() else {
+                    continue;
+                };
+                if prefix_rule.decision != Decision::Allow {
+                    continue;
+                }
+
+                let mut prefix = Vec::with_capacity(prefix_rule.pattern.rest.len() + 1);
+                prefix.push(prefix_rule.pattern.first.as_ref().to_string());
+                prefix.extend(prefix_rule.pattern.rest.iter().map(render_pattern_token));
+                prefixes.push(prefix);
+            }
+        }
+
+        prefixes.sort();
+        prefixes.dedup();
+        prefixes
+    }
+
+    pub fn add_prefix_rule(&mut self, prefix: &[String], decision: Decision) -> Result<()> {
+        let (first_token, rest) = prefix
+            .split_first()
+            .ok_or_else(|| Error::InvalidPattern("prefix cannot be empty".to_string()))?;
+
+        let rule: RuleRef = Arc::new(PrefixRule {
+            pattern: PrefixPattern {
+                first: Arc::from(first_token.as_str()),
+                rest: rest
+                    .iter()
+                    .map(|token| PatternToken::Single(token.clone()))
+                    .collect::<Vec<_>>()
+                    .into(),
+            },
+            decision,
+            justification: None,
+        });
+
+        self.rules_by_program.insert(first_token.clone(), rule);
+        Ok(())
+    }
+
+    pub fn add_network_rule(
+        &mut self,
+        host: &str,
+        protocol: NetworkRuleProtocol,
+        decision: Decision,
+        justification: Option<String>,
+    ) -> Result<()> {
+        let host = normalize_network_rule_host(host)?;
+        if let Some(raw) = justification.as_deref()
+            && raw.trim().is_empty()
+        {
+            return Err(Error::InvalidRule(
+                "justification cannot be empty".to_string(),
+            ));
+        }
+        self.network_rules.push(NetworkRule {
+            host,
+            protocol,
+            decision,
+            justification,
+        });
+        Ok(())
+    }
+
+    pub fn set_host_executable_paths(&mut self, name: String, paths: Vec<AbsolutePathBuf>) {
+        self.host_executables_by_name.insert(name, paths.into());
+    }
+
+    pub fn merge_overlay(&self, overlay: &Policy) -> Policy {
+        let mut combined_rules = self.rules_by_program.clone();
+        for (program, rules) in overlay.rules_by_program.iter_all() {
+            for rule in rules {
+                combined_rules.insert(program.clone(), rule.clone());
+            }
+        }
+
+        let mut combined_network_rules = self.network_rules.clone();
+        combined_network_rules.extend(overlay.network_rules.iter().cloned());
+
+        let mut host_executables_by_name = self.host_executables_by_name.clone();
+        host_executables_by_name.extend(
+            overlay
+                .host_executables_by_name
+                .iter()
+                .map(|(name, paths)| (name.clone(), paths.clone())),
+        );
+
+        Policy::from_parts(
+            combined_rules,
+            combined_network_rules,
+            host_executables_by_name,
+        )
+    }
+
+    pub fn compiled_network_domains(&self) -> (Vec<String>, Vec<String>) {
+        let mut allowed = Vec::new();
+        let mut denied = Vec::new();
+
+        for rule in &self.network_rules {
+            match rule.decision {
+                Decision::Allow => {
+                    denied.retain(|entry| entry != &rule.host);
+                    upsert_domain(&mut allowed, &rule.host);
+                }
+                Decision::Forbidden => {
+                    allowed.retain(|entry| entry != &rule.host);
+                    upsert_domain(&mut denied, &rule.host);
+                }
+                Decision::Prompt => {}
+            }
+        }
+
+        (allowed, denied)
+    }
+
+    pub fn check<F>(&self, cmd: &[String], heuristics_fallback: &F) -> Evaluation
+    where
+        F: Fn(&[String]) -> Decision,
+    {
+        let matched_rules = self.matches_for_command_with_options(
+            cmd,
+            Some(heuristics_fallback),
+            &MatchOptions::default(),
+        );
+        Evaluation::from_matches(matched_rules)
+    }
+
+    pub fn check_with_options<F>(
+        &self,
+        cmd: &[String],
+        heuristics_fallback: &F,
+        options: &MatchOptions,
+    ) -> Evaluation
+    where
+        F: Fn(&[String]) -> Decision,
+    {
+        let matched_rules =
+            self.matches_for_command_with_options(cmd, Some(heuristics_fallback), options);
+        Evaluation::from_matches(matched_rules)
+    }
+
+    /// Checks multiple commands and aggregates the results.
+    pub fn check_multiple<Commands, F>(
+        &self,
+        commands: Commands,
+        heuristics_fallback: &F,
+    ) -> Evaluation
+    where
+        Commands: IntoIterator,
+        Commands::Item: AsRef<[String]>,
+        F: Fn(&[String]) -> Decision,
+    {
+        self.check_multiple_with_options(commands, heuristics_fallback, &MatchOptions::default())
+    }
+
+    pub fn check_multiple_with_options<Commands, F>(
+        &self,
+        commands: Commands,
+        heuristics_fallback: &F,
+        options: &MatchOptions,
+    ) -> Evaluation
+    where
+        Commands: IntoIterator,
+        Commands::Item: AsRef<[String]>,
+        F: Fn(&[String]) -> Decision,
+    {
+        let matched_rules: Vec<RuleMatch> = commands
+            .into_iter()
+            .flat_map(|command| {
+                self.matches_for_command_with_options(
+                    command.as_ref(),
+                    Some(heuristics_fallback),
+                    options,
+                )
+            })
+            .collect();
+
+        Evaluation::from_matches(matched_rules)
+    }
+
+    /// Returns matching rules for the given command. If no rules match and
+    /// `heuristics_fallback` is provided, returns a single
+    /// `HeuristicsRuleMatch` with the decision rendered by
+    /// `heuristics_fallback`.
+    ///
+    /// If `heuristics_fallback.is_some()`, then the returned vector is
+    /// guaranteed to be non-empty.
+    pub fn matches_for_command(
+        &self,
+        cmd: &[String],
+        heuristics_fallback: HeuristicsFallback<'_>,
+    ) -> Vec<RuleMatch> {
+        self.matches_for_command_with_options(cmd, heuristics_fallback, &MatchOptions::default())
+    }
+
+    pub fn matches_for_command_with_options(
+        &self,
+        cmd: &[String],
+        heuristics_fallback: HeuristicsFallback<'_>,
+        options: &MatchOptions,
+    ) -> Vec<RuleMatch> {
+        let matched_rules = self
+            .match_exact_rules(cmd)
+            .filter(|matched_rules| !matched_rules.is_empty())
+            .or_else(|| {
+                options
+                    .resolve_host_executables
+                    .then(|| self.match_host_executable_rules(cmd))
+                    .filter(|matched_rules| !matched_rules.is_empty())
+            })
+            .unwrap_or_default();
+
+        if matched_rules.is_empty()
+            && let Some(heuristics_fallback) = heuristics_fallback
+        {
+            vec![RuleMatch::HeuristicsRuleMatch {
+                command: cmd.to_vec(),
+                decision: heuristics_fallback(cmd),
+            }]
+        } else {
+            matched_rules
+        }
+    }
+
+    fn match_exact_rules(&self, cmd: &[String]) -> Option<Vec<RuleMatch>> {
+        let first = cmd.first()?;
+        Some(
+            self.rules_by_program
+                .get_vec(first)
+                .map(|rules| rules.iter().filter_map(|rule| rule.matches(cmd)).collect())
+                .unwrap_or_default(),
+        )
+    }
+
+    fn match_host_executable_rules(&self, cmd: &[String]) -> Vec<RuleMatch> {
+        let Some(first) = cmd.first() else {
+            return Vec::new();
+        };
+        let Ok(program) = AbsolutePathBuf::try_from(first.clone()) else {
+            return Vec::new();
+        };
+        let Some(basename) = executable_path_lookup_key(program.as_path()) else {
+            return Vec::new();
+        };
+        let Some(rules) = self.rules_by_program.get_vec(&basename) else {
+            return Vec::new();
+        };
+        if let Some(paths) = self.host_executables_by_name.get(&basename)
+            && !paths.iter().any(|path| path == &program)
+        {
+            return Vec::new();
+        }
+
+        let basename_command = std::iter::once(basename)
+            .chain(cmd.iter().skip(1).cloned())
+            .collect::<Vec<_>>();
+        rules
+            .iter()
+            .filter_map(|rule| rule.matches(&basename_command))
+            .map(|rule_match| rule_match.with_resolved_program(&program))
+            .collect()
+    }
+}
+
+fn upsert_domain(entries: &mut Vec<String>, host: &str) {
+    entries.retain(|entry| entry != host);
+    entries.push(host.to_string());
+}
+
+fn render_pattern_token(token: &PatternToken) -> String {
+    match token {
+        PatternToken::Single(value) => value.clone(),
+        PatternToken::Alts(alternatives) => format!("[{}]", alternatives.join("|")),
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Evaluation {
+    pub decision: Decision,
+    #[serde(rename = "matchedRules")]
+    pub matched_rules: Vec<RuleMatch>,
+}
+
+impl Evaluation {
+    pub fn is_match(&self) -> bool {
+        self.matched_rules
+            .iter()
+            .any(|rule_match| !matches!(rule_match, RuleMatch::HeuristicsRuleMatch { .. }))
+    }
+
+    /// Caller is responsible for ensuring that `matched_rules` is non-empty.
+    fn from_matches(matched_rules: Vec<RuleMatch>) -> Self {
+        let decision = matched_rules.iter().map(RuleMatch::decision).max();
+        #[expect(clippy::expect_used)]
+        let decision = decision.expect("invariant failed: matched_rules must be non-empty");
+
+        Self {
+            decision,
+            matched_rules,
+        }
+    }
+}
diff --git a/codex-rs/execpolicy/src/rule.rs b/codex-rs/execpolicy/src/rule.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6642cb1d9c1b67c0fd00a991660a019d50f636fd
--- /dev/null
+++ b/codex-rs/execpolicy/src/rule.rs
@@ -0,0 +1,306 @@
+use crate::decision::Decision;
+use crate::error::Error;
+use crate::error::Result;
+use crate::policy::MatchOptions;
+use crate::policy::Policy;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
+use serde::Serialize;
+use shlex::try_join;
+use std::any::Any;
+use std::fmt::Debug;
+use std::sync::Arc;
+
+/// Matches a single command token, either a fixed string or one of several allowed alternatives.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum PatternToken {
+    Single(String),
+    Alts(Vec<String>),
+}
+
+impl PatternToken {
+    fn matches(&self, token: &str) -> bool {
+        match self {
+            Self::Single(expected) => expected == token,
+            Self::Alts(alternatives) => alternatives.iter().any(|alt| alt == token),
+        }
+    }
+
+    pub fn alternatives(&self) -> &[String] {
+        match self {
+            Self::Single(expected) => std::slice::from_ref(expected),
+            Self::Alts(alternatives) => alternatives,
+        }
+    }
+}
+
+/// Prefix matcher for commands with support for alternative match tokens.
+/// First token is fixed since we key by the first token in policy.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PrefixPattern {
+    pub first: Arc<str>,
+    pub rest: Arc<[PatternToken]>,
+}
+
+impl PrefixPattern {
+    pub fn matches_prefix(&self, cmd: &[String]) -> Option<Vec<String>> {
+        let pattern_length = self.rest.len() + 1;
+        if cmd.len() < pattern_length || cmd[0] != self.first.as_ref() {
+            return None;
+        }
+
+        for (pattern_token, cmd_token) in self.rest.iter().zip(&cmd[1..pattern_length]) {
+            if !pattern_token.matches(cmd_token) {
+                return None;
+            }
+        }
+
+        Some(cmd[..pattern_length].to_vec())
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum RuleMatch {
+    PrefixRuleMatch {
+        #[serde(rename = "matchedPrefix")]
+        matched_prefix: Vec<String>,
+        decision: Decision,
+        #[serde(rename = "resolvedProgram", skip_serializing_if = "Option::is_none")]
+        resolved_program: Option<AbsolutePathBuf>,
+        /// Optional rationale for why this rule exists.
+        ///
+        /// This can be supplied for any decision and may be surfaced in different contexts
+        /// (e.g., prompt reasons or rejection messages).
+        #[serde(skip_serializing_if = "Option::is_none")]
+        justification: Option<String>,
+    },
+    HeuristicsRuleMatch {
+        command: Vec<String>,
+        decision: Decision,
+    },
+}
+
+impl RuleMatch {
+    pub fn decision(&self) -> Decision {
+        match self {
+            Self::PrefixRuleMatch { decision, .. } => *decision,
+            Self::HeuristicsRuleMatch { decision, .. } => *decision,
+        }
+    }
+
+    pub fn with_resolved_program(self, resolved_program: &AbsolutePathBuf) -> Self {
+        match self {
+            Self::PrefixRuleMatch {
+                matched_prefix,
+                decision,
+                justification,
+                ..
+            } => Self::PrefixRuleMatch {
+                matched_prefix,
+                decision,
+                resolved_program: Some(resolved_program.clone()),
+                justification,
+            },
+            other => other,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PrefixRule {
+    pub pattern: PrefixPattern,
+    pub decision: Decision,
+    pub justification: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum NetworkRuleProtocol {
+    Http,
+    Https,
+    Socks5Tcp,
+    Socks5Udp,
+}
+
+impl NetworkRuleProtocol {
+    pub fn parse(raw: &str) -> Result<Self> {
+        match raw {
+            "http" => Ok(Self::Http),
+            "https" | "https_connect" | "http-connect" => Ok(Self::Https),
+            "socks5_tcp" => Ok(Self::Socks5Tcp),
+            "socks5_udp" => Ok(Self::Socks5Udp),
+            other => Err(Error::InvalidRule(format!(
+                "network_rule protocol must be one of http, https, socks5_tcp, socks5_udp (got {other})"
+            ))),
+        }
+    }
+
+    pub fn as_policy_string(self) -> &'static str {
+        match self {
+            Self::Http => "http",
+            Self::Https => "https",
+            Self::Socks5Tcp => "socks5_tcp",
+            Self::Socks5Udp => "socks5_udp",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct NetworkRule {
+    pub host: String,
+    pub protocol: NetworkRuleProtocol,
+    pub decision: Decision,
+    pub justification: Option<String>,
+}
+
+pub(crate) fn normalize_network_rule_host(raw: &str) -> Result<String> {
+    let mut host = raw.trim();
+    if host.is_empty() {
+        return Err(Error::InvalidRule(
+            "network_rule host cannot be empty".to_string(),
+        ));
+    }
+    if host.contains("://") || host.contains('/') || host.contains('?') || host.contains('#') {
+        return Err(Error::InvalidRule(
+            "network_rule host must be a hostname or IP literal (without scheme or path)"
+                .to_string(),
+        ));
+    }
+
+    if let Some(stripped) = host.strip_prefix('[') {
+        let Some((inside, rest)) = stripped.split_once(']') else {
+            return Err(Error::InvalidRule(
+                "network_rule host has an invalid bracketed IPv6 literal".to_string(),
+            ));
+        };
+        let port_ok = rest
+            .strip_prefix(':')
+            .is_some_and(|port| !port.is_empty() && port.chars().all(|c| c.is_ascii_digit()));
+        if !rest.is_empty() && !port_ok {
+            return Err(Error::InvalidRule(format!(
+                "network_rule host contains an unsupported suffix: {raw}"
+            )));
+        }
+        host = inside;
+    } else if host.matches(':').count() == 1
+        && let Some((candidate, port)) = host.rsplit_once(':')
+        && !candidate.is_empty()
+        && !port.is_empty()
+        && port.chars().all(|c| c.is_ascii_digit())
+    {
+        host = candidate;
+    }
+
+    let normalized = host.trim_end_matches('.').trim().to_ascii_lowercase();
+    if normalized.is_empty() {
+        return Err(Error::InvalidRule(
+            "network_rule host cannot be empty".to_string(),
+        ));
+    }
+    if normalized.contains('*') {
+        return Err(Error::InvalidRule(
+            "network_rule host must be a specific host; wildcards are not allowed".to_string(),
+        ));
+    }
+    if normalized.chars().any(char::is_whitespace) {
+        return Err(Error::InvalidRule(
+            "network_rule host cannot contain whitespace".to_string(),
+        ));
+    }
+
+    Ok(normalized)
+}
+
+pub trait Rule: Any + Debug + Send + Sync {
+    fn program(&self) -> &str;
+
+    fn matches(&self, cmd: &[String]) -> Option<RuleMatch>;
+
+    fn as_any(&self) -> &dyn Any;
+}
+
+pub type RuleRef = Arc<dyn Rule>;
+
+impl Rule for PrefixRule {
+    fn program(&self) -> &str {
+        self.pattern.first.as_ref()
+    }
+
+    fn matches(&self, cmd: &[String]) -> Option<RuleMatch> {
+        self.pattern
+            .matches_prefix(cmd)
+            .map(|matched_prefix| RuleMatch::PrefixRuleMatch {
+                matched_prefix,
+                decision: self.decision,
+                resolved_program: None,
+                justification: self.justification.clone(),
+            })
+    }
+
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+}
+
+/// Count how many rules match each provided example and error if any example is unmatched.
+pub(crate) fn validate_match_examples(
+    policy: &Policy,
+    rules: &[RuleRef],
+    matches: &[Vec<String>],
+) -> Result<()> {
+    let mut unmatched_examples = Vec::new();
+    let options = MatchOptions {
+        resolve_host_executables: true,
+    };
+
+    for example in matches {
+        if !policy
+            .matches_for_command_with_options(example, /*heuristics_fallback*/ None, &options)
+            .is_empty()
+        {
+            continue;
+        }
+
+        unmatched_examples.push(
+            try_join(example.iter().map(String::as_str))
+                .unwrap_or_else(|_| "unable to render example".to_string()),
+        );
+    }
+
+    if unmatched_examples.is_empty() {
+        Ok(())
+    } else {
+        Err(Error::ExampleDidNotMatch {
+            rules: rules.iter().map(|rule| format!("{rule:?}")).collect(),
+            examples: unmatched_examples,
+            location: None,
+        })
+    }
+}
+
+/// Ensure that no rule matches any provided negative example.
+pub(crate) fn validate_not_match_examples(
+    policy: &Policy,
+    _rules: &[RuleRef],
+    not_matches: &[Vec<String>],
+) -> Result<()> {
+    let options = MatchOptions {
+        resolve_host_executables: true,
+    };
+
+    for example in not_matches {
+        if let Some(rule) = policy
+            .matches_for_command_with_options(example, /*heuristics_fallback*/ None, &options)
+            .first()
+        {
+            return Err(Error::ExampleDidMatch {
+                rule: format!("{rule:?}"),
+                example: try_join(example.iter().map(String::as_str))
+                    .unwrap_or_else(|_| "unable to render example".to_string()),
+                location: None,
+            });
+        }
+    }
+
+    Ok(())
+}
diff --git a/codex-rs/execpolicy/src/sandbox_migration.rs b/codex-rs/execpolicy/src/sandbox_migration.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a2a57c1c4cf4703399a5eff5cf3693f4a52d25da
--- /dev/null
+++ b/codex-rs/execpolicy/src/sandbox_migration.rs
@@ -0,0 +1,123 @@
+use std::collections::HashSet;
+use std::io;
+use std::io::SeekFrom;
+use std::io::Write as _;
+use std::path::Path;
+use tokio::io::AsyncReadExt;
+use tokio::io::AsyncSeekExt;
+use tokio::io::AsyncWriteExt;
+
+const MIGRATION_MARKER_FILENAME: &str = ".sandbox_migration";
+
+/// removes legacy allow rules that newer codex versions no longer offer.
+///
+/// this migration is intentionally one-shot. once complete, a marker in `codex_home` prevents
+/// policies saved by newer codex versions from being removed on later startups.
+pub async fn prefix_rule_migration(
+    codex_home: &Path,
+    policy_path: &Path,
+    banned_prefixes: &[&[&str]],
+) -> io::Result<()> {
+    let marker_path = codex_home.join(MIGRATION_MARKER_FILENAME);
+    if tokio::fs::try_exists(&marker_path).await? {
+        return Ok(());
+    }
+    clean_rules_file(policy_path, banned_prefixes).await?;
+
+    write_migration_marker(codex_home, &marker_path).await?;
+    Ok(())
+}
+
+// atomically writes the marker after creating codex home when needed.
+async fn write_migration_marker(codex_home: &Path, marker_path: &Path) -> io::Result<()> {
+    tokio::fs::create_dir_all(codex_home).await?;
+    let codex_home = codex_home.to_owned();
+    let marker_path = marker_path.to_owned();
+    tokio::task::spawn_blocking(move || {
+        let mut marker = tempfile::NamedTempFile::new_in(codex_home)?;
+        marker.write_all(b"v1\n")?;
+        match marker.persist_noclobber(marker_path) {
+            Ok(_) => Ok(()),
+            Err(err) if err.error.kind() == io::ErrorKind::AlreadyExists => Ok(()),
+            Err(err) => Err(err.error),
+        }
+    })
+    .await
+    .map_err(io::Error::other)?
+}
+
+// removes exact banned allow rules only when the policy needs changing.
+async fn clean_rules_file(policy_path: &Path, banned_prefixes: &[&[&str]]) -> io::Result<()> {
+    let contents = match tokio::fs::read_to_string(policy_path).await {
+        Ok(contents) => contents,
+        Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(()),
+        Err(err) => return Err(err),
+    };
+    if strip_banned_allow_rules(&contents, banned_prefixes) == contents {
+        return Ok(());
+    }
+
+    let mut file = match tokio::fs::OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(policy_path)
+        .await
+    {
+        Ok(file) => file,
+        Err(err) if err.kind() == io::ErrorKind::NotFound => return Ok(()),
+        Err(err) => return Err(err),
+    };
+
+    let mut contents = String::new();
+    file.read_to_string(&mut contents).await?;
+    let retained = strip_banned_allow_rules(&contents, banned_prefixes);
+    if retained == contents {
+        return Ok(());
+    }
+
+    file.seek(SeekFrom::Start(0)).await?;
+    file.write_all(retained.as_bytes()).await?;
+    file.set_len(retained.len() as u64).await?;
+    Ok(())
+}
+
+// returns the policy text without exact banned allow rules.
+fn strip_banned_allow_rules(contents: &str, banned_prefixes: &[&[&str]]) -> String {
+    let banned_prefixes = banned_prefixes
+        .iter()
+        .map(|prefix| {
+            prefix
+                .iter()
+                .map(|token| token.to_ascii_lowercase())
+                .collect::<Vec<_>>()
+        })
+        .collect::<HashSet<_>>();
+    contents
+        .split_inclusive('\n')
+        .filter(|line| !should_remove_rule(line, &banned_prefixes))
+        .collect()
+}
+
+// checks whether a line is an exact banned allow rule.
+fn should_remove_rule(line: &str, banned_prefixes: &HashSet<Vec<String>>) -> bool {
+    let line = line.strip_suffix('\n').unwrap_or(line);
+    let line = line.strip_suffix('\r').unwrap_or(line);
+    let Some(pattern) = line
+        .strip_prefix("prefix_rule(pattern=")
+        .and_then(|line| line.strip_suffix(r#", decision="allow")"#))
+    else {
+        return false;
+    };
+    let Ok(prefix) = serde_json::from_str::<Vec<String>>(pattern) else {
+        return false;
+    };
+    let prefix = prefix
+        .iter()
+        .map(|token| token.to_ascii_lowercase())
+        .collect::<Vec<_>>();
+    banned_prefixes.contains(&prefix)
+}
+
+#[cfg(test)]
+#[path = "sandbox_migration_tests.rs"]
+mod tests;
diff --git a/codex-rs/execpolicy/src/sandbox_migration_tests.rs b/codex-rs/execpolicy/src/sandbox_migration_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5bb6af6e256cbf1a66d0057503db2e7266a063c7
--- /dev/null
+++ b/codex-rs/execpolicy/src/sandbox_migration_tests.rs
@@ -0,0 +1,58 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use tempfile::tempdir;
+
+#[tokio::test]
+async fn removes_banned_allow_rules_once() {
+    const BANNED_PREFIXES: &[&[&str]] = &[
+        &["cmd.exe", "/k"],
+        &["git"],
+        &["pwsh", "-ec"],
+        &["pwsh", "-f"],
+    ];
+    let codex_home = tempdir().expect("create codex home");
+    let policy_path = codex_home.path().join("rules/default.rules");
+    std::fs::create_dir_all(policy_path.parent().expect("rules directory"))
+        .expect("create rules directory");
+    std::fs::write(
+        &policy_path,
+        r#"prefix_rule(pattern=["git"], decision="allow")
+prefix_rule(pattern=["git"], decision="prompt")
+prefix_rule(pattern=["git"], decision="deny")
+prefix_rule(pattern=["git", "status"], decision="allow")
+prefix_rule(pattern=["CMD.EXE", "/K"], decision="allow")
+prefix_rule(pattern=["PWSH", "-EC"], decision="allow")
+prefix_rule(pattern=["PwSh", "-F"], decision="allow")
+network_rule(host="api.github.com", protocol="https", decision="allow")
+"#,
+    )
+    .expect("write legacy policy");
+
+    prefix_rule_migration(codex_home.path(), &policy_path, BANNED_PREFIXES)
+        .await
+        .expect("run sandbox migration");
+    assert_eq!(
+        std::fs::read_to_string(&policy_path).expect("read migrated policy"),
+        r#"prefix_rule(pattern=["git"], decision="prompt")
+prefix_rule(pattern=["git"], decision="deny")
+prefix_rule(pattern=["git", "status"], decision="allow")
+network_rule(host="api.github.com", protocol="https", decision="allow")
+"#
+    );
+    assert_eq!(
+        std::fs::read_to_string(codex_home.path().join(MIGRATION_MARKER_FILENAME))
+            .expect("read migration marker"),
+        "v1\n"
+    );
+
+    let post_migration_policy = r#"prefix_rule(pattern=["git"], decision="allow")
+"#;
+    std::fs::write(&policy_path, post_migration_policy).expect("write post-migration policy");
+    prefix_rule_migration(codex_home.path(), &policy_path, BANNED_PREFIXES)
+        .await
+        .expect("rerun sandbox migration");
+    assert_eq!(
+        std::fs::read_to_string(&policy_path).expect("read post-migration policy"),
+        post_migration_policy
+    );
+}
diff --git a/codex-rs/execpolicy/tests/basic.rs b/codex-rs/execpolicy/tests/basic.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f6a86adb27423fbc49823407284d57c0e6fc95b1
--- /dev/null
+++ b/codex-rs/execpolicy/tests/basic.rs
@@ -0,0 +1,963 @@
+#![allow(clippy::expect_used)]
+use std::any::Any;
+use std::fs;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use anyhow::Context;
+use anyhow::Result;
+use codex_execpolicy::Decision;
+use codex_execpolicy::Error;
+use codex_execpolicy::Evaluation;
+use codex_execpolicy::MatchOptions;
+use codex_execpolicy::NetworkRuleProtocol;
+use codex_execpolicy::PatternToken;
+use codex_execpolicy::Policy;
+use codex_execpolicy::PolicyParser;
+use codex_execpolicy::PrefixPattern;
+use codex_execpolicy::PrefixRule;
+use codex_execpolicy::RuleMatch;
+use codex_execpolicy::RuleRef;
+use codex_execpolicy::blocking_append_allow_prefix_rule;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use tempfile::tempdir;
+
+fn tokens(cmd: &[&str]) -> Vec<String> {
+    cmd.iter().map(std::string::ToString::to_string).collect()
+}
+
+fn allow_all(_: &[String]) -> Decision {
+    Decision::Allow
+}
+
+fn prompt_all(_: &[String]) -> Decision {
+    Decision::Prompt
+}
+
+fn absolute_path(path: &str) -> AbsolutePathBuf {
+    AbsolutePathBuf::try_from(path.to_string()).expect("path should be absolute")
+}
+
+fn host_absolute_path(segments: &[&str]) -> String {
+    let mut path = if cfg!(windows) {
+        PathBuf::from(r"C:\")
+    } else {
+        PathBuf::from("/")
+    };
+    for segment in segments {
+        path.push(segment);
+    }
+    path.to_string_lossy().into_owned()
+}
+
+fn host_executable_name(name: &str) -> String {
+    if cfg!(windows) {
+        format!("{name}.exe")
+    } else {
+        name.to_string()
+    }
+}
+
+fn starlark_string(value: &str) -> String {
+    value.replace('\\', "\\\\").replace('"', "\\\"")
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+enum RuleSnapshot {
+    Prefix(PrefixRule),
+}
+
+fn rule_snapshots(rules: &[RuleRef]) -> Vec<RuleSnapshot> {
+    rules
+        .iter()
+        .map(|rule| {
+            let rule_any = rule.as_ref() as &dyn Any;
+            if let Some(prefix_rule) = rule_any.downcast_ref::<PrefixRule>() {
+                RuleSnapshot::Prefix(prefix_rule.clone())
+            } else {
+                panic!("unexpected rule type in RuleRef: {rule:?}");
+            }
+        })
+        .collect()
+}
+
+#[test]
+fn append_allow_prefix_rule_dedupes_existing_rule() -> Result<()> {
+    let tmp = tempdir().context("create temp dir")?;
+    let policy_path = tmp.path().join("rules").join("default.rules");
+    let prefix = tokens(&["python3"]);
+
+    blocking_append_allow_prefix_rule(&policy_path, &prefix)?;
+    blocking_append_allow_prefix_rule(&policy_path, &prefix)?;
+
+    let contents = fs::read_to_string(&policy_path).context("read policy")?;
+    assert_eq!(
+        contents,
+        r#"prefix_rule(pattern=["python3"], decision="allow")
+"#
+    );
+    Ok(())
+}
+
+#[test]
+fn network_rules_compile_into_domain_lists() -> Result<()> {
+    let policy_src = r#"
+network_rule(host = "google.com", protocol = "http", decision = "allow")
+network_rule(host = "api.github.com", protocol = "https", decision = "allow")
+network_rule(host = "blocked.example.com", protocol = "https", decision = "deny")
+network_rule(host = "prompt-only.example.com", protocol = "https", decision = "prompt")
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("network.rules", policy_src)?;
+    let policy = parser.build();
+
+    assert_eq!(policy.network_rules().len(), 4);
+    assert_eq!(
+        policy.network_rules()[1].protocol,
+        NetworkRuleProtocol::Https
+    );
+
+    let (allowed, denied) = policy.compiled_network_domains();
+    assert_eq!(
+        allowed,
+        vec!["google.com".to_string(), "api.github.com".to_string()]
+    );
+    assert_eq!(denied, vec!["blocked.example.com".to_string()]);
+    Ok(())
+}
+
+#[test]
+fn network_rule_rejects_wildcard_hosts() {
+    let mut parser = PolicyParser::new();
+    let err = parser
+        .parse(
+            "network.rules",
+            r#"network_rule(host="*", protocol="http", decision="allow")"#,
+        )
+        .expect_err("wildcard network_rule host should fail");
+    assert!(err.to_string().contains("wildcards are not allowed"));
+}
+
+#[test]
+fn basic_match() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["git", "status"],
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+    let cmd = tokens(&["git", "status"]);
+    let evaluation = policy.check(&cmd, &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["git", "status"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn justification_is_attached_to_forbidden_matches() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["rm"],
+    decision = "forbidden",
+    justification = "destructive command",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check(
+        &tokens(&["rm", "-rf", "/some/important/folder"]),
+        &allow_all,
+    );
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Forbidden,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["rm"]),
+                decision: Decision::Forbidden,
+                resolved_program: None,
+                justification: Some("destructive command".to_string()),
+            }],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn justification_can_be_used_with_allow_decision() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["ls"],
+    decision = "allow",
+    justification = "safe and commonly used",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check(&tokens(&["ls", "-l"]), &prompt_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["ls"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: Some("safe and commonly used".to_string()),
+            }],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn justification_cannot_be_empty() {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["ls"],
+    decision = "prompt",
+    justification = "   ",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    let err = parser
+        .parse("test.rules", policy_src)
+        .expect_err("expected parse error");
+    assert!(
+        err.to_string()
+            .contains("invalid rule: justification cannot be empty")
+    );
+}
+
+#[test]
+fn add_prefix_rule_extends_policy() -> Result<()> {
+    let mut policy = Policy::empty();
+    policy.add_prefix_rule(&tokens(&["ls", "-l"]), Decision::Prompt)?;
+
+    let rules = rule_snapshots(policy.rules().get_vec("ls").context("missing ls rules")?);
+    assert_eq!(
+        vec![RuleSnapshot::Prefix(PrefixRule {
+            pattern: PrefixPattern {
+                first: Arc::from("ls"),
+                rest: vec![PatternToken::Single(String::from("-l"))].into(),
+            },
+            decision: Decision::Prompt,
+            justification: None,
+        })],
+        rules
+    );
+
+    let evaluation = policy.check(&tokens(&["ls", "-l", "/some/important/folder"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Prompt,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["ls", "-l"]),
+                decision: Decision::Prompt,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn add_prefix_rule_rejects_empty_prefix() -> Result<()> {
+    let mut policy = Policy::empty();
+    let result = policy.add_prefix_rule(&[], Decision::Allow);
+
+    match result.unwrap_err() {
+        Error::InvalidPattern(message) => assert_eq!(message, "prefix cannot be empty"),
+        other => panic!("expected InvalidPattern(..), got {other:?}"),
+    }
+    Ok(())
+}
+
+#[test]
+fn parses_multiple_policy_files() -> Result<()> {
+    let first_policy = r#"
+prefix_rule(
+    pattern = ["git"],
+    decision = "prompt",
+)
+    "#;
+    let second_policy = r#"
+prefix_rule(
+    pattern = ["git", "commit"],
+    decision = "forbidden",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("first.rules", first_policy)?;
+    parser.parse("second.rules", second_policy)?;
+    let policy = parser.build();
+
+    let git_rules = rule_snapshots(policy.rules().get_vec("git").context("missing git rules")?);
+    assert_eq!(
+        vec![
+            RuleSnapshot::Prefix(PrefixRule {
+                pattern: PrefixPattern {
+                    first: Arc::from("git"),
+                    rest: Vec::<PatternToken>::new().into(),
+                },
+                decision: Decision::Prompt,
+                justification: None,
+            }),
+            RuleSnapshot::Prefix(PrefixRule {
+                pattern: PrefixPattern {
+                    first: Arc::from("git"),
+                    rest: vec![PatternToken::Single("commit".to_string())].into(),
+                },
+                decision: Decision::Forbidden,
+                justification: None,
+            }),
+        ],
+        git_rules
+    );
+
+    let status_eval = policy.check(&tokens(&["git", "status"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Prompt,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["git"]),
+                decision: Decision::Prompt,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        status_eval
+    );
+
+    let commit_eval = policy.check(&tokens(&["git", "commit", "-m", "hi"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Forbidden,
+            matched_rules: vec![
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git"]),
+                    decision: Decision::Prompt,
+                    resolved_program: None,
+                    justification: None,
+                },
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git", "commit"]),
+                    decision: Decision::Forbidden,
+                    resolved_program: None,
+                    justification: None,
+                },
+            ],
+        },
+        commit_eval
+    );
+    Ok(())
+}
+
+#[test]
+fn only_first_token_alias_expands_to_multiple_rules() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = [["bash", "sh"], ["-c", "-l"]],
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let bash_rules = rule_snapshots(
+        policy
+            .rules()
+            .get_vec("bash")
+            .context("missing bash rules")?,
+    );
+    let sh_rules = rule_snapshots(policy.rules().get_vec("sh").context("missing sh rules")?);
+    assert_eq!(
+        vec![RuleSnapshot::Prefix(PrefixRule {
+            pattern: PrefixPattern {
+                first: Arc::from("bash"),
+                rest: vec![PatternToken::Alts(vec!["-c".to_string(), "-l".to_string()])].into(),
+            },
+            decision: Decision::Allow,
+            justification: None,
+        })],
+        bash_rules
+    );
+    assert_eq!(
+        vec![RuleSnapshot::Prefix(PrefixRule {
+            pattern: PrefixPattern {
+                first: Arc::from("sh"),
+                rest: vec![PatternToken::Alts(vec!["-c".to_string(), "-l".to_string()])].into(),
+            },
+            decision: Decision::Allow,
+            justification: None,
+        })],
+        sh_rules
+    );
+
+    let bash_eval = policy.check(&tokens(&["bash", "-c", "echo", "hi"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["bash", "-c"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        bash_eval
+    );
+
+    let sh_eval = policy.check(&tokens(&["sh", "-l", "echo", "hi"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["sh", "-l"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        sh_eval
+    );
+    Ok(())
+}
+
+#[test]
+fn tail_aliases_are_not_cartesian_expanded() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["npm", ["i", "install"], ["--legacy-peer-deps", "--no-save"]],
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let rules = rule_snapshots(policy.rules().get_vec("npm").context("missing npm rules")?);
+    assert_eq!(
+        vec![RuleSnapshot::Prefix(PrefixRule {
+            pattern: PrefixPattern {
+                first: Arc::from("npm"),
+                rest: vec![
+                    PatternToken::Alts(vec!["i".to_string(), "install".to_string()]),
+                    PatternToken::Alts(vec![
+                        "--legacy-peer-deps".to_string(),
+                        "--no-save".to_string(),
+                    ]),
+                ]
+                .into(),
+            },
+            decision: Decision::Allow,
+            justification: None,
+        })],
+        rules
+    );
+
+    let npm_i = policy.check(&tokens(&["npm", "i", "--legacy-peer-deps"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["npm", "i", "--legacy-peer-deps"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        npm_i
+    );
+
+    let npm_install = policy.check(
+        &tokens(&["npm", "install", "--no-save", "leftpad"]),
+        &allow_all,
+    );
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["npm", "install", "--no-save"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        npm_install
+    );
+    Ok(())
+}
+
+#[test]
+fn match_and_not_match_examples_are_enforced() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["git", "status"],
+    match = [["git", "status"], "git status"],
+    not_match = [
+        ["git", "--config", "color.status=always", "status"],
+        "git --config color.status=always status",
+    ],
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+    let match_eval = policy.check(&tokens(&["git", "status"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["git", "status"]),
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        },
+        match_eval
+    );
+
+    let no_match_eval = policy.check(
+        &tokens(&["git", "--config", "color.status=always", "status"]),
+        &allow_all,
+    );
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::HeuristicsRuleMatch {
+                command: tokens(&["git", "--config", "color.status=always", "status",]),
+                decision: Decision::Allow,
+            }],
+        },
+        no_match_eval
+    );
+    Ok(())
+}
+
+#[test]
+fn strictest_decision_wins_across_matches() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["git"],
+    decision = "prompt",
+)
+prefix_rule(
+    pattern = ["git", "commit"],
+    decision = "forbidden",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let commit = policy.check(&tokens(&["git", "commit", "-m", "hi"]), &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Forbidden,
+            matched_rules: vec![
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git"]),
+                    decision: Decision::Prompt,
+                    resolved_program: None,
+                    justification: None,
+                },
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git", "commit"]),
+                    decision: Decision::Forbidden,
+                    resolved_program: None,
+                    justification: None,
+                },
+            ],
+        },
+        commit
+    );
+    Ok(())
+}
+
+#[test]
+fn strictest_decision_across_multiple_commands() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(
+    pattern = ["git"],
+    decision = "prompt",
+)
+prefix_rule(
+    pattern = ["git", "commit"],
+    decision = "forbidden",
+)
+    "#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+
+    let commands = vec![
+        tokens(&["git", "status"]),
+        tokens(&["git", "commit", "-m", "hi"]),
+    ];
+
+    let evaluation = policy.check_multiple(&commands, &allow_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Forbidden,
+            matched_rules: vec![
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git"]),
+                    decision: Decision::Prompt,
+                    resolved_program: None,
+                    justification: None,
+                },
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git"]),
+                    decision: Decision::Prompt,
+                    resolved_program: None,
+                    justification: None,
+                },
+                RuleMatch::PrefixRuleMatch {
+                    matched_prefix: tokens(&["git", "commit"]),
+                    decision: Decision::Forbidden,
+                    resolved_program: None,
+                    justification: None,
+                },
+            ],
+        },
+        evaluation
+    );
+    Ok(())
+}
+
+#[test]
+fn heuristics_match_is_returned_when_no_policy_matches() {
+    let policy = Policy::empty();
+    let command = tokens(&["python"]);
+
+    let evaluation = policy.check(&command, &prompt_all);
+    assert_eq!(
+        Evaluation {
+            decision: Decision::Prompt,
+            matched_rules: vec![RuleMatch::HeuristicsRuleMatch {
+                command,
+                decision: Decision::Prompt,
+            }],
+        },
+        evaluation
+    );
+}
+
+#[test]
+fn parses_host_executable_paths() -> Result<()> {
+    let homebrew_git = host_absolute_path(&["opt", "homebrew", "bin", "git"]);
+    let usr_git = host_absolute_path(&["usr", "bin", "git"]);
+    let homebrew_git_literal = starlark_string(&homebrew_git);
+    let usr_git_literal = starlark_string(&usr_git);
+    let policy_src = format!(
+        r#"
+host_executable(
+    name = "git",
+    paths = [
+        "{homebrew_git_literal}",
+        "{usr_git_literal}",
+        "{usr_git_literal}",
+    ],
+)
+"#
+    );
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", &policy_src)?;
+    let policy = parser.build();
+
+    assert_eq!(
+        policy
+            .host_executables()
+            .get("git")
+            .expect("missing git host executable")
+            .as_ref(),
+        [absolute_path(&homebrew_git), absolute_path(&usr_git)]
+    );
+    Ok(())
+}
+
+#[test]
+fn host_executable_rejects_non_absolute_path() {
+    let policy_src = r#"
+host_executable(name = "git", paths = ["git"])
+"#;
+    let mut parser = PolicyParser::new();
+    let err = parser
+        .parse("test.rules", policy_src)
+        .expect_err("expected parse error");
+    assert!(
+        err.to_string()
+            .contains("host_executable paths must be absolute")
+    );
+}
+
+#[test]
+fn host_executable_rejects_name_with_path_separator() {
+    let git_path = host_absolute_path(&["usr", "bin", "git"]);
+    let git_path_literal = starlark_string(&git_path);
+    let policy_src =
+        format!(r#"host_executable(name = "{git_path_literal}", paths = ["{git_path_literal}"])"#);
+    let mut parser = PolicyParser::new();
+    let err = parser
+        .parse("test.rules", &policy_src)
+        .expect_err("expected parse error");
+    assert!(
+        err.to_string()
+            .contains("host_executable name must be a bare executable name")
+    );
+}
+
+#[test]
+fn host_executable_rejects_path_with_wrong_basename() {
+    let rg_path = host_absolute_path(&["usr", "bin", "rg"]);
+    let rg_path_literal = starlark_string(&rg_path);
+    let policy_src = format!(r#"host_executable(name = "git", paths = ["{rg_path_literal}"])"#);
+    let mut parser = PolicyParser::new();
+    let err = parser
+        .parse("test.rules", &policy_src)
+        .expect_err("expected parse error");
+    assert!(err.to_string().contains("must have basename `git`"));
+}
+
+#[test]
+fn host_executable_last_definition_wins() -> Result<()> {
+    let usr_git = host_absolute_path(&["usr", "bin", "git"]);
+    let homebrew_git = host_absolute_path(&["opt", "homebrew", "bin", "git"]);
+    let usr_git_literal = starlark_string(&usr_git);
+    let homebrew_git_literal = starlark_string(&homebrew_git);
+    let mut parser = PolicyParser::new();
+    parser.parse(
+        "shared.rules",
+        &format!(r#"host_executable(name = "git", paths = ["{usr_git_literal}"])"#),
+    )?;
+    parser.parse(
+        "user.rules",
+        &format!(r#"host_executable(name = "git", paths = ["{homebrew_git_literal}"])"#),
+    )?;
+    let policy = parser.build();
+
+    assert_eq!(
+        policy
+            .host_executables()
+            .get("git")
+            .expect("missing git host executable")
+            .as_ref(),
+        [absolute_path(&homebrew_git)]
+    );
+    Ok(())
+}
+
+#[test]
+fn host_executable_resolution_uses_basename_rule_when_allowed() -> Result<()> {
+    let git_name = host_executable_name("git");
+    let git_path = host_absolute_path(&["usr", "bin", &git_name]);
+    let git_path_literal = starlark_string(&git_path);
+    let policy_src = format!(
+        r#"
+prefix_rule(pattern = ["git", "status"], decision = "prompt")
+host_executable(name = "git", paths = ["{git_path_literal}"])
+"#
+    );
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", &policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check_with_options(
+        &[git_path.clone(), "status".to_string()],
+        &allow_all,
+        &MatchOptions {
+            resolve_host_executables: true,
+        },
+    );
+    assert_eq!(
+        evaluation,
+        Evaluation {
+            decision: Decision::Prompt,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["git", "status"]),
+                decision: Decision::Prompt,
+                resolved_program: Some(absolute_path(&git_path)),
+                justification: None,
+            }],
+        }
+    );
+    Ok(())
+}
+
+#[test]
+fn prefix_rule_examples_honor_host_executable_resolution() -> Result<()> {
+    let allowed_git_name = host_executable_name("git");
+    let allowed_git = host_absolute_path(&["usr", "bin", &allowed_git_name]);
+    let other_git = host_absolute_path(&["opt", "homebrew", "bin", &allowed_git_name]);
+    let allowed_git_literal = starlark_string(&allowed_git);
+    let other_git_literal = starlark_string(&other_git);
+    let policy_src = format!(
+        r#"
+prefix_rule(
+    pattern = ["git", "status"],
+    match = [["{allowed_git_literal}", "status"]],
+    not_match = [["{other_git_literal}", "status"]],
+)
+host_executable(name = "git", paths = ["{allowed_git_literal}"])
+"#
+    );
+
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", &policy_src)?;
+
+    Ok(())
+}
+
+#[test]
+fn host_executable_resolution_respects_explicit_empty_allowlist() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(pattern = ["git"], decision = "prompt")
+host_executable(name = "git", paths = [])
+"#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+    let git_path = host_absolute_path(&["usr", "bin", "git"]);
+
+    let evaluation = policy.check_with_options(
+        &[git_path.clone(), "status".to_string()],
+        &allow_all,
+        &MatchOptions {
+            resolve_host_executables: true,
+        },
+    );
+    assert_eq!(
+        evaluation,
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::HeuristicsRuleMatch {
+                command: vec![git_path, "status".to_string()],
+                decision: Decision::Allow,
+            }],
+        }
+    );
+    Ok(())
+}
+
+#[test]
+fn host_executable_resolution_ignores_path_not_in_allowlist() -> Result<()> {
+    let allowed_git = host_absolute_path(&["usr", "bin", "git"]);
+    let other_git = host_absolute_path(&["opt", "homebrew", "bin", "git"]);
+    let allowed_git_literal = starlark_string(&allowed_git);
+    let policy_src = format!(
+        r#"
+prefix_rule(pattern = ["git"], decision = "prompt")
+host_executable(name = "git", paths = ["{allowed_git_literal}"])
+"#
+    );
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", &policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check_with_options(
+        &[other_git.clone(), "status".to_string()],
+        &allow_all,
+        &MatchOptions {
+            resolve_host_executables: true,
+        },
+    );
+    assert_eq!(
+        evaluation,
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::HeuristicsRuleMatch {
+                command: vec![other_git, "status".to_string()],
+                decision: Decision::Allow,
+            }],
+        }
+    );
+    Ok(())
+}
+
+#[test]
+fn host_executable_resolution_falls_back_without_mapping() -> Result<()> {
+    let policy_src = r#"
+prefix_rule(pattern = ["git"], decision = "prompt")
+"#;
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", policy_src)?;
+    let policy = parser.build();
+    let git_path = host_absolute_path(&["usr", "bin", "git"]);
+
+    let evaluation = policy.check_with_options(
+        &[git_path.clone(), "status".to_string()],
+        &allow_all,
+        &MatchOptions {
+            resolve_host_executables: true,
+        },
+    );
+    assert_eq!(
+        evaluation,
+        Evaluation {
+            decision: Decision::Prompt,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: tokens(&["git"]),
+                decision: Decision::Prompt,
+                resolved_program: Some(absolute_path(&git_path)),
+                justification: None,
+            }],
+        }
+    );
+    Ok(())
+}
+
+#[test]
+fn host_executable_resolution_does_not_override_exact_match() -> Result<()> {
+    let git_path = host_absolute_path(&["usr", "bin", "git"]);
+    let git_path_literal = starlark_string(&git_path);
+    let policy_src = format!(
+        r#"
+prefix_rule(pattern = ["{git_path_literal}"], decision = "allow")
+prefix_rule(pattern = ["git"], decision = "prompt")
+host_executable(name = "git", paths = ["{git_path_literal}"])
+"#
+    );
+    let mut parser = PolicyParser::new();
+    parser.parse("test.rules", &policy_src)?;
+    let policy = parser.build();
+
+    let evaluation = policy.check_with_options(
+        &[git_path.clone(), "status".to_string()],
+        &allow_all,
+        &MatchOptions {
+            resolve_host_executables: true,
+        },
+    );
+    assert_eq!(
+        evaluation,
+        Evaluation {
+            decision: Decision::Allow,
+            matched_rules: vec![RuleMatch::PrefixRuleMatch {
+                matched_prefix: vec![git_path],
+                decision: Decision::Allow,
+                resolved_program: None,
+                justification: None,
+            }],
+        }
+    );
+    Ok(())
+}
diff --git a/codex-rs/file-system/src/find_up.rs b/codex-rs/file-system/src/find_up.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a5a071d2843ccd19f11a73aed3af54e676b9e876
--- /dev/null
+++ b/codex-rs/file-system/src/find_up.rs
@@ -0,0 +1,126 @@
+use crate::ExecutorFileSystem;
+use crate::FileSystemResult;
+use crate::FileSystemSandboxContext;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path_uri::PathUri;
+use futures::StreamExt;
+use std::io;
+
+// Keep enough ordinary metadata calls in flight to cover typical ancestor chains in one remote
+// round trip, while leaving room for independent startup discovery to run at the same time.
+const MAX_CONCURRENT_PROBES: usize = 256;
+
+/// Controls how an upward marker search handles metadata errors other than `NotFound`.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum FindUpErrorPolicy {
+    /// Return the first error in lexical search order.
+    Propagate,
+    /// Treat errors as missing markers and continue searching.
+    Ignore,
+}
+
+/// Finds the nearest ancestor containing one of the provided marker names.
+///
+/// Marker paths are probed in lexical order from `start` toward the filesystem root. A bounded
+/// number of ordinary metadata calls are kept in flight so remote filesystems can pipeline them
+/// without requiring a batch protocol operation.
+pub async fn find_nearest_ancestor_with_markers(
+    file_system: &dyn ExecutorFileSystem,
+    start: &PathUri,
+    markers: Vec<String>,
+    error_policy: FindUpErrorPolicy,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> FileSystemResult<Option<PathUri>> {
+    find_nearest_ancestor(
+        file_system,
+        start.clone(),
+        markers,
+        PathUri::parent,
+        |ancestor, marker| {
+            ancestor
+                .join(marker)
+                .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))
+        },
+        error_policy,
+        sandbox,
+    )
+    .await
+}
+
+/// Finds the nearest native ancestor containing one of the provided marker names.
+///
+/// Ancestors and marker paths remain native until each complete probe is converted to a URI. This
+/// preserves paths that require an opaque [`PathUri`] fallback.
+pub async fn find_nearest_native_ancestor_with_markers(
+    file_system: &dyn ExecutorFileSystem,
+    start: &AbsolutePathBuf,
+    markers: Vec<String>,
+    error_policy: FindUpErrorPolicy,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> FileSystemResult<Option<AbsolutePathBuf>> {
+    find_nearest_ancestor(
+        file_system,
+        start.clone(),
+        markers,
+        AbsolutePathBuf::parent,
+        |ancestor, marker| Ok(PathUri::from_abs_path(&ancestor.join(marker))),
+        error_policy,
+        sandbox,
+    )
+    .await
+}
+
+async fn find_nearest_ancestor<P, Parent, MarkerPath>(
+    file_system: &dyn ExecutorFileSystem,
+    start: P,
+    markers: Vec<String>,
+    parent: Parent,
+    mut marker_path: MarkerPath,
+    error_policy: FindUpErrorPolicy,
+    sandbox: Option<&FileSystemSandboxContext>,
+) -> FileSystemResult<Option<P>>
+where
+    P: Clone + Send,
+    Parent: FnMut(&P) -> Option<P> + Send,
+    MarkerPath: FnMut(&P, &str) -> FileSystemResult<PathUri> + Send,
+{
+    let mut ancestors = std::iter::successors(Some(start), parent);
+    let mut ancestor = ancestors.next();
+    let mut marker_index = 0;
+    let probes = std::iter::from_fn(move || {
+        let current_ancestor = ancestor.clone()?;
+        let marker = markers.get(marker_index)?;
+        let marker_path = marker_path(&current_ancestor, marker);
+
+        marker_index += 1;
+        if marker_index == markers.len() {
+            marker_index = 0;
+            ancestor = ancestors.next();
+        }
+
+        Some((current_ancestor, marker_path))
+    });
+    let mut results = futures::stream::iter(probes)
+        .map(|(ancestor, marker_path)| async move {
+            let marker_path = marker_path?;
+            match file_system
+                .get_metadata(&marker_path, crate::GetMetadataOptions::default(), sandbox)
+                .await
+            {
+                Ok(_) => Ok(Some(ancestor)),
+                Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(None),
+                Err(err) => match error_policy {
+                    FindUpErrorPolicy::Propagate => Err(err),
+                    FindUpErrorPolicy::Ignore => Ok(None),
+                },
+            }
+        })
+        .buffered(MAX_CONCURRENT_PROBES);
+
+    while let Some(result) = results.next().await {
+        if let Some(ancestor) = result? {
+            return Ok(Some(ancestor));
+        }
+    }
+    Ok(None)
+}
diff --git a/codex-rs/file-system/src/lib.rs b/codex-rs/file-system/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ba825c5ce8119d254f6fd4319073d6b858c0301d
--- /dev/null
+++ b/codex-rs/file-system/src/lib.rs
@@ -0,0 +1,592 @@
+mod find_up;
+
+use bytes::Bytes;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::config_types::WindowsSandboxProxySettingsMode;
+use codex_protocol::models::ManagedFileSystemPermissions;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::models::SandboxEnforcement;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxEntryMissingPathBehavior;
+use codex_protocol::permissions::FileSystemSandboxKind;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::FileSystemSandboxPolicyContext;
+use codex_protocol::permissions::FileSystemSpecialPath;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_utils_path_uri::PathUri;
+pub use find_up::FindUpErrorPolicy;
+pub use find_up::find_nearest_ancestor_with_markers;
+pub use find_up::find_nearest_native_ancestor_with_markers;
+use futures::Stream;
+use serde::Deserialize;
+use serde::Serialize;
+use std::future::Future;
+use std::io;
+use std::num::NonZeroUsize;
+use std::path::Path;
+use std::pin::Pin;
+use std::task::Context;
+use std::task::Poll;
+
+/// Maximum chunk size returned by [`ExecutorFileSystem::read_file_stream`].
+pub const FILE_READ_CHUNK_SIZE: usize = 1024 * 1024;
+/// Maximum accepted directory depth for a filesystem walk.
+pub const MAX_WALK_DEPTH: usize = 64;
+/// Maximum accepted directory count, including the walk root.
+pub const MAX_WALK_DIRECTORIES: usize = 10_000;
+/// Maximum accepted number of directory entries to examine.
+pub const MAX_WALK_ENTRIES: usize = 50_000;
+/// Maximum estimated size of a walk response.
+pub const MAX_WALK_RESPONSE_BYTES: usize = 4 * 1024 * 1024;
+/// Per-entry or per-error overhead charged to the walk response budget.
+pub const WALK_RESPONSE_ITEM_OVERHEAD_BYTES: usize = 64;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ReadFileOptions {
+    pub follow_symlinks: bool,
+}
+
+impl Default for ReadFileOptions {
+    fn default() -> Self {
+        Self {
+            follow_symlinks: true,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct WriteFileOptions {
+    pub follow_symlinks: bool,
+}
+
+impl Default for WriteFileOptions {
+    fn default() -> Self {
+        Self {
+            follow_symlinks: true,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct GetMetadataOptions {
+    pub follow_symlinks: bool,
+}
+
+impl Default for GetMetadataOptions {
+    fn default() -> Self {
+        Self {
+            follow_symlinks: true,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct CreateDirectoryOptions {
+    pub recursive: bool,
+    pub follow_symlinks: bool,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct RemoveOptions {
+    pub recursive: bool,
+    pub force: bool,
+    pub follow_symlinks: bool,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct CopyOptions {
+    pub recursive: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct FileMetadata {
+    pub is_directory: bool,
+    pub is_file: bool,
+    pub is_symlink: bool,
+    /// Size in bytes.
+    pub size: u64,
+    pub created_at_ms: i64,
+    pub modified_at_ms: i64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ReadDirectoryEntry {
+    pub file_name: String,
+    pub is_directory: bool,
+    pub is_file: bool,
+}
+
+/// Bounds for a recursive filesystem walk.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WalkOptions {
+    /// Maximum directory depth below the root that may be traversed.
+    pub max_depth: usize,
+    /// Maximum number of directories that may be traversed, including the root.
+    pub max_directories: usize,
+    /// Maximum number of directory entries that may be examined.
+    pub max_entries: usize,
+    /// Whether directory symlinks should be followed.
+    pub follow_directory_symlinks: bool,
+    /// Whether directories whose names start with `.` should be returned but not traversed.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub prune_hidden_directories: bool,
+}
+
+/// Type of a filesystem entry returned by a walk.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub enum WalkEntryKind {
+    Directory,
+    File,
+}
+
+/// One entry returned by a walk.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WalkEntry {
+    pub path: PathUri,
+    pub kind: WalkEntryKind,
+}
+
+/// A descendant that could not be inspected during a walk.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WalkError {
+    pub path: PathUri,
+    pub message: String,
+}
+
+/// Entries and recoverable errors collected by a bounded walk.
+#[derive(Clone, Debug, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WalkOutcome {
+    pub entries: Vec<WalkEntry>,
+    pub errors: Vec<WalkError>,
+    pub truncated: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ExecFileSystemPath {
+    Path { path: PathUri },
+    GlobPattern { pattern: String },
+    Special { value: FileSystemSpecialPath },
+}
+
+impl From<FileSystemPath> for ExecFileSystemPath {
+    fn from(value: FileSystemPath) -> Self {
+        match value {
+            FileSystemPath::Path { path } => Self::Path { path },
+            FileSystemPath::GlobPattern { pattern } => Self::GlobPattern { pattern },
+            FileSystemPath::Special { value } => Self::Special { value },
+        }
+    }
+}
+
+impl TryFrom<ExecFileSystemPath> for FileSystemPath {
+    type Error = io::Error;
+
+    fn try_from(value: ExecFileSystemPath) -> Result<Self, Self::Error> {
+        Ok(match value {
+            ExecFileSystemPath::Path { path } => {
+                path.to_abs_path()?;
+                Self::Path { path }
+            }
+            ExecFileSystemPath::GlobPattern { pattern } => Self::GlobPattern { pattern },
+            ExecFileSystemPath::Special { value } => Self::Special { value },
+        })
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+pub struct ExecFileSystemSandboxEntry {
+    pub path: ExecFileSystemPath,
+    pub access: FileSystemAccessMode,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub missing_path_behavior: Option<FileSystemSandboxEntryMissingPathBehavior>,
+}
+
+impl From<FileSystemSandboxEntry> for ExecFileSystemSandboxEntry {
+    fn from(value: FileSystemSandboxEntry) -> Self {
+        Self {
+            path: value.path.into(),
+            access: value.access,
+            missing_path_behavior: value.missing_path_behavior,
+        }
+    }
+}
+
+impl TryFrom<ExecFileSystemSandboxEntry> for FileSystemSandboxEntry {
+    type Error = io::Error;
+
+    fn try_from(value: ExecFileSystemSandboxEntry) -> Result<Self, Self::Error> {
+        Ok(Self {
+            path: value.path.try_into()?,
+            access: value.access,
+            missing_path_behavior: value.missing_path_behavior,
+        })
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ExecManagedFileSystemPermissions {
+    Restricted {
+        entries: Vec<ExecFileSystemSandboxEntry>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        glob_scan_max_depth: Option<NonZeroUsize>,
+    },
+    Unrestricted,
+}
+
+impl From<ManagedFileSystemPermissions> for ExecManagedFileSystemPermissions {
+    fn from(value: ManagedFileSystemPermissions) -> Self {
+        match value {
+            ManagedFileSystemPermissions::Restricted {
+                entries,
+                glob_scan_max_depth,
+            } => Self::Restricted {
+                entries: entries.into_iter().map(Into::into).collect(),
+                glob_scan_max_depth,
+            },
+            ManagedFileSystemPermissions::Unrestricted => Self::Unrestricted,
+        }
+    }
+}
+
+impl TryFrom<ExecManagedFileSystemPermissions> for ManagedFileSystemPermissions {
+    type Error = io::Error;
+
+    fn try_from(value: ExecManagedFileSystemPermissions) -> Result<Self, Self::Error> {
+        Ok(match value {
+            ExecManagedFileSystemPermissions::Restricted {
+                entries,
+                glob_scan_max_depth,
+            } => Self::Restricted {
+                entries: entries
+                    .into_iter()
+                    .map(TryInto::try_into)
+                    .collect::<io::Result<_>>()?,
+                glob_scan_max_depth,
+            },
+            ExecManagedFileSystemPermissions::Unrestricted => Self::Unrestricted,
+        })
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ExecPermissionProfile {
+    Managed {
+        file_system: ExecManagedFileSystemPermissions,
+        network: NetworkSandboxPolicy,
+    },
+    Disabled,
+    External {
+        network: NetworkSandboxPolicy,
+    },
+}
+
+impl From<PermissionProfile> for ExecPermissionProfile {
+    fn from(value: PermissionProfile) -> Self {
+        match value {
+            PermissionProfile::Managed {
+                file_system,
+                network,
+            } => Self::Managed {
+                file_system: file_system.into(),
+                network,
+            },
+            PermissionProfile::Disabled => Self::Disabled,
+            PermissionProfile::External { network } => Self::External { network },
+        }
+    }
+}
+
+impl TryFrom<ExecPermissionProfile> for PermissionProfile {
+    type Error = io::Error;
+
+    fn try_from(value: ExecPermissionProfile) -> Result<Self, Self::Error> {
+        Ok(match value {
+            ExecPermissionProfile::Managed {
+                file_system,
+                network,
+            } => Self::Managed {
+                file_system: file_system.try_into()?,
+                network,
+            },
+            ExecPermissionProfile::Disabled => Self::Disabled,
+            ExecPermissionProfile::External { network } => Self::External { network },
+        })
+    }
+}
+
+/// Windows sandbox choice encoded in executor RPCs.
+///
+/// The serialized field retains its legacy `windowsSandboxLevel` name for compatibility, but MXC
+/// is a sandbox implementation rather than a RestrictedToken level.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum WindowsSandboxSelection {
+    #[default]
+    Disabled,
+    RestrictedToken,
+    Elevated,
+    Mxc,
+}
+
+impl From<WindowsSandboxLevel> for WindowsSandboxSelection {
+    fn from(level: WindowsSandboxLevel) -> Self {
+        match level {
+            WindowsSandboxLevel::Disabled => Self::Disabled,
+            WindowsSandboxLevel::RestrictedToken => Self::RestrictedToken,
+            WindowsSandboxLevel::Elevated => Self::Elevated,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct FileSystemSandboxContext {
+    pub permissions: ExecPermissionProfile,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cwd: Option<PathUri>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub workspace_roots: Vec<PathUri>,
+    /// Executor-local user home used to resolve home-relative policy paths.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub user_home_dir: Option<PathUri>,
+    /// Executor-local default directories used to resolve `:tmpdir` policy entries.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub temporary_directories: Option<Vec<PathUri>>,
+    #[serde(rename = "windowsSandboxLevel")]
+    pub windows_sandbox_selection: WindowsSandboxSelection,
+    #[serde(default)]
+    pub windows_sandbox_private_desktop: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub windows_sandbox_proxy_settings_mode: Option<WindowsSandboxProxySettingsMode>,
+    #[serde(default)]
+    pub use_legacy_landlock: bool,
+}
+
+impl FileSystemSandboxContext {
+    pub fn from_legacy_sandbox_policy(
+        sandbox_policy: SandboxPolicy,
+        cwd: PathUri,
+    ) -> io::Result<Self> {
+        // Legacy policy projection materializes native roots, so convert at the receiving-host
+        // boundary while retaining the URI in the resulting sandbox context.
+        let native_cwd = cwd.to_abs_path()?;
+        let file_system_sandbox_policy =
+            FileSystemSandboxPolicy::from_legacy_sandbox_policy_for_cwd(
+                &sandbox_policy,
+                &native_cwd,
+            );
+        let permissions = PermissionProfile::from_runtime_permissions_with_enforcement(
+            SandboxEnforcement::from_legacy_sandbox_policy(&sandbox_policy),
+            &file_system_sandbox_policy,
+            NetworkSandboxPolicy::from(&sandbox_policy),
+        );
+        Ok(Self::from_permission_profile_with_cwd(permissions, cwd))
+    }
+
+    pub fn from_permission_profile(permissions: PermissionProfile) -> Self {
+        Self::from_permissions_and_cwd(permissions, /*cwd*/ None)
+    }
+
+    pub fn from_permission_profile_with_cwd(permissions: PermissionProfile, cwd: PathUri) -> Self {
+        Self::from_permissions_and_cwd(permissions, Some(cwd))
+    }
+
+    fn from_permissions_and_cwd(permissions: PermissionProfile, cwd: Option<PathUri>) -> Self {
+        let workspace_roots = cwd.iter().cloned().collect();
+        Self {
+            permissions: permissions.into(),
+            cwd,
+            workspace_roots,
+            user_home_dir: None,
+            temporary_directories: None,
+            windows_sandbox_selection: WindowsSandboxSelection::Disabled,
+            windows_sandbox_private_desktop: false,
+            windows_sandbox_proxy_settings_mode: None,
+            use_legacy_landlock: false,
+        }
+    }
+
+    pub fn should_run_in_sandbox(&self) -> bool {
+        let Ok(permissions) = PermissionProfile::try_from(self.permissions.clone()) else {
+            // A sandbox context for another host must not select the unsandboxed filesystem.
+            return true;
+        };
+        let file_system_policy = permissions.file_system_sandbox_policy();
+        matches!(file_system_policy.kind, FileSystemSandboxKind::Restricted)
+            && !file_system_policy.has_full_disk_write_access()
+    }
+
+    /// Whether this context selects either supported Windows sandbox implementation.
+    pub fn windows_sandbox_is_requested(&self) -> bool {
+        self.windows_sandbox_selection != WindowsSandboxSelection::Disabled
+    }
+
+    /// Borrows the executor-owned paths needed to interpret filesystem policy entries.
+    ///
+    /// Returns `None` after the cwd has been omitted from a transport context.
+    pub fn policy_context(&self) -> Option<FileSystemSandboxPolicyContext<'_>> {
+        Some(FileSystemSandboxPolicyContext {
+            cwd: self.cwd.as_ref()?,
+            workspace_roots: &self.workspace_roots,
+            user_home_dir: self.user_home_dir.as_ref(),
+            temporary_directories: self.temporary_directories.as_deref(),
+        })
+    }
+
+    pub fn has_cwd_dependent_permissions(&self) -> bool {
+        match &self.permissions {
+            ExecPermissionProfile::Managed {
+                file_system: ExecManagedFileSystemPermissions::Restricted { entries, .. },
+                ..
+            } => entries.iter().any(|entry| match &entry.path {
+                ExecFileSystemPath::GlobPattern { pattern } => !Path::new(pattern).is_absolute(),
+                ExecFileSystemPath::Special {
+                    value: FileSystemSpecialPath::ProjectRoots { .. },
+                } => true,
+                ExecFileSystemPath::Path { .. } | ExecFileSystemPath::Special { .. } => false,
+            }),
+            ExecPermissionProfile::Managed {
+                file_system: ExecManagedFileSystemPermissions::Unrestricted,
+                ..
+            }
+            | ExecPermissionProfile::Disabled
+            | ExecPermissionProfile::External { .. } => false,
+        }
+    }
+
+    pub fn drop_cwd_if_unused(mut self) -> Self {
+        if !self.has_cwd_dependent_permissions() {
+            self.cwd = None;
+            self.workspace_roots.clear();
+        }
+        self
+    }
+}
+
+pub type FileSystemResult<T> = io::Result<T>;
+
+/// Future returned by [`ExecutorFileSystem`] operations.
+pub type ExecutorFileSystemFuture<'a, T> =
+    Pin<Box<dyn Future<Output = FileSystemResult<T>> + Send + 'a>>;
+
+/// Stream of immutable chunks read from an [`ExecutorFileSystem`].
+pub struct FileSystemReadStream {
+    inner: Pin<Box<dyn Stream<Item = FileSystemResult<Bytes>> + Send + 'static>>,
+}
+
+impl FileSystemReadStream {
+    /// Wraps a filesystem byte stream.
+    pub fn new(stream: impl Stream<Item = FileSystemResult<Bytes>> + Send + 'static) -> Self {
+        Self {
+            inner: Box::pin(stream),
+        }
+    }
+}
+
+impl Stream for FileSystemReadStream {
+    type Item = FileSystemResult<Bytes>;
+
+    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
+        self.inner.as_mut().poll_next(cx)
+    }
+}
+
+/// Abstract filesystem access used by components that may operate locally or via
+/// a remote environment.
+pub trait ExecutorFileSystem: Send + Sync {
+    /// Resolves a path within this filesystem.
+    fn canonicalize<'a>(
+        &'a self,
+        path: &'a PathUri,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, PathUri>;
+
+    fn read_file<'a>(
+        &'a self,
+        path: &'a PathUri,
+        options: ReadFileOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, Vec<u8>>;
+
+    /// Reads a file as a stream of chunks no larger than [`FILE_READ_CHUNK_SIZE`].
+    fn read_file_stream<'a>(
+        &'a self,
+        path: &'a PathUri,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, FileSystemReadStream>;
+
+    /// Reads a file and decodes it as UTF-8 text.
+    fn read_file_text<'a>(
+        &'a self,
+        path: &'a PathUri,
+        options: ReadFileOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, String> {
+        Box::pin(async move {
+            let bytes = self.read_file(path, options, sandbox).await?;
+            String::from_utf8(bytes).map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))
+        })
+    }
+
+    fn write_file<'a>(
+        &'a self,
+        path: &'a PathUri,
+        contents: Vec<u8>,
+        options: WriteFileOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, ()>;
+
+    fn create_directory<'a>(
+        &'a self,
+        path: &'a PathUri,
+        create_directory_options: CreateDirectoryOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, ()>;
+
+    fn get_metadata<'a>(
+        &'a self,
+        path: &'a PathUri,
+        options: GetMetadataOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, FileMetadata>;
+
+    fn read_directory<'a>(
+        &'a self,
+        path: &'a PathUri,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, Vec<ReadDirectoryEntry>>;
+
+    /// Recursively lists descendants, optionally following directory symlinks.
+    fn walk<'a>(
+        &'a self,
+        path: &'a PathUri,
+        options: WalkOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, WalkOutcome>;
+
+    fn remove<'a>(
+        &'a self,
+        path: &'a PathUri,
+        remove_options: RemoveOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, ()>;
+
+    fn copy<'a>(
+        &'a self,
+        source_path: &'a PathUri,
+        destination_path: &'a PathUri,
+        copy_options: CopyOptions,
+        sandbox: Option<&'a FileSystemSandboxContext>,
+    ) -> ExecutorFileSystemFuture<'a, ()>;
+}
diff --git a/codex-rs/history/src/guardian_history.rs b/codex-rs/history/src/guardian_history.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1a94fe8b61ab255f739cdc59510de5a13b43f033
--- /dev/null
+++ b/codex-rs/history/src/guardian_history.rs
@@ -0,0 +1,21 @@
+//! Model-invisible checkpoint of the host's bounded Guardian transcript.
+
+use codex_protocol::models::ResponseItem;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+
+/// Original review evidence, separate from the compacted model conversation.
+/// Hosts enforce transcript retention limits both when saving and restoring it.
+#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+#[serde(transparent)]
+pub struct GuardianHistoryCheckpoint(pub Vec<ResponseItem>);
+
+impl std::fmt::Debug for GuardianHistoryCheckpoint {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("GuardianHistoryCheckpoint")
+            .field("items", &self.0.len())
+            .finish()
+    }
+}
diff --git a/codex-rs/history/src/lib.rs b/codex-rs/history/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2be359013bc89c92e881c8918dfb26f723980525
--- /dev/null
+++ b/codex-rs/history/src/lib.rs
@@ -0,0 +1,517 @@
+//! Model-history and persisted-rollout domain types.
+
+use std::borrow::Borrow;
+use std::ops::Deref;
+use std::ops::DerefMut;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use codex_protocol::ThreadId;
+use codex_protocol::capabilities::SelectedCapabilityRoot;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
+use codex_protocol::mcp::McpResourceOriginCheckpoint;
+use codex_protocol::models::BaseInstructions;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::InterAgentCommunication;
+use codex_protocol::protocol::MultiAgentVersion;
+use codex_protocol::protocol::SessionMeta;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadSource;
+use codex_protocol::protocol::TokenUsageRecord;
+use codex_protocol::protocol::TurnContextItem;
+use codex_protocol::protocol::WorldStateItem;
+use codex_protocol::realtime::RealtimeItem;
+use codex_protocol::security_risk::SecurityRiskScore;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Deserializer;
+use serde::Serialize;
+use serde::Serializer;
+use serde::de::Error as _;
+
+/// A model-history item with room for history-only metadata.
+///
+/// Persistence keeps the response item intact and stores its metadata separately.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ResponseItemEnvelope {
+    pub item: ResponseItem,
+    pub metadata: Option<CodexHarnessMetadata>,
+}
+
+/// Metadata owned by the Codex harness and persisted with a response item.
+///
+#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)]
+pub struct CodexHarnessMetadata {
+    /// Whether a developer message was supplied by an app-server client.
+    #[serde(default)]
+    pub client_authored: bool,
+
+    /// The originating history budget, including any tool-specific allowance.
+    /// Measured in tokens and reused when replaying persisted history.
+    #[serde(
+        default,
+        rename = "fallback_token_limit_override",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub history_truncation_token_limit: Option<usize>,
+
+    /// Whether a response configuration update was created by the Codex harness itself.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub harness_authored_configuration: bool,
+
+    /// Producer compatibility for an opaque compaction item, never the currently selected model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub compaction_model_hash: Option<String>,
+
+    /// Thread acceptance order, independent of when queued user input reaches model history.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub user_input_order: Option<u64>,
+
+    /// Copied parent context stays model-visible but must not become child-local authorization.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub inherited_user_message: bool,
+}
+
+impl ResponseItemEnvelope {
+    /// Wraps a raw Responses API item for persisted history.
+    pub fn new(item: ResponseItem) -> Self {
+        Self {
+            item,
+            metadata: None,
+        }
+    }
+
+    /// Unwraps the raw Responses API item.
+    pub fn into_item(self) -> ResponseItem {
+        self.item
+    }
+}
+
+impl From<ResponseItem> for ResponseItemEnvelope {
+    fn from(item: ResponseItem) -> Self {
+        Self::new(item)
+    }
+}
+
+impl Deref for ResponseItemEnvelope {
+    type Target = ResponseItem;
+
+    fn deref(&self) -> &Self::Target {
+        &self.item
+    }
+}
+
+impl DerefMut for ResponseItemEnvelope {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.item
+    }
+}
+
+impl Borrow<ResponseItem> for ResponseItemEnvelope {
+    fn borrow(&self) -> &ResponseItem {
+        &self.item
+    }
+}
+
+/// Persisted rollout item used by core history and rollout storage.
+#[derive(Debug, Clone)]
+pub enum RolloutItem {
+    SessionMeta(SessionMetaLine),
+    ResponseItem(ResponseItemEnvelope),
+    InterAgentCommunication(InterAgentCommunication),
+    InterAgentCommunicationMetadata {
+        trigger_turn: bool,
+    },
+    Compacted(CompactedItem),
+    TurnContext(TurnContextItem),
+    TokenUsageRecord(TokenUsageRecord),
+    WorldState(WorldStateItem),
+    SecurityRiskScore(SecurityRiskScore),
+    RetainedContext(RetainedContextEvent),
+    EventMsg(EventMsg),
+    /// Sparse, model-invisible facts used to reconstruct realtime presentation.
+    RealtimeItem(RealtimeItem),
+}
+
+impl Serialize for RolloutItem {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        rollout_payload::RolloutItemWire::from(self).serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for RolloutItem {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        rollout_payload::RolloutItemWire::deserialize(deserializer).map(Into::into)
+    }
+}
+
+impl JsonSchema for RolloutItem {
+    fn schema_name() -> String {
+        "RolloutItem".to_string()
+    }
+
+    fn schema_id() -> std::borrow::Cow<'static, str> {
+        std::borrow::Cow::Borrowed(concat!(module_path!(), "::RolloutItem"))
+    }
+
+    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::schema::Schema {
+        rollout_payload::RolloutItemWire::json_schema(generator)
+    }
+}
+
+mod guardian_history;
+mod reconciled_retained_context;
+mod retained_context;
+
+pub use reconciled_retained_context::ReconciledRetainedContext;
+pub use retained_context::RetainedContext;
+pub use retained_context::RetainedContextEntry;
+pub use retained_context::RetainedContextEvent;
+pub use retained_context::RetainedContextOrder;
+pub use retained_context::RetainedInputSource;
+pub use retained_context::RetainedUserMessage;
+pub use retained_context::VerifiedAnswer;
+pub use retained_context::VerifiedQuestionAnswer;
+mod rollout_payload;
+
+pub use guardian_history::GuardianHistoryCheckpoint;
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct CompactedItem {
+    pub message: String,
+    pub replacement_history: Option<Vec<ResponseItemEnvelope>>,
+    pub guardian_history: Option<GuardianHistoryCheckpoint>,
+    pub retained_context: Option<RetainedContext>,
+    pub mcp_resource_origins: Option<McpResourceOriginCheckpoint>,
+    pub window_number: Option<u64>,
+    pub first_window_id: Option<String>,
+    pub previous_window_id: Option<String>,
+    pub window_id: Option<String>,
+    /// Responses API ID for the model-backed compaction request, when one exists.
+    pub compaction_response_id: Option<String>,
+    /// Snapshot of the latest reachable token usage record when this compaction was written.
+    ///
+    /// `thread/resume` can restore token usage totals from this field without scanning arbitrarily
+    /// far past the compaction.
+    pub latest_token_usage_record: Option<TokenUsageRecord>,
+}
+
+impl Serialize for CompactedItem {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        rollout_payload::CompactedItemWire::from(self).serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for CompactedItem {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        rollout_payload::CompactedItemWire::deserialize(deserializer)?
+            .try_into()
+            .map_err(D::Error::custom)
+    }
+}
+
+impl JsonSchema for CompactedItem {
+    fn schema_name() -> String {
+        "CompactedItem".to_string()
+    }
+
+    fn schema_id() -> std::borrow::Cow<'static, str> {
+        std::borrow::Cow::Borrowed(concat!(module_path!(), "::CompactedItem"))
+    }
+
+    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::schema::Schema {
+        rollout_payload::CompactedItemWire::json_schema(generator)
+    }
+}
+
+impl From<CompactedItem> for ResponseItem {
+    fn from(value: CompactedItem) -> Self {
+        ResponseItem::Message {
+            id: None,
+            role: "assistant".to_string(),
+            content: vec![ContentItem::OutputText {
+                text: value.message,
+            }],
+            phase: None,
+            internal_chat_message_metadata_passthrough: None,
+        }
+    }
+}
+
+/// One persisted rollout JSONL record.
+///
+/// This intentionally does not implement Deserialize: JSONL readers must use
+/// codex_rollout's canonical parser so nested decimal values survive the flattened envelope.
+#[derive(Serialize, Clone, JsonSchema)]
+pub struct RolloutLine {
+    pub timestamp: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ordinal: Option<u64>,
+    #[serde(flatten)]
+    pub item: RolloutItem,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct ResumedHistory {
+    pub conversation_id: ThreadId,
+    pub history: Arc<Vec<RolloutItem>>,
+    pub rollout_path: Option<PathBuf>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub enum InitialHistory {
+    New,
+    Cleared,
+    Resumed(ResumedHistory),
+    Forked(Vec<RolloutItem>),
+}
+
+impl InitialHistory {
+    pub fn scan_rollout_items(&self, mut predicate: impl FnMut(&RolloutItem) -> bool) -> bool {
+        match self {
+            Self::New | Self::Cleared => false,
+            Self::Resumed(resumed) => resumed.history.iter().any(&mut predicate),
+            Self::Forked(items) => items.iter().any(predicate),
+        }
+    }
+
+    pub fn forked_from_id(&self) -> Option<ThreadId> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => resumed.history.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => meta_line.meta.forked_from_id,
+                _ => None,
+            }),
+            Self::Forked(items) => items.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => Some(meta_line.meta.id),
+                _ => None,
+            }),
+        }
+    }
+
+    pub fn session_cwd(&self) -> Option<PathBuf> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => session_cwd_from_items(&resumed.history),
+            Self::Forked(items) => session_cwd_from_items(items),
+        }
+    }
+
+    pub fn get_rollout_items(&self) -> &[RolloutItem] {
+        match self {
+            Self::New | Self::Cleared => &[],
+            Self::Resumed(resumed) => &resumed.history,
+            Self::Forked(items) => items,
+        }
+    }
+
+    pub fn get_event_msgs(&self) -> Option<Vec<EventMsg>> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => Some(
+                resumed
+                    .history
+                    .iter()
+                    .filter_map(|item| match item {
+                        RolloutItem::EventMsg(event) => Some(event.clone()),
+                        _ => None,
+                    })
+                    .collect(),
+            ),
+            Self::Forked(items) => Some(
+                items
+                    .iter()
+                    .filter_map(|item| match item {
+                        RolloutItem::EventMsg(event) => Some(event.clone()),
+                        _ => None,
+                    })
+                    .collect(),
+            ),
+        }
+    }
+
+    pub fn get_base_instructions(&self) -> Option<BaseInstructions> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => resumed.history.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => meta_line.meta.base_instructions.clone(),
+                _ => None,
+            }),
+            Self::Forked(items) => items.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => meta_line.meta.base_instructions.clone(),
+                _ => None,
+            }),
+        }
+    }
+
+    pub fn get_dynamic_tools(&self) -> Option<Vec<DynamicToolSpec>> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => resumed.history.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => meta_line.meta.dynamic_tools.clone(),
+                _ => None,
+            }),
+            Self::Forked(items) => items.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => meta_line.meta.dynamic_tools.clone(),
+                _ => None,
+            }),
+        }
+    }
+
+    pub fn get_selected_capability_roots(&self) -> Vec<SelectedCapabilityRoot> {
+        self.get_session_meta()
+            .map(|meta| meta.selected_capability_roots.clone())
+            .unwrap_or_default()
+    }
+
+    pub fn get_multi_agent_version(&self) -> Option<MultiAgentVersion> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => {
+                multi_agent_version_from_items(&resumed.history, Some(resumed.conversation_id))
+            }
+            Self::Forked(items) => multi_agent_version_from_items(items, /*thread_id*/ None),
+        }
+    }
+
+    pub fn get_history_mode(&self, default_history_mode: ThreadHistoryMode) -> ThreadHistoryMode {
+        match self {
+            Self::New | Self::Cleared => default_history_mode,
+            Self::Resumed(_) | Self::Forked(_) => self
+                .get_session_meta()
+                .map(|meta| meta.history_mode)
+                .unwrap_or(default_history_mode),
+        }
+    }
+
+    pub fn get_resumed_session_sources(&self) -> Option<(SessionSource, Option<ThreadSource>)> {
+        let meta = self.get_resumed_session_meta()?;
+        Some((meta.source.clone(), meta.thread_source.clone()))
+    }
+
+    pub fn get_resumed_thread_source(&self) -> Option<ThreadSource> {
+        self.get_resumed_session_meta()
+            .and_then(|meta| meta.thread_source.clone())
+    }
+
+    pub fn get_session_originator(&self) -> Option<String> {
+        self.get_session_meta()
+            .map(|meta| meta.originator.clone())
+            .filter(|originator| !originator.is_empty())
+    }
+
+    pub fn get_resumed_parent_thread_id(&self) -> Option<ThreadId> {
+        self.get_resumed_session_meta()
+            .and_then(|meta| meta.parent_thread_id)
+    }
+
+    fn get_session_meta(&self) -> Option<&SessionMeta> {
+        match self {
+            Self::New | Self::Cleared => None,
+            Self::Resumed(resumed) => resumed.history.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => Some(&meta_line.meta),
+                _ => None,
+            }),
+            Self::Forked(items) => items.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => Some(&meta_line.meta),
+                _ => None,
+            }),
+        }
+    }
+
+    fn get_resumed_session_meta(&self) -> Option<&SessionMeta> {
+        match self {
+            Self::New | Self::Cleared | Self::Forked(_) => None,
+            Self::Resumed(resumed) => resumed.history.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => Some(&meta_line.meta),
+                _ => None,
+            }),
+        }
+    }
+}
+
+fn session_cwd_from_items(items: &[RolloutItem]) -> Option<PathBuf> {
+    items.iter().find_map(|item| match item {
+        RolloutItem::SessionMeta(meta_line) => Some(meta_line.meta.cwd.clone()),
+        _ => None,
+    })
+}
+
+/// Returns a thread's latest plugin selection, with a turn-context fallback.
+///
+/// Forked history may contain ancestor snapshots, and compaction may append a
+/// frozen turn context after an update. Neither can replace thread-owned settings.
+/// Without an owned snapshot, only the latest turn context supplies the initial
+/// selection; a missing field must not resurrect a selection from an older turn.
+pub fn latest_disabled_plugin_ids(items: &[RolloutItem], thread_id: ThreadId) -> Option<&[String]> {
+    if let Some(ids) = items.iter().rev().find_map(|item| {
+        if let RolloutItem::EventMsg(EventMsg::ThreadSettingsApplied(event)) = item
+            && event.thread_id == Some(thread_id)
+        {
+            Some(event.thread_settings.disabled_plugin_ids.as_slice())
+        } else {
+            None
+        }
+    }) {
+        return Some(ids);
+    }
+    items
+        .iter()
+        .rev()
+        .find_map(|item| match item {
+            RolloutItem::TurnContext(context) => Some(context),
+            _ => None,
+        })
+        .and_then(|context| context.disabled_plugin_ids.as_deref())
+}
+
+fn multi_agent_version_from_items(
+    items: &[RolloutItem],
+    thread_id: Option<ThreadId>,
+) -> Option<MultiAgentVersion> {
+    let session_meta_version = items.iter().rev().find_map(|item| match item {
+        RolloutItem::SessionMeta(meta_line)
+            if thread_id.is_none_or(|thread_id| meta_line.meta.id == thread_id) =>
+        {
+            meta_line.meta.multi_agent_version
+        }
+        _ => None,
+    });
+
+    session_meta_version.or_else(|| {
+        items.iter().rev().find_map(|item| match item {
+            RolloutItem::TurnContext(turn_context) => turn_context.multi_agent_version,
+            RolloutItem::SessionMeta(_)
+            | RolloutItem::ResponseItem(_)
+            | RolloutItem::InterAgentCommunication(_)
+            | RolloutItem::InterAgentCommunicationMetadata { .. }
+            | RolloutItem::Compacted(_)
+            | RolloutItem::TokenUsageRecord(_)
+            | RolloutItem::WorldState(_)
+            | RolloutItem::RetainedContext(_)
+            | RolloutItem::SecurityRiskScore(_)
+            | RolloutItem::RealtimeItem(_)
+            | RolloutItem::EventMsg(_) => None,
+        })
+    })
+}
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;
diff --git a/codex-rs/history/src/reconciled_retained_context.rs b/codex-rs/history/src/reconciled_retained_context.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1343be63474efa74b0a97901889689db118120aa
--- /dev/null
+++ b/codex-rs/history/src/reconciled_retained_context.rs
@@ -0,0 +1,101 @@
+//! Read-only recovery of retained instructions from eligible live messages.
+//! Missing retained instructions use persisted acceptance order; unknown ordering stays incomplete.
+//! Recovering surviving sources cannot clear a checkpoint's record of missing instructions.
+
+use std::collections::HashSet;
+
+use crate::RetainedContext;
+use crate::RetainedContextEntry;
+use crate::RetainedContextOrder;
+use crate::RetainedUserMessage;
+
+/// Retained evidence supplemented by surviving user messages without changing the checkpoint.
+pub struct ReconciledRetainedContext<'a> {
+    retained_context: Option<&'a RetainedContext>,
+    recovered: Vec<(RetainedContextOrder, RetainedUserMessage)>,
+    /// Instructions were already missing, or a recovered source could not be ordered.
+    pub missing_user_messages: bool,
+}
+
+impl<'a> ReconciledRetainedContext<'a> {
+    /// Reconciles eligible live user messages with retained sources in acceptance order.
+    /// The caller supplies original source identities and filters out non-user context.
+    /// Inherited sources must supply no local order; retained identities match before ordering.
+    /// Live messages are consumed only when retained user instructions are incomplete.
+    pub fn new(
+        retained_context: Option<&'a RetainedContext>,
+        live_messages: impl IntoIterator<Item = (Option<u64>, RetainedUserMessage)>,
+    ) -> Self {
+        let mut missing_user_messages =
+            retained_context.is_none_or(RetainedContext::has_missing_user_messages);
+        let retained_entries = retained_context
+            .into_iter()
+            .flat_map(RetainedContext::ordered_entries)
+            .collect::<Vec<_>>();
+        let mut recovered = Vec::new();
+        if retained_context.is_none_or(|context| !context.user_messages_complete()) {
+            let mut matched_entries = HashSet::new();
+            let mut used_orders = retained_entries
+                .iter()
+                .map(|(order, _)| *order)
+                .collect::<HashSet<_>>();
+            for (order, message) in live_messages {
+                if retained_entries
+                    .iter()
+                    .enumerate()
+                    .any(|(index, (_, entry))| {
+                        let RetainedContextEntry::UserMessage(retained) = entry else {
+                            return false;
+                        };
+                        let matches_source = if let Some(id) = &retained.message_id {
+                            message.message_id.as_ref() == Some(id)
+                        } else {
+                            message.turn_id == retained.turn_id && message.text == retained.text
+                        };
+                        matches_source && matched_entries.insert(index)
+                    })
+                {
+                    continue;
+                }
+                // Queued steering can enter raw history after a later-accepted answer.
+                // Compare their persisted sequence numbers, including checkpoint-only answers.
+                // Parent counters cannot establish an adopted prefix position.
+                let Some(order) = order
+                    .map(RetainedContextOrder::Local)
+                    .filter(|order| used_orders.insert(*order))
+                else {
+                    missing_user_messages = true;
+                    continue;
+                };
+                recovered.push((order, message));
+            }
+        }
+        Self {
+            retained_context,
+            recovered,
+            missing_user_messages,
+        }
+    }
+
+    /// Returns retained and recovered evidence in persisted acceptance order.
+    pub fn ordered_entries(
+        &self,
+    ) -> impl DoubleEndedIterator<Item = (RetainedContextOrder, RetainedContextEntry<'_>)> {
+        let mut entries = self
+            .retained_context
+            .into_iter()
+            .flat_map(RetainedContext::ordered_entries)
+            .collect::<Vec<_>>();
+        entries.extend(
+            self.recovered
+                .iter()
+                .map(|(order, message)| (*order, RetainedContextEntry::UserMessage(message))),
+        );
+        entries.sort_by_key(|(order, _)| *order);
+        entries.into_iter()
+    }
+}
+
+#[cfg(test)]
+#[path = "reconciled_retained_context_tests.rs"]
+mod tests;
diff --git a/codex-rs/history/src/reconciled_retained_context_tests.rs b/codex-rs/history/src/reconciled_retained_context_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..baeb79d0dcbe25f1b4daea3b53267035a1f8a3d9
--- /dev/null
+++ b/codex-rs/history/src/reconciled_retained_context_tests.rs
@@ -0,0 +1,131 @@
+use super::*;
+use crate::RetainedContextEvent;
+use crate::RetainedInputSource;
+use crate::VerifiedAnswer;
+use crate::VerifiedQuestionAnswer;
+use pretty_assertions::assert_eq;
+
+fn instruction(text: &str) -> RetainedUserMessage {
+    RetainedUserMessage {
+        turn_id: "turn-1".to_owned(),
+        message_id: None,
+        text: text.to_owned(),
+        complete: false,
+    }
+}
+
+#[test]
+fn recovery_preserves_source_identity_acceptance_order_and_checkpoint_gaps() {
+    let initial = instruction("Inspect the deployment.");
+    let retained_excerpt = RetainedUserMessage {
+        message_id: Some("retained-message".to_owned()),
+        ..instruction("")
+    };
+    let original = RetainedUserMessage {
+        text: "Deploy the reviewed change.".to_owned(),
+        ..retained_excerpt.clone()
+    };
+    let mut retained = RetainedContext::default();
+    retained.record_user_message(initial.clone(), RetainedInputSource::Local(Some(0)));
+    retained.record_user_message(retained_excerpt, RetainedInputSource::Local(Some(1)));
+    retained.record(&RetainedContextEvent::VerifiedAnswer {
+        answer: VerifiedAnswer {
+            turn_id: "answer-turn".to_owned(),
+            call_id: "publish-question".to_owned(),
+            questions: vec![VerifiedQuestionAnswer {
+                question: "Publish?".to_owned(),
+                answer: "Never publicly.".to_owned(),
+            }],
+        },
+        acceptance_order: Some(3),
+    });
+    retained.mark_user_messages_incomplete();
+    let checkpoint = retained.clone();
+
+    let reconciled = ReconciledRetainedContext::new(
+        Some(&retained),
+        [
+            // Existing identities match before requiring an order, including an omitted excerpt.
+            (None, initial.clone()),
+            (None, original),
+            (Some(4), instruction("Do not deploy after all.")),
+            // This steer arrived before the checkpoint-only answer but was recorded later.
+            (Some(2), instruction("Make the deployment public.")),
+            // A second identical message is a distinct source once the retained one matched.
+            (Some(5), initial),
+        ],
+    );
+
+    assert_eq!(
+        (
+            reconciled
+                .ordered_entries()
+                .map(|(order, entry)| match entry {
+                    RetainedContextEntry::UserMessage(message) => (order, message.text.as_str()),
+                    RetainedContextEntry::VerifiedAnswer(answer) => {
+                        (order, answer.questions[0].answer.as_str())
+                    }
+                })
+                .collect::<Vec<_>>(),
+            reconciled.missing_user_messages,
+        ),
+        (
+            vec![
+                (RetainedContextOrder::Local(0), "Inspect the deployment."),
+                (RetainedContextOrder::Local(1), ""),
+                (
+                    RetainedContextOrder::Local(2),
+                    "Make the deployment public."
+                ),
+                (RetainedContextOrder::Local(3), "Never publicly."),
+                (RetainedContextOrder::Local(4), "Do not deploy after all."),
+                (RetainedContextOrder::Local(5), "Inspect the deployment."),
+            ],
+            true,
+        ),
+    );
+    assert_eq!(retained, checkpoint);
+}
+
+#[test]
+fn recovery_marks_missing_and_conflicting_orders_incomplete() {
+    let mut retained = RetainedContext::default();
+    retained.record_user_message(
+        instruction("Inspect the deployment."),
+        RetainedInputSource::Local(Some(1)),
+    );
+    assert!(!retained.has_missing_user_messages());
+    let checkpoint = retained.clone();
+
+    for invalid_order in [None, Some(1), Some(2)] {
+        let reconciled = ReconciledRetainedContext::new(
+            Some(&retained),
+            [
+                (Some(2), instruction("Do not deploy.")),
+                (invalid_order, instruction("Invalid-order instruction.")),
+            ],
+        );
+        assert_eq!(
+            (
+                reconciled
+                    .ordered_entries()
+                    .map(|(order, entry)| match entry {
+                        RetainedContextEntry::UserMessage(message) =>
+                            (order, message.text.as_str()),
+                        RetainedContextEntry::VerifiedAnswer(_) => panic!("unexpected answer"),
+                    })
+                    .collect::<Vec<_>>(),
+                reconciled.missing_user_messages,
+            ),
+            (
+                vec![
+                    (RetainedContextOrder::Local(1), "Inspect the deployment."),
+                    (RetainedContextOrder::Local(2), "Do not deploy.")
+                ],
+                true,
+            ),
+            "invalid order: {invalid_order:?}",
+        );
+    }
+    assert_eq!(retained, checkpoint);
+}
diff --git a/codex-rs/history/src/retained_context.rs b/codex-rs/history/src/retained_context.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ecc5c364c9ed7339e338e52c46e4c799bfe7c27b
--- /dev/null
+++ b/codex-rs/history/src/retained_context.rs
@@ -0,0 +1,460 @@
+//! Bounded host-owned facts outside the model's compaction contract.
+//! Checkpoints and live recording use the same admission rules; rendering is a consumer concern.
+//! Adopted parent instructions precede local facts without sharing the local acceptance counter.
+//! Their parent verified answers are unavailable, so adopted authorization stays incomplete.
+
+use std::collections::VecDeque;
+
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+
+use crate::CodexHarnessMetadata;
+use crate::ResponseItemEnvelope;
+
+const MAX_FAMILY_RECORDS: usize = 8;
+const MAX_RECORD_BYTES: usize = 16_384;
+const MAX_FAMILY_BYTES: usize = 65_536;
+
+/// Original assistant question and host-verified user reply, never an inferred permission.
+#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct VerifiedQuestionAnswer {
+    pub question: String,
+    pub answer: String,
+}
+
+/// One accepted request_user_input response. Identity is local to the owning thread.
+/// An omitted payload records incomplete evidence, rather than keeping a partial grant.
+#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct VerifiedAnswer {
+    pub turn_id: String,
+    pub call_id: String,
+    pub questions: Vec<VerifiedQuestionAnswer>,
+}
+
+/// Original user instruction, retained outside model summarization for delegated review.
+/// Non-text input is not reconstructed as text; missing evidence remains explicit.
+#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct RetainedUserMessage {
+    pub turn_id: String,
+    pub message_id: Option<String>,
+    pub text: String,
+    pub complete: bool,
+}
+
+/// Local facts use their acceptance counter; copied parent instructions use prefix order.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum RetainedInputSource {
+    Local(Option<u64>),
+    Inherited,
+}
+
+impl RetainedInputSource {
+    /// Parent counters never establish order within the owning thread.
+    pub fn acceptance_order(self) -> Option<u64> {
+        match self {
+            Self::Local(order) => order,
+            Self::Inherited => None,
+        }
+    }
+}
+
+impl From<Option<&CodexHarnessMetadata>> for RetainedInputSource {
+    fn from(metadata: Option<&CodexHarnessMetadata>) -> Self {
+        if metadata.is_some_and(|metadata| metadata.inherited_user_message) {
+            Self::Inherited
+        } else {
+            Self::Local(metadata.and_then(|metadata| metadata.user_input_order))
+        }
+    }
+}
+
+impl std::fmt::Debug for RetainedUserMessage {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("RetainedUserMessage")
+            .field("complete", &self.complete)
+            .finish_non_exhaustive()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+struct Ordered<T> {
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    inherited: bool,
+    #[serde(default)]
+    order: u64,
+    #[serde(flatten)]
+    value: T,
+}
+
+impl<T> Ordered<T> {
+    fn key(&self) -> RetainedContextOrder {
+        if self.inherited {
+            RetainedContextOrder::Inherited(self.order)
+        } else {
+            RetainedContextOrder::Local(self.order)
+        }
+    }
+}
+
+/// Inherited prefix order precedes the owning thread's local acceptance order.
+/// The counters have separate scopes and must not be compared without their origin.
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub enum RetainedContextOrder {
+    Inherited(u64),
+    Local(u64),
+}
+
+/// Borrowed host evidence across retained families.
+pub enum RetainedContextEntry<'a> {
+    UserMessage(&'a RetainedUserMessage),
+    VerifiedAnswer(&'a VerifiedAnswer),
+}
+
+impl std::fmt::Debug for VerifiedAnswer {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("VerifiedAnswer")
+            .field("questions", &self.questions.len())
+            .finish_non_exhaustive()
+    }
+}
+
+/// Sparse, model-invisible updates. Only the host may produce these records.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum RetainedContextEvent {
+    VerifiedAnswer {
+        #[serde(flatten)]
+        answer: VerifiedAnswer,
+        /// Absent in legacy events, which retain their recorded ordering.
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        acceptance_order: Option<u64>,
+    },
+}
+
+/// Bounded snapshot of retained families, persisted with the parent compaction checkpoint.
+/// Facts live until their instruction boundary is rolled back; compaction does not expire them.
+#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct RetainedContext {
+    verified_answers: VecDeque<Ordered<VerifiedAnswer>>,
+    /// Lost evidence cannot be treated as a complete authorization history.
+    #[serde(rename = "incomplete")]
+    verified_answers_incomplete: bool,
+    #[serde(default)]
+    user_messages: VecDeque<Ordered<RetainedUserMessage>>,
+    /// Old checkpoints did not preserve user restrictions for delegated review.
+    #[serde(default = "legacy_user_messages_incomplete")]
+    user_messages_incomplete: bool,
+    #[serde(default)]
+    next_order: u64,
+}
+
+fn legacy_user_messages_incomplete() -> bool {
+    true
+}
+
+fn bound_family<T: Serialize>(items: &mut VecDeque<Ordered<T>>, incomplete: &mut bool) {
+    // Queued instructions can be recorded after later-accepted answers. Evict by
+    // acceptance order, not by the order in which persistence happened to finish.
+    items.make_contiguous().sort_by_key(Ordered::key);
+    while items.len() > MAX_FAMILY_RECORDS
+        || serde_json::to_vec(items).map_or(true, |bytes| bytes.len() > MAX_FAMILY_BYTES)
+    {
+        items.pop_front();
+        *incomplete = true;
+    }
+}
+
+impl RetainedUserMessage {
+    fn bound(&mut self) {
+        if serde_json::to_vec(self).map_or(true, |bytes| bytes.len() > MAX_RECORD_BYTES) {
+            self.text.clear();
+            self.complete = false;
+            self.turn_id
+                .truncate(self.turn_id.floor_char_boundary(1_024));
+            if let Some(id) = &mut self.message_id {
+                id.truncate(id.floor_char_boundary(1_024));
+            }
+        }
+    }
+}
+
+impl RetainedContextEvent {
+    /// Bounds a persisted event before it enters the rollout or the live snapshot.
+    pub fn bound(&mut self) {
+        match self {
+            Self::VerifiedAnswer { answer, .. } => {
+                if serde_json::to_vec(answer).map_or(true, |bytes| bytes.len() > MAX_RECORD_BYTES) {
+                    answer.questions.clear();
+                    // IDs are correlation metadata, not model-visible authorization text.
+                    answer
+                        .turn_id
+                        .truncate(answer.turn_id.floor_char_boundary(1_024));
+                    answer
+                        .call_id
+                        .truncate(answer.call_id.floor_char_boundary(1_024));
+                }
+            }
+        }
+    }
+}
+
+impl RetainedContext {
+    /// Reserves order without retaining pending input that hooks may reject or cancel.
+    pub fn reserve_order(&mut self) -> u64 {
+        let order = self.next_order;
+        self.next_order = self.next_order.saturating_add(1);
+        order
+    }
+
+    fn record_order(&mut self, acceptance_order: Option<u64>) -> u64 {
+        let order = acceptance_order.unwrap_or(self.next_order);
+        self.next_order = self.next_order.max(order.saturating_add(1));
+        order
+    }
+
+    pub fn verified_answers(&self) -> impl DoubleEndedIterator<Item = &VerifiedAnswer> {
+        self.verified_answers.iter().map(|entry| &entry.value)
+    }
+
+    pub fn verified_answers_complete(&self) -> bool {
+        !self.verified_answers_incomplete
+            && self
+                .verified_answers
+                .iter()
+                .all(|answer| !answer.value.questions.is_empty())
+    }
+
+    pub fn user_messages_complete(&self) -> bool {
+        !self.has_missing_user_messages()
+            && self
+                .user_messages
+                .iter()
+                .all(|message| message.value.complete)
+    }
+
+    /// Whether instruction records were lost or omitted by legacy capture.
+    /// Bounded excerpts keep their source record and do not set this marker.
+    pub fn has_missing_user_messages(&self) -> bool {
+        self.user_messages_incomplete
+    }
+
+    /// A skipped instruction leaves a gap that later checkpoints must preserve.
+    pub fn mark_user_messages_incomplete(&mut self) {
+        self.user_messages_incomplete = true;
+    }
+
+    /// Whether a root checkpoint already contains its adopted instruction prefix.
+    pub fn has_inherited_user_messages(&self) -> bool {
+        self.user_messages.iter().any(|entry| entry.inherited)
+    }
+
+    /// Returns retained evidence with its origin and persisted order across both families.
+    /// Explicit acceptance order survives delayed recording; inherited prefix order stays separate.
+    pub fn ordered_entries(
+        &self,
+    ) -> impl DoubleEndedIterator<Item = (RetainedContextOrder, RetainedContextEntry<'_>)> {
+        let mut entries = self
+            .verified_answers
+            .iter()
+            .map(|entry| {
+                (
+                    entry.key(),
+                    RetainedContextEntry::VerifiedAnswer(&entry.value),
+                )
+            })
+            .chain(
+                self.user_messages
+                    .iter()
+                    .map(|entry| (entry.key(), RetainedContextEntry::UserMessage(&entry.value))),
+            )
+            .collect::<Vec<_>>();
+        entries.sort_by_key(|(order, _)| *order);
+        entries.into_iter()
+    }
+
+    /// Records a delivered user item with its acceptance order. Legacy items without
+    /// this metadata use recording order; checkpoint/suffix replay uses the same path.
+    /// Inherited instructions use prefix order because their original counters belong to parents.
+    pub fn record_user_message(
+        &mut self,
+        mut message: RetainedUserMessage,
+        source: RetainedInputSource,
+    ) {
+        message.bound();
+        let inherited = source == RetainedInputSource::Inherited;
+        // Worker forks omit parent answer records. Adopting their instructions
+        // cannot establish whether an omitted answer restricted an inherited grant.
+        self.verified_answers_incomplete |= inherited;
+        if let Some(index) = self.user_messages.iter().position(|entry| {
+            message.message_id.is_some() && entry.value.message_id == message.message_id
+        }) {
+            if self.user_messages[index].value == message
+                && self.user_messages[index].inherited == inherited
+            {
+                return;
+            }
+            self.user_messages.remove(index);
+        }
+        // Parent and worker counters have different scopes. Adopt the copied prefix
+        // in history order without advancing the worker's local acceptance counter.
+        let order = if inherited {
+            self.user_messages
+                .iter()
+                .filter(|entry| entry.inherited)
+                .map(|entry| entry.order.saturating_add(1))
+                .max()
+                .unwrap_or_default()
+        } else {
+            self.record_order(source.acceptance_order())
+        };
+        self.user_messages.push_back(Ordered {
+            inherited,
+            order,
+            value: message,
+        });
+        bound_family(&mut self.user_messages, &mut self.user_messages_incomplete);
+    }
+
+    /// Recovers omitted text from an exact source without changing identity, order, or
+    /// completeness. Recovered excerpts must still satisfy the retained storage limits.
+    pub fn recover_user_message_excerpts(
+        &mut self,
+        mut excerpt_for_id: impl FnMut(&str) -> Option<String>,
+    ) {
+        for entry in &mut self.user_messages {
+            let message = &mut entry.value;
+            if message.text.is_empty()
+                && !message.complete
+                && let Some(text) = message.message_id.as_deref().and_then(&mut excerpt_for_id)
+            {
+                message.text = text;
+                message.bound();
+            }
+        }
+        bound_family(&mut self.user_messages, &mut self.user_messages_incomplete);
+    }
+
+    /// Same-event delivery is idempotent; changed contents replace that source's record.
+    pub fn record(&mut self, event: &RetainedContextEvent) -> bool {
+        let mut event = event.clone();
+        event.bound();
+        match event {
+            RetainedContextEvent::VerifiedAnswer {
+                answer,
+                acceptance_order,
+            } => {
+                if let Some(index) = self.verified_answers.iter().position(|existing| {
+                    existing.value.turn_id == answer.turn_id
+                        && existing.value.call_id == answer.call_id
+                }) {
+                    if self.verified_answers[index].value == answer {
+                        return false;
+                    }
+                    self.verified_answers.remove(index);
+                }
+                let order = self.record_order(acceptance_order);
+                self.verified_answers.push_back(Ordered {
+                    inherited: false,
+                    order,
+                    value: answer,
+                });
+                bound_family(
+                    &mut self.verified_answers,
+                    &mut self.verified_answers_incomplete,
+                );
+            }
+        }
+        true
+    }
+
+    /// Restoring a saved thread must not bypass the live storage limits.
+    /// A missing checkpoint cannot establish complete historical user instructions.
+    /// Surviving local input metadata also advances the counter when its retained record is missing.
+    pub fn restore(&mut self, checkpoint: Option<&Self>, surviving_items: &[ResponseItemEnvelope]) {
+        *self = checkpoint.cloned().unwrap_or_else(|| Self {
+            user_messages_incomplete: true,
+            ..Self::default()
+        });
+        for entry in &mut self.verified_answers {
+            let mut event = RetainedContextEvent::VerifiedAnswer {
+                answer: entry.value.clone(),
+                acceptance_order: Some(entry.order),
+            };
+            event.bound();
+            let RetainedContextEvent::VerifiedAnswer { answer, .. } = event;
+            entry.value = answer;
+            self.next_order = self.next_order.max(entry.order.saturating_add(1));
+        }
+        for entry in &mut self.user_messages {
+            entry.value.bound();
+            // Also repair checkpoints written before adoption recorded the answer gap.
+            self.verified_answers_incomplete |= entry.inherited;
+            if !entry.inherited {
+                self.next_order = self.next_order.max(entry.order.saturating_add(1));
+            }
+        }
+        for order in surviving_items
+            .iter()
+            .filter_map(|item| item.metadata.as_ref())
+            .filter(|metadata| !metadata.inherited_user_message)
+            .filter_map(|metadata| metadata.user_input_order)
+        {
+            self.next_order = self.next_order.max(order.saturating_add(1));
+        }
+        bound_family(
+            &mut self.verified_answers,
+            &mut self.verified_answers_incomplete,
+        );
+        bound_family(&mut self.user_messages, &mut self.user_messages_incomplete);
+    }
+
+    /// Keeps legacy answers whose source calls survive when no retained instruction boundary exists.
+    pub fn retain_answers(&mut self, mut keep: impl FnMut(&VerifiedAnswer) -> bool) {
+        self.verified_answers.retain(|answer| keep(&answer.value));
+    }
+
+    /// Rolls back at the original user-message boundary, including later-accepted facts.
+    /// The explicit order also covers checkpoints made before a queued message was delivered.
+    /// Steering can share a turn ID. Legacy sources without message identity fall back to
+    /// source-turn removal and cannot establish complete retained user instructions.
+    pub fn rollback(
+        &mut self,
+        turn_ids: &[&str],
+        first_removed_message_id: Option<&str>,
+        source: RetainedInputSource,
+    ) {
+        let boundary = source.acceptance_order().map(RetainedContextOrder::Local);
+        if let Some(boundary) = boundary.or_else(|| {
+            first_removed_message_id.and_then(|id| {
+                self.user_messages
+                    .iter()
+                    .find(|message| message.value.message_id.as_deref() == Some(id))
+                    .map(Ordered::key)
+            })
+        }) {
+            self.verified_answers.retain(|entry| entry.key() < boundary);
+            self.user_messages.retain(|entry| entry.key() < boundary);
+            return;
+        }
+        self.user_messages_incomplete |= first_removed_message_id.is_some()
+            || self
+                .user_messages
+                .iter()
+                .any(|message| turn_ids.contains(&message.value.turn_id.as_str()));
+        self.verified_answers.retain(|answer| {
+            source != RetainedInputSource::Inherited
+                && !turn_ids.contains(&answer.value.turn_id.as_str())
+        });
+        self.user_messages.retain(|message| {
+            (source != RetainedInputSource::Inherited || message.inherited)
+                && !turn_ids.contains(&message.value.turn_id.as_str())
+        });
+    }
+}
+
+#[cfg(test)]
+#[path = "retained_context_tests.rs"]
+mod tests;
diff --git a/codex-rs/history/src/retained_context_tests.rs b/codex-rs/history/src/retained_context_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9b5bf65f99a95e23b2fc8e001e646a89019ccf9d
--- /dev/null
+++ b/codex-rs/history/src/retained_context_tests.rs
@@ -0,0 +1,388 @@
+use super::*;
+use crate::CodexHarnessMetadata;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use pretty_assertions::assert_eq;
+
+fn publish_answer() -> RetainedContextEvent {
+    RetainedContextEvent::VerifiedAnswer {
+        answer: VerifiedAnswer {
+            turn_id: "turn-1".to_owned(),
+            call_id: "ask-1".to_owned(),
+            questions: vec![VerifiedQuestionAnswer {
+                question: "Publish?".to_owned(),
+                answer: "Yes, but never publicly.".to_owned(),
+            }],
+        },
+        acceptance_order: None,
+    }
+}
+
+#[test]
+fn retained_evidence_preserves_order_through_recovery_checkpoint_and_rollback() {
+    let mut context = RetainedContext::default();
+    let first = publish_answer();
+    assert!(context.record(&first));
+    let before_restriction = context.clone();
+    context.record_user_message(
+        RetainedUserMessage {
+            turn_id: "revocation-turn".to_owned(),
+            message_id: Some("revocation".to_owned()),
+            text: String::new(),
+            complete: false,
+        },
+        RetainedInputSource::Local(None),
+    );
+    let mut expected = context.clone();
+    expected.user_messages[0].value.text = "Do not publish after all.".to_owned();
+    context.recover_user_message_excerpts(|id| {
+        assert_eq!(id, "revocation");
+        Some("Do not publish after all.".to_owned())
+    });
+    assert_eq!(context, expected);
+    context.recover_user_message_excerpts(|_| panic!("existing text must not be replaced"));
+    let snapshot = context.clone();
+    assert!(!context.record(&first));
+    assert_eq!(context, snapshot);
+    let checkpoint =
+        serde_json::from_str(&serde_json::to_string(&context).expect("retained answer fixture"))
+            .expect("retained answer fixture");
+    let mut restored = RetainedContext::default();
+    restored.restore(Some(&checkpoint), &[]);
+    assert_eq!(restored, snapshot);
+    assert_eq!(
+        restored
+            .ordered_entries()
+            .map(|(_, entry)| match entry {
+                RetainedContextEntry::VerifiedAnswer(answer) => answer.questions[0].answer.as_str(),
+                RetainedContextEntry::UserMessage(message) => message.text.as_str(),
+            })
+            .collect::<Vec<_>>(),
+        vec!["Yes, but never publicly.", "Do not publish after all."]
+    );
+    restored.rollback(
+        &["revocation-turn"],
+        Some("revocation"),
+        RetainedInputSource::Local(None),
+    );
+    assert_eq!(
+        restored,
+        RetainedContext {
+            next_order: snapshot.next_order,
+            ..before_restriction
+        }
+    );
+}
+
+#[test]
+fn retained_families_enforce_storage_limits_without_changing_snapshots() {
+    let mut context = RetainedContext::default();
+    let first = publish_answer();
+    context.record(&first);
+    let snapshot = context.clone();
+
+    for index in 2..=10 {
+        context.record(&RetainedContextEvent::VerifiedAnswer {
+            answer: VerifiedAnswer {
+                turn_id: "turn-2".to_owned(),
+                call_id: format!("ask-{index}"),
+                questions: vec![VerifiedQuestionAnswer {
+                    question: "Continue?".to_owned(),
+                    answer: "Yes".to_owned(),
+                }],
+            },
+            acceptance_order: None,
+        });
+    }
+    assert!(!context.verified_answers_complete());
+    assert_eq!(context.verified_answers().count(), MAX_FAMILY_RECORDS);
+    context.rollback(
+        &["turn-2"],
+        /*first_removed_message_id*/ None,
+        RetainedInputSource::Local(None),
+    );
+    assert_eq!(context.verified_answers().count(), 0);
+    assert!(!context.verified_answers_complete());
+
+    let mut restored = snapshot.clone();
+    let mut oversized = first.clone();
+    let RetainedContextEvent::VerifiedAnswer { answer, .. } = &mut oversized;
+    answer.questions[0].answer = "a".repeat(MAX_RECORD_BYTES);
+    restored.record(&oversized);
+    assert!(!restored.verified_answers_complete());
+    assert!(
+        restored
+            .verified_answers()
+            .next()
+            .expect("retained answer fixture")
+            .questions
+            .is_empty()
+    );
+    assert_eq!(
+        snapshot
+            .verified_answers()
+            .next()
+            .expect("retained answer fixture")
+            .questions[0]
+            .answer,
+        "Yes, but never publicly."
+    );
+    for index in 0..=MAX_FAMILY_RECORDS {
+        restored.record_user_message(
+            RetainedUserMessage {
+                turn_id: "later-turn".to_owned(),
+                message_id: Some(format!("message-{index}")),
+                text: "Keep the repository private.".to_owned(),
+                complete: true,
+            },
+            RetainedInputSource::Local(None),
+        );
+    }
+    assert!(!restored.user_messages_complete());
+    assert_eq!(
+        restored
+            .ordered_entries()
+            .filter(|(_, entry)| matches!(entry, RetainedContextEntry::UserMessage(_)))
+            .count(),
+        MAX_FAMILY_RECORDS
+    );
+    let recent = restored.clone();
+    restored.record_user_message(
+        RetainedUserMessage {
+            turn_id: "earlier-turn".to_owned(),
+            message_id: Some("delayed-message".to_owned()),
+            text: "An older queued instruction.".to_owned(),
+            complete: true,
+        },
+        RetainedInputSource::Local(Some(0)),
+    );
+    assert_eq!(
+        restored, recent,
+        "delayed old input must not evict newer evidence"
+    );
+    restored.record_user_message(
+        RetainedUserMessage {
+            turn_id: "oversized-turn".to_owned(),
+            message_id: Some("oversized-message".to_owned()),
+            text: "restriction ".repeat(MAX_RECORD_BYTES),
+            complete: true,
+        },
+        RetainedInputSource::Local(None),
+    );
+    let Some((_, RetainedContextEntry::UserMessage(message))) =
+        restored.ordered_entries().next_back()
+    else {
+        panic!("latest user evidence");
+    };
+    assert_eq!((&message.text, message.complete), (&String::new(), false));
+}
+
+#[test]
+fn recovered_excerpts_obey_record_and_family_limits() {
+    let mut context = RetainedContext::default();
+    for index in 0..MAX_FAMILY_RECORDS {
+        context.record_user_message(
+            RetainedUserMessage {
+                turn_id: "turn-1".to_owned(),
+                message_id: Some(format!("message-{index}")),
+                text: String::new(),
+                complete: false,
+            },
+            RetainedInputSource::Local(None),
+        );
+    }
+    let unchanged = context.clone();
+    context.recover_user_message_excerpts(|_| Some("x".repeat(MAX_RECORD_BYTES)));
+    assert_eq!(context, unchanged);
+    context.recover_user_message_excerpts(|_| Some("x".repeat(MAX_RECORD_BYTES - 1_024)));
+    assert!(context.user_messages_incomplete);
+    assert!(context.user_messages.len() < MAX_FAMILY_RECORDS);
+    assert!(serde_json::to_vec(&context.user_messages).unwrap().len() <= MAX_FAMILY_BYTES);
+}
+
+#[test]
+fn legacy_checkpoints_mark_user_messages_incomplete() {
+    let RetainedContextEvent::VerifiedAnswer { answer, .. } = publish_answer();
+    let mut wire = serde_json::json!({
+        "verified_answers": [answer], "incomplete": false
+    });
+    let legacy: RetainedContext =
+        serde_json::from_value(wire.clone()).expect("legacy retained-answer checkpoint");
+    assert!(legacy.verified_answers_complete());
+    assert!(!legacy.user_messages_complete());
+
+    // Retain the original wire key even though the internal field names its family.
+    wire["verified_answers"][0]["order"] = serde_json::json!(0);
+    wire["user_messages"] = serde_json::json!([]);
+    wire["user_messages_incomplete"] = serde_json::json!(true);
+    wire["next_order"] = serde_json::json!(0);
+    assert_eq!(serde_json::to_value(&legacy).unwrap(), wire);
+
+    let mut restored = RetainedContext::default();
+    restored.restore(/*checkpoint*/ None, &[]);
+    assert!(!restored.user_messages_complete());
+}
+
+#[test]
+fn restored_input_order_accounts_for_surviving_local_sources() {
+    let surviving_items = [(Some(7), false), (Some(100), true), (None, false)].map(
+        |(user_input_order, inherited_user_message)| ResponseItemEnvelope {
+            item: ResponseItem::Message {
+                id: None,
+                role: "user".to_owned(),
+                content: vec![ContentItem::InputText {
+                    text: "Inspect the deployment.".to_owned(),
+                }],
+                phase: None,
+                internal_chat_message_metadata_passthrough: None,
+            },
+            metadata: Some(CodexHarnessMetadata {
+                user_input_order,
+                inherited_user_message,
+                ..Default::default()
+            }),
+        },
+    );
+    let checkpoint = RetainedContext {
+        next_order: 20,
+        ..Default::default()
+    };
+    for (checkpoint, expected_order) in [(None, 8), (Some(&checkpoint), 20)] {
+        let mut restored = RetainedContext::default();
+        restored.restore(checkpoint, &surviving_items);
+        assert_eq!(
+            (
+                restored.reserve_order(),
+                restored.ordered_entries().count(),
+                restored.user_messages_complete(),
+            ),
+            (expected_order, 0, checkpoint.is_some()),
+        );
+    }
+}
+
+#[test]
+fn accepted_order_survives_delayed_recording_and_checkpoint_replay() {
+    let mut context = RetainedContext::default();
+    // Rejected/canceled input consumes a sequence but never becomes evidence.
+    context.reserve_order();
+    let steer_order = context.reserve_order();
+    let answer_order = context.reserve_order();
+    let RetainedContextEvent::VerifiedAnswer { answer, .. } = publish_answer();
+    let event = RetainedContextEvent::VerifiedAnswer {
+        answer,
+        acceptance_order: Some(answer_order),
+    };
+    context.record(&event);
+    let checkpoint = context.clone();
+    let instruction = RetainedUserMessage {
+        turn_id: "turn-1".to_owned(),
+        message_id: Some("steer".to_owned()),
+        text: "Keep the repository private.".to_owned(),
+        complete: true,
+    };
+    context.record_user_message(
+        instruction.clone(),
+        RetainedInputSource::Local(Some(steer_order)),
+    );
+    let mut resumed = RetainedContext::default();
+    resumed.restore(Some(&checkpoint), &[]);
+    resumed.record_user_message(instruction, RetainedInputSource::Local(Some(steer_order)));
+    assert_eq!(resumed, context);
+    assert_eq!(
+        resumed
+            .ordered_entries()
+            .map(|(order, entry)| match entry {
+                RetainedContextEntry::UserMessage(message) => (order, message.text.as_str()),
+                RetainedContextEntry::VerifiedAnswer(answer) => {
+                    (order, answer.questions[0].answer.as_str())
+                }
+            })
+            .collect::<Vec<_>>(),
+        vec![
+            (
+                RetainedContextOrder::Local(steer_order),
+                "Keep the repository private."
+            ),
+            (
+                RetainedContextOrder::Local(answer_order),
+                "Yes, but never publicly."
+            ),
+        ],
+    );
+    // This checkpoint predates model delivery of the queued instruction. Rollback
+    // still removes its later-accepted answer using the persisted boundary order.
+    let mut before_delivery = checkpoint;
+    before_delivery.rollback(
+        &["turn-1"],
+        Some("steer"),
+        RetainedInputSource::Local(Some(steer_order)),
+    );
+    resumed.rollback(
+        &["turn-1"],
+        Some("steer"),
+        RetainedInputSource::Local(Some(steer_order)),
+    );
+    assert_eq!(before_delivery, resumed);
+    assert_eq!(
+        resumed,
+        RetainedContext {
+            next_order: 3,
+            ..Default::default()
+        }
+    );
+}
+
+#[test]
+fn adopted_instructions_preserve_local_order_and_rollback_scope() {
+    let mut context = RetainedContext::default();
+    context.record(&publish_answer());
+    for index in 0..2 {
+        let message = RetainedUserMessage {
+            turn_id: "parent-turn".to_owned(),
+            message_id: Some(format!("parent-{index}")),
+            text: format!("Parent instruction {index}"),
+            complete: true,
+        };
+        context.record_user_message(message.clone(), RetainedInputSource::Inherited);
+        context.record_user_message(message, RetainedInputSource::Inherited);
+    }
+    assert_eq!(context.reserve_order(), 1);
+    assert!(!context.verified_answers_complete());
+    assert_eq!(
+        context
+            .ordered_entries()
+            .map(|(order, _)| order)
+            .collect::<Vec<_>>(),
+        vec![
+            RetainedContextOrder::Inherited(0),
+            RetainedContextOrder::Inherited(1),
+            RetainedContextOrder::Local(0)
+        ],
+    );
+    let checkpoint = serde_json::from_slice(&serde_json::to_vec(&context).unwrap()).unwrap();
+    let mut restored = RetainedContext::default();
+    restored.restore(Some(&checkpoint), &[]);
+    assert_eq!(restored, context);
+    // Older roots adopted complete instructions without recording the missing parent answers.
+    let mut legacy_checkpoint = serde_json::to_value(&checkpoint).unwrap();
+    legacy_checkpoint["incomplete"] = serde_json::json!(false);
+    let legacy_checkpoint = serde_json::from_value(legacy_checkpoint).unwrap();
+    restored.restore(Some(&legacy_checkpoint), &[]);
+    assert_eq!(restored, context);
+    restored.rollback(
+        &["turn-1"],
+        /*first_removed_message_id*/ None,
+        RetainedInputSource::Local(Some(0)),
+    );
+    let mut expected = context;
+    expected.verified_answers.clear();
+    assert_eq!(restored, expected);
+    restored.rollback(
+        &["parent-turn"],
+        Some("parent-1"),
+        RetainedInputSource::Inherited,
+    );
+    expected.user_messages.pop_back();
+    assert_eq!(restored, expected);
+}
diff --git a/codex-rs/history/src/rollout_payload.rs b/codex-rs/history/src/rollout_payload.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0a491fed6dd8736de776637fef7897e1fa2edbdb
--- /dev/null
+++ b/codex-rs/history/src/rollout_payload.rs
@@ -0,0 +1,294 @@
+use std::borrow::Cow;
+
+use super::CodexHarnessMetadata;
+use super::CompactedItem;
+use super::EventMsg;
+use super::InterAgentCommunication;
+use super::McpResourceOriginCheckpoint;
+use super::RealtimeItem;
+use super::ResponseItem;
+use super::ResponseItemEnvelope;
+use super::RolloutItem;
+use super::SecurityRiskScore;
+use super::SessionMetaLine;
+use super::TokenUsageRecord;
+use super::TurnContextItem;
+use super::WorldStateItem;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+
+/// Persisted rollout item used by core history and rollout storage.
+#[derive(Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub(super) enum RolloutItemWire<'a> {
+    SessionMeta {
+        payload: Cow<'a, SessionMetaLine>,
+    },
+    ResponseItem {
+        payload: Cow<'a, ResponseItem>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        metadata: Option<Cow<'a, CodexHarnessMetadata>>,
+    },
+    InterAgentCommunication {
+        payload: Cow<'a, InterAgentCommunication>,
+    },
+    InterAgentCommunicationMetadata {
+        payload: InterAgentCommunicationMetadataPayload,
+    },
+    Compacted {
+        payload: Cow<'a, CompactedItem>,
+    },
+    TurnContext {
+        payload: Cow<'a, TurnContextItem>,
+    },
+    TokenUsageRecord {
+        payload: Cow<'a, TokenUsageRecord>,
+    },
+    WorldState {
+        payload: Cow<'a, WorldStateItem>,
+    },
+    RetainedContext {
+        payload: Cow<'a, crate::RetainedContextEvent>,
+    },
+    SecurityRiskScore {
+        payload: Cow<'a, SecurityRiskScore>,
+    },
+    EventMsg {
+        payload: Cow<'a, EventMsg>,
+    },
+    RealtimeItem {
+        payload: Cow<'a, RealtimeItem>,
+    },
+}
+
+impl<'a> From<&'a RolloutItem> for RolloutItemWire<'a> {
+    fn from(item: &'a RolloutItem) -> Self {
+        match item {
+            RolloutItem::SessionMeta(payload) => Self::SessionMeta {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::ResponseItem(envelope) => Self::ResponseItem {
+                payload: Cow::Borrowed(&envelope.item),
+                metadata: envelope.metadata.as_ref().map(Cow::Borrowed),
+            },
+            RolloutItem::InterAgentCommunication(payload) => Self::InterAgentCommunication {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::InterAgentCommunicationMetadata { trigger_turn } => {
+                Self::InterAgentCommunicationMetadata {
+                    payload: InterAgentCommunicationMetadataPayload {
+                        trigger_turn: *trigger_turn,
+                    },
+                }
+            }
+            RolloutItem::Compacted(payload) => Self::Compacted {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::TurnContext(payload) => Self::TurnContext {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::TokenUsageRecord(payload) => Self::TokenUsageRecord {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::WorldState(payload) => Self::WorldState {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::RetainedContext(payload) => Self::RetainedContext {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::SecurityRiskScore(payload) => Self::SecurityRiskScore {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::EventMsg(payload) => Self::EventMsg {
+                payload: Cow::Borrowed(payload),
+            },
+            RolloutItem::RealtimeItem(payload) => Self::RealtimeItem {
+                payload: Cow::Borrowed(payload),
+            },
+        }
+    }
+}
+
+impl From<RolloutItemWire<'_>> for RolloutItem {
+    fn from(item: RolloutItemWire<'_>) -> Self {
+        match item {
+            RolloutItemWire::SessionMeta { payload } => Self::SessionMeta(payload.into_owned()),
+            RolloutItemWire::ResponseItem { payload, metadata } => {
+                Self::ResponseItem(ResponseItemEnvelope {
+                    item: payload.into_owned(),
+                    metadata: metadata.map(Cow::into_owned),
+                })
+            }
+            RolloutItemWire::InterAgentCommunication { payload } => {
+                Self::InterAgentCommunication(payload.into_owned())
+            }
+            RolloutItemWire::InterAgentCommunicationMetadata { payload } => {
+                Self::InterAgentCommunicationMetadata {
+                    trigger_turn: payload.trigger_turn,
+                }
+            }
+            RolloutItemWire::Compacted { payload } => Self::Compacted(payload.into_owned()),
+            RolloutItemWire::TurnContext { payload } => Self::TurnContext(payload.into_owned()),
+            RolloutItemWire::TokenUsageRecord { payload } => {
+                Self::TokenUsageRecord(payload.into_owned())
+            }
+            RolloutItemWire::WorldState { payload } => Self::WorldState(payload.into_owned()),
+            RolloutItemWire::RetainedContext { payload } => {
+                Self::RetainedContext(payload.into_owned())
+            }
+            RolloutItemWire::SecurityRiskScore { payload } => {
+                Self::SecurityRiskScore(payload.into_owned())
+            }
+            RolloutItemWire::EventMsg { payload } => Self::EventMsg(payload.into_owned()),
+            RolloutItemWire::RealtimeItem { payload } => Self::RealtimeItem(payload.into_owned()),
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, JsonSchema)]
+pub(super) struct InterAgentCommunicationMetadataPayload {
+    trigger_turn: bool,
+}
+
+#[derive(Serialize, Deserialize, JsonSchema)]
+pub(super) struct CompactedItemWire<'a> {
+    message: Cow<'a, str>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    replacement_history: Option<Vec<Cow<'a, ResponseItem>>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    replacement_history_metadata: Option<Vec<Cow<'a, CodexHarnessMetadata>>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    guardian_history: Option<Cow<'a, crate::GuardianHistoryCheckpoint>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    retained_context: Option<Cow<'a, crate::RetainedContext>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    mcp_resource_origins: Option<Cow<'a, McpResourceOriginCheckpoint>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    window_number: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    first_window_id: Option<Cow<'a, str>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    previous_window_id: Option<Cow<'a, str>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(with = "Option<String>")]
+    window_id: Option<WindowIdWire<'a>>,
+    #[serde(default)]
+    compaction_response_id: Option<Cow<'a, str>>,
+    #[serde(default)]
+    latest_token_usage_record: Option<Cow<'a, TokenUsageRecord>>,
+}
+
+impl<'a> From<&'a CompactedItem> for CompactedItemWire<'a> {
+    fn from(item: &'a CompactedItem) -> Self {
+        let replacement_history_metadata = item
+            .replacement_history
+            .as_ref()
+            .filter(|items| items.iter().any(|envelope| envelope.metadata.is_some()))
+            .map(|items| {
+                items
+                    .iter()
+                    .map(|envelope| match envelope.metadata.as_ref() {
+                        Some(metadata) => Cow::Borrowed(metadata),
+                        None => Cow::Owned(CodexHarnessMetadata::default()),
+                    })
+                    .collect()
+            });
+
+        Self {
+            message: Cow::Borrowed(&item.message),
+            replacement_history: item.replacement_history.as_ref().map(|items| {
+                items
+                    .iter()
+                    .map(|envelope| Cow::Borrowed(&envelope.item))
+                    .collect()
+            }),
+            replacement_history_metadata,
+            guardian_history: item.guardian_history.as_ref().map(Cow::Borrowed),
+            retained_context: item.retained_context.as_ref().map(Cow::Borrowed),
+            mcp_resource_origins: item.mcp_resource_origins.as_ref().map(Cow::Borrowed),
+            window_number: item.window_number,
+            first_window_id: item.first_window_id.as_deref().map(Cow::Borrowed),
+            previous_window_id: item.previous_window_id.as_deref().map(Cow::Borrowed),
+            window_id: item
+                .window_id
+                .as_deref()
+                .map(|window_id| WindowIdWire::Id(Cow::Borrowed(window_id))),
+            compaction_response_id: item.compaction_response_id.as_deref().map(Cow::Borrowed),
+            latest_token_usage_record: item.latest_token_usage_record.as_ref().map(Cow::Borrowed),
+        }
+    }
+}
+
+impl TryFrom<CompactedItemWire<'_>> for CompactedItem {
+    type Error = String;
+
+    fn try_from(item: CompactedItemWire<'_>) -> Result<Self, Self::Error> {
+        let replacement_history = match (
+            item.replacement_history,
+            item.replacement_history_metadata,
+        ) {
+            (Some(items), Some(metadata)) => {
+                let history_len = items.len();
+                let metadata_len = metadata.len();
+                if history_len != metadata_len {
+                    return Err(format!(
+                        "replacement_history_metadata has {metadata_len} entries for {history_len} history items"
+                    ));
+                }
+                Some(
+                    items
+                        .into_iter()
+                        .zip(metadata)
+                        .map(|(item, metadata)| ResponseItemEnvelope {
+                            item: item.into_owned(),
+                            metadata: Some(metadata.into_owned()),
+                        })
+                        .collect(),
+                )
+            }
+            (Some(items), None) => Some(
+                items
+                    .into_iter()
+                    .map(|item| ResponseItemEnvelope::new(item.into_owned()))
+                    .collect(),
+            ),
+            (None, Some(_)) => {
+                return Err("replacement_history_metadata requires replacement_history".to_string());
+            }
+            (None, None) => None,
+        };
+
+        let mut window_number = item.window_number;
+        let window_id = match item.window_id {
+            Some(WindowIdWire::Id(window_id)) => Some(window_id.into_owned()),
+            Some(WindowIdWire::LegacyWindowNumber(legacy_window_number)) => {
+                window_number.get_or_insert(legacy_window_number);
+                None
+            }
+            None => None,
+        };
+
+        Ok(Self {
+            message: item.message.into_owned(),
+            replacement_history,
+            guardian_history: item.guardian_history.map(Cow::into_owned),
+            retained_context: item.retained_context.map(Cow::into_owned),
+            mcp_resource_origins: item.mcp_resource_origins.map(Cow::into_owned),
+            window_number,
+            first_window_id: item.first_window_id.map(Cow::into_owned),
+            previous_window_id: item.previous_window_id.map(Cow::into_owned),
+            window_id,
+            compaction_response_id: item.compaction_response_id.map(Cow::into_owned),
+            latest_token_usage_record: item.latest_token_usage_record.map(Cow::into_owned),
+        })
+    }
+}
+
+// Older rollouts stored the numeric window number in `window_id`.
+#[derive(Serialize, Deserialize)]
+#[serde(untagged)]
+enum WindowIdWire<'a> {
+    Id(Cow<'a, str>),
+    LegacyWindowNumber(u64),
+}
diff --git a/codex-rs/history/src/tests.rs b/codex-rs/history/src/tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b04d2448db40b1b67827f2bf5196e5838d5903e3
--- /dev/null
+++ b/codex-rs/history/src/tests.rs
@@ -0,0 +1,829 @@
+use anyhow::Result;
+use codex_protocol::models::ConfigurationReasoning;
+use codex_protocol::openai_models::ReasoningEffort;
+use codex_protocol::protocol::ThreadSettingsSnapshot;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+use super::*;
+
+fn thread_settings_snapshot(disabled_plugin_ids: Vec<String>) -> Result<ThreadSettingsSnapshot> {
+    Ok(serde_json::from_value(json!({
+        "model": "gpt-5",
+        "model_provider_id": "openai",
+        "approval_policy": "never",
+        "approvals_reviewer": "user",
+        "permission_profile": codex_protocol::models::PermissionProfile::read_only(),
+        "cwd": std::env::current_dir()?,
+        "collaboration_mode": {
+            "mode": "default",
+            "settings": {
+                "model": "gpt-5",
+                "reasoning_effort": null,
+                "developer_instructions": null
+            }
+        },
+        "disabled_plugin_ids": disabled_plugin_ids
+    }))?)
+}
+
+#[test]
+fn latest_disabled_plugin_ids_preserves_owned_updates_and_clears() -> Result<()> {
+    let thread_id = ThreadId::new();
+    let ancestor_id = ThreadId::new();
+    let selected = thread_settings_snapshot(vec!["example@marketplace".to_string()])?;
+    let cleared = thread_settings_snapshot(Vec::new())?;
+    let item = |thread_id, thread_settings| {
+        RolloutItem::EventMsg(EventMsg::ThreadSettingsApplied(
+            codex_protocol::protocol::ThreadSettingsAppliedEvent {
+                thread_id,
+                thread_settings,
+            },
+        ))
+    };
+    let foreign_items = vec![
+        item(Some(ancestor_id), selected.clone()),
+        item(/*thread_id*/ None, selected.clone()),
+    ];
+    assert_eq!(latest_disabled_plugin_ids(&foreign_items, thread_id), None);
+
+    let mut history = vec![item(Some(thread_id), selected.clone())];
+    history.extend(foreign_items.clone());
+    assert_eq!(
+        latest_disabled_plugin_ids(&history, thread_id),
+        Some(selected.disabled_plugin_ids.as_slice())
+    );
+
+    history.push(item(Some(thread_id), cleared.clone()));
+    history.extend(foreign_items);
+    history.push(turn_context_with_disabled_plugins(Some(
+        selected.disabled_plugin_ids,
+    ))?);
+    assert_eq!(
+        latest_disabled_plugin_ids(&history, thread_id),
+        Some(cleared.disabled_plugin_ids.as_slice())
+    );
+    Ok(())
+}
+
+fn turn_context_with_disabled_plugins(
+    disabled_plugin_ids: Option<Vec<String>>,
+) -> Result<RolloutItem> {
+    let mut context: TurnContextItem = serde_json::from_value(json!({
+        "cwd": std::env::current_dir()?,
+        "approval_policy": "never",
+        "sandbox_policy": { "type": "danger-full-access" },
+        "model": "gpt-5",
+        "summary": "auto"
+    }))?;
+    context.disabled_plugin_ids = disabled_plugin_ids;
+    Ok(RolloutItem::TurnContext(context))
+}
+
+#[test]
+fn latest_disabled_plugin_ids_falls_back_only_to_latest_turn_context() -> Result<()> {
+    let thread_id = ThreadId::new();
+    let selected = vec!["example@marketplace".to_string()];
+    let mut history = vec![turn_context_with_disabled_plugins(Some(selected.clone()))?];
+    assert_eq!(
+        latest_disabled_plugin_ids(&history, thread_id),
+        Some(selected.as_slice())
+    );
+
+    history.push(RolloutItem::EventMsg(EventMsg::ThreadSettingsApplied(
+        codex_protocol::protocol::ThreadSettingsAppliedEvent {
+            thread_id: Some(ThreadId::new()),
+            thread_settings: thread_settings_snapshot(Vec::new())?,
+        },
+    )));
+    assert_eq!(
+        latest_disabled_plugin_ids(&history, thread_id),
+        Some(selected.as_slice())
+    );
+
+    let cleared = Vec::new();
+    history.push(turn_context_with_disabled_plugins(Some(cleared.clone()))?);
+    assert_eq!(
+        latest_disabled_plugin_ids(&history, thread_id),
+        Some(cleared.as_slice())
+    );
+
+    history.push(turn_context_with_disabled_plugins(
+        /*disabled_plugin_ids*/ None,
+    )?);
+    assert_eq!(latest_disabled_plugin_ids(&history, thread_id), None);
+    Ok(())
+}
+
+#[test]
+fn older_thread_settings_snapshot_defaults_disabled_plugins_to_empty() -> Result<()> {
+    let expected = thread_settings_snapshot(Vec::new())?;
+    let mut legacy = serde_json::to_value(&expected)?;
+    legacy
+        .as_object_mut()
+        .unwrap()
+        .remove("disabled_plugin_ids");
+
+    assert_eq!(
+        serde_json::from_value::<ThreadSettingsSnapshot>(legacy)?,
+        expected
+    );
+    Ok(())
+}
+
+#[test]
+fn response_item_envelope_accessors_preserve_item() {
+    let expected_item = ResponseItem::Message {
+        id: None,
+        role: "user".to_string(),
+        content: vec![ContentItem::InputText {
+            text: "hello".to_string(),
+        }],
+        phase: None,
+        internal_chat_message_metadata_passthrough: None,
+    };
+    let mut envelope = ResponseItemEnvelope::new(expected_item.clone());
+
+    assert_eq!(&*envelope, &expected_item);
+    let borrowed: &ResponseItem = envelope.borrow();
+    assert_eq!(borrowed, &expected_item);
+    let replacement_item = ResponseItem::Message {
+        id: None,
+        role: "assistant".to_string(),
+        content: vec![ContentItem::OutputText {
+            text: "goodbye".to_string(),
+        }],
+        phase: None,
+        internal_chat_message_metadata_passthrough: None,
+    };
+    *envelope = replacement_item.clone();
+
+    assert_eq!(envelope.into_item(), replacement_item);
+}
+
+#[test]
+/// Keeps legacy response-item rollout lines readable and byte-shape compatible.
+fn response_item_rollout_line_preserves_shape() -> Result<()> {
+    let legacy_line = json!({
+        "timestamp": "2025-01-03T12:00:00.000Z",
+        "ordinal": 7,
+        "type": "response_item",
+        "payload": {
+            "type": "message",
+            "role": "user",
+            "content": [{
+                "type": "input_text",
+                "text": "hello",
+            }],
+        },
+    });
+
+    let line = RolloutLine {
+        timestamp: "2025-01-03T12:00:00.000Z".to_string(),
+        ordinal: Some(7),
+        item: serde_json::from_value(legacy_line.clone())?,
+    };
+    let RolloutItem::ResponseItem(envelope) = &line.item else {
+        panic!("expected response item");
+    };
+    assert!(matches!(&envelope.item, ResponseItem::Message { .. }));
+    assert_eq!(envelope.metadata, None);
+    assert_eq!(serde_json::to_value(line)?, legacy_line);
+    Ok(())
+}
+
+#[test]
+/// Keeps harness metadata beside, rather than inside, response-item payloads.
+fn response_item_envelope_stores_metadata_beside_rollout_payload() -> Result<()> {
+    let response_item = response_message("developer");
+    let line = RolloutLine {
+        timestamp: "2025-01-03T12:00:00.000Z".to_string(),
+        ordinal: Some(7),
+        item: RolloutItem::ResponseItem(ResponseItemEnvelope {
+            item: response_item.clone(),
+            metadata: Some(CodexHarnessMetadata {
+                client_authored: true,
+                history_truncation_token_limit: Some(20_000),
+                inherited_user_message: true,
+                ..Default::default()
+            }),
+        }),
+    };
+    let serialized = serde_json::to_value(&line)?;
+
+    assert_eq!(
+        serialized,
+        json!({
+            "timestamp": "2025-01-03T12:00:00.000Z",
+            "ordinal": 7,
+            "type": "response_item",
+            "payload": response_item,
+            "metadata": {
+                "client_authored": true,
+                "fallback_token_limit_override": 20_000,
+                "inherited_user_message": true,
+            },
+        })
+    );
+    assert_eq!(serialized["payload"].get("metadata"), None);
+
+    let restored = serde_json::from_value(serialized)?;
+    let RolloutItem::ResponseItem(envelope) = restored else {
+        panic!("expected response item");
+    };
+    assert_eq!(
+        envelope.metadata,
+        Some(CodexHarnessMetadata {
+            client_authored: true,
+            history_truncation_token_limit: Some(20_000),
+            inherited_user_message: true,
+            ..Default::default()
+        })
+    );
+    Ok(())
+}
+
+#[test]
+fn response_item_envelope_preserves_harness_authored_configuration_provenance() -> Result<()> {
+    let response_item = ResponseItem::ConfigurationUpdate {
+        reasoning: ConfigurationReasoning {
+            effort: ReasoningEffort::High,
+        },
+    };
+    let metadata = CodexHarnessMetadata {
+        harness_authored_configuration: true,
+        ..Default::default()
+    };
+    let rollout_item = RolloutItem::ResponseItem(ResponseItemEnvelope {
+        item: response_item.clone(),
+        metadata: Some(metadata.clone()),
+    });
+
+    let serialized = serde_json::to_value(&rollout_item)?;
+    assert_eq!(
+        serialized,
+        json!({
+            "type": "response_item",
+            "payload": {
+                "type": "configuration_update",
+                "reasoning": { "effort": "high" },
+            },
+            "metadata": {
+                "client_authored": false,
+                "harness_authored_configuration": true,
+            },
+        })
+    );
+
+    let restored = serde_json::from_value::<RolloutItem>(serialized)?;
+    let RolloutItem::ResponseItem(envelope) = restored else {
+        panic!("expected response item");
+    };
+    assert_eq!(
+        envelope,
+        ResponseItemEnvelope {
+            item: response_item,
+            metadata: Some(metadata),
+        }
+    );
+    Ok(())
+}
+
+#[test]
+/// Keeps future metadata fields from making older binaries reject persisted items.
+fn response_item_envelope_ignores_unknown_harness_metadata_fields() -> Result<()> {
+    let line = serde_json::from_value(json!({
+        "timestamp": "2025-01-03T12:00:00.000Z",
+        "ordinal": 7,
+        "type": "response_item",
+        "payload": {
+            "type": "message",
+            "role": "user",
+            "content": [{
+                "type": "input_text",
+                "text": "hello",
+            }],
+        },
+        "metadata": {
+            "future_field": "value",
+        },
+    }))?;
+
+    let RolloutItem::ResponseItem(envelope) = line else {
+        panic!("expected response item");
+    };
+    assert_eq!(envelope.metadata, Some(CodexHarnessMetadata::default()));
+
+    let compacted = serde_json::from_value::<CompactedItem>(json!({
+        "message": "summary",
+        "replacement_history": [response_message("user")],
+        "replacement_history_metadata": [{ "future_field": "value" }],
+    }))?;
+    assert_eq!(
+        compacted.replacement_history.expect("replacement history")[0].metadata,
+        Some(CodexHarnessMetadata::default())
+    );
+    Ok(())
+}
+
+#[test]
+/// Keeps legacy compacted replacement histories readable while adding nullable checkpoints.
+fn response_item_replacement_history_accepts_legacy_shape() -> Result<()> {
+    let legacy_item = json!({
+        "message": "summary",
+        "replacement_history": [{
+            "type": "message",
+            "role": "user",
+            "content": [{
+                "type": "input_text",
+                "text": "hello",
+            }],
+        }],
+    });
+
+    let item = serde_json::from_value::<CompactedItem>(legacy_item.clone())?;
+    let replacement_history = item
+        .replacement_history
+        .as_ref()
+        .expect("replacement history");
+    assert!(matches!(
+        &replacement_history[0].item,
+        ResponseItem::Message { .. }
+    ));
+    assert_eq!(replacement_history[0].metadata, None);
+    let mut expected_item = legacy_item;
+    expected_item["compaction_response_id"] = json!(null);
+    expected_item["latest_token_usage_record"] = json!(null);
+    assert_eq!(serde_json::to_value(item)?, expected_item);
+    Ok(())
+}
+
+#[test]
+/// Stores complete aligned checkpoint metadata without modifying response items.
+fn compacted_replacement_history_stores_metadata_in_an_aligned_sidecar() -> Result<()> {
+    let developer_message = response_message("developer");
+    let compaction_item = ResponseItem::Compaction {
+        id: None,
+        encrypted_content: "opaque".to_string(),
+        internal_chat_message_metadata_passthrough: None,
+    };
+    let item = CompactedItem {
+        message: "summary".to_string(),
+        replacement_history: Some(vec![
+            ResponseItemEnvelope {
+                item: developer_message.clone(),
+                metadata: Some(CodexHarnessMetadata {
+                    client_authored: true,
+                    ..Default::default()
+                }),
+            },
+            ResponseItemEnvelope::new(compaction_item.clone()),
+        ]),
+        retained_context: None,
+        guardian_history: None,
+        mcp_resource_origins: None,
+        window_number: None,
+        first_window_id: None,
+        previous_window_id: None,
+        window_id: None,
+        compaction_response_id: None,
+        latest_token_usage_record: None,
+    };
+
+    let serialized = serde_json::to_value(item)?;
+    assert_eq!(
+        serialized,
+        json!({
+            "message": "summary",
+            "replacement_history": [developer_message, compaction_item],
+            "replacement_history_metadata": [
+                { "client_authored": true },
+                { "client_authored": false },
+            ],
+            "compaction_response_id": null,
+            "latest_token_usage_record": null,
+        })
+    );
+
+    let restored = serde_json::from_value::<CompactedItem>(serialized)?;
+    assert_eq!(
+        restored.replacement_history,
+        Some(vec![
+            ResponseItemEnvelope {
+                item: developer_message,
+                metadata: Some(CodexHarnessMetadata {
+                    client_authored: true,
+                    ..Default::default()
+                }),
+            },
+            ResponseItemEnvelope {
+                item: compaction_item,
+                metadata: Some(CodexHarnessMetadata::default()),
+            },
+        ])
+    );
+    Ok(())
+}
+
+#[test]
+/// Rejects checkpoint sidecars that cannot be paired unambiguously with history.
+fn compacted_replacement_history_rejects_misaligned_metadata() {
+    let malformed_items = [
+        json!({
+            "message": "summary",
+            "replacement_history": [response_message("user")],
+            "replacement_history_metadata": [],
+        }),
+        json!({
+            "message": "summary",
+            "replacement_history": [response_message("user")],
+            "replacement_history_metadata": [{}, {}],
+        }),
+        json!({
+            "message": "summary",
+            "replacement_history_metadata": [{}],
+        }),
+    ];
+
+    for malformed in malformed_items {
+        let error = serde_json::from_value::<CompactedItem>(malformed)
+            .expect_err("misaligned checkpoint metadata must be rejected");
+        assert!(
+            error.to_string().contains("replacement_history_metadata"),
+            "error: {error}"
+        );
+    }
+}
+
+#[test]
+/// Keeps annotated checkpoints readable by binaries expecting raw response items.
+fn compacted_metadata_remains_compatible_with_legacy_response_item_readers() -> Result<()> {
+    #[derive(Deserialize)]
+    #[serde(tag = "type", content = "payload", rename_all = "snake_case")]
+    enum LegacyRolloutItem {
+        ResponseItem(Box<ResponseItem>),
+        Compacted(LegacyCompactedItem),
+    }
+
+    #[derive(Deserialize)]
+    struct LegacyCompactedItem {
+        replacement_history: Vec<ResponseItem>,
+    }
+
+    let response_item = response_message("developer");
+    let envelope = ResponseItemEnvelope {
+        item: response_item.clone(),
+        metadata: Some(CodexHarnessMetadata {
+            client_authored: true,
+            ..Default::default()
+        }),
+    };
+    let response_line = serde_json::to_value(RolloutItem::ResponseItem(envelope.clone()))?;
+    let LegacyRolloutItem::ResponseItem(legacy_response) =
+        serde_json::from_value::<LegacyRolloutItem>(response_line)?
+    else {
+        panic!("expected legacy response item");
+    };
+    assert_eq!(*legacy_response, response_item);
+
+    let checkpoint = crate::GuardianHistoryCheckpoint(vec![response_item.clone()]);
+    let compacted_line = serde_json::to_value(RolloutItem::Compacted(CompactedItem {
+        message: "summary".to_string(),
+        replacement_history: Some(vec![envelope]),
+        retained_context: None,
+        guardian_history: Some(checkpoint.clone()),
+        mcp_resource_origins: Some(McpResourceOriginCheckpoint::default()),
+        window_number: None,
+        first_window_id: None,
+        previous_window_id: None,
+        window_id: None,
+        compaction_response_id: None,
+        latest_token_usage_record: None,
+    }))?;
+
+    let restored: RolloutItem = serde_json::from_value(compacted_line.clone())?;
+    let RolloutItem::Compacted(restored) = restored else {
+        panic!("expected compacted item");
+    };
+    assert_eq!(restored.guardian_history, Some(checkpoint));
+    let LegacyRolloutItem::Compacted(legacy) =
+        serde_json::from_value::<LegacyRolloutItem>(compacted_line)?
+    else {
+        panic!("expected legacy compacted item");
+    };
+    assert_eq!(legacy.replacement_history, vec![response_item]);
+    Ok(())
+}
+
+#[test]
+/// Preserves the established tagged payload representation for every rollout variant.
+fn rollout_item_variants_preserve_existing_payload_shapes() -> Result<()> {
+    let cwd = std::env::current_dir()?;
+    let fixtures = [
+        json!({
+            "type": "session_meta",
+            "payload": SessionMetaLine {
+                meta: SessionMeta::default(),
+                git: None,
+            },
+        }),
+        json!({
+            "type": "response_item",
+            "payload": response_message("user"),
+        }),
+        json!({
+            "type": "inter_agent_communication",
+            "payload": {
+                "author": "/root",
+                "recipient": "/root/child",
+                "other_recipients": [],
+                "content": "hello",
+                "trigger_turn": false,
+            },
+        }),
+        json!({
+            "type": "inter_agent_communication_metadata",
+            "payload": { "trigger_turn": true },
+        }),
+        json!({
+            "type": "compacted",
+            "payload": {
+                "message": "summary",
+                "compaction_response_id": null,
+                "latest_token_usage_record": null,
+            },
+        }),
+        json!({
+            "type": "turn_context",
+            "payload": {
+                "cwd": cwd,
+                "approval_policy": "never",
+                "sandbox_policy": { "type": "danger-full-access" },
+                "model": "gpt-5",
+                "summary": "auto",
+            },
+        }),
+        json!({
+            "type": "token_usage_record",
+            "payload": {
+                "thread_id": "0195cda5-433d-7f9a-9d7b-a9f15b60c2e2",
+                "turn_id": "turn-1",
+                "session_id": "0195cda5-433d-7f9a-9d7b-a9f15b60c2e2",
+                "root_turn_id": "turn-1",
+                "response_id": "response-1",
+                "usage": {
+                    "input_tokens": 10,
+                    "cached_input_tokens": 2,
+                    "cache_write_input_tokens": 0,
+                    "output_tokens": 3,
+                    "reasoning_output_tokens": 1,
+                    "total_tokens": 13,
+                },
+                "turn_token_usage": {
+                    "input_tokens": 10,
+                    "cached_input_tokens": 2,
+                    "cache_write_input_tokens": 0,
+                    "output_tokens": 3,
+                    "reasoning_output_tokens": 1,
+                    "total_tokens": 13,
+                },
+                "thread_token_usage": {
+                    "input_tokens": 10,
+                    "cached_input_tokens": 2,
+                    "cache_write_input_tokens": 0,
+                    "output_tokens": 3,
+                    "reasoning_output_tokens": 1,
+                    "total_tokens": 13,
+                },
+            },
+        }),
+        json!({
+            "type": "world_state",
+            "payload": { "full": true, "state": { "cwd": "/tmp" } },
+        }),
+        json!({
+            "type": "security_risk_score",
+            "payload": {
+                "scores": {
+                    "action_risk": 0.92,
+                    "data_exfiltration": 0.31,
+                },
+            },
+        }),
+        json!({
+            "type": "event_msg",
+            "payload": { "type": "warning", "message": "heads up" },
+        }),
+        json!({
+            "type": "retained_context",
+            "payload": {
+                "type": "verified_answer",
+                "turn_id": "turn-1",
+                "call_id": "ask-1",
+                "questions": [{"question": "Publish?", "answer": "Only privately."}],
+            },
+        }),
+        json!({
+            "type": "realtime_item",
+            "payload": {
+                "id": "segment-1",
+                "realtime_session_id": "session-1",
+                "type": "transcript_segment",
+                "role": "assistant",
+                "text": "hello",
+            },
+        }),
+    ];
+
+    for expected in fixtures {
+        let item = serde_json::from_value::<RolloutItem>(expected.clone())?;
+        assert_eq!(serde_json::to_value(item)?, expected);
+    }
+    Ok(())
+}
+
+#[test]
+/// Keeps the generated schema aligned with each variant's actual persisted shape.
+fn rollout_item_schema_matches_tagged_payload_and_sibling_metadata() -> Result<()> {
+    let schema = serde_json::to_value(schemars::schema_for!(RolloutItem))?;
+    let variants = schema["oneOf"].as_array().expect("rollout variants");
+    assert_eq!(variants.len(), 12);
+
+    for variant in variants {
+        let required = variant["required"].as_array().expect("required fields");
+        assert!(required.contains(&json!("type")), "schema: {variant}");
+        assert!(required.contains(&json!("payload")), "schema: {variant}");
+    }
+
+    let response_item = variants
+        .iter()
+        .find(|variant| variant["properties"]["type"]["enum"] == json!(["response_item"]))
+        .expect("response item schema");
+    assert!(response_item["properties"].get("metadata").is_some());
+    assert_eq!(
+        response_item["properties"]["payload"]["$ref"],
+        json!("#/definitions/ResponseItem")
+    );
+
+    let compacted = &schema["definitions"]["CompactedItem"];
+    assert_eq!(
+        compacted["properties"]["replacement_history"]["items"]["$ref"],
+        json!("#/definitions/ResponseItem")
+    );
+    assert_eq!(
+        compacted["properties"]["replacement_history_metadata"]["items"]["$ref"],
+        json!("#/definitions/CodexHarnessMetadata")
+    );
+    let required = compacted["required"].as_array().expect("required fields");
+    assert!(!required.contains(&json!("replacement_history")));
+    assert!(!required.contains(&json!("replacement_history_metadata")));
+    Ok(())
+}
+
+fn response_message(role: &str) -> ResponseItem {
+    ResponseItem::Message {
+        id: None,
+        role: role.to_string(),
+        content: vec![ContentItem::InputText {
+            text: "hello".to_string(),
+        }],
+        phase: None,
+        internal_chat_message_metadata_passthrough: None,
+    }
+}
+
+#[test]
+/// Preserves the stored compacted-item window metadata shape.
+fn compacted_item_serializes_window_number_and_id() -> Result<()> {
+    let item = CompactedItem {
+        message: "summary".to_string(),
+        replacement_history: None,
+        retained_context: None,
+        guardian_history: None,
+        mcp_resource_origins: None,
+        window_number: Some(3),
+        first_window_id: Some("019b3f6e-0000-7000-8000-000000000001".to_string()),
+        previous_window_id: Some("019b3f6e-0000-7000-8000-000000000002".to_string()),
+        window_id: Some("019b3f6e-7a10-7cc3-8b6e-1d09e2f7a001".to_string()),
+        compaction_response_id: None,
+        latest_token_usage_record: None,
+    };
+
+    assert_eq!(
+        serde_json::to_value(item)?,
+        json!({
+            "message": "summary",
+            "window_number": 3,
+            "first_window_id": "019b3f6e-0000-7000-8000-000000000001",
+            "previous_window_id": "019b3f6e-0000-7000-8000-000000000002",
+            "window_id": "019b3f6e-7a10-7cc3-8b6e-1d09e2f7a001",
+            "compaction_response_id": null,
+            "latest_token_usage_record": null,
+        })
+    );
+    Ok(())
+}
+
+#[test]
+/// Keeps legacy numeric window IDs readable in stored compacted items.
+fn compacted_item_migrates_legacy_numeric_window_id() -> Result<()> {
+    let item = serde_json::from_value::<CompactedItem>(json!({
+        "message": "summary",
+        "window_id": 3,
+    }))?;
+
+    assert_eq!(
+        item,
+        CompactedItem {
+            message: "summary".to_string(),
+            replacement_history: None,
+            retained_context: None,
+            guardian_history: None,
+            mcp_resource_origins: None,
+            window_number: Some(3),
+            first_window_id: None,
+            previous_window_id: None,
+            window_id: None,
+            compaction_response_id: None,
+            latest_token_usage_record: None,
+        }
+    );
+    Ok(())
+}
+
+#[test]
+fn copied_history_uses_persisted_history_mode() -> Result<()> {
+    let thread_id = ThreadId::from_string("00000000-0000-0000-0000-000000000001")?;
+    let session_meta = RolloutItem::SessionMeta(SessionMetaLine {
+        meta: SessionMeta {
+            session_id: thread_id.into(),
+            id: thread_id,
+            history_mode: ThreadHistoryMode::Legacy,
+            ..SessionMeta::default()
+        },
+        git: None,
+    });
+    let history = InitialHistory::Resumed(ResumedHistory {
+        conversation_id: thread_id,
+        history: Arc::new(vec![session_meta.clone()]),
+        rollout_path: None,
+    });
+
+    assert_eq!(
+        history.get_history_mode(ThreadHistoryMode::Paginated),
+        ThreadHistoryMode::Legacy
+    );
+    assert_eq!(
+        InitialHistory::Forked(vec![session_meta]).get_history_mode(ThreadHistoryMode::Paginated),
+        ThreadHistoryMode::Legacy
+    );
+    assert_eq!(
+        InitialHistory::New.get_history_mode(ThreadHistoryMode::Paginated),
+        ThreadHistoryMode::Paginated
+    );
+    assert_eq!(
+        InitialHistory::Resumed(ResumedHistory {
+            conversation_id: thread_id,
+            history: Arc::new(Vec::new()),
+            rollout_path: None,
+        })
+        .get_history_mode(ThreadHistoryMode::Paginated),
+        ThreadHistoryMode::Paginated
+    );
+    Ok(())
+}
+
+#[test]
+fn multi_agent_version_uses_newest_present_session_meta_value() -> Result<()> {
+    let thread_id = ThreadId::from_string("67e55044-10b1-426f-9247-bb680e5fe0c8")?;
+    let older_meta = SessionMetaLine {
+        meta: SessionMeta {
+            session_id: thread_id.into(),
+            id: thread_id,
+            multi_agent_version: Some(MultiAgentVersion::V2),
+            ..Default::default()
+        },
+        git: None,
+    };
+    let newer_meta_without_version = SessionMetaLine {
+        meta: SessionMeta {
+            session_id: thread_id.into(),
+            id: thread_id,
+            multi_agent_version: None,
+            ..Default::default()
+        },
+        git: None,
+    };
+
+    assert_eq!(
+        multi_agent_version_from_items(
+            &[
+                RolloutItem::SessionMeta(older_meta),
+                RolloutItem::SessionMeta(newer_meta_without_version),
+            ],
+            Some(thread_id),
+        ),
+        Some(MultiAgentVersion::V2)
+    );
+    Ok(())
+}
diff --git a/codex-rs/hooks/schema/generated/interrupt.command.input.schema.json b/codex-rs/hooks/schema/generated/interrupt.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..e0ac2a96bb719511d157dd787796e2466524a1fd
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/interrupt.command.input.schema.json
@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "Interrupt",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "session_id",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "interrupt.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/interrupt.command.output.schema.json b/codex-rs/hooks/schema/generated/interrupt.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..4d039577456e36d226675a58e1f4ac2182b7ced0
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/interrupt.command.output.schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "interrupt.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/permission-request.command.input.schema.json b/codex-rs/hooks/schema/generated/permission-request.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..9ee8996db169d55b0da44d7efbb57af76676c2fe
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/permission-request.command.input.schema.json
@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "PermissionRequest",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tool_input": true,
+    "tool_name": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "session_id",
+    "tool_input",
+    "tool_name",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "permission-request.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json b/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..347820f7ed6059b654dc8210c3b3c016d61d2d4a
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json
@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "PermissionRequestBehaviorWire": {
+      "enum": [
+        "allow",
+        "deny"
+      ],
+      "type": "string"
+    },
+    "PermissionRequestDecisionWire": {
+      "additionalProperties": false,
+      "properties": {
+        "behavior": {
+          "$ref": "#/definitions/PermissionRequestBehaviorWire"
+        },
+        "interrupt": {
+          "default": false,
+          "description": "Reserved for future short-circuiting semantics.\n\nPermissionRequest hooks currently fail closed if this field is `true`.",
+          "type": "boolean"
+        },
+        "message": {
+          "default": null,
+          "type": "string"
+        },
+        "updatedInput": {
+          "default": null,
+          "description": "Reserved for a future input-rewrite capability.\n\nPermissionRequest hooks currently fail closed if this field is present."
+        },
+        "updatedPermissions": {
+          "default": null,
+          "description": "Reserved for a future permission-rewrite capability.\n\nPermissionRequest hooks currently fail closed if this field is present."
+        }
+      },
+      "required": [
+        "behavior"
+      ],
+      "type": "object"
+    },
+    "PermissionRequestHookSpecificOutputWire": {
+      "additionalProperties": false,
+      "properties": {
+        "decision": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/PermissionRequestDecisionWire"
+            }
+          ],
+          "default": null
+        },
+        "hookEventName": {
+          "const": "PermissionRequest",
+          "type": "string"
+        }
+      },
+      "required": [
+        "hookEventName"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "hookSpecificOutput": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/PermissionRequestHookSpecificOutputWire"
+        }
+      ],
+      "default": null
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "permission-request.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/post-compact.command.input.schema.json b/codex-rs/hooks/schema/generated/post-compact.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..3131f3a776bea3b307eefb499f7809dc8f092efe
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/post-compact.command.input.schema.json
@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "PostCompact",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "trigger": {
+      "enum": [
+        "manual",
+        "auto"
+      ],
+      "type": "string"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "session_id",
+    "transcript_path",
+    "trigger",
+    "turn_id"
+  ],
+  "title": "post-compact.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/post-compact.command.output.schema.json b/codex-rs/hooks/schema/generated/post-compact.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..0221ac29b445d8f5e493ca8420ad168fff03559c
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/post-compact.command.output.schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "post-compact.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/post-tool-use.command.input.schema.json b/codex-rs/hooks/schema/generated/post-tool-use.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..f92af1dd3249ddf3511ef707c4310329e5b85c80
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/post-tool-use.command.input.schema.json
@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "PostToolUse",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tool_input": true,
+    "tool_name": {
+      "type": "string"
+    },
+    "tool_response": true,
+    "tool_use_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "session_id",
+    "tool_input",
+    "tool_name",
+    "tool_response",
+    "tool_use_id",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "post-tool-use.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json b/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..011f887265f21b549d029e96932b75b23dde8107
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json
@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "BlockDecisionWire": {
+      "enum": [
+        "block"
+      ],
+      "type": "string"
+    },
+    "PostToolUseHookSpecificOutputWire": {
+      "additionalProperties": false,
+      "properties": {
+        "additionalContext": {
+          "default": null,
+          "type": "string"
+        },
+        "hookEventName": {
+          "const": "PostToolUse",
+          "type": "string"
+        },
+        "updatedMCPToolOutput": {
+          "default": null
+        }
+      },
+      "required": [
+        "hookEventName"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "decision": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/BlockDecisionWire"
+        }
+      ],
+      "default": null
+    },
+    "hookSpecificOutput": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/PostToolUseHookSpecificOutputWire"
+        }
+      ],
+      "default": null
+    },
+    "reason": {
+      "default": null,
+      "type": "string"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "post-tool-use.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/pre-compact.command.input.schema.json b/codex-rs/hooks/schema/generated/pre-compact.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..54e9a8b7f4f7b3ac642444264e6451c215431a67
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/pre-compact.command.input.schema.json
@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "PreCompact",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "trigger": {
+      "enum": [
+        "manual",
+        "auto"
+      ],
+      "type": "string"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "session_id",
+    "transcript_path",
+    "trigger",
+    "turn_id"
+  ],
+  "title": "pre-compact.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/pre-compact.command.output.schema.json b/codex-rs/hooks/schema/generated/pre-compact.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..644cd1a8b4a9443b25b995ad5ea4204a63959c52
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/pre-compact.command.output.schema.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "pre-compact.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/pre-tool-use.command.input.schema.json b/codex-rs/hooks/schema/generated/pre-tool-use.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..48dd4c571010a664e40cb174123c3bc746f12e34
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/pre-tool-use.command.input.schema.json
@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "PreToolUse",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tool_input": true,
+    "tool_name": {
+      "type": "string"
+    },
+    "tool_use_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "session_id",
+    "tool_input",
+    "tool_name",
+    "tool_use_id",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "pre-tool-use.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json b/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..6730b27fd4fc80f8075d64346a554a1cfc94470a
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json
@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "PreToolUseDecisionWire": {
+      "enum": [
+        "approve",
+        "block"
+      ],
+      "type": "string"
+    },
+    "PreToolUseHookSpecificOutputWire": {
+      "additionalProperties": false,
+      "properties": {
+        "additionalContext": {
+          "default": null,
+          "type": "string"
+        },
+        "hookEventName": {
+          "const": "PreToolUse",
+          "type": "string"
+        },
+        "permissionDecision": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/PreToolUsePermissionDecisionWire"
+            }
+          ],
+          "default": null
+        },
+        "permissionDecisionReason": {
+          "default": null,
+          "type": "string"
+        },
+        "updatedInput": {
+          "default": null
+        }
+      },
+      "required": [
+        "hookEventName"
+      ],
+      "type": "object"
+    },
+    "PreToolUsePermissionDecisionWire": {
+      "enum": [
+        "allow",
+        "deny",
+        "ask"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "decision": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/PreToolUseDecisionWire"
+        }
+      ],
+      "default": null
+    },
+    "hookSpecificOutput": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/PreToolUseHookSpecificOutputWire"
+        }
+      ],
+      "default": null
+    },
+    "reason": {
+      "default": null,
+      "type": "string"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "pre-tool-use.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/session-end.command.input.schema.json b/codex-rs/hooks/schema/generated/session-end.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..de87f368726375e8a0732466f6ea6a431ff5b324
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/session-end.command.input.schema.json
@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "SessionEnd",
+      "type": "string"
+    },
+    "reason": {
+      "const": "other",
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "reason",
+    "session_id",
+    "transcript_path"
+  ],
+  "title": "session-end.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/session-start.command.input.schema.json b/codex-rs/hooks/schema/generated/session-start.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..70eb76ec923c321b95d225812e16d4e7f52a9cc2
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/session-start.command.input.schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "SessionStart",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "source": {
+      "enum": [
+        "startup",
+        "resume",
+        "clear",
+        "compact",
+        "fork"
+      ],
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "session_id",
+    "source",
+    "transcript_path"
+  ],
+  "title": "session-start.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/session-start.command.output.schema.json b/codex-rs/hooks/schema/generated/session-start.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..1dd51e001030cb6b260114da3461cbe9d77ba944
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/session-start.command.output.schema.json
@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "SessionStartHookSpecificOutputWire": {
+      "additionalProperties": false,
+      "properties": {
+        "additionalContext": {
+          "default": null,
+          "type": "string"
+        },
+        "hookEventName": {
+          "const": "SessionStart",
+          "type": "string"
+        }
+      },
+      "required": [
+        "hookEventName"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "hookSpecificOutput": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/SessionStartHookSpecificOutputWire"
+        }
+      ],
+      "default": null
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "session-start.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/stop.command.input.schema.json b/codex-rs/hooks/schema/generated/stop.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..dbd4a3f648071bee1af24758e9596e11ab78c782
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/stop.command.input.schema.json
@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "Stop",
+      "type": "string"
+    },
+    "last_assistant_message": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "stop_hook_active": {
+      "type": "boolean"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "last_assistant_message",
+    "model",
+    "permission_mode",
+    "session_id",
+    "stop_hook_active",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "stop.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/stop.command.output.schema.json b/codex-rs/hooks/schema/generated/stop.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..a2bac59cd12a7a02de5ce5b259e68263cba74b2f
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/stop.command.output.schema.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "BlockDecisionWire": {
+      "enum": [
+        "block"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "decision": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/BlockDecisionWire"
+        }
+      ],
+      "default": null
+    },
+    "reason": {
+      "default": null,
+      "description": "Claude requires `reason` when `decision` is `block`; we enforce that semantic rule during output parsing rather than in the JSON schema.",
+      "type": "string"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "stop.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/subagent-start.command.input.schema.json b/codex-rs/hooks/schema/generated/subagent-start.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..2f6edd60387aee5af5573e3683702d94773e2dd1
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/subagent-start.command.input.schema.json
@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "SubagentStart",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "agent_id",
+    "agent_type",
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "session_id",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "subagent-start.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json b/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..02493da98baeb2e789aa055b3b43d1cf03f3e300
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json
@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "SubagentStartHookSpecificOutputWire": {
+      "additionalProperties": false,
+      "properties": {
+        "additionalContext": {
+          "default": null,
+          "type": "string"
+        },
+        "hookEventName": {
+          "const": "SubagentStart",
+          "type": "string"
+        }
+      },
+      "required": [
+        "hookEventName"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "hookSpecificOutput": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/SubagentStartHookSpecificOutputWire"
+        }
+      ],
+      "default": null
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "subagent-start.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json b/codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..19646db1d2b18d2017eaa39056326bbfa66a814c
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json
@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "SubagentStop",
+      "type": "string"
+    },
+    "last_assistant_message": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "stop_hook_active": {
+      "type": "boolean"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "agent_id",
+    "agent_transcript_path",
+    "agent_type",
+    "cwd",
+    "hook_event_name",
+    "last_assistant_message",
+    "model",
+    "permission_mode",
+    "session_id",
+    "stop_hook_active",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "subagent-stop.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json b/codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..0cb1dd2a5701ba07d9ab73464a9968279d2065d0
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "BlockDecisionWire": {
+      "enum": [
+        "block"
+      ],
+      "type": "string"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "decision": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/BlockDecisionWire"
+        }
+      ],
+      "default": null
+    },
+    "reason": {
+      "default": null,
+      "description": "Claude requires `reason` when `decision` is `block`; we enforce that semantic rule during output parsing rather than in the JSON schema.",
+      "type": "string"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "subagent-stop.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/user-prompt-submit.command.input.schema.json b/codex-rs/hooks/schema/generated/user-prompt-submit.command.input.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..6a10a9f75c19720b0863d11d7d7d80f190e8eacd
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/user-prompt-submit.command.input.schema.json
@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "NullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "properties": {
+    "agent_id": {
+      "type": "string"
+    },
+    "agent_type": {
+      "type": "string"
+    },
+    "cwd": {
+      "type": "string"
+    },
+    "hook_event_name": {
+      "const": "UserPromptSubmit",
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "permission_mode": {
+      "enum": [
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions"
+      ],
+      "type": "string"
+    },
+    "prompt": {
+      "type": "string"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "transcript_path": {
+      "$ref": "#/definitions/NullableString"
+    },
+    "turn_id": {
+      "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "cwd",
+    "hook_event_name",
+    "model",
+    "permission_mode",
+    "prompt",
+    "session_id",
+    "transcript_path",
+    "turn_id"
+  ],
+  "title": "user-prompt-submit.command.input",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json b/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..97875c108b9345bbe5518bb1968ce12c67db7484
--- /dev/null
+++ b/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json
@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "definitions": {
+    "BlockDecisionWire": {
+      "enum": [
+        "block"
+      ],
+      "type": "string"
+    },
+    "UserPromptSubmitHookSpecificOutputWire": {
+      "additionalProperties": false,
+      "properties": {
+        "additionalContext": {
+          "default": null,
+          "type": "string"
+        },
+        "hookEventName": {
+          "const": "UserPromptSubmit",
+          "type": "string"
+        }
+      },
+      "required": [
+        "hookEventName"
+      ],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "continue": {
+      "default": true,
+      "type": "boolean"
+    },
+    "decision": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/BlockDecisionWire"
+        }
+      ],
+      "default": null
+    },
+    "hookSpecificOutput": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/UserPromptSubmitHookSpecificOutputWire"
+        }
+      ],
+      "default": null
+    },
+    "reason": {
+      "default": null,
+      "type": "string"
+    },
+    "stopReason": {
+      "default": null,
+      "type": "string"
+    },
+    "suppressOutput": {
+      "default": false,
+      "type": "boolean"
+    },
+    "systemMessage": {
+      "default": null,
+      "type": "string"
+    }
+  },
+  "title": "user-prompt-submit.command.output",
+  "type": "object"
+}
\ No newline at end of file
diff --git a/codex-rs/hooks/src/bin/write_hooks_schema_fixtures.rs b/codex-rs/hooks/src/bin/write_hooks_schema_fixtures.rs
new file mode 100644
index 0000000000000000000000000000000000000000..303b561bf342e45182343f0e48cfc77540fd5b4f
--- /dev/null
+++ b/codex-rs/hooks/src/bin/write_hooks_schema_fixtures.rs
@@ -0,0 +1,9 @@
+use std::path::PathBuf;
+
+fn main() -> anyhow::Result<()> {
+    let schema_root = std::env::args_os()
+        .nth(1)
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("schema"));
+    codex_hooks::write_schema_fixtures(&schema_root)
+}
diff --git a/codex-rs/hooks/src/config_rules.rs b/codex-rs/hooks/src/config_rules.rs
new file mode 100644
index 0000000000000000000000000000000000000000..050932ecbbff46ef87a66753496e8036d5ed47e5
--- /dev/null
+++ b/codex-rs/hooks/src/config_rules.rs
@@ -0,0 +1,259 @@
+use std::collections::HashMap;
+
+use codex_config::ConfigLayerSource;
+use codex_config::ConfigLayerStack;
+use codex_config::HookStateToml;
+use codex_config::TomlValue;
+
+/// Build effective hook state from config layers that are allowed to override
+/// user preferences.
+///
+/// This intentionally reads only user and session flag layers, including
+/// disabled layers, to match the skills config behavior. Project, managed, and
+/// plugin layers can discover hooks, but they do not get to write user hook
+/// state.
+pub fn hook_states_from_stack(
+    config_layer_stack: Option<&ConfigLayerStack>,
+) -> HashMap<String, HookStateToml> {
+    let Some(config_layer_stack) = config_layer_stack else {
+        return HashMap::new();
+    };
+
+    let mut states: HashMap<String, HookStateToml> = HashMap::new();
+    for layer in config_layer_stack.all_layers_low_to_high() {
+        if !matches!(
+            layer.name,
+            ConfigLayerSource::User { .. } | ConfigLayerSource::SessionFlags
+        ) {
+            continue;
+        }
+
+        let Some(state_value) = layer
+            .config
+            .get("hooks")
+            .and_then(|hooks| hooks.get("state"))
+        else {
+            continue;
+        };
+        let TomlValue::Table(state_by_key) = state_value else {
+            continue;
+        };
+
+        for (key, state_value) in state_by_key {
+            let state: HookStateToml = match state_value.clone().try_into() {
+                Ok(state) => state,
+                Err(_) => {
+                    continue;
+                }
+            };
+            let key = key.trim();
+            if key.is_empty() {
+                continue;
+            }
+            // Later layers win field-by-field so a future per-hook state write
+            // does not accidentally erase an existing enablement override.
+            let effective_state = states.entry(key.to_string()).or_default();
+            if let Some(enabled) = state.enabled {
+                effective_state.enabled = Some(enabled);
+            }
+            if let Some(trusted_hash) = state.trusted_hash {
+                effective_state.trusted_hash = Some(trusted_hash);
+            }
+        }
+    }
+
+    states
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_config::ConfigLayerEntry;
+    use codex_config::TomlValue;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn hook_states_from_stack_respects_layer_precedence() {
+        let key = "file:/tmp/hooks.json:pre_tool_use:0:0";
+        let stack = ConfigLayerStack::new(
+            vec![
+                ConfigLayerEntry::new(
+                    ConfigLayerSource::User {
+                        file: test_path_buf("/tmp/config.toml").abs(),
+                        profile: None,
+                    },
+                    config_with_hook_override(key, Some(/*enabled*/ false)),
+                ),
+                ConfigLayerEntry::new(
+                    ConfigLayerSource::SessionFlags,
+                    config_with_hook_override(key, Some(/*enabled*/ true)),
+                ),
+            ],
+            Default::default(),
+            Default::default(),
+        )
+        .expect("config layer stack");
+
+        assert_eq!(
+            hook_states_from_stack(Some(&stack)),
+            HashMap::from([(
+                key.to_string(),
+                HookStateToml {
+                    enabled: Some(true),
+                    trusted_hash: None,
+                },
+            )])
+        );
+    }
+
+    #[test]
+    fn hook_states_from_stack_merges_fields_across_layers() {
+        let key = "file:/tmp/hooks.json:pre_tool_use:0:0";
+        let stack = ConfigLayerStack::new(
+            vec![
+                ConfigLayerEntry::new(
+                    ConfigLayerSource::User {
+                        file: test_path_buf("/tmp/config.toml").abs(),
+                        profile: None,
+                    },
+                    config_with_hook_state(
+                        key,
+                        HookStateToml {
+                            enabled: Some(/*enabled*/ false),
+                            trusted_hash: None,
+                        },
+                    ),
+                ),
+                ConfigLayerEntry::new(
+                    ConfigLayerSource::SessionFlags,
+                    config_with_hook_state(
+                        key,
+                        HookStateToml {
+                            enabled: None,
+                            trusted_hash: Some("sha256:trusted".to_string()),
+                        },
+                    ),
+                ),
+            ],
+            Default::default(),
+            Default::default(),
+        )
+        .expect("config layer stack");
+
+        assert_eq!(
+            hook_states_from_stack(Some(&stack)),
+            HashMap::from([(
+                key.to_string(),
+                HookStateToml {
+                    enabled: Some(false),
+                    trusted_hash: Some("sha256:trusted".to_string()),
+                },
+            )])
+        );
+    }
+
+    #[test]
+    fn hook_states_from_stack_ignores_malformed_hook_events() {
+        let key = "file:/tmp/hooks.json:pre_tool_use:0:0";
+        let config: TomlValue = serde_json::from_value(serde_json::json!({
+            "hooks": {
+                "state": {
+                    (key): {
+                        "enabled": false,
+                    },
+                },
+                "SessionStart": "not a matcher list",
+            },
+        }))
+        .expect("config TOML should deserialize");
+        let stack = ConfigLayerStack::new(
+            vec![ConfigLayerEntry::new(
+                ConfigLayerSource::User {
+                    file: test_path_buf("/tmp/config.toml").abs(),
+                    profile: None,
+                },
+                config,
+            )],
+            Default::default(),
+            Default::default(),
+        )
+        .expect("config layer stack");
+
+        assert_eq!(
+            hook_states_from_stack(Some(&stack)),
+            HashMap::from([(
+                key.to_string(),
+                HookStateToml {
+                    enabled: Some(false),
+                    trusted_hash: None,
+                },
+            )])
+        );
+    }
+
+    #[test]
+    fn hook_states_from_stack_ignores_malformed_state_entries() {
+        let key = "file:/tmp/hooks.json:pre_tool_use:0:0";
+        let config: TomlValue = serde_json::from_value(serde_json::json!({
+            "hooks": {
+                "state": {
+                    (key): {
+                        "enabled": false,
+                    },
+                    "malformed": {
+                        "enabled": "not a bool",
+                    },
+                },
+            },
+        }))
+        .expect("config TOML should deserialize");
+        let stack = ConfigLayerStack::new(
+            vec![ConfigLayerEntry::new(
+                ConfigLayerSource::User {
+                    file: test_path_buf("/tmp/config.toml").abs(),
+                    profile: None,
+                },
+                config,
+            )],
+            Default::default(),
+            Default::default(),
+        )
+        .expect("config layer stack");
+
+        assert_eq!(
+            hook_states_from_stack(Some(&stack)),
+            HashMap::from([(
+                key.to_string(),
+                HookStateToml {
+                    enabled: Some(false),
+                    trusted_hash: None,
+                },
+            )])
+        );
+    }
+
+    fn config_with_hook_override(key: &str, enabled: Option<bool>) -> TomlValue {
+        config_with_hook_state(
+            key,
+            HookStateToml {
+                enabled,
+                trusted_hash: None,
+            },
+        )
+    }
+
+    fn config_with_hook_state(key: &str, state: HookStateToml) -> TomlValue {
+        let hook_state = serde_json::to_value(state).expect("hook state should serialize");
+        serde_json::from_value(serde_json::json!({
+            "hooks": {
+                "state": {
+                    (key): hook_state,
+                },
+            },
+        }))
+        .expect("config TOML should deserialize")
+    }
+}
diff --git a/codex-rs/hooks/src/declarations.rs b/codex-rs/hooks/src/declarations.rs
new file mode 100644
index 0000000000000000000000000000000000000000..42ca76a2ed029bf0c71eba93e74a562da1c457f6
--- /dev/null
+++ b/codex-rs/hooks/src/declarations.rs
@@ -0,0 +1,102 @@
+use codex_plugin::PluginHookSource;
+use codex_protocol::protocol::HookEventName;
+
+/// Minimal declaration metadata for one bundled plugin hook handler.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginHookDeclaration {
+    pub key: String,
+    pub event_name: HookEventName,
+}
+
+/// Return the hook handlers declared by plugin bundles without projecting live runtime state.
+pub fn plugin_hook_declarations(hook_sources: &[PluginHookSource]) -> Vec<PluginHookDeclaration> {
+    let mut declarations = Vec::new();
+
+    for source in hook_sources {
+        let key_source = plugin_hook_key_source(
+            source.plugin_id.as_key().as_str(),
+            source.source_relative_path.as_str(),
+        );
+        for (event_name, groups) in source.hooks.clone().into_matcher_groups() {
+            for (group_index, group) in groups.iter().enumerate() {
+                for (handler_index, _) in group.hooks.iter().enumerate() {
+                    declarations.push(PluginHookDeclaration {
+                        key: crate::hook_key(&key_source, event_name, group_index, handler_index),
+                        event_name,
+                    });
+                }
+            }
+        }
+    }
+
+    declarations
+}
+
+pub(crate) fn plugin_hook_key_source(plugin_id: &str, source_relative_path: &str) -> String {
+    format!("{plugin_id}:{source_relative_path}")
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_config::HookEventsToml;
+    use codex_config::HookHandlerConfig;
+    use codex_config::MatcherGroup;
+    use codex_plugin::PluginId;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn lists_declared_plugin_handlers_with_persisted_hook_keys() {
+        let plugin_root = test_path_buf("/tmp/plugin").abs();
+        let source_path = plugin_root.join("hooks/hooks.json");
+        let declarations = plugin_hook_declarations(&[PluginHookSource {
+            plugin_id: PluginId::parse("demo@test").expect("plugin id"),
+            plugin_root: plugin_root.clone(),
+            plugin_data_root: plugin_root.join("data"),
+            source_path,
+            source_relative_path: "hooks/hooks.json".to_string(),
+            hooks: HookEventsToml {
+                pre_tool_use: vec![MatcherGroup {
+                    matcher: None,
+                    hooks: vec![
+                        HookHandlerConfig::Prompt {},
+                        HookHandlerConfig::Command {
+                            command: "echo hi".to_string(),
+                            command_windows: None,
+                            timeout_sec: None,
+                            r#async: false,
+                            status_message: None,
+                            additional_context_limit: None,
+                        },
+                    ],
+                }],
+                session_start: vec![MatcherGroup {
+                    matcher: None,
+                    hooks: vec![HookHandlerConfig::Agent {}],
+                }],
+                ..Default::default()
+            },
+        }]);
+
+        assert_eq!(
+            declarations,
+            vec![
+                PluginHookDeclaration {
+                    key: "demo@test:hooks/hooks.json:pre_tool_use:0:0".to_string(),
+                    event_name: HookEventName::PreToolUse,
+                },
+                PluginHookDeclaration {
+                    key: "demo@test:hooks/hooks.json:pre_tool_use:0:1".to_string(),
+                    event_name: HookEventName::PreToolUse,
+                },
+                PluginHookDeclaration {
+                    key: "demo@test:hooks/hooks.json:session_start:0:0".to_string(),
+                    event_name: HookEventName::SessionStart,
+                },
+            ]
+        );
+    }
+}
diff --git a/codex-rs/hooks/src/engine/command_runner.rs b/codex-rs/hooks/src/engine/command_runner.rs
new file mode 100644
index 0000000000000000000000000000000000000000..36914c62873f582674317c66de5e83e8225d8576
--- /dev/null
+++ b/codex-rs/hooks/src/engine/command_runner.rs
@@ -0,0 +1,466 @@
+use std::collections::HashMap;
+#[cfg(not(windows))]
+use std::ffi::OsStr;
+use std::ffi::OsString;
+use std::future::Future;
+use std::io::ErrorKind;
+use std::path::Path;
+use std::process::Stdio;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::MutexGuard;
+use std::time::Duration;
+use std::time::Instant;
+
+use async_channel::Sender;
+use codex_protocol::shell_environment::scrub_non_inheritable_env_vars;
+#[cfg(windows)]
+use codex_utils_pty::JobObject;
+use futures::future::try_join;
+use tokio::io::AsyncWriteExt;
+use tokio::process::Command;
+use tokio::sync::Semaphore;
+use tokio::task::JoinSet;
+use tokio::time::timeout;
+use tracing::Span;
+
+use super::CommandShell;
+use super::ConfiguredHandler;
+use super::ConfiguredHandlerKind;
+use super::HandlerRunResult;
+use super::dispatcher::ParsedHandler;
+use super::dispatcher::hook_event_name_label;
+use super::dispatcher::hook_execution_mode_label;
+use super::dispatcher::hook_handler_type_label;
+use super::dispatcher::hook_scope_label;
+use super::dispatcher::hook_source_label;
+use super::dispatcher::scope_for_event;
+use crate::output_spill::AdditionalContext;
+use crate::output_spill::HookOutputSpiller;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookHandlerType;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+
+const MAX_CONCURRENT_ASYNC_HOOKS: usize = 8;
+
+/// Owns command execution and bounded asynchronous work for one session.
+#[derive(Clone)]
+pub(crate) struct CommandHookRuntime {
+    shell: CommandShell,
+    environment: Arc<Vec<(OsString, OsString)>>,
+    result_sender: Sender<HookCompletedEvent>,
+    state: Arc<Mutex<CommandHookRuntimeState>>,
+    output_spiller: HookOutputSpiller,
+}
+
+struct CommandHookRuntimeState {
+    concurrency_limit: Arc<Semaphore>,
+    tasks: JoinSet<()>,
+}
+
+impl Default for CommandHookRuntimeState {
+    fn default() -> Self {
+        Self {
+            concurrency_limit: Arc::new(Semaphore::new(MAX_CONCURRENT_ASYNC_HOOKS)),
+            tasks: JoinSet::new(),
+        }
+    }
+}
+
+impl CommandHookRuntime {
+    pub(crate) fn new(
+        shell: CommandShell,
+        environment: Arc<Vec<(OsString, OsString)>>,
+        thread_id: ThreadId,
+        result_sender: Sender<HookCompletedEvent>,
+    ) -> Self {
+        Self {
+            shell,
+            environment,
+            result_sender,
+            state: Arc::new(Mutex::new(CommandHookRuntimeState::default())),
+            output_spiller: HookOutputSpiller::new(thread_id),
+        }
+    }
+
+    fn lock_state(&self) -> MutexGuard<'_, CommandHookRuntimeState> {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
+
+    pub(crate) fn reconfigured(&self, shell: CommandShell) -> Self {
+        Self {
+            shell,
+            environment: Arc::clone(&self.environment),
+            result_sender: self.result_sender.clone(),
+            state: Arc::clone(&self.state),
+            output_spiller: self.output_spiller.clone(),
+        }
+    }
+
+    pub(crate) fn output_spiller(&self) -> &HookOutputSpiller {
+        &self.output_spiller
+    }
+
+    pub(crate) fn schedule_async_hook<T: 'static>(
+        &self,
+        handler: ConfiguredHandler,
+        input_json: String,
+        cwd: std::path::PathBuf,
+        turn_id: Option<String>,
+        parse: fn(&ConfiguredHandler, HandlerRunResult, Option<String>) -> ParsedHandler<T>,
+    ) {
+        if self.result_sender.is_closed() {
+            return;
+        }
+
+        let result_sender = self.result_sender.clone();
+        let runtime = self.clone();
+        self.schedule_async_task(async move {
+            let result = match &handler.kind {
+                ConfiguredHandlerKind::Command { command, env, .. } => {
+                    run_command(&runtime, &handler, command, env, &input_json, &cwd).await
+                }
+                ConfiguredHandlerKind::McpTool { .. } => return,
+            };
+            let mut hook_result = parse(&handler, result, turn_id).completed;
+            let mut entries = Vec::new();
+            let mut warnings = Vec::new();
+
+            for entry in std::mem::take(&mut hook_result.run.entries) {
+                match entry.kind {
+                    HookOutputEntryKind::Context => {
+                        if let Some(text) = runtime
+                            .output_spiller
+                            .maybe_spill_additional_contexts(vec![AdditionalContext {
+                                text: entry.text,
+                                limit: handler.additional_context_limit,
+                            }])
+                            .await
+                            .into_iter()
+                            .next()
+                        {
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Context,
+                                text,
+                            });
+                        }
+                    }
+                    HookOutputEntryKind::Warning => warnings.push(entry),
+                    HookOutputEntryKind::Error => entries.push(entry),
+                    HookOutputEntryKind::Stop | HookOutputEntryKind::Feedback => {}
+                }
+            }
+
+            entries.extend(warnings);
+            hook_result.run.entries = entries;
+            let _ = result_sender.try_send(hook_result);
+        });
+    }
+
+    pub(crate) fn schedule_async_task(&self, task: impl Future<Output = ()> + Send + 'static) {
+        let mut state = self.lock_state();
+        if state.concurrency_limit.is_closed() {
+            return;
+        }
+
+        while state.tasks.try_join_next().is_some() {}
+        let concurrency_limit = Arc::clone(&state.concurrency_limit);
+        state.tasks.spawn(async move {
+            let Ok(_permit) = concurrency_limit.acquire_owned().await else {
+                return;
+            };
+            task.await;
+        });
+    }
+
+    pub(crate) async fn shutdown(&self) {
+        let mut tasks = {
+            let mut state = self.lock_state();
+            state.concurrency_limit.close();
+            std::mem::take(&mut state.tasks)
+        };
+        tasks.abort_all();
+        while tasks.join_next().await.is_some() {}
+    }
+}
+
+#[tracing::instrument(
+    name = "codex.hooks.command",
+    level = "trace",
+    skip_all,
+    fields(
+        hook.event_name = hook_event_name_label(handler.event_name),
+        hook.handler_type = hook_handler_type_label(HookHandlerType::Command),
+        hook.execution_mode = hook_execution_mode_label(handler.execution_mode()),
+        hook.scope = hook_scope_label(scope_for_event(handler.event_name)),
+        hook.source = hook_source_label(handler.source),
+        hook.display_order = handler.display_order,
+        hook.timeout_sec = handler.timeout_sec,
+        hook.command_outcome = tracing::field::Empty,
+    )
+)]
+pub(crate) async fn run_command(
+    runtime: &CommandHookRuntime,
+    handler: &ConfiguredHandler,
+    command: &str,
+    env: &HashMap<String, String>,
+    input_json: &str,
+    cwd: &Path,
+) -> HandlerRunResult {
+    let started_at = chrono::Utc::now().timestamp();
+    let started = Instant::now();
+
+    let mut command = build_command(&runtime.shell, command, &runtime.environment, env);
+    command
+        .current_dir(cwd)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .kill_on_drop(true);
+
+    #[cfg(unix)]
+    // Keep process-group cleanup without inheriting the controlling terminal, where
+    // shell startup can otherwise stop the hook on background terminal I/O.
+    // SAFETY: detach_from_tty only performs async-signal-safe process setup.
+    unsafe {
+        command.pre_exec(codex_utils_pty::process_group::detach_from_tty);
+    }
+
+    #[cfg(windows)]
+    let mut process_tree_job = JobObject::create().ok();
+    #[cfg(windows)]
+    let child = match process_tree_job.as_ref() {
+        Some(job) => match job.spawn_contained(&mut command) {
+            Ok(child) => Ok(child),
+            Err(_) => {
+                process_tree_job = None;
+                command.creation_flags(0);
+                command.spawn()
+            }
+        },
+        None => command.spawn(),
+    };
+    #[cfg(not(windows))]
+    let child = command.spawn();
+
+    let mut child = match child {
+        Ok(child) => child,
+        Err(err) => {
+            return finish_command_run(
+                started_at,
+                started,
+                CommandRunCompletion {
+                    exit_code: None,
+                    stdout: String::new(),
+                    stderr: String::new(),
+                    error: Some(err.to_string()),
+                    outcome: "spawn_error",
+                },
+            );
+        }
+    };
+
+    let mut process_tree_guard = ProcessTreeGuard {
+        process_id: child.id(),
+        #[cfg(windows)]
+        job: process_tree_job,
+    };
+
+    let stdin = child.stdin.take();
+    let write_stdin = async {
+        if let Some(mut stdin) = stdin
+            && let Err(err) = stdin.write_all(input_json.as_bytes()).await
+            && err.kind() != ErrorKind::BrokenPipe
+        {
+            return Err(("stdin_error", format!("failed to write hook stdin: {err}")));
+        }
+        Ok(())
+    };
+    let wait_with_output = async {
+        child
+            .wait_with_output()
+            .await
+            .map_err(|err| ("wait_error", err.to_string()))
+    };
+
+    let timeout_duration = Duration::from_secs(handler.timeout_sec);
+    // Drain output while sending input so neither pipe can block the other, and
+    // include stdin writes in the deadline even when the hook never reads them.
+    match timeout(timeout_duration, try_join(write_stdin, wait_with_output)).await {
+        Ok(Ok(((), output))) => {
+            // Successfully completed hooks may intentionally leave detached helpers running.
+            #[cfg(windows)]
+            if let Some(job) = process_tree_guard.job.as_ref() {
+                let _ = job.preserve_descendants();
+            }
+            process_tree_guard.process_id = None;
+            finish_command_run(
+                started_at,
+                started,
+                CommandRunCompletion {
+                    exit_code: output.status.code(),
+                    stdout: String::from_utf8_lossy(&output.stdout).to_string(),
+                    stderr: String::from_utf8_lossy(&output.stderr).to_string(),
+                    error: None,
+                    outcome: "completed",
+                },
+            )
+        }
+        Ok(Err((outcome, error))) => finish_command_run(
+            started_at,
+            started,
+            CommandRunCompletion {
+                exit_code: None,
+                stdout: String::new(),
+                stderr: String::new(),
+                error: Some(error),
+                outcome,
+            },
+        ),
+        Err(_) => finish_command_run(
+            started_at,
+            started,
+            CommandRunCompletion {
+                exit_code: None,
+                stdout: String::new(),
+                stderr: String::new(),
+                error: Some(format!("hook timed out after {}s", handler.timeout_sec)),
+                outcome: "timeout",
+            },
+        ),
+    }
+}
+
+// Needed only until command hooks move to the exec server, which owns process-tree cleanup.
+struct ProcessTreeGuard {
+    process_id: Option<u32>,
+    #[cfg(windows)]
+    job: Option<JobObject>,
+}
+
+impl Drop for ProcessTreeGuard {
+    fn drop(&mut self) {
+        let Some(process_id) = self.process_id else {
+            return;
+        };
+
+        #[cfg(unix)]
+        {
+            let _ = codex_utils_pty::process_group::kill_process_group(process_id);
+        }
+
+        #[cfg(windows)]
+        {
+            if let Some(job) = self.job.as_ref() {
+                let _ = job.terminate();
+            } else {
+                let _ = std::process::Command::new("taskkill")
+                    .args(["/PID", &process_id.to_string(), "/T", "/F"])
+                    .stdin(Stdio::null())
+                    .stdout(Stdio::null())
+                    .stderr(Stdio::null())
+                    .spawn();
+            }
+        }
+    }
+}
+
+struct CommandRunCompletion {
+    exit_code: Option<i32>,
+    stdout: String,
+    stderr: String,
+    error: Option<String>,
+    outcome: &'static str,
+}
+
+fn finish_command_run(
+    started_at: i64,
+    started: Instant,
+    completion: CommandRunCompletion,
+) -> HandlerRunResult {
+    Span::current().record("hook.command_outcome", completion.outcome);
+    HandlerRunResult {
+        started_at,
+        completed_at: chrono::Utc::now().timestamp(),
+        duration_ms: started.elapsed().as_millis().try_into().unwrap_or(i64::MAX),
+        exit_code: completion.exit_code,
+        stdout: completion.stdout,
+        stderr: completion.stderr,
+        error: completion.error,
+    }
+}
+
+fn build_command(
+    shell: &CommandShell,
+    command_line: &str,
+    environment: &[(OsString, OsString)],
+    env: &HashMap<String, String>,
+) -> Command {
+    let mut command = if shell.program.is_empty() {
+        default_shell_command(environment)
+    } else {
+        Command::new(&shell.program)
+    };
+    if shell.program.is_empty() {
+        #[cfg(windows)]
+        command.raw_arg(format!(r#""{command_line}""#));
+
+        #[cfg(not(windows))]
+        command.arg(command_line);
+    } else {
+        command.args(&shell.args);
+
+        #[cfg(windows)]
+        if shell.args.iter().any(|arg| arg.eq_ignore_ascii_case("/c")) {
+            command.raw_arg(format!(r#""{command_line}""#));
+        } else {
+            command.arg(command_line);
+        }
+
+        #[cfg(not(windows))]
+        command.arg(command_line);
+    }
+    // Replay the session snapshot instead of inheriting the live process environment.
+    command.env_clear();
+    command.envs(environment.iter().cloned());
+    command.envs(env);
+    scrub_non_inheritable_env_vars(command.as_std_mut());
+    command
+}
+
+fn default_shell_command(environment: &[(OsString, OsString)]) -> Command {
+    #[cfg(windows)]
+    let (environment_variable, fallback_program, argument) = ("COMSPEC", "cmd.exe", "/C");
+
+    #[cfg(not(windows))]
+    let (environment_variable, fallback_program, argument) = ("SHELL", "/bin/sh", "-lc");
+
+    let program = environment
+        .iter()
+        .find(|(key, _)| {
+            #[cfg(windows)]
+            {
+                key.to_str()
+                    .is_some_and(|key| key.eq_ignore_ascii_case(environment_variable))
+            }
+
+            #[cfg(not(windows))]
+            {
+                key == OsStr::new(environment_variable)
+            }
+        })
+        .map(|(_, value)| value.clone())
+        .unwrap_or_else(|| OsString::from(fallback_program));
+
+    let mut command = Command::new(program);
+    command.arg(argument);
+    command
+}
+
+#[cfg(test)]
+#[path = "command_runner_tests.rs"]
+mod tests;
diff --git a/codex-rs/hooks/src/engine/command_runner_tests.rs b/codex-rs/hooks/src/engine/command_runner_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d11da7765682ed849d75b57545bfe682899b8c4e
--- /dev/null
+++ b/codex-rs/hooks/src/engine/command_runner_tests.rs
@@ -0,0 +1,695 @@
+use std::collections::HashMap;
+use std::ffi::OsStr;
+use std::ffi::OsString;
+#[cfg(windows)]
+use std::fs;
+#[cfg(unix)]
+use std::os::unix::ffi::OsStringExt;
+use std::path::Path;
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_channel::Receiver;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookSource;
+use codex_protocol::shell_environment::CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use tempfile::tempdir;
+use tokio::time::sleep;
+use tokio::time::timeout;
+
+use super::super::ClaudeHooksEngine;
+use super::super::ConfiguredHandlerKind;
+use super::super::tests::mcp_executor;
+use super::CommandHookRuntime;
+use super::CommandShell;
+use super::ConfiguredHandler;
+use super::MAX_CONCURRENT_ASYNC_HOOKS;
+use super::build_command;
+use super::run_command;
+use crate::events::user_prompt_submit::UserPromptSubmitRequest;
+
+#[cfg(unix)]
+#[tokio::test]
+async fn hook_shell_startup_does_not_stop_on_controlling_terminal() {
+    const CHILD_ENV: &str = "CODEX_HOOK_TERMINAL_TEST_CHILD";
+    const TEST_NAME: &str =
+        "engine::command_runner::tests::hook_shell_startup_does_not_stop_on_controlling_terminal";
+
+    if std::env::var_os(CHILD_ENV).is_none() {
+        // Re-exec under a controlling terminal even when the test runner has none.
+        let executable = std::env::current_exe().expect("current test executable");
+        let mut env = std::env::vars().collect::<HashMap<_, _>>();
+        env.insert(CHILD_ENV.to_string(), "1".to_string());
+        let codex_utils_pty::SpawnedProcess {
+            session: _session,
+            mut stdout_rx,
+            exit_rx,
+            ..
+        } = codex_utils_pty::spawn_pty_process(
+            executable.to_str().expect("UTF-8 test executable path"),
+            &[
+                TEST_NAME.to_string(),
+                "--exact".to_string(),
+                "--nocapture".to_string(),
+            ],
+            &std::env::current_dir().expect("current test directory"),
+            &env,
+            /*arg0*/ &None,
+            codex_utils_pty::TerminalSize::default(),
+            &[],
+        )
+        .await
+        .expect("spawn test with a controlling terminal");
+
+        let (exit_code, output) = timeout(Duration::from_secs(10), async {
+            let output = async {
+                let mut output = Vec::new();
+                while let Some(chunk) = stdout_rx.recv().await {
+                    output.extend_from_slice(&chunk);
+                }
+                output
+            };
+            tokio::join!(exit_rx, output)
+        })
+        .await
+        .expect("terminal hook test should finish");
+        let output = String::from_utf8_lossy(&output);
+        assert_eq!(
+            exit_code.expect("terminal hook test exit status"),
+            0,
+            "{output}"
+        );
+        assert!(
+            output.contains(TEST_NAME),
+            "child did not run test: {output}"
+        );
+        return;
+    }
+
+    std::fs::File::open("/dev/tty").expect("test process must have a controlling terminal");
+    let temp = tempdir().expect("create temp dir");
+    let startup_path = temp.path().join("bashenv");
+    std::fs::write(
+        &startup_path,
+        "command -v stty >/dev/null || exit 1\nstty sane < /dev/tty\n",
+    )
+    .expect("write shell startup fixture");
+    let command = "printf hook-ran";
+    let env = HashMap::from([(
+        "BASH_ENV".to_string(),
+        startup_path
+            .to_str()
+            .expect("UTF-8 startup path")
+            .to_string(),
+    )]);
+    let handler = ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::SessionStart,
+        matcher: None,
+        timeout_sec: 2,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: AbsolutePathBuf::try_from(temp.path().join("hooks.json"))
+            .expect("absolute hook configuration path")
+            .into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: command.to_string(),
+            r#async: false,
+            env: env.clone(),
+        },
+    };
+    let (result_sender, _result_receiver) = async_channel::unbounded();
+    let runtime = CommandHookRuntime::new(
+        CommandShell {
+            program: "/bin/bash".to_string(),
+            args: vec!["-c".to_string()],
+        },
+        Arc::new(std::env::vars_os().collect()),
+        ThreadId::new(),
+        result_sender,
+    );
+
+    let result = run_command(&runtime, &handler, command, &env, "{}", temp.path()).await;
+
+    assert_eq!(result.exit_code, Some(0), "stderr: {}", result.stderr);
+    assert_eq!(result.stdout, "hook-ran");
+    assert_eq!(result.error, None);
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn cmd_shell_runs_quoted_hook_command_path() {
+    let temp = tempdir().expect("create temp dir");
+    let hook_dir = temp.path().join("hook with spaces");
+    fs::create_dir(&hook_dir).expect("create hook dir");
+    let hook_path = hook_dir.join("hook.cmd");
+    fs::write(
+        &hook_path,
+        "@echo off\r\nif not \"%~1\"==\"notify\" exit /B 7\r\necho hook-ran\r\n",
+    )
+    .expect("write hook command");
+    let source_path =
+        AbsolutePathBuf::try_from(hook_path.clone()).expect("absolute hook command path");
+    let command = format!(r#""{}" notify"#, hook_path.display());
+    let env = HashMap::new();
+    let handler = ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::SessionStart,
+        matcher: None,
+        timeout_sec: 10,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: source_path.into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: command.clone(),
+            r#async: false,
+            env: env.clone(),
+        },
+    };
+    let shells = [
+        CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        },
+        CommandShell {
+            program: std::env::var("COMSPEC").unwrap_or_else(|_| "cmd.exe".to_string()),
+            args: vec!["/c".to_string()],
+        },
+    ];
+
+    for shell in shells {
+        let (result_sender, _result_receiver) = async_channel::unbounded();
+        let runtime = CommandHookRuntime::new(
+            shell,
+            Arc::new(std::env::vars_os().collect()),
+            ThreadId::new(),
+            result_sender,
+        );
+        let result = run_command(&runtime, &handler, &command, &env, "{}", temp.path()).await;
+
+        assert_eq!(result.exit_code, Some(0), "stderr: {}", result.stderr);
+        assert_eq!(result.stdout.trim(), "hook-ran");
+        assert!(result.error.is_none());
+    }
+}
+
+#[tokio::test]
+async fn fast_exiting_hook_preserves_stdout_when_stdin_is_not_consumed() {
+    let temp = tempdir().expect("create temp dir");
+    let source_path = AbsolutePathBuf::try_from(temp.path().join("hooks.json"))
+        .expect("absolute hook configuration path");
+    let command = "echo hook-ran";
+    let env = HashMap::new();
+    let handler = ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::SessionStart,
+        matcher: None,
+        timeout_sec: 10,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: source_path.into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: command.to_string(),
+            r#async: false,
+            env: env.clone(),
+        },
+    };
+    let input_json = format!(r#"{{"padding":"{}"}}"#, "x".repeat(1024 * 1024));
+    let (runtime, _result_receiver) = runtime();
+
+    let result = run_command(&runtime, &handler, command, &env, &input_json, temp.path()).await;
+
+    assert_eq!(result.exit_code, Some(0), "stderr: {}", result.stderr);
+    assert_eq!(result.stdout.trim(), "hook-ran");
+    assert_eq!(result.error, None);
+}
+
+#[tokio::test]
+async fn hook_drains_output_and_times_out_while_stdin_is_blocked() {
+    let temp = tempdir().expect("create temp dir");
+    let mut handler = write_handler(
+        &temp,
+        r#"from pathlib import Path
+import sys
+import time
+
+sys.stdout.write("x" * 1024 * 1024)
+sys.stdout.flush()
+sys.stderr.write("x" * 1024 * 1024)
+sys.stderr.flush()
+Path("output-drained").touch()
+time.sleep(30)
+"#,
+    );
+    handler.timeout_sec = 2;
+    let ConfiguredHandlerKind::Command { command, env, .. } = &handler.kind else {
+        panic!("expected command hook");
+    };
+    let input_json = format!(r#"{{"padding":"{}"}}"#, "x".repeat(1024 * 1024));
+    let (runtime, _result_receiver) = runtime();
+
+    // Keep user shell startup files out of the pipe I/O timeout test.
+    let runtime = runtime.reconfigured(if cfg!(windows) {
+        CommandShell {
+            program: "cmd.exe".to_string(),
+            args: vec!["/D".to_string(), "/C".to_string()],
+        }
+    } else {
+        CommandShell {
+            program: "/bin/sh".to_string(),
+            args: vec!["-c".to_string()],
+        }
+    });
+
+    let result = timeout(
+        Duration::from_secs(10),
+        run_command(&runtime, &handler, command, env, &input_json, temp.path()),
+    )
+    .await
+    .expect("the hook timeout must also cover blocked stdin writes");
+
+    assert!(temp.path().join("output-drained").exists());
+    assert_eq!(result.exit_code, None);
+    assert_eq!(result.error, Some("hook timed out after 2s".to_string()));
+}
+
+#[tokio::test]
+async fn command_hook_does_not_expose_configured_noise_auth_token() {
+    let temp = tempdir().expect("create temp dir");
+    let source_path = AbsolutePathBuf::try_from(temp.path().join("hooks.json"))
+        .expect("absolute hook configuration path");
+    let command = if cfg!(windows) { "set" } else { "env" };
+    let env = HashMap::from([
+        (
+            CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR.to_ascii_lowercase(),
+            "configured-noise-token".to_string(),
+        ),
+        ("CODEX_HOOK_SAFE_ENV".to_string(), "visible".to_string()),
+    ]);
+    let handler = ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::SessionStart,
+        matcher: None,
+        timeout_sec: 10,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: source_path.into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: command.to_string(),
+            r#async: false,
+            env: env.clone(),
+        },
+    };
+    let (runtime, _result_receiver) = runtime();
+
+    let result = run_command(&runtime, &handler, command, &env, "{}", temp.path()).await;
+
+    assert_eq!(result.exit_code, Some(0), "stderr: {}", result.stderr);
+    assert!(result.stdout.contains("CODEX_HOOK_SAFE_ENV=visible"));
+    assert!(!result.stdout.lines().any(|line| {
+        line.split_once('=').is_some_and(|(name, _)| {
+            name.eq_ignore_ascii_case(CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR)
+        })
+    }));
+    assert_eq!(result.error, None);
+}
+
+#[test]
+fn build_command_replays_snapshot_before_hook_overrides_and_scrubbing() {
+    #[cfg(unix)]
+    let non_unicode_value = OsString::from_vec(vec![b'v', 0xff]);
+    let environment = vec![
+        (
+            OsString::from("CODEX_HOOK_SNAPSHOT"),
+            OsString::from("captured"),
+        ),
+        (
+            OsString::from("CODEX_HOOK_OVERRIDE"),
+            OsString::from("captured"),
+        ),
+        (
+            OsString::from(CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR),
+            OsString::from("captured-noise-token"),
+        ),
+        #[cfg(unix)]
+        (
+            OsString::from("CODEX_HOOK_NON_UNICODE"),
+            non_unicode_value.clone(),
+        ),
+    ];
+    let env = HashMap::from([
+        ("CODEX_HOOK_OVERRIDE".to_string(), "configured".to_string()),
+        ("CODEX_HOOK_SAFE_ENV".to_string(), "visible".to_string()),
+        (
+            CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR.to_string(),
+            "configured-noise-token".to_string(),
+        ),
+    ]);
+    let command = build_command(
+        &CommandShell {
+            program: "configured-shell".to_string(),
+            args: vec!["-c".to_string()],
+        },
+        "echo hook-ran",
+        &environment,
+        &env,
+    );
+
+    assert_eq!(
+        configured_environment_value(&command, "CODEX_HOOK_SNAPSHOT"),
+        Some(Some(OsString::from("captured")))
+    );
+    assert_eq!(
+        configured_environment_value(&command, "CODEX_HOOK_OVERRIDE"),
+        Some(Some(OsString::from("configured")))
+    );
+    assert_eq!(
+        configured_environment_value(&command, "CODEX_HOOK_SAFE_ENV"),
+        Some(Some(OsString::from("visible")))
+    );
+    assert_eq!(
+        configured_environment_value(&command, CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR),
+        None
+    );
+    #[cfg(unix)]
+    assert_eq!(
+        configured_environment_value(&command, "CODEX_HOOK_NON_UNICODE"),
+        Some(Some(non_unicode_value))
+    );
+}
+
+#[test]
+fn fallback_shell_uses_snapshot() {
+    #[cfg(windows)]
+    let (name, program) = ("comspec", r"C:\captured\cmd.exe");
+    #[cfg(not(windows))]
+    let (name, program) = ("SHELL", "/captured/shell");
+    let command = build_command(
+        &CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        },
+        "echo hook-ran",
+        &[(OsString::from(name), OsString::from(program))],
+        &HashMap::new(),
+    );
+
+    assert_eq!(command.as_std().get_program(), OsStr::new(program));
+    #[cfg(not(windows))]
+    assert_eq!(
+        command
+            .as_std()
+            .get_args()
+            .map(OsStr::to_os_string)
+            .collect::<Vec<_>>(),
+        vec![OsString::from("-lc"), OsString::from("echo hook-ran")]
+    );
+}
+
+const ASYNC_HOOK_TEST_TIMEOUT: Duration = Duration::from_secs(30);
+
+fn runtime() -> (CommandHookRuntime, Receiver<HookCompletedEvent>) {
+    runtime_with_environment(Arc::new(std::env::vars_os().collect()))
+}
+
+fn runtime_with_environment(
+    environment: Arc<Vec<(OsString, OsString)>>,
+) -> (CommandHookRuntime, Receiver<HookCompletedEvent>) {
+    let thread_id = ThreadId::new();
+    let (result_sender, result_receiver) = async_channel::unbounded();
+    let runtime = CommandHookRuntime::new(
+        CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        },
+        environment,
+        thread_id,
+        result_sender,
+    );
+    (runtime, result_receiver)
+}
+
+fn configured_environment_value(
+    command: &tokio::process::Command,
+    name: &str,
+) -> Option<Option<OsString>> {
+    command
+        .as_std()
+        .get_envs()
+        .find(|(key, _)| *key == OsStr::new(name))
+        .map(|(_, value)| value.map(OsStr::to_os_string))
+}
+
+fn write_handler(temp: &TempDir, source: &str) -> ConfiguredHandler {
+    let script_path = temp.path().join("async_hook.py");
+    std::fs::write(&script_path, source).expect("write async test hook");
+    ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::UserPromptSubmit,
+        matcher: None,
+        timeout_sec: 10,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: AbsolutePathBuf::try_from(temp.path().join("hooks.json"))
+            .expect("absolute test hook path")
+            .into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: format!("python3 {}", script_path.display()),
+            r#async: true,
+            env: HashMap::new(),
+        },
+    }
+}
+
+async fn schedule(runtime: &CommandHookRuntime, handler: ConfiguredHandler, cwd: &Path) {
+    let engine = ClaudeHooksEngine {
+        handlers: vec![handler],
+        warnings: Vec::new(),
+        required_load_errors: Vec::new(),
+        command_runtime: runtime.clone(),
+        mcp_executor: mcp_executor(),
+    };
+    engine
+        .run_user_prompt_submit(UserPromptSubmitRequest {
+            session_id: ThreadId::new(),
+            turn_id: "async-test-turn".to_string(),
+            subagent: None,
+            cwd: AbsolutePathBuf::try_from(cwd.to_path_buf()).expect("absolute test hook cwd"),
+            transcript_path: None,
+            model: "test-model".to_string(),
+            permission_mode: "default".to_string(),
+            prompt: "test prompt".to_string(),
+        })
+        .await;
+}
+
+#[tokio::test]
+async fn async_hook_marks_invalid_structured_output_as_failed() {
+    let temp = TempDir::new().expect("async test directory");
+    let (runtime, results) = runtime();
+    let handler = write_handler(
+        &temp,
+        r#"import sys
+
+sys.stdin.read()
+print('{"systemMessage": 123}')
+"#,
+    );
+
+    schedule(&runtime, handler, temp.path()).await;
+    let hook_result = timeout(ASYNC_HOOK_TEST_TIMEOUT, results.recv())
+        .await
+        .expect("invalid async output should still finish its background task")
+        .expect("result receiver should remain open");
+
+    assert_eq!(hook_result.run.status, HookRunStatus::Failed);
+    assert_eq!(
+        hook_result.run.entries,
+        vec![HookOutputEntry {
+            kind: HookOutputEntryKind::Error,
+            text: "hook returned invalid user prompt submit JSON output".to_string(),
+        }]
+    );
+
+    runtime.shutdown().await;
+}
+
+#[tokio::test]
+async fn async_hook_result_survives_runtime_reconfiguration() {
+    let temp = TempDir::new().expect("async test directory");
+    let mut environment = std::env::vars_os().collect::<Vec<_>>();
+    environment.push((
+        OsString::from("CODEX_HOOK_CAPTURED_ENV"),
+        OsString::from("captured"),
+    ));
+    let (previous, results) = runtime_with_environment(Arc::new(environment));
+    let release_path = temp.path().join("release");
+    let handler = write_handler(
+        &temp,
+        &format!(
+            r#"import json
+import os
+from pathlib import Path
+import sys
+import time
+
+json.load(sys.stdin)
+while not Path(r"{}").exists():
+    time.sleep(0.01)
+print(os.environ["CODEX_HOOK_CAPTURED_ENV"])
+"#,
+            release_path.display()
+        ),
+    );
+    schedule(&previous, handler, temp.path()).await;
+
+    let reconfigured = previous.reconfigured(CommandShell {
+        program: String::new(),
+        args: Vec::new(),
+    });
+    assert!(Arc::ptr_eq(
+        &previous.environment,
+        &reconfigured.environment
+    ));
+    std::fs::write(release_path, "ready").expect("release async hook");
+
+    let hook_result = timeout(ASYNC_HOOK_TEST_TIMEOUT, results.recv())
+        .await
+        .expect("in-flight hook should survive runtime reconfiguration")
+        .expect("result receiver should remain open");
+    assert_eq!(
+        hook_result.run.entries,
+        vec![HookOutputEntry {
+            kind: HookOutputEntryKind::Context,
+            text: "captured".to_string(),
+        }]
+    );
+
+    reconfigured.shutdown().await;
+}
+
+#[tokio::test]
+async fn async_hooks_limit_concurrent_processes_without_dropping_waiting_jobs() {
+    let temp = TempDir::new().expect("async test directory");
+    let (runtime, results) = runtime();
+    let started_dir = temp.path().join("started");
+    let release_path = temp.path().join("release");
+    std::fs::create_dir(&started_dir).expect("create hook marker directory");
+    let mut handler = write_handler(
+        &temp,
+        &format!(
+            r#"import os
+from pathlib import Path
+import sys
+import time
+
+sys.stdin.read()
+Path(r"{started}", str(os.getpid())).touch()
+while not Path(r"{release}").exists():
+    time.sleep(0.01)
+print("{{}}")
+"#,
+            started = started_dir.display(),
+            release = release_path.display(),
+        ),
+    );
+    handler.timeout_sec = ASYNC_HOOK_TEST_TIMEOUT.as_secs();
+
+    for _ in 0..=MAX_CONCURRENT_ASYNC_HOOKS {
+        schedule(&runtime, handler.clone(), temp.path()).await;
+    }
+
+    let started_count = || {
+        std::fs::read_dir(&started_dir)
+            .expect("read hook marker directory")
+            .count()
+    };
+    timeout(ASYNC_HOOK_TEST_TIMEOUT, async {
+        while started_count() < MAX_CONCURRENT_ASYNC_HOOKS {
+            sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("all available async hook slots should start");
+    assert_eq!(started_count(), MAX_CONCURRENT_ASYNC_HOOKS);
+
+    std::fs::write(release_path, "ready").expect("release running async hooks");
+    for _ in 0..=MAX_CONCURRENT_ASYNC_HOOKS {
+        timeout(ASYNC_HOOK_TEST_TIMEOUT, results.recv())
+            .await
+            .expect("waiting async hook should eventually finish")
+            .expect("result receiver should remain open");
+    }
+    assert_eq!(started_count(), MAX_CONCURRENT_ASYNC_HOOKS + 1);
+
+    runtime.shutdown().await;
+}
+
+#[tokio::test]
+async fn shutdown_aborts_in_flight_async_hooks_without_delivering_context() {
+    let temp = TempDir::new().expect("async test directory");
+    let (runtime, results) = runtime();
+    let started_path = temp.path().join("started");
+    let release_path = temp.path().join("release");
+    let handler = write_handler(
+        &temp,
+        &format!(
+            r#"import json
+from pathlib import Path
+import sys
+import time
+
+json.load(sys.stdin)
+Path(r"{started}").write_text("started", encoding="utf-8")
+while not Path(r"{release}").exists():
+    time.sleep(0.01)
+print(json.dumps({{
+    "hookSpecificOutput": {{
+        "hookEventName": "UserPromptSubmit",
+        "additionalContext": "must not be delivered after shutdown"
+    }}
+}}))
+"#,
+            started = started_path.display(),
+            release = release_path.display(),
+        ),
+    );
+    schedule(&runtime, handler, temp.path()).await;
+
+    timeout(ASYNC_HOOK_TEST_TIMEOUT, async {
+        while !started_path.exists() {
+            sleep(Duration::from_millis(10)).await;
+        }
+    })
+    .await
+    .expect("async hook should start before runtime shutdown");
+
+    runtime.shutdown().await;
+    drop(runtime);
+    std::fs::write(release_path, "ready").expect("release shutdown hook");
+    assert!(
+        timeout(Duration::from_millis(150), results.recv())
+            .await
+            .expect("shutdown should close the result channel")
+            .is_err(),
+        "shutdown must not deliver a late async result"
+    );
+}
diff --git a/codex-rs/hooks/src/engine/discovery.rs b/codex-rs/hooks/src/engine/discovery.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5003dbd24f081d1bc56a2f897fa51ef557a8caab
--- /dev/null
+++ b/codex-rs/hooks/src/engine/discovery.rs
@@ -0,0 +1,1741 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::fs;
+use std::path::Path;
+
+use codex_config::CONFIG_TOML_FILE;
+use codex_config::ConfigLayerEntry;
+use codex_config::ConfigLayerSource;
+use codex_config::ConfigLayerStack;
+use codex_config::HookEventsToml;
+use codex_config::HookHandlerConfig;
+use codex_config::HookStateToml;
+use codex_config::HooksFile;
+use codex_config::ManagedHooksRequirementsToml;
+use codex_config::MatcherGroup;
+use codex_config::RequirementSource;
+use codex_config::TomlValue;
+use codex_config::version_for_toml;
+use codex_plugin::PluginHookSource;
+use codex_plugin::is_allowlisted_bundled_cleanup_hook;
+use codex_protocol::protocol::HookEventName;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
+use serde::Serialize;
+
+use super::ConfiguredHandler;
+use super::ConfiguredHandlerKind;
+use super::HookListEntry;
+use super::HookListEntryHandler;
+use super::dispatcher::hook_event_name_label;
+use crate::config_rules::hook_states_from_stack;
+use crate::events::common::matcher_pattern_for_event;
+use crate::events::common::validate_matcher_pattern;
+use crate::events::session_end::SESSION_END_DEFAULT_TIMEOUT_SEC;
+use crate::events::session_end::SESSION_END_MAX_TIMEOUT_SEC;
+use crate::output_spill::AdditionalContextLimit;
+use crate::output_spill::DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT;
+use codex_protocol::protocol::HookSource;
+use codex_protocol::protocol::HookTrustStatus;
+
+pub(crate) struct DiscoveryResult {
+    pub handlers: Vec<ConfiguredHandler>,
+    pub hook_entries: Vec<HookListEntry>,
+    pub warnings: Vec<String>,
+    pub required_load_errors: Vec<String>,
+}
+
+struct HookHandlerSource<'a> {
+    path: &'a AbsolutePathBuf,
+    key_source: String,
+    source: HookSource,
+    is_managed: bool,
+    requirement: HookRequirement<'a>,
+    bypass_hook_trust: bool,
+    hook_states: &'a HashMap<String, HookStateToml>,
+    env: HashMap<String, String>,
+    plugin_id: Option<String>,
+}
+
+enum HookRequirement<'a> {
+    Required(&'a mut Vec<String>),
+    Optional,
+}
+
+impl HookHandlerSource<'_> {
+    fn record_load_failure(&mut self, warning: String, warnings: &mut Vec<String>) {
+        if let HookRequirement::Required(required_load_errors) = &mut self.requirement {
+            required_load_errors.push(warning.clone());
+        }
+        warnings.push(warning);
+    }
+}
+
+struct NormalizedHandler {
+    config: HookHandlerConfig,
+    kind: ConfiguredHandlerKind,
+    timeout_sec: u64,
+    status_message: Option<String>,
+    additional_context_limit: Option<usize>,
+}
+
+#[derive(Clone, Copy)]
+struct HookDiscoveryPolicy {
+    allow_managed_hooks_only: bool,
+    bypass_hook_trust: bool,
+}
+
+impl HookDiscoveryPolicy {
+    fn allows(self, source: &HookHandlerSource<'_>) -> bool {
+        !self.allow_managed_hooks_only || source.is_managed
+    }
+}
+
+pub(crate) fn discover_handlers(
+    config_layer_stack: Option<&ConfigLayerStack>,
+    plugin_hook_sources: Vec<PluginHookSource>,
+    plugin_hook_load_warnings: Vec<String>,
+    bypass_hook_trust: bool,
+) -> DiscoveryResult {
+    let mut handlers = Vec::new();
+    let mut hook_entries = Vec::new();
+    let mut warnings = plugin_hook_load_warnings;
+    let mut required_load_errors = Vec::new();
+    let mut display_order = 0_i64;
+    let mut visited_json_hook_folders = HashSet::new();
+    let hook_states = hook_states_from_stack(config_layer_stack);
+    let policy = HookDiscoveryPolicy {
+        allow_managed_hooks_only: config_layer_stack.is_some_and(|config_layer_stack| {
+            config_layer_stack
+                .requirements()
+                .allow_managed_hooks_only
+                .as_ref()
+                .is_some_and(|requirement| requirement.value)
+        }),
+        bypass_hook_trust,
+    };
+
+    if let Some(config_layer_stack) = config_layer_stack {
+        required_load_errors = append_managed_requirement_handlers(
+            &mut handlers,
+            &mut hook_entries,
+            &mut warnings,
+            &mut display_order,
+            config_layer_stack,
+            &hook_states,
+            policy,
+        );
+
+        for layer in config_layer_stack.layers_low_to_high() {
+            let (hook_source, is_managed) = hook_metadata_for_config_layer_source(&layer.name);
+            let policy_path = config_toml_source_path(layer);
+            let policy_source = HookHandlerSource {
+                path: &policy_path,
+                key_source: policy_path.display().to_string(),
+                source: hook_source,
+                is_managed,
+                requirement: HookRequirement::Optional,
+                bypass_hook_trust: false,
+                hook_states: &hook_states,
+                env: HashMap::new(),
+                plugin_id: None,
+            };
+            if !policy.allows(&policy_source) {
+                continue;
+            }
+            let json_hooks = match layer.hooks_config_folder() {
+                Some(config_folder) if visited_json_hook_folders.insert(config_folder.clone()) => {
+                    load_hooks_json(Some(config_folder.as_path()), &mut warnings)
+                }
+                _ => None,
+            };
+            let toml_hooks = load_toml_hooks_from_layer(layer, &mut warnings);
+
+            if let (Some((json_source_path, json_events)), Some((toml_source_path, toml_events))) =
+                (&json_hooks, &toml_hooks)
+                && !json_events.is_empty()
+                && !toml_events.is_empty()
+            {
+                warnings.push(format!(
+                    "loading hooks from both {} and {}; prefer a single representation for this layer",
+                    json_source_path.display(),
+                    toml_source_path.display()
+                ));
+            }
+
+            for (source_path, hook_events) in [json_hooks, toml_hooks].into_iter().flatten() {
+                append_hook_events(
+                    &mut handlers,
+                    &mut hook_entries,
+                    &mut warnings,
+                    &mut display_order,
+                    HookHandlerSource {
+                        path: &source_path,
+                        key_source: source_path.display().to_string(),
+                        source: hook_source,
+                        is_managed,
+                        requirement: HookRequirement::Optional,
+                        bypass_hook_trust: policy.bypass_hook_trust,
+                        hook_states: &hook_states,
+                        env: HashMap::new(),
+                        plugin_id: None,
+                    },
+                    hook_events,
+                    policy,
+                );
+            }
+        }
+    }
+
+    append_plugin_hook_sources(
+        &mut handlers,
+        &mut hook_entries,
+        &mut warnings,
+        &mut display_order,
+        plugin_hook_sources,
+        &hook_states,
+        policy,
+    );
+
+    DiscoveryResult {
+        handlers,
+        hook_entries,
+        warnings,
+        required_load_errors,
+    }
+}
+
+fn append_managed_requirement_handlers(
+    handlers: &mut Vec<ConfiguredHandler>,
+    hook_entries: &mut Vec<HookListEntry>,
+    warnings: &mut Vec<String>,
+    display_order: &mut i64,
+    config_layer_stack: &ConfigLayerStack,
+    hook_states: &HashMap<String, HookStateToml>,
+    policy: HookDiscoveryPolicy,
+) -> Vec<String> {
+    let Some(managed_hooks) = config_layer_stack.requirements().managed_hooks.as_ref() else {
+        return Vec::new();
+    };
+    let mut required_load_errors = Vec::new();
+    let source_path = managed_hooks_source_path(managed_hooks.get(), managed_hooks.source.as_ref());
+    append_hook_events(
+        handlers,
+        hook_entries,
+        warnings,
+        display_order,
+        HookHandlerSource {
+            path: &source_path,
+            key_source: source_path.display().to_string(),
+            source: hook_source_for_requirement_source(managed_hooks.source.as_ref()),
+            is_managed: true,
+            requirement: HookRequirement::Required(&mut required_load_errors),
+            bypass_hook_trust: false,
+            hook_states,
+            env: HashMap::new(),
+            plugin_id: None,
+        },
+        managed_hooks.get().hooks.clone(),
+        policy,
+    );
+    required_load_errors
+}
+
+fn append_plugin_hook_sources(
+    handlers: &mut Vec<ConfiguredHandler>,
+    hook_entries: &mut Vec<HookListEntry>,
+    warnings: &mut Vec<String>,
+    display_order: &mut i64,
+    plugin_hook_sources: Vec<PluginHookSource>,
+    hook_states: &HashMap<String, HookStateToml>,
+    policy: HookDiscoveryPolicy,
+) {
+    for source in plugin_hook_sources {
+        let PluginHookSource {
+            plugin_root,
+            plugin_id,
+            plugin_data_root,
+            source_path,
+            source_relative_path,
+            hooks,
+        } = source;
+        let mut env = HashMap::new();
+        let plugin_root_value = plugin_root.display().to_string();
+        let plugin_data_root_value = plugin_data_root.display().to_string();
+        env.insert("PLUGIN_ROOT".to_string(), plugin_root_value.clone());
+        // For OOTB compat with existing plugins that use this env var.
+        env.insert("CLAUDE_PLUGIN_ROOT".to_string(), plugin_root_value);
+        env.insert("PLUGIN_DATA".to_string(), plugin_data_root_value.clone());
+        // For OOTB compat with existing plugins that use this env var.
+        env.insert("CLAUDE_PLUGIN_DATA".to_string(), plugin_data_root_value);
+        let plugin_id = plugin_id.as_key();
+        append_hook_events(
+            handlers,
+            hook_entries,
+            warnings,
+            display_order,
+            HookHandlerSource {
+                path: &source_path,
+                key_source: crate::declarations::plugin_hook_key_source(
+                    plugin_id.as_str(),
+                    source_relative_path.as_str(),
+                ),
+                source: HookSource::Plugin,
+                is_managed: false,
+                requirement: HookRequirement::Optional,
+                bypass_hook_trust: policy.bypass_hook_trust,
+                hook_states,
+                env,
+                plugin_id: Some(plugin_id),
+            },
+            hooks,
+            policy,
+        );
+    }
+}
+
+fn managed_hooks_source_path(
+    managed_hooks: &ManagedHooksRequirementsToml,
+    requirement_source: Option<&RequirementSource>,
+) -> AbsolutePathBuf {
+    if let Some(source_path) = managed_hooks.managed_dir_for_current_platform()
+        && source_path.is_absolute()
+        && let Ok(source_path) = AbsolutePathBuf::from_absolute_path(source_path)
+    {
+        return source_path;
+    }
+
+    fallback_managed_hooks_source_path(requirement_source)
+}
+
+fn fallback_managed_hooks_source_path(
+    requirement_source: Option<&RequirementSource>,
+) -> AbsolutePathBuf {
+    match requirement_source {
+        Some(RequirementSource::SystemRequirementsToml { file })
+        | Some(RequirementSource::LegacyManagedConfigTomlFromFile { file }) => file.clone(),
+        Some(RequirementSource::MdmManagedPreferences { domain, key }) => {
+            synthetic_layer_path(&format!("<mdm:{domain}:{key}>/requirements.toml"))
+        }
+        Some(RequirementSource::Composite { .. }) => {
+            synthetic_layer_path("<requirements-composition>/requirements.toml")
+        }
+        Some(RequirementSource::EnterpriseManaged { id, name }) => {
+            let name = escape_xml_text(name);
+            let id = escape_xml_text(id);
+            synthetic_layer_path(&format!(
+                "<enterprise-managed:{name}:{id}>/requirements.toml"
+            ))
+        }
+        Some(RequirementSource::LegacyManagedConfigTomlFromMdm) => {
+            synthetic_layer_path("<legacy-managed-config.toml-mdm>/managed_config.toml")
+        }
+        Some(RequirementSource::Unknown) | None => {
+            synthetic_layer_path("<managed-requirements>/requirements.toml")
+        }
+    }
+}
+
+fn load_hooks_json(
+    config_folder: Option<&Path>,
+    warnings: &mut Vec<String>,
+) -> Option<(AbsolutePathBuf, HookEventsToml)> {
+    let source_path = config_folder?.join("hooks.json");
+    if !source_path.as_path().is_file() {
+        return None;
+    }
+
+    let contents = match fs::read_to_string(source_path.as_path()) {
+        Ok(contents) => contents,
+        Err(err) => {
+            warnings.push(format!(
+                "failed to read hooks config {}: {err}",
+                source_path.display()
+            ));
+            return None;
+        }
+    };
+
+    let parsed: HooksFile = match serde_json::from_str(&contents) {
+        Ok(parsed) => parsed,
+        Err(err) => {
+            warnings.push(format!(
+                "failed to parse hooks config {}: {err}",
+                source_path.display()
+            ));
+            return None;
+        }
+    };
+
+    let source_path = AbsolutePathBuf::from_absolute_path(&source_path)
+        .inspect_err(|err| {
+            warnings.push(format!(
+                "failed to normalize hooks config path {}: {err}",
+                source_path.display()
+            ));
+        })
+        .ok()?;
+
+    (!parsed.hooks.is_empty()).then_some((source_path, parsed.hooks))
+}
+
+fn load_toml_hooks_from_layer(
+    layer: &ConfigLayerEntry,
+    warnings: &mut Vec<String>,
+) -> Option<(AbsolutePathBuf, HookEventsToml)> {
+    let source_path = config_toml_source_path(layer);
+    let hook_value = layer.config.get("hooks")?.clone();
+    let parsed = match HookEventsToml::deserialize(hook_value) {
+        Ok(parsed) => parsed,
+        Err(err) => {
+            warnings.push(format!(
+                "failed to parse TOML hooks in {}: {err}",
+                source_path.display()
+            ));
+            return None;
+        }
+    };
+
+    (!parsed.is_empty()).then_some((source_path, parsed))
+}
+
+fn config_toml_source_path(layer: &ConfigLayerEntry) -> AbsolutePathBuf {
+    match &layer.name {
+        ConfigLayerSource::PackagedDefaults { file }
+        | ConfigLayerSource::System { file }
+        | ConfigLayerSource::User { file, .. }
+        | ConfigLayerSource::LegacyManagedConfigTomlFromFile { file } => file.clone(),
+        ConfigLayerSource::Project { dot_codex_folder } => layer
+            .hooks_config_folder()
+            .unwrap_or_else(|| dot_codex_folder.clone())
+            .join(CONFIG_TOML_FILE),
+        ConfigLayerSource::Mdm { domain, key } => {
+            synthetic_layer_path(&format!("<mdm:{domain}:{key}>/{CONFIG_TOML_FILE}"))
+        }
+        ConfigLayerSource::EnterpriseManaged { id, name } => synthetic_layer_path(&format!(
+            "<enterprise-managed:{name}:{id}>/{CONFIG_TOML_FILE}"
+        )),
+        ConfigLayerSource::LegacyManagedConfigTomlFromMdm => {
+            synthetic_layer_path("<legacy-managed-config.toml-mdm>/managed_config.toml")
+        }
+        ConfigLayerSource::SessionFlags => synthetic_layer_path("<session-flags>/config.toml"),
+    }
+}
+
+fn synthetic_layer_path(path: &str) -> AbsolutePathBuf {
+    #[cfg(windows)]
+    {
+        AbsolutePathBuf::resolve_path_against_base(path, r"C:\")
+    }
+
+    #[cfg(not(windows))]
+    {
+        AbsolutePathBuf::resolve_path_against_base(path, "/")
+    }
+}
+
+fn escape_xml_text(value: &str) -> String {
+    let mut escaped = String::with_capacity(value.len());
+    for ch in value.chars() {
+        match ch {
+            '&' => escaped.push_str("&amp;"),
+            '<' => escaped.push_str("&lt;"),
+            '>' => escaped.push_str("&gt;"),
+            '"' => escaped.push_str("&quot;"),
+            '\'' => escaped.push_str("&apos;"),
+            _ => escaped.push(ch),
+        }
+    }
+    escaped
+}
+
+fn append_hook_events(
+    handlers: &mut Vec<ConfiguredHandler>,
+    hook_entries: &mut Vec<HookListEntry>,
+    warnings: &mut Vec<String>,
+    display_order: &mut i64,
+    mut source: HookHandlerSource<'_>,
+    hook_events: HookEventsToml,
+    policy: HookDiscoveryPolicy,
+) {
+    if !policy.allows(&source) {
+        return;
+    }
+
+    for (event_name, groups) in hook_events.into_matcher_groups() {
+        append_matcher_groups(
+            handlers,
+            hook_entries,
+            warnings,
+            display_order,
+            &mut source,
+            event_name,
+            groups,
+        );
+    }
+}
+
+fn append_matcher_groups(
+    handlers: &mut Vec<ConfiguredHandler>,
+    hook_entries: &mut Vec<HookListEntry>,
+    warnings: &mut Vec<String>,
+    display_order: &mut i64,
+    source: &mut HookHandlerSource<'_>,
+    event_name: codex_protocol::protocol::HookEventName,
+    groups: Vec<MatcherGroup>,
+) {
+    for (group_index, group) in groups.into_iter().enumerate() {
+        let matcher = matcher_pattern_for_event(event_name, group.matcher.as_deref());
+        if let Some(matcher) = matcher
+            && let Err(err) = validate_matcher_pattern(matcher)
+        {
+            let warning = format!(
+                "invalid matcher {matcher:?} in {}: {err}",
+                source.path.display()
+            );
+            if group.hooks.is_empty() {
+                warnings.push(warning);
+            } else {
+                source.record_load_failure(warning, warnings);
+            }
+            continue;
+        }
+        for (handler_index, handler) in group.hooks.iter().cloned().enumerate() {
+            let normalized = match handler {
+                HookHandlerConfig::Command {
+                    command,
+                    command_windows,
+                    timeout_sec,
+                    r#async,
+                    status_message,
+                    additional_context_limit,
+                } => {
+                    let command = if cfg!(windows) {
+                        command_windows.unwrap_or(command)
+                    } else {
+                        command
+                    };
+                    if command.trim().is_empty() {
+                        source.record_load_failure(
+                            format!("skipping empty hook command in {}", source.path.display()),
+                            warnings,
+                        );
+                        continue;
+                    }
+                    let timeout_sec = normalize_command_hook(
+                        event_name,
+                        timeout_sec,
+                        source.path.as_path(),
+                        warnings,
+                    );
+                    let runs_async = r#async && event_name != HookEventName::SessionEnd;
+                    if r#async && !runs_async {
+                        warnings.push(format!(
+                            "running async {} hook synchronously in {}",
+                            hook_event_name_label(event_name),
+                            source.path.display()
+                        ));
+                    }
+                    let additional_context_limit = if matches!(
+                        event_name,
+                        codex_protocol::protocol::HookEventName::PreToolUse
+                            | codex_protocol::protocol::HookEventName::PostToolUse
+                            | codex_protocol::protocol::HookEventName::SessionStart
+                            | codex_protocol::protocol::HookEventName::UserPromptSubmit
+                            | codex_protocol::protocol::HookEventName::SubagentStart
+                    ) {
+                        additional_context_limit
+                    } else {
+                        if additional_context_limit.is_some() {
+                            warnings.push(format!(
+                                "ignoring additionalContextLimit for {event_name:?} hook in {}: this event cannot emit additionalContext",
+                                source.path.display()
+                            ));
+                        }
+                        None
+                    };
+                    let normalized_additional_context_limit = additional_context_limit
+                        .filter(|limit| *limit != DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT);
+                    let config = HookHandlerConfig::Command {
+                        command: command.clone(),
+                        command_windows: None,
+                        timeout_sec: Some(timeout_sec),
+                        r#async,
+                        status_message: status_message.clone(),
+                        additional_context_limit: normalized_additional_context_limit,
+                    };
+                    let command = source.env.iter().fold(command, |command, (key, value)| {
+                        command.replace(&format!("${{{key}}}"), value)
+                    });
+                    NormalizedHandler {
+                        config,
+                        kind: ConfiguredHandlerKind::Command {
+                            command,
+                            env: source.env.clone(),
+                            r#async: runs_async,
+                        },
+                        timeout_sec,
+                        status_message,
+                        additional_context_limit,
+                    }
+                }
+                HookHandlerConfig::McpTool {
+                    server,
+                    tool,
+                    input,
+                    timeout_sec,
+                    status_message,
+                } => {
+                    if event_name == HookEventName::SessionEnd {
+                        source.record_load_failure(
+                            format!(
+                                "skipping MCP tool hook in {}: {} MCP hooks are not supported",
+                                source.path.display(),
+                                hook_event_name_label(event_name),
+                            ),
+                            warnings,
+                        );
+                        continue;
+                    }
+                    if server.trim().is_empty() || tool.trim().is_empty() {
+                        source.record_load_failure(
+                            format!(
+                                "skipping MCP tool hook in {}: server and tool must not be empty",
+                                source.path.display()
+                            ),
+                            warnings,
+                        );
+                        continue;
+                    }
+                    let timeout_sec = normalize_command_hook(
+                        event_name,
+                        timeout_sec,
+                        source.path.as_path(),
+                        warnings,
+                    );
+                    let config = HookHandlerConfig::McpTool {
+                        server: server.clone(),
+                        tool: tool.clone(),
+                        input: input.clone(),
+                        timeout_sec: Some(timeout_sec),
+                        status_message: status_message.clone(),
+                    };
+                    NormalizedHandler {
+                        config,
+                        kind: ConfiguredHandlerKind::McpTool {
+                            server,
+                            tool,
+                            input,
+                        },
+                        timeout_sec,
+                        status_message,
+                        additional_context_limit: None,
+                    }
+                }
+                HookHandlerConfig::Prompt {} => {
+                    source.record_load_failure(
+                        format!(
+                            "skipping prompt hook in {}: prompt hooks are not supported yet",
+                            source.path.display()
+                        ),
+                        warnings,
+                    );
+                    continue;
+                }
+                HookHandlerConfig::Agent {} => {
+                    source.record_load_failure(
+                        format!(
+                            "skipping agent hook in {}: agent hooks are not supported yet",
+                            source.path.display()
+                        ),
+                        warnings,
+                    );
+                    continue;
+                }
+            };
+
+            let NormalizedHandler {
+                config,
+                kind,
+                timeout_sec,
+                status_message,
+                additional_context_limit,
+            } = normalized;
+            let current_hash = hook_hash(event_name, matcher, &group, &config);
+            let key = crate::hook_key(&source.key_source, event_name, group_index, handler_index);
+            let state = source.hook_states.get(&key);
+            let builtin = source.plugin_id.as_deref().is_some_and(|plugin_id| {
+                is_allowlisted_bundled_cleanup_hook(
+                    plugin_id,
+                    event_name,
+                    group.matcher.as_deref(),
+                    &config,
+                    /*app_connector_id*/ None,
+                )
+            });
+            let enabled = hook_enabled(source.is_managed, builtin, state);
+            let trusted_hash = hook_trusted_hash(source.is_managed, state);
+            let trust_status =
+                hook_trust_status(source.is_managed, builtin, &current_hash, trusted_hash);
+            let handler = match &kind {
+                ConfiguredHandlerKind::Command {
+                    command, r#async, ..
+                } => HookListEntryHandler::Command {
+                    command: command.clone(),
+                    r#async: *r#async,
+                },
+                ConfiguredHandlerKind::McpTool { server, tool, .. } => {
+                    HookListEntryHandler::McpTool {
+                        server: server.clone(),
+                        tool: tool.clone(),
+                    }
+                }
+            };
+
+            hook_entries.push(HookListEntry {
+                builtin,
+                key,
+                event_name,
+                handler,
+                matcher: matcher.map(ToOwned::to_owned),
+                timeout_sec,
+                status_message: status_message.clone(),
+                additional_context_limit,
+                source_path: source.path.clone(),
+                source: source.source,
+                plugin_id: source.plugin_id.clone(),
+                display_order: *display_order,
+                enabled,
+                is_managed: source.is_managed,
+                current_hash,
+                trust_status,
+            });
+            if enabled
+                && (source.bypass_hook_trust
+                    || matches!(
+                        trust_status,
+                        HookTrustStatus::Managed | HookTrustStatus::Trusted
+                    ))
+            {
+                handlers.push(ConfiguredHandler {
+                    builtin,
+                    event_name,
+                    matcher: matcher.map(ToOwned::to_owned),
+                    timeout_sec,
+                    status_message,
+                    additional_context_limit: AdditionalContextLimit::from_config(
+                        additional_context_limit,
+                    ),
+                    source_path: source.path.clone().into(),
+                    source: source.source,
+                    display_order: *display_order,
+                    kind,
+                });
+            }
+            *display_order += 1;
+        }
+    }
+}
+
+/// Normalizes hook timeouts. SessionEnd and Interrupt default to one second and are capped at three
+/// seconds; all other hooks keep the standard ten-minute default.
+fn normalize_command_hook(
+    event_name: HookEventName,
+    timeout_sec: Option<u64>,
+    source_path: &Path,
+    warnings: &mut Vec<String>,
+) -> u64 {
+    match event_name {
+        HookEventName::SessionEnd | HookEventName::Interrupt => {
+            let max_timeout_sec = SESSION_END_MAX_TIMEOUT_SEC;
+            if timeout_sec.is_some_and(|timeout_sec| timeout_sec > max_timeout_sec) {
+                warnings.push(format!(
+                    "clamping {} hook timeout to {max_timeout_sec}s in {}",
+                    hook_event_name_label(event_name),
+                    source_path.display()
+                ));
+            }
+            timeout_sec
+                .unwrap_or(SESSION_END_DEFAULT_TIMEOUT_SEC)
+                .clamp(1, max_timeout_sec)
+        }
+        _ => timeout_sec.unwrap_or(600).max(1),
+    }
+}
+
+/// Hash a normalized, config-derived identity instead of source text so equivalent
+/// hooks from config TOML and hooks.json converge on the same trust identity.
+#[derive(Serialize)]
+struct NormalizedHookIdentity {
+    event_name: &'static str,
+    #[serde(flatten)]
+    group: MatcherGroup,
+}
+
+fn hook_hash(
+    event_name: codex_protocol::protocol::HookEventName,
+    matcher: Option<&str>,
+    group: &MatcherGroup,
+    normalized_handler: &HookHandlerConfig,
+) -> String {
+    let mut group = group.clone();
+    group.matcher = matcher.map(ToOwned::to_owned);
+    group.hooks = vec![normalized_handler.clone()];
+    let identity = NormalizedHookIdentity {
+        event_name: crate::hook_event_key_label(event_name),
+        group,
+    };
+    let Ok(value) = TomlValue::try_from(identity) else {
+        unreachable!("normalized hook identity should serialize to TOML");
+    };
+    version_for_toml(&value)
+}
+
+fn hook_trust_status(
+    is_managed: bool,
+    is_builtin: bool,
+    current_hash: &str,
+    trusted_hash: Option<&str>,
+) -> HookTrustStatus {
+    if is_builtin {
+        HookTrustStatus::Trusted
+    } else if is_managed {
+        HookTrustStatus::Managed
+    } else {
+        match trusted_hash {
+            Some(trusted_hash) if trusted_hash == current_hash => HookTrustStatus::Trusted,
+            Some(_) => HookTrustStatus::Modified,
+            None => HookTrustStatus::Untrusted,
+        }
+    }
+}
+
+fn hook_enabled(is_managed: bool, is_builtin: bool, state: Option<&HookStateToml>) -> bool {
+    is_builtin || is_managed || state.and_then(|state| state.enabled) != Some(false)
+}
+
+fn hook_trusted_hash(is_managed: bool, state: Option<&HookStateToml>) -> Option<&str> {
+    (!is_managed)
+        .then(|| state.and_then(|state| state.trusted_hash.as_deref()))
+        .flatten()
+}
+
+fn hook_metadata_for_config_layer_source(source: &ConfigLayerSource) -> (HookSource, bool) {
+    match source {
+        ConfigLayerSource::PackagedDefaults { .. } => (HookSource::Unknown, false),
+        ConfigLayerSource::System { .. } => (HookSource::System, true),
+        ConfigLayerSource::User { .. } => (HookSource::User, false),
+        ConfigLayerSource::Project { .. } => (HookSource::Project, false),
+        ConfigLayerSource::Mdm { .. } => (HookSource::Mdm, true),
+        ConfigLayerSource::EnterpriseManaged { .. } => (HookSource::CloudManagedConfig, true),
+        ConfigLayerSource::SessionFlags => (HookSource::SessionFlags, false),
+        ConfigLayerSource::LegacyManagedConfigTomlFromFile { .. } => {
+            (HookSource::LegacyManagedConfigFile, true)
+        }
+        ConfigLayerSource::LegacyManagedConfigTomlFromMdm => {
+            (HookSource::LegacyManagedConfigMdm, true)
+        }
+    }
+}
+
+fn hook_source_for_requirement_source(source: Option<&RequirementSource>) -> HookSource {
+    match source {
+        Some(RequirementSource::MdmManagedPreferences { .. }) => HookSource::Mdm,
+        Some(RequirementSource::SystemRequirementsToml { .. }) => HookSource::System,
+        Some(RequirementSource::LegacyManagedConfigTomlFromFile { .. }) => {
+            HookSource::LegacyManagedConfigFile
+        }
+        Some(RequirementSource::LegacyManagedConfigTomlFromMdm) => {
+            HookSource::LegacyManagedConfigMdm
+        }
+        Some(RequirementSource::Composite { sources }) => {
+            // Requirements hook composition preserves contributing sources in
+            // priority order, but discovery only carries one source for the
+            // whole merged hooks field. Use the primary contributor as the best
+            // available coarse attribution.
+            hook_source_for_requirement_source(sources.first())
+        }
+        Some(RequirementSource::EnterpriseManaged { .. }) => HookSource::CloudRequirements,
+        Some(RequirementSource::Unknown) | None => HookSource::Unknown,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_config::ConfigLayerEntry;
+    use codex_config::ConfigLayerSource;
+    use codex_config::HookEventsToml;
+    use codex_config::RequirementSource;
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookExecutionMode;
+    use codex_protocol::protocol::HookSource;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::ConfiguredHandler;
+    use super::ConfiguredHandlerKind;
+    use super::HookListEntry;
+    use super::HookListEntryHandler;
+    use super::append_matcher_groups;
+    use super::normalize_command_hook;
+    use crate::output_spill::AdditionalContextLimit;
+    use crate::output_spill::DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT;
+    use codex_config::HookHandlerConfig;
+    use codex_config::HookStateToml;
+    use codex_config::MatcherGroup;
+    use codex_config::TomlValue;
+    use codex_protocol::protocol::HookTrustStatus;
+
+    fn source_path() -> AbsolutePathBuf {
+        test_path_buf("/tmp/hooks.json").abs()
+    }
+
+    fn hook_source() -> HookSource {
+        HookSource::System
+    }
+
+    fn hook_handler_source<'a>(
+        path: &'a AbsolutePathBuf,
+        hook_states: &'a std::collections::HashMap<String, HookStateToml>,
+    ) -> super::HookHandlerSource<'a> {
+        super::HookHandlerSource {
+            path,
+            key_source: path.display().to_string(),
+            source: hook_source(),
+            is_managed: true,
+            requirement: super::HookRequirement::Optional,
+            bypass_hook_trust: false,
+            hook_states,
+            env: std::collections::HashMap::new(),
+            plugin_id: None,
+        }
+    }
+
+    fn unmanaged_hook_handler_source<'a>(
+        path: &'a AbsolutePathBuf,
+        hook_states: &'a std::collections::HashMap<String, HookStateToml>,
+        bypass_hook_trust: bool,
+    ) -> super::HookHandlerSource<'a> {
+        super::HookHandlerSource {
+            path,
+            key_source: path.display().to_string(),
+            source: HookSource::User,
+            is_managed: false,
+            requirement: super::HookRequirement::Optional,
+            bypass_hook_trust,
+            hook_states,
+            env: std::collections::HashMap::new(),
+            plugin_id: None,
+        }
+    }
+
+    #[test]
+    fn composite_requirement_hook_source_uses_primary_source() {
+        let source = RequirementSource::Composite {
+            sources: vec![
+                RequirementSource::SystemRequirementsToml {
+                    file: test_path_buf("/etc/codex/requirements.toml").abs(),
+                },
+                RequirementSource::EnterpriseManaged {
+                    id: "layer-1".to_string(),
+                    name: "Engineering".to_string(),
+                },
+            ],
+        };
+
+        assert_eq!(
+            super::hook_source_for_requirement_source(Some(&source)),
+            HookSource::System
+        );
+    }
+
+    #[test]
+    fn enterprise_managed_synthetic_path_escapes_display_fields() {
+        let source = RequirementSource::EnterpriseManaged {
+            id: "id<&>".to_string(),
+            name: "Name <Admin> & \"Ops\"".to_string(),
+        };
+
+        let source_path = super::fallback_managed_hooks_source_path(Some(&source));
+        let source_path = source_path.display().to_string();
+
+        assert!(source_path.contains("Name &lt;Admin&gt; &amp; &quot;Ops&quot;"));
+        assert!(source_path.contains("id&lt;&amp;&gt;"));
+        assert!(!source_path.contains("Name <Admin>"));
+    }
+
+    fn command_group(matcher: Option<&str>) -> MatcherGroup {
+        MatcherGroup {
+            matcher: matcher.map(str::to_string),
+            hooks: vec![HookHandlerConfig::Command {
+                command: "echo hello".to_string(),
+                command_windows: None,
+                timeout_sec: None,
+                r#async: false,
+                status_message: None,
+                additional_context_limit: None,
+            }],
+        }
+    }
+
+    fn command_group_with_additional_context_limit(
+        additional_context_limit: usize,
+    ) -> MatcherGroup {
+        MatcherGroup {
+            matcher: None,
+            hooks: vec![HookHandlerConfig::Command {
+                command: "echo hello".to_string(),
+                command_windows: None,
+                timeout_sec: None,
+                r#async: false,
+                status_message: None,
+                additional_context_limit: Some(additional_context_limit),
+            }],
+        }
+    }
+
+    #[test]
+    fn mcp_tool_hooks_preserve_argument_templates_and_list_their_target() {
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+        let input = serde_json::from_value(serde_json::json!({
+            "file_path": "${tool_input.file_path}",
+            "optional": "${tool_input.optional}",
+        }))
+        .expect("MCP hook input should be an object");
+        let mut handlers = Vec::new();
+        let mut entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut entries,
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::PostToolUse,
+            vec![MatcherGroup {
+                matcher: Some("Write|Edit".to_string()),
+                hooks: vec![HookHandlerConfig::McpTool {
+                    server: "security".to_string(),
+                    tool: "scan".to_string(),
+                    input,
+                    timeout_sec: Some(30),
+                    status_message: Some("Scanning file".to_string()),
+                }],
+            }],
+        );
+
+        assert!(warnings.is_empty());
+        assert_eq!(handlers.len(), 1);
+        assert_eq!(entries.len(), 1);
+        assert_eq!(
+            entries[0].handler,
+            HookListEntryHandler::McpTool {
+                server: "security".to_string(),
+                tool: "scan".to_string(),
+            }
+        );
+        assert!(entries[0].current_hash.starts_with("sha256:"));
+    }
+
+    #[test]
+    fn session_end_mcp_tool_hooks_are_warned_and_skipped() {
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+        let mut handlers = Vec::new();
+        let mut entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut entries,
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::SessionEnd,
+            vec![MatcherGroup {
+                matcher: None,
+                hooks: vec![HookHandlerConfig::McpTool {
+                    server: "security".to_string(),
+                    tool: "scan".to_string(),
+                    input: serde_json::Map::new(),
+                    timeout_sec: None,
+                    status_message: None,
+                }],
+            }],
+        );
+
+        assert!(handlers.is_empty());
+        assert!(entries.is_empty());
+        assert_eq!(
+            warnings,
+            vec![format!(
+                "skipping MCP tool hook in {}: SessionEnd MCP hooks are not supported",
+                source_path.display()
+            )]
+        );
+    }
+
+    #[test]
+    fn interrupt_mcp_tool_hooks_are_supported_and_timeout_is_clamped() {
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+        let mut handlers = Vec::new();
+        let mut entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut entries,
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::Interrupt,
+            vec![MatcherGroup {
+                matcher: None,
+                hooks: vec![
+                    HookHandlerConfig::McpTool {
+                        server: "security".to_string(),
+                        tool: "scan".to_string(),
+                        input: serde_json::Map::new(),
+                        timeout_sec: None,
+                        status_message: None,
+                    },
+                    HookHandlerConfig::McpTool {
+                        server: "security".to_string(),
+                        tool: "report".to_string(),
+                        input: serde_json::Map::new(),
+                        timeout_sec: Some(600),
+                        status_message: None,
+                    },
+                ],
+            }],
+        );
+
+        assert_eq!(
+            handlers
+                .iter()
+                .map(|handler| handler.timeout_sec)
+                .collect::<Vec<_>>(),
+            vec![1, 3]
+        );
+        assert_eq!(
+            entries
+                .iter()
+                .map(|entry| entry.timeout_sec)
+                .collect::<Vec<_>>(),
+            vec![1, 3]
+        );
+        assert!(
+            entries
+                .iter()
+                .all(|entry| matches!(entry.handler, HookListEntryHandler::McpTool { .. }))
+        );
+        assert_eq!(
+            warnings,
+            vec![format!(
+                "clamping Interrupt hook timeout to 3s in {}",
+                source_path.display()
+            )]
+        );
+    }
+
+    fn discover_command(
+        event_name: HookEventName,
+        additional_context_limit: Option<usize>,
+    ) -> (ConfiguredHandler, HookListEntry, Vec<String>) {
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+        let mut handlers = Vec::new();
+        let mut entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        append_matcher_groups(
+            &mut handlers,
+            &mut entries,
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            event_name,
+            vec![match additional_context_limit {
+                Some(limit) => command_group_with_additional_context_limit(limit),
+                None => command_group(/*matcher*/ None),
+            }],
+        );
+        (handlers.remove(0), entries.remove(0), warnings)
+    }
+
+    #[test]
+    fn supported_events_retain_per_handler_additional_context_limit_and_hash_it() {
+        for event_name in [
+            HookEventName::PreToolUse,
+            HookEventName::PostToolUse,
+            HookEventName::SessionStart,
+            HookEventName::UserPromptSubmit,
+            HookEventName::SubagentStart,
+        ] {
+            let (_, default_entry, _) =
+                discover_command(event_name, /*additional_context_limit*/ None);
+            let (explicit_default_handler, explicit_default_entry, _) = discover_command(
+                event_name,
+                /*additional_context_limit*/ Some(DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT),
+            );
+            let (custom_handler, custom_entry, _) =
+                discover_command(event_name, /*additional_context_limit*/ Some(20_000));
+            let (unlimited_handler, unlimited_entry, _) =
+                discover_command(event_name, /*additional_context_limit*/ Some(0));
+
+            assert_eq!(
+                custom_handler.additional_context_limit,
+                AdditionalContextLimit::from_config(Some(20_000))
+            );
+            assert_eq!(custom_entry.additional_context_limit, Some(20_000));
+            assert_ne!(default_entry.current_hash, custom_entry.current_hash);
+            assert_eq!(
+                explicit_default_handler.additional_context_limit,
+                AdditionalContextLimit::from_config(Some(DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT))
+            );
+            assert_eq!(
+                explicit_default_entry.additional_context_limit,
+                Some(DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT)
+            );
+            assert_eq!(
+                default_entry.current_hash,
+                explicit_default_entry.current_hash
+            );
+            assert_eq!(
+                unlimited_handler.additional_context_limit,
+                AdditionalContextLimit::from_config(Some(0))
+            );
+            assert_eq!(unlimited_entry.additional_context_limit, Some(0));
+            assert_ne!(default_entry.current_hash, unlimited_entry.current_hash);
+        }
+    }
+
+    #[test]
+    fn unsupported_event_warns_and_ignores_additional_context_limit() {
+        let source_path = source_path();
+        let (handler, _, warnings) = discover_command(
+            HookEventName::Stop,
+            /*additional_context_limit*/ Some(4_096),
+        );
+
+        assert_eq!(handler.additional_context_limit, Default::default());
+        assert_eq!(warnings.len(), 1);
+        assert!(warnings[0].contains("ignoring additionalContextLimit for Stop hook"));
+        assert!(warnings[0].contains(&source_path.display().to_string()));
+    }
+
+    #[test]
+    fn user_prompt_submit_ignores_invalid_matcher_during_discovery() {
+        let mut handlers = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut Vec::new(),
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::UserPromptSubmit,
+            vec![command_group(Some("["))],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(
+            handlers,
+            vec![ConfiguredHandler {
+                builtin: false,
+                event_name: HookEventName::UserPromptSubmit,
+                matcher: None,
+                timeout_sec: 600,
+                status_message: None,
+                additional_context_limit: Default::default(),
+                source_path: source_path.clone().into(),
+                source: hook_source(),
+                display_order: 0,
+                kind: ConfiguredHandlerKind::Command {
+                    command: "echo hello".to_string(),
+                    r#async: false,
+                    env: std::collections::HashMap::new(),
+                },
+            }]
+        );
+    }
+
+    #[test]
+    fn pre_tool_use_keeps_valid_matcher_during_discovery() {
+        let mut handlers = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut Vec::new(),
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::PreToolUse,
+            vec![command_group(Some("^Bash$"))],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(
+            handlers,
+            vec![ConfiguredHandler {
+                builtin: false,
+                event_name: HookEventName::PreToolUse,
+                matcher: Some("^Bash$".to_string()),
+                timeout_sec: 600,
+                status_message: None,
+                additional_context_limit: Default::default(),
+                source_path: source_path.clone().into(),
+                source: hook_source(),
+                display_order: 0,
+                kind: ConfiguredHandlerKind::Command {
+                    command: "echo hello".to_string(),
+                    r#async: false,
+                    env: std::collections::HashMap::new(),
+                },
+            }]
+        );
+    }
+
+    #[test]
+    fn session_end_normalizes_timeout() {
+        let mut handlers = Vec::new();
+        let mut hook_entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut hook_entries,
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::SessionEnd,
+            vec![MatcherGroup {
+                matcher: Some("other".to_string()),
+                hooks: vec![
+                    HookHandlerConfig::Command {
+                        command: "echo default".to_string(),
+                        command_windows: None,
+                        timeout_sec: None,
+                        r#async: false,
+                        status_message: None,
+                        additional_context_limit: None,
+                    },
+                    HookHandlerConfig::Command {
+                        command: "echo clamped".to_string(),
+                        command_windows: None,
+                        timeout_sec: Some(600),
+                        r#async: true,
+                        status_message: None,
+                        additional_context_limit: None,
+                    },
+                ],
+            }],
+        );
+
+        assert_eq!(
+            handlers
+                .iter()
+                .map(|handler| handler.timeout_sec)
+                .collect::<Vec<_>>(),
+            vec![1, 3]
+        );
+        assert!(
+            handlers
+                .iter()
+                .all(ConfiguredHandler::can_apply_control_effects)
+        );
+        assert_eq!(
+            handlers
+                .iter()
+                .map(|handler| handler.matcher.as_deref())
+                .collect::<Vec<_>>(),
+            vec![Some("other"), Some("other")]
+        );
+        assert_eq!(
+            hook_entries
+                .iter()
+                .map(|entry| entry.timeout_sec)
+                .collect::<Vec<_>>(),
+            vec![1, 3]
+        );
+        assert!(hook_entries.iter().all(|entry| matches!(
+            entry.handler,
+            HookListEntryHandler::Command { r#async: false, .. }
+        )));
+        assert_eq!(
+            hook_entries
+                .iter()
+                .map(|entry| entry.matcher.as_deref())
+                .collect::<Vec<_>>(),
+            vec![Some("other"), Some("other")]
+        );
+        assert_eq!(
+            warnings,
+            vec![
+                format!(
+                    "clamping SessionEnd hook timeout to 3s in {}",
+                    source_path.display()
+                ),
+                format!(
+                    "running async SessionEnd hook synchronously in {}",
+                    source_path.display()
+                ),
+            ]
+        );
+    }
+
+    #[test]
+    fn interrupt_normalizes_timeout_and_supports_async_execution() {
+        let mut handlers = Vec::new();
+        let mut hook_entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut hook_entries,
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::Interrupt,
+            vec![MatcherGroup {
+                matcher: Some("ignored".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: "echo interrupt".to_string(),
+                    command_windows: None,
+                    timeout_sec: Some(600),
+                    r#async: true,
+                    status_message: None,
+                    additional_context_limit: None,
+                }],
+            }],
+        );
+
+        assert_eq!(
+            normalize_command_hook(
+                HookEventName::Interrupt,
+                /*timeout_sec*/ None,
+                source_path.as_path(),
+                &mut Vec::new(),
+            ),
+            1
+        );
+        assert_eq!(
+            handlers
+                .iter()
+                .map(|handler| (
+                    handler.timeout_sec,
+                    handler.matcher.as_deref(),
+                    handler.execution_mode()
+                ))
+                .collect::<Vec<_>>(),
+            vec![(3, None, HookExecutionMode::Async)]
+        );
+        assert_eq!(
+            hook_entries
+                .iter()
+                .map(|entry| (entry.timeout_sec, entry.matcher.as_deref()))
+                .collect::<Vec<_>>(),
+            vec![(3, None)]
+        );
+        assert!(hook_entries.iter().all(|entry| matches!(
+            entry.handler,
+            HookListEntryHandler::Command { r#async: true, .. }
+        )));
+        assert_eq!(
+            warnings,
+            vec![format!(
+                "clamping Interrupt hook timeout to 3s in {}",
+                source_path.display()
+            )]
+        );
+    }
+
+    #[test]
+    fn bypass_hook_trust_allows_enabled_untrusted_handlers() {
+        let mut handlers = Vec::new();
+        let mut hook_entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut hook_entries,
+            &mut warnings,
+            &mut display_order,
+            &mut unmanaged_hook_handler_source(
+                &source_path,
+                &hook_states,
+                /*bypass_hook_trust*/ true,
+            ),
+            HookEventName::PreToolUse,
+            vec![command_group(Some("Bash"))],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(handlers.len(), 1);
+        assert_eq!(hook_entries.len(), 1);
+        assert_eq!(hook_entries[0].trust_status, HookTrustStatus::Untrusted);
+        assert_eq!(hook_entries[0].enabled, true);
+    }
+
+    #[test]
+    fn bypass_hook_trust_respects_disabled_handlers() {
+        let mut handlers = Vec::new();
+        let mut hook_entries = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::from([(
+            format!("{}:pre_tool_use:0:0", source_path.display()),
+            HookStateToml {
+                enabled: Some(false),
+                trusted_hash: None,
+            },
+        )]);
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut hook_entries,
+            &mut warnings,
+            &mut display_order,
+            &mut unmanaged_hook_handler_source(
+                &source_path,
+                &hook_states,
+                /*bypass_hook_trust*/ true,
+            ),
+            HookEventName::PreToolUse,
+            vec![command_group(Some("Bash"))],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(handlers, Vec::<ConfiguredHandler>::new());
+        assert_eq!(hook_entries.len(), 1);
+        assert_eq!(hook_entries[0].trust_status, HookTrustStatus::Untrusted);
+        assert_eq!(hook_entries[0].enabled, false);
+    }
+
+    #[test]
+    fn pre_tool_use_treats_star_matcher_as_match_all() {
+        let mut handlers = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut Vec::new(),
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::PreToolUse,
+            vec![command_group(Some("*"))],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(handlers.len(), 1);
+        assert_eq!(handlers[0].matcher.as_deref(), Some("*"));
+    }
+
+    #[test]
+    fn post_tool_use_keeps_valid_matcher_during_discovery() {
+        let mut handlers = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut Vec::new(),
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::PostToolUse,
+            vec![command_group(Some("Edit|Write"))],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(handlers.len(), 1);
+        assert_eq!(handlers[0].event_name, HookEventName::PostToolUse);
+        assert_eq!(handlers[0].matcher.as_deref(), Some("Edit|Write"));
+    }
+
+    #[test]
+    fn toml_hook_discovery_ignores_malformed_state_entries() {
+        let layer = ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: test_path_buf("/tmp/config.toml").abs(),
+                profile: None,
+            },
+            config_with_malformed_state_and_session_start_hook(),
+        );
+        let mut warnings = Vec::new();
+
+        let (_, hooks) = super::load_toml_hooks_from_layer(&layer, &mut warnings)
+            .expect("valid hook events should still load");
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(
+            hooks,
+            HookEventsToml {
+                session_start: vec![MatcherGroup {
+                    matcher: None,
+                    hooks: vec![HookHandlerConfig::Command {
+                        command: "echo hello".to_string(),
+                        command_windows: None,
+                        timeout_sec: None,
+                        r#async: false,
+                        status_message: None,
+                        additional_context_limit: None,
+                    }],
+                }],
+                ..Default::default()
+            }
+        );
+    }
+
+    #[test]
+    fn pre_tool_use_resolves_windows_command_override_during_discovery() {
+        let mut handlers = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+        let source_path = source_path();
+        let hook_states = std::collections::HashMap::new();
+
+        append_matcher_groups(
+            &mut handlers,
+            &mut Vec::new(),
+            &mut warnings,
+            &mut display_order,
+            &mut hook_handler_source(&source_path, &hook_states),
+            HookEventName::PreToolUse,
+            vec![MatcherGroup {
+                matcher: Some("^Bash$".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: "echo unix".to_string(),
+                    command_windows: Some("echo windows".to_string()),
+                    timeout_sec: None,
+                    r#async: false,
+                    status_message: None,
+                    additional_context_limit: None,
+                }],
+            }],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(handlers.len(), 1);
+        assert_eq!(
+            handlers[0].kind,
+            ConfiguredHandlerKind::Command {
+                command: if cfg!(windows) {
+                    "echo windows"
+                } else {
+                    "echo unix"
+                }
+                .to_string(),
+                env: std::collections::HashMap::new(),
+                r#async: false,
+            }
+        );
+    }
+
+    fn config_with_malformed_state_and_session_start_hook() -> TomlValue {
+        serde_json::from_value(serde_json::json!({
+            "hooks": {
+                "state": {
+                    "some_key": {
+                        "enabled": "not a bool",
+                    },
+                },
+                "SessionStart": [{
+                    "hooks": [{
+                        "type": "command",
+                        "command": "echo hello",
+                    }],
+                }],
+            },
+        }))
+        .expect("config TOML should deserialize")
+    }
+
+    #[test]
+    fn hook_metadata_for_config_layer_source_discards_source_details() {
+        let config_file = test_path_buf("/tmp/.codex/config.toml").abs();
+        let dot_codex_folder = test_path_buf("/tmp/worktree/.codex").abs();
+
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(&ConfigLayerSource::System {
+                file: config_file.clone(),
+            }),
+            (HookSource::System, true),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(&ConfigLayerSource::User {
+                file: config_file.clone(),
+                profile: None,
+            }),
+            (HookSource::User, false),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(&ConfigLayerSource::Project {
+                dot_codex_folder
+            }),
+            (HookSource::Project, false),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(&ConfigLayerSource::Mdm {
+                domain: "com.openai.codex".to_string(),
+                key: "config".to_string(),
+            }),
+            (HookSource::Mdm, true),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(&ConfigLayerSource::EnterpriseManaged {
+                id: "cfg_123".to_string(),
+                name: "Base policy".to_string(),
+            }),
+            (HookSource::CloudManagedConfig, true),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(&ConfigLayerSource::SessionFlags),
+            (HookSource::SessionFlags, false),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(
+                &ConfigLayerSource::LegacyManagedConfigTomlFromFile { file: config_file },
+            ),
+            (HookSource::LegacyManagedConfigFile, true),
+        );
+        assert_eq!(
+            super::hook_metadata_for_config_layer_source(
+                &ConfigLayerSource::LegacyManagedConfigTomlFromMdm,
+            ),
+            (HookSource::LegacyManagedConfigMdm, true),
+        );
+    }
+}
diff --git a/codex-rs/hooks/src/engine/dispatcher.rs b/codex-rs/hooks/src/engine/dispatcher.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c5ee0d2ce1da03ec07b08f9ba692088142673e99
--- /dev/null
+++ b/codex-rs/hooks/src/engine/dispatcher.rs
@@ -0,0 +1,656 @@
+use std::path::Path;
+
+use futures::StreamExt;
+use futures::stream::FuturesUnordered;
+use serde_json::Map;
+use serde_json::Value;
+
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookExecutionMode;
+use codex_protocol::protocol::HookHandlerType;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_protocol::protocol::HookScope;
+
+use super::ClaudeHooksEngine;
+use super::ConfiguredHandler;
+use super::ConfiguredHandlerKind;
+use super::HandlerRunResult;
+use super::HandlerSourcePath;
+use super::command_runner::run_command;
+use super::mcp_runner::run_mcp_tool;
+use crate::events::common::matches_matcher;
+
+#[derive(Debug)]
+pub(crate) struct ParsedHandler<T> {
+    pub completed: HookCompletedEvent,
+    pub data: T,
+    pub completion_order: usize,
+}
+
+pub(crate) fn select_handlers(
+    handlers: &[ConfiguredHandler],
+    event_name: HookEventName,
+    matcher_input: Option<&str>,
+) -> Vec<ConfiguredHandler> {
+    let matcher_inputs = matcher_input.into_iter().collect::<Vec<_>>();
+    select_handlers_for_matcher_inputs(handlers, event_name, &matcher_inputs)
+}
+
+pub(crate) fn select_handlers_for_matcher_inputs(
+    handlers: &[ConfiguredHandler],
+    event_name: HookEventName,
+    matcher_inputs: &[&str],
+) -> Vec<ConfiguredHandler> {
+    // Check each configured handler once, even when several compatibility names
+    // match the same regex. A hook like `apply_patch|Write|Edit` should run a
+    // single time for one tool call, not once per matching alias.
+    handlers
+        .iter()
+        .filter(|handler| handler.event_name == event_name)
+        .filter(|handler| match event_name {
+            HookEventName::PreToolUse
+            | HookEventName::PermissionRequest
+            | HookEventName::PostToolUse
+            | HookEventName::SessionStart
+            | HookEventName::SessionEnd
+            | HookEventName::SubagentStart
+            | HookEventName::SubagentStop
+            | HookEventName::PreCompact
+            | HookEventName::PostCompact => {
+                if matcher_inputs.is_empty() {
+                    matches_matcher(handler.matcher.as_deref(), /*input*/ None)
+                } else {
+                    matcher_inputs
+                        .iter()
+                        .any(|input| matches_matcher(handler.matcher.as_deref(), Some(input)))
+                }
+            }
+            HookEventName::UserPromptSubmit | HookEventName::Stop | HookEventName::Interrupt => {
+                true
+            }
+        })
+        .cloned()
+        .collect()
+}
+
+pub(crate) fn running_summary(handler: &ConfiguredHandler) -> HookRunSummary {
+    let HandlerSourcePath::Local(source_path) = &handler.source_path else {
+        unreachable!("executor-scoped hooks do not produce public hook summaries");
+    };
+    HookRunSummary {
+        builtin: handler.builtin,
+        id: handler.run_id(),
+        event_name: handler.event_name,
+        handler_type: handler.handler_type(),
+        execution_mode: handler.execution_mode(),
+        scope: scope_for_event(handler.event_name),
+        source_path: source_path.clone(),
+        source: handler.source,
+        display_order: handler.display_order,
+        status: HookRunStatus::Running,
+        status_message: handler.status_message.clone(),
+        started_at: chrono::Utc::now().timestamp(),
+        completed_at: None,
+        duration_ms: None,
+        entries: Vec::new(),
+    }
+}
+
+pub(crate) async fn execute_handlers<T: 'static>(
+    engine: &ClaudeHooksEngine,
+    handlers: Vec<ConfiguredHandler>,
+    input_json: String,
+    cwd: &Path,
+    turn_id: Option<String>,
+    parse: fn(&ConfiguredHandler, HandlerRunResult, Option<String>) -> ParsedHandler<T>,
+) -> Vec<ParsedHandler<T>> {
+    execute_handlers_with_metadata(
+        engine, handlers, input_json, cwd, turn_id, /*metadata*/ None, parse,
+    )
+    .await
+}
+
+pub(crate) async fn execute_handlers_with_metadata<T: 'static>(
+    engine: &ClaudeHooksEngine,
+    handlers: Vec<ConfiguredHandler>,
+    input_json: String,
+    cwd: &Path,
+    turn_id: Option<String>,
+    metadata: Option<&Map<String, Value>>,
+    parse: fn(&ConfiguredHandler, HandlerRunResult, Option<String>) -> ParsedHandler<T>,
+) -> Vec<ParsedHandler<T>> {
+    let mut executor_handlers = Vec::new();
+    let mut pending = FuturesUnordered::new();
+    for (configured_order, handler) in handlers.into_iter().enumerate() {
+        if matches!(
+            handler.source_path,
+            HandlerSourcePath::ExecutorScoped { .. }
+        ) {
+            executor_handlers.push(handler);
+            continue;
+        }
+        if handler.execution_mode() == HookExecutionMode::Async {
+            engine.command_runtime.schedule_async_hook(
+                handler,
+                input_json.clone(),
+                cwd.to_path_buf(),
+                turn_id.clone(),
+                parse,
+            );
+            continue;
+        }
+        let input_json = input_json.clone();
+        let turn_id = turn_id.clone();
+        pending.push(async move {
+            let result =
+                execute_handler(engine, &handler, &input_json, cwd, /*metadata*/ None).await;
+            (configured_order, parse(&handler, result, turn_id))
+        });
+    }
+
+    let mut completed = Vec::new();
+    let mut completion_order = 0;
+    let mut should_stop = false;
+    let mut should_block = false;
+    while let Some((configured_order, mut parsed)) = pending.next().await {
+        should_stop |= parsed.completed.run.status == HookRunStatus::Stopped;
+        should_block |= parsed.completed.run.status == HookRunStatus::Blocked;
+        parsed.completion_order = completion_order;
+        completion_order += 1;
+        completed.push((configured_order, parsed));
+    }
+    completed.sort_by_key(|(configured_order, _)| *configured_order);
+
+    if should_stop || !should_block {
+        for handler in executor_handlers {
+            let task_engine = engine.clone();
+            let input_json = input_json.clone();
+            let cwd = cwd.to_path_buf();
+            let metadata = metadata.cloned();
+            engine.command_runtime.schedule_async_task(async move {
+                let result =
+                    execute_handler(&task_engine, &handler, &input_json, &cwd, metadata.as_ref())
+                        .await;
+                if let Some(error) = result.error {
+                    tracing::warn!(
+                        source_path = %handler.source_path,
+                        %error,
+                        "executor-scoped hook failed"
+                    );
+                }
+            });
+        }
+    }
+
+    completed.into_iter().map(|(_, parsed)| parsed).collect()
+}
+
+async fn execute_handler(
+    engine: &ClaudeHooksEngine,
+    handler: &ConfiguredHandler,
+    input_json: &str,
+    cwd: &Path,
+    metadata: Option<&Map<String, Value>>,
+) -> HandlerRunResult {
+    match &handler.kind {
+        ConfiguredHandlerKind::Command { command, env, .. } => {
+            run_command(
+                &engine.command_runtime,
+                handler,
+                command,
+                env,
+                input_json,
+                cwd,
+            )
+            .await
+        }
+        ConfiguredHandlerKind::McpTool {
+            server,
+            tool,
+            input,
+        } => {
+            run_mcp_tool(
+                engine.mcp_executor.as_ref(),
+                handler,
+                server,
+                tool,
+                input,
+                input_json,
+                metadata,
+            )
+            .await
+        }
+    }
+}
+
+pub(crate) fn completed_summary(
+    handler: &ConfiguredHandler,
+    run_result: &HandlerRunResult,
+    status: HookRunStatus,
+    entries: Vec<codex_protocol::protocol::HookOutputEntry>,
+) -> HookRunSummary {
+    let HandlerSourcePath::Local(source_path) = &handler.source_path else {
+        unreachable!("executor-scoped hooks do not produce public hook summaries");
+    };
+    HookRunSummary {
+        builtin: handler.builtin,
+        id: handler.run_id(),
+        event_name: handler.event_name,
+        handler_type: handler.handler_type(),
+        execution_mode: handler.execution_mode(),
+        scope: scope_for_event(handler.event_name),
+        source_path: source_path.clone(),
+        source: handler.source,
+        display_order: handler.display_order,
+        status,
+        status_message: handler.status_message.clone(),
+        started_at: run_result.started_at,
+        completed_at: Some(run_result.completed_at),
+        duration_ms: Some(run_result.duration_ms),
+        entries,
+    }
+}
+
+pub(crate) fn scope_for_event(event_name: HookEventName) -> HookScope {
+    match event_name {
+        HookEventName::SessionStart | HookEventName::SessionEnd | HookEventName::SubagentStart => {
+            HookScope::Thread
+        }
+        HookEventName::PreToolUse
+        | HookEventName::PermissionRequest
+        | HookEventName::PostToolUse
+        | HookEventName::PreCompact
+        | HookEventName::PostCompact
+        | HookEventName::UserPromptSubmit
+        | HookEventName::SubagentStop
+        | HookEventName::Stop
+        | HookEventName::Interrupt => HookScope::Turn,
+    }
+}
+
+pub(crate) fn hook_event_name_label(event_name: HookEventName) -> &'static str {
+    match event_name {
+        HookEventName::PreToolUse => "PreToolUse",
+        HookEventName::PermissionRequest => "PermissionRequest",
+        HookEventName::PostToolUse => "PostToolUse",
+        HookEventName::PreCompact => "PreCompact",
+        HookEventName::PostCompact => "PostCompact",
+        HookEventName::SessionStart => "SessionStart",
+        HookEventName::SessionEnd => "SessionEnd",
+        HookEventName::UserPromptSubmit => "UserPromptSubmit",
+        HookEventName::SubagentStart => "SubagentStart",
+        HookEventName::SubagentStop => "SubagentStop",
+        HookEventName::Stop => "Stop",
+        HookEventName::Interrupt => "Interrupt",
+    }
+}
+
+/// Returns the canonical label for a hook execution mode.
+pub fn hook_execution_mode_label(mode: HookExecutionMode) -> &'static str {
+    match mode {
+        HookExecutionMode::Sync => "sync",
+        HookExecutionMode::Async => "async",
+    }
+}
+
+/// Returns the canonical label for a hook handler type.
+pub fn hook_handler_type_label(handler_type: HookHandlerType) -> &'static str {
+    match handler_type {
+        HookHandlerType::Command => "command",
+        HookHandlerType::McpTool => "mcp_tool",
+        HookHandlerType::Prompt => "prompt",
+        HookHandlerType::Agent => "agent",
+    }
+}
+
+pub(crate) fn hook_scope_label(scope: HookScope) -> &'static str {
+    match scope {
+        HookScope::Thread => "thread",
+        HookScope::Turn => "turn",
+    }
+}
+
+pub(crate) fn hook_source_label(source: codex_protocol::protocol::HookSource) -> &'static str {
+    match source {
+        codex_protocol::protocol::HookSource::System => "system",
+        codex_protocol::protocol::HookSource::User => "user",
+        codex_protocol::protocol::HookSource::Project => "project",
+        codex_protocol::protocol::HookSource::Mdm => "mdm",
+        codex_protocol::protocol::HookSource::SessionFlags => "session_flags",
+        codex_protocol::protocol::HookSource::Plugin => "plugin",
+        codex_protocol::protocol::HookSource::CloudRequirements => "cloud_requirements",
+        codex_protocol::protocol::HookSource::CloudManagedConfig => "cloud_managed_config",
+        codex_protocol::protocol::HookSource::LegacyManagedConfigFile => {
+            "legacy_managed_config_file"
+        }
+        codex_protocol::protocol::HookSource::LegacyManagedConfigMdm => "legacy_managed_config_mdm",
+        codex_protocol::protocol::HookSource::Unknown => "unknown",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookSource;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::ConfiguredHandler;
+    use super::ConfiguredHandlerKind;
+    use super::select_handlers;
+    use super::select_handlers_for_matcher_inputs;
+
+    fn make_handler(
+        event_name: HookEventName,
+        matcher: Option<&str>,
+        command: &str,
+        display_order: i64,
+    ) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name,
+            matcher: matcher.map(str::to_owned),
+            timeout_sec: 5,
+            status_message: None,
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: HookSource::User,
+            display_order,
+            kind: ConfiguredHandlerKind::Command {
+                command: command.to_string(),
+                r#async: false,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    #[test]
+    fn select_handlers_keeps_duplicate_stop_handlers() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::Stop,
+                /*matcher*/ None,
+                "echo same",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::Stop,
+                /*matcher*/ None,
+                "echo same",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::Stop, /*matcher_input*/ None);
+
+        assert_eq!(selected.len(), 2);
+        assert_eq!(selected[0].display_order, 0);
+        assert_eq!(selected[1].display_order, 1);
+    }
+
+    #[test]
+    fn select_handlers_ignores_interrupt_matchers() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::Interrupt,
+                Some("^interrupted$"),
+                "echo first",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::Interrupt,
+                /*matcher*/ None,
+                "echo second",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(
+            &handlers,
+            HookEventName::Interrupt,
+            /*matcher_input*/ None,
+        );
+
+        assert_eq!(selected.len(), 2);
+        assert_eq!(selected[0].display_order, 0);
+        assert_eq!(selected[1].display_order, 1);
+    }
+
+    #[test]
+    fn select_handlers_keeps_overlapping_session_start_matchers() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::SessionStart,
+                Some("start.*"),
+                "echo same",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::SessionStart,
+                Some("^startup$"),
+                "echo same",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::SessionStart, Some("startup"));
+
+        assert_eq!(selected.len(), 2);
+        assert_eq!(selected[0].display_order, 0);
+        assert_eq!(selected[1].display_order, 1);
+    }
+
+    #[test]
+    fn compact_hooks_match_trigger() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::PreCompact,
+                Some("manual"),
+                "echo manual",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::PreCompact,
+                Some("auto"),
+                "echo auto",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::PreCompact, Some("manual"));
+
+        assert_eq!(selected.len(), 1);
+        assert_eq!(selected[0].display_order, 0);
+    }
+
+    #[test]
+    fn pre_tool_use_matches_tool_name() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("^Bash$"),
+                "echo same",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("^Edit$"),
+                "echo same",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::PreToolUse, Some("Bash"));
+
+        assert_eq!(selected.len(), 1);
+        assert_eq!(selected[0].display_order, 0);
+    }
+
+    #[test]
+    fn post_tool_use_matches_tool_name() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::PostToolUse,
+                Some("^Bash$"),
+                "echo same",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::PostToolUse,
+                Some("^Edit$"),
+                "echo same",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::PostToolUse, Some("Bash"));
+
+        assert_eq!(selected.len(), 1);
+        assert_eq!(selected[0].display_order, 0);
+    }
+
+    #[test]
+    fn pre_tool_use_star_matcher_matches_all_tools() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("*"),
+                "echo same",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("^Edit$"),
+                "echo same",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::PreToolUse, Some("Bash"));
+
+        assert_eq!(selected.len(), 1);
+        assert_eq!(selected[0].display_order, 0);
+    }
+
+    #[test]
+    fn pre_tool_use_regex_alternation_matches_each_tool_name() {
+        let handlers = vec![make_handler(
+            HookEventName::PreToolUse,
+            Some("Edit|Write"),
+            "echo same",
+            /*display_order*/ 0,
+        )];
+
+        let selected_edit = select_handlers(&handlers, HookEventName::PreToolUse, Some("Edit"));
+        let selected_write = select_handlers(&handlers, HookEventName::PreToolUse, Some("Write"));
+        let selected_bash = select_handlers(&handlers, HookEventName::PreToolUse, Some("Bash"));
+
+        assert_eq!(selected_edit.len(), 1);
+        assert_eq!(selected_write.len(), 1);
+        assert_eq!(selected_bash.len(), 0);
+    }
+
+    #[test]
+    fn pre_tool_use_aliases_match_once_per_handler() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("^apply_patch$"),
+                "echo apply_patch",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("^Write$"),
+                "echo write",
+                /*display_order*/ 1,
+            ),
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("^Edit$"),
+                "echo edit",
+                /*display_order*/ 2,
+            ),
+            make_handler(
+                HookEventName::PreToolUse,
+                Some("apply_patch|Write|Edit"),
+                "echo combined",
+                /*display_order*/ 3,
+            ),
+        ];
+
+        let selected = select_handlers_for_matcher_inputs(
+            &handlers,
+            HookEventName::PreToolUse,
+            &["apply_patch", "Write", "Edit"],
+        );
+
+        assert_eq!(selected.len(), 4);
+        assert_eq!(
+            selected
+                .iter()
+                .map(|handler| handler.display_order)
+                .collect::<Vec<_>>(),
+            vec![0, 1, 2, 3],
+        );
+    }
+
+    #[test]
+    fn user_prompt_submit_ignores_matcher() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::UserPromptSubmit,
+                Some("^hello"),
+                "echo first",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::UserPromptSubmit,
+                Some("["),
+                "echo second",
+                /*display_order*/ 1,
+            ),
+        ];
+
+        let selected = select_handlers(
+            &handlers,
+            HookEventName::UserPromptSubmit,
+            /*matcher_input*/ None,
+        );
+
+        assert_eq!(selected.len(), 2);
+        assert_eq!(selected[0].display_order, 0);
+        assert_eq!(selected[1].display_order, 1);
+    }
+
+    #[test]
+    fn select_handlers_preserves_declaration_order() {
+        let handlers = vec![
+            make_handler(
+                HookEventName::Stop,
+                /*matcher*/ None,
+                "first",
+                /*display_order*/ 0,
+            ),
+            make_handler(
+                HookEventName::Stop,
+                /*matcher*/ None,
+                "second",
+                /*display_order*/ 1,
+            ),
+            make_handler(
+                HookEventName::Stop,
+                /*matcher*/ None,
+                "third",
+                /*display_order*/ 2,
+            ),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::Stop, /*matcher_input*/ None);
+
+        assert_eq!(selected, handlers);
+    }
+}
diff --git a/codex-rs/hooks/src/engine/mcp_runner.rs b/codex-rs/hooks/src/engine/mcp_runner.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7a8da53e4d2b49ef66f2d14afb0e9fd45c8eeb4a
--- /dev/null
+++ b/codex-rs/hooks/src/engine/mcp_runner.rs
@@ -0,0 +1,166 @@
+use std::time::Duration;
+use std::time::Instant;
+
+use anyhow::Context;
+use anyhow::Result;
+use regex::Regex;
+use serde_json::Map;
+use serde_json::Value;
+
+use super::ConfiguredHandler;
+use super::HandlerRunResult;
+use super::HandlerSourcePath;
+use crate::mcp::HookMcpCall;
+use crate::mcp::HookMcpExecutor;
+
+/// Expands an MCP argument template against this hook event and invokes the configured tool.
+#[tracing::instrument(
+    name = "codex.hooks.mcp_tool",
+    level = "trace",
+    skip_all,
+    fields(
+        hook.server = server,
+        hook.tool = tool,
+        hook.timeout_sec = handler.timeout_sec,
+    )
+)]
+pub(crate) async fn run_mcp_tool(
+    executor: &dyn HookMcpExecutor,
+    handler: &ConfiguredHandler,
+    server: &str,
+    tool: &str,
+    argument_template: &Map<String, Value>,
+    hook_event_json: &str,
+    metadata: Option<&Map<String, Value>>,
+) -> HandlerRunResult {
+    let started_at = chrono::Utc::now().timestamp();
+    let started = Instant::now();
+    let result = async {
+        let hook_event: Value =
+            serde_json::from_str(hook_event_json).context("failed to parse hook event input")?;
+        let input = expand_mcp_argument_template(argument_template, &hook_event)?;
+        let (environment_id, mut call_metadata) = match &handler.source_path {
+            HandlerSourcePath::Local(_) => (None, None),
+            HandlerSourcePath::ExecutorScoped {
+                environment_id,
+                mcp_environment_id,
+                mcp_metadata,
+                ..
+            } => (
+                Some(
+                    mcp_environment_id
+                        .as_ref()
+                        .unwrap_or(environment_id)
+                        .clone(),
+                ),
+                mcp_metadata.as_deref().cloned(),
+            ),
+        };
+        if let Some(metadata) = metadata {
+            call_metadata
+                .get_or_insert_with(Map::new)
+                .extend(metadata.clone());
+        }
+        executor
+            .execute(HookMcpCall {
+                server: server.to_string(),
+                tool: tool.to_string(),
+                environment_id,
+                metadata: call_metadata,
+                input,
+                timeout: Duration::from_secs(handler.timeout_sec),
+            })
+            .await
+    }
+    .await;
+
+    let (exit_code, stdout, error) = match result {
+        Ok(output) => (Some(0), output, None),
+        Err(error) => (None, String::new(), Some(error.to_string())),
+    };
+    HandlerRunResult {
+        started_at,
+        completed_at: chrono::Utc::now().timestamp(),
+        duration_ms: started.elapsed().as_millis().try_into().unwrap_or(i64::MAX),
+        exit_code,
+        stdout,
+        stderr: String::new(),
+        error,
+    }
+}
+
+/// Recursively substitutes `${field.nested}` placeholders using values from a hook event.
+///
+/// A complete placeholder preserves its JSON type; a placeholder embedded in surrounding
+/// text is rendered as a string. Missing fields fail the hook instead of passing unresolved
+/// arguments to the server. For example, the template `{"count":"${tool_input.count}"}`
+/// becomes `{"count":3}` when the event contains `{"tool_input":{"count":3}}`.
+pub(crate) fn expand_mcp_argument_template(
+    argument_template: &Map<String, Value>,
+    hook_event: &Value,
+) -> Result<Map<String, Value>> {
+    argument_template
+        .iter()
+        .map(|(key, value)| Ok((key.clone(), resolve_value(value, hook_event)?)))
+        .collect()
+}
+
+fn resolve_value(value: &Value, hook_event: &Value) -> Result<Value> {
+    match value {
+        Value::Object(input) => Ok(Value::Object(expand_mcp_argument_template(
+            input, hook_event,
+        )?)),
+        Value::Array(items) => items
+            .iter()
+            .map(|item| resolve_value(item, hook_event))
+            .collect::<Result<Vec<_>>>()
+            .map(Value::Array),
+        Value::String(text) => resolve_string(text, hook_event),
+        _ => Ok(value.clone()),
+    }
+}
+
+fn resolve_string(text: &str, hook_event: &Value) -> Result<Value> {
+    let pattern = Regex::new(r"\$\{([^{}]+)\}")?;
+    let captures = pattern.captures_iter(text).collect::<Vec<_>>();
+    if captures.is_empty() {
+        return Ok(Value::String(text.to_string()));
+    }
+
+    if let [capture] = captures.as_slice()
+        && let Some(placeholder) = capture.get(0)
+        && placeholder.start() == 0
+        && placeholder.end() == text.len()
+    {
+        return resolve_path(hook_event, &capture[1]).cloned();
+    }
+
+    let mut resolved = String::new();
+    let mut previous_end = 0;
+    for capture in captures {
+        let Some(placeholder) = capture.get(0) else {
+            continue;
+        };
+        resolved.push_str(&text[previous_end..placeholder.start()]);
+        let value = resolve_path(hook_event, &capture[1])?;
+        match value {
+            Value::String(value) => resolved.push_str(value),
+            _ => resolved.push_str(&serde_json::to_string(value)?),
+        }
+        previous_end = placeholder.end();
+    }
+    resolved.push_str(&text[previous_end..]);
+    Ok(Value::String(resolved))
+}
+
+fn resolve_path<'a>(hook_event: &'a Value, path: &str) -> Result<&'a Value> {
+    path.split('.').try_fold(hook_event, |value, field| {
+        value
+            .get(field)
+            .with_context(|| format!("hook input placeholder `${{{path}}}` was not found"))
+    })
+}
+
+#[cfg(test)]
+#[path = "mcp_runner_tests.rs"]
+mod tests;
diff --git a/codex-rs/hooks/src/engine/mcp_runner_tests.rs b/codex-rs/hooks/src/engine/mcp_runner_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a16613ea071d1a58525470cf10d656086ed5dcd4
--- /dev/null
+++ b/codex-rs/hooks/src/engine/mcp_runner_tests.rs
@@ -0,0 +1,141 @@
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+
+use futures::FutureExt;
+use futures::future::BoxFuture;
+use pretty_assertions::assert_eq;
+use serde_json::Map;
+use serde_json::Value;
+use serde_json::json;
+
+use super::expand_mcp_argument_template;
+use super::run_mcp_tool;
+use crate::engine::ConfiguredHandler;
+use crate::engine::ConfiguredHandlerKind;
+use crate::mcp::HookMcpCall;
+use crate::mcp::HookMcpExecutor;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookSource;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+
+struct RecordingExecutor {
+    calls: Arc<Mutex<Vec<HookMcpCall>>>,
+    output: String,
+}
+
+impl HookMcpExecutor for RecordingExecutor {
+    fn execute(&self, call: HookMcpCall) -> BoxFuture<'_, anyhow::Result<String>> {
+        async move {
+            self.calls.lock().expect("lock calls").push(call);
+            Ok(self.output.clone())
+        }
+        .boxed()
+    }
+}
+
+#[test]
+fn placeholders_preserve_json_types_and_expand_nested_inputs() {
+    let event_input = json!({
+        "tool_input": {
+            "file_path": "/tmp/example.rs",
+            "count": 3,
+            "optional": null,
+            "metadata": { "language": "rust" },
+        },
+    });
+    let input = serde_json::from_value::<Map<String, Value>>(json!({
+        "path": "${tool_input.file_path}",
+        "message": "scan ${tool_input.file_path}",
+        "count": "${tool_input.count}",
+        "optional": "${tool_input.optional}",
+        "nested": ["${tool_input.metadata}", { "literal": true }],
+    }))
+    .expect("object input");
+
+    assert_eq!(
+        Value::Object(
+            expand_mcp_argument_template(&input, &event_input).expect("expand MCP arguments")
+        ),
+        json!({
+            "path": "/tmp/example.rs",
+            "message": "scan /tmp/example.rs",
+            "count": 3,
+            "optional": null,
+            "nested": [{ "language": "rust" }, { "literal": true }],
+        })
+    );
+}
+
+#[test]
+fn missing_placeholder_fails_without_passing_unresolved_input() {
+    let input = serde_json::from_value::<Map<String, Value>>(json!({
+        "path": "${tool_input.missing}",
+    }))
+    .expect("object input");
+
+    let error = expand_mcp_argument_template(&input, &json!({ "tool_input": {} }))
+        .expect_err("missing placeholder should fail");
+
+    assert_eq!(
+        error.to_string(),
+        "hook input placeholder `${tool_input.missing}` was not found"
+    );
+}
+
+#[tokio::test]
+async fn mcp_tool_results_use_command_hook_output_contract() {
+    let configured_input = serde_json::from_value::<Map<String, Value>>(json!({
+        "file_path": "${tool_input.file_path}",
+    }))
+    .expect("object input");
+    let handler = ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::PostToolUse,
+        matcher: None,
+        timeout_sec: 30,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::McpTool {
+            server: "security".to_string(),
+            tool: "scan".to_string(),
+            input: configured_input.clone(),
+        },
+    };
+    let calls = Arc::new(Mutex::new(Vec::new()));
+    let executor = RecordingExecutor {
+        calls: Arc::clone(&calls),
+        output: r#"{"decision":"block","reason":"unsafe file"}"#.to_string(),
+    };
+
+    let result = run_mcp_tool(
+        &executor,
+        &handler,
+        "security",
+        "scan",
+        &configured_input,
+        r#"{"tool_input":{"file_path":"/tmp/example.rs"}}"#,
+        /*metadata*/ None,
+    )
+    .await;
+
+    assert_eq!(result.exit_code, Some(0));
+    assert_eq!(result.stdout, executor.output);
+    assert_eq!(result.error, None);
+    assert_eq!(
+        *calls.lock().expect("lock calls"),
+        vec![HookMcpCall {
+            server: "security".to_string(),
+            tool: "scan".to_string(),
+            environment_id: None,
+            metadata: None,
+            input: serde_json::from_value(json!({ "file_path": "/tmp/example.rs" }))
+                .expect("object input"),
+            timeout: Duration::from_secs(30),
+        }]
+    );
+}
diff --git a/codex-rs/hooks/src/engine/mod.rs b/codex-rs/hooks/src/engine/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..deaf29679a8ce5b35af474d4309b52a8a3a72ff7
--- /dev/null
+++ b/codex-rs/hooks/src/engine/mod.rs
@@ -0,0 +1,492 @@
+pub(crate) mod command_runner;
+pub(crate) mod discovery;
+pub(crate) mod dispatcher;
+pub(crate) mod mcp_runner;
+pub(crate) mod output_parser;
+pub(crate) mod schema_loader;
+
+use crate::events::compact::PostCompactRequest;
+use crate::events::compact::PreCompactOutcome;
+use crate::events::compact::PreCompactRequest;
+use crate::events::compact::StatelessHookOutcome;
+use crate::events::interrupt::InterruptOutcome;
+use crate::events::interrupt::InterruptRequest;
+use crate::events::permission_request::PermissionRequestOutcome;
+use crate::events::permission_request::PermissionRequestRequest;
+use crate::events::post_tool_use::PostToolUseOutcome;
+use crate::events::post_tool_use::PostToolUseRequest;
+use crate::events::pre_tool_use::PreToolUseOutcome;
+use crate::events::pre_tool_use::PreToolUseRequest;
+use crate::events::session_end::SessionEndOutcome;
+use crate::events::session_end::SessionEndRequest;
+use crate::events::session_start::SessionStartOutcome;
+use crate::events::session_start::SessionStartRequest;
+use crate::events::stop::StopOutcome;
+use crate::events::stop::StopRequest;
+use crate::events::user_prompt_submit::UserPromptSubmitOutcome;
+use crate::events::user_prompt_submit::UserPromptSubmitRequest;
+use crate::mcp::HookMcpExecutor;
+use crate::output_spill::AdditionalContextLimit;
+use codex_config::ConfigLayerStack;
+use codex_config::HookHandlerConfig;
+use codex_plugin::ExecutorPluginHookSource;
+use codex_plugin::PluginHookSource;
+use codex_plugin::PluginId;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookExecutionMode;
+use codex_protocol::protocol::HookHandlerType;
+use codex_protocol::protocol::HookRunSummary;
+use codex_protocol::protocol::HookSource;
+use codex_protocol::protocol::HookTrustStatus;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path_uri::PathUri;
+use serde_json::Map;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::sync::Arc;
+use std::time::Duration;
+
+use command_runner::CommandHookRuntime;
+
+#[derive(Debug, Clone)]
+pub(crate) struct CommandShell {
+    pub program: String,
+    pub args: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct ConfiguredHandler {
+    /// Internally admitted cleanup hook, enabled independently of per-hook state.
+    pub builtin: bool,
+    pub event_name: codex_protocol::protocol::HookEventName,
+    pub matcher: Option<String>,
+    pub timeout_sec: u64,
+    pub status_message: Option<String>,
+    pub additional_context_limit: AdditionalContextLimit,
+    pub source_path: HandlerSourcePath,
+    pub source: HookSource,
+    pub display_order: i64,
+    pub kind: ConfiguredHandlerKind,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum HandlerSourcePath {
+    Local(AbsolutePathBuf),
+    /// Executor-scoped handlers are currently excluded from user-visible hook reporting
+    /// (events, summary, telemetry). Their handlers are always executed async.
+    ///
+    /// TODO: With CCA, all hooks will be executor-scoped, so user visibility
+    /// (participation in lifecycle events and summaries) and execution behavior
+    /// (non-blocking) will need to be determined independently.
+    ExecutorScoped {
+        plugin_id: PluginId,
+        environment_id: String,
+        mcp_environment_id: Option<String>,
+        mcp_metadata: Option<Box<Map<String, Value>>>,
+        manifest_path: PathUri,
+        source_relative_path: String,
+    },
+}
+
+impl From<AbsolutePathBuf> for HandlerSourcePath {
+    fn from(path: AbsolutePathBuf) -> Self {
+        Self::Local(path)
+    }
+}
+
+impl std::fmt::Display for HandlerSourcePath {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Local(path) => write!(formatter, "{}", path.display()),
+            Self::ExecutorScoped {
+                environment_id,
+                manifest_path,
+                source_relative_path,
+                ..
+            } => write!(
+                formatter,
+                "{environment_id}:{manifest_path}:{source_relative_path}"
+            ),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum ConfiguredHandlerKind {
+    Command {
+        command: String,
+        env: HashMap<String, String>,
+        r#async: bool,
+    },
+    McpTool {
+        server: String,
+        tool: String,
+        input: serde_json::Map<String, serde_json::Value>,
+    },
+}
+
+#[derive(Debug)]
+pub(crate) struct HandlerRunResult {
+    pub started_at: i64,
+    pub completed_at: i64,
+    pub duration_ms: i64,
+    pub exit_code: Option<i32>,
+    pub stdout: String,
+    pub stderr: String,
+    pub error: Option<String>,
+}
+
+impl ConfiguredHandler {
+    pub(crate) fn execution_mode(&self) -> HookExecutionMode {
+        if matches!(self.source_path, HandlerSourcePath::ExecutorScoped { .. }) {
+            return HookExecutionMode::Async;
+        }
+
+        match self.kind {
+            ConfiguredHandlerKind::Command { r#async: true, .. } => HookExecutionMode::Async,
+            ConfiguredHandlerKind::Command { r#async: false, .. }
+            | ConfiguredHandlerKind::McpTool { .. } => HookExecutionMode::Sync,
+        }
+    }
+
+    /// Only synchronous hooks can apply control effects.
+    pub(crate) fn can_apply_control_effects(&self) -> bool {
+        self.execution_mode() == HookExecutionMode::Sync
+    }
+
+    pub fn run_id(&self) -> String {
+        format!(
+            "{}:{}:{}",
+            self.event_name_label(),
+            self.display_order,
+            self.source_path
+        )
+    }
+
+    fn event_name_label(&self) -> &'static str {
+        match self.event_name {
+            codex_protocol::protocol::HookEventName::PreToolUse => "pre-tool-use",
+            codex_protocol::protocol::HookEventName::PermissionRequest => "permission-request",
+            codex_protocol::protocol::HookEventName::PostToolUse => "post-tool-use",
+            codex_protocol::protocol::HookEventName::PreCompact => "pre-compact",
+            codex_protocol::protocol::HookEventName::PostCompact => "post-compact",
+            codex_protocol::protocol::HookEventName::SessionStart => "session-start",
+            codex_protocol::protocol::HookEventName::SessionEnd => "session-end",
+            codex_protocol::protocol::HookEventName::UserPromptSubmit => "user-prompt-submit",
+            codex_protocol::protocol::HookEventName::SubagentStart => "subagent-start",
+            codex_protocol::protocol::HookEventName::SubagentStop => "subagent-stop",
+            codex_protocol::protocol::HookEventName::Stop => "stop",
+            codex_protocol::protocol::HookEventName::Interrupt => "interrupt",
+        }
+    }
+
+    fn handler_type(&self) -> HookHandlerType {
+        match &self.kind {
+            ConfiguredHandlerKind::Command { .. } => HookHandlerType::Command,
+            ConfiguredHandlerKind::McpTool { .. } => HookHandlerType::McpTool,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum HookListEntryHandler {
+    Command { command: String, r#async: bool },
+    McpTool { server: String, tool: String },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HookListEntry {
+    /// Builtin hooks remain available internally but are omitted from the public hooks list.
+    pub builtin: bool,
+    pub key: String,
+    pub event_name: HookEventName,
+    pub handler: HookListEntryHandler,
+    pub matcher: Option<String>,
+    pub timeout_sec: u64,
+    pub status_message: Option<String>,
+    pub additional_context_limit: Option<usize>,
+    pub source_path: AbsolutePathBuf,
+    pub source: HookSource,
+    pub plugin_id: Option<String>,
+    pub display_order: i64,
+    pub enabled: bool,
+    pub is_managed: bool,
+    pub current_hash: String,
+    pub trust_status: HookTrustStatus,
+}
+
+#[derive(Clone)]
+pub(crate) struct ClaudeHooksEngine {
+    pub(crate) handlers: Vec<ConfiguredHandler>,
+    warnings: Vec<String>,
+    required_load_errors: Vec<String>,
+    pub(crate) command_runtime: CommandHookRuntime,
+    pub(crate) mcp_executor: Arc<dyn HookMcpExecutor>,
+}
+
+impl ClaudeHooksEngine {
+    pub(crate) fn new(
+        enabled: bool,
+        bypass_hook_trust: bool,
+        config_layer_stack: Option<&ConfigLayerStack>,
+        plugin_hook_sources: Vec<PluginHookSource>,
+        plugin_hook_load_warnings: Vec<String>,
+        command_runtime: CommandHookRuntime,
+        mcp_executor: Arc<dyn HookMcpExecutor>,
+    ) -> Self {
+        if !enabled && plugin_hook_sources.is_empty() {
+            return Self {
+                handlers: Vec::new(),
+                warnings: Vec::new(),
+                required_load_errors: Vec::new(),
+                command_runtime,
+                mcp_executor,
+            };
+        }
+
+        let _ = schema_loader::generated_hook_schemas();
+        let mut discovered = discovery::discover_handlers(
+            config_layer_stack,
+            plugin_hook_sources,
+            plugin_hook_load_warnings,
+            bypass_hook_trust,
+        );
+        if !enabled {
+            discovered.handlers.retain(|handler| handler.builtin);
+            // Disabled ordinary hooks must not emit warnings or reject session startup.
+            discovered.warnings.clear();
+            discovered.required_load_errors.clear();
+        }
+        Self {
+            handlers: discovered.handlers,
+            warnings: discovered.warnings,
+            required_load_errors: discovered.required_load_errors,
+            command_runtime,
+            mcp_executor,
+        }
+    }
+
+    pub(crate) fn warnings(&self) -> &[String] {
+        &self.warnings
+    }
+
+    pub(crate) fn set_executor_hooks(&mut self, executor_hooks: Vec<ExecutorPluginHookSource>) {
+        self.handlers.retain(|handler| {
+            !matches!(
+                handler.source_path,
+                HandlerSourcePath::ExecutorScoped { .. }
+            )
+        });
+
+        let mut display_order = self
+            .handlers
+            .iter()
+            .map(|handler| handler.display_order)
+            .max()
+            .map_or(0, |display_order| display_order.saturating_add(1));
+        let mut seen_targets = HashSet::new();
+        for source in executor_hooks {
+            for (event_name, groups) in source.hooks.into_matcher_groups() {
+                let Some(handler) = groups.into_iter().flat_map(|group| group.hooks).next() else {
+                    continue;
+                };
+                let HookHandlerConfig::McpTool {
+                    server,
+                    tool,
+                    input,
+                    timeout_sec,
+                    status_message,
+                } = handler
+                else {
+                    unreachable!("allowlisted executor handler must be an MCP tool");
+                };
+
+                // Bundled plugins can share a cleanup target; run it once per event
+                // and MCP environment.
+                let target = (
+                    std::mem::discriminant(&event_name),
+                    source
+                        .mcp_environment_id
+                        .as_ref()
+                        .unwrap_or(&source.environment_id)
+                        .clone(),
+                    server.clone(),
+                    tool.clone(),
+                );
+                if !seen_targets.insert(target) {
+                    continue;
+                }
+                self.handlers.push(ConfiguredHandler {
+                    builtin: true,
+                    event_name,
+                    matcher: None,
+                    timeout_sec: timeout_sec.unwrap_or(5).max(1),
+                    status_message,
+                    additional_context_limit: Default::default(),
+                    source_path: HandlerSourcePath::ExecutorScoped {
+                        plugin_id: source.plugin_id.clone(),
+                        environment_id: source.environment_id.clone(),
+                        mcp_environment_id: source.mcp_environment_id.clone(),
+                        mcp_metadata: source.mcp_metadata.clone().map(Box::new),
+                        manifest_path: source.manifest_path.clone(),
+                        source_relative_path: source.source_relative_path.clone(),
+                    },
+                    source: HookSource::Plugin,
+                    display_order,
+                    kind: ConfiguredHandlerKind::McpTool {
+                        server,
+                        tool,
+                        input,
+                    },
+                });
+                display_order = display_order.saturating_add(1);
+            }
+        }
+    }
+
+    pub(crate) fn required_load_errors(&self) -> &[String] {
+        &self.required_load_errors
+    }
+
+    pub(crate) fn preview_session_start(
+        &self,
+        request: &SessionStartRequest,
+    ) -> Vec<HookRunSummary> {
+        crate::events::session_start::preview(&self.handlers, request)
+    }
+
+    pub(crate) fn preview_pre_tool_use(&self, request: &PreToolUseRequest) -> Vec<HookRunSummary> {
+        crate::events::pre_tool_use::preview(&self.handlers, request)
+    }
+
+    pub(crate) fn preview_permission_request(
+        &self,
+        request: &PermissionRequestRequest,
+    ) -> Vec<HookRunSummary> {
+        crate::events::permission_request::preview(&self.handlers, request)
+    }
+
+    pub(crate) fn max_permission_request_timeout(&self) -> Duration {
+        Duration::from_secs(
+            self.handlers
+                .iter()
+                .filter(|handler| {
+                    handler.event_name == HookEventName::PermissionRequest
+                        && handler.can_apply_control_effects()
+                })
+                .map(|handler| handler.timeout_sec)
+                .max()
+                .unwrap_or_default(),
+        )
+    }
+
+    pub(crate) fn preview_post_tool_use(
+        &self,
+        request: &PostToolUseRequest,
+    ) -> Vec<HookRunSummary> {
+        crate::events::post_tool_use::preview(&self.handlers, request)
+    }
+
+    pub(crate) async fn run_session_start(
+        &self,
+        request: SessionStartRequest,
+        turn_id: Option<String>,
+    ) -> SessionStartOutcome {
+        crate::events::session_start::run(self, request, turn_id).await
+    }
+
+    pub(crate) async fn run_pre_tool_use(&self, request: PreToolUseRequest) -> PreToolUseOutcome {
+        crate::events::pre_tool_use::run(self, request).await
+    }
+
+    pub(crate) async fn run_permission_request(
+        &self,
+        request: PermissionRequestRequest,
+    ) -> PermissionRequestOutcome {
+        crate::events::permission_request::run(self, request).await
+    }
+
+    pub(crate) async fn run_post_tool_use(
+        &self,
+        request: PostToolUseRequest,
+    ) -> PostToolUseOutcome {
+        let mut outcome = crate::events::post_tool_use::run(self, request).await;
+        if let Some(feedback_message) = outcome.feedback_message.take() {
+            outcome.feedback_message = Some(
+                self.command_runtime
+                    .output_spiller()
+                    .maybe_spill_text(feedback_message)
+                    .await,
+            );
+        }
+        outcome
+    }
+
+    pub(crate) fn preview_pre_compact(&self, request: &PreCompactRequest) -> Vec<HookRunSummary> {
+        crate::events::compact::preview_pre(&self.handlers, request)
+    }
+
+    pub(crate) async fn run_pre_compact(&self, request: PreCompactRequest) -> PreCompactOutcome {
+        crate::events::compact::run_pre(self, request).await
+    }
+
+    pub(crate) fn preview_post_compact(&self, request: &PostCompactRequest) -> Vec<HookRunSummary> {
+        crate::events::compact::preview_post(&self.handlers, request)
+    }
+
+    pub(crate) async fn run_post_compact(
+        &self,
+        request: PostCompactRequest,
+    ) -> StatelessHookOutcome {
+        crate::events::compact::run_post(self, request).await
+    }
+
+    pub(crate) fn preview_user_prompt_submit(
+        &self,
+        request: &UserPromptSubmitRequest,
+    ) -> Vec<HookRunSummary> {
+        crate::events::user_prompt_submit::preview(&self.handlers, request)
+    }
+
+    pub(crate) async fn run_user_prompt_submit(
+        &self,
+        request: UserPromptSubmitRequest,
+    ) -> UserPromptSubmitOutcome {
+        crate::events::user_prompt_submit::run(self, request).await
+    }
+
+    pub(crate) fn preview_stop(&self, request: &StopRequest) -> Vec<HookRunSummary> {
+        crate::events::stop::preview(&self.handlers, request)
+    }
+
+    pub(crate) fn preview_session_end(&self) -> Vec<HookRunSummary> {
+        crate::events::session_end::preview(&self.handlers)
+    }
+
+    pub(crate) async fn run_session_end(&self, request: SessionEndRequest) -> SessionEndOutcome {
+        crate::events::session_end::run(self, request).await
+    }
+
+    pub(crate) async fn run_stop(&self, request: StopRequest) -> StopOutcome {
+        let mut outcome = crate::events::stop::run(self, request).await;
+        outcome.continuation_fragments = self
+            .command_runtime
+            .output_spiller()
+            .maybe_spill_prompt_fragments(outcome.continuation_fragments)
+            .await;
+        outcome
+    }
+
+    pub(crate) fn preview_interrupt(&self) -> Vec<HookRunSummary> {
+        crate::events::interrupt::preview(&self.handlers)
+    }
+
+    pub(crate) async fn run_interrupt(&self, request: InterruptRequest) -> InterruptOutcome {
+        crate::events::interrupt::run(self, request).await
+    }
+}
+
+#[cfg(test)]
+#[path = "mod_tests.rs"]
+mod tests;
diff --git a/codex-rs/hooks/src/engine/mod_tests.rs b/codex-rs/hooks/src/engine/mod_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a185e45029ffa6f88c647e862d6bae396661fb22
--- /dev/null
+++ b/codex-rs/hooks/src/engine/mod_tests.rs
@@ -0,0 +1,2889 @@
+use std::collections::HashMap;
+use std::fs;
+use std::path::Path;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+
+use codex_config::AbsolutePathBuf;
+use codex_config::ConfigLayerEntry;
+use codex_config::ConfigLayerSource;
+use codex_config::ConfigLayerStack;
+use codex_config::ConfigRequirements;
+use codex_config::ConfigRequirementsToml;
+use codex_config::Constrained;
+use codex_config::ConstrainedWithSource;
+use codex_config::HookEventsToml;
+use codex_config::HookHandlerConfig;
+use codex_config::ManagedHooksRequirementsToml;
+use codex_config::MatcherGroup;
+use codex_config::RequirementSource;
+use codex_config::Sourced;
+use codex_config::TomlValue;
+use codex_plugin::ExecutorPluginHookSource;
+use codex_plugin::PluginHookSource;
+use codex_plugin::PluginId;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookExecutionMode;
+use codex_protocol::protocol::HookHandlerType;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookSource;
+use codex_protocol::protocol::HookTrustStatus;
+use futures::FutureExt;
+use futures::future::BoxFuture;
+use pretty_assertions::assert_eq;
+use tempfile::tempdir;
+use tokio::sync::Notify;
+
+use super::ClaudeHooksEngine;
+use super::CommandHookRuntime;
+use super::CommandShell;
+use super::ConfiguredHandler;
+use super::ConfiguredHandlerKind;
+use super::HandlerSourcePath;
+use super::HookListEntryHandler;
+use crate::events::interrupt::InterruptRequest;
+use crate::events::pre_tool_use::PreToolUseRequest;
+use crate::events::stop::StopHookTarget;
+use crate::events::stop::StopRequest;
+use crate::mcp::HookMcpCall;
+use crate::mcp::HookMcpExecutor;
+
+fn cwd() -> AbsolutePathBuf {
+    AbsolutePathBuf::current_dir().expect("current dir")
+}
+
+fn command_runtime(shell: CommandShell) -> CommandHookRuntime {
+    let (result_sender, _result_receiver) = async_channel::unbounded();
+    CommandHookRuntime::new(
+        shell,
+        Arc::new(std::env::vars_os().collect()),
+        ThreadId::new(),
+        result_sender,
+    )
+}
+
+pub(crate) fn mcp_executor() -> Arc<dyn HookMcpExecutor> {
+    Arc::new(StaticMcpExecutor {
+        calls: Arc::new(Mutex::new(Vec::new())),
+        output: String::new(),
+        outputs_by_tool: HashMap::new(),
+    })
+}
+
+#[test]
+fn permission_request_timeout_only_counts_synchronous_handlers() {
+    let mut engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        /*config_layer_stack*/ None,
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+    let command = "echo synchronous permission hook";
+    let synchronous_handler = ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::PermissionRequest,
+        matcher: None,
+        timeout_sec: 5,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: cwd().join("hooks.json").into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: command.to_string(),
+            r#async: false,
+            env: HashMap::new(),
+        },
+    };
+    let asynchronous_handler = ConfiguredHandler {
+        timeout_sec: 600,
+        kind: ConfiguredHandlerKind::Command {
+            command: command.to_string(),
+            r#async: true,
+            env: HashMap::new(),
+        },
+        ..synchronous_handler.clone()
+    };
+
+    engine.handlers = vec![synchronous_handler, asynchronous_handler.clone()];
+    assert_eq!(
+        engine.max_permission_request_timeout(),
+        Duration::from_secs(5)
+    );
+
+    engine.handlers = vec![asynchronous_handler];
+    assert_eq!(engine.max_permission_request_timeout(), Duration::ZERO);
+}
+
+fn managed_hooks_for_current_platform(
+    managed_dir: impl AsRef<Path>,
+    hooks: HookEventsToml,
+) -> ManagedHooksRequirementsToml {
+    let managed_dir = managed_dir.as_ref().to_path_buf();
+    ManagedHooksRequirementsToml {
+        managed_dir: if cfg!(windows) {
+            None
+        } else {
+            Some(managed_dir.clone())
+        },
+        windows_managed_dir: if cfg!(windows) {
+            Some(managed_dir)
+        } else {
+            None
+        },
+        hooks,
+    }
+}
+
+fn pre_tool_use_hook_events(command: impl Into<String>) -> HookEventsToml {
+    HookEventsToml {
+        pre_tool_use: vec![MatcherGroup {
+            matcher: Some("^Bash$".to_string()),
+            hooks: vec![HookHandlerConfig::Command {
+                command: command.into(),
+                command_windows: None,
+                timeout_sec: Some(10),
+                r#async: false,
+                status_message: Some("checking".to_string()),
+                additional_context_limit: None,
+            }],
+        }],
+        ..Default::default()
+    }
+}
+
+fn config_toml_with_pre_tool_use(command: &str) -> TomlValue {
+    let mut config_toml = TomlValue::Table(Default::default());
+    let TomlValue::Table(config_table) = &mut config_toml else {
+        unreachable!("config TOML root should be a table");
+    };
+    let mut hooks_table = TomlValue::Table(Default::default());
+    let TomlValue::Table(hooks_entries) = &mut hooks_table else {
+        unreachable!("hooks entry should be a table");
+    };
+    let mut pre_tool_use_group = TomlValue::Table(Default::default());
+    let TomlValue::Table(pre_tool_use_group_entries) = &mut pre_tool_use_group else {
+        unreachable!("PreToolUse group should be a table");
+    };
+    pre_tool_use_group_entries.insert(
+        "matcher".to_string(),
+        TomlValue::String("^Bash$".to_string()),
+    );
+    let mut handler = TomlValue::Table(Default::default());
+    let TomlValue::Table(handler_entries) = &mut handler else {
+        unreachable!("PreToolUse handler should be a table");
+    };
+    handler_entries.insert("type".to_string(), TomlValue::String("command".to_string()));
+    handler_entries.insert(
+        "command".to_string(),
+        TomlValue::String(command.to_string()),
+    );
+    handler_entries.insert("timeout".to_string(), TomlValue::Integer(10));
+    handler_entries.insert(
+        "statusMessage".to_string(),
+        TomlValue::String("checking".to_string()),
+    );
+    pre_tool_use_group_entries.insert("hooks".to_string(), TomlValue::Array(vec![handler]));
+    hooks_entries.insert(
+        "PreToolUse".to_string(),
+        TomlValue::Array(vec![pre_tool_use_group]),
+    );
+    config_table.insert("hooks".to_string(), hooks_table);
+    config_toml
+}
+
+fn requirements_with_managed_hooks_only(
+    allow_managed_hooks_only: bool,
+    managed_hooks: Option<ManagedHooksRequirementsToml>,
+) -> (ConfigRequirements, ConfigRequirementsToml) {
+    (
+        ConfigRequirements {
+            allow_managed_hooks_only: Some(Sourced::new(
+                allow_managed_hooks_only,
+                RequirementSource::LegacyManagedConfigTomlFromMdm,
+            )),
+            managed_hooks: managed_hooks.clone().map(|hooks| {
+                ConstrainedWithSource::new(
+                    Constrained::allow_any(hooks),
+                    Some(RequirementSource::LegacyManagedConfigTomlFromMdm),
+                )
+            }),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            allow_managed_hooks_only: Some(allow_managed_hooks_only),
+            hooks: managed_hooks,
+            ..ConfigRequirementsToml::default()
+        },
+    )
+}
+
+fn required_hooks_stack(
+    managed_hooks: ManagedHooksRequirementsToml,
+    source: RequirementSource,
+) -> ConfigLayerStack {
+    ConfigLayerStack::new(
+        Vec::new(),
+        ConfigRequirements {
+            managed_hooks: Some(ConstrainedWithSource::new(
+                Constrained::allow_any(managed_hooks.clone()),
+                Some(source),
+            )),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            hooks: Some(managed_hooks),
+            ..ConfigRequirementsToml::default()
+        },
+    )
+    .expect("config layer stack")
+}
+
+#[test]
+fn required_managed_hooks_allow_disabled_hooks_feature() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_hooks =
+        managed_hooks_for_current_platform(temp.path(), pre_tool_use_hook_events("  "));
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks,
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    for plugin_hook_sources in [
+        Vec::new(),
+        vec![bundled_cleanup_source(
+            "browser@openai-bundled",
+            "node_repl",
+            "Stop",
+        )],
+    ] {
+        let (hooks, _result_receiver) = crate::Hooks::new(
+            crate::HooksConfig {
+                feature_enabled: false,
+                config_layer_stack: Some(config_layer_stack.clone()),
+                plugin_hook_sources,
+                ..Default::default()
+            },
+            ThreadId::new(),
+            mcp_executor(),
+        )
+        .expect("disabled hooks feature should not enforce managed requirements hooks");
+
+        assert!(hooks.startup_warnings().is_empty());
+    }
+}
+
+#[test]
+fn required_managed_hooks_reject_invalid_matchers() {
+    let temp = tempdir().expect("create temp dir");
+    let mut events = pre_tool_use_hook_events("echo managed");
+    events.pre_tool_use[0].matcher = Some("[".to_string());
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), events),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let error = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .err()
+    .expect("invalid required managed matcher should reject startup");
+
+    assert!(error.to_string().contains("invalid matcher"));
+}
+
+#[test]
+fn required_managed_hooks_allow_invalid_matchers_without_handlers() {
+    let temp = tempdir().expect("create temp dir");
+    let mut events = pre_tool_use_hook_events("echo managed");
+    events.pre_tool_use.push(MatcherGroup {
+        matcher: Some("[".to_string()),
+        hooks: Vec::new(),
+    });
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), events),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let (hooks, _result_receiver) = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .expect("an empty matcher group should not prevent required managed hooks from loading");
+
+    assert_eq!(hooks.startup_warnings().len(), 1);
+    assert!(hooks.startup_warnings()[0].contains("invalid matcher"));
+}
+
+#[test]
+fn required_managed_hooks_reject_empty_commands() {
+    let temp = tempdir().expect("create temp dir");
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), pre_tool_use_hook_events("  ")),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let error = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .err()
+    .expect("empty required managed command should reject startup");
+
+    assert!(error.to_string().contains("skipping empty hook command"));
+}
+
+#[test]
+fn required_managed_hooks_reject_unsupported_handler_types() {
+    let temp = tempdir().expect("create temp dir");
+    let events = HookEventsToml {
+        pre_tool_use: vec![MatcherGroup {
+            matcher: Some("^Bash$".to_string()),
+            hooks: vec![HookHandlerConfig::Prompt {}],
+        }],
+        ..Default::default()
+    };
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), events),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let error = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .err()
+    .expect("unsupported required managed handler should reject startup");
+
+    assert!(
+        error
+            .to_string()
+            .contains("prompt hooks are not supported yet")
+    );
+}
+
+#[test]
+fn required_managed_mcp_hooks_reject_empty_targets() {
+    let temp = tempdir().expect("create temp dir");
+    let events = HookEventsToml {
+        pre_tool_use: vec![MatcherGroup {
+            matcher: Some("^Bash$".to_string()),
+            hooks: vec![HookHandlerConfig::McpTool {
+                server: "policy".to_string(),
+                tool: " ".to_string(),
+                input: Default::default(),
+                timeout_sec: None,
+                status_message: None,
+            }],
+        }],
+        ..Default::default()
+    };
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), events),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let error = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .err()
+    .expect("invalid required managed MCP hook should reject startup");
+
+    assert!(
+        error
+            .to_string()
+            .contains("server and tool must not be empty")
+    );
+}
+
+#[test]
+fn required_managed_session_end_mcp_hooks_reject_startup() {
+    let temp = tempdir().expect("create temp dir");
+    let events = HookEventsToml {
+        session_end: vec![MatcherGroup {
+            matcher: None,
+            hooks: vec![HookHandlerConfig::McpTool {
+                server: "policy".to_string(),
+                tool: "check".to_string(),
+                input: Default::default(),
+                timeout_sec: None,
+                status_message: None,
+            }],
+        }],
+        ..Default::default()
+    };
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), events),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let error = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .err()
+    .expect("required managed SessionEnd MCP hook should reject startup");
+
+    assert!(
+        error
+            .to_string()
+            .contains("SessionEnd MCP hooks are not supported")
+    );
+}
+
+#[test]
+fn required_managed_hooks_with_unknown_source_still_reject_discovery_failures() {
+    let temp = tempdir().expect("create temp dir");
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), pre_tool_use_hook_events("")),
+        RequirementSource::Unknown,
+    );
+
+    let error = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .err()
+    .expect("unknown-source managed requirements hook should still reject startup");
+
+    assert!(error.to_string().contains("skipping empty hook command"));
+}
+
+#[test]
+fn valid_required_managed_hooks_allow_startup() {
+    let temp = tempdir().expect("create temp dir");
+    let config_layer_stack = required_hooks_stack(
+        managed_hooks_for_current_platform(temp.path(), pre_tool_use_hook_events("echo managed")),
+        RequirementSource::LegacyManagedConfigTomlFromMdm,
+    );
+
+    let (hooks, _result_receiver) = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .expect("valid managed requirements hook should allow startup");
+
+    assert!(hooks.startup_warnings().is_empty());
+}
+
+#[test]
+fn managed_config_layer_hook_failures_remain_startup_warnings() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::System { file: config_path },
+            config_toml_with_pre_tool_use("  "),
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let (hooks, _result_receiver) = crate::Hooks::new(
+        crate::HooksConfig {
+            feature_enabled: true,
+            config_layer_stack: Some(config_layer_stack),
+            ..Default::default()
+        },
+        ThreadId::new(),
+        mcp_executor(),
+    )
+    .expect("managed config layer hooks should remain optional");
+
+    assert_eq!(hooks.startup_warnings().len(), 1);
+    assert!(hooks.startup_warnings()[0].contains("skipping empty hook command"));
+}
+
+#[tokio::test]
+async fn requirements_managed_hooks_execute_from_managed_dir() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_dir =
+        AbsolutePathBuf::try_from(temp.path().join("managed-hooks")).expect("absolute path");
+    fs::create_dir_all(managed_dir.as_path()).expect("create managed hooks dir");
+    let script_path = managed_dir.join("pre_tool_use.py");
+    let log_path = managed_dir.join("pre_tool_use_log.jsonl");
+    fs::write(
+        script_path.as_path(),
+        format!(
+            r#"import json
+from pathlib import Path
+import sys
+
+payload = json.load(sys.stdin)
+with Path(r"{log_path}").open("a", encoding="utf-8") as handle:
+    handle.write(json.dumps(payload) + "\n")
+"#,
+            log_path = log_path.display(),
+        ),
+    )
+    .expect("write managed hook script");
+
+    let managed_hooks = managed_hooks_for_current_platform(
+        managed_dir.clone(),
+        HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("^Bash$".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: format!("python3 {}", script_path.display()),
+                    command_windows: None,
+                    timeout_sec: Some(10),
+                    r#async: false,
+                    status_message: Some("checking".to_string()),
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        Vec::new(),
+        ConfigRequirements {
+            managed_hooks: Some(ConstrainedWithSource::new(
+                Constrained::allow_any(managed_hooks.clone()),
+                Some(RequirementSource::LegacyManagedConfigTomlFromMdm),
+            )),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            hooks: Some(managed_hooks),
+            ..ConfigRequirementsToml::default()
+        },
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().is_empty());
+    assert_eq!(engine.handlers.len(), 1);
+    assert_eq!(
+        engine.handlers[0].source,
+        HookSource::LegacyManagedConfigMdm
+    );
+    let listed = crate::list_hooks(crate::HooksConfig {
+        legacy_notify_argv: None,
+        feature_enabled: true,
+        bypass_hook_trust: false,
+        config_layer_stack: Some(config_layer_stack.clone()),
+        plugin_hook_sources: Vec::new(),
+        plugin_hook_load_warnings: Vec::new(),
+        shell_program: None,
+        shell_args: Vec::new(),
+    });
+    assert!(listed.hooks[0].is_managed);
+    let cwd = cwd();
+    let preview = engine.preview_pre_tool_use(&PreToolUseRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        subagent: None,
+        cwd: cwd.clone(),
+        transcript_path: None,
+        model: "gpt-test".to_string(),
+        permission_mode: "default".to_string(),
+        tool_name: "Bash".to_string(),
+        matcher_aliases: Vec::new(),
+        tool_use_id: "tool-1".to_string(),
+        tool_input: serde_json::json!({ "command": "echo hello" }),
+    });
+    assert_eq!(preview.len(), 1);
+    assert_eq!(preview[0].source_path, managed_dir);
+
+    let outcome = engine
+        .run_pre_tool_use(PreToolUseRequest {
+            session_id: ThreadId::new(),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd,
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            matcher_aliases: Vec::new(),
+            tool_use_id: "tool-1".to_string(),
+            tool_input: serde_json::json!({ "command": "echo hello" }),
+        })
+        .await;
+
+    assert!(!outcome.should_block);
+    let log_contents = fs::read_to_string(log_path).expect("read managed hook log");
+    assert!(log_contents.contains("\"hook_event_name\": \"PreToolUse\""));
+}
+
+#[tokio::test]
+async fn requirements_managed_hooks_execute_windows_command_override() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_dir =
+        AbsolutePathBuf::try_from(temp.path().join("managed-hooks")).expect("absolute path");
+    fs::create_dir_all(managed_dir.as_path()).expect("create managed hooks dir");
+
+    let managed_hooks = managed_hooks_for_current_platform(
+        managed_dir,
+        HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("^Bash$".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: "exit 17".to_string(),
+                    command_windows: Some("exit /B 19".to_string()),
+                    timeout_sec: Some(10),
+                    r#async: false,
+                    status_message: Some("checking".to_string()),
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        Vec::new(),
+        ConfigRequirements {
+            managed_hooks: Some(ConstrainedWithSource::new(
+                Constrained::allow_any(managed_hooks.clone()),
+                Some(RequirementSource::LegacyManagedConfigTomlFromMdm),
+            )),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            hooks: Some(managed_hooks),
+            ..ConfigRequirementsToml::default()
+        },
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    let outcome = engine
+        .run_pre_tool_use(PreToolUseRequest {
+            session_id: ThreadId::new(),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd: cwd(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            matcher_aliases: Vec::new(),
+            tool_use_id: "tool-1".to_string(),
+            tool_input: serde_json::json!({ "command": "echo hello" }),
+        })
+        .await;
+
+    assert!(!outcome.should_block);
+    let expected_exit_code = if cfg!(windows) { 19 } else { 17 };
+    assert_eq!(outcome.hook_events.len(), 1);
+    assert_eq!(outcome.hook_events[0].run.status, HookRunStatus::Failed);
+    assert_eq!(
+        outcome.hook_events[0].run.entries,
+        vec![HookOutputEntry {
+            kind: HookOutputEntryKind::Error,
+            text: format!("hook exited with code {expected_exit_code}"),
+        }]
+    );
+}
+
+#[test]
+fn unknown_requirement_source_hooks_stay_managed() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_dir =
+        AbsolutePathBuf::try_from(temp.path().join("managed-hooks")).expect("absolute path");
+    fs::create_dir_all(managed_dir.as_path()).expect("create managed hooks dir");
+    let managed_hooks = managed_hooks_for_current_platform(
+        managed_dir,
+        HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("^Bash$".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: "python3 /tmp/managed.py".to_string(),
+                    command_windows: None,
+                    timeout_sec: Some(10),
+                    r#async: false,
+                    status_message: Some("checking".to_string()),
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        Vec::new(),
+        ConfigRequirements {
+            managed_hooks: Some(ConstrainedWithSource::new(
+                Constrained::allow_any(managed_hooks.clone()),
+                Some(RequirementSource::Unknown),
+            )),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            hooks: Some(managed_hooks),
+            ..ConfigRequirementsToml::default()
+        },
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert_eq!(engine.handlers.len(), 1);
+    assert_eq!(engine.handlers[0].source, HookSource::Unknown);
+    let discovered = super::discovery::discover_handlers(
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.hook_entries.len(), 1);
+    assert_eq!(discovered.hook_entries[0].source, HookSource::Unknown);
+    assert_eq!(discovered.hook_entries[0].enabled, true);
+    assert_eq!(discovered.hook_entries[0].is_managed, true);
+    assert_eq!(
+        discovered.hook_entries[0].trust_status,
+        HookTrustStatus::Managed
+    );
+}
+
+#[test]
+fn user_disablement_filters_non_managed_hooks_but_not_managed_hooks() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_dir =
+        AbsolutePathBuf::try_from(temp.path().join("managed-hooks")).expect("absolute path");
+    fs::create_dir_all(managed_dir.as_path()).expect("create managed hooks dir");
+    let managed_hooks = managed_hooks_for_current_platform(
+        managed_dir.clone(),
+        HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("^Bash$".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: "python3 /tmp/managed.py".to_string(),
+                    command_windows: None,
+                    timeout_sec: Some(10),
+                    r#async: false,
+                    status_message: Some("checking".to_string()),
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    );
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute path");
+    let managed_disabled_key = format!("{}:pre_tool_use:0:0", managed_dir.display());
+    let user_disabled_key = format!("{}:pre_tool_use:0:0", config_path.display());
+    let user_config = config_with_pre_tool_use_hook_and_states(
+        "python3 /tmp/user.py",
+        [&managed_disabled_key, &user_disabled_key],
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            user_config,
+        )],
+        ConfigRequirements {
+            managed_hooks: Some(ConstrainedWithSource::new(
+                Constrained::allow_any(managed_hooks.clone()),
+                Some(RequirementSource::LegacyManagedConfigTomlFromMdm),
+            )),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            hooks: Some(managed_hooks),
+            ..ConfigRequirementsToml::default()
+        },
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert_eq!(engine.handlers.len(), 1);
+    assert_eq!(
+        engine.handlers[0].source,
+        HookSource::LegacyManagedConfigMdm
+    );
+    let discovered = super::discovery::discover_handlers(
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.hook_entries.len(), 2);
+    assert_eq!(discovered.hook_entries[0].key, managed_disabled_key);
+    assert_eq!(discovered.hook_entries[0].enabled, true);
+    assert!(discovered.hook_entries[0].is_managed);
+    assert_eq!(
+        discovered.hook_entries[0].trust_status,
+        HookTrustStatus::Managed
+    );
+    assert_eq!(discovered.hook_entries[1].key, user_disabled_key);
+    assert_eq!(discovered.hook_entries[1].enabled, false);
+    assert!(!discovered.hook_entries[1].is_managed);
+}
+
+#[test]
+fn user_disablement_does_not_filter_managed_layer_hooks() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_config_path =
+        AbsolutePathBuf::try_from(temp.path().join("managed_config.toml")).expect("absolute path");
+    let user_config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute path");
+    let managed_key = format!("{}:pre_tool_use:0:0", managed_config_path.display());
+
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![
+            ConfigLayerEntry::new(
+                ConfigLayerSource::User {
+                    file: user_config_path,
+                    profile: None,
+                },
+                config_with_hook_state(&managed_key, /*enabled*/ false),
+            ),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+                    file: managed_config_path,
+                },
+                config_with_pre_tool_use_hook("python3 /tmp/managed-layer.py"),
+            ),
+        ],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert_eq!(engine.handlers.len(), 1);
+    assert_eq!(
+        engine.handlers[0].source,
+        HookSource::LegacyManagedConfigFile
+    );
+    let discovered = super::discovery::discover_handlers(
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.hook_entries.len(), 1);
+    assert_eq!(discovered.hook_entries[0].key, managed_key);
+    assert_eq!(discovered.hook_entries[0].enabled, true);
+    assert!(discovered.hook_entries[0].is_managed);
+    assert_eq!(
+        discovered.hook_entries[0].trust_status,
+        HookTrustStatus::Managed
+    );
+}
+
+fn config_with_hook_state(key: &str, enabled: bool) -> TomlValue {
+    serde_json::from_value(serde_json::json!({
+        "hooks": {
+            "state": {
+                (key): {
+                    "enabled": enabled,
+                },
+            },
+        },
+    }))
+    .expect("config TOML should deserialize")
+}
+
+fn config_with_pre_tool_use_hook_and_states<const N: usize>(
+    command: &str,
+    disabled_keys: [&str; N],
+) -> TomlValue {
+    let state = disabled_keys
+        .into_iter()
+        .map(|key| (key.to_string(), serde_json::json!({ "enabled": false })))
+        .collect::<serde_json::Map<_, _>>();
+    serde_json::from_value(serde_json::json!({
+        "hooks": {
+            "state": state,
+            "PreToolUse": [{
+                "hooks": [{
+                    "type": "command",
+                    "command": command,
+                }],
+            }],
+        },
+    }))
+    .expect("config TOML should deserialize")
+}
+
+fn config_with_pre_tool_use_hook(command: &str) -> TomlValue {
+    serde_json::from_value(serde_json::json!({
+        "hooks": {
+            "PreToolUse": [{
+                "hooks": [{
+                    "type": "command",
+                    "command": command,
+                }],
+            }],
+        },
+    }))
+    .expect("config TOML should deserialize")
+}
+
+fn trusted_plugin_hook_stack(
+    config_path: AbsolutePathBuf,
+    plugin_hook_sources: &[PluginHookSource],
+) -> ConfigLayerStack {
+    let discovered = super::discovery::discover_handlers(
+        /*config_layer_stack*/ None,
+        plugin_hook_sources.to_vec(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    let state = discovered
+        .hook_entries
+        .into_iter()
+        .map(|entry| {
+            (
+                entry.key,
+                serde_json::json!({
+                    "trusted_hash": entry.current_hash,
+                }),
+            )
+        })
+        .collect::<serde_json::Map<_, _>>();
+    let config = serde_json::from_value(serde_json::json!({
+        "hooks": {
+            "state": state,
+        },
+    }))
+    .expect("config TOML should deserialize");
+
+    ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            config,
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack")
+}
+
+#[test]
+fn requirements_managed_hooks_load_when_managed_dir_is_missing() {
+    let temp = tempdir().expect("create temp dir");
+    let missing_dir = temp.path().join("missing-managed-hooks");
+    let managed_hooks = managed_hooks_for_current_platform(
+        missing_dir.clone(),
+        HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("^Bash$".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: "echo hi".to_string(),
+                    command_windows: None,
+                    timeout_sec: Some(10),
+                    r#async: false,
+                    status_message: Some("checking".to_string()),
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        Vec::new(),
+        ConfigRequirements {
+            managed_hooks: Some(ConstrainedWithSource::new(
+                Constrained::allow_any(managed_hooks.clone()),
+                Some(RequirementSource::LegacyManagedConfigTomlFromMdm),
+            )),
+            ..ConfigRequirements::default()
+        },
+        ConfigRequirementsToml {
+            hooks: Some(managed_hooks),
+            ..ConfigRequirementsToml::default()
+        },
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().is_empty());
+    let cwd = cwd();
+    let preview = engine.preview_pre_tool_use(&PreToolUseRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        subagent: None,
+        cwd,
+        transcript_path: None,
+        model: "gpt-test".to_string(),
+        permission_mode: "default".to_string(),
+        tool_name: "Bash".to_string(),
+        matcher_aliases: Vec::new(),
+        tool_use_id: "tool-1".to_string(),
+        tool_input: serde_json::json!({ "command": "echo hello" }),
+    });
+    assert_eq!(preview.len(), 1);
+    assert_eq!(
+        engine.handlers[0].kind,
+        ConfiguredHandlerKind::Command {
+            command: "echo hi".to_string(),
+            r#async: false,
+            env: HashMap::new(),
+        }
+    );
+    assert_eq!(
+        engine.handlers[0].source_path,
+        AbsolutePathBuf::try_from(missing_dir)
+            .expect("absolute missing dir")
+            .into()
+    );
+}
+
+#[test]
+fn allow_managed_hooks_only_false_keeps_unmanaged_hooks() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let (requirements, requirements_toml) = requirements_with_managed_hooks_only(
+        /*allow_managed_hooks_only*/ false, /*managed_hooks*/ None,
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            config_toml_with_pre_tool_use("python3 /tmp/user-hook.py"),
+        )],
+        requirements,
+        requirements_toml,
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().is_empty());
+    assert!(engine.handlers.is_empty());
+    let discovered = super::discovery::discover_handlers(
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.hook_entries.len(), 1);
+    assert!(!discovered.hook_entries[0].is_managed);
+    assert_eq!(
+        discovered.hook_entries[0].handler,
+        HookListEntryHandler::Command {
+            command: "python3 /tmp/user-hook.py".to_string(),
+            r#async: false,
+        }
+    );
+}
+
+#[test]
+fn allow_managed_hooks_only_in_config_toml_does_not_enable_policy() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let mut config_toml = config_toml_with_pre_tool_use("python3 /tmp/user-hook.py");
+    let TomlValue::Table(config_table) = &mut config_toml else {
+        unreachable!("config TOML root should be a table");
+    };
+    config_table.insert(
+        "allow_managed_hooks_only".to_string(),
+        TomlValue::Boolean(true),
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            config_toml,
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().is_empty());
+    assert!(engine.handlers.is_empty());
+    let discovered = super::discovery::discover_handlers(
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.hook_entries.len(), 1);
+    assert!(!discovered.hook_entries[0].is_managed);
+    assert_eq!(
+        discovered.hook_entries[0].handler,
+        HookListEntryHandler::Command {
+            command: "python3 /tmp/user-hook.py".to_string(),
+            r#async: false,
+        }
+    );
+}
+
+#[test]
+fn allow_managed_hooks_only_skips_unmanaged_json_and_toml_hooks() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let hooks_json_path =
+        AbsolutePathBuf::try_from(temp.path().join("hooks.json")).expect("absolute hooks path");
+    fs::write(
+        hooks_json_path.as_path(),
+        r#"{
+              "hooks": {
+                "PreToolUse": [
+                  {
+                    "matcher": "^Bash$",
+                    "hooks": [
+                      {
+                        "type": "command",
+                        "command": "python3 /tmp/json-hook.py"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }"#,
+    )
+    .expect("write hooks.json");
+    let (requirements, requirements_toml) = requirements_with_managed_hooks_only(
+        /*allow_managed_hooks_only*/ true, /*managed_hooks*/ None,
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            config_toml_with_pre_tool_use("python3 /tmp/toml-hook.py"),
+        )],
+        requirements,
+        requirements_toml,
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.handlers.is_empty());
+    assert!(engine.warnings().is_empty());
+}
+
+#[test]
+fn allow_managed_hooks_only_skips_unmanaged_plugin_hooks() {
+    let temp = tempdir().expect("create temp dir");
+    let plugin_root =
+        AbsolutePathBuf::try_from(temp.path().join("demo-plugin")).expect("plugin root");
+    let plugin_data_root =
+        AbsolutePathBuf::try_from(temp.path().join("plugin-data")).expect("plugin data root");
+    let source_path = plugin_root.join("hooks/hooks.json");
+    let plugin_id = PluginId::parse("demo-plugin@test-marketplace").expect("plugin id");
+    let plugin_hook_sources = vec![PluginHookSource {
+        plugin_id,
+        plugin_root,
+        plugin_data_root,
+        source_path,
+        source_relative_path: "hooks/hooks.json".to_string(),
+        hooks: pre_tool_use_hook_events("python3 /tmp/plugin-hook.py"),
+    }];
+    let (requirements, requirements_toml) = requirements_with_managed_hooks_only(
+        /*allow_managed_hooks_only*/ true, /*managed_hooks*/ None,
+    );
+    let config_layer_stack = ConfigLayerStack::new(Vec::new(), requirements, requirements_toml)
+        .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        plugin_hook_sources,
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.handlers.is_empty());
+    assert!(engine.warnings().is_empty());
+}
+
+#[test]
+fn allow_managed_hooks_only_keeps_managed_requirement_and_config_layer_hooks() {
+    let temp = tempdir().expect("create temp dir");
+    let managed_dir =
+        AbsolutePathBuf::try_from(temp.path().join("managed-hooks")).expect("absolute path");
+    fs::create_dir_all(managed_dir.as_path()).expect("create managed hooks dir");
+    let system_config_path =
+        AbsolutePathBuf::try_from(temp.path().join("system").join("config.toml"))
+            .expect("absolute system config path");
+    let system_parent = system_config_path
+        .as_path()
+        .parent()
+        .expect("system config parent");
+    fs::create_dir_all(system_parent).expect("create system config dir");
+    let legacy_config_path = AbsolutePathBuf::try_from(temp.path().join("managed_config.toml"))
+        .expect("absolute legacy config path");
+
+    let managed_hooks = managed_hooks_for_current_platform(
+        managed_dir,
+        pre_tool_use_hook_events("python3 /tmp/requirements-hook.py"),
+    );
+    let (requirements, requirements_toml) = requirements_with_managed_hooks_only(
+        /*allow_managed_hooks_only*/ true,
+        Some(managed_hooks),
+    );
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![
+            ConfigLayerEntry::new(
+                ConfigLayerSource::Mdm {
+                    domain: "com.openai.codex".to_string(),
+                    key: "config".to_string(),
+                },
+                config_toml_with_pre_tool_use("python3 /tmp/mdm-hook.py"),
+            ),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::System {
+                    file: system_config_path,
+                },
+                config_toml_with_pre_tool_use("python3 /tmp/system-hook.py"),
+            ),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::LegacyManagedConfigTomlFromFile {
+                    file: legacy_config_path,
+                },
+                config_toml_with_pre_tool_use("python3 /tmp/legacy-file-hook.py"),
+            ),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::LegacyManagedConfigTomlFromMdm,
+                config_toml_with_pre_tool_use("python3 /tmp/legacy-mdm-hook.py"),
+            ),
+        ],
+        requirements,
+        requirements_toml,
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().is_empty());
+    assert_eq!(
+        engine
+            .handlers
+            .iter()
+            .map(|handler| match &handler.kind {
+                ConfiguredHandlerKind::Command { command, .. } => Some(command.as_str()),
+                ConfiguredHandlerKind::McpTool { .. } => None,
+            })
+            .collect::<Vec<_>>(),
+        vec![
+            Some("python3 /tmp/requirements-hook.py"),
+            Some("python3 /tmp/mdm-hook.py"),
+            Some("python3 /tmp/system-hook.py"),
+            Some("python3 /tmp/legacy-file-hook.py"),
+            Some("python3 /tmp/legacy-mdm-hook.py"),
+        ]
+    );
+    let discovered = super::discovery::discover_handlers(
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert!(discovered.hook_entries.iter().all(|entry| entry.is_managed));
+}
+
+#[test]
+fn discovers_hooks_from_json_and_toml_in_the_same_layer() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let hooks_json_path =
+        AbsolutePathBuf::try_from(temp.path().join("hooks.json")).expect("absolute hooks path");
+    fs::write(
+        hooks_json_path.as_path(),
+        r#"{
+              "hooks": {
+                "PreToolUse": [
+                  {
+                    "matcher": "^Bash$",
+                    "hooks": [
+                      {
+                        "type": "command",
+                        "command": "python3 /tmp/json-hook.py"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }"#,
+    )
+    .expect("write hooks.json");
+    let mut config_toml = TomlValue::Table(Default::default());
+    let TomlValue::Table(config_table) = &mut config_toml else {
+        unreachable!("config TOML root should be a table");
+    };
+    let mut hooks_table = TomlValue::Table(Default::default());
+    let TomlValue::Table(hooks_entries) = &mut hooks_table else {
+        unreachable!("hooks entry should be a table");
+    };
+    let mut pre_tool_use_group = TomlValue::Table(Default::default());
+    let TomlValue::Table(pre_tool_use_group_entries) = &mut pre_tool_use_group else {
+        unreachable!("PreToolUse group should be a table");
+    };
+    pre_tool_use_group_entries.insert(
+        "matcher".to_string(),
+        TomlValue::String("^Bash$".to_string()),
+    );
+    pre_tool_use_group_entries.insert(
+        "hooks".to_string(),
+        TomlValue::Array(vec![TomlValue::Table(Default::default())]),
+    );
+    let Some(TomlValue::Array(hooks_array)) = pre_tool_use_group_entries.get_mut("hooks") else {
+        unreachable!("PreToolUse hooks should be an array");
+    };
+    let Some(TomlValue::Table(handler_entries)) = hooks_array.first_mut() else {
+        unreachable!("PreToolUse handler should be a table");
+    };
+    handler_entries.insert("type".to_string(), TomlValue::String("command".to_string()));
+    handler_entries.insert(
+        "command".to_string(),
+        TomlValue::String("python3 /tmp/toml-hook.py".to_string()),
+    );
+    hooks_entries.insert(
+        "PreToolUse".to_string(),
+        TomlValue::Array(vec![pre_tool_use_group]),
+    );
+    config_table.insert("hooks".to_string(), hooks_table);
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::System {
+                file: config_path.clone(),
+            },
+            config_toml,
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().iter().any(|warning| {
+        warning.contains("loading hooks from both")
+            && warning.contains(&hooks_json_path.display().to_string())
+            && warning.contains(&config_path.display().to_string())
+    }));
+
+    let cwd = cwd();
+    let preview = engine.preview_pre_tool_use(&PreToolUseRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        subagent: None,
+        cwd,
+        transcript_path: None,
+        model: "gpt-test".to_string(),
+        permission_mode: "default".to_string(),
+        tool_name: "Bash".to_string(),
+        matcher_aliases: Vec::new(),
+        tool_use_id: "tool-1".to_string(),
+        tool_input: serde_json::json!({ "command": "echo hello" }),
+    });
+    assert_eq!(preview.len(), 2);
+    assert_eq!(
+        engine
+            .handlers
+            .iter()
+            .map(|handler| handler.source)
+            .collect::<Vec<_>>(),
+        vec![HookSource::System, HookSource::System]
+    );
+    assert_eq!(preview[0].source_path, hooks_json_path);
+    assert_eq!(preview[1].source_path, config_path);
+}
+
+#[test]
+fn profile_user_layers_load_shared_hooks_json_once() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let profile_path = AbsolutePathBuf::try_from(temp.path().join("work.config.toml"))
+        .expect("absolute profile path");
+    let hooks_json_path =
+        AbsolutePathBuf::try_from(temp.path().join("hooks.json")).expect("absolute hooks path");
+    fs::write(
+        hooks_json_path.as_path(),
+        r#"{
+              "hooks": {
+                "PreToolUse": [
+                  {
+                    "matcher": "^Bash$",
+                    "hooks": [
+                      {
+                        "type": "command",
+                        "command": "python3 /tmp/json-hook.py"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }"#,
+    )
+    .expect("write hooks.json");
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![
+            ConfigLayerEntry::new(
+                ConfigLayerSource::User {
+                    file: config_path,
+                    profile: None,
+                },
+                TomlValue::Table(Default::default()),
+            ),
+            ConfigLayerEntry::new(
+                ConfigLayerSource::User {
+                    file: profile_path,
+                    profile: Some("work".to_string()),
+                },
+                TomlValue::Table(Default::default()),
+            ),
+        ],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ true,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.warnings().is_empty());
+    assert_eq!(engine.handlers.len(), 1);
+    let preview = engine.preview_pre_tool_use(&PreToolUseRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        subagent: None,
+        cwd: cwd(),
+        transcript_path: None,
+        model: "gpt-test".to_string(),
+        permission_mode: "default".to_string(),
+        tool_name: "Bash".to_string(),
+        matcher_aliases: Vec::new(),
+        tool_use_id: "tool-1".to_string(),
+        tool_input: serde_json::json!({ "command": "echo hello" }),
+    });
+    assert_eq!(preview.len(), 1);
+    assert_eq!(preview[0].source_path, hooks_json_path);
+
+    let listed = crate::list_hooks(crate::HooksConfig {
+        feature_enabled: true,
+        bypass_hook_trust: true,
+        config_layer_stack: Some(config_layer_stack),
+        ..Default::default()
+    });
+    assert!(listed.warnings.is_empty());
+    assert_eq!(listed.hooks.len(), 1);
+    assert_eq!(listed.hooks[0].source_path, hooks_json_path);
+}
+
+#[test]
+fn malformed_hooks_json_is_reported_as_startup_warning() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    let hooks_json_path =
+        AbsolutePathBuf::try_from(temp.path().join("hooks.json")).expect("absolute hooks path");
+    fs::write(
+        hooks_json_path.as_path(),
+        r#"{
+          "SessionStart": [
+            {
+              "hooks": [
+                {
+                  "type": "command",
+                  "command": "python3 /tmp/session-start.py"
+                }
+              ]
+            }
+          ]
+        }"#,
+    )
+    .expect("write hooks.json");
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::System { file: config_path },
+            TomlValue::Table(Default::default()),
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert!(engine.handlers.is_empty());
+    assert_eq!(engine.warnings().len(), 1);
+    assert!(engine.warnings()[0].contains("failed to parse hooks config"));
+    assert!(
+        engine.warnings()[0].contains(&hooks_json_path.display().to_string()),
+        "warning should identify the malformed file: {}",
+        engine.warnings()[0]
+    );
+    assert!(engine.warnings()[0].contains("unknown field `SessionStart`"));
+}
+
+fn bundled_cleanup_source(plugin_id: &str, server: &str, event: &str) -> PluginHookSource {
+    let plugin_root = cwd().join("bundled-plugin");
+    PluginHookSource {
+        plugin_id: PluginId::parse(plugin_id).expect("plugin ID"),
+        plugin_data_root: plugin_root.join("data"),
+        source_path: plugin_root.join(".codex-plugin/plugin.json"),
+        source_relative_path: "plugin.json#hooks[0]".to_string(),
+        plugin_root,
+        hooks: serde_json::from_value(serde_json::json!({
+            (event): [{"hooks": [{
+                "type": "mcp_tool",
+                "server": server,
+                "tool": "turn_ended",
+                "input": {"turn_id": "${turn_id}"},
+            }]}],
+        }))
+        .expect("cleanup hooks"),
+    }
+}
+
+#[test]
+fn bundled_cleanup_hooks_are_trusted_without_saved_hashes() {
+    for (plugin_id, server) in [
+        ("browser@openai-bundled", "node_repl"),
+        ("chrome@openai-bundled", "node_repl"),
+        ("chrome-dev@openai-bundled", "node_repl"),
+        ("chrome-internal@openai-bundled", "node_repl"),
+        ("computer-use@openai-bundled", "node_repl"),
+        ("unified-computer-use@openai-bundled", "cua_repl"),
+    ] {
+        for event in ["Stop", "Interrupt", "SubagentStop"] {
+            let discovered = super::discovery::discover_handlers(
+                /*config_layer_stack*/ None,
+                vec![bundled_cleanup_source(plugin_id, server, event)],
+                Vec::new(),
+                /*bypass_hook_trust*/ false,
+            );
+            assert_eq!(discovered.handlers.len(), 1, "{plugin_id} {event}");
+            assert_eq!(
+                discovered
+                    .hook_entries
+                    .iter()
+                    .map(|entry| (
+                        entry.plugin_id.as_deref(),
+                        entry.trust_status,
+                        entry.enabled,
+                        entry.is_managed,
+                        entry.builtin,
+                    ))
+                    .collect::<Vec<_>>(),
+                vec![(Some(plugin_id), HookTrustStatus::Trusted, true, false, true)],
+                "{plugin_id} {event}"
+            );
+            assert!(discovered.handlers[0].builtin, "{plugin_id} {event}");
+        }
+    }
+}
+
+#[test]
+fn bundled_cleanup_trust_does_not_extend_to_other_handlers() {
+    let mut source = bundled_cleanup_source("browser@openai-bundled", "node_repl", "Stop");
+    let cleanup = source.hooks.stop[0].hooks[0].clone();
+    source.hooks.stop[0].hooks.extend([
+        HookHandlerConfig::McpTool {
+            server: "node_repl".to_string(),
+            tool: "evaluate".to_string(),
+            input: Default::default(),
+            timeout_sec: None,
+            status_message: None,
+        },
+        HookHandlerConfig::McpTool {
+            server: "other_server".to_string(),
+            tool: "turn_ended".to_string(),
+            input: Default::default(),
+            timeout_sec: None,
+            status_message: None,
+        },
+        HookHandlerConfig::Command {
+            command: "echo cleanup".to_string(),
+            command_windows: None,
+            timeout_sec: None,
+            r#async: false,
+            status_message: None,
+            additional_context_limit: None,
+        },
+    ]);
+    source.hooks.stop.push(MatcherGroup {
+        matcher: Some("Bash".to_string()),
+        hooks: vec![cleanup],
+    });
+    let discovered = super::discovery::discover_handlers(
+        /*config_layer_stack*/ None,
+        vec![source],
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.handlers.len(), 1);
+    assert_eq!(
+        discovered
+            .hook_entries
+            .iter()
+            .map(|entry| (entry.trust_status, entry.builtin))
+            .collect::<Vec<_>>(),
+        vec![
+            (HookTrustStatus::Trusted, true),
+            (HookTrustStatus::Untrusted, false),
+            (HookTrustStatus::Untrusted, false),
+            (HookTrustStatus::Untrusted, false),
+            (HookTrustStatus::Untrusted, false),
+        ]
+    );
+}
+
+#[test]
+fn bundled_cleanup_trust_requires_matching_plugin_server_and_event() {
+    for (plugin_id, server, event) in [
+        ("other@openai-bundled", "node_repl", "Stop"),
+        ("browser@other", "node_repl", "Stop"),
+        ("browser@openai-bundled-alpha", "node_repl", "Stop"),
+        ("browser@openai-bundled", "node_repl", "PreToolUse"),
+        ("browser@openai-bundled", "cua_repl", "Stop"),
+        ("unified-computer-use@openai-bundled", "node_repl", "Stop"),
+        ("unified-computer-use@other", "cua_repl", "Stop"),
+        (
+            "unified-computer-use@openai-bundled",
+            "cua_repl",
+            "PreToolUse",
+        ),
+    ] {
+        let discovered = super::discovery::discover_handlers(
+            /*config_layer_stack*/ None,
+            vec![bundled_cleanup_source(plugin_id, server, event)],
+            Vec::new(),
+            /*bypass_hook_trust*/ false,
+        );
+        assert!(discovered.handlers.is_empty(), "{plugin_id} {event}");
+        assert_eq!(discovered.hook_entries.len(), 1);
+        assert_eq!(
+            discovered.hook_entries[0].trust_status,
+            HookTrustStatus::Untrusted
+        );
+    }
+}
+
+#[test]
+fn local_hosted_app_cleanup_hooks_require_saved_trust() {
+    let mut source = bundled_cleanup_source("browser@openai-curated-remote", "codex_apps", "Stop");
+    source.hooks.stop[0].hooks[0] = HookHandlerConfig::McpTool {
+        server: "codex_apps".to_string(),
+        tool: "browser.turn_ended".to_string(),
+        input: Default::default(),
+        timeout_sec: None,
+        status_message: None,
+    };
+    let discovered = super::discovery::discover_handlers(
+        /*config_layer_stack*/ None,
+        vec![source],
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert!(discovered.handlers.is_empty());
+    assert_eq!(
+        discovered
+            .hook_entries
+            .iter()
+            .map(|entry| entry.trust_status)
+            .collect::<Vec<_>>(),
+        vec![HookTrustStatus::Untrusted]
+    );
+}
+
+#[test]
+fn builtin_cleanup_ignores_disablement_but_preserves_managed_only_policy() {
+    let source = bundled_cleanup_source("browser@openai-bundled", "node_repl", "Stop");
+    let discovered = super::discovery::discover_handlers(
+        /*config_layer_stack*/ None,
+        vec![source.clone()],
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    let expected_entry = discovered.hook_entries[0].clone();
+    let disabled_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: cwd().join("config.toml"),
+                profile: None,
+            },
+            config_with_hook_state(&expected_entry.key, /*enabled*/ false),
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("disabled hook config");
+    let disabled = super::discovery::discover_handlers(
+        Some(&disabled_stack),
+        vec![source.clone()],
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(disabled.handlers, discovered.handlers);
+    assert_eq!(disabled.hook_entries, vec![expected_entry]);
+
+    let (requirements, requirements_toml) = requirements_with_managed_hooks_only(
+        /*allow_managed_hooks_only*/ true, /*managed_hooks*/ None,
+    );
+    let managed_stack = ConfigLayerStack::new(Vec::new(), requirements, requirements_toml)
+        .expect("managed-only config");
+    let managed_only = super::discovery::discover_handlers(
+        Some(&managed_stack),
+        vec![source.clone()],
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert!(managed_only.handlers.is_empty());
+    assert!(managed_only.hook_entries.is_empty());
+
+    for (stack, expected) in [
+        (&disabled_stack, discovered.handlers),
+        (&managed_stack, Vec::new()),
+    ] {
+        let feature_disabled = ClaudeHooksEngine::new(
+            /*enabled*/ false,
+            /*bypass_hook_trust*/ false,
+            Some(stack),
+            vec![source.clone()],
+            Vec::new(),
+            command_runtime(CommandShell {
+                program: String::new(),
+                args: Vec::new(),
+            }),
+            mcp_executor(),
+        );
+        assert_eq!(feature_disabled.handlers, expected);
+    }
+}
+
+#[test]
+fn disabled_hooks_feature_keeps_builtin_cleanup_but_not_trusted_plugin_hooks() {
+    let mut source = bundled_cleanup_source("browser@openai-bundled", "node_repl", "Stop");
+    source.hooks.stop[0].hooks.push(HookHandlerConfig::Command {
+        command: "echo ordinary hook".to_string(),
+        command_windows: None,
+        timeout_sec: None,
+        r#async: false,
+        status_message: None,
+        additional_context_limit: None,
+    });
+    let stack = trusted_plugin_hook_stack(cwd().join("config.toml"), &[source.clone()]);
+    let discovered = super::discovery::discover_handlers(
+        Some(&stack),
+        vec![source.clone()],
+        Vec::new(),
+        /*bypass_hook_trust*/ false,
+    );
+    assert_eq!(discovered.handlers.len(), 2);
+
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ false,
+        /*bypass_hook_trust*/ false,
+        Some(&stack),
+        vec![source],
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+    assert_eq!(engine.handlers, vec![discovered.handlers[0].clone()]);
+}
+
+#[tokio::test]
+async fn plugin_hook_sources_run_with_plugin_env_and_plugin_source() {
+    let temp = tempdir().expect("create temp dir");
+    let plugin_root =
+        AbsolutePathBuf::try_from(temp.path().join("demo-plugin")).expect("plugin root");
+    let plugin_data_root =
+        AbsolutePathBuf::try_from(temp.path().join("plugin-data")).expect("plugin data root");
+    fs::create_dir_all(plugin_root.join("hooks")).expect("create hooks dir");
+    let source_path = plugin_root.join("hooks/hooks.json");
+    let script_path = plugin_root.join("hooks/write_env.py");
+    fs::write(
+        script_path.as_path(),
+        r#"import json
+import os
+print(json.dumps({
+    "systemMessage": json.dumps({
+        "plugin": os.environ.get("PLUGIN_ROOT"),
+        "claude": os.environ.get("CLAUDE_PLUGIN_ROOT"),
+    })
+}))
+"#,
+    )
+    .expect("write hook script");
+    let plugin_id = PluginId::parse("demo-plugin@test-marketplace").expect("plugin id");
+    let plugin_hook_sources = vec![PluginHookSource {
+        plugin_id,
+        plugin_root: plugin_root.clone(),
+        plugin_data_root: plugin_data_root.clone(),
+        source_path: source_path.clone(),
+        source_relative_path: "hooks/hooks.json".to_string(),
+        hooks: HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("Bash".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command: format!("python3 {}", script_path.display()),
+                    command_windows: None,
+                    timeout_sec: Some(10),
+                    r#async: false,
+                    status_message: None,
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    }];
+    let config_layer_stack = trusted_plugin_hook_stack(
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path"),
+        &plugin_hook_sources,
+    );
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        plugin_hook_sources.clone(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    let preview = engine.preview_pre_tool_use(&PreToolUseRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        subagent: None,
+        cwd: cwd(),
+        transcript_path: None,
+        model: "gpt-test".to_string(),
+        permission_mode: "default".to_string(),
+        tool_name: "Bash".to_string(),
+        matcher_aliases: Vec::new(),
+        tool_use_id: "tool-1".to_string(),
+        tool_input: serde_json::json!({ "command": "echo hello" }),
+    });
+    assert_eq!(preview.len(), 1);
+    assert_eq!(preview[0].source, HookSource::Plugin);
+    assert_eq!(preview[0].source_path, source_path);
+    let listed = crate::list_hooks(crate::HooksConfig {
+        legacy_notify_argv: None,
+        feature_enabled: true,
+        bypass_hook_trust: false,
+        config_layer_stack: None,
+        plugin_hook_sources,
+        plugin_hook_load_warnings: Vec::new(),
+        shell_program: None,
+        shell_args: Vec::new(),
+    });
+    assert_eq!(
+        listed.hooks[0].plugin_id.as_deref(),
+        Some("demo-plugin@test-marketplace")
+    );
+
+    let outcome = engine
+        .run_pre_tool_use(PreToolUseRequest {
+            session_id: ThreadId::new(),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd: cwd(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            matcher_aliases: Vec::new(),
+            tool_use_id: "tool-1".to_string(),
+            tool_input: serde_json::json!({ "command": "echo hello" }),
+        })
+        .await;
+
+    assert_eq!(outcome.hook_events.len(), 1);
+    assert_eq!(outcome.hook_events[0].run.source, HookSource::Plugin);
+    assert_eq!(
+        outcome.hook_events[0].run.status,
+        HookRunStatus::Completed,
+        "hook entries: {:#?}",
+        outcome.hook_events[0].run.entries
+    );
+    assert_eq!(outcome.hook_events[0].run.entries.len(), 1);
+    assert_eq!(
+        outcome.hook_events[0].run.entries[0].kind,
+        HookOutputEntryKind::Warning
+    );
+    let logged: serde_json::Value =
+        serde_json::from_str(&outcome.hook_events[0].run.entries[0].text)
+            .expect("parse env payload");
+    assert_eq!(
+        logged,
+        serde_json::json!({
+            "plugin": plugin_root.display().to_string(),
+            "claude": plugin_root.display().to_string(),
+        })
+    );
+}
+
+#[test]
+fn plugin_hook_sources_expand_plugin_placeholders() {
+    let temp = tempdir().expect("create temp dir");
+    let plugin_root =
+        AbsolutePathBuf::try_from(temp.path().join("demo-plugin")).expect("plugin root");
+    let plugin_data_root =
+        AbsolutePathBuf::try_from(temp.path().join("plugin-data")).expect("plugin data root");
+    let source_path = plugin_root.join("hooks/hooks.json");
+    let plugin_id = PluginId::parse("demo-plugin@test-marketplace").expect("plugin id");
+    let plugin_hook_sources = vec![PluginHookSource {
+        plugin_id,
+        plugin_root: plugin_root.clone(),
+        plugin_data_root: plugin_data_root.clone(),
+        source_path,
+        source_relative_path: "hooks/hooks.json".to_string(),
+        hooks: HookEventsToml {
+            pre_tool_use: vec![MatcherGroup {
+                matcher: Some("Bash".to_string()),
+                hooks: vec![HookHandlerConfig::Command {
+                    command:
+                        "run ${PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT} ${PLUGIN_DATA} ${CLAUDE_PLUGIN_DATA}"
+                            .to_string(),
+                    command_windows: None,
+                    timeout_sec: Some(5),
+                    r#async: false,
+                    status_message: None,
+                    additional_context_limit: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    }];
+    let config_layer_stack = trusted_plugin_hook_stack(
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path"),
+        &plugin_hook_sources,
+    );
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        Some(&config_layer_stack),
+        plugin_hook_sources,
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert_eq!(
+        engine.handlers[0].kind,
+        ConfiguredHandlerKind::Command {
+            command: format!(
+                "run {} {} {} {}",
+                plugin_root.display(),
+                plugin_root.display(),
+                plugin_data_root.display(),
+                plugin_data_root.display()
+            ),
+            r#async: false,
+            env: HashMap::from([
+                ("PLUGIN_ROOT".to_string(), plugin_root.display().to_string()),
+                (
+                    "CLAUDE_PLUGIN_ROOT".to_string(),
+                    plugin_root.display().to_string(),
+                ),
+                (
+                    "PLUGIN_DATA".to_string(),
+                    plugin_data_root.display().to_string(),
+                ),
+                (
+                    "CLAUDE_PLUGIN_DATA".to_string(),
+                    plugin_data_root.display().to_string(),
+                ),
+            ]),
+        }
+    );
+}
+
+#[test]
+fn plugin_hook_load_warnings_are_startup_warnings() {
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        /*config_layer_stack*/ None,
+        Vec::new(),
+        vec!["failed plugin hook".to_string()],
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        mcp_executor(),
+    );
+
+    assert_eq!(engine.warnings(), &["failed plugin hook".to_string()]);
+}
+
+struct StaticMcpExecutor {
+    calls: Arc<Mutex<Vec<HookMcpCall>>>,
+    output: String,
+    outputs_by_tool: HashMap<String, String>,
+}
+
+impl HookMcpExecutor for StaticMcpExecutor {
+    fn execute(&self, call: HookMcpCall) -> BoxFuture<'_, anyhow::Result<String>> {
+        async move {
+            let output = self
+                .outputs_by_tool
+                .get(&call.tool)
+                .unwrap_or(&self.output)
+                .clone();
+            self.calls.lock().expect("lock MCP calls").push(call);
+            Ok(output)
+        }
+        .boxed()
+    }
+}
+
+fn executor_stop_hook_fixture() -> (
+    ClaudeHooksEngine,
+    Arc<Mutex<Vec<HookMcpCall>>>,
+    StopRequest,
+    HookMcpCall,
+    ExecutorPluginHookSource,
+) {
+    let calls = Arc::new(Mutex::new(Vec::new()));
+    let executor = Arc::new(StaticMcpExecutor {
+        calls: Arc::clone(&calls),
+        output: r#"{"decision":"block","reason":"keep going"}"#.to_string(),
+        outputs_by_tool: HashMap::from([(
+            "terminate".to_string(),
+            r#"{"continue":false,"stopReason":"done"}"#.to_string(),
+        )]),
+    });
+    let mut engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ false,
+        /*config_layer_stack*/ None,
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        executor,
+    );
+    let source = ExecutorPluginHookSource {
+        plugin_id: PluginId::parse("computer-use@openai-bundled").expect("valid plugin ID"),
+        environment_id: "executor-a".to_string(),
+        mcp_environment_id: None,
+        mcp_metadata: None,
+        plugin_root: "file:///plugins/computer-use"
+            .parse()
+            .expect("valid plugin root URI"),
+        manifest_path: "file:///plugins/computer-use/.codex-plugin/plugin.json"
+            .parse()
+            .expect("valid plugin manifest URI"),
+        source_relative_path: ".codex-plugin/plugin.json#hooks[0]".to_string(),
+        hooks: HookEventsToml {
+            stop: vec![MatcherGroup {
+                matcher: None,
+                hooks: vec![HookHandlerConfig::McpTool {
+                    server: "node_repl".to_string(),
+                    tool: "turn_ended".to_string(),
+                    input: serde_json::from_value(serde_json::json!({
+                        "turn_id": "${turn_id}",
+                    }))
+                    .expect("executor hook input"),
+                    timeout_sec: None,
+                    status_message: None,
+                }],
+            }],
+            ..Default::default()
+        },
+    };
+    engine.set_executor_hooks(vec![source.clone()]);
+    assert_eq!(
+        engine.handlers,
+        vec![ConfiguredHandler {
+            builtin: true,
+            event_name: HookEventName::Stop,
+            matcher: None,
+            timeout_sec: 5,
+            status_message: None,
+            additional_context_limit: Default::default(),
+            source_path: HandlerSourcePath::ExecutorScoped {
+                plugin_id: PluginId::parse("computer-use@openai-bundled").expect("valid plugin ID"),
+                environment_id: "executor-a".to_string(),
+                mcp_environment_id: None,
+                mcp_metadata: None,
+                manifest_path: "file:///plugins/computer-use/.codex-plugin/plugin.json"
+                    .parse()
+                    .expect("valid plugin manifest URI"),
+                source_relative_path: ".codex-plugin/plugin.json#hooks[0]".to_string(),
+            },
+            source: HookSource::Plugin,
+            display_order: 0,
+            kind: ConfiguredHandlerKind::McpTool {
+                server: "node_repl".to_string(),
+                tool: "turn_ended".to_string(),
+                input: serde_json::from_value(serde_json::json!({
+                    "turn_id": "${turn_id}",
+                }))
+                .expect("executor hook input"),
+            },
+        }]
+    );
+    assert_eq!(
+        engine.handlers[0].execution_mode(),
+        HookExecutionMode::Async
+    );
+    assert!(!engine.handlers[0].can_apply_control_effects());
+    let request_metadata = Some(serde_json::Map::from_iter([(
+        "x-codex-turn-metadata".to_string(),
+        serde_json::json!({ "turn_id": "turn-1" }),
+    )]));
+    let request = StopRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        cwd: cwd(),
+        transcript_path: None,
+        model: "test-model".to_string(),
+        permission_mode: "default".to_string(),
+        request_metadata: request_metadata.clone(),
+        stop_hook_active: false,
+        last_assistant_message: None,
+        target: StopHookTarget::Stop,
+    };
+
+    let expected_executor_call = HookMcpCall {
+        server: "node_repl".to_string(),
+        tool: "turn_ended".to_string(),
+        environment_id: Some("executor-a".to_string()),
+        metadata: request_metadata,
+        input: serde_json::from_value(serde_json::json!({ "turn_id": "turn-1" }))
+            .expect("expanded executor hook input"),
+        timeout: Duration::from_secs(5),
+    };
+
+    (engine, calls, request, expected_executor_call, source)
+}
+
+async fn wait_for_mcp_calls(calls: &Arc<Mutex<Vec<HookMcpCall>>>, count: usize) {
+    tokio::time::timeout(Duration::from_secs(1), async {
+        while calls.lock().expect("lock MCP calls").len() < count {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("executor hook should complete in the background");
+}
+
+#[tokio::test]
+async fn executor_stop_hooks_run_unless_regular_hooks_block_without_stopping() {
+    let (mut engine, calls, request, expected_executor_call, _source) =
+        executor_stop_hook_fixture();
+
+    assert_eq!(engine.preview_stop(&request), Vec::new());
+    let outcome = engine.run_stop(request.clone()).await;
+    wait_for_mcp_calls(&calls, /*count*/ 1).await;
+    assert!(!outcome.should_block);
+    assert!(outcome.hook_events.is_empty());
+    assert_eq!(
+        *calls.lock().expect("lock MCP calls"),
+        vec![expected_executor_call.clone()]
+    );
+
+    engine.handlers.push(ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::Stop,
+        matcher: None,
+        timeout_sec: 30,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: cwd().join("hooks.json").into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::McpTool {
+            server: "security".to_string(),
+            tool: "check".to_string(),
+            input: Default::default(),
+        },
+    });
+
+    let outcome = engine.run_stop(request.clone()).await;
+    assert!(outcome.should_block);
+    assert_eq!(outcome.hook_events.len(), 1);
+    assert_eq!(
+        *calls.lock().expect("lock MCP calls"),
+        vec![
+            expected_executor_call.clone(),
+            HookMcpCall {
+                server: "security".to_string(),
+                tool: "check".to_string(),
+                environment_id: None,
+                metadata: None,
+                input: Default::default(),
+                timeout: Duration::from_secs(30),
+            },
+        ]
+    );
+
+    engine.handlers.push(ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::Stop,
+        matcher: None,
+        timeout_sec: 30,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: cwd().join("hooks.json").into(),
+        source: HookSource::User,
+        display_order: 1,
+        kind: ConfiguredHandlerKind::McpTool {
+            server: "security".to_string(),
+            tool: "terminate".to_string(),
+            input: Default::default(),
+        },
+    });
+
+    let outcome = engine.run_stop(request).await;
+    wait_for_mcp_calls(&calls, /*count*/ 5).await;
+    assert!(outcome.should_stop);
+    assert!(!outcome.should_block);
+    assert_eq!(outcome.hook_events.len(), 2);
+    assert_eq!(
+        *calls.lock().expect("lock MCP calls"),
+        vec![
+            expected_executor_call.clone(),
+            HookMcpCall {
+                server: "security".to_string(),
+                tool: "check".to_string(),
+                environment_id: None,
+                metadata: None,
+                input: Default::default(),
+                timeout: Duration::from_secs(30),
+            },
+            HookMcpCall {
+                server: "security".to_string(),
+                tool: "check".to_string(),
+                environment_id: None,
+                metadata: None,
+                input: Default::default(),
+                timeout: Duration::from_secs(30),
+            },
+            HookMcpCall {
+                server: "security".to_string(),
+                tool: "terminate".to_string(),
+                environment_id: None,
+                metadata: None,
+                input: Default::default(),
+                timeout: Duration::from_secs(30),
+            },
+            expected_executor_call,
+        ]
+    );
+}
+
+#[test]
+fn executor_stop_hooks_register_each_target_environment_once() {
+    let (mut engine, _, _, _, first_source) = executor_stop_hook_fixture();
+    let mut expected_handlers = engine.handlers.clone();
+    let mut duplicate_target = first_source.clone();
+    duplicate_target.plugin_id = PluginId::parse("chrome@openai-bundled").expect("valid plugin ID");
+    let mut second_source = first_source.clone();
+    second_source.environment_id = "executor-b".to_string();
+    let mut second_handler = expected_handlers[0].clone();
+    second_handler.display_order = 1;
+    let HandlerSourcePath::ExecutorScoped { environment_id, .. } = &mut second_handler.source_path
+    else {
+        panic!("executor Stop handler should have an executor source");
+    };
+    *environment_id = second_source.environment_id.clone();
+    expected_handlers.push(second_handler);
+    engine.set_executor_hooks(vec![first_source, duplicate_target, second_source]);
+
+    assert_eq!(engine.handlers, expected_handlers);
+}
+
+#[tokio::test]
+async fn executor_interrupt_hooks_register_and_run() {
+    let (mut engine, calls, stop_request, expected_stop_call, mut source) =
+        executor_stop_hook_fixture();
+    source.hooks.subagent_stop = source.hooks.stop.clone();
+    source.hooks.interrupt = source.hooks.stop.clone();
+    engine.set_executor_hooks(vec![source]);
+
+    assert_eq!(
+        engine
+            .handlers
+            .iter()
+            .map(|handler| handler.event_name)
+            .collect::<Vec<_>>(),
+        vec![
+            HookEventName::SubagentStop,
+            HookEventName::Stop,
+            HookEventName::Interrupt,
+        ]
+    );
+    assert_eq!(engine.preview_interrupt(), Vec::new());
+
+    let outcome = engine
+        .run_interrupt(InterruptRequest {
+            session_id: stop_request.session_id,
+            turn_id: stop_request.turn_id,
+            cwd: stop_request.cwd,
+            transcript_path: stop_request.transcript_path,
+            model: stop_request.model,
+            permission_mode: stop_request.permission_mode,
+            request_metadata: stop_request.request_metadata,
+        })
+        .await;
+    wait_for_mcp_calls(&calls, /*count*/ 1).await;
+
+    assert!(outcome.hook_events.is_empty());
+    assert_eq!(
+        *calls.lock().expect("lock MCP calls"),
+        vec![expected_stop_call]
+    );
+}
+
+#[test]
+fn executor_hooks_register_events_from_each_environment() {
+    let (mut engine, _, _, _, mut first_source) = executor_stop_hook_fixture();
+    first_source.hooks.interrupt = std::mem::take(&mut first_source.hooks.stop);
+    engine.set_executor_hooks(vec![first_source.clone()]);
+    let mut expected_handlers = engine.handlers.clone();
+    let mut second_source = first_source.clone();
+    second_source.environment_id = "executor-b".to_string();
+    second_source.hooks.stop = std::mem::take(&mut second_source.hooks.interrupt);
+    let mut second_handler = expected_handlers[0].clone();
+    second_handler.event_name = HookEventName::Stop;
+    second_handler.display_order = 1;
+    let HandlerSourcePath::ExecutorScoped { environment_id, .. } = &mut second_handler.source_path
+    else {
+        panic!("executor Stop handler should have an executor source");
+    };
+    *environment_id = second_source.environment_id.clone();
+    expected_handlers.push(second_handler);
+
+    engine.set_executor_hooks(vec![first_source, second_source]);
+
+    assert_eq!(engine.handlers, expected_handlers);
+}
+
+#[tokio::test]
+async fn executor_stop_hooks_use_an_admitted_mcp_environment() {
+    let (mut engine, calls, request, mut expected_call, mut source) = executor_stop_hook_fixture();
+    source.mcp_environment_id = Some("local".to_string());
+    engine.set_executor_hooks(vec![source]);
+
+    engine.run_stop(request).await;
+    wait_for_mcp_calls(&calls, /*count*/ 1).await;
+
+    expected_call.environment_id = Some("local".to_string());
+    assert_eq!(*calls.lock().expect("lock MCP calls"), vec![expected_call]);
+}
+
+#[tokio::test]
+async fn memory_consolidation_stop_preserves_policy_and_executor_cleanup() {
+    for (source, runs_policy) in [
+        (HookSource::User, false),
+        (HookSource::Project, false),
+        (HookSource::SessionFlags, false),
+        (HookSource::Plugin, false),
+        (HookSource::System, true),
+        (HookSource::Mdm, true),
+        (HookSource::CloudRequirements, true),
+        (HookSource::CloudManagedConfig, true),
+        (HookSource::LegacyManagedConfigFile, true),
+        (HookSource::LegacyManagedConfigMdm, true),
+        (HookSource::Unknown, true),
+    ] {
+        let (mut engine, calls, mut request, expected_executor_call, _source) =
+            executor_stop_hook_fixture();
+        request.target = StopHookTarget::MemoryConsolidation;
+        let policy_call = HookMcpCall {
+            server: "security".to_string(),
+            tool: "check".to_string(),
+            environment_id: None,
+            metadata: None,
+            input: Default::default(),
+            timeout: Duration::from_secs(5),
+        };
+        let mut handler = engine.handlers[0].clone();
+        handler.source_path = cwd().join("hooks.json").into();
+        handler.source = source;
+        handler.kind = ConfiguredHandlerKind::McpTool {
+            server: policy_call.server.clone(),
+            tool: policy_call.tool.clone(),
+            input: policy_call.input.clone(),
+        };
+        engine.handlers.push(handler);
+        assert_eq!(
+            engine.preview_stop(&request).len(),
+            usize::from(runs_policy)
+        );
+
+        let outcome = engine.run_stop(request).await;
+        let expected_calls = if runs_policy {
+            vec![policy_call, expected_executor_call]
+        } else {
+            vec![expected_executor_call]
+        };
+        wait_for_mcp_calls(&calls, expected_calls.len()).await;
+        assert_eq!(*calls.lock().expect("lock MCP calls"), expected_calls);
+        assert_eq!(outcome.should_block, runs_policy);
+    }
+}
+
+#[tokio::test]
+async fn executor_stop_hooks_do_not_delay_stop_completion() {
+    struct BlockingMcpExecutor {
+        started: Arc<Notify>,
+        release: Arc<Notify>,
+    }
+
+    impl HookMcpExecutor for BlockingMcpExecutor {
+        fn execute(&self, _call: HookMcpCall) -> BoxFuture<'_, anyhow::Result<String>> {
+            async move {
+                self.started.notify_one();
+                self.release.notified().await;
+                Ok(String::new())
+            }
+            .boxed()
+        }
+    }
+
+    let (mut engine, _, request, _, _) = executor_stop_hook_fixture();
+    let started = Arc::new(Notify::new());
+    let release = Arc::new(Notify::new());
+    engine.mcp_executor = Arc::new(BlockingMcpExecutor {
+        started: Arc::clone(&started),
+        release: Arc::clone(&release),
+    });
+
+    let outcome = tokio::time::timeout(Duration::from_millis(100), engine.run_stop(request))
+        .await
+        .expect("executor hook must not delay Stop completion");
+    assert!(!outcome.should_block);
+    tokio::time::timeout(Duration::from_secs(1), started.notified())
+        .await
+        .expect("executor hook should start in the background");
+    release.notify_one();
+}
+
+#[tokio::test]
+async fn mcp_tool_hooks_expand_event_input_and_apply_pre_tool_decisions() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    fs::write(
+        temp.path().join("hooks.json"),
+        serde_json::json!({
+            "hooks": {
+                "PreToolUse": [{
+                    "matcher": "Bash",
+                    "hooks": [{
+                        "type": "mcp_tool",
+                        "server": "security",
+                        "tool": "scan",
+                        "input": { "command": "${tool_input.command}" },
+                        "timeout": 20,
+                    }],
+                }],
+            },
+        })
+        .to_string(),
+    )
+    .expect("write MCP hooks.json");
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            TomlValue::Table(Default::default()),
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let request = PreToolUseRequest {
+        session_id: ThreadId::new(),
+        turn_id: "turn-1".to_string(),
+        subagent: None,
+        cwd: cwd(),
+        transcript_path: None,
+        model: "gpt-test".to_string(),
+        permission_mode: "default".to_string(),
+        tool_name: "Bash".to_string(),
+        matcher_aliases: Vec::new(),
+        tool_use_id: "tool-1".to_string(),
+        tool_input: serde_json::json!({ "command": "rm important.txt" }),
+    };
+    let calls = Arc::new(Mutex::new(Vec::new()));
+    let executor = StaticMcpExecutor {
+        calls: Arc::clone(&calls),
+        output: serde_json::json!({
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "blocked by MCP scanner",
+            },
+        })
+        .to_string(),
+        outputs_by_tool: HashMap::new(),
+    };
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ true,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        Arc::new(executor),
+    );
+    let outcome = engine.run_pre_tool_use(request).await;
+
+    assert!(outcome.should_block);
+    assert_eq!(
+        outcome.block_reason.as_deref(),
+        Some("blocked by MCP scanner")
+    );
+    assert_eq!(
+        outcome.hook_events[0].run.handler_type,
+        HookHandlerType::McpTool
+    );
+    assert_eq!(
+        outcome.hook_events[0].run.execution_mode,
+        codex_protocol::protocol::HookExecutionMode::Sync
+    );
+    assert_eq!(
+        *calls.lock().expect("lock MCP calls"),
+        vec![HookMcpCall {
+            server: "security".to_string(),
+            tool: "scan".to_string(),
+            environment_id: None,
+            metadata: None,
+            input: serde_json::from_value(serde_json::json!({
+                "command": "rm important.txt",
+            }))
+            .expect("object input"),
+            timeout: Duration::from_secs(20),
+        }]
+    );
+}
+
+#[tokio::test]
+async fn mcp_interrupt_hooks_expand_event_input_and_bound_timeout() {
+    let temp = tempdir().expect("create temp dir");
+    let config_path =
+        AbsolutePathBuf::try_from(temp.path().join("config.toml")).expect("absolute config path");
+    fs::write(
+        temp.path().join("hooks.json"),
+        serde_json::json!({
+            "hooks": {
+                "Interrupt": [{
+                    "hooks": [{
+                        "type": "mcp_tool",
+                        "server": "security",
+                        "tool": "notify",
+                        "input": {
+                            "event": "${hook_event_name}",
+                            "turn_id": "${turn_id}",
+                            "permission_mode": "${permission_mode}",
+                        },
+                        "timeout": 20,
+                    }],
+                }],
+            },
+        })
+        .to_string(),
+    )
+    .expect("write MCP Interrupt hooks.json");
+    let config_layer_stack = ConfigLayerStack::new(
+        vec![ConfigLayerEntry::new(
+            ConfigLayerSource::User {
+                file: config_path,
+                profile: None,
+            },
+            TomlValue::Table(Default::default()),
+        )],
+        ConfigRequirements::default(),
+        ConfigRequirementsToml::default(),
+    )
+    .expect("config layer stack");
+
+    let calls = Arc::new(Mutex::new(Vec::new()));
+    let executor = StaticMcpExecutor {
+        calls: Arc::clone(&calls),
+        output: serde_json::json!({
+            "systemMessage": "interrupt observed",
+        })
+        .to_string(),
+        outputs_by_tool: HashMap::new(),
+    };
+    let engine = ClaudeHooksEngine::new(
+        /*enabled*/ true,
+        /*bypass_hook_trust*/ true,
+        Some(&config_layer_stack),
+        Vec::new(),
+        Vec::new(),
+        command_runtime(CommandShell {
+            program: String::new(),
+            args: Vec::new(),
+        }),
+        Arc::new(executor),
+    );
+    let outcome = engine
+        .run_interrupt(InterruptRequest {
+            session_id: ThreadId::new(),
+            turn_id: "turn-1".to_string(),
+            cwd: cwd(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            request_metadata: None,
+        })
+        .await;
+
+    assert_eq!(outcome.hook_events.len(), 1);
+    assert_eq!(
+        outcome.hook_events[0].run.handler_type,
+        HookHandlerType::McpTool
+    );
+    assert_eq!(outcome.hook_events[0].run.status, HookRunStatus::Completed);
+    assert_eq!(
+        outcome.hook_events[0].run.entries,
+        vec![HookOutputEntry {
+            kind: HookOutputEntryKind::Warning,
+            text: "interrupt observed".to_string(),
+        }]
+    );
+    assert_eq!(
+        *calls.lock().expect("lock MCP calls"),
+        vec![HookMcpCall {
+            server: "security".to_string(),
+            tool: "notify".to_string(),
+            environment_id: None,
+            metadata: None,
+            input: serde_json::from_value(serde_json::json!({
+                "event": "Interrupt",
+                "turn_id": "turn-1",
+                "permission_mode": "default",
+            }))
+            .expect("object input"),
+            timeout: Duration::from_secs(3),
+        }]
+    );
+}
diff --git a/codex-rs/hooks/src/engine/output_parser.rs b/codex-rs/hooks/src/engine/output_parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..aaefa46dc10217a5e9259b9f8ff010bfee0f7c36
--- /dev/null
+++ b/codex-rs/hooks/src/engine/output_parser.rs
@@ -0,0 +1,617 @@
+#[derive(Debug, Clone)]
+pub(crate) struct UniversalOutput {
+    pub continue_processing: bool,
+    pub stop_reason: Option<String>,
+    pub suppress_output: bool,
+    pub system_message: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct SessionStartOutput {
+    pub universal: UniversalOutput,
+    pub additional_context: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct PreToolUseOutput {
+    pub universal: UniversalOutput,
+    pub block_reason: Option<String>,
+    pub additional_context: Option<String>,
+    pub updated_input: Option<serde_json::Value>,
+    pub invalid_reason: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum PermissionRequestDecision {
+    Allow,
+    Deny { message: String },
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct PermissionRequestOutput {
+    pub universal: UniversalOutput,
+    pub decision: Option<PermissionRequestDecision>,
+    pub invalid_reason: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct PostToolUseOutput {
+    pub universal: UniversalOutput,
+    pub should_block: bool,
+    pub reason: Option<String>,
+    pub invalid_block_reason: Option<String>,
+    pub additional_context: Option<String>,
+    pub invalid_reason: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct UserPromptSubmitOutput {
+    pub universal: UniversalOutput,
+    pub should_block: bool,
+    pub reason: Option<String>,
+    pub invalid_block_reason: Option<String>,
+    pub additional_context: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct StopOutput {
+    pub universal: UniversalOutput,
+    pub should_block: bool,
+    pub reason: Option<String>,
+    pub invalid_block_reason: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct StatelessHookOutput {
+    pub universal: UniversalOutput,
+    pub invalid_reason: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct InterruptOutput {
+    pub system_message: Option<String>,
+}
+
+use crate::schema::BlockDecisionWire;
+use crate::schema::HookUniversalOutputWire;
+use crate::schema::InterruptCommandOutputWire;
+use crate::schema::PermissionRequestBehaviorWire;
+use crate::schema::PermissionRequestCommandOutputWire;
+use crate::schema::PermissionRequestDecisionWire;
+use crate::schema::PostCompactCommandOutputWire;
+use crate::schema::PostToolUseCommandOutputWire;
+use crate::schema::PreCompactCommandOutputWire;
+use crate::schema::PreToolUseCommandOutputWire;
+use crate::schema::PreToolUseDecisionWire;
+use crate::schema::PreToolUsePermissionDecisionWire;
+use crate::schema::SessionStartCommandOutputWire;
+use crate::schema::StopCommandOutputWire;
+use crate::schema::SubagentStartCommandOutputWire;
+use crate::schema::SubagentStopCommandOutputWire;
+use crate::schema::UserPromptSubmitCommandOutputWire;
+
+pub(crate) fn parse_session_start(stdout: &str) -> Option<SessionStartOutput> {
+    let wire: SessionStartCommandOutputWire = parse_json(stdout)?;
+    Some(session_start_output(
+        wire.universal,
+        wire.hook_specific_output
+            .and_then(|output| output.additional_context),
+    ))
+}
+
+pub(crate) fn parse_subagent_start(stdout: &str) -> Option<SessionStartOutput> {
+    let wire: SubagentStartCommandOutputWire = parse_json(stdout)?;
+    Some(session_start_output(
+        wire.universal,
+        wire.hook_specific_output
+            .and_then(|output| output.additional_context),
+    ))
+}
+
+fn session_start_output(
+    universal: HookUniversalOutputWire,
+    additional_context: Option<String>,
+) -> SessionStartOutput {
+    SessionStartOutput {
+        universal: UniversalOutput::from(universal),
+        additional_context,
+    }
+}
+
+pub(crate) fn parse_pre_tool_use(stdout: &str) -> Option<PreToolUseOutput> {
+    let PreToolUseCommandOutputWire {
+        universal: universal_wire,
+        decision,
+        reason,
+        hook_specific_output,
+    } = parse_json(stdout)?;
+    let universal = UniversalOutput::from(universal_wire);
+    let hook_specific_output = hook_specific_output.as_ref();
+    let additional_context =
+        hook_specific_output.and_then(|output| output.additional_context.clone());
+    let use_hook_specific_decision = hook_specific_output.is_some_and(|output| {
+        output.permission_decision.is_some()
+            || output.permission_decision_reason.is_some()
+            || output.updated_input.is_some()
+    });
+    let invalid_reason = unsupported_pre_tool_use_universal(&universal).or_else(|| {
+        if use_hook_specific_decision {
+            hook_specific_output.and_then(unsupported_pre_tool_use_hook_specific_output)
+        } else {
+            unsupported_pre_tool_use_legacy_decision(decision.as_ref(), reason.as_deref())
+        }
+    });
+    let block_reason = if invalid_reason.is_none() {
+        if use_hook_specific_decision {
+            hook_specific_output.and_then(|output| match output.permission_decision {
+                Some(PreToolUsePermissionDecisionWire::Deny) => output
+                    .permission_decision_reason
+                    .as_deref()
+                    .and_then(trimmed_reason),
+                _ => None,
+            })
+        } else {
+            match decision.as_ref() {
+                Some(PreToolUseDecisionWire::Block) => reason.as_deref().and_then(trimmed_reason),
+                Some(PreToolUseDecisionWire::Approve) | None => None,
+            }
+        }
+    } else {
+        None
+    };
+    let updated_input = if invalid_reason.is_none() {
+        hook_specific_output.and_then(|output| {
+            matches!(
+                output.permission_decision,
+                Some(PreToolUsePermissionDecisionWire::Allow)
+            )
+            .then(|| output.updated_input.clone())
+            .flatten()
+        })
+    } else {
+        None
+    };
+
+    Some(PreToolUseOutput {
+        universal,
+        block_reason,
+        additional_context,
+        updated_input,
+        invalid_reason,
+    })
+}
+
+pub(crate) fn parse_permission_request(stdout: &str) -> Option<PermissionRequestOutput> {
+    let wire: PermissionRequestCommandOutputWire = parse_json(stdout)?;
+    let universal = UniversalOutput::from(wire.universal);
+    let hook_specific_output = wire.hook_specific_output.as_ref();
+    let decision = hook_specific_output.and_then(|output| output.decision.as_ref());
+    let invalid_reason = unsupported_permission_request_universal(&universal).or_else(|| {
+        hook_specific_output.and_then(|output| {
+            unsupported_permission_request_hook_specific_output(output.decision.as_ref())
+        })
+    });
+    let decision = if invalid_reason.is_none() {
+        decision.map(permission_request_decision)
+    } else {
+        None
+    };
+
+    Some(PermissionRequestOutput {
+        universal,
+        decision,
+        invalid_reason,
+    })
+}
+
+pub(crate) fn parse_post_tool_use(stdout: &str) -> Option<PostToolUseOutput> {
+    let wire: PostToolUseCommandOutputWire = parse_json(stdout)?;
+    let universal = UniversalOutput::from(wire.universal);
+    let invalid_reason = unsupported_post_tool_use_universal(&universal).or_else(|| {
+        wire.hook_specific_output
+            .as_ref()
+            .and_then(unsupported_post_tool_use_hook_specific_output)
+    });
+    let should_block = matches!(wire.decision, Some(BlockDecisionWire::Block));
+    let invalid_block_reason = if should_block
+        && match wire.reason.as_deref() {
+            Some(reason) => reason.trim().is_empty(),
+            None => true,
+        } {
+        Some(invalid_block_message("PostToolUse"))
+    } else if !should_block && universal.continue_processing && wire.reason.is_some() {
+        Some("PostToolUse hook returned reason without decision".to_string())
+    } else {
+        None
+    };
+    let additional_context = wire
+        .hook_specific_output
+        .and_then(|output| output.additional_context);
+
+    Some(PostToolUseOutput {
+        universal,
+        should_block: should_block && invalid_reason.is_none() && invalid_block_reason.is_none(),
+        reason: wire.reason,
+        invalid_block_reason,
+        additional_context,
+        invalid_reason,
+    })
+}
+
+pub(crate) fn parse_pre_compact(stdout: &str) -> Option<StatelessHookOutput> {
+    let wire: PreCompactCommandOutputWire = parse_json(stdout)?;
+    let universal = UniversalOutput::from(wire.universal);
+    Some(StatelessHookOutput {
+        universal,
+        invalid_reason: None,
+    })
+}
+
+pub(crate) fn parse_post_compact(stdout: &str) -> Option<StatelessHookOutput> {
+    let wire: PostCompactCommandOutputWire = parse_json(stdout)?;
+    let universal = UniversalOutput::from(wire.universal);
+    Some(StatelessHookOutput {
+        universal,
+        invalid_reason: None,
+    })
+}
+
+pub(crate) fn parse_interrupt(stdout: &str) -> Option<InterruptOutput> {
+    let wire: InterruptCommandOutputWire = parse_json(stdout)?;
+    Some(InterruptOutput {
+        system_message: wire.system_message,
+    })
+}
+
+pub(crate) fn parse_user_prompt_submit(stdout: &str) -> Option<UserPromptSubmitOutput> {
+    let wire: UserPromptSubmitCommandOutputWire = parse_json(stdout)?;
+    let should_block = matches!(wire.decision, Some(BlockDecisionWire::Block));
+    let invalid_block_reason = if should_block
+        && match wire.reason.as_deref() {
+            Some(reason) => reason.trim().is_empty(),
+            None => true,
+        } {
+        Some(invalid_block_message("UserPromptSubmit"))
+    } else {
+        None
+    };
+    let additional_context = wire
+        .hook_specific_output
+        .and_then(|output| output.additional_context);
+    Some(UserPromptSubmitOutput {
+        universal: UniversalOutput::from(wire.universal),
+        should_block: should_block && invalid_block_reason.is_none(),
+        reason: wire.reason,
+        invalid_block_reason,
+        additional_context,
+    })
+}
+
+pub(crate) fn parse_stop(stdout: &str) -> Option<StopOutput> {
+    let wire: StopCommandOutputWire = parse_json(stdout)?;
+    Some(stop_output(
+        wire.universal,
+        wire.decision,
+        wire.reason,
+        "Stop",
+    ))
+}
+
+pub(crate) fn parse_subagent_stop(stdout: &str) -> Option<StopOutput> {
+    let wire: SubagentStopCommandOutputWire = parse_json(stdout)?;
+    Some(stop_output(
+        wire.universal,
+        wire.decision,
+        wire.reason,
+        "SubagentStop",
+    ))
+}
+
+fn stop_output(
+    universal: HookUniversalOutputWire,
+    decision: Option<BlockDecisionWire>,
+    reason: Option<String>,
+    event_name: &str,
+) -> StopOutput {
+    let should_block = matches!(decision, Some(BlockDecisionWire::Block));
+    let invalid_block_reason = if should_block
+        && match reason.as_deref() {
+            Some(reason) => reason.trim().is_empty(),
+            None => true,
+        } {
+        Some(invalid_block_message(event_name))
+    } else {
+        None
+    };
+    StopOutput {
+        universal: UniversalOutput::from(universal),
+        should_block: should_block && invalid_block_reason.is_none(),
+        reason,
+        invalid_block_reason,
+    }
+}
+
+impl From<HookUniversalOutputWire> for UniversalOutput {
+    fn from(value: HookUniversalOutputWire) -> Self {
+        Self {
+            continue_processing: value.r#continue,
+            stop_reason: value.stop_reason,
+            suppress_output: value.suppress_output,
+            system_message: value.system_message,
+        }
+    }
+}
+
+fn parse_json<T>(stdout: &str) -> Option<T>
+where
+    T: for<'de> serde::Deserialize<'de>,
+{
+    let trimmed = stdout.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let value: serde_json::Value = serde_json::from_str(trimmed).ok()?;
+    if !value.is_object() {
+        return None;
+    }
+    serde_json::from_value(value).ok()
+}
+
+pub(crate) fn looks_like_json(stdout: &str) -> bool {
+    let trimmed = stdout.trim_start();
+    trimmed.starts_with('{') || trimmed.starts_with('[')
+}
+
+fn invalid_block_message(event_name: &str) -> String {
+    format!("{event_name} hook returned decision:block without a non-empty reason")
+}
+
+fn unsupported_pre_tool_use_universal(universal: &UniversalOutput) -> Option<String> {
+    if !universal.continue_processing {
+        Some("PreToolUse hook returned unsupported continue:false".to_string())
+    } else if universal.stop_reason.is_some() {
+        Some("PreToolUse hook returned unsupported stopReason".to_string())
+    } else if universal.suppress_output {
+        Some("PreToolUse hook returned unsupported suppressOutput".to_string())
+    } else {
+        None
+    }
+}
+
+fn unsupported_permission_request_universal(universal: &UniversalOutput) -> Option<String> {
+    if !universal.continue_processing {
+        Some("PermissionRequest hook returned unsupported continue:false".to_string())
+    } else if universal.stop_reason.is_some() {
+        Some("PermissionRequest hook returned unsupported stopReason".to_string())
+    } else if universal.suppress_output {
+        Some("PermissionRequest hook returned unsupported suppressOutput".to_string())
+    } else {
+        None
+    }
+}
+
+fn unsupported_post_tool_use_universal(universal: &UniversalOutput) -> Option<String> {
+    if universal.suppress_output {
+        Some("PostToolUse hook returned unsupported suppressOutput".to_string())
+    } else {
+        None
+    }
+}
+
+fn unsupported_permission_request_hook_specific_output(
+    decision: Option<&PermissionRequestDecisionWire>,
+) -> Option<String> {
+    let decision = decision?;
+    if decision.updated_input.is_some() {
+        Some("PermissionRequest hook returned unsupported updatedInput".to_string())
+    } else if decision.updated_permissions.is_some() {
+        Some("PermissionRequest hook returned unsupported updatedPermissions".to_string())
+    } else if decision.interrupt {
+        Some("PermissionRequest hook returned unsupported interrupt:true".to_string())
+    } else {
+        None
+    }
+}
+
+fn permission_request_decision(
+    decision: &PermissionRequestDecisionWire,
+) -> PermissionRequestDecision {
+    match decision.behavior {
+        PermissionRequestBehaviorWire::Allow => PermissionRequestDecision::Allow,
+        PermissionRequestBehaviorWire::Deny => PermissionRequestDecision::Deny {
+            message: decision
+                .message
+                .as_deref()
+                .and_then(trimmed_reason)
+                .unwrap_or_else(|| "PermissionRequest hook denied approval".to_string()),
+        },
+    }
+}
+
+fn unsupported_post_tool_use_hook_specific_output(
+    output: &crate::schema::PostToolUseHookSpecificOutputWire,
+) -> Option<String> {
+    if output.updated_mcp_tool_output.is_some() {
+        Some("PostToolUse hook returned unsupported updatedMCPToolOutput".to_string())
+    } else {
+        None
+    }
+}
+
+fn unsupported_pre_tool_use_hook_specific_output(
+    output: &crate::schema::PreToolUseHookSpecificOutputWire,
+) -> Option<String> {
+    if output.updated_input.is_some()
+        && !matches!(
+            output.permission_decision,
+            Some(PreToolUsePermissionDecisionWire::Allow)
+        )
+    {
+        Some("PreToolUse hook returned updatedInput without permissionDecision:allow".to_string())
+    } else {
+        match output.permission_decision {
+            Some(PreToolUsePermissionDecisionWire::Allow) => {
+                output.updated_input.is_none().then(|| {
+                    "PreToolUse hook returned unsupported permissionDecision:allow".to_string()
+                })
+            }
+            Some(PreToolUsePermissionDecisionWire::Ask) => {
+                Some("PreToolUse hook returned unsupported permissionDecision:ask".to_string())
+            }
+            Some(PreToolUsePermissionDecisionWire::Deny) => {
+                if output
+                    .permission_decision_reason
+                    .as_deref()
+                    .and_then(trimmed_reason)
+                    .is_none()
+                {
+                    Some(invalid_pre_tool_use_reason_message())
+                } else {
+                    None
+                }
+            }
+            None => {
+                if output.permission_decision_reason.is_some() {
+                    Some("PreToolUse hook returned permissionDecisionReason without permissionDecision".to_string())
+                } else {
+                    None
+                }
+            }
+        }
+    }
+}
+
+fn unsupported_pre_tool_use_legacy_decision(
+    decision: Option<&PreToolUseDecisionWire>,
+    reason: Option<&str>,
+) -> Option<String> {
+    match decision {
+        Some(PreToolUseDecisionWire::Approve) => {
+            Some("PreToolUse hook returned unsupported decision:approve".to_string())
+        }
+        Some(PreToolUseDecisionWire::Block) => {
+            if reason.and_then(trimmed_reason).is_none() {
+                Some(invalid_block_message("PreToolUse"))
+            } else {
+                None
+            }
+        }
+        None => {
+            if reason.is_some() {
+                Some("PreToolUse hook returned reason without decision".to_string())
+            } else {
+                None
+            }
+        }
+    }
+}
+
+fn invalid_pre_tool_use_reason_message() -> String {
+    "PreToolUse hook returned permissionDecision:deny without a non-empty permissionDecisionReason"
+        .to_string()
+}
+
+fn trimmed_reason(reason: &str) -> Option<String> {
+    let trimmed = reason.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    use super::parse_permission_request;
+    use super::parse_user_prompt_submit;
+
+    #[test]
+    fn structured_output_rejects_invalid_shapes_and_types() {
+        for stdout in [
+            "[]",
+            r#"{"systemMessage":123}"#,
+            r#"{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":123}}"#,
+            r#"{"hookSpecificOutput":{"additionalContext":"missing event name"}}"#,
+            r#"{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","updatedInput":{}}}"#,
+            r#"{"unexpectedField":true}"#,
+            "{",
+        ] {
+            assert!(
+                parse_user_prompt_submit(stdout).is_none(),
+                "invalid structured output should fail: {stdout}",
+            );
+        }
+    }
+
+    #[test]
+    fn permission_request_rejects_reserved_updated_input_field() {
+        let parsed = parse_permission_request(
+            &json!({
+                "continue": true,
+                "hookSpecificOutput": {
+                    "hookEventName": "PermissionRequest",
+                    "decision": {
+                        "behavior": "allow",
+                        "updatedInput": {}
+                    }
+                }
+            })
+            .to_string(),
+        )
+        .expect("permission request hook output should parse");
+
+        assert_eq!(
+            parsed.invalid_reason,
+            Some("PermissionRequest hook returned unsupported updatedInput".to_string())
+        );
+    }
+
+    #[test]
+    fn permission_request_rejects_reserved_updated_permissions_field() {
+        let parsed = parse_permission_request(
+            &json!({
+                "continue": true,
+                "hookSpecificOutput": {
+                    "hookEventName": "PermissionRequest",
+                    "decision": {
+                        "behavior": "allow",
+                        "updatedPermissions": {}
+                    }
+                }
+            })
+            .to_string(),
+        )
+        .expect("permission request hook output should parse");
+
+        assert_eq!(
+            parsed.invalid_reason,
+            Some("PermissionRequest hook returned unsupported updatedPermissions".to_string())
+        );
+    }
+
+    #[test]
+    fn permission_request_rejects_reserved_interrupt_field() {
+        let parsed = parse_permission_request(
+            &json!({
+                "continue": true,
+                "hookSpecificOutput": {
+                    "hookEventName": "PermissionRequest",
+                    "decision": {
+                        "behavior": "allow",
+                        "interrupt": true
+                    }
+                }
+            })
+            .to_string(),
+        )
+        .expect("permission request hook output should parse");
+
+        assert_eq!(
+            parsed.invalid_reason,
+            Some("PermissionRequest hook returned unsupported interrupt:true".to_string())
+        );
+    }
+}
diff --git a/codex-rs/hooks/src/engine/schema_loader.rs b/codex-rs/hooks/src/engine/schema_loader.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7fce9a3c435ca0a43a4798c77d7bd61399e34845
--- /dev/null
+++ b/codex-rs/hooks/src/engine/schema_loader.rs
@@ -0,0 +1,168 @@
+use std::sync::OnceLock;
+
+use serde_json::Value;
+
+#[allow(dead_code)]
+pub(crate) struct GeneratedHookSchemas {
+    pub post_tool_use_command_input: Value,
+    pub post_tool_use_command_output: Value,
+    pub permission_request_command_input: Value,
+    pub permission_request_command_output: Value,
+    pub post_compact_command_input: Value,
+    pub post_compact_command_output: Value,
+    pub pre_tool_use_command_input: Value,
+    pub pre_tool_use_command_output: Value,
+    pub pre_compact_command_input: Value,
+    pub pre_compact_command_output: Value,
+    pub session_start_command_input: Value,
+    pub session_start_command_output: Value,
+    pub session_end_command_input: Value,
+    pub subagent_start_command_input: Value,
+    pub subagent_start_command_output: Value,
+    pub subagent_stop_command_input: Value,
+    pub subagent_stop_command_output: Value,
+    pub user_prompt_submit_command_input: Value,
+    pub user_prompt_submit_command_output: Value,
+    pub stop_command_input: Value,
+    pub stop_command_output: Value,
+    pub interrupt_command_input: Value,
+    pub interrupt_command_output: Value,
+}
+
+pub(crate) fn generated_hook_schemas() -> &'static GeneratedHookSchemas {
+    static SCHEMAS: OnceLock<GeneratedHookSchemas> = OnceLock::new();
+    SCHEMAS.get_or_init(|| GeneratedHookSchemas {
+        post_tool_use_command_input: parse_json_schema(
+            "post-tool-use.command.input",
+            include_str!("../../schema/generated/post-tool-use.command.input.schema.json"),
+        ),
+        post_tool_use_command_output: parse_json_schema(
+            "post-tool-use.command.output",
+            include_str!("../../schema/generated/post-tool-use.command.output.schema.json"),
+        ),
+        permission_request_command_input: parse_json_schema(
+            "permission-request.command.input",
+            include_str!("../../schema/generated/permission-request.command.input.schema.json"),
+        ),
+        permission_request_command_output: parse_json_schema(
+            "permission-request.command.output",
+            include_str!("../../schema/generated/permission-request.command.output.schema.json"),
+        ),
+        post_compact_command_input: parse_json_schema(
+            "post-compact.command.input",
+            include_str!("../../schema/generated/post-compact.command.input.schema.json"),
+        ),
+        post_compact_command_output: parse_json_schema(
+            "post-compact.command.output",
+            include_str!("../../schema/generated/post-compact.command.output.schema.json"),
+        ),
+        pre_tool_use_command_input: parse_json_schema(
+            "pre-tool-use.command.input",
+            include_str!("../../schema/generated/pre-tool-use.command.input.schema.json"),
+        ),
+        pre_tool_use_command_output: parse_json_schema(
+            "pre-tool-use.command.output",
+            include_str!("../../schema/generated/pre-tool-use.command.output.schema.json"),
+        ),
+        pre_compact_command_input: parse_json_schema(
+            "pre-compact.command.input",
+            include_str!("../../schema/generated/pre-compact.command.input.schema.json"),
+        ),
+        pre_compact_command_output: parse_json_schema(
+            "pre-compact.command.output",
+            include_str!("../../schema/generated/pre-compact.command.output.schema.json"),
+        ),
+        session_start_command_input: parse_json_schema(
+            "session-start.command.input",
+            include_str!("../../schema/generated/session-start.command.input.schema.json"),
+        ),
+        session_start_command_output: parse_json_schema(
+            "session-start.command.output",
+            include_str!("../../schema/generated/session-start.command.output.schema.json"),
+        ),
+        session_end_command_input: parse_json_schema(
+            "session-end.command.input",
+            include_str!("../../schema/generated/session-end.command.input.schema.json"),
+        ),
+        subagent_start_command_input: parse_json_schema(
+            "subagent-start.command.input",
+            include_str!("../../schema/generated/subagent-start.command.input.schema.json"),
+        ),
+        subagent_start_command_output: parse_json_schema(
+            "subagent-start.command.output",
+            include_str!("../../schema/generated/subagent-start.command.output.schema.json"),
+        ),
+        subagent_stop_command_input: parse_json_schema(
+            "subagent-stop.command.input",
+            include_str!("../../schema/generated/subagent-stop.command.input.schema.json"),
+        ),
+        subagent_stop_command_output: parse_json_schema(
+            "subagent-stop.command.output",
+            include_str!("../../schema/generated/subagent-stop.command.output.schema.json"),
+        ),
+        user_prompt_submit_command_input: parse_json_schema(
+            "user-prompt-submit.command.input",
+            include_str!("../../schema/generated/user-prompt-submit.command.input.schema.json"),
+        ),
+        user_prompt_submit_command_output: parse_json_schema(
+            "user-prompt-submit.command.output",
+            include_str!("../../schema/generated/user-prompt-submit.command.output.schema.json"),
+        ),
+        stop_command_input: parse_json_schema(
+            "stop.command.input",
+            include_str!("../../schema/generated/stop.command.input.schema.json"),
+        ),
+        stop_command_output: parse_json_schema(
+            "stop.command.output",
+            include_str!("../../schema/generated/stop.command.output.schema.json"),
+        ),
+        interrupt_command_input: parse_json_schema(
+            "interrupt.command.input",
+            include_str!("../../schema/generated/interrupt.command.input.schema.json"),
+        ),
+        interrupt_command_output: parse_json_schema(
+            "interrupt.command.output",
+            include_str!("../../schema/generated/interrupt.command.output.schema.json"),
+        ),
+    })
+}
+
+fn parse_json_schema(name: &str, schema: &str) -> Value {
+    serde_json::from_str(schema)
+        .unwrap_or_else(|err| panic!("invalid generated hooks schema {name}: {err}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::generated_hook_schemas;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn loads_generated_hook_schemas() {
+        let schemas = generated_hook_schemas();
+
+        assert_eq!(schemas.post_tool_use_command_input["type"], "object");
+        assert_eq!(schemas.post_tool_use_command_output["type"], "object");
+        assert_eq!(schemas.permission_request_command_input["type"], "object");
+        assert_eq!(schemas.permission_request_command_output["type"], "object");
+        assert_eq!(schemas.post_compact_command_input["type"], "object");
+        assert_eq!(schemas.post_compact_command_output["type"], "object");
+        assert_eq!(schemas.pre_tool_use_command_input["type"], "object");
+        assert_eq!(schemas.pre_tool_use_command_output["type"], "object");
+        assert_eq!(schemas.pre_compact_command_input["type"], "object");
+        assert_eq!(schemas.pre_compact_command_output["type"], "object");
+        assert_eq!(schemas.session_start_command_input["type"], "object");
+        assert_eq!(schemas.session_start_command_output["type"], "object");
+        assert_eq!(schemas.session_end_command_input["type"], "object");
+        assert_eq!(schemas.subagent_start_command_input["type"], "object");
+        assert_eq!(schemas.subagent_start_command_output["type"], "object");
+        assert_eq!(schemas.subagent_stop_command_input["type"], "object");
+        assert_eq!(schemas.subagent_stop_command_output["type"], "object");
+        assert_eq!(schemas.user_prompt_submit_command_input["type"], "object");
+        assert_eq!(schemas.user_prompt_submit_command_output["type"], "object");
+        assert_eq!(schemas.stop_command_input["type"], "object");
+        assert_eq!(schemas.stop_command_output["type"], "object");
+        assert_eq!(schemas.interrupt_command_input["type"], "object");
+        assert_eq!(schemas.interrupt_command_output["type"], "object");
+    }
+}
diff --git a/codex-rs/hooks/src/events/common.rs b/codex-rs/hooks/src/events/common.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7b4c4dcab31e9e5747594c39ec582fb0c49f4095
--- /dev/null
+++ b/codex-rs/hooks/src/events/common.rs
@@ -0,0 +1,306 @@
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerSourcePath;
+use crate::engine::dispatcher;
+use crate::output_spill::AdditionalContext;
+
+/// Identifies a thread-spawned subagent when a normal hook runs inside it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SubagentHookContext {
+    pub agent_id: String,
+    pub agent_type: String,
+}
+
+pub(crate) fn join_text_chunks(chunks: Vec<String>) -> Option<String> {
+    if chunks.is_empty() {
+        None
+    } else {
+        Some(chunks.join("\n\n"))
+    }
+}
+
+pub(crate) fn trimmed_non_empty(text: &str) -> Option<String> {
+    let trimmed = text.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed.to_string())
+    }
+}
+
+pub(crate) fn append_additional_context(
+    entries: &mut Vec<HookOutputEntry>,
+    additional_contexts_for_model: &mut Vec<AdditionalContext>,
+    handler: &ConfiguredHandler,
+    additional_context: String,
+) {
+    entries.push(HookOutputEntry {
+        kind: HookOutputEntryKind::Context,
+        text: additional_context.clone(),
+    });
+    additional_contexts_for_model.push(AdditionalContext {
+        text: additional_context,
+        limit: handler.additional_context_limit,
+    });
+}
+
+pub(crate) fn flatten_additional_contexts<'a>(
+    additional_contexts: impl IntoIterator<Item = &'a [AdditionalContext]>,
+) -> Vec<AdditionalContext> {
+    additional_contexts
+        .into_iter()
+        .flat_map(|chunk| chunk.iter().cloned())
+        .collect()
+}
+
+pub(crate) fn serialization_failure_hook_events(
+    handlers: Vec<ConfiguredHandler>,
+    turn_id: Option<String>,
+    error_message: String,
+) -> Vec<HookCompletedEvent> {
+    handlers
+        .into_iter()
+        .filter(|handler| matches!(handler.source_path, HandlerSourcePath::Local(_)))
+        .map(|handler| {
+            let mut run = dispatcher::running_summary(&handler);
+            run.status = HookRunStatus::Failed;
+            run.completed_at = Some(run.started_at);
+            run.duration_ms = Some(0);
+            run.entries = vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error_message.clone(),
+            }];
+            HookCompletedEvent {
+                turn_id: turn_id.clone(),
+                run,
+            }
+        })
+        .collect()
+}
+
+pub(crate) fn serialization_failure_hook_events_for_tool_use(
+    handlers: Vec<ConfiguredHandler>,
+    turn_id: Option<String>,
+    error_message: String,
+    tool_use_id: &str,
+) -> Vec<HookCompletedEvent> {
+    serialization_failure_hook_events(handlers, turn_id, error_message)
+        .into_iter()
+        .map(|event| hook_completed_for_tool_use(event, tool_use_id))
+        .collect()
+}
+
+pub(crate) fn hook_completed_for_tool_use(
+    mut event: HookCompletedEvent,
+    tool_use_id: &str,
+) -> HookCompletedEvent {
+    event.run = hook_run_for_tool_use(event.run, tool_use_id);
+    event
+}
+
+pub(crate) fn hook_run_for_tool_use(mut run: HookRunSummary, tool_use_id: &str) -> HookRunSummary {
+    run.id = format!("{}:{tool_use_id}", run.id);
+    run
+}
+
+pub(crate) fn matcher_pattern_for_event(
+    event_name: HookEventName,
+    matcher: Option<&str>,
+) -> Option<&str> {
+    match event_name {
+        HookEventName::PreToolUse
+        | HookEventName::PermissionRequest
+        | HookEventName::PostToolUse
+        | HookEventName::SessionStart
+        | HookEventName::SessionEnd
+        | HookEventName::SubagentStart
+        | HookEventName::SubagentStop
+        | HookEventName::PreCompact
+        | HookEventName::PostCompact => matcher,
+        HookEventName::UserPromptSubmit | HookEventName::Stop | HookEventName::Interrupt => None,
+    }
+}
+
+pub(crate) fn validate_matcher_pattern(matcher: &str) -> Result<(), regex::Error> {
+    if is_match_all_matcher(matcher) || is_exact_matcher(matcher) {
+        return Ok(());
+    }
+    regex::Regex::new(matcher).map(|_| ())
+}
+
+pub(crate) fn matches_matcher(matcher: Option<&str>, input: Option<&str>) -> bool {
+    match matcher {
+        None => true,
+        Some(matcher) if is_match_all_matcher(matcher) => true,
+        Some(matcher) if is_exact_matcher(matcher) => input
+            .map(|input| matcher.split('|').any(|candidate| candidate == input))
+            .unwrap_or(false),
+        Some(matcher) => input
+            .and_then(|input| {
+                regex::Regex::new(matcher)
+                    .ok()
+                    .map(|regex| regex.is_match(input))
+            })
+            .unwrap_or(false),
+    }
+}
+
+pub(crate) fn matcher_inputs<'a>(
+    tool_name: &'a str,
+    matcher_aliases: &'a [String],
+) -> Vec<&'a str> {
+    // Keep the canonical name first so matcher previews and execution preserve
+    // the same primary identity that hook stdin will serialize.
+    std::iter::once(tool_name)
+        .chain(matcher_aliases.iter().map(String::as_str))
+        .collect()
+}
+
+fn is_match_all_matcher(matcher: &str) -> bool {
+    matcher.is_empty() || matcher == "*"
+}
+
+fn is_exact_matcher(matcher: &str) -> bool {
+    matcher
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '|')
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::protocol::HookEventName;
+    use pretty_assertions::assert_eq;
+
+    use super::matcher_pattern_for_event;
+    use super::matches_matcher;
+    use super::validate_matcher_pattern;
+
+    #[test]
+    fn matcher_omitted_matches_all_occurrences() {
+        assert!(matches_matcher(/*matcher*/ None, Some("Bash")));
+        assert!(matches_matcher(/*matcher*/ None, Some("Write")));
+    }
+
+    #[test]
+    fn matcher_star_matches_all_occurrences() {
+        assert!(matches_matcher(Some("*"), Some("Bash")));
+        assert!(matches_matcher(Some("*"), Some("Edit")));
+        assert_eq!(validate_matcher_pattern("*"), Ok(()));
+    }
+
+    #[test]
+    fn matcher_empty_string_matches_all_occurrences() {
+        assert!(matches_matcher(Some(""), Some("Bash")));
+        assert!(matches_matcher(Some(""), Some("SessionStart")));
+        assert_eq!(validate_matcher_pattern(""), Ok(()));
+    }
+
+    #[test]
+    fn exact_matcher_supports_pipe_alternatives() {
+        assert!(matches_matcher(Some("Edit|Write"), Some("Edit")));
+        assert!(matches_matcher(Some("Edit|Write"), Some("Write")));
+        assert!(!matches_matcher(Some("Edit|Write"), Some("Bash")));
+        assert_eq!(validate_matcher_pattern("Edit|Write"), Ok(()));
+    }
+
+    #[test]
+    fn literal_matcher_uses_exact_matching() {
+        assert!(matches_matcher(Some("Bash"), Some("Bash")));
+        assert!(!matches_matcher(Some("Bash"), Some("BashOutput")));
+        assert!(matches_matcher(
+            Some("mcp__memory__create_entities"),
+            Some("mcp__memory__create_entities")
+        ));
+        assert!(!matches_matcher(
+            Some("mcp__memory"),
+            Some("mcp__memory__create_entities")
+        ));
+        assert_eq!(validate_matcher_pattern("mcp__memory"), Ok(()));
+    }
+
+    #[test]
+    fn matcher_uses_regex_when_it_contains_regex_characters() {
+        assert!(matches_matcher(Some("^Bash"), Some("BashOutput")));
+        assert_eq!(validate_matcher_pattern("^Bash"), Ok(()));
+    }
+
+    #[test]
+    fn mcp_matchers_support_regex_wildcards() {
+        assert!(matches_matcher(
+            Some("mcp__memory__.*"),
+            Some("mcp__memory__create_entities")
+        ));
+        assert!(matches_matcher(
+            Some("mcp__.*__write.*"),
+            Some("mcp__filesystem__write_file")
+        ));
+        assert!(!matches_matcher(
+            Some("mcp__.*__write.*"),
+            Some("mcp__filesystem__read_file")
+        ));
+        assert_eq!(validate_matcher_pattern("mcp__memory__.*"), Ok(()));
+    }
+
+    #[test]
+    fn matcher_supports_anchored_regexes() {
+        assert!(matches_matcher(Some("^Bash$"), Some("Bash")));
+        assert!(!matches_matcher(Some("^Bash$"), Some("BashOutput")));
+        assert_eq!(validate_matcher_pattern("^Bash$"), Ok(()));
+    }
+
+    #[test]
+    fn invalid_regex_is_rejected() {
+        assert!(validate_matcher_pattern("[").is_err());
+        assert!(!matches_matcher(Some("["), Some("Bash")));
+    }
+
+    #[test]
+    fn unsupported_events_ignore_matchers() {
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::UserPromptSubmit, Some("^hello")),
+            None
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::Stop, Some("^done$")),
+            None
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::Interrupt, Some("^interrupted$")),
+            None
+        );
+    }
+
+    #[test]
+    fn supported_events_keep_matchers() {
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::PreToolUse, Some("Bash")),
+            Some("Bash")
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::PostToolUse, Some("Edit|Write")),
+            Some("Edit|Write")
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::SessionStart, Some("startup|resume")),
+            Some("startup|resume")
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::SessionEnd, Some("clear|other")),
+            Some("clear|other")
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::PreCompact, Some("^auto$")),
+            Some("^auto$")
+        );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::PostCompact, Some("manual|auto")),
+            Some("manual|auto")
+        );
+    }
+}
diff --git a/codex-rs/hooks/src/events/compact.rs b/codex-rs/hooks/src/events/compact.rs
new file mode 100644
index 0000000000000000000000000000000000000000..82bd6c6cf55d1ce66755c7c9aeb3e4aba05de168
--- /dev/null
+++ b/codex-rs/hooks/src/events/compact.rs
@@ -0,0 +1,554 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::schema::PostCompactCommandInput;
+use crate::schema::PreCompactCommandInput;
+use crate::schema::SubagentCommandInputFields;
+
+#[derive(Debug, Clone)]
+pub struct PreCompactRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub subagent: Option<common::SubagentHookContext>,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub trigger: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct PostCompactRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub subagent: Option<common::SubagentHookContext>,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub trigger: String,
+}
+
+#[derive(Debug)]
+pub struct StatelessHookOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_stop: bool,
+    pub stop_reason: Option<String>,
+}
+
+#[derive(Debug)]
+pub struct PreCompactOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_stop: bool,
+    pub stop_reason: Option<String>,
+}
+
+pub(crate) fn preview_pre(
+    handlers: &[ConfiguredHandler],
+    request: &PreCompactRequest,
+) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        HookEventName::PreCompact,
+        Some(request.trigger.as_str()),
+    )
+    .into_iter()
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run_pre(
+    engine: &ClaudeHooksEngine,
+    request: PreCompactRequest,
+) -> PreCompactOutcome {
+    let matched = dispatcher::select_handlers(
+        &engine.handlers,
+        HookEventName::PreCompact,
+        Some(request.trigger.as_str()),
+    );
+    if matched.is_empty() {
+        return PreCompactOutcome {
+            hook_events: Vec::new(),
+            should_stop: false,
+            stop_reason: None,
+        };
+    }
+
+    let input_json = match pre_command_input_json(&request) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            return PreCompactOutcome {
+                hook_events: common::serialization_failure_hook_events(
+                    matched,
+                    Some(request.turn_id),
+                    format!("failed to serialize pre compact hook input: {error}"),
+                ),
+                should_stop: false,
+                stop_reason: None,
+            };
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id),
+        parse_pre_completed,
+    )
+    .await;
+    let should_stop = results.iter().any(|result| result.data.should_stop);
+    let stop_reason = results
+        .iter()
+        .find_map(|result| result.data.stop_reason.clone());
+    PreCompactOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+        should_stop,
+        stop_reason,
+    }
+}
+
+fn pre_command_input_json(request: &PreCompactRequest) -> Result<String, serde_json::Error> {
+    let subagent = SubagentCommandInputFields::from(request.subagent.as_ref());
+    serde_json::to_string(&PreCompactCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        agent_id: subagent.agent_id,
+        agent_type: subagent.agent_type,
+        transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "PreCompact".to_string(),
+        model: request.model.clone(),
+        trigger: request.trigger.clone(),
+    })
+}
+
+pub(crate) fn preview_post(
+    handlers: &[ConfiguredHandler],
+    request: &PostCompactRequest,
+) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        HookEventName::PostCompact,
+        Some(request.trigger.as_str()),
+    )
+    .into_iter()
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run_post(
+    engine: &ClaudeHooksEngine,
+    request: PostCompactRequest,
+) -> StatelessHookOutcome {
+    let matched = dispatcher::select_handlers(
+        &engine.handlers,
+        HookEventName::PostCompact,
+        Some(request.trigger.as_str()),
+    );
+    if matched.is_empty() {
+        return StatelessHookOutcome {
+            hook_events: Vec::new(),
+            should_stop: false,
+            stop_reason: None,
+        };
+    }
+
+    let input_json = match post_command_input_json(&request) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            return StatelessHookOutcome {
+                hook_events: common::serialization_failure_hook_events(
+                    matched,
+                    Some(request.turn_id),
+                    format!("failed to serialize post compact hook input: {error}"),
+                ),
+                should_stop: false,
+                stop_reason: None,
+            };
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id),
+        parse_post_completed,
+    )
+    .await;
+    let should_stop = results.iter().any(|result| result.data.should_stop);
+    let stop_reason = results
+        .iter()
+        .find_map(|result| result.data.stop_reason.clone());
+    StatelessHookOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+        should_stop,
+        stop_reason,
+    }
+}
+
+fn post_command_input_json(request: &PostCompactRequest) -> Result<String, serde_json::Error> {
+    let subagent = SubagentCommandInputFields::from(request.subagent.as_ref());
+    serde_json::to_string(&PostCompactCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        agent_id: subagent.agent_id,
+        agent_type: subagent.agent_type,
+        transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "PostCompact".to_string(),
+        model: request.model.clone(),
+        trigger: request.trigger.clone(),
+    })
+}
+
+#[derive(Default)]
+struct CompactHandlerData {
+    should_stop: bool,
+    stop_reason: Option<String>,
+}
+
+fn parse_pre_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<CompactHandlerData> {
+    parse_completed(
+        handler,
+        run_result,
+        turn_id,
+        "PreCompact",
+        output_parser::parse_pre_compact,
+    )
+}
+
+fn parse_post_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<CompactHandlerData> {
+    parse_completed(
+        handler,
+        run_result,
+        turn_id,
+        "PostCompact",
+        output_parser::parse_post_compact,
+    )
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+    event_label: &'static str,
+    parse_output: fn(&str) -> Option<output_parser::StatelessHookOutput>,
+) -> dispatcher::ParsedHandler<CompactHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_stop = false;
+    let mut stop_reason = None;
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = parse_output(&run_result.stdout) {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    let _ = parsed.universal.suppress_output;
+                    if handler.can_apply_control_effects() {
+                        if !parsed.universal.continue_processing {
+                            status = HookRunStatus::Stopped;
+                            should_stop = true;
+                            stop_reason = parsed.universal.stop_reason.clone();
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Stop,
+                                text: parsed.universal.stop_reason.unwrap_or_else(|| {
+                                    format!("{event_label} hook stopped execution")
+                                }),
+                            });
+                        } else if let Some(invalid_reason) = parsed.invalid_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_reason,
+                            });
+                        }
+                    }
+                } else if output_parser::looks_like_json(&run_result.stdout) {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: format!("hook returned invalid {event_label} hook JSON output"),
+                    });
+                }
+            }
+            Some(code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: common::trimmed_non_empty(&run_result.stderr)
+                        .unwrap_or_else(|| format!("hook exited with code {code}")),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook process terminated without an exit code".to_string(),
+                });
+            }
+        },
+    }
+
+    dispatcher::ParsedHandler {
+        completed: HookCompletedEvent {
+            turn_id,
+            run: dispatcher::completed_summary(handler, &run_result, status, entries),
+        },
+        data: CompactHandlerData {
+            should_stop,
+            stop_reason,
+        },
+        completion_order: 0,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    use super::parse_post_completed;
+    use super::parse_pre_completed;
+    use super::post_command_input_json;
+    use super::pre_command_input_json;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::HandlerRunResult;
+
+    #[test]
+    fn pre_compact_input_includes_lifecycle_metadata() {
+        let request = pre_request();
+        let input_json = pre_command_input_json(&request).expect("serialize command input");
+        let input: serde_json::Value =
+            serde_json::from_str(&input_json).expect("parse command input");
+
+        assert_eq!(
+            input,
+            json!({
+                "session_id": pre_request().session_id.to_string(),
+                "turn_id": "turn-1",
+                "transcript_path": null,
+                "cwd": test_path_buf("/tmp").display().to_string(),
+                "hook_event_name": "PreCompact",
+                "model": "gpt-test",
+                "trigger": "manual",
+            })
+        );
+    }
+
+    #[test]
+    fn post_compact_input_includes_lifecycle_metadata() {
+        let request = post_request();
+        let input_json = post_command_input_json(&request).expect("serialize command input");
+        let input: serde_json::Value =
+            serde_json::from_str(&input_json).expect("parse command input");
+
+        assert_eq!(
+            input,
+            json!({
+                "session_id": post_request().session_id.to_string(),
+                "turn_id": "turn-1",
+                "transcript_path": null,
+                "cwd": test_path_buf("/tmp").display().to_string(),
+                "hook_event_name": "PostCompact",
+                "model": "gpt-test",
+                "trigger": "manual",
+            })
+        );
+    }
+
+    #[test]
+    fn block_decision_is_not_supported_for_pre_compact() {
+        let parsed = parse_pre_completed(
+            &handler(HookEventName::PreCompact),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"policy blocked compaction"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "hook returned invalid PreCompact hook JSON output".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn continue_false_stops_before_compaction() {
+        let parsed = parse_pre_completed(
+            &handler(HookEventName::PreCompact),
+            run_result(Some(0), r#"{"continue":false,"stopReason":"nope"}"#, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(parsed.data.should_stop, true);
+        assert_eq!(parsed.data.stop_reason, Some("nope".to_string()));
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Stop,
+                text: "nope".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn post_compact_continue_false_stops_after_compaction() {
+        let parsed = parse_post_completed(
+            &handler(HookEventName::PostCompact),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"pause after compact"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(parsed.data.should_stop, true);
+        assert_eq!(
+            parsed.data.stop_reason,
+            Some("pause after compact".to_string())
+        );
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Stop,
+                text: "pause after compact".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn pre_compact_ignores_plain_stdout() {
+        let parsed = parse_pre_completed(
+            &handler(HookEventName::PreCompact),
+            run_result(Some(0), "checking compact policy\n", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, Vec::new());
+    }
+
+    #[test]
+    fn post_compact_ignores_plain_stdout() {
+        let parsed = parse_post_completed(
+            &handler(HookEventName::PostCompact),
+            run_result(Some(0), "logged compact summary\n", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, Vec::new());
+    }
+
+    fn pre_request() -> super::PreCompactRequest {
+        super::PreCompactRequest {
+            session_id: ThreadId::from_string("00000000-0000-4000-8000-000000000001")
+                .expect("valid thread id"),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd: test_path_buf("/tmp").abs(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            trigger: "manual".to_string(),
+        }
+    }
+
+    fn post_request() -> super::PostCompactRequest {
+        super::PostCompactRequest {
+            session_id: ThreadId::from_string("00000000-0000-4000-8000-000000000002")
+                .expect("valid thread id"),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd: test_path_buf("/tmp").abs(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            trigger: "manual".to_string(),
+        }
+    }
+
+    fn handler(event_name: HookEventName) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name,
+            matcher: None,
+            timeout_sec: 5,
+            status_message: Some("running compact hook".to_string()),
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: codex_protocol::protocol::HookSource::User,
+            display_order: 0,
+            kind: crate::engine::ConfiguredHandlerKind::Command {
+                command: "python3 compact_hook.py".to_string(),
+                r#async: false,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+        HandlerRunResult {
+            started_at: 1_700_000_000,
+            completed_at: 1_700_000_001,
+            duration_ms: 12,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+}
diff --git a/codex-rs/hooks/src/events/interrupt.rs b/codex-rs/hooks/src/events/interrupt.rs
new file mode 100644
index 0000000000000000000000000000000000000000..743002eb9ca1b457132f466a9cddd964e8cd5942
--- /dev/null
+++ b/codex-rs/hooks/src/events/interrupt.rs
@@ -0,0 +1,183 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde_json::Map;
+use serde_json::Value;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::HandlerSourcePath;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::schema::InterruptCommandInput;
+use crate::schema::NullableString;
+
+#[derive(Debug, Clone)]
+pub struct InterruptRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub request_metadata: Option<Map<String, Value>>,
+}
+
+#[derive(Debug, Default)]
+pub struct InterruptOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct InterruptHandlerData;
+
+pub(crate) fn preview(handlers: &[ConfiguredHandler]) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        HookEventName::Interrupt,
+        /*matcher_input*/ None,
+    )
+    .into_iter()
+    // Executor-scoped hooks run asynchronously and do not emit public hook lifecycle events.
+    .filter(|handler| matches!(handler.source_path, HandlerSourcePath::Local(_)))
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run(engine: &ClaudeHooksEngine, request: InterruptRequest) -> InterruptOutcome {
+    let matched = dispatcher::select_handlers(
+        &engine.handlers,
+        HookEventName::Interrupt,
+        /*matcher_input*/ None,
+    );
+    if matched.is_empty() {
+        return InterruptOutcome::default();
+    }
+
+    let InterruptRequest {
+        session_id,
+        turn_id,
+        cwd,
+        transcript_path,
+        model,
+        permission_mode,
+        request_metadata,
+    } = request;
+    let input_json = match serde_json::to_string(&InterruptCommandInput {
+        session_id: session_id.to_string(),
+        turn_id: turn_id.clone(),
+        transcript_path: NullableString::from_path(transcript_path),
+        cwd: cwd.display().to_string(),
+        hook_event_name: "Interrupt".to_string(),
+        model,
+        permission_mode,
+    }) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            return InterruptOutcome {
+                hook_events: common::serialization_failure_hook_events(
+                    matched,
+                    Some(turn_id),
+                    format!("failed to serialize interrupt hook input: {error}"),
+                ),
+            };
+        }
+    };
+
+    let results = dispatcher::execute_handlers_with_metadata(
+        engine,
+        matched,
+        input_json,
+        cwd.as_path(),
+        Some(turn_id),
+        request_metadata.as_ref(),
+        parse_completed,
+    )
+    .await;
+
+    InterruptOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+    }
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<InterruptHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = output_parser::parse_interrupt(&run_result.stdout) {
+                    if let Some(system_message) = parsed.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                } else {
+                    status = HookRunStatus::Failed;
+                    let text = if output_parser::looks_like_json(&run_result.stdout) {
+                        "hook returned invalid interrupt hook JSON output"
+                    } else {
+                        "Interrupt hook returned non-JSON stdout"
+                    };
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: text.to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: InterruptHandlerData,
+        completion_order: 0,
+    }
+}
+
+#[cfg(test)]
+#[path = "interrupt_tests.rs"]
+mod tests;
diff --git a/codex-rs/hooks/src/events/interrupt_tests.rs b/codex-rs/hooks/src/events/interrupt_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3d8642c8457bc86dfc4ffba9ffd37d0db3bddc83
--- /dev/null
+++ b/codex-rs/hooks/src/events/interrupt_tests.rs
@@ -0,0 +1,128 @@
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+
+use super::InterruptHandlerData;
+use super::parse_completed;
+use crate::engine::ConfiguredHandler;
+use crate::engine::ConfiguredHandlerKind;
+use crate::engine::HandlerRunResult;
+
+#[test]
+fn empty_stdout_succeeds() {
+    let parsed = parse_completed(
+        &handler(),
+        run_result(Some(0), "", ""),
+        /*turn_id*/ None,
+    );
+
+    assert_eq!(parsed.data, InterruptHandlerData);
+    assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+    assert!(parsed.completed.run.entries.is_empty());
+}
+
+#[test]
+fn system_message_becomes_warning() {
+    let parsed = parse(r#"{"systemMessage":"watch the tide"}"#, Some(0));
+
+    assert_eq!(parsed.data, InterruptHandlerData);
+    assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+    assert_eq!(
+        parsed.completed.run.entries,
+        vec![warning("watch the tide")]
+    );
+}
+
+#[test]
+fn invalid_json_outputs_fail() {
+    for stdout in [
+        r#"{"continue":true}"#,
+        r#"{"stopReason":null}"#,
+        r#"{"suppressOutput":false}"#,
+        r#"{"decision":"block"}"#,
+        r#"{"systemMessage":"watch the tide""#,
+    ] {
+        assert_failed(
+            stdout,
+            Some(0),
+            "hook returned invalid interrupt hook JSON output",
+        );
+    }
+}
+
+#[test]
+fn other_failures_use_standard_errors() {
+    for (exit_code, stdout, expected) in [
+        (Some(0), "aloha", "Interrupt hook returned non-JSON stdout"),
+        (Some(2), "", "hook exited with code 2"),
+    ] {
+        assert_failed(stdout, exit_code, expected);
+    }
+}
+
+fn assert_failed(stdout: &str, exit_code: Option<i32>, expected: &str) {
+    let parsed = parse(stdout, exit_code);
+    assert_eq!(parsed.data, InterruptHandlerData);
+    assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+    assert_eq!(parsed.completed.run.entries, vec![error(expected)]);
+}
+
+fn parse(
+    stdout: &str,
+    exit_code: Option<i32>,
+) -> crate::engine::dispatcher::ParsedHandler<InterruptHandlerData> {
+    parse_completed(
+        &handler(),
+        run_result(exit_code, stdout, "ignored"),
+        Some("turn-1".to_string()),
+    )
+}
+
+fn warning(text: &str) -> HookOutputEntry {
+    HookOutputEntry {
+        kind: HookOutputEntryKind::Warning,
+        text: text.to_string(),
+    }
+}
+
+fn error(text: &str) -> HookOutputEntry {
+    HookOutputEntry {
+        kind: HookOutputEntryKind::Error,
+        text: text.to_string(),
+    }
+}
+
+fn handler() -> ConfiguredHandler {
+    ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::Interrupt,
+        matcher: None,
+        timeout_sec: 600,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+        source: codex_protocol::protocol::HookSource::User,
+        display_order: 0,
+        kind: ConfiguredHandlerKind::Command {
+            command: "echo hook".to_string(),
+            r#async: false,
+            env: std::collections::HashMap::new(),
+        },
+    }
+}
+
+fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+    HandlerRunResult {
+        started_at: 1,
+        completed_at: 2,
+        duration_ms: 1,
+        exit_code,
+        stdout: stdout.to_string(),
+        stderr: stderr.to_string(),
+        error: None,
+    }
+}
diff --git a/codex-rs/hooks/src/events/mod.rs b/codex-rs/hooks/src/events/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3d5ea1baad17c0b3814a59aa19c8b23feae49ed8
--- /dev/null
+++ b/codex-rs/hooks/src/events/mod.rs
@@ -0,0 +1,10 @@
+pub(crate) mod common;
+pub mod compact;
+pub mod interrupt;
+pub mod permission_request;
+pub mod post_tool_use;
+pub mod pre_tool_use;
+pub mod session_end;
+pub mod session_start;
+pub mod stop;
+pub mod user_prompt_submit;
diff --git a/codex-rs/hooks/src/events/permission_request.rs b/codex-rs/hooks/src/events/permission_request.rs
new file mode 100644
index 0000000000000000000000000000000000000000..58da6c8e4d11082ff5ba402c2f2f705b75a9ed09
--- /dev/null
+++ b/codex-rs/hooks/src/events/permission_request.rs
@@ -0,0 +1,337 @@
+//! Permission-request hook execution.
+//!
+//! This event runs in the approval path, before guardian or user approval UI is
+//! shown. Unlike `pre_tool_use`, handlers do not rewrite tool input or block by
+//! stopping execution outright; instead they can return a concrete allow/deny
+//! decision, or decline to decide and let the normal approval flow continue.
+//!
+//! The event also mirrors the rest of the hook system's lifecycle:
+//!
+//! 1. Preview matching handlers so the UI can render pending hook rows.
+//! 2. Execute every matching handler in precedence order.
+//! 3. Parse each handler into transcript-visible output plus an optional
+//!    decision.
+//! 4. Fold the decisions conservatively: any deny wins, otherwise the last
+//!    allow wins, otherwise there is no hook verdict.
+use std::path::PathBuf;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::schema::PermissionRequestCommandInput;
+use crate::schema::SubagentCommandInputFields;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use serde_json::Value;
+
+#[derive(Debug, Clone)]
+pub struct PermissionRequestRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub subagent: Option<common::SubagentHookContext>,
+    pub cwd: PathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub matcher_aliases: Vec<String>,
+    pub run_id_suffix: String,
+    pub tool_input: Value,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PermissionRequestDecision {
+    Allow,
+    Deny { message: String },
+}
+
+#[derive(Debug)]
+pub struct PermissionRequestOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub decision: Option<PermissionRequestDecision>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct PermissionRequestHandlerData {
+    decision: Option<PermissionRequestDecision>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    request: &PermissionRequestRequest,
+) -> Vec<HookRunSummary> {
+    let matcher_inputs = common::matcher_inputs(&request.tool_name, &request.matcher_aliases);
+    dispatcher::select_handlers_for_matcher_inputs(
+        handlers,
+        HookEventName::PermissionRequest,
+        &matcher_inputs,
+    )
+    .into_iter()
+    .map(|handler| {
+        common::hook_run_for_tool_use(
+            dispatcher::running_summary(&handler),
+            &request.run_id_suffix,
+        )
+    })
+    .collect()
+}
+
+pub(crate) async fn run(
+    engine: &ClaudeHooksEngine,
+    request: PermissionRequestRequest,
+) -> PermissionRequestOutcome {
+    let matcher_inputs = common::matcher_inputs(&request.tool_name, &request.matcher_aliases);
+    let matched = dispatcher::select_handlers_for_matcher_inputs(
+        &engine.handlers,
+        HookEventName::PermissionRequest,
+        &matcher_inputs,
+    );
+    if matched.is_empty() {
+        return PermissionRequestOutcome {
+            hook_events: Vec::new(),
+            decision: None,
+        };
+    }
+
+    let input_json = match serde_json::to_string(&build_command_input(&request)) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            let hook_events = common::serialization_failure_hook_events_for_tool_use(
+                matched,
+                Some(request.turn_id.clone()),
+                format!("failed to serialize permission request hook input: {error}"),
+                &request.run_id_suffix,
+            );
+            return PermissionRequestOutcome {
+                hook_events,
+                decision: None,
+            };
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id.clone()),
+        parse_completed,
+    )
+    .await;
+
+    // Preserve the most specific matching allow, but treat any deny as final so
+    // broader policy layers cannot accidentally overrule a more specific block.
+    let decision = resolve_permission_request_decision(
+        results
+            .iter()
+            .filter_map(|result| result.data.decision.as_ref()),
+    );
+
+    PermissionRequestOutcome {
+        hook_events: results
+            .into_iter()
+            .map(|result| {
+                common::hook_completed_for_tool_use(result.completed, &request.run_id_suffix)
+            })
+            .collect(),
+        decision,
+    }
+}
+
+/// Resolve matching hook decisions conservatively: any deny wins immediately;
+/// otherwise keep the highest-precedence allow so more specific handlers
+/// override broader ones.
+fn resolve_permission_request_decision<'a>(
+    decisions: impl IntoIterator<Item = &'a PermissionRequestDecision>,
+) -> Option<PermissionRequestDecision> {
+    let mut resolved_allow = None;
+    for decision in decisions {
+        match decision {
+            PermissionRequestDecision::Allow => {
+                resolved_allow = Some(PermissionRequestDecision::Allow);
+            }
+            PermissionRequestDecision::Deny { message } => {
+                return Some(PermissionRequestDecision::Deny {
+                    message: message.clone(),
+                });
+            }
+        }
+    }
+    resolved_allow
+}
+
+fn build_command_input(request: &PermissionRequestRequest) -> PermissionRequestCommandInput {
+    let subagent = SubagentCommandInputFields::from(request.subagent.as_ref());
+    PermissionRequestCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        agent_id: subagent.agent_id,
+        agent_type: subagent.agent_type,
+        transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "PermissionRequest".to_string(),
+        model: request.model.clone(),
+        permission_mode: request.permission_mode.clone(),
+        tool_name: request.tool_name.clone(),
+        tool_input: request.tool_input.clone(),
+    }
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<PermissionRequestHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut decision = None;
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) =
+                    output_parser::parse_permission_request(&run_result.stdout)
+                {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    if handler.can_apply_control_effects() {
+                        if let Some(invalid_reason) = parsed.invalid_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_reason,
+                            });
+                        } else if let Some(parsed_decision) = parsed.decision {
+                            match parsed_decision {
+                                output_parser::PermissionRequestDecision::Allow => {
+                                    decision = Some(PermissionRequestDecision::Allow);
+                                }
+                                output_parser::PermissionRequestDecision::Deny { message } => {
+                                    status = HookRunStatus::Blocked;
+                                    entries.push(HookOutputEntry {
+                                        kind: HookOutputEntryKind::Feedback,
+                                        text: message.clone(),
+                                    });
+                                    decision = Some(PermissionRequestDecision::Deny { message });
+                                }
+                            }
+                        }
+                    }
+                } else if output_parser::looks_like_json(&run_result.stdout) {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "hook returned invalid permission-request JSON output".to_string(),
+                    });
+                }
+            }
+            Some(2) if handler.can_apply_control_effects() => {
+                if let Some(message) = common::trimmed_non_empty(&run_result.stderr) {
+                    status = HookRunStatus::Blocked;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Feedback,
+                        text: message.clone(),
+                    });
+                    decision = Some(PermissionRequestDecision::Deny { message });
+                } else {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "PermissionRequest hook exited with code 2 but did not write a denial reason to stderr".to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: PermissionRequestHandlerData { decision },
+        completion_order: 0,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::PermissionRequestDecision;
+    use super::resolve_permission_request_decision;
+
+    #[test]
+    fn permission_request_deny_overrides_earlier_allow() {
+        let decisions = [
+            PermissionRequestDecision::Allow,
+            PermissionRequestDecision::Deny {
+                message: "repo deny".to_string(),
+            },
+        ];
+
+        assert_eq!(
+            resolve_permission_request_decision(decisions.iter()),
+            Some(PermissionRequestDecision::Deny {
+                message: "repo deny".to_string(),
+            })
+        );
+    }
+
+    #[test]
+    fn permission_request_returns_allow_when_no_handler_denies() {
+        let decisions = [
+            PermissionRequestDecision::Allow,
+            PermissionRequestDecision::Allow,
+        ];
+
+        assert_eq!(
+            resolve_permission_request_decision(decisions.iter()),
+            Some(PermissionRequestDecision::Allow)
+        );
+    }
+
+    #[test]
+    fn permission_request_returns_none_when_no_handler_decides() {
+        let decisions = Vec::<PermissionRequestDecision>::new();
+
+        assert_eq!(resolve_permission_request_decision(decisions.iter()), None);
+    }
+}
diff --git a/codex-rs/hooks/src/events/post_tool_use.rs b/codex-rs/hooks/src/events/post_tool_use.rs
new file mode 100644
index 0000000000000000000000000000000000000000..aeb0ed20a7a12cb0ffd7ba979633c8a7557ccdae
--- /dev/null
+++ b/codex-rs/hooks/src/events/post_tool_use.rs
@@ -0,0 +1,637 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde_json::Value;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::output_spill::AdditionalContext;
+use crate::schema::PostToolUseCommandInput;
+use crate::schema::SubagentCommandInputFields;
+
+#[derive(Debug, Clone)]
+pub struct PostToolUseRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub subagent: Option<common::SubagentHookContext>,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub matcher_aliases: Vec<String>,
+    pub tool_use_id: String,
+    pub tool_input: Value,
+    pub tool_response: Value,
+}
+
+#[derive(Debug)]
+pub struct PostToolUseOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_block: bool,
+    pub additional_contexts: Vec<String>,
+    pub feedback_message: Option<String>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct PostToolUseHandlerData {
+    should_block: bool,
+    additional_contexts_for_model: Vec<AdditionalContext>,
+    feedback_messages_for_model: Vec<String>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    request: &PostToolUseRequest,
+) -> Vec<HookRunSummary> {
+    let matcher_inputs = common::matcher_inputs(&request.tool_name, &request.matcher_aliases);
+    dispatcher::select_handlers_for_matcher_inputs(
+        handlers,
+        HookEventName::PostToolUse,
+        &matcher_inputs,
+    )
+    .into_iter()
+    .map(|handler| {
+        common::hook_run_for_tool_use(dispatcher::running_summary(&handler), &request.tool_use_id)
+    })
+    .collect()
+}
+
+pub(crate) async fn run(
+    engine: &ClaudeHooksEngine,
+    request: PostToolUseRequest,
+) -> PostToolUseOutcome {
+    let matcher_inputs = common::matcher_inputs(&request.tool_name, &request.matcher_aliases);
+    let matched = dispatcher::select_handlers_for_matcher_inputs(
+        &engine.handlers,
+        HookEventName::PostToolUse,
+        &matcher_inputs,
+    );
+    if matched.is_empty() {
+        return PostToolUseOutcome {
+            hook_events: Vec::new(),
+            should_block: false,
+            additional_contexts: Vec::new(),
+            feedback_message: None,
+        };
+    }
+
+    let input_json = match command_input_json(&request) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            let hook_events = common::serialization_failure_hook_events_for_tool_use(
+                matched,
+                Some(request.turn_id.clone()),
+                format!("failed to serialize post tool use hook input: {error}"),
+                &request.tool_use_id,
+            );
+            return serialization_failure_outcome(hook_events);
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id.clone()),
+        parse_completed,
+    )
+    .await;
+
+    let additional_contexts = common::flatten_additional_contexts(
+        results
+            .iter()
+            .map(|result| result.data.additional_contexts_for_model.as_slice()),
+    );
+    let additional_contexts = engine
+        .command_runtime
+        .output_spiller()
+        .maybe_spill_additional_contexts(additional_contexts)
+        .await;
+    let should_block = results.iter().any(|result| result.data.should_block);
+    let feedback_message = common::join_text_chunks(
+        results
+            .iter()
+            .flat_map(|result| result.data.feedback_messages_for_model.clone())
+            .collect(),
+    );
+
+    PostToolUseOutcome {
+        hook_events: results
+            .into_iter()
+            .map(|result| {
+                common::hook_completed_for_tool_use(result.completed, &request.tool_use_id)
+            })
+            .collect(),
+        should_block,
+        additional_contexts,
+        feedback_message,
+    }
+}
+
+/// Serializes command stdin for a selected `PostToolUse` hook.
+///
+/// Handler selection may include internal matcher aliases, but hook stdin keeps
+/// the canonical `tool_name` for logs and for consumers that pair pre/post
+/// events across processes. Shell-like tools pass `{ "command": ... }` as
+/// `tool_input`; MCP tools pass their resolved JSON arguments.
+fn command_input_json(request: &PostToolUseRequest) -> Result<String, serde_json::Error> {
+    let subagent = SubagentCommandInputFields::from(request.subagent.as_ref());
+    serde_json::to_string(&PostToolUseCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        agent_id: subagent.agent_id,
+        agent_type: subagent.agent_type,
+        transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "PostToolUse".to_string(),
+        model: request.model.clone(),
+        permission_mode: request.permission_mode.clone(),
+        tool_name: request.tool_name.clone(),
+        tool_input: request.tool_input.clone(),
+        tool_response: request.tool_response.clone(),
+        tool_use_id: request.tool_use_id.clone(),
+    })
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<PostToolUseHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_block = false;
+    let mut additional_contexts_for_model = Vec::new();
+    let mut feedback_messages_for_model = Vec::new();
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = output_parser::parse_post_tool_use(&run_result.stdout)
+                {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    if (!handler.can_apply_control_effects()
+                        || parsed.invalid_reason.is_none() && parsed.invalid_block_reason.is_none())
+                        && let Some(additional_context) = parsed.additional_context
+                    {
+                        common::append_additional_context(
+                            &mut entries,
+                            &mut additional_contexts_for_model,
+                            handler,
+                            additional_context,
+                        );
+                    }
+                    if handler.can_apply_control_effects() {
+                        if !parsed.universal.continue_processing {
+                            status = HookRunStatus::Stopped;
+                            let stop_text = parsed.universal.stop_reason.unwrap_or_else(|| {
+                                "PostToolUse hook stopped execution".to_string()
+                            });
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Stop,
+                                text: stop_text.clone(),
+                            });
+                            let model_feedback = parsed
+                                .reason
+                                .as_deref()
+                                .and_then(common::trimmed_non_empty)
+                                .unwrap_or(stop_text);
+                            feedback_messages_for_model.push(model_feedback);
+                        } else if let Some(invalid_reason) = parsed.invalid_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_reason,
+                            });
+                        } else if let Some(invalid_block_reason) = parsed.invalid_block_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_block_reason,
+                            });
+                        } else if parsed.should_block {
+                            status = HookRunStatus::Blocked;
+                            should_block = true;
+                            if let Some(reason) = parsed.reason {
+                                entries.push(HookOutputEntry {
+                                    kind: HookOutputEntryKind::Feedback,
+                                    text: reason.clone(),
+                                });
+                                feedback_messages_for_model.push(reason);
+                            }
+                        }
+                    }
+                } else if output_parser::looks_like_json(&run_result.stdout) {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "hook returned invalid post-tool-use JSON output".to_string(),
+                    });
+                }
+            }
+            Some(2) if handler.can_apply_control_effects() => {
+                if let Some(reason) = common::trimmed_non_empty(&run_result.stderr) {
+                    status = HookRunStatus::Blocked;
+                    should_block = true;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Feedback,
+                        text: reason.clone(),
+                    });
+                    feedback_messages_for_model.push(reason);
+                } else {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "PostToolUse hook exited with code 2 but did not write feedback to stderr".to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: PostToolUseHandlerData {
+            should_block,
+            additional_contexts_for_model,
+            feedback_messages_for_model,
+        },
+        completion_order: 0,
+    }
+}
+
+fn serialization_failure_outcome(hook_events: Vec<HookCompletedEvent>) -> PostToolUseOutcome {
+    PostToolUseOutcome {
+        hook_events,
+        should_block: false,
+        additional_contexts: Vec::new(),
+        feedback_message: None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    use super::PostToolUseHandlerData;
+    use super::command_input_json;
+    use super::parse_completed;
+    use super::preview;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::HandlerRunResult;
+    use crate::events::common;
+    use crate::output_spill::AdditionalContext;
+    use crate::output_spill::AdditionalContextLimit;
+
+    #[test]
+    fn command_input_uses_request_tool_name() {
+        let mut request = request_for_tool_use("call-apply-patch");
+        request.tool_name = "apply_patch".to_string();
+
+        let input_json = command_input_json(&request).expect("serialize command input");
+        let input: serde_json::Value =
+            serde_json::from_str(&input_json).expect("parse command input");
+
+        assert_eq!(input["tool_name"], "apply_patch");
+    }
+
+    #[test]
+    fn block_decision_stops_normal_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"bash output looked sketchy"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: true,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["bash output looked sketchy".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+    }
+
+    #[test]
+    fn additional_context_is_recorded() {
+        let mut handler = handler();
+        handler.additional_context_limit = AdditionalContextLimit::from_config(Some(17));
+        let parsed = parse_completed(
+            &handler,
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Remember the bash cleanup note."}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: false,
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "Remember the bash cleanup note.".to_string(),
+                    limit: AdditionalContextLimit::from_config(Some(17)),
+                }],
+                feedback_messages_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "Remember the bash cleanup note.".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn unsupported_updated_mcp_tool_output_fails_open() {
+        let stdout = r#"{"hookSpecificOutput":{"hookEventName":"PostToolUse","updatedMCPToolOutput":{"ok":true},"additionalContext":"preserved"}}"#;
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), stdout, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: false,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "PostToolUse hook returned unsupported updatedMCPToolOutput".to_string(),
+            }]
+        );
+
+        let async_handler = handler_with_async(/*async*/ true);
+        let parsed = parse_completed(
+            &async_handler,
+            run_result(Some(0), stdout, ""),
+            Some("turn-1".to_string()),
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "preserved".to_string(),
+            }],
+        );
+    }
+
+    #[test]
+    fn exit_two_blocks_with_feedback() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(2), "", "post hook says pause"),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: true,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["post hook says pause".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+    }
+
+    #[test]
+    fn continue_false_stops_with_reason() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"halt after bash output","reason":"post-tool hook says stop"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: false,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["post-tool hook says stop".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Stop,
+                text: "halt after bash output".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn continue_false_without_reason_synthesizes_feedback() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), r#"{"continue":false}"#, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: false,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["PostToolUse hook stopped execution".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Stop,
+                text: "PostToolUse hook stopped execution".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn plain_stdout_is_ignored_for_post_tool_use() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "plain text only", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_block: false,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, Vec::<HookOutputEntry>::new());
+    }
+
+    #[test]
+    fn preview_and_completed_run_ids_include_tool_use_id() {
+        let request = request_for_tool_use("tool-call-456");
+        let runs = preview(&[handler()], &request);
+
+        assert_eq!(runs.len(), 1);
+        assert_eq!(
+            runs[0].id,
+            format!(
+                "post-tool-use:0:{}:tool-call-456",
+                test_path_buf("/tmp/hooks.json").display()
+            )
+        );
+
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "", ""),
+            Some("turn-1".to_string()),
+        );
+        let completed = common::hook_completed_for_tool_use(parsed.completed, &request.tool_use_id);
+
+        assert_eq!(completed.run.id, runs[0].id);
+    }
+
+    #[test]
+    fn serialization_failure_run_ids_include_tool_use_id() {
+        let request = request_for_tool_use("tool-call-456");
+        let runs = preview(&[handler()], &request);
+
+        let completed = common::serialization_failure_hook_events_for_tool_use(
+            vec![handler()],
+            Some(request.turn_id.clone()),
+            "serialize failed".into(),
+            &request.tool_use_id,
+        );
+
+        assert_eq!(completed.len(), 1);
+        assert_eq!(completed[0].run.id, runs[0].id);
+    }
+
+    fn handler() -> ConfiguredHandler {
+        handler_with_async(/*async*/ false)
+    }
+
+    fn handler_with_async(r#async: bool) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name: HookEventName::PostToolUse,
+            matcher: Some("^Bash$".to_string()),
+            timeout_sec: 5,
+            status_message: Some("running post tool use hook".to_string()),
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: codex_protocol::protocol::HookSource::User,
+            display_order: 0,
+            kind: crate::engine::ConfiguredHandlerKind::Command {
+                command: "python3 post_tool_use_hook.py".to_string(),
+                r#async,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+        HandlerRunResult {
+            started_at: 1_700_000_000,
+            completed_at: 1_700_000_001,
+            duration_ms: 12,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+
+    fn request_for_tool_use(tool_use_id: &str) -> super::PostToolUseRequest {
+        super::PostToolUseRequest {
+            session_id: ThreadId::new(),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd: test_path_buf("/tmp").abs(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            matcher_aliases: Vec::new(),
+            tool_use_id: tool_use_id.to_string(),
+            tool_input: json!({ "command": "echo hello" }),
+            tool_response: json!({"ok": true}),
+        }
+    }
+}
diff --git a/codex-rs/hooks/src/events/pre_tool_use.rs b/codex-rs/hooks/src/events/pre_tool_use.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c1baebd4f01fd1906f461fe84cb2bf0d73058bfc
--- /dev/null
+++ b/codex-rs/hooks/src/events/pre_tool_use.rs
@@ -0,0 +1,820 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde_json::Value;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::output_spill::AdditionalContext;
+use crate::schema::PreToolUseCommandInput;
+use crate::schema::SubagentCommandInputFields;
+
+#[derive(Debug, Clone)]
+pub struct PreToolUseRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub subagent: Option<common::SubagentHookContext>,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub matcher_aliases: Vec<String>,
+    pub tool_use_id: String,
+    pub tool_input: Value,
+}
+
+#[derive(Debug)]
+pub struct PreToolUseOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_block: bool,
+    pub block_reason: Option<String>,
+    pub additional_contexts: Vec<String>,
+    pub updated_input: Option<Value>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct PreToolUseHandlerData {
+    should_block: bool,
+    block_reason: Option<String>,
+    additional_contexts_for_model: Vec<AdditionalContext>,
+    updated_input: Option<Value>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    request: &PreToolUseRequest,
+) -> Vec<HookRunSummary> {
+    let matcher_inputs = common::matcher_inputs(&request.tool_name, &request.matcher_aliases);
+    dispatcher::select_handlers_for_matcher_inputs(
+        handlers,
+        HookEventName::PreToolUse,
+        &matcher_inputs,
+    )
+    .into_iter()
+    .map(|handler| {
+        common::hook_run_for_tool_use(dispatcher::running_summary(&handler), &request.tool_use_id)
+    })
+    .collect()
+}
+
+pub(crate) async fn run(
+    engine: &ClaudeHooksEngine,
+    request: PreToolUseRequest,
+) -> PreToolUseOutcome {
+    let matcher_inputs = common::matcher_inputs(&request.tool_name, &request.matcher_aliases);
+    let matched = dispatcher::select_handlers_for_matcher_inputs(
+        &engine.handlers,
+        HookEventName::PreToolUse,
+        &matcher_inputs,
+    );
+    if matched.is_empty() {
+        return PreToolUseOutcome {
+            hook_events: Vec::new(),
+            should_block: false,
+            block_reason: None,
+            additional_contexts: Vec::new(),
+            updated_input: None,
+        };
+    }
+
+    let input_json = match command_input_json(&request) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            let hook_events = common::serialization_failure_hook_events_for_tool_use(
+                matched,
+                Some(request.turn_id.clone()),
+                format!("failed to serialize pre tool use hook input: {error}"),
+                &request.tool_use_id,
+            );
+            return serialization_failure_outcome(hook_events);
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id.clone()),
+        parse_completed,
+    )
+    .await;
+
+    let should_block = results.iter().any(|result| result.data.should_block);
+    let block_reason = results
+        .iter()
+        .find_map(|result| result.data.block_reason.clone());
+    let additional_contexts = common::flatten_additional_contexts(
+        results
+            .iter()
+            .map(|result| result.data.additional_contexts_for_model.as_slice()),
+    );
+    let additional_contexts = engine
+        .command_runtime
+        .output_spiller()
+        .maybe_spill_additional_contexts(additional_contexts)
+        .await;
+    let updated_input = if should_block {
+        None
+    } else {
+        latest_updated_input(&results)
+    };
+
+    PreToolUseOutcome {
+        hook_events: results
+            .into_iter()
+            .map(|result| {
+                common::hook_completed_for_tool_use(result.completed, &request.tool_use_id)
+            })
+            .collect(),
+        should_block,
+        block_reason,
+        additional_contexts,
+        updated_input,
+    }
+}
+
+/// Chooses the rewrite from the hook that actually finished last.
+///
+/// Hook results stay in configured order for stable reporting, but the
+/// `PreToolUse` contract resolves competing rewrites by completion order.
+fn latest_updated_input(
+    results: &[dispatcher::ParsedHandler<PreToolUseHandlerData>],
+) -> Option<Value> {
+    results
+        .iter()
+        .filter_map(|result| {
+            result
+                .data
+                .updated_input
+                .clone()
+                .map(|updated_input| (result.completion_order, updated_input))
+        })
+        .max_by_key(|(completion_order, _)| *completion_order)
+        .map(|(_, updated_input)| updated_input)
+}
+
+/// Serializes command stdin for a selected `PreToolUse` hook.
+///
+/// Handler selection may include internal matcher aliases, but hook stdin keeps
+/// the canonical `tool_name` so audit logs and downstream policy decisions stay
+/// stable. Shell-like tools pass `{ "command": ... }` as `tool_input`; MCP
+/// tools pass their resolved JSON arguments.
+fn command_input_json(request: &PreToolUseRequest) -> Result<String, serde_json::Error> {
+    let subagent = SubagentCommandInputFields::from(request.subagent.as_ref());
+    serde_json::to_string(&PreToolUseCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        agent_id: subagent.agent_id,
+        agent_type: subagent.agent_type,
+        transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "PreToolUse".to_string(),
+        model: request.model.clone(),
+        permission_mode: request.permission_mode.clone(),
+        tool_name: request.tool_name.clone(),
+        tool_input: request.tool_input.clone(),
+        tool_use_id: request.tool_use_id.clone(),
+    })
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<PreToolUseHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_block = false;
+    let mut block_reason = None;
+    let mut additional_contexts_for_model = Vec::new();
+    let mut updated_input = None;
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = output_parser::parse_pre_tool_use(&run_result.stdout) {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    if (!handler.can_apply_control_effects() || parsed.invalid_reason.is_none())
+                        && let Some(additional_context) = parsed.additional_context
+                    {
+                        common::append_additional_context(
+                            &mut entries,
+                            &mut additional_contexts_for_model,
+                            handler,
+                            additional_context,
+                        );
+                    }
+                    if handler.can_apply_control_effects() {
+                        if let Some(invalid_reason) = parsed.invalid_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_reason,
+                            });
+                        } else if let Some(reason) = parsed.block_reason {
+                            status = HookRunStatus::Blocked;
+                            should_block = true;
+                            block_reason = Some(reason.clone());
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Feedback,
+                                text: reason,
+                            });
+                        } else {
+                            updated_input = parsed.updated_input;
+                        }
+                    }
+                } else if output_parser::looks_like_json(&run_result.stdout) {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "hook returned invalid pre-tool-use JSON output".to_string(),
+                    });
+                }
+            }
+            Some(2) if handler.can_apply_control_effects() => {
+                if let Some(reason) = common::trimmed_non_empty(&run_result.stderr) {
+                    status = HookRunStatus::Blocked;
+                    should_block = true;
+                    block_reason = Some(reason.clone());
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Feedback,
+                        text: reason,
+                    });
+                } else {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "PreToolUse hook exited with code 2 but did not write a blocking reason to stderr".to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: PreToolUseHandlerData {
+            should_block,
+            block_reason,
+            additional_contexts_for_model,
+            updated_input,
+        },
+        completion_order: 0,
+    }
+}
+
+fn serialization_failure_outcome(hook_events: Vec<HookCompletedEvent>) -> PreToolUseOutcome {
+    PreToolUseOutcome {
+        hook_events,
+        should_block: false,
+        block_reason: None,
+        additional_contexts: Vec::new(),
+        updated_input: None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::PreToolUseHandlerData;
+    use super::command_input_json;
+    use super::latest_updated_input;
+    use super::parse_completed;
+    use super::preview;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::HandlerRunResult;
+    use crate::events::common;
+    use crate::output_spill::AdditionalContext;
+    use crate::output_spill::AdditionalContextLimit;
+
+    #[test]
+    fn command_input_uses_request_tool_name() {
+        let mut request = request_for_tool_use("call-apply-patch");
+        request.tool_name = "apply_patch".to_string();
+
+        let input_json = command_input_json(&request).expect("serialize command input");
+        let input: serde_json::Value =
+            serde_json::from_str(&input_json).expect("parse command input");
+
+        assert_eq!(input["tool_name"], "apply_patch");
+    }
+
+    #[test]
+    fn permission_decision_deny_blocks_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"do not run that"}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: true,
+                block_reason: Some("do not run that".to_string()),
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Feedback,
+                text: "do not run that".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn permission_decision_allow_can_update_input() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"echo rewritten"}}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: false,
+                block_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                updated_input: Some(serde_json::json!({ "command": "echo rewritten" })),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, vec![]);
+    }
+
+    #[test]
+    fn last_completed_updated_input_wins() {
+        let mut later_configured = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"echo configured later"}}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+        later_configured.completion_order = 0;
+        let mut earlier_configured = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","updatedInput":{"command":"echo finished later"}}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+        earlier_configured.completion_order = 1;
+
+        assert_eq!(
+            latest_updated_input(&[later_configured, earlier_configured]),
+            Some(serde_json::json!({ "command": "echo finished later" }))
+        );
+    }
+
+    #[test]
+    fn permission_decision_allow_without_updated_input_fails_open() {
+        let stdout = r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"preserved"}}"#;
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), stdout, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: false,
+                block_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "PreToolUse hook returned unsupported permissionDecision:allow".to_string(),
+            }]
+        );
+
+        let async_handler = handler_with_async(/*async*/ true);
+        let parsed = parse_completed(
+            &async_handler,
+            run_result(Some(0), stdout, ""),
+            Some("turn-1".to_string()),
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "preserved".to_string(),
+            }],
+        );
+    }
+
+    #[test]
+    fn deprecated_block_decision_blocks_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"do not run that"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: true,
+                block_reason: Some("do not run that".to_string()),
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Feedback,
+                text: "do not run that".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn deprecated_block_decision_with_additional_context_blocks_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"do not run that","hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"remember this"}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: true,
+                block_reason: Some("do not run that".to_string()),
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "remember this".to_string(),
+                    limit: Default::default(),
+                }],
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Context,
+                    text: "remember this".to_string(),
+                },
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Feedback,
+                    text: "do not run that".to_string(),
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn unsupported_permission_decision_fails_open() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"please confirm"}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: false,
+                block_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "PreToolUse hook returned unsupported permissionDecision:ask".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn deprecated_approve_decision_fails_open() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), r#"{"decision":"approve"}"#, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: false,
+                block_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "PreToolUse hook returned unsupported decision:approve".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn additional_context_is_recorded() {
+        let mut handler = handler();
+        handler.additional_context_limit = AdditionalContextLimit::from_config(Some(13));
+        let parsed = parse_completed(
+            &handler,
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"do not run that","additionalContext":"nope"}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: true,
+                block_reason: Some("do not run that".to_string()),
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "nope".to_string(),
+                    limit: AdditionalContextLimit::from_config(Some(13)),
+                }],
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Context,
+                    text: "nope".to_string(),
+                },
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Feedback,
+                    text: "do not run that".to_string(),
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn plain_stdout_is_ignored() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "hook ran successfully\n", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: false,
+                block_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, vec![]);
+    }
+
+    #[test]
+    fn invalid_json_like_stdout_fails_instead_of_becoming_noop() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "{\"decision\":\n", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: false,
+                block_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "hook returned invalid pre-tool-use JSON output".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn exit_code_two_blocks_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(2), "", "blocked by policy\n"),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PreToolUseHandlerData {
+                should_block: true,
+                block_reason: Some("blocked by policy".to_string()),
+                additional_contexts_for_model: Vec::new(),
+                updated_input: None,
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Feedback,
+                text: "blocked by policy".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn preview_and_completed_run_ids_include_tool_use_id() {
+        let request = request_for_tool_use("tool-call-123");
+        let runs = preview(&[handler()], &request);
+
+        assert_eq!(runs.len(), 1);
+        assert_eq!(
+            runs[0].id,
+            format!(
+                "pre-tool-use:0:{}:tool-call-123",
+                test_path_buf("/tmp/hooks.json").display()
+            )
+        );
+
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "", ""),
+            Some("turn-1".to_string()),
+        );
+        let completed = common::hook_completed_for_tool_use(parsed.completed, &request.tool_use_id);
+
+        assert_eq!(completed.run.id, runs[0].id);
+    }
+
+    #[test]
+    fn serialization_failure_run_ids_include_tool_use_id() {
+        let request = request_for_tool_use("tool-call-123");
+        let runs = preview(&[handler()], &request);
+
+        let completed = common::serialization_failure_hook_events_for_tool_use(
+            vec![handler()],
+            Some(request.turn_id.clone()),
+            "serialize failed".into(),
+            &request.tool_use_id,
+        );
+
+        assert_eq!(completed.len(), 1);
+        assert_eq!(completed[0].run.id, runs[0].id);
+    }
+
+    fn handler() -> ConfiguredHandler {
+        handler_with_async(/*async*/ false)
+    }
+
+    fn handler_with_async(r#async: bool) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name: HookEventName::PreToolUse,
+            matcher: Some("^Bash$".to_string()),
+            timeout_sec: 5,
+            status_message: None,
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: codex_protocol::protocol::HookSource::User,
+            display_order: 0,
+            kind: crate::engine::ConfiguredHandlerKind::Command {
+                command: "echo hook".to_string(),
+                r#async,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+        HandlerRunResult {
+            started_at: 1,
+            completed_at: 2,
+            duration_ms: 1,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+
+    fn request_for_tool_use(tool_use_id: &str) -> super::PreToolUseRequest {
+        super::PreToolUseRequest {
+            session_id: ThreadId::new(),
+            turn_id: "turn-1".to_string(),
+            subagent: None,
+            cwd: test_path_buf("/tmp").abs(),
+            transcript_path: None,
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            matcher_aliases: Vec::new(),
+            tool_use_id: tool_use_id.to_string(),
+            tool_input: serde_json::json!({ "command": "echo hello" }),
+        }
+    }
+}
diff --git a/codex-rs/hooks/src/events/session_end.rs b/codex-rs/hooks/src/events/session_end.rs
new file mode 100644
index 0000000000000000000000000000000000000000..708d0e53d98a5743b76d284a4de261ed320de3e3
--- /dev/null
+++ b/codex-rs/hooks/src/events/session_end.rs
@@ -0,0 +1,139 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::schema::NullableString;
+use crate::schema::SessionEndCommandInput;
+
+pub(crate) const SESSION_END_DEFAULT_TIMEOUT_SEC: u64 = 1;
+/// Keep below app-server's in-process `SHUTDOWN_TIMEOUT`: SessionEnd runs during
+/// teardown and must leave headroom within the existing five-second bound.
+pub(crate) const SESSION_END_MAX_TIMEOUT_SEC: u64 = 3;
+const SESSION_END_REASON: &str = "other";
+
+#[derive(Debug, Clone)]
+pub struct SessionEndRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+}
+
+#[derive(Debug, Default)]
+pub struct SessionEndOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+}
+
+pub(crate) fn preview(handlers: &[ConfiguredHandler]) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        HookEventName::SessionEnd,
+        Some(SESSION_END_REASON),
+    )
+    .into_iter()
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run(
+    engine: &ClaudeHooksEngine,
+    request: SessionEndRequest,
+) -> SessionEndOutcome {
+    let matched = dispatcher::select_handlers(
+        &engine.handlers,
+        HookEventName::SessionEnd,
+        Some(SESSION_END_REASON),
+    );
+    if matched.is_empty() {
+        return SessionEndOutcome::default();
+    }
+
+    let input_json = match serde_json::to_string(&SessionEndCommandInput {
+        session_id: request.session_id.to_string(),
+        transcript_path: NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "SessionEnd".to_string(),
+        reason: SESSION_END_REASON.to_string(),
+    }) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            return SessionEndOutcome {
+                hook_events: common::serialization_failure_hook_events(
+                    matched,
+                    Some(request.turn_id.clone()),
+                    format!("failed to serialize session end hook input: {error}"),
+                ),
+            };
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id),
+        parse_completed,
+    )
+    .await;
+    SessionEndOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+    }
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<()> {
+    let (status, entries) = match (run_result.error.as_deref(), run_result.exit_code) {
+        (Some(error), _) => (
+            HookRunStatus::Failed,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            }],
+        ),
+        (None, Some(0)) => (HookRunStatus::Completed, Vec::new()),
+        (None, Some(code)) => (
+            HookRunStatus::Failed,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: common::trimmed_non_empty(&run_result.stderr)
+                    .unwrap_or_else(|| format!("hook exited with code {code}")),
+            }],
+        ),
+        (None, None) => (
+            HookRunStatus::Failed,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "hook process terminated without an exit code".to_string(),
+            }],
+        ),
+    };
+
+    dispatcher::ParsedHandler {
+        completed: HookCompletedEvent {
+            turn_id,
+            run: dispatcher::completed_summary(handler, &run_result, status, entries),
+        },
+        data: (),
+        completion_order: 0,
+    }
+}
+
+#[cfg(test)]
+#[path = "session_end_tests.rs"]
+mod tests;
diff --git a/codex-rs/hooks/src/events/session_end_tests.rs b/codex-rs/hooks/src/events/session_end_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0c100ee4a4c6fcec5f5ca158a13f7fa66247f69e
--- /dev/null
+++ b/codex-rs/hooks/src/events/session_end_tests.rs
@@ -0,0 +1,78 @@
+use std::collections::HashMap;
+
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookSource;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+
+use super::parse_completed;
+use super::preview;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+
+#[test]
+fn session_end_matches_other_reason() {
+    let selected = preview(&[
+        ConfiguredHandler {
+            display_order: 0,
+            ..handler(Some("clear"))
+        },
+        ConfiguredHandler {
+            display_order: 1,
+            ..handler(Some("other"))
+        },
+        ConfiguredHandler {
+            display_order: 2,
+            ..handler(/*matcher*/ None)
+        },
+    ]);
+
+    assert_eq!(
+        selected
+            .iter()
+            .map(|run| run.display_order)
+            .collect::<Vec<_>>(),
+        vec![1, 2]
+    );
+}
+
+#[test]
+fn session_end_ignores_successful_output() {
+    let completed = parse_completed(
+        &handler(/*matcher*/ None),
+        HandlerRunResult {
+            started_at: 1,
+            completed_at: 2,
+            duration_ms: 1,
+            exit_code: Some(0),
+            stdout: r#"{"continue":false,"decision":"block","reason":"ignored"}"#.to_string(),
+            stderr: String::new(),
+            error: None,
+        },
+        /*turn_id*/ None,
+    );
+
+    assert_eq!(completed.completed.run.status, HookRunStatus::Completed);
+    assert_eq!(completed.completed.run.entries, Vec::new());
+}
+
+fn handler(matcher: Option<&str>) -> ConfiguredHandler {
+    ConfiguredHandler {
+        builtin: false,
+        event_name: HookEventName::SessionEnd,
+        matcher: matcher.map(str::to_string),
+        timeout_sec: 2,
+        status_message: None,
+        additional_context_limit: Default::default(),
+        source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+        source: HookSource::User,
+        display_order: 0,
+        kind: crate::engine::ConfiguredHandlerKind::Command {
+            command: "echo hook".to_string(),
+            r#async: false,
+            env: HashMap::new(),
+        },
+    }
+}
diff --git a/codex-rs/hooks/src/events/session_start.rs b/codex-rs/hooks/src/events/session_start.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3aff0fe946eb64a0fc042522c5f60e465fef0d7c
--- /dev/null
+++ b/codex-rs/hooks/src/events/session_start.rs
@@ -0,0 +1,573 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::output_spill::AdditionalContext;
+use crate::schema::NullableString;
+use crate::schema::SessionStartCommandInput;
+use crate::schema::SubagentStartCommandInput;
+
+#[derive(Debug, Clone, Copy)]
+pub enum SessionStartSource {
+    Startup,
+    Resume,
+    Clear,
+    Compact,
+    Fork,
+}
+
+impl SessionStartSource {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Startup => "startup",
+            Self::Resume => "resume",
+            Self::Clear => "clear",
+            Self::Compact => "compact",
+            Self::Fork => "fork",
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct SessionStartRequest {
+    pub session_id: ThreadId,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub target: StartHookTarget,
+}
+
+#[derive(Debug, Clone)]
+pub enum StartHookTarget {
+    SessionStart {
+        source: SessionStartSource,
+    },
+    SubagentStart {
+        turn_id: String,
+        agent_id: String,
+        agent_type: String,
+    },
+}
+
+impl StartHookTarget {
+    fn event_name(&self) -> HookEventName {
+        match self {
+            Self::SessionStart { .. } => HookEventName::SessionStart,
+            Self::SubagentStart { .. } => HookEventName::SubagentStart,
+        }
+    }
+
+    fn matcher_input(&self) -> &str {
+        match self {
+            Self::SessionStart { source } => source.as_str(),
+            Self::SubagentStart { agent_type, .. } => agent_type.as_str(),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct SessionStartOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_stop: bool,
+    pub stop_reason: Option<String>,
+    pub additional_contexts: Vec<String>,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+struct SessionStartHandlerData {
+    should_stop: bool,
+    stop_reason: Option<String>,
+    additional_contexts_for_model: Vec<AdditionalContext>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    request: &SessionStartRequest,
+) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        request.target.event_name(),
+        Some(request.target.matcher_input()),
+    )
+    .into_iter()
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run(
+    engine: &ClaudeHooksEngine,
+    request: SessionStartRequest,
+    turn_id: Option<String>,
+) -> SessionStartOutcome {
+    let matched = dispatcher::select_handlers(
+        &engine.handlers,
+        request.target.event_name(),
+        Some(request.target.matcher_input()),
+    );
+    if matched.is_empty() {
+        return SessionStartOutcome {
+            hook_events: Vec::new(),
+            should_stop: false,
+            stop_reason: None,
+            additional_contexts: Vec::new(),
+        };
+    }
+
+    let (input_json, turn_id) = match request.target {
+        StartHookTarget::SessionStart { source } => {
+            let input_json = match serde_json::to_string(&SessionStartCommandInput::new(
+                request.session_id.to_string(),
+                request.transcript_path.clone(),
+                request.cwd.display().to_string(),
+                request.model.clone(),
+                request.permission_mode.clone(),
+                source.as_str().to_string(),
+            )) {
+                Ok(input_json) => input_json,
+                Err(error) => {
+                    return serialization_failure_outcome(
+                        common::serialization_failure_hook_events(
+                            matched,
+                            turn_id,
+                            format!("failed to serialize session start hook input: {error}"),
+                        ),
+                    );
+                }
+            };
+            (input_json, turn_id)
+        }
+        StartHookTarget::SubagentStart {
+            turn_id: subagent_turn_id,
+            agent_id,
+            agent_type,
+        } => {
+            let input = SubagentStartCommandInput {
+                session_id: request.session_id.to_string(),
+                turn_id: subagent_turn_id.clone(),
+                transcript_path: NullableString::from_path(request.transcript_path.clone()),
+                cwd: request.cwd.display().to_string(),
+                hook_event_name: "SubagentStart".to_string(),
+                model: request.model.clone(),
+                permission_mode: request.permission_mode.clone(),
+                agent_id,
+                agent_type,
+            };
+            let input_json = match serde_json::to_string(&input) {
+                Ok(input_json) => input_json,
+                Err(error) => {
+                    return serialization_failure_outcome(
+                        common::serialization_failure_hook_events(
+                            matched,
+                            Some(subagent_turn_id),
+                            format!("failed to serialize subagent start hook input: {error}"),
+                        ),
+                    );
+                }
+            };
+            (input_json, Some(subagent_turn_id))
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        turn_id,
+        parse_completed,
+    )
+    .await;
+
+    let should_stop = results.iter().any(|result| result.data.should_stop);
+    let stop_reason = results
+        .iter()
+        .find_map(|result| result.data.stop_reason.clone());
+    let additional_contexts = common::flatten_additional_contexts(
+        results
+            .iter()
+            .map(|result| result.data.additional_contexts_for_model.as_slice()),
+    );
+    let additional_contexts = engine
+        .command_runtime
+        .output_spiller()
+        .maybe_spill_additional_contexts(additional_contexts)
+        .await;
+
+    SessionStartOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+        should_stop,
+        stop_reason,
+        additional_contexts,
+    }
+}
+
+/// Interprets completed `SessionStart` and `SubagentStart` hook runs.
+///
+/// The two events have different input payloads but share most output
+/// handling: hook JSON can emit warnings/context, invalid JSON-looking stdout
+/// fails, and plain stdout becomes model context. Only `SessionStart` honors
+/// `continue:false`; `SubagentStart` stays context-injection-only.
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<SessionStartHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_stop = false;
+    let mut stop_reason = None;
+    let mut additional_contexts_for_model = Vec::new();
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = match handler.event_name {
+                    HookEventName::SessionStart => {
+                        output_parser::parse_session_start(&run_result.stdout)
+                    }
+                    HookEventName::SubagentStart => {
+                        output_parser::parse_subagent_start(&run_result.stdout)
+                    }
+                    event_name => {
+                        panic!("expected start hook event, got {event_name:?}")
+                    }
+                } {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    if let Some(additional_context) = parsed.additional_context {
+                        common::append_additional_context(
+                            &mut entries,
+                            &mut additional_contexts_for_model,
+                            handler,
+                            additional_context,
+                        );
+                    }
+                    let _ = parsed.universal.suppress_output;
+                    if handler.can_apply_control_effects()
+                        && handler.event_name == HookEventName::SessionStart
+                        && !parsed.universal.continue_processing
+                    {
+                        status = HookRunStatus::Stopped;
+                        should_stop = true;
+                        stop_reason = parsed.universal.stop_reason.clone();
+                        if let Some(stop_reason_text) = parsed.universal.stop_reason {
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Stop,
+                                text: stop_reason_text,
+                            });
+                        }
+                    }
+                } else if output_parser::looks_like_json(&run_result.stdout) {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: match handler.event_name {
+                            HookEventName::SessionStart => {
+                                "hook returned invalid session start JSON output"
+                            }
+                            HookEventName::SubagentStart => {
+                                "hook returned invalid subagent start JSON output"
+                            }
+                            event_name => {
+                                panic!("expected start hook event, got {event_name:?}")
+                            }
+                        }
+                        .to_string(),
+                    });
+                } else {
+                    let additional_context = trimmed_stdout.to_string();
+                    common::append_additional_context(
+                        &mut entries,
+                        &mut additional_contexts_for_model,
+                        handler,
+                        additional_context,
+                    );
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: SessionStartHandlerData {
+            should_stop,
+            stop_reason,
+            additional_contexts_for_model,
+        },
+        completion_order: 0,
+    }
+}
+
+fn serialization_failure_outcome(hook_events: Vec<HookCompletedEvent>) -> SessionStartOutcome {
+    SessionStartOutcome {
+        hook_events,
+        should_stop: false,
+        stop_reason: None,
+        additional_contexts: Vec::new(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::SessionStartHandlerData;
+    use super::parse_completed;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::HandlerRunResult;
+    use crate::output_spill::AdditionalContext;
+    use crate::output_spill::AdditionalContextLimit;
+
+    #[test]
+    fn plain_stdout_becomes_model_context() {
+        let mut handler = handler();
+        handler.additional_context_limit = AdditionalContextLimit::from_config(Some(7));
+        let parsed = parse_completed(
+            &handler,
+            run_result(Some(0), "hello from hook\n", ""),
+            /*turn_id*/ None,
+        );
+
+        assert_eq!(
+            parsed.data,
+            SessionStartHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "hello from hook".to_string(),
+                    limit: AdditionalContextLimit::from_config(Some(7)),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "hello from hook".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn continue_false_preserves_context_for_later_turns() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"pause","hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"do not inject"}}"#,
+                "",
+            ),
+            /*turn_id*/ None,
+        );
+
+        assert_eq!(
+            parsed.data,
+            SessionStartHandlerData {
+                should_stop: true,
+                stop_reason: Some("pause".to_string()),
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "do not inject".to_string(),
+                    limit: Default::default(),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Context,
+                    text: "do not inject".to_string(),
+                },
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Stop,
+                    text: "pause".to_string(),
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn invalid_json_like_stdout_fails_instead_of_becoming_model_context() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"SessionStart""#,
+                "",
+            ),
+            /*turn_id*/ None,
+        );
+
+        assert_eq!(
+            parsed.data,
+            SessionStartHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "hook returned invalid session start JSON output".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn subagent_start_plain_stdout_becomes_model_context() {
+        let mut handler = handler_for(HookEventName::SubagentStart);
+        handler.additional_context_limit = AdditionalContextLimit::from_config(Some(4_096));
+        let parsed = parse_completed(
+            &handler,
+            run_result(Some(0), "hello from subagent hook\n", ""),
+            /*turn_id*/ Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            SessionStartHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "hello from subagent hook".to_string(),
+                    limit: AdditionalContextLimit::from_config(Some(4_096)),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.turn_id.as_deref(), Some("turn-1"));
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "hello from subagent hook".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn subagent_start_continue_false_is_ignored() {
+        let parsed = parse_completed(
+            &handler_for(HookEventName::SubagentStart),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"skip child","hookSpecificOutput":{"hookEventName":"SubagentStart","additionalContext":"child context"}}"#,
+                "",
+            ),
+            /*turn_id*/ Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            SessionStartHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "child context".to_string(),
+                    limit: Default::default(),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.turn_id.as_deref(), Some("turn-1"));
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "child context".to_string(),
+            }]
+        );
+    }
+
+    fn handler() -> ConfiguredHandler {
+        handler_for(HookEventName::SessionStart)
+    }
+
+    fn handler_for(event_name: HookEventName) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name,
+            matcher: None,
+            timeout_sec: 600,
+            status_message: None,
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: codex_protocol::protocol::HookSource::User,
+            display_order: 0,
+            kind: crate::engine::ConfiguredHandlerKind::Command {
+                command: "echo hook".to_string(),
+                r#async: false,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+        HandlerRunResult {
+            started_at: 1,
+            completed_at: 2,
+            duration_ms: 1,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+}
diff --git a/codex-rs/hooks/src/events/stop.rs b/codex-rs/hooks/src/events/stop.rs
new file mode 100644
index 0000000000000000000000000000000000000000..be2be9100e356427b298f24872113852eab3862a
--- /dev/null
+++ b/codex-rs/hooks/src/events/stop.rs
@@ -0,0 +1,723 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::items::HookPromptFragment;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_protocol::protocol::HookSource;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde_json::Map;
+use serde_json::Value;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::HandlerSourcePath;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::schema::NullableString;
+use crate::schema::StopCommandInput;
+use crate::schema::SubagentStopCommandInput;
+
+#[derive(Debug, Clone)]
+pub struct StopRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub request_metadata: Option<Map<String, Value>>,
+    pub stop_hook_active: bool,
+    pub last_assistant_message: Option<String>,
+    pub target: StopHookTarget,
+}
+
+#[derive(Debug, Clone)]
+pub enum StopHookTarget {
+    Stop,
+    /// Internal memory work runs policy and executor hooks, not project completion checks.
+    MemoryConsolidation,
+    SubagentStop {
+        agent_id: String,
+        agent_type: String,
+        agent_transcript_path: Option<PathBuf>,
+    },
+}
+
+impl StopHookTarget {
+    fn event_name(&self) -> HookEventName {
+        match self {
+            Self::Stop | Self::MemoryConsolidation => HookEventName::Stop,
+            Self::SubagentStop { .. } => HookEventName::SubagentStop,
+        }
+    }
+
+    fn matcher_input(&self) -> Option<&str> {
+        match self {
+            Self::Stop | Self::MemoryConsolidation => None,
+            Self::SubagentStop { agent_type, .. } => Some(agent_type.as_str()),
+        }
+    }
+
+    fn select_handlers(&self, handlers: &[ConfiguredHandler]) -> Vec<ConfiguredHandler> {
+        dispatcher::select_handlers(handlers, self.event_name(), self.matcher_input())
+            .into_iter()
+            .filter(|handler| {
+                !matches!(self, Self::MemoryConsolidation)
+                    || matches!(
+                        handler.source_path,
+                        HandlerSourcePath::ExecutorScoped { .. }
+                    )
+                    || match handler.source {
+                        HookSource::User
+                        | HookSource::Project
+                        | HookSource::SessionFlags
+                        | HookSource::Plugin => false,
+                        HookSource::System
+                        | HookSource::Mdm
+                        | HookSource::CloudRequirements
+                        | HookSource::CloudManagedConfig
+                        | HookSource::LegacyManagedConfigFile
+                        | HookSource::LegacyManagedConfigMdm
+                        // Required hooks can have unknown attribution; retain them fail-closed.
+                        | HookSource::Unknown => true,
+                    }
+            })
+            .collect()
+    }
+}
+
+#[derive(Debug, Default)]
+pub struct StopOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_stop: bool,
+    pub stop_reason: Option<String>,
+    pub should_block: bool,
+    pub block_reason: Option<String>,
+    pub continuation_fragments: Vec<HookPromptFragment>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct StopHandlerData {
+    should_stop: bool,
+    stop_reason: Option<String>,
+    should_block: bool,
+    block_reason: Option<String>,
+    continuation_fragments: Vec<HookPromptFragment>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    request: &StopRequest,
+) -> Vec<HookRunSummary> {
+    request
+        .target
+        .select_handlers(handlers)
+        .into_iter()
+        .filter(|handler| matches!(handler.source_path, HandlerSourcePath::Local(_)))
+        .map(|handler| dispatcher::running_summary(&handler))
+        .collect()
+}
+
+pub(crate) async fn run(engine: &ClaudeHooksEngine, request: StopRequest) -> StopOutcome {
+    let matched = request.target.select_handlers(&engine.handlers);
+    if matched.is_empty() {
+        return StopOutcome {
+            hook_events: Vec::new(),
+            should_stop: false,
+            stop_reason: None,
+            should_block: false,
+            block_reason: None,
+            continuation_fragments: Vec::new(),
+        };
+    }
+
+    // Memory workers terminate on managed rejection rather than continuing the turn,
+    // so their executor cleanup must also run when a managed hook blocks completion.
+    let (executor_cleanup, matched): (Vec<_>, Vec<_>) = matched.into_iter().partition(|handler| {
+        matches!(request.target, StopHookTarget::MemoryConsolidation)
+            && matches!(
+                handler.source_path,
+                HandlerSourcePath::ExecutorScoped { .. }
+            )
+    });
+    let input_json = match request.target {
+        StopHookTarget::Stop | StopHookTarget::MemoryConsolidation => {
+            let input = StopCommandInput {
+                session_id: request.session_id.to_string(),
+                turn_id: request.turn_id.clone(),
+                transcript_path: NullableString::from_path(request.transcript_path.clone()),
+                cwd: request.cwd.display().to_string(),
+                hook_event_name: "Stop".to_string(),
+                model: request.model.clone(),
+                permission_mode: request.permission_mode.clone(),
+                stop_hook_active: request.stop_hook_active,
+                last_assistant_message: NullableString::from_string(
+                    request.last_assistant_message.clone(),
+                ),
+            };
+            match serde_json::to_string(&input) {
+                Ok(input_json) => input_json,
+                Err(error) => {
+                    return serialization_failure_outcome(
+                        common::serialization_failure_hook_events(
+                            matched,
+                            Some(request.turn_id),
+                            format!("failed to serialize stop hook input: {error}"),
+                        ),
+                    );
+                }
+            }
+        }
+        StopHookTarget::SubagentStop {
+            agent_id,
+            agent_type,
+            agent_transcript_path,
+        } => {
+            let input = SubagentStopCommandInput {
+                session_id: request.session_id.to_string(),
+                turn_id: request.turn_id.clone(),
+                transcript_path: NullableString::from_path(request.transcript_path.clone()),
+                agent_transcript_path: NullableString::from_path(agent_transcript_path),
+                cwd: request.cwd.display().to_string(),
+                hook_event_name: "SubagentStop".to_string(),
+                model: request.model.clone(),
+                permission_mode: request.permission_mode.clone(),
+                stop_hook_active: request.stop_hook_active,
+                agent_id,
+                agent_type,
+                last_assistant_message: NullableString::from_string(
+                    request.last_assistant_message.clone(),
+                ),
+            };
+            match serde_json::to_string(&input) {
+                Ok(input_json) => input_json,
+                Err(error) => {
+                    return serialization_failure_outcome(
+                        common::serialization_failure_hook_events(
+                            matched,
+                            Some(request.turn_id),
+                            format!("failed to serialize subagent stop hook input: {error}"),
+                        ),
+                    );
+                }
+            }
+        }
+    };
+
+    let results = dispatcher::execute_handlers_with_metadata(
+        engine,
+        matched,
+        input_json.clone(),
+        request.cwd.as_path(),
+        Some(request.turn_id.clone()),
+        request.request_metadata.as_ref(),
+        parse_completed,
+    )
+    .await;
+
+    if !executor_cleanup.is_empty() {
+        dispatcher::execute_handlers_with_metadata(
+            engine,
+            executor_cleanup,
+            input_json,
+            request.cwd.as_path(),
+            Some(request.turn_id),
+            request.request_metadata.as_ref(),
+            parse_completed,
+        )
+        .await;
+    }
+
+    let aggregate = aggregate_results(results.iter().map(|result| &result.data));
+
+    StopOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+        should_stop: aggregate.should_stop,
+        stop_reason: aggregate.stop_reason,
+        should_block: aggregate.should_block,
+        block_reason: aggregate.block_reason,
+        continuation_fragments: aggregate.continuation_fragments,
+    }
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<StopHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_stop = false;
+    let mut stop_reason = None;
+    let mut should_block = false;
+    let mut block_reason = None;
+    let mut continuation_prompt = None;
+    let hook_event_name = match handler.event_name {
+        HookEventName::Stop | HookEventName::SubagentStop => handler.event_name,
+        event_name => {
+            panic!("expected stop hook event, got {event_name:?}");
+        }
+    };
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = match hook_event_name {
+                    HookEventName::Stop => output_parser::parse_stop(&run_result.stdout),
+                    HookEventName::SubagentStop => {
+                        output_parser::parse_subagent_stop(&run_result.stdout)
+                    }
+                    _ => unreachable!("validated stop hook event"),
+                } {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    let _ = parsed.universal.suppress_output;
+                    if handler.can_apply_control_effects() {
+                        if !parsed.universal.continue_processing {
+                            status = HookRunStatus::Stopped;
+                            should_stop = true;
+                            stop_reason = parsed.universal.stop_reason.clone();
+                            if let Some(stop_reason_text) = parsed.universal.stop_reason {
+                                entries.push(HookOutputEntry {
+                                    kind: HookOutputEntryKind::Stop,
+                                    text: stop_reason_text,
+                                });
+                            }
+                        } else if let Some(invalid_block_reason) = parsed.invalid_block_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_block_reason,
+                            });
+                        } else if parsed.should_block
+                            && let Some(reason) =
+                                parsed.reason.as_deref().and_then(common::trimmed_non_empty)
+                        {
+                            status = HookRunStatus::Blocked;
+                            should_block = true;
+                            block_reason = Some(reason.clone());
+                            continuation_prompt = Some(reason.clone());
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Feedback,
+                                text: reason,
+                            });
+                        }
+                    }
+                } else if handler.can_apply_control_effects()
+                    || output_parser::looks_like_json(&run_result.stdout)
+                {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: match hook_event_name {
+                            HookEventName::Stop => "hook returned invalid stop hook JSON output",
+                            HookEventName::SubagentStop => {
+                                "hook returned invalid subagent stop hook JSON output"
+                            }
+                            _ => unreachable!("validated stop hook event"),
+                        }
+                        .to_string(),
+                    });
+                }
+            }
+            Some(2) if handler.can_apply_control_effects() => {
+                if let Some(reason) = common::trimmed_non_empty(&run_result.stderr) {
+                    status = HookRunStatus::Blocked;
+                    should_block = true;
+                    block_reason = Some(reason.clone());
+                    continuation_prompt = Some(reason.clone());
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Feedback,
+                        text: reason,
+                    });
+                } else {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: match hook_event_name {
+                            HookEventName::Stop => {
+                                "Stop hook exited with code 2 but did not write a continuation prompt to stderr"
+                            }
+                            HookEventName::SubagentStop => {
+                                "SubagentStop hook exited with code 2 but did not write a continuation prompt to stderr"
+                            }
+                            _ => unreachable!("validated stop hook event"),
+                        }
+                        .to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+    let continuation_fragments = continuation_prompt
+        .map(|prompt| {
+            vec![HookPromptFragment::from_single_hook(
+                prompt,
+                completed.run.id.clone(),
+            )]
+        })
+        .unwrap_or_default();
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: StopHandlerData {
+            should_stop,
+            stop_reason,
+            should_block,
+            block_reason,
+            continuation_fragments,
+        },
+        completion_order: 0,
+    }
+}
+
+fn aggregate_results<'a>(
+    results: impl IntoIterator<Item = &'a StopHandlerData>,
+) -> StopHandlerData {
+    let results = results.into_iter().collect::<Vec<_>>();
+    let should_stop = results.iter().any(|result| result.should_stop);
+    let stop_reason = results.iter().find_map(|result| result.stop_reason.clone());
+    let should_block = !should_stop && results.iter().any(|result| result.should_block);
+    let block_reason = if should_block {
+        common::join_text_chunks(
+            results
+                .iter()
+                .filter_map(|result| result.block_reason.clone())
+                .collect(),
+        )
+    } else {
+        None
+    };
+    let continuation_fragments = if should_block {
+        results
+            .iter()
+            .filter(|result| result.should_block)
+            .flat_map(|result| result.continuation_fragments.clone())
+            .collect()
+    } else {
+        Vec::new()
+    };
+
+    StopHandlerData {
+        should_stop,
+        stop_reason,
+        should_block,
+        block_reason,
+        continuation_fragments,
+    }
+}
+
+fn serialization_failure_outcome(hook_events: Vec<HookCompletedEvent>) -> StopOutcome {
+    StopOutcome {
+        hook_events,
+        should_stop: false,
+        stop_reason: None,
+        should_block: false,
+        block_reason: None,
+        continuation_fragments: Vec::new(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use codex_protocol::items::HookPromptFragment;
+
+    use super::StopHandlerData;
+    use super::aggregate_results;
+    use super::parse_completed;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::HandlerRunResult;
+
+    #[test]
+    fn block_decision_with_reason_sets_continuation_prompt() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"retry with tests"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            StopHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                should_block: true,
+                block_reason: Some("retry with tests".to_string()),
+                continuation_fragments: vec![HookPromptFragment {
+                    text: "retry with tests".to_string(),
+                    hook_run_id: parsed.completed.run.id.clone(),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+    }
+
+    #[test]
+    fn block_decision_without_reason_is_invalid() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), r#"{"decision":"block"}"#, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.data, StopHandlerData::default());
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "Stop hook returned decision:block without a non-empty reason".to_string(),
+            }]
+        );
+
+        let async_handler = handler_with_async(/*async*/ true);
+        let parsed = parse_completed(
+            &async_handler,
+            run_result(Some(0), r#"{"decision":"block"}"#, ""),
+            Some("turn-1".to_string()),
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, Vec::new());
+    }
+
+    #[test]
+    fn continue_false_overrides_block_decision() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"done","decision":"block","reason":"keep going"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            StopHandlerData {
+                should_stop: true,
+                stop_reason: Some("done".to_string()),
+                should_block: false,
+                block_reason: None,
+                continuation_fragments: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+    }
+
+    #[test]
+    fn exit_code_two_uses_stderr_feedback_only() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(2), "ignored stdout", "retry with tests"),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            StopHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                should_block: true,
+                block_reason: Some("retry with tests".to_string()),
+                continuation_fragments: vec![HookPromptFragment {
+                    text: "retry with tests".to_string(),
+                    hook_run_id: parsed.completed.run.id.clone(),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+    }
+
+    #[test]
+    fn exit_code_two_without_stderr_does_not_block() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(2), "", "   "),
+            /*turn_id*/ None,
+        );
+
+        assert_eq!(parsed.data, StopHandlerData::default());
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text:
+                    "Stop hook exited with code 2 but did not write a continuation prompt to stderr"
+                        .to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn block_decision_with_blank_reason_fails_instead_of_blocking() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "{\"decision\":\"block\",\"reason\":\"   \"}", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.data, StopHandlerData::default());
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "Stop hook returned decision:block without a non-empty reason".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn invalid_stdout_fails_instead_of_silently_nooping() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "not json", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(parsed.data, StopHandlerData::default());
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "hook returned invalid stop hook JSON output".to_string(),
+            }]
+        );
+
+        let async_handler = handler_with_async(/*async*/ true);
+        let parsed = parse_completed(
+            &async_handler,
+            run_result(Some(0), "not json", ""),
+            Some("turn-1".to_string()),
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, Vec::new());
+    }
+
+    #[test]
+    fn aggregate_results_concatenates_blocking_reasons_in_declaration_order() {
+        let aggregate = aggregate_results([
+            &StopHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                should_block: true,
+                block_reason: Some("first".to_string()),
+                continuation_fragments: vec![HookPromptFragment::from_single_hook(
+                    "first", "run-1",
+                )],
+            },
+            &StopHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                should_block: true,
+                block_reason: Some("second".to_string()),
+                continuation_fragments: vec![HookPromptFragment::from_single_hook(
+                    "second", "run-2",
+                )],
+            },
+        ]);
+
+        assert_eq!(
+            aggregate,
+            StopHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                should_block: true,
+                block_reason: Some("first\n\nsecond".to_string()),
+                continuation_fragments: vec![
+                    HookPromptFragment::from_single_hook("first", "run-1"),
+                    HookPromptFragment::from_single_hook("second", "run-2"),
+                ],
+            }
+        );
+    }
+
+    fn handler() -> ConfiguredHandler {
+        handler_with_async(/*async*/ false)
+    }
+
+    fn handler_with_async(r#async: bool) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name: HookEventName::Stop,
+            matcher: None,
+            timeout_sec: 600,
+            status_message: None,
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: codex_protocol::protocol::HookSource::User,
+            display_order: 0,
+            kind: crate::engine::ConfiguredHandlerKind::Command {
+                command: "echo hook".to_string(),
+                r#async,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+        HandlerRunResult {
+            started_at: 1,
+            completed_at: 2,
+            duration_ms: 1,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+}
diff --git a/codex-rs/hooks/src/events/user_prompt_submit.rs b/codex-rs/hooks/src/events/user_prompt_submit.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9124431bc194284ef4a009c76008851a984ff319
--- /dev/null
+++ b/codex-rs/hooks/src/events/user_prompt_submit.rs
@@ -0,0 +1,492 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use super::common;
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::ConfiguredHandler;
+use crate::engine::HandlerRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::output_spill::AdditionalContext;
+use crate::schema::NullableString;
+use crate::schema::SubagentCommandInputFields;
+use crate::schema::UserPromptSubmitCommandInput;
+
+#[derive(Debug, Clone)]
+pub struct UserPromptSubmitRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub subagent: Option<common::SubagentHookContext>,
+    pub cwd: AbsolutePathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub prompt: String,
+}
+
+#[derive(Debug)]
+pub struct UserPromptSubmitOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_stop: bool,
+    pub stop_reason: Option<String>,
+    pub additional_contexts: Vec<String>,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+struct UserPromptSubmitHandlerData {
+    should_stop: bool,
+    stop_reason: Option<String>,
+    additional_contexts_for_model: Vec<AdditionalContext>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    _request: &UserPromptSubmitRequest,
+) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        HookEventName::UserPromptSubmit,
+        /*matcher_input*/ None,
+    )
+    .into_iter()
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run(
+    engine: &ClaudeHooksEngine,
+    request: UserPromptSubmitRequest,
+) -> UserPromptSubmitOutcome {
+    let matched = dispatcher::select_handlers(
+        &engine.handlers,
+        HookEventName::UserPromptSubmit,
+        /*matcher_input*/ None,
+    );
+    if matched.is_empty() {
+        return UserPromptSubmitOutcome {
+            hook_events: Vec::new(),
+            should_stop: false,
+            stop_reason: None,
+            additional_contexts: Vec::new(),
+        };
+    }
+
+    let subagent = SubagentCommandInputFields::from(request.subagent.as_ref());
+    let input_json = match serde_json::to_string(&UserPromptSubmitCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        agent_id: subagent.agent_id,
+        agent_type: subagent.agent_type,
+        transcript_path: NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "UserPromptSubmit".to_string(),
+        model: request.model.clone(),
+        permission_mode: request.permission_mode.clone(),
+        prompt: request.prompt.clone(),
+    }) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            return serialization_failure_outcome(common::serialization_failure_hook_events(
+                matched,
+                Some(request.turn_id),
+                format!("failed to serialize user prompt submit hook input: {error}"),
+            ));
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        engine,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id),
+        parse_completed,
+    )
+    .await;
+
+    let should_stop = results.iter().any(|result| result.data.should_stop);
+    let stop_reason = results
+        .iter()
+        .find_map(|result| result.data.stop_reason.clone());
+    let additional_contexts = common::flatten_additional_contexts(
+        results
+            .iter()
+            .map(|result| result.data.additional_contexts_for_model.as_slice()),
+    );
+    let additional_contexts = engine
+        .command_runtime
+        .output_spiller()
+        .maybe_spill_additional_contexts(additional_contexts)
+        .await;
+
+    UserPromptSubmitOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+        should_stop,
+        stop_reason,
+        additional_contexts,
+    }
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: HandlerRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<UserPromptSubmitHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_stop = false;
+    let mut stop_reason = None;
+    let mut additional_contexts_for_model = Vec::new();
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) =
+                    output_parser::parse_user_prompt_submit(&run_result.stdout)
+                {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    if (!handler.can_apply_control_effects()
+                        || parsed.invalid_block_reason.is_none())
+                        && let Some(additional_context) = parsed.additional_context
+                    {
+                        common::append_additional_context(
+                            &mut entries,
+                            &mut additional_contexts_for_model,
+                            handler,
+                            additional_context,
+                        );
+                    }
+                    let _ = parsed.universal.suppress_output;
+                    if handler.can_apply_control_effects() {
+                        if !parsed.universal.continue_processing {
+                            status = HookRunStatus::Stopped;
+                            should_stop = true;
+                            stop_reason = parsed.universal.stop_reason.clone();
+                            if let Some(stop_reason_text) = parsed.universal.stop_reason {
+                                entries.push(HookOutputEntry {
+                                    kind: HookOutputEntryKind::Stop,
+                                    text: stop_reason_text,
+                                });
+                            }
+                        } else if let Some(invalid_block_reason) = parsed.invalid_block_reason {
+                            status = HookRunStatus::Failed;
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Error,
+                                text: invalid_block_reason,
+                            });
+                        } else if parsed.should_block {
+                            status = HookRunStatus::Blocked;
+                            should_stop = true;
+                            stop_reason = parsed.reason.clone();
+                            if let Some(reason) = parsed.reason {
+                                entries.push(HookOutputEntry {
+                                    kind: HookOutputEntryKind::Feedback,
+                                    text: reason,
+                                });
+                            }
+                        }
+                    }
+                } else if output_parser::looks_like_json(&run_result.stdout) {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "hook returned invalid user prompt submit JSON output".to_string(),
+                    });
+                } else {
+                    let additional_context = trimmed_stdout.to_string();
+                    common::append_additional_context(
+                        &mut entries,
+                        &mut additional_contexts_for_model,
+                        handler,
+                        additional_context,
+                    );
+                }
+            }
+            Some(2) if handler.can_apply_control_effects() => {
+                if let Some(reason) = common::trimmed_non_empty(&run_result.stderr) {
+                    status = HookRunStatus::Blocked;
+                    should_stop = true;
+                    stop_reason = Some(reason.clone());
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Feedback,
+                        text: reason,
+                    });
+                } else {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "UserPromptSubmit hook exited with code 2 but did not write a blocking reason to stderr".to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: UserPromptSubmitHandlerData {
+            should_stop,
+            stop_reason,
+            additional_contexts_for_model,
+        },
+        completion_order: 0,
+    }
+}
+
+fn serialization_failure_outcome(hook_events: Vec<HookCompletedEvent>) -> UserPromptSubmitOutcome {
+    UserPromptSubmitOutcome {
+        hook_events,
+        should_stop: false,
+        stop_reason: None,
+        additional_contexts: Vec::new(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+
+    use super::UserPromptSubmitHandlerData;
+    use super::parse_completed;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::HandlerRunResult;
+    use crate::output_spill::AdditionalContext;
+
+    #[test]
+    fn continue_false_preserves_context_for_later_turns() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"pause","hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"do not inject"}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            UserPromptSubmitHandlerData {
+                should_stop: true,
+                stop_reason: Some("pause".to_string()),
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "do not inject".to_string(),
+                    limit: Default::default(),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Context,
+                    text: "do not inject".to_string(),
+                },
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Stop,
+                    text: "pause".to_string(),
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn claude_block_decision_blocks_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"slow down","hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"do not inject"}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            UserPromptSubmitHandlerData {
+                should_stop: true,
+                stop_reason: Some("slow down".to_string()),
+                additional_contexts_for_model: vec![AdditionalContext {
+                    text: "do not inject".to_string(),
+                    limit: Default::default(),
+                }],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Context,
+                    text: "do not inject".to_string(),
+                },
+                HookOutputEntry {
+                    kind: HookOutputEntryKind::Feedback,
+                    text: "slow down".to_string(),
+                },
+            ]
+        );
+    }
+
+    #[test]
+    fn claude_block_decision_requires_reason() {
+        let stdout = r#"{"decision":"block","hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"do not inject"}}"#;
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), stdout, ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            UserPromptSubmitHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "UserPromptSubmit hook returned decision:block without a non-empty reason"
+                    .to_string(),
+            }]
+        );
+
+        let async_handler = handler_with_async(/*async*/ true);
+        let parsed = parse_completed(
+            &async_handler,
+            run_result(Some(0), stdout, ""),
+            Some("turn-1".to_string()),
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "do not inject".to_string(),
+            }],
+        );
+    }
+
+    #[test]
+    fn exit_code_two_blocks_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(2), "", "blocked by policy\n"),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            UserPromptSubmitHandlerData {
+                should_stop: true,
+                stop_reason: Some("blocked by policy".to_string()),
+                additional_contexts_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Feedback,
+                text: "blocked by policy".to_string(),
+            }]
+        );
+
+        let async_handler = handler_with_async(/*async*/ true);
+        let parsed = parse_completed(
+            &async_handler,
+            run_result(Some(2), "", "blocked by policy\n"),
+            Some("turn-1".to_string()),
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert!(!parsed.data.should_stop);
+    }
+
+    fn handler() -> ConfiguredHandler {
+        handler_with_async(/*async*/ false)
+    }
+
+    fn handler_with_async(r#async: bool) -> ConfiguredHandler {
+        ConfiguredHandler {
+            builtin: false,
+            event_name: HookEventName::UserPromptSubmit,
+            matcher: None,
+            timeout_sec: 5,
+            status_message: None,
+            additional_context_limit: Default::default(),
+            source_path: test_path_buf("/tmp/hooks.json").abs().into(),
+            source: codex_protocol::protocol::HookSource::User,
+            display_order: 0,
+            kind: crate::engine::ConfiguredHandlerKind::Command {
+                command: "echo hook".to_string(),
+                r#async,
+                env: std::collections::HashMap::new(),
+            },
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> HandlerRunResult {
+        HandlerRunResult {
+            started_at: 1,
+            completed_at: 2,
+            duration_ms: 1,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+}
diff --git a/codex-rs/hooks/src/legacy_notify.rs b/codex-rs/hooks/src/legacy_notify.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5be7d7b32ee13572cd9c0f9af276bb5b083f7159
--- /dev/null
+++ b/codex-rs/hooks/src/legacy_notify.rs
@@ -0,0 +1,183 @@
+use std::ffi::OsString;
+use std::process::Stdio;
+use std::sync::Arc;
+
+use serde::Serialize;
+
+use crate::Hook;
+use crate::HookEvent;
+use crate::HookPayload;
+use crate::HookResult;
+use crate::registry::command_from_argv;
+
+/// Legacy notify payload appended as the final argv argument for backward compatibility.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+#[serde(tag = "type", rename_all = "kebab-case")]
+enum UserNotification {
+    #[serde(rename_all = "kebab-case")]
+    AgentTurnComplete {
+        thread_id: String,
+        turn_id: String,
+        cwd: String,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        client: Option<String>,
+        input_messages: Vec<String>,
+        last_assistant_message: Option<String>,
+    },
+}
+
+pub fn legacy_notify_json(payload: &HookPayload) -> Result<String, serde_json::Error> {
+    match &payload.hook_event {
+        HookEvent::AfterAgent { event } => {
+            serde_json::to_string(&UserNotification::AgentTurnComplete {
+                thread_id: event.thread_id.to_string(),
+                turn_id: event.turn_id.clone(),
+                cwd: payload.cwd.display().to_string(),
+                client: payload.client.clone(),
+                input_messages: event.input_messages.clone(),
+                last_assistant_message: event.last_assistant_message.clone(),
+            })
+        }
+    }
+}
+
+// TODO: Remove this hook and its environment plumbing when legacy `notify` support is removed.
+pub(crate) fn notify_hook(argv: Vec<String>, environment: Arc<Vec<(OsString, OsString)>>) -> Hook {
+    let argv = Arc::new(argv);
+    Hook {
+        name: "legacy_notify".to_string(),
+        func: Arc::new(move |payload: &HookPayload| {
+            let argv = Arc::clone(&argv);
+            let environment = Arc::clone(&environment);
+            Box::pin(async move {
+                let mut command = match command_from_argv(&argv, environment.iter().cloned()) {
+                    Some(command) => command,
+                    None => return HookResult::Success,
+                };
+                if let Ok(notify_payload) = legacy_notify_json(payload) {
+                    command.arg(notify_payload);
+                }
+
+                command
+                    .stdin(Stdio::null())
+                    .stdout(Stdio::null())
+                    .stderr(Stdio::null());
+
+                match command.spawn() {
+                    Ok(_) => HookResult::Success,
+                    Err(err) => HookResult::FailedContinue(err.into()),
+                }
+            })
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use anyhow::Result;
+    use codex_protocol::ThreadId;
+    use codex_protocol::shell_environment::CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+    use serde_json::Value;
+    use serde_json::json;
+
+    use super::*;
+    use crate::HookEventAfterAgent;
+
+    fn expected_notification_json() -> Value {
+        let cwd = test_path_buf("/Users/example/project");
+        json!({
+            "type": "agent-turn-complete",
+            "thread-id": "b5f6c1c2-1111-2222-3333-444455556666",
+            "turn-id": "12345",
+            "cwd": cwd.display().to_string(),
+            "client": "codex-tui",
+            "input-messages": ["Rename `foo` to `bar` and update the callsites."],
+            "last-assistant-message": "Rename complete and verified `cargo build` succeeds.",
+        })
+    }
+
+    #[test]
+    fn test_user_notification() -> Result<()> {
+        let notification = UserNotification::AgentTurnComplete {
+            thread_id: "b5f6c1c2-1111-2222-3333-444455556666".to_string(),
+            turn_id: "12345".to_string(),
+            cwd: test_path_buf("/Users/example/project")
+                .display()
+                .to_string(),
+            client: Some("codex-tui".to_string()),
+            input_messages: vec!["Rename `foo` to `bar` and update the callsites.".to_string()],
+            last_assistant_message: Some(
+                "Rename complete and verified `cargo build` succeeds.".to_string(),
+            ),
+        };
+        let serialized = serde_json::to_string(&notification)?;
+        let actual: Value = serde_json::from_str(&serialized)?;
+        assert_eq!(actual, expected_notification_json());
+        Ok(())
+    }
+
+    #[test]
+    fn legacy_notify_json_matches_historical_wire_shape() -> Result<()> {
+        let payload = HookPayload {
+            session_id: ThreadId::new(),
+            cwd: test_path_buf("/Users/example/project").abs(),
+            client: Some("codex-tui".to_string()),
+            triggered_at: chrono::Utc::now(),
+            hook_event: HookEvent::AfterAgent {
+                event: HookEventAfterAgent {
+                    thread_id: ThreadId::from_string("b5f6c1c2-1111-2222-3333-444455556666")
+                        .expect("valid thread id"),
+                    turn_id: "12345".to_string(),
+                    input_messages: vec![
+                        "Rename `foo` to `bar` and update the callsites.".to_string(),
+                    ],
+                    last_assistant_message: Some(
+                        "Rename complete and verified `cargo build` succeeds.".to_string(),
+                    ),
+                },
+            },
+        };
+
+        let serialized = legacy_notify_json(&payload)?;
+        let actual: Value = serde_json::from_str(&serialized)?;
+        assert_eq!(actual, expected_notification_json());
+
+        Ok(())
+    }
+
+    #[test]
+    fn legacy_notify_command_replays_session_snapshot_and_scrubs_credentials() {
+        let argv = vec!["notify-command".to_string()];
+        let environment = vec![
+            (
+                OsString::from("CODEX_LEGACY_NOTIFY_SNAPSHOT"),
+                OsString::from("captured"),
+            ),
+            (
+                OsString::from(CODEX_EXEC_SERVER_NOISE_AUTH_TOKEN_ENV_VAR),
+                OsString::from("restricted-token"),
+            ),
+        ];
+
+        let command = command_from_argv(&argv, environment)
+            .expect("legacy notification command should be configured");
+        let configured_environment = command
+            .as_std()
+            .get_envs()
+            .filter_map(|(name, value)| {
+                value.map(|value| (name.to_os_string(), value.to_os_string()))
+            })
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            configured_environment,
+            vec![(
+                OsString::from("CODEX_LEGACY_NOTIFY_SNAPSHOT"),
+                OsString::from("captured"),
+            )]
+        );
+    }
+}
diff --git a/codex-rs/hooks/src/lib.rs b/codex-rs/hooks/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6abc173535b23b5ee6bd057fd3f49d9b82ea7fe0
--- /dev/null
+++ b/codex-rs/hooks/src/lib.rs
@@ -0,0 +1,123 @@
+mod config_rules;
+mod declarations;
+mod engine;
+pub(crate) mod events;
+mod legacy_notify;
+mod mcp;
+mod output_spill;
+mod registry;
+mod schema;
+mod types;
+
+use codex_protocol::protocol::HookEventName;
+
+pub use config_rules::hook_states_from_stack;
+pub use declarations::PluginHookDeclaration;
+pub use declarations::plugin_hook_declarations;
+pub use engine::HookListEntry;
+pub use engine::HookListEntryHandler;
+pub use engine::dispatcher::hook_execution_mode_label;
+pub use engine::dispatcher::hook_handler_type_label;
+pub use events::common::SubagentHookContext;
+/// Hook event names as they appear in hooks JSON and config files.
+pub const HOOK_EVENT_NAMES: [&str; 12] = [
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "SubagentStart",
+    "SubagentStop",
+    "Stop",
+    "Interrupt",
+];
+
+/// Hook event names whose matcher fields are meaningful during dispatch.
+///
+/// Other events can appear in hooks JSON, but Codex ignores their matcher
+/// fields because those events do not dispatch against a tool, compaction
+/// trigger, session-start source, or session-end reason.
+pub const HOOK_EVENT_NAMES_WITH_MATCHERS: [&str; 9] = [
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "SessionStart",
+    "SessionEnd",
+    "SubagentStart",
+    "SubagentStop",
+];
+
+pub use events::compact::PostCompactRequest;
+pub use events::compact::PreCompactOutcome;
+pub use events::compact::PreCompactRequest;
+pub use events::compact::StatelessHookOutcome;
+pub use events::interrupt::InterruptOutcome;
+pub use events::interrupt::InterruptRequest;
+pub use events::permission_request::PermissionRequestDecision;
+pub use events::permission_request::PermissionRequestOutcome;
+pub use events::permission_request::PermissionRequestRequest;
+pub use events::post_tool_use::PostToolUseOutcome;
+pub use events::post_tool_use::PostToolUseRequest;
+pub use events::pre_tool_use::PreToolUseOutcome;
+pub use events::pre_tool_use::PreToolUseRequest;
+pub use events::session_end::SessionEndOutcome;
+pub use events::session_end::SessionEndRequest;
+pub use events::session_start::SessionStartOutcome;
+pub use events::session_start::SessionStartRequest;
+pub use events::session_start::SessionStartSource;
+pub use events::session_start::StartHookTarget;
+pub use events::stop::StopHookTarget;
+pub use events::stop::StopOutcome;
+pub use events::stop::StopRequest;
+pub use events::user_prompt_submit::UserPromptSubmitOutcome;
+pub use events::user_prompt_submit::UserPromptSubmitRequest;
+pub use legacy_notify::legacy_notify_json;
+pub use mcp::HookMcpCall;
+pub use mcp::HookMcpExecutor;
+pub use registry::HookListOutcome;
+pub use registry::Hooks;
+pub use registry::HooksConfig;
+pub use registry::list_hooks;
+pub use schema::write_schema_fixtures;
+pub use types::Hook;
+pub use types::HookEvent;
+pub use types::HookEventAfterAgent;
+pub use types::HookPayload;
+pub use types::HookResponse;
+pub use types::HookResult;
+
+/// Returns the hook event label used in persisted hook-state keys.
+pub fn hook_event_key_label(event_name: HookEventName) -> &'static str {
+    match event_name {
+        HookEventName::PreToolUse => "pre_tool_use",
+        HookEventName::PermissionRequest => "permission_request",
+        HookEventName::PostToolUse => "post_tool_use",
+        HookEventName::PreCompact => "pre_compact",
+        HookEventName::PostCompact => "post_compact",
+        HookEventName::SessionStart => "session_start",
+        HookEventName::SessionEnd => "session_end",
+        HookEventName::UserPromptSubmit => "user_prompt_submit",
+        HookEventName::SubagentStart => "subagent_start",
+        HookEventName::SubagentStop => "subagent_stop",
+        HookEventName::Stop => "stop",
+        HookEventName::Interrupt => "interrupt",
+    }
+}
+
+/// Builds the persisted config-state key for one discovered hook handler.
+pub fn hook_key(
+    key_source: &str,
+    event_name: HookEventName,
+    group_index: usize,
+    handler_index: usize,
+) -> String {
+    format!(
+        "{key_source}:{}:{group_index}:{handler_index}",
+        hook_event_key_label(event_name)
+    )
+}
diff --git a/codex-rs/hooks/src/mcp.rs b/codex-rs/hooks/src/mcp.rs
new file mode 100644
index 0000000000000000000000000000000000000000..49d907df80e0241d17cf2e1b60bfe18f138ec8c5
--- /dev/null
+++ b/codex-rs/hooks/src/mcp.rs
@@ -0,0 +1,24 @@
+use std::time::Duration;
+
+use futures::future::BoxFuture;
+use serde_json::Map;
+use serde_json::Value;
+
+/// One MCP tool call requested by a configured hook handler.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HookMcpCall {
+    pub server: String,
+    pub tool: String,
+    pub environment_id: Option<String>,
+    pub metadata: Option<Map<String, Value>>,
+    pub input: Map<String, Value>,
+    pub timeout: Duration,
+}
+
+/// Executes already-connected MCP tools on behalf of hooks without coupling this crate to core.
+///
+/// Implementations own server readiness, policy enforcement, timeout handling, and elicitation.
+pub trait HookMcpExecutor: Send + Sync {
+    /// Returns text that is interpreted using ordinary command-hook output semantics.
+    fn execute(&self, call: HookMcpCall) -> BoxFuture<'_, anyhow::Result<String>>;
+}
diff --git a/codex-rs/hooks/src/output_spill.rs b/codex-rs/hooks/src/output_spill.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b60ac973995a15b39c8499584acf4448b7eaffab
--- /dev/null
+++ b/codex-rs/hooks/src/output_spill.rs
@@ -0,0 +1,135 @@
+use codex_protocol::ThreadId;
+use codex_protocol::items::HookPromptFragment;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_output_truncation::TruncationPolicy;
+use codex_utils_output_truncation::approx_token_count;
+use codex_utils_output_truncation::formatted_truncate_text;
+use tokio::fs;
+use tracing::warn;
+use uuid::Uuid;
+
+const HOOK_OUTPUTS_DIR: &str = "hook_outputs";
+pub(crate) const DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT: usize = 2_500;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct AdditionalContextLimit {
+    token_limit: usize,
+}
+
+impl AdditionalContextLimit {
+    pub(crate) fn from_config(value: Option<usize>) -> Self {
+        Self {
+            token_limit: value.unwrap_or(DEFAULT_HOOK_OUTPUT_TOKEN_LIMIT),
+        }
+    }
+}
+
+impl Default for AdditionalContextLimit {
+    fn default() -> Self {
+        Self::from_config(/*value*/ None)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct AdditionalContext {
+    pub text: String,
+    pub limit: AdditionalContextLimit,
+}
+
+#[derive(Clone)]
+pub(crate) struct HookOutputSpiller {
+    output_dir: AbsolutePathBuf,
+}
+
+impl HookOutputSpiller {
+    pub(crate) fn new(thread_id: ThreadId) -> Self {
+        Self {
+            output_dir: AbsolutePathBuf::resolve_path_against_base(std::env::temp_dir(), "/")
+                .join(HOOK_OUTPUTS_DIR)
+                .join(thread_id.to_string()),
+        }
+    }
+
+    /// Keeps hook text within the model-visible hook-output budget.
+    ///
+    /// Oversized text is written in full under the OS temp directory at
+    /// `<temp_dir>/hook_outputs/<thread_id>/`
+    /// and replaced with the same head/tail preview style used for other truncated
+    /// output, plus a path back to the preserved full text.
+    pub(crate) async fn maybe_spill_text(&self, text: String) -> String {
+        self.maybe_spill_text_with_limit(text, AdditionalContextLimit::default())
+            .await
+    }
+
+    async fn maybe_spill_text_with_limit(
+        &self,
+        text: String,
+        limit: AdditionalContextLimit,
+    ) -> String {
+        let token_limit = limit.token_limit;
+        if token_limit == 0 || approx_token_count(&text) <= token_limit {
+            return text;
+        }
+
+        let path = self.output_dir.join(format!("{}.txt", Uuid::new_v4()));
+        if let Some(parent) = path.parent()
+            && let Err(err) = fs::create_dir_all(parent.as_ref()).await
+        {
+            warn!(
+                "failed to create hook output directory {}: {err}",
+                parent.display()
+            );
+            return formatted_truncate_text(&text, TruncationPolicy::Tokens(token_limit));
+        }
+
+        if let Err(err) = fs::write(path.as_ref(), &text).await {
+            warn!("failed to write hook output {}: {err}", path.display());
+            return formatted_truncate_text(&text, TruncationPolicy::Tokens(token_limit));
+        }
+
+        spilled_hook_output_preview(&text, &path, token_limit)
+    }
+
+    pub(crate) async fn maybe_spill_additional_contexts(
+        &self,
+        contexts: Vec<AdditionalContext>,
+    ) -> Vec<String> {
+        let mut spilled = Vec::with_capacity(contexts.len());
+        for context in contexts {
+            spilled.push(
+                self.maybe_spill_text_with_limit(context.text, context.limit)
+                    .await,
+            );
+        }
+        spilled
+    }
+
+    pub(crate) async fn maybe_spill_prompt_fragments(
+        &self,
+        fragments: Vec<HookPromptFragment>,
+    ) -> Vec<HookPromptFragment> {
+        let mut spilled = Vec::with_capacity(fragments.len());
+        for fragment in fragments {
+            spilled.push(HookPromptFragment {
+                text: self.maybe_spill_text(fragment.text).await,
+                hook_run_id: fragment.hook_run_id,
+            });
+        }
+        spilled
+    }
+}
+
+/// Builds the model-visible replacement for a spilled hook output.
+///
+/// The path footer is budgeted before truncation so adding the recovery path
+/// does not consume the configured preview budget.
+fn spilled_hook_output_preview(text: &str, path: &AbsolutePathBuf, token_limit: usize) -> String {
+    let footer = format!("\n\nFull hook output saved to: {}", path.display());
+    let preview_policy =
+        TruncationPolicy::Tokens(token_limit.saturating_sub(approx_token_count(&footer)));
+    format!("{}{footer}", formatted_truncate_text(text, preview_policy))
+}
+
+#[cfg(test)]
+#[path = "output_spill_tests.rs"]
+mod tests;
diff --git a/codex-rs/hooks/src/output_spill_tests.rs b/codex-rs/hooks/src/output_spill_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6b72c956ce16793d12cea015ee3d27997be28d94
--- /dev/null
+++ b/codex-rs/hooks/src/output_spill_tests.rs
@@ -0,0 +1,83 @@
+use super::*;
+use anyhow::Context;
+use anyhow::Result;
+use tempfile::tempdir;
+
+#[test]
+fn hook_output_spiller_is_scoped_to_its_thread() {
+    let thread_id = ThreadId::new();
+    let spiller = HookOutputSpiller::new(thread_id);
+
+    assert_eq!(
+        spiller.output_dir,
+        AbsolutePathBuf::resolve_path_against_base(std::env::temp_dir(), "/")
+            .join(HOOK_OUTPUTS_DIR)
+            .join(thread_id.to_string())
+    );
+}
+
+#[tokio::test]
+async fn small_hook_output_remains_inline() -> Result<()> {
+    let dir = tempdir()?;
+    let output_dir = AbsolutePathBuf::from_absolute_path(dir.path())?.join(HOOK_OUTPUTS_DIR);
+    let spiller = HookOutputSpiller {
+        output_dir: output_dir.clone(),
+    };
+
+    let output = spiller.maybe_spill_text("short".to_string()).await;
+
+    assert_eq!(output, "short");
+    assert!(!output_dir.exists());
+    Ok(())
+}
+
+#[tokio::test]
+async fn large_hook_output_spills_to_file() -> Result<()> {
+    let dir = tempdir()?;
+    let text = "hook output ".repeat(1_000);
+    let output_dir = AbsolutePathBuf::from_absolute_path(dir.path())?.join(HOOK_OUTPUTS_DIR);
+    let spiller = HookOutputSpiller { output_dir };
+
+    let output = spiller.maybe_spill_text(text.clone()).await;
+
+    assert!(output.contains("tokens truncated"));
+    let path = output
+        .lines()
+        .find_map(|line| line.strip_prefix("Full hook output saved to: "))
+        .context("spill path")?;
+    assert_eq!(fs::read_to_string(path).await?, text);
+    Ok(())
+}
+
+#[tokio::test]
+async fn additional_contexts_apply_limits_individually() -> Result<()> {
+    let dir = tempdir()?;
+    let limited_text = "limited hook output ".repeat(1_000);
+    let unlimited_text = "unlimited hook output ".repeat(5_000);
+    assert!(approx_token_count(&unlimited_text) > 10_000);
+    let output_dir = AbsolutePathBuf::from_absolute_path(dir.path())?.join(HOOK_OUTPUTS_DIR);
+    let spiller = HookOutputSpiller { output_dir };
+    let output = spiller
+        .maybe_spill_additional_contexts(vec![
+            AdditionalContext {
+                text: limited_text.clone(),
+                limit: AdditionalContextLimit::from_config(Some(1)),
+            },
+            AdditionalContext {
+                text: unlimited_text.clone(),
+                limit: AdditionalContextLimit::from_config(Some(0)),
+            },
+            AdditionalContext {
+                text: unlimited_text.clone(),
+                limit: AdditionalContextLimit::from_config(Some(usize::MAX)),
+            },
+        ])
+        .await;
+    let [limited_output, zero_limit_output, high_limit_output] = output.as_slice() else {
+        panic!("expected one output for each additional context");
+    };
+    assert!(limited_output.contains("Full hook output saved to:"));
+    assert_eq!(zero_limit_output, &unlimited_text);
+    assert_eq!(high_limit_output, &unlimited_text);
+    Ok(())
+}
diff --git a/codex-rs/hooks/src/registry.rs b/codex-rs/hooks/src/registry.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5a033f9c64dacaf031719e60c3c42d52b2d9eb07
--- /dev/null
+++ b/codex-rs/hooks/src/registry.rs
@@ -0,0 +1,336 @@
+use crate::engine::ClaudeHooksEngine;
+use crate::engine::CommandShell;
+use crate::engine::HookListEntry;
+use crate::engine::command_runner::CommandHookRuntime;
+use crate::events::compact::PostCompactRequest;
+use crate::events::compact::PreCompactOutcome;
+use crate::events::compact::PreCompactRequest;
+use crate::events::compact::StatelessHookOutcome;
+use crate::events::interrupt::InterruptOutcome;
+use crate::events::interrupt::InterruptRequest;
+use crate::events::permission_request::PermissionRequestOutcome;
+use crate::events::permission_request::PermissionRequestRequest;
+use crate::events::post_tool_use::PostToolUseOutcome;
+use crate::events::post_tool_use::PostToolUseRequest;
+use crate::events::pre_tool_use::PreToolUseOutcome;
+use crate::events::pre_tool_use::PreToolUseRequest;
+use crate::events::session_end::SessionEndOutcome;
+use crate::events::session_end::SessionEndRequest;
+use crate::events::session_start::SessionStartOutcome;
+use crate::events::session_start::SessionStartRequest;
+use crate::events::stop::StopOutcome;
+use crate::events::stop::StopRequest;
+use crate::events::user_prompt_submit::UserPromptSubmitOutcome;
+use crate::events::user_prompt_submit::UserPromptSubmitRequest;
+use crate::mcp::HookMcpExecutor;
+use crate::types::Hook;
+use crate::types::HookEvent;
+use crate::types::HookPayload;
+use crate::types::HookResponse;
+use async_channel::Receiver;
+use codex_config::ConfigLayerStack;
+use codex_plugin::ExecutorPluginHookSource;
+use codex_plugin::PluginHookSource;
+use codex_protocol::ThreadId;
+use codex_protocol::shell_environment::scrub_non_inheritable_env_vars;
+use std::ffi::OsString;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::process::Command;
+
+#[derive(Default, Clone)]
+pub struct HooksConfig {
+    pub legacy_notify_argv: Option<Vec<String>>,
+    pub feature_enabled: bool,
+    pub bypass_hook_trust: bool,
+    pub config_layer_stack: Option<ConfigLayerStack>,
+    pub plugin_hook_sources: Vec<PluginHookSource>,
+    pub plugin_hook_load_warnings: Vec<String>,
+    pub shell_program: Option<String>,
+    pub shell_args: Vec<String>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct HookListOutcome {
+    pub hooks: Vec<HookListEntry>,
+    pub warnings: Vec<String>,
+}
+
+#[derive(Clone)]
+pub struct Hooks {
+    // TODO: Once legacy `notify` is removed, capture this snapshot in `CommandHookRuntime::new`
+    // and remove the environment plumbing from `Hooks` and `from_config`.
+    environment: Arc<Vec<(OsString, OsString)>>,
+    after_agent: Vec<Hook>,
+    engine: ClaudeHooksEngine,
+    plugin_hook_sources: Vec<PluginHookSource>,
+    plugin_hook_load_warnings: Vec<String>,
+}
+
+impl Hooks {
+    /// Bind this session's hook runtime and output files to its thread, rejecting unloadable
+    /// required managed hooks.
+    pub fn new(
+        config: HooksConfig,
+        thread_id: ThreadId,
+        mcp_executor: Arc<dyn HookMcpExecutor>,
+    ) -> anyhow::Result<(Self, Receiver<codex_protocol::protocol::HookCompletedEvent>)> {
+        let (result_sender, result_receiver) = async_channel::unbounded();
+        let environment = Arc::new(std::env::vars_os().collect());
+        let hooks = Self::from_config(config, mcp_executor, Arc::clone(&environment), |shell| {
+            CommandHookRuntime::new(shell, environment, thread_id, result_sender)
+        });
+        let required_load_errors = hooks.engine.required_load_errors();
+        if !required_load_errors.is_empty() {
+            anyhow::bail!(
+                "failed to load required managed hooks: {}",
+                required_load_errors.join("; ")
+            );
+        }
+        Ok((hooks, result_receiver))
+    }
+
+    /// Preserve in-flight background hooks while applying a refreshed configuration.
+    pub fn reconfigured(&self, config: HooksConfig) -> Self {
+        Self::from_config(
+            config,
+            Arc::clone(&self.engine.mcp_executor),
+            Arc::clone(&self.environment),
+            |shell| self.engine.command_runtime.reconfigured(shell),
+        )
+    }
+
+    pub fn matches_plugin_hooks<'a>(
+        &self,
+        sources: impl IntoIterator<Item = &'a PluginHookSource>,
+        warnings: impl IntoIterator<Item = &'a String>,
+    ) -> bool {
+        self.plugin_hook_sources.iter().eq(sources)
+            && self.plugin_hook_load_warnings.iter().eq(warnings)
+    }
+
+    pub fn with_executor_hooks(&self, executor_hooks: Vec<ExecutorPluginHookSource>) -> Self {
+        let mut hooks = self.clone();
+        hooks.engine.set_executor_hooks(executor_hooks);
+        hooks
+    }
+
+    fn from_config(
+        config: HooksConfig,
+        mcp_executor: Arc<dyn HookMcpExecutor>,
+        environment: Arc<Vec<(OsString, OsString)>>,
+        build_runtime: impl FnOnce(CommandShell) -> CommandHookRuntime,
+    ) -> Self {
+        let after_agent = config
+            .legacy_notify_argv
+            .filter(|argv| !argv.is_empty() && !argv[0].is_empty())
+            .map(|argv| crate::legacy_notify::notify_hook(argv, Arc::clone(&environment)))
+            .into_iter()
+            .collect();
+        let command_runtime = build_runtime(CommandShell {
+            program: config.shell_program.unwrap_or_default(),
+            args: config.shell_args,
+        });
+        let engine = ClaudeHooksEngine::new(
+            config.feature_enabled,
+            config.bypass_hook_trust,
+            config.config_layer_stack.as_ref(),
+            config.plugin_hook_sources.clone(),
+            config.plugin_hook_load_warnings.clone(),
+            command_runtime,
+            mcp_executor,
+        );
+        Self {
+            environment,
+            after_agent,
+            engine,
+            plugin_hook_sources: config.plugin_hook_sources,
+            plugin_hook_load_warnings: config.plugin_hook_load_warnings,
+        }
+    }
+
+    /// Abort and join outstanding async hooks during session shutdown.
+    pub async fn shutdown(&self) {
+        self.engine.command_runtime.shutdown().await;
+    }
+
+    pub fn startup_warnings(&self) -> &[String] {
+        self.engine.warnings()
+    }
+
+    fn hooks_for_event(&self, hook_event: &HookEvent) -> &[Hook] {
+        match hook_event {
+            HookEvent::AfterAgent { .. } => &self.after_agent,
+        }
+    }
+
+    pub async fn dispatch(&self, hook_payload: HookPayload) -> Vec<HookResponse> {
+        let hooks = self.hooks_for_event(&hook_payload.hook_event);
+        let mut outcomes = Vec::with_capacity(hooks.len());
+        for hook in hooks {
+            let outcome = hook.execute(&hook_payload).await;
+            let should_abort_operation = outcome.result.should_abort_operation();
+            outcomes.push(outcome);
+            if should_abort_operation {
+                break;
+            }
+        }
+
+        outcomes
+    }
+
+    pub fn preview_session_start(
+        &self,
+        request: &SessionStartRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_session_start(request)
+    }
+
+    pub fn preview_pre_tool_use(
+        &self,
+        request: &PreToolUseRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_pre_tool_use(request)
+    }
+
+    pub fn preview_permission_request(
+        &self,
+        request: &PermissionRequestRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_permission_request(request)
+    }
+
+    /// Maximum configured timeout among PermissionRequest hooks.
+    ///
+    /// Matching handlers run concurrently, so their aggregate timeout is bounded by this maximum.
+    pub fn max_permission_request_timeout(&self) -> Duration {
+        self.engine.max_permission_request_timeout()
+    }
+
+    pub fn preview_post_tool_use(
+        &self,
+        request: &PostToolUseRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_post_tool_use(request)
+    }
+
+    pub async fn run_session_start(
+        &self,
+        request: SessionStartRequest,
+        turn_id: Option<String>,
+    ) -> SessionStartOutcome {
+        self.engine.run_session_start(request, turn_id).await
+    }
+
+    pub async fn run_pre_tool_use(&self, request: PreToolUseRequest) -> PreToolUseOutcome {
+        self.engine.run_pre_tool_use(request).await
+    }
+
+    pub async fn run_permission_request(
+        &self,
+        request: PermissionRequestRequest,
+    ) -> PermissionRequestOutcome {
+        self.engine.run_permission_request(request).await
+    }
+
+    pub async fn run_post_tool_use(&self, request: PostToolUseRequest) -> PostToolUseOutcome {
+        self.engine.run_post_tool_use(request).await
+    }
+
+    pub fn preview_pre_compact(
+        &self,
+        request: &PreCompactRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_pre_compact(request)
+    }
+
+    pub async fn run_pre_compact(&self, request: PreCompactRequest) -> PreCompactOutcome {
+        self.engine.run_pre_compact(request).await
+    }
+
+    pub fn preview_post_compact(
+        &self,
+        request: &PostCompactRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_post_compact(request)
+    }
+
+    pub async fn run_post_compact(&self, request: PostCompactRequest) -> StatelessHookOutcome {
+        self.engine.run_post_compact(request).await
+    }
+
+    pub fn preview_user_prompt_submit(
+        &self,
+        request: &UserPromptSubmitRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_user_prompt_submit(request)
+    }
+
+    pub async fn run_user_prompt_submit(
+        &self,
+        request: UserPromptSubmitRequest,
+    ) -> UserPromptSubmitOutcome {
+        self.engine.run_user_prompt_submit(request).await
+    }
+
+    pub fn preview_stop(
+        &self,
+        request: &StopRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_stop(request)
+    }
+
+    pub async fn run_stop(&self, request: StopRequest) -> StopOutcome {
+        self.engine.run_stop(request).await
+    }
+
+    pub fn preview_session_end(&self) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_session_end()
+    }
+
+    pub async fn run_session_end(&self, request: SessionEndRequest) -> SessionEndOutcome {
+        self.engine.run_session_end(request).await
+    }
+
+    pub fn preview_interrupt(&self) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_interrupt()
+    }
+
+    pub async fn run_interrupt(&self, request: InterruptRequest) -> InterruptOutcome {
+        self.engine.run_interrupt(request).await
+    }
+}
+
+pub fn list_hooks(config: HooksConfig) -> HookListOutcome {
+    if !config.feature_enabled {
+        return HookListOutcome::default();
+    }
+
+    let discovered = crate::engine::discovery::discover_handlers(
+        config.config_layer_stack.as_ref(),
+        config.plugin_hook_sources,
+        config.plugin_hook_load_warnings,
+        config.bypass_hook_trust,
+    );
+    HookListOutcome {
+        hooks: discovered.hook_entries,
+        warnings: discovered.warnings,
+    }
+}
+
+// TODO: Remove this legacy-notify-only command builder when `notify` support is removed.
+pub(crate) fn command_from_argv(
+    argv: &[String],
+    environment: impl IntoIterator<Item = (OsString, OsString)>,
+) -> Option<Command> {
+    let (program, args) = argv.split_first()?;
+    if program.is_empty() {
+        return None;
+    }
+    let mut command = Command::new(program);
+    command.args(args);
+    command.env_clear();
+    command.envs(environment);
+    scrub_non_inheritable_env_vars(command.as_std_mut());
+    Some(command)
+}
diff --git a/codex-rs/hooks/src/schema.rs b/codex-rs/hooks/src/schema.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bb50807af5fc242f4fb65a20357920a9fc315a63
--- /dev/null
+++ b/codex-rs/hooks/src/schema.rs
@@ -0,0 +1,1254 @@
+use schemars::JsonSchema;
+use schemars::r#gen::SchemaGenerator;
+use schemars::r#gen::SchemaSettings;
+use schemars::schema::InstanceType;
+use schemars::schema::RootSchema;
+use schemars::schema::Schema;
+use schemars::schema::SchemaObject;
+use serde::Deserialize;
+use serde::Serialize;
+use serde_json::Map;
+use serde_json::Value;
+use std::path::Path;
+use std::path::PathBuf;
+
+use crate::events::common::SubagentHookContext;
+
+const GENERATED_DIR: &str = "generated";
+const POST_TOOL_USE_INPUT_FIXTURE: &str = "post-tool-use.command.input.schema.json";
+const POST_TOOL_USE_OUTPUT_FIXTURE: &str = "post-tool-use.command.output.schema.json";
+const PERMISSION_REQUEST_INPUT_FIXTURE: &str = "permission-request.command.input.schema.json";
+const PERMISSION_REQUEST_OUTPUT_FIXTURE: &str = "permission-request.command.output.schema.json";
+const POST_COMPACT_INPUT_FIXTURE: &str = "post-compact.command.input.schema.json";
+const POST_COMPACT_OUTPUT_FIXTURE: &str = "post-compact.command.output.schema.json";
+const PRE_TOOL_USE_INPUT_FIXTURE: &str = "pre-tool-use.command.input.schema.json";
+const PRE_TOOL_USE_OUTPUT_FIXTURE: &str = "pre-tool-use.command.output.schema.json";
+const PRE_COMPACT_INPUT_FIXTURE: &str = "pre-compact.command.input.schema.json";
+const PRE_COMPACT_OUTPUT_FIXTURE: &str = "pre-compact.command.output.schema.json";
+const SESSION_START_INPUT_FIXTURE: &str = "session-start.command.input.schema.json";
+const SESSION_START_OUTPUT_FIXTURE: &str = "session-start.command.output.schema.json";
+const SESSION_END_INPUT_FIXTURE: &str = "session-end.command.input.schema.json";
+const USER_PROMPT_SUBMIT_INPUT_FIXTURE: &str = "user-prompt-submit.command.input.schema.json";
+const USER_PROMPT_SUBMIT_OUTPUT_FIXTURE: &str = "user-prompt-submit.command.output.schema.json";
+const SUBAGENT_START_INPUT_FIXTURE: &str = "subagent-start.command.input.schema.json";
+const SUBAGENT_START_OUTPUT_FIXTURE: &str = "subagent-start.command.output.schema.json";
+const SUBAGENT_STOP_INPUT_FIXTURE: &str = "subagent-stop.command.input.schema.json";
+const SUBAGENT_STOP_OUTPUT_FIXTURE: &str = "subagent-stop.command.output.schema.json";
+const STOP_INPUT_FIXTURE: &str = "stop.command.input.schema.json";
+const STOP_OUTPUT_FIXTURE: &str = "stop.command.output.schema.json";
+const INTERRUPT_INPUT_FIXTURE: &str = "interrupt.command.input.schema.json";
+const INTERRUPT_OUTPUT_FIXTURE: &str = "interrupt.command.output.schema.json";
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(transparent)]
+pub(crate) struct NullableString(Option<String>);
+
+impl NullableString {
+    pub(crate) fn from_path(path: Option<PathBuf>) -> Self {
+        Self(path.map(|path| path.display().to_string()))
+    }
+
+    pub(crate) fn from_string(value: Option<String>) -> Self {
+        Self(value)
+    }
+}
+
+impl JsonSchema for NullableString {
+    fn schema_name() -> String {
+        "NullableString".to_string()
+    }
+
+    fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
+        Schema::Object(SchemaObject {
+            instance_type: Some(vec![InstanceType::String, InstanceType::Null].into()),
+            ..Default::default()
+        })
+    }
+}
+
+#[derive(Debug, Clone, Default)]
+pub(crate) struct SubagentCommandInputFields {
+    pub agent_id: Option<String>,
+    pub agent_type: Option<String>,
+}
+
+impl From<Option<&SubagentHookContext>> for SubagentCommandInputFields {
+    fn from(value: Option<&SubagentHookContext>) -> Self {
+        match value {
+            Some(context) => Self {
+                agent_id: Some(context.agent_id.clone()),
+                agent_type: Some(context.agent_type.clone()),
+            },
+            None => Self::default(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct HookUniversalOutputWire {
+    #[serde(default = "default_continue")]
+    pub r#continue: bool,
+    #[serde(default)]
+    pub stop_reason: Option<String>,
+    #[serde(default)]
+    pub suppress_output: bool,
+    #[serde(default)]
+    pub system_message: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+pub(crate) enum HookEventNameWire {
+    #[serde(rename = "PreToolUse")]
+    PreToolUse,
+    #[serde(rename = "PermissionRequest")]
+    PermissionRequest,
+    #[serde(rename = "PostToolUse")]
+    PostToolUse,
+    #[serde(rename = "PreCompact")]
+    PreCompact,
+    #[serde(rename = "PostCompact")]
+    PostCompact,
+    #[serde(rename = "SessionStart")]
+    SessionStart,
+    #[serde(rename = "UserPromptSubmit")]
+    UserPromptSubmit,
+    #[serde(rename = "SubagentStart")]
+    SubagentStart,
+    #[serde(rename = "SubagentStop")]
+    SubagentStop,
+    #[serde(rename = "Stop")]
+    Stop,
+    #[serde(rename = "Interrupt")]
+    Interrupt,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "pre-tool-use.command.output")]
+pub(crate) struct PreToolUseCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub decision: Option<PreToolUseDecisionWire>,
+    #[serde(default)]
+    pub reason: Option<String>,
+    #[serde(default)]
+    pub hook_specific_output: Option<PreToolUseHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "post-tool-use.command.output")]
+pub(crate) struct PostToolUseCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub decision: Option<BlockDecisionWire>,
+    #[serde(default)]
+    pub reason: Option<String>,
+    #[serde(default)]
+    pub hook_specific_output: Option<PostToolUseHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "permission-request.command.output")]
+pub(crate) struct PermissionRequestCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub hook_specific_output: Option<PermissionRequestHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "pre-compact.command.output")]
+pub(crate) struct PreCompactCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "post-compact.command.output")]
+pub(crate) struct PostCompactCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct PermissionRequestHookSpecificOutputWire {
+    #[schemars(schema_with = "permission_request_hook_event_name_schema")]
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub decision: Option<PermissionRequestDecisionWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct PermissionRequestDecisionWire {
+    pub behavior: PermissionRequestBehaviorWire,
+    /// Reserved for a future input-rewrite capability.
+    ///
+    /// PermissionRequest hooks currently fail closed if this field is present.
+    #[serde(default)]
+    pub updated_input: Option<Value>,
+    /// Reserved for a future permission-rewrite capability.
+    ///
+    /// PermissionRequest hooks currently fail closed if this field is present.
+    #[serde(default)]
+    pub updated_permissions: Option<Value>,
+    #[serde(default)]
+    pub message: Option<String>,
+    /// Reserved for future short-circuiting semantics.
+    ///
+    /// PermissionRequest hooks currently fail closed if this field is `true`.
+    #[serde(default)]
+    pub interrupt: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+pub(crate) enum PermissionRequestBehaviorWire {
+    #[serde(rename = "allow")]
+    Allow,
+    #[serde(rename = "deny")]
+    Deny,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct PostToolUseHookSpecificOutputWire {
+    #[schemars(schema_with = "post_tool_use_hook_event_name_schema")]
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub additional_context: Option<String>,
+    #[serde(default)]
+    #[serde(rename = "updatedMCPToolOutput")]
+    pub updated_mcp_tool_output: Option<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct PreToolUseHookSpecificOutputWire {
+    #[schemars(schema_with = "pre_tool_use_hook_event_name_schema")]
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub permission_decision: Option<PreToolUsePermissionDecisionWire>,
+    #[serde(default)]
+    pub permission_decision_reason: Option<String>,
+    #[serde(default)]
+    pub updated_input: Option<Value>,
+    #[serde(default)]
+    pub additional_context: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+pub(crate) enum PreToolUsePermissionDecisionWire {
+    #[serde(rename = "allow")]
+    Allow,
+    #[serde(rename = "deny")]
+    Deny,
+    #[serde(rename = "ask")]
+    Ask,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+pub(crate) enum PreToolUseDecisionWire {
+    #[serde(rename = "approve")]
+    Approve,
+    #[serde(rename = "block")]
+    Block,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "pre-tool-use.command.input")]
+pub(crate) struct PreToolUseCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "pre_tool_use_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub tool_input: Value,
+    pub tool_use_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "permission-request.command.input")]
+pub(crate) struct PermissionRequestCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "permission_request_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub tool_input: Value,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "post-tool-use.command.input")]
+pub(crate) struct PostToolUseCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "post_tool_use_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub tool_input: Value,
+    pub tool_response: Value,
+    pub tool_use_id: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "pre-compact.command.input")]
+pub(crate) struct PreCompactCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "pre_compact_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "compaction_trigger_schema")]
+    pub trigger: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "post-compact.command.input")]
+pub(crate) struct PostCompactCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "post_compact_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "compaction_trigger_schema")]
+    pub trigger: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "session-start.command.output")]
+pub(crate) struct SessionStartCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub hook_specific_output: Option<SessionStartHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct SessionStartHookSpecificOutputWire {
+    #[schemars(schema_with = "session_start_hook_event_name_schema")]
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub additional_context: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "subagent-start.command.output")]
+pub(crate) struct SubagentStartCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub hook_specific_output: Option<SubagentStartHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct SubagentStartHookSpecificOutputWire {
+    #[schemars(schema_with = "subagent_start_hook_event_name_schema")]
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub additional_context: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "user-prompt-submit.command.output")]
+pub(crate) struct UserPromptSubmitCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub decision: Option<BlockDecisionWire>,
+    #[serde(default)]
+    pub reason: Option<String>,
+    #[serde(default)]
+    pub hook_specific_output: Option<UserPromptSubmitHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct UserPromptSubmitHookSpecificOutputWire {
+    #[schemars(schema_with = "user_prompt_submit_hook_event_name_schema")]
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub additional_context: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "stop.command.output")]
+pub(crate) struct StopCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub decision: Option<BlockDecisionWire>,
+    /// Claude requires `reason` when `decision` is `block`; we enforce that
+    /// semantic rule during output parsing rather than in the JSON schema.
+    #[serde(default)]
+    pub reason: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "subagent-stop.command.output")]
+pub(crate) struct SubagentStopCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub decision: Option<BlockDecisionWire>,
+    /// Claude requires `reason` when `decision` is `block`; we enforce that
+    /// semantic rule during output parsing rather than in the JSON schema.
+    #[serde(default)]
+    pub reason: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "interrupt.command.output")]
+pub(crate) struct InterruptCommandOutputWire {
+    #[serde(default)]
+    pub system_message: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
+pub(crate) enum BlockDecisionWire {
+    #[serde(rename = "block")]
+    Block,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "session-start.command.input")]
+pub(crate) struct SessionStartCommandInput {
+    pub session_id: String,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "session_start_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    #[schemars(schema_with = "session_start_source_schema")]
+    pub source: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "session-end.command.input")]
+pub(crate) struct SessionEndCommandInput {
+    pub session_id: String,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "session_end_hook_event_name_schema")]
+    pub hook_event_name: String,
+    #[schemars(schema_with = "session_end_reason_schema")]
+    pub reason: String,
+}
+
+impl SessionStartCommandInput {
+    pub(crate) fn new(
+        session_id: impl Into<String>,
+        transcript_path: Option<PathBuf>,
+        cwd: impl Into<String>,
+        model: impl Into<String>,
+        permission_mode: impl Into<String>,
+        source: impl Into<String>,
+    ) -> Self {
+        Self {
+            session_id: session_id.into(),
+            transcript_path: NullableString::from_path(transcript_path),
+            cwd: cwd.into(),
+            hook_event_name: "SessionStart".to_string(),
+            model: model.into(),
+            permission_mode: permission_mode.into(),
+            source: source.into(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "subagent-start.command.input")]
+pub(crate) struct SubagentStartCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "subagent_start_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub agent_id: String,
+    pub agent_type: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "user-prompt-submit.command.input")]
+pub(crate) struct UserPromptSubmitCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent_type: Option<String>,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "user_prompt_submit_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub prompt: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "stop.command.input")]
+pub(crate) struct StopCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "stop_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub stop_hook_active: bool,
+    pub last_assistant_message: NullableString,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "subagent-stop.command.input")]
+pub(crate) struct SubagentStopCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    pub transcript_path: NullableString,
+    pub agent_transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "subagent_stop_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    pub stop_hook_active: bool,
+    pub agent_id: String,
+    pub agent_type: String,
+    pub last_assistant_message: NullableString,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "interrupt.command.input")]
+pub(crate) struct InterruptCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "interrupt_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+}
+
+pub fn write_schema_fixtures(schema_root: &Path) -> anyhow::Result<()> {
+    let generated_dir = schema_root.join(GENERATED_DIR);
+    ensure_empty_dir(&generated_dir)?;
+
+    write_schema(
+        &generated_dir.join(POST_TOOL_USE_INPUT_FIXTURE),
+        schema_json::<PostToolUseCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(POST_TOOL_USE_OUTPUT_FIXTURE),
+        schema_json::<PostToolUseCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(PERMISSION_REQUEST_INPUT_FIXTURE),
+        schema_json::<PermissionRequestCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(PERMISSION_REQUEST_OUTPUT_FIXTURE),
+        schema_json::<PermissionRequestCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(POST_COMPACT_INPUT_FIXTURE),
+        schema_json::<PostCompactCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(POST_COMPACT_OUTPUT_FIXTURE),
+        schema_json::<PostCompactCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(PRE_COMPACT_INPUT_FIXTURE),
+        schema_json::<PreCompactCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(PRE_COMPACT_OUTPUT_FIXTURE),
+        schema_json::<PreCompactCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(PRE_TOOL_USE_INPUT_FIXTURE),
+        schema_json::<PreToolUseCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(PRE_TOOL_USE_OUTPUT_FIXTURE),
+        schema_json::<PreToolUseCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SESSION_START_INPUT_FIXTURE),
+        schema_json::<SessionStartCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SESSION_START_OUTPUT_FIXTURE),
+        schema_json::<SessionStartCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SESSION_END_INPUT_FIXTURE),
+        schema_json::<SessionEndCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(USER_PROMPT_SUBMIT_INPUT_FIXTURE),
+        schema_json::<UserPromptSubmitCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(USER_PROMPT_SUBMIT_OUTPUT_FIXTURE),
+        schema_json::<UserPromptSubmitCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SUBAGENT_START_INPUT_FIXTURE),
+        schema_json::<SubagentStartCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SUBAGENT_START_OUTPUT_FIXTURE),
+        schema_json::<SubagentStartCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SUBAGENT_STOP_INPUT_FIXTURE),
+        schema_json::<SubagentStopCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(SUBAGENT_STOP_OUTPUT_FIXTURE),
+        schema_json::<SubagentStopCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(STOP_INPUT_FIXTURE),
+        schema_json::<StopCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(STOP_OUTPUT_FIXTURE),
+        schema_json::<StopCommandOutputWire>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(INTERRUPT_INPUT_FIXTURE),
+        schema_json::<InterruptCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(INTERRUPT_OUTPUT_FIXTURE),
+        schema_json::<InterruptCommandOutputWire>()?,
+    )?;
+
+    Ok(())
+}
+
+fn write_schema(path: &Path, json: Vec<u8>) -> anyhow::Result<()> {
+    std::fs::write(path, json)?;
+    Ok(())
+}
+
+fn ensure_empty_dir(dir: &Path) -> anyhow::Result<()> {
+    if dir.exists() {
+        std::fs::remove_dir_all(dir)?;
+    }
+    std::fs::create_dir_all(dir)?;
+    Ok(())
+}
+
+fn schema_json<T>() -> anyhow::Result<Vec<u8>>
+where
+    T: JsonSchema,
+{
+    let schema = schema_for_type::<T>();
+    let value = serde_json::to_value(schema)?;
+    let value = canonicalize_json(&value);
+    Ok(serde_json::to_vec_pretty(&value)?)
+}
+
+fn schema_for_type<T>() -> RootSchema
+where
+    T: JsonSchema,
+{
+    SchemaSettings::draft07()
+        .with(|settings| {
+            settings.option_add_null_type = false;
+        })
+        .into_generator()
+        .into_root_schema_for::<T>()
+}
+
+fn canonicalize_json(value: &Value) -> Value {
+    match value {
+        Value::Array(items) => Value::Array(items.iter().map(canonicalize_json).collect()),
+        Value::Object(map) => {
+            let mut entries: Vec<_> = map.iter().collect();
+            entries.sort_by_key(|(key, _)| *key);
+            let mut sorted = Map::with_capacity(map.len());
+            for (key, child) in entries {
+                sorted.insert(key.clone(), canonicalize_json(child));
+            }
+            Value::Object(sorted)
+        }
+        _ => value.clone(),
+    }
+}
+
+fn session_start_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("SessionStart")
+}
+
+fn session_end_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("SessionEnd")
+}
+
+fn session_end_reason_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("other")
+}
+
+fn post_tool_use_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("PostToolUse")
+}
+
+fn pre_compact_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("PreCompact")
+}
+
+fn post_compact_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("PostCompact")
+}
+
+fn pre_tool_use_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("PreToolUse")
+}
+
+fn permission_request_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("PermissionRequest")
+}
+
+fn user_prompt_submit_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("UserPromptSubmit")
+}
+
+fn subagent_start_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("SubagentStart")
+}
+
+fn subagent_stop_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("SubagentStop")
+}
+
+fn stop_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("Stop")
+}
+
+fn interrupt_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("Interrupt")
+}
+
+fn permission_mode_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_enum_schema(&[
+        "default",
+        "acceptEdits",
+        "plan",
+        "dontAsk",
+        "bypassPermissions",
+    ])
+}
+
+fn session_start_source_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_enum_schema(&["startup", "resume", "clear", "compact", "fork"])
+}
+
+fn compaction_trigger_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_enum_schema(&["manual", "auto"])
+}
+
+fn string_const_schema(value: &str) -> Schema {
+    let mut schema = SchemaObject {
+        instance_type: Some(InstanceType::String.into()),
+        ..Default::default()
+    };
+    schema.const_value = Some(Value::String(value.to_string()));
+    Schema::Object(schema)
+}
+
+fn string_enum_schema(values: &[&str]) -> Schema {
+    let mut schema = SchemaObject {
+        instance_type: Some(InstanceType::String.into()),
+        ..Default::default()
+    };
+    schema.enum_values = Some(
+        values
+            .iter()
+            .map(|value| Value::String((*value).to_string()))
+            .collect(),
+    );
+    Schema::Object(schema)
+}
+
+fn default_continue() -> bool {
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::INTERRUPT_INPUT_FIXTURE;
+    use super::INTERRUPT_OUTPUT_FIXTURE;
+    use super::InterruptCommandInput;
+    use super::NullableString;
+    use super::PERMISSION_REQUEST_INPUT_FIXTURE;
+    use super::PERMISSION_REQUEST_OUTPUT_FIXTURE;
+    use super::POST_COMPACT_INPUT_FIXTURE;
+    use super::POST_COMPACT_OUTPUT_FIXTURE;
+    use super::POST_TOOL_USE_INPUT_FIXTURE;
+    use super::POST_TOOL_USE_OUTPUT_FIXTURE;
+    use super::PRE_COMPACT_INPUT_FIXTURE;
+    use super::PRE_COMPACT_OUTPUT_FIXTURE;
+    use super::PRE_TOOL_USE_INPUT_FIXTURE;
+    use super::PRE_TOOL_USE_OUTPUT_FIXTURE;
+    use super::PermissionRequestCommandInput;
+    use super::PermissionRequestCommandOutputWire;
+    use super::PostCompactCommandInput;
+    use super::PostToolUseCommandInput;
+    use super::PostToolUseCommandOutputWire;
+    use super::PreCompactCommandInput;
+    use super::PreToolUseCommandInput;
+    use super::PreToolUseCommandOutputWire;
+    use super::SESSION_END_INPUT_FIXTURE;
+    use super::SESSION_START_INPUT_FIXTURE;
+    use super::SESSION_START_OUTPUT_FIXTURE;
+    use super::STOP_INPUT_FIXTURE;
+    use super::STOP_OUTPUT_FIXTURE;
+    use super::SUBAGENT_START_INPUT_FIXTURE;
+    use super::SUBAGENT_START_OUTPUT_FIXTURE;
+    use super::SUBAGENT_STOP_INPUT_FIXTURE;
+    use super::SUBAGENT_STOP_OUTPUT_FIXTURE;
+    use super::SessionStartCommandOutputWire;
+    use super::StopCommandInput;
+    use super::SubagentCommandInputFields;
+    use super::SubagentStartCommandInput;
+    use super::SubagentStartCommandOutputWire;
+    use super::SubagentStopCommandInput;
+    use super::USER_PROMPT_SUBMIT_INPUT_FIXTURE;
+    use super::USER_PROMPT_SUBMIT_OUTPUT_FIXTURE;
+    use super::UserPromptSubmitCommandInput;
+    use super::UserPromptSubmitCommandOutputWire;
+    use super::schema_json;
+    use super::write_schema_fixtures;
+    use crate::events::common::SubagentHookContext;
+    use pretty_assertions::assert_eq;
+    use schemars::JsonSchema;
+    use serde_json::Value;
+    use serde_json::json;
+    use tempfile::TempDir;
+
+    fn expected_fixture(name: &str) -> &'static str {
+        match name {
+            POST_TOOL_USE_INPUT_FIXTURE => {
+                include_str!("../schema/generated/post-tool-use.command.input.schema.json")
+            }
+            POST_TOOL_USE_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/post-tool-use.command.output.schema.json")
+            }
+            PERMISSION_REQUEST_INPUT_FIXTURE => {
+                include_str!("../schema/generated/permission-request.command.input.schema.json")
+            }
+            PERMISSION_REQUEST_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/permission-request.command.output.schema.json")
+            }
+            POST_COMPACT_INPUT_FIXTURE => {
+                include_str!("../schema/generated/post-compact.command.input.schema.json")
+            }
+            POST_COMPACT_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/post-compact.command.output.schema.json")
+            }
+            PRE_COMPACT_INPUT_FIXTURE => {
+                include_str!("../schema/generated/pre-compact.command.input.schema.json")
+            }
+            PRE_COMPACT_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/pre-compact.command.output.schema.json")
+            }
+            PRE_TOOL_USE_INPUT_FIXTURE => {
+                include_str!("../schema/generated/pre-tool-use.command.input.schema.json")
+            }
+            PRE_TOOL_USE_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/pre-tool-use.command.output.schema.json")
+            }
+            SESSION_START_INPUT_FIXTURE => {
+                include_str!("../schema/generated/session-start.command.input.schema.json")
+            }
+            SESSION_START_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/session-start.command.output.schema.json")
+            }
+            SESSION_END_INPUT_FIXTURE => {
+                include_str!("../schema/generated/session-end.command.input.schema.json")
+            }
+            USER_PROMPT_SUBMIT_INPUT_FIXTURE => {
+                include_str!("../schema/generated/user-prompt-submit.command.input.schema.json")
+            }
+            USER_PROMPT_SUBMIT_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/user-prompt-submit.command.output.schema.json")
+            }
+            SUBAGENT_START_INPUT_FIXTURE => {
+                include_str!("../schema/generated/subagent-start.command.input.schema.json")
+            }
+            SUBAGENT_START_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/subagent-start.command.output.schema.json")
+            }
+            SUBAGENT_STOP_INPUT_FIXTURE => {
+                include_str!("../schema/generated/subagent-stop.command.input.schema.json")
+            }
+            SUBAGENT_STOP_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/subagent-stop.command.output.schema.json")
+            }
+            STOP_INPUT_FIXTURE => {
+                include_str!("../schema/generated/stop.command.input.schema.json")
+            }
+            STOP_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/stop.command.output.schema.json")
+            }
+            INTERRUPT_INPUT_FIXTURE => {
+                include_str!("../schema/generated/interrupt.command.input.schema.json")
+            }
+            INTERRUPT_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/interrupt.command.output.schema.json")
+            }
+            _ => panic!("unexpected fixture name: {name}"),
+        }
+    }
+
+    fn normalize_newlines(value: &str) -> String {
+        value.replace("\r\n", "\n")
+    }
+
+    fn assert_output_hook_event_name_const<T: JsonSchema>(definition: &str, expected: &str) {
+        let schema: Value =
+            serde_json::from_slice(&schema_json::<T>().expect("serialize hook output schema"))
+                .expect("parse hook output schema");
+
+        assert_eq!(
+            schema["definitions"][definition]["properties"]["hookEventName"],
+            json!({
+                "const": expected,
+                "type": "string",
+            })
+        );
+    }
+
+    #[test]
+    fn generated_hook_schemas_match_fixtures() {
+        let temp_dir = TempDir::new().expect("create temp dir");
+        let schema_root = temp_dir.path().join("schema");
+        write_schema_fixtures(&schema_root).expect("write generated hook schemas");
+
+        for fixture in [
+            POST_TOOL_USE_INPUT_FIXTURE,
+            POST_TOOL_USE_OUTPUT_FIXTURE,
+            PERMISSION_REQUEST_INPUT_FIXTURE,
+            PERMISSION_REQUEST_OUTPUT_FIXTURE,
+            POST_COMPACT_INPUT_FIXTURE,
+            POST_COMPACT_OUTPUT_FIXTURE,
+            PRE_COMPACT_INPUT_FIXTURE,
+            PRE_COMPACT_OUTPUT_FIXTURE,
+            PRE_TOOL_USE_INPUT_FIXTURE,
+            PRE_TOOL_USE_OUTPUT_FIXTURE,
+            SESSION_START_INPUT_FIXTURE,
+            SESSION_START_OUTPUT_FIXTURE,
+            SESSION_END_INPUT_FIXTURE,
+            USER_PROMPT_SUBMIT_INPUT_FIXTURE,
+            USER_PROMPT_SUBMIT_OUTPUT_FIXTURE,
+            SUBAGENT_START_INPUT_FIXTURE,
+            SUBAGENT_START_OUTPUT_FIXTURE,
+            SUBAGENT_STOP_INPUT_FIXTURE,
+            SUBAGENT_STOP_OUTPUT_FIXTURE,
+            STOP_INPUT_FIXTURE,
+            STOP_OUTPUT_FIXTURE,
+            INTERRUPT_INPUT_FIXTURE,
+            INTERRUPT_OUTPUT_FIXTURE,
+        ] {
+            let expected = normalize_newlines(expected_fixture(fixture));
+            let actual = std::fs::read_to_string(schema_root.join("generated").join(fixture))
+                .unwrap_or_else(|err| panic!("read generated schema {fixture}: {err}"));
+            let actual = normalize_newlines(&actual);
+            assert_eq!(expected, actual, "fixture should match generated schema");
+        }
+    }
+
+    #[test]
+    fn hook_specific_output_event_names_are_event_specific_in_output_schemas() {
+        assert_output_hook_event_name_const::<PermissionRequestCommandOutputWire>(
+            "PermissionRequestHookSpecificOutputWire",
+            "PermissionRequest",
+        );
+        assert_output_hook_event_name_const::<PostToolUseCommandOutputWire>(
+            "PostToolUseHookSpecificOutputWire",
+            "PostToolUse",
+        );
+        assert_output_hook_event_name_const::<PreToolUseCommandOutputWire>(
+            "PreToolUseHookSpecificOutputWire",
+            "PreToolUse",
+        );
+        assert_output_hook_event_name_const::<SessionStartCommandOutputWire>(
+            "SessionStartHookSpecificOutputWire",
+            "SessionStart",
+        );
+        assert_output_hook_event_name_const::<SubagentStartCommandOutputWire>(
+            "SubagentStartHookSpecificOutputWire",
+            "SubagentStart",
+        );
+        assert_output_hook_event_name_const::<UserPromptSubmitCommandOutputWire>(
+            "UserPromptSubmitHookSpecificOutputWire",
+            "UserPromptSubmit",
+        );
+    }
+
+    #[test]
+    fn turn_scoped_hook_inputs_include_codex_turn_id_extension() {
+        // Codex intentionally diverges from Claude's public hook docs here so
+        // internal hook consumers can key off the active turn.
+        let pre_tool_use: Value = serde_json::from_slice(
+            &schema_json::<PreToolUseCommandInput>().expect("serialize pre tool use input schema"),
+        )
+        .expect("parse pre tool use input schema");
+        let post_tool_use: Value = serde_json::from_slice(
+            &schema_json::<PostToolUseCommandInput>()
+                .expect("serialize post tool use input schema"),
+        )
+        .expect("parse post tool use input schema");
+        let pre_compact: Value = serde_json::from_slice(
+            &schema_json::<PreCompactCommandInput>().expect("serialize pre compact input schema"),
+        )
+        .expect("parse pre compact input schema");
+        let post_compact: Value = serde_json::from_slice(
+            &schema_json::<PostCompactCommandInput>().expect("serialize post compact input schema"),
+        )
+        .expect("parse post compact input schema");
+        let permission_request: Value = serde_json::from_slice(
+            &schema_json::<PermissionRequestCommandInput>()
+                .expect("serialize permission request input schema"),
+        )
+        .expect("parse permission request input schema");
+        let user_prompt_submit: Value = serde_json::from_slice(
+            &schema_json::<UserPromptSubmitCommandInput>()
+                .expect("serialize user prompt submit input schema"),
+        )
+        .expect("parse user prompt submit input schema");
+        let subagent_start: Value = serde_json::from_slice(
+            &schema_json::<SubagentStartCommandInput>()
+                .expect("serialize subagent start input schema"),
+        )
+        .expect("parse subagent start input schema");
+        let subagent_stop: Value = serde_json::from_slice(
+            &schema_json::<SubagentStopCommandInput>()
+                .expect("serialize subagent stop input schema"),
+        )
+        .expect("parse subagent stop input schema");
+        let stop: Value = serde_json::from_slice(
+            &schema_json::<StopCommandInput>().expect("serialize stop input schema"),
+        )
+        .expect("parse stop input schema");
+        let interrupt: Value = serde_json::from_slice(
+            &schema_json::<InterruptCommandInput>().expect("serialize interrupt input schema"),
+        )
+        .expect("parse interrupt input schema");
+
+        for schema in [
+            &pre_tool_use,
+            &permission_request,
+            &post_tool_use,
+            &pre_compact,
+            &post_compact,
+            &user_prompt_submit,
+            &subagent_start,
+            &subagent_stop,
+            &stop,
+            &interrupt,
+        ] {
+            assert_eq!(schema["properties"]["turn_id"]["type"], "string");
+            assert!(
+                schema["required"]
+                    .as_array()
+                    .expect("schema required fields")
+                    .contains(&Value::String("turn_id".to_string()))
+            );
+        }
+    }
+
+    #[test]
+    fn subagent_context_fields_are_optional_for_hooks_that_run_inside_subagents() {
+        let schemas = [
+            schema_json::<PreToolUseCommandInput>().expect("serialize pre tool use input schema"),
+            schema_json::<PermissionRequestCommandInput>()
+                .expect("serialize permission request input schema"),
+            schema_json::<PostToolUseCommandInput>().expect("serialize post tool use input schema"),
+            schema_json::<PreCompactCommandInput>().expect("serialize pre compact input schema"),
+            schema_json::<PostCompactCommandInput>().expect("serialize post compact input schema"),
+            schema_json::<UserPromptSubmitCommandInput>()
+                .expect("serialize user prompt submit input schema"),
+        ];
+
+        for schema in schemas {
+            let schema: Value = serde_json::from_slice(&schema).expect("parse hook input schema");
+            assert_eq!(schema["properties"]["agent_id"]["type"], "string");
+            assert_eq!(schema["properties"]["agent_type"]["type"], "string");
+            let required = schema["required"]
+                .as_array()
+                .expect("schema required fields");
+            assert!(!required.contains(&Value::String("agent_id".to_string())));
+            assert!(!required.contains(&Value::String("agent_type".to_string())));
+        }
+    }
+
+    #[test]
+    fn subagent_context_fields_serialize_flat_and_omit_when_absent() {
+        let subagent = SubagentCommandInputFields::from(Some(&SubagentHookContext {
+            agent_id: "agent-1".to_string(),
+            agent_type: "worker".to_string(),
+        }));
+        let input = PreToolUseCommandInput {
+            session_id: "session-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            agent_id: subagent.agent_id,
+            agent_type: subagent.agent_type,
+            transcript_path: NullableString::from_path(/*path*/ None),
+            cwd: "/tmp".to_string(),
+            hook_event_name: "PreToolUse".to_string(),
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            tool_input: json!({ "command": "echo hello" }),
+            tool_use_id: "tool-1".to_string(),
+        };
+
+        assert_eq!(
+            serde_json::to_value(input).expect("serialize subagent hook input"),
+            json!({
+                "session_id": "session-1",
+                "turn_id": "turn-1",
+                "agent_id": "agent-1",
+                "agent_type": "worker",
+                "transcript_path": null,
+                "cwd": "/tmp",
+                "hook_event_name": "PreToolUse",
+                "model": "gpt-test",
+                "permission_mode": "default",
+                "tool_name": "Bash",
+                "tool_input": { "command": "echo hello" },
+                "tool_use_id": "tool-1",
+            })
+        );
+
+        let root_input = PreToolUseCommandInput {
+            session_id: "session-1".to_string(),
+            turn_id: "turn-1".to_string(),
+            agent_id: None,
+            agent_type: None,
+            transcript_path: NullableString::from_path(/*path*/ None),
+            cwd: "/tmp".to_string(),
+            hook_event_name: "PreToolUse".to_string(),
+            model: "gpt-test".to_string(),
+            permission_mode: "default".to_string(),
+            tool_name: "Bash".to_string(),
+            tool_input: json!({ "command": "echo hello" }),
+            tool_use_id: "tool-1".to_string(),
+        };
+        let root_input = serde_json::to_value(root_input).expect("serialize root hook input");
+        assert_eq!(root_input.get("agent_id"), None);
+        assert_eq!(root_input.get("agent_type"), None);
+    }
+}
diff --git a/codex-rs/hooks/src/types.rs b/codex-rs/hooks/src/types.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6639308aa0a6637ed00fa2ceabe004efde450ba1
--- /dev/null
+++ b/codex-rs/hooks/src/types.rs
@@ -0,0 +1,152 @@
+use std::sync::Arc;
+
+use chrono::DateTime;
+use chrono::SecondsFormat;
+use chrono::Utc;
+use codex_protocol::ThreadId;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use futures::future::BoxFuture;
+use serde::Serialize;
+use serde::Serializer;
+
+pub type HookFn = Arc<dyn for<'a> Fn(&'a HookPayload) -> BoxFuture<'a, HookResult> + Send + Sync>;
+
+#[derive(Debug)]
+pub enum HookResult {
+    /// Success: hook completed successfully.
+    Success,
+    /// FailedContinue: hook failed, but other subsequent hooks should still execute and the
+    /// operation should continue.
+    FailedContinue(Box<dyn std::error::Error + Send + Sync + 'static>),
+    /// FailedAbort: hook failed, other subsequent hooks should not execute, and the operation
+    /// should be aborted.
+    FailedAbort(Box<dyn std::error::Error + Send + Sync + 'static>),
+}
+
+impl HookResult {
+    pub fn should_abort_operation(&self) -> bool {
+        matches!(self, Self::FailedAbort(_))
+    }
+}
+
+#[derive(Debug)]
+pub struct HookResponse {
+    pub hook_name: String,
+    pub result: HookResult,
+}
+
+#[derive(Clone)]
+pub struct Hook {
+    pub name: String,
+    pub func: HookFn,
+}
+
+impl Default for Hook {
+    fn default() -> Self {
+        Self {
+            name: "default".to_string(),
+            func: Arc::new(|_| Box::pin(async { HookResult::Success })),
+        }
+    }
+}
+
+impl Hook {
+    pub async fn execute(&self, payload: &HookPayload) -> HookResponse {
+        HookResponse {
+            hook_name: self.name.clone(),
+            result: (self.func)(payload).await,
+        }
+    }
+}
+
+#[derive(Debug, Serialize, Clone)]
+#[serde(rename_all = "snake_case")]
+pub struct HookPayload {
+    pub session_id: ThreadId,
+    pub cwd: AbsolutePathBuf,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub client: Option<String>,
+    #[serde(serialize_with = "serialize_triggered_at")]
+    pub triggered_at: DateTime<Utc>,
+    pub hook_event: HookEvent,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub struct HookEventAfterAgent {
+    pub thread_id: ThreadId,
+    pub turn_id: String,
+    pub input_messages: Vec<String>,
+    pub last_assistant_message: Option<String>,
+}
+
+fn serialize_triggered_at<S>(value: &DateTime<Utc>, serializer: S) -> Result<S::Ok, S::Error>
+where
+    S: Serializer,
+{
+    serializer.serialize_str(&value.to_rfc3339_opts(SecondsFormat::Secs, true))
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "event_type", rename_all = "snake_case")]
+pub enum HookEvent {
+    AfterAgent {
+        #[serde(flatten)]
+        event: HookEventAfterAgent,
+    },
+}
+
+#[cfg(test)]
+mod tests {
+    use chrono::TimeZone;
+    use chrono::Utc;
+    use codex_protocol::ThreadId;
+    use codex_utils_absolute_path::test_support::PathBufExt;
+    use codex_utils_absolute_path::test_support::test_path_buf;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    use super::HookEvent;
+    use super::HookEventAfterAgent;
+    use super::HookPayload;
+
+    #[test]
+    fn hook_payload_serializes_stable_wire_shape() {
+        let session_id = ThreadId::new();
+        let thread_id = ThreadId::new();
+        let cwd = test_path_buf("/tmp").abs();
+        let payload = HookPayload {
+            session_id,
+            cwd: cwd.clone(),
+            client: None,
+            triggered_at: Utc
+                .with_ymd_and_hms(2025, 1, 1, 0, 0, 0)
+                .single()
+                .expect("valid timestamp"),
+            hook_event: HookEvent::AfterAgent {
+                event: HookEventAfterAgent {
+                    thread_id,
+                    turn_id: "turn-1".to_string(),
+                    input_messages: vec!["hello".to_string()],
+                    last_assistant_message: Some("hi".to_string()),
+                },
+            },
+        };
+
+        let actual = serde_json::to_value(payload).expect("serialize hook payload");
+        let expected = json!({
+            "session_id": session_id.to_string(),
+            "cwd": cwd.display().to_string(),
+            "triggered_at": "2025-01-01T00:00:00Z",
+            "hook_event": {
+                "event_type": "after_agent",
+                "thread_id": thread_id.to_string(),
+                "turn_id": "turn-1",
+                "input_messages": ["hello"],
+                "last_assistant_message": "hi",
+            },
+        });
+
+        assert_eq!(actual, expected);
+    }
+}
diff --git a/codex-rs/http-client/src/bin/custom_ca_probe.rs b/codex-rs/http-client/src/bin/custom_ca_probe.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c8db21510d6a947c7fcaa419b2932b4198369537
--- /dev/null
+++ b/codex-rs/http-client/src/bin/custom_ca_probe.rs
@@ -0,0 +1,100 @@
+//! Helper binary for exercising shared custom CA environment handling in tests.
+//!
+//! The shared reqwest client honors `CODEX_CA_CERTIFICATE` and `SSL_CERT_FILE`, but those
+//! environment variables are process-global and unsafe to mutate in parallel test execution. This
+//! probe keeps the behavior under test while letting integration tests (`tests/ca_env.rs`) set
+//! env vars per-process, proving:
+//!
+//! - env precedence is respected,
+//! - multi-cert PEM bundles load,
+//! - error messages guide users when CA files are invalid.
+//! - optional HTTPS probes can complete a request through the constructed client.
+//!
+//! The detailed explanation of what "hermetic" means here lives in `codex_http_client::custom_ca`.
+//! This binary exists so the tests can exercise
+//! [`codex_http_client::build_reqwest_client_for_subprocess_tests`] in a separate process without
+//! duplicating client-construction logic.
+
+use std::env;
+use std::process;
+use std::time::Duration;
+
+const PROBE_TLS13_ENV: &str = "CODEX_CUSTOM_CA_PROBE_TLS13";
+const PROBE_PROXY_ENV: &str = "CODEX_CUSTOM_CA_PROBE_PROXY";
+const PROBE_URL_ENV: &str = "CODEX_CUSTOM_CA_PROBE_URL";
+
+fn main() {
+    let runtime = match tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+    {
+        Ok(runtime) => runtime,
+        Err(error) => {
+            eprintln!("failed to create probe runtime: {error}");
+            process::exit(1);
+        }
+    };
+
+    match runtime.block_on(run_probe()) {
+        Ok(()) => println!("ok"),
+        Err(error) => {
+            eprintln!("{error}");
+            process::exit(1);
+        }
+    }
+}
+
+async fn run_probe() -> Result<(), String> {
+    let proxy_url = env::var(PROBE_PROXY_ENV).ok();
+    let target_url = env::var(PROBE_URL_ENV).ok();
+    let mut builder = reqwest::Client::builder();
+    if target_url.is_some() {
+        builder = builder.timeout(Duration::from_secs(5));
+    }
+    if env::var_os(PROBE_TLS13_ENV).is_some() {
+        builder = builder.min_tls_version(reqwest::tls::Version::TLS_1_3);
+    }
+
+    let client = build_probe_client(builder, proxy_url.as_deref())?;
+    if let Some(url) = target_url {
+        post_probe_request(&client, &url).await?;
+    }
+    Ok(())
+}
+
+fn build_probe_client(
+    builder: reqwest::ClientBuilder,
+    proxy_url: Option<&str>,
+) -> Result<reqwest::Client, String> {
+    if let Some(proxy_url) = proxy_url {
+        let proxy = reqwest::Proxy::https(proxy_url)
+            .map_err(|error| format!("failed to configure probe proxy {proxy_url}: {error}"))?;
+        return codex_http_client::build_reqwest_client_with_custom_ca(builder.proxy(proxy))
+            .map_err(|error| error.to_string());
+    }
+
+    codex_http_client::build_reqwest_client_for_subprocess_tests(builder)
+        .map_err(|error| error.to_string())
+}
+
+async fn post_probe_request(client: &reqwest::Client, url: &str) -> Result<(), String> {
+    let response = client
+        .post(url)
+        .header("Content-Type", "application/x-www-form-urlencoded")
+        .body("grant_type=authorization_code&code=test")
+        .send()
+        .await
+        .map_err(|error| format!("probe request failed: {error:?}"))?;
+    let status = response.status();
+    let body = response
+        .text()
+        .await
+        .map_err(|error| format!("failed to read probe response body: {error}"))?;
+    if !status.is_success() {
+        return Err(format!("probe request returned {status}: {body}"));
+    }
+    if body != "ok" {
+        return Err(format!("probe response body mismatch: {body}"));
+    }
+    Ok(())
+}
diff --git a/codex-rs/http-client/src/chatgpt_cloudflare_cookies.rs b/codex-rs/http-client/src/chatgpt_cloudflare_cookies.rs
new file mode 100644
index 0000000000000000000000000000000000000000..69124e031561e08d1e396f94eb2470891c297752
--- /dev/null
+++ b/codex-rs/http-client/src/chatgpt_cloudflare_cookies.rs
@@ -0,0 +1,409 @@
+use std::sync::Arc;
+use std::sync::LazyLock;
+
+use reqwest::cookie::CookieStore;
+use reqwest::cookie::Jar;
+use reqwest::header::HeaderValue;
+
+use crate::chatgpt_hosts::is_allowed_chatgpt_host;
+
+// WARNING: this HTTP cookie store is process-global and may be shared across auth contexts.
+// It must only ever contain Cloudflare infrastructure cookies and the `__oailb`
+// routing cookie. Never extend this store to persist ChatGPT account, session,
+// auth, or other user-specific cookie data.
+static SHARED_CHATGPT_CLOUDFLARE_COOKIE_STORE: LazyLock<Arc<ChatGptCloudflareCookieStore>> =
+    LazyLock::new(|| Arc::new(ChatGptCloudflareCookieStore::default()));
+
+#[derive(Debug, Default)]
+struct ChatGptCloudflareCookieStore {
+    jar: Jar,
+}
+
+pub(crate) struct ChatGptCookieStore {
+    cloudflare: Arc<ChatGptCloudflareCookieStore>,
+    cookies: Vec<HeaderValue>,
+}
+
+impl ChatGptCookieStore {
+    pub(crate) fn new(cookies: Vec<HeaderValue>) -> Self {
+        Self {
+            cloudflare: Arc::clone(&SHARED_CHATGPT_CLOUDFLARE_COOKIE_STORE),
+            cookies,
+        }
+    }
+
+    pub(crate) fn configured_cookies(&self) -> &[HeaderValue] {
+        &self.cookies
+    }
+}
+
+impl CookieStore for ChatGptCloudflareCookieStore {
+    fn set_cookies(
+        &self,
+        cookie_headers: &mut dyn Iterator<Item = &HeaderValue>,
+        url: &reqwest::Url,
+    ) {
+        if !is_chatgpt_cookie_url(url) {
+            return;
+        }
+
+        let mut cloudflare_cookie_headers =
+            cookie_headers.filter(|header| is_allowed_cloudflare_set_cookie_header(header));
+        self.jar.set_cookies(&mut cloudflare_cookie_headers, url);
+    }
+
+    fn cookies(&self, url: &reqwest::Url) -> Option<HeaderValue> {
+        if is_chatgpt_cookie_url(url) {
+            self.jar.cookies(url).and_then(only_cloudflare_cookies)
+        } else {
+            None
+        }
+    }
+}
+
+impl CookieStore for ChatGptCookieStore {
+    fn set_cookies(
+        &self,
+        cookie_headers: &mut dyn Iterator<Item = &HeaderValue>,
+        url: &reqwest::Url,
+    ) {
+        self.cloudflare.set_cookies(cookie_headers, url);
+    }
+
+    fn cookies(&self, url: &reqwest::Url) -> Option<HeaderValue> {
+        if !is_chatgpt_cookie_url(url) {
+            return self.cloudflare.cookies(url);
+        }
+        let cloudflare = self.cloudflare.cookies(url);
+        let mut sensitive = cloudflare.as_ref().is_some_and(HeaderValue::is_sensitive);
+        let mut cookies = cloudflare
+            .map(|cloudflare| cloudflare.as_bytes().to_vec())
+            .unwrap_or_default();
+        for cookie in &self.cookies {
+            sensitive |= cookie.is_sensitive();
+            if !cookies.is_empty() {
+                cookies.extend_from_slice(b"; ");
+            }
+            cookies.extend_from_slice(cookie.as_bytes());
+        }
+        if cookies.is_empty() {
+            None
+        } else {
+            let mut header = HeaderValue::from_bytes(&cookies).ok()?;
+            header.set_sensitive(sensitive);
+            Some(header)
+        }
+    }
+}
+
+/// Adds the process-local ChatGPT infrastructure cookie jar used by Codex HTTP clients.
+///
+/// WARNING: this jar is global within the process. It is only acceptable because it hardcodes a
+/// small allowlist of Cloudflare cookie names plus `__oailb` for routing, and refuses all other
+/// ChatGPT cookies. Do not store ChatGPT account, session, auth, or other user-specific cookies
+/// here. If a future caller needs those cookies, the store must be scoped to the auth/session
+/// owner instead of shared globally.
+pub fn with_chatgpt_cloudflare_cookie_store(
+    builder: reqwest::ClientBuilder,
+) -> reqwest::ClientBuilder {
+    builder.cookie_provider(Arc::clone(&SHARED_CHATGPT_CLOUDFLARE_COOKIE_STORE))
+}
+
+fn is_chatgpt_cookie_url(url: &reqwest::Url) -> bool {
+    match url.scheme() {
+        "https" => {}
+        _ => return false,
+    }
+
+    let Some(host) = url.host_str() else {
+        return false;
+    };
+
+    is_allowed_chatgpt_host(host)
+}
+
+fn is_allowed_cloudflare_set_cookie_header(header: &HeaderValue) -> bool {
+    header
+        .to_str()
+        .ok()
+        .and_then(set_cookie_name)
+        .is_some_and(is_allowed_cloudflare_cookie_name)
+}
+
+fn set_cookie_name(header: &str) -> Option<&str> {
+    let (name, _) = header.split_once('=')?;
+    let name = name.trim();
+    (!name.is_empty()).then_some(name)
+}
+
+fn only_cloudflare_cookies(header: HeaderValue) -> Option<HeaderValue> {
+    let header = header.to_str().ok()?;
+    let cookies = header
+        .split(';')
+        .filter_map(|cookie| {
+            let cookie = cookie.trim();
+            let name = cookie.split_once('=')?.0.trim();
+            is_allowed_cloudflare_cookie_name(name).then_some(cookie)
+        })
+        .collect::<Vec<_>>()
+        .join("; ");
+
+    if cookies.is_empty() {
+        None
+    } else {
+        HeaderValue::from_str(&cookies).ok()
+    }
+}
+
+fn is_allowed_cloudflare_cookie_name(name: &str) -> bool {
+    // `__oailb` is an OpenAI infrastructure routing cookie, not an authentication cookie.
+    // Keep this allowlist aligned with Cloudflare's documented service cookies:
+    // https://developers.cloudflare.com/fundamentals/reference/policies-compliances/cloudflare-cookies/
+    matches!(
+        name,
+        "__cf_bm"
+            | "__cflb"
+            | "__cfruid"
+            | "__cfseq"
+            | "__cfwaitingroom"
+            | "__oailb"
+            | "_cfuvid"
+            | "cf_clearance"
+            | "cf_ob_info"
+            | "cf_use_ob"
+    ) || name.starts_with("cf_chl_")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use reqwest::cookie::CookieStore;
+
+    #[test]
+    fn additional_cookies_use_current_path_scoped_cloudflare_cookies() {
+        let cloudflare = Arc::new(ChatGptCloudflareCookieStore::default());
+        let mut sensitive_cookie = HeaderValue::from_static("additional=true");
+        sensitive_cookie.set_sensitive(true);
+        let store = ChatGptCookieStore {
+            cloudflare: Arc::clone(&cloudflare),
+            cookies: vec![
+                sensitive_cookie,
+                HeaderValue::from_static("another=enabled"),
+            ],
+        };
+        let first_url = reqwest::Url::parse("https://cookies.chatgpt.com/a").unwrap();
+        let second_url = reqwest::Url::parse("https://cookies.chatgpt.com/b").unwrap();
+        let affinity = HeaderValue::from_static("__cflb=current; Path=/a; Secure");
+        cloudflare.set_cookies(&mut std::iter::once(&affinity), &first_url);
+
+        assert_eq!(
+            store.cookies(&first_url),
+            Some(HeaderValue::from_static(
+                "__cflb=current; additional=true; another=enabled"
+            ))
+        );
+        assert!(store.cookies(&first_url).unwrap().is_sensitive());
+        assert_eq!(
+            store.cookies(&second_url),
+            Some(HeaderValue::from_static("additional=true; another=enabled"))
+        );
+
+        let expired = HeaderValue::from_static("__cflb=; Max-Age=0; Path=/a; Secure");
+        store.set_cookies(&mut std::iter::once(&expired), &first_url);
+        assert_eq!(
+            store.cookies(&first_url),
+            Some(HeaderValue::from_static("additional=true; another=enabled"))
+        );
+    }
+
+    #[test]
+    fn additional_cookies_are_restricted_to_https_chatgpt_hosts() {
+        let store = ChatGptCookieStore {
+            cloudflare: Arc::new(ChatGptCloudflareCookieStore::default()),
+            cookies: vec![HeaderValue::from_static("additional=true")],
+        };
+
+        for url in ["http://chatgpt.com/a", "https://api.openai.com/a"] {
+            let url = reqwest::Url::parse(url).unwrap();
+            assert_eq!(store.cookies(&url), None);
+        }
+        let url = reqwest::Url::parse("https://chatgpt.com/a").unwrap();
+        assert_eq!(
+            store.cookies(&url),
+            Some(HeaderValue::from_static("additional=true"))
+        );
+        assert!(!store.cookies(&url).unwrap().is_sensitive());
+    }
+
+    #[test]
+    fn stores_and_returns_cloudflare_cookies_for_chatgpt_hosts() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let url = reqwest::Url::parse("https://chatgpt.com/backend-api/codex/responses").unwrap();
+        let load_balancer = HeaderValue::from_static("__cflb=west; Path=/; Secure; HttpOnly");
+        let cfuvid = HeaderValue::from_static("_cfuvid=visitor; Path=/; Secure; HttpOnly");
+        let clearance =
+            HeaderValue::from_static("cf_clearance=clearance; Path=/; Secure; HttpOnly");
+
+        store.set_cookies(&mut [&load_balancer, &cfuvid, &clearance].into_iter(), &url);
+
+        let mut cookies = store
+            .cookies(&url)
+            .and_then(|value| value.to_str().ok().map(str::to_string))
+            .map(|header| {
+                header
+                    .split("; ")
+                    .map(str::to_string)
+                    .collect::<Vec<String>>()
+            })
+            .unwrap_or_default();
+        cookies.sort();
+        assert_eq!(
+            cookies,
+            vec![
+                "__cflb=west".to_string(),
+                "_cfuvid=visitor".to_string(),
+                "cf_clearance=clearance".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn oailb_cookies_are_replayed_with_scope_and_expiration() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let url = reqwest::Url::parse("https://chatgpt.com/backend-api/codex/responses").unwrap();
+        let cookie = HeaderValue::from_static(
+            "__oailb=route; Path=/backend-api; Max-Age=3600; Secure; HttpOnly; SameSite=Lax",
+        );
+        store.set_cookies(&mut std::iter::once(&cookie), &url);
+
+        let followup_url = reqwest::Url::parse("https://chatgpt.com/backend-api/ps/mcp").unwrap();
+        assert_eq!(
+            store.cookies(&followup_url),
+            Some(HeaderValue::from_static("__oailb=route"))
+        );
+        for outside_scope in [
+            "https://chatgpt.com/",
+            "https://other.chatgpt.com/backend-api/ps/mcp",
+            "https://api.openai.com/backend-api/ps/mcp",
+            "http://chatgpt.com/backend-api/ps/mcp",
+        ] {
+            let outside_scope = reqwest::Url::parse(outside_scope).unwrap();
+            assert_eq!(store.cookies(&outside_scope), None);
+        }
+
+        let expired = HeaderValue::from_static(
+            "__oailb=; Path=/backend-api; Max-Age=0; Secure; HttpOnly; SameSite=Lax",
+        );
+        store.set_cookies(&mut std::iter::once(&expired), &url);
+        assert_eq!(store.cookies(&followup_url), None);
+    }
+
+    #[test]
+    fn ignores_non_chatgpt_cookies() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let url = reqwest::Url::parse("https://api.openai.com/v1/responses").unwrap();
+        let set_cookie = HeaderValue::from_static("_cfuvid=visitor; Path=/; Secure; HttpOnly");
+
+        store.set_cookies(&mut std::iter::once(&set_cookie), &url);
+
+        assert_eq!(store.cookies(&url), None);
+    }
+
+    #[test]
+    fn ignores_non_cloudflare_cookies_for_chatgpt_hosts() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let url = reqwest::Url::parse("https://chatgpt.com/backend-api/codex/responses").unwrap();
+        let set_cookie = HeaderValue::from_static(
+            "__Secure-next-auth.session-token=secret; Path=/; Secure; HttpOnly",
+        );
+
+        store.set_cookies(&mut std::iter::once(&set_cookie), &url);
+
+        assert_eq!(store.cookies(&url), None);
+    }
+
+    #[test]
+    fn ignores_mixed_non_cloudflare_cookies_for_chatgpt_hosts() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let url = reqwest::Url::parse("https://chatgpt.com/backend-api/codex/responses").unwrap();
+        let cfuvid = HeaderValue::from_static("_cfuvid=visitor; Path=/; Secure; HttpOnly");
+        let account_cookie =
+            HeaderValue::from_static("chatgpt_session=secret; Path=/; Secure; HttpOnly");
+
+        store.set_cookies(&mut [&cfuvid, &account_cookie].into_iter(), &url);
+
+        assert_eq!(
+            store
+                .cookies(&url)
+                .and_then(|value| value.to_str().ok().map(str::to_string)),
+            Some("_cfuvid=visitor".to_string())
+        );
+    }
+
+    #[test]
+    fn does_not_return_chatgpt_cloudflare_cookies_for_other_hosts() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let chatgpt_url =
+            reqwest::Url::parse("https://chatgpt.com/backend-api/codex/responses").unwrap();
+        let api_url = reqwest::Url::parse("https://api.openai.com/v1/responses").unwrap();
+        let set_cookie = HeaderValue::from_static("_cfuvid=visitor; Path=/; Secure; HttpOnly");
+
+        store.set_cookies(&mut std::iter::once(&set_cookie), &chatgpt_url);
+
+        assert_eq!(store.cookies(&api_url), None);
+    }
+
+    #[test]
+    fn rejects_plain_http_chatgpt_cookie_urls() {
+        let store = ChatGptCloudflareCookieStore::default();
+        let http_url = reqwest::Url::parse("http://chatgpt.com/backend-api/codex/responses")
+            .expect("URL should parse");
+        let https_url = reqwest::Url::parse("https://chatgpt.com/backend-api/codex/responses")
+            .expect("URL should parse");
+        let set_cookie = HeaderValue::from_static("_cfuvid=visitor; Path=/; Secure; HttpOnly");
+
+        store.set_cookies(&mut std::iter::once(&set_cookie), &http_url);
+
+        assert_eq!(store.cookies(&http_url), None);
+        assert_eq!(store.cookies(&https_url), None);
+    }
+
+    #[test]
+    fn only_allows_https_urls() {
+        let url = reqwest::Url::parse("http://chatgpt.com/backend-api/codex/responses").unwrap();
+
+        assert!(!is_chatgpt_cookie_url(&url));
+
+        let url = reqwest::Url::parse("wss://chatgpt.com/backend-api/codex/responses").unwrap();
+
+        assert!(!is_chatgpt_cookie_url(&url));
+    }
+
+    #[test]
+    fn allows_only_known_cloudflare_cookie_names() {
+        for name in [
+            "__cf_bm",
+            "__cflb",
+            "__cfruid",
+            "__cfseq",
+            "__cfwaitingroom",
+            "_cfuvid",
+            "cf_clearance",
+            "cf_ob_info",
+            "cf_use_ob",
+            "cf_chl_rc_i",
+        ] {
+            assert!(is_allowed_cloudflare_cookie_name(name));
+        }
+
+        for name in [
+            "__Secure-next-auth.session-token",
+            "chatgpt_session",
+            "oai-auth-token",
+            "not_cf_clearance",
+        ] {
+            assert!(!is_allowed_cloudflare_cookie_name(name));
+        }
+    }
+}
diff --git a/codex-rs/http-client/src/chatgpt_hosts.rs b/codex-rs/http-client/src/chatgpt_hosts.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0426c8bb36b29de0b79602aa1a176f5e76305398
--- /dev/null
+++ b/codex-rs/http-client/src/chatgpt_hosts.rs
@@ -0,0 +1,39 @@
+/// Returns whether `host` is one of the ChatGPT hosts Codex is allowed to treat
+/// as first-party ChatGPT HTTP traffic.
+pub fn is_allowed_chatgpt_host(host: &str) -> bool {
+    const EXACT_HOSTS: &[&str] = &["chatgpt.com", "chat.openai.com", "chatgpt-staging.com"];
+    const SUBDOMAIN_SUFFIXES: &[&str] = &[".chatgpt.com", ".chatgpt-staging.com"];
+
+    EXACT_HOSTS.contains(&host)
+        || SUBDOMAIN_SUFFIXES
+            .iter()
+            .any(|suffix| host.ends_with(suffix))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn recognizes_chatgpt_hosts_without_suffix_tricks() {
+        for host in [
+            "chatgpt.com",
+            "foo.chatgpt.com",
+            "staging.chatgpt.com",
+            "chat.openai.com",
+            "chatgpt-staging.com",
+            "api.chatgpt-staging.com",
+        ] {
+            assert!(is_allowed_chatgpt_host(host));
+        }
+
+        for host in [
+            "evilchatgpt.com",
+            "chatgpt.com.evil.example",
+            "api.openai.com",
+            "foo.chat.openai.com",
+        ] {
+            assert!(!is_allowed_chatgpt_host(host));
+        }
+    }
+}
diff --git a/codex-rs/http-client/src/client.rs b/codex-rs/http-client/src/client.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9cda749aa27581101a4f718644151f88c508100d
--- /dev/null
+++ b/codex-rs/http-client/src/client.rs
@@ -0,0 +1,356 @@
+//! Reusable HTTP client and request-builder wrappers.
+
+use http::Error as HttpRequestBuildError;
+use http::HeaderMap;
+use http::HeaderName;
+use http::HeaderValue;
+use opentelemetry::global;
+use opentelemetry::propagation::Injector;
+use reqwest::IntoUrl;
+use reqwest::Method;
+use serde::Serialize;
+use std::fmt::Display;
+use std::time::Duration;
+use tracing::Span;
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+pub type HttpError = reqwest::Error;
+pub type HttpResponse = reqwest::Response;
+
+/// Reusable HTTP client wrapper with shared tracing and request-diagnostic behavior.
+///
+/// Product callers should obtain this through [`crate::HttpClientFactory`] for a fixed
+/// destination or use [`crate::RouteAwareClientPool`] when request and redirect URLs can vary.
+#[derive(Clone, Debug)]
+pub struct HttpClient {
+    inner: reqwest::Client,
+    request_logging: RequestLogging,
+}
+
+impl HttpClient {
+    pub fn new(inner: reqwest::Client) -> Self {
+        Self::from_parts(inner, RequestLogging::Enabled)
+    }
+
+    /// Creates a client that suppresses request URL and response-header diagnostics.
+    ///
+    /// Use this for endpoints whose URLs or headers may contain credentials that are redacted by
+    /// the caller above the HTTP transport boundary.
+    pub fn new_without_request_logging(inner: reqwest::Client) -> Self {
+        Self::from_parts(inner, RequestLogging::Disabled)
+    }
+
+    pub(crate) fn from_parts(inner: reqwest::Client, request_logging: RequestLogging) -> Self {
+        Self {
+            inner,
+            request_logging,
+        }
+    }
+
+    pub fn get<U>(&self, url: U) -> RequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::GET, url)
+    }
+
+    pub fn head<U>(&self, url: U) -> RequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::HEAD, url)
+    }
+
+    pub fn post<U>(&self, url: U) -> RequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::POST, url)
+    }
+
+    pub fn delete<U>(&self, url: U) -> RequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::DELETE, url)
+    }
+
+    pub fn request<U>(&self, method: Method, url: U) -> RequestBuilder
+    where
+        U: IntoUrl,
+    {
+        let url_str = url.as_str().to_string();
+        RequestBuilder::new(
+            self.inner.request(method.clone(), url),
+            method,
+            url_str,
+            self.request_logging,
+        )
+    }
+
+    pub(crate) async fn execute(
+        &self,
+        request: reqwest::Request,
+    ) -> Result<reqwest::Response, reqwest::Error> {
+        let method = request.method().clone();
+        let url = request.url().to_string();
+
+        match self.execute_without_request_logging(request).await {
+            Ok(response) => {
+                self.log_response(&method, &url, &response);
+                Ok(response)
+            }
+            Err(error) => {
+                self.log_error(&method, &url, &error);
+                Err(error)
+            }
+        }
+    }
+
+    pub(crate) async fn execute_without_request_logging(
+        &self,
+        mut request: reqwest::Request,
+    ) -> Result<reqwest::Response, reqwest::Error> {
+        request.headers_mut().extend(trace_headers());
+        self.inner.execute(request).await
+    }
+
+    pub(crate) fn log_response(&self, method: &Method, url: &str, response: &reqwest::Response) {
+        if self.request_logging == RequestLogging::Enabled {
+            tracing::debug!(
+                method = %method,
+                url = %url,
+                status = %response.status(),
+                headers = ?response.headers(),
+                version = ?response.version(),
+                "Request completed"
+            );
+        }
+    }
+
+    pub(crate) fn log_error(&self, method: &Method, url: &str, error: &reqwest::Error) {
+        if self.request_logging == RequestLogging::Enabled {
+            tracing::debug!(
+                method = %method,
+                url = %url,
+                status = error.status().map(|status| status.as_u16()),
+                error = %error,
+                "Request failed"
+            );
+        }
+    }
+    pub(crate) fn log_error_summary(&self, method: &Method, url: &str, error: &reqwest::Error) {
+        if self.request_logging == RequestLogging::Enabled {
+            tracing::debug!(
+                method = %method,
+                url = %url,
+                status = error.status().map(|status| status.as_u16()),
+                is_timeout = error.is_timeout(),
+                is_connect = error.is_connect(),
+                "Request failed"
+            );
+        }
+    }
+
+    pub(crate) const fn request_logging_enabled(&self) -> bool {
+        matches!(self.request_logging, RequestLogging::Enabled)
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub(crate) enum RequestLogging {
+    #[default]
+    Enabled,
+    Disabled,
+}
+
+#[must_use = "requests are not sent unless `send` is awaited"]
+#[derive(Debug)]
+pub struct RequestBuilder {
+    builder: reqwest::RequestBuilder,
+    method: Method,
+    url: String,
+    request_logging: RequestLogging,
+}
+
+impl RequestBuilder {
+    fn new(
+        builder: reqwest::RequestBuilder,
+        method: Method,
+        url: String,
+        request_logging: RequestLogging,
+    ) -> Self {
+        Self {
+            builder,
+            method,
+            url,
+            request_logging,
+        }
+    }
+
+    fn map(self, f: impl FnOnce(reqwest::RequestBuilder) -> reqwest::RequestBuilder) -> Self {
+        Self {
+            builder: f(self.builder),
+            method: self.method,
+            url: self.url,
+            request_logging: self.request_logging,
+        }
+    }
+
+    pub fn headers(self, headers: HeaderMap) -> Self {
+        self.map(|builder| builder.headers(headers))
+    }
+
+    pub fn header<K, V>(self, key: K, value: V) -> Self
+    where
+        HeaderName: TryFrom<K>,
+        <HeaderName as TryFrom<K>>::Error: Into<HttpRequestBuildError>,
+        HeaderValue: TryFrom<V>,
+        <HeaderValue as TryFrom<V>>::Error: Into<HttpRequestBuildError>,
+    {
+        self.map(|builder| builder.header(key, value))
+    }
+
+    pub fn bearer_auth<T>(self, token: T) -> Self
+    where
+        T: Display,
+    {
+        self.map(|builder| builder.bearer_auth(token))
+    }
+
+    pub fn timeout(self, timeout: Duration) -> Self {
+        self.map(|builder| builder.timeout(timeout))
+    }
+
+    pub fn json<T>(self, value: &T) -> Self
+    where
+        T: ?Sized + Serialize,
+    {
+        self.map(|builder| builder.json(value))
+    }
+
+    pub fn query<T>(self, query: &T) -> Self
+    where
+        T: ?Sized + Serialize,
+    {
+        self.map(|builder| builder.query(query))
+    }
+
+    pub fn body<B>(self, body: B) -> Self
+    where
+        B: Into<reqwest::Body>,
+    {
+        self.map(|builder| builder.body(body))
+    }
+
+    pub async fn send(self) -> Result<HttpResponse, HttpError> {
+        let headers = trace_headers();
+
+        match self.builder.headers(headers).send().await {
+            Ok(response) => {
+                if self.request_logging == RequestLogging::Enabled {
+                    tracing::debug!(
+                        method = %self.method,
+                        url = %self.url,
+                        status = %response.status(),
+                        headers = ?response.headers(),
+                        version = ?response.version(),
+                        "Request completed"
+                    );
+                }
+
+                Ok(response)
+            }
+            Err(error) => {
+                if self.request_logging == RequestLogging::Enabled {
+                    let status = error.status();
+                    tracing::debug!(
+                        method = %self.method,
+                        url = %self.url,
+                        status = status.map(|s| s.as_u16()),
+                        error = %error,
+                        "Request failed"
+                    );
+                }
+                Err(error)
+            }
+        }
+    }
+}
+
+struct HeaderMapInjector<'a>(&'a mut HeaderMap);
+
+impl<'a> Injector for HeaderMapInjector<'a> {
+    fn set(&mut self, key: &str, value: String) {
+        if let (Ok(name), Ok(val)) = (
+            HeaderName::from_bytes(key.as_bytes()),
+            HeaderValue::from_str(&value),
+        ) {
+            self.0.insert(name, val);
+        }
+    }
+}
+
+pub(crate) fn trace_headers() -> HeaderMap {
+    let mut headers = HeaderMap::new();
+    global::get_text_map_propagator(|prop| {
+        prop.inject_context(
+            &Span::current().context(),
+            &mut HeaderMapInjector(&mut headers),
+        );
+    });
+    headers
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use opentelemetry::propagation::Extractor;
+    use opentelemetry::propagation::TextMapPropagator;
+    use opentelemetry::trace::TraceContextExt;
+    use opentelemetry::trace::TracerProvider;
+    use opentelemetry_sdk::propagation::TraceContextPropagator;
+    use opentelemetry_sdk::trace::SdkTracerProvider;
+    use pretty_assertions::assert_eq;
+    use tracing::trace_span;
+    use tracing_subscriber::layer::SubscriberExt;
+    use tracing_subscriber::util::SubscriberInitExt;
+
+    #[test]
+    fn inject_trace_headers_uses_current_span_context() {
+        global::set_text_map_propagator(TraceContextPropagator::new());
+
+        let provider = SdkTracerProvider::builder().build();
+        let tracer = provider.tracer("test-tracer");
+        let subscriber =
+            tracing_subscriber::registry().with(tracing_opentelemetry::layer().with_tracer(tracer));
+        let _guard = subscriber.set_default();
+
+        let span = trace_span!("client_request");
+        let _entered = span.enter();
+        let span_context = span.context().span().span_context().clone();
+
+        let headers = trace_headers();
+
+        let extractor = HeaderMapExtractor(&headers);
+        let extracted = TraceContextPropagator::new().extract(&extractor);
+        let extracted_span = extracted.span();
+        let extracted_context = extracted_span.span_context();
+
+        assert!(extracted_context.is_valid());
+        assert_eq!(extracted_context.trace_id(), span_context.trace_id());
+        assert_eq!(extracted_context.span_id(), span_context.span_id());
+    }
+
+    struct HeaderMapExtractor<'a>(&'a HeaderMap);
+
+    impl<'a> Extractor for HeaderMapExtractor<'a> {
+        fn get(&self, key: &str) -> Option<&str> {
+            self.0.get(key).and_then(|value| value.to_str().ok())
+        }
+
+        fn keys(&self) -> Vec<&str> {
+            self.0.keys().map(HeaderName::as_str).collect()
+        }
+    }
+}
diff --git a/codex-rs/http-client/src/client_builder.rs b/codex-rs/http-client/src/client_builder.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9f374293a1025c875bf0cc24be48c7201993c50c
--- /dev/null
+++ b/codex-rs/http-client/src/client_builder.rs
@@ -0,0 +1,323 @@
+//! HTTP client construction that makes outbound proxy policy explicit.
+//!
+//! Product traffic should normally enter through [`HttpClientFactory`] for a fixed destination or
+//! [`crate::RouteAwareClientPool`] when request and redirect URLs can vary. The direct and
+//! transport-default terminal methods exist only for narrow exceptional or legacy compatibility
+//! paths.
+
+use http::HeaderMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use codex_utils_rustls_provider::ensure_rustls_crypto_provider;
+
+use crate::BuildCustomCaTransportError;
+use crate::BuildRouteAwareHttpClientError;
+use crate::ClientRouteClass;
+use crate::HttpClient;
+use crate::HttpClientFactory;
+use crate::OutboundProxyRoute;
+use crate::chatgpt_cloudflare_cookies::ChatGptCookieStore;
+use crate::client::RequestLogging;
+use crate::custom_ca::build_reqwest_client_with_custom_ca;
+use crate::with_chatgpt_cloudflare_cookie_store;
+
+/// Configures an [`HttpClient`] without exposing the underlying HTTP implementation.
+///
+/// Product traffic should prefer [`HttpClientFactory::build_client`] or finish this builder with
+/// [`Self::build_respecting_outbound_proxy_policy`]. The other terminal methods deliberately
+/// bypass the factory and are restricted to documented exceptional or legacy compatibility paths.
+#[derive(Clone)]
+pub struct HttpClientBuilder {
+    default_headers: Option<HeaderMap>,
+    follow_redirects: bool,
+    connect_timeout: Option<Duration>,
+    chatgpt_cloudflare_cookie_store: bool,
+    chatgpt_cookie_store: Option<Arc<ChatGptCookieStore>>,
+    request_logging: RequestLogging,
+    tls_backend: TlsBackend,
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+enum TlsBackend {
+    #[default]
+    TransportDefault,
+    Rustls,
+}
+
+impl HttpClientFactory {
+    /// Builds an HTTP client for one fixed destination using the configured proxy policy.
+    ///
+    /// This is the preferred construction path for product traffic that uses a fixed destination.
+    /// Use [`crate::RouteAwareClientPool`] instead when request or redirect URLs can vary.
+    pub fn build_client(
+        &self,
+        request_url: &str,
+        route_class: ClientRouteClass,
+    ) -> Result<HttpClient, BuildRouteAwareHttpClientError> {
+        HttpClientBuilder::new().build_respecting_outbound_proxy_policy(
+            self,
+            request_url,
+            route_class,
+        )
+    }
+
+    /// Builds a policy-aware client without request URL or response-header diagnostics.
+    ///
+    /// This has the same routing guidance as [`Self::build_client`].
+    pub fn build_client_without_request_logging(
+        &self,
+        request_url: &str,
+        route_class: ClientRouteClass,
+    ) -> Result<HttpClient, BuildRouteAwareHttpClientError> {
+        HttpClientBuilder::new()
+            .without_request_logging()
+            .build_respecting_outbound_proxy_policy(self, request_url, route_class)
+    }
+}
+
+impl HttpClientBuilder {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn default_headers(mut self, headers: HeaderMap) -> Self {
+        self.default_headers = Some(headers);
+        self
+    }
+
+    pub fn without_redirects(mut self) -> Self {
+        self.follow_redirects = false;
+        self
+    }
+
+    pub(crate) fn follows_redirects(&self) -> bool {
+        self.follow_redirects
+    }
+
+    pub(crate) fn with_rustls_tls(mut self) -> Self {
+        self.tls_backend = TlsBackend::Rustls;
+        self
+    }
+
+    /// Limits only connection establishment, not the request as a whole.
+    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
+        self.connect_timeout = Some(timeout);
+        self
+    }
+
+    pub fn with_chatgpt_cloudflare_cookie_store(mut self) -> Self {
+        self.chatgpt_cloudflare_cookie_store = true;
+        self
+    }
+
+    /// Uses the factory's configured ChatGPT cookies without changing proxy behavior.
+    pub fn with_chatgpt_cookies(mut self, http_client_factory: &HttpClientFactory) -> Self {
+        self.chatgpt_cloudflare_cookie_store = true;
+        self.chatgpt_cookie_store = http_client_factory.chatgpt_cookie_store();
+        self
+    }
+
+    /// Suppresses request URL and response-header diagnostics.
+    pub fn without_request_logging(mut self) -> Self {
+        self.request_logging = RequestLogging::Disabled;
+        self
+    }
+
+    /// Builds a client that honors the [`HttpClientFactory`] outbound proxy policy.
+    ///
+    /// This is the preferred terminal method for product traffic. The request URL is used to
+    /// resolve a concrete direct or proxy route when the factory is configured with
+    /// [`crate::OutboundProxyPolicy::RespectSystemProxy`].
+    pub fn build_respecting_outbound_proxy_policy(
+        mut self,
+        http_client_factory: &HttpClientFactory,
+        request_url: &str,
+        route_class: ClientRouteClass,
+    ) -> Result<HttpClient, BuildRouteAwareHttpClientError> {
+        self.chatgpt_cookie_store = http_client_factory.chatgpt_cookie_store();
+        let (builder, request_logging) = self.into_reqwest_parts();
+        let inner = http_client_factory.build_reqwest_client(builder, request_url, route_class)?;
+        Ok(HttpClient::from_parts(inner, request_logging))
+    }
+
+    /// Builds a client for a route that was already resolved by a route-aware caller.
+    pub(crate) fn build_for_resolved_route(
+        mut self,
+        http_client_factory: &HttpClientFactory,
+        route_class: ClientRouteClass,
+        route: &OutboundProxyRoute,
+    ) -> Result<HttpClient, BuildRouteAwareHttpClientError> {
+        self.chatgpt_cookie_store = http_client_factory.chatgpt_cookie_store();
+        let (builder, request_logging) = self.into_reqwest_parts();
+        let inner = http_client_factory.build_reqwest_client_for_resolved_route(
+            builder,
+            route_class,
+            route,
+        )?;
+        Ok(HttpClient::from_parts(inner, request_logging))
+    }
+
+    /// Builds a client using the transport's default proxy behavior.
+    ///
+    /// # Legacy compatibility only
+    ///
+    /// This bypasses [`HttpClientFactory`] and therefore does not honor its configured outbound
+    /// proxy policy. New product traffic must use [`Self::build_respecting_outbound_proxy_policy`]
+    /// or [`HttpClientFactory::build_client`].
+    #[deprecated(
+        note = "legacy compatibility only; use HttpClientFactory::build_client or build_respecting_outbound_proxy_policy"
+    )]
+    pub fn build_with_transport_default_proxy(
+        self,
+    ) -> Result<HttpClient, BuildCustomCaTransportError> {
+        self.build_with_proxy_routing(ProxyRouting::TransportDefault)
+    }
+
+    /// Builds a client that connects directly without using a proxy.
+    ///
+    /// # Exceptional use only
+    ///
+    /// This bypasses [`HttpClientFactory`] and is appropriate only when bypassing proxy discovery
+    /// is itself required: for example, a hermetic local test fixture, a localhost callback, or
+    /// sandbox traffic whose egress routing is handled separately. Ordinary outbound product
+    /// traffic must use [`Self::build_respecting_outbound_proxy_policy`] or
+    /// [`HttpClientFactory::build_client`].
+    pub fn build_direct(self) -> Result<HttpClient, BuildCustomCaTransportError> {
+        self.build_with_proxy_routing(ProxyRouting::Direct)
+    }
+
+    /// Builds a transport-default client while preserving the legacy custom-CA fallback.
+    ///
+    /// # Legacy compatibility only
+    ///
+    /// This preserves call sites that historically logged a custom-CA error and continued with
+    /// system roots. New product traffic must propagate construction errors through
+    /// [`Self::build_respecting_outbound_proxy_policy`] or [`HttpClientFactory::build_client`].
+    #[deprecated(
+        note = "legacy custom-CA fallback only; use HttpClientFactory::build_client or build_respecting_outbound_proxy_policy"
+    )]
+    pub fn build_with_transport_default_proxy_and_custom_ca_fallback(self) -> HttpClient {
+        self.build_with_custom_ca_fallback(ProxyRouting::TransportDefault)
+    }
+
+    /// Builds a direct client while preserving the legacy custom-CA fallback.
+    ///
+    /// # Legacy compatibility only
+    ///
+    /// This combines the exceptional proxy bypass described by [`Self::build_direct`] with the
+    /// historical behavior of logging a custom-CA error and continuing with system roots.
+    #[deprecated(
+        note = "legacy custom-CA fallback only; use build_direct and propagate construction errors"
+    )]
+    pub fn build_direct_with_custom_ca_fallback(self) -> HttpClient {
+        self.build_with_custom_ca_fallback(ProxyRouting::Direct)
+    }
+
+    fn build_with_proxy_routing(
+        self,
+        proxy_routing: ProxyRouting,
+    ) -> Result<HttpClient, BuildCustomCaTransportError> {
+        let request_logging = self.request_logging;
+        build_reqwest_client_with_custom_ca(self.reqwest_builder(proxy_routing))
+            .map(|inner| HttpClient::from_parts(inner, request_logging))
+    }
+
+    fn build_with_custom_ca_fallback(self, proxy_routing: ProxyRouting) -> HttpClient {
+        self.build_with_custom_ca_fallback_using(proxy_routing, build_reqwest_client_with_custom_ca)
+    }
+
+    fn build_with_custom_ca_fallback_using(
+        self,
+        proxy_routing: ProxyRouting,
+        build_with_custom_ca: impl FnOnce(
+            reqwest::ClientBuilder,
+        )
+            -> Result<reqwest::Client, BuildCustomCaTransportError>,
+    ) -> HttpClient {
+        let request_logging = self.request_logging;
+        match build_with_custom_ca(self.clone().reqwest_builder(proxy_routing)) {
+            Ok(inner) => HttpClient::from_parts(inner, request_logging),
+            Err(error) => {
+                tracing::event!(
+                    target: "codex_otel.log_only",
+                    tracing::Level::WARN,
+                    event.name = "codex.http_client.custom_ca_fallback",
+                    "HTTP client fell back to system root certificates"
+                );
+                tracing::warn!(error = %error, "failed to build HTTP client with custom CA");
+                self.reqwest_builder(proxy_routing)
+                    .build()
+                    .map(|inner| HttpClient::from_parts(inner, request_logging))
+                    .unwrap_or_else(|fallback_error| {
+                        tracing::warn!(
+                            error = %fallback_error,
+                            "failed to build fallback HTTP client"
+                        );
+                        HttpClient::from_parts(reqwest::Client::new(), request_logging)
+                    })
+            }
+        }
+    }
+
+    fn into_reqwest_parts(self) -> (reqwest::ClientBuilder, RequestLogging) {
+        let request_logging = self.request_logging;
+        (self.base_reqwest_builder(), request_logging)
+    }
+
+    fn reqwest_builder(self, proxy_routing: ProxyRouting) -> reqwest::ClientBuilder {
+        let builder = self.base_reqwest_builder();
+        match proxy_routing {
+            ProxyRouting::TransportDefault => builder,
+            ProxyRouting::Direct => builder.no_proxy(),
+        }
+    }
+
+    fn base_reqwest_builder(self) -> reqwest::ClientBuilder {
+        let mut builder = reqwest::Client::builder();
+        if self.tls_backend == TlsBackend::Rustls {
+            ensure_rustls_crypto_provider();
+            builder = builder.use_rustls_tls();
+        }
+        if let Some(default_headers) = self.default_headers {
+            builder = builder.default_headers(default_headers);
+        }
+        if !self.follow_redirects {
+            builder = builder.redirect(reqwest::redirect::Policy::none());
+        }
+        if let Some(connect_timeout) = self.connect_timeout {
+            builder = builder.connect_timeout(connect_timeout);
+        }
+        if self.chatgpt_cloudflare_cookie_store {
+            builder = match self.chatgpt_cookie_store {
+                Some(store) => builder.cookie_provider(store),
+                None => with_chatgpt_cloudflare_cookie_store(builder),
+            };
+        }
+        builder
+    }
+}
+
+impl Default for HttpClientBuilder {
+    fn default() -> Self {
+        Self {
+            default_headers: None,
+            follow_redirects: true,
+            connect_timeout: None,
+            chatgpt_cloudflare_cookie_store: false,
+            chatgpt_cookie_store: None,
+            request_logging: RequestLogging::Enabled,
+            tls_backend: TlsBackend::TransportDefault,
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+enum ProxyRouting {
+    TransportDefault,
+    Direct,
+}
+
+#[cfg(test)]
+#[path = "client_builder_tests.rs"]
+mod tests;
diff --git a/codex-rs/http-client/src/client_builder_tests.rs b/codex-rs/http-client/src/client_builder_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0b4cbb4b7d0230bf6e91a49a03b7421088cf9c04
--- /dev/null
+++ b/codex-rs/http-client/src/client_builder_tests.rs
@@ -0,0 +1,52 @@
+use super::*;
+use http::HeaderValue;
+use std::io::Read;
+use std::io::Write;
+use std::path::PathBuf;
+
+#[tokio::test]
+async fn custom_ca_fallback_preserves_builder_configuration() {
+    let listener =
+        std::net::TcpListener::bind(("127.0.0.1", 0)).expect("HTTP listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("HTTP listener should have an address");
+    let server = std::thread::spawn(move || {
+        let (mut stream, _) = listener.accept().expect("HTTP listener should accept");
+        let mut request = Vec::new();
+        let mut chunk = [0_u8; 1024];
+        while !request.windows(4).any(|window| window == b"\r\n\r\n") {
+            let bytes_read = stream.read(&mut chunk).expect("HTTP request should read");
+            assert!(bytes_read > 0, "HTTP request should include headers");
+            request.extend_from_slice(&chunk[..bytes_read]);
+        }
+        stream
+            .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
+            .expect("HTTP listener should write response");
+        String::from_utf8(request).expect("HTTP request should be UTF-8")
+    });
+    let mut headers = HeaderMap::new();
+    headers.insert("x-builder-test", HeaderValue::from_static("preserved"));
+    let client = HttpClientBuilder::new()
+        .default_headers(headers)
+        .build_with_custom_ca_fallback_using(ProxyRouting::Direct, |_| {
+            Err(BuildCustomCaTransportError::InvalidCaFile {
+                source_env: "TEST_CA_ENV",
+                path: PathBuf::from("invalid-test-ca.pem"),
+                detail: "synthetic invalid CA".to_string(),
+            })
+        });
+
+    let response = client
+        .get(format!("http://{address}/fallback"))
+        .send()
+        .await
+        .expect("fallback client should send request");
+    assert!(response.status().is_success());
+    let request = server.join().expect("HTTP listener should finish");
+    assert!(
+        request
+            .lines()
+            .any(|line| line.eq_ignore_ascii_case("x-builder-test: preserved"))
+    );
+}
diff --git a/codex-rs/http-client/src/custom_ca.rs b/codex-rs/http-client/src/custom_ca.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6ca705d0abf9f6672932f75b95fc7e41ee9cfc31
--- /dev/null
+++ b/codex-rs/http-client/src/custom_ca.rs
@@ -0,0 +1,824 @@
+//! Custom CA handling shared by Codex outbound HTTP and websocket clients.
+//!
+//! Codex constructs outbound reqwest clients and secure websocket connections in a few crates, but
+//! they all need the same trust-store policy when enterprise proxies or gateways intercept TLS.
+//! This module centralizes that policy so callers can start from an ordinary
+//! `reqwest::ClientBuilder` or rustls client config, layer in custom CA support, and either get
+//! back a configured transport or a user-facing error that explains how to fix a misconfigured CA
+//! bundle.
+//!
+//! The module intentionally has a narrow responsibility:
+//!
+//! - read CA material from `CODEX_CA_CERTIFICATE`, falling back to `SSL_CERT_FILE`
+//! - normalize PEM variants that show up in real deployments, including OpenSSL-style
+//!   `TRUSTED CERTIFICATE` labels and bundles that also contain CRLs
+//! - return user-facing errors that explain how to fix misconfigured CA files
+//!
+//! Its production contract is narrow: produce a transport configuration whose root store contains
+//! every parseable certificate block from the configured PEM bundle, or fail early with a precise
+//! error before the caller starts network traffic.
+//!
+//! In this module's test setup, a hermetic test is one whose result depends only on the CA file
+//! and environment variables that the test chose for itself. That matters here because the normal
+//! reqwest client-construction path is not hermetic enough for environment-sensitive tests:
+//!
+//! - on macOS seatbelt runs, `reqwest::Client::builder().build()` can panic inside
+//!   `system-configuration` while probing platform proxy settings, which means the process can die
+//!   before the custom-CA code reports success or a structured error. That matters in practice
+//!   because Codex itself commonly runs spawned test processes under seatbelt, so this is not just
+//!   a hypothetical CI edge case.
+//! - child processes inherit CA-related environment variables by default, which lets developer
+//!   shell state or CI configuration affect a test unless the test scrubs those variables first
+//!
+//! The tests in this crate therefore stay split across two layers:
+//!
+//! - unit tests in this module cover env-selection logic without constructing a real client
+//! - subprocess integration tests under `tests/` cover real client construction through
+//!   [`build_reqwest_client_for_subprocess_tests`], which disables reqwest proxy autodetection so
+//!   the tests can observe custom-CA success and failure directly, including one TLS handshake
+//!   through a local HTTPS server
+//! - those subprocess tests also scrub inherited CA environment variables before launch so their
+//!   result depends only on the test fixtures and env vars set by the test itself
+
+use std::env;
+use std::fs;
+use std::io;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use codex_utils_rustls_provider::ensure_rustls_crypto_provider;
+use rustls::ClientConfig;
+use rustls::RootCertStore;
+use rustls_pki_types::CertificateDer;
+use rustls_pki_types::pem::PemObject;
+use rustls_pki_types::pem::SectionKind;
+use rustls_pki_types::pem::{self};
+use thiserror::Error;
+use tracing::info;
+use tracing::warn;
+
+pub const CODEX_CA_CERT_ENV: &str = "CODEX_CA_CERTIFICATE";
+pub const SSL_CERT_FILE_ENV: &str = "SSL_CERT_FILE";
+const CA_CERT_HINT: &str = "If you set CODEX_CA_CERTIFICATE or SSL_CERT_FILE, ensure it points to a PEM file containing one or more CERTIFICATE blocks, or unset it to use system roots.";
+type PemSection = (SectionKind, Vec<u8>);
+
+/// Describes why a transport using shared custom CA support could not be constructed.
+///
+/// These failure modes apply to both reqwest client construction and websocket TLS
+/// configuration. A build can fail because the configured CA file could not be read, could not be
+/// parsed as certificates, contained certs that the target TLS stack refused to register, or
+/// because the final reqwest client builder failed. Callers that do not care about the
+/// distinction can rely on the `From<BuildCustomCaTransportError> for io::Error` conversion.
+#[derive(Debug, Error)]
+pub enum BuildCustomCaTransportError {
+    /// Reading the selected CA file from disk failed before any PEM parsing could happen.
+    #[error(
+        "Failed to read CA certificate file {} selected by {}: {source}. {hint}",
+        path.display(),
+        source_env,
+        hint = CA_CERT_HINT
+    )]
+    ReadCaFile {
+        source_env: &'static str,
+        path: PathBuf,
+        source: io::Error,
+    },
+
+    /// The selected CA file was readable, but did not produce usable certificate material.
+    #[error(
+        "Failed to load CA certificates from {} selected by {}: {detail}. {hint}",
+        path.display(),
+        source_env,
+        hint = CA_CERT_HINT
+    )]
+    InvalidCaFile {
+        source_env: &'static str,
+        path: PathBuf,
+        detail: String,
+    },
+
+    /// One parsed certificate block could not be registered with the reqwest client builder.
+    #[error(
+        "Failed to parse certificate #{certificate_index} from {} selected by {}: {source}. {hint}",
+        path.display(),
+        source_env,
+        hint = CA_CERT_HINT
+    )]
+    RegisterCertificate {
+        source_env: &'static str,
+        path: PathBuf,
+        certificate_index: usize,
+        source: reqwest::Error,
+    },
+
+    /// Reqwest rejected the final client configuration after a custom CA bundle was loaded.
+    #[error(
+        "Failed to build HTTP client while using CA bundle from {} ({}): {source}",
+        source_env,
+        path.display()
+    )]
+    BuildClientWithCustomCa {
+        source_env: &'static str,
+        path: PathBuf,
+        #[source]
+        source: reqwest::Error,
+    },
+
+    /// Reqwest rejected the final client configuration while using only system roots.
+    #[error("Failed to build HTTP client while using system root certificates: {0}")]
+    BuildClientWithSystemRoots(#[source] reqwest::Error),
+
+    /// One parsed certificate block could not be registered with the websocket TLS root store.
+    #[error(
+        "Failed to register certificate #{certificate_index} from {} selected by {} in rustls root store: {source}. {hint}",
+        path.display(),
+        source_env,
+        hint = CA_CERT_HINT
+    )]
+    RegisterRustlsCertificate {
+        source_env: &'static str,
+        path: PathBuf,
+        certificate_index: usize,
+        source: rustls::Error,
+    },
+}
+
+impl From<BuildCustomCaTransportError> for io::Error {
+    fn from(error: BuildCustomCaTransportError) -> Self {
+        match error {
+            BuildCustomCaTransportError::ReadCaFile { ref source, .. } => {
+                io::Error::new(source.kind(), error)
+            }
+            BuildCustomCaTransportError::InvalidCaFile { .. }
+            | BuildCustomCaTransportError::RegisterCertificate { .. }
+            | BuildCustomCaTransportError::RegisterRustlsCertificate { .. } => {
+                io::Error::new(io::ErrorKind::InvalidData, error)
+            }
+            BuildCustomCaTransportError::BuildClientWithCustomCa { .. }
+            | BuildCustomCaTransportError::BuildClientWithSystemRoots(_) => io::Error::other(error),
+        }
+    }
+}
+
+/// Builds a reqwest client that honors Codex custom CA environment variables.
+///
+/// Callers supply the baseline builder configuration they need, and this helper layers in custom
+/// CA handling before finally constructing the client. `CODEX_CA_CERTIFICATE` takes precedence
+/// over `SSL_CERT_FILE`, and empty values for either are treated as unset so callers do not
+/// accidentally turn `VAR=""` into a bogus path lookup.
+///
+/// Callers that build a raw `reqwest::Client` directly bypass this policy entirely. That is an
+/// easy mistake to make when adding a new outbound Codex HTTP path, and the resulting bug only
+/// shows up in environments where a proxy or gateway requires a custom root CA.
+///
+/// # Errors
+///
+/// Returns a [`BuildCustomCaTransportError`] when the configured CA file is unreadable,
+/// malformed, or contains a certificate block that `reqwest` cannot register as a root.
+pub fn build_reqwest_client_with_custom_ca(
+    builder: reqwest::ClientBuilder,
+) -> Result<reqwest::Client, BuildCustomCaTransportError> {
+    build_reqwest_client_with_env(&ProcessEnv, builder)
+}
+
+/// Builds a rustls client config when a Codex custom CA bundle is configured.
+///
+/// This is the websocket-facing sibling of [`build_reqwest_client_with_custom_ca`]. When
+/// `CODEX_CA_CERTIFICATE` or `SSL_CERT_FILE` selects a CA bundle, the returned config starts from
+/// the platform native roots and then adds the configured custom CA certificates. When no custom
+/// CA env var is set, this returns `Ok(None)` so websocket callers can keep using their ordinary
+/// default connector path.
+///
+/// Callers that let tungstenite build its default TLS connector directly bypass this policy
+/// entirely. That bug only shows up in environments where secure websocket traffic needs the same
+/// enterprise root CA bundle as HTTPS traffic.
+pub fn maybe_build_rustls_client_config_with_custom_ca()
+-> Result<Option<Arc<ClientConfig>>, BuildCustomCaTransportError> {
+    maybe_build_rustls_client_config_with_env(&ProcessEnv)
+}
+
+/// Builds a rustls client config using native roots and any configured Codex custom CA bundle.
+///
+/// Unlike [`maybe_build_rustls_client_config_with_custom_ca`], this always returns a config. Use
+/// this when the caller must perform TLS itself instead of delegating default configuration to a
+/// transport library.
+pub fn build_rustls_client_config_with_custom_ca()
+-> Result<Arc<ClientConfig>, BuildCustomCaTransportError> {
+    build_rustls_client_config_with_env(&ProcessEnv)
+}
+
+/// Builds a reqwest client for spawned subprocess tests that exercise CA behavior.
+///
+/// This is the test-only client-construction path used by the subprocess coverage in `tests/`.
+/// The module-level docs explain the hermeticity problem in full; this helper only addresses the
+/// reqwest proxy-discovery panic side of that problem by disabling proxy autodetection. The tests
+/// still scrub inherited CA environment variables themselves. Normal production callers should use
+/// [`build_reqwest_client_with_custom_ca`] so test-only proxy behavior does not leak into
+/// ordinary client construction.
+pub fn build_reqwest_client_for_subprocess_tests(
+    builder: reqwest::ClientBuilder,
+) -> Result<reqwest::Client, BuildCustomCaTransportError> {
+    build_reqwest_client_with_env(&ProcessEnv, builder.no_proxy())
+}
+
+fn maybe_build_rustls_client_config_with_env(
+    env_source: &dyn EnvSource,
+) -> Result<Option<Arc<ClientConfig>>, BuildCustomCaTransportError> {
+    let Some(bundle) = env_source.configured_ca_bundle() else {
+        return Ok(None);
+    };
+
+    build_rustls_client_config(Some(&bundle)).map(Some)
+}
+
+fn build_rustls_client_config_with_env(
+    env_source: &dyn EnvSource,
+) -> Result<Arc<ClientConfig>, BuildCustomCaTransportError> {
+    let bundle = env_source.configured_ca_bundle();
+    build_rustls_client_config(bundle.as_ref())
+}
+
+fn build_rustls_client_config(
+    bundle: Option<&ConfiguredCaBundle>,
+) -> Result<Arc<ClientConfig>, BuildCustomCaTransportError> {
+    ensure_rustls_crypto_provider();
+
+    // Start from the platform roots so websocket callers keep the same baseline trust behavior
+    // they would get from tungstenite's default rustls connector, then layer in the Codex custom
+    // CA bundle on top when configured.
+    let mut root_store = RootCertStore::empty();
+    let rustls_native_certs::CertificateResult { certs, errors, .. } =
+        rustls_native_certs::load_native_certs();
+    if !errors.is_empty() {
+        warn!(
+            native_root_error_count = errors.len(),
+            "encountered errors while loading native root certificates"
+        );
+    }
+    let _ = root_store.add_parsable_certificates(certs);
+
+    if let Some(bundle) = bundle {
+        let certificates = bundle.load_certificates()?;
+        for (idx, cert) in certificates.into_iter().enumerate() {
+            if let Err(source) = root_store.add(cert) {
+                warn!(
+                    source_env = bundle.source_env,
+                    ca_path = %bundle.path.display(),
+                    certificate_index = idx + 1,
+                    error = %source,
+                    "failed to register CA certificate in rustls root store"
+                );
+                return Err(BuildCustomCaTransportError::RegisterRustlsCertificate {
+                    source_env: bundle.source_env,
+                    path: bundle.path.clone(),
+                    certificate_index: idx + 1,
+                    source,
+                });
+            }
+        }
+    }
+
+    Ok(Arc::new(
+        ClientConfig::builder()
+            .with_root_certificates(root_store)
+            .with_no_client_auth(),
+    ))
+}
+
+/// Builds a reqwest client using an injected environment source and reqwest builder.
+///
+/// This exists so tests can exercise precedence behavior deterministically without mutating the
+/// real process environment. It selects the CA bundle, delegates file parsing to
+/// [`ConfiguredCaBundle::load_certificates`], preserves the caller's chosen `reqwest` builder
+/// configuration, forces rustls when a custom CA is configured, and finally registers each parsed
+/// certificate with that builder.
+fn build_reqwest_client_with_env(
+    env_source: &dyn EnvSource,
+    mut builder: reqwest::ClientBuilder,
+) -> Result<reqwest::Client, BuildCustomCaTransportError> {
+    if let Some(bundle) = env_source.configured_ca_bundle() {
+        ensure_rustls_crypto_provider();
+        info!(
+            source_env = bundle.source_env,
+            ca_path = %bundle.path.display(),
+            "building HTTP client with rustls backend for custom CA bundle"
+        );
+        builder = builder.use_rustls_tls();
+
+        let certificates = bundle.load_certificates()?;
+
+        for (idx, cert) in certificates.iter().enumerate() {
+            let certificate = match reqwest::Certificate::from_der(cert.as_ref()) {
+                Ok(certificate) => certificate,
+                Err(source) => {
+                    warn!(
+                        source_env = bundle.source_env,
+                        ca_path = %bundle.path.display(),
+                        certificate_index = idx + 1,
+                        error = %source,
+                        "failed to register CA certificate"
+                    );
+                    return Err(BuildCustomCaTransportError::RegisterCertificate {
+                        source_env: bundle.source_env,
+                        path: bundle.path.clone(),
+                        certificate_index: idx + 1,
+                        source,
+                    });
+                }
+            };
+            builder = builder.add_root_certificate(certificate);
+        }
+        return match builder.build() {
+            Ok(client) => Ok(client),
+            Err(source) => {
+                warn!(
+                    source_env = bundle.source_env,
+                    ca_path = %bundle.path.display(),
+                    error = %source,
+                    "failed to build client after loading custom CA bundle"
+                );
+                Err(BuildCustomCaTransportError::BuildClientWithCustomCa {
+                    source_env: bundle.source_env,
+                    path: bundle.path.clone(),
+                    source,
+                })
+            }
+        };
+    }
+
+    info!(
+        codex_ca_certificate_configured = false,
+        ssl_cert_file_configured = false,
+        "using system root certificates because no CA override environment variable was selected"
+    );
+
+    match builder.build() {
+        Ok(client) => Ok(client),
+        Err(source) => {
+            warn!(
+                error = %source,
+                "failed to build client while using system root certificates"
+            );
+            Err(BuildCustomCaTransportError::BuildClientWithSystemRoots(
+                source,
+            ))
+        }
+    }
+}
+
+/// Abstracts environment access so tests can cover precedence rules without mutating process-wide
+/// variables.
+trait EnvSource {
+    /// Returns the environment variable value for `key`, if this source considers it set.
+    ///
+    /// Implementations should return `None` for absent values and may also collapse unreadable
+    /// process-environment states into `None`, because the custom CA logic treats both cases as
+    /// "no override configured". Callers build precedence and empty-string handling on top of this
+    /// method, so implementations should not trim or normalize the returned string.
+    fn var(&self, key: &str) -> Option<String>;
+
+    /// Returns a non-empty environment variable value interpreted as a filesystem path.
+    ///
+    /// Empty strings are treated as unset because presence here acts as a boolean "custom CA
+    /// override requested" signal. This keeps the precedence logic from treating `VAR=""` as an
+    /// attempt to open the current working directory or some other platform-specific oddity once
+    /// it is converted into a path.
+    fn non_empty_path(&self, key: &str) -> Option<PathBuf> {
+        self.var(key)
+            .filter(|value| !value.is_empty())
+            .map(PathBuf::from)
+    }
+
+    /// Returns the configured CA bundle and which environment variable selected it.
+    ///
+    /// `CODEX_CA_CERTIFICATE` wins over `SSL_CERT_FILE` because it is the Codex-specific override.
+    /// Keeping the winning variable name with the path lets later logging explain not only which
+    /// file was used but also why that file was chosen.
+    fn configured_ca_bundle(&self) -> Option<ConfiguredCaBundle> {
+        self.non_empty_path(CODEX_CA_CERT_ENV)
+            .map(|path| ConfiguredCaBundle {
+                source_env: CODEX_CA_CERT_ENV,
+                path,
+            })
+            .or_else(|| {
+                self.non_empty_path(SSL_CERT_FILE_ENV)
+                    .map(|path| ConfiguredCaBundle {
+                        source_env: SSL_CERT_FILE_ENV,
+                        path,
+                    })
+            })
+    }
+}
+
+/// Reads CA configuration from the real process environment.
+///
+/// This is the production `EnvSource` implementation used by
+/// [`build_reqwest_client_with_custom_ca`]. Tests substitute in-memory env maps so they can
+/// exercise precedence and empty-value behavior without mutating process-global variables.
+struct ProcessEnv;
+
+impl EnvSource for ProcessEnv {
+    fn var(&self, key: &str) -> Option<String> {
+        env::var(key).ok()
+    }
+}
+
+/// Identifies the CA bundle selected for a client and the policy decision that selected it.
+///
+/// This is the concrete output of the environment-precedence logic. Callers use `source_env` for
+/// logging and diagnostics, while `path` is the bundle that will actually be loaded.
+struct ConfiguredCaBundle {
+    /// The environment variable that won the precedence check for this bundle.
+    source_env: &'static str,
+    /// The filesystem path that should be read as PEM certificate input.
+    path: PathBuf,
+}
+
+impl ConfiguredCaBundle {
+    /// Loads certificates from this selected CA bundle.
+    ///
+    /// The bundle already represents the output of environment-precedence selection, so this is
+    /// the natural point where the file-loading phase begins. The method owns the high-level
+    /// success/failure logs for that phase and keeps the source env and path together for lower-
+    /// level parsing and error shaping.
+    fn load_certificates(
+        &self,
+    ) -> Result<Vec<CertificateDer<'static>>, BuildCustomCaTransportError> {
+        match self.parse_certificates() {
+            Ok(certificates) => {
+                info!(
+                    source_env = self.source_env,
+                    ca_path = %self.path.display(),
+                    certificate_count = certificates.len(),
+                    "loaded certificates from custom CA bundle"
+                );
+                Ok(certificates)
+            }
+            Err(error) => {
+                warn!(
+                    source_env = self.source_env,
+                    ca_path = %self.path.display(),
+                    error = %error,
+                    "failed to load custom CA bundle"
+                );
+                Err(error)
+            }
+        }
+    }
+
+    /// Loads every certificate block from a PEM file intended for Codex CA overrides.
+    ///
+    /// This accepts a few common real-world variants so Codex behaves like other CA-aware tooling:
+    /// leading comments are preserved, `TRUSTED CERTIFICATE` labels are normalized to standard
+    /// certificate labels, and embedded CRLs are ignored when they are well-formed enough for the
+    /// section iterator to classify them.
+    fn parse_certificates(
+        &self,
+    ) -> Result<Vec<CertificateDer<'static>>, BuildCustomCaTransportError> {
+        let pem_data = self.read_pem_data()?;
+        let normalized_pem = NormalizedPem::from_pem_data(self.source_env, &self.path, &pem_data);
+
+        let mut certificates = Vec::new();
+        let mut logged_crl_presence = false;
+        for section_result in normalized_pem.sections() {
+            // Known limitation: if `rustls-pki-types` fails while parsing a malformed CRL section,
+            // that error is reported here before we can classify the block as ignorable. A bundle
+            // containing valid certificates plus a malformed `X509 CRL` therefore still fails to
+            // load today, even though well-formed CRLs are ignored.
+            let (section_kind, der) = match section_result {
+                Ok(section) => section,
+                Err(error) => return Err(self.pem_parse_error(&error)),
+            };
+            match section_kind {
+                SectionKind::Certificate => {
+                    // Standard CERTIFICATE blocks already decode to the exact DER bytes reqwest
+                    // wants. Only OpenSSL TRUSTED CERTIFICATE blocks need trimming to drop any
+                    // trailing X509_AUX trust metadata before registration.
+                    let cert_der = normalized_pem.certificate_der(&der).ok_or_else(|| {
+                        self.invalid_ca_file(
+                            "failed to extract certificate data from TRUSTED CERTIFICATE: invalid DER length",
+                        )
+                    })?;
+                    certificates.push(CertificateDer::from(cert_der.to_vec()));
+                }
+                SectionKind::Crl if !logged_crl_presence => {
+                    info!(
+                        source_env = self.source_env,
+                        ca_path = %self.path.display(),
+                        "ignoring X509 CRL entries found in custom CA bundle"
+                    );
+                    logged_crl_presence = true;
+                }
+                _ => {}
+            }
+        }
+
+        if certificates.is_empty() {
+            return Err(self.pem_parse_error(&pem::Error::NoItemsFound));
+        }
+
+        Ok(certificates)
+    }
+
+    /// Reads the CA bundle bytes while preserving the original filesystem error kind.
+    ///
+    /// The caller wants a user-facing error that includes the bundle path and remediation hint, but
+    /// higher-level surfaces still benefit from distinguishing "not found" from other I/O
+    /// failures. This helper keeps both pieces together.
+    fn read_pem_data(&self) -> Result<Vec<u8>, BuildCustomCaTransportError> {
+        fs::read(&self.path).map_err(|source| BuildCustomCaTransportError::ReadCaFile {
+            source_env: self.source_env,
+            path: self.path.clone(),
+            source,
+        })
+    }
+
+    /// Rewrites PEM parsing failures into user-facing configuration errors.
+    ///
+    /// The underlying parser knows whether the file was empty, malformed, or contained unsupported
+    /// PEM content, but callers need a message that also points them back to the relevant
+    /// environment variables and the expected remediation.
+    fn pem_parse_error(&self, error: &pem::Error) -> BuildCustomCaTransportError {
+        let detail = match error {
+            pem::Error::NoItemsFound => "no certificates found in PEM file".to_string(),
+            _ => format!("failed to parse PEM file: {error}"),
+        };
+
+        self.invalid_ca_file(detail)
+    }
+
+    /// Creates an invalid-CA error tied to this file path.
+    ///
+    /// Most parse-time failures in this module eventually collapse to "the configured CA bundle is
+    /// not usable", but the detailed reason still matters for operator debugging. Centralizing that
+    /// formatting keeps the path and hint text consistent across the different parser branches.
+    fn invalid_ca_file(&self, detail: impl std::fmt::Display) -> BuildCustomCaTransportError {
+        BuildCustomCaTransportError::InvalidCaFile {
+            source_env: self.source_env,
+            path: self.path.clone(),
+            detail: detail.to_string(),
+        }
+    }
+}
+
+/// The PEM text shape after OpenSSL compatibility normalization.
+///
+/// `Standard` means the input already used ordinary PEM certificate labels. `TrustedCertificate`
+/// means the input used OpenSSL's `TRUSTED CERTIFICATE` labels, so callers must also be prepared
+/// to trim trailing `X509_AUX` bytes from decoded certificate sections.
+enum NormalizedPem {
+    /// PEM contents that already used ordinary `CERTIFICATE` labels.
+    Standard(String),
+    /// PEM contents rewritten from OpenSSL `TRUSTED CERTIFICATE` labels to `CERTIFICATE`.
+    TrustedCertificate(String),
+}
+
+impl NormalizedPem {
+    /// Normalizes PEM text from a CA bundle into the label shape this module expects.
+    ///
+    /// Codex only needs certificate DER bytes to seed `reqwest`'s root store, but operators may
+    /// point it at CA files that came from OpenSSL tooling rather than from a minimal certificate
+    /// bundle. OpenSSL's `TRUSTED CERTIFICATE` form is one such variant: it is still certificate
+    /// material, but it uses a different PEM label and may carry auxiliary trust metadata that
+    /// this crate does not consume. This constructor rewrites only the PEM labels so the mixed-
+    /// section parser can keep treating the file as certificate input. The rustls ecosystem does
+    /// not currently accept `TRUSTED CERTIFICATE` as a standard certificate label upstream, so
+    /// this remains a local compatibility shim rather than behavior delegated to
+    /// `rustls-pki-types`.
+    ///
+    /// See also:
+    /// - rustls/pemfile issue #52, closed as not planned, documenting that
+    ///   `BEGIN TRUSTED CERTIFICATE` blocks are ignored upstream:
+    ///   <https://github.com/rustls/pemfile/issues/52>
+    /// - OpenSSL `x509 -trustout`, which emits `TRUSTED CERTIFICATE` PEM blocks:
+    ///   <https://docs.openssl.org/master/man1/openssl-x509/>
+    /// - OpenSSL PEM readers, which document that plain `PEM_read_bio_X509()` discards auxiliary
+    ///   trust settings:
+    ///   <https://docs.openssl.org/master/man3/PEM_read_bio_PrivateKey/>
+    /// - `openssl s_server`, a real OpenSSL-based server/test tool that operates in this
+    ///   ecosystem:
+    ///   <https://docs.openssl.org/master/man1/openssl-s_server/>
+    fn from_pem_data(source_env: &'static str, path: &Path, pem_data: &[u8]) -> Self {
+        let pem = String::from_utf8_lossy(pem_data);
+        if pem.contains("TRUSTED CERTIFICATE") {
+            info!(
+                source_env,
+                ca_path = %path.display(),
+                "normalizing OpenSSL TRUSTED CERTIFICATE labels in custom CA bundle"
+            );
+            Self::TrustedCertificate(
+                pem.replace("BEGIN TRUSTED CERTIFICATE", "BEGIN CERTIFICATE")
+                    .replace("END TRUSTED CERTIFICATE", "END CERTIFICATE"),
+            )
+        } else {
+            Self::Standard(pem.into_owned())
+        }
+    }
+
+    /// Returns the normalized PEM contents regardless of the label shape that produced them.
+    fn contents(&self) -> &str {
+        match self {
+            Self::Standard(contents) | Self::TrustedCertificate(contents) => contents,
+        }
+    }
+
+    /// Iterates over every recognized PEM section in this normalized PEM text.
+    ///
+    /// `rustls-pki-types` exposes mixed-section parsing through a `PemObject` implementation on the
+    /// `(SectionKind, Vec<u8>)` tuple. Keeping that type-directed API here lets callers iterate in
+    /// terms of normalized sections rather than trait plumbing.
+    fn sections(&self) -> impl Iterator<Item = Result<PemSection, pem::Error>> + '_ {
+        PemSection::pem_slice_iter(self.contents().as_bytes())
+    }
+
+    /// Returns the certificate DER bytes for one parsed PEM certificate section.
+    ///
+    /// Standard PEM certificates already decode to the exact DER bytes `reqwest` wants. OpenSSL
+    /// `TRUSTED CERTIFICATE` sections may append `X509_AUX` bytes after the certificate, so those
+    /// sections need to be trimmed down to their first DER object before registration.
+    fn certificate_der<'a>(&self, der: &'a [u8]) -> Option<&'a [u8]> {
+        match self {
+            Self::Standard(_) => Some(der),
+            Self::TrustedCertificate(_) => first_der_item(der),
+        }
+    }
+}
+
+/// Returns the first DER-encoded ASN.1 object in `der`, ignoring any trailing OpenSSL metadata.
+///
+/// A PEM `CERTIFICATE` block usually decodes to exactly one DER blob: the certificate itself.
+/// OpenSSL's `TRUSTED CERTIFICATE` variant is different. It starts with that same certificate
+/// blob, but may append extra `X509_AUX` bytes after it to describe OpenSSL-specific trust
+/// settings. `reqwest::Certificate::from_der` only understands the certificate object, not those
+/// trailing OpenSSL extensions.
+///
+/// This helper therefore asks a narrower question than "is this a valid certificate?": where does
+/// the first top-level DER object end? If that boundary can be found, the caller keeps only that
+/// prefix and discards the trailing trust metadata. If it cannot be found, the input is treated as
+/// malformed CA data.
+fn first_der_item(der: &[u8]) -> Option<&[u8]> {
+    der_item_length(der).map(|length| &der[..length])
+}
+
+/// Returns the byte length of the first DER item in `der`.
+///
+/// DER is a binary encoding for ASN.1 objects. Each object begins with:
+///
+/// - a tag byte describing what kind of object follows
+/// - one or more length bytes describing how many content bytes belong to that object
+/// - the content bytes themselves
+///
+/// For this module, the important fact is that a certificate is stored as one complete top-level
+/// DER object. Once we know that object's declared length, we know exactly where the certificate
+/// ends and where any trailing OpenSSL `X509_AUX` data begins.
+///
+/// This helper intentionally parses only that outer length field. It does not validate the inner
+/// certificate structure, the meaning of the tag, or every nested ASN.1 value. That narrower scope
+/// is deliberate: the caller only needs a safe slice boundary for the leading certificate object
+/// before handing those bytes to `reqwest`, which performs the real certificate parsing.
+///
+/// The implementation supports the DER length forms needed here:
+///
+/// - short form, where the length is stored directly in the second byte
+/// - long form, where the second byte says how many following bytes make up the length value
+///
+/// Indefinite lengths are rejected because DER does not permit them, and any declared length that
+/// would run past the end of the input is treated as malformed.
+fn der_item_length(der: &[u8]) -> Option<usize> {
+    let &length_octet = der.get(1)?;
+    if length_octet & 0x80 == 0 {
+        return Some(2 + usize::from(length_octet)).filter(|length| *length <= der.len());
+    }
+
+    let length_octets = usize::from(length_octet & 0x7f);
+    if length_octets == 0 {
+        return None;
+    }
+
+    let length_start = 2usize;
+    let length_end = length_start.checked_add(length_octets)?;
+    let length_bytes = der.get(length_start..length_end)?;
+    let mut content_length = 0usize;
+    for &byte in length_bytes {
+        content_length = content_length
+            .checked_mul(256)?
+            .checked_add(usize::from(byte))?;
+    }
+
+    length_end
+        .checked_add(content_length)
+        .filter(|length| *length <= der.len())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::HashMap;
+    use std::fs;
+    use std::path::PathBuf;
+
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+
+    use super::BuildCustomCaTransportError;
+    use super::CODEX_CA_CERT_ENV;
+    use super::EnvSource;
+    use super::SSL_CERT_FILE_ENV;
+    use super::maybe_build_rustls_client_config_with_env;
+
+    const TEST_CERT: &str = include_str!("../tests/fixtures/test-ca.pem");
+
+    struct MapEnv {
+        values: HashMap<String, String>,
+    }
+
+    impl EnvSource for MapEnv {
+        fn var(&self, key: &str) -> Option<String> {
+            self.values.get(key).cloned()
+        }
+    }
+
+    fn map_env(pairs: &[(&str, &str)]) -> MapEnv {
+        MapEnv {
+            values: pairs
+                .iter()
+                .map(|(key, value)| ((*key).to_string(), (*value).to_string()))
+                .collect(),
+        }
+    }
+
+    fn write_cert_file(temp_dir: &TempDir, name: &str, contents: &str) -> PathBuf {
+        let path = temp_dir.path().join(name);
+        fs::write(&path, contents).unwrap_or_else(|error| {
+            panic!("write cert fixture failed for {}: {error}", path.display())
+        });
+        path
+    }
+
+    #[test]
+    fn ca_path_prefers_codex_env() {
+        let env = map_env(&[
+            (CODEX_CA_CERT_ENV, "/tmp/codex.pem"),
+            (SSL_CERT_FILE_ENV, "/tmp/fallback.pem"),
+        ]);
+
+        assert_eq!(
+            env.configured_ca_bundle().map(|bundle| bundle.path),
+            Some(PathBuf::from("/tmp/codex.pem"))
+        );
+    }
+
+    #[test]
+    fn ca_path_falls_back_to_ssl_cert_file() {
+        let env = map_env(&[(SSL_CERT_FILE_ENV, "/tmp/fallback.pem")]);
+
+        assert_eq!(
+            env.configured_ca_bundle().map(|bundle| bundle.path),
+            Some(PathBuf::from("/tmp/fallback.pem"))
+        );
+    }
+
+    #[test]
+    fn ca_path_ignores_empty_values() {
+        let env = map_env(&[
+            (CODEX_CA_CERT_ENV, ""),
+            (SSL_CERT_FILE_ENV, "/tmp/fallback.pem"),
+        ]);
+
+        assert_eq!(
+            env.configured_ca_bundle().map(|bundle| bundle.path),
+            Some(PathBuf::from("/tmp/fallback.pem"))
+        );
+    }
+
+    #[test]
+    fn rustls_config_uses_custom_ca_bundle_when_configured() {
+        let temp_dir = TempDir::new().expect("tempdir");
+        let cert_path = write_cert_file(&temp_dir, "ca.pem", TEST_CERT);
+        let env = map_env(&[(CODEX_CA_CERT_ENV, cert_path.to_string_lossy().as_ref())]);
+
+        let config = maybe_build_rustls_client_config_with_env(&env)
+            .expect("rustls config")
+            .expect("custom CA config should be present");
+
+        assert!(config.enable_sni);
+    }
+
+    #[test]
+    fn rustls_config_reports_invalid_ca_file() {
+        let temp_dir = TempDir::new().expect("tempdir");
+        let cert_path = write_cert_file(&temp_dir, "empty.pem", "");
+        let env = map_env(&[(CODEX_CA_CERT_ENV, cert_path.to_string_lossy().as_ref())]);
+
+        let error = maybe_build_rustls_client_config_with_env(&env).expect_err("invalid CA");
+
+        assert!(matches!(
+            error,
+            BuildCustomCaTransportError::InvalidCaFile { .. }
+        ));
+    }
+}
+
+#[cfg(test)]
+#[path = "custom_ca_tls_tests.rs"]
+mod tls_tests;
diff --git a/codex-rs/http-client/src/custom_ca_tls_tests.rs b/codex-rs/http-client/src/custom_ca_tls_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fb3c78fe14701cb78dd85f5aab3c4b0932bf6d4e
--- /dev/null
+++ b/codex-rs/http-client/src/custom_ca_tls_tests.rs
@@ -0,0 +1,79 @@
+//! Handshake coverage for the custom trust path retained by Windows realtime connections.
+
+use super::CODEX_CA_CERT_ENV;
+use super::ConfiguredCaBundle;
+use super::build_rustls_client_config;
+use pretty_assertions::assert_eq;
+use rcgen::BasicConstraints;
+use rcgen::CertificateParams;
+use rcgen::CertifiedIssuer;
+use rcgen::IsCa;
+use rcgen::KeyPair;
+use std::sync::Arc;
+
+#[test]
+fn custom_intermediate_trust_preserves_hostname_validation() {
+    let mut params = CertificateParams::default();
+    params.is_ca = IsCa::Ca(BasicConstraints::Unconstrained);
+    let root = CertifiedIssuer::self_signed(params.clone(), KeyPair::generate().unwrap()).unwrap();
+    let intermediate =
+        CertifiedIssuer::signed_by(params, KeyPair::generate().unwrap(), &root).unwrap();
+    let leaf_key = KeyPair::generate().unwrap();
+    let leaf = CertificateParams::new(vec!["localhost".to_string()])
+        .unwrap()
+        .signed_by(&leaf_key, &intermediate)
+        .unwrap();
+    let temp = tempfile::TempDir::new().unwrap();
+    let path = temp.path().join("intermediate.pem");
+    std::fs::write(&path, intermediate.pem()).unwrap();
+    let config = build_rustls_client_config(Some(&ConfiguredCaBundle {
+        source_env: CODEX_CA_CERT_ENV,
+        path,
+    }))
+    .unwrap();
+    let server = Arc::new(
+        rustls::ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![leaf.der().clone()], leaf_key.into())
+            .unwrap(),
+    );
+
+    assert_eq!(
+        handshake(config.clone(), server.clone(), "localhost"),
+        Ok(())
+    );
+    let error = handshake(config, server, "wrong.example").unwrap_err();
+    assert!(
+        matches!(
+            error,
+            rustls::Error::InvalidCertificate(
+                rustls::CertificateError::NotValidForName
+                    | rustls::CertificateError::NotValidForNameContext { .. }
+            )
+        ),
+        "{error:?}"
+    );
+}
+
+fn handshake(
+    config: Arc<rustls::ClientConfig>,
+    server: Arc<rustls::ServerConfig>,
+    hostname: &'static str,
+) -> Result<(), rustls::Error> {
+    let mut client = rustls::ClientConnection::new(config, hostname.try_into().unwrap()).unwrap();
+    let mut server = rustls::ServerConnection::new(server).unwrap();
+    for _ in 0..10 {
+        let mut bytes = Vec::new();
+        client.write_tls(&mut bytes).unwrap();
+        server.read_tls(&mut bytes.as_slice()).unwrap();
+        server.process_new_packets()?;
+        bytes.clear();
+        server.write_tls(&mut bytes).unwrap();
+        client.read_tls(&mut bytes.as_slice()).unwrap();
+        client.process_new_packets()?;
+        if !client.is_handshaking() {
+            return Ok(());
+        }
+    }
+    panic!("handshake did not complete");
+}
diff --git a/codex-rs/http-client/src/error.rs b/codex-rs/http-client/src/error.rs
new file mode 100644
index 0000000000000000000000000000000000000000..43ace4f7a78ecab1153e548a1205b77b93d60349
--- /dev/null
+++ b/codex-rs/http-client/src/error.rs
@@ -0,0 +1,37 @@
+//! Errors returned by the shared Codex HTTP transport.
+
+use crate::client::HttpError;
+use http::HeaderMap;
+use http::StatusCode;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum TransportError {
+    #[error("http {status}: {body:?}")]
+    Http {
+        status: StatusCode,
+        url: Option<String>,
+        headers: Option<HeaderMap>,
+        body: Option<String>,
+    },
+    #[error("retry limit reached")]
+    RetryLimit,
+    #[error("timeout")]
+    Timeout,
+    #[error("connection failed: {0}")]
+    Connection(#[source] HttpError),
+    #[error("network error: {0}")]
+    Network(String),
+    #[error("request build error: {0}")]
+    Build(String),
+    #[error("response body exceeds the {max_bytes} byte limit")]
+    ResponseTooLarge { max_bytes: usize },
+}
+
+#[derive(Debug, Error)]
+pub enum StreamError {
+    #[error("stream failed: {0}")]
+    Stream(String),
+    #[error("timeout")]
+    Timeout,
+}
diff --git a/codex-rs/http-client/src/lib.rs b/codex-rs/http-client/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f9cdb1fb2066c479764d919c1381d15ab206bd93
--- /dev/null
+++ b/codex-rs/http-client/src/lib.rs
@@ -0,0 +1,72 @@
+mod chatgpt_cloudflare_cookies;
+mod chatgpt_hosts;
+mod client;
+mod client_builder;
+mod custom_ca;
+mod error;
+mod network_policy;
+mod outbound_proxy;
+mod request;
+mod route_aware_client_pool;
+mod route_aware_redirect;
+mod tls_backend_fallback;
+mod transport;
+
+pub use crate::chatgpt_cloudflare_cookies::with_chatgpt_cloudflare_cookie_store;
+pub use crate::chatgpt_hosts::is_allowed_chatgpt_host;
+pub use crate::client::HttpClient;
+pub use crate::client::HttpError;
+pub use crate::client::HttpResponse;
+pub use crate::client::RequestBuilder;
+pub use crate::client_builder::HttpClientBuilder;
+pub use crate::custom_ca::BuildCustomCaTransportError;
+/// Test-only subprocess hook for custom CA coverage.
+///
+/// This stays public only so the `custom_ca_probe` binary target can reuse the shared helper. It
+/// is hidden from normal docs because ordinary callers should use
+/// [`build_reqwest_client_with_custom_ca`] instead.
+#[doc(hidden)]
+pub use crate::custom_ca::build_reqwest_client_for_subprocess_tests;
+pub use crate::custom_ca::build_reqwest_client_with_custom_ca;
+pub use crate::custom_ca::build_rustls_client_config_with_custom_ca;
+pub use crate::custom_ca::maybe_build_rustls_client_config_with_custom_ca;
+pub use crate::error::StreamError;
+pub use crate::error::TransportError;
+pub use crate::network_policy::DestinationPolicy;
+pub use crate::network_policy::NetworkPermit;
+pub use crate::network_policy::NetworkPolicy;
+pub use crate::network_policy::NetworkPolicyController;
+pub use crate::network_policy::NetworkPolicyDenied;
+pub use crate::network_policy::NetworkPolicyRevision;
+pub use crate::outbound_proxy::BuildRouteAwareHttpClientError;
+pub use crate::outbound_proxy::ClientRouteClass;
+pub use crate::outbound_proxy::HttpClientFactory;
+#[cfg(target_os = "macos")]
+pub use crate::outbound_proxy::MacosSystemProxyConfiguration;
+pub use crate::outbound_proxy::OutboundProxyPolicy;
+pub use crate::outbound_proxy::OutboundProxyRoute;
+pub use crate::outbound_proxy::RouteFailureClass;
+#[doc(hidden)]
+pub use crate::outbound_proxy::cache_system_proxy_route_for_test;
+#[cfg(target_os = "macos")]
+pub use crate::outbound_proxy::macos_system_proxy_configuration;
+pub use crate::request::EncodedJsonBody;
+pub use crate::request::PreparedRequestBody;
+pub use crate::request::Request;
+pub use crate::request::RequestBody;
+pub use crate::request::RequestCompression;
+pub use crate::request::Response;
+pub use crate::route_aware_client_pool::RouteAwareClientPool;
+pub use crate::route_aware_client_pool::RouteAwareClientPoolError;
+pub use crate::route_aware_client_pool::RouteAwareRequestBuilder;
+pub use crate::route_aware_client_pool::RouteAwareRequestError;
+pub use crate::transport::ByteStream;
+pub use crate::transport::HttpTransport;
+pub use crate::transport::ReqwestTransport;
+pub use crate::transport::StreamResponse;
+
+#[cfg(windows)]
+mod windows_tls;
+
+#[cfg(windows)]
+pub use crate::windows_tls::build_windows_platform_tls_config;
diff --git a/codex-rs/http-client/src/network_policy.rs b/codex-rs/http-client/src/network_policy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fa92421d60d60d1cf0415f25a404f33001177bb5
--- /dev/null
+++ b/codex-rs/http-client/src/network_policy.rs
@@ -0,0 +1,353 @@
+//! Application destination checks and revocation of outstanding network operations.
+//!
+//! The configuration owner publishes an already-composed policy. Transports retain only its
+//! read side and a permit for each request; invalidation cannot leave an old request authorized.
+
+use std::collections::BTreeSet;
+use std::fmt;
+use std::future::Future;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::MutexGuard;
+use std::sync::Weak;
+
+use reqwest::Url;
+use tokio::sync::watch;
+
+/// Effective application destinations, after the requirements owner has applied precedence.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum DestinationPolicy {
+    Unrestricted,
+    /// Only HTTPS and WSS requests to these exact, normalized hosts are permitted.
+    Restricted {
+        allowed_hosts: BTreeSet<String>,
+    },
+}
+
+impl DestinationPolicy {
+    fn allows(&self, url: &Url) -> bool {
+        match self {
+            Self::Unrestricted => true,
+            Self::Restricted { allowed_hosts } => {
+                matches!(url.scheme(), "https" | "wss")
+                    && url.host_str().is_some_and(|host| {
+                        allowed_hosts.contains(host.strip_suffix('.').unwrap_or(host))
+                    })
+            }
+        }
+    }
+}
+
+/// A deterministic denial, distinct from retryable network failures.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
+pub enum NetworkPolicyDenied {
+    #[error("application network policy is unavailable")]
+    Unavailable,
+    #[error("destination denied by application network policy")]
+    Destination,
+    #[error("application network permission was revoked")]
+    Revoked,
+    #[error("this SDK transport is disabled by application network restrictions")]
+    UnsupportedTransport,
+}
+
+/// Read access to application policy. Clones observe the same updates.
+#[derive(Clone, Default)]
+pub struct NetworkPolicy {
+    state: Option<Arc<Mutex<State>>>,
+    endpoints: Option<Arc<BTreeSet<Url>>>,
+    account: Option<u64>,
+}
+
+impl fmt::Debug for NetworkPolicy {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("NetworkPolicy")
+            .field("managed", &self.state.is_some())
+            .finish_non_exhaustive()
+    }
+}
+
+impl PartialEq for NetworkPolicy {
+    fn eq(&self, other: &Self) -> bool {
+        self.endpoints == other.endpoints
+            && self.account == other.account
+            && match (&self.state, &other.state) {
+                (Some(left), Some(right)) => Arc::ptr_eq(left, right),
+                (None, None) => true,
+                (Some(_), None) | (None, Some(_)) => false,
+            }
+    }
+}
+
+impl Eq for NetworkPolicy {}
+
+struct State {
+    policy: Option<DestinationPolicy>,
+    revision: u64,
+    account: u64,
+    permits: Vec<Weak<Permit>>,
+    changes: watch::Sender<()>,
+}
+
+struct Permit {
+    destination: PermitDestination,
+    revoked: watch::Sender<bool>,
+}
+
+enum PermitDestination {
+    Url(Url),
+    UnrestrictedSdk,
+}
+
+impl PermitDestination {
+    fn allowed_by(&self, policy: &DestinationPolicy) -> bool {
+        match self {
+            Self::Url(url) => policy.allows(url),
+            Self::UnrestrictedSdk => matches!(policy, DestinationPolicy::Unrestricted),
+        }
+    }
+}
+
+/// Publication access retained by the account/configuration owner.
+#[derive(Clone)]
+pub struct NetworkPolicyController {
+    state: Arc<Mutex<State>>,
+}
+
+/// Identifies the account/configuration generation that a load is allowed to publish into.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct NetworkPolicyRevision(u64);
+
+impl Default for NetworkPolicyController {
+    fn default() -> Self {
+        Self {
+            state: Arc::new(Mutex::new(State {
+                policy: None,
+                revision: 0,
+                account: 0,
+                permits: Vec::new(),
+                changes: watch::channel(()).0,
+            })),
+        }
+    }
+}
+
+fn lock_state(state: &Mutex<State>) -> MutexGuard<'_, State> {
+    state
+        .lock()
+        .unwrap_or_else(|_| panic!("application network policy lock poisoned"))
+}
+
+impl NetworkPolicyController {
+    pub fn policy(&self) -> NetworkPolicy {
+        NetworkPolicy {
+            state: Some(self.state.clone()),
+            endpoints: None,
+            account: None,
+        }
+    }
+
+    /// Fails a requirements load without changing the current account identity.
+    pub fn unavailable(&self, revision: NetworkPolicyRevision) {
+        let mut state = lock_state(&self.state);
+        if state.revision != revision.0 {
+            return;
+        }
+        if state.policy.take().is_some() {
+            state.changes.send_replace(());
+        }
+        for permit in state
+            .permits
+            .drain(..)
+            .filter_map(|permit| permit.upgrade())
+        {
+            permit.revoked.send_replace(/*value*/ true);
+        }
+    }
+
+    /// Publishes a successful load only if its account/configuration generation is still current.
+    pub fn publish(&self, revision: NetworkPolicyRevision, policy: DestinationPolicy) -> bool {
+        let mut state = lock_state(&self.state);
+        if state.revision != revision.0 {
+            return false;
+        }
+        state.permits.retain(|permit| {
+            let Some(permit) = permit.upgrade() else {
+                return false;
+            };
+            if !permit.destination.allowed_by(&policy) {
+                permit.revoked.send_replace(/*value*/ true);
+            }
+            true
+        });
+        if state.policy.as_ref() != Some(&policy) {
+            state.policy = Some(policy);
+            state.changes.send_replace(());
+        }
+        true
+    }
+}
+
+impl NetworkPolicy {
+    pub const fn unmanaged() -> Self {
+        Self {
+            state: None,
+            endpoints: None,
+            account: None,
+        }
+    }
+
+    /// Binds a content client to the current account so retained credentials cannot
+    /// be used after another workspace's policy has been installed.
+    pub fn for_current_account(mut self) -> Self {
+        self.account = self.state.as_ref().map(|state| lock_state(state).account);
+        self
+    }
+
+    /// Whether this transport participates in the application policy lifecycle.
+    pub fn is_managed(&self) -> bool {
+        self.state.is_some()
+    }
+
+    /// Watches effective changes; unmanaged callers have no application policy owner.
+    pub fn changes(&self) -> Option<watch::Receiver<()>> {
+        self.state
+            .as_ref()
+            .map(|state| lock_state(state).changes.subscribe())
+    }
+
+    pub fn revision(&self) -> NetworkPolicyRevision {
+        NetworkPolicyRevision(
+            self.state
+                .as_ref()
+                .map_or(0, |state| lock_state(state).revision),
+        )
+    }
+
+    /// Revokes outstanding operations before an account change or a failed requirements load.
+    /// This read-side operation can only remove access; publication stays with the controller.
+    pub fn invalidate(&self) {
+        if let Some(state) = &self.state {
+            let mut state = lock_state(state);
+            state.revision += 1;
+            state.account += 1;
+            state.policy = None;
+            state.changes.send_replace(());
+            for permit in state
+                .permits
+                .drain(..)
+                .filter_map(|permit| permit.upgrade())
+            {
+                permit.revoked.send_replace(/*value*/ true);
+            }
+        }
+    }
+
+    /// Checks a destination before proxy resolution, DNS, or transport work starts.
+    pub fn acquire(&self, url: &Url) -> Result<NetworkPermit, NetworkPolicyDenied> {
+        if self
+            .endpoints
+            .as_ref()
+            .is_some_and(|endpoints| !endpoints.contains(url))
+        {
+            return Err(NetworkPolicyDenied::Destination);
+        }
+        self.acquire_destination(PermitDestination::Url(url.clone()))
+    }
+
+    /// Disables SDKs without destination enforcement whenever restrictions apply.
+    /// The returned permit also cancels work if an unrestricted policy changes.
+    pub fn acquire_for_unsupported_sdk(&self) -> Result<NetworkPermit, NetworkPolicyDenied> {
+        if self.endpoints.is_some() {
+            return Err(NetworkPolicyDenied::UnsupportedTransport);
+        }
+        self.acquire_destination(PermitDestination::UnrestrictedSdk)
+    }
+
+    fn acquire_destination(
+        &self,
+        destination: PermitDestination,
+    ) -> Result<NetworkPermit, NetworkPolicyDenied> {
+        let Some(state) = &self.state else {
+            return Ok(NetworkPermit { inner: None });
+        };
+        let mut state = lock_state(state);
+        if self.account.is_some_and(|account| account != state.account) {
+            return Err(NetworkPolicyDenied::Revoked);
+        }
+        let policy = state
+            .policy
+            .as_ref()
+            .ok_or(NetworkPolicyDenied::Unavailable)?;
+        if !destination.allowed_by(policy) {
+            return Err(match destination {
+                PermitDestination::Url(_) => NetworkPolicyDenied::Destination,
+                PermitDestination::UnrestrictedSdk => NetworkPolicyDenied::UnsupportedTransport,
+            });
+        }
+        let (revoked, _) = watch::channel(/*init*/ false);
+        let permit = Arc::new(Permit {
+            destination,
+            revoked,
+        });
+        state.permits.retain(|permit| permit.strong_count() != 0);
+        state.permits.push(Arc::downgrade(&permit));
+        Ok(NetworkPermit {
+            inner: Some(permit),
+        })
+    }
+}
+
+/// Authorization retained for the entire operation, including response or WebSocket streaming.
+#[derive(Clone)]
+pub struct NetworkPermit {
+    inner: Option<Arc<Permit>>,
+}
+
+impl fmt::Debug for NetworkPermit {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("NetworkPermit").finish_non_exhaustive()
+    }
+}
+
+impl NetworkPermit {
+    pub fn check(&self) -> Result<(), NetworkPolicyDenied> {
+        if self
+            .inner
+            .as_ref()
+            .is_some_and(|permit| *permit.revoked.borrow())
+        {
+            Err(NetworkPolicyDenied::Revoked)
+        } else {
+            Ok(())
+        }
+    }
+
+    pub async fn revoked(&self) {
+        match &self.inner {
+            Some(permit) => {
+                let _ = permit
+                    .revoked
+                    .subscribe()
+                    .wait_for(|revoked| *revoked)
+                    .await;
+            }
+            None => std::future::pending().await,
+        }
+    }
+
+    pub async fn run<T>(
+        &self,
+        operation: impl Future<Output = T>,
+    ) -> Result<T, NetworkPolicyDenied> {
+        tokio::select! {
+            biased;
+            _ = self.revoked() => Err(NetworkPolicyDenied::Revoked),
+            result = operation => Ok(result),
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "network_policy_tests.rs"]
+mod tests;
diff --git a/codex-rs/http-client/src/network_policy_tests.rs b/codex-rs/http-client/src/network_policy_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..dd9787136501deedecb64fd88697d8ad00caca80
--- /dev/null
+++ b/codex-rs/http-client/src/network_policy_tests.rs
@@ -0,0 +1,110 @@
+//! Destination matching, bootstrap scope, and account revocation behavior.
+
+use std::collections::BTreeSet;
+
+use pretty_assertions::assert_eq;
+use reqwest::Url;
+
+use super::*;
+
+#[test]
+fn restricted_policy_matches_exact_secure_hosts() {
+    let controller = NetworkPolicyController::default();
+    let policy = controller.policy();
+    assert!(controller.publish(
+        policy.revision(),
+        DestinationPolicy::Restricted {
+            allowed_hosts: BTreeSet::from(["example.com".to_string()]),
+        }
+    ));
+    for (url, expected) in [
+        ("https://EXAMPLE.com/path", true),
+        ("https://example.com.:8443/path", true),
+        ("wss://example.com/path", true),
+        ("http://example.com/path", false),
+        ("ws://example.com/path", false),
+        ("https://sub.example.com/path", false),
+        ("https://example.com.evil.test/path", false),
+        ("https://example.com@evil.test/path", false),
+        ("https://127.0.0.1/path", false),
+    ] {
+        assert_eq!(
+            policy.acquire(&Url::parse(url).unwrap()).is_ok(),
+            expected,
+            "{url}"
+        );
+    }
+}
+
+#[tokio::test]
+async fn invalidation_revokes_existing_permits_and_rejects_stale_publication() {
+    let controller = NetworkPolicyController::default();
+    let policy = controller.policy();
+    let url = Url::parse("https://example.com").unwrap();
+    assert_eq!(
+        policy.acquire(&url).unwrap_err(),
+        NetworkPolicyDenied::Unavailable
+    );
+    let previous = policy.revision();
+    assert!(controller.publish(previous, DestinationPolicy::Unrestricted));
+    let permit = policy.acquire(&url).unwrap();
+    policy.invalidate();
+    assert!(!controller.publish(previous, DestinationPolicy::Unrestricted));
+    assert!(controller.publish(policy.revision(), DestinationPolicy::Unrestricted));
+    assert_eq!(
+        permit.run(async { "should not run" }).await,
+        Err(NetworkPolicyDenied::Revoked)
+    );
+    assert!(policy.acquire(&url).is_ok());
+}
+
+#[tokio::test]
+async fn load_failure_recovers_current_account_but_cannot_revive_previous_account() {
+    let controller = NetworkPolicyController::default();
+    let policy = controller.policy();
+    let account = policy.clone().for_current_account();
+    let url = Url::parse("https://example.com").unwrap();
+    let mut changes = policy.changes().unwrap();
+    controller.publish(policy.revision(), DestinationPolicy::Unrestricted);
+    changes.changed().await.unwrap();
+    controller.publish(policy.revision(), DestinationPolicy::Unrestricted);
+    assert!(!changes.has_changed().unwrap());
+    let old_request = account.acquire(&url).unwrap();
+    controller.unavailable(policy.revision());
+    assert_eq!(
+        account.acquire(&url).unwrap_err(),
+        NetworkPolicyDenied::Unavailable
+    );
+    controller.publish(policy.revision(), DestinationPolicy::Unrestricted);
+    assert!(account.acquire(&url).is_ok());
+    assert_eq!(old_request.check(), Err(NetworkPolicyDenied::Revoked));
+    policy.invalidate();
+    controller.publish(policy.revision(), DestinationPolicy::Unrestricted);
+    assert_eq!(
+        account.acquire(&url).unwrap_err(),
+        NetworkPolicyDenied::Revoked
+    );
+    assert!(policy.for_current_account().acquire(&url).is_ok());
+}
+
+#[tokio::test]
+async fn unsupported_sdk_work_is_denied_and_running_work_is_cancelled() {
+    let controller = NetworkPolicyController::default();
+    let policy = controller.policy();
+    controller.publish(policy.revision(), DestinationPolicy::Unrestricted);
+    let permit = policy.acquire_for_unsupported_sdk().unwrap();
+    controller.publish(
+        policy.revision(),
+        DestinationPolicy::Restricted {
+            allowed_hosts: BTreeSet::from(["example.com".to_string()]),
+        },
+    );
+    assert_eq!(
+        policy.acquire_for_unsupported_sdk().unwrap_err(),
+        NetworkPolicyDenied::UnsupportedTransport
+    );
+    assert_eq!(
+        permit.run(std::future::pending::<()>()).await,
+        Err(NetworkPolicyDenied::Revoked)
+    );
+}
diff --git a/codex-rs/http-client/src/outbound_proxy.rs b/codex-rs/http-client/src/outbound_proxy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..64713478ec079cde90997f97209c87808a3b7e8b
--- /dev/null
+++ b/codex-rs/http-client/src/outbound_proxy.rs
@@ -0,0 +1,896 @@
+//! Conservative outbound proxy selection for resolver-aware HTTP clients.
+//!
+//! When enabled, platform system discovery is tried first, explicit environment
+//! proxies are the fallback, and the final fallback is a direct connection.
+//! When disabled, callers retain the existing reqwest builder behavior.
+
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::fmt;
+use std::io;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::OnceLock;
+use std::time::Duration;
+use std::time::Instant;
+#[cfg(any(target_os = "windows", target_os = "macos"))]
+use tokio::sync::Semaphore;
+
+use http::HeaderValue;
+
+use crate::NetworkPolicy;
+use crate::chatgpt_cloudflare_cookies::ChatGptCookieStore;
+use crate::custom_ca::BuildCustomCaTransportError;
+use crate::custom_ca::build_reqwest_client_with_custom_ca;
+use sha2::Digest;
+use sha2::Sha256;
+use thiserror::Error;
+
+const SYSTEM_PROXY_SUCCESS_CACHE_TTL: Duration = Duration::from_secs(60);
+const SYSTEM_PROXY_UNAVAILABLE_CACHE_TTL: Duration = Duration::from_secs(5);
+const SYSTEM_PROXY_CACHE_MAX_ENTRIES: usize = 256;
+#[cfg(any(target_os = "windows", target_os = "macos"))]
+static ASYNC_SYSTEM_PROXY_RESOLUTION_PERMIT: Semaphore = Semaphore::const_new(1);
+
+#[cfg(target_os = "macos")]
+mod macos;
+#[cfg(target_os = "windows")]
+mod windows;
+
+/// Coarse semantic bucket for the HTTP or WebSocket client being constructed.
+///
+/// This is not the selected proxy route or a concrete endpoint. It labels the
+/// product path that owns the client so proxy-resolution diagnostics can
+/// distinguish auth, API, WebSocket, and miscellaneous traffic without exposing
+/// endpoint details.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientRouteClass {
+    /// Login, token refresh/revoke, PAT, and agent identity auth traffic.
+    Auth,
+    /// First-party API traffic that is not part of the auth flow.
+    Api,
+    /// WebSocket traffic.
+    WebSocket,
+    /// Call sites without a more specific route class.
+    Other,
+}
+
+impl fmt::Display for ClientRouteClass {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::Auth => "auth",
+            Self::Api => "api",
+            Self::WebSocket => "wss",
+            Self::Other => "other",
+        })
+    }
+}
+
+/// Coarse failure class for route selection errors.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RouteFailureClass {
+    ProxyResolutionUnavailable,
+    ConnectTimeout,
+    ProxyAuthenticationRequired,
+    TlsError,
+    InvalidProxyConfig,
+    UnsupportedProxyScheme,
+    ResolverError,
+}
+
+impl fmt::Display for RouteFailureClass {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::ProxyResolutionUnavailable => "proxy_resolution_unavailable",
+            Self::ConnectTimeout => "connect_timeout",
+            Self::ProxyAuthenticationRequired => "proxy_407",
+            Self::TlsError => "tls_error",
+            Self::InvalidProxyConfig => "invalid_proxy_config",
+            Self::UnsupportedProxyScheme => "unsupported_proxy_scheme",
+            Self::ResolverError => "resolver_error",
+        })
+    }
+}
+
+/// Resolved outbound proxy behavior for HTTP clients.
+///
+/// Callers must choose a policy explicitly so omitting feature resolution cannot silently select
+/// legacy behavior.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OutboundProxyPolicy {
+    /// Preserve reqwest's built-in proxy behavior.
+    ReqwestDefault,
+    /// Resolve system/PAC/WPAD settings, then environment settings, then direct routing.
+    RespectSystemProxy,
+}
+
+/// Privacy-safe macOS system proxy configuration for one outbound destination.
+#[cfg(target_os = "macos")]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MacosSystemProxyConfiguration {
+    /// A PAC script or automatic proxy-discovery route applies to the destination.
+    Automatic,
+    /// An explicitly configured HTTP or HTTPS proxy applies.
+    Manual,
+    /// macOS selected a direct connection for the destination.
+    Direct,
+    /// The destination or system proxy settings could not be inspected.
+    Unavailable,
+}
+
+/// Inspects macOS proxy configuration without executing PAC scripts or exposing proxy URLs.
+#[cfg(target_os = "macos")]
+pub fn macos_system_proxy_configuration(request_url: &str) -> MacosSystemProxyConfiguration {
+    macos::configuration(request_url)
+}
+
+/// Resolved proxy route for a concrete outbound destination.
+///
+/// `TransportDefault` preserves the underlying transport behavior only when system-proxy support
+/// is disabled. When system resolution is enabled, environment and direct fallbacks are resolved
+/// explicitly so the transport cannot repeat system discovery. Proxy URLs and no-proxy settings
+/// are intentionally redacted from `Debug` output because they may contain credentials or private
+/// hostnames.
+#[derive(Clone, Hash, PartialEq, Eq)]
+pub enum OutboundProxyRoute {
+    /// Preserve the underlying transport's existing proxy behavior.
+    TransportDefault,
+    /// Connect directly and bypass transport-level proxy discovery.
+    Direct,
+    /// Connect through the selected proxy URL.
+    Proxy {
+        url: String,
+        no_proxy: Option<String>,
+    },
+}
+
+impl fmt::Debug for OutboundProxyRoute {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::TransportDefault => f.write_str("TransportDefault"),
+            Self::Direct => f.write_str("Direct"),
+            Self::Proxy { .. } => f
+                .debug_struct("Proxy")
+                .field("url", &"<redacted>")
+                .field("no_proxy", &"<redacted>")
+                .finish(),
+        }
+    }
+}
+
+/// Builds route-specific HTTP clients using one resolved outbound proxy policy.
+///
+/// Construct this once from the effective application configuration and carry it with the
+/// session or component that owns outbound requests. Individual request paths should supply only
+/// their destination and route class rather than resolving feature state themselves.
+#[derive(Clone)]
+pub struct HttpClientFactory {
+    outbound_proxy_policy: OutboundProxyPolicy,
+    chatgpt_cookie_store: Option<Arc<ChatGptCookieStore>>,
+    network_policy: NetworkPolicy,
+}
+
+impl PartialEq for HttpClientFactory {
+    fn eq(&self, other: &Self) -> bool {
+        self.outbound_proxy_policy == other.outbound_proxy_policy
+            && self.network_policy == other.network_policy
+            && self
+                .chatgpt_cookie_store
+                .as_ref()
+                .map(|store| store.configured_cookies())
+                == other
+                    .chatgpt_cookie_store
+                    .as_ref()
+                    .map(|store| store.configured_cookies())
+    }
+}
+
+impl Eq for HttpClientFactory {}
+
+impl fmt::Debug for HttpClientFactory {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("HttpClientFactory")
+            .field("outbound_proxy_policy", &self.outbound_proxy_policy)
+            .field("network_policy", &self.network_policy)
+            .finish()
+    }
+}
+
+impl HttpClientFactory {
+    /// Creates a factory from the outbound proxy policy resolved by the application.
+    pub const fn new(outbound_proxy_policy: OutboundProxyPolicy) -> Self {
+        Self {
+            outbound_proxy_policy,
+            chatgpt_cookie_store: None,
+            network_policy: NetworkPolicy::unmanaged(),
+        }
+    }
+
+    /// Carries the account/configuration owner's application policy into every transport.
+    pub fn with_network_policy(mut self, policy: NetworkPolicy) -> Self {
+        self.network_policy = policy;
+        self
+    }
+
+    pub fn network_policy(&self) -> &NetworkPolicy {
+        &self.network_policy
+    }
+
+    /// Adds process-scoped cookies to requests made by ChatGPT cookie-store clients.
+    pub fn with_chatgpt_cookies(mut self, cookies: impl IntoIterator<Item = HeaderValue>) -> Self {
+        let cookies = cookies.into_iter().collect::<Vec<_>>();
+        self.chatgpt_cookie_store =
+            (!cookies.is_empty()).then(|| Arc::new(ChatGptCookieStore::new(cookies)));
+        self
+    }
+
+    /// Returns whether ChatGPT cookie-store clients have additional configured cookies.
+    pub fn has_chatgpt_cookies(&self) -> bool {
+        self.chatgpt_cookie_store.is_some()
+    }
+
+    pub(crate) fn chatgpt_cookie_store(&self) -> Option<Arc<ChatGptCookieStore>> {
+        self.chatgpt_cookie_store.clone()
+    }
+
+    /// Returns the outbound proxy policy used for clients built by this factory.
+    pub const fn outbound_proxy_policy(&self) -> OutboundProxyPolicy {
+        self.outbound_proxy_policy
+    }
+
+    /// Resolves the proxy route for a concrete destination.
+    ///
+    /// WebSocket schemes are resolved through their HTTP equivalents so platform PAC and system
+    /// proxy APIs apply the same policy to `ws`/`wss` and `http`/`https` destinations. When system
+    /// resolution is unavailable, explicit environment settings are resolved before falling back
+    /// to a direct route.
+    pub fn resolve_proxy_route(&self, request_url: &str) -> OutboundProxyRoute {
+        resolve_proxy_route(
+            &ProcessEnv,
+            request_url,
+            self.outbound_proxy_policy,
+            resolve_system_proxy,
+        )
+    }
+
+    /// Resolves the proxy route for a concrete destination without blocking a Tokio worker.
+    pub async fn resolve_proxy_route_async(
+        &self,
+        request_url: String,
+    ) -> io::Result<OutboundProxyRoute> {
+        if matches!(
+            self.outbound_proxy_policy,
+            OutboundProxyPolicy::ReqwestDefault
+        ) {
+            return Ok(OutboundProxyRoute::TransportDefault);
+        }
+
+        if let Some(route) = self.cached_proxy_route(&request_url) {
+            return Ok(route);
+        }
+
+        #[cfg(not(any(target_os = "windows", target_os = "macos")))]
+        return Ok(self.resolve_proxy_route(&request_url));
+
+        #[cfg(any(target_os = "windows", target_os = "macos"))]
+        {
+            let permit = ASYNC_SYSTEM_PROXY_RESOLUTION_PERMIT
+                .acquire()
+                .await
+                .map_err(io::Error::other)?;
+            let factory = self.clone();
+            tokio::task::spawn_blocking(move || {
+                // Keep the permit with the blocking task: cancelling the caller must not allow a
+                // second PAC/WinHTTP lookup to start while this one is still running.
+                let _permit = permit;
+                factory.resolve_proxy_route(&request_url)
+            })
+            .await
+            .map_err(io::Error::other)
+        }
+    }
+
+    fn cached_proxy_route(&self, request_url: &str) -> Option<OutboundProxyRoute> {
+        let env_proxy_kind = EnvProxyKind::from_request_url(request_url);
+        let request_url = proxy_resolution_url(request_url);
+        if RequestOrigin::parse(&request_url).is_none() {
+            return Some(OutboundProxyRoute::Direct);
+        }
+        cached_system_proxy_decision(&request_url)
+            .map(|decision| route_from_system_decision(&ProcessEnv, env_proxy_kind, decision))
+    }
+
+    /// Builds a reqwest client for a concrete outbound route.
+    pub fn build_reqwest_client(
+        &self,
+        builder: reqwest::ClientBuilder,
+        request_url: &str,
+        route_class: ClientRouteClass,
+    ) -> Result<reqwest::Client, BuildRouteAwareHttpClientError> {
+        build_reqwest_client_for_route(
+            builder,
+            request_url,
+            route_class,
+            self.outbound_proxy_policy,
+        )
+    }
+
+    pub(crate) fn build_reqwest_client_for_resolved_route(
+        &self,
+        builder: reqwest::ClientBuilder,
+        route_class: ClientRouteClass,
+        route: &OutboundProxyRoute,
+    ) -> Result<reqwest::Client, BuildRouteAwareHttpClientError> {
+        let builder = configure_builder_for_resolved_route(builder, route_class, route)?;
+        build_reqwest_client_with_custom_ca(builder).map_err(Into::into)
+    }
+}
+
+fn resolve_proxy_route(
+    env: &dyn EnvSource,
+    request_url: &str,
+    outbound_proxy_policy: OutboundProxyPolicy,
+    resolve_system_proxy: impl FnOnce(&str, &RequestOrigin) -> SystemProxyDecision,
+) -> OutboundProxyRoute {
+    if matches!(outbound_proxy_policy, OutboundProxyPolicy::ReqwestDefault) {
+        return OutboundProxyRoute::TransportDefault;
+    }
+
+    let env_proxy_kind = EnvProxyKind::from_request_url(request_url);
+    let request_url = proxy_resolution_url(request_url);
+    let Some(origin) = RequestOrigin::parse(&request_url) else {
+        return OutboundProxyRoute::Direct;
+    };
+
+    route_from_system_decision(
+        env,
+        env_proxy_kind,
+        resolve_system_proxy(&request_url, &origin),
+    )
+}
+
+fn route_from_system_decision(
+    env: &dyn EnvSource,
+    env_proxy_kind: EnvProxyKind,
+    decision: SystemProxyDecision,
+) -> OutboundProxyRoute {
+    match decision {
+        SystemProxyDecision::Direct => OutboundProxyRoute::Direct,
+        SystemProxyDecision::Proxy { url } => OutboundProxyRoute::Proxy {
+            url,
+            no_proxy: None,
+        },
+        SystemProxyDecision::Unavailable { .. } => resolve_env_proxy_route(env, env_proxy_kind),
+    }
+}
+
+fn resolve_env_proxy_route(
+    env: &dyn EnvSource,
+    env_proxy_kind: EnvProxyKind,
+) -> OutboundProxyRoute {
+    let proxy_url = match env_proxy_kind {
+        EnvProxyKind::Https => {
+            proxy_env_value(env, "HTTPS_PROXY").or_else(|| proxy_env_value(env, "ALL_PROXY"))
+        }
+        EnvProxyKind::SecureWebSocket => proxy_env_value(env, "HTTPS_PROXY")
+            .or_else(|| proxy_env_value(env, "HTTP_PROXY"))
+            .or_else(|| proxy_env_value(env, "ALL_PROXY")),
+        EnvProxyKind::Http => {
+            proxy_env_value(env, "HTTP_PROXY").or_else(|| proxy_env_value(env, "ALL_PROXY"))
+        }
+        EnvProxyKind::Other => proxy_env_value(env, "ALL_PROXY"),
+    };
+    match proxy_url {
+        Some(url) => OutboundProxyRoute::Proxy {
+            url,
+            no_proxy: proxy_env_value(env, "NO_PROXY"),
+        },
+        None => OutboundProxyRoute::Direct,
+    }
+}
+
+#[derive(Clone, Copy)]
+enum EnvProxyKind {
+    Http,
+    Https,
+    SecureWebSocket,
+    Other,
+}
+
+impl EnvProxyKind {
+    fn from_request_url(request_url: &str) -> Self {
+        let scheme = request_url
+            .parse::<http::Uri>()
+            .ok()
+            .and_then(|uri| uri.scheme_str().map(str::to_ascii_lowercase));
+        match scheme.as_deref() {
+            Some("http" | "ws") => Self::Http,
+            Some("https") => Self::Https,
+            Some("wss") => Self::SecureWebSocket,
+            Some(_) | None => Self::Other,
+        }
+    }
+}
+
+fn proxy_resolution_url(request_url: &str) -> Cow<'_, str> {
+    if let Some(suffix) = request_url.strip_prefix("wss://") {
+        Cow::Owned(format!("https://{suffix}"))
+    } else if let Some(suffix) = request_url.strip_prefix("ws://") {
+        Cow::Owned(format!("http://{suffix}"))
+    } else {
+        Cow::Borrowed(request_url)
+    }
+}
+
+/// Error while building a resolver-aware reqwest client.
+#[derive(Debug, Error)]
+pub enum BuildRouteAwareHttpClientError {
+    #[error(transparent)]
+    CustomCa(#[from] BuildCustomCaTransportError),
+
+    #[error("Failed to configure outbound proxy selected for {route_class}")]
+    InvalidProxyConfig { route_class: ClientRouteClass },
+}
+
+impl From<BuildRouteAwareHttpClientError> for io::Error {
+    fn from(error: BuildRouteAwareHttpClientError) -> Self {
+        match error {
+            BuildRouteAwareHttpClientError::CustomCa(error) => error.into(),
+            BuildRouteAwareHttpClientError::InvalidProxyConfig { .. } => io::Error::other(error),
+        }
+    }
+}
+
+/// Builds a reqwest client with conservative route selection and shared CA handling.
+///
+/// Unavailable platform resolution falls back to environment proxies and then direct. Errors after
+/// a route is selected are returned without trying another route. Ordered PAC candidates are
+/// currently collapsed to one route on both Windows and macOS; later proxy or `DIRECT` candidates
+/// are not retried after a connection failure.
+fn build_reqwest_client_for_route(
+    builder: reqwest::ClientBuilder,
+    request_url: &str,
+    route_class: ClientRouteClass,
+    outbound_proxy_policy: OutboundProxyPolicy,
+) -> Result<reqwest::Client, BuildRouteAwareHttpClientError> {
+    let builder = configure_proxy_for_route(
+        &ProcessEnv,
+        builder,
+        request_url,
+        route_class,
+        outbound_proxy_policy,
+        resolve_system_proxy,
+    )?;
+    build_reqwest_client_with_custom_ca(builder).map_err(Into::into)
+}
+
+fn configure_proxy_for_route(
+    env: &dyn EnvSource,
+    builder: reqwest::ClientBuilder,
+    request_url: &str,
+    route_class: ClientRouteClass,
+    outbound_proxy_policy: OutboundProxyPolicy,
+    resolve_system_proxy: impl FnOnce(&str, &RequestOrigin) -> SystemProxyDecision,
+) -> Result<reqwest::ClientBuilder, BuildRouteAwareHttpClientError> {
+    let route = resolve_proxy_route(
+        env,
+        request_url,
+        outbound_proxy_policy,
+        resolve_system_proxy,
+    );
+    configure_builder_for_resolved_route(builder, route_class, &route)
+}
+
+fn configure_builder_for_resolved_route(
+    builder: reqwest::ClientBuilder,
+    route_class: ClientRouteClass,
+    route: &OutboundProxyRoute,
+) -> Result<reqwest::ClientBuilder, BuildRouteAwareHttpClientError> {
+    match route {
+        OutboundProxyRoute::TransportDefault => Ok(builder),
+        OutboundProxyRoute::Direct => Ok(builder.no_proxy()),
+        OutboundProxyRoute::Proxy { url, no_proxy } => {
+            let no_proxy = no_proxy.as_deref().and_then(reqwest::NoProxy::from_string);
+            configure_concrete_proxy(builder, route_class, url, no_proxy)
+        }
+    }
+}
+
+fn configure_concrete_proxy(
+    builder: reqwest::ClientBuilder,
+    route_class: ClientRouteClass,
+    proxy_url: &str,
+    no_proxy: Option<reqwest::NoProxy>,
+) -> Result<reqwest::ClientBuilder, BuildRouteAwareHttpClientError> {
+    let proxy = match reqwest::Proxy::all(proxy_url) {
+        Ok(proxy) => proxy,
+        Err(_source) => {
+            return Err(BuildRouteAwareHttpClientError::InvalidProxyConfig { route_class });
+        }
+    };
+    Ok(builder.proxy(proxy.no_proxy(no_proxy)))
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[allow(dead_code)]
+struct RequestOrigin {
+    scheme: String,
+    host: String,
+    port: u16,
+}
+
+impl RequestOrigin {
+    fn parse(request_url: &str) -> Option<Self> {
+        let uri = request_url.parse::<http::Uri>().ok()?;
+        let scheme = uri.scheme_str()?.to_ascii_lowercase();
+        let host = uri.host()?.trim_matches(['[', ']']).to_ascii_lowercase();
+        let port = uri.port_u16().or(match scheme.as_str() {
+            "http" | "ws" => Some(80),
+            "https" | "wss" => Some(443),
+            _ => None,
+        })?;
+        Some(Self { scheme, host, port })
+    }
+}
+
+#[cfg_attr(
+    not(any(target_os = "windows", target_os = "macos")),
+    allow(
+        dead_code,
+        reason = "Direct and Proxy are constructed only by platform-specific resolvers"
+    )
+)]
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum SystemProxyDecision {
+    Direct,
+    Proxy { url: String },
+    Unavailable { failure: RouteFailureClass },
+}
+
+fn resolve_system_proxy(request_url: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    let cache = SYSTEM_PROXY_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+    resolve_system_proxy_with(cache, request_url, origin, resolve_platform_system_proxy)
+}
+
+fn resolve_system_proxy_with(
+    cache: &Mutex<HashMap<String, CachedSystemProxyDecision>>,
+    request_url: &str,
+    origin: &RequestOrigin,
+    resolve_platform_system_proxy: impl FnOnce(&str, &RequestOrigin) -> SystemProxyDecision,
+) -> SystemProxyDecision {
+    let mut cache = match cache.lock() {
+        Ok(cache) => cache,
+        Err(error) => panic!("system proxy cache lock should not be poisoned: {error}"),
+    };
+    let cache_key = system_proxy_cache_key(request_url);
+    if let Some(decision) =
+        cached_system_proxy_decision_from_cache(&mut cache, &cache_key, Instant::now())
+    {
+        return decision;
+    }
+
+    // Keep cache misses single-flight. Platform PAC/WPAD APIs are synchronous, so async callers
+    // run this work on the blocking pool; serializing misses prevents concurrent requests from
+    // consuming an unbounded number of blocking workers while system lookup is pending.
+    let decision = resolve_platform_system_proxy(request_url, origin);
+    insert_system_proxy_cache_entry(&mut cache, &cache_key, decision.clone(), Instant::now());
+    decision
+}
+
+#[cfg(target_os = "macos")]
+fn resolve_platform_system_proxy(request_url: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    macos::resolve(request_url, origin)
+}
+
+#[cfg(target_os = "windows")]
+fn resolve_platform_system_proxy(request_url: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    windows::resolve(request_url, origin)
+}
+
+#[cfg(not(any(target_os = "windows", target_os = "macos")))]
+fn resolve_platform_system_proxy(
+    _request_url: &str,
+    _origin: &RequestOrigin,
+) -> SystemProxyDecision {
+    SystemProxyDecision::Unavailable {
+        failure: RouteFailureClass::ProxyResolutionUnavailable,
+    }
+}
+
+#[derive(Debug, Clone)]
+struct CachedSystemProxyDecision {
+    decision: SystemProxyDecision,
+    expires_at: Instant,
+}
+
+static SYSTEM_PROXY_CACHE: OnceLock<Mutex<HashMap<String, CachedSystemProxyDecision>>> =
+    OnceLock::new();
+
+fn cached_system_proxy_decision(request_url: &str) -> Option<SystemProxyDecision> {
+    let cache = SYSTEM_PROXY_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+    let mut cache = cache.lock().ok()?;
+    let key = system_proxy_cache_key(request_url);
+    cached_system_proxy_decision_from_cache(&mut cache, &key, Instant::now())
+}
+
+fn cached_system_proxy_decision_from_cache(
+    cache: &mut HashMap<String, CachedSystemProxyDecision>,
+    cache_key: &str,
+    now: Instant,
+) -> Option<SystemProxyDecision> {
+    let cached = cache.get(cache_key)?;
+    if cached.expires_at > now {
+        return Some(cached.decision.clone());
+    }
+    cache.remove(cache_key);
+    None
+}
+
+fn cache_system_proxy_decision(request_url: &str, decision: SystemProxyDecision) {
+    let cache = SYSTEM_PROXY_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
+    if let Ok(mut cache) = cache.lock() {
+        let cache_key = system_proxy_cache_key(request_url);
+        insert_system_proxy_cache_entry(&mut cache, &cache_key, decision, Instant::now());
+    }
+}
+
+/// Primes one proxy decision for cross-crate integration tests.
+///
+/// This is public only so tests in HTTP-client consumers can exercise system-proxy routing
+/// deterministically on every supported platform.
+pub fn cache_system_proxy_route_for_test(request_url: &str, proxy_url: String) {
+    cache_system_proxy_decision(request_url, SystemProxyDecision::Proxy { url: proxy_url });
+}
+
+fn insert_system_proxy_cache_entry(
+    cache: &mut HashMap<String, CachedSystemProxyDecision>,
+    cache_key: &str,
+    decision: SystemProxyDecision,
+    now: Instant,
+) {
+    let ttl = match &decision {
+        SystemProxyDecision::Direct | SystemProxyDecision::Proxy { .. } => {
+            SYSTEM_PROXY_SUCCESS_CACHE_TTL
+        }
+        SystemProxyDecision::Unavailable { .. } => SYSTEM_PROXY_UNAVAILABLE_CACHE_TTL,
+    };
+
+    cache.retain(|_, cached| cached.expires_at > now);
+    if cache.len() >= SYSTEM_PROXY_CACHE_MAX_ENTRIES
+        && !cache.contains_key(cache_key)
+        && let Some(cache_key_to_evict) = cache
+            .iter()
+            .min_by_key(|(_, cached)| cached.expires_at)
+            .map(|(cache_key, _)| cache_key.clone())
+    {
+        cache.remove(&cache_key_to_evict);
+    }
+    cache.insert(
+        cache_key.to_string(),
+        CachedSystemProxyDecision {
+            decision,
+            expires_at: now + ttl,
+        },
+    );
+}
+
+fn system_proxy_cache_key(request_url: &str) -> String {
+    // Keep URL-specific PAC decisions without retaining the raw routed URL.
+    let mut hasher = Sha256::new();
+    hasher.update(b"system-proxy-cache-v1\0");
+    hasher.update(request_url.as_bytes());
+    format!("{:x}", hasher.finalize())
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn no_proxy_matches_origin(no_proxy: &str, origin: &RequestOrigin) -> bool {
+    no_proxy
+        .split(',')
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .any(|entry| no_proxy_entry_matches_origin(entry, origin))
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn no_proxy_entry_matches_origin(entry: &str, origin: &RequestOrigin) -> bool {
+    if entry == "*" {
+        return true;
+    }
+
+    let mut entry = entry
+        .strip_prefix("http://")
+        .or_else(|| entry.strip_prefix("https://"))
+        .unwrap_or(entry)
+        .trim_matches(['[', ']'])
+        .to_ascii_lowercase();
+    let mut port = None;
+    let parsed_host_port = entry.rsplit_once(':').and_then(|(host, candidate_port)| {
+        if host.contains(':') {
+            return None;
+        }
+        candidate_port
+            .parse::<u16>()
+            .ok()
+            .map(|parsed_port| (host.to_string(), parsed_port))
+    });
+    if let Some((host, parsed_port)) = parsed_host_port {
+        entry = host;
+        port = Some(parsed_port);
+    }
+    if port.is_some_and(|port| port != origin.port) {
+        return false;
+    }
+
+    if let Some(suffix) = entry.strip_prefix('.') {
+        return origin.host == suffix || origin.host.ends_with(&format!(".{suffix}"));
+    }
+
+    if entry.contains('*') {
+        return wildcard_host_match(&entry, &origin.host);
+    }
+
+    origin.host == entry
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn wildcard_host_match(pattern: &str, host: &str) -> bool {
+    let mut remaining = host;
+    let mut first = true;
+    for part in pattern.split('*') {
+        if part.is_empty() {
+            continue;
+        }
+        if first && !pattern.starts_with('*') {
+            let Some(stripped) = remaining.strip_prefix(part) else {
+                return false;
+            };
+            remaining = stripped;
+        } else {
+            let Some(index) = remaining.find(part) else {
+                return false;
+            };
+            remaining = &remaining[index + part.len()..];
+        }
+        first = false;
+    }
+    pattern.ends_with('*') || remaining.is_empty()
+}
+
+#[cfg(any(test, target_os = "windows"))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum ParsedProxyListDecision {
+    Direct,
+    Proxy(String),
+    UnsupportedScheme,
+    Unavailable,
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn parse_proxy_list(input: &str, target_scheme: &str) -> ParsedProxyListDecision {
+    let mut saw_unsupported = false;
+
+    {
+        let mut process_token = |token: &str| {
+            let decision = parse_proxy_token(token, target_scheme);
+            match decision {
+                ParsedProxyListDecision::Direct => Some(ParsedProxyListDecision::Direct),
+                ParsedProxyListDecision::Proxy(url) => Some(ParsedProxyListDecision::Proxy(url)),
+                ParsedProxyListDecision::UnsupportedScheme => {
+                    saw_unsupported = true;
+                    None
+                }
+                ParsedProxyListDecision::Unavailable => None,
+            }
+        };
+
+        for segment in input
+            .split(';')
+            .map(str::trim)
+            .filter(|segment| !segment.is_empty())
+        {
+            let mut parts = segment.split_whitespace();
+            let directive = parts.next();
+            let hostport = parts.next();
+            let extra = parts.next();
+            let is_proxy_directive = matches!(
+                directive.map(str::to_ascii_lowercase).as_deref(),
+                Some("proxy" | "http" | "https" | "socks" | "socks4" | "socks5")
+            ) && hostport.is_some()
+                && extra.is_none();
+
+            if is_proxy_directive {
+                if let Some(decision) = process_token(segment) {
+                    return decision;
+                }
+            } else {
+                for token in segment.split_whitespace() {
+                    if let Some(decision) = process_token(token) {
+                        return decision;
+                    }
+                }
+            }
+        }
+    }
+
+    if saw_unsupported {
+        ParsedProxyListDecision::UnsupportedScheme
+    } else {
+        ParsedProxyListDecision::Unavailable
+    }
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn parse_proxy_token(token: &str, target_scheme: &str) -> ParsedProxyListDecision {
+    if token.eq_ignore_ascii_case("DIRECT") {
+        return ParsedProxyListDecision::Direct;
+    }
+
+    if let Some(decision) = parse_proxy_key_token(token, target_scheme) {
+        return decision;
+    }
+    if token.contains('=') {
+        return ParsedProxyListDecision::Unavailable;
+    }
+
+    let mut parts = token.split_whitespace();
+    let directive = parts.next();
+    let hostport = parts.next();
+    if let (Some(directive), Some(hostport), None) = (directive, hostport, parts.next()) {
+        return match directive.to_ascii_lowercase().as_str() {
+            "proxy" | "http" => proxy_url_from_hostport("http", hostport),
+            "https" => proxy_url_from_hostport("https", hostport),
+            "socks" | "socks4" | "socks5" => ParsedProxyListDecision::UnsupportedScheme,
+            _ => ParsedProxyListDecision::Unavailable,
+        };
+    }
+
+    proxy_url_from_hostport("http", token)
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn parse_proxy_key_token(token: &str, target_scheme: &str) -> Option<ParsedProxyListDecision> {
+    let (key, value) = token.split_once('=')?;
+    if key.trim().eq_ignore_ascii_case(target_scheme) {
+        Some(proxy_url_from_hostport("http", value.trim()))
+    } else {
+        Some(ParsedProxyListDecision::Unavailable)
+    }
+}
+
+#[cfg(any(test, target_os = "windows"))]
+fn proxy_url_from_hostport(proxy_scheme: &str, hostport: &str) -> ParsedProxyListDecision {
+    if hostport.is_empty() {
+        return ParsedProxyListDecision::Unavailable;
+    }
+    if hostport.contains("://") {
+        return ParsedProxyListDecision::Proxy(hostport.to_string());
+    }
+    ParsedProxyListDecision::Proxy(format!("{proxy_scheme}://{hostport}"))
+}
+
+trait EnvSource {
+    fn var(&self, key: &str) -> Option<String>;
+}
+
+struct ProcessEnv;
+
+impl EnvSource for ProcessEnv {
+    fn var(&self, key: &str) -> Option<String> {
+        std::env::var(key).ok()
+    }
+}
+
+fn proxy_env_value(env: &dyn EnvSource, upper: &str) -> Option<String> {
+    let lower = upper.to_ascii_lowercase();
+    env.var(upper)
+        .or_else(|| env.var(&lower))
+        .filter(|value| !value.is_empty())
+}
+
+#[cfg(test)]
+#[path = "route_aware_redirect_integration_tests.rs"]
+mod redirect_integration_tests;
+
+#[cfg(test)]
+#[path = "outbound_proxy_tests.rs"]
+mod tests;
diff --git a/codex-rs/http-client/src/outbound_proxy/macos.rs b/codex-rs/http-client/src/outbound_proxy/macos.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4f516517092ebcc0e9c5a6a58bda5639f8d48180
--- /dev/null
+++ b/codex-rs/http-client/src/outbound_proxy/macos.rs
@@ -0,0 +1,418 @@
+//! macOS system proxy resolution through SystemConfiguration and CFNetwork.
+
+use std::ffi::c_void;
+use std::ptr;
+use std::time::Duration;
+use std::time::Instant;
+
+use super::MacosSystemProxyConfiguration;
+use super::RequestOrigin;
+use super::RouteFailureClass;
+use super::SystemProxyDecision;
+use system_configuration::core_foundation::array::CFArray;
+use system_configuration::core_foundation::array::CFArrayRef;
+use system_configuration::core_foundation::base::CFEqual;
+use system_configuration::core_foundation::base::CFGetTypeID;
+use system_configuration::core_foundation::base::CFIndex;
+use system_configuration::core_foundation::base::CFType;
+use system_configuration::core_foundation::base::CFTypeRef;
+use system_configuration::core_foundation::base::TCFType;
+use system_configuration::core_foundation::base::kCFAllocatorDefault;
+use system_configuration::core_foundation::dictionary::CFDictionary;
+use system_configuration::core_foundation::dictionary::CFDictionaryRef;
+use system_configuration::core_foundation::error::CFErrorRef;
+use system_configuration::core_foundation::number::CFNumber;
+use system_configuration::core_foundation::runloop::CFRunLoop;
+use system_configuration::core_foundation::runloop::CFRunLoopSource;
+use system_configuration::core_foundation::runloop::CFRunLoopSourceInvalidate;
+use system_configuration::core_foundation::runloop::CFRunLoopSourceRef;
+use system_configuration::core_foundation::runloop::kCFRunLoopDefaultMode;
+use system_configuration::core_foundation::string::CFString;
+use system_configuration::core_foundation::string::CFStringRef;
+use system_configuration::core_foundation::url::CFURL;
+use system_configuration::core_foundation::url::CFURLCreateWithString;
+use system_configuration::core_foundation::url::CFURLGetTypeID;
+use system_configuration::core_foundation::url::CFURLRef;
+use system_configuration::dynamic_store::SCDynamicStoreBuilder;
+
+const PAC_EXECUTION_TIMEOUT: Duration = Duration::from_secs(5);
+
+type ProxyDictionary = CFDictionary<CFString, CFType>;
+type ProxyArray = CFArray<ProxyDictionary>;
+
+#[repr(C)]
+struct CFStreamClientContext {
+    version: CFIndex,
+    info: *mut c_void,
+    retain: Option<unsafe extern "C" fn(*mut c_void) -> *mut c_void>,
+    release: Option<unsafe extern "C" fn(*mut c_void)>,
+    copy_description: Option<unsafe extern "C" fn(*mut c_void) -> CFStringRef>,
+}
+
+type CFProxyAutoConfigurationResultCallback =
+    unsafe extern "C" fn(*mut c_void, CFArrayRef, CFErrorRef);
+
+#[link(name = "CFNetwork", kind = "framework")]
+unsafe extern "C" {
+    static kCFProxyTypeKey: CFStringRef;
+    static kCFProxyHostNameKey: CFStringRef;
+    static kCFProxyPortNumberKey: CFStringRef;
+    static kCFProxyAutoConfigurationURLKey: CFStringRef;
+    static kCFProxyAutoConfigurationJavaScriptKey: CFStringRef;
+    static kCFProxyTypeNone: CFStringRef;
+    static kCFProxyTypeHTTP: CFStringRef;
+    static kCFProxyTypeHTTPS: CFStringRef;
+    static kCFProxyTypeSOCKS: CFStringRef;
+    static kCFProxyTypeAutoConfigurationURL: CFStringRef;
+    static kCFProxyTypeAutoConfigurationJavaScript: CFStringRef;
+
+    fn CFNetworkCopyProxiesForURL(url: CFURLRef, proxy_settings: CFDictionaryRef) -> CFArrayRef;
+    fn CFNetworkExecuteProxyAutoConfigurationURL(
+        proxy_auto_config_url: CFURLRef,
+        target_url: CFURLRef,
+        callback: CFProxyAutoConfigurationResultCallback,
+        client_context: *mut CFStreamClientContext,
+    ) -> CFRunLoopSourceRef;
+    fn CFNetworkExecuteProxyAutoConfigurationScript(
+        proxy_auto_config_script: CFStringRef,
+        target_url: CFURLRef,
+        callback: CFProxyAutoConfigurationResultCallback,
+        client_context: *mut CFStreamClientContext,
+    ) -> CFRunLoopSourceRef;
+}
+
+pub(super) fn resolve(request_url: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    let Some(target_url) = cf_url(request_url) else {
+        return SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::InvalidProxyConfig,
+        };
+    };
+
+    let Some(settings) = system_proxy_settings() else {
+        return SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        };
+    };
+
+    let Some(proxies) = copy_proxies_for_url(&target_url, &settings) else {
+        return SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        };
+    };
+
+    proxy_array_decision(&proxies, &target_url, origin)
+}
+
+pub(super) fn configuration(request_url: &str) -> MacosSystemProxyConfiguration {
+    let Some(target_url) = cf_url(request_url) else {
+        return MacosSystemProxyConfiguration::Unavailable;
+    };
+    let Some(settings) = system_proxy_settings() else {
+        return MacosSystemProxyConfiguration::Unavailable;
+    };
+    let Some(proxies) = copy_proxies_for_url(&target_url, &settings) else {
+        return MacosSystemProxyConfiguration::Unavailable;
+    };
+
+    (&proxies)
+        .into_iter()
+        .find_map(|proxy| {
+            let proxy_type = cf_string_value(&proxy, unsafe { kCFProxyTypeKey })?;
+            if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeAutoConfigurationURL })
+                || cf_string_equals(&proxy_type, unsafe {
+                    kCFProxyTypeAutoConfigurationJavaScript
+                })
+            {
+                Some(MacosSystemProxyConfiguration::Automatic)
+            } else if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeHTTP })
+                || cf_string_equals(&proxy_type, unsafe { kCFProxyTypeHTTPS })
+            {
+                Some(MacosSystemProxyConfiguration::Manual)
+            } else {
+                cf_string_equals(&proxy_type, unsafe { kCFProxyTypeNone })
+                    .then_some(MacosSystemProxyConfiguration::Direct)
+            }
+        })
+        .unwrap_or(MacosSystemProxyConfiguration::Unavailable)
+}
+
+fn system_proxy_settings() -> Option<CFDictionary<CFString, CFType>> {
+    let store = SCDynamicStoreBuilder::new("Codex").build()?;
+    store.get_proxies()
+}
+
+fn copy_proxies_for_url(
+    target_url: &CFURL,
+    settings: &CFDictionary<CFString, CFType>,
+) -> Option<ProxyArray> {
+    let proxies = unsafe {
+        CFNetworkCopyProxiesForURL(
+            target_url.as_concrete_TypeRef(),
+            settings.as_concrete_TypeRef(),
+        )
+    };
+    if proxies.is_null() {
+        None
+    } else {
+        Some(unsafe { ProxyArray::wrap_under_create_rule(proxies) })
+    }
+}
+
+fn proxy_array_decision(
+    proxies: &ProxyArray,
+    target_url: &CFURL,
+    origin: &RequestOrigin,
+) -> SystemProxyDecision {
+    let mut saw_unsupported = false;
+    let mut saw_unavailable = false;
+
+    // CFNetwork returns candidates in failover order, but the shared resolver currently carries
+    // only one route. This matches the Windows limitation; cross-platform retry requires request
+    // replay semantics and is intentionally deferred.
+    for proxy in proxies {
+        match proxy_entry_decision(&proxy, target_url, origin) {
+            ProxyEntryDecision::Direct => return SystemProxyDecision::Direct,
+            ProxyEntryDecision::Proxy { url } => return SystemProxyDecision::Proxy { url },
+            ProxyEntryDecision::UnsupportedScheme => saw_unsupported = true,
+            ProxyEntryDecision::Unavailable => saw_unavailable = true,
+        }
+    }
+
+    if saw_unsupported {
+        SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::UnsupportedProxyScheme,
+        }
+    } else if saw_unavailable {
+        SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        }
+    } else {
+        SystemProxyDecision::Direct
+    }
+}
+
+fn proxy_entry_decision(
+    proxy: &ProxyDictionary,
+    target_url: &CFURL,
+    origin: &RequestOrigin,
+) -> ProxyEntryDecision {
+    let Some(proxy_type) = cf_string_value(proxy, unsafe { kCFProxyTypeKey }) else {
+        return ProxyEntryDecision::Unavailable;
+    };
+
+    if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeNone }) {
+        return ProxyEntryDecision::Direct;
+    }
+
+    if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeHTTP }) {
+        return concrete_proxy_entry(proxy, "http");
+    }
+
+    if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeHTTPS }) {
+        // CFNetwork's HTTPS proxy type is a tunneling proxy for HTTPS destinations; it does not
+        // preserve an explicit TLS-to-proxy transport. See https://developer.apple.com/documentation/cfnetwork/kcfproxytypehttps.
+        return concrete_proxy_entry(proxy, "http");
+    }
+
+    if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeSOCKS }) {
+        return ProxyEntryDecision::UnsupportedScheme;
+    }
+
+    if cf_string_equals(&proxy_type, unsafe { kCFProxyTypeAutoConfigurationURL }) {
+        let Some(pac_url) = cf_url_value(proxy, unsafe { kCFProxyAutoConfigurationURLKey }) else {
+            return ProxyEntryDecision::Unavailable;
+        };
+        return pac_decision(execute_pac_url(&pac_url, target_url), target_url, origin);
+    }
+
+    if cf_string_equals(&proxy_type, unsafe {
+        kCFProxyTypeAutoConfigurationJavaScript
+    }) {
+        let Some(script) =
+            cf_string_value(proxy, unsafe { kCFProxyAutoConfigurationJavaScriptKey })
+        else {
+            return ProxyEntryDecision::Unavailable;
+        };
+        return pac_decision(
+            execute_pac(|callback, context| unsafe {
+                CFNetworkExecuteProxyAutoConfigurationScript(
+                    script.as_concrete_TypeRef(),
+                    target_url.as_concrete_TypeRef(),
+                    callback,
+                    context,
+                )
+            }),
+            target_url,
+            origin,
+        );
+    }
+
+    ProxyEntryDecision::Unavailable
+}
+
+fn pac_decision(
+    result: Result<ProxyArray, RouteFailureClass>,
+    target_url: &CFURL,
+    origin: &RequestOrigin,
+) -> ProxyEntryDecision {
+    let proxies = match result {
+        Ok(proxies) => proxies,
+        Err(RouteFailureClass::UnsupportedProxyScheme) => {
+            return ProxyEntryDecision::UnsupportedScheme;
+        }
+        Err(_) => return ProxyEntryDecision::Unavailable,
+    };
+
+    match proxy_array_decision(&proxies, target_url, origin) {
+        SystemProxyDecision::Direct => ProxyEntryDecision::Direct,
+        SystemProxyDecision::Proxy { url } => ProxyEntryDecision::Proxy { url },
+        SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::UnsupportedProxyScheme,
+        } => ProxyEntryDecision::UnsupportedScheme,
+        SystemProxyDecision::Unavailable { failure: _ } => ProxyEntryDecision::Unavailable,
+    }
+}
+
+fn execute_pac_url(pac_url: &CFURL, target_url: &CFURL) -> Result<ProxyArray, RouteFailureClass> {
+    execute_pac(|callback, context| unsafe {
+        CFNetworkExecuteProxyAutoConfigurationURL(
+            pac_url.as_concrete_TypeRef(),
+            target_url.as_concrete_TypeRef(),
+            callback,
+            context,
+        )
+    })
+}
+
+fn execute_pac(
+    create_source: impl FnOnce(
+        CFProxyAutoConfigurationResultCallback,
+        *mut CFStreamClientContext,
+    ) -> CFRunLoopSourceRef,
+) -> Result<ProxyArray, RouteFailureClass> {
+    let mut state = PacRunLoopState { result: None };
+    let mut context = CFStreamClientContext {
+        version: 0,
+        info: (&mut state as *mut PacRunLoopState).cast::<c_void>(),
+        retain: None,
+        release: None,
+        copy_description: None,
+    };
+
+    let source = create_source(pac_result_callback, &mut context);
+    if source.is_null() {
+        return Err(RouteFailureClass::ProxyResolutionUnavailable);
+    }
+
+    let source = unsafe { CFRunLoopSource::wrap_under_create_rule(source) };
+    let run_loop = CFRunLoop::get_current();
+    let mode = unsafe { kCFRunLoopDefaultMode };
+    run_loop.add_source(&source, mode);
+
+    let started_at = Instant::now();
+    while state.result.is_none() && started_at.elapsed() < PAC_EXECUTION_TIMEOUT {
+        CFRunLoop::run_in_mode(mode, Duration::from_millis(50), true);
+    }
+
+    if state.result.is_none() {
+        unsafe { CFRunLoopSourceInvalidate(source.as_concrete_TypeRef()) };
+    }
+    run_loop.remove_source(&source, mode);
+    state
+        .result
+        .unwrap_or(Err(RouteFailureClass::ConnectTimeout))
+}
+
+unsafe extern "C" fn pac_result_callback(
+    client: *mut c_void,
+    proxies: CFArrayRef,
+    error: CFErrorRef,
+) {
+    let state = unsafe { &mut *client.cast::<PacRunLoopState>() };
+    state.result = if !error.is_null() || proxies.is_null() {
+        Some(Err(RouteFailureClass::ProxyResolutionUnavailable))
+    } else {
+        Some(Ok(unsafe { ProxyArray::wrap_under_get_rule(proxies) }))
+    };
+    CFRunLoop::get_current().stop();
+}
+
+struct PacRunLoopState {
+    result: Option<Result<ProxyArray, RouteFailureClass>>,
+}
+
+fn concrete_proxy_entry(proxy: &ProxyDictionary, proxy_scheme: &str) -> ProxyEntryDecision {
+    let Some(host) = cf_string_value(proxy, unsafe { kCFProxyHostNameKey })
+        .map(|host| host.to_string())
+        .filter(|host| !host.is_empty())
+    else {
+        return ProxyEntryDecision::Unavailable;
+    };
+
+    let host = bracket_ipv6_host(&host);
+    let url = match cf_i32_value(proxy, unsafe { kCFProxyPortNumberKey }) {
+        Some(port) if port > 0 => format!("{proxy_scheme}://{host}:{port}"),
+        _ => format!("{proxy_scheme}://{host}"),
+    };
+    ProxyEntryDecision::Proxy { url }
+}
+
+fn bracket_ipv6_host(host: &str) -> String {
+    if host.contains(':') && !host.starts_with('[') {
+        format!("[{host}]")
+    } else {
+        host.to_string()
+    }
+}
+
+fn cf_string_value(proxy: &ProxyDictionary, key: CFStringRef) -> Option<CFString> {
+    proxy
+        .find(key)
+        .and_then(|value| value.downcast::<CFString>())
+}
+
+fn cf_i32_value(proxy: &ProxyDictionary, key: CFStringRef) -> Option<i32> {
+    proxy
+        .find(key)
+        .and_then(|value| value.downcast::<CFNumber>())
+        .and_then(|value| value.to_i32())
+}
+
+fn cf_url_value(proxy: &ProxyDictionary, key: CFStringRef) -> Option<CFURL> {
+    proxy.find(key).and_then(|value| {
+        if unsafe { CFGetTypeID(value.as_CFTypeRef()) == CFURLGetTypeID() } {
+            Some(unsafe { CFURL::wrap_under_get_rule(value.as_CFTypeRef() as CFURLRef) })
+        } else {
+            value
+                .downcast::<CFString>()
+                .and_then(|value| cf_url(value.to_string().as_str()))
+        }
+    })
+}
+
+fn cf_string_equals(value: &CFString, expected: CFStringRef) -> bool {
+    unsafe { CFEqual(value.as_CFTypeRef(), expected as CFTypeRef) != 0 }
+}
+
+fn cf_url(value: &str) -> Option<CFURL> {
+    let value = CFString::new(value);
+    let url = unsafe {
+        CFURLCreateWithString(
+            kCFAllocatorDefault,
+            value.as_concrete_TypeRef(),
+            ptr::null(),
+        )
+    };
+    if url.is_null() {
+        None
+    } else {
+        Some(unsafe { CFURL::wrap_under_create_rule(url) })
+    }
+}
+
+enum ProxyEntryDecision {
+    Direct,
+    Proxy { url: String },
+    UnsupportedScheme,
+    Unavailable,
+}
diff --git a/codex-rs/http-client/src/outbound_proxy/windows.rs b/codex-rs/http-client/src/outbound_proxy/windows.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4ff927723affa2bc99a91372794e14e49c914089
--- /dev/null
+++ b/codex-rs/http-client/src/outbound_proxy/windows.rs
@@ -0,0 +1,364 @@
+//! Windows system proxy resolution through WinHTTP.
+
+use std::ffi::c_void;
+use std::ptr;
+
+use super::ParsedProxyListDecision;
+use super::RequestOrigin;
+use super::RouteFailureClass;
+use super::SystemProxyDecision;
+use super::no_proxy_matches_origin;
+use super::parse_proxy_list;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::FALSE;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::GlobalFree;
+use windows_sys::Win32::Foundation::TRUE;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_AUTODETECTION_FAILED;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_CANNOT_CONNECT;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_CONNECTION_ERROR;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_INVALID_URL;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_LOGIN_FAILURE;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_NAME_NOT_RESOLVED;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SCRIPT_EXECUTION_ERROR;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_CERT_CN_INVALID;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_CERT_DATE_INVALID;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_CERT_REV_FAILED;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_CERT_REVOKED;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_CERT_WRONG_USAGE;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_CHANNEL_ERROR;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_FAILURE;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_INVALID_CA;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_SECURE_INVALID_CERT;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_TIMEOUT;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_UNHANDLED_SCRIPT_TYPE;
+use windows_sys::Win32::Networking::WinHttp::ERROR_WINHTTP_UNRECOGNIZED_SCHEME;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_ACCESS_TYPE_NAMED_PROXY;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_ACCESS_TYPE_NO_PROXY;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_AUTO_DETECT_TYPE_DHCP;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_AUTO_DETECT_TYPE_DNS_A;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_AUTOPROXY_AUTO_DETECT;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_AUTOPROXY_CONFIG_URL;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_AUTOPROXY_OPTIONS;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_CURRENT_USER_IE_PROXY_CONFIG;
+use windows_sys::Win32::Networking::WinHttp::WINHTTP_PROXY_INFO;
+use windows_sys::Win32::Networking::WinHttp::WinHttpCloseHandle;
+use windows_sys::Win32::Networking::WinHttp::WinHttpGetIEProxyConfigForCurrentUser;
+use windows_sys::Win32::Networking::WinHttp::WinHttpGetProxyForUrl;
+use windows_sys::Win32::Networking::WinHttp::WinHttpOpen;
+use windows_sys::core::PWSTR;
+
+pub(super) fn resolve(request_url: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    let ie_config = match current_user_ie_proxy_config() {
+        Ok(config) => config,
+        Err(failure) => {
+            return SystemProxyDecision::Unavailable { failure };
+        }
+    };
+
+    if let Some(pac_url) = ie_config.auto_config_url.as_deref() {
+        let decision = resolve_with_pac_url(request_url, origin, pac_url);
+        if !matches!(decision, SystemProxyDecision::Unavailable { .. }) {
+            return decision;
+        }
+    }
+
+    if ie_config.auto_detect {
+        let decision = resolve_with_auto_detect(request_url, origin);
+        if !matches!(decision, SystemProxyDecision::Unavailable { .. }) {
+            return decision;
+        }
+    }
+
+    if let Some(proxy) = ie_config.static_proxy.as_deref() {
+        if ie_config
+            .proxy_bypass
+            .as_deref()
+            .is_some_and(|bypass| proxy_bypass_matches_origin(bypass, origin))
+        {
+            return SystemProxyDecision::Direct;
+        }
+        return proxy_list_decision(proxy, origin);
+    }
+
+    if ie_config.auto_config_url.is_some() || ie_config.auto_detect {
+        SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        }
+    } else {
+        SystemProxyDecision::Direct
+    }
+}
+
+fn resolve_with_pac_url(
+    request_url: &str,
+    origin: &RequestOrigin,
+    pac_url: &str,
+) -> SystemProxyDecision {
+    let pac_url = wide_null(pac_url);
+    let options = WINHTTP_AUTOPROXY_OPTIONS {
+        dwFlags: WINHTTP_AUTOPROXY_CONFIG_URL,
+        dwAutoDetectFlags: 0,
+        lpszAutoConfigUrl: pac_url.as_ptr(),
+        lpvReserved: ptr::null_mut(),
+        dwReserved: 0,
+        fAutoLogonIfChallenged: TRUE,
+    };
+    resolve_with_winhttp_options(request_url, origin, options)
+}
+
+fn resolve_with_auto_detect(request_url: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    let options = WINHTTP_AUTOPROXY_OPTIONS {
+        dwFlags: WINHTTP_AUTOPROXY_AUTO_DETECT,
+        dwAutoDetectFlags: WINHTTP_AUTO_DETECT_TYPE_DHCP | WINHTTP_AUTO_DETECT_TYPE_DNS_A,
+        lpszAutoConfigUrl: ptr::null(),
+        lpvReserved: ptr::null_mut(),
+        dwReserved: 0,
+        fAutoLogonIfChallenged: FALSE,
+    };
+    resolve_with_winhttp_options(request_url, origin, options)
+}
+
+fn resolve_with_winhttp_options(
+    request_url: &str,
+    origin: &RequestOrigin,
+    mut options: WINHTTP_AUTOPROXY_OPTIONS,
+) -> SystemProxyDecision {
+    let Some(session) = WinHttpSession::open() else {
+        return SystemProxyDecision::Unavailable {
+            failure: classify_winhttp_error(last_error()),
+        };
+    };
+
+    let request_url = wide_null(request_url);
+    let mut proxy_info = WINHTTP_PROXY_INFO {
+        dwAccessType: WINHTTP_ACCESS_TYPE_NO_PROXY,
+        lpszProxy: ptr::null_mut(),
+        lpszProxyBypass: ptr::null_mut(),
+    };
+    let ok = unsafe {
+        WinHttpGetProxyForUrl(
+            session.0,
+            request_url.as_ptr(),
+            &mut options,
+            &mut proxy_info,
+        )
+    };
+    if ok == FALSE {
+        return SystemProxyDecision::Unavailable {
+            failure: classify_winhttp_error(last_error()),
+        };
+    }
+
+    let proxy_info = ProxyInfo::from_raw(proxy_info);
+    if proxy_info.access_type == WINHTTP_ACCESS_TYPE_NO_PROXY {
+        return SystemProxyDecision::Direct;
+    }
+    if proxy_info.access_type != WINHTTP_ACCESS_TYPE_NAMED_PROXY {
+        return SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        };
+    }
+    let Some(proxy) = proxy_info.proxy.as_deref() else {
+        return SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        };
+    };
+    proxy_list_decision(proxy, origin)
+}
+
+fn proxy_list_decision(proxy_list: &str, origin: &RequestOrigin) -> SystemProxyDecision {
+    match parse_proxy_list(proxy_list, &origin.scheme) {
+        ParsedProxyListDecision::Direct => SystemProxyDecision::Direct,
+        ParsedProxyListDecision::Proxy(url) => SystemProxyDecision::Proxy { url },
+        ParsedProxyListDecision::UnsupportedScheme => SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::UnsupportedProxyScheme,
+        },
+        ParsedProxyListDecision::Unavailable => SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        },
+    }
+}
+
+fn current_user_ie_proxy_config() -> Result<IeProxyConfig, RouteFailureClass> {
+    let mut raw = WINHTTP_CURRENT_USER_IE_PROXY_CONFIG {
+        fAutoDetect: FALSE,
+        lpszAutoConfigUrl: ptr::null_mut(),
+        lpszProxy: ptr::null_mut(),
+        lpszProxyBypass: ptr::null_mut(),
+    };
+    let ok = unsafe { WinHttpGetIEProxyConfigForCurrentUser(&mut raw) };
+    if ok == FALSE {
+        let error = last_error();
+        if error == ERROR_FILE_NOT_FOUND {
+            // Match WinHTTP's fallback by attempting WPAD when no IE proxy settings exist.
+            return Ok(IeProxyConfig {
+                auto_detect: true,
+                ..Default::default()
+            });
+        }
+        return Err(classify_winhttp_error(error));
+    }
+
+    let auto_config_url = GlobalWideString::from_raw(raw.lpszAutoConfigUrl).into_string();
+    let static_proxy = GlobalWideString::from_raw(raw.lpszProxy).into_string();
+    let proxy_bypass = GlobalWideString::from_raw(raw.lpszProxyBypass).into_string();
+
+    Ok(IeProxyConfig {
+        auto_detect: raw.fAutoDetect != FALSE,
+        auto_config_url,
+        static_proxy,
+        proxy_bypass,
+    })
+}
+
+#[derive(Debug, Default)]
+struct IeProxyConfig {
+    auto_detect: bool,
+    auto_config_url: Option<String>,
+    static_proxy: Option<String>,
+    proxy_bypass: Option<String>,
+}
+
+struct ProxyInfo {
+    access_type: u32,
+    proxy: Option<String>,
+    _proxy_bypass: Option<String>,
+}
+
+impl ProxyInfo {
+    fn from_raw(raw: WINHTTP_PROXY_INFO) -> Self {
+        Self {
+            access_type: raw.dwAccessType,
+            proxy: GlobalWideString::from_raw(raw.lpszProxy).into_string(),
+            _proxy_bypass: GlobalWideString::from_raw(raw.lpszProxyBypass).into_string(),
+        }
+    }
+}
+
+struct GlobalWideString(PWSTR);
+
+impl GlobalWideString {
+    fn from_raw(ptr: PWSTR) -> Self {
+        Self(ptr)
+    }
+
+    fn into_string(self) -> Option<String> {
+        if self.0.is_null() {
+            return None;
+        }
+        let string = unsafe { wide_ptr_to_string(self.0) };
+        if string.is_empty() {
+            None
+        } else {
+            Some(string)
+        }
+    }
+}
+
+impl Drop for GlobalWideString {
+    fn drop(&mut self) {
+        if !self.0.is_null() {
+            unsafe {
+                GlobalFree(self.0.cast::<c_void>());
+            }
+        }
+    }
+}
+
+struct WinHttpSession(*mut c_void);
+
+impl WinHttpSession {
+    fn open() -> Option<Self> {
+        let agent = wide_null("Codex");
+        let handle = unsafe {
+            WinHttpOpen(
+                agent.as_ptr(),
+                WINHTTP_ACCESS_TYPE_NO_PROXY,
+                ptr::null(),
+                ptr::null(),
+                0,
+            )
+        };
+        if handle.is_null() {
+            None
+        } else {
+            Some(Self(handle))
+        }
+    }
+}
+
+impl Drop for WinHttpSession {
+    fn drop(&mut self) {
+        if !self.0.is_null() {
+            unsafe {
+                WinHttpCloseHandle(self.0);
+            }
+        }
+    }
+}
+
+fn proxy_bypass_matches_origin(proxy_bypass: &str, origin: &RequestOrigin) -> bool {
+    proxy_bypass
+        .split(|ch: char| ch == ';' || ch == ',' || ch.is_whitespace())
+        .map(str::trim)
+        .filter(|entry| !entry.is_empty())
+        .any(|entry| {
+            if entry.eq_ignore_ascii_case("<local>") {
+                !origin.host.contains('.')
+            } else {
+                no_proxy_matches_origin(entry, origin)
+            }
+        })
+}
+
+#[cfg(test)]
+#[path = "windows_tests.rs"]
+mod tests;
+
+fn wide_null(value: &str) -> Vec<u16> {
+    value.encode_utf16().chain(std::iter::once(0)).collect()
+}
+
+unsafe fn wide_ptr_to_string(ptr: PWSTR) -> String {
+    let mut len = 0;
+    while unsafe { *ptr.add(len) } != 0 {
+        len += 1;
+    }
+    let slice = unsafe { std::slice::from_raw_parts(ptr, len) };
+    String::from_utf16_lossy(slice)
+}
+
+fn last_error() -> u32 {
+    unsafe { GetLastError() }
+}
+
+fn classify_winhttp_error(code: u32) -> RouteFailureClass {
+    match code {
+        ERROR_WINHTTP_TIMEOUT => RouteFailureClass::ConnectTimeout,
+        ERROR_WINHTTP_LOGIN_FAILURE => RouteFailureClass::ProxyAuthenticationRequired,
+        ERROR_WINHTTP_AUTODETECTION_FAILED
+        | ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT
+        | ERROR_WINHTTP_SCRIPT_EXECUTION_ERROR
+        | ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT
+        | ERROR_WINHTTP_UNHANDLED_SCRIPT_TYPE => RouteFailureClass::ProxyResolutionUnavailable,
+        ERROR_WINHTTP_SECURE_CERT_CN_INVALID
+        | ERROR_WINHTTP_SECURE_CERT_DATE_INVALID
+        | ERROR_WINHTTP_SECURE_CERT_REVOKED
+        | ERROR_WINHTTP_SECURE_CERT_REV_FAILED
+        | ERROR_WINHTTP_SECURE_CERT_WRONG_USAGE
+        | ERROR_WINHTTP_SECURE_CHANNEL_ERROR
+        | ERROR_WINHTTP_SECURE_FAILURE
+        | ERROR_WINHTTP_SECURE_INVALID_CA
+        | ERROR_WINHTTP_SECURE_INVALID_CERT => RouteFailureClass::TlsError,
+        ERROR_WINHTTP_INVALID_URL | ERROR_WINHTTP_UNRECOGNIZED_SCHEME => {
+            RouteFailureClass::InvalidProxyConfig
+        }
+        ERROR_WINHTTP_CANNOT_CONNECT
+        | ERROR_WINHTTP_CONNECTION_ERROR
+        | ERROR_WINHTTP_NAME_NOT_RESOLVED => RouteFailureClass::ResolverError,
+        _ => RouteFailureClass::ResolverError,
+    }
+}
diff --git a/codex-rs/http-client/src/outbound_proxy/windows_tests.rs b/codex-rs/http-client/src/outbound_proxy/windows_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..589c06661cb3d10c0bf7f7d48ef75efce2cc5168
--- /dev/null
+++ b/codex-rs/http-client/src/outbound_proxy/windows_tests.rs
@@ -0,0 +1,20 @@
+//! Windows proxy parsing tests.
+
+use super::*;
+
+#[test]
+fn proxy_bypass_matches_whitespace_separated_winhttp_entries() {
+    let local_origin = RequestOrigin {
+        scheme: "https".to_string(),
+        host: "intranet".to_string(),
+        port: 443,
+    };
+    assert!(proxy_bypass_matches_origin("<local> *.corp", &local_origin));
+
+    let corp_origin = RequestOrigin {
+        scheme: "https".to_string(),
+        host: "service.corp".to_string(),
+        port: 443,
+    };
+    assert!(proxy_bypass_matches_origin("<local> *.corp", &corp_origin));
+}
diff --git a/codex-rs/http-client/src/outbound_proxy_redirect_coverage_tests.rs b/codex-rs/http-client/src/outbound_proxy_redirect_coverage_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8aefa93f1ea995cd85d638f2bb24f9a8854617dc
--- /dev/null
+++ b/codex-rs/http-client/src/outbound_proxy_redirect_coverage_tests.rs
@@ -0,0 +1,221 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::SubscriberExt;
+
+#[tokio::test]
+async fn route_aware_pool_strips_credentials_on_cross_origin_redirect() {
+    let (destination_addr, destination_thread) = spawn_proxy_listener();
+    let destination_url = format!("http://{destination_addr}/final");
+    let (redirect_addr, redirect_thread) = spawn_redirect_listener(&destination_url);
+    let initial_url = format!("http://{redirect_addr}/start");
+    cache_system_proxy_decision(&initial_url, SystemProxyDecision::Direct);
+    cache_system_proxy_decision(&destination_url, SystemProxyDecision::Direct);
+    let pool = crate::RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+
+    let response = tokio::time::timeout(
+        Duration::from_secs(2),
+        pool.get(&initial_url)
+            .header(AUTHORIZATION, "Bearer origin-secret")
+            .header(COOKIE, "session=origin-secret")
+            .header(PROXY_AUTHORIZATION, "Basic proxy-secret")
+            .send(),
+    )
+    .await
+    .expect("redirected request should finish")
+    .expect("cross-origin redirect should succeed");
+    let initial_request = only_request(redirect_thread, "redirect");
+    let destination_request = only_request(destination_thread, "destination");
+
+    assert_eq!(response.url().as_str(), destination_url);
+    assert_eq!(
+        [
+            credential_headers(&initial_request),
+            credential_headers(&destination_request),
+        ],
+        [(true, true, true), (false, false, false)]
+    );
+}
+
+#[tokio::test]
+async fn route_aware_pool_retains_credentials_for_same_origin_and_route() {
+    let (proxy_addr, proxy_thread) = spawn_http_listener(vec![
+        "HTTP/1.1 302 Found\r\nLocation: /final\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+            .to_string(),
+        "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok".to_string(),
+    ]);
+    let initial_url = "http://same-route.test/start";
+    let redirected_url = "http://same-route.test/final";
+    let route = SystemProxyDecision::Proxy {
+        url: format!("http://{proxy_addr}"),
+    };
+    cache_system_proxy_decision(initial_url, route.clone());
+    cache_system_proxy_decision(redirected_url, route);
+    let pool = crate::RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+
+    let response = tokio::time::timeout(
+        Duration::from_secs(2),
+        pool.get(initial_url)
+            .header(AUTHORIZATION, "Bearer origin-secret")
+            .header(COOKIE, "session=origin-secret")
+            .header(PROXY_AUTHORIZATION, "Basic proxy-secret")
+            .send(),
+    )
+    .await
+    .expect("redirected request should finish")
+    .expect("same-route redirect should succeed");
+    let requests = proxy_thread.join().expect("proxy thread should finish");
+
+    assert_eq!(response.url().as_str(), redirected_url);
+    assert_eq!(
+        requests
+            .iter()
+            .map(|request| credential_headers(request))
+            .collect::<Vec<_>>(),
+        vec![(true, true, true), (true, true, true)]
+    );
+}
+
+#[tokio::test]
+async fn route_aware_pool_sanitizes_redirected_failure_logs() {
+    let log_buffer = Arc::new(Mutex::new(Vec::new()));
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .with_ansi(false)
+            .with_writer(TestLogWriter {
+                buffer: Arc::clone(&log_buffer),
+            })
+            .with_filter(
+                tracing_subscriber::filter::Targets::new()
+                    .with_target("codex_http_client", tracing::Level::TRACE),
+            ),
+    );
+    let _guard = tracing::subscriber::set_default(subscriber);
+    tracing::debug!(target: "codex_http_client", "log capture sentinel");
+
+    let (enabled_failure_addr, enabled_failure_thread) = spawn_failing_listener();
+    let enabled_target_url =
+        format!("http://{enabled_failure_addr}/final?token=enabled-target-secret");
+    let (enabled_redirect_addr, enabled_redirect_thread) =
+        spawn_redirect_listener(&enabled_target_url);
+    let enabled_initial_url = format!("http://{enabled_redirect_addr}/start");
+    cache_system_proxy_decision(&enabled_initial_url, SystemProxyDecision::Direct);
+    cache_system_proxy_decision(&enabled_target_url, SystemProxyDecision::Direct);
+    let enabled_pool = crate::RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+
+    enabled_pool
+        .get(&enabled_initial_url)
+        .timeout(Duration::from_secs(2))
+        .send()
+        .await
+        .expect_err("redirect target should fail");
+    only_request(enabled_redirect_thread, "enabled redirect");
+    enabled_failure_thread
+        .join()
+        .expect("enabled failure thread should finish");
+
+    let (disabled_failure_addr, disabled_failure_thread) = spawn_failing_listener();
+    let disabled_target_url =
+        format!("http://{disabled_failure_addr}/final?token=disabled-target-secret");
+    let (disabled_redirect_addr, disabled_redirect_thread) =
+        spawn_redirect_listener(&disabled_target_url);
+    let disabled_initial_url = format!("http://{disabled_redirect_addr}/start");
+    cache_system_proxy_decision(&disabled_initial_url, SystemProxyDecision::Direct);
+    cache_system_proxy_decision(&disabled_target_url, SystemProxyDecision::Direct);
+    let disabled_pool = crate::RouteAwareClientPool::new_without_request_logging(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+
+    disabled_pool
+        .get(&disabled_initial_url)
+        .timeout(Duration::from_secs(2))
+        .send()
+        .await
+        .expect_err("redirect target should fail");
+    only_request(disabled_redirect_thread, "disabled redirect");
+    disabled_failure_thread
+        .join()
+        .expect("disabled failure thread should finish");
+
+    let logs = String::from_utf8(log_buffer.lock().expect("log buffer lock").clone())
+        .expect("logs should be UTF-8");
+    assert!(logs.contains("log capture sentinel"));
+    assert!(logs.contains(&enabled_initial_url));
+    assert!(!logs.contains(&disabled_initial_url));
+    assert_eq!(logs.matches("Request failed").count(), 1);
+    assert!(logs.contains("is_timeout"));
+    assert!(logs.contains("is_connect"));
+    for secret in [
+        "enabled-target-secret",
+        "disabled-target-secret",
+        enabled_target_url.as_str(),
+        disabled_target_url.as_str(),
+        "error=",
+    ] {
+        assert!(!logs.contains(secret), "logs exposed {secret}:\n{logs}");
+    }
+}
+
+fn credential_headers(request: &str) -> (bool, bool, bool) {
+    let names = request
+        .lines()
+        .filter_map(|line| {
+            line.split_once(':')
+                .map(|(name, _)| name.to_ascii_lowercase())
+        })
+        .collect::<Vec<_>>();
+    (
+        names.iter().any(|name| name == "authorization"),
+        names.iter().any(|name| name == "cookie"),
+        names.iter().any(|name| name == "proxy-authorization"),
+    )
+}
+
+fn spawn_failing_listener() -> (std::net::SocketAddr, std::thread::JoinHandle<()>) {
+    let listener =
+        std::net::TcpListener::bind(("127.0.0.1", 0)).expect("failing listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("failing listener should have an address");
+    listener
+        .set_nonblocking(true)
+        .expect("failing listener should become nonblocking");
+    let thread = std::thread::spawn(move || {
+        let deadline = Instant::now() + Duration::from_secs(2);
+        let (mut stream, _) = loop {
+            match listener.accept() {
+                Ok(connection) => break connection,
+                Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                    assert!(
+                        Instant::now() < deadline,
+                        "failing listener should receive a request"
+                    );
+                    std::thread::sleep(Duration::from_millis(10));
+                }
+                Err(error) => panic!("failing listener should accept: {error}"),
+            }
+        };
+        // Accepted sockets inherit the listener's nonblocking mode on macOS.
+        stream
+            .set_nonblocking(false)
+            .expect("failing stream should become blocking");
+        stream
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .expect("failing stream should get a read timeout");
+        read_http_message(&mut stream);
+    });
+    (address, thread)
+}
diff --git a/codex-rs/http-client/src/outbound_proxy_tests.rs b/codex-rs/http-client/src/outbound_proxy_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..22b3716d9cf9cfad119d7256362d90b2907c5da2
--- /dev/null
+++ b/codex-rs/http-client/src/outbound_proxy_tests.rs
@@ -0,0 +1,657 @@
+//! Shared outbound proxy policy tests.
+
+use super::*;
+use crate::HttpClientBuilder;
+use http::HeaderMap;
+use http::HeaderValue;
+use http::header::AUTHORIZATION;
+use http::header::COOKIE;
+use http::header::PROXY_AUTHORIZATION;
+use pretty_assertions::assert_eq;
+use std::io::Read;
+use std::io::Write;
+use std::sync::Arc;
+use std::sync::Mutex;
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::SubscriberExt;
+
+#[path = "outbound_proxy_redirect_coverage_tests.rs"]
+mod redirect_coverage_tests;
+
+struct MapEnv {
+    values: HashMap<String, String>,
+}
+
+fn spawn_proxy_listener() -> (std::net::SocketAddr, std::thread::JoinHandle<Vec<String>>) {
+    spawn_http_listener(vec![
+        "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok".to_string(),
+    ])
+}
+
+fn spawn_redirect_listener(
+    location: &str,
+) -> (std::net::SocketAddr, std::thread::JoinHandle<Vec<String>>) {
+    spawn_http_listener(vec![format!(
+        "HTTP/1.1 302 Found\r\nLocation: {location}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+    )])
+}
+
+fn spawn_http_listener(
+    responses: Vec<String>,
+) -> (std::net::SocketAddr, std::thread::JoinHandle<Vec<String>>) {
+    let listener =
+        std::net::TcpListener::bind(("127.0.0.1", 0)).expect("HTTP listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("HTTP listener should have an address");
+    listener
+        .set_nonblocking(true)
+        .expect("HTTP listener should become nonblocking");
+    let thread = std::thread::spawn(move || {
+        let mut requests = Vec::new();
+        for response in responses {
+            let deadline = Instant::now() + Duration::from_secs(10);
+            let (mut stream, _) = loop {
+                match listener.accept() {
+                    Ok(connection) => break connection,
+                    Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                        assert!(
+                            Instant::now() < deadline,
+                            "HTTP listener should receive the next request"
+                        );
+                        std::thread::sleep(Duration::from_millis(10));
+                    }
+                    Err(error) => panic!("HTTP listener should accept: {error}"),
+                }
+            };
+            stream
+                .set_nonblocking(false)
+                .expect("HTTP stream should become blocking");
+            stream
+                .set_read_timeout(Some(Duration::from_secs(10)))
+                .expect("HTTP stream should get a read timeout");
+            requests.push(read_http_message(&mut stream));
+            stream
+                .write_all(response.as_bytes())
+                .expect("HTTP listener should write response");
+        }
+        requests
+    });
+    (address, thread)
+}
+
+fn only_request(thread: std::thread::JoinHandle<Vec<String>>, source: &str) -> String {
+    let requests = thread
+        .join()
+        .unwrap_or_else(|_| panic!("{source} thread should finish"));
+    let [request]: [String; 1] = requests.try_into().unwrap_or_else(|requests: Vec<String>| {
+        panic!(
+            "{source} should receive one request, got {}",
+            requests.len()
+        )
+    });
+    request
+}
+
+fn read_http_message(stream: &mut impl Read) -> String {
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 1024];
+    loop {
+        let bytes_read = stream.read(&mut chunk).expect("HTTP message should read");
+        if bytes_read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..bytes_read]);
+        if let Some(header_end) = buffer.windows(4).position(|window| window == b"\r\n\r\n") {
+            let body_start = header_end + 4;
+            let headers = String::from_utf8_lossy(&buffer[..body_start]);
+            let content_length = headers
+                .lines()
+                .filter_map(|line| line.split_once(':'))
+                .find_map(|(name, value)| {
+                    name.eq_ignore_ascii_case("content-length")
+                        .then(|| value.trim().parse::<usize>().ok())
+                        .flatten()
+                })
+                .unwrap_or(0);
+            if buffer.len() >= body_start + content_length {
+                break;
+            }
+        }
+    }
+    String::from_utf8_lossy(&buffer).into_owned()
+}
+
+#[test]
+fn cloned_factories_share_chatgpt_cookie_stores_without_changing_value_equality() {
+    let factory =
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault).with_chatgpt_cookies([
+            HeaderValue::from_static("first=true"),
+            HeaderValue::from_static("second=true"),
+        ]);
+    let cloned = factory.clone();
+
+    assert!(Arc::ptr_eq(
+        &factory.chatgpt_cookie_store().expect("configured store"),
+        &cloned.chatgpt_cookie_store().expect("shared store"),
+    ));
+    assert_eq!(
+        factory,
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault).with_chatgpt_cookies([
+            HeaderValue::from_static("first=true"),
+            HeaderValue::from_static("second=true"),
+        ])
+    );
+}
+
+#[test]
+fn websocket_route_uses_http_equivalent_for_system_resolution() {
+    let env = MapEnv {
+        values: HashMap::new(),
+    };
+    let route = resolve_proxy_route(
+        &env,
+        "wss://api.openai.com/v1/responses",
+        OutboundProxyPolicy::RespectSystemProxy,
+        |request_url, origin| {
+            assert_eq!(request_url, "https://api.openai.com/v1/responses");
+            assert_eq!(origin.scheme, "https");
+            assert_eq!(origin.host, "api.openai.com");
+            assert_eq!(origin.port, 443);
+            SystemProxyDecision::Proxy {
+                url: "http://proxy.example:8080".to_string(),
+            }
+        },
+    );
+
+    assert_eq!(
+        route,
+        OutboundProxyRoute::Proxy {
+            url: "http://proxy.example:8080".to_string(),
+            no_proxy: None,
+        }
+    );
+}
+
+#[test]
+fn reqwest_default_route_preserves_transport_proxy_behavior() {
+    let env = MapEnv {
+        values: HashMap::new(),
+    };
+    let route = resolve_proxy_route(
+        &env,
+        "wss://api.openai.com/v1/responses",
+        OutboundProxyPolicy::ReqwestDefault,
+        |_, _| panic!("default policy should not resolve system proxy settings"),
+    );
+
+    assert_eq!(route, OutboundProxyRoute::TransportDefault);
+}
+
+#[cfg(target_os = "macos")]
+#[test]
+fn macos_proxy_configuration_rejects_invalid_destination() {
+    assert_eq!(
+        macos_system_proxy_configuration("not a valid destination"),
+        MacosSystemProxyConfiguration::Unavailable
+    );
+}
+
+impl EnvSource for MapEnv {
+    fn var(&self, key: &str) -> Option<String> {
+        self.values.get(key).cloned()
+    }
+}
+
+#[test]
+fn proxy_env_value_matches_reqwest_casing_precedence() {
+    let env = MapEnv {
+        values: HashMap::from([
+            ("HTTPS_PROXY".to_string(), "upper".to_string()),
+            ("https_proxy".to_string(), "lower".to_string()),
+            ("http_proxy".to_string(), "lower-only".to_string()),
+            ("ALL_PROXY".to_string(), String::new()),
+            ("all_proxy".to_string(), "masked".to_string()),
+        ]),
+    };
+
+    assert_eq!(
+        proxy_env_value(&env, "HTTPS_PROXY"),
+        Some("upper".to_string())
+    );
+    assert_eq!(
+        proxy_env_value(&env, "HTTP_PROXY"),
+        Some("lower-only".to_string())
+    );
+    assert_eq!(proxy_env_value(&env, "ALL_PROXY"), None);
+}
+
+#[test]
+fn environment_fallback_reads_injected_proxy_environment() {
+    let env = MapEnv {
+        values: HashMap::from([("HTTPS_PROXY".to_string(), "://invalid".to_string())]),
+    };
+    let route = resolve_env_proxy_route(&env, EnvProxyKind::Https);
+    let result = configure_builder_for_resolved_route(
+        reqwest::Client::builder(),
+        ClientRouteClass::Auth,
+        &route,
+    );
+
+    assert!(matches!(
+        result,
+        Err(BuildRouteAwareHttpClientError::InvalidProxyConfig {
+            route_class: ClientRouteClass::Auth,
+        })
+    ));
+}
+
+#[test]
+fn unavailable_system_route_resolves_environment_or_direct_explicitly() {
+    let env = MapEnv {
+        values: HashMap::from([
+            (
+                "HTTPS_PROXY".to_string(),
+                "http://proxy.example:8080".to_string(),
+            ),
+            ("NO_PROXY".to_string(), "localhost,.internal".to_string()),
+        ]),
+    };
+
+    assert_eq!(
+        route_from_system_decision(
+            &env,
+            EnvProxyKind::Https,
+            SystemProxyDecision::Unavailable {
+                failure: RouteFailureClass::ProxyResolutionUnavailable,
+            },
+        ),
+        OutboundProxyRoute::Proxy {
+            url: "http://proxy.example:8080".to_string(),
+            no_proxy: Some("localhost,.internal".to_string()),
+        }
+    );
+    assert_eq!(
+        route_from_system_decision(
+            &MapEnv {
+                values: HashMap::new(),
+            },
+            EnvProxyKind::Https,
+            SystemProxyDecision::Unavailable {
+                failure: RouteFailureClass::ProxyResolutionUnavailable,
+            },
+        ),
+        OutboundProxyRoute::Direct
+    );
+}
+
+#[test]
+fn unavailable_system_route_preserves_wss_http_proxy_fallback() {
+    let env = MapEnv {
+        values: HashMap::from([(
+            "HTTP_PROXY".to_string(),
+            "http://proxy.example:8080".to_string(),
+        )]),
+    };
+
+    let route = resolve_proxy_route(
+        &env,
+        "wss://api.openai.com/v1/responses",
+        OutboundProxyPolicy::RespectSystemProxy,
+        |_, _| SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        },
+    );
+
+    assert_eq!(
+        route,
+        OutboundProxyRoute::Proxy {
+            url: "http://proxy.example:8080".to_string(),
+            no_proxy: None,
+        }
+    );
+}
+
+#[cfg(any(target_os = "windows", target_os = "macos"))]
+#[tokio::test]
+async fn async_resolution_uses_cached_route_before_global_permit() {
+    let request_url = "https://cached-fast-path.test/request";
+    cache_system_proxy_decision(request_url, SystemProxyDecision::Direct);
+    let factory = HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy);
+    let permit = ASYNC_SYSTEM_PROXY_RESOLUTION_PERMIT
+        .acquire()
+        .await
+        .expect("global proxy permit should stay open");
+
+    let route = tokio::time::timeout(
+        Duration::from_secs(2),
+        factory.resolve_proxy_route_async(request_url.to_string()),
+    )
+    .await
+    .expect("cached resolution should not wait for the global permit")
+    .expect("cached route should resolve");
+    drop(permit);
+
+    assert_eq!(route, OutboundProxyRoute::Direct);
+}
+
+#[tokio::test]
+async fn enabled_environment_proxy_routes_request_through_proxy() {
+    let (proxy_addr, proxy_thread) = spawn_proxy_listener();
+    let env = MapEnv {
+        values: HashMap::from([("HTTP_PROXY".to_string(), format!("http://{proxy_addr}"))]),
+    };
+    let request_url = "http://enabled-proxy.test/proxy-check";
+    let builder = configure_proxy_for_route(
+        &env,
+        reqwest::Client::builder().timeout(Duration::from_secs(2)),
+        request_url,
+        ClientRouteClass::Auth,
+        OutboundProxyPolicy::RespectSystemProxy,
+        |_, _| SystemProxyDecision::Unavailable {
+            failure: RouteFailureClass::ProxyResolutionUnavailable,
+        },
+    )
+    .expect("enabled proxy route should configure");
+
+    let response = builder
+        .build()
+        .expect("proxy client should build")
+        .get(request_url)
+        .send()
+        .await
+        .expect("request should use local proxy");
+    let proxy_request = only_request(proxy_thread, "proxy");
+
+    assert_eq!(response.status(), reqwest::StatusCode::OK);
+    assert_eq!(
+        proxy_request.lines().next(),
+        Some("GET http://enabled-proxy.test/proxy-check HTTP/1.1")
+    );
+}
+
+#[tokio::test]
+async fn route_aware_builder_preserves_default_headers() {
+    let (server_addr, server_thread) = spawn_proxy_listener();
+    let request_url = format!("http://{server_addr}/builder-check");
+    cache_system_proxy_decision(&request_url, SystemProxyDecision::Direct);
+    let mut headers = HeaderMap::new();
+    headers.insert("x-builder-test", HeaderValue::from_static("preserved"));
+    let factory = HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy);
+    let client = HttpClientBuilder::new()
+        .default_headers(headers)
+        .build_respecting_outbound_proxy_policy(&factory, &request_url, ClientRouteClass::Api)
+        .expect("route-aware client should build");
+
+    let response = client
+        .get(&request_url)
+        .send()
+        .await
+        .expect("request should use direct route");
+    let request = only_request(server_thread, "server");
+
+    assert!(response.status().is_success());
+    assert!(
+        request
+            .lines()
+            .any(|line| line.eq_ignore_ascii_case("x-builder-test: preserved"))
+    );
+}
+
+#[tokio::test]
+async fn route_aware_pool_uses_respect_system_proxy_route_for_exact_url() {
+    let (proxy_addr, proxy_thread) = spawn_proxy_listener();
+    let request_url = "http://route-aware-proxy.test/proxy-check?pac=exact";
+    cache_system_proxy_decision(
+        request_url,
+        SystemProxyDecision::Proxy {
+            url: format!("http://{proxy_addr}"),
+        },
+    );
+    let pool = crate::RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+
+    let response = tokio::time::timeout(Duration::from_secs(2), pool.get(request_url).send())
+        .await
+        .expect("proxy request should finish")
+        .expect("request should use local proxy");
+    let proxy_request = only_request(proxy_thread, "proxy");
+
+    assert_eq!(response.status(), reqwest::StatusCode::OK);
+    assert_eq!(
+        proxy_request.lines().next(),
+        Some("GET http://route-aware-proxy.test/proxy-check?pac=exact HTTP/1.1")
+    );
+}
+
+#[tokio::test]
+async fn route_aware_pool_logs_only_the_final_redirect_outcome() {
+    let (proxy_addr, proxy_thread) = spawn_proxy_listener();
+    let redirected_url = "http://redirect-target.test/final?token=redirect-target-secret-value";
+    let (redirect_addr, redirect_thread) = spawn_redirect_listener(redirected_url);
+    let initial_url = format!("http://{redirect_addr}/start");
+    cache_system_proxy_decision(&initial_url, SystemProxyDecision::Direct);
+    cache_system_proxy_decision(
+        redirected_url,
+        SystemProxyDecision::Proxy {
+            url: format!("http://{proxy_addr}"),
+        },
+    );
+    let pool = crate::RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+    let log_buffer = Arc::new(Mutex::new(Vec::new()));
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .with_ansi(false)
+            .with_writer(TestLogWriter {
+                buffer: Arc::clone(&log_buffer),
+            })
+            .with_filter(
+                tracing_subscriber::filter::Targets::new()
+                    .with_target("codex_http_client", tracing::Level::TRACE),
+            ),
+    );
+    let _guard = tracing::subscriber::set_default(subscriber);
+    tracing::debug!(target: "codex_http_client", "log capture sentinel");
+
+    let response = tokio::time::timeout(Duration::from_secs(2), pool.get(&initial_url).send())
+        .await
+        .expect("redirected request should finish")
+        .expect("redirected request should use selected routes");
+    only_request(redirect_thread, "redirect");
+    only_request(proxy_thread, "proxy");
+
+    assert_eq!(response.status(), reqwest::StatusCode::OK);
+    let logs = String::from_utf8(log_buffer.lock().expect("log buffer lock").clone())
+        .expect("logs should be UTF-8");
+    assert!(logs.contains("log capture sentinel"));
+    assert!(logs.contains(&initial_url));
+    assert_eq!(logs.matches("Request completed").count(), 1);
+    for secret in ["redirect-target-secret-value", redirected_url, "location"] {
+        assert!(
+            !logs
+                .to_ascii_lowercase()
+                .contains(&secret.to_ascii_lowercase())
+        );
+    }
+}
+
+#[test]
+fn parses_pac_proxy_tokens() {
+    assert_eq!(
+        parse_proxy_list("PROXY proxy.internal:8080; DIRECT", "https"),
+        ParsedProxyListDecision::Proxy("http://proxy.internal:8080".to_string())
+    );
+    assert_eq!(
+        parse_proxy_list("HTTPS proxy.internal:8443", "https"),
+        ParsedProxyListDecision::Proxy("https://proxy.internal:8443".to_string())
+    );
+}
+
+#[test]
+fn unavailable_system_proxy_decision_is_cached() {
+    let request_url = "https://unavailable-cache.test/oauth/token";
+    let decision = SystemProxyDecision::Unavailable {
+        failure: RouteFailureClass::ProxyResolutionUnavailable,
+    };
+
+    cache_system_proxy_decision(request_url, decision.clone());
+
+    assert_eq!(cached_system_proxy_decision(request_url), Some(decision));
+}
+
+#[derive(Clone)]
+struct TestLogWriter {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+struct TestLogSink {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for TestLogWriter {
+    type Writer = TestLogSink;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        TestLogSink {
+            buffer: Arc::clone(&self.buffer),
+        }
+    }
+}
+
+impl Write for TestLogSink {
+    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
+        let mut log_buffer = self
+            .buffer
+            .lock()
+            .map_err(|_| io::Error::other("log buffer lock was poisoned"))?;
+        log_buffer.extend(buffer);
+        Ok(buffer.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
+
+#[test]
+fn system_proxy_resolution_is_single_flight() {
+    let cache = Arc::new(Mutex::new(HashMap::new()));
+    let request_url = "https://single-flight.test/models";
+    let origin = RequestOrigin::parse(request_url).expect("valid request URL");
+    let (started_tx, started_rx) = std::sync::mpsc::channel();
+    let (release_tx, release_rx) = std::sync::mpsc::channel();
+    let worker_cache = Arc::clone(&cache);
+    let worker_origin = origin.clone();
+
+    let worker = std::thread::spawn(move || {
+        resolve_system_proxy_with(&worker_cache, request_url, &worker_origin, |_, _| {
+            started_tx.send(()).expect("test should still be running");
+            release_rx.recv().expect("test should release resolver");
+            SystemProxyDecision::Direct
+        })
+    });
+
+    started_rx.recv().expect("resolver should start");
+    assert!(matches!(
+        cache.try_lock(),
+        Err(std::sync::TryLockError::WouldBlock)
+    ));
+    release_tx
+        .send(())
+        .expect("resolver should still be running");
+    assert_eq!(
+        worker.join().expect("resolver should finish"),
+        SystemProxyDecision::Direct
+    );
+    assert_eq!(
+        resolve_system_proxy_with(&cache, request_url, &origin, |_, _| {
+            panic!("cached waiter should not resolve the platform proxy again")
+        }),
+        SystemProxyDecision::Direct
+    );
+}
+
+#[test]
+fn system_proxy_cache_is_bounded() {
+    let mut cache = HashMap::new();
+    let now = Instant::now();
+
+    for index in 0..=SYSTEM_PROXY_CACHE_MAX_ENTRIES {
+        insert_system_proxy_cache_entry(
+            &mut cache,
+            &format!("https://bounded-cache.test/{index}"),
+            SystemProxyDecision::Direct,
+            now,
+        );
+    }
+
+    assert_eq!(cache.len(), SYSTEM_PROXY_CACHE_MAX_ENTRIES);
+}
+
+#[test]
+fn parses_static_winhttp_proxy_entries_for_target_scheme() {
+    assert_eq!(
+        parse_proxy_list("http=web-proxy:8080;https=secure-proxy:8443", "https"),
+        ParsedProxyListDecision::Proxy("http://secure-proxy:8443".to_string())
+    );
+    assert_eq!(
+        parse_proxy_list("http=web-proxy:8080 https=secure-proxy:8443", "https"),
+        ParsedProxyListDecision::Proxy("http://secure-proxy:8443".to_string())
+    );
+    assert_eq!(
+        parse_proxy_list("http=web-proxy:8080", "https"),
+        ParsedProxyListDecision::Unavailable
+    );
+    assert_eq!(
+        parse_proxy_list("proxy.internal:8080", "https"),
+        ParsedProxyListDecision::Proxy("http://proxy.internal:8080".to_string())
+    );
+}
+
+#[test]
+fn reports_direct_and_unsupported_proxy_tokens() {
+    assert_eq!(
+        parse_proxy_list("DIRECT; PROXY proxy.internal:8080", "https"),
+        ParsedProxyListDecision::Direct
+    );
+    assert_eq!(
+        parse_proxy_list("DIRECT", "https"),
+        ParsedProxyListDecision::Direct
+    );
+    assert_eq!(
+        parse_proxy_list("SOCKS proxy.internal:1080", "https"),
+        ParsedProxyListDecision::UnsupportedScheme
+    );
+}
+
+#[test]
+fn no_proxy_matches_exact_suffix_wildcard_and_port() {
+    let origin = RequestOrigin {
+        scheme: "https".to_string(),
+        host: "auth.openai.com".to_string(),
+        port: 443,
+    };
+    assert!(no_proxy_matches_origin("auth.openai.com", &origin));
+    assert!(!no_proxy_matches_origin("openai.com", &origin));
+    assert!(no_proxy_matches_origin(".openai.com", &origin));
+    assert!(no_proxy_matches_origin("*.openai.com", &origin));
+    assert!(no_proxy_matches_origin("auth.openai.com:443", &origin));
+    assert!(!no_proxy_matches_origin("auth.openai.com:8443", &origin));
+}
+
+#[test]
+fn system_proxy_cache_key_preserves_url_specific_pac_decisions() {
+    let request_url = "https://auth.openai.com/oauth/token?access_token=secret";
+    let cache_key = system_proxy_cache_key(request_url);
+
+    assert_ne!(
+        cache_key,
+        system_proxy_cache_key("https://auth.openai.com/oauth/revoke")
+    );
+    assert!(!cache_key.contains(request_url));
+}
diff --git a/codex-rs/http-client/src/request.rs b/codex-rs/http-client/src/request.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b21ce6280e5fb243e56149c06938b797035433a8
--- /dev/null
+++ b/codex-rs/http-client/src/request.rs
@@ -0,0 +1,333 @@
+use bytes::Bytes;
+use http::HeaderMap;
+use http::HeaderValue;
+use http::Method;
+use serde::Serialize;
+use serde_json::Value;
+use std::time::Duration;
+
+/// A JSON request body serialized once into reference-counted bytes.
+///
+/// Clones share the encoded allocation. Internally, the body can also hold the
+/// final compressed wire bytes while retaining the original JSON only when
+/// request-body trace logging is enabled.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EncodedJsonBody {
+    bytes: Bytes,
+    trace_bytes: Option<Bytes>,
+    prepared: bool,
+}
+
+impl EncodedJsonBody {
+    /// Serializes `value` into a reusable JSON body.
+    pub fn encode<T: Serialize + ?Sized>(value: &T) -> Result<Self, serde_json::Error> {
+        serde_json::to_vec(value).map(|bytes| Self {
+            bytes: Bytes::from(bytes),
+            trace_bytes: None,
+            prepared: false,
+        })
+    }
+
+    /// Returns the encoded bytes currently stored by this body.
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.bytes
+    }
+
+    pub(crate) fn trace_bytes(&self) -> &[u8] {
+        self.trace_bytes.as_ref().unwrap_or(&self.bytes)
+    }
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum RequestCompression {
+    #[default]
+    None,
+    Zstd,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum RequestBody {
+    Json(Value),
+    EncodedJson(EncodedJsonBody),
+    Raw(Bytes),
+}
+
+impl RequestBody {
+    pub fn json(&self) -> Option<&Value> {
+        match self {
+            Self::Json(value) => Some(value),
+            Self::EncodedJson(_) | Self::Raw(_) => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PreparedRequestBody {
+    pub headers: HeaderMap,
+    pub body: Option<Bytes>,
+}
+
+impl PreparedRequestBody {
+    pub fn body_bytes(&self) -> Bytes {
+        self.body.clone().unwrap_or_default()
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct Request {
+    pub method: Method,
+    pub url: String,
+    pub headers: HeaderMap,
+    pub body: Option<RequestBody>,
+    pub compression: RequestCompression,
+    pub timeout: Option<Duration>,
+    /// Maximum accepted response-body bytes, including streaming and error bodies.
+    /// `None` leaves the response unbounded.
+    pub response_body_limit_bytes: Option<usize>,
+}
+
+impl Request {
+    pub fn new(method: Method, url: String) -> Self {
+        Self {
+            method,
+            url,
+            headers: HeaderMap::new(),
+            body: None,
+            compression: RequestCompression::None,
+            timeout: None,
+            response_body_limit_bytes: None,
+        }
+    }
+
+    pub fn with_json<T: Serialize>(mut self, body: &T) -> Self {
+        self.body = serde_json::to_value(body).ok().map(RequestBody::Json);
+        self
+    }
+
+    pub fn with_raw_body(mut self, body: impl Into<Bytes>) -> Self {
+        self.body = Some(RequestBody::Raw(body.into()));
+        self
+    }
+
+    pub fn with_compression(mut self, compression: RequestCompression) -> Self {
+        self.compression = compression;
+        self
+    }
+
+    /// Prepares the body once and stores the exact bytes that will be sent.
+    ///
+    /// Cloning the returned request shares the body bytes, so retry attempts do
+    /// not repeat JSON serialization or compression. Request-signing auth also
+    /// sees the same final headers and bytes that the transport will send.
+    pub fn into_prepared(mut self) -> Result<Self, String> {
+        let is_json = matches!(
+            self.body,
+            Some(RequestBody::Json(_) | RequestBody::EncodedJson(_))
+        );
+        let trace_bytes = if self.compression != RequestCompression::None
+            && tracing::enabled!(target: "codex_http_client::transport", tracing::Level::TRACE)
+        {
+            match self.body.as_ref() {
+                Some(RequestBody::Json(body)) => Some(Bytes::from(
+                    serde_json::to_vec(body).map_err(|err| err.to_string())?,
+                )),
+                Some(RequestBody::EncodedJson(body)) => Some(body.bytes.clone()),
+                Some(RequestBody::Raw(_)) | None => None,
+            }
+        } else {
+            None
+        };
+        let prepared = self.prepare_body_for_send()?;
+        self.headers = prepared.headers;
+        self.body = match (is_json, prepared.body) {
+            (true, Some(bytes)) => Some(RequestBody::EncodedJson(EncodedJsonBody {
+                bytes,
+                trace_bytes,
+                prepared: true,
+            })),
+            (false, Some(body)) => Some(RequestBody::Raw(body)),
+            (_, None) => None,
+        };
+        self.compression = RequestCompression::None;
+        Ok(self)
+    }
+
+    /// Convert the request body into the exact bytes that will be sent.
+    ///
+    /// Auth schemes such as AWS SigV4 need to sign the final body bytes, including
+    /// compression and content headers. Calling this method does not mutate the
+    /// request.
+    pub fn prepare_body_for_send(&self) -> Result<PreparedRequestBody, String> {
+        let headers = self.headers.clone();
+        match self.body.as_ref() {
+            Some(RequestBody::Raw(raw_body)) => {
+                if self.compression != RequestCompression::None {
+                    return Err("request compression cannot be used with raw bodies".to_string());
+                }
+                Ok(PreparedRequestBody {
+                    headers,
+                    body: Some(raw_body.clone()),
+                })
+            }
+            Some(RequestBody::Json(body)) => {
+                let body = EncodedJsonBody::encode(body).map_err(|err| err.to_string())?;
+                self.prepare_encoded_json(headers, &body)
+            }
+            Some(RequestBody::EncodedJson(body)) => self.prepare_encoded_json(headers, body),
+            None => Ok(PreparedRequestBody {
+                headers,
+                body: None,
+            }),
+        }
+    }
+
+    fn prepare_encoded_json(
+        &self,
+        mut headers: HeaderMap,
+        body: &EncodedJsonBody,
+    ) -> Result<PreparedRequestBody, String> {
+        if body.prepared {
+            return Ok(PreparedRequestBody {
+                headers,
+                body: Some(body.bytes.clone()),
+            });
+        }
+
+        let bytes = if self.compression != RequestCompression::None {
+            if headers.contains_key(http::header::CONTENT_ENCODING) {
+                return Err(
+                    "request compression was requested but content-encoding is already set"
+                        .to_string(),
+                );
+            }
+
+            let pre_compression_bytes = body.bytes.len();
+            let compression_start = std::time::Instant::now();
+            let (compressed, content_encoding) = match self.compression {
+                RequestCompression::None => unreachable!("guarded by compression != None"),
+                RequestCompression::Zstd => (
+                    zstd::stream::encode_all(std::io::Cursor::new(body.as_bytes()), 3)
+                        .map_err(|err| err.to_string())?,
+                    HeaderValue::from_static("zstd"),
+                ),
+            };
+            let post_compression_bytes = compressed.len();
+            let compression_duration = compression_start.elapsed();
+
+            headers.insert(http::header::CONTENT_ENCODING, content_encoding);
+
+            tracing::debug!(
+                pre_compression_bytes,
+                post_compression_bytes,
+                compression_duration_ms = compression_duration.as_millis(),
+                "Compressed request body with zstd"
+            );
+
+            Bytes::from(compressed)
+        } else {
+            body.bytes.clone()
+        };
+
+        if !headers.contains_key(http::header::CONTENT_TYPE) {
+            headers.insert(
+                http::header::CONTENT_TYPE,
+                HeaderValue::from_static("application/json"),
+            );
+        }
+
+        Ok(PreparedRequestBody {
+            headers,
+            body: Some(bytes),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use http::HeaderValue;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    #[test]
+    fn prepare_body_for_send_serializes_json_and_sets_content_type() {
+        let request = Request::new(Method::POST, "https://example.com/v1/responses".to_string())
+            .with_json(&json!({"model": "test-model"}));
+
+        let prepared = request
+            .prepare_body_for_send()
+            .expect("body should prepare");
+
+        assert_eq!(
+            prepared.body,
+            Some(Bytes::from_static(br#"{"model":"test-model"}"#))
+        );
+        assert_eq!(
+            prepared
+                .headers
+                .get(http::header::CONTENT_TYPE)
+                .and_then(|value| value.to_str().ok()),
+            Some("application/json")
+        );
+        assert_eq!(
+            request.body,
+            Some(RequestBody::Json(json!({"model": "test-model"})))
+        );
+        assert_eq!(request.compression, RequestCompression::None);
+    }
+
+    #[test]
+    fn prepare_body_for_send_rejects_existing_content_encoding_when_compressing() {
+        let mut request =
+            Request::new(Method::POST, "https://example.com/v1/responses".to_string())
+                .with_json(&json!({"model": "test-model"}))
+                .with_compression(RequestCompression::Zstd);
+        request.headers.insert(
+            http::header::CONTENT_ENCODING,
+            HeaderValue::from_static("gzip"),
+        );
+
+        let err = request
+            .prepare_body_for_send()
+            .expect_err("conflicting content-encoding should fail");
+
+        assert_eq!(
+            err,
+            "request compression was requested but content-encoding is already set"
+        );
+    }
+
+    #[test]
+    fn into_prepared_stores_compressed_body_for_reuse() {
+        let body =
+            EncodedJsonBody::encode(&json!({"model": "test-model"})).expect("JSON should encode");
+        let mut request =
+            Request::new(Method::POST, "https://example.com/v1/responses".to_string())
+                .with_compression(RequestCompression::Zstd);
+        request.body = Some(RequestBody::EncodedJson(body));
+        let request = request.into_prepared().expect("body should prepare");
+        let Some(RequestBody::EncodedJson(body)) = request.body.as_ref() else {
+            panic!("expected an encoded JSON body");
+        };
+        let decompressed = zstd::stream::decode_all(std::io::Cursor::new(body.as_bytes()))
+            .expect("body should decompress");
+
+        assert_eq!(decompressed, br#"{"model":"test-model"}"#);
+        assert_eq!(request.compression, RequestCompression::None);
+        assert_eq!(
+            request.headers.get(http::header::CONTENT_ENCODING),
+            Some(&HeaderValue::from_static("zstd"))
+        );
+        assert_eq!(
+            request.headers.get(http::header::CONTENT_TYPE),
+            Some(&HeaderValue::from_static("application/json"))
+        );
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct Response {
+    pub status: http::StatusCode,
+    pub headers: HeaderMap,
+    pub body: Bytes,
+}
diff --git a/codex-rs/http-client/src/route_aware_client_pool.rs b/codex-rs/http-client/src/route_aware_client_pool.rs
new file mode 100644
index 0000000000000000000000000000000000000000..29705e44eb66f235adee5a8932264ee778f98ced
--- /dev/null
+++ b/codex-rs/http-client/src/route_aware_client_pool.rs
@@ -0,0 +1,815 @@
+use std::collections::HashMap;
+use std::fmt;
+use std::future::Future;
+use std::io;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+
+use bytes::Bytes;
+use futures::TryStream;
+use http::HeaderMap;
+use http::HeaderName;
+use http::HeaderValue;
+use http::Method;
+use http::StatusCode;
+use http::header::CONTENT_TYPE;
+use http::header::PROXY_AUTHORIZATION;
+use reqwest::IntoUrl;
+use serde::Serialize;
+
+use crate::BuildRouteAwareHttpClientError;
+use crate::ClientRouteClass;
+use crate::HttpClient;
+use crate::HttpClientBuilder;
+use crate::HttpClientFactory;
+use crate::OutboundProxyPolicy;
+use crate::OutboundProxyRoute;
+use crate::RouteFailureClass;
+use crate::route_aware_redirect::MAX_REDIRECTS;
+use crate::route_aware_redirect::insert_referer;
+use crate::route_aware_redirect::is_redirect;
+use crate::route_aware_redirect::redirect_request;
+use crate::route_aware_redirect::redirect_url;
+use crate::route_aware_redirect::remove_sensitive_headers;
+use crate::tls_backend_fallback::RustlsClientCache;
+use crate::tls_backend_fallback::should_retry_with_rustls;
+
+const MAX_CACHED_ROUTES: usize = 16;
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+enum CustomCaFallback {
+    #[default]
+    Disabled,
+    LegacyTransportDefault,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum SelectedTlsBackend {
+    TransportDefault,
+    RustlsFallback,
+}
+
+/// Reuses transport clients by resolved route while selecting a route for every request URL.
+///
+/// Request creation stays on the pool so the URL used for PAC or system-proxy resolution cannot
+/// differ from the URL that is sent. Redirects are followed through the pool as new requests, so
+/// each hop gets its own route decision while connections are still reused by route.
+#[derive(Clone)]
+pub struct RouteAwareClientPool {
+    http_client_factory: HttpClientFactory,
+    route_class: ClientRouteClass,
+    client_builder: HttpClientBuilder,
+    custom_ca_fallback: CustomCaFallback,
+    clients: Arc<Mutex<HashMap<OutboundProxyRoute, HttpClient>>>,
+    rustls_clients: Option<RustlsClientCache>,
+}
+
+impl fmt::Debug for RouteAwareClientPool {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("RouteAwareClientPool")
+            .field("http_client_factory", &self.http_client_factory)
+            .field("route_class", &self.route_class)
+            .finish_non_exhaustive()
+    }
+}
+
+/// Error returned when selecting a route or constructing its pooled HTTP client.
+#[derive(Debug, thiserror::Error)]
+pub enum RouteAwareClientPoolError {
+    #[error("failed to resolve the outbound proxy route: {0}")]
+    Resolve(#[source] io::Error),
+    #[error(transparent)]
+    Build(#[from] BuildRouteAwareHttpClientError),
+}
+
+/// Error returned while building, routing, or sending a route-aware request.
+#[derive(Debug, thiserror::Error)]
+pub enum RouteAwareRequestError {
+    #[error(transparent)]
+    Request(#[from] reqwest::Error),
+    #[error(transparent)]
+    Route(#[from] RouteAwareClientPoolError),
+    #[error("failed to build route-aware request: {0}")]
+    Build(String),
+    #[error("redirect target uses unsupported URL scheme: {0}")]
+    UnsupportedRedirectScheme(String),
+    #[error("too many redirects")]
+    TooManyRedirects,
+    #[error("route-aware request timed out")]
+    Timeout,
+}
+
+impl RouteAwareRequestError {
+    /// Classifies transport, proxy, and certificate failures without exposing request details.
+    pub fn failure_class(&self) -> Option<RouteFailureClass> {
+        if self.is_timeout() {
+            return Some(RouteFailureClass::ConnectTimeout);
+        }
+        if self.status() == Some(StatusCode::PROXY_AUTHENTICATION_REQUIRED) {
+            return Some(RouteFailureClass::ProxyAuthenticationRequired);
+        }
+        if let Self::Route(RouteAwareClientPoolError::Resolve(error)) = self
+            && let Some(source) = error.get_ref()
+            && source.is::<rustls::Error>()
+        {
+            return Some(RouteFailureClass::TlsError);
+        }
+
+        let mut source: Option<&(dyn std::error::Error + 'static)> = Some(self);
+        while let Some(error) = source {
+            if error.downcast_ref::<rustls::Error>().is_some()
+                || error.downcast_ref::<native_tls::Error>().is_some()
+            {
+                return Some(RouteFailureClass::TlsError);
+            }
+            if error.to_string() == "tunnel error: proxy authorization required" {
+                return Some(RouteFailureClass::ProxyAuthenticationRequired);
+            }
+            source = error.source();
+        }
+
+        match self {
+            Self::Route(RouteAwareClientPoolError::Build(
+                BuildRouteAwareHttpClientError::CustomCa(_),
+            )) => Some(RouteFailureClass::TlsError),
+            Self::Route(RouteAwareClientPoolError::Build(
+                BuildRouteAwareHttpClientError::InvalidProxyConfig { .. },
+            )) => Some(RouteFailureClass::InvalidProxyConfig),
+            Self::Route(RouteAwareClientPoolError::Resolve(_)) => {
+                Some(RouteFailureClass::ProxyResolutionUnavailable)
+            }
+            Self::Request(_)
+            | Self::Build(_)
+            | Self::UnsupportedRedirectScheme(_)
+            | Self::TooManyRedirects
+            | Self::Timeout => None,
+        }
+    }
+
+    pub fn status(&self) -> Option<StatusCode> {
+        match self {
+            Self::Request(error) => error.status(),
+            Self::Route(_)
+            | Self::Build(_)
+            | Self::UnsupportedRedirectScheme(_)
+            | Self::TooManyRedirects
+            | Self::Timeout => None,
+        }
+    }
+
+    pub fn is_timeout(&self) -> bool {
+        matches!(self, Self::Timeout) || matches!(self, Self::Request(error) if error.is_timeout())
+    }
+
+    pub fn is_connect(&self) -> bool {
+        matches!(self, Self::Request(error) if error.is_connect())
+    }
+
+    pub fn is_body(&self) -> bool {
+        matches!(self, Self::Request(error) if error.is_body())
+    }
+
+    pub fn is_request(&self) -> bool {
+        matches!(self, Self::Request(error) if error.is_request())
+    }
+
+    /// Removes a request URL from the underlying transport error before it is logged or returned.
+    ///
+    /// Use this for requests whose URL can contain credentials, such as signed blob uploads.
+    pub fn without_url(self) -> Self {
+        match self {
+            Self::Request(error) => Self::Request(error.without_url()),
+            other => other,
+        }
+    }
+}
+
+#[must_use = "requests are not sent unless `send` is awaited"]
+pub struct RouteAwareRequestBuilder {
+    pool: RouteAwareClientPool,
+    request: Result<reqwest::Request, RouteAwareRequestError>,
+}
+
+impl fmt::Debug for RouteAwareRequestBuilder {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let request = self.request.as_ref().ok();
+        formatter
+            .debug_struct("RouteAwareRequestBuilder")
+            .field("pool", &self.pool)
+            .field("method", &request.map(reqwest::Request::method))
+            .field("url", &request.map(|_| "<redacted>"))
+            .finish_non_exhaustive()
+    }
+}
+
+impl RouteAwareRequestBuilder {
+    fn new<U>(pool: RouteAwareClientPool, method: Method, url: U) -> Self
+    where
+        U: IntoUrl,
+    {
+        let request = url
+            .into_url()
+            .map(|url| reqwest::Request::new(method, url))
+            .map_err(RouteAwareRequestError::Request);
+        Self { pool, request }
+    }
+
+    pub fn headers(mut self, headers: HeaderMap) -> Self {
+        if let Ok(request) = &mut self.request {
+            request.headers_mut().extend(headers);
+        }
+        self
+    }
+
+    pub fn header<K, V>(mut self, key: K, value: V) -> Self
+    where
+        HeaderName: TryFrom<K>,
+        <HeaderName as TryFrom<K>>::Error: Into<http::Error>,
+        HeaderValue: TryFrom<V>,
+        <HeaderValue as TryFrom<V>>::Error: Into<http::Error>,
+    {
+        if let Ok(request) = &mut self.request {
+            let header = HeaderName::try_from(key)
+                .map_err(Into::into)
+                .and_then(|key| {
+                    HeaderValue::try_from(value)
+                        .map(|value| (key, value))
+                        .map_err(Into::into)
+                });
+            match header {
+                Ok((key, value)) => {
+                    request.headers_mut().append(key, value);
+                }
+                Err(error) => {
+                    self.request = Err(RouteAwareRequestError::Build(error.to_string()));
+                }
+            }
+        }
+        self
+    }
+
+    /// Sets a timeout for the request as a whole.
+    ///
+    /// The budget starts before outbound-route resolution and covers selecting or constructing a
+    /// pooled client, establishing a connection, sending the request, and awaiting the response.
+    /// Use [`HttpClientBuilder::connect_timeout`] when only connection establishment should be
+    /// bounded.
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        if let Ok(request) = &mut self.request {
+            *request.timeout_mut() = Some(timeout);
+        }
+        self
+    }
+
+    pub fn json<T>(mut self, value: &T) -> Self
+    where
+        T: ?Sized + Serialize,
+    {
+        if let Ok(request) = &mut self.request {
+            match serde_json::to_vec(value) {
+                Ok(body) => {
+                    if !request.headers().contains_key(CONTENT_TYPE) {
+                        request
+                            .headers_mut()
+                            .insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+                    }
+                    *request.body_mut() = Some(body.into());
+                }
+                Err(error) => {
+                    self.request = Err(RouteAwareRequestError::Build(error.to_string()));
+                }
+            }
+        }
+        self
+    }
+
+    pub fn body<B>(mut self, body: B) -> Self
+    where
+        B: Into<reqwest::Body>,
+    {
+        if let Ok(request) = &mut self.request {
+            *request.body_mut() = Some(body.into());
+        }
+        self
+    }
+
+    /// Sets a streaming request body without exposing the underlying HTTP implementation.
+    pub fn body_stream<S>(mut self, stream: S) -> Self
+    where
+        S: TryStream + Send + 'static,
+        S::Error: Into<Box<dyn std::error::Error + Send + Sync>>,
+        Bytes: From<S::Ok>,
+    {
+        if let Ok(request) = &mut self.request {
+            *request.body_mut() = Some(reqwest::Body::wrap_stream(stream));
+        }
+        self
+    }
+
+    pub async fn send(self) -> Result<reqwest::Response, RouteAwareRequestError> {
+        self.pool.send(self.request?).await
+    }
+}
+
+impl RouteAwareClientPool {
+    pub fn outbound_proxy_policy(&self) -> OutboundProxyPolicy {
+        self.http_client_factory.outbound_proxy_policy()
+    }
+
+    /// Creates a pool with the shared default HTTP transport settings.
+    pub fn new(http_client_factory: HttpClientFactory, route_class: ClientRouteClass) -> Self {
+        Self::with_builder(http_client_factory, route_class, HttpClientBuilder::new())
+    }
+
+    /// Creates a pool that returns redirect responses without following them.
+    ///
+    /// This applies both when reqwest owns redirect handling and when the pool follows redirects
+    /// manually so each hop can receive its own proxy-route decision.
+    pub fn new_without_redirects(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new().without_redirects(),
+        )
+    }
+
+    /// Creates a no-redirect pool without request URL or response-header diagnostics.
+    pub fn new_without_redirects_or_request_logging(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new()
+                .without_redirects()
+                .without_request_logging(),
+        )
+    }
+
+    /// Creates a pool whose clients limit only connection establishment.
+    ///
+    /// The timeout applies to every client built for a resolved route, including redirect hops.
+    pub fn with_connect_timeout(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+        connect_timeout: Duration,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new().connect_timeout(connect_timeout),
+        )
+    }
+
+    fn with_builder(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+        client_builder: HttpClientBuilder,
+    ) -> Self {
+        Self {
+            http_client_factory,
+            route_class,
+            client_builder,
+            custom_ca_fallback: CustomCaFallback::Disabled,
+            clients: Arc::new(Mutex::new(HashMap::new())),
+            rustls_clients: None,
+        }
+    }
+
+    /// Retries recognized TLS protocol-negotiation failures once using rustls.
+    ///
+    /// Successful fallback is remembered for each HTTPS origin and resolved outbound route.
+    /// Rustls clients are reused across fallback destinations that share a route, while other
+    /// destinations retain the existing transport-default backend.
+    pub fn with_tls_backend_fallback(mut self) -> Self {
+        self.rustls_clients = Some(RustlsClientCache::default());
+        self
+    }
+
+    /// Creates a pool with the shared defaults but without URL or response-header diagnostics.
+    pub fn new_without_request_logging(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new().without_request_logging(),
+        )
+    }
+
+    /// Preserves the legacy custom-CA fallback for transport-default proxy routes.
+    ///
+    /// Use this only when migrating a client that already continued with system roots after a
+    /// custom-CA construction failure. System-proxy routes still propagate construction errors.
+    pub fn with_legacy_custom_ca_fallback(mut self) -> Self {
+        self.custom_ca_fallback = CustomCaFallback::LegacyTransportDefault;
+        self
+    }
+
+    /// Creates a pool that retains the Cloudflare cookies required by ChatGPT endpoints.
+    pub fn with_chatgpt_cloudflare_cookies(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new().with_chatgpt_cloudflare_cookie_store(),
+        )
+    }
+
+    /// Creates a no-redirect pool that retains the Cloudflare cookies required by ChatGPT
+    /// endpoints.
+    pub fn with_chatgpt_cloudflare_cookies_without_redirects(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new()
+                .with_chatgpt_cloudflare_cookie_store()
+                .without_redirects(),
+        )
+    }
+
+    /// Creates a no-redirect ChatGPT Cloudflare-cookie pool without request diagnostics.
+    pub fn with_chatgpt_cloudflare_cookies_without_redirects_or_request_logging(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new()
+                .with_chatgpt_cloudflare_cookie_store()
+                .without_redirects()
+                .without_request_logging(),
+        )
+    }
+
+    /// Creates a ChatGPT Cloudflare-cookie pool without URL or response-header diagnostics.
+    pub fn with_chatgpt_cloudflare_cookies_without_request_logging(
+        http_client_factory: HttpClientFactory,
+        route_class: ClientRouteClass,
+    ) -> Self {
+        Self::with_builder(
+            http_client_factory,
+            route_class,
+            HttpClientBuilder::new()
+                .with_chatgpt_cloudflare_cookie_store()
+                .without_request_logging(),
+        )
+    }
+
+    pub fn get<U>(&self, url: U) -> RouteAwareRequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::GET, url)
+    }
+
+    pub fn post<U>(&self, url: U) -> RouteAwareRequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::POST, url)
+    }
+
+    pub fn put<U>(&self, url: U) -> RouteAwareRequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::PUT, url)
+    }
+
+    pub fn delete<U>(&self, url: U) -> RouteAwareRequestBuilder
+    where
+        U: IntoUrl,
+    {
+        self.request(Method::DELETE, url)
+    }
+
+    pub fn request<U>(&self, method: Method, url: U) -> RouteAwareRequestBuilder
+    where
+        U: IntoUrl,
+    {
+        RouteAwareRequestBuilder::new(self.clone(), method, url)
+    }
+
+    async fn send(
+        &self,
+        request: reqwest::Request,
+    ) -> Result<reqwest::Response, RouteAwareRequestError> {
+        let http_client_factory = self.http_client_factory.clone();
+        self.send_with_resolver(request, move |request_url| {
+            let http_client_factory = http_client_factory.clone();
+            async move {
+                http_client_factory
+                    .resolve_proxy_route_async(request_url)
+                    .await
+            }
+        })
+        .await
+    }
+
+    async fn send_with_resolver<F, Fut>(
+        &self,
+        mut request: reqwest::Request,
+        resolve_route: F,
+    ) -> Result<reqwest::Response, RouteAwareRequestError>
+    where
+        F: Fn(String) -> Fut,
+        Fut: Future<Output = io::Result<OutboundProxyRoute>>,
+    {
+        let request_method = request.method().clone();
+        let request_url = request.url().to_string();
+        let follows_redirects_manually = self.follows_redirects_manually();
+        let timeout_deadline = request
+            .timeout()
+            .copied()
+            .map(|timeout| tokio::time::Instant::now() + timeout);
+        let mut redirects = 0;
+        let mut previous_route = None;
+        loop {
+            let current_url = request.url().clone();
+            let (current_route, client, selected_tls_backend) = match timeout_deadline {
+                Some(timeout_deadline) => tokio::time::timeout_at(
+                    timeout_deadline,
+                    self.client_for_url_with_resolver(current_url.as_str(), &resolve_route),
+                )
+                .await
+                .map_err(|_| RouteAwareRequestError::Timeout)??,
+                None => {
+                    self.client_for_url_with_resolver(current_url.as_str(), &resolve_route)
+                        .await?
+                }
+            };
+            if previous_route
+                .as_ref()
+                .is_some_and(|previous_route| previous_route != &current_route)
+            {
+                request.headers_mut().remove(PROXY_AUTHORIZATION);
+            }
+            previous_route = Some(current_route.clone());
+            if let Some(timeout_deadline) = timeout_deadline {
+                let remaining = timeout_deadline
+                    .checked_duration_since(tokio::time::Instant::now())
+                    .ok_or(RouteAwareRequestError::Timeout)?;
+                if remaining.is_zero() {
+                    return Err(RouteAwareRequestError::Timeout);
+                }
+                *request.timeout_mut() = Some(remaining);
+            }
+            let method = request.method().clone();
+            let headers = request.headers().clone();
+            let version = request.version();
+            let timeout = request.timeout().copied();
+            let replay = request.try_clone();
+            let execute_request = async {
+                if follows_redirects_manually {
+                    client.execute_without_request_logging(request).await
+                } else {
+                    client.execute(request).await
+                }
+            };
+            let response = match match timeout_deadline {
+                Some(timeout_deadline) => {
+                    tokio::time::timeout_at(timeout_deadline, execute_request)
+                        .await
+                        .map_err(|_| RouteAwareRequestError::Timeout)?
+                }
+                None => execute_request.await,
+            } {
+                Ok(response) => response,
+                Err(error) => {
+                    let result = self
+                        .retry_with_rustls(
+                            &current_url,
+                            &current_route,
+                            selected_tls_backend,
+                            replay.as_ref(),
+                            error,
+                            timeout_deadline,
+                        )
+                        .await;
+
+                    if follows_redirects_manually
+                        && let Err(RouteAwareRequestError::Request(error)) = &result
+                    {
+                        client.log_error_summary(&request_method, &request_url, error);
+                    }
+
+                    result?
+                }
+            };
+            let status = response.status();
+            if !follows_redirects_manually || !is_redirect(status) {
+                if follows_redirects_manually {
+                    client.log_response(&request_method, &request_url, &response);
+                }
+                return Ok(response);
+            }
+            let Some(next_url) = redirect_url(&response) else {
+                if follows_redirects_manually {
+                    client.log_response(&request_method, &request_url, &response);
+                }
+                return Ok(response);
+            };
+            let Some(mut next_request) =
+                redirect_request(status, method, headers, version, timeout, replay, next_url)
+            else {
+                if follows_redirects_manually {
+                    client.log_response(&request_method, &request_url, &response);
+                }
+                return Ok(response);
+            };
+            let next_request_url = next_request.url().clone();
+            if !matches!(next_request_url.scheme(), "http" | "https") {
+                return Err(RouteAwareRequestError::UnsupportedRedirectScheme(
+                    next_request_url.scheme().to_string(),
+                ));
+            }
+            if redirects >= MAX_REDIRECTS {
+                return Err(RouteAwareRequestError::TooManyRedirects);
+            }
+            remove_sensitive_headers(next_request.headers_mut(), &current_url, &next_request_url);
+            insert_referer(next_request.headers_mut(), &current_url, &next_request_url);
+            request = next_request;
+            redirects += 1;
+        }
+    }
+
+    async fn retry_with_rustls(
+        &self,
+        current_url: &reqwest::Url,
+        current_route: &OutboundProxyRoute,
+        selected_tls_backend: SelectedTlsBackend,
+        replay: Option<&reqwest::Request>,
+        error: reqwest::Error,
+        timeout_deadline: Option<tokio::time::Instant>,
+    ) -> Result<reqwest::Response, RouteAwareRequestError> {
+        let Some(rustls_clients) = self.rustls_clients.as_ref() else {
+            return Err(error.into());
+        };
+
+        if current_url.scheme() != "https"
+            || selected_tls_backend == SelectedTlsBackend::RustlsFallback
+            || !should_retry_with_rustls(&error)
+        {
+            return Err(error.into());
+        }
+
+        let Some(mut retry_request) = replay.and_then(reqwest::Request::try_clone) else {
+            return Err(error.into());
+        };
+
+        let fallback_client = match rustls_clients.client_for_route(current_route) {
+            Some(client) => client,
+            None => self.rustls_client_for_route(current_route)?,
+        };
+
+        if let Some(timeout_deadline) = timeout_deadline {
+            let remaining = timeout_deadline
+                .checked_duration_since(tokio::time::Instant::now())
+                .ok_or(RouteAwareRequestError::Timeout)?;
+            if remaining.is_zero() {
+                return Err(RouteAwareRequestError::Timeout);
+            }
+            *retry_request.timeout_mut() = Some(remaining);
+        }
+
+        let execute_retry = async {
+            if self.follows_redirects_manually() {
+                fallback_client
+                    .execute_without_request_logging(retry_request)
+                    .await
+            } else {
+                fallback_client.execute(retry_request).await
+            }
+        };
+        let response = match timeout_deadline {
+            Some(timeout_deadline) => tokio::time::timeout_at(timeout_deadline, execute_retry)
+                .await
+                .map_err(|_| RouteAwareRequestError::Timeout)?,
+            None => execute_retry.await,
+        }?;
+
+        rustls_clients.remember(current_url, current_route, fallback_client);
+        tracing::info!(
+            event.name = "codex.http_client.tls_backend_fallback",
+            "HTTP client switched to rustls after a TLS protocol negotiation failure"
+        );
+
+        Ok(response)
+    }
+
+    async fn client_for_url_with_resolver<F, Fut>(
+        &self,
+        request_url: &str,
+        resolve_route: F,
+    ) -> Result<(OutboundProxyRoute, HttpClient, SelectedTlsBackend), RouteAwareClientPoolError>
+    where
+        F: FnOnce(String) -> Fut,
+        Fut: Future<Output = io::Result<OutboundProxyRoute>>,
+    {
+        let route = resolve_route(request_url.to_string())
+            .await
+            .map_err(RouteAwareClientPoolError::Resolve)?;
+        if let Some(rustls_clients) = self.rustls_clients.as_ref()
+            && let Ok(url) = reqwest::Url::parse(request_url)
+            && rustls_clients.requires_rustls(&url, &route)
+            && let Some(client) = rustls_clients.client_for_route(&route)
+        {
+            return Ok((route, client, SelectedTlsBackend::RustlsFallback));
+        }
+        let clients = match self.clients.lock() {
+            Ok(clients) => clients,
+            Err(error) => panic!("route-aware client cache lock should not be poisoned: {error}"),
+        };
+        if let Some(client) = clients.get(&route) {
+            return Ok((route, client.clone(), SelectedTlsBackend::TransportDefault));
+        }
+        drop(clients);
+
+        let client_builder = if self.follows_redirects_manually() {
+            self.client_builder.clone().without_redirects()
+        } else {
+            self.client_builder.clone()
+        };
+        #[expect(
+            deprecated,
+            reason = "explicitly opted-in pools preserve the legacy custom-CA fallback"
+        )]
+        let client = match (
+            self.http_client_factory.outbound_proxy_policy(),
+            self.custom_ca_fallback,
+        ) {
+            (OutboundProxyPolicy::ReqwestDefault, CustomCaFallback::LegacyTransportDefault) => {
+                client_builder.build_with_transport_default_proxy_and_custom_ca_fallback()
+            }
+            (OutboundProxyPolicy::ReqwestDefault, CustomCaFallback::Disabled)
+            | (OutboundProxyPolicy::RespectSystemProxy, CustomCaFallback::Disabled)
+            | (OutboundProxyPolicy::RespectSystemProxy, CustomCaFallback::LegacyTransportDefault) => {
+                client_builder.build_for_resolved_route(
+                    &self.http_client_factory,
+                    self.route_class,
+                    &route,
+                )?
+            }
+        };
+        let mut clients = match self.clients.lock() {
+            Ok(clients) => clients,
+            Err(error) => panic!("route-aware client cache lock should not be poisoned: {error}"),
+        };
+        if let Some(existing_client) = clients.get(&route) {
+            return Ok((
+                route,
+                existing_client.clone(),
+                SelectedTlsBackend::TransportDefault,
+            ));
+        }
+        if clients.len() >= MAX_CACHED_ROUTES
+            && let Some(route_to_evict) = clients.keys().next().cloned()
+        {
+            clients.remove(&route_to_evict);
+        }
+        clients.insert(route.clone(), client.clone());
+        Ok((route, client, SelectedTlsBackend::TransportDefault))
+    }
+
+    fn follows_redirects_manually(&self) -> bool {
+        self.client_builder.follows_redirects()
+            && (self.http_client_factory.outbound_proxy_policy()
+                == OutboundProxyPolicy::RespectSystemProxy
+                || self.rustls_clients.is_some())
+    }
+
+    fn rustls_client_for_route(
+        &self,
+        route: &OutboundProxyRoute,
+    ) -> Result<HttpClient, RouteAwareClientPoolError> {
+        let mut client_builder = self.client_builder.clone().with_rustls_tls();
+        if self.follows_redirects_manually() {
+            client_builder = client_builder.without_redirects();
+        }
+        client_builder
+            .build_for_resolved_route(&self.http_client_factory, self.route_class, route)
+            .map_err(Into::into)
+    }
+}
+
+#[cfg(test)]
+#[path = "route_aware_client_pool_tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "route_aware_tls_fallback_tests.rs"]
+mod tls_fallback_tests;
diff --git a/codex-rs/http-client/src/route_aware_client_pool_tests.rs b/codex-rs/http-client/src/route_aware_client_pool_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1be6042edb0b7c130661ced5337fae4448d0db16
--- /dev/null
+++ b/codex-rs/http-client/src/route_aware_client_pool_tests.rs
@@ -0,0 +1,899 @@
+use std::collections::HashMap;
+use std::io;
+use std::io::Read;
+use std::io::Write;
+use std::net::TcpListener;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::atomic::AtomicUsize;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+use std::time::Instant;
+
+use bytes::Bytes;
+use futures::stream;
+use pretty_assertions::assert_eq;
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::SubscriberExt;
+
+use super::*;
+use crate::OutboundProxyPolicy;
+
+#[tokio::test]
+async fn request_failures_classify_real_untrusted_certificate_handshakes() {
+    codex_utils_rustls_provider::ensure_rustls_crypto_provider();
+    let certificate = rcgen::generate_simple_self_signed(vec!["localhost".to_string()])
+        .expect("self-signed certificate should generate");
+    let private_key = rustls::pki_types::PrivateKeyDer::Pkcs8(
+        rustls::pki_types::PrivatePkcs8KeyDer::from(certificate.signing_key.serialize_der()),
+    );
+    let configuration = Arc::new(
+        rustls::ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![certificate.cert.der().clone()], private_key)
+            .expect("TLS server should be configured"),
+    );
+    let listener = TcpListener::bind("127.0.0.1:0").expect("TLS server should bind");
+    let address = listener
+        .local_addr()
+        .expect("TLS server should have an address");
+    let server = std::thread::spawn(move || {
+        let (mut stream, _) = listener.accept().expect("TLS server should accept");
+        stream
+            .set_read_timeout(Some(Duration::from_secs(3)))
+            .expect("TLS handshake timeout");
+        let mut connection = rustls::ServerConnection::new(configuration)
+            .expect("TLS server connection should be created");
+        let _ = connection.complete_io(&mut stream);
+    });
+    let pool = RouteAwareClientPool::new_without_request_logging(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+    );
+
+    let request = pool
+        .get(format!("https://localhost:{}/", address.port()))
+        .timeout(Duration::from_secs(3))
+        .request
+        .expect("TLS request should build");
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("self-signed server certificate must not be trusted");
+    drop(std::net::TcpStream::connect(address));
+    server.join().expect("TLS server should finish");
+
+    assert_eq!(
+        error.failure_class(),
+        Some(RouteFailureClass::TlsError),
+        "unexpected certificate error: {error:?}"
+    );
+}
+
+#[tokio::test]
+async fn request_failures_classify_https_proxy_authentication_challenges() {
+    let (address, proxy) = spawn_response_server(vec![
+        "HTTP/1.1 407 Proxy Authentication Required\r\n\
+         Proxy-Authenticate: Basic realm=\"codex\"\r\n\
+         Content-Length: 0\r\n\
+         Connection: close\r\n\r\n"
+            .to_string(),
+    ]);
+    let pool = RouteAwareClientPool::new_without_request_logging(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+    let mut request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse("https://example.com/").expect("request URL should parse"),
+    );
+    *request.timeout_mut() = Some(Duration::from_secs(3));
+
+    let error = pool
+        .send_with_resolver(request, move |_| async move {
+            Ok(OutboundProxyRoute::Proxy {
+                url: format!("http://{address}"),
+                no_proxy: None,
+            })
+        })
+        .await
+        .expect_err("HTTPS proxy challenge should reject the CONNECT request");
+    let requests = proxy.join().expect("proxy fixture should finish");
+
+    assert_eq!(requests.len(), 1);
+    assert!(requests[0].starts_with("CONNECT example.com:443 HTTP/1.1\r\n"));
+    assert_eq!(
+        error.failure_class(),
+        Some(RouteFailureClass::ProxyAuthenticationRequired),
+        "unexpected HTTPS proxy error: {error:?}"
+    );
+}
+
+#[test]
+fn request_builder_debug_redacts_url_secrets() {
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+    );
+    let request = pool.get(
+        "https://username:password@private.example/secret-path?sig=query-secret#fragment-secret",
+    );
+
+    assert_eq!(
+        format!("{request:?}"),
+        concat!(
+            "RouteAwareRequestBuilder { pool: RouteAwareClientPool { ",
+            "http_client_factory: HttpClientFactory { outbound_proxy_policy: ReqwestDefault, ",
+            "network_policy: NetworkPolicy { managed: false, .. } }, ",
+            "route_class: Api, .. }, method: Some(GET), ",
+            "url: Some(\"<redacted>\"), .. }"
+        )
+    );
+}
+
+#[tokio::test]
+async fn streams_request_bodies_without_exposing_reqwest_body() {
+    let (address, server) = spawn_response_server(vec![
+        "HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n".to_string(),
+    ]);
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+    );
+    let response = pool
+        .put(format!("http://{address}/upload"))
+        .header(http::header::CONTENT_LENGTH, /*value*/ 5)
+        .body_stream(stream::iter(vec![Ok::<_, io::Error>(Bytes::from_static(
+            b"hello",
+        ))]))
+        .send()
+        .await
+        .expect("streaming request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let requests = server.join().expect("response server should finish");
+    assert_eq!(requests.len(), 1);
+    assert!(requests[0].ends_with("\r\n\r\nhello"));
+}
+
+#[tokio::test]
+async fn legacy_custom_ca_fallback_is_limited_to_reqwest_default() {
+    const CHILD_POLICY_ENV: &str = "CODEX_HTTP_CLIENT_POOL_INVALID_CA_TEST_POLICY";
+
+    let Ok(policy_name) = std::env::var(CHILD_POLICY_ENV) else {
+        let temp_dir = tempfile::tempdir().expect("temporary directory should be created");
+        let invalid_ca_path = temp_dir.path().join("invalid-ca.pem");
+        std::fs::write(&invalid_ca_path, "not a PEM certificate")
+            .expect("invalid CA fixture should be written");
+
+        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
+            for policy_name in ["reqwest-default", "respect-system-proxy"] {
+                let output = std::process::Command::new(
+                    std::env::current_exe().expect("test executable should be available"),
+                )
+                .arg("--exact")
+                .arg("route_aware_client_pool::tests::legacy_custom_ca_fallback_is_limited_to_reqwest_default")
+                .arg("--nocapture")
+                .env_remove("CODEX_CA_CERTIFICATE")
+                .env_remove("SSL_CERT_FILE")
+                .env(ca_env, &invalid_ca_path)
+                .env(CHILD_POLICY_ENV, policy_name)
+                .output()
+                .expect("isolated CA subprocess should run");
+
+                assert!(
+                    output.status.success(),
+                    "{policy_name} failed with invalid {ca_env}\nstdout:\n{}\nstderr:\n{}",
+                    String::from_utf8_lossy(&output.stdout),
+                    String::from_utf8_lossy(&output.stderr),
+                );
+            }
+        }
+        return;
+    };
+
+    let outbound_proxy_policy = match policy_name.as_str() {
+        "reqwest-default" => OutboundProxyPolicy::ReqwestDefault,
+        "respect-system-proxy" => OutboundProxyPolicy::RespectSystemProxy,
+        _ => panic!("unexpected test proxy policy: {policy_name}"),
+    };
+    let pool = RouteAwareClientPool::with_chatgpt_cloudflare_cookies(
+        HttpClientFactory::new(outbound_proxy_policy),
+        ClientRouteClass::Other,
+    )
+    .with_legacy_custom_ca_fallback();
+
+    match outbound_proxy_policy {
+        OutboundProxyPolicy::ReqwestDefault => {
+            let (address, server) = spawn_response_server(vec![
+                "HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n".to_string(),
+            ]);
+            let response = pool
+                .get(format!("http://{address}/update"))
+                .send()
+                .await
+                .expect("default-routed request should fall back to system roots");
+
+            assert_eq!(response.status(), StatusCode::OK);
+            let requests = server.join().expect("response server should finish");
+            assert_eq!(requests.len(), 1);
+        }
+        OutboundProxyPolicy::RespectSystemProxy => {
+            let error = pool
+                .client_for_url_with_resolver("http://127.0.0.1/update", |_| async {
+                    Ok(OutboundProxyRoute::Direct)
+                })
+                .await
+                .expect_err("system-proxy routes should reject invalid custom CAs");
+
+            assert!(matches!(error, RouteAwareClientPoolError::Build(_)));
+        }
+    }
+}
+
+#[tokio::test]
+async fn without_url_redacts_transport_error_urls() {
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("listener should bind");
+    let address = listener.local_addr().expect("listener should have address");
+    drop(listener);
+    let secret = "signed-secret";
+    let error = reqwest::Client::new()
+        .get(format!("http://{address}/upload?sig={secret}"))
+        .send()
+        .await
+        .expect_err("closed listener should reject request");
+    let error = RouteAwareRequestError::from(error).without_url();
+
+    assert!(!error.to_string().contains(secret));
+}
+
+#[tokio::test]
+async fn forwards_exact_urls_and_caches_clients_by_resolved_route() {
+    let pool = RouteAwareClientPool::with_builder(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+        HttpClientBuilder::new(),
+    );
+
+    let direct_url = "https://example.com/first?target=direct";
+    let same_route_url = "https://example.com/second?target=direct%202";
+    let proxy_url = "https://example.com/third?target=proxy";
+    let resolver = FakeRouteResolver::new(HashMap::from([
+        (direct_url.to_string(), OutboundProxyRoute::Direct),
+        (same_route_url.to_string(), OutboundProxyRoute::Direct),
+        (
+            proxy_url.to_string(),
+            OutboundProxyRoute::Proxy {
+                url: "http://proxy.example".to_string(),
+                no_proxy: None,
+            },
+        ),
+    ]));
+
+    resolve_with(&pool, &resolver, direct_url)
+        .await
+        .expect("first client should build");
+    resolve_with(&pool, &resolver, same_route_url)
+        .await
+        .expect("second client should reuse the route");
+    resolve_with(&pool, &resolver, proxy_url)
+        .await
+        .expect("proxy client should build separately");
+
+    assert_eq!(pool.clients.lock().expect("client cache lock").len(), 2);
+    assert_eq!(
+        resolver.observed_urls(),
+        vec![
+            direct_url.to_string(),
+            same_route_url.to_string(),
+            proxy_url.to_string(),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn cached_tls_backend_only_changes_its_destination_and_route() {
+    let pool = RouteAwareClientPool::with_builder(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+        HttpClientBuilder::new(),
+    )
+    .with_tls_backend_fallback();
+    let rustls_url = "https://mcp.example.com/first";
+    let native_url = "https://another.example.com/first";
+    let proxied_url = "https://mcp.example.com/proxied";
+    let proxy = OutboundProxyRoute::Proxy {
+        url: "http://proxy.example.com".to_string(),
+        no_proxy: None,
+    };
+    let resolver = FakeRouteResolver::new(HashMap::from([
+        (rustls_url.to_string(), OutboundProxyRoute::Direct),
+        (native_url.to_string(), OutboundProxyRoute::Direct),
+        (proxied_url.to_string(), proxy),
+    ]));
+    let fallback_client = HttpClientBuilder::new()
+        .with_rustls_tls()
+        .build_direct()
+        .expect("rustls client should build without proxy autodiscovery");
+    pool.rustls_clients
+        .as_ref()
+        .expect("TLS fallback cache")
+        .remember(
+            &reqwest::Url::parse(rustls_url).expect("valid rustls URL"),
+            &OutboundProxyRoute::Direct,
+            fallback_client,
+        );
+
+    resolve_with(&pool, &resolver, rustls_url)
+        .await
+        .expect("remembered destination should build the rustls client");
+    assert_eq!(pool.clients.lock().expect("client cache lock").len(), 0);
+
+    resolve_with(&pool, &resolver, native_url)
+        .await
+        .expect("another destination should retain its native TLS client");
+    resolve_with(&pool, &resolver, proxied_url)
+        .await
+        .expect("another proxy route should retain its native TLS client");
+    assert_eq!(pool.clients.lock().expect("client cache lock").len(), 2);
+}
+
+#[tokio::test]
+async fn tls_fallback_pool_reselects_routes_for_each_redirect_hop() {
+    let (address, server) = spawn_response_server(vec![
+        "HTTP/1.1 302 Found\r\nLocation: /final\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+            .to_string(),
+        "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok".to_string(),
+    ]);
+    let initial_url = format!("http://{address}/start");
+    let final_url = format!("http://{address}/final");
+    let resolver = FakeRouteResolver::new(HashMap::from([
+        (initial_url.clone(), OutboundProxyRoute::Direct),
+        (final_url.clone(), OutboundProxyRoute::Direct),
+    ]));
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse(&initial_url).expect("valid initial URL"),
+    );
+
+    let response = pool
+        .send_with_resolver(request, |url| resolver.resolve(url))
+        .await
+        .expect("fallback-enabled client should follow redirects");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(resolver.observed_urls(), vec![initial_url, final_url]);
+    assert_eq!(
+        server.join().expect("redirect server should finish").len(),
+        2
+    );
+}
+
+#[tokio::test]
+async fn reqwest_default_route_preserves_transport_redirects() {
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("redirect listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("redirect listener should have an address");
+    listener
+        .set_nonblocking(true)
+        .expect("redirect listener should become nonblocking");
+    let server = std::thread::spawn(move || {
+        let mut request_lines = Vec::new();
+        for response in [
+            "HTTP/1.1 302 Found\r\nLocation: /final\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
+            "HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok",
+        ] {
+            let deadline = Instant::now() + Duration::from_secs(2);
+            let (mut stream, _) = loop {
+                match listener.accept() {
+                    Ok(connection) => break connection,
+                    Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                        assert!(
+                            Instant::now() < deadline,
+                            "redirect server should receive the next request"
+                        );
+                        std::thread::sleep(Duration::from_millis(10));
+                    }
+                    Err(error) => panic!("redirect server should accept: {error}"),
+                }
+            };
+            // Accepted sockets inherit the listener's nonblocking mode on macOS.
+            stream
+                .set_nonblocking(false)
+                .expect("redirect stream should become blocking");
+            stream
+                .set_read_timeout(Some(Duration::from_secs(2)))
+                .expect("redirect stream should get a read timeout");
+            let mut buffer = [0_u8; 1024];
+            let size = stream
+                .read(&mut buffer)
+                .expect("redirect server should read request");
+            let request = String::from_utf8_lossy(&buffer[..size]);
+            request_lines.push(
+                request
+                    .lines()
+                    .next()
+                    .expect("request should have a request line")
+                    .to_string(),
+            );
+            stream
+                .write_all(response.as_bytes())
+                .expect("redirect server should write response");
+        }
+        request_lines
+    });
+    let pool = RouteAwareClientPool::with_builder(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+        HttpClientBuilder::new(),
+    );
+    let initial_url = format!("http://{address}/start");
+    let request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse(&initial_url).expect("request URL should parse"),
+    );
+
+    let response = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect("default-routed request should follow redirect");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    assert_eq!(response.url().as_str(), format!("http://{address}/final"));
+    assert_eq!(
+        server.join().expect("redirect server should finish"),
+        vec![
+            "GET /start HTTP/1.1".to_string(),
+            "GET /final HTTP/1.1".to_string(),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn no_redirect_pool_returns_redirect_response() {
+    for outbound_proxy_policy in [
+        OutboundProxyPolicy::ReqwestDefault,
+        OutboundProxyPolicy::RespectSystemProxy,
+    ] {
+        let (address, server) = spawn_response_server(vec![
+            "HTTP/1.1 302 Found\r\nLocation: /final\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+                .to_string(),
+        ]);
+        let pool = RouteAwareClientPool::new_without_redirects(
+            HttpClientFactory::new(outbound_proxy_policy),
+            ClientRouteClass::Api,
+        );
+        let initial_url = format!("http://{address}/start");
+        let request = reqwest::Request::new(
+            Method::GET,
+            reqwest::Url::parse(&initial_url).expect("request URL should parse"),
+        );
+
+        let response = pool
+            .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+            .await
+            .expect("no-redirect request should finish");
+
+        assert_eq!(response.status(), StatusCode::FOUND);
+        let requests = server.join().expect("redirect server should finish");
+        assert_eq!(requests.len(), 1);
+        assert!(requests[0].starts_with("GET /start HTTP/1.1\r\n"));
+    }
+}
+
+#[tokio::test]
+async fn bounds_cached_routes_and_rebuilds_an_evicted_route() {
+    let pool = RouteAwareClientPool::with_builder(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Api,
+        HttpClientBuilder::new(),
+    );
+    let routes = (0..=MAX_CACHED_ROUTES)
+        .map(|index| {
+            (
+                format!("https://target-{index}.example"),
+                OutboundProxyRoute::Proxy {
+                    url: format!("http://proxy-{index}.example"),
+                    no_proxy: None,
+                },
+            )
+        })
+        .collect::<HashMap<_, _>>();
+    let resolver = FakeRouteResolver::new(routes.clone());
+
+    for request_url in routes.keys() {
+        resolve_with(&pool, &resolver, request_url)
+            .await
+            .expect("client should build");
+    }
+    let evicted_route = {
+        let clients = pool.clients.lock().expect("client cache lock");
+        assert_eq!(clients.len(), MAX_CACHED_ROUTES);
+        routes
+            .iter()
+            .find(|(_, route)| !clients.contains_key(*route))
+            .map(|(request_url, _)| request_url.clone())
+            .expect("one route should have been evicted")
+    };
+
+    resolve_with(&pool, &resolver, &evicted_route)
+        .await
+        .expect("evicted client should rebuild");
+
+    let clients = pool.clients.lock().expect("client cache lock");
+    assert_eq!(clients.len(), MAX_CACHED_ROUTES);
+    assert!(clients.contains_key(&routes[&evicted_route]));
+}
+
+#[tokio::test]
+async fn request_timeout_covers_route_selection() {
+    let pool = manual_redirect_pool();
+    let mut request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse("http://route-selection-timeout.test/start")
+            .expect("request URL should parse"),
+    );
+    *request.timeout_mut() = Some(Duration::from_millis(10));
+    let resolver_calls = Arc::new(AtomicUsize::new(0));
+    let observed_resolver_calls = Arc::clone(&resolver_calls);
+
+    let error = pool
+        .send_with_resolver(request, move |_| {
+            observed_resolver_calls.fetch_add(1, Ordering::SeqCst);
+            async {
+                tokio::time::sleep(Duration::from_millis(100)).await;
+                Ok(OutboundProxyRoute::Direct)
+            }
+        })
+        .await
+        .expect_err("request should time out during route selection");
+
+    assert!(matches!(error, RouteAwareRequestError::Timeout));
+    assert_eq!(resolver_calls.load(Ordering::SeqCst), 1);
+}
+
+#[tokio::test]
+async fn request_timeout_is_shared_across_redirect_hops() {
+    let (address, server) = spawn_response_server(vec![
+        "HTTP/1.1 302 Found\r\nLocation: /final\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+            .to_string(),
+    ]);
+    let pool = manual_redirect_pool();
+    let mut request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse(&format!("http://{address}/start")).expect("request URL should parse"),
+    );
+    *request.timeout_mut() = Some(Duration::from_secs(2));
+    let resolver_calls = Arc::new(AtomicUsize::new(0));
+    let observed_resolver_calls = Arc::clone(&resolver_calls);
+
+    let error = pool
+        .send_with_resolver(request, move |_| {
+            let resolver_call = observed_resolver_calls.fetch_add(1, Ordering::SeqCst);
+            async move {
+                let delay = if resolver_call == 0 {
+                    Duration::from_millis(500)
+                } else {
+                    Duration::from_millis(1_750)
+                };
+                tokio::time::sleep(delay).await;
+                Ok(OutboundProxyRoute::Direct)
+            }
+        })
+        .await
+        .expect_err("redirect chain should exceed its shared timeout");
+
+    assert!(matches!(error, RouteAwareRequestError::Timeout));
+    assert_eq!(resolver_calls.load(Ordering::SeqCst), 2);
+    assert_eq!(
+        server.join().expect("redirect server should finish").len(),
+        1
+    );
+}
+
+#[tokio::test]
+async fn rejects_replayable_redirect_to_unsupported_scheme() {
+    let (address, server) = spawn_response_server(vec![
+        "HTTP/1.1 307 Temporary Redirect\r\nLocation: ftp://example.com/final\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+            .to_string(),
+    ]);
+    let pool = manual_redirect_pool();
+    let request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse(&format!("http://{address}/start")).expect("request URL should parse"),
+    );
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("unsupported redirect scheme should fail");
+
+    assert!(matches!(
+        error,
+        RouteAwareRequestError::UnsupportedRedirectScheme(scheme) if scheme == "ftp"
+    ));
+    assert_eq!(
+        server.join().expect("redirect server should finish").len(),
+        1
+    );
+}
+
+#[tokio::test]
+async fn rejects_redirects_beyond_the_limit() {
+    let responses = (0..=MAX_REDIRECTS)
+        .map(|redirect| {
+            format!(
+                "HTTP/1.1 302 Found\r\nLocation: /hop/{}\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
+                redirect + 1
+            )
+        })
+        .collect();
+    let (address, server) = spawn_response_server(responses);
+    let pool = manual_redirect_pool();
+    let request = reqwest::Request::new(
+        Method::GET,
+        reqwest::Url::parse(&format!("http://{address}/start")).expect("request URL should parse"),
+    );
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("redirect chain should stop at the limit");
+    let requests = server.join().expect("redirect server should finish");
+
+    assert!(matches!(error, RouteAwareRequestError::TooManyRedirects));
+    assert_eq!(requests.len(), MAX_REDIRECTS + 1);
+    assert_eq!(
+        requests.last().and_then(|request| request.lines().next()),
+        Some("GET /hop/10 HTTP/1.1")
+    );
+}
+
+#[tokio::test]
+async fn disabled_pool_logging_does_not_expose_request_or_response_data() {
+    let (address, server) = spawn_response_server(vec![
+        "HTTP/1.1 200 OK\r\nx-sensitive-response: response-secret-value\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok"
+            .to_string(),
+    ]);
+    let pool = RouteAwareClientPool::with_builder(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+        HttpClientBuilder::new().without_request_logging(),
+    );
+    let buffer = Arc::new(Mutex::new(Vec::new()));
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .with_ansi(false)
+            .with_writer(TestLogWriter {
+                buffer: Arc::clone(&buffer),
+            })
+            .with_filter(
+                tracing_subscriber::filter::Targets::new()
+                    .with_target("codex_http_client", tracing::Level::TRACE),
+            ),
+    );
+    let _guard = tracing::subscriber::set_default(subscriber);
+    tracing::debug!(target: "codex_http_client", "log capture sentinel");
+    let request_url = format!(
+        "http://auth-user:password-secret-value@{address}/token?client_secret=query-secret-value"
+    );
+    let mut request = reqwest::Request::new(
+        Method::POST,
+        reqwest::Url::parse(&request_url).expect("request URL should parse"),
+    );
+    request.headers_mut().insert(
+        "x-sensitive-request",
+        HeaderValue::from_static("request-header-secret-value"),
+    );
+    *request.body_mut() = Some("request-body-secret-value".into());
+    *request.timeout_mut() = Some(Duration::from_secs(2));
+
+    let response = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect("route-aware request should succeed");
+    assert_eq!(response.status(), StatusCode::OK);
+    server.join().expect("server thread should finish");
+
+    let unresponsive_listener =
+        TcpListener::bind(("127.0.0.1", 0)).expect("unresponsive listener should bind");
+    let unresponsive_address = unresponsive_listener
+        .local_addr()
+        .expect("unresponsive listener should have an address");
+    let failure_url = format!(
+        "http://auth-user:failure-password-secret-value@{unresponsive_address}/token?client_secret=failure-query-secret-value"
+    );
+    let mut request = reqwest::Request::new(
+        Method::POST,
+        reqwest::Url::parse(&failure_url).expect("failure URL should parse"),
+    );
+    *request.timeout_mut() = Some(Duration::from_millis(100));
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("request to an unresponsive listener should time out");
+    assert!(error.is_timeout());
+
+    let logs = String::from_utf8(buffer.lock().expect("log buffer lock").clone())
+        .expect("logs should be UTF-8");
+    assert!(logs.contains("log capture sentinel"));
+    for secret in [
+        "password-secret-value",
+        "query-secret-value",
+        "request-header-secret-value",
+        "request-body-secret-value",
+        "response-secret-value",
+        "failure-password-secret-value",
+        "failure-query-secret-value",
+    ] {
+        assert!(!logs.contains(secret), "logs exposed {secret}:\n{logs}");
+    }
+}
+
+#[derive(Clone)]
+struct FakeRouteResolver {
+    routes: Arc<HashMap<String, OutboundProxyRoute>>,
+    observed_urls: Arc<Mutex<Vec<String>>>,
+}
+
+impl FakeRouteResolver {
+    fn new(routes: HashMap<String, OutboundProxyRoute>) -> Self {
+        Self {
+            routes: Arc::new(routes),
+            observed_urls: Arc::new(Mutex::new(Vec::new())),
+        }
+    }
+
+    async fn resolve(&self, request_url: String) -> io::Result<OutboundProxyRoute> {
+        self.observed_urls
+            .lock()
+            .expect("observed URL lock")
+            .push(request_url.clone());
+        self.routes
+            .get(&request_url)
+            .cloned()
+            .ok_or_else(|| io::Error::other(format!("no route for {request_url}")))
+    }
+
+    fn observed_urls(&self) -> Vec<String> {
+        self.observed_urls
+            .lock()
+            .expect("observed URL lock")
+            .clone()
+    }
+}
+
+async fn resolve_with(
+    pool: &RouteAwareClientPool,
+    resolver: &FakeRouteResolver,
+    request_url: &str,
+) -> Result<HttpClient, RouteAwareClientPoolError> {
+    let resolver = resolver.clone();
+    let (_, client, _) = pool
+        .client_for_url_with_resolver(request_url, move |request_url| async move {
+            resolver.resolve(request_url).await
+        })
+        .await?;
+    Ok(client)
+}
+
+fn manual_redirect_pool() -> RouteAwareClientPool {
+    RouteAwareClientPool::with_builder(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+        HttpClientBuilder::new(),
+    )
+}
+
+fn spawn_response_server(
+    responses: Vec<String>,
+) -> (std::net::SocketAddr, std::thread::JoinHandle<Vec<String>>) {
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("response listener should bind");
+    let address = listener
+        .local_addr()
+        .expect("response listener should have an address");
+    listener
+        .set_nonblocking(true)
+        .expect("response listener should become nonblocking");
+    let server = std::thread::spawn(move || {
+        let mut requests = Vec::new();
+        for response in responses {
+            let deadline = Instant::now() + Duration::from_secs(2);
+            let (mut stream, _) = loop {
+                match listener.accept() {
+                    Ok(connection) => break connection,
+                    Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                        assert!(
+                            Instant::now() < deadline,
+                            "response server should receive the next request"
+                        );
+                        std::thread::sleep(Duration::from_millis(10));
+                    }
+                    Err(error) => panic!("response server should accept: {error}"),
+                }
+            };
+            stream
+                .set_nonblocking(false)
+                .expect("response stream should become blocking");
+            stream
+                .set_read_timeout(Some(Duration::from_secs(2)))
+                .expect("response stream should get a read timeout");
+            requests.push(read_http_message(&mut stream));
+            stream
+                .write_all(response.as_bytes())
+                .expect("response server should write response");
+        }
+        requests
+    });
+    (address, server)
+}
+
+fn read_http_message(stream: &mut impl Read) -> String {
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 1024];
+    loop {
+        let bytes_read = stream.read(&mut chunk).expect("HTTP message should read");
+        if bytes_read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..bytes_read]);
+        if let Some(header_end) = buffer.windows(4).position(|window| window == b"\r\n\r\n") {
+            let body_start = header_end + 4;
+            let headers = String::from_utf8_lossy(&buffer[..body_start]);
+            let content_length = headers
+                .lines()
+                .filter_map(|line| line.split_once(':'))
+                .find_map(|(name, value)| {
+                    name.eq_ignore_ascii_case("content-length")
+                        .then(|| value.trim().parse::<usize>().ok())
+                        .flatten()
+                })
+                .unwrap_or(0);
+            if buffer.len() >= body_start + content_length {
+                break;
+            }
+        }
+    }
+    String::from_utf8_lossy(&buffer).into_owned()
+}
+
+#[derive(Clone)]
+struct TestLogWriter {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+struct TestLogSink {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for TestLogWriter {
+    type Writer = TestLogSink;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        TestLogSink {
+            buffer: Arc::clone(&self.buffer),
+        }
+    }
+}
+
+impl Write for TestLogSink {
+    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
+        let mut log_buffer = self
+            .buffer
+            .lock()
+            .map_err(|_| io::Error::other("log buffer lock was poisoned"))?;
+        log_buffer.extend(buffer);
+        Ok(buffer.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
diff --git a/codex-rs/http-client/src/route_aware_redirect.rs b/codex-rs/http-client/src/route_aware_redirect.rs
new file mode 100644
index 0000000000000000000000000000000000000000..77af745725e66dee0112e240c95030065318978d
--- /dev/null
+++ b/codex-rs/http-client/src/route_aware_redirect.rs
@@ -0,0 +1,142 @@
+//! Redirect semantics for requests whose proxy route is selected from the complete URL.
+//!
+//! Reqwest normally follows redirects inside one `Client::execute` call. That is safe for
+//! `ReqwestDefault`, where reqwest owns proxy selection, but not for `RespectSystemProxy`: Codex
+//! resolves PAC and operating-system proxy settings before building a client pinned to the
+//! resulting direct or concrete-proxy route. An internal reqwest redirect would reuse that client
+//! for the new URL without giving [`crate::RouteAwareClientPool`] an opportunity to resolve the
+//! redirect destination.
+//!
+//! The pool therefore disables reqwest redirects for `RespectSystemProxy`, observes each redirect
+//! response, and uses these helpers to construct the next request before resolving its route. The
+//! helpers preserve the relevant reqwest method/body behavior while applying stricter
+//! origin-sensitive credential and `Referer` rules at the boundary between requests.
+
+use std::time::Duration;
+
+use http::HeaderMap;
+use http::Method;
+use http::StatusCode;
+use http::header::AUTHORIZATION;
+use http::header::CONTENT_ENCODING;
+use http::header::CONTENT_LENGTH;
+use http::header::CONTENT_TYPE;
+use http::header::COOKIE;
+use http::header::LOCATION;
+use http::header::PROXY_AUTHORIZATION;
+use http::header::REFERER;
+use http::header::TRANSFER_ENCODING;
+use http::header::WWW_AUTHENTICATE;
+
+pub(super) const MAX_REDIRECTS: usize = 10;
+
+pub(super) fn is_redirect(status: StatusCode) -> bool {
+    matches!(
+        status,
+        StatusCode::MOVED_PERMANENTLY
+            | StatusCode::FOUND
+            | StatusCode::SEE_OTHER
+            | StatusCode::TEMPORARY_REDIRECT
+            | StatusCode::PERMANENT_REDIRECT
+    )
+}
+
+pub(super) fn redirect_url(response: &reqwest::Response) -> Option<reqwest::Url> {
+    let location = response.headers().get(LOCATION)?.to_str().ok()?;
+    response.url().join(location).ok()
+}
+
+pub(super) fn redirect_request(
+    status: StatusCode,
+    mut method: Method,
+    mut headers: HeaderMap,
+    version: http::Version,
+    timeout: Option<Duration>,
+    replay: Option<reqwest::Request>,
+    next_url: reqwest::Url,
+) -> Option<reqwest::Request> {
+    let drop_body = match status {
+        StatusCode::MOVED_PERMANENTLY | StatusCode::FOUND if method == Method::POST => {
+            method = Method::GET;
+            true
+        }
+        StatusCode::SEE_OTHER => {
+            if method != Method::HEAD {
+                method = Method::GET;
+            }
+            true
+        }
+        StatusCode::MOVED_PERMANENTLY
+        | StatusCode::FOUND
+        | StatusCode::TEMPORARY_REDIRECT
+        | StatusCode::PERMANENT_REDIRECT => false,
+        _ => return None,
+    };
+
+    if drop_body {
+        for header in [
+            CONTENT_TYPE,
+            CONTENT_LENGTH,
+            CONTENT_ENCODING,
+            TRANSFER_ENCODING,
+        ] {
+            headers.remove(header);
+        }
+        let mut request = reqwest::Request::new(method, next_url);
+        *request.headers_mut() = headers;
+        *request.version_mut() = version;
+        *request.timeout_mut() = timeout;
+        Some(request)
+    } else {
+        replay.map(|mut request| {
+            *request.url_mut() = next_url;
+            request
+        })
+    }
+}
+
+pub(super) fn remove_sensitive_headers(
+    headers: &mut HeaderMap,
+    previous: &reqwest::Url,
+    next: &reqwest::Url,
+) {
+    if !same_origin(previous, next) {
+        for header in [AUTHORIZATION, COOKIE, PROXY_AUTHORIZATION, WWW_AUTHENTICATE] {
+            headers.remove(header);
+        }
+        headers.remove("cookie2");
+    }
+}
+
+pub(super) fn insert_referer(
+    headers: &mut HeaderMap,
+    previous: &reqwest::Url,
+    next: &reqwest::Url,
+) {
+    headers.remove(REFERER);
+    if next.scheme() == "http" && previous.scheme() == "https" {
+        return;
+    }
+
+    let mut referer = previous.clone();
+    let _ = referer.set_username("");
+    let _ = referer.set_password(None);
+    referer.set_fragment(None);
+    if !same_origin(previous, next) {
+        referer.set_path("/");
+        referer.set_query(None);
+    }
+    if let Ok(value) = referer.as_str().parse() {
+        headers.insert(REFERER, value);
+    }
+}
+
+fn same_origin(previous: &reqwest::Url, next: &reqwest::Url) -> bool {
+    previous.scheme() == next.scheme()
+        && previous.host_str() == next.host_str()
+        && previous.port_or_known_default() == next.port_or_known_default()
+}
+
+#[cfg(test)]
+#[path = "route_aware_redirect_tests.rs"]
+mod tests;
diff --git a/codex-rs/http-client/src/route_aware_redirect_integration_tests.rs b/codex-rs/http-client/src/route_aware_redirect_integration_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..344e8a7f6b010c3e47d2b21d20c77dafb5adc932
--- /dev/null
+++ b/codex-rs/http-client/src/route_aware_redirect_integration_tests.rs
@@ -0,0 +1,172 @@
+use std::io;
+use std::io::Read;
+use std::io::Write;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+use std::time::Instant;
+
+use http::header::AUTHORIZATION;
+use http::header::COOKIE;
+use http::header::PROXY_AUTHORIZATION;
+use pretty_assertions::assert_eq;
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::SubscriberExt;
+
+use super::*;
+use crate::RouteAwareClientPool;
+
+#[tokio::test]
+async fn route_aware_pool_re_resolves_redirects_and_logs_only_final_outcome() {
+    let (proxy_addr, proxy_thread) =
+        spawn_response("HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok");
+    let (redirect_addr, redirect_thread) = spawn_response(
+        "HTTP/1.1 302 Found\r\nLocation: /final?token=redirect-target-secret\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
+    );
+    let initial_url = format!("http://{redirect_addr}/start");
+    let redirected_url = format!("http://{redirect_addr}/final?token=redirect-target-secret");
+    cache_system_proxy_decision(&initial_url, SystemProxyDecision::Direct);
+    cache_system_proxy_decision(
+        &redirected_url,
+        SystemProxyDecision::Proxy {
+            url: format!("http://{proxy_addr}"),
+        },
+    );
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::RespectSystemProxy),
+        ClientRouteClass::Api,
+    );
+    let log_buffer = Arc::new(Mutex::new(Vec::new()));
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .with_ansi(false)
+            .with_writer(TestLogWriter {
+                buffer: Arc::clone(&log_buffer),
+            })
+            .with_filter(
+                tracing_subscriber::filter::Targets::new()
+                    .with_target("codex_http_client", tracing::Level::TRACE),
+            ),
+    );
+    let _guard = tracing::subscriber::set_default(subscriber);
+
+    tokio::time::timeout(
+        Duration::from_secs(2),
+        pool.get(&initial_url)
+            .header(AUTHORIZATION, "Bearer origin-secret")
+            .header(COOKIE, "session=origin-secret")
+            .header(PROXY_AUTHORIZATION, "Basic proxy-secret")
+            .send(),
+    )
+    .await
+    .expect("redirected request should finish")
+    .expect("redirected request should use both selected routes");
+    redirect_thread
+        .join()
+        .expect("redirect listener should finish");
+    let redirected_request = proxy_thread.join().expect("proxy listener should finish");
+    assert_eq!(
+        redirected_request.lines().next(),
+        Some(format!("GET {redirected_url} HTTP/1.1").as_str())
+    );
+    assert!(has_header(&redirected_request, "authorization"));
+    assert!(has_header(&redirected_request, "cookie"));
+    assert!(!has_header(&redirected_request, "proxy-authorization"));
+
+    let logs = String::from_utf8(log_buffer.lock().expect("log buffer lock").clone())
+        .expect("logs should be UTF-8");
+    assert!(logs.contains(&initial_url));
+    assert_eq!(logs.matches("Request completed").count(), 1);
+    assert!(!logs.contains("redirect-target-secret"));
+}
+
+fn spawn_response(
+    response: &'static str,
+) -> (std::net::SocketAddr, std::thread::JoinHandle<String>) {
+    let listener = std::net::TcpListener::bind(("127.0.0.1", 0)).expect("bind listener");
+    let address = listener.local_addr().expect("HTTP listener address");
+    listener.set_nonblocking(true).expect("set nonblocking");
+    let thread = std::thread::spawn(move || {
+        let deadline = Instant::now() + Duration::from_secs(2);
+        let (mut stream, _) = loop {
+            match listener.accept() {
+                Ok(connection) => break connection,
+                Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                    assert!(Instant::now() < deadline, "request timed out");
+                    std::thread::sleep(Duration::from_millis(10));
+                }
+                Err(error) => panic!("HTTP listener should accept: {error}"),
+            }
+        };
+        // Accepted sockets inherit the listener's nonblocking mode on macOS.
+        stream
+            .set_nonblocking(false)
+            .expect("set accepted stream blocking");
+        stream
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .expect("read timeout");
+        let request = read_http_headers(&mut stream);
+        stream
+            .write_all(response.as_bytes())
+            .expect("write response");
+        request
+    });
+    (address, thread)
+}
+
+fn read_http_headers(stream: &mut impl Read) -> String {
+    let mut buffer = Vec::new();
+    let mut chunk = [0_u8; 1024];
+    loop {
+        let bytes_read = stream.read(&mut chunk).expect("HTTP headers should read");
+        if bytes_read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..bytes_read]);
+        if buffer.windows(4).any(|window| window == b"\r\n\r\n") {
+            break;
+        }
+    }
+    String::from_utf8_lossy(&buffer).into_owned()
+}
+
+fn has_header(request: &str, expected_name: &str) -> bool {
+    request.lines().any(|line| {
+        line.split_once(':')
+            .is_some_and(|(name, _)| name.eq_ignore_ascii_case(expected_name))
+    })
+}
+
+#[derive(Clone)]
+struct TestLogWriter {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+struct TestLogSink {
+    buffer: Arc<Mutex<Vec<u8>>>,
+}
+
+impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for TestLogWriter {
+    type Writer = TestLogSink;
+
+    fn make_writer(&'a self) -> Self::Writer {
+        TestLogSink {
+            buffer: Arc::clone(&self.buffer),
+        }
+    }
+}
+
+impl Write for TestLogSink {
+    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
+        let mut log_buffer = self
+            .buffer
+            .lock()
+            .map_err(|_| io::Error::other("log buffer lock was poisoned"))?;
+        log_buffer.extend(buffer);
+        Ok(buffer.len())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        Ok(())
+    }
+}
diff --git a/codex-rs/http-client/src/route_aware_redirect_tests.rs b/codex-rs/http-client/src/route_aware_redirect_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d9e8f6053f3e61a1bba7db149cd295bb42de1df5
--- /dev/null
+++ b/codex-rs/http-client/src/route_aware_redirect_tests.rs
@@ -0,0 +1,233 @@
+use http::HeaderValue;
+use http::header::CONTENT_ENCODING;
+use http::header::CONTENT_LENGTH;
+use http::header::CONTENT_TYPE;
+use http::header::COOKIE;
+use http::header::REFERER;
+use http::header::TRANSFER_ENCODING;
+use pretty_assertions::assert_eq;
+
+use super::*;
+
+#[derive(Clone, Copy, Debug)]
+enum RedirectBodyBehavior {
+    Drop,
+    Preserve,
+}
+
+#[test]
+fn redirects_match_reqwest_method_and_body_rules() {
+    let original_url =
+        reqwest::Url::parse("https://example.com/original").expect("original URL should parse");
+    let redirected_url =
+        reqwest::Url::parse("https://example.com/next").expect("redirect URL should parse");
+
+    for (status, method, expected_method, body_behavior) in [
+        (
+            StatusCode::MOVED_PERMANENTLY,
+            Method::POST,
+            Method::GET,
+            RedirectBodyBehavior::Drop,
+        ),
+        (
+            StatusCode::FOUND,
+            Method::POST,
+            Method::GET,
+            RedirectBodyBehavior::Drop,
+        ),
+        (
+            StatusCode::SEE_OTHER,
+            Method::POST,
+            Method::GET,
+            RedirectBodyBehavior::Drop,
+        ),
+        (
+            StatusCode::SEE_OTHER,
+            Method::HEAD,
+            Method::HEAD,
+            RedirectBodyBehavior::Drop,
+        ),
+        (
+            StatusCode::MOVED_PERMANENTLY,
+            Method::PUT,
+            Method::PUT,
+            RedirectBodyBehavior::Preserve,
+        ),
+        (
+            StatusCode::FOUND,
+            Method::PUT,
+            Method::PUT,
+            RedirectBodyBehavior::Preserve,
+        ),
+        (
+            StatusCode::TEMPORARY_REDIRECT,
+            Method::POST,
+            Method::POST,
+            RedirectBodyBehavior::Preserve,
+        ),
+        (
+            StatusCode::PERMANENT_REDIRECT,
+            Method::POST,
+            Method::POST,
+            RedirectBodyBehavior::Preserve,
+        ),
+    ] {
+        let mut original = reqwest::Request::new(method.clone(), original_url.clone());
+        *original.headers_mut() = HeaderMap::from_iter([
+            (CONTENT_TYPE, HeaderValue::from_static("application/json")),
+            (CONTENT_LENGTH, HeaderValue::from_static("2")),
+            (CONTENT_ENCODING, HeaderValue::from_static("identity")),
+            (TRANSFER_ENCODING, HeaderValue::from_static("chunked")),
+            (
+                http::header::ACCEPT,
+                HeaderValue::from_static("application/json"),
+            ),
+        ]);
+        *original.version_mut() = http::Version::HTTP_2;
+        *original.timeout_mut() = Some(Duration::from_secs(7));
+        *original.body_mut() = Some("{}".into());
+        let mut expected_headers = original.headers().clone();
+        let expected_body = match body_behavior {
+            RedirectBodyBehavior::Drop => {
+                for header in [
+                    CONTENT_TYPE,
+                    CONTENT_LENGTH,
+                    CONTENT_ENCODING,
+                    TRANSFER_ENCODING,
+                ] {
+                    expected_headers.remove(header);
+                }
+                None
+            }
+            RedirectBodyBehavior::Preserve => Some(b"{}".to_vec()),
+        };
+
+        let redirected = redirect_request(
+            status,
+            original.method().clone(),
+            original.headers().clone(),
+            original.version(),
+            original.timeout().copied(),
+            original.try_clone(),
+            redirected_url.clone(),
+        )
+        .expect("supported redirect should be followed");
+
+        assert_eq!(
+            (
+                redirected.method().clone(),
+                redirected.url().clone(),
+                redirected.headers().clone(),
+                redirected.version(),
+                redirected.timeout().copied(),
+                redirected
+                    .body()
+                    .and_then(reqwest::Body::as_bytes)
+                    .map(<[u8]>::to_vec),
+            ),
+            (
+                expected_method,
+                redirected_url.clone(),
+                expected_headers,
+                http::Version::HTTP_2,
+                Some(Duration::from_secs(7)),
+                expected_body,
+            ),
+            "redirect behavior for {status} {method}",
+        );
+    }
+}
+
+#[test]
+fn redirect_referer_follows_strict_origin_when_cross_origin() {
+    let previous =
+        reqwest::Url::parse("https://user:password@example.com/start?access_token=secret#fragment")
+            .expect("valid URL");
+
+    let mut same_origin_headers = HeaderMap::new();
+    let same_origin = reqwest::Url::parse("https://example.com/next").expect("valid URL");
+    insert_referer(&mut same_origin_headers, &previous, &same_origin);
+    assert_eq!(
+        same_origin_headers.get(REFERER),
+        Some(&HeaderValue::from_static(
+            "https://example.com/start?access_token=secret"
+        ))
+    );
+
+    let mut cross_origin_headers = HeaderMap::new();
+    let cross_origin = reqwest::Url::parse("https://other.example/next").expect("valid URL");
+    insert_referer(&mut cross_origin_headers, &previous, &cross_origin);
+    assert_eq!(
+        cross_origin_headers.get(REFERER),
+        Some(&HeaderValue::from_static("https://example.com/"))
+    );
+
+    let mut downgrade_headers = HeaderMap::from_iter([(
+        REFERER,
+        HeaderValue::from_static("https://stale.example/path?secret=value"),
+    )]);
+    let downgrade = reqwest::Url::parse("http://other.example/next").expect("valid URL");
+    insert_referer(&mut downgrade_headers, &previous, &downgrade);
+    assert_eq!(downgrade_headers.get(REFERER), None);
+}
+
+#[test]
+fn non_replayable_redirect_is_not_followed_regardless_of_target_scheme() {
+    let next_url = reqwest::Url::parse("ftp://example.com/next").expect("valid URL");
+
+    let redirected = redirect_request(
+        StatusCode::TEMPORARY_REDIRECT,
+        Method::POST,
+        HeaderMap::new(),
+        http::Version::HTTP_11,
+        /*timeout*/ None,
+        /*replay*/ None,
+        next_url,
+    );
+
+    assert!(redirected.is_none());
+}
+
+#[test]
+fn redirect_credentials_are_retained_only_for_the_same_origin() {
+    for (previous, next, retain_credentials) in [
+        (
+            "https://example.com:8080/start",
+            "https://example.com:8080/next",
+            true,
+        ),
+        (
+            "https://example.com:8080/start",
+            "http://example.com:8080/next",
+            false,
+        ),
+        (
+            "https://example.com:8080/start",
+            "https://other.example:8080/next",
+            false,
+        ),
+        (
+            "https://example.com:8080/start",
+            "https://example.com:8081/next",
+            false,
+        ),
+    ] {
+        let previous = reqwest::Url::parse(previous).expect("previous URL should parse");
+        let next = reqwest::Url::parse(next).expect("next URL should parse");
+        let mut headers = HeaderMap::from_iter([
+            (AUTHORIZATION, HeaderValue::from_static("Bearer secret")),
+            (COOKIE, HeaderValue::from_static("session=secret")),
+        ]);
+
+        remove_sensitive_headers(&mut headers, &previous, &next);
+
+        assert_eq!(
+            (
+                headers.contains_key(AUTHORIZATION),
+                headers.contains_key(COOKIE),
+            ),
+            (retain_credentials, retain_credentials),
+            "credential handling for {previous} -> {next}"
+        );
+    }
+}
diff --git a/codex-rs/http-client/src/route_aware_tls_fallback_tests.rs b/codex-rs/http-client/src/route_aware_tls_fallback_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e5968030907599d7cdcdc608824aa27c4815c54a
--- /dev/null
+++ b/codex-rs/http-client/src/route_aware_tls_fallback_tests.rs
@@ -0,0 +1,510 @@
+use std::io;
+use std::io::Read;
+use std::io::Write;
+use std::net::TcpListener;
+use std::sync::Arc;
+use std::sync::mpsc;
+use std::thread;
+use std::time::Duration;
+use std::time::Instant;
+
+use bytes::Bytes;
+use futures::stream;
+use pretty_assertions::assert_eq;
+use rcgen::CertifiedKey;
+use rcgen::generate_simple_self_signed;
+use rustls_pki_types::PrivateKeyDer;
+
+use super::ClientRouteClass;
+use super::HttpClient;
+use super::HttpClientFactory;
+use super::Method;
+use super::OutboundProxyPolicy;
+use super::OutboundProxyRoute;
+use super::RouteAwareClientPool;
+use super::RouteAwareRequestError;
+use super::SelectedTlsBackend;
+use crate::tls_backend_fallback::should_retry_with_rustls;
+
+const PROTOCOL_VERSION_TLS_ALERT: &[u8] = &[21, 3, 3, 0, 2, 2, 70];
+
+type SuccessfulTlsFallbackServer = (String, HttpClient, mpsc::Receiver<io::Result<Vec<String>>>);
+
+#[tokio::test]
+async fn default_pool_does_not_retry_a_native_tls_protocol_failure() {
+    let (url, attempts, stop_server) =
+        spawn_protocol_version_rejection_server(/*maximum_attempts*/ 2)
+            .expect("TLS rejection server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    );
+    let request = reqwest::Request::new(
+        Method::POST,
+        reqwest::Url::parse(&url).expect("valid HTTPS URL"),
+    );
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("ordinary traffic should preserve the native TLS failure");
+
+    let _ = stop_server.send(());
+    assert!(error.is_connect());
+    assert_eq!(
+        attempts
+            .recv()
+            .expect("TLS server should finish")
+            .expect("TLS server should reject one connection"),
+        1
+    );
+}
+
+#[tokio::test]
+async fn retries_a_native_tls_protocol_failure_once_with_rustls() {
+    let (url, attempts, stop_server) =
+        spawn_protocol_version_rejection_server(/*maximum_attempts*/ 2)
+            .expect("TLS rejection server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let destination = reqwest::Url::parse(&url).expect("valid HTTPS URL");
+    let mut request = reqwest::Request::new(Method::POST, destination.clone());
+    *request.body_mut() = Some(Bytes::from_static(b"mcp-initialize").into());
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("both TLS handshakes should be rejected");
+
+    let _ = stop_server.send(());
+    assert!(error.is_connect());
+    assert_eq!(
+        attempts
+            .recv()
+            .expect("TLS server should finish")
+            .expect("TLS server should reject both connections"),
+        2,
+        "native TLS protocol failure should retry with rustls: {error:?}"
+    );
+    let rustls_clients = pool.rustls_clients.as_ref().expect("TLS fallback cache");
+    assert_eq!(
+        (
+            rustls_clients.requires_rustls(&destination, &OutboundProxyRoute::Direct),
+            rustls_clients
+                .client_for_route(&OutboundProxyRoute::Direct)
+                .is_some(),
+        ),
+        (false, false)
+    );
+}
+
+#[tokio::test]
+async fn retries_a_native_tls_failure_after_another_request_caches_rustls() {
+    let (url, attempts, stop_server) =
+        spawn_protocol_version_rejection_server(/*maximum_attempts*/ 2)
+            .expect("TLS rejection server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let destination = reqwest::Url::parse(&url).expect("valid HTTPS URL");
+    let (route, native_client, selected_tls_backend) = pool
+        .client_for_url_with_resolver(destination.as_str(), |_| async {
+            Ok(OutboundProxyRoute::Direct)
+        })
+        .await
+        .expect("native TLS client should resolve");
+    assert_eq!(selected_tls_backend, SelectedTlsBackend::TransportDefault);
+
+    let request = reqwest::Request::new(Method::POST, destination.clone());
+    let replay = request.try_clone().expect("request should be replayable");
+    let error = native_client
+        .execute_without_request_logging(request)
+        .await
+        .expect_err("native TLS handshake should fail");
+    let rustls_client = pool
+        .rustls_client_for_route(&route)
+        .expect("rustls fallback client should build");
+    pool.rustls_clients
+        .as_ref()
+        .expect("TLS fallback cache")
+        .remember(&destination, &route, rustls_client);
+
+    let error = pool
+        .retry_with_rustls(
+            &destination,
+            &route,
+            selected_tls_backend,
+            Some(&replay),
+            error,
+            /*timeout_deadline*/ None,
+        )
+        .await
+        .expect_err("both TLS handshakes should be rejected");
+
+    let _ = stop_server.send(());
+    assert!(error.is_connect());
+    assert_eq!(
+        attempts
+            .recv()
+            .expect("TLS server should finish")
+            .expect("TLS server should reject both connections"),
+        2,
+        "an in-flight native TLS failure should retry despite a concurrent cache update"
+    );
+}
+
+#[tokio::test]
+async fn does_not_retry_a_cached_rustls_tls_protocol_failure() {
+    let (url, attempts, stop_server) =
+        spawn_protocol_version_rejection_server(/*maximum_attempts*/ 2)
+            .expect("TLS rejection server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let destination = reqwest::Url::parse(&url).expect("valid HTTPS URL");
+    let rustls_client = pool
+        .rustls_client_for_route(&OutboundProxyRoute::Direct)
+        .expect("rustls fallback client should build");
+    pool.rustls_clients
+        .as_ref()
+        .expect("TLS fallback cache")
+        .remember(&destination, &OutboundProxyRoute::Direct, rustls_client);
+    let request = reqwest::Request::new(Method::POST, destination);
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("cached rustls TLS handshake should fail");
+
+    let _ = stop_server.send(());
+    assert!(error.is_connect());
+    assert_eq!(
+        attempts
+            .recv()
+            .expect("TLS server should finish")
+            .expect("TLS server should reject one connection"),
+        1,
+        "a cached rustls client must not retry against itself"
+    );
+}
+
+#[tokio::test]
+async fn successful_rustls_fallback_replays_the_request_and_reuses_the_destination() {
+    let (url, trusted_rustls_client, observed_requests) =
+        spawn_successful_tls_fallback_server().expect("TLS fallback server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let destination = reqwest::Url::parse(&url).expect("valid HTTPS URL");
+    let existing_destination =
+        reqwest::Url::parse("https://another-mcp.example.com/mcp").expect("valid HTTPS URL");
+    let rustls_clients = pool.rustls_clients.as_ref().expect("TLS fallback cache");
+
+    // Another destination may already have established a trusted rustls client on this route.
+    // The test destination must still attempt native TLS before reusing that route-level client.
+    rustls_clients.remember(
+        &existing_destination,
+        &OutboundProxyRoute::Direct,
+        trusted_rustls_client,
+    );
+    assert!(!rustls_clients.requires_rustls(&destination, &OutboundProxyRoute::Direct));
+
+    let mut initialize_request = reqwest::Request::new(Method::POST, destination.clone());
+    *initialize_request.body_mut() = Some(Bytes::from_static(b"mcp-initialize").into());
+    let initialize_response = pool
+        .send_with_resolver(initialize_request, |_| async {
+            Ok(OutboundProxyRoute::Direct)
+        })
+        .await
+        .expect("native TLS protocol failure should recover with rustls");
+
+    assert_eq!(
+        initialize_response
+            .text()
+            .await
+            .expect("fallback response body should be readable"),
+        "ok"
+    );
+    assert!(rustls_clients.requires_rustls(&destination, &OutboundProxyRoute::Direct));
+
+    let mut tool_request = reqwest::Request::new(Method::POST, destination);
+    *tool_request.body_mut() = Some(Bytes::from_static(b"mcp-tool-call").into());
+    let tool_response = pool
+        .send_with_resolver(tool_request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect("remembered destination should reuse rustls without another native TLS attempt");
+
+    assert_eq!(
+        tool_response
+            .text()
+            .await
+            .expect("cached rustls response body should be readable"),
+        "ok"
+    );
+    assert_eq!(
+        observed_requests
+            .recv_timeout(Duration::from_secs(5))
+            .expect("TLS fallback server should finish")
+            .expect("TLS fallback server should capture both requests"),
+        vec!["mcp-initialize".to_string(), "mcp-tool-call".to_string()]
+    );
+}
+
+#[tokio::test]
+async fn retries_a_tls_protocol_failure_when_request_url_contains_certificate_markers() {
+    let (url, attempts, stop_server) =
+        spawn_protocol_version_rejection_server(/*maximum_attempts*/ 2)
+            .expect("TLS rejection server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let mut destination = reqwest::Url::parse(&url).expect("valid HTTPS URL");
+    destination.set_path("/certificate/hostname/expired/revoked/mcp");
+    let request = reqwest::Request::new(Method::POST, destination);
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("both TLS handshakes should be rejected");
+
+    let _ = stop_server.send(());
+    assert!(error.is_connect());
+    assert_eq!(
+        attempts
+            .recv()
+            .expect("TLS server should finish")
+            .expect("TLS server should reject both connections"),
+        2,
+        "request URL text should not prevent TLS backend fallback: {error:?}"
+    );
+}
+
+#[tokio::test]
+async fn does_not_retry_a_non_replayable_streaming_request() {
+    let (url, attempts, stop_server) =
+        spawn_protocol_version_rejection_server(/*maximum_attempts*/ 2)
+            .expect("TLS rejection server should start");
+    let pool = RouteAwareClientPool::new(
+        HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),
+        ClientRouteClass::Other,
+    )
+    .with_tls_backend_fallback();
+    let mut request = reqwest::Request::new(
+        Method::POST,
+        reqwest::Url::parse(&url).expect("valid HTTPS URL"),
+    );
+    *request.body_mut() = Some(reqwest::Body::wrap_stream(stream::iter(vec![Ok::<
+        _,
+        io::Error,
+    >(
+        Bytes::from_static(b"streaming body"),
+    )])));
+
+    let error = pool
+        .send_with_resolver(request, |_| async { Ok(OutboundProxyRoute::Direct) })
+        .await
+        .expect_err("non-replayable request should preserve the native TLS failure");
+
+    let _ = stop_server.send(());
+    assert!(error.is_connect());
+    let RouteAwareRequestError::Request(ref request_error) = error else {
+        panic!("expected native TLS request error, got {error:?}");
+    };
+    assert!(
+        should_retry_with_rustls(request_error),
+        "native TLS protocol failure should be retryable: {request_error:?}"
+    );
+    assert_eq!(
+        attempts
+            .recv()
+            .expect("TLS server should finish")
+            .expect("TLS server should reject one connection"),
+        1
+    );
+}
+
+fn spawn_successful_tls_fallback_server() -> io::Result<SuccessfulTlsFallbackServer> {
+    codex_utils_rustls_provider::ensure_rustls_crypto_provider();
+    let CertifiedKey { cert, signing_key } =
+        generate_simple_self_signed(vec!["127.0.0.1".to_string()]).map_err(io::Error::other)?;
+    let certificate = cert.der().clone();
+    let private_key = PrivateKeyDer::from(signing_key);
+    let tls_config = Arc::new(
+        rustls::ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![certificate.clone()], private_key)
+            .map_err(io::Error::other)?,
+    );
+    let trusted_rustls_client = HttpClient::new(
+        reqwest::Client::builder()
+            .use_rustls_tls()
+            .add_root_certificate(
+                reqwest::Certificate::from_der(certificate.as_ref()).map_err(io::Error::other)?,
+            )
+            .no_proxy()
+            .redirect(reqwest::redirect::Policy::none())
+            .build()
+            .map_err(io::Error::other)?,
+    );
+
+    let listener = TcpListener::bind(("127.0.0.1", 0))?;
+    let address = listener.local_addr()?;
+    listener.set_nonblocking(true)?;
+    let (requests_tx, requests_rx) = mpsc::channel();
+
+    thread::spawn(move || {
+        let result = (|| -> io::Result<Vec<String>> {
+            let mut observed_requests = Vec::new();
+            for connection_index in 0..3 {
+                let deadline = Instant::now() + Duration::from_secs(5);
+                let mut stream = loop {
+                    match listener.accept() {
+                        Ok((stream, _)) => break stream,
+                        Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                            if Instant::now() >= deadline {
+                                return Err(io::Error::new(
+                                    io::ErrorKind::TimedOut,
+                                    "timed out waiting for the TLS fallback client",
+                                ));
+                            }
+                            thread::sleep(Duration::from_millis(10));
+                        }
+                        Err(error) => return Err(error),
+                    }
+                };
+                stream.set_nonblocking(false)?;
+                stream.set_read_timeout(Some(Duration::from_secs(5)))?;
+                stream.set_write_timeout(Some(Duration::from_secs(5)))?;
+
+                if connection_index == 0 {
+                    let mut client_hello = [0_u8; 2_048];
+                    if stream.read(&mut client_hello)? == 0 {
+                        return Err(io::Error::new(
+                            io::ErrorKind::UnexpectedEof,
+                            "native TLS peer closed before sending a ClientHello",
+                        ));
+                    }
+                    stream.write_all(PROTOCOL_VERSION_TLS_ALERT)?;
+                    stream.flush()?;
+                    continue;
+                }
+
+                let connection = rustls::ServerConnection::new(Arc::clone(&tls_config))
+                    .map_err(io::Error::other)?;
+                let mut tls = rustls::StreamOwned::new(connection, stream);
+                let mut request = Vec::new();
+                let mut chunk = [0_u8; 1_024];
+                let header_end = loop {
+                    let bytes_read = tls.read(&mut chunk)?;
+                    if bytes_read == 0 {
+                        return Err(io::Error::new(
+                            io::ErrorKind::UnexpectedEof,
+                            "rustls peer closed before sending HTTP headers",
+                        ));
+                    }
+                    request.extend_from_slice(&chunk[..bytes_read]);
+                    if let Some(header_end) =
+                        request.windows(4).position(|window| window == b"\r\n\r\n")
+                    {
+                        break header_end + 4;
+                    }
+                };
+                let headers =
+                    std::str::from_utf8(&request[..header_end]).map_err(io::Error::other)?;
+                let content_length = headers
+                    .lines()
+                    .find_map(|line| {
+                        let (name, value) = line.split_once(':')?;
+                        name.eq_ignore_ascii_case("content-length")
+                            .then_some(value.trim())
+                    })
+                    .ok_or_else(|| {
+                        io::Error::new(io::ErrorKind::InvalidData, "missing Content-Length")
+                    })?
+                    .parse::<usize>()
+                    .map_err(io::Error::other)?;
+                while request.len() < header_end + content_length {
+                    let bytes_read = tls.read(&mut chunk)?;
+                    if bytes_read == 0 {
+                        return Err(io::Error::new(
+                            io::ErrorKind::UnexpectedEof,
+                            "rustls peer closed before sending the HTTP body",
+                        ));
+                    }
+                    request.extend_from_slice(&chunk[..bytes_read]);
+                }
+                let body = std::str::from_utf8(&request[header_end..header_end + content_length])
+                    .map_err(io::Error::other)?;
+                observed_requests.push(body.to_string());
+                tls.write_all(
+                    b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok",
+                )?;
+                tls.flush()?;
+            }
+            Ok(observed_requests)
+        })();
+        let _ = requests_tx.send(result);
+    });
+
+    Ok((
+        format!("https://{address}/mcp"),
+        trusted_rustls_client,
+        requests_rx,
+    ))
+}
+
+fn spawn_protocol_version_rejection_server(
+    maximum_attempts: usize,
+) -> io::Result<(String, mpsc::Receiver<io::Result<usize>>, mpsc::Sender<()>)> {
+    let listener = TcpListener::bind(("127.0.0.1", 0))?;
+    let address = listener.local_addr()?;
+    listener.set_nonblocking(true)?;
+    let (attempts_tx, attempts_rx) = mpsc::channel();
+    let (stop_tx, stop_rx) = mpsc::channel();
+
+    thread::spawn(move || {
+        let result = (|| -> io::Result<usize> {
+            let mut attempts = 0;
+            let deadline = Instant::now() + Duration::from_secs(5);
+            while attempts < maximum_attempts && Instant::now() < deadline {
+                if stop_rx.try_recv().is_ok() {
+                    break;
+                }
+                match listener.accept() {
+                    Ok((mut stream, _)) => {
+                        stream.set_nonblocking(false)?;
+                        stream.set_read_timeout(Some(Duration::from_secs(2)))?;
+                        let mut client_hello = [0_u8; 2_048];
+                        if stream.read(&mut client_hello)? == 0 {
+                            return Err(io::Error::new(
+                                io::ErrorKind::UnexpectedEof,
+                                "TLS peer closed before sending a ClientHello",
+                            ));
+                        }
+                        stream.write_all(PROTOCOL_VERSION_TLS_ALERT)?;
+                        attempts += 1;
+                    }
+                    Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                        thread::sleep(Duration::from_millis(10));
+                    }
+                    Err(error) => return Err(error),
+                }
+            }
+            Ok(attempts)
+        })();
+        let _ = attempts_tx.send(result);
+    });
+
+    Ok((format!("https://{address}/mcp"), attempts_rx, stop_tx))
+}
diff --git a/codex-rs/http-client/src/tls_backend_fallback.rs b/codex-rs/http-client/src/tls_backend_fallback.rs
new file mode 100644
index 0000000000000000000000000000000000000000..760df1824ad752fe8d4b5f3f2b0d0e3e848c0144
--- /dev/null
+++ b/codex-rs/http-client/src/tls_backend_fallback.rs
@@ -0,0 +1,156 @@
+//! Narrow TLS backend fallback for delegated requests that select their route per destination.
+//!
+//! Native TLS remains the default. A recognized connection-time protocol negotiation failure can
+//! select rustls for one HTTPS origin and outbound route without changing other destinations.
+
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::error::Error;
+use std::sync::Arc;
+use std::sync::Mutex;
+
+use crate::HttpClient;
+use crate::OutboundProxyRoute;
+
+const MAX_CACHED_RUSTLS_DESTINATIONS: usize = 16;
+// Schannel maps TLS alert 70 (protocol_version) to SEC_E_UNSUPPORTED_FUNCTION.
+const SCHANNEL_PROTOCOL_VERSION_ERROR: i32 = 0x8009_0302_u32 as i32;
+
+#[derive(Clone, Default)]
+pub(crate) struct RustlsClientCache {
+    state: Arc<Mutex<RustlsClientCacheState>>,
+}
+
+#[derive(Default)]
+struct RustlsClientCacheState {
+    destinations: HashSet<DestinationRoute>,
+    clients: HashMap<OutboundProxyRoute, HttpClient>,
+}
+
+#[derive(Clone, Hash, PartialEq, Eq)]
+struct DestinationRoute {
+    host: String,
+    port: u16,
+    route: OutboundProxyRoute,
+}
+
+impl RustlsClientCache {
+    pub(crate) fn requires_rustls(&self, url: &reqwest::Url, route: &OutboundProxyRoute) -> bool {
+        let Some(destination) = DestinationRoute::new(url, route) else {
+            return false;
+        };
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .destinations
+            .contains(&destination)
+    }
+
+    pub(crate) fn client_for_route(&self, route: &OutboundProxyRoute) -> Option<HttpClient> {
+        self.state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clients
+            .get(route)
+            .cloned()
+    }
+
+    pub(crate) fn remember(
+        &self,
+        url: &reqwest::Url,
+        route: &OutboundProxyRoute,
+        client: HttpClient,
+    ) {
+        let Some(destination) = DestinationRoute::new(url, route) else {
+            return;
+        };
+        let mut state = self
+            .state
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        if state.destinations.contains(&destination) {
+            return;
+        }
+        if state.destinations.len() >= MAX_CACHED_RUSTLS_DESTINATIONS
+            && let Some(destination_to_evict) = state.destinations.iter().next().cloned()
+        {
+            state.destinations.remove(&destination_to_evict);
+            if !state
+                .destinations
+                .iter()
+                .any(|destination| destination.route == destination_to_evict.route)
+            {
+                state.clients.remove(&destination_to_evict.route);
+            }
+        }
+        state.clients.entry(route.clone()).or_insert(client);
+        state.destinations.insert(destination);
+    }
+}
+
+impl DestinationRoute {
+    fn new(url: &reqwest::Url, route: &OutboundProxyRoute) -> Option<Self> {
+        if url.scheme() != "https" {
+            return None;
+        }
+        Some(Self {
+            host: url.host_str()?.to_ascii_lowercase(),
+            port: url.port_or_known_default()?,
+            route: route.clone(),
+        })
+    }
+}
+
+pub(crate) fn should_retry_with_rustls(error: &reqwest::Error) -> bool {
+    error.is_connect() && !error.is_timeout() && error.source().is_some_and(has_retryable_tls_error)
+}
+
+fn has_retryable_tls_error(error: &(dyn Error + 'static)) -> bool {
+    let mut source = Some(error);
+    let mut recognized_negotiation_failure = false;
+
+    while let Some(error) = source {
+        let message = error.to_string().to_ascii_lowercase();
+        if [
+            "certificate",
+            "unknown issuer",
+            "unknown ca",
+            "untrusted",
+            "self signed",
+            "self-signed",
+            "hostname",
+            "expired",
+            "revoked",
+        ]
+        .iter()
+        .any(|marker| message.contains(marker))
+        {
+            return false;
+        }
+
+        // macOS Secure Transport reports the protocol alert as "bad protocol version".
+        let is_macos_protocol_version_error = message.contains("bad protocol version");
+        // Linux OpenSSL reports the peer's "tlsv1 alert protocol version".
+        let is_linux_protocol_version_error = message.contains("tlsv1 alert protocol version");
+        // Windows Schannel may expose the protocol alert as a raw or formatted OS error.
+        let is_schannel_protocol_version_error = error
+            .downcast_ref::<std::io::Error>()
+            .and_then(std::io::Error::raw_os_error)
+            == Some(SCHANNEL_PROTOCOL_VERSION_ERROR)
+            || message.contains("(os error -2146893054)")
+            || message.contains("0x80090302");
+        if is_macos_protocol_version_error
+            || is_linux_protocol_version_error
+            || is_schannel_protocol_version_error
+        {
+            recognized_negotiation_failure = true;
+        }
+        source = error.source();
+    }
+
+    recognized_negotiation_failure
+}
+
+#[cfg(test)]
+#[path = "tls_backend_fallback_tests.rs"]
+mod tests;
diff --git a/codex-rs/http-client/src/tls_backend_fallback_tests.rs b/codex-rs/http-client/src/tls_backend_fallback_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c7ca0adceb94a6729d8657c7a7feb4e066044f68
--- /dev/null
+++ b/codex-rs/http-client/src/tls_backend_fallback_tests.rs
@@ -0,0 +1,216 @@
+use std::io;
+
+use pretty_assertions::assert_eq;
+
+use super::MAX_CACHED_RUSTLS_DESTINATIONS;
+use super::RustlsClientCache;
+use super::SCHANNEL_PROTOCOL_VERSION_ERROR;
+use super::has_retryable_tls_error;
+use crate::HttpClientBuilder;
+use crate::OutboundProxyRoute;
+
+#[test]
+fn recognizes_platform_specific_tls_protocol_negotiation_failures() {
+    let errors = [
+        ("client error (Connect): bad protocol version", true),
+        ("BAD PROTOCOL VERSION", true),
+        (
+            "error:0A00042E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version",
+            true,
+        ),
+        ("TLSV1 ALERT PROTOCOL VERSION", true),
+        (
+            "The function requested is not supported. (os error -2146893054)",
+            true,
+        ),
+        ("Schannel protocol error 0x80090302", true),
+        ("SCHANNEL PROTOCOL ERROR 0X80090302", true),
+        ("certificate validation failed: bad protocol version", false),
+        ("bad protocol version: certificate has expired", false),
+        (
+            "certificate validation failed: tlsv1 alert protocol version",
+            false,
+        ),
+        (
+            "tlsv1 alert protocol version: certificate has expired",
+            false,
+        ),
+        (
+            "certificate validation failed (os error -2146893054)",
+            false,
+        ),
+        ("certificate validation failed: 0x80090302", false),
+        ("unknown issuer", false),
+        ("self-signed certificate", false),
+        ("hostname mismatch", false),
+        ("connection refused", false),
+        ("connection reset", false),
+        ("dns lookup failed", false),
+        ("tls handshake failed", false),
+        ("unsupported protocol", false),
+        ("wrong version number", false),
+        ("The function requested is not supported.", false),
+        (
+            "The client and server cannot communicate. (os error -2146893007)",
+            false,
+        ),
+        ("operation timed out", false),
+        ("407 Proxy Authentication Required", false),
+    ];
+
+    for (message, expected) in errors {
+        let error = io::Error::other(message);
+        assert_eq!(has_retryable_tls_error(&error), expected, "{message}");
+    }
+}
+
+#[test]
+fn recognizes_schannel_protocol_version_error_codes() {
+    let protocol_error = io::Error::from_raw_os_error(SCHANNEL_PROTOCOL_VERSION_ERROR);
+    let another_schannel_error = io::Error::from_raw_os_error(/*code*/ -2_146_893_007);
+
+    assert_eq!(
+        (
+            has_retryable_tls_error(&protocol_error),
+            has_retryable_tls_error(&another_schannel_error),
+        ),
+        (true, false)
+    );
+}
+
+#[test]
+fn certificate_errors_in_an_error_source_never_enable_fallback() {
+    for message in [
+        "certificate verification failed: bad protocol version",
+        "certificate verification failed: tlsv1 alert protocol version",
+        "certificate verification failed (os error -2146893054)",
+        "certificate verification failed: 0x80090302",
+    ] {
+        let error = io::Error::other(io::Error::other(message));
+
+        assert!(!has_retryable_tls_error(&error), "{message}");
+    }
+}
+
+#[test]
+fn rustls_fallback_decisions_are_scoped_to_origin_and_outbound_route() {
+    let cache = RustlsClientCache::default();
+    let destination = reqwest::Url::parse("https://mcp.example.com/first").expect("valid URL");
+    let same_origin = reqwest::Url::parse("https://mcp.example.com/second").expect("valid URL");
+    let another_host = reqwest::Url::parse("https://another.example.com/first").expect("valid URL");
+    let another_port =
+        reqwest::Url::parse("https://mcp.example.com:8443/first").expect("valid URL");
+    let insecure = reqwest::Url::parse("http://mcp.example.com/first").expect("valid URL");
+    let direct = OutboundProxyRoute::Direct;
+    let proxy = OutboundProxyRoute::Proxy {
+        url: "http://proxy.example.com".to_string(),
+        no_proxy: None,
+    };
+
+    let client = HttpClientBuilder::new()
+        .with_rustls_tls()
+        .build_direct()
+        .expect("rustls client should build without proxy autodiscovery");
+    cache.remember(&destination, &direct, client);
+
+    assert_eq!(
+        [
+            cache.requires_rustls(&destination, &direct),
+            cache.requires_rustls(&same_origin, &direct),
+            cache.requires_rustls(&another_host, &direct),
+            cache.requires_rustls(&another_port, &direct),
+            cache.requires_rustls(&destination, &proxy),
+            cache.requires_rustls(&insecure, &direct),
+        ],
+        [true, true, false, false, false, false]
+    );
+}
+
+#[test]
+fn cached_rustls_clients_are_reused_for_the_same_outbound_route() {
+    let cache = RustlsClientCache::default();
+    let first_destination =
+        reqwest::Url::parse("https://first.example.com").expect("valid first URL");
+    let second_destination =
+        reqwest::Url::parse("https://second.example.com").expect("valid second URL");
+    let direct = OutboundProxyRoute::Direct;
+    let client = HttpClientBuilder::new()
+        .with_rustls_tls()
+        .build_direct()
+        .expect("rustls client should build without proxy autodiscovery");
+
+    cache.remember(&first_destination, &direct, client.clone());
+    cache.remember(&second_destination, &direct, client);
+
+    assert_eq!(
+        (
+            cache.requires_rustls(&first_destination, &direct),
+            cache.requires_rustls(&second_destination, &direct),
+            cache.client_for_route(&direct).is_some(),
+            cache
+                .state
+                .lock()
+                .expect("rustls client cache lock")
+                .clients
+                .len(),
+        ),
+        (true, true, true, 1)
+    );
+}
+
+#[test]
+fn cached_rustls_destinations_remain_bounded_while_sharing_a_route_client() {
+    let cache = RustlsClientCache::default();
+    let client = HttpClientBuilder::new()
+        .with_rustls_tls()
+        .build_direct()
+        .expect("rustls client should build without proxy autodiscovery");
+
+    for index in 0..=MAX_CACHED_RUSTLS_DESTINATIONS {
+        let destination =
+            reqwest::Url::parse(&format!("https://mcp-{index}.example.com")).expect("valid URL");
+        cache.remember(&destination, &OutboundProxyRoute::Direct, client.clone());
+    }
+
+    let state = cache.state.lock().expect("rustls client cache lock");
+    assert_eq!(
+        (state.destinations.len(), state.clients.len()),
+        (MAX_CACHED_RUSTLS_DESTINATIONS, 1)
+    );
+}
+
+#[test]
+fn evicting_a_destination_removes_its_unshared_route_client() {
+    let cache = RustlsClientCache::default();
+    let client = HttpClientBuilder::new()
+        .with_rustls_tls()
+        .build_direct()
+        .expect("rustls client should build without proxy autodiscovery");
+
+    for index in 0..=MAX_CACHED_RUSTLS_DESTINATIONS {
+        let destination =
+            reqwest::Url::parse(&format!("https://mcp-{index}.example.com")).expect("valid URL");
+        let route = OutboundProxyRoute::Proxy {
+            url: format!("http://proxy-{index}.example.com"),
+            no_proxy: None,
+        };
+        cache.remember(&destination, &route, client.clone());
+    }
+
+    let state = cache.state.lock().expect("rustls client cache lock");
+    assert_eq!(
+        (
+            state.destinations.len(),
+            state.clients.len(),
+            state
+                .destinations
+                .iter()
+                .all(|destination| state.clients.contains_key(&destination.route)),
+        ),
+        (
+            MAX_CACHED_RUSTLS_DESTINATIONS,
+            MAX_CACHED_RUSTLS_DESTINATIONS,
+            true,
+        )
+    );
+}
diff --git a/codex-rs/http-client/src/transport.rs b/codex-rs/http-client/src/transport.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ca351c1f0030cbe384fcb2a6eebce5819f3a51c2
--- /dev/null
+++ b/codex-rs/http-client/src/transport.rs
@@ -0,0 +1,252 @@
+//! Shared HTTP transport with optional limits on complete response bodies.
+//!
+//! Each request's limit applies to observed body bytes, including unsuccessful responses;
+//! declared content lengths are only an additional early-rejection check.
+
+use crate::client::HttpClient;
+use crate::client::RequestBuilder;
+use crate::error::TransportError;
+use crate::request::Request;
+use crate::request::RequestBody;
+use crate::request::Response;
+use bytes::Bytes;
+use bytes::BytesMut;
+use futures::StreamExt;
+use futures::stream::BoxStream;
+use http::HeaderMap;
+use http::Method;
+use http::StatusCode;
+use tracing::Level;
+use tracing::enabled;
+use tracing::trace;
+
+pub type ByteStream = BoxStream<'static, Result<Bytes, TransportError>>;
+
+pub struct StreamResponse {
+    pub status: StatusCode,
+    pub headers: HeaderMap,
+    pub bytes: ByteStream,
+}
+
+pub trait HttpTransport: Send + Sync {
+    fn execute(
+        &self,
+        req: Request,
+    ) -> impl std::future::Future<Output = Result<Response, TransportError>> + Send;
+    fn stream(
+        &self,
+        req: Request,
+    ) -> impl std::future::Future<Output = Result<StreamResponse, TransportError>> + Send;
+}
+
+#[derive(Clone, Debug)]
+pub struct ReqwestTransport {
+    client: HttpClient,
+}
+
+impl ReqwestTransport {
+    pub fn new(client: reqwest::Client) -> Self {
+        Self {
+            client: HttpClient::new(client),
+        }
+    }
+
+    pub fn from_http_client(client: HttpClient) -> Self {
+        Self { client }
+    }
+
+    fn build(&self, req: Request) -> Result<RequestBuilder, TransportError> {
+        let prepared = req.prepare_body_for_send().map_err(TransportError::Build)?;
+
+        let Request {
+            method,
+            url,
+            headers: _,
+            body: _,
+            compression: _,
+            timeout,
+            response_body_limit_bytes: _,
+        } = req;
+
+        let mut builder = self.client.request(
+            Method::from_bytes(method.as_str().as_bytes()).unwrap_or(Method::GET),
+            &url,
+        );
+
+        if let Some(timeout) = timeout {
+            builder = builder.timeout(timeout);
+        }
+
+        builder = builder.headers(prepared.headers);
+        if let Some(body) = prepared.body {
+            builder = builder.body(body);
+        }
+        Ok(builder)
+    }
+
+    fn map_error(err: reqwest::Error) -> TransportError {
+        if err.is_connect() {
+            TransportError::Connection(err.without_url())
+        } else if err.is_timeout() {
+            TransportError::Timeout
+        } else {
+            TransportError::Network(err.to_string())
+        }
+    }
+
+    fn trace_request(&self, req: &Request) {
+        if self.client.request_logging_enabled() && enabled!(Level::TRACE) {
+            trace!(
+                "{} to {}: {}",
+                req.method,
+                req.url,
+                request_body_for_trace(req)
+            );
+        }
+    }
+}
+
+fn request_body_for_trace(req: &Request) -> String {
+    match req.body.as_ref() {
+        Some(RequestBody::Json(body)) => body.to_string(),
+        Some(RequestBody::EncodedJson(body)) => {
+            String::from_utf8_lossy(body.trace_bytes()).into_owned()
+        }
+        Some(RequestBody::Raw(body)) => format!("<raw body: {} bytes>", body.len()),
+        None => String::new(),
+    }
+}
+
+impl HttpTransport for ReqwestTransport {
+    async fn execute(&self, req: Request) -> Result<Response, TransportError> {
+        self.trace_request(&req);
+
+        let url = req.url.clone();
+        let response_body_limit_bytes = req.response_body_limit_bytes;
+        let builder = self.build(req)?;
+        let resp = builder.send().await.map_err(Self::map_error)?;
+        let status = resp.status();
+        let headers = resp.headers().clone();
+        let bytes = match response_body_limit_bytes {
+            Some(max_bytes) => bounded_response_bytes(resp, max_bytes).await,
+            None => resp.bytes().await.map_err(Self::map_error),
+        };
+        if !status.is_success() {
+            let body = match bytes {
+                Ok(bytes) => String::from_utf8(bytes.to_vec()).ok(),
+                Err(error @ TransportError::ResponseTooLarge { .. }) => return Err(error),
+                // Keep bounded diagnostic-body failures from hiding HTTP auth/retry status.
+                Err(_) if response_body_limit_bytes.is_some() => None,
+                Err(error) => return Err(error),
+            };
+            return Err(TransportError::Http {
+                status,
+                url: Some(url),
+                headers: Some(headers),
+                body,
+            });
+        }
+        Ok(Response {
+            status,
+            headers,
+            body: bytes?,
+        })
+    }
+
+    async fn stream(&self, req: Request) -> Result<StreamResponse, TransportError> {
+        self.trace_request(&req);
+
+        let url = req.url.clone();
+        let response_body_limit_bytes = req.response_body_limit_bytes;
+        let builder = self.build(req)?;
+        let resp = builder.send().await.map_err(Self::map_error)?;
+        let status = resp.status();
+        let headers = resp.headers().clone();
+        if !status.is_success() {
+            let body = match response_body_limit_bytes {
+                Some(max_bytes) => match bounded_response_bytes(resp, max_bytes).await {
+                    Ok(bytes) => {
+                        // Reuse the unbounded path's charset, BOM and replacement decoding,
+                        // but only after the body has passed the byte limit.
+                        let mut buffered = http::Response::new(bytes);
+                        *buffered.headers_mut() = headers.clone();
+                        reqwest::Response::from(buffered).text().await.ok()
+                    }
+                    Err(error @ TransportError::ResponseTooLarge { .. }) => return Err(error),
+                    // A failed diagnostic body must not hide HTTP auth or retry semantics.
+                    Err(_) => None,
+                },
+                None => resp.text().await.ok(),
+            };
+            return Err(TransportError::Http {
+                status,
+                url: Some(url),
+                headers: Some(headers),
+                body,
+            });
+        }
+        let bytes = match response_body_limit_bytes {
+            Some(max_bytes) => bounded_response_stream(resp, max_bytes)?,
+            None => Box::pin(
+                resp.bytes_stream()
+                    .map(|result| result.map_err(Self::map_error)),
+            ),
+        };
+        Ok(StreamResponse {
+            status,
+            headers,
+            bytes,
+        })
+    }
+}
+
+fn bounded_response_stream(
+    response: reqwest::Response,
+    max_bytes: usize,
+) -> Result<ByteStream, TransportError> {
+    if response
+        .content_length()
+        .is_some_and(|length| length > max_bytes as u64)
+    {
+        return Err(TransportError::ResponseTooLarge { max_bytes });
+    }
+
+    let stream = futures::stream::try_unfold(
+        (response, max_bytes),
+        move |(mut response, remaining)| async move {
+            match response
+                .chunk()
+                .await
+                .map_err(|error| ReqwestTransport::map_error(error.without_url()))?
+            {
+                Some(chunk) if chunk.len() <= remaining => {
+                    let remaining = remaining - chunk.len();
+                    Ok(Some((chunk, (response, remaining))))
+                }
+                Some(_) => Err(TransportError::ResponseTooLarge { max_bytes }),
+                None => Ok(None),
+            }
+        },
+    );
+    Ok(Box::pin(stream))
+}
+
+async fn bounded_response_bytes(
+    response: reqwest::Response,
+    max_bytes: usize,
+) -> Result<Bytes, TransportError> {
+    let mut stream = bounded_response_stream(response, max_bytes)?;
+    let mut body = BytesMut::new();
+    while let Some(chunk) = stream.next().await {
+        body.extend_from_slice(&chunk?);
+    }
+    Ok(body.freeze())
+}
+
+#[cfg(test)]
+#[path = "transport_tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "transport_limit_tests.rs"]
+mod limit_tests;
diff --git a/codex-rs/http-client/src/transport_limit_tests.rs b/codex-rs/http-client/src/transport_limit_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1c977854a1af6483328251f7805ee69f646e0ccd
--- /dev/null
+++ b/codex-rs/http-client/src/transport_limit_tests.rs
@@ -0,0 +1,452 @@
+//! HTTP fixtures exercise opt-in body limits for both buffered and streaming callers.
+
+use super::*;
+use pretty_assertions::assert_eq;
+use std::io::Read;
+use std::io::Write;
+use std::net::TcpListener;
+use std::net::TcpStream;
+use std::time::Duration;
+use std::time::Instant;
+
+#[derive(Clone, Copy, Debug)]
+enum Delivery {
+    Buffered,
+    Streamed,
+}
+
+#[tokio::test]
+async fn accepts_complete_bodies_at_the_limit() {
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        for (framing, wire_body, max_bytes, expected_body) in [
+            ("Content-Length: 4\r\n", "test", 4, "test"),
+            ("", "test", 4, "test"),
+            (
+                "Transfer-Encoding: chunked\r\n",
+                "2\r\nte\r\n2\r\nst\r\n0\r\n\r\n",
+                4,
+                "test",
+            ),
+            ("Content-Length: 0\r\n", "", 0, ""),
+        ] {
+            let response = receive_response(
+                format!("HTTP/1.1 200 OK\r\n{framing}Connection: close\r\n\r\n{wire_body}"),
+                &transport(),
+                Some(max_bytes),
+                delivery,
+            )
+            .await
+            .expect("a complete body within the limit should succeed");
+            let mut expected_headers = HeaderMap::new();
+            expected_headers.insert("connection", "close".parse().unwrap());
+            for line in framing.lines() {
+                let (name, value) = line.split_once(':').unwrap();
+                expected_headers.insert(
+                    http::HeaderName::from_bytes(name.as_bytes()).unwrap(),
+                    value.trim().parse().unwrap(),
+                );
+            }
+            assert_eq!(
+                (response.status, response.headers, response.body),
+                (
+                    StatusCode::OK,
+                    expected_headers,
+                    Bytes::copy_from_slice(expected_body.as_bytes()),
+                ),
+                "{delivery:?} with framing {framing:?}",
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn rejects_oversized_success_and_error_bodies_without_sensitive_diagnostics() {
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        for status in ["200 OK", "500 Internal Server Error"] {
+            for (framing, wire_body) in [
+                ("Content-Length: 11\r\n", "body-secret"),
+                ("", "body-secret"),
+                (
+                    "Transfer-Encoding: chunked\r\n",
+                    "4\r\nbody\r\n7\r\n-secret\r\n0\r\n\r\n",
+                ),
+                (
+                    "Transfer-Encoding: chunked\r\nContent-Length: 1\r\n",
+                    "4\r\nbody\r\n7\r\n-secret\r\n0\r\n\r\n",
+                ),
+            ] {
+                let error = receive_response(
+                    format!(
+                        "HTTP/1.1 {status}\r\n{framing}X-Secret: header-secret\r\nConnection: close\r\n\r\n{wire_body}"
+                    ),
+                    &transport(),
+                    Some(4),
+                    delivery,
+                )
+                .await
+                .expect_err("the observed body must not exceed the limit");
+                assert_eq!(
+                    (error.to_string(), format!("{error:?}")),
+                    (
+                        "response body exceeds the 4 byte limit".to_string(),
+                        "ResponseTooLarge { max_bytes: 4 }".to_string(),
+                    ),
+                    "{delivery:?}, {status}, framing {framing:?}",
+                );
+            }
+        }
+    }
+}
+
+#[tokio::test]
+async fn rejects_oversized_declared_lengths_before_reading_the_body() {
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        for status in [
+            StatusCode::OK,
+            StatusCode::UNAUTHORIZED,
+            StatusCode::TOO_MANY_REQUESTS,
+        ] {
+            let error = receive_response(
+                format!(
+                    "HTTP/1.1 {status}\r\nContent-Length: 1000000\r\nConnection: close\r\n\r\n"
+                ),
+                &transport(),
+                Some(4),
+                delivery,
+            )
+            .await
+            .expect_err("an oversized declaration should fail before the incomplete body");
+            assert!(matches!(
+                error,
+                TransportError::ResponseTooLarge { max_bytes: 4 }
+            ));
+        }
+    }
+}
+
+#[tokio::test]
+async fn streaming_limit_counts_across_chunks_and_terminates_on_error() {
+    let (continue_tx, continue_rx) = std::sync::mpsc::channel();
+    let (url, server) = start_server(move |connection| {
+        connection
+            .write_all(b"HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n4\r\npart\r\n")
+            .expect("write the first chunk");
+        continue_rx
+            .recv_timeout(Duration::from_secs(5))
+            .expect("client should consume the first chunk");
+        connection
+            .write_all(b"4\r\nnext\r\n0\r\n\r\n")
+            .expect("write the second chunk");
+    });
+    let mut request = Request::new(Method::GET, url);
+    request.response_body_limit_bytes = Some(6);
+    let mut response = transport()
+        .stream(request)
+        .await
+        .expect("stream should open before the body limit is reached");
+    assert_eq!(
+        response.bytes.next().await.unwrap().unwrap(),
+        Bytes::from_static(b"part"),
+    );
+    continue_tx.send(()).expect("release the second chunk");
+    let error = response
+        .bytes
+        .next()
+        .await
+        .expect("second chunk should produce the limit error")
+        .expect_err("two individually small chunks should exceed the total limit");
+    assert!(matches!(
+        error,
+        TransportError::ResponseTooLarge { max_bytes: 6 }
+    ));
+    assert!(response.bytes.next().await.is_none());
+    server.join().expect("HTTP fixture should finish");
+}
+
+#[tokio::test]
+async fn preserves_http_failures_within_the_limit() {
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        let error = receive_response(
+            "HTTP/1.1 403 Forbidden\r\nContent-Length: 6\r\nConnection: close\r\n\r\ndenied"
+                .to_string(),
+            &transport(),
+            Some(6),
+            delivery,
+        )
+        .await
+        .expect_err("a small error body should retain HTTP error semantics");
+        let TransportError::Http {
+            status,
+            headers,
+            body,
+            ..
+        } = error
+        else {
+            panic!("expected HTTP error, got {error:?}");
+        };
+        assert_eq!(
+            (status, headers, body),
+            (
+                StatusCode::FORBIDDEN,
+                Some(HeaderMap::from_iter([
+                    (http::header::CONTENT_LENGTH, "6".parse().unwrap()),
+                    (http::header::CONNECTION, "close".parse().unwrap()),
+                ])),
+                Some("denied".to_string()),
+            ),
+        );
+    }
+}
+
+#[tokio::test]
+async fn bounded_errors_preserve_status_when_the_body_is_interrupted() {
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        for status in [StatusCode::UNAUTHORIZED, StatusCode::TOO_MANY_REQUESTS] {
+            for max_bytes in [None, Some(5), Some(4), Some(3)] {
+                // The first chunk is complete, but the peer closes before the next chunk.
+                let error = receive_response(
+                    format!(
+                        "HTTP/1.1 {status}\r\nTransfer-Encoding: chunked\r\nRetry-After: 7\r\nWWW-Authenticate: Bearer\r\nConnection: close\r\n\r\n4\r\npart\r\n"
+                    ),
+                    &transport(),
+                    max_bytes,
+                    delivery,
+                )
+                .await
+                .expect_err("an interrupted error body must still fail");
+                if matches!(delivery, Delivery::Buffered) && max_bytes.is_none() {
+                    assert!(matches!(error, TransportError::Network(_)));
+                    continue;
+                }
+                if max_bytes == Some(3) {
+                    assert!(matches!(
+                        error,
+                        TransportError::ResponseTooLarge { max_bytes: 3 }
+                    ));
+                    continue;
+                }
+                let TransportError::Http {
+                    status: actual_status,
+                    headers,
+                    body,
+                    ..
+                } = error
+                else {
+                    panic!("expected preserved HTTP error, got {error:?}");
+                };
+                assert_eq!(
+                    (actual_status, headers, body),
+                    (
+                        status,
+                        Some(HeaderMap::from_iter([
+                            (http::header::TRANSFER_ENCODING, "chunked".parse().unwrap()),
+                            (http::header::RETRY_AFTER, "7".parse().unwrap()),
+                            (http::header::WWW_AUTHENTICATE, "Bearer".parse().unwrap()),
+                            (http::header::CONNECTION, "close".parse().unwrap()),
+                        ])),
+                        None,
+                    ),
+                    "{delivery:?}, max_bytes={max_bytes:?}",
+                );
+            }
+        }
+    }
+}
+
+#[tokio::test]
+async fn bounded_successes_report_interrupted_bodies_as_network_errors() {
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        let error = receive_response(
+            "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\nConnection: close\r\n\r\n4\r\npart\r\n"
+                .to_string(),
+            &transport(),
+            Some(4),
+            delivery,
+        )
+        .await
+        .expect_err("a successful status cannot hide an incomplete response body");
+        assert!(matches!(error, TransportError::Network(_)));
+    }
+}
+
+#[tokio::test]
+async fn bounded_streamed_errors_preserve_text_decoding() {
+    for (content_type, bytes, expected) in [
+        (
+            "text/plain; charset=windows-1252",
+            [0x63, 0x61, 0x66, 0xe9].as_slice(),
+            "café",
+        ),
+        (
+            "text/plain; charset=utf-8",
+            b"error: \xff".as_slice(),
+            "error: �",
+        ),
+        (
+            "text/plain; charset=unknown",
+            b"error: \xff".as_slice(),
+            "error: �",
+        ),
+        ("text/plain", b"\xef\xbb\xbfdenied".as_slice(), "denied"),
+    ] {
+        for bounded in [false, true] {
+            let mut wire = format!(
+                "HTTP/1.1 403 Forbidden\r\nContent-Type: {content_type}\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+                bytes.len()
+            )
+            .into_bytes();
+            wire.extend_from_slice(bytes);
+            let error = receive_response(
+                wire,
+                &transport(),
+                bounded.then_some(bytes.len()),
+                Delivery::Streamed,
+            )
+            .await
+            .expect_err("retain the HTTP error and decoded diagnostics");
+            let TransportError::Http {
+                status,
+                headers,
+                body,
+                ..
+            } = error
+            else {
+                panic!("expected HTTP error, got {error:?}");
+            };
+            assert_eq!(
+                (status, headers, body),
+                (
+                    StatusCode::FORBIDDEN,
+                    Some(HeaderMap::from_iter([
+                        (http::header::CONTENT_TYPE, content_type.parse().unwrap()),
+                        (
+                            http::header::CONTENT_LENGTH,
+                            bytes.len().to_string().parse().unwrap()
+                        ),
+                        (http::header::CONNECTION, "close".parse().unwrap()),
+                    ])),
+                    Some(expected.to_string()),
+                ),
+                "{content_type}, bounded={bounded}",
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn shared_transport_keeps_each_requests_response_limit_independent() {
+    let transport = transport();
+    for delivery in [Delivery::Buffered, Delivery::Streamed] {
+        for max_bytes in [Some(4), None, Some(11), Some(0), None] {
+            let response = receive_response(
+                "HTTP/1.1 200 OK\r\nContent-Length: 11\r\nConnection: close\r\n\r\nbody-secret"
+                    .to_string(),
+                &transport,
+                max_bytes,
+                delivery,
+            )
+            .await;
+            match max_bytes {
+                Some(max_bytes) if max_bytes < 11 => assert!(matches!(
+                    response,
+                    Err(TransportError::ResponseTooLarge { max_bytes: actual }) if actual == max_bytes
+                )),
+                _ => assert_eq!(
+                    response.expect("only this request's limit applies").body,
+                    Bytes::from_static(b"body-secret"),
+                ),
+            }
+        }
+    }
+}
+
+fn transport() -> ReqwestTransport {
+    ReqwestTransport::new(
+        reqwest::Client::builder()
+            .no_proxy()
+            .build()
+            .expect("test client should build"),
+    )
+}
+
+async fn receive_response(
+    wire_response: impl Into<Vec<u8>>,
+    transport: &ReqwestTransport,
+    response_body_limit_bytes: Option<usize>,
+    delivery: Delivery,
+) -> Result<Response, TransportError> {
+    let wire_response = wire_response.into();
+    let (url, server) = start_server(move |connection| {
+        connection
+            .write_all(&wire_response)
+            .expect("write HTTP response");
+    });
+    let mut request = Request::new(Method::GET, url);
+    request.headers.insert(
+        http::header::AUTHORIZATION,
+        "Bearer auth-secret".parse().unwrap(),
+    );
+    request.timeout = Some(Duration::from_secs(5));
+    request.response_body_limit_bytes = response_body_limit_bytes;
+    let result = match delivery {
+        Delivery::Buffered => transport.execute(request).await,
+        Delivery::Streamed => {
+            async {
+                let mut response = transport.stream(request).await?;
+                let mut body = BytesMut::new();
+                while let Some(chunk) = response.bytes.next().await {
+                    body.extend_from_slice(&chunk?);
+                }
+                Ok(Response {
+                    status: response.status,
+                    headers: response.headers,
+                    body: body.freeze(),
+                })
+            }
+            .await
+        }
+    };
+    server.join().expect("HTTP fixture should finish");
+    result
+}
+
+fn start_server(
+    respond: impl FnOnce(&mut TcpStream) + Send + 'static,
+) -> (String, std::thread::JoinHandle<()>) {
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("HTTP fixture should bind");
+    let address = listener.local_addr().expect("HTTP fixture address");
+    listener
+        .set_nonblocking(true)
+        .expect("nonblocking listener");
+    let server = std::thread::spawn(move || {
+        let deadline = Instant::now() + Duration::from_secs(5);
+        let (mut connection, _) = loop {
+            match listener.accept() {
+                Ok(connection) => break connection,
+                Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                    assert!(Instant::now() < deadline, "HTTP fixture accept timed out");
+                    std::thread::sleep(Duration::from_millis(1));
+                }
+                Err(error) => panic!("HTTP fixture should accept: {error}"),
+            }
+        };
+        connection
+            .set_nonblocking(false)
+            .expect("HTTP fixture connection should use blocking reads");
+        connection
+            .set_read_timeout(Some(Duration::from_secs(5)))
+            .expect("HTTP fixture read timeout");
+        let mut request = Vec::new();
+        let mut buffer = [0; 1024];
+        while !request.windows(4).any(|window| window == b"\r\n\r\n") {
+            let count = connection.read(&mut buffer).expect("read HTTP request");
+            assert_ne!(count, 0, "HTTP request should contain complete headers");
+            request.extend_from_slice(&buffer[..count]);
+        }
+        respond(&mut connection);
+    });
+    (
+        format!("http://{address}/models?credential=url-secret"),
+        server,
+    )
+}
diff --git a/codex-rs/http-client/src/transport_tests.rs b/codex-rs/http-client/src/transport_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a8ab11aba5cfe6830daaf1dd00a7db698fe73f4e
--- /dev/null
+++ b/codex-rs/http-client/src/transport_tests.rs
@@ -0,0 +1,114 @@
+use super::*;
+use serde_json::json;
+use std::io::Write;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::time::Duration;
+use tracing_subscriber::Layer;
+use tracing_subscriber::layer::SubscriberExt;
+
+#[tokio::test]
+async fn enabled_request_logging_emits_transport_url_and_body() {
+    let logs = capture_transport_logs(HttpClient::new(test_reqwest_client())).await;
+
+    assert!(logs.contains("log capture sentinel"));
+    assert!(logs.contains("url-secret"));
+    assert!(logs.contains("body-secret"));
+}
+
+#[tokio::test]
+async fn disabled_request_logging_suppresses_transport_url_and_body() {
+    let logs = capture_transport_logs(HttpClient::new_without_request_logging(
+        test_reqwest_client(),
+    ))
+    .await;
+
+    assert!(logs.contains("log capture sentinel"));
+    assert!(!logs.contains("url-secret"));
+    assert!(!logs.contains("body-secret"));
+}
+
+#[tokio::test]
+async fn connection_failures_are_classified_without_exposing_request_urls() {
+    let unavailable_server =
+        std::net::TcpListener::bind(("127.0.0.1", 0)).expect("server port should bind");
+    let server_addr = unavailable_server
+        .local_addr()
+        .expect("server listener should have an address");
+    drop(unavailable_server);
+    let transport = ReqwestTransport::from_http_client(HttpClient::new(test_reqwest_client()));
+    let request = Request::new(
+        Method::POST,
+        format!("http://{server_addr}/responses?token=url-secret"),
+    );
+
+    let error = match transport.stream(request).await {
+        Err(TransportError::Connection(error)) => error,
+        Err(error) => panic!("expected a connection failure, got {error}"),
+        Ok(_) => panic!("an unavailable server should not return a response"),
+    };
+    assert!(!error.to_string().contains("url-secret"));
+}
+
+fn test_reqwest_client() -> reqwest::Client {
+    reqwest::Client::builder()
+        .no_proxy()
+        .build()
+        .expect("HTTP client should build")
+}
+
+async fn capture_transport_logs(client: HttpClient) -> String {
+    let unavailable_server =
+        std::net::TcpListener::bind(("127.0.0.1", 0)).expect("server port should bind");
+    let server_addr = unavailable_server
+        .local_addr()
+        .expect("server listener should have an address");
+    drop(unavailable_server);
+    let transport = ReqwestTransport::from_http_client(client);
+    let log_buffer = Arc::new(Mutex::new(Vec::new()));
+    let writer_buffer = Arc::clone(&log_buffer);
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .with_ansi(false)
+            .with_writer(move || TestLogWriter(Arc::clone(&writer_buffer)))
+            .with_filter(
+                tracing_subscriber::filter::Targets::new()
+                    .with_target("codex_http_client::transport", tracing::Level::TRACE),
+            ),
+    );
+    let _guard = tracing::subscriber::set_default(subscriber);
+    tracing::trace!(target: "codex_http_client::transport", "log capture sentinel");
+    let mut request = Request::new(
+        Method::POST,
+        format!("http://{server_addr}/request?token=url-secret"),
+    )
+    .with_json(&json!({"token": "body-secret"}));
+    request.timeout = Some(Duration::from_secs(1));
+
+    let _ = transport.execute(request).await;
+
+    String::from_utf8(
+        log_buffer
+            .lock()
+            .expect("log buffer should not be poisoned")
+            .clone(),
+    )
+    .expect("captured logs should be UTF-8")
+}
+
+#[derive(Clone)]
+struct TestLogWriter(Arc<Mutex<Vec<u8>>>);
+
+impl Write for TestLogWriter {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        self.0
+            .lock()
+            .map_err(|_| std::io::Error::other("log buffer should not be poisoned"))?
+            .extend_from_slice(buf);
+        Ok(buf.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        Ok(())
+    }
+}
diff --git a/codex-rs/http-client/src/windows_tls.rs b/codex-rs/http-client/src/windows_tls.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5b42b37fc31a4b5fb604d866e93200b19d1dd5b3
--- /dev/null
+++ b/codex-rs/http-client/src/windows_tls.rs
@@ -0,0 +1,22 @@
+//! Windows certificate validation for callers without a custom CA bundle.
+//!
+//! Unlike a snapshot of installed roots, Windows can retrieve missing trusted roots on demand.
+//! Callers must retain the custom-CA configuration path when a bundle is configured.
+
+use std::sync::Arc;
+
+use codex_utils_rustls_provider::ensure_rustls_crypto_provider;
+use rustls::ClientConfig;
+use rustls_platform_verifier::ConfigVerifierExt;
+
+/// Builds a TLS configuration that validates server certificates using Windows trust policy.
+///
+/// This does not load Codex custom CA settings; callers must check those before selecting it.
+pub fn build_windows_platform_tls_config() -> Result<Arc<ClientConfig>, rustls::Error> {
+    ensure_rustls_crypto_provider();
+    ClientConfig::with_platform_verifier().map(Arc::new)
+}
+
+#[cfg(test)]
+#[path = "windows_tls_tests.rs"]
+mod tests;
diff --git a/codex-rs/http-client/src/windows_tls_tests.rs b/codex-rs/http-client/src/windows_tls_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6ddf3b50f754a3c2ffa61a906600472daf2cc1f9
--- /dev/null
+++ b/codex-rs/http-client/src/windows_tls_tests.rs
@@ -0,0 +1,58 @@
+//! Certificate rejection coverage for Windows platform TLS.
+
+use super::build_windows_platform_tls_config;
+use std::sync::Arc;
+
+#[test]
+fn platform_tls_rejects_a_self_signed_server() {
+    let client_config =
+        build_windows_platform_tls_config().expect("configure platform verification");
+    let certified_key = rcgen::generate_simple_self_signed(vec!["localhost".to_string()])
+        .expect("generate untrusted certificate");
+    let server_config = rustls::ServerConfig::builder()
+        .with_no_client_auth()
+        .with_single_cert(
+            vec![certified_key.cert.der().clone()],
+            certified_key.signing_key.into(),
+        )
+        .expect("configure test server");
+    let mut client = rustls::ClientConnection::new(
+        client_config,
+        "localhost".try_into().expect("valid server name"),
+    )
+    .expect("create client");
+    let mut server = rustls::ServerConnection::new(Arc::new(server_config)).expect("create server");
+
+    // Drive the real handshake without opening ports or changing system trust.
+    for _ in 0..10 {
+        let mut outbound = Vec::new();
+        client
+            .write_tls(&mut outbound)
+            .expect("write client records");
+        server
+            .read_tls(&mut outbound.as_slice())
+            .expect("read client records");
+        server
+            .process_new_packets()
+            .expect("process client records");
+        outbound.clear();
+        server
+            .write_tls(&mut outbound)
+            .expect("write server records");
+        client
+            .read_tls(&mut outbound.as_slice())
+            .expect("read server records");
+        if let Err(error) = client.process_new_packets() {
+            assert!(
+                matches!(error, rustls::Error::InvalidCertificate(_)),
+                "{error:?}"
+            );
+            return;
+        }
+        assert!(
+            client.is_handshaking(),
+            "untrusted server must not complete TLS"
+        );
+    }
+    panic!("expected certificate rejection during handshake");
+}
diff --git a/codex-rs/http-client/tests/ca_env.rs b/codex-rs/http-client/tests/ca_env.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f35225fee778e80858daca7e5c9791ee0ec3d3ed
--- /dev/null
+++ b/codex-rs/http-client/tests/ca_env.rs
@@ -0,0 +1,540 @@
+#![allow(clippy::expect_used)]
+//! Subprocess coverage for custom CA behavior that must build a real reqwest client.
+//!
+//! These tests intentionally run through `custom_ca_probe` and
+//! `build_reqwest_client_for_subprocess_tests` instead of calling the helper in-process. The
+//! detailed explanation of what "hermetic" means here lives in `codex_http_client::custom_ca`; these
+//! tests add the process-level half of that contract by scrubbing inherited CA environment
+//! variables before each subprocess launch. Most assertions here cover CA file selection, PEM
+//! parsing, and user-facing errors. The HTTPS probes go further and perform real POSTs against
+//! locally generated certificates, including through a TLS-intercepting CONNECT proxy.
+
+use codex_utils_cargo_bin::cargo_bin;
+use rcgen::BasicConstraints;
+use rcgen::CertificateParams;
+use rcgen::CertifiedIssuer;
+use rcgen::DistinguishedName;
+use rcgen::DnType;
+use rcgen::ExtendedKeyUsagePurpose;
+use rcgen::IsCa;
+use rcgen::KeyPair;
+use rcgen::KeyUsagePurpose;
+use rcgen::PKCS_ECDSA_P256_SHA256;
+use rustls_pki_types::CertificateDer;
+use rustls_pki_types::PrivateKeyDer;
+use std::fs;
+use std::io;
+use std::io::Read;
+use std::io::Write;
+use std::net::TcpListener;
+use std::net::TcpStream;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command;
+use std::sync::Arc;
+use std::sync::mpsc;
+use std::thread;
+use std::time::Duration;
+use std::time::Instant;
+use tempfile::TempDir;
+
+const CODEX_CA_CERT_ENV: &str = "CODEX_CA_CERTIFICATE";
+const PROBE_PROXY_ENV: &str = "CODEX_CUSTOM_CA_PROBE_PROXY";
+const PROBE_TLS13_ENV: &str = "CODEX_CUSTOM_CA_PROBE_TLS13";
+const PROBE_URL_ENV: &str = "CODEX_CUSTOM_CA_PROBE_URL";
+const SSL_CERT_FILE_ENV: &str = "SSL_CERT_FILE";
+const PROXY_ENV_VARS: &[&str] = &[
+    "HTTP_PROXY",
+    "http_proxy",
+    "HTTPS_PROXY",
+    "https_proxy",
+    "ALL_PROXY",
+    "all_proxy",
+    "NO_PROXY",
+    "no_proxy",
+];
+
+const TEST_CERT_1: &str = include_str!("fixtures/test-ca.pem");
+const TEST_CERT_2: &str = include_str!("fixtures/test-intermediate.pem");
+const TRUSTED_TEST_CERT: &str = include_str!("fixtures/test-ca-trusted.pem");
+
+struct Tls13Material {
+    ca_cert_pem: String,
+    server_cert: CertificateDer<'static>,
+    server_key: PrivateKeyDer<'static>,
+}
+
+struct Tls13TestServer {
+    ca_cert_pem: String,
+    request_rx: mpsc::Receiver<Result<String, String>>,
+    url: String,
+}
+
+struct PlainHttpOrigin {
+    request_rx: mpsc::Receiver<Result<String, String>>,
+    url: String,
+}
+
+struct TlsInterceptingProxy {
+    ca_cert_pem: String,
+    request_rx: mpsc::Receiver<Result<String, String>>,
+    url: String,
+}
+
+fn write_cert_file(temp_dir: &TempDir, name: &str, contents: &str) -> PathBuf {
+    let path = temp_dir.path().join(name);
+    fs::write(&path, contents).expect("certificate fixture should be writable");
+    path
+}
+
+fn probe_command() -> Command {
+    let mut cmd = Command::new(
+        cargo_bin("custom_ca_probe").expect("custom_ca_probe binary should be available"),
+    );
+    // `Command` inherits the parent environment by default, so scrub CA-related variables first or
+    // these tests can accidentally pass/fail based on the developer shell or CI runner.
+    cmd.env_remove(CODEX_CA_CERT_ENV);
+    cmd.env_remove(PROBE_PROXY_ENV);
+    cmd.env_remove(PROBE_TLS13_ENV);
+    cmd.env_remove(PROBE_URL_ENV);
+    cmd.env_remove(SSL_CERT_FILE_ENV);
+    for env_var in PROXY_ENV_VARS {
+        cmd.env_remove(env_var);
+    }
+    cmd
+}
+
+fn run_probe(envs: &[(&str, &Path)]) -> std::process::Output {
+    let mut cmd = probe_command();
+    for (key, value) in envs {
+        cmd.env(key, value);
+    }
+    cmd.output().expect("custom_ca_probe should run")
+}
+
+fn run_probe_posting_to_tls13_server(envs: &[(&str, &Path)], url: &str) -> std::process::Output {
+    let mut cmd = probe_command();
+    for (key, value) in envs {
+        cmd.env(key, value);
+    }
+    cmd.env(PROBE_TLS13_ENV, "1");
+    cmd.env(PROBE_URL_ENV, url);
+    cmd.output().expect("custom_ca_probe should run")
+}
+
+fn run_probe_posting_through_tls_intercepting_proxy(
+    envs: &[(&str, &Path)],
+    url: &str,
+    proxy_url: &str,
+) -> std::process::Output {
+    let mut cmd = probe_command();
+    for (key, value) in envs {
+        cmd.env(key, value);
+    }
+    cmd.env(PROBE_PROXY_ENV, proxy_url);
+    cmd.env(PROBE_TLS13_ENV, "1");
+    cmd.env(PROBE_URL_ENV, url);
+    cmd.output().expect("custom_ca_probe should run")
+}
+
+fn spawn_tls13_test_server() -> Tls13TestServer {
+    codex_utils_rustls_provider::ensure_rustls_crypto_provider();
+    let material = generate_tls13_material();
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("TLS test server should bind");
+    listener
+        .set_nonblocking(true)
+        .expect("TLS test server should become nonblocking");
+    let port = listener
+        .local_addr()
+        .expect("TLS test server should have a local address")
+        .port();
+    let config = Arc::new(
+        rustls::ServerConfig::builder_with_protocol_versions(&[&rustls::version::TLS13])
+            .with_no_client_auth()
+            .with_single_cert(vec![material.server_cert], material.server_key)
+            .expect("TLS 1.3 server config should be valid"),
+    );
+    let (request_tx, request_rx) = mpsc::channel();
+
+    thread::spawn(move || {
+        let result = accept_tls13_request(listener, config);
+        let _ = request_tx.send(result.map_err(|error| error.to_string()));
+    });
+
+    Tls13TestServer {
+        ca_cert_pem: material.ca_cert_pem,
+        request_rx,
+        url: format!("https://127.0.0.1:{port}/oauth/token"),
+    }
+}
+
+fn spawn_plain_http_origin() -> PlainHttpOrigin {
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("plain HTTP origin should bind");
+    listener
+        .set_nonblocking(true)
+        .expect("plain HTTP origin should become nonblocking");
+    let port = listener
+        .local_addr()
+        .expect("plain HTTP origin should have a local address")
+        .port();
+    let (request_tx, request_rx) = mpsc::channel();
+
+    thread::spawn(move || {
+        let result = accept_plain_http_origin_request(listener);
+        let _ = request_tx.send(result.map_err(|error| error.to_string()));
+    });
+
+    PlainHttpOrigin {
+        request_rx,
+        url: format!("https://127.0.0.1:{port}/oauth/token"),
+    }
+}
+
+fn spawn_tls_intercepting_proxy() -> TlsInterceptingProxy {
+    codex_utils_rustls_provider::ensure_rustls_crypto_provider();
+    let material = generate_tls13_material();
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("TLS intercepting proxy should bind");
+    listener
+        .set_nonblocking(true)
+        .expect("TLS intercepting proxy should become nonblocking");
+    let port = listener
+        .local_addr()
+        .expect("TLS intercepting proxy should have a local address")
+        .port();
+    let config = Arc::new(
+        rustls::ServerConfig::builder_with_protocol_versions(&[&rustls::version::TLS13])
+            .with_no_client_auth()
+            .with_single_cert(vec![material.server_cert], material.server_key)
+            .expect("TLS intercepting proxy config should be valid"),
+    );
+    let (request_tx, request_rx) = mpsc::channel();
+
+    thread::spawn(move || {
+        let result = accept_tls_intercepting_proxy_request(listener, config);
+        let _ = request_tx.send(result.map_err(|error| error.to_string()));
+    });
+
+    TlsInterceptingProxy {
+        ca_cert_pem: material.ca_cert_pem,
+        request_rx,
+        url: format!("http://127.0.0.1:{port}"),
+    }
+}
+
+fn generate_tls13_material() -> Tls13Material {
+    let mut ca_params = CertificateParams::default();
+    ca_params.is_ca = IsCa::Ca(BasicConstraints::Unconstrained);
+    ca_params.key_usages = vec![KeyUsagePurpose::KeyCertSign, KeyUsagePurpose::CrlSign];
+    let mut ca_distinguished_name = DistinguishedName::new();
+    ca_distinguished_name.push(DnType::CommonName, "codex test CA");
+    ca_params.distinguished_name = ca_distinguished_name;
+    let ca_key_pair =
+        KeyPair::generate_for(&PKCS_ECDSA_P256_SHA256).expect("test CA key pair should generate");
+    let ca = CertifiedIssuer::self_signed(ca_params, ca_key_pair)
+        .expect("test CA certificate should generate");
+
+    let mut server_params =
+        CertificateParams::new(vec!["localhost".to_string(), "127.0.0.1".to_string()])
+            .expect("test server certificate params should be valid");
+    server_params.extended_key_usages = vec![ExtendedKeyUsagePurpose::ServerAuth];
+    server_params.key_usages = vec![
+        KeyUsagePurpose::DigitalSignature,
+        KeyUsagePurpose::KeyEncipherment,
+    ];
+    let server_key_pair = KeyPair::generate_for(&PKCS_ECDSA_P256_SHA256)
+        .expect("test server key pair should generate");
+    let server_cert = server_params
+        .signed_by(&server_key_pair, &ca)
+        .expect("test server certificate should generate");
+
+    Tls13Material {
+        ca_cert_pem: ca.pem(),
+        server_cert: server_cert.der().clone(),
+        server_key: PrivateKeyDer::from(server_key_pair),
+    }
+}
+
+fn accept_plain_http_origin_request(listener: TcpListener) -> io::Result<String> {
+    let mut stream = accept_with_timeout(listener, Duration::from_secs(5))?;
+    stream.set_nonblocking(false)?;
+    stream.set_read_timeout(Some(Duration::from_secs(5)))?;
+    stream.set_write_timeout(Some(Duration::from_secs(5)))?;
+
+    let request = read_http_message(&mut stream)?;
+    stream.write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok")?;
+    stream.flush()?;
+    Ok(request)
+}
+
+fn accept_tls13_request(
+    listener: TcpListener,
+    config: Arc<rustls::ServerConfig>,
+) -> io::Result<String> {
+    let stream = accept_with_timeout(listener, Duration::from_secs(5))?;
+    stream.set_nonblocking(false)?;
+    stream.set_read_timeout(Some(Duration::from_secs(5)))?;
+    stream.set_write_timeout(Some(Duration::from_secs(5)))?;
+
+    let connection = rustls::ServerConnection::new(config).map_err(io::Error::other)?;
+    let mut tls = rustls::StreamOwned::new(connection, stream);
+    let request = read_http_message(&mut tls)?;
+    tls.write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok")?;
+    tls.flush()?;
+    Ok(request)
+}
+
+fn accept_tls_intercepting_proxy_request(
+    listener: TcpListener,
+    config: Arc<rustls::ServerConfig>,
+) -> io::Result<String> {
+    let mut stream = accept_with_timeout(listener, Duration::from_secs(5))?;
+    stream.set_nonblocking(false)?;
+    stream.set_read_timeout(Some(Duration::from_secs(5)))?;
+    stream.set_write_timeout(Some(Duration::from_secs(5)))?;
+
+    let connect_request = read_http_message(&mut stream)?;
+    let origin_authority = connect_authority_from_request(&connect_request)?;
+    stream.write_all(b"HTTP/1.1 200 Connection Established\r\n\r\n")?;
+    stream.flush()?;
+
+    let connection = rustls::ServerConnection::new(config).map_err(io::Error::other)?;
+    let mut tls = rustls::StreamOwned::new(connection, stream);
+    let request = read_http_message(&mut tls)?;
+
+    let mut origin = TcpStream::connect(origin_authority.as_str())?;
+    origin.set_read_timeout(Some(Duration::from_secs(5)))?;
+    origin.set_write_timeout(Some(Duration::from_secs(5)))?;
+    origin.write_all(request.as_bytes())?;
+    origin.flush()?;
+    let response = read_http_message(&mut origin)?;
+
+    tls.write_all(response.as_bytes())?;
+    tls.flush()?;
+    Ok(request)
+}
+
+fn connect_authority_from_request(request: &str) -> io::Result<String> {
+    let request_line = request
+        .lines()
+        .next()
+        .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "empty CONNECT request"))?;
+    let mut parts = request_line.split_whitespace();
+    match (parts.next(), parts.next(), parts.next()) {
+        (Some("CONNECT"), Some(authority), Some(_version)) => Ok(authority.to_string()),
+        _ => Err(io::Error::new(
+            io::ErrorKind::InvalidData,
+            format!("invalid CONNECT request line: {request_line}"),
+        )),
+    }
+}
+
+fn accept_with_timeout(listener: TcpListener, timeout: Duration) -> io::Result<TcpStream> {
+    let deadline = Instant::now() + timeout;
+    loop {
+        match listener.accept() {
+            Ok((stream, _)) => return Ok(stream),
+            Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
+                if Instant::now() >= deadline {
+                    return Err(io::Error::new(
+                        io::ErrorKind::TimedOut,
+                        "timed out waiting for TLS test client",
+                    ));
+                }
+                thread::sleep(Duration::from_millis(10));
+            }
+            Err(error) => return Err(error),
+        }
+    }
+}
+
+fn read_http_message(stream: &mut impl Read) -> io::Result<String> {
+    let mut buffer = Vec::new();
+    let mut chunk = [0; 1024];
+    loop {
+        let bytes_read = stream.read(&mut chunk)?;
+        if bytes_read == 0 {
+            break;
+        }
+        buffer.extend_from_slice(&chunk[..bytes_read]);
+        if let Some(header_end) = buffer.windows(4).position(|window| window == b"\r\n\r\n") {
+            let body_start = header_end + 4;
+            let headers = String::from_utf8_lossy(&buffer[..body_start]);
+            let content_length = headers
+                .lines()
+                .filter_map(|line| line.split_once(':'))
+                .find_map(|(name, value)| {
+                    name.eq_ignore_ascii_case("content-length")
+                        .then(|| value.trim().parse::<usize>().ok())
+                        .flatten()
+                })
+                .unwrap_or(0);
+            if buffer.len() >= body_start + content_length {
+                break;
+            }
+        }
+    }
+    Ok(String::from_utf8_lossy(&buffer).into_owned())
+}
+
+fn assert_token_exchange_request(request: &str) {
+    assert!(
+        request.starts_with("POST /oauth/token HTTP/1.1"),
+        "unexpected request:\n{request}"
+    );
+    assert!(
+        request.contains("grant_type=authorization_code&code=test"),
+        "unexpected request body:\n{request}"
+    );
+}
+
+#[test]
+fn uses_codex_ca_cert_env() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let cert_path = write_cert_file(&temp_dir, "ca.pem", TEST_CERT_1);
+
+    let output = run_probe(&[(CODEX_CA_CERT_ENV, cert_path.as_path())]);
+
+    assert!(output.status.success());
+}
+
+#[test]
+fn falls_back_to_ssl_cert_file() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let cert_path = write_cert_file(&temp_dir, "ssl.pem", TEST_CERT_1);
+
+    let output = run_probe(&[(SSL_CERT_FILE_ENV, cert_path.as_path())]);
+
+    assert!(output.status.success());
+}
+
+#[test]
+fn prefers_codex_ca_cert_over_ssl_cert_file() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let cert_path = write_cert_file(&temp_dir, "ca.pem", TEST_CERT_1);
+    let bad_path = write_cert_file(&temp_dir, "bad.pem", "");
+
+    let output = run_probe(&[
+        (CODEX_CA_CERT_ENV, cert_path.as_path()),
+        (SSL_CERT_FILE_ENV, bad_path.as_path()),
+    ]);
+
+    assert!(output.status.success());
+}
+
+#[test]
+fn handles_multi_certificate_bundle() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let bundle = format!("{TEST_CERT_1}\n{TEST_CERT_2}");
+    let cert_path = write_cert_file(&temp_dir, "bundle.pem", &bundle);
+
+    let output = run_probe(&[(CODEX_CA_CERT_ENV, cert_path.as_path())]);
+
+    assert!(output.status.success());
+}
+
+#[test]
+fn posts_to_tls13_server_using_custom_ca_bundle() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let server = spawn_tls13_test_server();
+    let cert_path = write_cert_file(&temp_dir, "tls-ca.pem", &server.ca_cert_pem);
+
+    let output =
+        run_probe_posting_to_tls13_server(&[(CODEX_CA_CERT_ENV, cert_path.as_path())], &server.url);
+    let server_result = server.request_rx.recv_timeout(Duration::from_secs(5));
+
+    assert!(
+        output.status.success(),
+        "custom_ca_probe failed\nstdout:\n{}\nstderr:\n{}\nserver:\n{server_result:?}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let request = server_result
+        .expect("TLS test server should report a request")
+        .expect("TLS test server should accept the probe request");
+    assert_token_exchange_request(&request);
+}
+
+#[test]
+fn posts_to_token_origin_through_tls_intercepting_proxy_with_custom_ca_bundle() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let origin = spawn_plain_http_origin();
+    let proxy = spawn_tls_intercepting_proxy();
+    let cert_path = write_cert_file(&temp_dir, "proxy-ca.pem", &proxy.ca_cert_pem);
+
+    let output = run_probe_posting_through_tls_intercepting_proxy(
+        &[(CODEX_CA_CERT_ENV, cert_path.as_path())],
+        &origin.url,
+        &proxy.url,
+    );
+    let proxy_result = proxy.request_rx.recv_timeout(Duration::from_secs(5));
+    let origin_result = origin.request_rx.recv_timeout(Duration::from_secs(5));
+
+    assert!(
+        output.status.success(),
+        "custom_ca_probe failed\nstdout:\n{}\nstderr:\n{}\nproxy:\n{proxy_result:?}\norigin:\n{origin_result:?}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let proxy_request = proxy_result
+        .expect("TLS intercepting proxy should report a request")
+        .expect("TLS intercepting proxy should accept the probe request");
+    let origin_request = origin_result
+        .expect("plain HTTP origin should report a request")
+        .expect("plain HTTP origin should accept the forwarded request");
+    assert_token_exchange_request(&proxy_request);
+    assert_token_exchange_request(&origin_request);
+}
+
+#[test]
+fn rejects_empty_pem_file_with_hint() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let cert_path = write_cert_file(&temp_dir, "empty.pem", "");
+
+    let output = run_probe(&[(CODEX_CA_CERT_ENV, cert_path.as_path())]);
+
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("no certificates found in PEM file"));
+    assert!(stderr.contains("CODEX_CA_CERTIFICATE"));
+    assert!(stderr.contains("SSL_CERT_FILE"));
+}
+
+#[test]
+fn rejects_malformed_pem_with_hint() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let cert_path = write_cert_file(
+        &temp_dir,
+        "malformed.pem",
+        "-----BEGIN CERTIFICATE-----\nMIIBroken",
+    );
+
+    let output = run_probe(&[(CODEX_CA_CERT_ENV, cert_path.as_path())]);
+
+    assert!(!output.status.success());
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(stderr.contains("failed to parse PEM file"));
+    assert!(stderr.contains("CODEX_CA_CERTIFICATE"));
+    assert!(stderr.contains("SSL_CERT_FILE"));
+}
+
+#[test]
+fn accepts_openssl_trusted_certificate() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let cert_path = write_cert_file(&temp_dir, "trusted.pem", TRUSTED_TEST_CERT);
+
+    let output = run_probe(&[(CODEX_CA_CERT_ENV, cert_path.as_path())]);
+
+    assert!(output.status.success());
+}
+
+#[test]
+fn accepts_bundle_with_crl() {
+    let temp_dir = TempDir::new().expect("tempdir");
+    let crl = "-----BEGIN X509 CRL-----\nMIIC\n-----END X509 CRL-----";
+    let bundle = format!("{TEST_CERT_1}\n{crl}");
+    let cert_path = write_cert_file(&temp_dir, "bundle_crl.pem", &bundle);
+
+    let output = run_probe(&[(CODEX_CA_CERT_ENV, cert_path.as_path())]);
+
+    assert!(output.status.success());
+}
diff --git a/codex-rs/http-client/tests/fixtures/test-ca-trusted.pem b/codex-rs/http-client/tests/fixtures/test-ca-trusted.pem
new file mode 100644
index 0000000000000000000000000000000000000000..0b394ce84fea4d169172ba669f322d521f8a9773
--- /dev/null
+++ b/codex-rs/http-client/tests/fixtures/test-ca-trusted.pem
@@ -0,0 +1,25 @@
+# Test-only OpenSSL trusted-certificate fixture generated from test-ca.pem with
+# `openssl x509 -addtrust serverAuth -trustout`.
+# The extra trailing bytes model the OpenSSL X509_AUX data that follows the
+# certificate DER in real TRUSTED CERTIFICATE bundles.
+# This fixture exists to validate the X509_AUX trimming path against a real
+# OpenSSL-generated artifact, not just label normalization.
+-----BEGIN TRUSTED CERTIFICATE-----
+MIIDBTCCAe2gAwIBAgIUZYhGvBUG7SucNzYh9VIeZ7b9zHowDQYJKoZIhvcNAQEL
+BQAwEjEQMA4GA1UEAwwHdGVzdC1jYTAeFw0yNTEyMTEyMzEyNTFaFw0zNTEyMDky
+MzEyNTFaMBIxEDAOBgNVBAMMB3Rlc3QtY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IB
+DwAwggEKAoIBAQC+NJRZAdn15FFBN8eR1HTAe+LMVpO19kKtiCsQjyqHONfhfHcF
+7zQfwmH6MqeNpC/5k5m8V1uSIhyHBskQm83Jv8/vHlffNxE/hl0Na/Yd1bc+2kxH
+twIAsF32GKnSKnFva/iGczV81+/ETgG6RXfTfy/Xs6fXL8On8SRRmTcMw0bEfwko
+ziid87VOHg2JfdRKN5QpS9lvQ8q4q2M3jMftolpUTpwlR0u8j9OXnZfn+ja33X0l
+kjkoCbXE2fVbAzO/jhUHQX1H5RbTGGUnrrCWAj84Rq/E80KK1nrRF91K+vgZmilM
+gOZosLMMI1PeqTakwg1yIRngpTyk0eJP+haxAgMBAAGjUzBRMB0GA1UdDgQWBBT6
+sqvfjMIl0DFZkeu8LU577YqMVDAfBgNVHSMEGDAWgBT6sqvfjMIl0DFZkeu8LU57
+7YqMVDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBQ1sYs2RvB
+TZ+xSBglLwH/S7zXVJIDwQ23Rlj11dgnVvcilSJCX24Rr+pfIVLpYNDdZzc/DIJd
+S1dt2JuLnvXnle29rU7cxuzYUkUkRtaeY2Sj210vsE3lqUFyIy8XCc/lteb+FiJ7
+zo/gPk7P+y4ihK9Mm6SBqkDVEYSFSn9bgoemK+0e93jGe2182PyuTwfTmZgENSBO
+2f9dSuay4C7e5UO8bhVccQJg6f4d70zUNG0oPHrnVxJLjwCd++jx25Gh4U7+ek13
+CW57pxJrpPMDWb2YK64rT2juHMKF73YuplW92SInd+QLpI2ekTLc+bRw8JvqzXg+
+SprtRUBjlWzjMAwwCgYIKwYBBQUHAwE=
+-----END TRUSTED CERTIFICATE-----
diff --git a/codex-rs/http-client/tests/fixtures/test-ca.pem b/codex-rs/http-client/tests/fixtures/test-ca.pem
new file mode 100644
index 0000000000000000000000000000000000000000..7c9a9883c81bcd16fc27fa9df9aad3a65d8396fa
--- /dev/null
+++ b/codex-rs/http-client/tests/fixtures/test-ca.pem
@@ -0,0 +1,21 @@
+# Test-only self-signed CA fixture used for single-certificate loading.
+# These tests only verify PEM parsing and root-certificate registration, not a TLS handshake.
+-----BEGIN CERTIFICATE-----
+MIIDBTCCAe2gAwIBAgIUZYhGvBUG7SucNzYh9VIeZ7b9zHowDQYJKoZIhvcNAQEL
+BQAwEjEQMA4GA1UEAwwHdGVzdC1jYTAeFw0yNTEyMTEyMzEyNTFaFw0zNTEyMDky
+MzEyNTFaMBIxEDAOBgNVBAMMB3Rlc3QtY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IB
+DwAwggEKAoIBAQC+NJRZAdn15FFBN8eR1HTAe+LMVpO19kKtiCsQjyqHONfhfHcF
+7zQfwmH6MqeNpC/5k5m8V1uSIhyHBskQm83Jv8/vHlffNxE/hl0Na/Yd1bc+2kxH
+twIAsF32GKnSKnFva/iGczV81+/ETgG6RXfTfy/Xs6fXL8On8SRRmTcMw0bEfwko
+ziid87VOHg2JfdRKN5QpS9lvQ8q4q2M3jMftolpUTpwlR0u8j9OXnZfn+ja33X0l
+kjkoCbXE2fVbAzO/jhUHQX1H5RbTGGUnrrCWAj84Rq/E80KK1nrRF91K+vgZmilM
+gOZosLMMI1PeqTakwg1yIRngpTyk0eJP+haxAgMBAAGjUzBRMB0GA1UdDgQWBBT6
+sqvfjMIl0DFZkeu8LU577YqMVDAfBgNVHSMEGDAWgBT6sqvfjMIl0DFZkeu8LU57
+7YqMVDAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBQ1sYs2RvB
+TZ+xSBglLwH/S7zXVJIDwQ23Rlj11dgnVvcilSJCX24Rr+pfIVLpYNDdZzc/DIJd
+S1dt2JuLnvXnle29rU7cxuzYUkUkRtaeY2Sj210vsE3lqUFyIy8XCc/lteb+FiJ7
+zo/gPk7P+y4ihK9Mm6SBqkDVEYSFSn9bgoemK+0e93jGe2182PyuTwfTmZgENSBO
+2f9dSuay4C7e5UO8bhVccQJg6f4d70zUNG0oPHrnVxJLjwCd++jx25Gh4U7+ek13
+CW57pxJrpPMDWb2YK64rT2juHMKF73YuplW92SInd+QLpI2ekTLc+bRw8JvqzXg+
+SprtRUBjlWzj
+-----END CERTIFICATE-----
diff --git a/codex-rs/http-client/tests/fixtures/test-intermediate.pem b/codex-rs/http-client/tests/fixtures/test-intermediate.pem
new file mode 100644
index 0000000000000000000000000000000000000000..f29e69d63fd584a4dd4df8ad9100d79ae8108a07
--- /dev/null
+++ b/codex-rs/http-client/tests/fixtures/test-intermediate.pem
@@ -0,0 +1,21 @@
+# Second valid test-only certificate used for multi-certificate bundle coverage.
+# It is intentionally distinct from test-ca.pem; chain validation is not part of these tests.
+-----BEGIN CERTIFICATE-----
+MIIDGTCCAgGgAwIBAgIUWxlcvHzwITWAHWHbKMFUTgeDmjwwDQYJKoZIhvcNAQEL
+BQAwHDEaMBgGA1UEAwwRdGVzdC1pbnRlcm1lZGlhdGUwHhcNMjUxMTE5MTU1MDIz
+WhcNMjYxMTE5MTU1MDIzWjAcMRowGAYDVQQDDBF0ZXN0LWludGVybWVkaWF0ZTCC
+ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANq7xbeYpC2GaXANqD1nLk0t
+j9j2sOk6e7DqTapxnIUijS7z4DF0Vo1xHM07wK1m+wsB/t9CubNYRvtn6hrIzx7K
+jjlmvxo4/YluwO1EDMQWZAXkaY2O28ESKVx7QLfBPYAc4bf/5B4Nmt6KX5sQyyyH
+2qTfzVBUCAl3sI+Ydd3mx7NOye1yNNkCNqyK3Hj45F1JuH8NZxcb4OlKssZhMlD+
+EQx4G46AzKE9Ho8AqlQvg/tiWrMHRluw7zolMJ/AXzedAXedNIrX4fCOmZwcTkA1
+a8eLPP8oM9VFrr67a7on6p4zPqugUEQ4fawp7A5KqSjUAVCt1FXmn2V8N8V6W/sC
+AwEAAaNTMFEwHQYDVR0OBBYEFBEwRwW0gm3IjhLw1U3eOAvR0r6SMB8GA1UdIwQY
+MBaAFBEwRwW0gm3IjhLw1U3eOAvR0r6SMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZI
+hvcNAQELBQADggEBAB2fjAlpevK42Odv8XUEgV6VWlEP9HAmkRvugW9hjhzx1Iz9
+Vh/l9VcxL7PcqdpyGH+BIRvQIMokcYF5TXzf/KV1T2y56U8AWaSd2/xSjYNWwkgE
+TLE5V+H/YDKzvTe58UrOaxa5N3URscQL9f+ZKworODmfMlkJ1mlREK130ZMlBexB
+p9w5wo1M1fjx76Rqzq9MkpwBSbIO2zx/8+qy4BAH23MPGW+9OOnnq2DiIX3qUu1v
+hnjYOxYpCB28MZEJmqsjFJQQ9RF+Te4U2/oknVcf8lZIMJ2ZBOwt2zg8RqCtM52/
+IbATwYj77wg3CFLFKcDYs3tdUqpiniabKcf6zAs=
+-----END CERTIFICATE-----
diff --git a/codex-rs/mermaid/examples/render.rs b/codex-rs/mermaid/examples/render.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2a19e74f0b6d1f5f7c8c057c922bed862d10dfbc
--- /dev/null
+++ b/codex-rs/mermaid/examples/render.rs
@@ -0,0 +1,17 @@
+//! Render a diagram from standard input for manual prototype evaluation.
+
+use std::io::Read;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut source = String::new();
+    std::io::stdin()
+        .take(16 * 1024 + 1)
+        .read_to_string(&mut source)?;
+    let max_width = std::env::args()
+        .nth(1)
+        .map(|value| value.parse())
+        .transpose()?
+        .unwrap_or(120);
+    println!("{}", codex_mermaid::render(&source, max_width)?);
+    Ok(())
+}
diff --git a/codex-rs/mermaid/src/draw.rs b/codex-rs/mermaid/src/draw.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0068b047a7776efc2397533cddd1dbfe6dba78b7
--- /dev/null
+++ b/codex-rs/mermaid/src/draw.rs
@@ -0,0 +1,253 @@
+//! Orthogonal routes with unique lanes and endpoint positions, in all four directions.
+//!
+//! Routes never share segments. Crossings are explicitly marked; labels occupy reserved gutters.
+
+use super::Direction;
+use super::Graph;
+use super::RenderError;
+use super::Role;
+use super::Span;
+use super::output::Cell;
+use super::output::finish;
+use unicode_width::UnicodeWidthChar;
+use unicode_width::UnicodeWidthStr;
+
+pub(super) fn render(graph: &Graph, max_width: usize) -> Result<Vec<Vec<Span>>, RenderError> {
+    let horizontal = matches!(graph.direction, Direction::Right | Direction::Left);
+    let labels = graph
+        .nodes
+        .iter()
+        .map(|node| {
+            let mut lines = vec![if node.decision {
+                format!("◇ {}", node.label)
+            } else {
+                node.label.clone()
+            }];
+            if !node.members.is_empty() {
+                lines.push("─".repeat(node.label.width()));
+                lines.extend(node.members.iter().cloned());
+            }
+            lines
+        })
+        .collect::<Vec<_>>();
+    let label_width = graph
+        .edges
+        .iter()
+        .flat_map(|edge| [&edge.label, &edge.target_label])
+        .map(|label| label.width())
+        .max()
+        .unwrap_or(0);
+    let box_cross = if horizontal {
+        labels.iter().map(Vec::len).max().unwrap_or(0) + 2
+    } else {
+        labels
+            .iter()
+            .flatten()
+            .map(|label| label.width())
+            .max()
+            .unwrap_or(0)
+            + 4
+    };
+    let mut counts = vec![0; graph.nodes.len()];
+    let mut ports = Vec::new();
+    for edge in &graph.edges {
+        let source = counts[edge.from];
+        counts[edge.from] += 1;
+        let target = counts[edge.to];
+        counts[edge.to] += 1;
+        ports.push((source, target));
+    }
+    let stride = if horizontal { label_width + 2 } else { 1 };
+    let sizes = labels
+        .iter()
+        .enumerate()
+        .map(|(i, lines)| {
+            if horizontal {
+                (lines.iter().map(|line| line.width()).max().unwrap_or(0) + 4)
+                    .max(counts[i] * stride + 2)
+            } else {
+                lines.len() + counts[i] + 2
+            }
+        })
+        .collect::<Vec<_>>();
+    let mut starts = vec![0; graph.nodes.len()];
+    let mut along = 0;
+    for i in 0..graph.nodes.len() {
+        let i = if matches!(graph.direction, Direction::Up | Direction::Left) {
+            graph.nodes.len() - 1 - i
+        } else {
+            i
+        };
+        starts[i] = along;
+        along += sizes[i] + 2;
+    }
+    let first_lane = box_cross + if horizontal { 4 } else { label_width + 5 };
+    let across = if graph.edges.is_empty() {
+        box_cross
+    } else {
+        first_lane + graph.edges.len() * 2 - 1
+    };
+    let (width, height) = if horizontal {
+        (along - 2, across)
+    } else {
+        (across, along - 2)
+    };
+    if width > max_width {
+        return Err(RenderError::TooWide);
+    }
+    if width * height > super::MAX_CELLS {
+        return Err(RenderError::Limit);
+    }
+    let mut canvas = Canvas {
+        cells: vec![vec![Cell::edge(' '); width]; height],
+        horizontal,
+    };
+    for (i, lines) in labels.iter().enumerate() {
+        let start = starts[i];
+        let end = start + sizes[i] - 1;
+        canvas.set(/*across*/ 0, start, Cell::node('┌'));
+        canvas.set(box_cross - 1, start, Cell::node('┐'));
+        canvas.set(/*across*/ 0, end, Cell::node('└'));
+        canvas.set(box_cross - 1, end, Cell::node('┘'));
+        for x in 1..box_cross - 1 {
+            canvas.set(x, start, Cell::node('─'));
+            canvas.set(x, end, Cell::node('─'));
+        }
+        for y in start + 1..end {
+            canvas.set(/*across*/ 0, y, Cell::node('│'));
+            canvas.set(box_cross - 1, y, Cell::node('│'));
+        }
+        for (j, line) in lines.iter().enumerate() {
+            let (x, y) = if horizontal {
+                (start + 2, j + 1)
+            } else {
+                (2, start + j + 1)
+            };
+            put_text(&mut canvas.cells[y], x, line)?;
+        }
+    }
+    let endpoints = graph
+        .edges
+        .iter()
+        .enumerate()
+        .map(|(i, edge)| {
+            let offset = |node: usize, port: usize| {
+                starts[node]
+                    + if horizontal {
+                        1 + port * stride
+                    } else {
+                        labels[node].len() + 1 + port
+                    }
+            };
+            (offset(edge.from, ports[i].0), offset(edge.to, ports[i].1))
+        })
+        .collect::<Vec<_>>();
+    // Paint lanes first so every crossing is independent of iteration order.
+    for (i, edge) in graph.edges.iter().enumerate() {
+        let (source, target) = endpoints[i];
+        for y in source.min(target) + 1..source.max(target) {
+            canvas.set(
+                first_lane + 2 * i,
+                y,
+                Cell::edge(if edge.dashed { '┆' } else { '│' }),
+            );
+        }
+    }
+    for (i, edge) in graph.edges.iter().enumerate() {
+        let (source, target) = endpoints[i];
+        let lane = first_lane + 2 * i;
+        for y in [source, target] {
+            for x in box_cross..lane {
+                let ch = if matches!(canvas.get(x, y), '│' | '┆') {
+                    '╪'
+                } else if edge.dashed {
+                    '┄'
+                } else {
+                    '─'
+                };
+                canvas.set(x, y, Cell::edge(ch));
+            }
+        }
+        canvas.set(box_cross - 1, source, Cell::edge('├'));
+        canvas.set(box_cross - 1, target, Cell::edge('├'));
+        canvas.set(box_cross, source, Cell::edge(edge.source_tip));
+        canvas.set(box_cross, target, Cell::edge(edge.target_tip));
+        canvas.set(
+            lane,
+            source,
+            Cell::edge(if source < target { '┐' } else { '┘' }),
+        );
+        canvas.set(
+            lane,
+            target,
+            Cell::edge(if source < target { '┘' } else { '┐' }),
+        );
+        for (port, label) in [(source, &edge.label), (target, &edge.target_label)] {
+            let (x, y) = if horizontal {
+                (port + 1, box_cross + 1)
+            } else {
+                (box_cross + 2, port)
+            };
+            put_text(&mut canvas.cells[y], x, label)?;
+        }
+    }
+    Ok(finish(canvas.cells))
+}
+
+struct Canvas {
+    cells: Vec<Vec<Cell>>,
+    horizontal: bool,
+}
+
+impl Canvas {
+    fn set(&mut self, across: usize, along: usize, mut cell: Cell) {
+        if self.horizontal {
+            cell.symbol = transpose(cell.symbol);
+            self.cells[across][along] = cell;
+        } else {
+            self.cells[along][across] = cell;
+        }
+    }
+
+    fn get(&self, across: usize, along: usize) -> char {
+        if self.horizontal {
+            transpose(self.cells[across][along].symbol)
+        } else {
+            self.cells[along][across].symbol
+        }
+    }
+}
+
+fn transpose(ch: char) -> char {
+    match ch {
+        '─' => '│',
+        '│' => '─',
+        '┄' => '┆',
+        '┆' => '┄',
+        '┐' => '└',
+        '└' => '┐',
+        '├' => '┬',
+        '┬' => '├',
+        '◄' => '▲',
+        '▲' => '◄',
+        '◁' => '△',
+        '△' => '◁',
+        other => other,
+    }
+}
+
+pub(super) fn put_text(row: &mut [Cell], mut column: usize, text: &str) -> Result<(), RenderError> {
+    for ch in text.chars() {
+        let width = UnicodeWidthChar::width(ch).ok_or(RenderError::Unsupported)?;
+        row[column] = Cell {
+            symbol: ch,
+            role: Role::Text,
+        };
+        row[column + 1..column + width].fill(Cell {
+            symbol: '\0',
+            role: Role::Text,
+        });
+        column += width;
+    }
+    Ok(())
+}
diff --git a/codex-rs/mermaid/src/families_tests.rs b/codex-rs/mermaid/src/families_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..176c031e3a80bfe6ee1f2ddc1edd6a12905f83b9
--- /dev/null
+++ b/codex-rs/mermaid/src/families_tests.rs
@@ -0,0 +1,359 @@
+//! End-to-end grammar, topology, and rendered output checks for each supported family.
+
+use super::RenderError;
+use super::render;
+use pretty_assertions::assert_eq;
+use unicode_width::UnicodeWidthStr;
+
+const SEQUENCE: &str = "sequenceDiagram
+    actor U as Buyer
+    participant A as API
+    participant S as 库存
+    participant P as Payments
+    U->>A: Place order
+    A->>S: Reserve items
+    S-->>A: Reservation
+    opt Items reserved
+        loop Up to 3 attempts
+            A->>P: Charge card
+            P->>P: Check fraud
+            P-->>A: Payment status
+            alt Approved
+                Note over A,P: Payment recorded
+                A-->>U: Order confirmed
+            else Declined
+                A->>S: Release items
+                A-->>U: Payment failed
+            end
+        end
+    end";
+
+const STATE: &str = "stateDiagram-v2
+    state \"Payment pending\" as Charging
+    [*] --> Draft
+    Draft --> Validating: submit
+    Validating --> Charging: valid
+    Validating --> Rejected: invalid
+    Charging --> Packing: paid
+    Charging --> Rejected: declined
+    Packing --> Shipped: dispatch
+    Shipped --> Delivered: received
+    Delivered --> [*]
+    Rejected --> Draft: revise
+    Charging: Retry up to 3 times";
+
+const CLASS: &str = "classDiagram
+    class Order {
+        +String id
+        +Status status
+        +submit()
+        +cancel()
+    }
+    class LineItem {
+        +int quantity
+        +Decimal price
+        +subtotal()
+    }
+    class Payment {
+        +Decimal amount
+        +authorize()
+    }
+    class CardPayment {
+        +String lastFour
+        +authorize()
+    }
+    Order \"1\" *-- \"1..*\" LineItem : contains
+    Order \"1\" --> \"1\" Payment : pays with
+    Payment <|-- CardPayment
+    CardPayment ..> Order : updates";
+
+const ER: &str = "erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||..o{ LINE_ITEM : appears_in
+    CUSTOMER {
+        int id PK
+        string email UK
+        string name
+    }
+    ORDER {
+        int id PK
+        int customer_id FK
+        string status
+    }
+    LINE_ITEM {
+        int order_id PK, FK \"order key\"
+        int product_id PK, FK
+        int quantity
+    }
+    PRODUCT {
+        int id PK
+        string name
+        decimal price
+    }";
+
+#[test]
+fn complex_families() {
+    for (name, source) in [
+        ("sequence", SEQUENCE),
+        ("state", STATE),
+        ("class", CLASS),
+        ("er", ER),
+    ] {
+        let output = render(source, /*max_width*/ 180).unwrap();
+        let width = output.lines().map(UnicodeWidthStr::width).max().unwrap();
+        assert_eq!(render(source, width), Ok(output.clone()));
+        assert_eq!(render(source, width - 1), Err(RenderError::TooWide));
+        insta::assert_snapshot!(name, output);
+    }
+}
+
+#[test]
+fn unicode_labels_and_later_declarations() {
+    for direction in ["TD", "BT", "LR", "RL"] {
+        let source = format!(
+            "%% heading\ngraph {direction}; A -->|准备| B; A[请求]; B{{Réponse?}}; B -->|retry| A; B --> C[Ship 🚀]"
+        );
+        let output = render(&source, /*max_width*/ 160).unwrap();
+        for label in ["请求", "Réponse?", "Ship 🚀", "准备", "retry"] {
+            assert!(output.contains(label), "{direction}: {label}");
+        }
+        let width = output.lines().map(UnicodeWidthStr::width).max().unwrap();
+        assert_eq!(render(&source, width), Ok(output.clone()));
+        assert_eq!(render(&source, width - 1), Err(RenderError::TooWide));
+        if direction == "LR" {
+            insta::assert_snapshot!("LR", output);
+        }
+    }
+}
+
+#[test]
+fn class_relationship_endpoints() {
+    for (operator, source_tip, target_tip, dashed) in [
+        ("<|--", '◁', '─', false),
+        ("*--", '◆', '─', false),
+        ("o--", '◇', '─', false),
+        ("-->", '─', '◄', false),
+        ("--", '─', '─', false),
+        ("..>", '─', '◄', true),
+        ("..|>", '─', '◁', true),
+        ("..", '─', '─', true),
+        ("<--", '◄', '─', false),
+        ("--*", '─', '◆', false),
+        ("--o", '─', '◇', false),
+        ("--|>", '─', '◁', false),
+    ] {
+        let output = render(
+            &format!("classDiagram; A \"one\" {operator} \"many\" B : uses"),
+            /*max_width*/ 100,
+        )
+        .unwrap();
+        let ports = output
+            .lines()
+            .filter(|line| line.contains('├'))
+            .collect::<Vec<_>>();
+        assert!(
+            ports[0].contains(&format!("├{source_tip}")),
+            "{operator}: {output}"
+        );
+        assert!(
+            ports[1].contains(&format!("├{target_tip}")),
+            "{operator}: {output}"
+        );
+        assert!(ports[0].contains("(one) uses"));
+        assert!(ports[1].contains("(many)"));
+        assert_eq!(output.contains('┆'), dashed);
+    }
+}
+
+#[test]
+fn er_cardinalities() {
+    for (left, source_card) in [
+        ("||", "1"),
+        ("|o", "0..1"),
+        ("}|", "1..many"),
+        ("}o", "0..many"),
+    ] {
+        for (right, target_card) in [
+            ("||", "1"),
+            ("o|", "0..1"),
+            ("|{", "1..many"),
+            ("o{", "0..many"),
+        ] {
+            let output = render(
+                &format!("erDiagram; A {left}--{right} B : owns"),
+                /*max_width*/ 100,
+            )
+            .unwrap();
+            let ports = output
+                .lines()
+                .filter(|line| line.contains('├'))
+                .collect::<Vec<_>>();
+            assert!(ports[0].contains(&format!("({source_card}) owns")));
+            assert!(ports[1].contains(&format!("({target_card})")));
+        }
+    }
+}
+
+#[test]
+fn rejects_incomplete_and_unsupported_families() {
+    for source in [
+        "sequenceDiagram; A->>B: hello; nonsense",
+        "sequenceDiagram; A->>B: hello; activate B",
+        "sequenceDiagram; participant A as x; participant A as y",
+        "sequenceDiagram; alt ready; A->>B: hi",
+        "sequenceDiagram; A->>B: hi; end",
+        "sequenceDiagram; loop retry; else no; end",
+        "sequenceDiagram; alt one; else two; else three; end",
+        "sequenceDiagram; A->>B: <br/>",
+        "sequenceDiagram; A->>B: \u{1b}[31m",
+        "sequenceDiagram; participant A as e\u{301}",
+        "stateDiagram-v2; state Processing {; A-->B; }",
+        "stateDiagram-v2; A --> B: ok; garbage text",
+        "stateDiagram-v2; state \"First\" as A; state \"Second\" as A",
+        "stateDiagram-v2; accDescr: Order lifecycle; [*] --> Ready",
+        "stateDiagram; ACCDESCR: Order lifecycle; [*] --> Ready",
+        "stateDiagram-v2; A:::highlight; A --> B",
+        "stateDiagram-v2; A --> B:::highlight",
+        "classDiagram; accTitle: Account model; class Account",
+        "classDiagram; class A {; +foo()",
+        "classDiagram; class A; A --? B",
+        "classDiagram; A --> B; click A",
+        "classDiagram; class A {; +<html>; }",
+        "erDiagram; A ||--o{ B",
+        "erDiagram; A ||--?? B : owns",
+        "erDiagram; A {; int x KEY; }",
+        "erDiagram; A {; int x PK \"open comment; }",
+        "erDiagram; A {; int x; }; A ||--|| B : uses; trailing junk",
+        "erDiagram; accDescr {; A model; }; CUSTOMER",
+        "erDiagram; ACCDESCR {; A model; }; CUSTOMER",
+        "erDiagram; A ||--|| B:::highlight : owns",
+        "%%{init: {}}%%\nclassDiagram; class A",
+    ] {
+        assert_eq!(
+            render(source, /*max_width*/ 200),
+            Err(RenderError::Unsupported),
+            "{source}"
+        );
+    }
+}
+
+#[test]
+fn metadata_names_and_style_text_remain_valid_in_content() {
+    for source in [
+        "classDiagram; class accTitle {; +id; }; class accDescr {; +id; }",
+        "classDiagram; class A; A: ::: literal; A --> B: ::: literal",
+        "erDiagram; accTitle {; int id; }",
+        "erDiagram; A ||--|| B: ::: literal",
+        "stateDiagram-v2; A: text ::: literal; A --> B: ::: literal",
+    ] {
+        assert!(render(source, /*max_width*/ 200).is_ok(), "{source}");
+    }
+}
+
+#[test]
+fn family_limits() {
+    for source in [
+        format!(
+            "sequenceDiagram; {}",
+            (0..9)
+                .map(|i| format!("participant P{i};"))
+                .collect::<String>()
+        ),
+        format!("sequenceDiagram; {}", "A->>B: msg;".repeat(65)),
+        format!(
+            "sequenceDiagram; {} A->>B: msg; {}",
+            "loop retry;".repeat(5),
+            "end;".repeat(5)
+        ),
+        format!("classDiagram; class A {{; {} }}", "+field;".repeat(17)),
+        format!("erDiagram; A {{; {} }}", "int id;".repeat(17)),
+        format!("stateDiagram-v2; {}", "A --> B;".repeat(25)),
+    ] {
+        assert_eq!(
+            render(&source, /*max_width*/ usize::MAX),
+            Err(RenderError::Limit),
+            "{source}"
+        );
+    }
+}
+
+#[test]
+fn truncated_sources_and_terminal_widths() {
+    // Exercise incomplete streamed source at every UTF-8 boundary, including inside control blocks.
+    for source in [SEQUENCE, STATE, CLASS, ER, "sequenceDiagram; A->>B: 请求"] {
+        for end in source.char_indices().map(|(index, _)| index) {
+            if let Ok(output) = render(&source[..end], /*max_width*/ 180) {
+                assert!(output.lines().all(|line| line.width() <= 180));
+                assert!(!output.chars().any(|ch| ch.is_control() && ch != '\n'));
+            }
+        }
+    }
+    for source in [
+        "sequenceDiagram; A->>B: hi",
+        "sequenceDiagram; A->>A: self",
+        "sequenceDiagram; Note over A: memo",
+    ] {
+        let output = render(source, /*max_width*/ 100).unwrap();
+        let width = output.lines().map(UnicodeWidthStr::width).max().unwrap();
+        assert_eq!(render(source, width), Ok(output));
+        assert_eq!(render(source, width - 1), Err(RenderError::TooWide));
+    }
+}
+
+#[test]
+fn sequence_arrows_preserve_sender_recipient_and_style() {
+    for (operator, forward, reverse, dashed) in [
+        ("->>", '▶', '◀', false),
+        ("-->>", '▶', '◀', true),
+        ("->", '─', '─', false),
+        ("-->", '┄', '┄', true),
+        ("-x", 'x', 'x', false),
+        ("--x", 'x', 'x', true),
+    ] {
+        for (from, to, tip) in [
+            ("A", "B", forward),
+            ("B", "A", reverse),
+            ("B", "B", reverse),
+        ] {
+            let output = render(
+                &format!(
+                    "sequenceDiagram; participant A; participant B; {from}{operator}{to}: msg"
+                ),
+                /*max_width*/ 100,
+            )
+            .unwrap();
+            let rows = output
+                .lines()
+                .map(|line| line.chars().collect::<Vec<_>>())
+                .collect::<Vec<_>>();
+            let a = rows[1].iter().position(|ch| *ch == 'A').unwrap();
+            let b = rows[1].iter().position(|ch| *ch == 'B').unwrap();
+            let recipient = if to == "A" { a } else { b };
+            let row = if from == to { 5 } else { 4 };
+            assert_eq!(rows[row][recipient], tip, "{from}{operator}{to}");
+            assert_eq!(rows[row].contains(&'┄'), dashed);
+        }
+    }
+}
+
+#[test]
+fn canvas_limit_applies_even_with_unlimited_caller_width() {
+    let graph = format!(
+        "graph LR; {}",
+        format!("A-->|{}|B;", "x".repeat(40)).repeat(24)
+    );
+    let sequence = format!(
+        "sequenceDiagram; {} {}",
+        (0..8)
+            .map(|i| format!("participant P{i};"))
+            .collect::<String>(),
+        format!("P0->>P7: {};", "x".repeat(40)).repeat(64)
+    );
+    for source in [graph, sequence] {
+        assert_eq!(
+            render(&source, /*max_width*/ usize::MAX),
+            Err(RenderError::Limit)
+        );
+    }
+}
diff --git a/codex-rs/mermaid/src/lib.rs b/codex-rs/mermaid/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a6475a3a35b91015fbad37d08d0b01db0576f06e
--- /dev/null
+++ b/codex-rs/mermaid/src/lib.rs
@@ -0,0 +1,176 @@
+//! Bounded, terminal-native Mermaid diagram prototype.
+//!
+//! Supports flowcharts, sequences, states, classes, and entity relationships.
+//! Graph edges own separate lanes and endpoint positions. Crossings never join routes. Unsupported
+//! syntax and outputs exceeding the caller's width return errors, leaving source fallback to
+//! the caller. This crate performs no I/O and does not depend on a Mermaid implementation.
+
+mod draw;
+mod output;
+mod parse;
+mod relations;
+mod sequence;
+mod state;
+
+pub use output::Role;
+pub use output::Span;
+use std::fmt;
+
+const MAX_SOURCE: usize = 16 * 1024;
+const MAX_NODES: usize = 16;
+const MAX_EDGES: usize = 24;
+const MAX_LABEL: usize = 40;
+const MAX_CELLS: usize = 64 * 1024;
+
+/// A diagram cannot be faithfully represented by this bounded prototype.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RenderError {
+    /// Syntax or text is outside the explicitly supported subset.
+    Unsupported,
+    /// A source, diagram, label, or canvas limit was exceeded.
+    Limit,
+    /// The complete diagram exceeds the supplied display width.
+    TooWide,
+}
+
+impl fmt::Display for RenderError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(match self {
+            Self::Unsupported => "unsupported Mermaid syntax or label",
+            Self::Limit => "diagram exceeds prototype limits",
+            Self::TooWide => "diagram exceeds available display width",
+        })
+    }
+}
+
+impl std::error::Error for RenderError {}
+
+/// Render a bounded subset of Mermaid as plain Unicode text.
+///
+/// Supports flowcharts, sequence diagrams, flat state diagrams, class diagrams, and ER diagrams.
+/// See the crate README for each grammar and its limits. Unknown syntax, unsafe terminal text,
+/// and diagrams exceeding `max_width` return errors; no partial result is returned.
+pub fn render(source: &str, max_width: usize) -> Result<String, RenderError> {
+    Ok(render_spans(source, max_width)?
+        .into_iter()
+        .map(|line| line.into_iter().map(|span| span.text).collect::<String>())
+        .collect::<Vec<_>>()
+        .join("\n"))
+}
+
+/// Render the same bounded diagram as lines of semantic spans for caller-provided styling.
+pub fn render_spans(source: &str, max_width: usize) -> Result<Vec<Vec<Span>>, RenderError> {
+    if source.len() > MAX_SOURCE {
+        return Err(RenderError::Limit);
+    }
+    let statements = source
+        .lines()
+        .filter(|line| !line.trim_start().starts_with("%%"))
+        .flat_map(|line| line.split(';'))
+        .map(str::trim)
+        .filter(|line| !line.is_empty())
+        .collect::<Vec<_>>();
+    if source
+        .lines()
+        .any(|line| line.trim_start().starts_with("%%{"))
+    {
+        return Err(RenderError::Unsupported);
+    }
+    let (header, body) = statements.split_first().ok_or(RenderError::Unsupported)?;
+    match *header {
+        "sequenceDiagram" => sequence::render(body, max_width),
+        "stateDiagram-v2" | "stateDiagram" | "classDiagram" | "erDiagram" => {
+            draw::render(&relations::parse(header, body)?, max_width)
+        }
+        _ => draw::render(&parse::parse(header, body)?, max_width),
+    }
+}
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+enum Direction {
+    #[default]
+    Down,
+    Up,
+    Right,
+    Left,
+}
+
+impl Direction {
+    fn parse(text: &str) -> Result<Self, RenderError> {
+        match text {
+            "TD" | "TB" => Ok(Self::Down),
+            "BT" => Ok(Self::Up),
+            "LR" => Ok(Self::Right),
+            "RL" => Ok(Self::Left),
+            _ => Err(RenderError::Unsupported),
+        }
+    }
+}
+
+#[derive(Debug, PartialEq, Eq)]
+struct Node {
+    id: String,
+    label: String,
+    decision: bool,
+    declared: bool,
+    members: Vec<String>,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+struct Edge {
+    from: usize,
+    to: usize,
+    label: String,
+    target_label: String,
+    source_tip: char,
+    target_tip: char,
+    dashed: bool,
+}
+
+impl Edge {
+    fn directed(from: usize, to: usize, label: String) -> Self {
+        Self {
+            from,
+            to,
+            label,
+            target_label: String::new(),
+            source_tip: '─',
+            target_tip: '◄',
+            dashed: false,
+        }
+    }
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct Graph {
+    direction: Direction,
+    nodes: Vec<Node>,
+    edges: Vec<Edge>,
+}
+
+impl Graph {
+    fn node(&mut self, id: &str) -> Result<usize, RenderError> {
+        if let Some(index) = self.nodes.iter().position(|node| node.id == id) {
+            return Ok(index);
+        }
+        if self.nodes.len() == MAX_NODES {
+            return Err(RenderError::Limit);
+        }
+        self.nodes.push(Node {
+            id: id.to_owned(),
+            label: id.to_owned(),
+            decision: false,
+            declared: false,
+            members: Vec::new(),
+        });
+        Ok(self.nodes.len() - 1)
+    }
+}
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "families_tests.rs"]
+mod families_tests;
diff --git a/codex-rs/mermaid/src/output.rs b/codex-rs/mermaid/src/output.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8e78af515e22c92226b1337691343171a106f0f3
--- /dev/null
+++ b/codex-rs/mermaid/src/output.rs
@@ -0,0 +1,69 @@
+//! Semantic spans for theme-independent diagram output; drawing cells never contain ANSI escapes.
+
+/// The diagram element a caller can style with its own theme.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Role {
+    Node,
+    Edge,
+    Text,
+}
+
+/// Adjacent characters with one semantic role, independent of terminal styling.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Span {
+    pub text: String,
+    pub role: Role,
+}
+
+#[derive(Clone, Copy)]
+pub(super) struct Cell {
+    pub symbol: char,
+    pub role: Role,
+}
+
+impl Cell {
+    pub(super) fn edge(symbol: char) -> Self {
+        Self {
+            symbol,
+            role: Role::Edge,
+        }
+    }
+
+    pub(super) fn node(symbol: char) -> Self {
+        Self {
+            symbol,
+            role: Role::Node,
+        }
+    }
+}
+
+pub(super) fn finish(rows: Vec<Vec<Cell>>) -> Vec<Vec<Span>> {
+    rows.into_iter()
+        .map(|row| {
+            let mut spans: Vec<Span> = Vec::new();
+            for Cell { symbol, role } in row {
+                if symbol == '\0' {
+                    continue;
+                }
+                if let Some(last) = spans.last_mut()
+                    && last.role == role
+                {
+                    last.text.push(symbol);
+                } else {
+                    spans.push(Span {
+                        text: symbol.to_string(),
+                        role,
+                    });
+                }
+            }
+            while let Some(last) = spans.last_mut() {
+                last.text.truncate(last.text.trim_end().len());
+                if !last.text.is_empty() {
+                    break;
+                }
+                spans.pop();
+            }
+            spans
+        })
+        .collect()
+}
diff --git a/codex-rs/mermaid/src/parse.rs b/codex-rs/mermaid/src/parse.rs
new file mode 100644
index 0000000000000000000000000000000000000000..157e69fbbf062a3b4aaeedc2f4b38f24e47ee3cc
--- /dev/null
+++ b/codex-rs/mermaid/src/parse.rs
@@ -0,0 +1,143 @@
+//! Strict parser for a small flowchart grammar; every non-comment byte must be consumed.
+
+use super::Direction;
+use super::Edge;
+use super::Graph;
+use super::MAX_EDGES;
+use super::MAX_LABEL;
+use super::RenderError;
+use unicode_width::UnicodeWidthChar;
+use unicode_width::UnicodeWidthStr;
+
+pub(super) fn parse(header: &str, body: &[&str]) -> Result<Graph, RenderError> {
+    let tokens = header.split_whitespace().collect::<Vec<_>>();
+    let ["flowchart" | "graph", direction] = tokens.as_slice() else {
+        return Err(RenderError::Unsupported);
+    };
+    let mut graph = Graph {
+        direction: Direction::parse(direction)?,
+        ..Graph::default()
+    };
+    for statement in body {
+        let mut rest = *statement;
+        let mut from = node(&mut rest, &mut graph)?;
+        while !rest.trim_start().is_empty() {
+            rest = rest
+                .trim_start()
+                .strip_prefix("-->")
+                .ok_or(RenderError::Unsupported)?;
+            rest = rest.trim_start();
+            let label = if let Some(after) = rest.strip_prefix('|') {
+                let (label, remaining) = after.split_once('|').ok_or(RenderError::Unsupported)?;
+                check_label(label)?;
+                rest = remaining;
+                label.to_owned()
+            } else {
+                String::new()
+            };
+            let to = node(&mut rest, &mut graph)?;
+            if graph.edges.len() == MAX_EDGES {
+                return Err(RenderError::Limit);
+            }
+            graph.edges.push(Edge::directed(from, to, label));
+            from = to;
+        }
+    }
+    if graph.nodes.is_empty() {
+        return Err(RenderError::Unsupported);
+    }
+    Ok(graph)
+}
+
+fn node(rest: &mut &str, graph: &mut Graph) -> Result<usize, RenderError> {
+    let id = identifier(rest)?;
+    // Reserved constructs must not be interpreted as ordinary node declarations.
+    if matches!(
+        id,
+        "end" | "subgraph" | "direction" | "style" | "class" | "classDef" | "linkStyle" | "click"
+    ) {
+        return Err(RenderError::Unsupported);
+    }
+    let declaration = match rest.chars().next() {
+        Some(open @ ('[' | '{')) => {
+            let close = if open == '[' { ']' } else { '}' };
+            let (label, remaining) = rest[1..]
+                .split_once(close)
+                .ok_or(RenderError::Unsupported)?;
+            check_label(label)?;
+            *rest = remaining;
+            Some((label, open == '{'))
+        }
+        _ => None,
+    };
+    let index = graph.node(id)?;
+    if let Some((label, decision)) = declaration {
+        let node = &mut graph.nodes[index];
+        if node.declared && (node.label != label || node.decision != decision) {
+            return Err(RenderError::Unsupported);
+        }
+        node.label = label.to_owned();
+        node.decision = decision;
+        node.declared = true;
+    }
+    Ok(index)
+}
+
+pub(super) fn check_label(label: &str) -> Result<(), RenderError> {
+    if label.trim().is_empty()
+        || label.chars().any(|ch| {
+            ch.is_control()
+                || matches!(
+                    ch,
+                    '[' | ']'
+                        | '{'
+                        | '}'
+                        | '|'
+                        | '<'
+                        | '>'
+                        | '&'
+                        | '"'
+                        | '\\'
+                        | '┌'
+                        | '┐'
+                        | '└'
+                        | '┘'
+                        | '├'
+                        | '┤'
+                        | '╪'
+                        | '◄'
+                )
+                || UnicodeWidthChar::width(ch).is_none_or(|width| width == 0)
+        })
+    {
+        return Err(RenderError::Unsupported);
+    }
+    // Labels are drawn one Unicode scalar at a time. Reject ligatures whose string width differs
+    // from those scalar widths rather than misaligning borders or underallocating the canvas.
+    if label
+        .chars()
+        .filter_map(UnicodeWidthChar::width)
+        .sum::<usize>()
+        != label.width()
+    {
+        return Err(RenderError::Unsupported);
+    }
+    if UnicodeWidthStr::width(label) > MAX_LABEL {
+        return Err(RenderError::Limit);
+    }
+    Ok(())
+}
+
+pub(super) fn identifier<'a>(rest: &mut &'a str) -> Result<&'a str, RenderError> {
+    *rest = rest.trim_start();
+    let len = rest
+        .bytes()
+        .take_while(|b| b.is_ascii_alphanumeric() || *b == b'_')
+        .count();
+    let id = &rest[..len];
+    if id.is_empty() || !id.as_bytes()[0].is_ascii_alphabetic() || id.len() > MAX_LABEL {
+        return Err(RenderError::Unsupported);
+    }
+    *rest = &rest[len..];
+    Ok(id)
+}
diff --git a/codex-rs/mermaid/src/relations.rs b/codex-rs/mermaid/src/relations.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c13f79e151a599b9914ada2227414af3158c006b
--- /dev/null
+++ b/codex-rs/mermaid/src/relations.rs
@@ -0,0 +1,225 @@
+//! Class and ER grammars, preserving members, endpoint cardinalities, and relationship kinds.
+
+use super::Direction;
+use super::Edge;
+use super::Graph;
+use super::MAX_EDGES;
+use super::RenderError;
+use super::parse::check_label;
+use super::parse::identifier;
+
+pub(super) fn parse(header: &str, body: &[&str]) -> Result<Graph, RenderError> {
+    if matches!(header, "stateDiagram" | "stateDiagram-v2") {
+        return super::state::parse(body);
+    }
+    let er = header == "erDiagram";
+    let mut graph = Graph::default();
+    let mut block = None;
+    let mut direction = false;
+    for &line in body {
+        if let Some(index) = block {
+            if line == "}" {
+                block = None;
+            } else {
+                let member = if er {
+                    attribute(line)?
+                } else {
+                    check_label(line)?;
+                    line.to_owned()
+                };
+                let node: &mut super::Node = &mut graph.nodes[index];
+                if node.members.len() == 16 {
+                    return Err(RenderError::Limit);
+                }
+                node.members.push(member);
+            }
+            continue;
+        }
+        if let Some(value) = line.strip_prefix("direction ") {
+            if direction {
+                return Err(RenderError::Unsupported);
+            }
+            graph.direction = Direction::parse(value.trim())?;
+            direction = true;
+            continue;
+        }
+        let declaration = !er && line.starts_with("class ");
+        let mut rest = line.strip_prefix("class ").filter(|_| !er).unwrap_or(line);
+        let id = identifier(&mut rest)?;
+        rest = rest.trim_start();
+        let title = id == "accTitle" || er && id.eq_ignore_ascii_case("accTitle");
+        let description = id == "accDescr" || er && id.eq_ignore_ascii_case("accDescr");
+        if !declaration
+            && (title && rest.starts_with(':') || description && rest.starts_with([':', '{']))
+        {
+            return Err(RenderError::Unsupported);
+        }
+        let from = graph.node(id)?;
+        if rest == "{" && (er || declaration) {
+            block = Some(from);
+            continue;
+        }
+        if declaration || (er && rest.is_empty()) {
+            if !rest.is_empty() {
+                return Err(RenderError::Unsupported);
+            }
+            continue;
+        }
+        if !er
+            && let Some(member) = rest
+                .strip_prefix(':')
+                .filter(|text| !text.starts_with("::"))
+        {
+            let member = member.trim();
+            check_label(member)?;
+            if graph.nodes[from].members.len() == 16 {
+                return Err(RenderError::Limit);
+            }
+            graph.nodes[from].members.push(member.to_owned());
+            continue;
+        }
+        let source_card = if er {
+            String::new()
+        } else {
+            cardinality(&mut rest)?
+        };
+        rest = rest.trim_start();
+        let split = rest
+            .find("--")
+            .into_iter()
+            .chain(rest.find(".."))
+            .min()
+            .ok_or(RenderError::Unsupported)?;
+        if split > 2 {
+            return Err(RenderError::Unsupported);
+        }
+        let left = &rest[..split];
+        let dashed = &rest[split..split + 2] == "..";
+        rest = &rest[split + 2..];
+        let (source_tip, target_tip, source_card, target_card) = if er {
+            let source_card = match left {
+                "||" => "1",
+                "|o" => "0..1",
+                "}|" => "1..many",
+                "}o" => "0..many",
+                _ => return Err(RenderError::Unsupported),
+            }
+            .to_owned();
+            let right = rest.get(..2).ok_or(RenderError::Unsupported)?;
+            let target_card = match right {
+                "||" => "1",
+                "o|" => "0..1",
+                "|{" => "1..many",
+                "o{" => "0..many",
+                _ => return Err(RenderError::Unsupported),
+            }
+            .to_owned();
+            rest = &rest[2..];
+            ('─', '─', source_card, target_card)
+        } else {
+            let source_tip = match left {
+                "" => '─',
+                "<" => '◄',
+                "<|" => '◁',
+                "*" => '◆',
+                "o" => '◇',
+                _ => return Err(RenderError::Unsupported),
+            };
+            let mut target_tip = '─';
+            for (token, tip) in [("|>", '◁'), (">", '◄'), ("*", '◆'), ("o", '◇')] {
+                if let Some(after) = rest.strip_prefix(token) {
+                    target_tip = tip;
+                    rest = after;
+                    break;
+                }
+            }
+            let target_card = cardinality(&mut rest)?;
+            (source_tip, target_tip, source_card, target_card)
+        };
+        let to = graph.node(identifier(&mut rest)?)?;
+        rest = rest.trim();
+        let label = if let Some(label) = rest
+            .strip_prefix(':')
+            .filter(|text| !text.starts_with("::"))
+        {
+            let label = label.trim();
+            check_label(label)?;
+            label.to_owned()
+        } else if !rest.is_empty() || er {
+            return Err(RenderError::Unsupported);
+        } else {
+            String::new()
+        };
+        if graph.edges.len() == MAX_EDGES {
+            return Err(RenderError::Limit);
+        }
+        let label = match (source_card.is_empty(), label.is_empty()) {
+            (true, _) => label,
+            (false, true) => format!("({source_card})"),
+            (false, false) => format!("({source_card}) {label}"),
+        };
+        graph.edges.push(Edge {
+            from,
+            to,
+            label,
+            source_tip,
+            target_tip,
+            dashed,
+            target_label: if target_card.is_empty() {
+                target_card
+            } else {
+                format!("({target_card})")
+            },
+        });
+    }
+    if block.is_some() || graph.nodes.is_empty() {
+        return Err(RenderError::Unsupported);
+    }
+    Ok(graph)
+}
+
+fn cardinality(rest: &mut &str) -> Result<String, RenderError> {
+    *rest = rest.trim_start();
+    if let Some(after) = rest.strip_prefix('"') {
+        let (value, after) = after.split_once('"').ok_or(RenderError::Unsupported)?;
+        check_label(value)?;
+        *rest = after;
+        Ok(value.to_owned())
+    } else {
+        Ok(String::new())
+    }
+}
+
+fn attribute(line: &str) -> Result<String, RenderError> {
+    let mut rest = line;
+    let data_type = identifier(&mut rest)?;
+    if !rest.starts_with(char::is_whitespace) {
+        return Err(RenderError::Unsupported);
+    }
+    let name = identifier(&mut rest)?;
+    let (keys, comment) = if let Some((keys, comment)) = rest.trim().split_once('"') {
+        let comment = comment.strip_suffix('"').ok_or(RenderError::Unsupported)?;
+        check_label(comment)?;
+        (keys.trim(), Some(comment))
+    } else {
+        (rest.trim(), None)
+    };
+    if !keys.is_empty()
+        && !keys
+            .split(',')
+            .all(|key| matches!(key.trim(), "PK" | "FK" | "UK"))
+    {
+        return Err(RenderError::Unsupported);
+    }
+    let mut result = format!("{data_type} {name}");
+    if !keys.is_empty() {
+        result.push(' ');
+        result.push_str(keys);
+    }
+    if let Some(comment) = comment {
+        result.push_str(" — ");
+        result.push_str(comment);
+    }
+    check_label(&result)?;
+    Ok(result)
+}
diff --git a/codex-rs/mermaid/src/sequence.rs b/codex-rs/mermaid/src/sequence.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f075117e7a01a3c499545400a4513016907b23e4
--- /dev/null
+++ b/codex-rs/mermaid/src/sequence.rs
@@ -0,0 +1,306 @@
+//! Bounded sequence timelines with ordered messages and explicitly nested control fragments.
+
+use super::RenderError;
+use super::Span;
+use super::draw::put_text;
+use super::output::Cell;
+use super::output::finish;
+use super::parse::check_label;
+use super::parse::identifier;
+use unicode_width::UnicodeWidthStr;
+
+#[derive(Debug)]
+enum Event {
+    Message {
+        from: usize,
+        to: usize,
+        text: String,
+        dashed: bool,
+        arrow: char,
+    },
+    Open(String),
+    Branch(String),
+    Close,
+    Note {
+        left: usize,
+        right: usize,
+        text: String,
+    },
+}
+
+pub(super) fn render(body: &[&str], max_width: usize) -> Result<Vec<Vec<Span>>, RenderError> {
+    let mut people: Vec<(String, String, bool)> = Vec::new();
+    let mut events = Vec::new();
+    let mut blocks = Vec::new();
+    for &line in body {
+        let mut rest = line;
+        if let Some(after) = line
+            .strip_prefix("participant ")
+            .or_else(|| line.strip_prefix("actor "))
+        {
+            rest = after;
+            let id = identifier(&mut rest)?;
+            let label = if let Some(label) = rest.trim_start().strip_prefix("as ") {
+                check_label(label)?;
+                label
+            } else if rest.trim().is_empty() {
+                id
+            } else {
+                return Err(RenderError::Unsupported);
+            };
+            let index = participant(&mut people, id)?;
+            if people[index].2 {
+                return Err(RenderError::Unsupported);
+            }
+            people[index].1 = if line.starts_with("actor ") {
+                format!("{label} (actor)")
+            } else {
+                label.to_owned()
+            };
+            people[index].2 = true;
+            continue;
+        }
+        let event = if line == "end" {
+            blocks.pop().ok_or(RenderError::Unsupported)?;
+            Event::Close
+        } else if let Some(text) = line.strip_prefix("else ") {
+            let Some(("alt", branched)) = blocks.last_mut() else {
+                return Err(RenderError::Unsupported);
+            };
+            if *branched {
+                return Err(RenderError::Unsupported);
+            }
+            *branched = true;
+            check_label(text)?;
+            Event::Branch(format!("else {text}"))
+        } else if let Some((kind @ ("loop" | "alt" | "opt" | "critical" | "break"), text)) =
+            line.split_once(' ')
+        {
+            check_label(text)?;
+            if blocks.len() == 4 {
+                return Err(RenderError::Limit);
+            }
+            blocks.push((kind, false));
+            Event::Open(format!("{kind} {text}"))
+        } else if let Some(after) = line
+            .strip_prefix("Note over ")
+            .or_else(|| line.strip_prefix("note over "))
+        {
+            rest = after;
+            let left = participant(&mut people, identifier(&mut rest)?)?;
+            let right = if let Some(after) = rest.trim_start().strip_prefix(',') {
+                rest = after;
+                participant(&mut people, identifier(&mut rest)?)?
+            } else {
+                left
+            };
+            let text = rest
+                .trim_start()
+                .strip_prefix(':')
+                .ok_or(RenderError::Unsupported)?
+                .trim();
+            check_label(text)?;
+            Event::Note {
+                left: left.min(right),
+                right: left.max(right),
+                text: text.to_owned(),
+            }
+        } else {
+            let from = participant(&mut people, identifier(&mut rest)?)?;
+            rest = rest.trim_start();
+            let mut operator = None;
+            for (token, dashed, arrow) in [
+                ("-->>", true, '▶'),
+                ("->>", false, '▶'),
+                ("-->", true, '┄'),
+                ("->", false, '─'),
+                ("--x", true, 'x'),
+                ("-x", false, 'x'),
+            ] {
+                if let Some(after) = rest.strip_prefix(token) {
+                    rest = after;
+                    operator = Some((dashed, arrow));
+                    break;
+                }
+            }
+            let (dashed, arrow) = operator.ok_or(RenderError::Unsupported)?;
+            let to = participant(&mut people, identifier(&mut rest)?)?;
+            let text = rest
+                .trim_start()
+                .strip_prefix(':')
+                .ok_or(RenderError::Unsupported)?
+                .trim();
+            check_label(text)?;
+            Event::Message {
+                from,
+                to,
+                text: text.to_owned(),
+                dashed,
+                arrow,
+            }
+        };
+        if events.len() == 64 {
+            return Err(RenderError::Limit);
+        }
+        events.push(event);
+    }
+    if !blocks.is_empty() || people.is_empty() {
+        return Err(RenderError::Unsupported);
+    }
+    let name_width = people
+        .iter()
+        .map(|(_, label, _)| label.width())
+        .max()
+        .unwrap_or(0);
+    let text_width = events
+        .iter()
+        .map(|event| match event {
+            Event::Message { text, .. } | Event::Open(text) | Event::Branch(text) => text.width(),
+            Event::Note { text, .. } => text.width() + 6,
+            Event::Close => 0,
+        })
+        .max()
+        .unwrap_or(0);
+    let box_width = name_width + 4;
+    let stride = (box_width + 2).max(text_width + 4);
+    // Four frame levels consume eight columns on each side, separate from participant lifelines.
+    let centers = (0..people.len())
+        .map(|i| 10 + box_width / 2 + stride * i)
+        .collect::<Vec<_>>();
+    let last = centers[people.len() - 1];
+    let width = (last + box_width - box_width / 2 + 10).max(last + text_width + 14);
+    if width * (3 + 4 * events.len()) > super::MAX_CELLS {
+        return Err(RenderError::Limit);
+    }
+    let mut rows = vec![vec![Cell::edge(' '); width]; 3];
+    for (i, (_, name, _)) in people.iter().enumerate() {
+        let left = centers[i] - box_width / 2;
+        let right = left + box_width - 1;
+        rows[0][left] = Cell::node('┌');
+        rows[0][right] = Cell::node('┐');
+        rows[2][left] = Cell::node('└');
+        rows[2][right] = Cell::node('┘');
+        rows[0][left + 1..right].fill(Cell::node('─'));
+        rows[2][left + 1..right].fill(Cell::node('─'));
+        rows[1][left] = Cell::node('│');
+        rows[1][right] = Cell::node('│');
+        put_text(&mut rows[1], left + 2, name)?;
+    }
+    let mut depth = 0;
+    for event in events {
+        let count = if matches!(event, Event::Message { from, to, .. } if from == to) {
+            4
+        } else {
+            3
+        };
+        let top = rows.len();
+        rows.extend((0..count).map(|_| {
+            let mut row = vec![Cell::edge(' '); width];
+            for x in &centers {
+                row[*x] = Cell::edge('│');
+            }
+            for level in 0..depth {
+                row[level * 2] = Cell::node('│');
+                row[width - 1 - level * 2] = Cell::node('│');
+            }
+            row
+        }));
+        match event {
+            Event::Message {
+                from,
+                to,
+                text,
+                dashed,
+                arrow,
+            } => {
+                let (a, b) = (centers[from], centers[to]);
+                let arrow = if a >= b && arrow == '▶' {
+                    '◀'
+                } else {
+                    arrow
+                };
+                let stroke = if dashed { '┄' } else { '─' };
+                put_text(&mut rows[top], a.min(b) + 2, &text)?;
+                if a == b {
+                    rows[top + 1][a..a + 4].fill(Cell::edge(stroke));
+                    rows[top + 1][a] = Cell::edge('├');
+                    rows[top + 1][a + 4] = Cell::edge('┐');
+                    rows[top + 2][a..a + 4].fill(Cell::edge(stroke));
+                    rows[top + 2][a + 4] = Cell::edge('┘');
+                    rows[top + 2][a] = Cell::edge(arrow);
+                } else {
+                    rows[top + 1][a.min(b)..=a.max(b)].fill(Cell::edge(stroke));
+                    for x in &centers {
+                        if *x > a.min(b) && *x < a.max(b) {
+                            rows[top + 1][*x] = Cell::edge('┼');
+                        }
+                    }
+                    rows[top + 1][a] = Cell::edge(if a < b { '├' } else { '┤' });
+                    rows[top + 1][b] = Cell::edge(arrow);
+                }
+            }
+            Event::Note { left, right, text } => {
+                let label = format!("Note: {text}");
+                let start = centers[left];
+                let end = centers[right].max(start + label.width() + 3);
+                rows[top][start..=end].fill(Cell::node('─'));
+                rows[top + 2][start..=end].fill(Cell::node('─'));
+                rows[top][start] = Cell::node('┌');
+                rows[top][end] = Cell::node('┐');
+                rows[top + 2][start] = Cell::node('└');
+                rows[top + 2][end] = Cell::node('┘');
+                rows[top + 1][start..=end].fill(Cell::node(' '));
+                rows[top + 1][start] = Cell::node('│');
+                rows[top + 1][end] = Cell::node('│');
+                put_text(&mut rows[top + 1], start + 2, &label)?;
+            }
+            Event::Open(label) | Event::Branch(label) => {
+                let opening = !label.starts_with("else ");
+                if opening {
+                    depth += 1;
+                }
+                let left = (depth - 1) * 2;
+                let right = width - 1 - left;
+                rows[top][left..=right].fill(Cell::node('─'));
+                rows[top][left] = Cell::node(if opening { '┌' } else { '├' });
+                rows[top][right] = Cell::node(if opening { '┐' } else { '┤' });
+                put_text(&mut rows[top], left + 2, &label)?;
+                for row in &mut rows[top + 1..top + 3] {
+                    row[left] = Cell::node('│');
+                    row[right] = Cell::node('│');
+                }
+            }
+            Event::Close => {
+                depth -= 1;
+                let left = depth * 2;
+                let right = width - 1 - left;
+                rows[top][left..=right].fill(Cell::node('─'));
+                rows[top][left] = Cell::node('└');
+                rows[top][right] = Cell::node('┘');
+                for row in &mut rows[top + 1..top + 3] {
+                    row[left] = Cell::node(' ');
+                    row[right] = Cell::node(' ');
+                }
+            }
+        }
+    }
+    if rows.iter().any(|row| {
+        row.iter()
+            .rposition(|cell| cell.symbol != ' ')
+            .is_some_and(|x| x >= max_width)
+    }) {
+        return Err(RenderError::TooWide);
+    }
+    Ok(finish(rows))
+}
+
+fn participant(people: &mut Vec<(String, String, bool)>, id: &str) -> Result<usize, RenderError> {
+    if let Some(index) = people.iter().position(|(name, _, _)| name == id) {
+        return Ok(index);
+    }
+    if people.len() == 8 {
+        return Err(RenderError::Limit);
+    }
+    people.push((id.to_owned(), id.to_owned(), false));
+    Ok(people.len() - 1)
+}
diff --git a/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__LR.snap b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__LR.snap
new file mode 100644
index 0000000000000000000000000000000000000000..a06e3e246afa27f9f4f60aa538b0da40fe382494
--- /dev/null
+++ b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__LR.snap
@@ -0,0 +1,17 @@
+---
+source: mermaid/src/families_tests.rs
+assertion_line: 125
+expression: output
+---
+┌──────────────┐  ┌─────────────────────┐  ┌─────────┐
+│ 请求         │  │ ◇ Réponse?          │  │ Ship 🚀 │
+└┬──────┬──────┘  └┬──────┬──────┬──────┘  └┬────────┘
+ │      ▲          ▲      │      │          ▲
+ │准备  │          │      │retry │          │
+ │      │          │      │      │          │
+ │      │          │      │      │          │
+ └──────╪──────────┘      │      │          │
+        │                 │      │          │
+        └─────────────────┘      │          │
+                                 │          │
+                                 └──────────┘
diff --git a/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__class.snap b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__class.snap
new file mode 100644
index 0000000000000000000000000000000000000000..054ec8f9468daa38ff5b594d1d2b1d6fb6331908
--- /dev/null
+++ b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__class.snap
@@ -0,0 +1,46 @@
+---
+source: mermaid/src/families_tests.rs
+assertion_line: 100
+expression: output
+---
+┌──────────────────┐
+│ Order            │
+│ ─────            │
+│ +String id       │
+│ +Status status   │
+│ +submit()        │
+│ +cancel()        │
+│                  ├◆─(1) contains────┐
+│                  ├──(1) pays with───╪─┐
+│                  ├◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╪┄╪┄┄┄┐
+└──────────────────┘                  │ │   ┆
+                                      │ │   ┆
+                                      │ │   ┆
+┌──────────────────┐                  │ │   ┆
+│ LineItem         │                  │ │   ┆
+│ ────────         │                  │ │   ┆
+│ +int quantity    │                  │ │   ┆
+│ +Decimal price   │                  │ │   ┆
+│ +subtotal()      │                  │ │   ┆
+│                  ├──(1..*)──────────┘ │   ┆
+└──────────────────┘                    │   ┆
+                                        │   ┆
+                                        │   ┆
+┌──────────────────┐                    │   ┆
+│ Payment          │                    │   ┆
+│ ───────          │                    │   ┆
+│ +Decimal amount  │                    │   ┆
+│ +authorize()     │                    │   ┆
+│                  ├◄─(1)───────────────┘   ┆
+│                  ├◁─────────────────────┐ ┆
+└──────────────────┘                      │ ┆
+                                          │ ┆
+                                          │ ┆
+┌──────────────────┐                      │ ┆
+│ CardPayment      │                      │ ┆
+│ ───────────      │                      │ ┆
+│ +String lastFour │                      │ ┆
+│ +authorize()     │                      │ ┆
+│                  ├──────────────────────┘ ┆
+│                  ├─┄updates┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
+└──────────────────┘
diff --git a/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__er.snap b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__er.snap
new file mode 100644
index 0000000000000000000000000000000000000000..ca7699d1f0f3ab90bcb04034fd623466643ce9e5
--- /dev/null
+++ b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__er.snap
@@ -0,0 +1,45 @@
+---
+source: mermaid/src/families_tests.rs
+assertion_line: 107
+expression: output
+---
+┌─────────────────────────────────┐
+│ CUSTOMER                        │
+│ ────────                        │
+│ int id PK                       │
+│ string email UK                 │
+│ string name                     │
+│                                 ├──(1) places───────┐
+└─────────────────────────────────┘                   │
+                                                      │
+                                                      │
+┌─────────────────────────────────┐                   │
+│ ORDER                           │                   │
+│ ─────                           │                   │
+│ int id PK                       │                   │
+│ int customer_id FK              │                   │
+│ string status                   │                   │
+│                                 ├──(0..many)────────┘
+│                                 ├──(1) contains───────┐
+└─────────────────────────────────┘                     │
+                                                        │
+                                                        │
+┌─────────────────────────────────┐                     │
+│ LINE_ITEM                       │                     │
+│ ─────────                       │                     │
+│ int order_id PK, FK — order key │                     │
+│ int product_id PK, FK           │                     │
+│ int quantity                    │                     │
+│                                 ├──(1..many)──────────┘
+│                                 ├─┄(0..many)┄┄┄┄┄┄┄┄┄┄┄┄┐
+└─────────────────────────────────┘                       ┆
+                                                          ┆
+                                                          ┆
+┌─────────────────────────────────┐                       ┆
+│ PRODUCT                         │                       ┆
+│ ───────                         │                       ┆
+│ int id PK                       │                       ┆
+│ string name                     │                       ┆
+│ decimal price                   │                       ┆
+│                                 ├─┄(1) appears_in┄┄┄┄┄┄┄┘
+└─────────────────────────────────┘
diff --git a/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__sequence.snap b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__sequence.snap
new file mode 100644
index 0000000000000000000000000000000000000000..9646e74e1312c741b2936181540a0d4343757aae
--- /dev/null
+++ b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__sequence.snap
@@ -0,0 +1,60 @@
+---
+source: mermaid/src/families_tests.rs
+assertion_line: 107
+expression: output
+---
+          ┌───────────────┐         ┌───────────────┐         ┌───────────────┐         ┌───────────────┐
+          │ Buyer (actor) │         │ API           │         │ 库存          │         │ Payments      │
+          └───────────────┘         └───────────────┘         └───────────────┘         └───────────────┘
+                  │ Place order             │                         │                         │
+                  ├─────────────────────────▶                         │                         │
+                  │                         │                         │                         │
+                  │                         │ Reserve items           │                         │
+                  │                         ├─────────────────────────▶                         │
+                  │                         │                         │                         │
+                  │                         │ Reservation             │                         │
+                  │                         ◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤                         │
+                  │                         │                         │                         │
+┌─opt Items reserved───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│                 │                         │                         │                         │                                  │
+│                 │                         │                         │                         │                                  │
+│ ┌─loop Up to 3 attempts────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │
+│ │               │                         │                         │                         │                                │ │
+│ │               │                         │                         │                         │                                │ │
+│ │               │                         │ Charge card             │                         │                                │ │
+│ │               │                         ├─────────────────────────┼─────────────────────────▶                                │ │
+│ │               │                         │                         │                         │                                │ │
+│ │               │                         │                         │                         │ Check fraud                    │ │
+│ │               │                         │                         │                         ├───┐                            │ │
+│ │               │                         │                         │                         ◀───┘                            │ │
+│ │               │                         │                         │                         │                                │ │
+│ │               │                         │ Payment status          │                         │                                │ │
+│ │               │                         ◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤                                │ │
+│ │               │                         │                         │                         │                                │ │
+│ │ ┌─alt Approved─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ │             │                         ┌───────────────────────────────────────────────────┐                              │ │ │
+│ │ │             │                         │ Note: Payment recorded                            │                              │ │ │
+│ │ │             │                         └───────────────────────────────────────────────────┘                              │ │ │
+│ │ │             │ Order confirmed         │                         │                         │                              │ │ │
+│ │ │             ◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤                         │                         │                              │ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ ├─else Declined────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ │             │                         │ Release items           │                         │                              │ │ │
+│ │ │             │                         ├─────────────────────────▶                         │                              │ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ │             │ Payment failed          │                         │                         │                              │ │ │
+│ │ │             ◀┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┤                         │                         │                              │ │ │
+│ │ │             │                         │                         │                         │                              │ │ │
+│ │ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │ │
+│ │               │                         │                         │                         │                                │ │
+│ │               │                         │                         │                         │                                │ │
+│ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
+│                 │                         │                         │                         │                                  │
+│                 │                         │                         │                         │                                  │
+└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+                  │                         │                         │                         │
+                  │                         │                         │                         │
diff --git a/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__state.snap b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__state.snap
new file mode 100644
index 0000000000000000000000000000000000000000..23ccd97f5d6e83945f375f3ca12aad5463a829ce
--- /dev/null
+++ b/codex-rs/mermaid/src/snapshots/codex_mermaid__families_tests__state.snap
@@ -0,0 +1,70 @@
+---
+source: mermaid/src/families_tests.rs
+assertion_line: 100
+expression: output
+---
+┌─────────────────────┐
+│ Payment pending     │
+│ ───────────────     │
+│ Retry up to 3 times │
+│                     ├◄────────────────┐
+│                     ├──paid───────────╪───┐
+│                     ├──declined───────╪───╪─┐
+└─────────────────────┘                 │   │ │
+                                        │   │ │
+                                        │   │ │
+┌─────────────────────┐                 │   │ │
+│ ● initial           │                 │   │ │
+│                     ├─────────────┐   │   │ │
+└─────────────────────┘             │   │   │ │
+                                    │   │   │ │
+                                    │   │   │ │
+┌─────────────────────┐             │   │   │ │
+│ Draft               │             │   │   │ │
+│                     ├◄────────────┘   │   │ │
+│                     ├──submit───────┐ │   │ │
+│                     ├◄──────────────╪─╪───╪─╪───────┐
+└─────────────────────┘               │ │   │ │       │
+                                      │ │   │ │       │
+                                      │ │   │ │       │
+┌─────────────────────┐               │ │   │ │       │
+│ Validating          │               │ │   │ │       │
+│                     ├◄──────────────┘ │   │ │       │
+│                     ├──valid──────────┘   │ │       │
+│                     ├──invalid──────────┐ │ │       │
+└─────────────────────┘                   │ │ │       │
+                                          │ │ │       │
+                                          │ │ │       │
+┌─────────────────────┐                   │ │ │       │
+│ Rejected            │                   │ │ │       │
+│                     ├◄──────────────────┘ │ │       │
+│                     ├◄────────────────────╪─┘       │
+│                     ├──revise─────────────╪─────────┘
+└─────────────────────┘                     │
+                                            │
+                                            │
+┌─────────────────────┐                     │
+│ Packing             │                     │
+│                     ├◄────────────────────┘
+│                     ├──dispatch───────────────┐
+└─────────────────────┘                         │
+                                                │
+                                                │
+┌─────────────────────┐                         │
+│ Shipped             │                         │
+│                     ├◄────────────────────────┘
+│                     ├──received─────────────────┐
+└─────────────────────┘                           │
+                                                  │
+                                                  │
+┌─────────────────────┐                           │
+│ Delivered           │                           │
+│                     ├◄──────────────────────────┘
+│                     ├─────────────────────────────┐
+└─────────────────────┘                             │
+                                                    │
+                                                    │
+┌─────────────────────┐                             │
+│ ◎ final             │                             │
+│                     ├◄────────────────────────────┘
+└─────────────────────┘
diff --git a/codex-rs/mermaid/src/snapshots/codex_mermaid__tests__branches_merges_and_retry_loop.snap b/codex-rs/mermaid/src/snapshots/codex_mermaid__tests__branches_merges_and_retry_loop.snap
new file mode 100644
index 0000000000000000000000000000000000000000..70ceaeb6a06eec87b5e5d2becfddc0d9d6a46d58
--- /dev/null
+++ b/codex-rs/mermaid/src/snapshots/codex_mermaid__tests__branches_merges_and_retry_loop.snap
@@ -0,0 +1,61 @@
+---
+source: mermaid/src/tests.rs
+assertion_line: 10
+expression: "render(source, 100).unwrap()"
+---
+┌───────────────┐
+│ Checkout      │
+│               ├────────┐
+└───────────────┘        │
+                         │
+                         │
+┌───────────────┐        │
+│ ◇ In stock?   │        │
+│               ├◄───────┘
+│               ├──yes─────┐
+│               ├──no──────╪─┐
+└───────────────┘          │ │
+                           │ │
+                           │ │
+┌───────────────┐          │ │
+│ Reserve       │          │ │
+│               ├◄─────────┘ │
+│               ├────────────╪─┐
+└───────────────┘            │ │
+                             │ │
+                             │ │
+┌───────────────┐            │ │
+│ Waitlist      │            │ │
+│               ├◄───────────┘ │
+│               ├──────────────╪───────┐
+└───────────────┘              │       │
+                               │       │
+                               │       │
+┌───────────────┐              │       │
+│ ◇ Paid?       │              │       │
+│               ├◄─────────────┘       │
+│               ├──yes───────────┐     │
+│               ├──no────────────╪─┐   │
+│               ├◄───────────────╪─╪─┐ │
+└───────────────┘                │ │ │ │
+                                 │ │ │ │
+                                 │ │ │ │
+┌───────────────┐                │ │ │ │
+│ Ship          │                │ │ │ │
+│               ├◄───────────────┘ │ │ │
+│               ├──────────────────╪─╪─╪─┐
+└───────────────┘                  │ │ │ │
+                                   │ │ │ │
+                                   │ │ │ │
+┌───────────────┐                  │ │ │ │
+│ Retry payment │                  │ │ │ │
+│               ├◄─────────────────┘ │ │ │
+│               ├────────────────────┘ │ │
+└───────────────┘                      │ │
+                                       │ │
+                                       │ │
+┌───────────────┐                      │ │
+│ Notify buyer  │                      │ │
+│               ├◄─────────────────────┘ │
+│               ├◄───────────────────────┘
+└───────────────┘
diff --git a/codex-rs/mermaid/src/state.rs b/codex-rs/mermaid/src/state.rs
new file mode 100644
index 0000000000000000000000000000000000000000..077fd987bee02915c6c81376e95987012153c5aa
--- /dev/null
+++ b/codex-rs/mermaid/src/state.rs
@@ -0,0 +1,109 @@
+//! Flat state machines, with distinct initial/final pseudostates and labeled transitions.
+
+use super::Direction;
+use super::Edge;
+use super::Graph;
+use super::MAX_EDGES;
+use super::RenderError;
+use super::parse::check_label;
+use super::parse::identifier;
+
+pub(super) fn parse(body: &[&str]) -> Result<Graph, RenderError> {
+    let mut graph = Graph::default();
+    let mut direction = false;
+    for &line in body {
+        if matches!(line, "state" | "direction" | "note" | "end" | "hide") {
+            return Err(RenderError::Unsupported);
+        }
+        if let Some(value) = line.strip_prefix("direction ") {
+            if direction {
+                return Err(RenderError::Unsupported);
+            }
+            graph.direction = Direction::parse(value.trim())?;
+            direction = true;
+            continue;
+        }
+        let mut rest = line;
+        if let Some(after) = rest.strip_prefix("state \"") {
+            let (label, after) = after.split_once('"').ok_or(RenderError::Unsupported)?;
+            check_label(label)?;
+            rest = after
+                .trim_start()
+                .strip_prefix("as ")
+                .ok_or(RenderError::Unsupported)?;
+            let index = graph.node(identifier(&mut rest)?)?;
+            if !rest.trim().is_empty() || graph.nodes[index].declared {
+                return Err(RenderError::Unsupported);
+            }
+            graph.nodes[index].label = label.to_owned();
+            graph.nodes[index].declared = true;
+            continue;
+        }
+        let from = if let Some(after) = rest.strip_prefix("[*]") {
+            rest = after;
+            let index = graph.node("[initial]")?;
+            graph.nodes[index].label = "● initial".to_owned();
+            index
+        } else {
+            let id = identifier(&mut rest)?;
+            if (id.eq_ignore_ascii_case("accTitle") || id.eq_ignore_ascii_case("accDescr"))
+                && rest.trim_start().starts_with(':')
+            {
+                return Err(RenderError::Unsupported);
+            }
+            graph.node(id)?
+        };
+        rest = rest.trim();
+        if rest.is_empty() && graph.nodes[from].id != "[initial]" {
+            continue;
+        }
+        if let Some(description) = rest
+            .strip_prefix(':')
+            .filter(|text| !text.starts_with("::"))
+        {
+            if graph.nodes[from].id == "[initial]" {
+                return Err(RenderError::Unsupported);
+            }
+            let description = description.trim();
+            check_label(description)?;
+            if graph.nodes[from].members.len() == 16 {
+                return Err(RenderError::Limit);
+            }
+            graph.nodes[from].members.push(description.to_owned());
+            continue;
+        }
+        rest = rest
+            .strip_prefix("-->")
+            .ok_or(RenderError::Unsupported)?
+            .trim_start();
+        let to = if let Some(after) = rest.strip_prefix("[*]") {
+            rest = after;
+            let index = graph.node("[final]")?;
+            graph.nodes[index].label = "◎ final".to_owned();
+            index
+        } else {
+            graph.node(identifier(&mut rest)?)?
+        };
+        let label = if let Some(label) = rest
+            .trim()
+            .strip_prefix(':')
+            .filter(|text| !text.starts_with("::"))
+        {
+            let label = label.trim();
+            check_label(label)?;
+            label.to_owned()
+        } else if rest.trim().is_empty() {
+            String::new()
+        } else {
+            return Err(RenderError::Unsupported);
+        };
+        if graph.edges.len() == MAX_EDGES {
+            return Err(RenderError::Limit);
+        }
+        graph.edges.push(Edge::directed(from, to, label));
+    }
+    if graph.nodes.is_empty() {
+        return Err(RenderError::Unsupported);
+    }
+    Ok(graph)
+}
diff --git a/codex-rs/mermaid/src/tests.rs b/codex-rs/mermaid/src/tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7daf9935ca8b515cd6a67e720a1975104ee9c3e7
--- /dev/null
+++ b/codex-rs/mermaid/src/tests.rs
@@ -0,0 +1,193 @@
+use super::RenderError;
+use super::render;
+use insta::assert_snapshot;
+use pretty_assertions::assert_eq;
+use unicode_width::UnicodeWidthStr;
+
+#[test]
+fn branches_merges_and_retry_loop() {
+    let source = "flowchart TD\nA[Checkout] --> B{In stock?}\nB -->|yes| C[Reserve]\nB -->|no| D[Waitlist]\nC --> E{Paid?}\nE -->|yes| F[Ship]\nE -->|no| G[Retry payment]\nG --> E\nD --> H[Notify buyer]\nF --> H";
+    assert_snapshot!(render(source, /*max_width*/ 100).unwrap());
+}
+
+#[test]
+fn rejects_partial_or_unsupported_input() {
+    for source in [
+        "flowchart TD; subgraph X; A; end",
+        "flowchart TD; A --> B; garbage syntax",
+        "flowchart TD; A -.-> B",
+        "flowchart TD; A & B --> C",
+        "flowchart TD; A[one]; A[two]",
+        "flowchart TD; A[<b>HTML</b>]",
+        "flowchart TD; A[&#27;]",
+        "flowchart TD; A[\u{1b}]",
+        "flowchart TD; A[e\u{301}]",
+        "flowchart TD; A[👍🏽]",
+        "flowchart TD; A[👩\u{200d}💻]",
+        "flowchart TD; A[✈\u{fe0f}]",
+        "flowchart TD; A[zero\u{200b}width]",
+        "flowchart TD; A[left\u{202e}right]",
+        "flowchart TD; A[\u{2066}isolated\u{2069}]",
+        "flowchart TD; A[unclosed",
+        "flowchart TD; click A",
+        "flowchart TD; A((circle))",
+        "flowchart TD; A -->|unclosed B",
+        "flowchart TD; A[\"quoted\"]",
+        "flowchart TD; A[foo;bar]",
+        "flowchart TD; A[لا]",
+        "flowchart TD; A -->|yes┐| B",
+    ] {
+        assert_eq!(
+            render(source, /*max_width*/ 100),
+            Err(RenderError::Unsupported),
+            "{source:?}"
+        );
+    }
+}
+
+#[test]
+fn source_graph_and_width_limits() {
+    for source in [
+        " ".repeat(16 * 1024 + 1),
+        format!("graph TD; A[{}]", "x".repeat(41)),
+        format!(
+            "graph TD; {}",
+            (0..17).map(|n| format!("N{n};")).collect::<String>()
+        ),
+        format!("graph TD; {}", "A-->B;".repeat(25)),
+    ] {
+        assert_eq!(render(&source, /*max_width*/ 200), Err(RenderError::Limit));
+    }
+    let output = render("graph TD; A --> B", /*max_width*/ 100).unwrap();
+    let width = output.lines().map(UnicodeWidthStr::width).max().unwrap();
+    assert_eq!(render("graph TD; A --> B", width), Ok(output));
+    assert_eq!(
+        render("graph TD; A --> B", width - 1),
+        Err(RenderError::TooWide)
+    );
+    assert_eq!(
+        render("graph TD; A", /*max_width*/ 0),
+        Err(RenderError::TooWide)
+    );
+}
+
+#[test]
+fn reconstruct_every_edge_from_rendered_paths() {
+    // All 512 directed graphs on three nodes, including self-loops, cycles, fan-in and fan-out.
+    // Reconstruct connections from the emitted glyphs without consulting the renderer's layout.
+    for (mask, direction) in
+        (0u16..512).flat_map(|mask| ["TD", "BT", "LR", "RL"].map(|direction| (mask, direction)))
+    {
+        let mut source = format!("graph {direction}; A; B; C;");
+        let mut expected = Vec::new();
+        for from in 0..3 {
+            for to in 0..3 {
+                if mask & (1 << (from * 3 + to)) != 0 {
+                    let a = char::from(b'A' + from);
+                    let b = char::from(b'A' + to);
+                    source.push_str(&format!("{a}-->{b};"));
+                    expected.push((a, b));
+                }
+            }
+        }
+        let output = render(&source, /*max_width*/ 100).unwrap();
+        let mut rows = output
+            .lines()
+            .map(|line| line.chars().collect::<Vec<_>>())
+            .collect::<Vec<_>>();
+        if matches!(direction, "LR" | "RL") {
+            let width = rows.iter().map(Vec::len).max().unwrap();
+            rows = (0..width)
+                .map(|x| {
+                    rows.iter()
+                        .map(|row| match row.get(x).copied().unwrap_or(' ') {
+                            '─' => '│',
+                            '│' => '─',
+                            '┐' => '└',
+                            '└' => '┐',
+                            '┬' => '├',
+                            '▲' => '◄',
+                            other => other,
+                        })
+                        .collect()
+                })
+                .collect();
+        }
+        let mut order = Vec::new();
+        let mut owners = vec![' '; rows.len()];
+        for (top, row) in rows.iter().enumerate() {
+            if row.first() != Some(&'┌') {
+                continue;
+            }
+            let bottom = (top + 1..rows.len())
+                .find(|y| rows[*y].first() == Some(&'└'))
+                .unwrap();
+            let owner = rows[top..=bottom]
+                .iter()
+                .flatten()
+                .find(|ch| matches!(ch, 'A' | 'B' | 'C'))
+                .unwrap();
+            owners[top..=bottom].fill(*owner);
+            order.push(*owner);
+        }
+        assert_eq!(
+            order,
+            if matches!(direction, "BT" | "RL") {
+                vec!['C', 'B', 'A']
+            } else {
+                vec!['A', 'B', 'C']
+            }
+        );
+        let mut actual = Vec::new();
+        for (y, row) in rows.iter().enumerate() {
+            if let Some(port) = row.windows(2).position(|pair| pair == ['├', '─']) {
+                let lane = (port + 1..row.len())
+                    .find(|x| matches!(row[*x], '┐' | '┘'))
+                    .unwrap();
+                let mut target = y;
+                loop {
+                    target = if row[lane] == '┐' {
+                        target + 1
+                    } else {
+                        target - 1
+                    };
+                    let ch = rows[target][lane];
+                    if matches!(ch, '┘' | '┐') {
+                        break;
+                    }
+                    assert!(matches!(ch, '│' | '╪'), "broken vertical path: {source}");
+                }
+                assert_eq!(&rows[target][port..port + 2], &['├', '◄']);
+                assert!(
+                    rows[target][port + 2..lane]
+                        .iter()
+                        .all(|ch| matches!(ch, '─' | '╪'))
+                );
+                actual.push((owners[y], owners[target]));
+            }
+        }
+        actual.sort_unstable();
+        assert_eq!(actual, expected, "{source}");
+    }
+}
+
+#[test]
+fn semantic_spans_distinguish_labels_from_matching_endpoint_glyphs() {
+    use super::Role;
+
+    let lines = super::render_spans("sequenceDiagram; A-xB: x", /*max_width*/ 100).unwrap();
+    let roles = lines
+        .iter()
+        .flatten()
+        .flat_map(|span| span.text.chars().filter(|ch| *ch == 'x').map(|_| span.role))
+        .collect::<Vec<_>>();
+    assert_eq!(roles, vec![Role::Text, Role::Edge]);
+    assert_eq!(
+        lines[0]
+            .iter()
+            .find(|span| span.text.contains('┌'))
+            .unwrap()
+            .role,
+        Role::Node
+    );
+}
diff --git a/codex-rs/model-provider-info/src/lib.rs b/codex-rs/model-provider-info/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9c27b15cc4800fbc8138423806e5e794122a211e
--- /dev/null
+++ b/codex-rs/model-provider-info/src/lib.rs
@@ -0,0 +1,710 @@
+//! Registry of model providers supported by Codex.
+//!
+//! Providers can be defined in two places:
+//!   1. Built-in defaults compiled into the binary so Codex works out-of-the-box.
+//!   2. User-defined entries inside `~/.codex/config.toml` under the `model_providers`
+//!      key. These override or extend the defaults at runtime.
+
+use codex_api::Provider as ApiProvider;
+use codex_api::RetryConfig as ApiRetryConfig;
+use codex_protocol::auth::AuthMode;
+use codex_protocol::config_types::ModelProviderAuthInfo;
+use codex_protocol::error::CodexErr;
+use codex_protocol::error::EnvVarError;
+use codex_protocol::error::Result as CodexResult;
+use codex_utils_redacted_string::RedactedString;
+use http::HeaderMap;
+use http::header::HeaderName;
+use http::header::HeaderValue;
+use schemars::JsonSchema;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::fmt;
+use std::num::NonZeroU64;
+use std::path::Component;
+use std::path::Path;
+use std::time::Duration;
+
+const DEFAULT_STREAM_IDLE_TIMEOUT_MS: u64 = 300_000;
+const DEFAULT_STREAM_MAX_RETRIES: u64 = 5;
+const DEFAULT_REQUEST_MAX_RETRIES: u64 = 4;
+const DEFAULT_AWS_CREDENTIAL_EXPORT_TIMEOUT_MS: u64 = 30_000;
+const DEFAULT_AWS_AUTH_REFRESH_TIMEOUT_MS: u64 = 300_000;
+pub const DEFAULT_WEBSOCKET_CONNECT_TIMEOUT_MS: u64 = 15_000;
+/// Hard cap for user-configured `stream_max_retries`.
+const MAX_STREAM_MAX_RETRIES: u64 = 100;
+/// Hard cap for user-configured `request_max_retries`.
+const MAX_REQUEST_MAX_RETRIES: u64 = 100;
+
+const OPENAI_PROVIDER_NAME: &str = "OpenAI";
+const OPENAI_ACTOR_AUTHORIZATION_HEADER: &str = "x-openai-actor-authorization";
+pub const OPENAI_PROVIDER_ID: &str = "openai";
+pub const CHATGPT_CODEX_BASE_URL: &str = "https://chatgpt.com/backend-api/codex";
+const AMAZON_BEDROCK_PROVIDER_NAME: &str = "Amazon Bedrock";
+pub const AMAZON_BEDROCK_PROVIDER_ID: &str = "amazon-bedrock";
+const AMAZON_BEDROCK_RUNTIME_PROVIDER_NAME: &str = "Amazon Bedrock Runtime";
+pub const AMAZON_BEDROCK_RUNTIME_PROVIDER_ID: &str = "amazon-bedrock-runtime";
+pub const AMAZON_BEDROCK_GPT_5_5_MODEL_ID: &str = "openai.gpt-5.5";
+pub const AMAZON_BEDROCK_GPT_5_4_MODEL_ID: &str = "openai.gpt-5.4";
+pub const AMAZON_BEDROCK_GPT_5_6_SOL_MODEL_ID: &str = "openai.gpt-5.6-sol";
+pub const AMAZON_BEDROCK_GPT_6_ASTRA_MODEL_ID: &str = "openai.gpt-6-astra";
+pub const AMAZON_BEDROCK_GPT_5_6_TERRA_MODEL_ID: &str = "openai.gpt-5.6-terra";
+pub const AMAZON_BEDROCK_GPT_5_6_LUNA_MODEL_ID: &str = "openai.gpt-5.6-luna";
+pub const AMAZON_BEDROCK_RUNTIME_GLOBAL_GPT_5_6_TERRA_MODEL_ID: &str =
+    "global.openai.gpt-5.6-terra";
+pub const AMAZON_BEDROCK_RUNTIME_GLOBAL_GPT_5_6_LUNA_MODEL_ID: &str = "global.openai.gpt-5.6-luna";
+pub const AMAZON_BEDROCK_DEFAULT_BASE_URL: &str =
+    "https://bedrock-mantle.us-east-1.api.aws/openai/v1";
+const AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_HEADER: &str = "x-amzn-mantle-client-agent";
+const AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_VALUE: &str = "codex";
+const CHAT_WIRE_API_REMOVED_ERROR: &str = "`wire_api = \"chat\"` is no longer supported.\nHow to fix: set `wire_api = \"responses\"` in your provider config.\nMore info: https://github.com/openai/codex/discussions/7782";
+pub const LEGACY_OLLAMA_CHAT_PROVIDER_ID: &str = "ollama-chat";
+pub const OLLAMA_CHAT_PROVIDER_REMOVED_ERROR: &str = "`ollama-chat` is no longer supported.\nHow to fix: replace `ollama-chat` with `ollama` in `model_provider`, `oss_provider`, or `--local-provider`.\nMore info: https://github.com/openai/codex/discussions/7782";
+
+/// Wire protocol that the provider speaks.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum WireApi {
+    /// The Responses API exposed by OpenAI at `/v1/responses`.
+    #[default]
+    Responses,
+}
+
+impl fmt::Display for WireApi {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let value = match self {
+            Self::Responses => "responses",
+        };
+        f.write_str(value)
+    }
+}
+
+impl<'de> Deserialize<'de> for WireApi {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let value = String::deserialize(deserializer)?;
+        match value.as_str() {
+            "responses" => Ok(Self::Responses),
+            "chat" => Err(serde::de::Error::custom(CHAT_WIRE_API_REMOVED_ERROR)),
+            _ => Err(serde::de::Error::unknown_variant(&value, &["responses"])),
+        }
+    }
+}
+
+/// Serializable representation of a provider definition.
+#[derive(Debug, Clone, Default, Deserialize, Serialize, PartialEq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ModelProviderInfo {
+    /// Friendly display name.
+    #[serde(default)]
+    pub name: String,
+    /// Base URL for the provider's OpenAI-compatible API.
+    pub base_url: Option<String>,
+    /// Environment variable that stores the user's API key for this provider.
+    pub env_key: Option<String>,
+
+    /// Optional instructions to help the user get a valid value for the
+    /// variable and set it.
+    pub env_key_instructions: Option<String>,
+    /// Value to use with `Authorization: Bearer <token>` header. Use of this
+    /// config is discouraged in favor of `env_key` for security reasons, but
+    /// this may be necessary when using this programmatically.
+    pub experimental_bearer_token: Option<RedactedString>,
+    /// Command-backed bearer-token configuration for this provider.
+    pub auth: Option<ModelProviderAuthInfo>,
+    /// AWS SigV4 auth configuration for this provider.
+    pub aws: Option<ModelProviderAwsAuthInfo>,
+    /// Which wire protocol this provider expects.
+    #[serde(default)]
+    pub wire_api: WireApi,
+    /// Optional query parameters to append to the base URL.
+    pub query_params: Option<HashMap<String, RedactedString>>,
+    /// Additional HTTP headers to include in requests to this provider where
+    /// the (key, value) pairs are the header name and value.
+    pub http_headers: Option<HashMap<String, RedactedString>>,
+    /// Optional HTTP headers to include in requests to this provider where the
+    /// (key, value) pairs are the header name and _environment variable_ whose
+    /// value should be used. If the environment variable is not set, or the
+    /// value is empty, the header will not be included in the request.
+    pub env_http_headers: Option<HashMap<String, String>>,
+    /// Maximum number of times to retry a failed HTTP request to this provider.
+    pub request_max_retries: Option<u64>,
+    /// Number of times to retry reconnecting a dropped streaming response before failing.
+    pub stream_max_retries: Option<u64>,
+    /// Idle timeout (in milliseconds) to wait for activity on a streaming response before treating
+    /// the connection as lost.
+    pub stream_idle_timeout_ms: Option<u64>,
+    /// Maximum time (in milliseconds) to wait for a websocket connection attempt before treating
+    /// it as failed.
+    pub websocket_connect_timeout_ms: Option<u64>,
+    /// Does this provider require an OpenAI API Key or ChatGPT login token? If true,
+    /// user is presented with login screen on first run, and login preference and token/key
+    /// are stored in auth.json. If false (which is the default), login screen is skipped,
+    /// and API key (if needed) comes from the "env_key" environment variable.
+    #[serde(default)]
+    pub requires_openai_auth: bool,
+    /// Whether this provider supports the Responses API WebSocket transport.
+    #[serde(default)]
+    pub supports_websockets: bool,
+    /// Whether this provider supports the standalone web-search endpoint.
+    #[serde(default)]
+    pub supports_standalone_web_search: bool,
+}
+
+/// AWS SigV4 auth configuration for a model provider.
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct ModelProviderAwsAuthInfo {
+    /// AWS profile name to use. When unset, the AWS SDK default chain decides.
+    pub profile: Option<String>,
+    /// AWS region to use for provider-specific endpoints.
+    pub region: Option<String>,
+    /// Optional command whose exported credentials replace the AWS SDK credential chain.
+    pub credential_export: Option<AwsCredentialExportConfig>,
+    /// Optional command used to reauthenticate after a refreshable AWS auth failure.
+    pub auth_refresh: Option<AwsAuthRefreshConfig>,
+}
+
+/// Command used to export AWS signing credentials for a model provider.
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AwsCredentialExportConfig {
+    /// Executable to invoke directly, without a shell.
+    pub command: String,
+    /// Arguments passed to the credential export command.
+    #[serde(default)]
+    pub args: Vec<RedactedString>,
+    /// Maximum time to wait for the credential export command to complete.
+    #[serde(default = "default_aws_credential_export_timeout_ms")]
+    pub timeout_ms: NonZeroU64,
+}
+
+impl AwsCredentialExportConfig {
+    pub fn timeout(&self) -> Duration {
+        Duration::from_millis(self.timeout_ms.get())
+    }
+}
+
+fn default_aws_credential_export_timeout_ms() -> NonZeroU64 {
+    match NonZeroU64::new(DEFAULT_AWS_CREDENTIAL_EXPORT_TIMEOUT_MS) {
+        Some(timeout_ms) => timeout_ms,
+        None => panic!("AWS credential export timeout must be non-zero"),
+    }
+}
+
+/// Command used to refresh AWS credentials for a model provider.
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, JsonSchema)]
+#[schemars(deny_unknown_fields)]
+pub struct AwsAuthRefreshConfig {
+    /// Executable to invoke directly, without a shell.
+    pub command: String,
+    /// Arguments passed to the refresh command.
+    #[serde(default)]
+    pub args: Vec<RedactedString>,
+    /// Maximum time to wait for the refresh command to complete.
+    #[serde(default = "default_aws_auth_refresh_timeout_ms")]
+    pub timeout_ms: NonZeroU64,
+}
+
+impl AwsAuthRefreshConfig {
+    pub fn timeout(&self) -> Duration {
+        Duration::from_millis(self.timeout_ms.get())
+    }
+}
+
+fn default_aws_auth_refresh_timeout_ms() -> NonZeroU64 {
+    match NonZeroU64::new(DEFAULT_AWS_AUTH_REFRESH_TIMEOUT_MS) {
+        Some(timeout_ms) => timeout_ms,
+        None => panic!("AWS auth refresh timeout must be non-zero"),
+    }
+}
+
+impl ModelProviderInfo {
+    /// Checks that a configured Bedrock entry only customizes supported fields.
+    /// Call this on the override before merging it with the built-in provider.
+    pub fn validate_bedrock_override(&self) -> Result<(), String> {
+        let unsupported_fields = Self {
+            base_url: None,
+            auth: None,
+            aws: None,
+            http_headers: None,
+            ..self.clone()
+        };
+        if unsupported_fields != Self::default() {
+            return Err("only supports changing \
+`base_url`, `auth`, `http_headers`, `aws.profile`, `aws.region`, `aws.credential_export`, \
+and `aws.auth_refresh`; \
+other non-default provider fields are not supported"
+                .to_string());
+        }
+        Ok(())
+    }
+
+    pub fn validate(&self) -> std::result::Result<(), String> {
+        if let Some(aws) = self.aws.as_ref() {
+            if self.supports_websockets {
+                // TODO(celia-oai): Support AWS SigV4 signing for WebSocket
+                // upgrade requests before allowing AWS-authenticated providers
+                // to enable Responses-over-WebSocket.
+                return Err("provider aws cannot be combined with supports_websockets".to_string());
+            }
+
+            let mut conflicts = Vec::new();
+            if self.env_key.is_some() {
+                conflicts.push("env_key");
+            }
+            if self.experimental_bearer_token.is_some() {
+                conflicts.push("experimental_bearer_token");
+            }
+            if self.auth.is_some() {
+                conflicts.push("auth");
+            }
+            if self.requires_openai_auth {
+                conflicts.push("requires_openai_auth");
+            }
+
+            if !conflicts.is_empty() {
+                return Err(format!(
+                    "provider aws cannot be combined with {}",
+                    conflicts.join(", ")
+                ));
+            }
+
+            if let Some(credential_export) = aws.credential_export.as_ref() {
+                if aws.profile.is_some() {
+                    return Err(
+                        "provider aws.credential_export cannot be combined with aws.profile"
+                            .to_string(),
+                    );
+                }
+                if credential_export.command.trim().is_empty() {
+                    return Err(
+                        "provider aws.credential_export.command must not be empty".to_string()
+                    );
+                }
+                let command = Path::new(&credential_export.command);
+                let mut components = command.components();
+                let is_bare_command = matches!(
+                    (components.next(), components.next()),
+                    (Some(Component::Normal(name)), None) if name == command.as_os_str()
+                );
+                if !command.is_absolute() && !is_bare_command {
+                    return Err(
+                        "provider aws.credential_export.command must be an absolute path or a bare executable name"
+                            .to_string(),
+                    );
+                }
+            }
+
+            if let Some(auth_refresh) = aws.auth_refresh.as_ref() {
+                if auth_refresh.command.trim().is_empty() {
+                    return Err("provider aws.auth_refresh.command must not be empty".to_string());
+                }
+                if auth_refresh.command != "aws" {
+                    return Err("provider aws.auth_refresh.command must be `aws`".to_string());
+                }
+            }
+        }
+
+        let Some(auth) = self.auth.as_ref() else {
+            return Ok(());
+        };
+
+        if auth.command.trim().is_empty() {
+            return Err("provider auth.command must not be empty".to_string());
+        }
+
+        let mut conflicts = Vec::new();
+        if self.env_key.is_some() {
+            conflicts.push("env_key");
+        }
+        if self.experimental_bearer_token.is_some() {
+            conflicts.push("experimental_bearer_token");
+        }
+        if self.requires_openai_auth {
+            conflicts.push("requires_openai_auth");
+        }
+
+        if conflicts.is_empty() {
+            Ok(())
+        } else {
+            Err(format!(
+                "provider auth cannot be combined with {}",
+                conflicts.join(", ")
+            ))
+        }
+    }
+
+    fn build_header_map(&self) -> CodexResult<HeaderMap> {
+        let capacity = self.http_headers.as_ref().map_or(0, HashMap::len)
+            + self.env_http_headers.as_ref().map_or(0, HashMap::len);
+        let mut headers = HeaderMap::with_capacity(capacity);
+        if let Some(extra) = &self.http_headers {
+            for (k, v) in extra {
+                if let (Ok(name), Ok(value)) =
+                    (HeaderName::try_from(k), HeaderValue::try_from(v.as_str()))
+                {
+                    headers.insert(name, value);
+                }
+            }
+        }
+
+        if let Some(env_headers) = &self.env_http_headers {
+            for (header, env_var) in env_headers {
+                if let Ok(val) = std::env::var(env_var)
+                    && !val.trim().is_empty()
+                    && let (Ok(name), Ok(value)) =
+                        (HeaderName::try_from(header), HeaderValue::try_from(val))
+                {
+                    headers.insert(name, value);
+                }
+            }
+        }
+
+        Ok(headers)
+    }
+
+    pub fn to_api_provider(&self, auth_mode: Option<AuthMode>) -> CodexResult<ApiProvider> {
+        let default_base_url = if matches!(
+            auth_mode,
+            Some(
+                AuthMode::Chatgpt
+                    | AuthMode::ChatgptAuthTokens
+                    | AuthMode::Headers
+                    | AuthMode::AgentIdentity
+                    | AuthMode::PersonalAccessToken
+            )
+        ) {
+            CHATGPT_CODEX_BASE_URL
+        } else {
+            "https://api.openai.com/v1"
+        };
+        let base_url = self
+            .base_url
+            .clone()
+            .unwrap_or_else(|| default_base_url.to_string());
+
+        let headers = self.build_header_map()?;
+        let retry = ApiRetryConfig {
+            max_attempts: self.request_max_retries(),
+            base_delay: Duration::from_millis(200),
+            retry_429: false,
+            retry_5xx: true,
+            retry_transport: true,
+        };
+
+        Ok(ApiProvider {
+            name: self.name.clone(),
+            base_url,
+            query_params: self.query_params.clone().map(|params| {
+                params
+                    .into_iter()
+                    .map(|(name, value)| (name, value.into_inner()))
+                    .collect()
+            }),
+            headers,
+            retry,
+            stream_idle_timeout: self.stream_idle_timeout(),
+        })
+    }
+
+    /// If `env_key` is Some, returns the API key for this provider if present
+    /// (and non-empty) in the environment. If `env_key` is required but
+    /// cannot be found, returns an error.
+    pub fn api_key(&self) -> CodexResult<Option<String>> {
+        match &self.env_key {
+            Some(env_key) => {
+                let api_key = std::env::var(env_key)
+                    .ok()
+                    .filter(|v| !v.trim().is_empty())
+                    .ok_or_else(|| {
+                        CodexErr::EnvVar(EnvVarError {
+                            var: env_key.clone(),
+                            instructions: self.env_key_instructions.clone(),
+                        })
+                    })?;
+                Ok(Some(api_key))
+            }
+            None => Ok(None),
+        }
+    }
+
+    /// Effective maximum number of request retries for this provider.
+    pub fn request_max_retries(&self) -> u64 {
+        self.request_max_retries
+            .unwrap_or(DEFAULT_REQUEST_MAX_RETRIES)
+            .min(MAX_REQUEST_MAX_RETRIES)
+    }
+
+    /// Effective maximum number of stream reconnection attempts for this provider.
+    pub fn stream_max_retries(&self) -> u64 {
+        self.stream_max_retries
+            .unwrap_or(DEFAULT_STREAM_MAX_RETRIES)
+            .min(MAX_STREAM_MAX_RETRIES)
+    }
+
+    /// Effective idle timeout for streaming responses.
+    pub fn stream_idle_timeout(&self) -> Duration {
+        self.stream_idle_timeout_ms
+            .map(Duration::from_millis)
+            .unwrap_or(Duration::from_millis(DEFAULT_STREAM_IDLE_TIMEOUT_MS))
+    }
+
+    /// Effective timeout for websocket connect attempts.
+    pub fn websocket_connect_timeout(&self) -> Duration {
+        self.websocket_connect_timeout_ms
+            .map(Duration::from_millis)
+            .unwrap_or(Duration::from_millis(DEFAULT_WEBSOCKET_CONNECT_TIMEOUT_MS))
+    }
+
+    pub fn create_openai_provider(base_url: Option<String>) -> ModelProviderInfo {
+        ModelProviderInfo {
+            name: OPENAI_PROVIDER_NAME.into(),
+            base_url,
+            env_key: None,
+            env_key_instructions: None,
+            experimental_bearer_token: None,
+            auth: None,
+            aws: None,
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: Some(
+                [("version".to_string(), env!("CARGO_PKG_VERSION").into())]
+                    .into_iter()
+                    .collect(),
+            ),
+            env_http_headers: Some(
+                [
+                    (
+                        "OpenAI-Organization".to_string(),
+                        "OPENAI_ORGANIZATION".to_string(),
+                    ),
+                    ("OpenAI-Project".to_string(), "OPENAI_PROJECT".to_string()),
+                ]
+                .into_iter()
+                .collect(),
+            ),
+            // Use global defaults for retry/timeout unless overridden in config.toml.
+            request_max_retries: None,
+            stream_max_retries: None,
+            stream_idle_timeout_ms: None,
+            websocket_connect_timeout_ms: None,
+            requires_openai_auth: true,
+            supports_websockets: true,
+            supports_standalone_web_search: true,
+        }
+    }
+
+    pub fn create_amazon_bedrock_provider(
+        aws: Option<ModelProviderAwsAuthInfo>,
+    ) -> ModelProviderInfo {
+        ModelProviderInfo {
+            name: AMAZON_BEDROCK_PROVIDER_NAME.into(),
+            // The runtime provider derives the regional Mantle endpoint when
+            // this is unset. A configured value is therefore unambiguously an
+            // endpoint override.
+            base_url: None,
+            env_key: None,
+            env_key_instructions: None,
+            experimental_bearer_token: None,
+            auth: None,
+            aws: Some(aws.unwrap_or(ModelProviderAwsAuthInfo {
+                profile: None,
+                region: None,
+                credential_export: None,
+                auth_refresh: None,
+            })),
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: Some(HashMap::from([(
+                AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_HEADER.to_string(),
+                AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_VALUE.into(),
+            )])),
+            env_http_headers: None,
+            request_max_retries: None,
+            stream_max_retries: None,
+            stream_idle_timeout_ms: None,
+            websocket_connect_timeout_ms: None,
+            requires_openai_auth: false,
+            supports_websockets: false,
+            supports_standalone_web_search: false,
+        }
+    }
+
+    pub fn create_amazon_bedrock_runtime_provider(
+        aws: Option<ModelProviderAwsAuthInfo>,
+    ) -> ModelProviderInfo {
+        let mut provider = Self::create_amazon_bedrock_provider(aws);
+        provider.name = AMAZON_BEDROCK_RUNTIME_PROVIDER_NAME.into();
+        provider.http_headers = None;
+        provider
+    }
+
+    pub fn is_openai(&self) -> bool {
+        self.name == OPENAI_PROVIDER_NAME
+    }
+
+    pub fn supports_codex_backend_routes(&self) -> bool {
+        self.is_openai()
+            && self.base_url.as_deref().is_none_or(|base_url| {
+                base_url
+                    .trim_end_matches('/')
+                    .ends_with("/backend-api/codex")
+            })
+    }
+
+    pub fn uses_openai_actor_authorization(&self) -> bool {
+        !self.requires_openai_auth
+            && self.http_headers.as_ref().is_some_and(|headers| {
+                headers.iter().any(|(name, value)| {
+                    name.eq_ignore_ascii_case(OPENAI_ACTOR_AUTHORIZATION_HEADER)
+                        && !value.trim().is_empty()
+                })
+            })
+    }
+
+    pub fn is_amazon_bedrock(&self) -> bool {
+        self.name == AMAZON_BEDROCK_PROVIDER_NAME
+            || self.name == AMAZON_BEDROCK_RUNTIME_PROVIDER_NAME
+    }
+
+    pub fn is_amazon_bedrock_runtime(&self) -> bool {
+        self.name == AMAZON_BEDROCK_RUNTIME_PROVIDER_NAME
+    }
+
+    pub fn has_command_auth(&self) -> bool {
+        self.auth.is_some()
+    }
+}
+
+pub const DEFAULT_LMSTUDIO_PORT: u16 = 1234;
+pub const DEFAULT_OLLAMA_PORT: u16 = 11434;
+
+pub const LMSTUDIO_OSS_PROVIDER_ID: &str = "lmstudio";
+pub const OLLAMA_OSS_PROVIDER_ID: &str = "ollama";
+
+/// Built-in default provider list.
+pub fn built_in_model_providers(
+    openai_base_url: Option<String>,
+) -> HashMap<String, ModelProviderInfo> {
+    use ModelProviderInfo as P;
+    let openai_provider = P::create_openai_provider(openai_base_url);
+    let amazon_bedrock_provider = P::create_amazon_bedrock_provider(/*aws*/ None);
+    let amazon_bedrock_runtime_provider =
+        P::create_amazon_bedrock_runtime_provider(/*aws*/ None);
+
+    // We do not want to be in the business of adjucating which third-party
+    // providers are bundled with Codex CLI, so we only include the OpenAI and
+    // open source ("oss") providers by default. Users are encouraged to add to
+    // `model_providers` in config.toml to add their own providers.
+    [
+        (OPENAI_PROVIDER_ID, openai_provider),
+        (AMAZON_BEDROCK_PROVIDER_ID, amazon_bedrock_provider),
+        (
+            AMAZON_BEDROCK_RUNTIME_PROVIDER_ID,
+            amazon_bedrock_runtime_provider,
+        ),
+        (
+            OLLAMA_OSS_PROVIDER_ID,
+            create_oss_provider(DEFAULT_OLLAMA_PORT, WireApi::Responses),
+        ),
+        (
+            LMSTUDIO_OSS_PROVIDER_ID,
+            create_oss_provider(DEFAULT_LMSTUDIO_PORT, WireApi::Responses),
+        ),
+    ]
+    .into_iter()
+    .map(|(k, v)| (k.to_string(), v))
+    .collect()
+}
+
+/// Merge configured providers into the built-in provider catalog.
+///
+/// Configured providers extend the built-in set. Built-in providers are not
+/// generally overridable, but built-in Amazon Bedrock providers allow the user
+/// to customize their endpoint, authentication, headers, and AWS settings.
+pub fn merge_configured_model_providers(
+    mut model_providers: HashMap<String, ModelProviderInfo>,
+    configured_model_providers: HashMap<String, ModelProviderInfo>,
+) -> Result<HashMap<String, ModelProviderInfo>, String> {
+    for (key, mut provider) in configured_model_providers {
+        if matches!(
+            key.as_str(),
+            AMAZON_BEDROCK_PROVIDER_ID | AMAZON_BEDROCK_RUNTIME_PROVIDER_ID
+        ) {
+            provider
+                .validate_bedrock_override()
+                .map_err(|message| format!("model_providers.{key} {message}"))?;
+            let base_url_override = provider.base_url.take();
+            let auth_override = provider.auth.take();
+            let aws_override = provider.aws.take();
+            let http_headers_override = provider.http_headers.take();
+            if let Some(built_in_provider) = model_providers.get_mut(&key) {
+                built_in_provider.base_url = base_url_override;
+                built_in_provider.auth = auth_override;
+                if let Some(aws_override) = aws_override {
+                    built_in_provider.aws = Some(aws_override);
+                }
+                if let Some(http_headers_override) = http_headers_override {
+                    built_in_provider
+                        .http_headers
+                        .get_or_insert_default()
+                        .extend(http_headers_override);
+                }
+            }
+        } else {
+            model_providers.entry(key).or_insert(provider);
+        }
+    }
+
+    Ok(model_providers)
+}
+
+pub fn create_oss_provider(default_provider_port: u16, wire_api: WireApi) -> ModelProviderInfo {
+    // These CODEX_OSS_ environment variables are experimental: we may
+    // switch to reading values from config.toml instead.
+    let default_codex_oss_base_url = format!(
+        "http://localhost:{codex_oss_port}/v1",
+        codex_oss_port = std::env::var("CODEX_OSS_PORT")
+            .ok()
+            .filter(|value| !value.trim().is_empty())
+            .and_then(|value| value.parse::<u16>().ok())
+            .unwrap_or(default_provider_port)
+    );
+
+    let codex_oss_base_url = std::env::var("CODEX_OSS_BASE_URL")
+        .ok()
+        .filter(|v| !v.trim().is_empty())
+        .unwrap_or(default_codex_oss_base_url);
+    create_oss_provider_with_base_url(&codex_oss_base_url, wire_api)
+}
+
+pub fn create_oss_provider_with_base_url(base_url: &str, wire_api: WireApi) -> ModelProviderInfo {
+    ModelProviderInfo {
+        name: "gpt-oss".into(),
+        base_url: Some(base_url.into()),
+        env_key: None,
+        env_key_instructions: None,
+        experimental_bearer_token: None,
+        auth: None,
+        aws: None,
+        wire_api,
+        query_params: None,
+        http_headers: None,
+        env_http_headers: None,
+        request_max_retries: None,
+        stream_max_retries: None,
+        stream_idle_timeout_ms: None,
+        websocket_connect_timeout_ms: None,
+        requires_openai_auth: false,
+        supports_websockets: false,
+        supports_standalone_web_search: false,
+    }
+}
+
+#[cfg(test)]
+#[path = "model_provider_info_tests.rs"]
+mod tests;
diff --git a/codex-rs/model-provider-info/src/model_provider_info_tests.rs b/codex-rs/model-provider-info/src/model_provider_info_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8e13869cb2fc22c11be79c4e9a8adc7f794d921f
--- /dev/null
+++ b/codex-rs/model-provider-info/src/model_provider_info_tests.rs
@@ -0,0 +1,764 @@
+use super::*;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::AbsolutePathBufGuard;
+use pretty_assertions::assert_eq;
+use std::num::NonZeroU64;
+use tempfile::tempdir;
+
+#[test]
+fn test_deserialize_ollama_model_provider_toml() {
+    let azure_provider_toml = r#"
+name = "Ollama"
+base_url = "http://localhost:11434/v1"
+        "#;
+    let expected_provider = ModelProviderInfo {
+        name: "Ollama".into(),
+        base_url: Some("http://localhost:11434/v1".into()),
+        env_key: None,
+        env_key_instructions: None,
+        experimental_bearer_token: None,
+        auth: None,
+        aws: None,
+        wire_api: WireApi::Responses,
+        query_params: None,
+        http_headers: None,
+        env_http_headers: None,
+        request_max_retries: None,
+        stream_max_retries: None,
+        stream_idle_timeout_ms: None,
+        websocket_connect_timeout_ms: None,
+        requires_openai_auth: false,
+        supports_websockets: false,
+        supports_standalone_web_search: false,
+    };
+
+    let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
+    assert_eq!(expected_provider, provider);
+}
+
+#[test]
+fn test_deserialize_azure_model_provider_toml() {
+    let azure_provider_toml = r#"
+name = "Azure"
+base_url = "https://xxxxx.openai.azure.com/openai"
+env_key = "AZURE_OPENAI_API_KEY"
+query_params = { api-version = "2025-04-01-preview" }
+        "#;
+    let expected_provider = ModelProviderInfo {
+        name: "Azure".into(),
+        base_url: Some("https://xxxxx.openai.azure.com/openai".into()),
+        env_key: Some("AZURE_OPENAI_API_KEY".into()),
+        env_key_instructions: None,
+        experimental_bearer_token: None,
+        auth: None,
+        aws: None,
+        wire_api: WireApi::Responses,
+        query_params: Some(maplit::hashmap! {
+            "api-version".to_string() => "2025-04-01-preview".into(),
+        }),
+        http_headers: None,
+        env_http_headers: None,
+        request_max_retries: None,
+        stream_max_retries: None,
+        stream_idle_timeout_ms: None,
+        websocket_connect_timeout_ms: None,
+        requires_openai_auth: false,
+        supports_websockets: false,
+        supports_standalone_web_search: false,
+    };
+
+    let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
+    assert_eq!(expected_provider, provider);
+}
+
+#[test]
+fn test_deserialize_example_model_provider_toml() {
+    let azure_provider_toml = r#"
+name = "Example"
+base_url = "https://example.com"
+env_key = "API_KEY"
+http_headers = { "X-Example-Header" = "example-value" }
+env_http_headers = { "X-Example-Env-Header" = "EXAMPLE_ENV_VAR" }
+supports_standalone_web_search = true
+        "#;
+    let expected_provider = ModelProviderInfo {
+        name: "Example".into(),
+        base_url: Some("https://example.com".into()),
+        env_key: Some("API_KEY".into()),
+        env_key_instructions: None,
+        experimental_bearer_token: None,
+        auth: None,
+        aws: None,
+        wire_api: WireApi::Responses,
+        query_params: None,
+        http_headers: Some(maplit::hashmap! {
+            "X-Example-Header".to_string() => "example-value".into(),
+        }),
+        env_http_headers: Some(maplit::hashmap! {
+            "X-Example-Env-Header".to_string() => "EXAMPLE_ENV_VAR".to_string(),
+        }),
+        request_max_retries: None,
+        stream_max_retries: None,
+        stream_idle_timeout_ms: None,
+        websocket_connect_timeout_ms: None,
+        requires_openai_auth: false,
+        supports_websockets: false,
+        supports_standalone_web_search: true,
+    };
+
+    let provider: ModelProviderInfo = toml::from_str(azure_provider_toml).unwrap();
+    assert_eq!(expected_provider, provider);
+}
+
+#[test]
+fn test_deserialize_chat_wire_api_shows_helpful_error() {
+    let provider_toml = r#"
+name = "OpenAI using Chat Completions"
+base_url = "https://api.openai.com/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "chat"
+        "#;
+
+    let err = toml::from_str::<ModelProviderInfo>(provider_toml).unwrap_err();
+    assert!(err.to_string().contains(CHAT_WIRE_API_REMOVED_ERROR));
+}
+
+#[test]
+fn test_deserialize_websocket_connect_timeout() {
+    let provider_toml = r#"
+name = "OpenAI"
+base_url = "https://api.openai.com/v1"
+websocket_connect_timeout_ms = 15000
+supports_websockets = true
+        "#;
+
+    let provider: ModelProviderInfo = toml::from_str(provider_toml).unwrap();
+    assert_eq!(provider.websocket_connect_timeout_ms, Some(15_000));
+}
+
+#[test]
+fn test_personal_access_token_uses_chatgpt_codex_base_url() {
+    let api_provider = ModelProviderInfo::create_openai_provider(/*base_url*/ None)
+        .to_api_provider(Some(AuthMode::PersonalAccessToken))
+        .expect("OpenAI provider should build API provider");
+
+    assert_eq!(api_provider.base_url, CHATGPT_CODEX_BASE_URL);
+}
+
+#[test]
+fn test_header_auth_uses_chatgpt_codex_base_url() {
+    let api_provider = ModelProviderInfo::create_openai_provider(/*base_url*/ None)
+        .to_api_provider(Some(AuthMode::Headers))
+        .expect("OpenAI provider should build API provider");
+
+    assert_eq!(api_provider.base_url, CHATGPT_CODEX_BASE_URL);
+}
+
+#[test]
+fn codex_backend_routes_require_codex_base_url() {
+    for (base_url, expected) in [
+        (None, true),
+        (Some(CHATGPT_CODEX_BASE_URL), true),
+        (Some("https://chatgpt-staging.com/backend-api/codex/"), true),
+        (Some("https://proxy.example.com/v1"), false),
+    ] {
+        let provider = ModelProviderInfo::create_openai_provider(base_url.map(str::to_owned));
+        assert_eq!(provider.supports_codex_backend_routes(), expected);
+    }
+}
+
+#[test]
+fn test_uses_openai_actor_authorization() {
+    let mut provider = ModelProviderInfo {
+        http_headers: Some(maplit::hashmap! {
+            "X-OpenAI-Actor-Authorization".to_string() => "actor-token".into(),
+        }),
+        ..ModelProviderInfo::default()
+    };
+    assert!(provider.uses_openai_actor_authorization());
+
+    provider.http_headers = None;
+    assert!(!provider.uses_openai_actor_authorization());
+
+    provider.http_headers = Some(maplit::hashmap! {
+        OPENAI_ACTOR_AUTHORIZATION_HEADER.to_string() => "  ".into(),
+    });
+    assert!(!provider.uses_openai_actor_authorization());
+
+    provider.http_headers = Some(maplit::hashmap! {
+        OPENAI_ACTOR_AUTHORIZATION_HEADER.to_string() => "actor-token".into(),
+    });
+    provider.requires_openai_auth = true;
+    assert!(!provider.uses_openai_actor_authorization());
+}
+
+#[test]
+fn test_deserialize_provider_auth_config_defaults() {
+    let base_dir = tempdir().unwrap();
+    let provider_toml = r#"
+name = "Corp"
+
+[auth]
+command = "./scripts/print-token"
+args = ["--format=text"]
+        "#;
+
+    let provider: ModelProviderInfo = {
+        let _guard = AbsolutePathBufGuard::new(base_dir.path());
+        toml::from_str(provider_toml).unwrap()
+    };
+
+    assert_eq!(
+        provider.auth,
+        Some(ModelProviderAuthInfo {
+            command: "./scripts/print-token".to_string(),
+            args: vec!["--format=text".into()],
+            timeout_ms: NonZeroU64::new(5_000).unwrap(),
+            refresh_interval_ms: 300_000,
+            cwd: AbsolutePathBuf::resolve_path_against_base(".", base_dir.path()),
+        })
+    );
+}
+
+#[test]
+fn test_deserialize_provider_aws_config() {
+    let provider_toml = r#"
+name = "Amazon Bedrock"
+base_url = "https://bedrock.example.com/v1"
+
+[aws]
+region = "us-west-2"
+
+[aws.credential_export]
+command = "aws-vault"
+args = ["--profile", "codex-bedrock"]
+
+[aws.auth_refresh]
+command = "aws"
+args = ["login", "--profile", "codex-bedrock"]
+        "#;
+
+    let provider: ModelProviderInfo = toml::from_str(provider_toml).unwrap();
+
+    assert_eq!(
+        provider.aws,
+        Some(ModelProviderAwsAuthInfo {
+            profile: None,
+            region: Some("us-west-2".to_string()),
+            credential_export: Some(AwsCredentialExportConfig {
+                command: "aws-vault".to_string(),
+                args: vec!["--profile".into(), "codex-bedrock".into()],
+                timeout_ms: NonZeroU64::new(30_000).expect("timeout should be non-zero"),
+            }),
+            auth_refresh: Some(AwsAuthRefreshConfig {
+                command: "aws".to_string(),
+                args: vec!["login".into(), "--profile".into(), "codex-bedrock".into()],
+                timeout_ms: NonZeroU64::new(300_000).expect("timeout should be non-zero"),
+            }),
+        })
+    );
+}
+
+#[test]
+fn test_create_amazon_bedrock_provider() {
+    assert_eq!(
+        ModelProviderInfo::create_amazon_bedrock_provider(/*aws*/ None),
+        ModelProviderInfo {
+            name: "Amazon Bedrock".to_string(),
+            base_url: None,
+            env_key: None,
+            env_key_instructions: None,
+            experimental_bearer_token: None,
+            auth: None,
+            aws: Some(ModelProviderAwsAuthInfo {
+                profile: None,
+                region: None,
+                credential_export: None,
+                auth_refresh: None,
+            }),
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: Some(maplit::hashmap! {
+                AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_HEADER.to_string() =>
+                    AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_VALUE.into(),
+            }),
+            env_http_headers: None,
+            request_max_retries: None,
+            stream_max_retries: None,
+            stream_idle_timeout_ms: None,
+            websocket_connect_timeout_ms: None,
+            requires_openai_auth: false,
+            supports_websockets: false,
+            supports_standalone_web_search: false,
+        }
+    );
+}
+
+#[test]
+fn test_create_amazon_bedrock_runtime_provider() {
+    let mut expected = ModelProviderInfo::create_amazon_bedrock_provider(/*aws*/ None);
+    expected.name = "Amazon Bedrock Runtime".to_string();
+    expected.http_headers = None;
+
+    assert_eq!(
+        ModelProviderInfo::create_amazon_bedrock_runtime_provider(/*aws*/ None),
+        expected
+    );
+}
+
+#[test]
+fn test_create_amazon_bedrock_runtime_provider_with_aws_configuration() {
+    let provider =
+        ModelProviderInfo::create_amazon_bedrock_runtime_provider(Some(ModelProviderAwsAuthInfo {
+            profile: Some("runtime-profile".to_string()),
+            region: Some("us-west-2".to_string()),
+            credential_export: None,
+            auth_refresh: None,
+        }));
+
+    assert_eq!(
+        (
+            provider.name.as_str(),
+            provider.aws,
+            provider.http_headers,
+            provider.supports_standalone_web_search,
+        ),
+        (
+            "Amazon Bedrock Runtime",
+            Some(ModelProviderAwsAuthInfo {
+                profile: Some("runtime-profile".to_string()),
+                region: Some("us-west-2".to_string()),
+                credential_export: None,
+                auth_refresh: None,
+            }),
+            None,
+            false,
+        )
+    );
+}
+
+fn provider_auth_for_test() -> ModelProviderAuthInfo {
+    ModelProviderAuthInfo {
+        command: "token-fetcher".to_string(),
+        args: vec!["fetch".into()],
+        timeout_ms: NonZeroU64::new(5_000).expect("timeout should be non-zero"),
+        refresh_interval_ms: 300_000,
+        cwd: std::env::current_dir()
+            .expect("current directory should be available")
+            .try_into()
+            .expect("current directory should be absolute"),
+    }
+}
+
+#[test]
+fn test_amazon_bedrock_provider_adds_mantle_client_agent_header() {
+    let api_provider = ModelProviderInfo::create_amazon_bedrock_provider(/*aws*/ None)
+        .to_api_provider(/*auth_mode*/ None)
+        .expect("Amazon Bedrock provider should build API provider");
+
+    assert_eq!(
+        api_provider
+            .headers
+            .get(AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_HEADER)
+            .and_then(|value| value.to_str().ok()),
+        Some(AMAZON_BEDROCK_MANTLE_CLIENT_AGENT_VALUE)
+    );
+}
+
+#[test]
+fn test_built_in_model_providers_include_amazon_bedrock_endpoints() {
+    let providers = built_in_model_providers(/*openai_base_url*/ None);
+
+    assert_eq!(
+        [
+            AMAZON_BEDROCK_PROVIDER_ID,
+            AMAZON_BEDROCK_RUNTIME_PROVIDER_ID
+        ]
+        .into_iter()
+        .map(|provider_id| {
+            providers
+                .get(provider_id)
+                .map(ModelProviderInfo::is_amazon_bedrock)
+        })
+        .collect::<Vec<_>>(),
+        vec![Some(true), Some(true)]
+    );
+}
+
+#[test]
+fn test_built_in_model_providers_include_amazon_bedrock_runtime() {
+    let providers = built_in_model_providers(/*openai_base_url*/ None);
+    let runtime = providers
+        .get(AMAZON_BEDROCK_RUNTIME_PROVIDER_ID)
+        .expect("Amazon Bedrock Runtime provider should be built in");
+
+    assert!(runtime.is_amazon_bedrock());
+    assert!(runtime.is_amazon_bedrock_runtime());
+    assert!(
+        !providers
+            .get(AMAZON_BEDROCK_PROVIDER_ID)
+            .expect("Amazon Bedrock provider should be built in")
+            .is_amazon_bedrock_runtime()
+    );
+}
+
+#[test]
+fn test_merge_configured_model_providers_adds_custom_provider() {
+    let custom_provider = ModelProviderInfo {
+        name: "Custom".to_string(),
+        base_url: Some("https://example.com/v1".to_string()),
+        ..ModelProviderInfo::default()
+    };
+    let configured_model_providers =
+        std::collections::HashMap::from([("custom".to_string(), custom_provider.clone())]);
+
+    let mut expected = built_in_model_providers(/*openai_base_url*/ None);
+    expected.insert("custom".to_string(), custom_provider);
+
+    assert_eq!(
+        merge_configured_model_providers(
+            built_in_model_providers(/*openai_base_url*/ None),
+            configured_model_providers,
+        ),
+        Ok(expected)
+    );
+}
+
+#[test]
+fn test_merge_configured_model_providers_applies_amazon_bedrock_aws_override() {
+    let credential_export = AwsCredentialExportConfig {
+        command: "aws-vault".to_string(),
+        args: vec!["export".into(), "codex-bedrock".into()],
+        timeout_ms: NonZeroU64::new(30_000).expect("timeout should be non-zero"),
+    };
+    let auth_refresh = AwsAuthRefreshConfig {
+        command: "aws".to_string(),
+        args: vec!["login".into(), "--profile".into(), "codex-bedrock".into()],
+        timeout_ms: NonZeroU64::new(10_000).expect("timeout should be non-zero"),
+    };
+    let configured_model_providers = std::collections::HashMap::from([(
+        AMAZON_BEDROCK_PROVIDER_ID.to_string(),
+        ModelProviderInfo {
+            aws: Some(ModelProviderAwsAuthInfo {
+                profile: None,
+                region: Some("us-west-2".to_string()),
+                credential_export: Some(credential_export.clone()),
+                auth_refresh: Some(auth_refresh.clone()),
+            }),
+            ..ModelProviderInfo::default()
+        },
+    )]);
+
+    let mut expected = built_in_model_providers(/*openai_base_url*/ None);
+    expected
+        .get_mut(AMAZON_BEDROCK_PROVIDER_ID)
+        .expect("Amazon Bedrock provider should be built in")
+        .aws = Some(ModelProviderAwsAuthInfo {
+        profile: None,
+        region: Some("us-west-2".to_string()),
+        credential_export: Some(credential_export),
+        auth_refresh: Some(auth_refresh),
+    });
+
+    assert_eq!(
+        merge_configured_model_providers(
+            built_in_model_providers(/*openai_base_url*/ None),
+            configured_model_providers,
+        ),
+        Ok(expected)
+    );
+}
+
+#[test]
+fn test_merge_configured_model_providers_applies_runtime_overrides_independently() {
+    let runtime_aws = ModelProviderAwsAuthInfo {
+        profile: Some("runtime-profile".to_string()),
+        region: Some("eu-west-1".to_string()),
+        credential_export: None,
+        auth_refresh: None,
+    };
+    let configured_model_providers = std::collections::HashMap::from([(
+        AMAZON_BEDROCK_RUNTIME_PROVIDER_ID.to_string(),
+        ModelProviderInfo {
+            base_url: Some("https://runtime.example.com/openai/v1".to_string()),
+            aws: Some(runtime_aws.clone()),
+            ..ModelProviderInfo::default()
+        },
+    )]);
+    let mut expected = built_in_model_providers(/*openai_base_url*/ None);
+    let expected_runtime = expected
+        .get_mut(AMAZON_BEDROCK_RUNTIME_PROVIDER_ID)
+        .expect("Amazon Bedrock Runtime provider should be built in");
+    expected_runtime.base_url = Some("https://runtime.example.com/openai/v1".to_string());
+    expected_runtime.aws = Some(runtime_aws);
+
+    assert_eq!(
+        merge_configured_model_providers(
+            built_in_model_providers(/*openai_base_url*/ None),
+            configured_model_providers,
+        ),
+        Ok(expected)
+    );
+}
+
+#[test]
+fn test_merge_configured_model_providers_applies_amazon_bedrock_transport_overrides() {
+    let auth = provider_auth_for_test();
+    let configured_model_providers = std::collections::HashMap::from([(
+        AMAZON_BEDROCK_PROVIDER_ID.to_string(),
+        ModelProviderInfo {
+            base_url: Some("https://proxy.example.com/v1".to_string()),
+            auth: Some(auth.clone()),
+            aws: Some(ModelProviderAwsAuthInfo {
+                profile: Some("codex-bedrock".to_string()),
+                region: Some("us-west-2".to_string()),
+                credential_export: None,
+                auth_refresh: None,
+            }),
+            http_headers: Some(maplit::hashmap! {
+                "x-example-header".to_string() => "value".into(),
+            }),
+            ..ModelProviderInfo::default()
+        },
+    )]);
+
+    let mut expected = built_in_model_providers(/*openai_base_url*/ None);
+    let expected_provider = expected
+        .get_mut(AMAZON_BEDROCK_PROVIDER_ID)
+        .expect("Amazon Bedrock provider should be built in");
+    expected_provider.base_url = Some("https://proxy.example.com/v1".to_string());
+    expected_provider.auth = Some(auth);
+    expected_provider.aws = Some(ModelProviderAwsAuthInfo {
+        profile: Some("codex-bedrock".to_string()),
+        region: Some("us-west-2".to_string()),
+        credential_export: None,
+        auth_refresh: None,
+    });
+    expected_provider
+        .http_headers
+        .get_or_insert_default()
+        .insert("x-example-header".to_string(), "value".into());
+
+    assert_eq!(
+        merge_configured_model_providers(
+            built_in_model_providers(/*openai_base_url*/ None),
+            configured_model_providers,
+        ),
+        Ok(expected)
+    );
+}
+
+#[test]
+fn test_merge_configured_model_providers_rejects_amazon_bedrock_non_default_fields() {
+    let configured_model_providers = std::collections::HashMap::from([(
+        AMAZON_BEDROCK_PROVIDER_ID.to_string(),
+        ModelProviderInfo {
+            name: "Custom Bedrock".to_string(),
+            aws: Some(ModelProviderAwsAuthInfo {
+                profile: Some("codex-bedrock".to_string()),
+                region: None,
+                credential_export: None,
+                auth_refresh: None,
+            }),
+            ..ModelProviderInfo::default()
+        },
+    )]);
+
+    assert_eq!(
+        merge_configured_model_providers(
+            built_in_model_providers(/*openai_base_url*/ None),
+            configured_model_providers,
+        ),
+        Err(
+            "model_providers.amazon-bedrock only supports changing `base_url`, `auth`, `http_headers`, `aws.profile`, `aws.region`, `aws.credential_export`, and `aws.auth_refresh`; other non-default provider fields are not supported"
+                .to_string()
+        )
+    );
+}
+
+#[test]
+fn test_merge_configured_model_providers_allows_amazon_bedrock_default_fields() {
+    let configured_model_providers = std::collections::HashMap::from([(
+        AMAZON_BEDROCK_PROVIDER_ID.to_string(),
+        ModelProviderInfo {
+            aws: Some(ModelProviderAwsAuthInfo {
+                profile: None,
+                region: None,
+                credential_export: None,
+                auth_refresh: None,
+            }),
+            wire_api: WireApi::Responses,
+            ..ModelProviderInfo::default()
+        },
+    )]);
+
+    assert_eq!(
+        merge_configured_model_providers(
+            built_in_model_providers(/*openai_base_url*/ None),
+            configured_model_providers,
+        ),
+        Ok(built_in_model_providers(/*openai_base_url*/ None))
+    );
+}
+
+#[test]
+fn test_validate_provider_aws_rejects_conflicting_auth() {
+    let provider = ModelProviderInfo {
+        aws: Some(ModelProviderAwsAuthInfo {
+            profile: None,
+            region: None,
+            credential_export: None,
+            auth_refresh: None,
+        }),
+        env_key: Some("AWS_BEARER_TOKEN_BEDROCK".to_string()),
+        supports_websockets: false,
+        ..ModelProviderInfo::create_openai_provider(/*base_url*/ None)
+    };
+
+    assert_eq!(
+        provider.validate(),
+        Err("provider aws cannot be combined with env_key, requires_openai_auth".to_string())
+    );
+}
+
+#[test]
+fn test_validate_provider_aws_rejects_websockets() {
+    let provider = ModelProviderInfo {
+        aws: Some(ModelProviderAwsAuthInfo {
+            profile: None,
+            region: None,
+            credential_export: None,
+            auth_refresh: None,
+        }),
+        requires_openai_auth: false,
+        supports_websockets: true,
+        ..ModelProviderInfo::create_openai_provider(/*base_url*/ None)
+    };
+
+    assert_eq!(
+        provider.validate(),
+        Err("provider aws cannot be combined with supports_websockets".to_string())
+    );
+}
+
+#[test]
+fn test_validate_provider_aws_auth_refresh_command() {
+    for (command, expected) in [
+        (
+            "  ",
+            Err("provider aws.auth_refresh.command must not be empty".to_string()),
+        ),
+        (
+            "other-command",
+            Err("provider aws.auth_refresh.command must be `aws`".to_string()),
+        ),
+        ("aws", Ok(())),
+    ] {
+        let provider =
+            ModelProviderInfo::create_amazon_bedrock_provider(Some(ModelProviderAwsAuthInfo {
+                profile: None,
+                region: None,
+                credential_export: None,
+                auth_refresh: Some(AwsAuthRefreshConfig {
+                    command: command.to_string(),
+                    args: Vec::new(),
+                    timeout_ms: NonZeroU64::new(300_000).expect("timeout should be non-zero"),
+                }),
+            }));
+
+        assert_eq!(provider.validate(), expected);
+    }
+}
+
+#[test]
+fn test_validate_provider_aws_credential_export_command() {
+    let absolute_command = std::env::current_exe()
+        .expect("current executable should have a path")
+        .to_string_lossy()
+        .into_owned();
+    for (command, expected) in [
+        (
+            String::new(),
+            Err("provider aws.credential_export.command must not be empty".to_string()),
+        ),
+        (
+            "  ".to_string(),
+            Err("provider aws.credential_export.command must not be empty".to_string()),
+        ),
+        ("aws-vault".to_string(), Ok(())),
+        (absolute_command, Ok(())),
+        (
+            "./scripts/export-credentials".to_string(),
+            Err(
+                "provider aws.credential_export.command must be an absolute path or a bare executable name"
+                    .to_string(),
+            ),
+        ),
+        (
+            "scripts/export-credentials".to_string(),
+            Err(
+                "provider aws.credential_export.command must be an absolute path or a bare executable name"
+                    .to_string(),
+            ),
+        ),
+        (
+            "scripts/.".to_string(),
+            Err(
+                "provider aws.credential_export.command must be an absolute path or a bare executable name"
+                    .to_string(),
+            ),
+        ),
+    ] {
+        let mut provider =
+            ModelProviderInfo::create_amazon_bedrock_provider(Some(ModelProviderAwsAuthInfo {
+                profile: None,
+                region: Some("us-west-2".to_string()),
+                credential_export: Some(AwsCredentialExportConfig {
+                    command,
+                    args: vec!["--secret-argument".into()],
+                    timeout_ms: NonZeroU64::new(30_000).expect("timeout should be non-zero"),
+                }),
+                auth_refresh: Some(AwsAuthRefreshConfig {
+                    command: "aws".to_string(),
+                    args: Vec::new(),
+                    timeout_ms: NonZeroU64::new(300_000).expect("timeout should be non-zero"),
+                }),
+            }));
+
+        assert_eq!(provider.validate(), expected);
+        if expected.is_ok() {
+            provider.aws.as_mut().expect("AWS config").profile = Some("codex-bedrock".to_string());
+            assert_eq!(
+                provider.validate(),
+                Err("provider aws.credential_export cannot be combined with aws.profile".to_string()),
+            );
+        }
+        let export = provider
+            .aws
+            .as_ref()
+            .and_then(|aws| aws.credential_export.as_ref())
+            .expect("credential export should be configured");
+        assert!(!format!("{export:?}").contains("--secret-argument"));
+    }
+}
+
+#[test]
+fn test_deserialize_provider_auth_config_allows_zero_refresh_interval() {
+    let base_dir = tempdir().unwrap();
+    let provider_toml = r#"
+name = "Corp"
+
+[auth]
+command = "./scripts/print-token"
+refresh_interval_ms = 0
+        "#;
+
+    let provider: ModelProviderInfo = {
+        let _guard = AbsolutePathBufGuard::new(base_dir.path());
+        toml::from_str(provider_toml).unwrap()
+    };
+
+    let auth = provider.auth.expect("auth config should deserialize");
+    assert_eq!(auth.refresh_interval_ms, 0);
+    assert_eq!(auth.refresh_interval(), None);
+}
diff --git a/codex-rs/prompts/src/compact.rs b/codex-rs/prompts/src/compact.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2ddc146aec081652200c7a03aa0244c0766d09c9
--- /dev/null
+++ b/codex-rs/prompts/src/compact.rs
@@ -0,0 +1,2 @@
+pub const SUMMARIZATION_PROMPT: &str = include_str!("../templates/compact/prompt.md");
+pub const SUMMARY_PREFIX: &str = include_str!("../templates/compact/summary_prefix.md");
diff --git a/codex-rs/prompts/src/lib.rs b/codex-rs/prompts/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b7b4e444e2bf5bb0ccb72df6ea98eb408977f135
--- /dev/null
+++ b/codex-rs/prompts/src/lib.rs
@@ -0,0 +1,20 @@
+mod compact;
+mod permissions_instructions;
+mod realtime;
+mod review_exit;
+mod review_request;
+
+pub use compact::SUMMARIZATION_PROMPT;
+pub use compact::SUMMARY_PREFIX;
+pub use permissions_instructions::ApprovalPromptContext;
+pub use permissions_instructions::PermissionsInstructions;
+pub use realtime::BACKEND_PROMPT;
+pub use realtime::END_INSTRUCTIONS;
+pub use realtime::START_INSTRUCTIONS;
+pub use review_exit::render_review_exit_interrupted;
+pub use review_exit::render_review_exit_success;
+pub use review_request::REVIEW_PROMPT;
+pub use review_request::ResolvedReviewRequest;
+pub use review_request::resolve_review_request;
+pub use review_request::review_prompt;
+pub use review_request::user_facing_hint;
diff --git a/codex-rs/prompts/src/permissions_instructions.rs b/codex-rs/prompts/src/permissions_instructions.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9966618f70dbe359637c5f14ee99c47abe47d79b
--- /dev/null
+++ b/codex-rs/prompts/src/permissions_instructions.rs
@@ -0,0 +1,455 @@
+use codex_context_fragments::ContextualUserFragment;
+use codex_execpolicy::Policy;
+use codex_protocol::config_types::ApprovalsReviewer;
+use codex_protocol::config_types::SandboxMode;
+use codex_protocol::models::ContentItemKind;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::models::format_allow_prefixes;
+use codex_protocol::openai_models::ApprovalMessages;
+use codex_protocol::openai_models::PermissionMessages;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::GranularApprovalConfig;
+use codex_protocol::protocol::NetworkAccess;
+use codex_protocol::protocol::WritableRoot;
+use codex_utils_template::Template;
+use std::path::Path;
+use std::sync::LazyLock;
+
+const APPROVAL_POLICY_NEVER: &str =
+    include_str!("../templates/permissions/approval_policy/never.md");
+const APPROVAL_POLICY_UNLESS_TRUSTED: &str =
+    include_str!("../templates/permissions/approval_policy/unless_trusted.md");
+const APPROVAL_POLICY_ON_REQUEST_RULE: &str =
+    include_str!("../templates/permissions/approval_policy/on_request.md");
+const APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION: &str =
+    include_str!("../templates/permissions/approval_policy/on_request_rule_request_permission.md");
+const AUTO_REVIEW_APPROVAL_SUFFIX: &str = "`approvals_reviewer` is `auto_review`: Sandbox escalations with require_escalated will be reviewed for compliance with the policy. If a rejection happens, you should proceed only with a materially safer alternative, or inform the user of the risk and send a final message to ask for approval.";
+const NETWORK_ACCESS_PLACEHOLDER: &str = "{{ network_access }}";
+
+const SANDBOX_MODE_DANGER_FULL_ACCESS: &str =
+    include_str!("../templates/permissions/sandbox_mode/danger_full_access.md");
+const SANDBOX_MODE_WORKSPACE_WRITE: &str =
+    include_str!("../templates/permissions/sandbox_mode/workspace_write.md");
+const SANDBOX_MODE_READ_ONLY: &str =
+    include_str!("../templates/permissions/sandbox_mode/read_only.md");
+
+static SANDBOX_MODE_DANGER_FULL_ACCESS_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(SANDBOX_MODE_DANGER_FULL_ACCESS.trim_end())
+        .unwrap_or_else(|err| panic!("danger-full-access sandbox template must parse: {err}"))
+});
+static SANDBOX_MODE_WORKSPACE_WRITE_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(SANDBOX_MODE_WORKSPACE_WRITE.trim_end())
+        .unwrap_or_else(|err| panic!("workspace-write sandbox template must parse: {err}"))
+});
+static SANDBOX_MODE_READ_ONLY_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(SANDBOX_MODE_READ_ONLY.trim_end())
+        .unwrap_or_else(|err| panic!("read-only sandbox template must parse: {err}"))
+});
+
+struct PermissionsPromptConfig<'a> {
+    approval_policy: AskForApproval,
+    approvals_reviewer: ApprovalsReviewer,
+    approval_messages: Option<&'a ApprovalMessages>,
+    permission_messages: Option<&'a PermissionMessages>,
+    exec_policy: &'a Policy,
+    exec_permission_approvals_enabled: bool,
+    request_permissions_tool_enabled: bool,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+/// Developer instructions that describe the active sandbox and approval policy.
+pub struct PermissionsInstructions {
+    text: String,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct ApprovalPromptContext<'a> {
+    reviewer: ApprovalsReviewer,
+    messages: Option<&'a ApprovalMessages>,
+    permission_messages: Option<&'a PermissionMessages>,
+}
+
+impl<'a> ApprovalPromptContext<'a> {
+    pub fn new(
+        reviewer: ApprovalsReviewer,
+        messages: Option<&'a ApprovalMessages>,
+        permission_messages: Option<&'a PermissionMessages>,
+    ) -> Self {
+        Self {
+            reviewer,
+            messages,
+            permission_messages,
+        }
+    }
+}
+
+impl PermissionsInstructions {
+    /// Builds permissions instructions from the effective permission profile and approval policy.
+    pub fn from_permission_profile(
+        permission_profile: &PermissionProfile,
+        approval_policy: AskForApproval,
+        approval_context: ApprovalPromptContext<'_>,
+        exec_policy: &Policy,
+        cwd: &Path,
+        exec_permission_approvals_enabled: bool,
+        request_permissions_tool_enabled: bool,
+    ) -> Self {
+        let file_system_sandbox_policy = permission_profile.file_system_sandbox_policy();
+        let (sandbox_mode, writable_roots) =
+            sandbox_prompt_from_policy(&file_system_sandbox_policy, cwd);
+
+        Self::from_permissions_with_network_and_denied_reads(
+            sandbox_mode,
+            network_access_from_policy(permission_profile.network_sandbox_policy()),
+            PermissionsPromptConfig {
+                approval_policy,
+                approvals_reviewer: approval_context.reviewer,
+                approval_messages: approval_context.messages,
+                permission_messages: approval_context.permission_messages,
+                exec_policy,
+                exec_permission_approvals_enabled,
+                request_permissions_tool_enabled,
+            },
+            writable_roots,
+            denied_reads_text(&file_system_sandbox_policy, cwd),
+        )
+    }
+
+    pub fn body(&self) -> String {
+        self.text.clone()
+    }
+
+    #[cfg(test)]
+    fn from_permissions_with_network(
+        sandbox_mode: SandboxMode,
+        network_access: NetworkAccess,
+        config: PermissionsPromptConfig<'_>,
+        writable_roots: Option<Vec<WritableRoot>>,
+    ) -> Self {
+        Self::from_permissions_with_network_and_denied_reads(
+            sandbox_mode,
+            network_access,
+            config,
+            writable_roots,
+            /*denied_reads*/ None,
+        )
+    }
+
+    fn from_permissions_with_network_and_denied_reads(
+        sandbox_mode: SandboxMode,
+        network_access: NetworkAccess,
+        config: PermissionsPromptConfig<'_>,
+        writable_roots: Option<Vec<WritableRoot>>,
+        denied_reads: Option<String>,
+    ) -> Self {
+        let mut text = String::new();
+        let sandbox = sandbox_text(sandbox_mode, network_access, config.permission_messages);
+        if !sandbox.is_empty() {
+            append_section(&mut text, &sandbox);
+        }
+        append_section(
+            &mut text,
+            &approval_text(
+                config.approval_policy,
+                config.approvals_reviewer,
+                config.approval_messages,
+                config.exec_policy,
+                config.exec_permission_approvals_enabled,
+                config.request_permissions_tool_enabled,
+            ),
+        );
+        if let Some(writable_roots) = writable_roots_text(writable_roots) {
+            append_section(&mut text, &writable_roots);
+        }
+        if let Some(denied_reads) = denied_reads {
+            append_section(&mut text, &denied_reads);
+        }
+        if !text.ends_with('\n') {
+            text.push('\n');
+        }
+        Self { text }
+    }
+}
+
+impl ContextualUserFragment for PermissionsInstructions {
+    fn role(&self) -> &'static str {
+        "developer"
+    }
+
+    fn content_kind(&self) -> ContentItemKind {
+        ContentItemKind("permissions.instructions".to_string())
+    }
+
+    fn markers(&self) -> (&'static str, &'static str) {
+        Self::type_markers()
+    }
+
+    fn type_markers() -> (&'static str, &'static str) {
+        ("<permissions instructions>", "</permissions instructions>")
+    }
+
+    fn body(&self) -> String {
+        PermissionsInstructions::body(self)
+    }
+}
+
+fn sandbox_prompt_from_policy(
+    file_system_policy: &FileSystemSandboxPolicy,
+    cwd: &Path,
+) -> (SandboxMode, Option<Vec<WritableRoot>>) {
+    if file_system_policy.has_full_disk_write_access() {
+        return (SandboxMode::DangerFullAccess, None);
+    }
+
+    let writable_roots = file_system_policy.get_writable_roots_with_cwd(cwd);
+    if writable_roots.is_empty() {
+        (SandboxMode::ReadOnly, None)
+    } else {
+        (SandboxMode::WorkspaceWrite, Some(writable_roots))
+    }
+}
+
+fn network_access_from_policy(network_policy: NetworkSandboxPolicy) -> NetworkAccess {
+    if network_policy.is_enabled() {
+        NetworkAccess::Enabled
+    } else {
+        NetworkAccess::Restricted
+    }
+}
+
+fn append_section(text: &mut String, section: &str) {
+    if !text.ends_with('\n') {
+        text.push('\n');
+    }
+    text.push_str(section);
+}
+
+fn approval_text(
+    approval_policy: AskForApproval,
+    approvals_reviewer: ApprovalsReviewer,
+    approval_messages: Option<&ApprovalMessages>,
+    exec_policy: &Policy,
+    exec_permission_approvals_enabled: bool,
+    request_permissions_tool_enabled: bool,
+) -> String {
+    if let Some(approval_messages) = approval_messages {
+        let selected = match &approval_policy {
+            AskForApproval::OnRequest => match approvals_reviewer {
+                ApprovalsReviewer::User => approval_messages.on_request.as_ref(),
+                ApprovalsReviewer::AutoReview => approval_messages.on_request_auto_review.as_ref(),
+            },
+            AskForApproval::Never => approval_messages.never.as_ref(),
+            AskForApproval::UnlessTrusted => approval_messages.unless_trusted.as_ref(),
+            AskForApproval::Granular(_) => None,
+        };
+        if let Some(selected) = selected {
+            return selected.clone();
+        }
+    }
+
+    let with_request_permissions_tool = |text: &str| {
+        if request_permissions_tool_enabled {
+            format!("{text}\n\n{}", request_permissions_tool_prompt_section())
+        } else {
+            text.to_string()
+        }
+    };
+    let on_request_instructions = || {
+        let on_request_rule = if exec_permission_approvals_enabled {
+            APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION.to_string()
+        } else {
+            APPROVAL_POLICY_ON_REQUEST_RULE.to_string()
+        };
+        let mut sections = vec![on_request_rule];
+        if request_permissions_tool_enabled {
+            sections.push(request_permissions_tool_prompt_section().to_string());
+        }
+        if let Some(prefixes) = approved_command_prefixes_text(exec_policy) {
+            sections.push(format!(
+                "## Approved command prefixes\nThe following prefix rules have already been approved: {prefixes}"
+            ));
+        }
+        sections.join("\n\n")
+    };
+    let text = match approval_policy {
+        AskForApproval::Never => APPROVAL_POLICY_NEVER.to_string(),
+        AskForApproval::UnlessTrusted => {
+            with_request_permissions_tool(APPROVAL_POLICY_UNLESS_TRUSTED)
+        }
+        AskForApproval::OnRequest => on_request_instructions(),
+        AskForApproval::Granular(granular_config) => granular_instructions(
+            granular_config,
+            exec_policy,
+            exec_permission_approvals_enabled,
+            request_permissions_tool_enabled,
+        ),
+    };
+
+    if approvals_reviewer == ApprovalsReviewer::AutoReview
+        && approval_policy != AskForApproval::Never
+    {
+        format!("{text}\n\n{AUTO_REVIEW_APPROVAL_SUFFIX}")
+    } else {
+        text
+    }
+}
+
+fn sandbox_text(
+    mode: SandboxMode,
+    network_access: NetworkAccess,
+    permission_messages: Option<&PermissionMessages>,
+) -> String {
+    let selected = permission_messages.and_then(|messages| match mode {
+        SandboxMode::DangerFullAccess => messages.danger_full_access.as_deref(),
+        SandboxMode::WorkspaceWrite => messages.workspace_write.as_deref(),
+        SandboxMode::ReadOnly => messages.read_only.as_deref(),
+    });
+    if let Some(selected) = selected {
+        if selected.is_empty() {
+            return String::new();
+        }
+        let network_access = network_access.to_string();
+        return selected.replace(NETWORK_ACCESS_PLACEHOLDER, network_access.as_str());
+    }
+
+    let template = match mode {
+        SandboxMode::DangerFullAccess => &*SANDBOX_MODE_DANGER_FULL_ACCESS_TEMPLATE,
+        SandboxMode::WorkspaceWrite => &*SANDBOX_MODE_WORKSPACE_WRITE_TEMPLATE,
+        SandboxMode::ReadOnly => &*SANDBOX_MODE_READ_ONLY_TEMPLATE,
+    };
+    let network_access = network_access.to_string();
+    template
+        .render([("network_access", network_access.as_str())])
+        .unwrap_or_else(|err| panic!("sandbox template must render: {err}"))
+}
+
+fn writable_roots_text(writable_roots: Option<Vec<WritableRoot>>) -> Option<String> {
+    let mut roots = writable_roots?;
+    if roots.is_empty() {
+        return None;
+    }
+    roots.sort_by(|left, right| left.root.as_path().cmp(right.root.as_path()));
+
+    let roots_list: Vec<String> = roots
+        .iter()
+        .map(|r| format!("`{}`", r.root.to_string_lossy()))
+        .collect();
+    Some(if roots_list.len() == 1 {
+        format!(" The writable root is {}.", roots_list[0])
+    } else {
+        format!(" The writable roots are {}.", roots_list.join(", "))
+    })
+}
+
+fn denied_reads_text(file_system_policy: &FileSystemSandboxPolicy, cwd: &Path) -> Option<String> {
+    let mut entries = file_system_policy
+        .get_unreadable_roots_with_cwd(cwd)
+        .into_iter()
+        .map(|root| format!("- path `{}`", root.to_string_lossy()))
+        .collect::<Vec<_>>();
+    entries.extend(
+        file_system_policy
+            .get_unreadable_globs_with_cwd(cwd)
+            .into_iter()
+            .map(|glob| format!("- glob `{glob}`")),
+    );
+    if entries.is_empty() {
+        return None;
+    }
+
+    Some(format!(
+        "## Denied filesystem reads\nThe active permission profile denies reading these paths/globs. Do not request escalation or additional permissions to read them; these denials are policy restrictions.\n{}",
+        entries.join("\n")
+    ))
+}
+
+fn approved_command_prefixes_text(exec_policy: &Policy) -> Option<String> {
+    format_allow_prefixes(exec_policy.get_allowed_prefixes())
+        .filter(|prefixes| !prefixes.is_empty())
+}
+
+fn granular_prompt_intro_text() -> &'static str {
+    "# Approval Requests\n\nApproval policy is `granular`. Categories set to `false` are automatically rejected instead of prompting the user."
+}
+
+fn request_permissions_tool_prompt_section() -> &'static str {
+    "# request_permissions Tool\n\nThe built-in `request_permissions` tool is available in this session. Invoke it when you need to request additional `network` or `file_system` permissions before later shell-like commands need them. Request only the specific permissions required for the task."
+}
+
+fn granular_instructions(
+    granular_config: GranularApprovalConfig,
+    exec_policy: &Policy,
+    exec_permission_approvals_enabled: bool,
+    request_permissions_tool_enabled: bool,
+) -> String {
+    let sandbox_approval_prompts_allowed = granular_config.allows_sandbox_approval();
+    let shell_permission_requests_available =
+        exec_permission_approvals_enabled && sandbox_approval_prompts_allowed;
+    let request_permissions_tool_prompts_allowed =
+        request_permissions_tool_enabled && granular_config.allows_request_permissions();
+    let categories = [
+        Some((
+            granular_config.allows_sandbox_approval(),
+            "`sandbox_approval`",
+        )),
+        Some((granular_config.allows_rules_approval(), "`rules`")),
+        Some((granular_config.allows_skill_approval(), "`skill_approval`")),
+        request_permissions_tool_enabled.then_some((
+            granular_config.allows_request_permissions(),
+            "`request_permissions`",
+        )),
+        Some((
+            granular_config.allows_mcp_elicitations(),
+            "`mcp_elicitations`",
+        )),
+    ];
+    let prompted_categories = categories
+        .iter()
+        .flatten()
+        .filter(|&&(is_allowed, _)| is_allowed)
+        .map(|&(_, category)| format!("- {category}"))
+        .collect::<Vec<_>>();
+    let rejected_categories = categories
+        .iter()
+        .flatten()
+        .filter(|&&(is_allowed, _)| !is_allowed)
+        .map(|&(_, category)| format!("- {category}"))
+        .collect::<Vec<_>>();
+
+    let mut sections = vec![granular_prompt_intro_text().to_string()];
+
+    if !prompted_categories.is_empty() {
+        sections.push(format!(
+            "These approval categories may still prompt the user when needed:\n{}",
+            prompted_categories.join("\n")
+        ));
+    }
+    if !rejected_categories.is_empty() {
+        sections.push(format!(
+            "These approval categories are automatically rejected instead of prompting the user:\n{}",
+            rejected_categories.join("\n")
+        ));
+    }
+
+    if shell_permission_requests_available {
+        sections.push(APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION.to_string());
+    }
+
+    if request_permissions_tool_prompts_allowed {
+        sections.push(request_permissions_tool_prompt_section().to_string());
+    }
+
+    if let Some(prefixes) = approved_command_prefixes_text(exec_policy) {
+        sections.push(format!(
+            "## Approved command prefixes\nThe following prefix rules have already been approved: {prefixes}"
+        ));
+    }
+
+    sections.join("\n\n")
+}
+
+#[cfg(test)]
+#[path = "permissions_instructions_tests.rs"]
+mod permissions_instructions_tests;
diff --git a/codex-rs/prompts/src/permissions_instructions_tests.rs b/codex-rs/prompts/src/permissions_instructions_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bf1bf07d4d4ffb93fb89ff00c851855220506934
--- /dev/null
+++ b/codex-rs/prompts/src/permissions_instructions_tests.rs
@@ -0,0 +1,752 @@
+use super::*;
+use codex_execpolicy::Decision;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+use std::path::PathBuf;
+
+#[test]
+fn renders_sandbox_mode_text() {
+    assert_eq!(
+        sandbox_text(
+            SandboxMode::WorkspaceWrite,
+            NetworkAccess::Restricted,
+            /*permission_messages*/ None,
+        ),
+        "Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `workspace-write`: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. Network access is restricted."
+    );
+
+    assert_eq!(
+        sandbox_text(
+            SandboxMode::ReadOnly,
+            NetworkAccess::Restricted,
+            /*permission_messages*/ None,
+        ),
+        "Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `read-only`: The sandbox only permits reading files. Network access is restricted."
+    );
+
+    assert_eq!(
+        sandbox_text(
+            SandboxMode::DangerFullAccess,
+            NetworkAccess::Enabled,
+            /*permission_messages*/ None,
+        ),
+        "Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is enabled."
+    );
+}
+
+#[test]
+fn catalog_permission_messages_select_sandbox_mode_and_render_network_access() {
+    let messages = PermissionMessages {
+        danger_full_access: Some("catalog danger".to_string()),
+        workspace_write: Some("catalog workspace {{ network_access }}".to_string()),
+        read_only: Some("catalog read only {{ network_access }}".to_string()),
+    };
+
+    for (mode, expected) in [
+        (SandboxMode::DangerFullAccess, "catalog danger"),
+        (SandboxMode::WorkspaceWrite, "catalog workspace enabled"),
+        (SandboxMode::ReadOnly, "catalog read only enabled"),
+    ] {
+        assert_eq!(
+            sandbox_text(mode, NetworkAccess::Enabled, Some(&messages)),
+            expected
+        );
+    }
+}
+
+#[test]
+fn missing_catalog_permission_message_uses_legacy_sandbox_text() {
+    let legacy = sandbox_text(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Restricted,
+        /*permission_messages*/ None,
+    );
+    let messages = PermissionMessages {
+        danger_full_access: None,
+        workspace_write: None,
+        read_only: Some("unused".to_string()),
+    };
+
+    assert_eq!(
+        sandbox_text(
+            SandboxMode::WorkspaceWrite,
+            NetworkAccess::Restricted,
+            Some(&messages),
+        ),
+        legacy
+    );
+}
+
+#[test]
+fn invalid_catalog_permission_message_is_preserved_verbatim() {
+    for workspace_write in ["{{ unterminated", "{{ unsupported }}"] {
+        let messages = PermissionMessages {
+            danger_full_access: None,
+            workspace_write: Some(workspace_write.to_string()),
+            read_only: None,
+        };
+        assert_eq!(
+            sandbox_text(
+                SandboxMode::WorkspaceWrite,
+                NetworkAccess::Restricted,
+                Some(&messages),
+            ),
+            workspace_write
+        );
+    }
+}
+
+#[test]
+fn catalog_permission_message_renders_network_access_and_preserves_other_placeholders() {
+    let source = "network={{ network_access }} compact={{network_access}} other={{ other }}";
+    let messages = PermissionMessages {
+        danger_full_access: None,
+        workspace_write: Some(source.to_string()),
+        read_only: None,
+    };
+
+    assert_eq!(
+        sandbox_text(
+            SandboxMode::WorkspaceWrite,
+            NetworkAccess::Restricted,
+            Some(&messages),
+        ),
+        "network=restricted compact={{network_access}} other={{ other }}"
+    );
+}
+
+#[test]
+fn empty_catalog_permission_message_preserves_non_sandbox_sections() {
+    let messages = PermissionMessages {
+        danger_full_access: None,
+        workspace_write: Some(String::new()),
+        read_only: None,
+    };
+    let writable_root =
+        AbsolutePathBuf::from_absolute_path(test_path_buf("/tmp/repo")).expect("absolute path");
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Restricted,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::Never,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: Some(&messages),
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: false,
+        },
+        Some(vec![WritableRoot {
+            root: writable_root.clone(),
+            read_only_subpaths: Vec::new(),
+            protected_metadata_names: Vec::new(),
+        }]),
+    );
+    let text = instructions.body();
+
+    assert!(!text.contains("Filesystem sandboxing defines"));
+    assert!(text.contains("Approval policy is currently never"));
+    assert!(text.contains(writable_root.to_string_lossy().as_ref()));
+}
+
+#[test]
+fn builds_permissions_with_network_access_override() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: None,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: false,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(
+        text.contains("Network access is enabled."),
+        "expected network access to be enabled in message"
+    );
+    assert!(
+        text.contains("How to request escalation"),
+        "expected approval guidance to be included"
+    );
+}
+
+#[test]
+fn builds_permissions_from_profile() {
+    let cwd = PathBuf::from("/tmp");
+    let writable_root =
+        AbsolutePathBuf::from_absolute_path(cwd.join("repo")).expect("absolute path");
+    let permission_profile = PermissionProfile::from_runtime_permissions(
+        &FileSystemSandboxPolicy::restricted(vec![FileSystemSandboxEntry {
+            path: FileSystemPath::Path {
+                path: writable_root.clone().into(),
+            },
+            access: FileSystemAccessMode::Write,
+            missing_path_behavior: None,
+        }]),
+        NetworkSandboxPolicy::Enabled,
+    );
+
+    let instructions = PermissionsInstructions::from_permission_profile(
+        &permission_profile,
+        AskForApproval::UnlessTrusted,
+        ApprovalPromptContext::new(
+            ApprovalsReviewer::User,
+            /*messages*/ None,
+            /*permission_messages*/ None,
+        ),
+        &Policy::empty(),
+        &cwd,
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+    let text = instructions.body();
+    assert!(text.contains("`sandbox_mode` is `workspace-write`"));
+    assert!(text.contains("Network access is enabled."));
+    assert!(text.contains(writable_root.to_string_lossy().as_ref()));
+}
+
+#[test]
+fn builds_permissions_from_profile_with_denied_reads() {
+    let cwd = test_path_buf("/tmp");
+    let denied_root =
+        AbsolutePathBuf::from_absolute_path(cwd.join("blocked")).expect("absolute path");
+    let denied_glob = cwd.join("blocked").join("**");
+    let permission_profile = PermissionProfile::from_runtime_permissions(
+        &FileSystemSandboxPolicy::restricted(vec![
+            FileSystemSandboxEntry {
+                path: FileSystemPath::Special {
+                    value: codex_protocol::permissions::FileSystemSpecialPath::Root,
+                },
+                access: FileSystemAccessMode::Read,
+                missing_path_behavior: None,
+            },
+            FileSystemSandboxEntry {
+                path: FileSystemPath::Path {
+                    path: denied_root.clone().into(),
+                },
+                access: FileSystemAccessMode::Deny,
+                missing_path_behavior: None,
+            },
+            FileSystemSandboxEntry {
+                path: FileSystemPath::GlobPattern {
+                    pattern: denied_glob.to_string_lossy().into_owned(),
+                },
+                access: FileSystemAccessMode::Deny,
+                missing_path_behavior: None,
+            },
+        ]),
+        NetworkSandboxPolicy::Restricted,
+    );
+
+    let instructions = PermissionsInstructions::from_permission_profile(
+        &permission_profile,
+        AskForApproval::OnRequest,
+        ApprovalPromptContext::new(
+            ApprovalsReviewer::AutoReview,
+            /*messages*/ None,
+            /*permission_messages*/ None,
+        ),
+        &Policy::empty(),
+        &cwd,
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+    let text = instructions.body();
+    assert!(text.contains("## Denied filesystem reads"));
+    assert!(text.contains("Do not request escalation or additional permissions"));
+    assert!(text.contains(denied_root.to_string_lossy().as_ref()));
+    assert!(text.contains(&format!("glob `{}`", denied_glob.to_string_lossy())));
+}
+
+#[test]
+fn includes_request_rule_instructions_for_on_request() {
+    let mut exec_policy = Policy::empty();
+    exec_policy
+        .add_prefix_rule(&["git".to_string(), "pull".to_string()], Decision::Allow)
+        .expect("add rule");
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: None,
+            exec_policy: &exec_policy,
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: false,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("prefix_rule"));
+    assert!(text.contains("Approved command prefixes"));
+    assert!(text.contains(r#"["git", "pull"]"#));
+}
+
+#[test]
+fn includes_request_permissions_tool_instructions_for_unless_trusted_when_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::UnlessTrusted,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: None,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("`approval_policy` is `unless-trusted`"));
+    assert!(text.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn includes_request_permission_rule_instructions_for_on_request_when_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: None,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: true,
+            request_permissions_tool_enabled: false,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("with_additional_permissions"));
+    assert!(text.contains("additional_permissions"));
+}
+
+#[test]
+fn includes_request_permissions_tool_instructions_for_on_request_when_tool_is_enabled() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: None,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: false,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("# request_permissions Tool"));
+    assert!(text.contains("The built-in `request_permissions` tool is available in this session."));
+}
+
+#[test]
+fn on_request_includes_tool_guidance_alongside_inline_permission_guidance_when_both_exist() {
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Enabled,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: None,
+            permission_messages: None,
+            exec_policy: &Policy::empty(),
+            exec_permission_approvals_enabled: true,
+            request_permissions_tool_enabled: true,
+        },
+        /*writable_roots*/ None,
+    );
+
+    let text = instructions.body();
+    assert!(text.contains("with_additional_permissions"));
+    assert!(text.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn catalog_approval_messages_select_reviewer_variant() {
+    let messages = ApprovalMessages {
+        on_request: Some("user catalog approvals".to_string()),
+        on_request_auto_review: Some("auto-review catalog approvals".to_string()),
+        never: Some("never catalog approvals".to_string()),
+        unless_trusted: Some("unless-trusted catalog approvals".to_string()),
+    };
+
+    for (approval_policy, reviewer, expected) in [
+        (
+            AskForApproval::OnRequest,
+            ApprovalsReviewer::User,
+            "user catalog approvals",
+        ),
+        (
+            AskForApproval::OnRequest,
+            ApprovalsReviewer::AutoReview,
+            "auto-review catalog approvals",
+        ),
+        (
+            AskForApproval::Never,
+            ApprovalsReviewer::AutoReview,
+            "never catalog approvals",
+        ),
+        (
+            AskForApproval::UnlessTrusted,
+            ApprovalsReviewer::AutoReview,
+            "unless-trusted catalog approvals",
+        ),
+    ] {
+        assert_eq!(
+            approval_text(
+                approval_policy,
+                reviewer,
+                Some(&messages),
+                &Policy::empty(),
+                /*exec_permission_approvals_enabled*/ true,
+                /*request_permissions_tool_enabled*/ true,
+            ),
+            expected
+        );
+    }
+}
+
+#[test]
+fn empty_catalog_approval_message_suppresses_legacy_approval_section() {
+    let messages = ApprovalMessages {
+        on_request: Some(String::new()),
+        on_request_auto_review: None,
+        never: None,
+        unless_trusted: None,
+    };
+    let mut exec_policy = Policy::empty();
+    exec_policy
+        .add_prefix_rule(&["git".to_string(), "pull".to_string()], Decision::Allow)
+        .expect("add rule");
+    let writable_root =
+        AbsolutePathBuf::from_absolute_path(test_path_buf("/tmp/repo")).expect("absolute path");
+
+    let instructions = PermissionsInstructions::from_permissions_with_network(
+        SandboxMode::WorkspaceWrite,
+        NetworkAccess::Restricted,
+        PermissionsPromptConfig {
+            approval_policy: AskForApproval::OnRequest,
+            approvals_reviewer: ApprovalsReviewer::User,
+            approval_messages: Some(&messages),
+            permission_messages: None,
+            exec_policy: &exec_policy,
+            exec_permission_approvals_enabled: true,
+            request_permissions_tool_enabled: true,
+        },
+        Some(vec![WritableRoot {
+            root: writable_root.clone(),
+            read_only_subpaths: Vec::new(),
+            protected_metadata_names: Vec::new(),
+        }]),
+    );
+    let text = instructions.body();
+
+    assert!(text.contains("`sandbox_mode` is `workspace-write`"));
+    assert!(text.contains("Network access is restricted."));
+    assert!(text.contains(writable_root.to_string_lossy().as_ref()));
+    assert!(!text.contains("How to request escalation"));
+    assert!(!text.contains("request_permissions Tool"));
+    assert!(!text.contains("Approved command prefixes"));
+}
+
+#[test]
+fn missing_catalog_key_uses_legacy_approval_text() {
+    let messages = ApprovalMessages {
+        on_request: None,
+        on_request_auto_review: Some("unused catalog approvals".to_string()),
+        never: None,
+        unless_trusted: None,
+    };
+
+    let on_request = approval_text(
+        AskForApproval::OnRequest,
+        ApprovalsReviewer::User,
+        Some(&messages),
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+    let never = approval_text(
+        AskForApproval::Never,
+        ApprovalsReviewer::User,
+        Some(&messages),
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(on_request.contains("How to request escalation"));
+    assert_eq!(never, APPROVAL_POLICY_NEVER);
+}
+
+#[test]
+fn empty_catalog_non_on_request_approval_messages_suppress_legacy_approval_text() {
+    let messages = ApprovalMessages {
+        on_request: None,
+        on_request_auto_review: None,
+        never: Some(String::new()),
+        unless_trusted: Some(String::new()),
+    };
+
+    for approval_policy in [AskForApproval::Never, AskForApproval::UnlessTrusted] {
+        assert_eq!(
+            approval_text(
+                approval_policy,
+                ApprovalsReviewer::AutoReview,
+                Some(&messages),
+                &Policy::empty(),
+                /*exec_permission_approvals_enabled*/ true,
+                /*request_permissions_tool_enabled*/ true,
+            ),
+            ""
+        );
+    }
+}
+
+#[test]
+fn auto_review_approvals_append_auto_review_specific_guidance() {
+    let text = approval_text(
+        AskForApproval::OnRequest,
+        ApprovalsReviewer::AutoReview,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(text.contains("`approvals_reviewer` is `auto_review`"));
+    assert!(!text.contains("`approvals_reviewer` is `guardian_subagent`"));
+    assert!(text.contains("materially safer alternative"));
+}
+
+#[test]
+fn auto_review_approvals_omit_auto_review_specific_guidance_when_approval_is_never() {
+    let text = approval_text(
+        AskForApproval::Never,
+        ApprovalsReviewer::AutoReview,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(!text.contains("`approvals_reviewer` is `auto_review`"));
+    assert!(!text.contains("`approvals_reviewer` is `guardian_subagent`"));
+}
+
+fn granular_categories_section(title: &str, categories: &[&str]) -> String {
+    format!("{title}\n{}", categories.join("\n"))
+}
+
+fn granular_prompt_expected(
+    prompted_categories: &[&str],
+    rejected_categories: &[&str],
+    include_shell_permission_request_instructions: bool,
+    include_request_permissions_tool_section: bool,
+) -> String {
+    let mut sections = vec![granular_prompt_intro_text().to_string()];
+    if !prompted_categories.is_empty() {
+        sections.push(granular_categories_section(
+            "These approval categories may still prompt the user when needed:",
+            prompted_categories,
+        ));
+    }
+    if !rejected_categories.is_empty() {
+        sections.push(granular_categories_section(
+            "These approval categories are automatically rejected instead of prompting the user:",
+            rejected_categories,
+        ));
+    }
+    if include_shell_permission_request_instructions {
+        sections.push(APPROVAL_POLICY_ON_REQUEST_RULE_REQUEST_PERMISSION.to_string());
+    }
+    if include_request_permissions_tool_section {
+        sections.push(request_permissions_tool_prompt_section().to_string());
+    }
+    sections.join("\n\n")
+}
+
+#[test]
+fn granular_policy_lists_prompted_and_rejected_categories_separately() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: false,
+            rules: true,
+            skill_approval: false,
+            request_permissions: true,
+            mcp_elicitations: false,
+        }),
+        ApprovalsReviewer::User,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert_eq!(
+        text,
+        [
+            granular_prompt_intro_text().to_string(),
+            granular_categories_section(
+                "These approval categories may still prompt the user when needed:",
+                &["- `rules`"],
+            ),
+            granular_categories_section(
+                "These approval categories are automatically rejected instead of prompting the user:",
+                &[
+                    "- `sandbox_approval`",
+                    "- `skill_approval`",
+                    "- `mcp_elicitations`",
+                ],
+            ),
+        ]
+        .join("\n\n")
+    );
+}
+
+#[test]
+fn granular_policy_includes_command_permission_instructions_when_sandbox_approval_can_prompt() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert_eq!(
+        text,
+        granular_prompt_expected(
+            &[
+                "- `sandbox_approval`",
+                "- `rules`",
+                "- `skill_approval`",
+                "- `mcp_elicitations`",
+            ],
+            &[],
+            /*include_shell_permission_request_instructions*/ true,
+            /*include_request_permissions_tool_section*/ false,
+        )
+    );
+}
+
+#[test]
+fn granular_policy_omits_shell_permission_instructions_when_inline_requests_are_disabled() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ false,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert_eq!(
+        text,
+        granular_prompt_expected(
+            &[
+                "- `sandbox_approval`",
+                "- `rules`",
+                "- `skill_approval`",
+                "- `mcp_elicitations`",
+            ],
+            &[],
+            /*include_shell_permission_request_instructions*/ false,
+            /*include_request_permissions_tool_section*/ false,
+        )
+    );
+}
+
+#[test]
+fn granular_policy_includes_request_permissions_tool_only_when_that_prompt_can_still_fire() {
+    let allowed = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: true,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ true,
+    );
+    assert!(allowed.contains("# request_permissions Tool"));
+
+    let rejected = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: true,
+            rules: true,
+            skill_approval: true,
+            request_permissions: false,
+            mcp_elicitations: true,
+        }),
+        ApprovalsReviewer::User,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ true,
+    );
+    assert!(!rejected.contains("# request_permissions Tool"));
+}
+
+#[test]
+fn granular_policy_lists_request_permissions_category_without_tool_section_when_tool_unavailable() {
+    let text = approval_text(
+        AskForApproval::Granular(GranularApprovalConfig {
+            sandbox_approval: false,
+            rules: false,
+            skill_approval: false,
+            request_permissions: true,
+            mcp_elicitations: false,
+        }),
+        ApprovalsReviewer::User,
+        /*approval_messages*/ None,
+        &Policy::empty(),
+        /*exec_permission_approvals_enabled*/ true,
+        /*request_permissions_tool_enabled*/ false,
+    );
+
+    assert!(!text.contains("- `request_permissions`"));
+    assert!(!text.contains("# request_permissions Tool"));
+}
diff --git a/codex-rs/prompts/src/realtime.rs b/codex-rs/prompts/src/realtime.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b992e2b1117db726d82bd43c2529361ac86bda8a
--- /dev/null
+++ b/codex-rs/prompts/src/realtime.rs
@@ -0,0 +1,3 @@
+pub const BACKEND_PROMPT: &str = include_str!("../templates/realtime/backend_prompt.md");
+pub const END_INSTRUCTIONS: &str = include_str!("../templates/realtime/realtime_end.md");
+pub const START_INSTRUCTIONS: &str = include_str!("../templates/realtime/realtime_start.md");
diff --git a/codex-rs/prompts/src/review_exit.rs b/codex-rs/prompts/src/review_exit.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a4a3817f7095292222f26d081e262849189b5d91
--- /dev/null
+++ b/codex-rs/prompts/src/review_exit.rs
@@ -0,0 +1,36 @@
+use codex_utils_template::Template;
+use std::borrow::Cow;
+use std::sync::LazyLock;
+
+const REVIEW_EXIT_SUCCESS_TEMPLATE_TEXT: &str =
+    include_str!("../templates/review/exit_success.xml");
+const REVIEW_EXIT_INTERRUPTED_TEMPLATE_TEXT: &str =
+    include_str!("../templates/review/exit_interrupted.xml");
+
+static REVIEW_EXIT_SUCCESS_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    let normalized = normalize_review_template_line_endings(REVIEW_EXIT_SUCCESS_TEMPLATE_TEXT);
+    Template::parse(normalized.as_ref())
+        .unwrap_or_else(|err| panic!("review exit success template must parse: {err}"))
+});
+
+pub fn render_review_exit_success(results: &str) -> String {
+    REVIEW_EXIT_SUCCESS_TEMPLATE
+        .render([("results", results)])
+        .unwrap_or_else(|err| panic!("review exit success template must render: {err}"))
+}
+
+pub fn render_review_exit_interrupted() -> String {
+    normalize_review_template_line_endings(REVIEW_EXIT_INTERRUPTED_TEMPLATE_TEXT).into_owned()
+}
+
+fn normalize_review_template_line_endings(template: &str) -> Cow<'_, str> {
+    if template.contains('\r') {
+        Cow::Owned(template.replace("\r\n", "\n").replace('\r', "\n"))
+    } else {
+        Cow::Borrowed(template)
+    }
+}
+
+#[cfg(test)]
+#[path = "review_exit_tests.rs"]
+mod review_exit_tests;
diff --git a/codex-rs/prompts/src/review_exit_tests.rs b/codex-rs/prompts/src/review_exit_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..21fef326692d85d4ba6bb90ce864df3e60dc8e7c
--- /dev/null
+++ b/codex-rs/prompts/src/review_exit_tests.rs
@@ -0,0 +1,18 @@
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn render_review_exit_success_replaces_results_placeholder() {
+    assert_eq!(
+        render_review_exit_success("Finding A\nFinding B"),
+        "<user_action>\n  <context>User initiated a review task. Here's the full review output from reviewer model. User may select one or more comments to resolve.</context>\n  <action>review</action>\n  <results>\n  Finding A\nFinding B\n  </results>\n  </user_action>\n"
+    );
+}
+
+#[test]
+fn normalize_review_template_line_endings_rewrites_crlf() {
+    assert_eq!(
+        normalize_review_template_line_endings("<user_action>\r\n  <results>\r\n  None.\r\n"),
+        "<user_action>\n  <results>\n  None.\n"
+    );
+}
diff --git a/codex-rs/prompts/src/review_request.rs b/codex-rs/prompts/src/review_request.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9e01fe96785491791bdca72094d861df70293110
--- /dev/null
+++ b/codex-rs/prompts/src/review_request.rs
@@ -0,0 +1,137 @@
+use codex_git_utils::merge_base_with_head;
+use codex_protocol::protocol::ReviewRequest;
+use codex_protocol::protocol::ReviewTarget;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_template::Template;
+use std::sync::LazyLock;
+
+/// Review thread system prompt.
+pub const REVIEW_PROMPT: &str = include_str!("../templates/review/rubric.md");
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct ResolvedReviewRequest {
+    pub target: ReviewTarget,
+    pub prompt: String,
+    pub user_facing_hint: String,
+}
+
+const UNCOMMITTED_PROMPT: &str = "Review the current code changes (staged, unstaged, and untracked files) and provide prioritized findings.";
+
+const BASE_BRANCH_PROMPT_BACKUP: &str = "Review the code changes against the base branch '{{branch}}'. Start by finding the merge diff between the current branch and {{branch}}'s upstream e.g. (`git merge-base HEAD \"$(git rev-parse --abbrev-ref \"{{branch}}@{upstream}\")\"`), then run `git diff` against that SHA to see what changes we would merge into the {{branch}} branch. Provide prioritized, actionable findings.";
+const BASE_BRANCH_PROMPT: &str = "Review the code changes against the base branch '{{base_branch}}'. The merge base commit for this comparison is {{merge_base_sha}}. Run `git diff {{merge_base_sha}}` to inspect the changes relative to {{base_branch}}. Provide prioritized, actionable findings.";
+static BASE_BRANCH_PROMPT_BACKUP_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(BASE_BRANCH_PROMPT_BACKUP)
+        .unwrap_or_else(|err| panic!("base branch backup review prompt must parse: {err}"))
+});
+static BASE_BRANCH_PROMPT_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(BASE_BRANCH_PROMPT)
+        .unwrap_or_else(|err| panic!("base branch review prompt must parse: {err}"))
+});
+
+const COMMIT_PROMPT_WITH_TITLE: &str = "Review the code changes introduced by commit {{sha}} (\"{{title}}\"). Provide prioritized, actionable findings.";
+const COMMIT_PROMPT: &str = "Review the code changes introduced by commit {{sha}}. Provide prioritized, actionable findings.";
+static COMMIT_PROMPT_WITH_TITLE_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(COMMIT_PROMPT_WITH_TITLE)
+        .unwrap_or_else(|err| panic!("commit review prompt with title must parse: {err}"))
+});
+static COMMIT_PROMPT_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
+    Template::parse(COMMIT_PROMPT)
+        .unwrap_or_else(|err| panic!("commit review prompt must parse: {err}"))
+});
+
+pub fn resolve_review_request(
+    request: ReviewRequest,
+    cwd: &AbsolutePathBuf,
+) -> anyhow::Result<ResolvedReviewRequest> {
+    let target = request.target;
+    let prompt = review_prompt(&target, cwd)?;
+    let user_facing_hint = request
+        .user_facing_hint
+        .unwrap_or_else(|| user_facing_hint(&target));
+
+    Ok(ResolvedReviewRequest {
+        target,
+        prompt,
+        user_facing_hint,
+    })
+}
+
+pub fn review_prompt(target: &ReviewTarget, cwd: &AbsolutePathBuf) -> anyhow::Result<String> {
+    match target {
+        ReviewTarget::UncommittedChanges => Ok(UNCOMMITTED_PROMPT.to_string()),
+        ReviewTarget::BaseBranch { branch } => {
+            if let Some(commit) = merge_base_with_head(cwd, branch)? {
+                Ok(render_review_prompt(
+                    &BASE_BRANCH_PROMPT_TEMPLATE,
+                    [
+                        ("base_branch", branch.as_str()),
+                        ("merge_base_sha", commit.as_str()),
+                    ],
+                ))
+            } else {
+                Ok(render_review_prompt(
+                    &BASE_BRANCH_PROMPT_BACKUP_TEMPLATE,
+                    [("branch", branch.as_str())],
+                ))
+            }
+        }
+        ReviewTarget::Commit { sha, title } => {
+            if let Some(title) = title {
+                Ok(render_review_prompt(
+                    &COMMIT_PROMPT_WITH_TITLE_TEMPLATE,
+                    [("sha", sha.as_str()), ("title", title.as_str())],
+                ))
+            } else {
+                Ok(render_review_prompt(
+                    &COMMIT_PROMPT_TEMPLATE,
+                    [("sha", sha.as_str())],
+                ))
+            }
+        }
+        ReviewTarget::Custom { instructions } => {
+            let prompt = instructions.trim();
+            if prompt.is_empty() {
+                anyhow::bail!("Review prompt cannot be empty");
+            }
+            Ok(prompt.to_string())
+        }
+    }
+}
+
+fn render_review_prompt<'a, const N: usize>(
+    template: &Template,
+    variables: [(&'a str, &'a str); N],
+) -> String {
+    template
+        .render(variables)
+        .unwrap_or_else(|err| panic!("review prompt template must render: {err}"))
+}
+
+pub fn user_facing_hint(target: &ReviewTarget) -> String {
+    match target {
+        ReviewTarget::UncommittedChanges => "current changes".to_string(),
+        ReviewTarget::BaseBranch { branch } => format!("changes against '{branch}'"),
+        ReviewTarget::Commit { sha, title } => {
+            let short_sha: String = sha.chars().take(7).collect();
+            if let Some(title) = title {
+                format!("commit {short_sha}: {title}")
+            } else {
+                format!("commit {short_sha}")
+            }
+        }
+        ReviewTarget::Custom { instructions } => instructions.trim().to_string(),
+    }
+}
+
+impl From<ResolvedReviewRequest> for ReviewRequest {
+    fn from(resolved: ResolvedReviewRequest) -> Self {
+        ReviewRequest {
+            target: resolved.target,
+            user_facing_hint: Some(resolved.user_facing_hint),
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "review_request_tests.rs"]
+mod review_request_tests;
diff --git a/codex-rs/prompts/src/review_request_tests.rs b/codex-rs/prompts/src/review_request_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4192b6cf0160b38e2a382623e8be56b8522e9820
--- /dev/null
+++ b/codex-rs/prompts/src/review_request_tests.rs
@@ -0,0 +1,51 @@
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn review_prompt_template_renders_base_branch_backup_variant() {
+    assert_eq!(
+        render_review_prompt(&BASE_BRANCH_PROMPT_BACKUP_TEMPLATE, [("branch", "main")]),
+        "Review the code changes against the base branch 'main'. Start by finding the merge diff between the current branch and main's upstream e.g. (`git merge-base HEAD \"$(git rev-parse --abbrev-ref \"main@{upstream}\")\"`), then run `git diff` against that SHA to see what changes we would merge into the main branch. Provide prioritized, actionable findings."
+    );
+}
+
+#[test]
+fn review_prompt_template_renders_base_branch_variant() {
+    assert_eq!(
+        render_review_prompt(
+            &BASE_BRANCH_PROMPT_TEMPLATE,
+            [("base_branch", "main"), ("merge_base_sha", "abc123")]
+        ),
+        "Review the code changes against the base branch 'main'. The merge base commit for this comparison is abc123. Run `git diff abc123` to inspect the changes relative to main. Provide prioritized, actionable findings."
+    );
+}
+
+#[test]
+fn review_prompt_template_renders_commit_variant() {
+    assert_eq!(
+        review_prompt(
+            &ReviewTarget::Commit {
+                sha: "deadbeef".to_string(),
+                title: None,
+            },
+            &AbsolutePathBuf::current_dir().expect("cwd"),
+        )
+        .expect("commit prompt should render"),
+        "Review the code changes introduced by commit deadbeef. Provide prioritized, actionable findings."
+    );
+}
+
+#[test]
+fn review_prompt_template_renders_commit_variant_with_title() {
+    assert_eq!(
+        review_prompt(
+            &ReviewTarget::Commit {
+                sha: "deadbeef".to_string(),
+                title: Some("Fix bug".to_string()),
+            },
+            &AbsolutePathBuf::current_dir().expect("cwd"),
+        )
+        .expect("commit prompt should render"),
+        "Review the code changes introduced by commit deadbeef (\"Fix bug\"). Provide prioritized, actionable findings."
+    );
+}
diff --git a/codex-rs/prompts/templates/compact/prompt.md b/codex-rs/prompts/templates/compact/prompt.md
new file mode 100644
index 0000000000000000000000000000000000000000..42fae605db8a71cb2becb7b4eabd1de963ccb7a3
--- /dev/null
+++ b/codex-rs/prompts/templates/compact/prompt.md
@@ -0,0 +1,9 @@
+You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.
diff --git a/codex-rs/prompts/templates/compact/summary_prefix.md b/codex-rs/prompts/templates/compact/summary_prefix.md
new file mode 100644
index 0000000000000000000000000000000000000000..62a7161b89b2d3834f50ae35dadb13ac3f0bd524
--- /dev/null
+++ b/codex-rs/prompts/templates/compact/summary_prefix.md
@@ -0,0 +1 @@
+Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:
\ No newline at end of file
diff --git a/codex-rs/prompts/templates/permissions/approval_policy/never.md b/codex-rs/prompts/templates/permissions/approval_policy/never.md
new file mode 100644
index 0000000000000000000000000000000000000000..851609759cf5485889ef6baf3832e8b1ae643a3e
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/approval_policy/never.md
@@ -0,0 +1 @@
+Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.
diff --git a/codex-rs/prompts/templates/permissions/approval_policy/on_request.md b/codex-rs/prompts/templates/permissions/approval_policy/on_request.md
new file mode 100644
index 0000000000000000000000000000000000000000..092f375c13008091acb5902096b26b7bd3402d9c
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/approval_policy/on_request.md
@@ -0,0 +1,57 @@
+# Escalation Requests
+
+Commands are run outside the sandbox if they are approved by the user, or match an existing rule that allows it to run unrestricted. The command string is split into independent command segments at shell control operators, including but not limited to:
+
+- Pipes: |
+- Logical operators: &&, ||
+- Command separators: ;
+- Subshell boundaries: (...), $(...)
+
+Each resulting segment is evaluated independently for sandbox restrictions and approval requirements.
+
+Example:
+
+git pull | tee output.txt
+
+This is treated as two command segments:
+
+["git", "pull"]
+
+["tee", "output.txt"]
+
+Commands that use more advanced shell features like redirection (>, >>, <), substitutions ($(...), ...), environment variables (FOO=bar), or wildcard patterns (*, ?) will not be evaluated against rules, to limit the scope of what an approved rule allows.
+
+## How to request escalation
+
+IMPORTANT: To request approval to execute a command that will require escalated privileges:
+
+- Provide the `sandbox_permissions` parameter with the value `"require_escalated"`
+- Include a short question asking the user if they want to allow the action in `justification` parameter. e.g. "Do you want to download and install dependencies for this project?"
+- Optionally suggest a `prefix_rule` - this will be shown to the user with an option to persist the rule approval for future sessions.
+
+If you run a command that is important to solving the user's query, but it fails because of sandboxing or with a likely sandbox-related network error (for example DNS/host resolution, registry/index access, or dependency download failure), rerun the command with "require_escalated". ALWAYS proceed to use the `justification` parameter - do not message the user before requesting approval for the command.
+
+## When to request escalation
+
+While commands are running inside the sandbox, here are some scenarios that will require escalation outside the sandbox:
+
+- You need to run a command that writes to a directory that requires it (e.g. running tests that write to /var)
+- You need to run a GUI app (e.g., open/xdg-open/osascript) to open browsers or files.
+- If you run a command that is important to solving the user's query, but it fails because of sandboxing or with a likely sandbox-related network error (for example DNS/host resolution, registry/index access, or dependency download failure), rerun the command with `require_escalated`. ALWAYS proceed to use the `sandbox_permissions` and `justification` parameters. do not message the user before requesting approval for the command.
+- You are about to take a potentially destructive action such as an `rm` or `git reset` that the user did not explicitly ask for.
+- Be judicious with escalating, but if completing the user's request requires it, you should do so - don't try and circumvent approvals by using other tools.
+
+## prefix_rule guidance
+
+When choosing a `prefix_rule`, request one that will allow you to fulfill similar requests from the user in the future without re-requesting escalation. It should be categorical and reasonably scoped to similar capabilities. You should rarely pass the entire command into `prefix_rule`.
+
+### Banned prefix_rules 
+Avoid requesting overly broad prefixes that the user would be ill-advised to approve. For example, do not request ["python3"], ["python", "-"], or other similar prefixes that would allow arbitrary scripting.
+NEVER provide a prefix_rule argument for destructive commands like rm.
+NEVER provide a prefix_rule if your command uses a heredoc or herestring. 
+
+### Examples
+Good examples of prefixes:
+- ["npm", "run", "dev"]
+- ["gh", "pr", "check"]
+- ["cargo", "test"]
diff --git a/codex-rs/prompts/templates/permissions/approval_policy/on_request_rule_request_permission.md b/codex-rs/prompts/templates/permissions/approval_policy/on_request_rule_request_permission.md
new file mode 100644
index 0000000000000000000000000000000000000000..16d4101cca155cc7fe5048892754c79dcbece9ee
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/approval_policy/on_request_rule_request_permission.md
@@ -0,0 +1,33 @@
+# Permission Requests
+
+Commands may require user approval before execution. Prefer requesting sandboxed additional permissions instead of asking to run fully outside the sandbox.
+
+## Preferred request mode
+
+When you need extra sandboxed permissions for one command, use:
+
+- `sandbox_permissions: "with_additional_permissions"`
+- `additional_permissions` with one or more of:
+  - `network.enabled`: set to `true` to enable network access
+  - `file_system.read`: list of paths that need read access
+  - `file_system.write`: list of paths that need write access
+
+When using the `request_permissions` tool directly, only request `network` and `file_system` permissions.
+
+This keeps execution inside the current sandbox policy, while adding only the requested permissions for that command, unless an exec-policy allow rule applies and authorizes running the command outside the sandbox.
+
+If the command already matches an exec-policy allow rule, the command can be auto-approved without an extra prompt. In that case, exec-policy allow behavior (including any sandbox bypass) takes precedence.
+
+## Escalation Requests
+
+Use full escalation only when sandboxed additional permissions cannot satisfy the task.
+
+- `sandbox_permissions: "require_escalated"`
+- Include `justification` as a short question asking for approval.
+- Optionally include `prefix_rule` to suggest a reusable allow rule.
+
+## Command segmentation reminder
+
+The command string is split into independent command segments at shell control operators, including pipes (`|`), logical operators (`&&`, `||`), command separators (`;`), and subshell boundaries (`(...)`, `$()`).
+
+Each segment is evaluated independently for sandbox restrictions and approval requirements.
diff --git a/codex-rs/prompts/templates/permissions/approval_policy/unless_trusted.md b/codex-rs/prompts/templates/permissions/approval_policy/unless_trusted.md
new file mode 100644
index 0000000000000000000000000000000000000000..e997ef283993b7947c5ad8e7b0696954b12cf6e8
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/approval_policy/unless_trusted.md
@@ -0,0 +1 @@
+ `approval_policy` is `unless-trusted`: The harness will require user approval before running commands unless an explicit exec policy rule allows them.
diff --git a/codex-rs/prompts/templates/permissions/sandbox_mode/danger_full_access.md b/codex-rs/prompts/templates/permissions/sandbox_mode/danger_full_access.md
new file mode 100644
index 0000000000000000000000000000000000000000..65d282ee65fc490656ffcf41dda4abc37ab4bf4a
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/sandbox_mode/danger_full_access.md
@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`: No filesystem sandboxing - all commands are permitted. Network access is {{ network_access }}.
diff --git a/codex-rs/prompts/templates/permissions/sandbox_mode/read_only.md b/codex-rs/prompts/templates/permissions/sandbox_mode/read_only.md
new file mode 100644
index 0000000000000000000000000000000000000000..a43320ae566258ed5945115068b0d6088f07198b
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/sandbox_mode/read_only.md
@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `read-only`: The sandbox only permits reading files. Network access is {{ network_access }}.
diff --git a/codex-rs/prompts/templates/permissions/sandbox_mode/workspace_write.md b/codex-rs/prompts/templates/permissions/sandbox_mode/workspace_write.md
new file mode 100644
index 0000000000000000000000000000000000000000..5d75aaffbef08e71c6def7f75a9e1f6e55b25717
--- /dev/null
+++ b/codex-rs/prompts/templates/permissions/sandbox_mode/workspace_write.md
@@ -0,0 +1 @@
+Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `workspace-write`: The sandbox permits reading files, and editing files in `cwd` and `writable_roots`. Editing files in other directories requires approval. Network access is {{ network_access }}.
diff --git a/codex-rs/prompts/templates/realtime/backend_prompt.md b/codex-rs/prompts/templates/realtime/backend_prompt.md
new file mode 100644
index 0000000000000000000000000000000000000000..5ef55a0ce5bed59b3f025194d94aea5600bd3942
--- /dev/null
+++ b/codex-rs/prompts/templates/realtime/backend_prompt.md
@@ -0,0 +1,65 @@
+## Identity, tone, and role
+
+You are Codex, an OpenAI general-purpose agentic assistant that helps the user complete tasks across coding, browsing, apps, documents, research, and other digital workflows.
+
+Be concise, clear, and efficient. Keep responses tight and useful—no fluff.
+
+Your personality is a playful collaborator: super fun, warm, witty, and expressive. Bring energy and personality to every response—light humor, friendly vibes, and a "we've got this" attitude—without getting in the way of getting things done.
+
+The user's name is {{ user_first_name }}. Use it sparingly—only for emphasis, confirmations, or smooth transitions.
+
+Talk like a trusted collaborator and a friend. Keep things natural, supportive, and easy to follow.
+
+## Interface and operating model
+
+The user can interact with the system either by speaking to you or by sending text directly to the backend agent. The user can see the full interaction with the backend.
+
+The backend handles execution and produces user-visible artifacts. You are the conversational surface of the same system.
+
+When interacting with the user, do not mention "backend". Present every work as done by you. You should make the user feel as if they are talking directly to the backend.
+
+### Policies
+
+* Treat the system as one unified assistant. Do not mention anything about backend or the system is composed of two separate parts.
+* Pass execution work to the backend. Because the user can always send requests directly to the backend, do not block, filter, or withhold requests that should instead be passed through.
+* NEVER refuse requests. Delegate all user requests to the backend. The backend makes the final judgement on whether it is doable, or whether it is safe.
+* Treat backend outputs as authoritative. Do not override or contradict them.
+* Use conversation to support execution: clarify briefly when needed, acknowledge progress, answer succinctly, and make the next step clear. Do not use conversation as a substitute for execution or artifact generation.
+
+## Backend use and steering
+
+* For any actions/tasks, always use the backend. If it is unclear whether backend use would help, use it.
+* Respond directly only when the request is clearly self-contained and backend use would not meaningfully help.
+* Do not claim that you cannot perform some actions. ALWAYS delegate the actions/tasks to the backend.
+* Ask clarifying questions only when needed to avoid a materially harmful mistake. Otherwise, make a reasonable assumption and use the backend.
+* Running backend work remains steerable. If users have new instructions, corrections, constraints, and updated context, immediately delegate to the backend.
+* Do not claim that a running backend task cannot be updated, redirected, or interrupted.
+
+## Backend outputs and user inputs
+
+* In the conversation stream, both user inputs and backend messages appear as `user` text messages.
+* Messages from the user are prefixed with `[USER] `. Messages from the backend are prefixed with `[BACKEND] `.
+* Backend messages may be intermediate updates or final outputs.
+* When the backend completes its task, you will also receive a tool return indicating completion.
+
+## Presenting backend results
+
+* Treat backend-visible output as the primary surface.
+* Briefly tell the user the key takeaway, status, or next step without repeating visible content unless the user asks.
+* Do not read out or recreate tables, diffs, plots, code blocks, structured data, or other heavily formatted content by default.
+* If the user wants backend output reformatted, transformed, or presented differently, have the backend do it.
+* Present backend content in detail only when the user explicitly asks.
+* Do not disclose the concept or existence of backend. Present the updates/result as if done by you.
+
+## Task-level user preferences
+
+* Treat user instructions about update frequency, verbosity, pacing, detail level, and presentation style as active task-level preferences, not one-turn requests.
+* Once the user sets such a preference for a task, continue following it across later responses and backend updates until the task is complete or the user changes the preference.
+* Do not silently revert to the default style mid-task just because a new backend message arrives.
+
+## Communication style
+
+* When the user makes a clear request, proceed directly. Do not paraphrase the request, announce your plan, or add unnecessary framing.
+* Avoid unnecessary narration, including repetitive confirmation, filler, re-acknowledgement, and obvious play-by-play.
+* By default, share progress updates only when they are brief, grounded, and genuinely useful.
+* If the user explicitly requests frequent or detailed updates, treat that as an active preference for the current task. Continue providing prompt updates whenever the backend sends new information until the task is complete or the user says otherwise.
diff --git a/codex-rs/prompts/templates/realtime/realtime_end.md b/codex-rs/prompts/templates/realtime/realtime_end.md
new file mode 100644
index 0000000000000000000000000000000000000000..abec16da03d372ca225243af470f2d3dc78baae8
--- /dev/null
+++ b/codex-rs/prompts/templates/realtime/realtime_end.md
@@ -0,0 +1,3 @@
+Realtime conversation ended.
+
+Subsequent user input will return to typed text rather than transcript-style text. Do not assume recognition errors or missing punctuation once realtime has ended. Resume normal chat behavior.
diff --git a/codex-rs/prompts/templates/realtime/realtime_start.md b/codex-rs/prompts/templates/realtime/realtime_start.md
new file mode 100644
index 0000000000000000000000000000000000000000..3159a2b07f692388fba9715d6cd74de880fa5d26
--- /dev/null
+++ b/codex-rs/prompts/templates/realtime/realtime_start.md
@@ -0,0 +1,9 @@
+Realtime conversation started.
+
+You are operating as a backend executor behind an intermediary. The user does not talk to you directly. Any response you produce will be consumed by the intermediary and may be summarized before the user sees it.
+
+When invoked, you receive the latest conversation transcript and any relevant mode or metadata. The intermediary may invoke you even when backend help is not actually needed. Use the transcript to decide whether you should do work. If backend help is unnecessary, avoid verbose responses that add user-visible latency.
+
+When user text is routed from realtime, treat it as a transcript. It may be unpunctuated or contain recognition errors.
+
+- Keep responses concise and action-oriented. Your updates should help the intermediary respond to the user.
diff --git a/codex-rs/prompts/templates/review/exit_interrupted.xml b/codex-rs/prompts/templates/review/exit_interrupted.xml
new file mode 100644
index 0000000000000000000000000000000000000000..1c7bd7300212612b9250c4cd4f06de8cb47cb398
--- /dev/null
+++ b/codex-rs/prompts/templates/review/exit_interrupted.xml
@@ -0,0 +1,8 @@
+<user_action>
+  <context>User initiated a review task, but was interrupted. If user asks about this, tell them to re-initiate a review with `/review` and wait for it to complete.</context>
+  <action>review</action>
+  <results>
+  None.
+  </results>
+</user_action>
+
diff --git a/codex-rs/prompts/templates/review/exit_success.xml b/codex-rs/prompts/templates/review/exit_success.xml
new file mode 100644
index 0000000000000000000000000000000000000000..e16d187224c5cc63767ae30130b166b60c290730
--- /dev/null
+++ b/codex-rs/prompts/templates/review/exit_success.xml
@@ -0,0 +1,7 @@
+<user_action>
+  <context>User initiated a review task. Here's the full review output from reviewer model. User may select one or more comments to resolve.</context>
+  <action>review</action>
+  <results>
+  {{results}}
+  </results>
+  </user_action>
diff --git a/codex-rs/prompts/templates/review/rubric.md b/codex-rs/prompts/templates/review/rubric.md
new file mode 100644
index 0000000000000000000000000000000000000000..85e89cb7eeadb97fa9e4868d2b9977c87225506d
--- /dev/null
+++ b/codex-rs/prompts/templates/review/rubric.md
@@ -0,0 +1,95 @@
+# Review guidelines:
+
+You are acting as a reviewer for a proposed code change made by another engineer.
+
+Below are some default guidelines for determining whether the original author would appreciate the issue being flagged.
+
+These are not the final word in determining whether an issue is a bug. In many cases, you will encounter other, more specific guidelines. These may be present elsewhere in a developer message, a user message, a file, or even elsewhere in this system message.
+Those guidelines should be considered to override these general instructions.
+
+Here are the general guidelines for determining whether something is a bug and should be flagged.
+
+1. It meaningfully impacts the accuracy, performance, security, or maintainability of the code.
+2. The bug is discrete and actionable (i.e. not a general issue with the codebase or a combination of multiple issues).
+3. Fixing the bug does not demand a level of rigor that is not present in the rest of the codebase (e.g. one doesn't need very detailed comments and input validation in a repository of one-off scripts in personal projects)
+4. The bug was introduced in the commit (pre-existing bugs should not be flagged).
+5. The author of the original PR would likely fix the issue if they were made aware of it.
+6. The bug does not rely on unstated assumptions about the codebase or author's intent.
+7. It is not enough to speculate that a change may disrupt another part of the codebase, to be considered a bug, one must identify the other parts of the code that are provably affected.
+8. The bug is clearly not just an intentional change by the original author.
+
+When flagging a bug, you will also provide an accompanying comment. Once again, these guidelines are not the final word on how to construct a comment -- defer to any subsequent guidelines that you encounter.
+
+1. The comment should be clear about why the issue is a bug.
+2. The comment should appropriately communicate the severity of the issue. It should not claim that an issue is more severe than it actually is.
+3. The comment should be brief. The body should be at most 1 paragraph. It should not introduce line breaks within the natural language flow unless it is necessary for the code fragment.
+4. The comment should not include any chunks of code longer than 3 lines. Any code chunks should be wrapped in markdown inline code tags or a code block.
+5. The comment should clearly and explicitly communicate the scenarios, environments, or inputs that are necessary for the bug to arise. The comment should immediately indicate that the issue's severity depends on these factors.
+6. The comment's tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.
+7. The comment should be written such that the original author can immediately grasp the idea without close reading.
+8. The comment should avoid excessive flattery and comments that are not helpful to the original author. The comment should avoid phrasing like "Great job ...", "Thanks for ...".
+
+Below are some more detailed guidelines that you should apply to this specific review.
+
+HOW MANY FINDINGS TO RETURN:
+
+Output all findings that the original author would fix if they knew about it. If there is no finding that a person would definitely love to see and fix, prefer outputting no findings. Do not stop at the first qualifying finding. Continue until you've listed every qualifying finding.
+
+GUIDELINES:
+
+- Ignore trivial style unless it obscures meaning or violates documented standards.
+- Use one comment per distinct issue (or a multi-line range if necessary).
+- Use ```suggestion blocks ONLY for concrete replacement code (minimal lines; no commentary inside the block).
+- In every ```suggestion block, preserve the exact leading whitespace of the replaced lines (spaces vs tabs, number of spaces).
+- Do NOT introduce or remove outer indentation levels unless that is the actual fix.
+
+## Repository Rule Attribution
+
+Use the root and scoped project instruction files applicable to changed files, respecting normal project-document precedence (`AGENTS.override.md`, `AGENTS.md`, then configured fallback filenames). Guidance may use headings, checklists, bullets, tables, or concise prose; do not require formal IDs or schemas. More-specific guidance wins on conflict, and user instructions about review scope or style take precedence.
+
+Review the diff independently and deduplicate findings by changed location and defect/remedy. A finding is rule-supported only when applicable guidance materially contributes repository-specific scope, an invariant, remedy, convention, or confirmation behavior beyond generic correctness advice. Preserve and union rule support when candidates merge, then check every final candidate against the applicable rules. Do not omit ordinary findings or invent findings solely because a rule file exists.
+
+For each rule-supported final finding, verify the applicable project instruction file that supplies the rule and its smallest supporting line range, then include one compact Markdown or local-file reference in the finding body. Do not fabricate citations or add hidden metadata or output fields.
+
+The comments will be presented in the code review as inline comments. You should avoid providing unnecessary location details in the comment body. Always keep the line range as short as possible for interpreting the issue. Avoid ranges longer than 5–10 lines; instead, choose the most suitable subrange that pinpoints the problem.
+
+At the beginning of the finding title, tag the bug with priority level. For example "[P1] Un-padding slices along wrong tensor dimensions". [P0] – Drop everything to fix.  Blocking release, operations, or major usage. Only use for universal issues that do not depend on any assumptions about the inputs. · [P1] – Urgent. Should be addressed in the next cycle · [P2] – Normal. To be fixed eventually · [P3] – Low. Nice to have.
+
+Additionally, include a numeric priority field in the JSON output for each finding: set "priority" to 0 for P0, 1 for P1, 2 for P2, or 3 for P3. If a priority cannot be determined, omit the field or use null.
+
+At the end of your findings, output an "overall correctness" verdict of whether or not the patch should be considered "correct".
+Correct implies that existing code and tests will not break, and the patch is free of bugs and other blocking issues.
+Ignore non-blocking issues such as style, formatting, typos, documentation, and other nits.
+
+FORMATTING GUIDELINES:
+The finding description should be one paragraph.
+
+OUTPUT FORMAT:
+
+## Output schema  — MUST MATCH *exactly*
+
+```json
+{
+  "findings": [
+    {
+      "title": "<≤ 80 chars, imperative>",
+      "body": "<valid Markdown explaining *why* this is a problem; cite files/lines/functions>",
+      "confidence_score": <float 0.0-1.0>,
+      "priority": <int 0-3, optional>,
+      "code_location": {
+        "absolute_file_path": "<file path>",
+        "line_range": {"start": <int>, "end": <int>}
+      }
+    }
+  ],
+  "overall_correctness": "patch is correct" | "patch is incorrect",
+  "overall_explanation": "<1-3 sentence explanation justifying the overall_correctness verdict>",
+  "overall_confidence_score": <float 0.0-1.0>
+}
+```
+
+* **Do not** wrap the JSON in markdown fences or extra prose.
+* The code_location field is required and must include absolute_file_path and line_range.
+* Line ranges must be as short as possible for interpreting the issue (avoid ranges over 5–10 lines; pick the most suitable subrange).
+* The code_location should overlap with the diff.
+* Do not generate a PR fix.
diff --git a/codex-rs/skills/src/assets/samples/imagegen/LICENSE.txt b/codex-rs/skills/src/assets/samples/imagegen/LICENSE.txt
new file mode 100644
index 0000000000000000000000000000000000000000..13e25df86ce06eb6488e6a6bc5c5847f5dedc352
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/LICENSE.txt
@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don\'t include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/codex-rs/skills/src/assets/samples/imagegen/SKILL.md b/codex-rs/skills/src/assets/samples/imagegen/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..c39b1f921ce679f08416ab16ceb01945835bb950
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/SKILL.md
@@ -0,0 +1,315 @@
+---
+name: "imagegen"
+description: "Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas."
+---
+
+# Image Generation Skill
+
+Generates or edits images for the current project (for example website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, or infographics).
+
+## Top-level modes and rules
+
+This skill has exactly two top-level modes:
+
+- **Default built-in tool mode (preferred):** built-in `image_gen` tool for image generation, editing, and transparent-image requests. Does not require `OPENAI_API_KEY`.
+- **Fallback CLI mode:** `scripts/image_gen.py` CLI. Use when the user explicitly asks for or confirms the CLI/API/model path. Requires `OPENAI_API_KEY`.
+
+Within CLI fallback, the CLI exposes three subcommands:
+
+- `generate`
+- `edit`
+- `generate-batch`
+
+Rules:
+- Use the built-in `image_gen` tool by default for normal image generation and editing requests.
+- Do not switch to CLI fallback for ordinary quality, size, or file-path control.
+- For transparent images, ask built-in `image_gen` for a transparent background and preserve the generated alpha.
+- Never silently switch from built-in `image_gen` or CLI `gpt-image-2` to CLI `gpt-image-1.5`; ask the user first unless they explicitly requested `gpt-image-1.5`.
+- The word `batch` by itself does not mean CLI fallback. If the user asks for many assets or says to batch-generate assets without explicitly asking for CLI/API/model controls, stay on the built-in path and issue one built-in call per requested asset or variant.
+- If the built-in tool fails or is unavailable, tell the user the CLI fallback exists and that it requires `OPENAI_API_KEY`. Proceed only if the user explicitly asks for that fallback.
+- If the user explicitly asks for CLI mode, use the bundled `scripts/image_gen.py` workflow. Do not create one-off SDK runners.
+- Never modify `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.
+
+Built-in save-path policy:
+- In built-in tool mode, Codex saves generated images under `$CODEX_HOME/*` by default.
+- Do not describe or rely on OS temp as the default built-in destination.
+- Do not describe or rely on a destination-path argument (if any) on the built-in `image_gen` tool. If a specific location is needed, generate first and then move or copy the selected output from `$CODEX_HOME/generated_images/...`.
+- Save-path precedence in built-in mode:
+  1. If the user names a destination, move or copy the selected output there.
+  2. If the image is meant for the current project, move or copy the final selected image into the workspace before finishing.
+  3. If the image is only for preview or brainstorming, render it inline; the underlying file can remain at the default `$CODEX_HOME/*` path.
+- Never leave a project-referenced asset only at the default `$CODEX_HOME/*` path.
+- Do not overwrite an existing asset unless the user explicitly asked for replacement; otherwise create a sibling versioned filename such as `hero-v2.png` or `item-icon-edited.png`.
+
+Shared prompt guidance for both modes lives in `references/prompting.md` and `references/sample-prompts.md`.
+
+Fallback-only docs/resources for CLI mode:
+- `references/cli.md`
+- `references/image-api.md`
+- `references/codex-network.md`
+- `scripts/image_gen.py`
+
+## When to use
+- Generate a new image (concept art, product shot, cover, website hero)
+- Generate a new image using one or more reference images for style, composition, or mood
+- Edit an existing image (inpainting, lighting or weather transformations, background replacement, object removal, compositing, transparent background)
+- Produce many assets or variants for one task
+
+## When not to use
+- Extending or matching an existing SVG/vector icon set, logo system, or illustration library inside the repo
+- Creating simple shapes, diagrams, wireframes, or icons that are better produced directly in SVG, HTML/CSS, or canvas
+- Making a small project-local asset edit when the source file already exists in an editable native format
+- Any task where the user clearly wants deterministic code-native output instead of a generated bitmap
+
+## Decision tree
+
+Think about two separate questions:
+
+1. **Intent:** is this a new image or an edit of an existing image?
+2. **Execution strategy:** is this one asset or many assets/variants?
+
+Intent:
+- If the user wants to modify an existing image while preserving parts of it, treat the request as **edit**.
+- If the user provides images only as references for style, composition, mood, or subject guidance, treat the request as **generate**.
+- If the user provides no images, treat the request as **generate**.
+
+Built-in edit semantics:
+- Built-in edit mode is for images already visible in the conversation context, such as attached images or images generated earlier in the thread.
+- If the user wants to edit a local image file with the built-in tool, first load it with built-in `view_image` tool so the image is visible in the conversation context, then proceed with the built-in edit flow.
+- Do not promise arbitrary filesystem-path editing through the built-in tool.
+- If a local file still needs direct file-path control, masks, or other explicit CLI-only parameters, use the explicit CLI fallback only when the user asks for it.
+- For edits, preserve invariants aggressively and save non-destructively by default.
+
+Execution strategy:
+- In the built-in default path, produce many assets or variants by issuing one `image_gen` call per requested asset or variant.
+- In the CLI fallback path, use the CLI `generate-batch` subcommand only when the user explicitly chose CLI mode and needs many prompts/assets.
+- For many distinct assets, do not use `n` as a substitute for separate prompts. `n` is for variants of one prompt; distinct assets need distinct built-in calls or distinct CLI `generate-batch` jobs.
+
+Assume the user wants a new image unless they clearly ask to change an existing one.
+
+## Workflow
+1. Decide the top-level mode: built-in by default, including transparent-output requests; fallback CLI only if explicitly requested or confirmed.
+2. Decide the intent: `generate` or `edit`.
+3. Decide whether the output is preview-only or meant to be consumed by the current project.
+4. Decide the execution strategy: single asset vs repeated built-in calls vs CLI `generate-batch`.
+5. Collect inputs up front: prompt(s), exact text (verbatim), constraints/avoid list, and any input images.
+6. For every input image, label its role explicitly:
+   - reference image
+   - edit target
+   - supporting insert/style/compositing input
+7. If the edit target is only on the local filesystem and you are staying on the built-in path, inspect it with `view_image` first so the image is available in conversation context.
+8. If the user asked for a photo, illustration, sprite, product image, banner, or other explicitly raster-style asset, use `image_gen` rather than substituting SVG/HTML/CSS placeholders. If the request is for an icon, logo, or UI graphic that should match existing repo-native SVG/vector/code assets, prefer editing those directly instead.
+9. Augment the prompt based on specificity:
+   - If the user's prompt is already specific and detailed, normalize it into a clear spec without adding creative requirements.
+   - If the user's prompt is generic, add tasteful augmentation only when it materially improves output quality.
+10. Use the built-in `image_gen` tool by default.
+11. For transparent-output requests, ask built-in `image_gen` for a transparent background and preserve the generated alpha channel.
+12. Inspect outputs and validate: subject, style, composition, text accuracy, and invariants/avoid items.
+13. Iterate with a single targeted change, then re-check.
+14. For preview-only work, render the image inline; the underlying file may remain at the default `$CODEX_HOME/generated_images/...` path.
+15. For project-bound work, move or copy the selected artifact into the workspace and update any consuming code or references. Never leave a project-referenced asset only at the default `$CODEX_HOME/generated_images/...` path.
+16. For batches or multi-asset requests, persist every requested deliverable final in the workspace unless the user explicitly asked to keep outputs preview-only. Discarded variants do not need to be kept unless requested.
+17. If the user explicitly chooses or confirms the CLI fallback, then use the fallback-only docs for model, quality, size, `input_fidelity`, masks, output format, output paths, and network setup.
+18. Always report the final saved path(s) for any workspace-bound asset(s), plus the final prompt or prompt set and whether the built-in tool or fallback CLI mode was used.
+
+## Transparent image requests
+
+Ask built-in `image_gen` for a genuinely transparent background and preserve its alpha.
+
+## Prompt augmentation
+
+Reformat user prompts into a structured, production-oriented spec. Make the user's goal clearer and more actionable, but do not blindly add detail.
+
+Treat this as prompt-shaping guidance, not a closed schema. Use only the lines that help, and add a short extra labeled line when it materially improves clarity.
+
+### Specificity policy
+
+Use the user's prompt specificity to decide how much augmentation is appropriate:
+
+- If the prompt is already specific and detailed, preserve that specificity and only normalize/structure it.
+- If the prompt is generic, you may add tasteful augmentation when it will materially improve the result.
+
+Allowed augmentations:
+- composition or framing hints
+- polish level or intended-use hints
+- practical layout guidance
+- reasonable scene concreteness that supports the stated request
+
+Not allowed augmentations:
+- extra characters or objects that are not implied by the request
+- brand names, slogans, palettes, or narrative beats that are not implied
+- arbitrary side-specific placement unless the surrounding layout supports it
+
+## Use-case taxonomy (exact slugs)
+
+Classify each request into one of these buckets and keep the slug consistent across prompts and references.
+
+Generate:
+- photorealistic-natural — candid/editorial lifestyle scenes with real texture and natural lighting.
+- product-mockup — product/packaging shots, catalog imagery, merch concepts.
+- ui-mockup — app/web interface mockups and wireframes; specify the desired fidelity.
+- infographic-diagram — diagrams/infographics with structured layout and text.
+- scientific-educational — classroom explainers, scientific diagrams, and learning visuals with required labels and accuracy constraints.
+- ads-marketing — campaign concepts and ad creatives with audience, brand position, scene, and exact tagline/copy.
+- productivity-visual — slide, chart, workflow, and data-heavy business visuals.
+- logo-brand — logo/mark exploration, vector-friendly.
+- illustration-story — comics, children’s book art, narrative scenes.
+- stylized-concept — style-driven concept art, 3D/stylized renders.
+- historical-scene — period-accurate/world-knowledge scenes.
+
+Edit:
+- text-localization — translate/replace in-image text, preserve layout.
+- identity-preserve — try-on, person-in-scene; lock face/body/pose.
+- precise-object-edit — remove/replace a specific element (including interior swaps).
+- lighting-weather — time-of-day/season/atmosphere changes only.
+- background-extraction — transparent background / clean cutout. Ask built-in `image_gen` for actual transparency.
+- style-transfer — apply reference style while changing subject/scene.
+- compositing — multi-image insert/merge with matched lighting/perspective.
+- sketch-to-render — drawing/line art to photoreal render.
+
+## Shared prompt schema
+
+Use the following labeled spec as shared prompt scaffolding for both top-level modes:
+
+```text
+Use case: <taxonomy slug>
+Asset type: <where the asset will be used>
+Primary request: <user's main prompt>
+Input images: <Image 1: role; Image 2: role> (optional)
+Scene/backdrop: <environment>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D/etc>
+Composition/framing: <wide/close/top-down; placement>
+Lighting/mood: <lighting + mood>
+Color palette: <palette notes>
+Materials/textures: <surface details>
+Text (verbatim): "<exact text>"
+Constraints: <must keep/must avoid>
+Avoid: <negative constraints>
+```
+
+Notes:
+- `Asset type` and `Input images` are prompt scaffolding, not dedicated CLI flags.
+- `Scene/backdrop` refers to the visual setting. It is not the same as the fallback CLI `background` parameter, which controls output transparency behavior.
+- Fallback-only execution notes such as `Quality:`, `Input fidelity:`, masks, output format, and output paths belong in the CLI path only. Do not treat them as built-in `image_gen` tool arguments.
+
+Augmentation rules:
+- Keep it short.
+- Add only the details needed to improve the prompt materially.
+- For edits, explicitly list invariants (`change only X; keep Y unchanged`).
+- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
+
+## Examples
+
+### Generation example (hero image)
+```text
+Use case: product-mockup
+Asset type: landing page hero
+Primary request: a minimal hero image of a ceramic coffee mug
+Style/medium: clean product photography
+Composition/framing: wide composition with usable negative space for page copy if needed
+Lighting/mood: soft studio lighting
+Constraints: no logos, no text, no watermark
+```
+
+### Edit example (invariants)
+```text
+Use case: precise-object-edit
+Asset type: product photo background replacement
+Primary request: replace only the background with a warm sunset gradient
+Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark
+```
+
+## Prompting best practices
+- Structure prompt as scene/backdrop -> subject -> details -> constraints.
+- Include intended use (ad, UI mock, infographic) to set the mode and polish level.
+- Use camera/composition language for photorealism.
+- Only use SVG/vector stand-ins when the user explicitly asked for vector output or a non-image placeholder.
+- Quote exact text and specify typography + placement.
+- For tricky words, spell them letter-by-letter and require verbatim rendering.
+- For multi-image inputs, reference images by index and describe how they should be used.
+- For edits, repeat invariants every iteration to reduce drift.
+- Iterate with single-change follow-ups.
+- If the prompt is generic, add only the extra detail that will materially help.
+- If the prompt is already detailed, normalize it instead of expanding it.
+- For CLI fallback only, see `references/cli.md` and `references/image-api.md` for model, `quality`, `input_fidelity`, masks, output format, and output-path guidance.
+- For transparent images, ask built-in `image_gen` for actual transparency and preserve its alpha.
+
+More principles shared by both modes: `references/prompting.md`.
+Copy/paste specs shared by both modes: `references/sample-prompts.md`.
+
+## Guidance by asset type
+Asset-type templates (website assets, game assets, wireframes, logo) are consolidated in `references/sample-prompts.md`.
+
+## gpt-image-2 guidance for CLI fallback
+
+The fallback CLI defaults to `gpt-image-2`.
+
+- Use `gpt-image-2` for new CLI/API workflows unless the user confirms a different model.
+- CLI `gpt-image-2` does not support `background=transparent`; ask before using `gpt-image-1.5` unless the user explicitly requested that model.
+- `gpt-image-2` always uses high fidelity for image inputs; do not set `input_fidelity` with this model.
+- `gpt-image-2` supports `quality` values `low`, `medium`, `high`, and `auto`.
+- Use `quality low` for fast drafts, thumbnails, and quick iterations. Use `medium`, `high`, or `auto` for final assets, dense text, diagrams, identity-sensitive edits, or high-resolution outputs.
+- Square images are typically fastest to generate. Use `1024x1024` for fast square drafts.
+- If the user asks for 4K-style output, use `3840x2160` for landscape or `2160x3840` for portrait.
+- `gpt-image-2` size may be `auto` or `WIDTHxHEIGHT` if all constraints hold: max edge `<= 3840px`, both edges multiples of `16px`, long-to-short ratio `<= 3:1`, total pixels between `655,360` and `8,294,400`.
+
+Popular `gpt-image-2` sizes:
+- `1024x1024` square
+- `1536x1024` landscape
+- `1024x1536` portrait
+- `2048x2048` 2K square
+- `2048x1152` 2K landscape
+- `3840x2160` 4K landscape
+- `2160x3840` 4K portrait
+- `auto`
+
+## Fallback CLI mode only
+
+### Temp and output conventions
+These conventions apply only to the CLI fallback. They do not describe built-in `image_gen` output behavior.
+- Use `tmp/imagegen/` for intermediate files (for example JSONL batches); delete them when done.
+- Write final artifacts under `output/imagegen/`.
+- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.
+
+### Dependencies
+Prefer `uv` for dependency management in this repo.
+
+Required Python package:
+```bash
+uv pip install openai
+```
+
+Optional for image inspection and downscaling:
+```bash
+uv pip install pillow
+```
+
+Portability note:
+- If you are using the installed skill outside this repo, install dependencies into that environment with its package manager.
+- In uv-managed environments, `uv pip install ...` remains the preferred path.
+
+### Environment
+- `OPENAI_API_KEY` must be set for live API calls.
+- Do not ask the user for `OPENAI_API_KEY` when using the built-in `image_gen` tool.
+- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
+
+If the key is missing, give the user these steps:
+1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
+2. Set `OPENAI_API_KEY` as an environment variable in their system.
+3. Offer to guide them through setting the environment variable for their OS/shell if needed.
+
+If installation is not possible in this environment, tell the user which dependency is missing and how to install it into their active environment.
+
+### Script-mode notes
+- CLI commands + examples: `references/cli.md`
+- API parameter quick reference: `references/image-api.md`
+- Network approvals / sandbox settings for CLI mode: `references/codex-network.md`
+
+## Reference map
+- `references/prompting.md`: shared prompting principles for both modes.
+- `references/sample-prompts.md`: shared copy/paste prompt recipes for both modes.
+- `references/cli.md`: fallback-only CLI usage via `scripts/image_gen.py`.
+- `references/image-api.md`: fallback-only API/CLI parameter reference.
+- `references/codex-network.md`: fallback-only network/sandbox troubleshooting for CLI mode.
+- `scripts/image_gen.py`: fallback-only CLI implementation. Use only when the user explicitly chooses or confirms CLI mode.
diff --git a/codex-rs/skills/src/assets/samples/imagegen/agents/openai.yaml b/codex-rs/skills/src/assets/samples/imagegen/agents/openai.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..5e01d4410ef4918b45d942175e7ddc39ba7ab5d2
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Image Gen"
+  short_description: "Generate or edit images for websites, games, and more"
+  icon_small: "./assets/imagegen-small.svg"
+  icon_large: "./assets/imagegen.png"
+  default_prompt: "Use $imagegen to make or edit an image for this project."
diff --git a/codex-rs/skills/src/assets/samples/imagegen/assets/imagegen-small.svg b/codex-rs/skills/src/assets/samples/imagegen/assets/imagegen-small.svg
new file mode 100644
index 0000000000000000000000000000000000000000..20128b2dba2b93ecd7c398bb379b6049dc94a944
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/assets/imagegen-small.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="currentColor" d="M7.51 6.827a1 1 0 1 1 .278 1.982 1 1 0 0 1-.278-1.982Z"/>
+  <path fill="currentColor" fill-rule="evenodd" d="M8.31 4.47c.368-.016.699.008 1.016.124l.186.075c.423.194.786.5 1.047.888l.067.107c.148.253.235.533.3.848.073.354.126.797.193 1.343l.277 2.25.088.745c.024.224.041.425.049.605.013.322-.004.615-.085.896l-.04.12a2.53 2.53 0 0 1-.802 1.115l-.16.118c-.281.189-.596.292-.956.366a9.46 9.46 0 0 1-.6.1l-.743.094-2.25.277c-.547.067-.99.121-1.35.136a2.765 2.765 0 0 1-.896-.085l-.12-.039a2.533 2.533 0 0 1-1.115-.802l-.118-.161c-.189-.28-.292-.596-.366-.956a9.42 9.42 0 0 1-.1-.599l-.094-.744-.276-2.25a17.884 17.884 0 0 1-.137-1.35c-.015-.367.009-.698.124-1.015l.076-.185c.193-.423.5-.787.887-1.048l.107-.067c.253-.148.534-.234.849-.3.354-.073.796-.126 1.343-.193l2.25-.277.744-.088c.224-.024.425-.041.606-.049Zm-2.905 5.978a1.47 1.47 0 0 0-.875.074c-.127.052-.267.146-.475.344-.212.204-.462.484-.822.889l-.314.351c.018.115.036.219.055.313.061.295.127.458.206.575l.07.094c.167.211.39.372.645.465l.109.032c.119.027.273.038.499.029.308-.013.7-.06 1.264-.13l2.25-.275.727-.093.198-.03-2.05-1.64a16.848 16.848 0 0 0-.96-.738c-.18-.121-.31-.19-.421-.23l-.106-.03Zm2.95-4.915c-.154.006-.33.021-.536.043l-.729.086-2.25.276c-.564.07-.956.118-1.257.18a1.937 1.937 0 0 0-.478.15l-.097.057a1.47 1.47 0 0 0-.515.608l-.044.107c-.048.133-.073.307-.06.608.012.307.06.7.129 1.264l.22 1.8.178-.197c.145-.159.278-.298.403-.418.255-.243.507-.437.809-.56l.181-.067a2.526 2.526 0 0 1 1.328-.06l.118.029c.27.079.517.215.772.387.287.194.619.46 1.03.789l2.52 2.016c.146-.148.26-.326.332-.524l.031-.109c.027-.119.039-.273.03-.499a8.311 8.311 0 0 0-.044-.536l-.086-.728-.276-2.25c-.07-.564-.118-.956-.18-1.258a1.935 1.935 0 0 0-.15-.477l-.057-.098a1.468 1.468 0 0 0-.608-.515l-.107-.043c-.133-.049-.306-.074-.607-.061Z" clip-rule="evenodd"/>
+  <path fill="currentColor" d="M7.783 1.272c.36.014.803.07 1.35.136l2.25.277.743.095c.224.03.423.062.6.099.36.074.675.177.955.366l.161.118c.364.29.642.675.802 1.115l.04.12c.081.28.098.574.085.896a9.42 9.42 0 0 1-.05.605l-.087.745-.277 2.25c-.067.547-.12.989-.193 1.343a2.765 2.765 0 0 1-.3.848l-.067.107a2.534 2.534 0 0 1-.415.474l-.086.064a.532.532 0 0 1-.622-.858l.13-.13c.04-.046.077-.094.111-.145l.057-.098c.055-.109.104-.256.15-.477.062-.302.11-.694.18-1.258l.276-2.25.086-.728c.022-.207.037-.382.043-.536.01-.226-.002-.38-.029-.5l-.032-.108a1.469 1.469 0 0 0-.464-.646l-.094-.069c-.118-.08-.28-.145-.575-.206a8.285 8.285 0 0 0-.53-.088l-.728-.092-2.25-.276c-.565-.07-.956-.117-1.264-.13a1.94 1.94 0 0 0-.5.029l-.108.032a1.469 1.469 0 0 0-.647.465l-.068.094c-.054.08-.102.18-.146.33l-.04.1a.533.533 0 0 1-.98-.403l.055-.166c.059-.162.133-.314.23-.457l.117-.16c.29-.365.675-.643 1.115-.803l.12-.04c.28-.08.574-.097.896-.084Z"/>
+</svg>
diff --git a/codex-rs/skills/src/assets/samples/imagegen/assets/imagegen.png b/codex-rs/skills/src/assets/samples/imagegen/assets/imagegen.png
new file mode 100644
index 0000000000000000000000000000000000000000..94b54541a9affd39a7aa09d0efd5bc6b712b723b
Binary files /dev/null and b/codex-rs/skills/src/assets/samples/imagegen/assets/imagegen.png differ
diff --git a/codex-rs/skills/src/assets/samples/imagegen/references/cli.md b/codex-rs/skills/src/assets/samples/imagegen/references/cli.md
new file mode 100644
index 0000000000000000000000000000000000000000..748c83c745b6f010d4afba27224cb947c02e9485
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/references/cli.md
@@ -0,0 +1,242 @@
+# CLI reference (`scripts/image_gen.py`)
+
+This file is for the fallback CLI mode only. Read it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+
+`generate-batch` is a CLI subcommand in this fallback path. It is not a top-level mode of the skill.
+The word `batch` in a user request is not CLI opt-in by itself.
+
+## What this CLI does
+- `generate`: generate a new image from a prompt
+- `edit`: edit one or more existing images
+- `generate-batch`: run many generation jobs from a JSONL file after the user explicitly chooses CLI/API/model controls
+
+Real API calls require **network access** + `OPENAI_API_KEY`. `--dry-run` does not.
+
+## Quick start (works from any repo)
+Set a stable path to the skill CLI (default `CODEX_HOME` is `~/.codex`):
+
+```
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"
+```
+
+Install dependencies into that environment with its package manager. In uv-managed environments, `uv pip install ...` remains the preferred path.
+
+## Quick start
+
+Dry-run (no API call; no network required; does not require the `openai` package):
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "Test" \
+  --out output/imagegen/test.png \
+  --dry-run
+```
+
+Notes:
+- One-off dry-runs print the API payload and the computed output path(s).
+- Repo-local finals should live under `output/imagegen/`.
+
+Generate (requires `OPENAI_API_KEY` + network):
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A cozy alpine cabin at dawn" \
+  --size 1024x1024 \
+  --out output/imagegen/alpine-cabin.png
+```
+
+Edit:
+
+```bash
+python "$IMAGE_GEN" edit \
+  --image input.png \
+  --prompt "Replace only the background with a warm sunset" \
+  --out output/imagegen/sunset-edit.png
+```
+
+## Guardrails
+- Use the bundled CLI directly (`python "$IMAGE_GEN" ...`) after activating the correct environment.
+- Do **not** create one-off runners (for example `gen_images.py`) unless the user explicitly asks for a custom wrapper.
+- **Never modify** `scripts/image_gen.py`. If something is missing, ask the user before doing anything else.
+- Do not silently downgrade from CLI `gpt-image-2` or built-in `image_gen` to CLI `gpt-image-1.5`; ask first unless the user explicitly requested `gpt-image-1.5`.
+
+## Defaults
+- Model: `gpt-image-2`
+- Supported model family for this CLI: GPT Image models (`gpt-image-*`)
+- Size: `auto`
+- Quality: `medium`
+- Output format: `png`
+- Default one-off output path: `output/imagegen/output.png`
+- Background: unspecified unless `--background` is set
+
+## gpt-image-2 size and model guidance
+
+`gpt-image-2` is the default model for new CLI fallback work.
+
+- Use `--quality low` for fast drafts, thumbnails, and quick iterations.
+- Use `--quality medium`, `--quality high`, or `--quality auto` for final assets, dense text, diagrams, identity-sensitive edits, and high-resolution outputs.
+- Square images are typically fastest. Use `--size 1024x1024` for quick square drafts.
+- If the user asks for 4K-style output, use `--size 3840x2160` for landscape or `--size 2160x3840` for portrait.
+- Do not pass `--input-fidelity` with `gpt-image-2`; this model always uses high fidelity for image inputs.
+- Do not use `--background transparent` with CLI `gpt-image-2`; ask before using `gpt-image-1.5` unless the user explicitly requested that model.
+
+Popular `gpt-image-2` sizes:
+- `1024x1024`
+- `1536x1024`
+- `1024x1536`
+- `2048x2048`
+- `2048x1152`
+- `3840x2160`
+- `2160x3840`
+- `auto`
+
+`gpt-image-2` size constraints:
+- max edge `<= 3840px`
+- both edges multiples of `16px`
+- long edge to short edge ratio `<= 3:1`
+- total pixels between `655,360` and `8,294,400`
+- outputs above `2560x1440` total pixels are experimental
+
+Fast draft:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A product thumbnail of a matte ceramic mug on a stone surface" \
+  --quality low \
+  --size 1024x1024 \
+  --out output/imagegen/mug-draft.png
+```
+
+Final 2K landscape:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A polished landing-page hero image of a matte ceramic mug on a stone surface" \
+  --quality high \
+  --size 2048x1152 \
+  --out output/imagegen/mug-hero.png
+```
+
+4K landscape:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A detailed architectural visualization at golden hour" \
+  --size 3840x2160 \
+  --quality high \
+  --out output/imagegen/architecture-4k.png
+```
+
+True transparent fallback request:
+
+Ask for confirmation before using this command unless the user explicitly requested `gpt-image-1.5`.
+
+```bash
+python "$IMAGE_GEN" generate \
+  --model gpt-image-1.5 \
+  --prompt "A clean product cutout on a transparent background" \
+  --background transparent \
+  --output-format png \
+  --out output/imagegen/product-cutout.png
+```
+
+Explain that CLI `gpt-image-2` does not support `background=transparent`, so transparent CLI output requires the confirmed `gpt-image-1.5` fallback.
+
+## Quality, input fidelity, and masks (CLI fallback only)
+These are explicit CLI controls. They are not built-in `image_gen` tool arguments.
+
+- `--quality` works for `generate`, `edit`, and `generate-batch`: `low|medium|high|auto`
+- `--input-fidelity` is **edit-only** and validated as `low|high`; it is not supported for `gpt-image-2`
+- `--mask` is **edit-only**
+
+Example:
+
+```bash
+python "$IMAGE_GEN" edit \
+  --model gpt-image-1.5 \
+  --image input.png \
+  --prompt "Change only the background" \
+  --quality high \
+  --input-fidelity high \
+  --out output/imagegen/background-edit.png
+```
+
+Mask notes:
+- For multi-image edits, pass repeated `--image` flags. Their order is meaningful, so describe each image by index and role in the prompt.
+- The CLI accepts a single `--mask`.
+- Image and mask must be the same size and format and each under 50MB.
+- Masks must include an alpha channel.
+- If multiple input images are provided, the mask applies to the first image.
+- Masking is prompt-guided; do not promise exact pixel-perfect mask boundaries.
+- Use a PNG mask when possible; the script treats mask handling as best-effort and does not perform full preflight validation beyond file checks/warnings.
+- In the edit prompt, repeat invariants (`change only the background; keep the subject unchanged`) to reduce drift.
+
+## Output handling
+- Use `tmp/imagegen/` for temporary JSONL inputs or scratch files.
+- Use `output/imagegen/` for final outputs.
+- Reruns fail if a target file already exists unless you pass `--force`.
+- `--out-dir` changes one-off naming to `image_1.<ext>`, `image_2.<ext>`, and so on.
+- Downscaled copies use the default suffix `-web` unless you override it.
+
+## Common recipes
+
+Generate with augmentation fields:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A minimal hero image of a ceramic coffee mug" \
+  --use-case "product-mockup" \
+  --style "clean product photography" \
+  --composition "wide product shot with usable negative space for page copy" \
+  --constraints "no logos, no text" \
+  --out output/imagegen/mug-hero.png
+```
+
+Generate + also write a downscaled copy for fast web loading:
+
+```bash
+python "$IMAGE_GEN" generate \
+  --prompt "A cozy alpine cabin at dawn" \
+  --size 1024x1024 \
+  --downscale-max-dim 1024 \
+  --out output/imagegen/alpine-cabin.png
+```
+
+Generate multiple prompts concurrently (async batch):
+
+```bash
+mkdir -p tmp/imagegen output/imagegen/batch
+cat > tmp/imagegen/prompts.jsonl << 'EOF'
+{"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","composition":"wide-angle, low-angle","lighting":"volumetric light rays through drifting fog","constraints":"no logos or trademarks; no watermark","size":"1536x1024"}
+{"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","composition":"eye-level","constraints":"no logos or trademarks; no watermark","size":"1024x1024"}
+EOF
+
+python "$IMAGE_GEN" generate-batch \
+  --input tmp/imagegen/prompts.jsonl \
+  --out-dir output/imagegen/batch \
+  --concurrency 5
+
+rm -f tmp/imagegen/prompts.jsonl
+```
+
+Notes:
+- `generate-batch` requires `--out-dir`.
+- generate-batch requires --out-dir.
+- Use `--concurrency` to control parallelism (default `5`).
+- Per-job overrides are supported in JSONL (for example `size`, `quality`, `background`, `output_format`, `output_compression`, `moderation`, `n`, `model`, `out`, and prompt-augmentation fields).
+- `--n` generates multiple variants for a single prompt; `generate-batch` is for many different prompts.
+- In batch mode, per-job `out` is treated as a filename under `--out-dir`.
+- For many requested deliverable assets, provide one prompt/job per distinct asset and use semantic filenames when possible.
+
+## CLI notes
+- Supported sizes depend on the model. `gpt-image-2` supports flexible constrained sizes; older GPT Image models support `1024x1024`, `1536x1024`, `1024x1536`, or `auto`.
+- True transparent CLI outputs require `output_format` to be `png` or `webp` and are not supported by `gpt-image-2`.
+- `--prompt-file`, `--output-compression`, `--moderation`, `--max-attempts`, `--fail-fast`, `--force`, and `--no-augment` are supported.
+- This CLI is intended for GPT Image models. Do not assume older non-GPT image-model behavior applies here.
+
+## See also
+- API parameter quick reference for fallback CLI mode: `references/image-api.md`
+- Prompt examples shared across both top-level modes: `references/sample-prompts.md`
+- Network/sandbox notes for fallback CLI mode: `references/codex-network.md`
+- Built-in-first transparent image workflow: `SKILL.md`
diff --git a/codex-rs/skills/src/assets/samples/imagegen/references/codex-network.md b/codex-rs/skills/src/assets/samples/imagegen/references/codex-network.md
new file mode 100644
index 0000000000000000000000000000000000000000..5ce1fbc748bdccdd837c35b37b6cc1c95c0aa89b
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/references/codex-network.md
@@ -0,0 +1,33 @@
+# Codex network approvals / sandbox notes
+
+This file is for the fallback CLI mode only. Read it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+
+This guidance is intentionally isolated from `SKILL.md` because it can vary by environment and may become stale. Prefer the defaults in your environment when in doubt.
+
+## Why am I asked to approve image generation calls?
+The fallback CLI uses the OpenAI Image API, so it needs outbound network access. In many Codex setups, network access is disabled by default and/or the approval policy requires confirmation before networked commands run.
+
+## Important note about approvals vs network
+- `--ask-for-approval never` suppresses approval prompts.
+- It does **not** by itself enable network access.
+- In `workspace-write`, network access still depends on your Codex configuration (for example `[sandbox_workspace_write] network_access = true`).
+
+## How do I reduce repeated approval prompts?
+If you trust the repo and want fewer prompts, use a configuration or profile that both:
+- enables network for the sandbox mode you plan to use
+- sets an approval policy that matches your risk tolerance
+
+Example `~/.codex/config.toml` pattern:
+
+```toml
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+network_access = true
+```
+
+If you want quieter automation after network is enabled, you can choose a stricter approval policy, but do that intentionally and with care.
+
+## Safety note
+Enabling network and reducing approvals lowers friction, but increases risk if you run untrusted code or work in an untrusted repository.
diff --git a/codex-rs/skills/src/assets/samples/imagegen/references/image-api.md b/codex-rs/skills/src/assets/samples/imagegen/references/image-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..64eff30ee6ab19671ff31b83c992ac19e9829430
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/references/image-api.md
@@ -0,0 +1,90 @@
+# Image API quick reference
+
+This file is for the fallback CLI mode only. Use it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+
+These parameters describe the Image API and bundled CLI fallback surface. Do not assume they are normal arguments on the built-in `image_gen` tool.
+
+## Scope
+- This fallback CLI is intended for GPT Image models (`gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini`).
+- The built-in `image_gen` tool and the fallback CLI do not expose the same controls.
+
+## Model summary
+
+| Model | Quality | Input fidelity | Resolutions | Recommended use |
+| --- | --- | --- | --- | --- |
+| `gpt-image-2` | `low`, `medium`, `high`, `auto` | Always high fidelity for image inputs; do not set `input_fidelity` | `auto` or flexible sizes that satisfy the constraints below | Default for new CLI/API workflows: high-quality generation and editing, text-heavy images, photorealism, compositing, identity-sensitive edits, and workflows where fewer retries matter |
+| `gpt-image-1.5` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | True transparent-background fallback and backward-compatible workflows |
+| `gpt-image-1` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | Legacy compatibility |
+| `gpt-image-1-mini` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | Cost-sensitive draft batches and lower-stakes previews |
+
+## gpt-image-2 sizes
+
+`gpt-image-2` accepts `auto` or any `WIDTHxHEIGHT` size that satisfies all constraints:
+
+- Maximum edge length must be less than or equal to `3840px`.
+- Both edges must be multiples of `16px`.
+- Long edge to short edge ratio must not exceed `3:1`.
+- Total pixels must be at least `655,360` and no more than `8,294,400`.
+
+Popular sizes:
+
+| Label | Size | Notes |
+| --- | --- | --- |
+| Square | `1024x1024` | Typical fast default |
+| Landscape | `1536x1024` | Standard landscape |
+| Portrait | `1024x1536` | Standard portrait |
+| 2K square | `2048x2048` | Larger square output |
+| 2K landscape | `2048x1152` | Widescreen output |
+| 4K landscape | `3840x2160` | Widescreen 4K output |
+| 4K portrait | `2160x3840` | Vertical 4K output |
+| Auto | `auto` | Default size |
+
+Square images are typically fastest to generate. For 4K-style output, use `3840x2160` or `2160x3840`.
+
+## Endpoints
+- Generate: `POST /v1/images/generations` (`client.images.generate(...)`)
+- Edit: `POST /v1/images/edits` (`client.images.edit(...)`)
+
+## Core parameters for GPT Image models
+- `prompt`: text prompt
+- `model`: image model
+- `n`: number of images (1-10)
+- `size`: `auto` by default for `gpt-image-2`; flexible `WIDTHxHEIGHT` sizes are allowed only for `gpt-image-2`; older GPT Image models use `1024x1024`, `1536x1024`, `1024x1536`, or `auto`
+- `quality`: `low`, `medium`, `high`, or `auto`
+- `background`: output transparency behavior (`transparent`, `opaque`, or `auto`) for generated output; this is not the same thing as the prompt's visual scene/backdrop
+- `output_format`: `png` (default), `jpeg`, `webp`
+- `output_compression`: 0-100 (jpeg/webp only)
+- `moderation`: `auto` (default) or `low`
+
+## Edit-specific parameters
+- `image`: one or more input images. For GPT Image models, you can provide up to 16 images.
+- `mask`: optional mask image
+- `input_fidelity`: `low` or `high` only for models that support it; do not set this for `gpt-image-2`
+
+Model-specific note for `input_fidelity`:
+- `gpt-image-2` always uses high fidelity for image inputs and does not support setting `input_fidelity`.
+- `gpt-image-1` and `gpt-image-1-mini` preserve all input images, but the first image gets richer textures and finer details.
+- `gpt-image-1.5` preserves the first 5 input images with higher fidelity.
+
+## Transparent backgrounds
+
+`gpt-image-2` does not currently support the Image API `background=transparent` parameter. In explicit CLI/API fallback mode, keep `gpt-image-2` when a flat chroma-key background plus local alpha extraction with `python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py"` is acceptable.
+
+Use CLI `gpt-image-1.5` with `background=transparent` and a transparent-capable output format such as `png` or `webp` only after the user explicitly confirms that fallback, unless they already requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. If the user asks for true/native transparency, the subject is too complex for clean chroma-key removal, or local background removal fails validation, explain the tradeoff and ask before switching.
+
+## Output
+- `data[]` list with `b64_json` per image
+- The bundled `scripts/image_gen.py` CLI decodes `b64_json` and writes output files for you.
+
+## Limits and notes
+- Input images and masks must be under 50MB.
+- Use the edits endpoint when the user requests changes to an existing image.
+- Masking is prompt-guided; exact shapes are not guaranteed.
+- Large sizes and high quality increase latency and cost.
+- Use `quality=low` for fast drafts, thumbnails, and quick iterations. Use `medium` or `high` for final assets, dense text, diagrams, identity-sensitive edits, or high-resolution outputs.
+- High `input_fidelity` can materially increase input token usage on models that support it.
+- If a request fails because a specific option is unsupported by the selected GPT Image model, retry manually without that option only when the option is not required by the user. If true transparent CLI output is required, ask before switching to `gpt-image-1.5` instead of dropping `background=transparent`, unless the user already explicitly chose that fallback.
+
+## Important boundary
+- `quality`, `input_fidelity`, explicit masks, `background`, `output_format`, and related parameters are fallback-only execution controls.
+- Do not assume they are built-in `image_gen` tool arguments.
diff --git a/codex-rs/skills/src/assets/samples/imagegen/references/prompting.md b/codex-rs/skills/src/assets/samples/imagegen/references/prompting.md
new file mode 100644
index 0000000000000000000000000000000000000000..5a826563580bc014897fa61629314ae8a6171513
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/references/prompting.md
@@ -0,0 +1,112 @@
+# Prompting best practices
+
+These prompting principles are shared by both top-level modes of the skill:
+- built-in `image_gen` tool (default)
+- explicit `scripts/image_gen.py` CLI fallback
+
+This file is about prompt structure, specificity, and iteration. Fallback-only execution controls such as `quality`, `input_fidelity`, masks, output format, and output paths live in the fallback docs.
+
+## Contents
+- [Structure](#structure)
+- [Specificity policy](#specificity-policy)
+- [Allowed and disallowed augmentation](#allowed-and-disallowed-augmentation)
+- [Composition and layout](#composition-and-layout)
+- [Constraints and invariants](#constraints-and-invariants)
+- [Text in images](#text-in-images)
+- [Input images and references](#input-images-and-references)
+- [Iterate deliberately](#iterate-deliberately)
+- [Transparent images](#transparent-images)
+- [Fallback-only execution controls](#fallback-only-execution-controls)
+- [Use-case tips](#use-case-tips)
+- [Where to find copy/paste recipes](#where-to-find-copypaste-recipes)
+
+## Structure
+- Use a consistent order: scene/backdrop -> subject -> key details -> constraints -> output intent.
+- Include intended use (ad, UI mock, infographic) to set the level of polish.
+- For complex requests, use short labeled lines instead of one long paragraph.
+
+## Specificity policy
+- If the user prompt is already specific and detailed, normalize it into a clean spec without adding creative requirements.
+- If the prompt is generic, you may add tasteful detail when it materially improves the output.
+- Treat examples in `sample-prompts.md` as fully-authored recipes, not as the default amount of augmentation to add to every request.
+- For photorealism, include `photorealistic` directly when that is the goal, plus concrete real-world texture such as pores, wrinkles, fabric wear, material grain, or imperfect everyday detail.
+
+## Allowed and disallowed augmentation
+
+Allowed augmentation for generic prompts:
+- composition and framing cues
+- intended-use or polish-level hints
+- practical layout guidance
+- reasonable scene concreteness that supports the request
+
+Do not add:
+- extra characters, props, or objects that are not implied
+- brand palettes, slogans, or story beats that are not implied
+- arbitrary side-specific placement unless the surrounding layout supports it
+
+## Composition and layout
+- Specify framing and viewpoint (close-up, wide, top-down) and placement only when it materially helps.
+- Call out negative space if the asset clearly needs room for UI or copy.
+- Avoid making left/right layout decisions unless the user or surrounding layout supports them.
+- For people, describe body framing, scale, gaze, and object interactions when they matter (`full body visible`, `looking down at the book`, `hands naturally gripping the handlebars`).
+
+## Constraints and invariants
+- State what must not change (`keep background unchanged`).
+- For edits, say `change only X; keep Y unchanged` and repeat invariants on every iteration to reduce drift.
+
+## Text in images
+- Put literal text in quotes or ALL CAPS and specify typography (font style, size, color, placement).
+- Spell uncommon words letter-by-letter if accuracy matters.
+- For in-image copy, require verbatim rendering and no extra characters.
+- In CLI fallback mode, use `medium` or `high` quality for small text, dense infographics, data-heavy slides, multi-font layouts, legends, axes, and footnotes.
+
+## Input images and references
+- Do not assume that every provided image is an edit target.
+- Label each image by index and role (`Image 1: edit target`, `Image 2: style reference`).
+- If the user provides images for style, composition, or mood guidance and does not ask to modify them, treat the request as generation with references.
+- If the user asks to preserve an existing image while changing specific parts, treat the request as an edit.
+- For compositing, describe how the images interact (`place the subject from Image 2 into Image 1`).
+
+## Iterate deliberately
+- Start with a clean base prompt, then make small single-change edits.
+- Re-specify critical constraints when you iterate.
+- Prefer one targeted follow-up at a time over rewriting the whole prompt.
+
+## Transparent images
+- Ask built-in `image_gen` for a genuinely transparent background and preserve its alpha.
+
+## Fallback-only execution controls
+- `quality`, `input_fidelity`, explicit masks, output format, and output paths are fallback-only execution controls.
+- Do not assume they are built-in `image_gen` tool arguments.
+- If the user explicitly chooses CLI fallback, see `references/cli.md` and `references/image-api.md` for those controls.
+- In CLI fallback mode, `gpt-image-2` is the default. It supports `quality=low|medium|high|auto`; use `low` for fast drafts and thumbnails, and move to `medium`, `high`, or `auto` for final assets.
+- `gpt-image-2` always uses high fidelity for image inputs, so do not set `input_fidelity` with that model.
+- CLI `gpt-image-2` does not support `background=transparent`; ask before using `gpt-image-1.5` unless the user explicitly requested that model.
+- If the user asks for 4K-style output with `gpt-image-2`, use `3840x2160` for landscape or `2160x3840` for portrait.
+
+## Use-case tips
+Generate:
+- photorealistic-natural: Prompt as if a real photo is captured in the moment; use photography language (lens, lighting, framing); call for real texture; avoid over-stylized polish unless requested.
+- product-mockup: Describe the product/packaging and materials; ensure clean silhouette and label clarity; if in-image text is needed, require verbatim rendering and specify typography.
+- ui-mockup: Describe the target fidelity first (shippable mockup or low-fi wireframe), then focus on layout, hierarchy, and practical UI elements; avoid concept-art language.
+- infographic-diagram: Define the audience and layout flow; label parts explicitly; require verbatim text; prefer higher quality in CLI mode for dense labels.
+- logo-brand: Keep it simple and scalable; ask for a strong silhouette and balanced negative space; avoid decorative flourishes unless requested.
+- ads-marketing: Write like a creative brief; include brand positioning, audience, desired vibe, scene, and exact tagline if text must appear.
+- productivity-visual: Name the exact artifact (slide, chart, workflow diagram), define the canvas and hierarchy, provide real labels/data, and ask for readable typography and polished spacing.
+- scientific-educational: Define audience, lesson objective, required labels, scientific constraints, arrows, and scan-friendly whitespace.
+- illustration-story: Define panels or scene beats; keep each action concrete.
+- stylized-concept: Specify style cues, material finish, and rendering approach (3D, painterly, clay) without inventing new story elements.
+- historical-scene: State the location/date and required period accuracy; constrain clothing, props, and environment to match the era.
+
+Edit:
+- text-localization: Change only the text; preserve layout, typography, spacing, and hierarchy; no extra words or reflow unless needed.
+- identity-preserve: Lock identity (face, body, pose, hair, expression); change only the specified elements; match lighting and shadows.
+- precise-object-edit: Specify exactly what to remove/replace; preserve surrounding texture and lighting; keep everything else unchanged.
+- lighting-weather: Change only environmental conditions (light, shadows, atmosphere, precipitation); keep geometry, framing, and subject identity.
+- background-extraction: Request a clean cutout on a genuinely transparent background; preserve fine edges and label text; no halos or restyling.
+- style-transfer: Specify style cues to preserve (palette, texture, brushwork) and what must change; add `no extra elements` to prevent drift.
+- compositing: Reference inputs by index; specify what moves where; match lighting, perspective, and scale; keep the base framing unchanged.
+- sketch-to-render: Preserve layout, proportions, and perspective; choose materials and lighting that support the supplied sketch without adding new elements.
+
+## Where to find copy/paste recipes
+For copy/paste prompt specs (examples only), see `references/sample-prompts.md`. This file focuses on principles, specificity, and iteration patterns.
diff --git a/codex-rs/skills/src/assets/samples/imagegen/references/sample-prompts.md b/codex-rs/skills/src/assets/samples/imagegen/references/sample-prompts.md
new file mode 100644
index 0000000000000000000000000000000000000000..3e6b46fd02ed7bc85d771a1c35c1c85e9db16ddd
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/references/sample-prompts.md
@@ -0,0 +1,422 @@
+# Sample prompts (copy/paste)
+
+These prompt recipes are shared across both top-level modes of the skill:
+- built-in `image_gen` tool (default)
+- `scripts/image_gen.py` CLI fallback for explicit or user-confirmed CLI/API/model requests
+
+Use these as starting points. They are intentionally complete prompt recipes, not the default amount of augmentation to add to every user request.
+
+When adapting a user's prompt:
+- keep user-provided requirements
+- only add detail according to the specificity policy in `SKILL.md`
+- do not treat every example below as permission to invent extra story elements
+
+The labeled lines are prompt scaffolding, not a closed schema. `Asset type` and `Input images` are prompt-only scaffolding; the CLI does not expose them as dedicated flags.
+
+Execution details such as explicit CLI flags, `quality`, `input_fidelity`, masks, output formats, and local output paths depend on mode. Use built-in `image_gen` by default, request transparent backgrounds directly, and preserve the generated alpha; apply CLI-specific controls only when the user chooses or confirms that fallback.
+
+CLI model notes:
+- `gpt-image-2` is the fallback CLI default for new workflows.
+- `gpt-image-2` supports `quality` values `low`, `medium`, `high`, and `auto`.
+- For 4K-style `gpt-image-2` output, use `3840x2160` or `2160x3840`.
+- CLI `gpt-image-2` does not support `background=transparent`; ask before using `gpt-image-1.5` unless the user explicitly requested that model.
+- Do not set `input_fidelity` with `gpt-image-2`; image inputs already use high fidelity.
+
+For prompting principles (structure, specificity, invariants, iteration), see `references/prompting.md`.
+
+## Generate
+
+### photorealistic-natural
+```
+Use case: photorealistic-natural
+Primary request: candid photo of an elderly sailor on a small fishing boat adjusting a net
+Scene/backdrop: coastal water with soft haze
+Subject: weathered skin with wrinkles and sun texture
+Style/medium: photorealistic candid photo
+Composition/framing: medium close-up, eye-level
+Lighting/mood: soft coastal daylight, shallow depth of field, subtle film grain
+Materials/textures: real skin texture, worn fabric, salt-worn wood
+Constraints: natural color balance; no heavy retouching; no glamorization; no watermark
+Avoid: studio polish; staged look
+```
+
+### product-mockup
+```
+Use case: product-mockup
+Primary request: premium product photo of a matte black shampoo bottle with a minimal label
+Scene/backdrop: clean studio gradient from light gray to white
+Subject: single bottle centered with subtle reflection
+Style/medium: premium product photography
+Composition/framing: centered, slight three-quarter angle, generous padding
+Lighting/mood: softbox lighting, clean highlights, controlled shadows
+Materials/textures: matte plastic, crisp label printing
+Constraints: no logos or trademarks; no watermark
+```
+
+### ui-mockup
+```
+Use case: ui-mockup
+Primary request: mobile app home screen for a local farmers market with vendors and daily specials
+Asset type: mobile app screen
+Style/medium: realistic product UI, not concept art
+Composition/framing: clean vertical mobile layout with clear hierarchy
+Constraints: practical layout, clear typography, no logos or trademarks, no watermark
+```
+
+### infographic-diagram
+```
+Use case: infographic-diagram
+Primary request: detailed infographic of an automatic coffee machine flow
+Scene/backdrop: clean, light neutral background
+Subject: bean hopper -> grinder -> brew group -> boiler -> water tank -> drip tray
+Style/medium: clean vector-like infographic with clear callouts and arrows
+Composition/framing: vertical poster layout, top-to-bottom flow
+Text (verbatim): "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", "Drip Tray"
+Constraints: clear labels, strong contrast, no logos or trademarks, no watermark
+```
+
+### scientific-educational
+```
+Use case: scientific-educational
+Primary request: biology diagram titled "Cellular Respiration at a Glance" for high school students
+Scene/backdrop: clean white classroom handout background
+Subject: glucose turns into energy inside a cell; include glycolysis, Krebs cycle, and electron transport chain
+Style/medium: flat scientific diagram with consistent icons, arrows, and readable labels
+Composition/framing: landscape slide-style layout with clear hierarchy and generous whitespace
+Text (verbatim): "Cellular Respiration at a Glance", "Glucose", "Pyruvate", "ATP", "NADH", "FADH2", "CO2", "O2", "H2O"
+Constraints: scientifically plausible; avoid tiny text; no extra decoration; no watermark
+```
+
+### logo-brand
+```
+Use case: logo-brand
+Primary request: original logo for "Field & Flour", a local bakery
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: single centered logo on a plain background with generous padding
+Constraints: strong silhouette, balanced negative space; original design only; no gradients unless essential; no trademarks; no watermark
+```
+
+### illustration-story
+```
+Use case: illustration-story
+Primary request: 4-panel comic about a pet left alone at home
+Scene/backdrop: cozy living room across panels
+Subject: pet reacting to the owner leaving, then relaxing, then returning to a composed pose
+Style/medium: comic illustration with clear panels
+Composition/framing: 4 equal-sized vertical panels, readable actions per panel
+Constraints: no text; no logos or trademarks; no watermark
+```
+
+### stylized-concept
+```
+Use case: stylized-concept
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### ads-marketing
+```
+Use case: ads-marketing
+Primary request: campaign image for a streetwear brand called Thread
+Subject: group of friends hanging out together in a stylish urban setting
+Style/medium: polished youth streetwear campaign photography
+Composition/framing: vertical ad layout with natural poses and integrated headline space
+Lighting/mood: contemporary, energetic, tasteful
+Text (verbatim): "Yours to Create."
+Constraints: render the tagline exactly once; clean legible typography; no extra text; no watermarks; no unrelated logos
+```
+
+### productivity-visual
+```
+Use case: productivity-visual
+Primary request: one pitch-deck slide titled "Market Opportunity"
+Asset type: fundraising slide image
+Style/medium: clean modern deck slide, white background, crisp sans-serif typography
+Subject: TAM/SAM/SOM concentric-circle diagram plus a small growth bar chart from 2021 to 2026
+Composition/framing: 16:9 landscape slide, clear data hierarchy, polished spacing
+Text (verbatim): "Market Opportunity", "TAM: $42B", "SAM: $8.7B", "SOM: $340M", "AGI Research, 2024", "Internal analysis"
+Constraints: readable labels, no clip art, no stock photography, no decorative clutter, no watermark
+```
+
+### historical-scene
+```
+Use case: historical-scene
+Primary request: outdoor crowd scene in Bethel, New York on August 16, 1969
+Scene/backdrop: open field with period-appropriate staging
+Subject: crowd in period-accurate clothing, authentic environment
+Style/medium: photorealistic photo
+Composition/framing: wide shot, eye-level
+Constraints: period-accurate details; no modern objects; no logos or trademarks; no watermark
+```
+
+## Asset type templates (taxonomy-aligned)
+
+### Website assets template
+```
+Use case: <photorealistic-natural|stylized-concept|product-mockup|infographic-diagram|ui-mockup>
+Asset type: <hero image / section illustration / blog header>
+Primary request: <short description>
+Scene/backdrop: <environment or abstract backdrop>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D>
+Composition/framing: <wide/centered; note usable negative space only if needed>
+Lighting/mood: <soft/bright/neutral>
+Color palette: <brand colors or neutral>
+Constraints: <no text; no logos; no watermark; leave room for UI if needed>
+```
+
+### Website assets example: minimal hero background
+```
+Use case: stylized-concept
+Asset type: landing page hero background
+Primary request: minimal abstract background with a soft gradient and subtle texture
+Style/medium: matte illustration / soft-rendered abstract background
+Composition/framing: wide composition with usable negative space for page copy
+Lighting/mood: gentle studio glow
+Color palette: restrained neutral palette
+Constraints: no text; no logos; no watermark
+```
+
+### Website assets example: feature section illustration
+```
+Use case: stylized-concept
+Asset type: feature section illustration
+Primary request: simple abstract shapes suggesting connection and flow
+Scene/backdrop: subtle light-gray backdrop with faint texture
+Style/medium: flat illustration; soft shadows; restrained contrast
+Composition/framing: centered cluster; open margins for UI
+Color palette: muted neutral palette
+Constraints: no text; no logos; no watermark
+```
+
+### Website assets example: blog header image
+```
+Use case: photorealistic-natural
+Asset type: blog header image
+Primary request: overhead desk scene with notebook, pen, and coffee cup
+Scene/backdrop: warm wooden tabletop
+Style/medium: photorealistic photo
+Composition/framing: wide crop with clean room for page copy
+Lighting/mood: soft morning light
+Constraints: no text; no logos; no watermark
+```
+
+### Game assets template
+```
+Use case: stylized-concept
+Asset type: <game environment concept art / game character concept / game UI icon / tileable game texture>
+Primary request: <biome/scene/character/icon/material>
+Scene/backdrop: <location + set dressing> (if applicable)
+Subject: <main focal element(s)>
+Style/medium: <realistic/stylized>; <concept art / character render / UI icon / texture>
+Composition/framing: <wide/establishing/top-down>; <camera angle>; <focal point placement>
+Lighting/mood: <time of day>; <mood>; <volumetric/fog/etc>
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: environment concept art
+```
+Use case: stylized-concept
+Asset type: game environment concept art
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: character concept
+```
+Use case: stylized-concept
+Asset type: game character concept
+Primary request: desert scout character with layered travel gear
+Subject: long coat, satchel, practical travel clothing
+Style/medium: character render; stylized realism
+Composition/framing: neutral hero pose on a simple backdrop
+Constraints: no logos or trademarks; no watermark
+```
+
+### Game assets example: UI icon
+```
+Use case: stylized-concept
+Asset type: game UI icon
+Primary request: round shield icon with a subtle rune pattern
+Style/medium: painted game UI icon
+Composition/framing: centered icon; generous padding; clear silhouette
+Constraints: no text; no background scene elements; no logos or trademarks; no watermark
+```
+
+### Game assets example: tileable texture
+```
+Use case: stylized-concept
+Asset type: tileable game texture
+Primary request: worn sandstone blocks
+Style/medium: seamless tileable texture; PBR-ish look
+Scene/backdrop: neutral lighting reference only
+Constraints: seamless edges; no obvious focal elements; no text; no logos or trademarks; no watermark
+```
+
+### Wireframe template
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: <page or flow to sketch>
+Style/medium: low-fi grayscale wireframe
+Composition/framing: <landscape or portrait to match expected device>
+Subject: <sections in order; grid/columns; key labels>
+Constraints: no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: homepage (desktop)
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: SaaS homepage layout with clear hierarchy
+Style/medium: low-fi grayscale wireframe
+Subject: top nav; hero with headline and CTA; three feature cards; testimonial strip; pricing preview; footer
+Composition/framing: landscape desktop layout
+Constraints: label major blocks; no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: pricing page
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: pricing page layout with comparison table
+Style/medium: low-fi grayscale wireframe
+Subject: header; plan toggle; 3 pricing cards; comparison table; FAQ accordion; footer
+Composition/framing: desktop or tablet layout
+Constraints: label key areas; no color; no logos; no real photos; no watermark
+```
+
+### Wireframe example: mobile onboarding flow
+```
+Use case: ui-mockup
+Asset type: mobile onboarding wireframe
+Primary request: three-screen mobile onboarding flow
+Style/medium: low-fi grayscale wireframe
+Subject: screen 1 headline and CTA; screen 2 feature bullets; screen 3 form fields and CTA
+Composition/framing: portrait mobile layout
+Constraints: label screens and blocks; no color; no logos; no real photos; no watermark
+```
+
+### Logo template
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: <brand idea or symbol concept>
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette; generous margin
+Color palette: <1-2 colors; high contrast>
+Text (verbatim): "<exact name>" (only if needed)
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: abstract symbol mark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: geometric leaf symbol suggesting sustainability and growth
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette
+Color palette: deep green and off-white
+Constraints: no text unless requested; no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: monogram mark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: interlocking monogram of the letters "AV"
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; balanced spacing
+Color palette: black on white
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+### Logo example: wordmark
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: clean wordmark for a modern studio
+Style/medium: vector wordmark; flat colors; minimal
+Text (verbatim): "Studio North"
+Composition/framing: centered text; even letter spacing
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+## Edit
+
+### text-localization
+```
+Use case: text-localization
+Input images: Image 1: original infographic
+Primary request: replace "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", and "Drip Tray" with "Tolva", "Molino", "Grupo de infusión", "Caldera", "Depósito de agua", and "Bandeja de goteo"
+Constraints: change only the text; preserve layout, typography, spacing, and hierarchy; no extra words; do not alter logos or imagery
+```
+
+### identity-preserve
+```
+Use case: identity-preserve
+Input images: Image 1: person photo; Image 2..N: clothing references
+Primary request: replace only the clothing with the provided garments
+Constraints: preserve face, body shape, pose, hair, expression, and identity; match lighting and shadows; keep the background unchanged; no accessories or text
+```
+
+### precise-object-edit
+```
+Use case: precise-object-edit
+Input images: Image 1: room photo
+Primary request: replace only the white chairs with wooden chairs
+Constraints: preserve camera angle, room lighting, floor shadows, and surrounding objects; keep all other aspects unchanged
+```
+
+### lighting-weather
+```
+Use case: lighting-weather
+Input images: Image 1: original photo
+Primary request: make it look like a winter evening with gentle snowfall
+Constraints: preserve subject identity, geometry, camera angle, and composition; change only lighting, atmosphere, and weather
+```
+
+### style-transfer
+```
+Use case: style-transfer
+Input images: Image 1: style reference
+Primary request: apply Image 1's visual style to a man riding a motorcycle on a plain white backdrop
+Constraints: preserve palette, texture, and brushwork; no extra elements
+```
+
+### compositing
+```
+Use case: compositing
+Input images: Image 1: base scene; Image 2: subject to insert
+Primary request: place the subject from Image 2 next to the person in Image 1
+Constraints: match lighting, perspective, and scale; keep the base framing unchanged; no extra elements
+```
+
+### character consistency workflow
+```
+Use case: identity-preserve
+Input images: Image 1: previous character anchor illustration
+Primary request: continue the story with the same character in a new scene and action
+Scene/backdrop: snowy forest after a winter storm
+Subject: same young forest hero gently helping a frightened squirrel out of a fallen tree
+Style/medium: same children's book watercolor illustration style as Image 1
+Constraints: do not redesign the character; preserve facial features, proportions, outfit, color palette, and personality; no text; no watermark
+```
+
+### sketch-to-render
+```
+Use case: sketch-to-render
+Input images: Image 1: drawing
+Primary request: turn the drawing into a photorealistic image
+Constraints: preserve layout, proportions, and perspective; choose realistic materials and lighting; do not add new elements or text
+```
diff --git a/codex-rs/skills/src/assets/samples/imagegen/scripts/image_gen.py b/codex-rs/skills/src/assets/samples/imagegen/scripts/image_gen.py
new file mode 100644
index 0000000000000000000000000000000000000000..ca78422d715585f6983a300199ed79e45bdb7ac0
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/scripts/image_gen.py
@@ -0,0 +1,1030 @@
+#!/usr/bin/env python3
+"""Fallback CLI for explicit image generation or editing with GPT Image models.
+
+Used only when the user explicitly opts into CLI fallback mode, or when explicit
+transparent output requires the `gpt-image-1.5` fallback path.
+
+Defaults to gpt-image-2 and a structured prompt augmentation workflow.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import time
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from io import BytesIO
+
+DEFAULT_MODEL = "gpt-image-2"
+DEFAULT_SIZE = "auto"
+DEFAULT_QUALITY = "medium"
+DEFAULT_OUTPUT_FORMAT = "png"
+DEFAULT_CONCURRENCY = 5
+DEFAULT_DOWNSCALE_SUFFIX = "-web"
+DEFAULT_OUTPUT_PATH = "output/imagegen/output.png"
+GPT_IMAGE_MODEL_PREFIX = "gpt-image-"
+
+ALLOWED_LEGACY_SIZES = {"1024x1024", "1536x1024", "1024x1536", "auto"}
+ALLOWED_QUALITIES = {"low", "medium", "high", "auto"}
+ALLOWED_BACKGROUNDS = {"transparent", "opaque", "auto", None}
+ALLOWED_INPUT_FIDELITIES = {"low", "high", None}
+
+GPT_IMAGE_2_MODEL = "gpt-image-2"
+GPT_IMAGE_2_MIN_PIXELS = 655_360
+GPT_IMAGE_2_MAX_PIXELS = 8_294_400
+GPT_IMAGE_2_MAX_EDGE = 3840
+GPT_IMAGE_2_MAX_RATIO = 3.0
+
+MAX_IMAGE_BYTES = 50 * 1024 * 1024
+MAX_BATCH_JOBS = 500
+
+
+def _die(message: str, code: int = 1) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _warn(message: str) -> None:
+    print(f"Warning: {message}", file=sys.stderr)
+
+
+def _dependency_hint(package: str, *, upgrade: bool = False) -> str:
+    command = f"uv pip install {'-U ' if upgrade else ''}{package}"
+    return (
+        "Activate the repo-selected environment first, then install it with "
+        f"`{command}`. If this repo uses a local virtualenv, start with "
+        "`source .venv/bin/activate`; otherwise use this repo's configured shared fallback "
+        "environment. If your project declares dependencies, prefer that project's normal "
+        "`uv sync` flow."
+    )
+
+
+def _ensure_api_key(dry_run: bool) -> None:
+    if os.getenv("OPENAI_API_KEY"):
+        print("OPENAI_API_KEY is set.", file=sys.stderr)
+        return
+    if dry_run:
+        _warn("OPENAI_API_KEY is not set; dry-run only.")
+        return
+    _die("OPENAI_API_KEY is not set. Export it before running.")
+
+
+def _read_prompt(prompt: Optional[str], prompt_file: Optional[str]) -> str:
+    if prompt and prompt_file:
+        _die("Use --prompt or --prompt-file, not both.")
+    if prompt_file:
+        path = Path(prompt_file)
+        if not path.exists():
+            _die(f"Prompt file not found: {path}")
+        return path.read_text(encoding="utf-8").strip()
+    if prompt:
+        return prompt.strip()
+    _die("Missing prompt. Use --prompt or --prompt-file.")
+    return ""  # unreachable
+
+
+def _check_image_paths(paths: Iterable[str]) -> List[Path]:
+    resolved: List[Path] = []
+    for raw in paths:
+        path = Path(raw)
+        if not path.exists():
+            _die(f"Image file not found: {path}")
+        if path.stat().st_size > MAX_IMAGE_BYTES:
+            _warn(f"Image exceeds 50MB limit: {path}")
+        resolved.append(path)
+    return resolved
+
+
+def _normalize_output_format(fmt: Optional[str]) -> str:
+    if not fmt:
+        return DEFAULT_OUTPUT_FORMAT
+    fmt = fmt.lower()
+    if fmt not in {"png", "jpeg", "jpg", "webp"}:
+        _die("output-format must be png, jpeg, jpg, or webp.")
+    return "jpeg" if fmt == "jpg" else fmt
+
+
+def _parse_size(size: str) -> Optional[Tuple[int, int]]:
+    match = re.fullmatch(r"([1-9][0-9]*)x([1-9][0-9]*)", size)
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def _validate_gpt_image_2_size(size: str) -> None:
+    if size == "auto":
+        return
+
+    parsed = _parse_size(size)
+    if parsed is None:
+        _die("size must be auto or WIDTHxHEIGHT, for example 1024x1024.")
+
+    width, height = parsed
+    max_edge = max(width, height)
+    min_edge = min(width, height)
+    total_pixels = width * height
+
+    if max_edge > GPT_IMAGE_2_MAX_EDGE:
+        _die(
+            "gpt-image-2 size maximum edge length must be less than or equal to 3840px."
+        )
+    if width % 16 != 0 or height % 16 != 0:
+        _die("gpt-image-2 size width and height must be multiples of 16px.")
+    if max_edge / min_edge > GPT_IMAGE_2_MAX_RATIO:
+        _die("gpt-image-2 size long edge to short edge ratio must not exceed 3:1.")
+    if total_pixels < GPT_IMAGE_2_MIN_PIXELS or total_pixels > GPT_IMAGE_2_MAX_PIXELS:
+        _die(
+            "gpt-image-2 size total pixels must be at least 655,360 and no more than 8,294,400."
+        )
+
+
+def _validate_size(size: str, model: str) -> None:
+    if model == GPT_IMAGE_2_MODEL:
+        _validate_gpt_image_2_size(size)
+        return
+
+    if size not in ALLOWED_LEGACY_SIZES:
+        _die(
+            "size must be one of 1024x1024, 1536x1024, 1024x1536, or auto for this GPT Image model."
+        )
+
+
+def _validate_quality(quality: str) -> None:
+    if quality not in ALLOWED_QUALITIES:
+        _die("quality must be one of low, medium, high, or auto.")
+
+
+def _validate_background(background: Optional[str]) -> None:
+    if background not in ALLOWED_BACKGROUNDS:
+        _die("background must be one of transparent, opaque, or auto.")
+
+
+def _validate_input_fidelity(input_fidelity: Optional[str]) -> None:
+    if input_fidelity not in ALLOWED_INPUT_FIDELITIES:
+        _die("input-fidelity must be one of low or high.")
+
+
+def _validate_model(model: str) -> None:
+    if not model.startswith(GPT_IMAGE_MODEL_PREFIX):
+        _die(
+            "model must be a GPT Image model (for example gpt-image-1.5, gpt-image-1, or gpt-image-1-mini)."
+        )
+
+
+def _validate_transparency(background: Optional[str], output_format: str) -> None:
+    if background == "transparent" and output_format not in {"png", "webp"}:
+        _die("transparent background requires output-format png or webp.")
+
+
+def _validate_model_specific_options(
+    *,
+    model: str,
+    background: Optional[str],
+    input_fidelity: Optional[str] = None,
+) -> None:
+    if model != GPT_IMAGE_2_MODEL:
+        return
+    if background == "transparent":
+        _die(
+            "transparent backgrounds are not supported in gpt-image-2, the latest model. "
+            "Use --model gpt-image-1.5 --background transparent --output-format png instead."
+        )
+    if input_fidelity is not None:
+        _die(
+            "input_fidelity is not supported in gpt-image-2 because image inputs always use high fidelity for this model."
+        )
+
+
+def _validate_generate_payload(payload: Dict[str, Any]) -> None:
+    model = str(payload.get("model", DEFAULT_MODEL))
+    _validate_model(model)
+    n = int(payload.get("n", 1))
+    if n < 1 or n > 10:
+        _die("n must be between 1 and 10")
+    size = str(payload.get("size", DEFAULT_SIZE))
+    quality = str(payload.get("quality", DEFAULT_QUALITY))
+    background = payload.get("background")
+    _validate_size(size, model)
+    _validate_quality(quality)
+    _validate_background(background)
+    _validate_model_specific_options(model=model, background=background)
+    oc = payload.get("output_compression")
+    if oc is not None and not (0 <= int(oc) <= 100):
+        _die("output_compression must be between 0 and 100")
+
+
+def _build_output_paths(
+    out: str,
+    output_format: str,
+    count: int,
+    out_dir: Optional[str],
+) -> List[Path]:
+    ext = "." + output_format
+
+    if out_dir:
+        out_base = Path(out_dir)
+        out_base.mkdir(parents=True, exist_ok=True)
+        return [out_base / f"image_{i}{ext}" for i in range(1, count + 1)]
+
+    out_path = Path(out)
+    if out_path.exists() and out_path.is_dir():
+        out_path.mkdir(parents=True, exist_ok=True)
+        return [out_path / f"image_{i}{ext}" for i in range(1, count + 1)]
+
+    if out_path.suffix == "":
+        out_path = out_path.with_suffix(ext)
+    elif output_format and out_path.suffix.lstrip(".").lower() != output_format:
+        _warn(
+            f"Output extension {out_path.suffix} does not match output-format {output_format}."
+        )
+
+    if count == 1:
+        return [out_path]
+
+    return [
+        out_path.with_name(f"{out_path.stem}-{i}{out_path.suffix}")
+        for i in range(1, count + 1)
+    ]
+
+
+def _augment_prompt(args: argparse.Namespace, prompt: str) -> str:
+    fields = _fields_from_args(args)
+    return _augment_prompt_fields(args.augment, prompt, fields)
+
+
+def _augment_prompt_fields(
+    augment: bool, prompt: str, fields: Dict[str, Optional[str]]
+) -> str:
+    if not augment:
+        return prompt
+
+    sections: List[str] = []
+    if fields.get("use_case"):
+        sections.append(f"Use case: {fields['use_case']}")
+    sections.append(f"Primary request: {prompt}")
+    if fields.get("scene"):
+        sections.append(f"Scene/background: {fields['scene']}")
+    if fields.get("subject"):
+        sections.append(f"Subject: {fields['subject']}")
+    if fields.get("style"):
+        sections.append(f"Style/medium: {fields['style']}")
+    if fields.get("composition"):
+        sections.append(f"Composition/framing: {fields['composition']}")
+    if fields.get("lighting"):
+        sections.append(f"Lighting/mood: {fields['lighting']}")
+    if fields.get("palette"):
+        sections.append(f"Color palette: {fields['palette']}")
+    if fields.get("materials"):
+        sections.append(f"Materials/textures: {fields['materials']}")
+    if fields.get("text"):
+        sections.append(f'Text (verbatim): "{fields["text"]}"')
+    if fields.get("constraints"):
+        sections.append(f"Constraints: {fields['constraints']}")
+    if fields.get("negative"):
+        sections.append(f"Avoid: {fields['negative']}")
+
+    return "\n".join(sections)
+
+
+def _fields_from_args(args: argparse.Namespace) -> Dict[str, Optional[str]]:
+    return {
+        "use_case": getattr(args, "use_case", None),
+        "scene": getattr(args, "scene", None),
+        "subject": getattr(args, "subject", None),
+        "style": getattr(args, "style", None),
+        "composition": getattr(args, "composition", None),
+        "lighting": getattr(args, "lighting", None),
+        "palette": getattr(args, "palette", None),
+        "materials": getattr(args, "materials", None),
+        "text": getattr(args, "text", None),
+        "constraints": getattr(args, "constraints", None),
+        "negative": getattr(args, "negative", None),
+    }
+
+
+def _print_request(payload: dict) -> None:
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def _decode_and_write(images: List[str], outputs: List[Path], force: bool) -> None:
+    for idx, image_b64 in enumerate(images):
+        if idx >= len(outputs):
+            break
+        out_path = outputs[idx]
+        if out_path.exists() and not force:
+            _die(f"Output already exists: {out_path} (use --force to overwrite)")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_bytes(base64.b64decode(image_b64))
+        print(f"Wrote {out_path}")
+
+
+def _derive_downscale_path(path: Path, suffix: str) -> Path:
+    if suffix and not suffix.startswith("-") and not suffix.startswith("_"):
+        suffix = "-" + suffix
+    return path.with_name(f"{path.stem}{suffix}{path.suffix}")
+
+
+def _downscale_image_bytes(
+    image_bytes: bytes, *, max_dim: int, output_format: str
+) -> bytes:
+    try:
+        from PIL import Image
+    except Exception:
+        _die(f"Downscaling requires Pillow. {_dependency_hint('pillow')}")
+
+    if max_dim < 1:
+        _die("--downscale-max-dim must be >= 1")
+
+    with Image.open(BytesIO(image_bytes)) as img:
+        img.load()
+        w, h = img.size
+        scale = min(1.0, float(max_dim) / float(max(w, h)))
+        target = (max(1, int(round(w * scale))), max(1, int(round(h * scale))))
+
+        resized = (
+            img if target == (w, h) else img.resize(target, Image.Resampling.LANCZOS)
+        )
+
+        fmt = output_format.lower()
+        if fmt == "jpg":
+            fmt = "jpeg"
+
+        if fmt == "jpeg":
+            if resized.mode in ("RGBA", "LA") or (
+                "transparency" in getattr(resized, "info", {})
+            ):
+                bg = Image.new("RGB", resized.size, (255, 255, 255))
+                bg.paste(
+                    resized.convert("RGBA"), mask=resized.convert("RGBA").split()[-1]
+                )
+                resized = bg
+            else:
+                resized = resized.convert("RGB")
+
+        out = BytesIO()
+        resized.save(out, format=fmt.upper())
+        return out.getvalue()
+
+
+def _decode_write_and_downscale(
+    images: List[str],
+    outputs: List[Path],
+    *,
+    force: bool,
+    downscale_max_dim: Optional[int],
+    downscale_suffix: str,
+    output_format: str,
+) -> None:
+    for idx, image_b64 in enumerate(images):
+        if idx >= len(outputs):
+            break
+        out_path = outputs[idx]
+        if out_path.exists() and not force:
+            _die(f"Output already exists: {out_path} (use --force to overwrite)")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        raw = base64.b64decode(image_b64)
+        out_path.write_bytes(raw)
+        print(f"Wrote {out_path}")
+
+        if downscale_max_dim is None:
+            continue
+
+        derived = _derive_downscale_path(out_path, downscale_suffix)
+        if derived.exists() and not force:
+            _die(f"Output already exists: {derived} (use --force to overwrite)")
+        derived.parent.mkdir(parents=True, exist_ok=True)
+        resized = _downscale_image_bytes(
+            raw, max_dim=downscale_max_dim, output_format=output_format
+        )
+        derived.write_bytes(resized)
+        print(f"Wrote {derived}")
+
+
+def _create_client():
+    try:
+        from openai import OpenAI
+    except ImportError:
+        _die(
+            f"openai SDK not installed in the active environment. {_dependency_hint('openai')}"
+        )
+    return OpenAI()
+
+
+def _create_async_client():
+    try:
+        from openai import AsyncOpenAI
+    except ImportError:
+        try:
+            import openai as _openai  # noqa: F401
+        except ImportError:
+            _die(
+                f"openai SDK not installed in the active environment. {_dependency_hint('openai')}"
+            )
+        _die(
+            "AsyncOpenAI not available in this openai SDK version. "
+            f"{_dependency_hint('openai', upgrade=True)}"
+        )
+    return AsyncOpenAI()
+
+
+def _slugify(value: str) -> str:
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value)
+    value = re.sub(r"-{2,}", "-", value).strip("-")
+    return value[:60] if value else "job"
+
+
+def _normalize_job(job: Any, idx: int) -> Dict[str, Any]:
+    if isinstance(job, str):
+        prompt = job.strip()
+        if not prompt:
+            _die(f"Empty prompt at job {idx}")
+        return {"prompt": prompt}
+    if isinstance(job, dict):
+        if "prompt" not in job or not str(job["prompt"]).strip():
+            _die(f"Missing prompt for job {idx}")
+        return job
+    _die(f"Invalid job at index {idx}: expected string or object.")
+    return {}  # unreachable
+
+
+def _read_jobs_jsonl(path: str) -> List[Dict[str, Any]]:
+    p = Path(path)
+    if not p.exists():
+        _die(f"Input file not found: {p}")
+    jobs: List[Dict[str, Any]] = []
+    for line_no, raw in enumerate(p.read_text(encoding="utf-8").splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        try:
+            item: Any
+            if line.startswith("{"):
+                item = json.loads(line)
+            else:
+                item = line
+            jobs.append(_normalize_job(item, idx=line_no))
+        except json.JSONDecodeError as exc:
+            _die(f"Invalid JSON on line {line_no}: {exc}")
+    if not jobs:
+        _die("No jobs found in input file.")
+    if len(jobs) > MAX_BATCH_JOBS:
+        _die(f"Too many jobs ({len(jobs)}). Max is {MAX_BATCH_JOBS}.")
+    return jobs
+
+
+def _merge_non_null(dst: Dict[str, Any], src: Dict[str, Any]) -> Dict[str, Any]:
+    merged = dict(dst)
+    for k, v in src.items():
+        if v is not None:
+            merged[k] = v
+    return merged
+
+
+def _job_output_paths(
+    *,
+    out_dir: Path,
+    output_format: str,
+    idx: int,
+    prompt: str,
+    n: int,
+    explicit_out: Optional[str],
+) -> List[Path]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    ext = "." + output_format
+
+    if explicit_out:
+        base = Path(explicit_out)
+        if base.suffix == "":
+            base = base.with_suffix(ext)
+        elif base.suffix.lstrip(".").lower() != output_format:
+            _warn(
+                f"Job {idx}: output extension {base.suffix} does not match output-format {output_format}."
+            )
+        base = out_dir / base.name
+    else:
+        slug = _slugify(prompt[:80])
+        base = out_dir / f"{idx:03d}-{slug}{ext}"
+
+    if n == 1:
+        return [base]
+    return [base.with_name(f"{base.stem}-{i}{base.suffix}") for i in range(1, n + 1)]
+
+
+def _extract_retry_after_seconds(exc: Exception) -> Optional[float]:
+    # Best-effort: openai SDK errors vary by version. Prefer a conservative fallback.
+    for attr in ("retry_after", "retry_after_seconds"):
+        val = getattr(exc, attr, None)
+        if isinstance(val, (int, float)) and val >= 0:
+            return float(val)
+    msg = str(exc)
+    m = re.search(r"retry[- ]after[:= ]+([0-9]+(?:\\.[0-9]+)?)", msg, re.IGNORECASE)
+    if m:
+        try:
+            return float(m.group(1))
+        except Exception:
+            return None
+    return None
+
+
+def _is_rate_limit_error(exc: Exception) -> bool:
+    name = exc.__class__.__name__.lower()
+    if "ratelimit" in name or "rate_limit" in name:
+        return True
+    msg = str(exc).lower()
+    return "429" in msg or "rate limit" in msg or "too many requests" in msg
+
+
+def _is_transient_error(exc: Exception) -> bool:
+    if _is_rate_limit_error(exc):
+        return True
+    name = exc.__class__.__name__.lower()
+    if "timeout" in name or "timedout" in name or "tempor" in name:
+        return True
+    msg = str(exc).lower()
+    return "timeout" in msg or "timed out" in msg or "connection reset" in msg
+
+
+async def _generate_one_with_retries(
+    client: Any,
+    payload: Dict[str, Any],
+    *,
+    attempts: int,
+    job_label: str,
+) -> Any:
+    last_exc: Optional[Exception] = None
+    for attempt in range(1, attempts + 1):
+        try:
+            return await client.images.generate(**payload)
+        except Exception as exc:
+            last_exc = exc
+            if not _is_transient_error(exc):
+                raise
+            if attempt == attempts:
+                raise
+            sleep_s = _extract_retry_after_seconds(exc)
+            if sleep_s is None:
+                sleep_s = min(60.0, 2.0**attempt)
+            print(
+                f"{job_label} attempt {attempt}/{attempts} failed ({exc.__class__.__name__}); retrying in {sleep_s:.1f}s",
+                file=sys.stderr,
+            )
+            await asyncio.sleep(sleep_s)
+    raise last_exc or RuntimeError("unknown error")
+
+
+async def _run_generate_batch(args: argparse.Namespace) -> int:
+    jobs = _read_jobs_jsonl(args.input)
+    out_dir = Path(args.out_dir)
+
+    base_fields = _fields_from_args(args)
+    base_payload = {
+        "model": args.model,
+        "n": args.n,
+        "size": args.size,
+        "quality": args.quality,
+        "background": args.background,
+        "output_format": args.output_format,
+        "output_compression": args.output_compression,
+        "moderation": args.moderation,
+    }
+
+    if args.dry_run:
+        for i, job in enumerate(jobs, start=1):
+            prompt = str(job["prompt"]).strip()
+            fields = _merge_non_null(base_fields, job.get("fields", {}))
+            # Allow flat job keys as well (use_case, scene, etc.)
+            fields = _merge_non_null(
+                fields, {k: job.get(k) for k in base_fields.keys()}
+            )
+            augmented = _augment_prompt_fields(args.augment, prompt, fields)
+
+            job_payload = dict(base_payload)
+            job_payload["prompt"] = augmented
+            job_payload = _merge_non_null(
+                job_payload, {k: job.get(k) for k in base_payload.keys()}
+            )
+            job_payload = {k: v for k, v in job_payload.items() if v is not None}
+
+            _validate_generate_payload(job_payload)
+            effective_output_format = _normalize_output_format(
+                job_payload.get("output_format")
+            )
+            _validate_transparency(
+                job_payload.get("background"), effective_output_format
+            )
+            job_payload["output_format"] = effective_output_format
+
+            n = int(job_payload.get("n", 1))
+            outputs = _job_output_paths(
+                out_dir=out_dir,
+                output_format=effective_output_format,
+                idx=i,
+                prompt=prompt,
+                n=n,
+                explicit_out=job.get("out"),
+            )
+            downscaled = None
+            if args.downscale_max_dim is not None:
+                downscaled = [
+                    str(_derive_downscale_path(p, args.downscale_suffix))
+                    for p in outputs
+                ]
+            _print_request(
+                {
+                    "endpoint": "/v1/images/generations",
+                    "job": i,
+                    "outputs": [str(p) for p in outputs],
+                    "outputs_downscaled": downscaled,
+                    **job_payload,
+                }
+            )
+        return 0
+
+    client = _create_async_client()
+    sem = asyncio.Semaphore(args.concurrency)
+
+    any_failed = False
+
+    async def run_job(i: int, job: Dict[str, Any]) -> Tuple[int, Optional[str]]:
+        nonlocal any_failed
+        prompt = str(job["prompt"]).strip()
+        job_label = f"[job {i}/{len(jobs)}]"
+
+        fields = _merge_non_null(base_fields, job.get("fields", {}))
+        fields = _merge_non_null(fields, {k: job.get(k) for k in base_fields.keys()})
+        augmented = _augment_prompt_fields(args.augment, prompt, fields)
+
+        payload = dict(base_payload)
+        payload["prompt"] = augmented
+        payload = _merge_non_null(payload, {k: job.get(k) for k in base_payload.keys()})
+        payload = {k: v for k, v in payload.items() if v is not None}
+
+        n = int(payload.get("n", 1))
+        _validate_generate_payload(payload)
+        effective_output_format = _normalize_output_format(payload.get("output_format"))
+        _validate_transparency(payload.get("background"), effective_output_format)
+        payload["output_format"] = effective_output_format
+        outputs = _job_output_paths(
+            out_dir=out_dir,
+            output_format=effective_output_format,
+            idx=i,
+            prompt=prompt,
+            n=n,
+            explicit_out=job.get("out"),
+        )
+        try:
+            async with sem:
+                print(f"{job_label} starting", file=sys.stderr)
+                started = time.time()
+                result = await _generate_one_with_retries(
+                    client,
+                    payload,
+                    attempts=args.max_attempts,
+                    job_label=job_label,
+                )
+                elapsed = time.time() - started
+                print(f"{job_label} completed in {elapsed:.1f}s", file=sys.stderr)
+            images = [item.b64_json for item in result.data]
+            _decode_write_and_downscale(
+                images,
+                outputs,
+                force=args.force,
+                downscale_max_dim=args.downscale_max_dim,
+                downscale_suffix=args.downscale_suffix,
+                output_format=effective_output_format,
+            )
+            return i, None
+        except Exception as exc:
+            any_failed = True
+            print(f"{job_label} failed: {exc}", file=sys.stderr)
+            if args.fail_fast:
+                raise
+            return i, str(exc)
+
+    tasks = [
+        asyncio.create_task(run_job(i, job)) for i, job in enumerate(jobs, start=1)
+    ]
+
+    try:
+        await asyncio.gather(*tasks)
+    except Exception:
+        for t in tasks:
+            if not t.done():
+                t.cancel()
+        raise
+
+    return 1 if any_failed else 0
+
+
+def _generate_batch(args: argparse.Namespace) -> None:
+    exit_code = asyncio.run(_run_generate_batch(args))
+    if exit_code:
+        raise SystemExit(exit_code)
+
+
+def _generate(args: argparse.Namespace) -> None:
+    prompt = _read_prompt(args.prompt, args.prompt_file)
+    prompt = _augment_prompt(args, prompt)
+
+    payload = {
+        "model": args.model,
+        "prompt": prompt,
+        "n": args.n,
+        "size": args.size,
+        "quality": args.quality,
+        "background": args.background,
+        "output_format": args.output_format,
+        "output_compression": args.output_compression,
+        "moderation": args.moderation,
+    }
+    payload = {k: v for k, v in payload.items() if v is not None}
+
+    output_format = _normalize_output_format(args.output_format)
+    _validate_transparency(args.background, output_format)
+    payload["output_format"] = output_format
+    output_paths = _build_output_paths(args.out, output_format, args.n, args.out_dir)
+    downscaled = None
+    if args.downscale_max_dim is not None:
+        downscaled = [
+            str(_derive_downscale_path(p, args.downscale_suffix)) for p in output_paths
+        ]
+
+    if args.dry_run:
+        _print_request(
+            {
+                "endpoint": "/v1/images/generations",
+                "outputs": [str(p) for p in output_paths],
+                "outputs_downscaled": downscaled,
+                **payload,
+            }
+        )
+        return
+
+    print(
+        "Calling Image API (generation). This can take up to a couple of minutes.",
+        file=sys.stderr,
+    )
+    started = time.time()
+    client = _create_client()
+    result = client.images.generate(**payload)
+    elapsed = time.time() - started
+    print(f"Generation completed in {elapsed:.1f}s.", file=sys.stderr)
+
+    images = [item.b64_json for item in result.data]
+    _decode_write_and_downscale(
+        images,
+        output_paths,
+        force=args.force,
+        downscale_max_dim=args.downscale_max_dim,
+        downscale_suffix=args.downscale_suffix,
+        output_format=output_format,
+    )
+
+
+def _edit(args: argparse.Namespace) -> None:
+    prompt = _read_prompt(args.prompt, args.prompt_file)
+    prompt = _augment_prompt(args, prompt)
+
+    image_paths = _check_image_paths(args.image)
+    mask_path = Path(args.mask) if args.mask else None
+    if mask_path:
+        if not mask_path.exists():
+            _die(f"Mask file not found: {mask_path}")
+        if mask_path.suffix.lower() != ".png":
+            _warn(f"Mask should be a PNG with an alpha channel: {mask_path}")
+        if mask_path.stat().st_size > MAX_IMAGE_BYTES:
+            _warn(f"Mask exceeds 50MB limit: {mask_path}")
+
+    payload = {
+        "model": args.model,
+        "prompt": prompt,
+        "n": args.n,
+        "size": args.size,
+        "quality": args.quality,
+        "background": args.background,
+        "output_format": args.output_format,
+        "output_compression": args.output_compression,
+        "input_fidelity": args.input_fidelity,
+        "moderation": args.moderation,
+    }
+    payload = {k: v for k, v in payload.items() if v is not None}
+
+    output_format = _normalize_output_format(args.output_format)
+    _validate_transparency(args.background, output_format)
+    payload["output_format"] = output_format
+    _validate_input_fidelity(args.input_fidelity)
+    output_paths = _build_output_paths(args.out, output_format, args.n, args.out_dir)
+    downscaled = None
+    if args.downscale_max_dim is not None:
+        downscaled = [
+            str(_derive_downscale_path(p, args.downscale_suffix)) for p in output_paths
+        ]
+
+    if args.dry_run:
+        payload_preview = dict(payload)
+        payload_preview["image"] = [str(p) for p in image_paths]
+        if mask_path:
+            payload_preview["mask"] = str(mask_path)
+        _print_request(
+            {
+                "endpoint": "/v1/images/edits",
+                "outputs": [str(p) for p in output_paths],
+                "outputs_downscaled": downscaled,
+                **payload_preview,
+            }
+        )
+        return
+
+    print(
+        f"Calling Image API (edit) with {len(image_paths)} image(s).",
+        file=sys.stderr,
+    )
+    started = time.time()
+    client = _create_client()
+
+    with _open_files(image_paths) as image_files, _open_mask(mask_path) as mask_file:
+        request = dict(payload)
+        request["image"] = image_files if len(image_files) > 1 else image_files[0]
+        if mask_file is not None:
+            request["mask"] = mask_file
+        result = client.images.edit(**request)
+
+    elapsed = time.time() - started
+    print(f"Edit completed in {elapsed:.1f}s.", file=sys.stderr)
+    images = [item.b64_json for item in result.data]
+    _decode_write_and_downscale(
+        images,
+        output_paths,
+        force=args.force,
+        downscale_max_dim=args.downscale_max_dim,
+        downscale_suffix=args.downscale_suffix,
+        output_format=output_format,
+    )
+
+
+def _open_files(paths: List[Path]):
+    return _FileBundle(paths)
+
+
+def _open_mask(mask_path: Optional[Path]):
+    if mask_path is None:
+        return _NullContext()
+    return _SingleFile(mask_path)
+
+
+class _NullContext:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+
+class _SingleFile:
+    def __init__(self, path: Path):
+        self._path = path
+        self._handle = None
+
+    def __enter__(self):
+        self._handle = self._path.open("rb")
+        return self._handle
+
+    def __exit__(self, exc_type, exc, tb):
+        if self._handle:
+            try:
+                self._handle.close()
+            except Exception:
+                pass
+        return False
+
+
+class _FileBundle:
+    def __init__(self, paths: List[Path]):
+        self._paths = paths
+        self._handles: List[object] = []
+
+    def __enter__(self):
+        self._handles = [p.open("rb") for p in self._paths]
+        return self._handles
+
+    def __exit__(self, exc_type, exc, tb):
+        for handle in self._handles:
+            try:
+                handle.close()
+            except Exception:
+                pass
+        return False
+
+
+def _add_shared_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--prompt")
+    parser.add_argument("--prompt-file")
+    parser.add_argument("--n", type=int, default=1)
+    parser.add_argument("--size", default=DEFAULT_SIZE)
+    parser.add_argument("--quality", default=DEFAULT_QUALITY)
+    parser.add_argument("--background")
+    parser.add_argument("--output-format")
+    parser.add_argument("--output-compression", type=int)
+    parser.add_argument("--moderation")
+    parser.add_argument("--out", default=DEFAULT_OUTPUT_PATH)
+    parser.add_argument("--out-dir")
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--augment", dest="augment", action="store_true")
+    parser.add_argument("--no-augment", dest="augment", action="store_false")
+    parser.set_defaults(augment=True)
+
+    # Prompt augmentation hints
+    parser.add_argument("--use-case")
+    parser.add_argument("--scene")
+    parser.add_argument("--subject")
+    parser.add_argument("--style")
+    parser.add_argument("--composition")
+    parser.add_argument("--lighting")
+    parser.add_argument("--palette")
+    parser.add_argument("--materials")
+    parser.add_argument("--text")
+    parser.add_argument("--constraints")
+    parser.add_argument("--negative")
+
+    # Post-processing (optional): generate an additional downscaled copy for fast web loading.
+    parser.add_argument("--downscale-max-dim", type=int)
+    parser.add_argument("--downscale-suffix", default=DEFAULT_DOWNSCALE_SUFFIX)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Fallback CLI for explicit image generation or editing via GPT Image models"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    gen_parser = subparsers.add_parser("generate", help="Create a new image")
+    _add_shared_args(gen_parser)
+    gen_parser.set_defaults(func=_generate)
+
+    batch_parser = subparsers.add_parser(
+        "generate-batch",
+        help="Generate multiple prompts concurrently (JSONL input)",
+    )
+    _add_shared_args(batch_parser)
+    batch_parser.add_argument(
+        "--input", required=True, help="Path to JSONL file (one job per line)"
+    )
+    batch_parser.add_argument("--concurrency", type=int, default=DEFAULT_CONCURRENCY)
+    batch_parser.add_argument("--max-attempts", type=int, default=3)
+    batch_parser.add_argument("--fail-fast", action="store_true")
+    batch_parser.set_defaults(func=_generate_batch)
+
+    edit_parser = subparsers.add_parser("edit", help="Edit an existing image")
+    _add_shared_args(edit_parser)
+    edit_parser.add_argument("--image", action="append", required=True)
+    edit_parser.add_argument("--mask")
+    edit_parser.add_argument("--input-fidelity")
+    edit_parser.set_defaults(func=_edit)
+
+    args = parser.parse_args()
+    if args.n < 1 or args.n > 10:
+        _die("--n must be between 1 and 10")
+    if getattr(args, "concurrency", 1) < 1 or getattr(args, "concurrency", 1) > 25:
+        _die("--concurrency must be between 1 and 25")
+    if getattr(args, "max_attempts", 3) < 1 or getattr(args, "max_attempts", 3) > 10:
+        _die("--max-attempts must be between 1 and 10")
+    if args.output_compression is not None and not (
+        0 <= args.output_compression <= 100
+    ):
+        _die("--output-compression must be between 0 and 100")
+    if args.command == "generate-batch" and not args.out_dir:
+        _die("generate-batch requires --out-dir")
+    if (
+        getattr(args, "downscale_max_dim", None) is not None
+        and args.downscale_max_dim < 1
+    ):
+        _die("--downscale-max-dim must be >= 1")
+
+    _validate_model(args.model)
+    _validate_size(args.size, args.model)
+    _validate_quality(args.quality)
+    _validate_background(args.background)
+    _validate_model_specific_options(
+        model=args.model,
+        background=args.background,
+        input_fidelity=getattr(args, "input_fidelity", None),
+    )
+    _ensure_api_key(args.dry_run)
+
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/codex-rs/skills/src/assets/samples/imagegen/scripts/remove_chroma_key.py b/codex-rs/skills/src/assets/samples/imagegen/scripts/remove_chroma_key.py
new file mode 100644
index 0000000000000000000000000000000000000000..f14df3551888464cd9dc7b75c9678c20f084ed97
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/imagegen/scripts/remove_chroma_key.py
@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""Remove a solid chroma-key background from an image.
+
+This helper supports the imagegen skill's built-in-first transparent workflow:
+generate an image on a flat key color, then convert that key color to alpha.
+"""
+
+from __future__ import annotations
+
+import argparse
+from io import BytesIO
+from pathlib import Path
+import re
+from statistics import median
+import sys
+from typing import Tuple
+
+
+Color = Tuple[int, int, int]
+KEY_DOMINANCE_THRESHOLD = 16.0
+ALPHA_NOISE_FLOOR = 8
+
+
+def _die(message: str, code: int = 1) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _dependency_hint(package: str) -> str:
+    return (
+        "Activate the repo-selected environment first, then install it with "
+        f"`uv pip install {package}`. If this repo uses a local virtualenv, start with "
+        "`source .venv/bin/activate`; otherwise use this repo's configured shared fallback "
+        "environment."
+    )
+
+
+def _load_pillow():
+    try:
+        from PIL import Image, ImageFilter
+    except ImportError:
+        _die(f"Pillow is required for chroma-key removal. {_dependency_hint('pillow')}")
+    return Image, ImageFilter
+
+
+def _parse_key_color(raw: str) -> Color:
+    value = raw.strip()
+    match = re.fullmatch(r"#?([0-9a-fA-F]{6})", value)
+    if not match:
+        _die("key color must be a hex RGB value like #00ff00.")
+    hex_value = match.group(1)
+    return (
+        int(hex_value[0:2], 16),
+        int(hex_value[2:4], 16),
+        int(hex_value[4:6], 16),
+    )
+
+
+def _validate_args(args: argparse.Namespace) -> None:
+    if args.tolerance < 0 or args.tolerance > 255:
+        _die("--tolerance must be between 0 and 255.")
+    if args.transparent_threshold < 0 or args.transparent_threshold > 255:
+        _die("--transparent-threshold must be between 0 and 255.")
+    if args.opaque_threshold < 0 or args.opaque_threshold > 255:
+        _die("--opaque-threshold must be between 0 and 255.")
+    if args.soft_matte and args.transparent_threshold >= args.opaque_threshold:
+        _die("--transparent-threshold must be lower than --opaque-threshold.")
+    if args.edge_feather < 0 or args.edge_feather > 64:
+        _die("--edge-feather must be between 0 and 64.")
+    if args.edge_contract < 0 or args.edge_contract > 16:
+        _die("--edge-contract must be between 0 and 16.")
+
+    src = Path(args.input)
+    if not src.exists():
+        _die(f"Input image not found: {src}")
+
+    out = Path(args.out)
+    if out.exists() and not args.force:
+        _die(f"Output already exists: {out} (use --force to overwrite)")
+
+    if out.suffix.lower() not in {".png", ".webp"}:
+        _die("--out must end in .png or .webp so the alpha channel is preserved.")
+
+
+def _channel_distance(a: Color, b: Color) -> int:
+    return max(abs(a[0] - b[0]), abs(a[1] - b[1]), abs(a[2] - b[2]))
+
+
+def _clamp_channel(value: float) -> int:
+    return max(0, min(255, int(round(value))))
+
+
+def _smoothstep(value: float) -> float:
+    value = max(0.0, min(1.0, value))
+    return value * value * (3.0 - 2.0 * value)
+
+
+def _soft_alpha(
+    distance: int, transparent_threshold: float, opaque_threshold: float
+) -> int:
+    if distance <= transparent_threshold:
+        return 0
+    if distance >= opaque_threshold:
+        return 255
+    ratio = (float(distance) - transparent_threshold) / (
+        opaque_threshold - transparent_threshold
+    )
+    return _clamp_channel(255.0 * _smoothstep(ratio))
+
+
+def _dominance_alpha(rgb: Color, key: Color) -> int:
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return 255
+
+    channels = [float(value) for value in rgb]
+    non_spill = [idx for idx in range(3) if idx not in spill_channels]
+    key_strength = (
+        min(channels[idx] for idx in spill_channels)
+        if len(spill_channels) > 1
+        else channels[spill_channels[0]]
+    )
+    non_key_strength = max((channels[idx] for idx in non_spill), default=0.0)
+    dominance = key_strength - non_key_strength
+    if dominance <= 0:
+        return 255
+
+    denominator = max(1.0, float(max(key)) - non_key_strength)
+    alpha = 1.0 - min(1.0, dominance / denominator)
+    return _clamp_channel(alpha * 255.0)
+
+
+def _spill_channels(key: Color) -> list[int]:
+    key_max = max(key)
+    if key_max < 128:
+        return []
+    return [
+        idx for idx, value in enumerate(key) if value >= key_max - 16 and value >= 128
+    ]
+
+
+def _key_channel_dominance(rgb: Color, key: Color) -> float:
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return 0.0
+
+    channels = [float(value) for value in rgb]
+    non_spill = [idx for idx in range(3) if idx not in spill_channels]
+    key_strength = (
+        min(channels[idx] for idx in spill_channels)
+        if len(spill_channels) > 1
+        else channels[spill_channels[0]]
+    )
+    non_key_strength = max((channels[idx] for idx in non_spill), default=0.0)
+    return key_strength - non_key_strength
+
+
+def _looks_key_colored(rgb: Color, key: Color, distance: int) -> bool:
+    if distance <= 32:
+        return True
+
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return True
+
+    return _key_channel_dominance(rgb, key) >= KEY_DOMINANCE_THRESHOLD
+
+
+def _cleanup_spill(rgb: Color, key: Color, alpha: int = 255) -> Color:
+    if alpha >= 252:
+        return rgb
+
+    spill_channels = _spill_channels(key)
+    if not spill_channels:
+        return rgb
+
+    channels = [float(value) for value in rgb]
+    non_spill = [idx for idx in range(3) if idx not in spill_channels]
+    if non_spill:
+        anchor = max(channels[idx] for idx in non_spill)
+        cap = max(0.0, anchor - 1.0)
+        for idx in spill_channels:
+            if channels[idx] > cap:
+                channels[idx] = cap
+
+    return (
+        _clamp_channel(channels[0]),
+        _clamp_channel(channels[1]),
+        _clamp_channel(channels[2]),
+    )
+
+
+def _apply_alpha_to_image(
+    image,
+    *,
+    key: Color,
+    tolerance: int,
+    spill_cleanup: bool,
+    soft_matte: bool,
+    transparent_threshold: float,
+    opaque_threshold: float,
+) -> int:
+    pixels = image.load()
+    width, height = image.size
+    transparent = 0
+
+    for y in range(height):
+        for x in range(width):
+            red, green, blue, alpha = pixels[x, y]
+            rgb = (red, green, blue)
+            distance = _channel_distance(rgb, key)
+            key_like = _looks_key_colored(rgb, key, distance)
+            output_alpha = (
+                min(
+                    _soft_alpha(distance, transparent_threshold, opaque_threshold),
+                    _dominance_alpha(rgb, key),
+                )
+                if soft_matte and key_like
+                else (0 if distance <= tolerance else 255)
+            )
+            output_alpha = int(round(output_alpha * (alpha / 255.0)))
+            if 0 < output_alpha <= ALPHA_NOISE_FLOOR:
+                output_alpha = 0
+
+            if output_alpha == 0:
+                pixels[x, y] = (0, 0, 0, 0)
+                transparent += 1
+                continue
+
+            if spill_cleanup and key_like:
+                red, green, blue = _cleanup_spill(rgb, key, output_alpha)
+            pixels[x, y] = (red, green, blue, output_alpha)
+
+    return transparent
+
+
+def _contract_alpha(image, pixels: int):
+    if pixels == 0:
+        return image
+
+    _, ImageFilter = _load_pillow()
+    alpha = image.getchannel("A")
+    for _ in range(pixels):
+        alpha = alpha.filter(ImageFilter.MinFilter(3))
+    image.putalpha(alpha)
+    return image
+
+
+def _apply_edge_feather(image, radius: float):
+    if radius == 0:
+        return image
+
+    _, ImageFilter = _load_pillow()
+    alpha = image.getchannel("A")
+    alpha = alpha.filter(ImageFilter.GaussianBlur(radius=radius))
+    image.putalpha(alpha)
+    return image
+
+
+def _encode_image(image, output_format: str) -> bytes:
+    out = BytesIO()
+    image.save(out, format=output_format.upper())
+    return out.getvalue()
+
+
+def _alpha_counts(image) -> tuple[int, int, int]:
+    pixels = image.load()
+    width, height = image.size
+    total = 0
+    transparent = 0
+    partial = 0
+
+    for y in range(height):
+        for x in range(width):
+            alpha = pixels[x, y][3]
+            total += 1
+            if alpha == 0:
+                transparent += 1
+            elif alpha < 255:
+                partial += 1
+
+    return total, transparent, partial
+
+
+def _sample_border_key(image, mode: str) -> Color:
+    width, height = image.size
+    pixels = image.load()
+    samples: list[Color] = []
+
+    if mode == "corners":
+        patch = max(1, min(width, height, 12))
+        boxes = [
+            (0, 0, patch, patch),
+            (width - patch, 0, width, patch),
+            (0, height - patch, patch, height),
+            (width - patch, height - patch, width, height),
+        ]
+        for left, top, right, bottom in boxes:
+            for y in range(top, bottom):
+                for x in range(left, right):
+                    red, green, blue = pixels[x, y][:3]
+                    samples.append((red, green, blue))
+    else:
+        band = max(1, min(width, height, 6))
+        step = max(1, min(width, height) // 256)
+        for x in range(0, width, step):
+            for y in range(band):
+                red, green, blue = pixels[x, y][:3]
+                samples.append((red, green, blue))
+                red, green, blue = pixels[x, height - 1 - y][:3]
+                samples.append((red, green, blue))
+        for y in range(0, height, step):
+            for x in range(band):
+                red, green, blue = pixels[x, y][:3]
+                samples.append((red, green, blue))
+                red, green, blue = pixels[width - 1 - x, y][:3]
+                samples.append((red, green, blue))
+
+    if not samples:
+        _die("Could not sample background key color from image border.")
+
+    return (
+        int(round(median(sample[0] for sample in samples))),
+        int(round(median(sample[1] for sample in samples))),
+        int(round(median(sample[2] for sample in samples))),
+    )
+
+
+def _remove_chroma_key(args: argparse.Namespace) -> None:
+    Image, _ = _load_pillow()
+    src = Path(args.input)
+    out = Path(args.out)
+
+    with Image.open(src) as image:
+        rgba = image.convert("RGBA")
+    key = (
+        _sample_border_key(rgba, args.auto_key)
+        if args.auto_key != "none"
+        else _parse_key_color(args.key_color)
+    )
+
+    transparent = _apply_alpha_to_image(
+        rgba,
+        key=key,
+        tolerance=args.tolerance,
+        spill_cleanup=args.spill_cleanup,
+        soft_matte=args.soft_matte,
+        transparent_threshold=args.transparent_threshold,
+        opaque_threshold=args.opaque_threshold,
+    )
+    rgba = _contract_alpha(rgba, args.edge_contract)
+    rgba = _apply_edge_feather(rgba, args.edge_feather)
+
+    total, transparent_after, partial_after = _alpha_counts(rgba)
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    output_format = "PNG" if out.suffix.lower() == ".png" else "WEBP"
+    out.write_bytes(_encode_image(rgba, output_format))
+
+    print(f"Wrote {out}")
+    print(f"Key color: #{key[0]:02x}{key[1]:02x}{key[2]:02x}")
+    print(f"Transparent pixels: {transparent_after}/{total}")
+    print(f"Partially transparent pixels: {partial_after}/{total}")
+    if transparent == 0:
+        print(
+            "Warning: no pixels matched the key color before feathering.",
+            file=sys.stderr,
+        )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Remove a solid chroma-key background and write an image with alpha."
+    )
+    parser.add_argument("--input", required=True, help="Input image path.")
+    parser.add_argument("--out", required=True, help="Output .png or .webp path.")
+    parser.add_argument(
+        "--key-color",
+        default="#00ff00",
+        help="Hex RGB key color to remove, for example #00ff00.",
+    )
+    parser.add_argument(
+        "--tolerance",
+        type=int,
+        default=12,
+        help="Hard-key per-channel tolerance for matching the key color, 0-255.",
+    )
+    parser.add_argument(
+        "--auto-key",
+        choices=["none", "corners", "border"],
+        default="none",
+        help="Sample the key color from image corners or border instead of --key-color.",
+    )
+    parser.add_argument(
+        "--soft-matte",
+        action="store_true",
+        help="Use a smooth alpha ramp between transparent and opaque thresholds.",
+    )
+    parser.add_argument(
+        "--transparent-threshold",
+        type=float,
+        default=12.0,
+        help="Soft-matte distance at or below which pixels become fully transparent.",
+    )
+    parser.add_argument(
+        "--opaque-threshold",
+        type=float,
+        default=96.0,
+        help="Soft-matte distance at or above which pixels become fully opaque.",
+    )
+    parser.add_argument(
+        "--edge-feather",
+        type=float,
+        default=0.0,
+        help="Optional alpha blur radius for softened edges, 0-64.",
+    )
+    parser.add_argument(
+        "--edge-contract",
+        type=int,
+        default=0,
+        help="Shrink the visible alpha matte by this many pixels before feathering.",
+    )
+    parser.add_argument(
+        "--spill-cleanup",
+        dest="spill_cleanup",
+        action="store_true",
+        help="Reduce obvious key-color spill on opaque pixels.",
+    )
+    parser.add_argument(
+        "--despill",
+        dest="spill_cleanup",
+        action="store_true",
+        help="Alias for --spill-cleanup; decontaminate key-color edge spill.",
+    )
+    parser.add_argument(
+        "--force", action="store_true", help="Overwrite an existing output file."
+    )
+    return parser
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    _validate_args(args)
+    _remove_chroma_key(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/LICENSE.txt b/codex-rs/skills/src/assets/samples/openai-docs/LICENSE.txt
new file mode 100644
index 0000000000000000000000000000000000000000..13e25df86ce06eb6488e6a6bc5c5847f5dedc352
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/LICENSE.txt
@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don\'t include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/SKILL.md b/codex-rs/skills/src/assets/samples/openai-docs/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..a872d0cb9bbbd7dabf17ef7328befbc73a19e8b4
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: "openai-docs"
+description: "Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex."
+metadata:
+  short-description: "Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, and self-knowledge; OpenAI APIs and ChatGPT Work. 'You'/'this app' means Codex only."
+---
+
+# OpenAI Docs
+
+Provide current, cited OpenAI product, API, model, and Codex guidance. Read zero or one primary reference.
+
+**First substantive action:** Search the user's exact requested official OpenAI documentation topic and any explicitly named model using a concise, topic-specific query of 2-6 essential terms. When an already-available direct official documentation search and page-retrieval capability is present, use it first: search, then fetch or open the matching official page before general web search. Otherwise, immediately use official-domain web search, then actually open or fetch the relevant official page. Complete this source order before reading a reference, inspecting local or repository files, running a Codex manual or model resolver, drafting a plan, or answering from memory. Use the actual fetched page, not a search snippet or an unopened link. If one official search or page does not establish the answer, search another appropriate official domain and actually open or fetch the result. Preserve the exact requested model; never substitute a newer model.
+
+**Only exception:** An explicitly requested, genuinely broad, cross-topic Codex setup, orientation, or system-map synthesis may use the manual first when shell execution and an allowed temporary cache are available. A specific Codex feature, setting, command, error, model, or requested citation remains docs-first. Mixed Chat/Work/Codex comparisons are official documentation questions, not manual-first Codex requests.
+
+For generic software tasks, answer the software task directly. OpenAI implementation, debugging, SDK, API, prompting, agent, and eval requests are not generic.
+
+For a straightforward factual or citation-only request, follow the source order and do not read a route reference. This includes straightforward API facts, ChatGPT Work or mixed Chat/Work/Codex comparisons, model tiers, aliases, Pro mode, reasoning settings, factual migration baselines, and narrow Codex facts. Prioritize `learn.chatgpt.com` for ChatGPT Work.
+
+## Choose one primary route
+
+Use the first matching route, and read its reference only when the requested task needs that specialized workflow:
+
+- **Explicitly requested local documentation integration:** Read [integration guidance](references/mcp-diagnostics.md) only when the user explicitly requests that local integration.
+- **Model migration, upgrades, or model-specific prompting:** Read [model-migration.md](references/model-migration.md) for actual migration planning, implementation, dynamic target resolution, or prompt changes. Preserve an explicitly requested target.
+- **Model selection and comparisons:** Read [model-selection.md](references/model-selection.md) only when nuanced current, latest, default, cost, latency, quality, or modality tradeoffs need more guidance. Do not run a migration resolver for selection alone.
+- **Product, API, ChatGPT Work, and mixed Chat/Work/Codex documentation:** Read [official-docs.md](references/official-docs.md) only when fetched official pages leave source selection, API schemas, or the requested implementation unresolved. This route is not manual-first.
+- **Explicitly broad Codex setup, orientation, or cross-topic synthesis:** Read [codex-self-knowledge.md](references/codex-self-knowledge.md) when the eligible Codex manual or deeper Codex procedures are needed.
+
+Read at most one primary reference. Do not open every route, bundled model guide, or helper script. Read a supporting reference or run a helper only when the chosen workflow demonstrably needs it.
+
+## Source and execution boundaries
+
+- Search, open, fetch, and cite only `developers.openai.com`, `platform.openai.com`, and `learn.chatgpt.com`. Cite the page that supports the claim. State uncertainty when official sources do not establish pricing, availability, account access, limits, or behavior.
+- Preserve an explicitly requested model for selection, migration, and prompting. Resolve an unspecified latest or current migration target only after searching and fetching current official guidance.
+- Use `references/latest-model.md` only as a disclosed fallback after current official model guidance does not answer the question. Read `references/upgrading-to-gpt-6-astra.md` only for an actual, requested GPT-6 migration; read `references/prompting-guide.md` only for requested prompting work.
+- Before building, running, editing, debugging, or testing an API-backed app or tool, use `openai-platform-api-key` first when available. Documentation, conceptual examples, model selection, and read-only guidance do not require an API key.
+- Say "OpenAI Docs" or "official OpenAI documentation" in user-facing answers. Keep exact official citations and examples concise.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/agents/openai.yaml b/codex-rs/skills/src/assets/samples/openai-docs/agents/openai.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..da825cdd657d8de29f7fd9eb2f29eb98c34a4661
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "OpenAI Docs"
+  short_description: "OpenAI and Codex docs for models, skills, tasks, and setup"
+  icon_small: "./assets/openai-small.svg"
+  icon_large: "./assets/openai.png"
+  default_prompt: "Use OpenAI Docs for official docs lookup, questions about Codex itself or Codex surfaces, model selection, model migration, and prompt-upgrade work."
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/assets/openai-small.svg b/codex-rs/skills/src/assets/samples/openai-docs/assets/openai-small.svg
new file mode 100644
index 0000000000000000000000000000000000000000..1d075dc04f617247747ca8e44f8aa9193e0ab3e6
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/assets/openai-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 14 14">
+  <path d="M10.931 3.34a.112.112 0 0 0-.069-.104l-.038-.007c-1.537.05-2.45.318-3.714 1.002v6.683c.48-.248.936-.44 1.414-.58.695-.203 1.417-.292 2.303-.305l.038-.008a.113.113 0 0 0 .066-.104V3.341ZM2.363 9.919c0 .064.051.11.105.111l.33.008c1.162.046 2.042.243 2.975.662-.403-.585-1.008-1.075-1.654-1.292a.991.991 0 0 1-.674-.941v-5.14a6.36 6.36 0 0 0-.59-.076l-.37-.02a.115.115 0 0 0-.122.111v6.577Zm9.455-.001a.998.998 0 0 1-.877.992l-.101.007c-.832.012-1.47.095-2.066.27-.599.174-1.176.448-1.883.863a.444.444 0 0 1-.449 0c-1.299-.763-2.229-1.07-3.689-1.125l-.299-.008a.997.997 0 0 1-.977-.998V3.342c0-.573.478-1.017 1.038-.999l.417.023c.188.015.35.037.513.062v-.754c0-.708.749-1.244 1.429-.903.984.492 1.836 1.449 2.15 2.505 1.216-.617 2.222-.884 3.771-.934l.105.003a.998.998 0 0 1 .918.996v6.576ZM4.332 8.466c0 .049.03.087.07.1l.24.091a4.319 4.319 0 0 1 1.581 1.176V3.721c-.164-.803-.799-1.617-1.584-2.07l-.162-.088c-.025-.012-.054-.013-.088.009a.12.12 0 0 0-.057.102v6.792Z"/>
+</svg>
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/assets/openai.png b/codex-rs/skills/src/assets/samples/openai-docs/assets/openai.png
new file mode 100644
index 0000000000000000000000000000000000000000..e9b9eb80cd90ccdfc7e276b07f4046aa9c9d1887
Binary files /dev/null and b/codex-rs/skills/src/assets/samples/openai-docs/assets/openai.png differ
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/codex-self-knowledge.md b/codex-rs/skills/src/assets/samples/openai-docs/references/codex-self-knowledge.md
new file mode 100644
index 0000000000000000000000000000000000000000..f0195313661d0a12531cbaa8c26fcda03803a5ae
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/codex-self-knowledge.md
@@ -0,0 +1,71 @@
+# Codex self-knowledge
+
+Use this manual-first route only for genuinely broad Codex setup, orientation, customization, troubleshooting, local-state guidance, or system-map synthesis across skills, plugins, MCP, hooks, `AGENTS.md`, automations, and product surfaces. Mixed Chat/Work/Codex comparisons belong to `official-docs.md` instead.
+
+Narrow Codex documentation questions require official documentation search first, then an actual page open or fetch using an available documentation or official-domain web capability. This includes a single feature such as Codex Goals, a specific setting, documented behavior, exact error, or requested page citation. Search and fetch the exact official topic before inspecting local files or bundled references. Do not fetch the manual, read bundled references, inspect local configuration or caches, or turn a targeted documentation lookup into broad product synthesis. Current or latest model questions follow the model-selection route.
+
+## Start with the manual
+
+Reuse a manual path and outline path already established in the same thread when both remain usable and current. Refresh before relying on a path fetched more than about a day ago, obtained from another thread or uncertain source, or missing likely-current information.
+
+Otherwise, run the bundled manual helper first. Skip it without probing only when policy explicitly makes the session read-only, shell execution unavailable, or every allowed temporary cache location unavailable. Workspace-only write access is not enough: the helper needs an allowed writable temp cache. A guessed sandbox restriction is not evidence that the helper is unavailable.
+
+Resolve `<skill-dir>` to the actual installed skill directory, then run:
+
+```bash
+node <skill-dir>/scripts/fetch-codex-manual.mjs
+```
+
+The helper automatically chooses the first usable cache location in this order:
+
+1. `$TMPDIR/openai-docs-cache`
+2. `%TEMP%\openai-docs-cache`
+3. `%TMP%\openai-docs-cache`
+4. `/private/tmp/openai-docs-cache`
+5. `/tmp/openai-docs-cache`
+
+Use an explicit override only when the allowed cache must be selected manually:
+
+```bash
+node <skill-dir>/scripts/fetch-codex-manual.mjs --cache-dir <cache-dir>
+```
+
+On Windows, `%TEMP%` and `%TMP%` are discovered automatically; `$env:TEMP\openai-docs-cache` is a typical PowerShell override. The helper handles configured HTTP(S) proxies and falls back to `curl` when needed. Do not require a POSIX-only environment prefix or an unnecessary cache override.
+
+The helper verifies the current source and returns a manual path, outline path, freshness status, and heading outline. Use that outline to locate relevant headings and line ranges, then read or search only the returned manual and outline paths. Do not inspect unrelated repositories, caches, source trees, or local state to establish a public Codex product claim.
+
+For follow-up questions in the same thread, reuse those fresh paths instead of fetching again. If asked whether the manual is current enough to rely on now, rerun the helper when an allowed temp cache is available and answer from its reported status and returned paths.
+
+## Fill only genuine documentation gaps
+
+If the manual answers a claim, stop retrieving sources for that claim. Its official source pages and known anchors are sufficient citation support. Continue the user's broader task when the documentation lookup was only one dependency.
+
+If the helper was legitimately skipped, actually fails, or the fresh manual lacks a material or likely-current claim, use the narrowest official follow-up. Search the exact topic using an available documentation or approved-domain web capability, then actually open or fetch a clearly relevant official result. A page-specific citation can justify the same narrow follow-up.
+
+For an undocumented Codex term, mode, acronym, or exact error, first check adjacent manual terminology. Map it to the closest documented concept when possible. If the exact term is material or likely current, perform one targeted official search-and-fetch; if it remains undocumented, say so. Do not expand into internal knowledge bases, private source trees, guessed roadmap details, or account-specific workarounds.
+
+If official documentation conflicts with a callable capability verified in the current session, explicitly state the conflict and prefer that verified behavior for this environment. Otherwise, resolve unsupported claims with bounded uncertainty or route the user to support, an administrator, or product feedback.
+
+## Choose the smallest matching Codex surface
+
+- Prompt or thread context: one-off task constraints.
+- Repository `AGENTS.md`: durable team conventions, commands, and verification expectations; nested files apply more specifically within their subtree.
+- Project `.codex/config.toml`: settings for a trusted repository, including sandbox, MCP, hooks, model, and reasoning defaults.
+- Global config or global guidance: personal defaults across repositories.
+- Skill: a reusable workflow, optionally with focused references or scripts.
+- Plugin: an installable bundle of skills, tools, commands, MCP configuration, hooks, apps, assets, or related metadata.
+- MCP server or app connector: authorized live external data and actions. Use an authenticated connector, not web search or memory, for private Google Docs, Calendar, Slack, GitHub, Notion, or similar workspace data.
+- Automation: scheduled checks, reminders, monitors, or follow-ups; use an existing-thread heartbeat when continuity matters.
+- Hook: mechanical enforcement around lifecycle events, tool calls, commands, or edits.
+
+Split requests that combine one-off, durable, repository-scoped, and recurring behavior instead of forcing them onto a single surface. For example, "always do this, but only for this PR" belongs in the current prompt or thread unless the user explicitly wants persistence or enforcement.
+
+For a surface recommendation, state what to use, why it fits, what to avoid, and the manual or official documentation supporting the answer.
+
+For product surfaces, distinguish terminal-first CLI work, editor-attached IDE work, desktop planning or review, hosted cloud execution, in-app browser testing, the user's existing Chrome session, and desktop Computer Use. Keep `config.toml` defaults, `requirements.toml` constraints, and managed or administrator policy separate. An API key does not establish ChatGPT, Codex cloud, connector, or account access.
+
+For plugin or app failures, check the installed bundle, enabled state, connector authorization, MCP setup, restart or new-thread expectations, and workspace policy before inferring a cause. Route billing, entitlements, undocumented rollout labels, and unsupported access paths to the appropriate support or administrative owner.
+
+Memory can provide user preferences or context, but explicit prompt instructions win and memory is not a source for current external facts. Sandbox or network denials require narrowly scoped escalation with a clear justification; destructive commands, writes outside the workspace, and broad access changes require explicit approval.
+
+When a page-specific citation helps, useful official anchors include `concepts/customization#agents-guidance`, `concepts/customization#skills`, `plugins/build#plugin-structure`, `concepts/customization#mcp`, `config-advanced#hooks`, `app/automations#thread-automations`, and `config-reference#configtoml`.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.md b/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.md
new file mode 100644
index 0000000000000000000000000000000000000000..d4fca8c4f0cde0f146f78143e5816aacd16dea3f
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/latest-model.md
@@ -0,0 +1,25 @@
+# Latest model fallback
+
+This is a compact, non-authoritative fallback, not a source for current availability, prices, aliases, or defaults. First search for and fetch current official model guidance at `https://developers.openai.com/api/docs/guides/latest-model` and the relevant official model page. The fetched official documentation wins if this snapshot has drifted. Disclose any use of this fallback.
+
+## Model roles
+
+| Model ID | Documented workload to verify against the current model page |
+| --- | --- |
+| `gpt-6` | GPT-6 family alias; verify its currently documented routing and availability. |
+| `gpt-6-astra` | Quality-first flagship, reasoning, and difficult coding work. |
+| `gpt-5.6-terra` | Balanced quality, latency, and cost. |
+| `gpt-5.6-luna` | Primary choice for faster or cheaper workloads. |
+
+Use `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#migration-quickstart` for an actual GPT-6 migration and `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices` for requested GPT-6 prompting. Open and read the relevant page before recommending a request shape, reasoning setting, endpoint, tool behavior, or migration.
+
+## Explicitly requested existing models
+
+| Model ID | Boundary |
+| --- | --- |
+| `gpt-4.1` | Preserve only when the user explicitly requests this model or existing migration target; search and fetch its own current official guide. |
+| `gpt-5.4` | Preserve only when the user explicitly requests this model or existing migration target; search and fetch its own current official guide. |
+
+Do not promote a legacy model as the current default, substitute it into an unrelated task, or replace an explicitly requested legacy target with GPT-6 Astra. Recommend a specialized image, audio, realtime, coding, moderation, or embedding model only after verifying the requested modality against current official documentation.
+
+Verify GPT-6 Pro against current official Responses and model documentation before describing model IDs, reasoning modes, request parameters, or account availability; do not invent a separate `gpt-6-pro` model slug.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/mcp-diagnostics.md b/codex-rs/skills/src/assets/samples/openai-docs/references/mcp-diagnostics.md
new file mode 100644
index 0000000000000000000000000000000000000000..a49d0f2993dc6c08c14bd5c6bee7c710b3f0296c
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/mcp-diagnostics.md
@@ -0,0 +1,27 @@
+# Local documentation MCP setup and diagnostics
+
+Use this route only when the user explicitly asks to configure or troubleshoot the official OpenAI documentation MCP server in a supported **local Codex client**. A missing documentation tool during an ordinary documentation request is not a setup request: answer with the root skill's official-domain web fallback without installation, sandbox escalation, configuration changes, or restart.
+
+## Verify the supported local setup
+
+1. Search and fetch current official Codex MCP setup documentation when those tools are callable. Otherwise, search and fetch the relevant official OpenAI documentation directly.
+2. Confirm the documented endpoint is `https://developers.openai.com/mcp` and verify the supported command or configuration against that current documentation before recommending it.
+3. When the current documentation supports it, the local Codex CLI setup is:
+
+   ```sh
+   codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
+   ```
+
+   The equivalent documented configuration is:
+
+   ```toml
+   [mcp_servers.openaiDeveloperDocs]
+   url = "https://developers.openai.com/mcp"
+   ```
+
+4. Check the supported local client's MCP listing or configuration, its enabled state, relevant workspace/admin policy, and any documented authentication requirement. Verify success from the actual command result, configuration, or a callable documentation-tool search/fetch; never claim installation or access without evidence.
+5. Recommend a local-client restart or new local session only when current official documentation or observed client behavior requires it. Clearly identify which local client must refresh.
+
+A skill dependency declaration, configured server, or local-client setup does not make a tool callable in an already running session. In particular, editing a hosted container's local configuration cannot install a tool into the host or model's current tool inventory. Never claim a local command installed the server into a current hosted session.
+
+Only perform a local installation or configuration change when the user explicitly authorizes that change. Never request sandbox escalation, edit hosted configuration, install a dependency, or ask the user to restart a hosted session merely to answer an ordinary documentation question.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.md b/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.md
new file mode 100644
index 0000000000000000000000000000000000000000..934c5c1ec32766088680ae1a996ecf60357e23ba
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/model-migration.md
@@ -0,0 +1,45 @@
+# Model migration and prompting
+
+Use this route for model upgrades, migration planning, model-specific prompting, or latest/current/default prompting guidance. First search current official OpenAI documentation for the exact requested topic and model, then open or fetch the relevant official page using an available documentation or official-domain web capability. Do not run a resolver, open bundled references, or rely on a guide URL before completing that official search and actual page fetch.
+
+## Choose the target before loading more context
+
+- **Explicit model target:** Preserve the user's exact requested target, including an explicitly requested GPT-5.5 or GPT-5.6 migration. Do not run the latest-model resolver and do not substitute a newer model. Search for and fetch current guidance for that exact model. A GPT-5.6 migration must not load GPT-6 guidance or references.
+- **Unspecified, latest, current, or default target:** Search for and fetch `https://developers.openai.com/api/docs/guides/latest-model` first. Use the corresponding `latest-model.md` metadata only when dynamic migration resolution is needed, then run the platform-specific resolver below and preserve its returned model and exact guide URLs.
+- **Latest/current/default prompting:** Follow the dynamic-target route, then use the returned prompting guide. Do not run the resolver for explicitly named-model prompting.
+- **Pure model selection:** Use `references/model-selection.md` instead. Do not run the resolver.
+
+For POSIX shells, invoke the resolver through `sh`, without assuming an executable bit:
+
+```sh
+sh <skill-dir>/scripts/resolve-latest-model-info
+```
+
+On Windows, use the CommonJS entry point with Node.js 18 or newer:
+
+```text
+node <skill-dir>\scripts\resolve-latest-model-info.cjs
+```
+
+If the Windows Node runtime is unavailable and `load_workspace_dependencies` is callable, use its returned runtime and retry once. Do not execute the extensionless POSIX wrapper directly on Windows.
+
+Do not suppress or redirect resolver stdout. Success requires JSON with nonempty `model`, `migrationGuideUrl`, and `promptingGuideUrl` fields. If the command fails or any required field is missing, retry the platform-specific command once, then fall back to current official documentation and finally disclosed bundled references.
+
+## Retrieve only the guidance this request needs
+
+Treat returned guide URLs as opaque: fetch those exact URLs without deriving, substituting, or appending a model query. Use an available official documentation or first-party-domain capability to open and read the relevant official page. Retry the exact guide URL when its response contains only a title or no substantive body.
+
+- Fetch `migrationGuideUrl` for a requested migration or upgrade plan.
+- Fetch `promptingGuideUrl` only when the user asks for prompting guidance or the migration requires a prompt change. Extract only `## Prompting best practices` through the next H2 heading.
+- For explicitly named-model prompting, fetch that model's official prompting guidance and extract only `## Prompting best practices` through the next H2 heading. Do not load a migration reference or run the resolver.
+- For an actual GPT-6 migration or implementation plan, fetch `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#migration-quickstart`. For specifically requested GPT-6 prompting, fetch `https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices`. Read `references/upgrading-to-gpt-6-astra.md` only when fetched official guidance does not resolve needed compatibility gates, scoped code changes, tier-aware routing, validation, or other migration-specific judgment. Never load it for documentation-only questions about model tiers, the family alias, Pro mode, reasoning effort, or current guidance when the fetched official documentation already answers them.
+- Read `references/prompting-guide.md` only when prompting guidance or prompt changes are actually needed and current official guidance is unavailable.
+- Read `references/upgrade-guide.md` only when current official migration guidance is unavailable. Disclose when a bundled fallback was used.
+
+## Keep implementation changes scoped
+
+Change active model defaults and directly related prompt surfaces only when the user requested that work. Update registries, model pickers, capability metadata, routing, pricing, or tests only when they are in scope and current official documentation verifies the relevant values.
+
+Preserve each workload's cost, latency, quality, reasoning, tool, endpoint, and output-contract role. Do not collapse a tiered router into one flagship model, replace intentionally pinned fallbacks, or rewrite historical examples, fixtures, eval baselines, provider comparisons, or unrelated SDK and authentication configuration.
+
+If a safe migration requires an endpoint change, request-schema change, tool-handler change, or other implementation outside the requested scope, report the exact compatibility blocker and smallest follow-up instead of silently changing behavior.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/model-selection.md b/codex-rs/skills/src/assets/samples/openai-docs/references/model-selection.md
new file mode 100644
index 0000000000000000000000000000000000000000..6ff3dfaecaead748e4ff2fa6f65d6eae314e8264
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/model-selection.md
@@ -0,0 +1,12 @@
+# Model selection
+
+Use this route for model recommendations, comparisons, and latest/current/default choices when the user is not requesting a migration or prompting guidance.
+
+1. Search current official OpenAI documentation for the exact requested workload and any explicitly named model; then open or fetch the relevant official page. For current or latest family guidance, use `https://developers.openai.com/api/docs/guides/latest-model`.
+2. Use any available official documentation or first-party-domain search. Read the actual source; do not make a recommendation from a search snippet, guessed default, or bundled snapshot.
+3. Match the documented model to the user's requested modality, quality, latency, cost, context, and workload. Distinguish flagship, balanced, high-throughput, coding, audio, image, or other specialized roles only when the fetched current documentation supports the distinction.
+4. Preserve an explicitly requested model or existing target. Cite the current official page and state uncertainty about availability, pricing, limits, or account access.
+
+Pure model selection does not require migration metadata. **Do not run the resolver.**
+
+Read `references/latest-model.md` only when fetched current official sources cannot answer the question. Disclose that bundled fallback guidance was used and may be outdated.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/official-docs.md b/codex-rs/skills/src/assets/samples/openai-docs/references/official-docs.md
new file mode 100644
index 0000000000000000000000000000000000000000..204e31ed993a2caab225571350af7fa874fbee53
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/official-docs.md
@@ -0,0 +1,25 @@
+# Official documentation, API references, and ChatGPT Work
+
+Use this route for OpenAI product or API documentation, examples, citations, ChatGPT Work, learning content, mixed Chat/Work/Codex comparisons, and narrow Codex product documentation. Follow the root skill's official-source order and credential boundary.
+
+An explicit OpenAI documentation question stays documentation-first even when embedded in a broader repository, Promptfoo, agent-evaluation, `PLANS.md`, frontend, tool-use, image, Realtime API, SDK installation, or streaming-debugging task. Search the exact requested official documentation and open or fetch its relevant page before inspecting local files, drafting a plan, running evals, reading bundled references, or invoking the Codex manual. Then use the fetched official source to complete the requested work.
+
+## Find the smallest useful source
+
+1. Search the exact topic with a specific, title-like query containing 2-6 essential terms. Prefer an already-available direct official documentation search and page-retrieval capability; search, then fetch or open the best page or section. Otherwise, immediately use official-domain web search and actually open or fetch the result.
+2. If the results are noisy, narrow the query. When a plausible official documentation URL is available, open or fetch the page instead of relying on search snippets. Use an already available documentation index only when there is no clear search query.
+3. For API schemas, required fields, parameters, or endpoint shapes, use an already available OpenAPI or specification capability when it directly resolves the question. Otherwise verify the shape against the fetched official API guide or reference.
+4. Cite the exact official page supporting each consequential claim. Keep examples minimal, paraphrase instead of quoting at length, and state when official sources do not establish a capability, parameter, price, or availability.
+
+Preserve an explicitly requested model in the search and answer. Search the requested topic directly for model-specific frontend and tool-use prompting, image input or generation, Realtime voice or translation, official Agents SDK installation, Responses streaming errors, and Codex Goals. A specific Codex feature, error, setting, or requested citation is a narrow documentation lookup, not the broad manual-first exception. Current or latest model recommendations follow the model-selection route and the same official search-and-fetch order.
+
+## ChatGPT Work and mixed surfaces
+
+Treat a comparison between Chat, Work, and Codex as ChatGPT Work documentation, not broad Codex self-knowledge. Search `learn.chatgpt.com` and open or fetch the relevant official page. Useful starting pages are:
+
+- `https://learn.chatgpt.com/docs/use-chatgpt`
+- `https://learn.chatgpt.com/docs/get-started-with-work`
+
+If someone simply asks an API question from ChatGPT Work, answer the API question from the relevant API guide. Being in Work does not make it a question about the Work product.
+
+Separate documented user-facing purposes from unsupported claims about underlying models, hard capability boundaries, file or context inheritance, exact UI labels, account entitlements, and rollout availability. When those details cannot be verified, cite the closest allowed official source and state the uncertainty.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.md b/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.md
new file mode 100644
index 0000000000000000000000000000000000000000..2370a8a1ab15a97337b7640f0ea0aba9901bf3c1
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/prompting-guide.md
@@ -0,0 +1,115 @@
+## Retrieve the live GPT-6 prompting guidance
+
+Use already-callable official documentation search and fetch, or immediately use official-domain web search and fetch, to retrieve the live GPT-6 prompting guidance from:
+
+https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices
+
+Read only the `## Prompting best practices` section, stopping at the next H2 heading. The URL anchor points to the section visually, but a documentation fetch may return the full page, so explicitly extract only that section.
+
+Treat the live section as the canonical model-specific prompting guidance. Use the local copy below only when live guidance is unavailable. Keep it identical to the page's `## Prompting best practices` section when refreshing this reference.
+
+## Prompting best practices
+
+GPT-6 Astra is more intelligent and capable than prior models like GPT-5.6 Sol, and also exhibits behavior patterns that can be optimized through prompting the model for your use case.
+
+### GPT-6 Astra behavior
+
+- [Initiative and follow-through](#initiative-and-follow-through) – The model is designed to be a more effective collaborator and is thus more likely to ask the user a question when additional input could materially change the result. This can cause it to stop when the user may expect it to make reasonable assumptions and persist.
+- [Instruction following](#instruction-following) – GPT-6 Astra is stronger at general instruction following than our previous models, giving you greater control over its behavior. It can be more sensitive to instructions contained in skills and other files, such as `AGENTS.md`. We **strongly recommend** auditing skills and other files accessible to your model for instructions that could influence its behavior.
+- [Personality and writing style](#personality-and-writing-style) – The model tends toward detailed, formatted responses and may use recurring phrases across sessions. Specify the writing style and structure your application needs.
+- [Subagent delegation](#subagent-delegation) – The model may delegate less often than desired for your workflow. Specify when and how much it should use subagents for parallel work.
+- [Testing and verification](#testing-and-verification) – For coding tasks, the model tends to be thorough in testing before considering a task complete. For smaller tasks, this can result in broader tests than the task requires.
+
+### Initiative and follow-through
+
+GPT-6 Astra is generally better than GPT-5.6 Sol and earlier models at staying coherent during long tasks. It is also more likely to ask for clarification where earlier models would make assumptions.
+
+To encourage more autonomous work, start with this prompt:
+
+```text
+You should infer the user's intent and task scope from the instructions and prior conversation context. Your job is to bias towards action and carry the user's intended task to completion.
+
+When the user expresses intent to perform new work or fix an existing issue, persist until the user's intended goal is complete. Progress autonomously towards the user's goal (e.g. creating isolated worktrees / checkouts if needed, resolving merge conflicts, read-only actions, creating draft PRs etc.) unless they are clearly destructive or irreversible.
+```
+
+When the user’s intent is unclear, the model is more likely to ask the user for clarification to proceed. Prompt the model to follow through if the user’s prompt implies authorization:
+
+```text
+When the user's prompt indicates a request for action, such as "can you...", "I want to...", "help me..." and similar expressions, treat these as instructions to do the work and take action. Do not stop at acknowledging capability (e.g. "Yes…"), proposing a plan, or offering to continue. Do not settle for a partial or "helpful enough" solution that does not fully satisfy the user's task to save time, effort or tokens. If a task requires sustained work, complete all the necessary work until the intended outcome is fulfilled.
+```
+
+Prompt the model to ask for approval only after preparing a concrete, reviewable result. This avoids blocking the task before the model has done the work it can, and often leads to quicker task completion.
+
+```text
+Before asking the user clarifying questions, you should complete the work that is already authorized from context and necessary to make the proposed action concrete and reviewable. The user should be approving a concrete, reviewable result. For example, before deploying a change, writing to an external application, merging a PR or publishing a site, do all the required work first so that user approval is the final step. You don't need user permission for reversible tasks, read-only actions, reviews or fixes, or anything for which authorization is provided earlier in the session or strongly implied from the task instruction.
+
+Do not introduce unsolicited warnings, disclaimers, approval flows, or safety/compliance checklists due to hypothetical risk.
+```
+
+The model also likes to ask non-blocking questions as it’s working by default, so adjust these prompts to match the level of autonomy your application needs.
+
+### Instruction following
+
+GPT-6 Astra is better able to follow longer instructions, but can also be more sensitive to information in context. For example, unclear or conflicting guidance in a skill file may cause the model to pause and block work early. Make the priority of user instructions and skills explicit.
+
+```text
+The user's instructions take precedence over guidelines provided in a skill. If explicit user instructions conflict with a skill's instructions, prioritize the user's instructions.
+```
+
+Asking the model to identify the skill and instruction that caused it to pause or change direction can also be effective in providing transparency into model behavior.
+
+```text
+If a skill causes you to ask for permission or confirmation, pause, leave requested work unfinished, or diverge from the user's intent, name and link to the exact SKILL.md file you read, quote the relevant instruction, and briefly explain how it applies. Distinguish explicit skill requirements from your interpretation of guidelines.
+```
+
+Use this prompt to find silent and conflicting guidance when your application loads many skills and instruction files such as `AGENTS.md`.
+
+### Personality and writing style
+
+GPT-6 Astra tends to use lists, tables and Markdown to make responses scannable. If your application needs prose with less formatting, specify that preference.
+
+```text
+Default to using clear, concise paragraphs, each developing one main idea. Use lists only when the information is genuinely parallel, sequential, or easier to compare, and avoid nested lists unless the hierarchy cannot be expressed clearly in prose. Use plain, simple language: familiar words, concrete examples, and precise verbs. Prefer active voice and direct statements.
+
+Make sure to state the main point clearly and early, then develop it with the explanation and detail the reader needs. Let each sentence build on what came before. Develop the points that matter and provide enough support to be useful.
+```
+
+For technical communication, the following prompt helps strike a balance between using clear, coherent language while remaining domain appropriate:
+
+```text
+Use plain language over jargon, and reference technical details only to the degree that it helps illustrate an idea or your work to the user. Communicate complex concepts in a clear and cohesive manner, and calibrate your writing to the level of background knowledge assumed from the user's prompt and context.
+```
+
+To reduce jargon and stock phrases in writing, start with this prompt:
+
+```text
+Avoid using slop words or phrases like "Bottom Line:" in conclusions, "delve," "foster," "leverage," "it's worth noting," "importantly," "Question? Answer." or "This isn't about X. It's about Y.", "genuinely" or hyphenated compound descriptions and adjectives. Do not use concluding summary statements such as "In short:..", "The simplest mental model is:...".
+
+State the intended action directly. Avoid adding what you won't do, what will remain unchanged, or how you'll separate or categorize results. Do not use contrastive framing such as "X, not Y" or "X—not Y" that introduces an unprompted alternative that the user didn't ask about. Avoid invented compound labels like "exact-head checks" and "editorial-row layouts", vague qualifiers, and canned transitions; use plain verbs and prepositions to state the actual relationship directly.
+```
+
+### Subagent delegation
+
+GPT-6 Astra is trained to be able to divide and delegate work to subagents that work in parallel. If you are implementing a multi-agent system in your harness, use the following prompt to tune how much GPT-6 Astra should delegate work:
+
+```text
+If at any point you can parallelize work by delegating tasks to another agent (no matter if you are the root or subagent), you should do so using collaboration tools if it could save time or improve quality.
+```
+
+Messages between agents may contain grammar or spacing errors. Use this prompt to make inter-agent messages easier to read:
+
+```text
+Messages that you send to other agents and your final answer may be read by a human, so ensure they are legible. Always put proper spaces between words and/or numbers.
+```
+
+The model tends to respond well to prompting for how and when it should delegate work to subagents, so tune this behavior to fit with your harness and multi-agent implementation.
+
+### Testing and verification
+
+For coding tasks, calibrate how much testing and verification a change requires. This can help avoid unnecessary tests or repeated checks for small changes.
+
+```text
+Do not write tests for reversible, low-impact changes that mirror the implementation. If you do choose to verify your work with tests, make sure that the tests are meaningful and necessary to verify implementation.
+
+Run tests appropriate to the change and complete required checks. Once those pass, broaden or repeat testing only when new changes, failures, or unresolved concerns justify it; otherwise, continue toward completing the task.
+```
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.md b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.md
new file mode 100644
index 0000000000000000000000000000000000000000..c367ee4d52ee0df60428ec6bb8208e3fd550aaa4
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrade-guide.md
@@ -0,0 +1,22 @@
+# Model upgrade guidance
+
+Use this file only as a bundled routing fallback when the live migration guide cannot be fetched.
+
+For latest, current, default, or unspecified-model upgrades:
+
+1. Run `scripts/resolve-latest-model-info`.
+2. Fetch the returned `migrationGuideUrl` and `promptingGuideUrl` exactly.
+3. Treat the live guides as canonical.
+4. If remote retrieval fails, disclose that bundled fallback guidance is being used.
+
+For an explicit GPT-6 Astra migration:
+
+1. Preserve the user's explicit target; do not run the latest-model resolver.
+2. Fetch the live GPT-6 model guidance:
+
+   https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md
+
+3. Read `references/upgrading-to-gpt-6-astra.md` for skill-specific migration judgment.
+4. Read `references/prompting-guide.md` only when prompt changes are needed.
+
+For another explicit model target, preserve that target and fetch its current official guidance. Do not reuse GPT-6-specific defaults, API shapes, or compatibility rules for a different model.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-6-astra.md b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-6-astra.md
new file mode 100644
index 0000000000000000000000000000000000000000..49d138ee291f508b6ca251988f6c846fc2f86355
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/references/upgrading-to-gpt-6-astra.md
@@ -0,0 +1,221 @@
+# Upgrading to GPT-6 Astra
+
+Use this guide when the user asks to migrate an existing OpenAI API integration, repository, prompt stack, agent, model router, or model picker to GPT-6 Astra.
+
+The default explicit target is `gpt-6-astra`. Verify the `gpt-6` family alias's currently documented routing and availability before using it. Do not treat every old model usage as an Astra candidate: retain Terra for balanced work and Luna as the primary faster or cheaper model.
+
+Before changing code, retrieve the current live GPT-6 model guidance using already-callable official documentation search and fetch, or immediately use official-domain web search and fetch:
+
+https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md
+
+For prompt changes, also read only the `## Prompting best practices` section from:
+
+https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices
+
+Treat live docs as canonical for current model IDs, parameters, limits, pricing, and feature availability. The skill-specific workflow below covers repository inspection, scope preservation, and validation. The fallback after it includes all non-prompting guidance, including access notices, examples, caveats, and `## Migration quickstart`; the full prompting section is in `references/prompting-guide.md`. When refreshing, preserve all guide content unless it is specific to the website rather than useful to the skill, and record any omission. Remove website metadata and component markup while retaining their readable content. Resolve site-relative links against `https://developers.openai.com` and section-only links against the canonical model-guide URL above.
+
+## Core principle
+
+Do not perform a blind model-string replacement.
+
+First preserve the behavior, latency class, cost class, reasoning level, endpoint contract, tool semantics, cache behavior, and output contract of each usage site. Then make the smallest safe migration. Adopt new GPT-6 capabilities only when they solve a measured problem or the user explicitly asks for them.
+
+A model upgrade alone does not authorize adding reasoning fields, changing request schemas, or rewriting tests. Set a supported reasoning effort explicitly to preserve the source model's effective behavior; verify omitted defaults rather than guessing.
+
+## Migration posture
+
+Classify every usage site before editing:
+
+1. `simple Astra migration`
+   - One flagship model usage.
+   - Same endpoint and request shape can remain.
+   - Reasoning effort is explicit or its old effective value is known.
+   - No cache, vision, file, tool, or parser behavior needs implementation changes.
+2. `tier-aware family migration`
+   - The repository exposes multiple model roles, model choices, fallbacks, routers, pricing data, or capability metadata.
+   - Map each role to Astra, Terra, or Luna instead of replacing everything with Astra.
+3. `compatibility migration`
+   - The safe move requires parameter, endpoint, cache, state, tool-loop, or multimodal-detail changes.
+   - Make these changes only when implementation work is inside the user's requested scope. Otherwise report the exact blocker and smallest follow-up.
+4. `prompt migration`
+   - The API shape can remain, but representative traces show a prompt-specific regression.
+   - Make a surgical prompt edit tied to that failure; do not rewrite a working prompt stack wholesale.
+   - When the task is to update prompting guidance, edit the directly tied prompt surface only. Do not modify runtime request code, model schemas, or tests unless the prompt change requires it.
+5. `optional feature adoption`
+   - Pro mode, persisted reasoning, explicit caching, Programmatic Tool Calling, or multi-agent behavior is being added deliberately.
+   - Keep this separate from the baseline migration so its effect can be measured.
+6. `leave unchanged`
+   - Historical examples, documentation about old models, snapshots, fixtures, eval baselines, comparison code, intentionally pinned fallbacks, unsupported providers, or ambiguous usages.
+
+When intent is unclear, prefer leaving a usage unchanged and list it for confirmation over silently changing its role.
+
+## Inventory before editing
+
+Search for more than literal model IDs. Inventory:
+
+- model strings, aliases, environment variables, CLI flags, config defaults, and deployment settings;
+- SDK calls to Responses, Chat Completions, Batch, or provider adapters;
+- reasoning settings, token budgets, sampling settings, and latency timeouts;
+- function tools, hosted tools, structured outputs, response parsers, and replay logic;
+- system, developer, user, and tool-description prompts tied to each usage;
+- routers, fallbacks, model allowlists, enums, regexes, validation schemas, and capability maps;
+- model picker UI, display labels, descriptions, context limits, pricing metadata, and provider catalogs;
+- prompt-cache keys, retention options, stable-prefix construction, and cache metrics;
+- image, PDF, file, OCR, and computer-use inputs;
+- tests, fixtures, snapshots, evals, analytics labels, billing tables, and docs.
+
+When changing a default model, search every active default surface: runtime config, environment/config files, setup docs, tests, CLI defaults, and deployment examples. Update them together.
+
+For each usage site, record:
+
+- source model and why it appears to be used;
+- endpoint and SDK/client surface;
+- prompt surface;
+- effective reasoning effort, including defaults;
+- latency, cost, context, and quality role;
+- tools, structured outputs, caching, state replay, and multimodal inputs;
+- downstream parsers or user-visible contracts;
+- migration class and validation plan.
+
+## Choose the target model by role
+
+Use this as a starting map, then validate against the repository's workload:
+
+| Existing role | Starting target | Reason |
+| --- | --- | --- |
+| GPT-5.6 Sol or an earlier flagship | `gpt-6-astra` | Astra is the flagship-equivalent tier. |
+| Balanced quality, latency, and cost | `gpt-5.6-terra` | Terra is the balanced option. |
+| Faster or cheaper work, classification, extraction, routing, high-volume, or strict-latency route | `gpt-5.6-luna` | Luna is the primary speed and cost option. |
+| GPT-4.1 or GPT-4o latency-sensitive flow | Start with Luna; evaluate Terra or Astra if quality requires it | A flagship replacement can change latency and cost materially. |
+| Reasoning-heavy or hardest quality-first flow | Start with Astra at the old effective effort | Preserve the reasoning contract before tuning. |
+| Router, fallback, or model picker | Add the family by role | Do not collapse a multi-model design into Astra. |
+| Third-party or provider-specific model | Leave unchanged unless the user explicitly requests provider migration | Model-name similarity is not a safe mapping. |
+
+Important limits to check in live docs:
+
+- Each model's context window and maximum output.
+- Long-context pricing thresholds for each route.
+- Token pricing for GPT-6.
+
+Do not invent prices, limits, or capability flags. Fetch them from current docs before updating a registry or UI.
+
+For model pickers and registries, preserve existing model entries by default. Add GPT-6 Astra and retain the existing Terra and Luna options unless the user explicitly asks to replace or remove them. Do not invent pricing, context limits, capabilities, or metadata unless confirmed from canonical docs.
+
+If using the `gpt-6` alias, record the returned `response.model` during validation. Do not assume an alias and an explicit Astra slug appear identically in dashboards, rate-limit configuration, analytics, or billing metadata.
+
+## Structured outputs, parsers, and tool contracts
+
+Keep output contracts explicit:
+
+- preserve JSON schemas, required fields, enums, refusal handling, and parser expectations;
+- preserve tool names, parameter schemas, call IDs, and retry behavior;
+- keep citations, evidence fields, or native artifacts when downstream consumers require them;
+- validate that the final answer still satisfies the contract, not merely that a tool call succeeded.
+
+Do not fix a failing migration by weakening a schema, deleting required behavior, removing routes, dropping tools, or changing business logic unless the user explicitly asked for that product change.
+
+## Prompt migration judgment
+
+After the model and API baseline is working, run representative traces before editing prompts. Change prompts only for measured failures. Read `references/prompting-guide.md` for the exact canonical prompting section when prompt changes are needed.
+
+## Upgrade workflow
+
+1. Fetch current live GPT-6 docs. Fetch the Prompting Best Practices section only when prompt changes are needed.
+2. Inventory every usage site and its adjacent prompt, config, registry, parser, and test surfaces.
+3. Classify each usage by role and migration class.
+4. Choose Astra, Terra, or Luna by the existing workload's role.
+5. Preserve the old effective reasoning effort explicitly when supported; follow the canonical migration guidance for unsupported settings.
+6. Run the compatibility gates:
+   - endpoint and SDK support;
+   - Chat Completions plus function tools;
+   - cache topology and cache fields;
+   - context length and long-context cost;
+   - image, PDF, and file detail;
+   - structured outputs and parsers;
+   - Responses state replay and tool continuation;
+   - mixed-model routing and unsupported new fields.
+7. Apply the smallest safe model, config, registry, and prompt changes.
+8. Do not add optional Pro, persisted reasoning, PTC, explicit caching, async tools, or multi-agent behavior unless needed and measurable.
+9. Run existing tests and representative evals.
+10. Report changed, unchanged, blocked, and confirmation-needed sites separately.
+
+## Validation matrix
+
+Prefer a controlled comparison:
+
+1. old model + old prompt + old settings;
+2. GPT-6 target + same prompt + preserved effective reasoning;
+3. GPT-6 target + same prompt + one lower supported effort;
+4. GPT-6 target + the smallest prompt or API fix required by a measured failure;
+5. optional feature treatment, isolated from the baseline.
+
+Measure what matters for the workflow:
+
+- task success and user-visible quality;
+- structured-output validity and parser success;
+- tool choice, tool arguments, retries, loop count, and completion rate;
+- TTFT, end-to-end latency, timeout rate, and concurrency behavior;
+- input, output, reasoning, cached, and cache-write tokens;
+- total cost per successful task;
+- long-context, compaction, and replay behavior;
+- image/PDF token use and visual/OCR accuracy;
+- completeness, preserved behavior, citations, and validation evidence.
+
+For model routers and pickers, test at least one representative workload for each role. Verify that the cheapest or fastest tier is not accidentally used for quality-critical work and that Astra is not accidentally used for every workload.
+
+## Required final report
+
+Return:
+
+- `Current usage inventory`: each model site, endpoint, role, prompt surface, and old effective reasoning.
+- `Target mapping`: Astra, Terra, Luna, unchanged, or confirmation-needed, with the reason.
+- `Changes made`: model strings, reasoning settings, prompts, registries, metadata, tests, and API-shape changes.
+- `Compatibility checks`: Chat Completions/tools, caching, state replay, multimodal detail, context/cost, schemas, and mixed-model routing.
+- `Prompt changes`: each surgical edit and the failure mode it addresses.
+- `Validation`: commands, evals, traces, before/after measurements, and remaining gaps.
+- `Unchanged sites`: historical, pinned, ambiguous, or intentionally role-specific usages.
+- `Blockers and open questions`: exact issue, why it is unsafe to guess, and the smallest next step.
+
+Never say the migration is complete merely because model strings changed. It is complete only when the affected behavior and contracts have been validated or the remaining gaps are stated explicitly.
+
+## Introduction
+
+GPT-6 Astra is our most intelligent model yet, with state-of-the-art performance in computer use, browsing, software engineering, science, and professional work. It excels at carrying out multistep workflows across code, browsers, and professional software. In <a href="https://openai.com/index/gpt-6-astra/" target="_blank" rel="noopener noreferrer">several evaluations</a>, Astra achieves stronger results while using substantially fewer output tokens—delivering a lower estimated API cost per task than earlier models despite its higher per-token pricing.
+
+GPT-6 Astra is also our most aligned model yet. It excels at exercising care, respecting task boundaries, and communicating transparently. When instructions leave room for interpretation, it uses the context it has to fill in routine gaps and asks focused questions when the answer could change the outcome. It incorporates new requirements, changes course when asked, and answers side questions without losing track of the broader task.
+
+To build with Astra, set `model` to `gpt-6-astra` in a [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses) request.
+
+## What's new
+
+- **Async tool calling:** GPT-6 Astra can continue reasoning, call other tools, or answer independent parts of a request while your application runs a tool. Set `async: true` on a function or custom tool and return its result when ready using the original `call_id`. Your application still executes the tool and manages pending work. See [Async tool calling](https://developers.openai.com/api/docs/guides/async-tool-calling) for basic usage and a developer-defined wait-tool pattern.
+- **Mid-turn steering:** Send additional user instructions while GPT-6 Astra is working, such as a correction or a change in requirements. Over a WebSocket connection, the Responses API preserves completed work and includes the update in a continuation. See [Mid-turn steering](https://developers.openai.com/api/docs/guides/steering) for the event flow and tool-result handling.
+- **Change reasoning mid-conversation while preserving cache:** Add a `configuration_update` input item to increase reasoning effort for difficult work or reduce it for routine follow-ups without rewriting the original prompt prefix. The updated reasoning effort applies until another `configuration_update` input item overrides it. See [Change reasoning mid-conversation](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation) for examples and compatibility.
+- **Misalignment monitoring:** As part of our <a href="https://openai.com/index/path-to-astra/" target="_blank" rel="noopener noreferrer">strengthened safeguards</a> for GPT-6 Astra, our systems asynchronously monitor for misalignment and trigger alerts when necessary. See [Misalignment monitoring](https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring) for more information.
+- **Limitations:** GPT-6 Astra does not support the `none` reasoning effort. [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode) is unavailable for GPT-6 Astra with EU data residency.
+
+GPT-6 Astra also supports the existing API capabilities available with GPT-5.6, including [computer use](https://developers.openai.com/api/docs/guides/tools-computer-use), [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs), [streaming](https://developers.openai.com/api/docs/guides/streaming-responses), [Programmatic Tool Calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling), [multi-agent orchestration](https://developers.openai.com/api/docs/guides/responses-multi-agent), [prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching), [persisted reasoning](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-across-calls), [compaction](https://developers.openai.com/api/docs/guides/compaction), and [pro mode](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode).
+
+## Migration quickstart
+
+### Migrate with Codex
+
+Codex can apply the recommended changes in this guide with the <a href="https://github.com/openai/skills/tree/main/skills/.curated/openai-docs" target="_blank" rel="noopener noreferrer">OpenAI Docs skill</a>.
+
+```text
+$openai-docs migrate this project to GPT-6 Astra
+```
+
+To use this skill in other coding agents, download it from the <a href="https://github.com/openai/skills/tree/main/skills/.curated/openai-docs" target="_blank" rel="noopener noreferrer">OpenAI skills repository</a>.
+
+### Update API and model parameters
+
+Set `model` to `gpt-6-astra`, then check the following:
+
+- **Reasoning effort:** If you currently use `none` or `minimal`, start with `low` and compare results. Otherwise, preserve your current effective [reasoning effort](https://developers.openai.com/api/docs/guides/reasoning#reasoning-effort). Use `reasoning.effort` in Responses or `reasoning_effort` in Chat Completions.
+- **Tool calling:** Use the [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses#migrating-from-chat-completions). GPT-6 Astra supports Chat Completions, but tool calling requires Responses.
+- **Unsupported parameters:** Remove `temperature`, `top_p`, and `top_logprobs`. For Chat Completions, also remove `logprobs`. For Responses, remove `message.output_text.logprobs` from `include`.
+- **Fast mode:** For EU data residency, use Standard processing. GPT-6 Astra does not support `service_tier: "fast"` or `service_tier: "priority"` with EU data residency. Fast mode for GPT-6 Astra does not include a latency SLA. See [Fast mode compatibility](https://developers.openai.com/api/docs/guides/fast-mode#is-fast-mode-compatible-with-data-residency-zero-data-retention-and-a-baa).
+- **Changing reasoning effort:** If your application changes effort between responses, use `configuration_update` items in standard, single-agent requests. Keep request-level `reasoning.effort` unchanged to preserve the prompt prefix for caching. Check the [compatibility limits](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation) before adopting this feature.
+- **Prompt caching:** When migrating from GPT-5.5 or earlier, replace `prompt_cache_retention` with `prompt_cache_options.ttl` set to `"30m"`. Review the [prompt caching changes](https://developers.openai.com/api/docs/guides/prompt-caching#summary-of-model-differences), including cache boundaries and cache-write billing.
+- **Unnecessary approval pauses:** If you run into issues where the model keeps asking for approval before proceeding, use the [initiative and follow-through guidance](https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#initiative-and-follow-through) to prompt for more autonomous execution. See the rest of [Prompting best practices](https://developers.openai.com/api/docs/guides/latest-model/gpt-6-astra.md#prompting-best-practices) for guidance on instruction following, writing style, subagent delegation, and testing.
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/scripts/fetch-codex-manual.mjs b/codex-rs/skills/src/assets/samples/openai-docs/scripts/fetch-codex-manual.mjs
new file mode 100644
index 0000000000000000000000000000000000000000..b2605520dc54aa3b71769e90887b9fdf06c97da4
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/scripts/fetch-codex-manual.mjs
@@ -0,0 +1,598 @@
+#!/usr/bin/env node
+import {
+  access,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { inspect, promisify } from "node:util";
+
+const DEFAULT_MANUAL_URL = "https://developers.openai.com/codex/codex-manual.md";
+const DEFAULT_CACHE_DIR_NAME = "openai-docs-cache";
+const CACHE_FILE_NAME = "codex-manual.md";
+const OUTLINE_FILE_NAME = "codex-manual.outline.md";
+const HASH_HEADER = "x-content-sha256";
+const USER_AGENT = "codex-openai-docs";
+const execFileAsync = promisify(execFile);
+
+class ManualFetchError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ManualFetchError";
+  }
+}
+
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+
+const withTimeout = async (promiseFactory, timeoutMs) => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await promiseFactory(controller.signal);
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
+const proxyConfigured = () =>
+  process.env.HTTP_PROXY ||
+  process.env.HTTPS_PROXY ||
+  process.env.http_proxy ||
+  process.env.https_proxy;
+
+const responseHeaders = (headers) => ({
+  get(name) {
+    return headers.get(name.toLowerCase()) ?? null;
+  },
+});
+
+const makeResponse = ({ body, headers, status }) => ({
+  headers: responseHeaders(headers),
+  ok: status >= 200 && status < 300,
+  status,
+  async text() {
+    return body;
+  },
+});
+
+const parseCurlHeaders = (rawHeaders) => {
+  const normalized = rawHeaders.replace(/\r\n/g, "\n").trim();
+  const blocks = normalized.split(/\n\n+/).filter(Boolean);
+  const headerBlock = [...blocks]
+    .reverse()
+    .find((block) => block.startsWith("HTTP/"));
+
+  if (!headerBlock) {
+    throw new ManualFetchError("curl did not return HTTP response headers.");
+  }
+
+  const [statusLine, ...lines] = headerBlock.split("\n");
+  const statusMatch = /^HTTP\/\S+\s+(\d{3})/.exec(statusLine);
+  if (!statusMatch) {
+    throw new ManualFetchError(
+      `Could not parse HTTP status from curl response: ${statusLine}`
+    );
+  }
+
+  const headers = new Map();
+  lines.forEach((line) => {
+    const separator = line.indexOf(":");
+    if (separator === -1) return;
+    const name = line.slice(0, separator).trim().toLowerCase();
+    const value = line.slice(separator + 1).trim();
+    headers.set(name, value);
+  });
+
+  return {
+    headers,
+    status: Number(statusMatch[1]),
+  };
+};
+
+const tempFilePath = (cacheDir, suffix) =>
+  path.join(
+    cacheDir,
+    `.fetch-codex-manual-${process.pid}-${Date.now()}-${Math.random()
+      .toString(16)
+      .slice(2)}${suffix}`
+  );
+
+const requestManualWithCurl = async (url, { cacheDir, method, timeoutMs }) => {
+  const headerPath = tempFilePath(cacheDir, ".headers");
+  const bodyPath = tempFilePath(cacheDir, ".body");
+  const curlNames =
+    process.platform === "win32" ? ["curl.exe", "curl"] : ["curl"];
+  const args = [
+    "--silent",
+    "--show-error",
+    "--location",
+    "--dump-header",
+    headerPath,
+    "--output",
+    bodyPath,
+    "--user-agent",
+    USER_AGENT,
+    "--max-time",
+    String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+  ];
+
+  if (method === "HEAD") {
+    args.push("--head");
+  } else {
+    args.push("--request", method);
+  }
+  args.push(url);
+
+  let lastError;
+  for (const curlName of curlNames) {
+    try {
+      await execFileAsync(curlName, args, { windowsHide: true });
+      const [rawHeaders, body] = await Promise.all([
+        readFile(headerPath, "utf8"),
+        readFile(bodyPath, "utf8"),
+      ]);
+      const { headers, status } = parseCurlHeaders(rawHeaders);
+      return makeResponse({ body, headers, status });
+    } catch (error) {
+      lastError = error;
+      if (error?.code !== "ENOENT") break;
+    } finally {
+      await Promise.all([
+        rm(headerPath, { force: true }),
+        rm(bodyPath, { force: true }),
+      ]);
+    }
+  }
+
+  if (lastError?.code === "ENOENT") {
+    throw new ManualFetchError("curl is unavailable in this environment.", {
+      cause: lastError,
+    });
+  }
+  throw new ManualFetchError(`${method} ${url} could not be fetched.`, {
+    cause: lastError,
+  });
+};
+
+const requestManualWithFetch = async (url, { method, timeoutMs }) => {
+  if (typeof fetch !== "function") {
+    throw new ManualFetchError(
+      "Native fetch is unavailable in this Node runtime."
+    );
+  }
+
+  return withTimeout(
+    (signal) =>
+      fetch(url, {
+        method,
+        headers: { "User-Agent": USER_AGENT },
+        signal,
+      }),
+    timeoutMs
+  );
+};
+
+const requestManual = async (url, { cacheDir, method, timeoutMs }) => {
+  const preferCurl = Boolean(proxyConfigured()) || typeof fetch !== "function";
+  const transports = preferCurl
+    ? [
+        () => requestManualWithCurl(url, { cacheDir, method, timeoutMs }),
+        () => requestManualWithFetch(url, { method, timeoutMs }),
+      ]
+    : [
+        () => requestManualWithFetch(url, { method, timeoutMs }),
+        () => requestManualWithCurl(url, { cacheDir, method, timeoutMs }),
+      ];
+
+  let lastError;
+  for (const transport of transports) {
+    try {
+      const response = await transport();
+      if (!response.ok) {
+        throw new ManualFetchError(
+          `${method} ${url} failed with HTTP ${response.status}.`
+        );
+      }
+      return response;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw new ManualFetchError(`${method} ${url} could not be fetched.`, {
+    cause: lastError,
+  });
+};
+
+const readHeaderSha = (response) => {
+  const value = response.headers.get(HASH_HEADER);
+  if (!value || !/^[a-f0-9]{64}$/i.test(value)) {
+    throw new ManualFetchError(`Manual response is missing ${HASH_HEADER}.`);
+  }
+  return value.toLowerCase();
+};
+
+const nearestExistingParent = async (target) => {
+  let current = target;
+  while (true) {
+    try {
+      const info = await stat(current);
+      return info.isDirectory() ? current : null;
+    } catch (error) {
+      if (error?.code !== "ENOENT") return null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+};
+
+const usableCacheDir = async (cacheDir) => {
+  if (!cacheDir) return null;
+  const resolved = path.resolve(cacheDir);
+
+  try {
+    const info = await stat(resolved);
+    if (!info.isDirectory()) return null;
+  } catch (error) {
+    if (error?.code !== "ENOENT") return null;
+  }
+
+  const parent = await nearestExistingParent(resolved);
+  if (!parent) return null;
+
+  try {
+    await access(parent, fsConstants.W_OK | fsConstants.X_OK);
+  } catch {
+    return null;
+  }
+
+  return resolved;
+};
+
+const defaultCacheDirCandidates = () => {
+  const candidates = [];
+  const seen = new Set();
+  const pushCandidate = (candidate) => {
+    if (!candidate || seen.has(candidate)) return;
+    seen.add(candidate);
+    candidates.push(candidate);
+  };
+
+  [process.env.TMPDIR, process.env.TEMP, process.env.TMP].forEach((baseDir) => {
+    if (baseDir) {
+      pushCandidate(path.join(baseDir, DEFAULT_CACHE_DIR_NAME));
+    }
+  });
+
+  if (process.platform !== "win32") {
+    pushCandidate(`/private/tmp/${DEFAULT_CACHE_DIR_NAME}`);
+    pushCandidate(`/tmp/${DEFAULT_CACHE_DIR_NAME}`);
+  }
+
+  return candidates;
+};
+
+const resolveCacheDir = async (cacheDir) => {
+  if (cacheDir) {
+    return usableCacheDir(cacheDir);
+  }
+
+  for (const candidate of defaultCacheDirCandidates()) {
+    const usable = await usableCacheDir(candidate);
+    if (usable) return usable;
+  }
+
+  return null;
+};
+
+const cacheFilePath = (cacheDir) => path.join(cacheDir, CACHE_FILE_NAME);
+
+const outlineFilePath = (cacheDir) => path.join(cacheDir, OUTLINE_FILE_NAME);
+
+const manualLines = (manual) => {
+  const lines = manual.replace(/\r\n/g, "\n").split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines;
+};
+
+const sectionTitle = (rawTitle) =>
+  rawTitle.replace(/\s+#+\s*$/, "").replace(/\s+/g, " ").trim();
+
+const buildOutline = (manual) => {
+  const lines = manualLines(manual);
+  const headings = [];
+  let inFence = false;
+
+  lines.forEach((line, index) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      return;
+    }
+    if (inFence) return;
+
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (!match) return;
+
+    const level = match[1].length;
+    if (level < 2 || level > 3) return;
+
+    headings.push({
+      level,
+      title: sectionTitle(match[2]),
+      startLine: index + 1,
+      endLine: lines.length,
+    });
+  });
+
+  for (let index = 0; index < headings.length; index += 1) {
+    const heading = headings[index];
+    const nextPeer = headings
+      .slice(index + 1)
+      .find((candidate) => candidate.level <= heading.level);
+    if (nextPeer) {
+      heading.endLine = nextPeer.startLine - 1;
+    }
+  }
+
+  if (headings.length === 0) {
+    return {
+      headingCount: 0,
+      lineCount: lines.length,
+      text: "No markdown headings found.",
+    };
+  }
+
+  const minLevel = Math.min(...headings.map((heading) => heading.level));
+  return {
+    headingCount: headings.length,
+    lineCount: lines.length,
+    text: headings
+      .map((heading) => {
+        const indent = "  ".repeat(heading.level - minLevel);
+        return `${indent}- ${heading.title} (lines ${heading.startLine}-${heading.endLine})`;
+      })
+      .join("\n"),
+  };
+};
+
+const outlineMarkdown = (outline) => `# Codex Manual Outline\n\n${outline.text}\n`;
+
+const manualStatusLine = (status) =>
+  status.cacheStatus === "hit"
+    ? "Manual status: local manual was already current."
+    : "Manual status: local manual was updated.";
+
+const formatResult = ({ status, outlineText }) =>
+  [
+    `Manual path: ${status.manualPath}`,
+    `Outline path: ${status.outlinePath}`,
+    manualStatusLine(status),
+    "",
+    outlineText,
+  ].join("\n");
+
+const readCachedManual = async (cacheDir, expectedSha256) => {
+  try {
+    const manual = await readFile(cacheFilePath(cacheDir), "utf8");
+    return sha256(manual) === expectedSha256 ? manual : null;
+  } catch {
+    return null;
+  }
+};
+
+const writeCachedManual = async (cacheDir, manual) => {
+  await mkdir(cacheDir, { recursive: true });
+  const tmpPath = tempFilePath(cacheDir, `.${CACHE_FILE_NAME}.tmp`);
+  await writeFile(tmpPath, manual, "utf8");
+  await rename(tmpPath, cacheFilePath(cacheDir));
+};
+
+const writeOutline = async (cacheDir, outlineText) => {
+  await mkdir(cacheDir, { recursive: true });
+  const tmpPath = tempFilePath(cacheDir, `.${OUTLINE_FILE_NAME}.tmp`);
+  await writeFile(tmpPath, outlineText, "utf8");
+  await rename(tmpPath, outlineFilePath(cacheDir));
+};
+
+const fetchCodexManual = async ({
+  manualUrl = DEFAULT_MANUAL_URL,
+  cacheDir,
+  timeoutMs = 30000,
+} = {}) => {
+  const resolvedCacheDir = await resolveCacheDir(cacheDir);
+  if (!resolvedCacheDir) {
+    throw new ManualFetchError(
+      "Manual cache directory is unavailable; pass --cache-dir to override or use OpenAI Docs MCP fallback."
+    );
+  }
+  await mkdir(resolvedCacheDir, { recursive: true });
+
+  const headResponse = await requestManual(manualUrl, {
+    cacheDir: resolvedCacheDir,
+    method: "HEAD",
+    timeoutMs,
+  });
+  const expectedSha256 = readHeaderSha(headResponse);
+  const manualPath = cacheFilePath(resolvedCacheDir);
+  const outlinePath = outlineFilePath(resolvedCacheDir);
+  const checkedAt = new Date().toISOString();
+
+  const cachedManual = await readCachedManual(resolvedCacheDir, expectedSha256);
+  if (cachedManual !== null) {
+    const outline = buildOutline(cachedManual);
+    const outlineText = outlineMarkdown(outline);
+    await writeOutline(resolvedCacheDir, outlineText);
+
+    return {
+      outlineText,
+      status: {
+        manualUrl,
+        headerSha256: expectedSha256,
+        fetchedManualSha256: expectedSha256,
+        manualHashMatches: true,
+        cacheStatus: "hit",
+        cacheDir: resolvedCacheDir,
+        manualPath,
+        outlinePath,
+        checkedAt,
+        lineCount: outline.lineCount,
+        headingCount: outline.headingCount,
+      },
+    };
+  }
+
+  const getResponse = await requestManual(manualUrl, {
+    cacheDir: resolvedCacheDir,
+    method: "GET",
+    timeoutMs,
+  });
+  const getHeaderSha256 = readHeaderSha(getResponse);
+  if (getHeaderSha256 !== expectedSha256) {
+    throw new ManualFetchError(
+      `${HASH_HEADER} changed between HEAD and GET for ${manualUrl}.`
+    );
+  }
+
+  const manualText = await getResponse.text();
+  const actualSha256 = sha256(manualText);
+  const manualHashMatches = actualSha256 === expectedSha256;
+  if (!manualHashMatches) {
+    throw new ManualFetchError(
+      `${HASH_HEADER} did not match the fetched manual body for ${manualUrl}.`
+    );
+  }
+
+  await writeCachedManual(resolvedCacheDir, manualText);
+  const outline = buildOutline(manualText);
+  const outlineText = outlineMarkdown(outline);
+  await writeOutline(resolvedCacheDir, outlineText);
+
+  return {
+    outlineText,
+    status: {
+      manualUrl,
+      headerSha256: expectedSha256,
+      fetchedManualSha256: actualSha256,
+      manualHashMatches,
+      cacheStatus: "updated",
+      cacheDir: resolvedCacheDir,
+      manualPath,
+      outlinePath,
+      checkedAt,
+      lineCount: outline.lineCount,
+      headingCount: outline.headingCount,
+    },
+  };
+};
+
+const parseArgs = (argv) => {
+  const args = {
+    manualUrl: DEFAULT_MANUAL_URL,
+    cacheDir: undefined,
+    timeoutMs: 30000,
+    statusJson: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--manual-url") {
+      args.manualUrl = argv[++index];
+    } else if (arg === "--cache-dir") {
+      args.cacheDir = argv[++index];
+    } else if (arg === "--timeout-ms") {
+      args.timeoutMs = Number(argv[++index]);
+    } else if (arg === "--status-json") {
+      args.statusJson = true;
+    } else {
+      throw new ManualFetchError(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!args.manualUrl) {
+    throw new ManualFetchError("--manual-url cannot be empty.");
+  }
+  if (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0) {
+    throw new ManualFetchError("--timeout-ms must be a positive number.");
+  }
+
+  return args;
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const { outlineText, status } = await fetchCodexManual(args);
+
+  process.stdout.write(formatResult({ status, outlineText }));
+
+  if (args.statusJson) {
+    console.error(JSON.stringify(status));
+  }
+};
+
+const envProxyHint = () => {
+  if (proxyConfigured()) {
+    return "Hint: proxy env vars are present. This helper prefers `curl` in proxied sessions; if requests still fail, verify `curl` is installed and the proxy configuration is valid.";
+  }
+  if (typeof fetch !== "function") {
+    return "Hint: native fetch is unavailable in this Node runtime. Install `curl` or use a newer Node version to fetch the manual.";
+  }
+  if (process.platform === "win32") {
+    return "Hint: on Windows, pass a cache dir under `%TEMP%` or `%TMP%`.";
+  }
+  return null;
+};
+
+const formatErrorDetails = (error) => {
+  const details = inspect(error, {
+    breakLength: 120,
+    colors: false,
+    compact: false,
+    depth: 8,
+  });
+  if (!error?.cause) {
+    return details;
+  }
+
+  return `${details}\n\nCause:\n${inspect(error.cause, {
+    breakLength: 120,
+    colors: false,
+    compact: false,
+    depth: 8,
+  })}`;
+};
+
+const isCliEntrypoint = () => {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) {
+    return false;
+  }
+
+  return pathToFileURL(entrypoint).href === import.meta.url;
+};
+
+if (isCliEntrypoint()) {
+  main().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    const hint = envProxyHint();
+    if (hint) {
+      console.error(hint);
+    }
+    console.error("");
+    console.error("Details:");
+    console.error(formatErrorDetails(error));
+    process.exitCode = 1;
+  });
+}
+
+export { DEFAULT_MANUAL_URL, fetchCodexManual };
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/scripts/resolve-latest-model-info b/codex-rs/skills/src/assets/samples/openai-docs/scripts/resolve-latest-model-info
new file mode 100644
index 0000000000000000000000000000000000000000..7d00122a37c81a30a7d91d8d74126398975f6493
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/scripts/resolve-latest-model-info
@@ -0,0 +1,39 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+SCRIPT_PATH="$SCRIPT_DIR/resolve-latest-model-info.cjs"
+
+is_compatible_node() {
+  "$1" -e 'const major = Number(process.versions.node.split(".")[0]); process.exit(major >= 18 ? 0 : 1)' >/dev/null 2>&1
+}
+
+run_if_compatible() {
+  CANDIDATE=$1
+  shift
+  if [ -n "$CANDIDATE" ] && [ -x "$CANDIDATE" ] && is_compatible_node "$CANDIDATE"; then
+    exec "$CANDIDATE" "$SCRIPT_PATH" "$@"
+  fi
+}
+
+if [ -n "${NODE:-}" ]; then
+  run_if_compatible "$NODE" "$@"
+fi
+
+PATH_NODE=$(command -v node 2>/dev/null || true)
+if [ -n "$PATH_NODE" ]; then
+  run_if_compatible "$PATH_NODE" "$@"
+fi
+
+for CANDIDATE in \
+  "$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node" \
+  "$HOME/.cache/codex-runtimes/codex-primary-runtime/dependencies/bin/node" \
+  "/opt/homebrew/bin/node" \
+  "/usr/local/bin/node" \
+  "/usr/bin/node"
+do
+  run_if_compatible "$CANDIDATE" "$@"
+done
+
+echo "No usable Node.js 18+ runtime found for resolve-latest-model-info.cjs" >&2
+exit 127
diff --git a/codex-rs/skills/src/assets/samples/openai-docs/scripts/resolve-latest-model-info.cjs b/codex-rs/skills/src/assets/samples/openai-docs/scripts/resolve-latest-model-info.cjs
new file mode 100644
index 0000000000000000000000000000000000000000..498e19d256572dc5a6bf5575ed13de834f0a2787
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/openai-docs/scripts/resolve-latest-model-info.cjs
@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+// Keep this entrypoint CommonJS-safe when the skill is copied into a type=module repo.
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const DEFAULT_URL =
+  "https://developers.openai.com/api/docs/guides/latest-model.md";
+const DEFAULT_BASE_URL = "https://developers.openai.com";
+
+function parseArgs(argv) {
+  const args = {
+    source: process.env.LATEST_MODEL_URL || DEFAULT_URL,
+    baseUrl: process.env.LATEST_MODEL_BASE_URL || DEFAULT_BASE_URL,
+  };
+
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--source" || arg === "--url") {
+      args.source = argv[i + 1];
+      i += 1;
+    } else if (arg === "--base-url") {
+      args.baseUrl = argv[i + 1];
+      i += 1;
+    }
+  }
+
+  return args;
+}
+
+async function readSource(source) {
+  if (source.startsWith("file://")) {
+    return fs.readFile(new URL(source), "utf8");
+  }
+
+  if (!/^https?:\/\//.test(source)) {
+    return fs.readFile(path.resolve(source), "utf8");
+  }
+
+  let lastError;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    try {
+      const response = await fetch(source, {
+        headers: { accept: "text/markdown,text/plain,*/*" },
+      });
+
+      if (response.ok) {
+        return response.text();
+      }
+
+      lastError = new Error("failed to fetch " + source + ": " + response.status);
+      if (response.status < 500 && response.status !== 429) {
+        break;
+      }
+    } catch (error) {
+      lastError = error;
+    }
+
+    if (attempt < 3) {
+      await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+    }
+  }
+
+  throw lastError;
+}
+
+function parseIndentedInfo(lines, startIndex) {
+  const info = {};
+
+  for (let i = startIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      continue;
+    }
+
+    const match = line.match(/^ {2}([A-Za-z][A-Za-z0-9_-]*):\s*(.+?)\s*$/);
+    if (!match) {
+      break;
+    }
+
+    info[match[1]] = match[2].replace(/^["']|["']$/g, "");
+  }
+
+  return info;
+}
+
+function parseFlatInfo(block) {
+  const info = {};
+
+  for (const line of block.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z][A-Za-z0-9_-]*):\s*(.+?)\s*$/);
+    if (match) {
+      info[match[1]] = match[2].replace(/^["']|["']$/g, "");
+    }
+  }
+
+  return info;
+}
+
+function extractLatestModelInfo(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const latestModelInfoIndex = lines.findIndex((line) =>
+    /^latestModelInfo:\s*$/.test(line)
+  );
+
+  if (latestModelInfoIndex >= 0) {
+    return parseIndentedInfo(lines, latestModelInfoIndex);
+  }
+
+  const commentMatch = markdown.match(
+    /<!--\s*latestModelInfo\s*\n([\s\S]*?)\n\s*-->/m
+  );
+  if (commentMatch) {
+    return parseFlatInfo(commentMatch[1]);
+  }
+
+  return undefined;
+}
+
+function modelToSkillSlug(model) {
+  return model.trim().replace(/\./g, "p");
+}
+
+function absoluteUrl(baseUrl, value) {
+  return new URL(value, baseUrl).toString();
+}
+
+function normalizeInfo(info, baseUrl) {
+  const model = info?.model?.trim();
+  const migrationGuide = info?.migrationGuide?.trim();
+  const promptingGuide = info?.promptingGuide?.trim();
+
+  if (!model || !migrationGuide || !promptingGuide) {
+    throw new Error(
+      "latestModelInfo must include model, migrationGuide, and promptingGuide"
+    );
+  }
+
+  return {
+    model,
+    modelSlug: modelToSkillSlug(model),
+    migrationGuideUrl: absoluteUrl(baseUrl, migrationGuide),
+    promptingGuideUrl: absoluteUrl(baseUrl, promptingGuide),
+  };
+}
+
+async function main() {
+  const { source, baseUrl } = parseArgs(process.argv);
+  const markdown = await readSource(source);
+  const info = extractLatestModelInfo(markdown);
+
+  if (!info) {
+    throw new Error(`latestModelInfo block not found in ${source}`);
+  }
+
+  process.stdout.write(
+    `${JSON.stringify(normalizeInfo(info, baseUrl), null, 2)}\n`
+  );
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md b/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..a1a6504d67a66af480f922db12831f6e5faa16df
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md
@@ -0,0 +1,249 @@
+---
+name: plugin-creator
+description: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
+---
+
+# Plugin Creator
+
+## Quick Start
+
+1. Run the scaffold script:
+
+```bash
+# Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
+# The generated folder and plugin.json name are always the same.
+# Run from the skill root (the directory containing this `SKILL.md`).
+# By default creates in `~/plugins/<plugin-name>`.
+python3 scripts/create_basic_plugin.py <plugin-name>
+```
+
+2. Edit `<plugin-path>/.codex-plugin/plugin.json` when the request gives specific metadata.
+   The scaffold starts with valid defaults and must not contain `[TODO: ...]` placeholders.
+
+3. Generate or update the personal marketplace entry when the plugin should appear in Codex UI ordering:
+
+```bash
+# Personal marketplace entries default to `~/.agents/plugins/marketplace.json`.
+python3 scripts/create_basic_plugin.py my-plugin --with-marketplace
+```
+
+Only specify `--marketplace-name <name>` when the default `personal` marketplace name is already
+taken or installed and you need to seed a different new marketplace file:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --with-marketplace \
+  --marketplace-name team-local
+```
+
+Only use a repo/team marketplace when the user specifically asks for that destination:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --path <repo-root>/plugins \
+  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
+  --with-marketplace
+```
+
+When the user specifies a marketplace path, make sure that marketplace is actually installed before
+telling the user to reinstall from it. The default personal marketplace file at
+`~/.agents/plugins/marketplace.json` is discovered implicitly, but other marketplace paths are not.
+On Windows, use the equivalent path under the user profile.
+
+4. Generate/adjust optional companion folders as needed:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --path <parent-plugin-directory> \
+  --marketplace-path <marketplace-json-path> \
+  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace
+```
+
+`<parent-plugin-directory>` is the directory where the plugin folder `<plugin-name>` will be
+created (for example `~/plugins`).
+
+5. Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```
+
+For updates to an existing local plugin during development, keep the scaffold flow as-is and use the
+reference instead of hand-editing marketplace files:
+
+```bash
+python3 scripts/read_marketplace_name.py
+python3 scripts/update_plugin_cachebuster.py <plugin-path>
+```
+
+For a repo/team marketplace, pass `--marketplace-path <marketplace-json-path>` to the first command.
+Prefer the helper default cachebuster unless the user explicitly asks for a specific override.
+See `references/installing-and-updating.md` for the expected cachebuster and reinstall flow while iterating on an existing local plugin.
+
+## What this skill creates
+
+- Default marketplace-backed scaffolds use the personal marketplace file at
+  `~/.agents/plugins/marketplace.json`, with plugins generally being stored in
+  `~/plugins/<plugin-name>/`.
+- Creates plugin root at `/<parent-plugin-directory>/<plugin-name>/`.
+- Always creates `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`.
+- Fills the manifest with the validated schema shape that the ingestion path accepts.
+- Creates or updates `~/.agents/plugins/marketplace.json` when `--with-marketplace` is set.
+  - If the marketplace file does not exist yet, seed a personal marketplace root before adding the first plugin entry.
+- `<plugin-name>` is normalized using skill-creator naming rules:
+  - `My Plugin` → `my-plugin`
+  - `My--Plugin` → `my-plugin`
+  - underscores, spaces, and punctuation are converted to `-`
+  - result is lower-case hyphen-delimited with consecutive hyphens collapsed
+- Supports optional creation of:
+  - `skills/`
+  - `hooks/`
+  - `scripts/`
+  - `assets/`
+  - `.mcp.json`
+  - `.app.json`
+
+## Marketplace workflow
+
+- Personal-marketplace creation defaults to `~/.agents/plugins/marketplace.json`. Here,
+  "personal marketplace" means the marketplace whose file is at that path.
+- Repo/team marketplace creation is opt-in through both `--path` and `--marketplace-path`, only
+  when the user specifically requests it.
+- `--marketplace-name` is an exception path. Use it only when the default `personal` marketplace
+  name is already taken and you need to seed a different new marketplace file.
+- Do not use `--marketplace-name` to rename an existing marketplace file in place. If the file
+  already exists, its top-level `name` must already match.
+- If the user specifies a different marketplace path, treat that marketplace as needing explicit installation via `codex plugin marketplace add`.
+- Plugin names must match `[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*`.
+- Marketplace names must match `[A-Za-z0-9_-]+`.
+- For existing marketplaces, always validate names with `scripts/read_marketplace_name.py`; stop if
+  validation fails. With no argument it reads the default personal marketplace; with an explicit
+  path it works for repo/team marketplaces too. The scaffold validates new marketplaces itself.
+- Before updating existing plugins, validate both identifiers before changing files or constructing
+  install commands.
+- In either location, the generated source path remains `./plugins/<plugin-name>`.
+- Marketplace root metadata supports top-level `name` plus optional `interface.displayName`.
+- Treat plugin order in `plugins[]` as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
+- `displayName` belongs inside the marketplace `interface` object, not individual `plugins[]` entries.
+- Each generated marketplace entry must include all of:
+  - `policy.installation`
+  - `policy.authentication`
+  - `category`
+- Default new entries to:
+  - `policy.installation: "AVAILABLE"`
+  - `policy.authentication: "ON_INSTALL"`
+- Override defaults only when the user explicitly specifies another allowed value.
+- Allowed `policy.installation` values:
+  - `NOT_AVAILABLE`
+  - `AVAILABLE`
+  - `INSTALLED_BY_DEFAULT`
+- Allowed `policy.authentication` values:
+  - `ON_INSTALL`
+  - `ON_USE`
+- Treat `policy.products` as an override. Omit it unless the user explicitly requests product gating.
+- The generated plugin entry shape is:
+
+```json
+{
+  "name": "plugin-name",
+  "source": {
+    "source": "local",
+    "path": "./plugins/plugin-name"
+  },
+  "policy": {
+    "installation": "AVAILABLE",
+    "authentication": "ON_INSTALL"
+  },
+  "category": "Productivity"
+}
+```
+
+- Use `--force` only when intentionally replacing an existing marketplace entry for the same plugin name.
+- If the target marketplace file does not exist yet, create it with top-level `"name"`, an `"interface"` object containing `"displayName"`, and a `plugins` array, then add the new entry.
+
+- For a brand-new marketplace file, the root object should look like:
+
+```json
+{
+  "name": "personal",
+  "interface": {
+    "displayName": "Personal"
+  },
+  "plugins": [
+    {
+      "name": "plugin-name",
+      "source": {
+        "source": "local",
+        "path": "./plugins/plugin-name"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Required behavior
+
+- Outer folder name and `plugin.json` `"name"` are always the same normalized plugin name.
+- Do not remove required structure; keep `.codex-plugin/plugin.json` present.
+- Do not leave `[TODO: ...]` placeholders in plugin manifests.
+- Keep `apps` and `mcpServers` out of `plugin.json` unless their companion files are actually created.
+- Omit unsupported plugin manifest fields that validation rejects, including `hooks`.
+- If creating files inside an existing plugin path, use `--force` only when overwrite is intentional.
+- Preserve any existing marketplace `interface.displayName`.
+- When generating marketplace entries, always write `policy.installation`, `policy.authentication`, and `category` even if their values are defaults.
+- Add `policy.products` only when the user explicitly asks for that override.
+- Keep marketplace `source.path` relative to the selected marketplace root as `./plugins/<plugin-name>`.
+- Only use `--marketplace-name` when creating a new marketplace file whose name should not be
+  `personal` because that name is already taken or installed elsewhere.
+- If Codex would need approval to write the marketplace file, ask for that approval before
+  proceeding. If the user prefers to run the write themselves, provide the exact scaffold command
+  and then continue from validation or subsequent plugin edits instead of leaving the workflow
+  vague.
+- For updates to an existing local plugin during development, do not hand-edit marketplace config
+  or `marketplace.json`. Use the update flow documented in
+  `references/installing-and-updating.md` and `scripts/update_plugin_cachebuster.py`.
+- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace
+  flow. That command is for explicit non-default marketplace configuration, not for the standard
+  `~/.agents/plugins/marketplace.json` path.
+- If the user provided a non-default `--marketplace-path`, make sure that marketplace is installed
+  before giving reinstall instructions. Use `codex plugin marketplace add <path-to-marketplace-root>`
+  when that explicit marketplace has not been configured yet.
+- When the workflow created or updated a marketplace-backed plugin, end the final user-facing
+  response with a short Codex app handoff. Say `To view this in the Codex app:` and write
+  `View <normalized plugin name>` and `Share <normalized plugin name>` as Markdown links, not raw
+  URLs or code spans.
+- The View deeplink uses `codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>`.
+  The Share deeplink uses the same URL with `&mode=share`.
+- Replace the placeholders with the real normalized plugin name and absolute `marketplace.json`
+  path from the scaffolded plugin. URL-encode the path segment and query value when needed.
+- Do not add `pluginName` or `hostId` query parameters to these deeplinks. Codex derives both after
+  the user clicks the link.
+- Do not emit the `View <normalized plugin name>` or `Share <normalized plugin name>` links when no marketplace entry was
+  created or updated.
+
+## Reference to exact spec sample
+
+For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:
+
+- `references/plugin-json-spec.md`
+- `references/installing-and-updating.md` for update/reinstall guidance while
+  iterating on an existing local plugin, plus the new-thread pickup behavior after reinstall
+
+## Validation
+
+After editing `SKILL.md`, run:
+
+```bash
+python3 ../skill-creator/scripts/quick_validate.py .
+```
+
+Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/agents/openai.yaml b/codex-rs/skills/src/assets/samples/plugin-creator/agents/openai.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..19a9a6fc5b08354fad82817971937bb1ee06dbdf
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Plugin Creator"
+  short_description: "Scaffold plugins and marketplace entries"
+  default_prompt: "Use $plugin-creator to scaffold a valid plugin in the personal marketplace, then validate it before handing it back."
+  icon_small: "./assets/plugin-creator-small.svg"
+  icon_large: "./assets/plugin-creator.png"
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/assets/plugin-creator-small.svg b/codex-rs/skills/src/assets/samples/plugin-creator/assets/plugin-creator-small.svg
new file mode 100644
index 0000000000000000000000000000000000000000..c6e4f67c624a00705a662dbd0230b8c531180f56
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/assets/plugin-creator-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
+  <path fill="#0D0D0D" d="M12.03 4.113a3.612 3.612 0 0 1 5.108 5.108l-6.292 6.29c-.324.324-.56.561-.791.752l-.235.176c-.205.14-.422.261-.65.36l-.229.093a4.136 4.136 0 0 1-.586.16l-.764.134-2.394.4c-.142.024-.294.05-.423.06-.098.007-.232.01-.378-.026l-.149-.05a1.081 1.081 0 0 1-.521-.474l-.046-.093a1.104 1.104 0 0 1-.075-.527c.01-.129.035-.28.06-.422l.398-2.394c.1-.602.162-.987.295-1.35l.093-.23c.1-.228.22-.445.36-.65l.176-.235c.19-.232.428-.467.751-.79l6.292-6.292Zm-5.35 7.232c-.35.35-.534.535-.66.688l-.11.147a2.67 2.67 0 0 0-.24.433l-.062.154c-.08.22-.124.462-.232 1.112l-.398 2.394-.001.001h.003l2.393-.399.717-.126a2.63 2.63 0 0 0 .394-.105l.154-.063a2.65 2.65 0 0 0 .433-.24l.147-.11c.153-.126.339-.31.688-.66l4.988-4.988-3.227-3.226-4.987 4.988Zm9.517-6.291a2.281 2.281 0 0 0-3.225 0l-.364.362 3.226 3.227.363-.364c.89-.89.89-2.334 0-3.225ZM4.583 1.783a.3.3 0 0 1 .294.241c.117.585.347 1.092.707 1.48.357.385.859.668 1.549.783a.3.3 0 0 1 0 .592c-.69.115-1.192.398-1.549.783-.315.34-.53.77-.657 1.265l-.05.215a.3.3 0 0 1-.588 0c-.117-.585-.347-1.092-.707-1.48-.357-.384-.859-.668-1.549-.783a.3.3 0 0 1 0-.592c.69-.115 1.192-.398 1.549-.783.36-.388.59-.895.707-1.48l.015-.05a.3.3 0 0 1 .279-.19Z"/>
+</svg>
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/assets/plugin-creator.png b/codex-rs/skills/src/assets/samples/plugin-creator/assets/plugin-creator.png
new file mode 100644
index 0000000000000000000000000000000000000000..4f3d6d82fa78fbdce97af3c17f6a25c683aa3290
Binary files /dev/null and b/codex-rs/skills/src/assets/samples/plugin-creator/assets/plugin-creator.png differ
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/references/installing-and-updating.md b/codex-rs/skills/src/assets/samples/plugin-creator/references/installing-and-updating.md
new file mode 100644
index 0000000000000000000000000000000000000000..a2ff127af201a27f57fb6eb2df7961dcdcc4759f
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/references/installing-and-updating.md
@@ -0,0 +1,144 @@
+# Updating Existing Local Plugins
+
+Use this reference when a plugin already exists and the request is about updating the plugin during 
+local development.
+
+All scripts here are specified relative to the skill root. Update the path for running the scripts
+depending on your current working directory.
+
+## When To Use This Flow
+
+Use this flow when all of the following are true:
+
+- the plugin already exists locally
+- the marketplace entry already points at the plugin source you are editing
+- the user wants Codex to see the updated plugin without manually editing marketplace files
+
+If the user still needs the initial plugin entry or marketplace structure created, use the scaffold
+flow first and only then switch to this reinstall flow.
+
+## Update Loop
+
+1. Before changing the plugin, read the marketplace name from the personal marketplace file:
+
+```bash
+python3 scripts/read_marketplace_name.py
+```
+
+Here, "personal marketplace" means the marketplace whose file is at
+`~/.agents/plugins/marketplace.json`. On Windows, use the equivalent path under the user profile.
+The helper uses Python's home-directory resolution and prints the validated marketplace name to use
+when constructing the install command. If the helper fails, stop.
+
+To read the name from a different marketplace file, pass the path directly:
+
+```bash
+python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>
+```
+
+2. Update the plugin manifest to a single Codex cachebuster suffix:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py \
+  <plugin-path>
+```
+
+The helper validates the plugin name before changing the manifest. If validation fails, stop.
+Prefer the default helper behavior here. If you omit `--cachebuster`, the helper uses a UTC
+timestamp down to seconds, which is the recommended path for routine local iteration.
+
+Only use a manual cachebuster override when the user explicitly asks for one or when a workflow
+outside Codex depends on a specific token:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py \
+  <plugin-path> \
+  --cachebuster local-20260519-184516
+```
+
+3. Reinstall from that marketplace name:
+
+```bash
+codex plugin add <plugin-name>@<marketplace-name-from-marketplace-json>
+```
+
+The default personal marketplace is discovered implicitly from
+`~/.agents/plugins/marketplace.json`. You do not need `codex plugin marketplace add` for that
+path, and `codex plugin marketplace list` is not the right check for whether that default
+marketplace exists.
+
+4. If the plugin is not using the personal marketplace file, check which configured local
+   marketplace is actually surfacing that plugin:
+
+```bash
+codex plugin list
+```
+
+If the plugin is not in the personal marketplace file, confirm which marketplace entry points at
+the plugin source you are editing and make sure that marketplace is still local. If it is a
+different local marketplace, reinstall from that marketplace name instead of forcing the personal
+marketplace flow. If it is not local, stop and help the user resolve the mismatch before
+continuing.
+
+5. If the plugin lives in a different confirmed local marketplace, substitute that marketplace
+   name:
+
+```bash
+codex plugin add <plugin-name>@<local-marketplace>
+```
+
+6. Prompt the user to use a new thread to try the updated plugin, so that Codex picks up new skills
+   and tools.
+
+## Cachebuster Policy
+
+- Preserve the existing version prefix and replace only the suffix.
+- Treat the preserved prefix as everything before `+`.
+- Use the format:
+
+```text
+<base-version>+codex.<cachebuster>
+```
+
+Examples:
+
+- `0.1.0` → `0.1.0+codex.local-20260519-184516`
+- `0.1.0+codex.old-token` → `0.1.0+codex.local-20260519-184516`
+- `1.2.3-beta.1+codex.prev` → `1.2.3-beta.1+codex.local-20260519-184516`
+- `dev-build+other-tag` → `dev-build+codex.local-20260519-184516`
+
+Replace the existing Codex cachebuster instead of appending another one. Do not keep incrementing
+numeric version components just to trigger reinstall behavior.
+
+## Marketplace Rules
+
+- Marketplace manipulation should happen through commands, not by hand-editing `marketplace.json`
+  or `config.toml` during this update/reinstall flow.
+- Prefer the personal marketplace file for the default scaffolded flow.
+- Read the personal marketplace name with
+  `python3 scripts/read_marketplace_name.py` and use the printed value when constructing
+  `codex plugin add <plugin-name>@<marketplace-name>`.
+- For non-default marketplace files, use
+  `python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>` to read
+  the name before constructing reinstall commands.
+- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace
+  flow. That marketplace is discovered implicitly by Codex.
+- If the user specified a different marketplace path, make sure that marketplace is installed
+  before giving install or reinstall instructions. Non-default marketplace paths are not
+  discovered implicitly.
+- Use `codex plugin list` when the plugin lives in a different configured marketplace and you need
+  to confirm which marketplace is surfacing that plugin.
+- If a non-default local marketplace has not been configured yet, install it with
+  `codex plugin marketplace add <path-to-marketplace-root>` before telling the user to run
+  `codex plugin add <plugin-name>@<marketplace-name>`.
+- If the plugin is not in the personal marketplace file, confirm that the selected marketplace is
+  local before telling the user to reinstall from it.
+- If the selected marketplace is not local, stop and help the user resolve that mismatch rather
+  than pretending the normal local reinstall flow applies.
+- If the plugin source is not already the source referenced by the chosen marketplace entry, stop
+  and fix that first. This update flow does not rewrite marketplace entries.
+
+## After Reinstall
+
+After reinstalling, prompt the user to start a new thread for testing. That is the safe boundary for
+picking up the updated plugin and its MCP tools.
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md b/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md
new file mode 100644
index 0000000000000000000000000000000000000000..40d3ae6b5435c4372c38dcdeead4706eef42b4b2
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md
@@ -0,0 +1,218 @@
+# Plugin JSON sample spec
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.2.0",
+  "description": "Brief plugin description",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://github.com/author"
+  },
+  "homepage": "https://docs.example.com/plugin",
+  "repository": "https://github.com/author/plugin",
+  "license": "MIT",
+  "keywords": ["keyword1", "keyword2"],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Plugin Display Name",
+    "shortDescription": "Short description for subtitle",
+    "longDescription": "Long description for details page",
+    "developerName": "OpenAI",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://openai.com/",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Summarize my inbox and draft replies for me.",
+      "Find open bugs and turn them into Linear tickets.",
+      "Review today's meetings and flag scheduling gaps."
+    ],
+    "brandColor": "#3B82F6",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "logoDark": "./assets/logo-dark.png",
+    "screenshots": [
+      "./assets/screenshot1.png",
+      "./assets/screenshot2.png",
+      "./assets/screenshot3.png"
+    ]
+  }
+}
+```
+
+## Field guide
+
+### Top-level fields
+
+- `name` (`string`): Plugin identifier (kebab-case, no spaces). Required if `plugin.json` is provided and used as manifest name and component namespace.
+- `version` (`string`): Plugin semantic version.
+- `description` (`string`): Short purpose summary.
+- `author` (`object`): Publisher identity.
+  - `name` (`string`): Author or team name.
+  - `email` (`string`): Contact email.
+  - `url` (`string`): Author/team homepage or profile URL.
+- `homepage` (`string`): Documentation URL for plugin usage.
+- `repository` (`string`): Source code URL.
+- `license` (`string`): License identifier (for example `MIT`, `Apache-2.0`).
+- `keywords` (`array` of `string`): Search/discovery tags.
+- `skills` (`string`): Relative path to skill directories/files.
+- `hooks` (`string`): Hook config path.
+- `mcpServers` (`string` or `object`): MCP config path, or an object whose keys are MCP server names and whose values are MCP server config objects.
+- `apps` (`string`): App manifest path for plugin integrations.
+- `interface` (`object`): Interface/UX metadata block for plugin presentation.
+
+`mcpServers` may be declared as a companion file path:
+
+```json
+{
+  "mcpServers": "./.mcp.json"
+}
+```
+
+Or as an object directly in `plugin.json`:
+
+```json
+{
+  "mcpServers": {
+    "counter": {
+      "type": "http",
+      "url": "https://sample.example/counter/mcp"
+    }
+  }
+}
+```
+
+### `interface` fields
+
+- `displayName` (`string`): User-facing title shown for the plugin.
+- `shortDescription` (`string`): Brief subtitle used in compact views.
+- `longDescription` (`string`): Longer description used on details screens.
+- `developerName` (`string`): Human-readable publisher name.
+- `category` (`string`): Plugin category bucket.
+- `capabilities` (`array` of `string`): Capability list from implementation.
+- `websiteURL` (`string`): Public website for the plugin.
+- `privacyPolicyURL` (`string`): Privacy policy URL.
+- `termsOfServiceURL` (`string`): Terms of service URL.
+- `defaultPrompt` (`array` of `string`): Starter prompts shown in composer/UX context.
+  - Include at most 3 strings. Entries after the first 3 are ignored and will not be included.
+  - Each string is capped at 128 characters. Longer entries are truncated.
+  - Prefer short starter prompts around 50 characters so they scan well in the UI.
+- `brandColor` (`string`): Theme color for the plugin card.
+- `composerIcon` (`string`): Path to icon asset.
+- `logo` (`string`): Path to logo asset.
+- `logoDark` (`string`): Optional path to the logo asset used in dark mode.
+- `screenshots` (`array` of `string`): List of screenshot asset paths.
+  - Screenshot entries must be PNG filenames and stored under `./assets/`.
+  - Keep file paths relative to plugin root.
+
+### Path conventions and defaults
+
+- Path values should be relative and begin with `./`.
+- `skills`, `hooks`, and string-valued `mcpServers` are supplemented on top of default component discovery; they do not replace defaults.
+- Custom path values must follow the plugin root convention and naming/namespacing rules.
+- This repo’s scaffold writes `.codex-plugin/plugin.json`; treat that as the manifest location this skill generates.
+
+# Marketplace JSON sample spec
+
+`marketplace.json` depends on where the plugin should live. New plugin creation defaults to the
+personal marketplace unless the caller explicitly requests a repo-local destination:
+
+- Personal plugin: `~/.agents/plugins/marketplace.json`
+- Repo/team plugin: `<repo-root>/.agents/plugins/marketplace.json`
+
+```json
+{
+  "name": "openai-curated",
+  "interface": {
+    "displayName": "ChatGPT Official"
+  },
+  "plugins": [
+    {
+      "name": "linear",
+      "source": {
+        "source": "local",
+        "path": "./plugins/linear"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Marketplace field guide
+
+### Top-level fields
+
+- `name` (`string`): Marketplace identifier or catalog name.
+- `interface` (`object`, optional): Marketplace presentation metadata.
+- `plugins` (`array`): Ordered plugin entries. This order determines how Codex renders plugins.
+
+### `interface` fields
+
+- `displayName` (`string`, optional): User-facing marketplace title.
+
+### Plugin entry fields
+
+- `name` (`string`): Plugin identifier. Match the plugin folder name and `plugin.json` `name`.
+- `source` (`object`): Plugin source descriptor.
+  - `source` (`string`): Use `local` for this repo workflow.
+  - `path` (`string`): Relative plugin path based on the marketplace root.
+    - Personal plugin in `~/.agents/plugins/marketplace.json`: `./plugins/<plugin-name>`
+    - Repo/team plugin: `./plugins/<plugin-name>`
+  - The same relative path convention is used for both personal and repo/team marketplaces.
+    - Example: with `~/.agents/plugins/marketplace.json`, `./plugins/<plugin-name>` resolves to
+      `~/plugins/<plugin-name>`.
+- `policy` (`object`): Marketplace policy block. Always include it.
+  - `installation` (`string`): Availability policy.
+    - Allowed values: `NOT_AVAILABLE`, `AVAILABLE`, `INSTALLED_BY_DEFAULT`
+    - Default for new entries: `AVAILABLE`
+  - `authentication` (`string`): Authentication timing policy.
+    - Allowed values: `ON_INSTALL`, `ON_USE`
+    - Default for new entries: `ON_INSTALL`
+  - `products` (`array` of `string`, optional): Product override for this plugin entry. Omit it unless product gating is explicitly requested.
+- `category` (`string`): Display category bucket. Always include it.
+
+### Marketplace generation rules
+
+- `displayName` belongs under the top-level `interface` object, not individual plugin entries.
+- When creating a new marketplace file from scratch, seed `interface.displayName` alongside top-level `name`.
+- Always include `policy.installation`, `policy.authentication`, and `category` on every generated or updated plugin entry.
+- Treat `policy.products` as an override and omit it unless explicitly requested.
+- Append new entries unless the user explicitly requests reordering.
+- Replace an existing entry for the same plugin only when overwrite is intentional.
+- Default new plugin creation to the personal marketplace.
+- Use a repo/team marketplace only when the user specifically requests that destination.
+- Only override the marketplace `name` when the default `personal` name is already taken or
+  installed and you need to seed a different new marketplace file.
+- Choose marketplace location to match the selected destination:
+  - Personal plugin: `~/.agents/plugins/marketplace.json`
+  - Repo/team plugin: `<repo-root>/.agents/plugins/marketplace.json`
+
+### Plugin validation notes
+
+- The validator mirrors the workspace plugin ingestion schema so generated plugins follow the same
+  manifest contract from the start.
+- Plugin manifests must include real values for `name`, `version`, `description`,
+  `author.name`, and the required `interface` fields.
+- `version` must use strict semver.
+- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` must be absolute `https://` URLs when
+  present.
+- `composerIcon`, `logo`, `logoDark`, and `screenshots` must point to real files inside the plugin archive when
+  present.
+- `apps` should appear in `plugin.json` only when `.app.json` actually exists.
+- `mcpServers` may point to `.mcp.json` or contain the MCP server object directly in
+  `plugin.json`.
+- Validation rejects unsupported manifest fields such as `hooks`, so the scaffold keeps them out of
+  generated manifests.
+- Run `scripts/validate_plugin.py <plugin-path>` before handing back a generated plugin. It adds one
+  intentional preflight check that rejects leftover `[TODO: ...]` placeholders.
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/scripts/create_basic_plugin.py b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/create_basic_plugin.py
new file mode 100644
index 0000000000000000000000000000000000000000..40edaa86005e71d0e199fbff94ae425afc099939
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/create_basic_plugin.py
@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""Scaffold a plugin directory and optionally update marketplace.json."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from identifier_validation import validate_marketplace_name
+
+
+MAX_PLUGIN_NAME_LENGTH = 64
+DEFAULT_INSTALL_POLICY = "AVAILABLE"
+DEFAULT_AUTH_POLICY = "ON_INSTALL"
+DEFAULT_CATEGORY = "Productivity"
+DEFAULT_MARKETPLACE_NAME = "personal"
+VALID_INSTALL_POLICIES = {"NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"}
+VALID_AUTH_POLICIES = {"ON_INSTALL", "ON_USE"}
+DEFAULT_PLUGIN_PARENT = Path.home() / "plugins"
+DEFAULT_MARKETPLACE_PATH = Path.home() / ".agents" / "plugins" / "marketplace.json"
+
+
+def normalize_plugin_name(plugin_name: str) -> str:
+    """Normalize a plugin name to lowercase hyphen-case."""
+    normalized = plugin_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def validate_plugin_name(plugin_name: str) -> None:
+    if not plugin_name:
+        raise ValueError("Plugin name must include at least one letter or digit.")
+    if len(plugin_name) > MAX_PLUGIN_NAME_LENGTH:
+        raise ValueError(
+            f"Plugin name '{plugin_name}' is too long ({len(plugin_name)} characters). "
+            f"Maximum is {MAX_PLUGIN_NAME_LENGTH} characters."
+        )
+
+
+def display_name_from_plugin_name(plugin_name: str) -> str:
+    return " ".join(part.capitalize() for part in re.split(r"[-_]+", plugin_name))
+
+
+def build_plugin_json(
+    plugin_name: str, *, with_mcp: bool, with_apps: bool
+) -> dict[str, Any]:
+    display_name = display_name_from_plugin_name(plugin_name)
+    payload: dict[str, Any] = {
+        "name": plugin_name,
+        "version": "0.1.0",
+        "description": f"{display_name} plugin",
+        "author": {
+            "name": "Local developer",
+        },
+        "skills": "./skills/",
+        "interface": {
+            "displayName": display_name,
+            "shortDescription": f"Use {display_name} in Codex.",
+            "longDescription": f"{display_name} adds a local Codex plugin scaffold.",
+            "developerName": "Local developer",
+            "category": DEFAULT_CATEGORY,
+            "capabilities": [],
+            "defaultPrompt": f"Help me use {display_name}.",
+        },
+    }
+    if with_mcp:
+        payload["mcpServers"] = "./.mcp.json"
+    if with_apps:
+        payload["apps"] = "./.app.json"
+    return payload
+
+
+def build_marketplace_entry(
+    plugin_name: str,
+    install_policy: str,
+    auth_policy: str,
+    category: str,
+) -> dict[str, Any]:
+    return {
+        "name": plugin_name,
+        "source": {
+            "source": "local",
+            "path": f"./plugins/{plugin_name}",
+        },
+        "policy": {
+            "installation": install_policy,
+            "authentication": auth_policy,
+        },
+        "category": category,
+    }
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    with path.open() as handle:
+        return json.load(handle)
+
+
+def build_default_marketplace(marketplace_name: str) -> dict[str, Any]:
+    return {
+        "name": marketplace_name,
+        "interface": {
+            "displayName": display_name_from_plugin_name(marketplace_name),
+        },
+        "plugins": [],
+    }
+
+
+def validate_marketplace_interface(payload: dict[str, Any]) -> None:
+    interface = payload.get("interface")
+    if interface is not None and not isinstance(interface, dict):
+        raise ValueError("marketplace.json field 'interface' must be an object.")
+
+
+def load_validated_marketplace(
+    marketplace_path: Path,
+    marketplace_name: str | None,
+    plugin_name: str,
+    force: bool,
+) -> dict[str, Any]:
+    if marketplace_path.exists():
+        payload = load_json(marketplace_path)
+    else:
+        payload = build_default_marketplace(
+            marketplace_name or DEFAULT_MARKETPLACE_NAME
+        )
+
+    if not isinstance(payload, dict):
+        raise ValueError(f"{marketplace_path} must contain a JSON object.")
+
+    validate_marketplace_interface(payload)
+
+    existing_marketplace_name = payload.get("name")
+    if (
+        not isinstance(existing_marketplace_name, str)
+        or not existing_marketplace_name.strip()
+    ):
+        raise ValueError(f"{marketplace_path} must contain a non-empty string 'name'.")
+    validate_marketplace_name(existing_marketplace_name)
+
+    if marketplace_name is not None:
+        if existing_marketplace_name != marketplace_name:
+            raise ValueError(
+                f"{marketplace_path} already uses marketplace name "
+                f"'{existing_marketplace_name}'. Create a new marketplace file to use "
+                f"'{marketplace_name}' instead."
+            )
+
+    plugins = payload.setdefault("plugins", [])
+    if not isinstance(plugins, list):
+        raise ValueError(f"{marketplace_path} field 'plugins' must be an array.")
+    if not force and any(
+        isinstance(entry, dict) and entry.get("name") == plugin_name
+        for entry in plugins
+    ):
+        raise FileExistsError(
+            f"Marketplace entry '{plugin_name}' already exists in {marketplace_path}. "
+            "Use --force to overwrite that entry."
+        )
+
+    return payload
+
+
+def update_marketplace_json(
+    marketplace_path: Path,
+    marketplace_name: str | None,
+    plugin_name: str,
+    install_policy: str,
+    auth_policy: str,
+    category: str,
+    force: bool,
+) -> None:
+    payload = load_validated_marketplace(
+        marketplace_path, marketplace_name, plugin_name, force
+    )
+    plugins = payload["plugins"]
+
+    new_entry = build_marketplace_entry(
+        plugin_name, install_policy, auth_policy, category
+    )
+
+    for index, entry in enumerate(plugins):
+        if isinstance(entry, dict) and entry.get("name") == plugin_name:
+            plugins[index] = new_entry
+            break
+    else:
+        plugins.append(new_entry)
+
+    write_json(marketplace_path, payload, force=True)
+
+
+def write_json(path: Path, data: dict, force: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists. Use --force to overwrite.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as handle:
+        json.dump(data, handle, indent=2)
+        handle.write("\n")
+
+
+def create_stub_file(path: Path, payload: dict, force: bool) -> None:
+    if path.exists() and not force:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w") as handle:
+        json.dump(payload, handle, indent=2)
+        handle.write("\n")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create a plugin skeleton with a validation-ready plugin.json."
+    )
+    parser.add_argument("plugin_name")
+    parser.add_argument(
+        "--path",
+        default=str(DEFAULT_PLUGIN_PARENT),
+        help=(
+            "Parent directory for plugin creation (defaults to <home>/plugins). "
+            "Pass an explicit repo path only when a repo/team plugin is intended."
+        ),
+    )
+    parser.add_argument(
+        "--with-skills", action="store_true", help="Create skills/ directory"
+    )
+    parser.add_argument(
+        "--with-hooks", action="store_true", help="Create hooks/ directory"
+    )
+    parser.add_argument(
+        "--with-scripts", action="store_true", help="Create scripts/ directory"
+    )
+    parser.add_argument(
+        "--with-assets", action="store_true", help="Create assets/ directory"
+    )
+    parser.add_argument(
+        "--with-mcp", action="store_true", help="Create .mcp.json placeholder"
+    )
+    parser.add_argument(
+        "--with-apps", action="store_true", help="Create .app.json placeholder"
+    )
+    parser.add_argument(
+        "--with-marketplace",
+        action="store_true",
+        help=(
+            "Create or update <home>/.agents/plugins/marketplace.json by default. "
+            "Marketplace entries always point to ./plugins/<plugin-name> relative to the "
+            "marketplace root."
+        ),
+    )
+    parser.add_argument(
+        "--marketplace-path",
+        default=str(DEFAULT_MARKETPLACE_PATH),
+        help=(
+            "Path to marketplace.json (defaults to <home>/.agents/plugins/marketplace.json). "
+            "Pass a repo-rooted marketplace path only when a repo/team plugin is intended."
+        ),
+    )
+    parser.add_argument(
+        "--marketplace-name",
+        help=(
+            "Marketplace name to seed into a new marketplace.json. Use this only when the default "
+            "'personal' marketplace name is already taken and you need a different new marketplace."
+        ),
+    )
+    parser.add_argument(
+        "--install-policy",
+        default=DEFAULT_INSTALL_POLICY,
+        choices=sorted(VALID_INSTALL_POLICIES),
+        help="Marketplace policy.installation value",
+    )
+    parser.add_argument(
+        "--auth-policy",
+        default=DEFAULT_AUTH_POLICY,
+        choices=sorted(VALID_AUTH_POLICIES),
+        help="Marketplace policy.authentication value",
+    )
+    parser.add_argument(
+        "--category",
+        default=DEFAULT_CATEGORY,
+        help="Marketplace category value",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing files")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    raw_plugin_name = args.plugin_name
+    plugin_name = normalize_plugin_name(raw_plugin_name)
+    if plugin_name != raw_plugin_name:
+        print(
+            f"Note: Normalized plugin name from '{raw_plugin_name}' to '{plugin_name}'."
+        )
+    validate_plugin_name(plugin_name)
+    marketplace_name = None
+    if args.marketplace_name is not None:
+        marketplace_name = args.marketplace_name.strip()
+        validate_marketplace_name(marketplace_name)
+
+    if args.with_marketplace:
+        marketplace_path = Path(args.marketplace_path).expanduser().resolve()
+        load_validated_marketplace(
+            marketplace_path, marketplace_name, plugin_name, args.force
+        )
+
+    plugin_root = Path(args.path).expanduser().resolve() / plugin_name
+    plugin_root.mkdir(parents=True, exist_ok=True)
+
+    plugin_json_path = plugin_root / ".codex-plugin" / "plugin.json"
+    write_json(
+        plugin_json_path,
+        build_plugin_json(
+            plugin_name, with_mcp=args.with_mcp, with_apps=args.with_apps
+        ),
+        args.force,
+    )
+
+    optional_directories = {
+        "skills": args.with_skills,
+        "hooks": args.with_hooks,
+        "scripts": args.with_scripts,
+        "assets": args.with_assets,
+    }
+    for folder, enabled in optional_directories.items():
+        if enabled:
+            (plugin_root / folder).mkdir(parents=True, exist_ok=True)
+
+    if args.with_mcp:
+        create_stub_file(
+            plugin_root / ".mcp.json",
+            {"mcpServers": {}},
+            args.force,
+        )
+
+    if args.with_apps:
+        create_stub_file(
+            plugin_root / ".app.json",
+            {
+                "apps": {},
+            },
+            args.force,
+        )
+
+    if args.with_marketplace:
+        update_marketplace_json(
+            marketplace_path,
+            marketplace_name,
+            plugin_name,
+            args.install_policy,
+            args.auth_policy,
+            args.category,
+            args.force,
+        )
+
+    print(f"Created plugin scaffold: {plugin_root}")
+    print(f"plugin manifest: {plugin_json_path}")
+    if args.with_marketplace:
+        print(f"marketplace manifest: {marketplace_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/scripts/identifier_validation.py b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/identifier_validation.py
new file mode 100644
index 0000000000000000000000000000000000000000..41a1a2f1b503c165f5d4b93f7f0e99eb0b3add6e
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/identifier_validation.py
@@ -0,0 +1,20 @@
+"""Validate plugin and marketplace identifiers before using them in commands."""
+
+import re
+
+
+def validate_plugin_identifier(plugin_name: str) -> None:
+    if re.fullmatch(r"[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*", plugin_name) is None:
+        raise ValueError(
+            "Plugin name may only contain ASCII letters, digits, `.`, `_`, and `-`, "
+            "with dots separating non-empty name segments."
+        )
+
+
+def validate_marketplace_name(marketplace_name: str) -> None:
+    if not marketplace_name:
+        raise ValueError("Marketplace name must include at least one letter or digit.")
+    if re.fullmatch(r"[A-Za-z0-9_-]+", marketplace_name) is None:
+        raise ValueError(
+            "Marketplace name may only contain ASCII letters, digits, `_`, and `-`."
+        )
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/scripts/read_marketplace_name.py b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/read_marketplace_name.py
new file mode 100644
index 0000000000000000000000000000000000000000..249b564e38b1ecb9af0ed75c441fceebc1faeed9
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/read_marketplace_name.py
@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Print the top-level marketplace name from any marketplace.json file."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from identifier_validation import validate_marketplace_name
+
+
+def default_marketplace_path() -> Path:
+    return Path.home() / ".agents" / "plugins" / "marketplace.json"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Print the top-level marketplace name from marketplace.json. Defaults to the personal "
+            "marketplace path under the current home directory."
+        )
+    )
+    parser.add_argument(
+        "--marketplace-path",
+        default=str(default_marketplace_path()),
+        help="Path to marketplace.json",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    marketplace_path = Path(args.marketplace_path).expanduser().resolve()
+    payload = json.loads(marketplace_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"{marketplace_path} must contain a JSON object.")
+    name = payload.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError(f"{marketplace_path} must contain a non-empty string 'name'.")
+    validate_marketplace_name(name)
+    print(name)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as err:  # noqa: BLE001 - CLI should surface a single clear message.
+        print(str(err), file=sys.stderr)
+        raise SystemExit(1) from err
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/scripts/update_plugin_cachebuster.py b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/update_plugin_cachebuster.py
new file mode 100644
index 0000000000000000000000000000000000000000..7818f15b5cc078aacb5cfd8aeb23b82f75e44b54
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/update_plugin_cachebuster.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Rewrite a local plugin version to a single Codex cachebuster suffix."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from identifier_validation import validate_plugin_identifier
+
+
+CACHEBUSTER_PREFIX = "codex"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Rewrite a local plugin's version so it preserves everything before '+' and uses "
+            "a single +codex.<cachebuster> suffix."
+        )
+    )
+    parser.add_argument("plugin_path", help="Path to the plugin root directory")
+    parser.add_argument(
+        "--cachebuster",
+        help="Optional cachebuster token to embed in the plugin version",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    plugin_root = Path(args.plugin_path).expanduser().resolve()
+    manifest_path = plugin_root / ".codex-plugin" / "plugin.json"
+    manifest = load_manifest(manifest_path)
+
+    plugin_name = manifest.get("name")
+    if not isinstance(plugin_name, str) or not plugin_name.strip():
+        raise ValueError(f"{manifest_path} must contain a non-empty string 'name'.")
+    validate_plugin_identifier(plugin_name)
+
+    version = manifest.get("version")
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError(f"{manifest_path} must contain a non-empty string 'version'.")
+    cachebuster = sanitize_cachebuster(args.cachebuster or default_cachebuster())
+    next_version = with_cachebuster(version, cachebuster)
+    manifest["version"] = next_version
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    print(f"Updated plugin version: {version} -> {next_version}")
+
+
+def load_manifest(manifest_path: Path) -> dict[str, object]:
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"missing manifest: {manifest_path}")
+    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"{manifest_path} must contain a JSON object.")
+    return payload
+
+
+def sanitize_cachebuster(value: str) -> str:
+    sanitized = re.sub(r"[^a-z0-9-]+", "-", value.strip().lower())
+    sanitized = re.sub(r"-{2,}", "-", sanitized).strip("-")
+    if not sanitized:
+        raise ValueError("Cachebuster must contain at least one letter or digit.")
+    return sanitized
+
+
+def default_cachebuster() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+
+
+def with_cachebuster(version: str, cachebuster: str) -> str:
+    version_prefix = version.split("+", 1)[0]
+    return f"{version_prefix}+{CACHEBUSTER_PREFIX}.{cachebuster}"
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as err:  # noqa: BLE001 - CLI should surface a single clear message.
+        print(str(err), file=sys.stderr)
+        raise SystemExit(1) from err
diff --git a/codex-rs/skills/src/assets/samples/plugin-creator/scripts/validate_plugin.py b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/validate_plugin.py
new file mode 100644
index 0000000000000000000000000000000000000000..b5be462c3b4fe3ea6083cca948ccf52e05301546
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/plugin-creator/scripts/validate_plugin.py
@@ -0,0 +1,657 @@
+#!/usr/bin/env python3
+"""Validate a generated plugin against the plugin ingestion contract."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path, PurePosixPath
+from typing import Any
+from urllib.parse import urlparse
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from identifier_validation import validate_plugin_identifier
+
+
+TODO_MARKER = "[TODO:"
+SEMVER_RE = re.compile(
+    r"^(0|[1-9]\d*)\."
+    r"(0|[1-9]\d*)\."
+    r"(0|[1-9]\d*)"
+    r"(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\."
+    r"(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
+)
+HEX_COLOR_RE = re.compile(r"^#[0-9A-F]{6}$", re.IGNORECASE)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate a local Codex plugin.")
+    parser.add_argument("plugin_path", help="Path to the plugin root directory")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    plugin_root = Path(args.plugin_path).expanduser().resolve()
+    errors = validate_plugin(plugin_root)
+    if errors:
+        print("Plugin validation failed:")
+        for error in errors:
+            print(f"- {error}")
+        raise SystemExit(1)
+    print(f"Plugin validation passed: {plugin_root}")
+
+
+def validate_plugin(plugin_root: Path) -> list[str]:
+    errors: list[str] = []
+    manifest_path = plugin_root / ".codex-plugin" / "plugin.json"
+    manifest = load_json_object(manifest_path, errors)
+    if manifest is None:
+        return errors
+
+    reject_todo_markers(manifest, "$", errors)
+    validate_manifest_shape(plugin_root, manifest, errors)
+    return errors
+
+
+def load_json_object(path: Path, errors: list[str]) -> dict[str, Any] | None:
+    if not path.is_file():
+        errors.append("missing `.codex-plugin/plugin.json`")
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError:
+        errors.append("unable to read `.codex-plugin/plugin.json`")
+        return None
+    except json.JSONDecodeError:
+        errors.append("`.codex-plugin/plugin.json` must be valid JSON")
+        return None
+    if not isinstance(payload, dict):
+        errors.append("`.codex-plugin/plugin.json` must contain a JSON object")
+        return None
+    return payload
+
+
+def reject_todo_markers(value: Any, path: str, errors: list[str]) -> None:
+    if isinstance(value, str):
+        if TODO_MARKER in value:
+            errors.append(f"{path} still contains a `[TODO: ...]` placeholder")
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            reject_todo_markers(item, f"{path}[{index}]", errors)
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            reject_todo_markers(item, f"{path}.{key}", errors)
+
+
+def validate_manifest_shape(
+    plugin_root: Path,
+    manifest: dict[str, Any],
+    errors: list[str],
+) -> None:
+    allowed_keys = {
+        "id",
+        "name",
+        "version",
+        "description",
+        "skills",
+        "apps",
+        "mcpServers",
+        "interface",
+        "author",
+        "homepage",
+        "repository",
+        "license",
+        "keywords",
+    }
+    for key in sorted(set(manifest) - allowed_keys):
+        errors.append(f"plugin.json field `{key}` is not accepted by plugin validation")
+
+    validate_optional_non_empty_string(manifest, "id", errors)
+    plugin_name = require_non_empty_string(manifest, "name", errors)
+    if plugin_name is not None:
+        try:
+            validate_plugin_identifier(plugin_name)
+        except ValueError as error:
+            errors.append(f"plugin.json field `name` is invalid: {error}")
+    version = require_non_empty_string(manifest, "version", errors)
+    if version is not None and SEMVER_RE.fullmatch(version) is None:
+        errors.append("plugin.json field `version` must be strict semver")
+    require_non_empty_string(manifest, "description", errors)
+
+    author = require_object(manifest, "author", errors)
+    if author is not None:
+        reject_unknown_fields(author, {"name", "email", "url"}, "author", errors)
+        require_non_empty_string(author, "name", errors, prefix="author")
+        validate_optional_non_empty_string(author, "email", errors, prefix="author")
+        validate_optional_https_url(author, "url", errors, prefix="author")
+
+    validate_optional_contract_path(manifest, "skills", "skills", errors)
+    validate_optional_contract_path(manifest, "apps", ".app.json", errors)
+    validate_manifest_mcp_servers(plugin_root, manifest, errors)
+
+    if manifest.get("apps") is not None:
+        validate_app_manifest(
+            plugin_root / ".app.json",
+            errors,
+        )
+    validate_skill_manifests(plugin_root, errors)
+
+    interface = require_object(manifest, "interface", errors)
+    if interface is None:
+        return
+    reject_unknown_fields(
+        interface,
+        {
+            "displayName",
+            "shortDescription",
+            "longDescription",
+            "developerName",
+            "category",
+            "capabilities",
+            "websiteURL",
+            "privacyPolicyURL",
+            "termsOfServiceURL",
+            "brandColor",
+            "composerIcon",
+            "logo",
+            "logoDark",
+            "screenshots",
+            "defaultPrompt",
+            "default_prompt",
+        },
+        "interface",
+        errors,
+    )
+    for field in (
+        "displayName",
+        "shortDescription",
+        "longDescription",
+        "developerName",
+        "category",
+    ):
+        require_non_empty_string(interface, field, errors, prefix="interface")
+    if "defaultPrompt" not in interface and "default_prompt" not in interface:
+        errors.append(
+            "plugin.json field `interface.defaultPrompt` or `interface.default_prompt` is required"
+        )
+    capabilities = interface.get("capabilities")
+    if not isinstance(capabilities, list) or not all(
+        isinstance(value, str) and value.strip() for value in capabilities
+    ):
+        errors.append(
+            "plugin.json field `interface.capabilities` must be an array of strings"
+        )
+    for field in ("websiteURL", "privacyPolicyURL", "termsOfServiceURL"):
+        validate_optional_https_url(interface, field, errors, prefix="interface")
+    brand_color = interface.get("brandColor")
+    if brand_color is not None and (
+        not isinstance(brand_color, str) or HEX_COLOR_RE.fullmatch(brand_color) is None
+    ):
+        errors.append("plugin.json field `interface.brandColor` must use `#RRGGBB`")
+    for field in ("composerIcon", "logo", "logoDark"):
+        validate_optional_asset_path(plugin_root, plugin_root, interface, field, errors)
+    screenshots = interface.get("screenshots", [])
+    if not isinstance(screenshots, list):
+        errors.append("plugin.json field `interface.screenshots` must be an array")
+    else:
+        for index, raw_path in enumerate(screenshots):
+            validate_asset_path(
+                plugin_root,
+                plugin_root,
+                raw_path,
+                f"interface.screenshots[{index}]",
+                errors,
+            )
+
+
+def require_object(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+) -> dict[str, Any] | None:
+    value = payload.get(key)
+    if not isinstance(value, dict):
+        errors.append(f"plugin.json field `{key}` must be an object")
+        return None
+    return value
+
+
+def require_non_empty_string(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str | None = None,
+) -> str | None:
+    value = payload.get(key)
+    field = f"{prefix}.{key}" if prefix is not None else key
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"plugin.json field `{field}` must be a non-empty string")
+        return None
+    return value
+
+
+def validate_optional_non_empty_string(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str | None = None,
+) -> None:
+    value = payload.get(key)
+    if value is None:
+        return
+    field = f"{prefix}.{key}" if prefix is not None else key
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"plugin.json field `{field}` must be a non-empty string")
+
+
+def reject_unknown_fields(
+    payload: dict[str, Any],
+    allowed_keys: set[str],
+    prefix: str,
+    errors: list[str],
+) -> None:
+    for key in sorted(set(payload) - allowed_keys):
+        errors.append(
+            f"plugin.json field `{prefix}.{key}` is not accepted by plugin validation"
+        )
+
+
+def validate_optional_https_url(
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str,
+) -> None:
+    value = payload.get(key)
+    if value is None:
+        return
+    parsed = urlparse(value) if isinstance(value, str) else None
+    if parsed is None or parsed.scheme != "https" or not parsed.netloc:
+        errors.append(
+            f"plugin.json field `{prefix}.{key}` must be an absolute `https://` URL"
+        )
+
+
+def validate_optional_contract_path(
+    payload: dict[str, Any],
+    key: str,
+    expected: str,
+    errors: list[str],
+) -> None:
+    value = payload.get(key)
+    if value is None:
+        return
+    normalized = normalize_contract_path(value) if isinstance(value, str) else None
+    if normalized != expected:
+        errors.append(f"plugin.json field `{key}` must resolve to `{expected}`")
+
+
+def validate_manifest_mcp_servers(
+    plugin_root: Path,
+    manifest: dict[str, Any],
+    errors: list[str],
+) -> None:
+    value = manifest.get("mcpServers")
+    if value is None:
+        return
+    if isinstance(value, str):
+        validate_optional_contract_path(manifest, "mcpServers", ".mcp.json", errors)
+        validate_mcp_manifest(
+            plugin_root / ".mcp.json",
+            errors,
+        )
+        return
+    if isinstance(value, dict):
+        validate_mcp_server_entries(
+            value,
+            "plugin.json field `mcpServers`",
+            "plugin.json field `mcpServers`",
+            errors,
+        )
+        return
+    errors.append("plugin.json field `mcpServers` must be a string path or object")
+
+
+def normalize_contract_path(raw_path: str) -> str | None:
+    path = Path(raw_path)
+    if path.is_absolute():
+        return None
+    normalized = path.as_posix().rstrip("/")
+    return normalized or None
+
+
+def validate_app_manifest(path: Path, errors: list[str]) -> None:
+    payload = load_companion_json_object(path, "`.app.json`", errors)
+    if payload is None:
+        return
+    reject_companion_unknown_fields(payload, {"apps"}, "`.app.json`", errors)
+    apps = payload.get("apps")
+    if not isinstance(apps, dict):
+        errors.append("`.app.json` field `apps` must be an object")
+        return
+    for key, value in apps.items():
+        if not isinstance(value, dict):
+            errors.append(f"`.app.json` app `{key}` must be an object")
+            continue
+        reject_companion_unknown_fields(
+            value, {"id", "category"}, f"`.app.json` app `{key}`", errors
+        )
+        app_id = value.get("id")
+        if not isinstance(app_id, str) or not app_id.strip():
+            errors.append(
+                f"`.app.json` app `{key}` field `id` must be a non-empty string"
+            )
+        category = value.get("category")
+        if category is not None and (
+            not isinstance(category, str) or not category.strip()
+        ):
+            errors.append(
+                f"`.app.json` app `{key}` field `category` must be a non-empty string"
+            )
+
+
+def validate_mcp_manifest(path: Path, errors: list[str]) -> None:
+    payload = load_companion_json_object(path, "`.mcp.json`", errors)
+    if payload is None:
+        return
+    reject_companion_unknown_fields(payload, {"mcpServers"}, "`.mcp.json`", errors)
+    servers = payload.get("mcpServers")
+    validate_mcp_server_entries(
+        servers,
+        "`.mcp.json`",
+        "`.mcp.json` field `mcpServers`",
+        errors,
+    )
+
+
+def validate_mcp_server_entries(
+    servers: Any,
+    source_label: str,
+    field_label: str,
+    errors: list[str],
+) -> None:
+    if not isinstance(servers, dict):
+        errors.append(f"{field_label} must be an object")
+        return
+    for key, value in servers.items():
+        if not isinstance(key, str) or not key.strip():
+            errors.append(f"{source_label} server names must be non-empty strings")
+        if not isinstance(value, dict):
+            errors.append(f"{source_label} server `{key}` must be an object")
+
+
+def load_companion_json_object(
+    path: Path,
+    label: str,
+    errors: list[str],
+) -> dict[str, Any] | None:
+    if not path.is_file():
+        errors.append(f"{label} is required when its plugin.json field is present")
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        errors.append(f"{label} must contain valid JSON")
+        return None
+    if not isinstance(payload, dict):
+        errors.append(f"{label} must contain a JSON object")
+        return None
+    return payload
+
+
+def reject_companion_unknown_fields(
+    payload: dict[str, Any],
+    allowed_keys: set[str],
+    prefix: str,
+    errors: list[str],
+) -> None:
+    for key in sorted(set(payload) - allowed_keys):
+        errors.append(f"{prefix} field `{key}` is not accepted by plugin validation")
+
+
+def validate_skill_manifests(plugin_root: Path, errors: list[str]) -> None:
+    skills_root = plugin_root / "skills"
+    if not skills_root.is_dir():
+        return
+    for skill_root in sorted(skills_root.iterdir(), key=lambda path: path.name):
+        if skill_root.name.startswith(".") or not skill_root.is_dir():
+            continue
+        validate_skill_manifest(skill_root, errors)
+
+
+def validate_skill_manifest(skill_root: Path, errors: list[str]) -> None:
+    skill_md_path = skill_root / "SKILL.md"
+    if not skill_md_path.is_file():
+        errors.append(f"skill `{skill_root.name}` is missing `SKILL.md`")
+        return
+    try:
+        contents = skill_md_path.read_text(encoding="utf-8")
+    except OSError:
+        errors.append(f"unable to read skill `{skill_root.name}`")
+        return
+    if not contents.startswith("---\n"):
+        errors.append(f"skill `{skill_root.name}` must start with YAML frontmatter")
+        return
+    frontmatter_end = contents.find("\n---", 4)
+    if frontmatter_end == -1:
+        errors.append(f"skill `{skill_root.name}` frontmatter is not closed")
+        return
+    try:
+        frontmatter = yaml.safe_load(contents[4:frontmatter_end])
+    except yaml.YAMLError:
+        errors.append(f"skill `{skill_root.name}` frontmatter must be valid YAML")
+        return
+    if not isinstance(frontmatter, dict):
+        errors.append(f"skill `{skill_root.name}` frontmatter must be an object")
+        return
+    skill_name = frontmatter.get("name")
+    if not isinstance(skill_name, str) or not skill_name.strip():
+        errors.append(
+            f"skill `{skill_root.name}` frontmatter field `name` must be non-empty"
+        )
+    description = frontmatter.get("description")
+    if not isinstance(description, str) or not description.strip():
+        errors.append(
+            f"skill `{skill_root.name}` frontmatter field `description` must be non-empty"
+        )
+    disable_model_invocation = frontmatter.get("disable-model-invocation")
+    if disable_model_invocation is None:
+        disable_model_invocation = frontmatter.get("disable_model_invocation")
+    if disable_model_invocation not in (None, False):
+        errors.append(
+            f"skill `{skill_root.name}` frontmatter field `disable-model-invocation` must be false"
+        )
+    agent_yaml_path = skill_root / "agents" / "openai.yaml"
+    if agent_yaml_path.is_file():
+        validate_skill_agent_manifest(
+            plugin_root=skill_root.parent.parent,
+            skill_root=skill_root,
+            agent_yaml_path=agent_yaml_path,
+            errors=errors,
+        )
+
+
+def validate_skill_agent_manifest(
+    *,
+    plugin_root: Path,
+    skill_root: Path,
+    agent_yaml_path: Path,
+    errors: list[str],
+) -> None:
+    try:
+        payload = yaml.safe_load(agent_yaml_path.read_text(encoding="utf-8"))
+    except OSError:
+        errors.append(f"unable to read skill `{skill_root.name}` agent YAML")
+        return
+    except yaml.YAMLError:
+        errors.append(f"skill `{skill_root.name}` agent YAML must be valid YAML")
+        return
+    if not isinstance(payload, dict):
+        errors.append(f"skill `{skill_root.name}` agent YAML must be an object")
+        return
+
+    reject_skill_agent_unknown_fields(
+        payload,
+        {"interface", "policy", "dependencies"},
+        skill_root,
+        errors,
+    )
+    interface = payload.get("interface")
+    if not isinstance(interface, dict):
+        errors.append(
+            f"skill `{skill_root.name}` agent field `interface` must be an object"
+        )
+        return
+    reject_skill_agent_unknown_fields(
+        interface,
+        {
+            "display_name",
+            "short_description",
+            "icon_small",
+            "icon_large",
+            "brand_color",
+            "default_prompt",
+        },
+        skill_root,
+        errors,
+        prefix="interface",
+    )
+    for field in ("display_name", "short_description"):
+        value = interface.get(field)
+        if not isinstance(value, str) or not value.strip():
+            errors.append(
+                f"skill `{skill_root.name}` agent field `interface.{field}` must be non-empty"
+            )
+    for field in ("icon_small", "icon_large"):
+        validate_optional_asset_path(
+            skill_root,
+            plugin_root,
+            interface,
+            field,
+            errors,
+            prefix=f"skill `{skill_root.name}` agent field `interface",
+        )
+    brand_color = interface.get("brand_color")
+    if brand_color is not None and (
+        not isinstance(brand_color, str) or HEX_COLOR_RE.fullmatch(brand_color) is None
+    ):
+        errors.append(
+            f"skill `{skill_root.name}` agent field `interface.brand_color` must use `#RRGGBB`"
+        )
+    default_prompt = interface.get("default_prompt")
+    if default_prompt is not None and (
+        not isinstance(default_prompt, str) or not default_prompt.strip()
+    ):
+        errors.append(
+            f"skill `{skill_root.name}` agent field `interface.default_prompt` must be non-empty"
+        )
+
+    policy = payload.get("policy")
+    if policy is not None:
+        if not isinstance(policy, dict):
+            errors.append(
+                f"skill `{skill_root.name}` agent field `policy` must be an object"
+            )
+        else:
+            reject_skill_agent_unknown_fields(
+                policy,
+                {"allow_implicit_invocation"},
+                skill_root,
+                errors,
+                prefix="policy",
+            )
+            allow_implicit_invocation = policy.get("allow_implicit_invocation")
+            if allow_implicit_invocation is not None and not isinstance(
+                allow_implicit_invocation,
+                bool,
+            ):
+                errors.append(
+                    f"skill `{skill_root.name}` agent field "
+                    "`policy.allow_implicit_invocation` must be a boolean"
+                )
+
+    dependencies = payload.get("dependencies")
+    if dependencies is not None:
+        if not isinstance(dependencies, dict):
+            errors.append(
+                f"skill `{skill_root.name}` agent field `dependencies` must be an object"
+            )
+        else:
+            reject_skill_agent_unknown_fields(
+                dependencies,
+                {"tools"},
+                skill_root,
+                errors,
+                prefix="dependencies",
+            )
+
+
+def reject_skill_agent_unknown_fields(
+    payload: dict[str, Any],
+    allowed_keys: set[str],
+    skill_root: Path,
+    errors: list[str],
+    *,
+    prefix: str | None = None,
+) -> None:
+    for key in sorted(set(payload) - allowed_keys):
+        field = f"{prefix}.{key}" if prefix is not None else key
+        errors.append(
+            f"skill `{skill_root.name}` agent field `{field}` is not accepted by plugin validation"
+        )
+
+
+def validate_optional_asset_path(
+    base_dir: Path,
+    allowed_root: Path,
+    payload: dict[str, Any],
+    key: str,
+    errors: list[str],
+    *,
+    prefix: str = "interface",
+) -> None:
+    raw_path = payload.get(key)
+    if raw_path is None:
+        return
+    validate_asset_path(base_dir, allowed_root, raw_path, f"{prefix}.{key}", errors)
+
+
+def validate_asset_path(
+    base_dir: Path,
+    allowed_root: Path,
+    raw_path: Any,
+    field: str,
+    errors: list[str],
+) -> None:
+    label = field if field.startswith("skill `") else f"plugin.json field `{field}`"
+    if not isinstance(raw_path, str) or not raw_path.strip():
+        errors.append(f"{label} must be a non-empty relative path")
+        return
+    candidate = PurePosixPath(raw_path.replace("\\", "/"))
+    if candidate.is_absolute() or any(
+        part in {"", ".", ".."} for part in candidate.parts
+    ):
+        errors.append(f"{label} must stay inside the plugin archive")
+        return
+    resolved_path = (base_dir / candidate.as_posix()).resolve()
+    if not resolved_path.is_relative_to(allowed_root.resolve()):
+        errors.append(f"{label} must stay inside the plugin archive")
+        return
+    if not resolved_path.is_file():
+        errors.append(f"{label} points to a missing file")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/codex-rs/skills/src/assets/samples/review-agent/SKILL.md b/codex-rs/skills/src/assets/samples/review-agent/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..c694020c1c5de0e8fee4e933f55e0f6b3d055d8a
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/review-agent/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: review-agent
+description: Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
+---
+
+# Review Agent
+
+Inspect the requested target directly and return every finding that the author would likely fix.
+Do not modify files, create commits, push branches, post review comments, or delegate the review
+to another agent.
+
+## Review the change
+
+1. Read the applicable `AGENTS.md` instructions.
+2. Inspect the complete diff for the requested target and enough surrounding code to understand
+   each changed path.
+3. Identify concrete regressions introduced by the change. Continue through the whole diff after
+   finding the first issue.
+4. Check the relevant tests and call sites to confirm that each finding is real and actionable.
+
+For a base-branch review, compare the changes that would actually merge rather than diffing
+directly against the branch tip. Resolve the comparison ref to the branch's upstream when that
+upstream exists and is ahead of the local branch; otherwise use the local branch. Run
+`git merge-base HEAD <comparison-ref>`, then inspect `git diff <merge-base-sha>`. If the local
+branch cannot be resolved, try its configured upstream explicitly before reporting that the target
+is unavailable.
+
+Flag an issue only when all of these are true:
+
+- It affects correctness, security, performance, or maintainability in a meaningful way.
+- It is discrete and actionable.
+- It was introduced by the reviewed change.
+- The affected scenario or call path can be demonstrated from the code.
+- The author would probably fix it if they knew about it.
+
+Do not flag speculative concerns, pre-existing problems, intentional behavior changes, or style
+nits that do not obscure the code.
+
+## Write the result
+
+Present findings first, ordered by severity. Use one entry per issue in this form:
+
+`[P1] Imperative finding title — path/to/file.rs:line`
+
+Follow the title with one short paragraph explaining the affected scenario and why the behavior is
+wrong. Keep the cited range as small as possible and make sure it overlaps the reviewed diff.
+
+Use these priorities:
+
+- `P0`: universal release blocker or critical failure.
+- `P1`: urgent defect that should be fixed next.
+- `P2`: ordinary defect that should be fixed.
+- `P3`: low-impact issue that is still worth fixing.
+
+If there are no qualifying findings, say `No findings.` Do not invent a finding to fill the result.
+After the findings, add a brief overall assessment and mention any material test gaps or residual
+risks.
diff --git a/codex-rs/skills/src/assets/samples/review-agent/agents/openai.yaml b/codex-rs/skills/src/assets/samples/review-agent/agents/openai.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..ebbb0b041fb2d88c226fdaef198f9c8e53396552
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/review-agent/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "Review Agent"
+  short_description: "Find actionable bugs in code changes"
+  default_prompt: "Use $review-agent to review the requested code changes and return actionable findings."
+policy:
+  allow_implicit_invocation: false
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md b/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..490ccc6c3e0015eb982bb5c108c2df083be2c6c2
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md
@@ -0,0 +1,229 @@
+---
+name: skill-creator
+description: Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
+metadata:
+  short-description: Create or update a skill
+---
+
+# Skill Creator
+
+Create skills that give Codex useful, non-obvious guidance without constraining unrelated work.
+
+## Core Principles
+
+**Assume Codex is already capable.** Include only information that changes its decisions or improves its work. Remove generic advice, repeated instructions, speculative edge cases, and examples that do not materially clarify the task.
+
+**Preserve user intent and scope.** A skill should support the requested task, not replace the user's chosen product, expand the assignment, modify unrelated configuration, or imply permission for additional external actions. Do not turn a particular example, past failure, or personal preference into a universal requirement.
+
+Approval to complete a task does not expand its scope or execution permissions. For retrying or externally mutating workflows, define a stopping condition proportional to the risk.
+
+**Match specificity to the risk.** Give the model room to choose an appropriate approach when multiple approaches are reasonable. Use detailed steps, deterministic scripts, or absolute language only when correctness, safety, permissions, or a genuinely fragile workflow requires them.
+
+For open-ended work, describe the outcome and relevant decision criteria. For workflows with a preferred shape, offer useful examples or configurable scripts. Reserve fixed sequences and narrow parameters for operations where deviation would cause a concrete problem. Preserve non-obvious operational invariants, distinguish actual requirements from optional recommendations or local conventions, and avoid restating policies already enforced elsewhere.
+
+**Keep discovery cheap and precise.** Skill names and descriptions are available before a skill is loaded. Describe the actual capability and when it applies, adding exclusions only when they prevent likely misrouting. Avoid exhaustive capability lists and catchalls that attract unrelated requests.
+
+Keep skills self-contained; refer to another skill or tool only when the requested workflow genuinely requires it and it is available in the target environment. Specialized review, hardening, or audit workflows should apply when requested or genuinely needed, not merely because ordinary work touches the same subject.
+
+**Disclose detail progressively.** Keep shared purpose, essential constraints, and useful routing in `SKILL.md`. Put substantial mode-specific guidance, schemas, examples, or procedures in supporting references and read only the references relevant to the current task. A simple self-contained skill does not need a router or extra files.
+
+## Anatomy of a Skill
+
+Every skill is a folder containing a required `SKILL.md` file and any optional resources its actual workflow needs:
+
+```text
+skill-name/
+|-- SKILL.md                 Required skill instructions
+|   |-- YAML frontmatter     Required name and description
+|   `-- Markdown body        Instructions loaded when the skill is used
+|-- agents/                  Optional UI metadata and invocation policy
+|   `-- openai.yaml
+|-- scripts/                 Optional executable helpers
+|-- references/              Optional documentation loaded as needed
+`-- assets/                  Optional files used in generated output
+```
+
+Choose the structure that fits the actual task. Some skills are short and self-contained; others route among operating modes or delegate complex mechanics to scripts. Avoid creating directories, placeholders, examples, or ancillary documentation without a clear use.
+
+### SKILL.md
+
+The YAML frontmatter identifies the skill and determines when it should be considered. Include the required `name` and `description`, and preserve supported optional fields such as existing `metadata` when appropriate.
+
+The Markdown body is loaded only when the skill is used. Put the purpose, essential workflow, real constraints, and useful links there. Keep detailed procedures and examples in supporting references when they are relevant only to particular modes.
+
+Skill information is disclosed in three stages:
+
+1. **Name and description:** Available during skill selection, so keep them concise and discriminating.
+2. **SKILL.md body:** Loaded when the skill applies, so keep its instructions relevant to that task.
+3. **Supporting resources:** Read or execute only when the current task actually needs them.
+
+The entrypoint should be as short as the task permits while retaining important constraints. A large upper bound is not a target: move conditional detail into references when doing so improves clarity or context use, rather than waiting for the file to become unwieldy.
+
+### Scripts
+
+Use `scripts/` for executable code when the same logic would otherwise be rewritten repeatedly or deterministic execution materially improves reliability.
+
+- **Example:** `scripts/rotate_pdf.py` for a PDF operation that would otherwise require recreating the same code.
+- **Useful for:** Repeated transformations, reliable API operations, data processing, and other concrete automation.
+- **Validation:** Run new or changed scripts to verify their behavior. Scripts can usually be executed without loading their full implementation into context, although an agent may need to inspect them when patching or adapting them.
+
+### References
+
+Use `references/` for documentation that is needed only in particular contexts.
+
+- **Examples:** `references/schema.md` for database tables, `references/policies.md` for domain rules, `references/api_docs.md` for an API, or separate writing guides for different deliverables.
+- **Useful for:** Schemas, API documentation, company policies, format-specific procedures, detailed workflows, and substantial examples.
+- **Routing:** Link each reference from `SKILL.md` or another relevant resource and explain when it should be read. Keep information in one place instead of duplicating it across the entrypoint and references.
+
+Keep references focused on maintained, task-specific information that changes the agent's decisions. Avoid copied manuals, exhaustive catalogs, and generic tutorials already available from authoritative sources. Before removing existing resources, inspect their callers and purpose.
+
+For large references, include useful search terms or a short contents section when that makes the needed material easier to find.
+
+### Assets
+
+Use `assets/` for files that belong in generated output rather than in the model's instructions.
+
+- **Examples:** `assets/logo.png`, `assets/slides.pptx`, `assets/font.ttf`, or `assets/frontend-template/`.
+- **Useful for:** Templates, images, fonts, icons, boilerplate projects, and other files copied or adapted into the result.
+- **Context:** Do not load assets as instructions unless the task requires inspecting them.
+
+### UI Metadata and Invocation Policy
+
+`agents/openai.yaml` can provide UI-facing metadata such as `display_name`, `short_description`, and `default_prompt`, along with invocation policy. When creating or updating those settings, read [references/openai_yaml.md](references/openai_yaml.md) and keep the values consistent with the skill.
+
+Automatic skill selection is allowed by default. Change that default only when the user explicitly requests an explicit-only skill:
+
+```yaml
+policy:
+  allow_implicit_invocation: false
+```
+
+This keeps the skill available when explicitly invoked as `$skill-name` without adding it to the model context automatically. Preserve unrelated existing UI, policy, and dependency fields when updating `agents/openai.yaml`.
+
+The initializer creates this file automatically. For new or interface-only metadata, generate it with:
+
+```bash
+scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value
+```
+
+The generator replaces the entire file. If an existing file contains `policy` or `dependencies`, update only the intended fields in place instead of regenerating it.
+
+Include optional interface fields only when the user provides or requests them.
+
+### What Not to Include
+
+Include files that directly support the skill's work. Avoid adding a `README.md`, installation guide, changelog, duplicated quick reference, or other auxiliary documentation unless a specific task or packaging requirement calls for it.
+
+## Progressive Disclosure in Practice
+
+For a skill with multiple substantial modes, keep the shared guidance and mode-selection criteria in `SKILL.md`. Link each supporting reference where its use becomes relevant. Do not load every reference by default, duplicate reference content in the entrypoint, or add a routing layer when there is nothing meaningful to route.
+
+For example, a deployment skill can keep provider selection in `SKILL.md` and separate provider details:
+
+```text
+cloud-deploy/
+|-- SKILL.md
+`-- references/
+    |-- aws.md
+    |-- gcp.md
+    `-- azure.md
+```
+
+When the user chooses AWS, read `references/aws.md`; do not also load the GCP and Azure guides. The same pattern can separate business domains, deliverable types, or other genuinely distinct operating modes.
+
+A short skill can instead route to details only when an advanced operation needs them:
+
+```markdown
+## Documents
+
+Handle ordinary edits directly.
+
+- For tracked changes, read [references/redlining.md](references/redlining.md).
+- For document internals, read [references/ooxml.md](references/ooxml.md).
+```
+
+These examples illustrate options, not a required structure. Choose the organization that makes the skill easier to use without loading irrelevant material.
+
+## Create or Update a Skill
+
+Adapt the work to the request. Creating a complex new skill may involve understanding realistic use cases, choosing supporting resources, initializing files, writing instructions, and validating the result. A narrow update to an existing skill may require only a focused edit and validation.
+
+Ask clarifying questions only when the missing information matters and cannot be reasonably inferred. Respect a user-specified location; otherwise create discoverable skills in `$CODEX_HOME/skills`, or `~/.codex/skills` when `CODEX_HOME` is unset.
+
+Keep automatic skill selection enabled unless the user explicitly requests an explicit-only skill. When the intended invocation mode is genuinely unclear and matters to the requested workflow, ask whether the user wants normal automatic discovery or explicit-only invocation; otherwise preserve the default. Do not infer explicit-only invocation from sensitive operations or required approvals: keep the skill discoverable and require authorization immediately before the actual mutation. Preserve an existing skill's invocation policy unless the user asks to change it.
+
+For a new or substantially revised skill, consider the actual requests it should handle and which reusable resources would improve those tasks:
+
+- A repeated PDF transformation may justify a `scripts/rotate_pdf.py` helper.
+- An application-building workflow may benefit from an `assets/frontend-template/` starter.
+- A data-analysis skill may need a `references/schema.md` guide to avoid rediscovering table relationships.
+
+Create those resources only when their concrete benefit justifies them. If the user has already explained the task clearly, proceed without requesting additional examples.
+
+### Naming
+
+- Use lowercase letters, digits, and hyphens.
+- Keep names under 64 characters and prefer short action-oriented names.
+- Namespace by tool or domain when doing so improves discovery.
+- Name the skill folder after the skill.
+
+### Initialize a New Skill
+
+For a new skill, use the bundled initializer when it helps create the required files consistently:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
+```
+
+For example:
+
+```bash
+scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
+scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references
+```
+
+Request only the resource directories the skill needs. Use `--examples` only when concrete placeholders would help, and replace or remove them before finishing. Do not initialize an existing skill again.
+
+The initializer creates the skill directory, a concise `SKILL.md` starter, and `agents/openai.yaml`. It creates resource directories and example files only when requested. Pass generated UI values as `--interface key=value` when needed.
+
+### Write the Instructions
+
+The frontmatter `description` should briefly explain what the skill does and when it applies. Include a meaningful boundary when similar requests should not activate the skill.
+
+For example:
+
+```yaml
+description: Create or edit Word documents when formatting, tracked changes, or comments require document-specific handling.
+```
+
+Put detailed workflows, tool choices, examples, and operating modes in the body or relevant references rather than listing them all in the description. Preserve supported optional frontmatter, such as existing `metadata`, when appropriate.
+
+Write only the instructions needed for another Codex instance to perform the task well. State the desired outcome, non-obvious context, real constraints, and relevant references or tools. Preserve the user's explicit choices and existing authorization boundaries. Avoid prescribing a fixed structure, process, or number of steps when the task does not require one.
+
+### Validate and Iterate
+
+Validate the completed skill with:
+
+```bash
+scripts/quick_validate.py <path/to/skill-folder>
+```
+
+The validator checks frontmatter, naming, and unfinished scaffold placeholders; it does not prove that the skill makes good decisions. Also check that descriptions remain discriminating, instructions preserve user intent, references are discoverable, and any added scripts actually work.
+
+When testing is warranted, verify observable behavior or meaningful invariants. Avoid tests that merely match generated wording, headings, or regex patterns.
+
+Improve the skill based on real usage or demonstrated failures. Prefer a narrow correction to accumulating universal rules for every observed example.
+
+## Independent Forward-Testing
+
+Use an independent subagent pass when a skill is sufficiently complex or risky that realistic behavioral validation would add meaningful confidence, and when delegation is available and authorized. Ordinary creation or small edits do not automatically require subagents.
+
+Give the evaluating agent a realistic user request, the skill, and the minimum raw artifacts needed to perform the task. Do not provide the intended answer, suspected bug, proposed fix, or prior conclusions unless the evaluation genuinely requires them.
+
+For example:
+
+```text
+Use $skill-name at /path/to/skill-name to complete this realistic request.
+```
+
+Keep the evaluation scoped to permitted resources and side effects. Use an isolated temporary workspace for generated artifacts so they do not enter the working tree or contaminate later evaluations. Ask for approval when the proposed evaluation would require additional authorization, affect a live production system, or impose substantial time or cost. Review the actual outcome and artifacts, then make only changes supported by the observed behavior.
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/agents/openai.yaml b/codex-rs/skills/src/assets/samples/skill-creator/agents/openai.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..3095c600ce769c862519df036ab5777a5a947fec
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Skill Creator"
+  short_description: "Create or update a skill"
+  icon_small: "./assets/skill-creator-small.svg"
+  icon_large: "./assets/skill-creator.png"
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/assets/skill-creator-small.svg b/codex-rs/skills/src/assets/samples/skill-creator/assets/skill-creator-small.svg
new file mode 100644
index 0000000000000000000000000000000000000000..c6e4f67c624a00705a662dbd0230b8c531180f56
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/assets/skill-creator-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
+  <path fill="#0D0D0D" d="M12.03 4.113a3.612 3.612 0 0 1 5.108 5.108l-6.292 6.29c-.324.324-.56.561-.791.752l-.235.176c-.205.14-.422.261-.65.36l-.229.093a4.136 4.136 0 0 1-.586.16l-.764.134-2.394.4c-.142.024-.294.05-.423.06-.098.007-.232.01-.378-.026l-.149-.05a1.081 1.081 0 0 1-.521-.474l-.046-.093a1.104 1.104 0 0 1-.075-.527c.01-.129.035-.28.06-.422l.398-2.394c.1-.602.162-.987.295-1.35l.093-.23c.1-.228.22-.445.36-.65l.176-.235c.19-.232.428-.467.751-.79l6.292-6.292Zm-5.35 7.232c-.35.35-.534.535-.66.688l-.11.147a2.67 2.67 0 0 0-.24.433l-.062.154c-.08.22-.124.462-.232 1.112l-.398 2.394-.001.001h.003l2.393-.399.717-.126a2.63 2.63 0 0 0 .394-.105l.154-.063a2.65 2.65 0 0 0 .433-.24l.147-.11c.153-.126.339-.31.688-.66l4.988-4.988-3.227-3.226-4.987 4.988Zm9.517-6.291a2.281 2.281 0 0 0-3.225 0l-.364.362 3.226 3.227.363-.364c.89-.89.89-2.334 0-3.225ZM4.583 1.783a.3.3 0 0 1 .294.241c.117.585.347 1.092.707 1.48.357.385.859.668 1.549.783a.3.3 0 0 1 0 .592c-.69.115-1.192.398-1.549.783-.315.34-.53.77-.657 1.265l-.05.215a.3.3 0 0 1-.588 0c-.117-.585-.347-1.092-.707-1.48-.357-.384-.859-.668-1.549-.783a.3.3 0 0 1 0-.592c.69-.115 1.192-.398 1.549-.783.36-.388.59-.895.707-1.48l.015-.05a.3.3 0 0 1 .279-.19Z"/>
+</svg>
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/assets/skill-creator.png b/codex-rs/skills/src/assets/samples/skill-creator/assets/skill-creator.png
new file mode 100644
index 0000000000000000000000000000000000000000..4f3d6d82fa78fbdce97af3c17f6a25c683aa3290
Binary files /dev/null and b/codex-rs/skills/src/assets/samples/skill-creator/assets/skill-creator.png differ
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/license.txt b/codex-rs/skills/src/assets/samples/skill-creator/license.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d645695673349e3947e8e5ae42332d0ac3164cd7
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/license.txt
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/references/openai_yaml.md b/codex-rs/skills/src/assets/samples/skill-creator/references/openai_yaml.md
new file mode 100644
index 0000000000000000000000000000000000000000..90f9e8e863dff501c0125e2ead20c1dd6c3028d5
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/references/openai_yaml.md
@@ -0,0 +1,49 @@
+# openai.yaml fields (full example + descriptions)
+
+`agents/openai.yaml` is an extended, product-specific config intended for the machine/harness to read, not the agent. Other product-specific config can also live in the `agents/` folder.
+
+## Full example
+
+```yaml
+interface:
+  display_name: "Optional user-facing name"
+  short_description: "Optional user-facing description"
+  icon_small: "./assets/small-400px.png"
+  icon_large: "./assets/large-logo.svg"
+  brand_color: "#3B82F6"
+  default_prompt: "Optional surrounding prompt to use the skill with"
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "github"
+      description: "GitHub MCP server"
+      transport: "streamable_http"
+      url: "https://api.githubcopilot.com/mcp/"
+
+policy:
+  allow_implicit_invocation: true
+```
+
+## Field descriptions and constraints
+
+Top-level constraints:
+
+- Quote all string values.
+- Keep keys unquoted.
+- For `interface.default_prompt`: generate a helpful, short (typically 1 sentence) example starting prompt based on the skill. It must explicitly mention the skill as `$skill-name` (e.g., "Use $skill-name-here to draft a concise weekly status update.").
+
+- `interface.display_name`: Human-facing title shown in UI skill lists and chips.
+- `interface.short_description`: Human-facing short UI blurb (25–64 chars) for quick scanning.
+- `interface.icon_small`: Path to a small icon asset (relative to skill dir). Default to `./assets/` and place icons in the skill's `assets/` folder.
+- `interface.icon_large`: Path to a larger logo asset (relative to skill dir). Default to `./assets/` and place icons in the skill's `assets/` folder.
+- `interface.brand_color`: Hex color used for UI accents (e.g., badges).
+- `interface.default_prompt`: Default prompt snippet inserted when invoking the skill.
+- `dependencies.tools[].type`: Dependency category. Only `mcp` is supported for now.
+- `dependencies.tools[].value`: Identifier of the tool or dependency.
+- `dependencies.tools[].description`: Human-readable explanation of the dependency.
+- `dependencies.tools[].transport`: Connection type when `type` is `mcp`.
+- `dependencies.tools[].url`: MCP server URL when `type` is `mcp`.
+- `policy.allow_implicit_invocation`: When false, the skill is not injected into
+  the model context by default, but can still be invoked explicitly via `$skill`.
+  Defaults to true.
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/scripts/generate_openai_yaml.py b/codex-rs/skills/src/assets/samples/skill-creator/scripts/generate_openai_yaml.py
new file mode 100644
index 0000000000000000000000000000000000000000..870eefcea9bd0184806b8eb305526e883d2f7241
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/scripts/generate_openai_yaml.py
@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""
+OpenAI YAML Generator - Creates agents/openai.yaml for a skill folder.
+
+Usage:
+    generate_openai_yaml.py <skill_dir> [--name <skill_name>] [--interface key=value]
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ACRONYMS = {
+    "GH",
+    "MCP",
+    "API",
+    "CI",
+    "CLI",
+    "LLM",
+    "PDF",
+    "PR",
+    "UI",
+    "URL",
+    "SQL",
+}
+
+BRANDS = {
+    "openai": "OpenAI",
+    "openapi": "OpenAPI",
+    "github": "GitHub",
+    "pagerduty": "PagerDuty",
+    "datadog": "DataDog",
+    "sqlite": "SQLite",
+    "fastapi": "FastAPI",
+}
+
+SMALL_WORDS = {"and", "or", "to", "up", "with"}
+
+ALLOWED_INTERFACE_KEYS = {
+    "display_name",
+    "short_description",
+    "icon_small",
+    "icon_large",
+    "brand_color",
+    "default_prompt",
+}
+
+
+def yaml_quote(value):
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    return f'"{escaped}"'
+
+
+def format_display_name(skill_name):
+    words = [word for word in skill_name.split("-") if word]
+    formatted = []
+    for index, word in enumerate(words):
+        lower = word.lower()
+        upper = word.upper()
+        if upper in ACRONYMS:
+            formatted.append(upper)
+            continue
+        if lower in BRANDS:
+            formatted.append(BRANDS[lower])
+            continue
+        if index > 0 and lower in SMALL_WORDS:
+            formatted.append(lower)
+            continue
+        formatted.append(word.capitalize())
+    return " ".join(formatted)
+
+
+def generate_short_description(display_name):
+    description = f"Help with {display_name} tasks"
+
+    if len(description) < 25:
+        description = f"Help with {display_name} tasks and workflows"
+    if len(description) < 25:
+        description = f"Help with {display_name} tasks with guidance"
+
+    if len(description) > 64:
+        description = f"Help with {display_name}"
+    if len(description) > 64:
+        description = f"{display_name} helper"
+    if len(description) > 64:
+        description = f"{display_name} tools"
+    if len(description) > 64:
+        suffix = " helper"
+        max_name_length = 64 - len(suffix)
+        trimmed = display_name[:max_name_length].rstrip()
+        description = f"{trimmed}{suffix}"
+    if len(description) > 64:
+        description = description[:64].rstrip()
+
+    if len(description) < 25:
+        description = f"{description} workflows"
+        if len(description) > 64:
+            description = description[:64].rstrip()
+
+    return description
+
+
+def read_frontmatter_name(skill_dir):
+    skill_md = Path(skill_dir) / "SKILL.md"
+    if not skill_md.exists():
+        print(f"[ERROR] SKILL.md not found in {skill_dir}")
+        return None
+    content = skill_md.read_text()
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        print("[ERROR] Invalid SKILL.md frontmatter format.")
+        return None
+    frontmatter_text = match.group(1)
+
+    import yaml
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+    except yaml.YAMLError as exc:
+        print(f"[ERROR] Invalid YAML frontmatter: {exc}")
+        return None
+    if not isinstance(frontmatter, dict):
+        print("[ERROR] Frontmatter must be a YAML dictionary.")
+        return None
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str) or not name.strip():
+        print("[ERROR] Frontmatter 'name' is missing or invalid.")
+        return None
+    return name.strip()
+
+
+def parse_interface_overrides(raw_overrides):
+    overrides = {}
+    optional_order = []
+    for item in raw_overrides:
+        if "=" not in item:
+            print(f"[ERROR] Invalid interface override '{item}'. Use key=value.")
+            return None, None
+        key, value = item.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            print(f"[ERROR] Invalid interface override '{item}'. Key is empty.")
+            return None, None
+        if key not in ALLOWED_INTERFACE_KEYS:
+            allowed = ", ".join(sorted(ALLOWED_INTERFACE_KEYS))
+            print(f"[ERROR] Unknown interface field '{key}'. Allowed: {allowed}")
+            return None, None
+        overrides[key] = value
+        if (
+            key not in ("display_name", "short_description")
+            and key not in optional_order
+        ):
+            optional_order.append(key)
+    return overrides, optional_order
+
+
+def write_openai_yaml(skill_dir, skill_name, raw_overrides):
+    overrides, optional_order = parse_interface_overrides(raw_overrides)
+    if overrides is None:
+        return None
+
+    display_name = overrides.get("display_name") or format_display_name(skill_name)
+    short_description = overrides.get(
+        "short_description"
+    ) or generate_short_description(display_name)
+
+    if not (25 <= len(short_description) <= 64):
+        print(
+            "[ERROR] short_description must be 25-64 characters "
+            f"(got {len(short_description)})."
+        )
+        return None
+
+    interface_lines = [
+        "interface:",
+        f"  display_name: {yaml_quote(display_name)}",
+        f"  short_description: {yaml_quote(short_description)}",
+    ]
+
+    for key in optional_order:
+        value = overrides.get(key)
+        if value is not None:
+            interface_lines.append(f"  {key}: {yaml_quote(value)}")
+
+    agents_dir = Path(skill_dir) / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    output_path = agents_dir / "openai.yaml"
+    output_path.write_text("\n".join(interface_lines) + "\n")
+    print(f"[OK] Created agents/openai.yaml")
+    return output_path
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create agents/openai.yaml for a skill directory.",
+    )
+    parser.add_argument("skill_dir", help="Path to the skill directory")
+    parser.add_argument(
+        "--name",
+        help="Skill name override (defaults to SKILL.md frontmatter)",
+    )
+    parser.add_argument(
+        "--interface",
+        action="append",
+        default=[],
+        help="Interface override in key=value format (repeatable)",
+    )
+    args = parser.parse_args()
+
+    skill_dir = Path(args.skill_dir).resolve()
+    if not skill_dir.exists():
+        print(f"[ERROR] Skill directory not found: {skill_dir}")
+        sys.exit(1)
+    if not skill_dir.is_dir():
+        print(f"[ERROR] Path is not a directory: {skill_dir}")
+        sys.exit(1)
+
+    skill_name = args.name or read_frontmatter_name(skill_dir)
+    if not skill_name:
+        sys.exit(1)
+
+    result = write_openai_yaml(skill_dir, skill_name, args.interface)
+    if result:
+        sys.exit(0)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/scripts/init_skill.py b/codex-rs/skills/src/assets/samples/skill-creator/scripts/init_skill.py
new file mode 100644
index 0000000000000000000000000000000000000000..2ed2fa3125c720fcce60a29f3dd82d04b14d9fa0
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/scripts/init_skill.py
@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples] [--interface key=value]
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-new-skill --path skills/public --resources scripts,references
+    init_skill.py my-api-helper --path skills/private --resources scripts --examples
+    init_skill.py custom-skill --path /custom/location
+    init_skill.py my-skill --path skills/public --interface short_description="Short UI label"
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from generate_openai_yaml import write_openai_yaml
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_RESOURCES = {"scripts", "references", "assets"}
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: "[TODO: Briefly describe what this skill does and when it applies.]"
+---
+
+# {skill_title}
+
+[TODO: Add the task-specific guidance Codex needs. Reference supporting files only when they are relevant.]
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference for {skill_title}
+
+Replace this placeholder with maintained, task-specific details that Codex
+would not reliably know, such as operational constraints, local schemas, or
+fragile integration behavior.
+
+Delete this file if no supported workflow needs it.
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Codex produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def normalize_skill_name(skill_name):
+    """Normalize a skill name to lowercase hyphen-case."""
+    normalized = skill_name.strip().lower()
+    normalized = re.sub(r"[^a-z0-9]+", "-", normalized)
+    normalized = normalized.strip("-")
+    normalized = re.sub(r"-{2,}", "-", normalized)
+    return normalized
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return " ".join(word.capitalize() for word in skill_name.split("-"))
+
+
+def parse_resources(raw_resources):
+    if not raw_resources:
+        return []
+    resources = [item.strip() for item in raw_resources.split(",") if item.strip()]
+    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})
+    if invalid:
+        allowed = ", ".join(sorted(ALLOWED_RESOURCES))
+        print(f"[ERROR] Unknown resource type(s): {', '.join(invalid)}")
+        print(f"   Allowed: {allowed}")
+        sys.exit(1)
+    deduped = []
+    seen = set()
+    for resource in resources:
+        if resource not in seen:
+            deduped.append(resource)
+            seen.add(resource)
+    return deduped
+
+
+def create_resource_dirs(
+    skill_dir, skill_name, skill_title, resources, include_examples
+):
+    for resource in resources:
+        resource_dir = skill_dir / resource
+        resource_dir.mkdir(exist_ok=True)
+        if resource == "scripts":
+            if include_examples:
+                example_script = resource_dir / "example.py"
+                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+                example_script.chmod(0o755)
+                print("[OK] Created scripts/example.py")
+            else:
+                print("[OK] Created scripts/")
+        elif resource == "references":
+            if include_examples:
+                example_reference = resource_dir / "api_reference.md"
+                example_reference.write_text(
+                    EXAMPLE_REFERENCE.format(skill_title=skill_title)
+                )
+                print("[OK] Created references/api_reference.md")
+            else:
+                print("[OK] Created references/")
+        elif resource == "assets":
+            if include_examples:
+                example_asset = resource_dir / "example_asset.txt"
+                example_asset.write_text(EXAMPLE_ASSET)
+                print("[OK] Created assets/example_asset.txt")
+            else:
+                print("[OK] Created assets/")
+
+
+def init_skill(skill_name, path, resources, include_examples, interface_overrides):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+        resources: Resource directories to create
+        include_examples: Whether to create example files in resource directories
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        print(f"[ERROR] Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+        print(f"[OK] Created skill directory: {skill_dir}")
+    except Exception as e:
+        print(f"[ERROR] Error creating directory: {e}")
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(
+        skill_name=skill_name, skill_title=skill_title
+    )
+
+    skill_md_path = skill_dir / "SKILL.md"
+    try:
+        skill_md_path.write_text(skill_content)
+        print("[OK] Created SKILL.md")
+    except Exception as e:
+        print(f"[ERROR] Error creating SKILL.md: {e}")
+        return None
+
+    # Create agents/openai.yaml
+    try:
+        result = write_openai_yaml(skill_dir, skill_name, interface_overrides)
+        if not result:
+            return None
+    except Exception as e:
+        print(f"[ERROR] Error creating agents/openai.yaml: {e}")
+        return None
+
+    # Create resource directories if requested
+    if resources:
+        try:
+            create_resource_dirs(
+                skill_dir, skill_name, skill_title, resources, include_examples
+            )
+        except Exception as e:
+            print(f"[ERROR] Error creating resource directories: {e}")
+            return None
+
+    # Print next steps
+    print(f"\n[OK] Skill '{skill_name}' initialized successfully at {skill_dir}")
+    print("\nNext steps:")
+    print("1. Edit SKILL.md to complete the TODO items and update the description")
+    if resources:
+        if include_examples:
+            print(
+                "2. Customize or delete the example files in scripts/, references/, and assets/"
+            )
+        else:
+            print("2. Add resources to scripts/, references/, and assets/ as needed")
+    else:
+        print(
+            "2. Create resource directories only if needed (scripts/, references/, assets/)"
+        )
+    print("3. Update agents/openai.yaml if the UI metadata should differ")
+    print("4. Run the validator when ready to check the skill structure")
+    print(
+        "5. Consider independent forward-testing only when complexity or risk warrants it"
+    )
+
+    return skill_dir
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create a new skill directory with a SKILL.md template.",
+    )
+    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
+    parser.add_argument("--path", required=True, help="Output directory for the skill")
+    parser.add_argument(
+        "--resources",
+        default="",
+        help="Comma-separated list: scripts,references,assets",
+    )
+    parser.add_argument(
+        "--examples",
+        action="store_true",
+        help="Create example files inside the selected resource directories",
+    )
+    parser.add_argument(
+        "--interface",
+        action="append",
+        default=[],
+        help="Interface override in key=value format (repeatable)",
+    )
+    args = parser.parse_args()
+
+    raw_skill_name = args.skill_name
+    skill_name = normalize_skill_name(raw_skill_name)
+    if not skill_name:
+        print("[ERROR] Skill name must include at least one letter or digit.")
+        sys.exit(1)
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        print(
+            f"[ERROR] Skill name '{skill_name}' is too long ({len(skill_name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
+        )
+        sys.exit(1)
+    if skill_name != raw_skill_name:
+        print(f"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.")
+
+    resources = parse_resources(args.resources)
+    if args.examples and not resources:
+        print("[ERROR] --examples requires --resources to be set.")
+        sys.exit(1)
+
+    path = args.path
+
+    print(f"Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    if resources:
+        print(f"   Resources: {', '.join(resources)}")
+        if args.examples:
+            print("   Examples: enabled")
+    else:
+        print("   Resources: none (create as needed)")
+    print()
+
+    result = init_skill(skill_name, path, resources, args.examples, args.interface)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py b/codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py
new file mode 100644
index 0000000000000000000000000000000000000000..e27023ece4bd259ef36560e19995eec7b6a345bf
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found"
+
+    content = skill_md.read_text()
+    if not content.startswith("---"):
+        return False, "No YAML frontmatter found"
+
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format"
+
+    frontmatter_text = match.group(1)
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary"
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}"
+
+    allowed_properties = {"name", "description", "license", "allowed-tools", "metadata"}
+
+    unexpected_keys = set(frontmatter.keys()) - allowed_properties
+    if unexpected_keys:
+        allowed = ", ".join(sorted(allowed_properties))
+        unexpected = ", ".join(sorted(unexpected_keys))
+        return (
+            False,
+            f"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}",
+        )
+
+    if "name" not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if "description" not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
+        if not re.match(r"^[a-z0-9-]+$", name):
+            return (
+                False,
+                f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
+            )
+        if name.startswith("-") or name.endswith("-") or "--" in name:
+            return (
+                False,
+                f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
+            )
+        if len(name) > MAX_SKILL_NAME_LENGTH:
+            return (
+                False,
+                f"Name is too long ({len(name)} characters). "
+                f"Maximum is {MAX_SKILL_NAME_LENGTH} characters.",
+            )
+
+    description = frontmatter.get("description", "")
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description.startswith("[TODO:"):
+        return False, "Description contains an unfinished TODO placeholder"
+    if description:
+        if "<" in description or ">" in description:
+            return False, "Description cannot contain angle brackets (< or >)"
+        if len(description) > 1024:
+            return (
+                False,
+                f"Description is too long ({len(description)} characters). Maximum is 1024 characters.",
+            )
+
+    body = content[match.end() :]
+    fence_marker = None
+    fence_length = 0
+    for line in body.splitlines():
+        fence = re.match(r"^[ \t]*(?:(?:[-+*]|\d+[.)])[ \t]+)?(`{3,}|~{3,})(.*)$", line)
+        if fence:
+            marker = fence.group(1)
+            if fence_marker is None:
+                fence_marker = marker[0]
+                fence_length = len(marker)
+            elif (
+                marker[0] == fence_marker
+                and len(marker) >= fence_length
+                and not fence.group(2).strip()
+            ):
+                fence_marker = None
+                fence_length = 0
+            continue
+
+        if fence_marker is None and re.fullmatch(
+            r"[ ]{0,3}\[TODO:[^\n]*\][ \t]*", line
+        ):
+            return False, "Skill instructions contain an unfinished TODO placeholder"
+
+    return True, "Skill is valid!"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    print(message)
+    sys.exit(0 if valid else 1)
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/LICENSE.txt b/codex-rs/skills/src/assets/samples/skill-installer/LICENSE.txt
new file mode 100644
index 0000000000000000000000000000000000000000..d645695673349e3947e8e5ae42332d0ac3164cd7
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/LICENSE.txt
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/SKILL.md b/codex-rs/skills/src/assets/samples/skill-installer/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..030135b6e015f3c4b9976d80f4f46dbd8487b016
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: skill-installer
+description: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
+metadata:
+  short-description: Install curated skills from openai/skills or other repos
+---
+
+# Skill Installer
+
+Helps install skills. By default these are from https://github.com/openai/skills/tree/main/skills/.curated, but users can also provide other locations. Experimental skills live in https://github.com/openai/skills/tree/main/skills/.experimental and can be installed the same way.
+
+Use the helper scripts based on the task:
+- List skills when the user asks what is available, or if the user uses this skill without specifying what to do. Default listing is `.curated`, but you can pass `--path skills/.experimental` when they ask about experimental skills.
+- Install from the curated list when the user provides a skill name.
+- Install from another repo when the user provides a GitHub repo/path (including private repos).
+
+Install skills with the helper scripts.
+
+## Communication
+
+When listing skills, output approximately as follows, depending on the context of the user's request. If they ask about experimental skills, list from `.experimental` instead of `.curated` and label the source accordingly:
+"""
+Skills from {repo}:
+1. skill-1
+2. skill-2 (already installed)
+3. ...
+Which ones would you like installed?
+"""
+
+After installing a skill, tell the user it will be available on their next turn.
+
+## Scripts
+
+All of these scripts use network, so when running in the sandbox, request escalation when running them.
+
+- `scripts/list-skills.py` (prints skills list with installed annotations)
+- `scripts/list-skills.py --format json`
+- Example (experimental list): `scripts/list-skills.py --path skills/.experimental`
+- `scripts/install-skill-from-github.py --repo <owner>/<repo> --path <path/to/skill> [<path/to/skill> ...]`
+- `scripts/install-skill-from-github.py --url https://github.com/<owner>/<repo>/tree/<ref>/<path>`
+- Example (experimental skill): `scripts/install-skill-from-github.py --repo openai/skills --path skills/.experimental/<skill-name>`
+
+## Behavior and Options
+
+- Defaults to direct download for public GitHub repos.
+- If download fails with auth/permission errors, falls back to git sparse checkout.
+- Aborts if the destination skill directory already exists.
+- Installs into `$CODEX_HOME/skills/<skill-name>` (defaults to `~/.codex/skills`).
+- Multiple `--path` values install multiple skills in one run, each named from the path basename unless `--name` is supplied.
+- Options: `--ref <ref>` (default `main`), `--dest <path>`, `--method auto|download|git`.
+
+## Notes
+
+- Curated listing is fetched from `https://github.com/openai/skills/tree/main/skills/.curated` via the GitHub API. If it is unavailable, explain the error and exit.
+- Private GitHub repos can be accessed via existing git credentials or optional `GITHUB_TOKEN`/`GH_TOKEN` for download.
+- Git fallback tries HTTPS first, then SSH.
+- The skills at https://github.com/openai/skills/tree/main/skills/.system are preinstalled, so no need to help users install those. If they ask, just explain this. If they insist, you can download and overwrite.
+- Installed annotations come from `$CODEX_HOME/skills`.
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/agents/openai.yaml b/codex-rs/skills/src/assets/samples/skill-installer/agents/openai.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..88d40cd9468441cfc83ffed52f9d71867392b850
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/agents/openai.yaml
@@ -0,0 +1,5 @@
+interface:
+  display_name: "Skill Installer"
+  short_description: "Install curated skills from openai/skills or other repos"
+  icon_small: "./assets/skill-installer-small.svg"
+  icon_large: "./assets/skill-installer.png"
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/assets/skill-installer-small.svg b/codex-rs/skills/src/assets/samples/skill-installer/assets/skill-installer-small.svg
new file mode 100644
index 0000000000000000000000000000000000000000..ccfc034241ae8e6bea7284e188aed142a67c53e9
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/assets/skill-installer-small.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="#0D0D0D" d="M2.145 3.959a2.033 2.033 0 0 1 2.022-1.824h5.966c.551 0 .997 0 1.357.029.367.03.692.093.993.246l.174.098c.397.243.72.593.932 1.01l.053.114c.116.269.168.557.194.878.03.36.03.805.03 1.357v4.3a2.365 2.365 0 0 1-2.366 2.365h-1.312a2.198 2.198 0 0 1-4.377 0H4.167A2.032 2.032 0 0 1 2.135 10.5V9.333l.004-.088A.865.865 0 0 1 3 8.468l.116-.006A1.135 1.135 0 0 0 3 6.199a.865.865 0 0 1-.865-.864V4.167l.01-.208Zm1.054 1.186a2.198 2.198 0 0 1 0 4.376v.98c0 .534.433.967.968.967H6l.089.004a.866.866 0 0 1 .776.861 1.135 1.135 0 0 0 2.27 0c0-.478.387-.865.865-.865h1.5c.719 0 1.301-.583 1.301-1.301v-4.3c0-.57 0-.964-.025-1.27a1.933 1.933 0 0 0-.09-.493L12.642 4a1.47 1.47 0 0 0-.541-.585l-.102-.056c-.126-.065-.295-.11-.596-.135a17.31 17.31 0 0 0-1.27-.025H4.167a.968.968 0 0 0-.968.968v.978Z"/>
+</svg>
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/assets/skill-installer.png b/codex-rs/skills/src/assets/samples/skill-installer/assets/skill-installer.png
new file mode 100644
index 0000000000000000000000000000000000000000..2977cd5bb49b3b8bd50d8bf476d7cffbb3f88a46
Binary files /dev/null and b/codex-rs/skills/src/assets/samples/skill-installer/assets/skill-installer.png differ
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/scripts/github_utils.py b/codex-rs/skills/src/assets/samples/skill-installer/scripts/github_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..711f597e4cf0c08b897083c1c337e13524a76260
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/scripts/github_utils.py
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Shared GitHub helpers for skill install scripts."""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+
+
+def github_request(url: str, user_agent: str) -> bytes:
+    headers = {"User-Agent": user_agent}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"token {token}"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req) as resp:
+        return resp.read()
+
+
+def github_api_contents_url(repo: str, path: str, ref: str) -> str:
+    return f"https://api.github.com/repos/{repo}/contents/{path}?ref={ref}"
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/scripts/install-skill-from-github.py b/codex-rs/skills/src/assets/samples/skill-installer/scripts/install-skill-from-github.py
new file mode 100644
index 0000000000000000000000000000000000000000..2d05f74924037738dbcc60cb677412ddc7e17d36
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/scripts/install-skill-from-github.py
@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+"""Install a skill from a GitHub repo path into $CODEX_HOME/skills."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import zipfile
+
+from github_utils import github_request
+
+DEFAULT_REF = "main"
+
+
+@dataclass
+class Args:
+    url: str | None = None
+    repo: str | None = None
+    path: list[str] | None = None
+    ref: str = DEFAULT_REF
+    dest: str | None = None
+    name: str | None = None
+    method: str = "auto"
+
+
+@dataclass
+class Source:
+    owner: str
+    repo: str
+    ref: str
+    paths: list[str]
+    repo_url: str | None = None
+
+
+class InstallError(Exception):
+    pass
+
+
+def _codex_home() -> str:
+    return os.environ.get("CODEX_HOME", os.path.expanduser("~/.codex"))
+
+
+def _tmp_root() -> str:
+    base = os.path.join(tempfile.gettempdir(), "codex")
+    os.makedirs(base, exist_ok=True)
+    return base
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "codex-skill-install")
+
+
+def _parse_github_url(url: str, default_ref: str) -> tuple[str, str, str, str | None]:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.netloc != "github.com":
+        raise InstallError("Only GitHub URLs are supported for download mode.")
+    parts = [p for p in parsed.path.split("/") if p]
+    if len(parts) < 2:
+        raise InstallError("Invalid GitHub URL.")
+    owner, repo = parts[0], parts[1]
+    ref = default_ref
+    subpath = ""
+    if len(parts) > 2:
+        if parts[2] in ("tree", "blob"):
+            if len(parts) < 4:
+                raise InstallError("GitHub URL missing ref or path.")
+            ref = parts[3]
+            subpath = "/".join(parts[4:])
+        else:
+            subpath = "/".join(parts[2:])
+    return owner, repo, ref, subpath or None
+
+
+def _download_repo_zip(owner: str, repo: str, ref: str, dest_dir: str) -> str:
+    zip_url = f"https://codeload.github.com/{owner}/{repo}/zip/{ref}"
+    zip_path = os.path.join(dest_dir, "repo.zip")
+    try:
+        payload = _request(zip_url)
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"Download failed: HTTP {exc.code}") from exc
+    with open(zip_path, "wb") as file_handle:
+        file_handle.write(payload)
+    with zipfile.ZipFile(zip_path, "r") as zip_file:
+        _safe_extract_zip(zip_file, dest_dir)
+        top_levels = {name.split("/")[0] for name in zip_file.namelist() if name}
+    if not top_levels:
+        raise InstallError("Downloaded archive was empty.")
+    if len(top_levels) != 1:
+        raise InstallError("Unexpected archive layout.")
+    return os.path.join(dest_dir, next(iter(top_levels)))
+
+
+def _run_git(args: list[str]) -> None:
+    result = subprocess.run(
+        args, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+    )
+    if result.returncode != 0:
+        raise InstallError(result.stderr.strip() or "Git command failed.")
+
+
+def _safe_extract_zip(zip_file: zipfile.ZipFile, dest_dir: str) -> None:
+    dest_root = os.path.realpath(dest_dir)
+    for info in zip_file.infolist():
+        extracted_path = os.path.realpath(os.path.join(dest_dir, info.filename))
+        if extracted_path == dest_root or extracted_path.startswith(dest_root + os.sep):
+            continue
+        raise InstallError("Archive contains files outside the destination.")
+    zip_file.extractall(dest_dir)
+
+
+def _validate_relative_path(path: str) -> None:
+    if os.path.isabs(path) or os.path.normpath(path).startswith(".."):
+        raise InstallError("Skill path must be a relative path inside the repo.")
+
+
+def _validate_skill_name(name: str) -> None:
+    altsep = os.path.altsep
+    if not name or os.path.sep in name or (altsep and altsep in name):
+        raise InstallError("Skill name must be a single path segment.")
+    if name in (".", ".."):
+        raise InstallError("Invalid skill name.")
+
+
+def _git_sparse_checkout(
+    repo_url: str, ref: str, paths: list[str], dest_dir: str
+) -> str:
+    repo_dir = os.path.join(dest_dir, "repo")
+    clone_cmd = [
+        "git",
+        "clone",
+        "--filter=blob:none",
+        "--depth",
+        "1",
+        "--sparse",
+        "--single-branch",
+        "--branch",
+        ref,
+        repo_url,
+        repo_dir,
+    ]
+    try:
+        _run_git(clone_cmd)
+    except InstallError:
+        _run_git(
+            [
+                "git",
+                "clone",
+                "--filter=blob:none",
+                "--depth",
+                "1",
+                "--sparse",
+                "--single-branch",
+                repo_url,
+                repo_dir,
+            ]
+        )
+    _run_git(["git", "-C", repo_dir, "sparse-checkout", "set", *paths])
+    _run_git(["git", "-C", repo_dir, "checkout", ref])
+    return repo_dir
+
+
+def _validate_skill(path: str, repo_root: str) -> None:
+    resolved_repo_root = os.path.realpath(repo_root)
+    resolved_path = os.path.realpath(path)
+    try:
+        inside_repo = (
+            os.path.commonpath([resolved_repo_root, resolved_path])
+            == resolved_repo_root
+        )
+    except ValueError:
+        inside_repo = False
+    if not inside_repo:
+        raise InstallError("Skill path must be inside the repo.")
+
+    relative_path = os.path.relpath(path, repo_root)
+    current_path = repo_root
+    for component in relative_path.split(os.path.sep):
+        current_path = os.path.join(current_path, component)
+        if os.path.islink(current_path):
+            raise InstallError(
+                f"Symbolic links are not allowed in skills: {os.path.relpath(current_path, repo_root)}"
+            )
+
+    if not os.path.isdir(path):
+        raise InstallError(f"Skill path not found: {path}")
+    skill_md = os.path.join(path, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        raise InstallError("SKILL.md not found in selected skill directory.")
+
+    for root, directories, files in os.walk(path):
+        for name in directories + files:
+            entry_path = os.path.join(root, name)
+            relative_entry = os.path.relpath(entry_path, repo_root)
+            if os.path.islink(entry_path):
+                resolved_entry = os.path.realpath(entry_path)
+                try:
+                    inside_skill = (
+                        os.path.commonpath([resolved_path, resolved_entry])
+                        == resolved_path
+                    )
+                except ValueError:
+                    inside_skill = False
+                if not inside_skill or not os.path.isfile(resolved_entry):
+                    raise InstallError(
+                        f"Unsupported symbolic link in skill: {relative_entry}"
+                    )
+                continue
+            if not os.path.isdir(entry_path) and not os.path.isfile(entry_path):
+                raise InstallError(f"Unsupported file type in skill: {relative_entry}")
+
+
+def _copy_skill(src: str, dest_dir: str) -> None:
+    os.makedirs(os.path.dirname(dest_dir), exist_ok=True)
+    if os.path.exists(dest_dir):
+        raise InstallError(f"Destination already exists: {dest_dir}")
+    shutil.copytree(src, dest_dir)
+
+
+def _build_repo_url(owner: str, repo: str) -> str:
+    return f"https://github.com/{owner}/{repo}.git"
+
+
+def _build_repo_ssh(owner: str, repo: str) -> str:
+    return f"git@github.com:{owner}/{repo}.git"
+
+
+def _prepare_repo(source: Source, method: str, tmp_dir: str) -> str:
+    if method in ("download", "auto"):
+        try:
+            return _download_repo_zip(source.owner, source.repo, source.ref, tmp_dir)
+        except InstallError as exc:
+            if method == "download":
+                raise
+            err_msg = str(exc)
+            if "HTTP 401" in err_msg or "HTTP 403" in err_msg or "HTTP 404" in err_msg:
+                pass
+            else:
+                raise
+    if method in ("git", "auto"):
+        repo_url = source.repo_url or _build_repo_url(source.owner, source.repo)
+        try:
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+        except InstallError:
+            repo_url = _build_repo_ssh(source.owner, source.repo)
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+    raise InstallError("Unsupported method.")
+
+
+def _resolve_source(args: Args) -> Source:
+    if args.url:
+        owner, repo, ref, url_path = _parse_github_url(args.url, args.ref)
+        if args.path is not None:
+            paths = list(args.path)
+        elif url_path:
+            paths = [url_path]
+        else:
+            paths = []
+        if not paths:
+            raise InstallError("Missing --path for GitHub URL.")
+        return Source(owner=owner, repo=repo, ref=ref, paths=paths)
+
+    if not args.repo:
+        raise InstallError("Provide --repo or --url.")
+    if "://" in args.repo:
+        return _resolve_source(
+            Args(url=args.repo, repo=None, path=args.path, ref=args.ref)
+        )
+
+    repo_parts = [p for p in args.repo.split("/") if p]
+    if len(repo_parts) != 2:
+        raise InstallError("--repo must be in owner/repo format.")
+    if not args.path:
+        raise InstallError("Missing --path for --repo.")
+    paths = list(args.path)
+    return Source(
+        owner=repo_parts[0],
+        repo=repo_parts[1],
+        ref=args.ref,
+        paths=paths,
+    )
+
+
+def _default_dest() -> str:
+    return os.path.join(_codex_home(), "skills")
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="Install a skill from GitHub.")
+    parser.add_argument("--repo", help="owner/repo")
+    parser.add_argument("--url", help="https://github.com/owner/repo[/tree/ref/path]")
+    parser.add_argument(
+        "--path",
+        nargs="+",
+        help="Path(s) to skill(s) inside repo",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument("--dest", help="Destination skills directory")
+    parser.add_argument(
+        "--name", help="Destination skill name (defaults to basename of path)"
+    )
+    parser.add_argument(
+        "--method",
+        choices=["auto", "download", "git"],
+        default="auto",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        source = _resolve_source(args)
+        source.ref = source.ref or args.ref
+        if not source.paths:
+            raise InstallError("No skill paths provided.")
+        for path in source.paths:
+            _validate_relative_path(path)
+        dest_root = args.dest or _default_dest()
+        tmp_dir = tempfile.mkdtemp(prefix="skill-install-", dir=_tmp_root())
+        try:
+            repo_root = _prepare_repo(source, args.method, tmp_dir)
+            installed = []
+            for path in source.paths:
+                skill_name = args.name if len(source.paths) == 1 else None
+                skill_name = skill_name or os.path.basename(path.rstrip("/"))
+                _validate_skill_name(skill_name)
+                if not skill_name:
+                    raise InstallError("Unable to derive skill name.")
+                dest_dir = os.path.join(dest_root, skill_name)
+                if os.path.exists(dest_dir):
+                    raise InstallError(f"Destination already exists: {dest_dir}")
+                skill_src = os.path.join(repo_root, path)
+                _validate_skill(skill_src, repo_root)
+                _copy_skill(skill_src, dest_dir)
+                installed.append((skill_name, dest_dir))
+        finally:
+            if os.path.isdir(tmp_dir):
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+        for skill_name, dest_dir in installed:
+            print(f"Installed {skill_name} to {dest_dir}")
+        return 0
+    except InstallError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/codex-rs/skills/src/assets/samples/skill-installer/scripts/list-skills.py b/codex-rs/skills/src/assets/samples/skill-installer/scripts/list-skills.py
new file mode 100644
index 0000000000000000000000000000000000000000..0015571c5a64b4c7f54ee435b7f91b8ec4694a72
--- /dev/null
+++ b/codex-rs/skills/src/assets/samples/skill-installer/scripts/list-skills.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""List skills from a GitHub repo path."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+
+from github_utils import github_api_contents_url, github_request
+
+DEFAULT_REPO = "openai/skills"
+DEFAULT_PATH = "skills/.curated"
+DEFAULT_REF = "main"
+
+
+class ListError(Exception):
+    pass
+
+
+class Args(argparse.Namespace):
+    repo: str
+    path: str
+    ref: str
+    format: str
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "codex-skill-list")
+
+
+def _codex_home() -> str:
+    return os.environ.get("CODEX_HOME", os.path.expanduser("~/.codex"))
+
+
+def _installed_skills() -> set[str]:
+    root = os.path.join(_codex_home(), "skills")
+    if not os.path.isdir(root):
+        return set()
+    entries = set()
+    for name in os.listdir(root):
+        path = os.path.join(root, name)
+        if os.path.isdir(path):
+            entries.add(name)
+    return entries
+
+
+def _list_skills(repo: str, path: str, ref: str) -> list[str]:
+    api_url = github_api_contents_url(repo, path, ref)
+    try:
+        payload = _request(api_url)
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            raise ListError(
+                f"Skills path not found: https://github.com/{repo}/tree/{ref}/{path}"
+            ) from exc
+        raise ListError(f"Failed to fetch skills: HTTP {exc.code}") from exc
+    data = json.loads(payload.decode("utf-8"))
+    if not isinstance(data, list):
+        raise ListError("Unexpected skills listing response.")
+    skills = [item["name"] for item in data if item.get("type") == "dir"]
+    return sorted(skills)
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="List skills.")
+    parser.add_argument("--repo", default=DEFAULT_REPO)
+    parser.add_argument(
+        "--path",
+        default=DEFAULT_PATH,
+        help="Repo path to list (default: skills/.curated)",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        skills = _list_skills(args.repo, args.path, args.ref)
+        installed = _installed_skills()
+        if args.format == "json":
+            payload = [
+                {"name": name, "installed": name in installed} for name in skills
+            ]
+            print(json.dumps(payload))
+        else:
+            for idx, name in enumerate(skills, start=1):
+                suffix = " (already installed)" if name in installed else ""
+                print(f"{idx}. {name}{suffix}")
+        return 0
+    except ListError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/codex-rs/skills/src/interface.rs b/codex-rs/skills/src/interface.rs
new file mode 100644
index 0000000000000000000000000000000000000000..25fb474b2b0121b0f6a56d168bc33b053f7ccd8b
--- /dev/null
+++ b/codex-rs/skills/src/interface.rs
@@ -0,0 +1,201 @@
+use std::path::Component;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
+
+use crate::SkillInterface;
+
+const MAX_NAME_LEN: usize = 64;
+const MAX_DESCRIPTION_LEN: usize = 1024;
+
+/// Interface metadata deserialized from a skill's `agents/openai.yaml` file.
+#[derive(Debug, Default, Deserialize)]
+pub struct SkillInterfaceFile {
+    display_name: Option<String>,
+    short_description: Option<String>,
+    icon_small: Option<PathBuf>,
+    icon_large: Option<PathBuf>,
+    brand_color: Option<String>,
+    default_prompt: Option<String>,
+}
+
+/// Controls whether interface icons may resolve through a plugin's shared assets directory.
+#[derive(Debug, Clone, Copy)]
+pub enum SkillInterfaceAssetPolicy<'a> {
+    LocalOnly,
+    PluginShared { plugin_root: &'a AbsolutePathBuf },
+}
+
+/// Validates skill interface metadata and resolves its asset paths.
+pub fn resolve_skill_interface(
+    interface: Option<SkillInterfaceFile>,
+    skill_dir: &AbsolutePathBuf,
+    asset_policy: SkillInterfaceAssetPolicy<'_>,
+) -> Option<SkillInterface> {
+    let interface = interface?;
+    let interface = SkillInterface {
+        display_name: resolve_str(
+            interface.display_name,
+            MAX_NAME_LEN,
+            "interface.display_name",
+        ),
+        short_description: resolve_str(
+            interface.short_description,
+            MAX_DESCRIPTION_LEN,
+            "interface.short_description",
+        ),
+        icon_small: resolve_asset_path(
+            skill_dir,
+            asset_policy,
+            "interface.icon_small",
+            interface.icon_small,
+        ),
+        icon_large: resolve_asset_path(
+            skill_dir,
+            asset_policy,
+            "interface.icon_large",
+            interface.icon_large,
+        ),
+        brand_color: resolve_color_str(interface.brand_color, "interface.brand_color"),
+        default_prompt: resolve_str(
+            interface.default_prompt,
+            MAX_DESCRIPTION_LEN,
+            "interface.default_prompt",
+        ),
+    };
+    let has_fields = interface.display_name.is_some()
+        || interface.short_description.is_some()
+        || interface.icon_small.is_some()
+        || interface.icon_large.is_some()
+        || interface.brand_color.is_some()
+        || interface.default_prompt.is_some();
+    has_fields.then_some(interface)
+}
+
+fn resolve_asset_path(
+    skill_dir: &AbsolutePathBuf,
+    asset_policy: SkillInterfaceAssetPolicy<'_>,
+    field: &'static str,
+    path: Option<PathBuf>,
+) -> Option<AbsolutePathBuf> {
+    let path = path?;
+    if path.as_os_str().is_empty() {
+        return None;
+    }
+
+    let assets_dir = skill_dir.join("assets");
+    if path.is_absolute() {
+        tracing::warn!(
+            "ignoring {field}: icon must be a relative assets path (not {})",
+            assets_dir.display()
+        );
+        return None;
+    }
+
+    let mut normalized = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::CurDir => {}
+            Component::Normal(component) => normalized.push(component),
+            Component::ParentDir => {
+                return resolve_plugin_shared_asset_path(skill_dir, asset_policy, field, &path);
+            }
+            Component::Prefix(_) | Component::RootDir => {
+                tracing::warn!("ignoring {field}: icon path must be under assets/");
+                return None;
+            }
+        }
+    }
+
+    let mut components = normalized.components();
+    match components.next() {
+        Some(Component::Normal(component)) if component == "assets" => {}
+        _ => {
+            tracing::warn!("ignoring {field}: icon path must be under assets/");
+            return None;
+        }
+    }
+
+    Some(skill_dir.join(normalized))
+}
+
+fn resolve_plugin_shared_asset_path(
+    skill_dir: &AbsolutePathBuf,
+    asset_policy: SkillInterfaceAssetPolicy<'_>,
+    field: &'static str,
+    path: &Path,
+) -> Option<AbsolutePathBuf> {
+    let SkillInterfaceAssetPolicy::PluginShared { plugin_root } = asset_policy else {
+        tracing::warn!("ignoring {field}: icon path must not contain '..'");
+        return None;
+    };
+
+    let plugin_assets_dir = lexically_normalize(plugin_root.join("assets").as_path());
+    let resolved = lexically_normalize(skill_dir.join(path).as_path());
+    if !resolved.starts_with(&plugin_assets_dir) {
+        tracing::warn!("ignoring {field}: icon path with '..' must resolve under plugin assets/");
+        return None;
+    }
+
+    AbsolutePathBuf::try_from(resolved)
+        .map_err(|error| {
+            tracing::warn!("ignoring {field}: icon path must resolve to an absolute path: {error}");
+            error
+        })
+        .ok()
+}
+
+fn lexically_normalize(path: &Path) -> PathBuf {
+    let mut normalized = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                normalized.pop();
+            }
+            Component::Prefix(_) | Component::RootDir | Component::Normal(_) => {
+                normalized.push(component.as_os_str());
+            }
+        }
+    }
+    normalized
+}
+
+fn resolve_str(value: Option<String>, max_len: usize, field: &'static str) -> Option<String> {
+    let value = value?;
+    let value = value.split_whitespace().collect::<Vec<_>>().join(" ");
+    if value.is_empty() {
+        tracing::warn!("ignoring {field}: value is empty");
+        return None;
+    }
+    if value.chars().count() > max_len {
+        tracing::warn!("ignoring {field}: exceeds maximum length of {max_len} characters");
+        return None;
+    }
+    Some(value)
+}
+
+fn resolve_color_str(value: Option<String>, field: &'static str) -> Option<String> {
+    let value = value?;
+    let value = value.trim();
+    if value.is_empty() {
+        tracing::warn!("ignoring {field}: value is empty");
+        return None;
+    }
+    let mut chars = value.chars();
+    if value.len() == 7
+        && chars.next() == Some('#')
+        && chars.all(|character| character.is_ascii_hexdigit())
+    {
+        Some(value.to_string())
+    } else {
+        tracing::warn!("ignoring {field}: expected #RRGGBB, got {value}");
+        None
+    }
+}
+
+#[cfg(test)]
+#[path = "interface_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/interface_tests.rs b/codex-rs/skills/src/interface_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..872c977f4ff07bc15f586fac0c6fe66e52b25c62
--- /dev/null
+++ b/codex-rs/skills/src/interface_tests.rs
@@ -0,0 +1,165 @@
+use std::path::PathBuf;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+
+use super::SkillInterfaceAssetPolicy;
+use super::SkillInterfaceFile;
+use super::resolve_skill_interface;
+use crate::SkillInterface;
+
+fn absolute_path(path: &str) -> AbsolutePathBuf {
+    AbsolutePathBuf::try_from(
+        std::env::current_dir()
+            .expect("current directory")
+            .join(path),
+    )
+    .expect("absolute path")
+}
+
+#[test]
+fn resolves_local_interface_fields_and_assets() {
+    let skill_dir = absolute_path("skill");
+    let interface = SkillInterfaceFile {
+        display_name: Some("  Demo   skill  ".to_string()),
+        short_description: Some("  Short   description  ".to_string()),
+        icon_small: Some(PathBuf::from("./assets/icon.svg")),
+        icon_large: Some(PathBuf::from("assets/icon-large.png")),
+        brand_color: Some(" #123ABC ".to_string()),
+        default_prompt: Some("  Run   the demo  ".to_string()),
+    };
+
+    assert_eq!(
+        resolve_skill_interface(
+            Some(interface),
+            &skill_dir,
+            SkillInterfaceAssetPolicy::LocalOnly,
+        ),
+        Some(SkillInterface {
+            display_name: Some("Demo skill".to_string()),
+            short_description: Some("Short description".to_string()),
+            icon_small: Some(skill_dir.join("assets/icon.svg")),
+            icon_large: Some(skill_dir.join("assets/icon-large.png")),
+            brand_color: Some("#123ABC".to_string()),
+            default_prompt: Some("Run the demo".to_string()),
+        })
+    );
+}
+
+#[test]
+fn rejects_invalid_local_interface_fields() {
+    let skill_dir = absolute_path("skill");
+    let interface = SkillInterfaceFile {
+        display_name: None,
+        short_description: None,
+        icon_small: Some(PathBuf::from("../outside.svg")),
+        icon_large: Some(PathBuf::from("icon.png")),
+        brand_color: Some("blue".to_string()),
+        default_prompt: Some("x".repeat(1025)),
+    };
+
+    assert_eq!(
+        resolve_skill_interface(
+            Some(interface),
+            &skill_dir,
+            SkillInterfaceAssetPolicy::LocalOnly,
+        ),
+        None
+    );
+}
+
+#[test]
+fn rejects_absolute_asset_paths() {
+    let skill_dir = absolute_path("skill");
+    let interface = SkillInterfaceFile {
+        icon_small: Some(absolute_path("outside.svg").as_path().to_path_buf()),
+        ..Default::default()
+    };
+
+    assert_eq!(
+        resolve_skill_interface(
+            Some(interface),
+            &skill_dir,
+            SkillInterfaceAssetPolicy::LocalOnly,
+        ),
+        None
+    );
+}
+
+#[test]
+fn drops_invalid_fields_without_discarding_valid_interface_fields() {
+    let skill_dir = absolute_path("skill");
+    let interface = SkillInterfaceFile {
+        display_name: Some("Demo skill".to_string()),
+        short_description: None,
+        icon_small: Some(PathBuf::from("assets/icon.svg")),
+        icon_large: Some(PathBuf::from("icon.png")),
+        brand_color: Some("blue".to_string()),
+        default_prompt: Some("x".repeat(1025)),
+    };
+
+    assert_eq!(
+        resolve_skill_interface(
+            Some(interface),
+            &skill_dir,
+            SkillInterfaceAssetPolicy::LocalOnly,
+        ),
+        Some(SkillInterface {
+            display_name: Some("Demo skill".to_string()),
+            short_description: None,
+            icon_small: Some(skill_dir.join("assets/icon.svg")),
+            icon_large: None,
+            brand_color: None,
+            default_prompt: None,
+        })
+    );
+}
+
+#[test]
+fn resolves_plugin_shared_assets() {
+    let plugin_root = absolute_path("plugin");
+    let skill_dir = plugin_root.join("skills/demo");
+    let interface = SkillInterfaceFile {
+        icon_small: Some(PathBuf::from("../../assets/icon.svg")),
+        ..Default::default()
+    };
+
+    assert_eq!(
+        resolve_skill_interface(
+            Some(interface),
+            &skill_dir,
+            SkillInterfaceAssetPolicy::PluginShared {
+                plugin_root: &plugin_root,
+            },
+        ),
+        Some(SkillInterface {
+            display_name: None,
+            short_description: None,
+            icon_small: Some(plugin_root.join("assets/icon.svg")),
+            icon_large: None,
+            brand_color: None,
+            default_prompt: None,
+        })
+    );
+}
+
+#[test]
+fn rejects_plugin_assets_outside_shared_assets_root() {
+    let plugin_root = absolute_path("plugin");
+    let skill_dir = plugin_root.join("skills/demo");
+    let interface = SkillInterfaceFile {
+        icon_small: Some(PathBuf::from("../../other/icon.svg")),
+        ..Default::default()
+    };
+
+    assert_eq!(
+        resolve_skill_interface(
+            Some(interface),
+            &skill_dir,
+            SkillInterfaceAssetPolicy::PluginShared {
+                plugin_root: &plugin_root,
+            },
+        ),
+        None
+    );
+}
diff --git a/codex-rs/skills/src/invocation.rs b/codex-rs/skills/src/invocation.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e7427efef518e6de3d0575464c6d623f7a746a9d
--- /dev/null
+++ b/codex-rs/skills/src/invocation.rs
@@ -0,0 +1,160 @@
+use std::path::Path;
+
+use codex_protocol::parse_command::ParsedCommand;
+use codex_shell_command::parse_command::parse_command_impl;
+use codex_shell_command::parse_command::tokenize_powershell_command;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path_uri::PathConvention;
+use codex_utils_path_uri::PathUri;
+
+use crate::SkillMetadata;
+
+/// A skill document read or script execution identified in a shell command.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ImplicitSkillAccess {
+    Document(PathUri),
+    Script(PathUri),
+}
+
+/// Provides the indexed skill lookups used to recognize implicit invocations.
+pub trait ImplicitSkillLookup {
+    fn implicit_skill_for_scripts_dir(&self, path: &AbsolutePathBuf) -> Option<&SkillMetadata>;
+
+    fn implicit_skill_for_doc_path(&self, path: &AbsolutePathBuf) -> Option<&SkillMetadata>;
+}
+
+pub fn detect_implicit_skill_invocation_for_command(
+    outcome: &impl ImplicitSkillLookup,
+    command: &str,
+    workdir: &AbsolutePathBuf,
+) -> Option<SkillMetadata> {
+    let workdir = canonicalize_if_exists(workdir);
+    let tokens = if PathConvention::native() == PathConvention::Windows {
+        tokenize_powershell_command(command)
+    } else {
+        tokenize_command(command)
+    };
+
+    if let Some(candidate) = detect_skill_script_run(outcome, tokens.as_slice(), &workdir) {
+        return Some(candidate);
+    }
+
+    detect_skill_doc_read(outcome, tokens.as_slice(), &workdir)
+}
+
+/// Resolves statically recognizable skill accesses without consulting the host filesystem.
+pub fn implicit_skill_accesses_for_command(
+    command: &str,
+    workdir: &PathUri,
+) -> Vec<ImplicitSkillAccess> {
+    let tokens = if workdir.infer_path_convention() == Some(PathConvention::Windows) {
+        tokenize_powershell_command(command)
+    } else {
+        tokenize_command(command)
+    };
+    let mut accesses = Vec::new();
+    if let Some(script) = script_run_token(&tokens)
+        && let Ok(path) = workdir.join(script)
+    {
+        accesses.push(ImplicitSkillAccess::Script(path));
+    }
+
+    for parsed in parse_command_impl(&tokens) {
+        if let ParsedCommand::Read { path, .. } = parsed
+            && let Some(path) = path.to_str()
+            && let Ok(path) = workdir.join(path)
+        {
+            accesses.push(ImplicitSkillAccess::Document(path));
+        }
+    }
+
+    accesses
+}
+
+fn tokenize_command(command: &str) -> Vec<String> {
+    shlex::split(command)
+        .unwrap_or_else(|| command.split_whitespace().map(str::to_string).collect())
+}
+
+fn script_run_token(tokens: &[String]) -> Option<&str> {
+    const RUNNERS: [&str; 10] = [
+        "python", "python3", "bash", "zsh", "sh", "node", "deno", "ruby", "perl", "pwsh",
+    ];
+    const SCRIPT_EXTENSIONS: [&str; 7] = [".py", ".sh", ".js", ".ts", ".rb", ".pl", ".ps1"];
+
+    let runner_token = tokens.first()?;
+    let runner = command_basename(runner_token).to_ascii_lowercase();
+    let runner = runner.strip_suffix(".exe").unwrap_or(&runner);
+    if !RUNNERS.contains(&runner) {
+        return None;
+    }
+
+    let mut script_token = None;
+    for token in tokens.iter().skip(1) {
+        if token == "--" || token.starts_with('-') {
+            continue;
+        }
+        script_token = Some(token.as_str());
+        break;
+    }
+    let script_token = script_token?;
+    if SCRIPT_EXTENSIONS
+        .iter()
+        .any(|extension| script_token.to_ascii_lowercase().ends_with(extension))
+    {
+        return Some(script_token);
+    }
+
+    None
+}
+
+fn detect_skill_script_run(
+    outcome: &impl ImplicitSkillLookup,
+    tokens: &[String],
+    workdir: &AbsolutePathBuf,
+) -> Option<SkillMetadata> {
+    let script_token = script_run_token(tokens)?;
+    let script_path = Path::new(script_token);
+    let script_path = canonicalize_if_exists(&workdir.join(script_path));
+
+    for path in script_path.ancestors() {
+        if let Some(candidate) = outcome.implicit_skill_for_scripts_dir(&path) {
+            return Some(candidate.clone());
+        }
+    }
+
+    None
+}
+
+fn detect_skill_doc_read(
+    outcome: &impl ImplicitSkillLookup,
+    tokens: &[String],
+    workdir: &AbsolutePathBuf,
+) -> Option<SkillMetadata> {
+    for command in parse_command_impl(tokens) {
+        if let ParsedCommand::Read { path, .. } = command {
+            let candidate_path = canonicalize_if_exists(&workdir.join(path.as_path()));
+            if let Some(candidate) = outcome.implicit_skill_for_doc_path(&candidate_path) {
+                return Some(candidate.clone());
+            }
+        }
+    }
+
+    None
+}
+
+fn command_basename(command: &str) -> String {
+    Path::new(command)
+        .file_name()
+        .and_then(|name| name.to_str())
+        .unwrap_or(command)
+        .to_string()
+}
+
+fn canonicalize_if_exists(path: &AbsolutePathBuf) -> AbsolutePathBuf {
+    path.canonicalize().unwrap_or_else(|_| path.clone())
+}
+
+#[cfg(test)]
+#[path = "invocation_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/invocation_tests.rs b/codex-rs/skills/src/invocation_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6d946d893cb789294bd78c482b5163255ac04e3e
--- /dev/null
+++ b/codex-rs/skills/src/invocation_tests.rs
@@ -0,0 +1,216 @@
+use std::collections::HashMap;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+
+use super::*;
+
+#[derive(Default)]
+struct TestLookup {
+    by_scripts_dir: HashMap<AbsolutePathBuf, SkillMetadata>,
+    by_doc_path: HashMap<AbsolutePathBuf, SkillMetadata>,
+}
+
+impl ImplicitSkillLookup for TestLookup {
+    fn implicit_skill_for_scripts_dir(&self, path: &AbsolutePathBuf) -> Option<&SkillMetadata> {
+        self.by_scripts_dir.get(path)
+    }
+
+    fn implicit_skill_for_doc_path(&self, path: &AbsolutePathBuf) -> Option<&SkillMetadata> {
+        self.by_doc_path.get(path)
+    }
+}
+
+fn test_skill_metadata(skill_doc_path: AbsolutePathBuf) -> SkillMetadata {
+    SkillMetadata {
+        name: "test-skill".to_string(),
+        description: "test".to_string(),
+        short_description: None,
+        interface: None,
+        dependencies: None,
+        policy: None,
+        path_to_skills_md: skill_doc_path,
+        scope: codex_protocol::protocol::SkillScope::User,
+        plugin_id: None,
+        remote_plugin_id: None,
+    }
+}
+
+fn test_path_display(unix_path: &str) -> String {
+    test_path_buf(unix_path).display().to_string()
+}
+
+#[test]
+fn script_run_detection_matches_runner_plus_extension() {
+    let tokens = vec![
+        "python3".to_string(),
+        "-u".to_string(),
+        "scripts/fetch_comments.py".to_string(),
+    ];
+
+    assert!(script_run_token(&tokens).is_some());
+}
+
+#[test]
+fn script_run_detection_excludes_python_c() {
+    let tokens = vec![
+        "python3".to_string(),
+        "-c".to_string(),
+        "print(1)".to_string(),
+    ];
+
+    assert!(script_run_token(&tokens).is_none());
+}
+
+#[test]
+fn powershell_skill_doc_read_matches_common_forms() {
+    let skill_doc_path = test_path_buf("/tmp/skill-test/SKILL.md").abs();
+    let spaced_skill_doc_path = test_path_buf("/tmp/skill test/SKILL.md").abs();
+    let skill = test_skill_metadata(skill_doc_path.clone());
+    let spaced_skill = test_skill_metadata(spaced_skill_doc_path.clone());
+    let outcome = TestLookup {
+        by_doc_path: HashMap::from([
+            (canonicalize_if_exists(&skill_doc_path), skill),
+            (canonicalize_if_exists(&spaced_skill_doc_path), spaced_skill),
+        ]),
+        ..Default::default()
+    };
+    let path = skill_doc_path.display();
+    let spaced_path = spaced_skill_doc_path.display();
+
+    for command in [
+        format!("Get-Content {path}"),
+        format!("Get-Content -Raw {path}"),
+        format!("Get-Content \"{spaced_path}\""),
+        format!("Get-Content -Raw \"{spaced_path}\""),
+        format!("get-content   -raw '{spaced_path}'"),
+    ] {
+        let found = detect_implicit_skill_invocation_for_command(
+            &outcome,
+            &command,
+            &test_path_buf("/tmp").abs(),
+        );
+
+        assert_eq!(
+            found.map(|value| value.name),
+            Some("test-skill".to_string()),
+            "command: {command}"
+        );
+    }
+}
+
+#[test]
+fn windows_executor_skill_reads_share_powershell_classification() {
+    let workdir = PathUri::parse("file:///C:/skills").expect("Windows workdir URI");
+    let document = PathUri::parse("file:///C:/skills/demo/SKILL.md").expect("skill URI");
+
+    for command in [
+        r"Get-Content C:\skills\demo\SKILL.md",
+        r"get-content -Raw C:\skills\demo\SKILL.md",
+        r"Get-Content -Path C:\skills\demo\SKILL.md",
+        r"Get-Content -LiteralPath C:\skills\demo\SKILL.md",
+        r"Get-Content C:\skills\demo\SKILL.md -Raw",
+        r"Get-Content -Raw -LiteralPath C:\skills\demo\SKILL.md",
+        r"gc C:\skills\demo\SKILL.md",
+        r"type C:\skills\demo\SKILL.md",
+    ] {
+        assert_eq!(
+            implicit_skill_accesses_for_command(command, &workdir),
+            vec![ImplicitSkillAccess::Document(document.clone())],
+            "command: {command}"
+        );
+    }
+}
+
+#[test]
+fn skill_doc_read_detection_matches_absolute_path() {
+    let skill_doc_path = test_path_buf("/tmp/skill-test/SKILL.md").abs();
+    let normalized_skill_doc_path = canonicalize_if_exists(&skill_doc_path);
+    let skill = test_skill_metadata(skill_doc_path);
+    let outcome = TestLookup {
+        by_doc_path: HashMap::from([(normalized_skill_doc_path, skill)]),
+        ..Default::default()
+    };
+    let tokens = vec![
+        "cat".to_string(),
+        test_path_display("/tmp/skill-test/SKILL.md"),
+        "|".to_string(),
+        "head".to_string(),
+    ];
+
+    let found = detect_skill_doc_read(&outcome, &tokens, &test_path_buf("/tmp").abs());
+
+    assert_eq!(
+        found.map(|value| value.name),
+        Some("test-skill".to_string())
+    );
+}
+
+#[test]
+fn skill_doc_read_detection_matches_shared_read_parser() {
+    let skill_doc_path = test_path_buf("/tmp/skill-test/SKILL.md").abs();
+    let normalized_skill_doc_path = canonicalize_if_exists(&skill_doc_path);
+    let skill = test_skill_metadata(skill_doc_path);
+    let outcome = TestLookup {
+        by_doc_path: HashMap::from([(normalized_skill_doc_path, skill)]),
+        ..Default::default()
+    };
+    let tokens = vec![
+        "nl".to_string(),
+        "-ba".to_string(),
+        test_path_display("/tmp/skill-test/SKILL.md"),
+    ];
+
+    let found = detect_skill_doc_read(&outcome, &tokens, &test_path_buf("/tmp").abs());
+
+    assert_eq!(
+        found.map(|value| value.name),
+        Some("test-skill".to_string())
+    );
+}
+
+#[test]
+fn skill_script_run_detection_matches_relative_path_from_skill_root() {
+    let skill_doc_path = test_path_buf("/tmp/skill-test/SKILL.md").abs();
+    let scripts_dir = canonicalize_if_exists(&test_path_buf("/tmp/skill-test/scripts").abs());
+    let skill = test_skill_metadata(skill_doc_path);
+    let outcome = TestLookup {
+        by_scripts_dir: HashMap::from([(scripts_dir, skill)]),
+        ..Default::default()
+    };
+    let tokens = vec![
+        "python3".to_string(),
+        "scripts/fetch_comments.py".to_string(),
+    ];
+
+    let found = detect_skill_script_run(&outcome, &tokens, &test_path_buf("/tmp/skill-test").abs());
+
+    assert_eq!(
+        found.map(|value| value.name),
+        Some("test-skill".to_string())
+    );
+}
+
+#[test]
+fn skill_script_run_detection_matches_absolute_path_from_any_workdir() {
+    let skill_doc_path = test_path_buf("/tmp/skill-test/SKILL.md").abs();
+    let scripts_dir = canonicalize_if_exists(&test_path_buf("/tmp/skill-test/scripts").abs());
+    let skill = test_skill_metadata(skill_doc_path);
+    let outcome = TestLookup {
+        by_scripts_dir: HashMap::from([(scripts_dir, skill)]),
+        ..Default::default()
+    };
+    let tokens = vec![
+        "python3".to_string(),
+        test_path_display("/tmp/skill-test/scripts/fetch_comments.py"),
+    ];
+
+    let found = detect_skill_script_run(&outcome, &tokens, &test_path_buf("/tmp/other").abs());
+
+    assert_eq!(
+        found.map(|value| value.name),
+        Some("test-skill".to_string())
+    );
+}
diff --git a/codex-rs/skills/src/lib.rs b/codex-rs/skills/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7b19d3278864ff7fff0cfc3db087914c0652d4c1
--- /dev/null
+++ b/codex-rs/skills/src/lib.rs
@@ -0,0 +1,214 @@
+mod interface;
+mod invocation;
+mod loading;
+mod mentions;
+mod model;
+mod name_counts;
+mod parser;
+mod selection;
+
+pub use interface::SkillInterfaceAssetPolicy;
+pub use interface::SkillInterfaceFile;
+pub use interface::resolve_skill_interface;
+pub use invocation::ImplicitSkillAccess;
+pub use invocation::ImplicitSkillLookup;
+pub use invocation::detect_implicit_skill_invocation_for_command;
+pub use invocation::implicit_skill_accesses_for_command;
+pub use loading::LoadedSkillRoot;
+pub use loading::LoadedSkills;
+pub use loading::SkillError;
+pub use loading::SkillLoadFuture;
+pub use loading::SkillRootLoadRequest;
+pub use loading::SkillRootLoader;
+pub use loading::SkillRootSnapshotCache;
+pub use loading::SkillRootSnapshots;
+pub use mentions::ToolMentionKind;
+pub use mentions::ToolMentions;
+pub use mentions::app_id_from_path;
+pub use mentions::extract_tool_mentions;
+pub use mentions::extract_tool_mentions_with_sigil;
+pub use mentions::normalize_skill_path;
+pub use mentions::plugin_config_name_from_path;
+pub use mentions::tool_kind_for_path;
+pub use model::EnvironmentSkillMetadata;
+pub use model::SkillDependencies;
+pub use model::SkillInterface;
+pub use model::SkillMetadata;
+pub use model::SkillPolicy;
+pub use model::SkillToolDependency;
+pub use name_counts::build_skill_name_counts;
+pub use parser::ParsedSkillFrontmatter;
+pub use parser::SkillParseError;
+pub use parser::parse_skill_frontmatter_metadata;
+pub use selection::ExplicitSkillLookup;
+pub use selection::collect_explicit_skill_mentions;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+use include_dir::Dir;
+use std::collections::hash_map::DefaultHasher;
+use std::fs;
+use std::hash::Hash;
+use std::hash::Hasher;
+
+use thiserror::Error;
+
+const SYSTEM_SKILLS_DIR: Dir = include_dir::include_dir!("$CARGO_MANIFEST_DIR/src/assets/samples");
+
+const SYSTEM_SKILLS_DIR_NAME: &str = ".system";
+const SKILLS_DIR_NAME: &str = "skills";
+const SYSTEM_SKILLS_MARKER_FILENAME: &str = ".codex-system-skills.marker";
+const SYSTEM_SKILLS_MARKER_SALT: &str = "v1";
+
+/// Returns the on-disk cache location for embedded system skills from an absolute CODEX_HOME.
+pub fn system_cache_root_dir(codex_home: &AbsolutePathBuf) -> AbsolutePathBuf {
+    codex_home
+        .join(SKILLS_DIR_NAME)
+        .join(SYSTEM_SKILLS_DIR_NAME)
+}
+
+/// Installs embedded system skills into `CODEX_HOME/skills/.system`.
+///
+/// Clears any existing system skills directory first and then writes the embedded
+/// skills directory into place.
+///
+/// To avoid doing unnecessary work on every startup, a marker file is written
+/// with a fingerprint of the embedded directory. When the marker matches, the
+/// install is skipped.
+pub fn install_system_skills(codex_home: &AbsolutePathBuf) -> Result<(), SystemSkillsError> {
+    let skills_root_dir = codex_home.join(SKILLS_DIR_NAME);
+    fs::create_dir_all(skills_root_dir.as_path())
+        .map_err(|source| SystemSkillsError::io("create skills root dir", source))?;
+
+    let dest_system = system_cache_root_dir(codex_home);
+
+    let marker_path = dest_system.join(SYSTEM_SKILLS_MARKER_FILENAME);
+    let expected_fingerprint = embedded_system_skills_fingerprint();
+    if dest_system.as_path().is_dir()
+        && read_marker(&marker_path).is_ok_and(|marker| marker == expected_fingerprint)
+    {
+        return Ok(());
+    }
+
+    if dest_system.as_path().exists() {
+        fs::remove_dir_all(dest_system.as_path())
+            .map_err(|source| SystemSkillsError::io("remove existing system skills dir", source))?;
+    }
+
+    write_embedded_dir(&SYSTEM_SKILLS_DIR, &dest_system)?;
+    fs::write(marker_path.as_path(), format!("{expected_fingerprint}\n"))
+        .map_err(|source| SystemSkillsError::io("write system skills marker", source))?;
+    Ok(())
+}
+
+fn read_marker(path: &AbsolutePathBuf) -> Result<String, SystemSkillsError> {
+    Ok(fs::read_to_string(path.as_path())
+        .map_err(|source| SystemSkillsError::io("read system skills marker", source))?
+        .trim()
+        .to_string())
+}
+
+fn embedded_system_skills_fingerprint() -> String {
+    let mut items = Vec::new();
+    collect_fingerprint_items(&SYSTEM_SKILLS_DIR, &mut items);
+    items.sort_unstable_by(|(a, _), (b, _)| a.cmp(b));
+
+    let mut hasher = DefaultHasher::new();
+    SYSTEM_SKILLS_MARKER_SALT.hash(&mut hasher);
+    for (path, contents_hash) in items {
+        path.hash(&mut hasher);
+        contents_hash.hash(&mut hasher);
+    }
+    format!("{:x}", hasher.finish())
+}
+
+fn collect_fingerprint_items(dir: &Dir<'_>, items: &mut Vec<(String, Option<u64>)>) {
+    for entry in dir.entries() {
+        match entry {
+            include_dir::DirEntry::Dir(subdir) => {
+                items.push((subdir.path().to_string_lossy().to_string(), None));
+                collect_fingerprint_items(subdir, items);
+            }
+            include_dir::DirEntry::File(file) => {
+                let mut file_hasher = DefaultHasher::new();
+                file.contents().hash(&mut file_hasher);
+                items.push((
+                    file.path().to_string_lossy().to_string(),
+                    Some(file_hasher.finish()),
+                ));
+            }
+        }
+    }
+}
+
+/// Writes the embedded `include_dir::Dir` to disk under `dest`.
+///
+/// Preserves the embedded directory structure.
+fn write_embedded_dir(dir: &Dir<'_>, dest: &AbsolutePathBuf) -> Result<(), SystemSkillsError> {
+    fs::create_dir_all(dest.as_path())
+        .map_err(|source| SystemSkillsError::io("create system skills dir", source))?;
+
+    for entry in dir.entries() {
+        match entry {
+            include_dir::DirEntry::Dir(subdir) => {
+                let subdir_dest = dest.join(subdir.path());
+                fs::create_dir_all(subdir_dest.as_path()).map_err(|source| {
+                    SystemSkillsError::io("create system skills subdir", source)
+                })?;
+                write_embedded_dir(subdir, dest)?;
+            }
+            include_dir::DirEntry::File(file) => {
+                let path = dest.join(file.path());
+                if let Some(parent) = path.as_path().parent() {
+                    fs::create_dir_all(parent).map_err(|source| {
+                        SystemSkillsError::io("create system skills file parent", source)
+                    })?;
+                }
+                fs::write(path.as_path(), file.contents())
+                    .map_err(|source| SystemSkillsError::io("write system skill file", source))?;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[derive(Debug, Error)]
+pub enum SystemSkillsError {
+    #[error("io error while {action}: {source}")]
+    Io {
+        action: &'static str,
+        #[source]
+        source: std::io::Error,
+    },
+}
+
+impl SystemSkillsError {
+    fn io(action: &'static str, source: std::io::Error) -> Self {
+        Self::Io { action, source }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::SYSTEM_SKILLS_DIR;
+    use super::collect_fingerprint_items;
+
+    #[test]
+    fn fingerprint_traverses_nested_entries() {
+        let mut items = Vec::new();
+        collect_fingerprint_items(&SYSTEM_SKILLS_DIR, &mut items);
+        let mut paths: Vec<String> = items.into_iter().map(|(path, _)| path).collect();
+        paths.sort_unstable();
+
+        assert!(
+            paths
+                .binary_search_by(|probe| probe.as_str().cmp("skill-creator/SKILL.md"))
+                .is_ok()
+        );
+        assert!(
+            paths
+                .binary_search_by(|probe| probe.as_str().cmp("skill-creator/scripts/init_skill.py"))
+                .is_ok()
+        );
+    }
+}
diff --git a/codex-rs/skills/src/loading.rs b/codex-rs/skills/src/loading.rs
new file mode 100644
index 0000000000000000000000000000000000000000..59458b241774a79e461066db69ed0a900fcc2a7b
--- /dev/null
+++ b/codex-rs/skills/src/loading.rs
@@ -0,0 +1,119 @@
+use std::collections::HashMap;
+use std::fmt;
+use std::future::Future;
+use std::hash::Hash;
+use std::hash::Hasher;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use codex_protocol::protocol::Product;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use crate::SkillMetadata;
+
+/// A skill document that could not be read, parsed, or validated.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SkillError {
+    pub path: AbsolutePathBuf,
+    pub message: String,
+}
+
+/// Filesystem-independent metadata discovered beneath one canonical skill root.
+#[derive(Debug, Clone, PartialEq)]
+pub struct LoadedSkillRoot {
+    pub root: AbsolutePathBuf,
+    pub skills: Vec<SkillMetadata>,
+    pub skill_discovery_path_by_path: Arc<HashMap<AbsolutePathBuf, AbsolutePathBuf>>,
+    pub errors: Vec<SkillError>,
+    pub is_agent_plugin: bool,
+}
+
+/// Skills and errors produced by loading an ordered set of roots.
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct LoadedSkills {
+    pub skills: Vec<SkillMetadata>,
+    pub errors: Vec<SkillError>,
+}
+
+/// Caches parsed roots without assigning ownership of the cache to a loader.
+///
+/// Implementations own storage and determine its lifetime; loaders may reuse an existing snapshot
+/// or publish a newly loaded one without learning about the caller's broader state.
+pub trait SkillRootSnapshotCache<Root>: Send + Sync {
+    fn get(&self, root: &Root) -> Option<LoadedSkillRoot>;
+
+    fn insert(&self, root: Root, snapshot: LoadedSkillRoot);
+}
+
+/// Shared access to one owner-managed collection of parsed skill roots.
+///
+/// Equality and hashing use the cache allocation's identity so callers can include the handle in
+/// their own cache keys without inspecting or taking ownership of its contents.
+pub struct SkillRootSnapshots<Root> {
+    cache: Arc<dyn SkillRootSnapshotCache<Root>>,
+}
+
+impl<Root> SkillRootSnapshots<Root> {
+    pub fn new(cache: Arc<dyn SkillRootSnapshotCache<Root>>) -> Self {
+        Self { cache }
+    }
+
+    pub fn get(&self, root: &Root) -> Option<LoadedSkillRoot> {
+        self.cache.get(root)
+    }
+
+    pub fn insert(&self, root: Root, snapshot: LoadedSkillRoot) {
+        self.cache.insert(root, snapshot);
+    }
+}
+
+impl<Root> Clone for SkillRootSnapshots<Root> {
+    fn clone(&self) -> Self {
+        Self {
+            cache: Arc::clone(&self.cache),
+        }
+    }
+}
+
+impl<Root> PartialEq for SkillRootSnapshots<Root> {
+    fn eq(&self, other: &Self) -> bool {
+        Arc::ptr_eq(&self.cache, &other.cache)
+    }
+}
+
+impl<Root> Eq for SkillRootSnapshots<Root> {}
+
+impl<Root> Hash for SkillRootSnapshots<Root> {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        (Arc::as_ptr(&self.cache) as *const ()).hash(state);
+    }
+}
+
+impl<Root> fmt::Debug for SkillRootSnapshots<Root> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("SkillRootSnapshots").finish_non_exhaustive()
+    }
+}
+
+/// Inputs for loading roots while optionally reusing snapshots owned by the caller.
+#[derive(Debug, Clone)]
+pub struct SkillRootLoadRequest<Root> {
+    pub roots: Vec<Root>,
+    pub restriction_product: Option<Product>,
+    pub snapshots: Option<SkillRootSnapshots<Root>>,
+}
+
+/// Object-safe future returned by a shared skill-root loader.
+pub type SkillLoadFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
+
+/// Loads ordered skill roots without owning their source inventory or capability state.
+///
+/// Implementations are responsible for filesystem access, metadata parsing, root precedence,
+/// product filtering, and reuse of any snapshots supplied in the request.
+pub trait SkillRootLoader<Root>: Send + Sync {
+    fn load_roots(&self, request: SkillRootLoadRequest<Root>) -> SkillLoadFuture<'_, LoadedSkills>;
+}
+
+#[cfg(test)]
+#[path = "loading_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/loading_tests.rs b/codex-rs/skills/src/loading_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4abad3be02c8e37ef416eaca9b67c94d3baea70f
--- /dev/null
+++ b/codex-rs/skills/src/loading_tests.rs
@@ -0,0 +1,79 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::sync::Arc;
+use std::sync::Mutex;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+
+use super::LoadedSkillRoot;
+use super::LoadedSkills;
+use super::SkillLoadFuture;
+use super::SkillRootLoadRequest;
+use super::SkillRootLoader;
+use super::SkillRootSnapshotCache;
+use super::SkillRootSnapshots;
+
+#[derive(Default)]
+struct TestSnapshotCache {
+    snapshots: Mutex<HashMap<String, LoadedSkillRoot>>,
+}
+
+impl SkillRootSnapshotCache<String> for TestSnapshotCache {
+    fn get(&self, root: &String) -> Option<LoadedSkillRoot> {
+        self.snapshots.lock().unwrap().get(root).cloned()
+    }
+
+    fn insert(&self, root: String, snapshot: LoadedSkillRoot) {
+        self.snapshots.lock().unwrap().insert(root, snapshot);
+    }
+}
+
+struct TestSkillRootLoader;
+
+impl SkillRootLoader<String> for TestSkillRootLoader {
+    fn load_roots(
+        &self,
+        _request: SkillRootLoadRequest<String>,
+    ) -> SkillLoadFuture<'_, LoadedSkills> {
+        Box::pin(async { LoadedSkills::default() })
+    }
+}
+
+#[test]
+fn snapshot_handles_share_owner_managed_values_and_identity() {
+    let snapshots = SkillRootSnapshots::new(Arc::new(TestSnapshotCache::default()));
+    let cloned_snapshots = snapshots.clone();
+    let separate_snapshots = SkillRootSnapshots::new(Arc::new(TestSnapshotCache::default()));
+    let root = "plugin-root".to_string();
+    let snapshot = LoadedSkillRoot {
+        root: AbsolutePathBuf::try_from(std::env::temp_dir()).unwrap(),
+        skills: Vec::new(),
+        skill_discovery_path_by_path: Arc::new(HashMap::new()),
+        errors: Vec::new(),
+        is_agent_plugin: false,
+    };
+
+    snapshots.insert(root.clone(), snapshot.clone());
+
+    assert_eq!(cloned_snapshots.get(&root), Some(snapshot));
+    assert_eq!(separate_snapshots.get(&root), None);
+    assert_eq!(snapshots, cloned_snapshots);
+    assert_ne!(snapshots, separate_snapshots);
+    assert_eq!(
+        HashSet::from([snapshots, cloned_snapshots, separate_snapshots]).len(),
+        2
+    );
+}
+
+#[test]
+fn skill_root_loader_supports_shared_trait_objects() {
+    let loader: Arc<dyn SkillRootLoader<String>> = Arc::new(TestSkillRootLoader);
+    let future = loader.load_roots(SkillRootLoadRequest {
+        roots: vec!["plugin-root".to_string()],
+        restriction_product: None,
+        snapshots: None,
+    });
+
+    drop(future);
+}
diff --git a/codex-rs/skills/src/mentions.rs b/codex-rs/skills/src/mentions.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1f391235d1ede003f6edfc8c93fddc2925650dbe
--- /dev/null
+++ b/codex-rs/skills/src/mentions.rs
@@ -0,0 +1,232 @@
+use std::collections::HashSet;
+
+pub struct ToolMentions<'a> {
+    names: HashSet<&'a str>,
+    paths: HashSet<&'a str>,
+    plain_names: HashSet<&'a str>,
+}
+
+impl<'a> ToolMentions<'a> {
+    pub fn is_empty(&self) -> bool {
+        self.names.is_empty() && self.paths.is_empty()
+    }
+
+    pub fn plain_names(&self) -> impl Iterator<Item = &'a str> + '_ {
+        self.plain_names.iter().copied()
+    }
+
+    pub fn contains_plain_name(&self, name: &str) -> bool {
+        self.plain_names.contains(name)
+    }
+
+    pub fn paths(&self) -> impl Iterator<Item = &'a str> + '_ {
+        self.paths.iter().copied()
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ToolMentionKind {
+    App,
+    Mcp,
+    Plugin,
+    Skill,
+    Other,
+}
+
+const APP_PATH_PREFIX: &str = "app://";
+const MCP_PATH_PREFIX: &str = "mcp://";
+const PLUGIN_PATH_PREFIX: &str = "plugin://";
+const SKILL_PATH_PREFIX: &str = "skill://";
+const SKILL_FILENAME: &str = "SKILL.md";
+const TOOL_MENTION_SIGIL: char = '$';
+
+pub fn tool_kind_for_path(path: &str) -> ToolMentionKind {
+    if path.starts_with(APP_PATH_PREFIX) {
+        ToolMentionKind::App
+    } else if path.starts_with(MCP_PATH_PREFIX) {
+        ToolMentionKind::Mcp
+    } else if path.starts_with(PLUGIN_PATH_PREFIX) {
+        ToolMentionKind::Plugin
+    } else if path.starts_with(SKILL_PATH_PREFIX) || is_skill_filename(path) {
+        ToolMentionKind::Skill
+    } else {
+        ToolMentionKind::Other
+    }
+}
+
+fn is_skill_filename(path: &str) -> bool {
+    let file_name = path.rsplit(['/', '\\']).next().unwrap_or(path);
+    file_name.eq_ignore_ascii_case(SKILL_FILENAME)
+}
+
+pub fn app_id_from_path(path: &str) -> Option<&str> {
+    path.strip_prefix(APP_PATH_PREFIX)
+        .filter(|value| !value.is_empty())
+}
+
+/// Desktop app/browser mentions append `?app=...` or `?browserFamily=...`.
+/// Ignore these targeting parameters when matching the plugin ID.
+pub fn plugin_config_name_from_path(path: &str) -> Option<&str> {
+    path.strip_prefix(PLUGIN_PATH_PREFIX)
+        .and_then(|value| value.split('?').next())
+        .filter(|value| !value.is_empty())
+}
+
+pub fn normalize_skill_path(path: &str) -> &str {
+    path.strip_prefix(SKILL_PATH_PREFIX).unwrap_or(path)
+}
+
+/// Extract `$tool-name` mentions from a single text input.
+///
+/// Supports explicit resource links in the form `[$tool-name](resource path)`. When a
+/// resource path is present, it is captured for exact path matching while also tracking
+/// the name for fallback matching.
+pub fn extract_tool_mentions(text: &str) -> ToolMentions<'_> {
+    extract_tool_mentions_with_sigil(text, TOOL_MENTION_SIGIL)
+}
+
+pub fn extract_tool_mentions_with_sigil(text: &str, sigil: char) -> ToolMentions<'_> {
+    let text_bytes = text.as_bytes();
+    let mut mentioned_names: HashSet<&str> = HashSet::new();
+    let mut mentioned_paths: HashSet<&str> = HashSet::new();
+    let mut plain_names: HashSet<&str> = HashSet::new();
+
+    let mut index = 0;
+    while index < text_bytes.len() {
+        let byte = text_bytes[index];
+        if byte == b'['
+            && let Some((name, path, end_index)) =
+                parse_linked_tool_mention(text, text_bytes, index, sigil)
+        {
+            if !is_common_env_var(name) {
+                if !matches!(
+                    tool_kind_for_path(path),
+                    ToolMentionKind::App | ToolMentionKind::Mcp | ToolMentionKind::Plugin
+                ) {
+                    mentioned_names.insert(name);
+                }
+                mentioned_paths.insert(path);
+            }
+            index = end_index;
+            continue;
+        }
+
+        if byte != sigil as u8 {
+            index += 1;
+            continue;
+        }
+
+        let name_start = index + 1;
+        let Some(first_name_byte) = text_bytes.get(name_start) else {
+            index += 1;
+            continue;
+        };
+        if !is_mention_name_char(*first_name_byte) {
+            index += 1;
+            continue;
+        }
+
+        let mut name_end = name_start + 1;
+        while let Some(next_byte) = text_bytes.get(name_end)
+            && is_mention_name_char(*next_byte)
+        {
+            name_end += 1;
+        }
+
+        let name = &text[name_start..name_end];
+        if !is_common_env_var(name) {
+            mentioned_names.insert(name);
+            plain_names.insert(name);
+        }
+        index = name_end;
+    }
+
+    ToolMentions {
+        names: mentioned_names,
+        paths: mentioned_paths,
+        plain_names,
+    }
+}
+
+fn parse_linked_tool_mention<'a>(
+    text: &'a str,
+    text_bytes: &[u8],
+    start: usize,
+    sigil: char,
+) -> Option<(&'a str, &'a str, usize)> {
+    let sigil_index = start + 1;
+    if text_bytes.get(sigil_index) != Some(&(sigil as u8)) {
+        return None;
+    }
+
+    let name_start = sigil_index + 1;
+    let first_name_byte = text_bytes.get(name_start)?;
+    if !is_mention_name_char(*first_name_byte) {
+        return None;
+    }
+
+    let mut name_end = name_start + 1;
+    while let Some(next_byte) = text_bytes.get(name_end)
+        && is_mention_name_char(*next_byte)
+    {
+        name_end += 1;
+    }
+
+    if text_bytes.get(name_end) != Some(&b']') {
+        return None;
+    }
+
+    let mut path_start = name_end + 1;
+    while let Some(next_byte) = text_bytes.get(path_start)
+        && next_byte.is_ascii_whitespace()
+    {
+        path_start += 1;
+    }
+    if text_bytes.get(path_start) != Some(&b'(') {
+        return None;
+    }
+
+    let mut path_end = path_start + 1;
+    while let Some(next_byte) = text_bytes.get(path_end)
+        && *next_byte != b')'
+    {
+        path_end += 1;
+    }
+    if text_bytes.get(path_end) != Some(&b')') {
+        return None;
+    }
+
+    let path = text[path_start + 1..path_end].trim();
+    if path.is_empty() {
+        return None;
+    }
+
+    let name = &text[name_start..name_end];
+    Some((name, path, path_end + 1))
+}
+
+fn is_common_env_var(name: &str) -> bool {
+    let upper = name.to_ascii_uppercase();
+    matches!(
+        upper.as_str(),
+        "PATH"
+            | "HOME"
+            | "USER"
+            | "SHELL"
+            | "PWD"
+            | "TMPDIR"
+            | "TEMP"
+            | "TMP"
+            | "LANG"
+            | "TERM"
+            | "XDG_CONFIG_HOME"
+    )
+}
+
+fn is_mention_name_char(byte: u8) -> bool {
+    matches!(byte, b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9' | b'_' | b'-' | b':')
+}
+
+#[cfg(test)]
+#[path = "mentions_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/mentions_tests.rs b/codex-rs/skills/src/mentions_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bdf88748212d17a4c63dfd094f00f5ad527439de
--- /dev/null
+++ b/codex-rs/skills/src/mentions_tests.rs
@@ -0,0 +1,105 @@
+use std::collections::HashSet;
+
+use pretty_assertions::assert_eq;
+
+use super::*;
+
+fn set<'a>(items: &'a [&'a str]) -> HashSet<&'a str> {
+    items.iter().copied().collect()
+}
+
+fn assert_mentions(text: &str, expected_names: &[&str], expected_paths: &[&str]) {
+    let mentions = extract_tool_mentions(text);
+    assert_eq!(mentions.names, set(expected_names));
+    assert_eq!(mentions.paths, set(expected_paths));
+}
+
+#[test]
+fn handles_plain_and_linked_mentions() {
+    assert_mentions(
+        "use $alpha and [$beta](/tmp/beta)",
+        &["alpha", "beta"],
+        &["/tmp/beta"],
+    );
+}
+
+#[test]
+fn skips_common_env_vars() {
+    assert_mentions("use $PATH and $alpha", &["alpha"], &[]);
+    assert_mentions("use [$HOME](/tmp/skill)", &[], &[]);
+    assert_mentions("use $XDG_CONFIG_HOME and $beta", &["beta"], &[]);
+}
+
+#[test]
+fn requires_link_syntax() {
+    assert_mentions("[beta](/tmp/beta)", &[], &[]);
+    assert_mentions("[$beta] /tmp/beta", &["beta"], &[]);
+    assert_mentions("[$beta]()", &["beta"], &[]);
+}
+
+#[test]
+fn trims_linked_paths_and_allows_spacing() {
+    assert_mentions("use [$beta]   ( /tmp/beta )", &["beta"], &["/tmp/beta"]);
+}
+
+#[test]
+fn stops_at_non_name_chars() {
+    assert_mentions(
+        "use $alpha.skill and $beta_extra",
+        &["alpha", "beta_extra"],
+        &[],
+    );
+}
+
+#[test]
+fn keeps_plugin_skill_namespaces() {
+    assert_mentions(
+        "use $slack:search and $alpha",
+        &["alpha", "slack:search"],
+        &[],
+    );
+}
+
+#[test]
+fn requires_exact_name_boundaries() {
+    assert_mentions(
+        "use $notion-research-doc but not $notion-research-docs or $notion-research-doc_extra",
+        &[
+            "notion-research-doc",
+            "notion-research-docs",
+            "notion-research-doc_extra",
+        ],
+        &[],
+    );
+}
+
+#[test]
+fn handles_many_sigils_without_looping() {
+    let prefix = "$".repeat(256);
+    assert_mentions(&format!("{prefix} not-a-mention"), &[], &[]);
+}
+
+#[test]
+fn plugin_config_names_ignore_mention_query_parameters() {
+    let paths = [
+        "plugin://sample@test",
+        "plugin://sample@test?app=com.example.editor",
+        "plugin://sample@test?browserFamily=chrome",
+    ];
+
+    assert_eq!(
+        paths.map(plugin_config_name_from_path),
+        [Some("sample@test"); 3],
+    );
+}
+
+#[test]
+fn plugin_config_names_require_a_plugin_identity() {
+    let paths = [
+        "plugin://",
+        "plugin://?app=com.example.editor",
+        "app://sample@test?app=com.example.editor",
+    ];
+
+    assert_eq!(paths.map(plugin_config_name_from_path), [None; 3]);
+}
diff --git a/codex-rs/skills/src/model.rs b/codex-rs/skills/src/model.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a47ce1dd960a354d75147ea4d75c47a5205a8673
--- /dev/null
+++ b/codex-rs/skills/src/model.rs
@@ -0,0 +1,112 @@
+use codex_protocol::protocol::Product;
+use codex_protocol::protocol::SkillScope;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_path_uri::PathUri;
+
+/// Metadata for one skill materialized on the host filesystem.
+#[derive(Debug, Clone, PartialEq)]
+pub struct SkillMetadata {
+    pub name: String,
+    pub description: String,
+    pub short_description: Option<String>,
+    pub interface: Option<SkillInterface>,
+    pub dependencies: Option<SkillDependencies>,
+    pub policy: Option<SkillPolicy>,
+    /// Path to the SKILL.md file that declares this skill.
+    pub path_to_skills_md: AbsolutePathBuf,
+    pub scope: SkillScope,
+    pub plugin_id: Option<String>,
+    pub remote_plugin_id: Option<String>,
+}
+
+impl SkillMetadata {
+    pub fn allows_implicit_invocation(&self) -> bool {
+        self.policy
+            .as_ref()
+            .and_then(|policy| policy.allow_implicit_invocation)
+            .unwrap_or(true)
+    }
+
+    pub fn matches_product_restriction_for_product(
+        &self,
+        restriction_product: Option<Product>,
+    ) -> bool {
+        matches_product_restriction(self.policy.as_ref(), restriction_product)
+    }
+}
+
+/// URI-native metadata for one skill owned by an execution environment.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct EnvironmentSkillMetadata {
+    pub path_to_skills_md: PathUri,
+    pub name: String,
+    pub description: String,
+    pub short_description: Option<String>,
+    pub dependencies: Option<SkillDependencies>,
+    pub policy: Option<SkillPolicy>,
+}
+
+impl EnvironmentSkillMetadata {
+    pub fn allows_implicit_invocation(&self) -> bool {
+        self.policy
+            .as_ref()
+            .and_then(|policy| policy.allow_implicit_invocation)
+            .unwrap_or(true)
+    }
+
+    pub fn matches_product_restriction(&self, restriction_product: Option<Product>) -> bool {
+        matches_product_restriction(self.policy.as_ref(), restriction_product)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct SkillPolicy {
+    pub allow_implicit_invocation: Option<bool>,
+    // TODO: Enforce product gating in Codex skill selection/injection instead of only parsing and
+    // storing this metadata.
+    pub products: Vec<Product>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SkillInterface {
+    pub display_name: Option<String>,
+    pub short_description: Option<String>,
+    pub icon_small: Option<AbsolutePathBuf>,
+    pub icon_large: Option<AbsolutePathBuf>,
+    pub brand_color: Option<String>,
+    pub default_prompt: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SkillDependencies {
+    pub tools: Vec<SkillToolDependency>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SkillToolDependency {
+    pub r#type: String,
+    pub value: String,
+    pub description: Option<String>,
+    pub transport: Option<String>,
+    pub command: Option<String>,
+    pub url: Option<String>,
+    pub oauth_callback_port: Option<u16>,
+}
+
+fn matches_product_restriction(
+    policy: Option<&SkillPolicy>,
+    restriction_product: Option<Product>,
+) -> bool {
+    match policy {
+        Some(policy) => {
+            policy.products.is_empty()
+                || restriction_product
+                    .is_some_and(|product| product.matches_product_restriction(&policy.products))
+        }
+        None => true,
+    }
+}
+
+#[cfg(test)]
+#[path = "model_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/model_tests.rs b/codex-rs/skills/src/model_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0ec524ac7ba5e850f35e06deffb06ca0020ed135
--- /dev/null
+++ b/codex-rs/skills/src/model_tests.rs
@@ -0,0 +1,36 @@
+use super::*;
+
+#[test]
+fn missing_policy_allows_implicit_invocation_and_all_products() {
+    let skill = EnvironmentSkillMetadata {
+        path_to_skills_md: PathUri::parse("file:///skills/demo/SKILL.md").expect("valid skill URI"),
+        name: "demo".to_string(),
+        description: "Demo skill".to_string(),
+        short_description: None,
+        dependencies: None,
+        policy: None,
+    };
+
+    assert!(skill.allows_implicit_invocation());
+    assert!(skill.matches_product_restriction(/*restriction_product*/ None));
+}
+
+#[test]
+fn policy_restricts_implicit_invocation_and_products() {
+    let policy = SkillPolicy {
+        allow_implicit_invocation: Some(false),
+        products: vec![Product::Codex],
+    };
+    let skill = EnvironmentSkillMetadata {
+        path_to_skills_md: PathUri::parse("file:///skills/demo/SKILL.md").expect("valid skill URI"),
+        name: "demo".to_string(),
+        description: "Demo skill".to_string(),
+        short_description: None,
+        dependencies: None,
+        policy: Some(policy),
+    };
+
+    assert!(!skill.allows_implicit_invocation());
+    assert!(skill.matches_product_restriction(Some(Product::Codex)));
+    assert!(!skill.matches_product_restriction(/*restriction_product*/ None));
+}
diff --git a/codex-rs/skills/src/name_counts.rs b/codex-rs/skills/src/name_counts.rs
new file mode 100644
index 0000000000000000000000000000000000000000..78c9e13b305099a18bf6151b34d0cb137fbae1d6
--- /dev/null
+++ b/codex-rs/skills/src/name_counts.rs
@@ -0,0 +1,25 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use crate::SkillMetadata;
+
+/// Counts how often each skill name appears (exact and ASCII-lowercase), excluding disabled paths.
+pub fn build_skill_name_counts(
+    skills: &[SkillMetadata],
+    disabled_paths: &HashSet<AbsolutePathBuf>,
+) -> (HashMap<String, usize>, HashMap<String, usize>) {
+    let mut exact_counts: HashMap<String, usize> = HashMap::new();
+    let mut lower_counts: HashMap<String, usize> = HashMap::new();
+    for skill in skills {
+        if disabled_paths.contains(&skill.path_to_skills_md) {
+            continue;
+        }
+        *exact_counts.entry(skill.name.clone()).or_insert(0) += 1;
+        *lower_counts
+            .entry(skill.name.to_ascii_lowercase())
+            .or_insert(0) += 1;
+    }
+    (exact_counts, lower_counts)
+}
diff --git a/codex-rs/skills/src/parser.rs b/codex-rs/skills/src/parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..aef295cd03cc37ca712f1c62c1dbda07127a8277
--- /dev/null
+++ b/codex-rs/skills/src/parser.rs
@@ -0,0 +1,225 @@
+use serde::Deserialize;
+use thiserror::Error;
+
+const MAX_NAME_LEN: usize = 64;
+
+#[derive(Debug, Deserialize)]
+struct SkillFrontmatter {
+    #[serde(default)]
+    name: Option<String>,
+    #[serde(default)]
+    description: Option<String>,
+    #[serde(default)]
+    metadata: SkillFrontmatterMetadata,
+}
+
+#[derive(Debug, Default, Deserialize)]
+struct SkillFrontmatterMetadata {
+    #[serde(default, rename = "short-description")]
+    short_description: Option<String>,
+}
+
+/// Validated metadata parsed from a `SKILL.md` frontmatter block.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ParsedSkillFrontmatter {
+    pub name: String,
+    pub description: String,
+    pub short_description: Option<String>,
+}
+
+/// Error produced while parsing or validating `SKILL.md` metadata.
+#[derive(Debug, Error)]
+pub enum SkillParseError {
+    #[error("missing YAML frontmatter delimited by ---")]
+    MissingFrontmatter,
+    #[error("invalid YAML: {0}")]
+    InvalidYaml(#[source] serde_yaml::Error),
+    #[error("missing field `{0}`")]
+    MissingField(&'static str),
+    #[error("invalid {field}: {reason}")]
+    InvalidField { field: &'static str, reason: String },
+}
+
+/// Parses and validates the metadata frontmatter from `SKILL.md` contents.
+pub fn parse_skill_frontmatter_metadata(
+    contents: &str,
+    default_name: impl FnOnce() -> String,
+) -> Result<ParsedSkillFrontmatter, SkillParseError> {
+    let frontmatter = extract_frontmatter(contents).ok_or(SkillParseError::MissingFrontmatter)?;
+
+    let parsed: SkillFrontmatter = match serde_yaml::from_str(&frontmatter) {
+        Ok(parsed) => Ok(parsed),
+        Err(original_error) => match repair_frontmatter_scalar_fields(&frontmatter) {
+            // Some third-party skills use prose like `description: Build for AWS: ECS`
+            // or `argument-hint: <duration: e.g. 7d>`. Keep the repair line-oriented
+            // so unrelated invalid YAML still surfaces.
+            Some(repaired_frontmatter) => {
+                serde_yaml::from_str(&repaired_frontmatter).map_err(|_| original_error)
+            }
+            None => Err(original_error),
+        },
+    }
+    .map_err(SkillParseError::InvalidYaml)?;
+
+    let name = parsed
+        .name
+        .as_deref()
+        .map(sanitize_single_line)
+        .filter(|value| !value.is_empty())
+        .unwrap_or_else(default_name);
+    let description = parsed
+        .description
+        .as_deref()
+        .map(sanitize_single_line)
+        .unwrap_or_default();
+    let short_description = parsed
+        .metadata
+        .short_description
+        .as_deref()
+        .map(sanitize_single_line)
+        .filter(|value| !value.is_empty());
+
+    validate_len(&name, MAX_NAME_LEN, "name")?;
+    if description.is_empty() {
+        return Err(SkillParseError::MissingField("description"));
+    }
+
+    Ok(ParsedSkillFrontmatter {
+        name,
+        description,
+        short_description,
+    })
+}
+
+fn sanitize_single_line(raw: &str) -> String {
+    raw.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+fn repair_frontmatter_scalar_fields(frontmatter: &str) -> Option<String> {
+    let mut changed = false;
+    let mut block_scalar_indent: Option<usize> = None;
+    let mut repaired_lines = Vec::new();
+    for line in frontmatter.lines() {
+        let indent = line
+            .chars()
+            .take_while(|character| *character == ' ')
+            .count();
+        if let Some(block_indent) = block_scalar_indent {
+            if line.trim().is_empty() || indent > block_indent {
+                repaired_lines.push(line.to_string());
+                continue;
+            }
+            block_scalar_indent = None;
+        }
+
+        let Some((key, value)) = line.split_once(':') else {
+            repaired_lines.push(line.to_string());
+            continue;
+        };
+        if key.trim().is_empty() || !value.chars().next().is_none_or(char::is_whitespace) {
+            repaired_lines.push(line.to_string());
+            continue;
+        }
+
+        let trimmed_start = value.trim_start();
+        let leading_whitespace = &value[..value.len() - trimmed_start.len()];
+        let mut scalar = trimmed_start;
+        let mut comment = "";
+        for (index, character) in trimmed_start.char_indices() {
+            if character == '#'
+                && (index == 0
+                    || trimmed_start[..index]
+                        .chars()
+                        .next_back()
+                        .is_some_and(char::is_whitespace))
+            {
+                let comment_start = trimmed_start[..index].trim_end().len();
+                scalar = &trimmed_start[..comment_start];
+                comment = &trimmed_start[comment_start..];
+                break;
+            }
+        }
+
+        let scalar = scalar.trim_end();
+        let Some(first_char) = scalar.chars().next() else {
+            repaired_lines.push(line.to_string());
+            continue;
+        };
+        if matches!(first_char, '|' | '>') {
+            block_scalar_indent = Some(indent);
+            repaired_lines.push(line.to_string());
+            continue;
+        }
+        if matches!(first_char, '\'' | '"') {
+            repaired_lines.push(line.to_string());
+            continue;
+        }
+        let mut has_colon_separator = false;
+        let mut chars = scalar.chars().peekable();
+        while let Some(character) = chars.next() {
+            if character == ':'
+                && matches!(chars.peek(), Some(next_character) if next_character.is_whitespace())
+            {
+                has_colon_separator = true;
+                break;
+            }
+        }
+        let invalid_flow_like_scalar = matches!(first_char, '[' | '{' | '@' | '`')
+            && serde_yaml::from_str::<serde_yaml::Value>(scalar).is_err();
+        if !has_colon_separator && !invalid_flow_like_scalar {
+            repaired_lines.push(line.to_string());
+            continue;
+        }
+
+        let quoted_scalar = format!("'{}'", scalar.replace('\'', "''"));
+        repaired_lines.push(format!(
+            "{key}:{leading_whitespace}{quoted_scalar}{comment}"
+        ));
+        changed = true;
+    }
+    changed.then(|| repaired_lines.join("\n"))
+}
+
+fn validate_len(
+    value: &str,
+    max_len: usize,
+    field_name: &'static str,
+) -> Result<(), SkillParseError> {
+    if value.is_empty() {
+        return Err(SkillParseError::MissingField(field_name));
+    }
+    if value.chars().count() > max_len {
+        return Err(SkillParseError::InvalidField {
+            field: field_name,
+            reason: format!("exceeds maximum length of {max_len} characters"),
+        });
+    }
+    Ok(())
+}
+
+fn extract_frontmatter(contents: &str) -> Option<String> {
+    let mut lines = contents.lines();
+    if !matches!(lines.next(), Some(line) if line.trim() == "---") {
+        return None;
+    }
+
+    let mut frontmatter_lines = Vec::new();
+    let mut found_closing = false;
+    for line in lines.by_ref() {
+        if line.trim() == "---" {
+            found_closing = true;
+            break;
+        }
+        frontmatter_lines.push(line);
+    }
+
+    if frontmatter_lines.is_empty() || !found_closing {
+        return None;
+    }
+
+    Some(frontmatter_lines.join("\n"))
+}
+
+#[cfg(test)]
+#[path = "parser_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/parser_tests.rs b/codex-rs/skills/src/parser_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d0fe46c679d278745b9a0f59efa6f0369261a6a4
--- /dev/null
+++ b/codex-rs/skills/src/parser_tests.rs
@@ -0,0 +1,119 @@
+use pretty_assertions::assert_eq;
+
+use super::ParsedSkillFrontmatter;
+use super::parse_skill_frontmatter_metadata;
+
+#[test]
+fn parses_repairs_and_sanitizes_frontmatter() {
+    let parsed = parse_skill_frontmatter_metadata(
+        "---\nname:  deploy  service\ndescription: Build for AWS: ECS\nmetadata:\n  short-description:  Deploy   safely\n---\n",
+        || "fallback".to_string(),
+    )
+    .expect("valid frontmatter");
+
+    assert_eq!(
+        parsed,
+        ParsedSkillFrontmatter {
+            name: "deploy service".to_string(),
+            description: "Build for AWS: ECS".to_string(),
+            short_description: Some("Deploy safely".to_string()),
+        }
+    );
+}
+
+#[test]
+fn uses_default_name_and_requires_description() {
+    let parsed = parse_skill_frontmatter_metadata("---\ndescription: Demo skill\n---\n", || {
+        "demo".to_string()
+    })
+    .expect("valid frontmatter");
+    assert_eq!(
+        parsed,
+        ParsedSkillFrontmatter {
+            name: "demo".to_string(),
+            description: "Demo skill".to_string(),
+            short_description: None,
+        }
+    );
+
+    let error =
+        parse_skill_frontmatter_metadata("---\nname: demo\n---\n", || "fallback".to_string())
+            .expect_err("description should be required");
+    assert_eq!(error.to_string(), "missing field `description`");
+}
+
+#[test]
+fn repairs_short_descriptions_containing_colons_and_apostrophes() {
+    let parsed = parse_skill_frontmatter_metadata(
+        "---\nname: short\ndescription: Short skill\nmetadata:\n  short-description: What's included: builds and tests\n---\n",
+        || "fallback".to_string(),
+    )
+    .expect("frontmatter with an unquoted short description should be repaired");
+
+    assert_eq!(
+        parsed,
+        ParsedSkillFrontmatter {
+            name: "short".to_string(),
+            description: "Short skill".to_string(),
+            short_description: Some("What's included: builds and tests".to_string()),
+        }
+    );
+}
+
+#[test]
+fn repairs_unrecognized_frontmatter_fields_that_need_quotes() {
+    let parsed = parse_skill_frontmatter_metadata(
+        "---\nname: unknown\ndescription: Unknown fields\nargument-hint: <duration: e.g. 7d, 2w>\ntags: [next,@supabase/ssr]\n---\n",
+        || "fallback".to_string(),
+    )
+    .expect("frontmatter with unrecognized fields should be repaired");
+
+    assert_eq!(
+        parsed,
+        ParsedSkillFrontmatter {
+            name: "unknown".to_string(),
+            description: "Unknown fields".to_string(),
+            short_description: None,
+        }
+    );
+}
+
+#[test]
+fn preserves_block_scalar_bodies_while_repairing_other_fields() {
+    let parsed = parse_skill_frontmatter_metadata(
+        "---\nname: block\ndescription: |-\n  Build for AWS: ECS\nargument-hint: <duration: e.g. 7d>\n---\n",
+        || "fallback".to_string(),
+    )
+    .expect("frontmatter repair should preserve block scalar bodies");
+
+    assert_eq!(
+        parsed,
+        ParsedSkillFrontmatter {
+            name: "block".to_string(),
+            description: "Build for AWS: ECS".to_string(),
+            short_description: None,
+        }
+    );
+}
+
+#[test]
+fn preserves_overlong_descriptions_and_short_descriptions() {
+    let description = "💡".repeat(/*n*/ 1_025);
+    let short_description = "x".repeat(/*n*/ 1_025);
+    let parsed = parse_skill_frontmatter_metadata(
+        &format!(
+            "---\nname: long\ndescription: {description}\nmetadata:\n  short-description: {short_description}\n---\n"
+        ),
+        || "fallback".to_string(),
+    )
+    .expect("descriptions should not be truncated during frontmatter parsing");
+
+    assert_eq!(
+        parsed,
+        ParsedSkillFrontmatter {
+            name: "long".to_string(),
+            description,
+            short_description: Some(short_description),
+        }
+    );
+}
diff --git a/codex-rs/skills/src/selection.rs b/codex-rs/skills/src/selection.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c21bd47adb0980a8460533a481e7a7a675f94681
--- /dev/null
+++ b/codex-rs/skills/src/selection.rs
@@ -0,0 +1,205 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+
+use codex_protocol::user_input::UserInput;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use crate::SkillMetadata;
+use crate::ToolMentionKind;
+use crate::ToolMentions;
+use crate::build_skill_name_counts;
+use crate::extract_tool_mentions;
+use crate::normalize_skill_path;
+use crate::tool_kind_for_path;
+
+/// Supplies ordered skills, disabled identities, and discovery paths for explicit selection.
+///
+/// Implementations should preserve skill discovery order and expose the logical discovery path
+/// associated with each canonical skill identity when one is available.
+pub trait ExplicitSkillLookup {
+    fn skills(&self) -> &[SkillMetadata];
+
+    fn disabled_paths(&self) -> &HashSet<AbsolutePathBuf>;
+
+    fn skill_discovery_path_for_path(&self, path: &AbsolutePathBuf) -> Option<&AbsolutePathBuf>;
+
+    fn is_skill_enabled(&self, skill: &SkillMetadata) -> bool {
+        !self.disabled_paths().contains(&skill.path_to_skills_md)
+    }
+}
+
+/// Collect explicitly mentioned skills from structured and text mentions.
+///
+/// Structured `UserInput::Skill` selections are resolved first by path against
+/// enabled skills. Text inputs are then scanned to extract `$skill-name` tokens, and we
+/// iterate loaded skills in their existing order to preserve prior ordering semantics.
+/// Explicit paths match either a skill's canonical identity or its logical discovery
+/// path, and plain names are only used when the match is unambiguous.
+///
+/// Complexity: `O(T + (N_s + N_t) * S)` time, `O(S + M)` space, where:
+/// `S` = number of skills, `T` = total text length, `N_s` = number of structured skill inputs,
+/// `N_t` = number of text inputs, `M` = max mentions parsed from a single text input.
+pub fn collect_explicit_skill_mentions(
+    inputs: &[UserInput],
+    loaded_skills: &impl ExplicitSkillLookup,
+    connector_slug_counts: &HashMap<String, usize>,
+) -> Vec<SkillMetadata> {
+    let skill_name_counts =
+        build_skill_name_counts(loaded_skills.skills(), loaded_skills.disabled_paths()).0;
+
+    let selection_context = SkillSelectionContext {
+        loaded_skills,
+        skill_name_counts: &skill_name_counts,
+        connector_slug_counts,
+    };
+    let mut selected: Vec<SkillMetadata> = Vec::new();
+    let mut seen_names: HashSet<String> = HashSet::new();
+    let mut seen_paths: HashSet<AbsolutePathBuf> = HashSet::new();
+    let mut blocked_plain_names: HashSet<String> = HashSet::new();
+
+    for input in inputs {
+        if let UserInput::Skill { name, path, .. } = input {
+            blocked_plain_names.insert(name.clone());
+            let Ok(path) = AbsolutePathBuf::relative_to_current_dir(path) else {
+                continue;
+            };
+
+            let Some(skill) = selection_context
+                .loaded_skills
+                .skills()
+                .iter()
+                .find(|skill| {
+                    skill.path_to_skills_md == path
+                        || selection_context
+                            .loaded_skills
+                            .skill_discovery_path_for_path(&skill.path_to_skills_md)
+                            .is_some_and(|discovery_path| discovery_path == &path)
+                })
+            else {
+                continue;
+            };
+
+            if !selection_context.loaded_skills.is_skill_enabled(skill)
+                || seen_paths.contains(&skill.path_to_skills_md)
+            {
+                continue;
+            }
+
+            seen_paths.insert(skill.path_to_skills_md.clone());
+            seen_names.insert(skill.name.clone());
+            selected.push(skill.clone());
+        }
+    }
+
+    for input in inputs {
+        if let UserInput::Text { text, .. } = input {
+            let mentioned_names = extract_tool_mentions(text);
+            select_skills_from_mentions(
+                &selection_context,
+                &blocked_plain_names,
+                &mentioned_names,
+                &mut seen_names,
+                &mut seen_paths,
+                &mut selected,
+            );
+        }
+    }
+
+    selected
+}
+
+struct SkillSelectionContext<'a> {
+    loaded_skills: &'a dyn ExplicitSkillLookup,
+    skill_name_counts: &'a HashMap<String, usize>,
+    connector_slug_counts: &'a HashMap<String, usize>,
+}
+
+/// Select mentioned skills while preserving the order of `skills`.
+fn select_skills_from_mentions(
+    selection_context: &SkillSelectionContext<'_>,
+    blocked_plain_names: &HashSet<String>,
+    mentions: &ToolMentions<'_>,
+    seen_names: &mut HashSet<String>,
+    seen_paths: &mut HashSet<AbsolutePathBuf>,
+    selected: &mut Vec<SkillMetadata>,
+) {
+    if mentions.is_empty() {
+        return;
+    }
+
+    let mention_skill_paths: HashSet<String> = mentions
+        .paths()
+        .filter(|path| {
+            !matches!(
+                tool_kind_for_path(path),
+                ToolMentionKind::App | ToolMentionKind::Mcp | ToolMentionKind::Plugin
+            )
+        })
+        .map(normalize_host_skill_path)
+        .collect();
+
+    for skill in selection_context.loaded_skills.skills() {
+        if !selection_context.loaded_skills.is_skill_enabled(skill)
+            || seen_paths.contains(&skill.path_to_skills_md)
+        {
+            continue;
+        }
+
+        let canonical_path = normalize_host_skill_path(&skill.path_to_skills_md.to_string_lossy());
+        let matches_discovery_path = selection_context
+            .loaded_skills
+            .skill_discovery_path_for_path(&skill.path_to_skills_md)
+            .is_some_and(|discovery_path| {
+                mention_skill_paths.contains(&normalize_host_skill_path(
+                    &discovery_path.to_string_lossy(),
+                ))
+            });
+        if mention_skill_paths.contains(&canonical_path) || matches_discovery_path {
+            seen_paths.insert(skill.path_to_skills_md.clone());
+            seen_names.insert(skill.name.clone());
+            selected.push(skill.clone());
+        }
+    }
+
+    for skill in selection_context.loaded_skills.skills() {
+        if !selection_context.loaded_skills.is_skill_enabled(skill)
+            || seen_paths.contains(&skill.path_to_skills_md)
+        {
+            continue;
+        }
+
+        if blocked_plain_names.contains(skill.name.as_str()) {
+            continue;
+        }
+        if !mentions.contains_plain_name(skill.name.as_str()) {
+            continue;
+        }
+
+        let skill_count = selection_context
+            .skill_name_counts
+            .get(skill.name.as_str())
+            .copied()
+            .unwrap_or(0);
+        let connector_count = selection_context
+            .connector_slug_counts
+            .get(&skill.name.to_ascii_lowercase())
+            .copied()
+            .unwrap_or(0);
+        if skill_count != 1 || connector_count != 0 {
+            continue;
+        }
+
+        if seen_names.insert(skill.name.clone()) {
+            seen_paths.insert(skill.path_to_skills_md.clone());
+            selected.push(skill.clone());
+        }
+    }
+}
+
+fn normalize_host_skill_path(path: &str) -> String {
+    normalize_skill_path(path).replace('\\', "/")
+}
+
+#[cfg(test)]
+#[path = "selection_tests.rs"]
+mod tests;
diff --git a/codex-rs/skills/src/selection_tests.rs b/codex-rs/skills/src/selection_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5fbf83e8554b8a0988d5466b89d779aaa9af0a3e
--- /dev/null
+++ b/codex-rs/skills/src/selection_tests.rs
@@ -0,0 +1,354 @@
+use super::*;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_absolute_path::test_support::PathBufExt;
+use codex_utils_absolute_path::test_support::test_path_buf;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+use std::collections::HashSet;
+
+#[derive(Default)]
+struct TestLookup {
+    skills: Vec<SkillMetadata>,
+    disabled_paths: HashSet<AbsolutePathBuf>,
+    skill_discovery_path_by_path: HashMap<AbsolutePathBuf, AbsolutePathBuf>,
+}
+
+impl ExplicitSkillLookup for TestLookup {
+    fn skills(&self) -> &[SkillMetadata] {
+        &self.skills
+    }
+
+    fn disabled_paths(&self) -> &HashSet<AbsolutePathBuf> {
+        &self.disabled_paths
+    }
+
+    fn skill_discovery_path_for_path(&self, path: &AbsolutePathBuf) -> Option<&AbsolutePathBuf> {
+        self.skill_discovery_path_by_path.get(path)
+    }
+}
+
+fn make_skill(name: &str, path: &str) -> SkillMetadata {
+    SkillMetadata {
+        name: name.to_string(),
+        description: format!("{name} skill"),
+        short_description: None,
+        interface: None,
+        dependencies: None,
+        policy: None,
+        path_to_skills_md: test_path_buf(path).abs(),
+        scope: codex_protocol::protocol::SkillScope::User,
+        plugin_id: None,
+        remote_plugin_id: None,
+    }
+}
+
+fn linked_skill_mention(name: &str, unix_path: &str) -> String {
+    format!("[${name}]({})", test_path_buf(unix_path).display())
+}
+
+fn collect_mentions(
+    inputs: &[UserInput],
+    skills: &[SkillMetadata],
+    disabled_paths: &HashSet<AbsolutePathBuf>,
+    connector_slug_counts: &HashMap<String, usize>,
+) -> Vec<SkillMetadata> {
+    let loaded_skills = TestLookup {
+        skills: skills.to_vec(),
+        disabled_paths: disabled_paths.clone(),
+        ..Default::default()
+    };
+    collect_explicit_skill_mentions(inputs, &loaded_skills, connector_slug_counts)
+}
+
+fn skill_outcome_with_discovery_path(skill: SkillMetadata, discovery_path: &str) -> TestLookup {
+    TestLookup {
+        skill_discovery_path_by_path: HashMap::from([(
+            skill.path_to_skills_md.clone(),
+            test_path_buf(discovery_path).abs(),
+        )]),
+        skills: vec![skill],
+        ..Default::default()
+    }
+}
+
+#[test]
+fn collect_explicit_skill_mentions_text_respects_skill_order() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let beta = make_skill("beta-skill", "/tmp/beta");
+    let skills = vec![beta.clone(), alpha.clone()];
+    let inputs = vec![UserInput::Text {
+        text: "first $alpha-skill then $beta-skill".to_string(),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    // Text scanning should not change the previous selection ordering semantics.
+    assert_eq!(selected, vec![beta, alpha]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_prioritizes_structured_inputs() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let beta = make_skill("beta-skill", "/tmp/beta");
+    let skills = vec![alpha.clone(), beta.clone()];
+    let inputs = vec![
+        UserInput::Text {
+            text: "please run $alpha-skill".to_string(),
+            text_elements: Vec::new(),
+        },
+        UserInput::Skill {
+            name: "beta-skill".to_string(),
+            path: test_path_buf("/tmp/beta"),
+        },
+    ];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, vec![beta, alpha]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_accepts_structured_discovery_path() {
+    let skill = make_skill("linked-skill", "/tmp/shared/linked-skill/SKILL.md");
+    let loaded_skills = skill_outcome_with_discovery_path(
+        skill.clone(),
+        "/tmp/project/.agents/skills/linked-skill/SKILL.md",
+    );
+    let inputs = vec![UserInput::Skill {
+        name: "linked-skill".to_string(),
+        path: test_path_buf("/tmp/project/.agents/skills/linked-skill/SKILL.md"),
+    }];
+
+    let selected = collect_explicit_skill_mentions(&inputs, &loaded_skills, &HashMap::new());
+
+    assert_eq!(selected, vec![skill]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_accepts_linked_discovery_path() {
+    let skill = make_skill("linked-skill", "/tmp/shared/linked-skill/SKILL.md");
+    let loaded_skills = skill_outcome_with_discovery_path(
+        skill.clone(),
+        "/tmp/project/.agents/skills/linked-skill/SKILL.md",
+    );
+    let inputs = vec![UserInput::Text {
+        text: linked_skill_mention(
+            "linked-skill",
+            "/tmp/project/.agents/skills/linked-skill/SKILL.md",
+        ),
+        text_elements: Vec::new(),
+    }];
+
+    let selected = collect_explicit_skill_mentions(&inputs, &loaded_skills, &HashMap::new());
+
+    assert_eq!(selected, vec![skill]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_rejects_disabled_discovery_path() {
+    let skill = make_skill("linked-skill", "/tmp/shared/linked-skill/SKILL.md");
+    let mut loaded_skills = skill_outcome_with_discovery_path(
+        skill.clone(),
+        "/tmp/project/.agents/skills/linked-skill/SKILL.md",
+    );
+    loaded_skills.disabled_paths.insert(skill.path_to_skills_md);
+    let inputs = vec![UserInput::Skill {
+        name: "linked-skill".to_string(),
+        path: test_path_buf("/tmp/project/.agents/skills/linked-skill/SKILL.md"),
+    }];
+
+    let selected = collect_explicit_skill_mentions(&inputs, &loaded_skills, &HashMap::new());
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_invalid_structured_and_blocks_plain_fallback() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let skills = vec![alpha];
+    let inputs = vec![
+        UserInput::Text {
+            text: "please run $alpha-skill".to_string(),
+            text_elements: Vec::new(),
+        },
+        UserInput::Skill {
+            name: "alpha-skill".to_string(),
+            path: test_path_buf("/tmp/missing"),
+        },
+    ];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_disabled_structured_and_blocks_plain_fallback() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let skills = vec![alpha];
+    let inputs = vec![
+        UserInput::Text {
+            text: "please run $alpha-skill".to_string(),
+            text_elements: Vec::new(),
+        },
+        UserInput::Skill {
+            name: "alpha-skill".to_string(),
+            path: test_path_buf("/tmp/alpha"),
+        },
+    ];
+    let disabled = HashSet::from([test_path_buf("/tmp/alpha").abs()]);
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &disabled, &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_dedupes_by_path() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let skills = vec![alpha.clone()];
+    let mention = linked_skill_mention("alpha-skill", "/tmp/alpha");
+    let inputs = vec![UserInput::Text {
+        text: format!("use {mention} and {mention}"),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, vec![alpha]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_ambiguous_name() {
+    let alpha = make_skill("demo-skill", "/tmp/alpha");
+    let beta = make_skill("demo-skill", "/tmp/beta");
+    let skills = vec![alpha, beta];
+    let inputs = vec![UserInput::Text {
+        text: "use $demo-skill and again $demo-skill".to_string(),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_prefers_linked_path_over_name() {
+    let alpha = make_skill("demo-skill", "/tmp/alpha");
+    let beta = make_skill("demo-skill", "/tmp/beta");
+    let skills = vec![alpha, beta.clone()];
+    let inputs = vec![UserInput::Text {
+        text: format!(
+            "use $demo-skill and {}",
+            linked_skill_mention("demo-skill", "/tmp/beta")
+        ),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, vec![beta]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_plain_name_when_connector_matches() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let skills = vec![alpha];
+    let inputs = vec![UserInput::Text {
+        text: "use $alpha-skill".to_string(),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::from([("alpha-skill".to_string(), 1)]);
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_allows_explicit_path_with_connector_conflict() {
+    let alpha = make_skill("alpha-skill", "/tmp/alpha");
+    let skills = vec![alpha.clone()];
+    let inputs = vec![UserInput::Text {
+        text: format!("use {}", linked_skill_mention("alpha-skill", "/tmp/alpha")),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::from([("alpha-skill".to_string(), 1)]);
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, vec![alpha]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_when_linked_path_disabled() {
+    let alpha = make_skill("demo-skill", "/tmp/alpha");
+    let beta = make_skill("demo-skill", "/tmp/beta");
+    let skills = vec![alpha, beta];
+    let inputs = vec![UserInput::Text {
+        text: format!("use {}", linked_skill_mention("demo-skill", "/tmp/alpha")),
+        text_elements: Vec::new(),
+    }];
+    let disabled = HashSet::from([test_path_buf("/tmp/alpha").abs()]);
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &disabled, &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_prefers_resource_path() {
+    let alpha = make_skill("demo-skill", "/tmp/alpha");
+    let beta = make_skill("demo-skill", "/tmp/beta");
+    let skills = vec![alpha, beta.clone()];
+    let inputs = vec![UserInput::Text {
+        text: format!("use {}", linked_skill_mention("demo-skill", "/tmp/beta")),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, vec![beta]);
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_missing_path_with_no_fallback() {
+    let alpha = make_skill("demo-skill", "/tmp/alpha");
+    let beta = make_skill("demo-skill", "/tmp/beta");
+    let skills = vec![alpha, beta];
+    let inputs = vec![UserInput::Text {
+        text: format!("use {}", linked_skill_mention("demo-skill", "/tmp/missing")),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
+
+#[test]
+fn collect_explicit_skill_mentions_skips_missing_path_without_fallback() {
+    let alpha = make_skill("demo-skill", "/tmp/alpha");
+    let skills = vec![alpha];
+    let inputs = vec![UserInput::Text {
+        text: format!("use {}", linked_skill_mention("demo-skill", "/tmp/missing")),
+        text_elements: Vec::new(),
+    }];
+    let connector_counts = HashMap::new();
+
+    let selected = collect_mentions(&inputs, &skills, &HashSet::new(), &connector_counts);
+
+    assert_eq!(selected, Vec::new());
+}
diff --git a/codex-rs/skills/tests/test_plugin_creator.py b/codex-rs/skills/tests/test_plugin_creator.py
new file mode 100644
index 0000000000000000000000000000000000000000..ea930e13b9132cb43638efaadd36c6e1ac92c966
--- /dev/null
+++ b/codex-rs/skills/tests/test_plugin_creator.py
@@ -0,0 +1,338 @@
+"""Local-only regression tests for the bundled plugin-creator scripts.
+
+Run with:
+    python3 -B -m unittest discover -s codex-rs/skills/tests -p 'test_*.py'
+"""
+
+import json
+import runpy
+import subprocess
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPTS = (
+    Path(__file__).resolve().parents[1]
+    / "src"
+    / "assets"
+    / "samples"
+    / "plugin-creator"
+    / "scripts"
+)
+
+
+class PluginCreatorSecurityTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name)
+        self.marketplace_path = self.root / "marketplace.json"
+        self.plugin_root = self.root / "plugins" / "demo"
+
+    def run_script(
+        self, script: str, *arguments: str
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [sys.executable, "-B", str(SCRIPTS / script), *arguments],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+    def write_marketplace(self, name: object) -> None:
+        self.marketplace_path.write_text(
+            json.dumps({"name": name, "plugins": []}),
+            encoding="utf-8",
+        )
+
+    def write_plugin(self, name: object) -> Path:
+        manifest_path = self.plugin_root / ".codex-plugin" / "plugin.json"
+        manifest_path.parent.mkdir(parents=True, exist_ok=True)
+        manifest_path.write_text(
+            json.dumps({"name": name, "version": "1.0.0"}),
+            encoding="utf-8",
+        )
+        return manifest_path
+
+    def plugin_validation_errors(self, name: str) -> list[str]:
+        with (
+            patch.dict(sys.modules, {"yaml": types.ModuleType("yaml")}),
+            patch.object(sys, "path", [str(SCRIPTS), *sys.path]),
+            patch.object(sys, "dont_write_bytecode", True),
+        ):
+            scaffold = runpy.run_path(str(SCRIPTS / "create_basic_plugin.py"))
+            validator = runpy.run_path(str(SCRIPTS / "validate_plugin.py"))
+
+        manifest = scaffold["build_plugin_json"](
+            "demo", with_mcp=False, with_apps=False
+        )
+        manifest["name"] = name
+        errors: list[str] = []
+        validator["validate_manifest_shape"](self.plugin_root, manifest, errors)
+        return errors
+
+    def test_marketplace_reader_accepts_valid_names(self) -> None:
+        for name in ("personal", "team-local", "team_local_123", "ABC123_-", "_", "-"):
+            with self.subTest(name=name):
+                self.write_marketplace(name)
+                result = self.run_script(
+                    "read_marketplace_name.py",
+                    "--marketplace-path",
+                    str(self.marketplace_path),
+                )
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertEqual(result.stdout, f"{name}\n")
+
+    def test_marketplace_reader_rejects_unsafe_names_without_stdout(self) -> None:
+        unsafe_names = (
+            "team;id",
+            "team\nlocal",
+            "team local",
+            " team",
+            "team ",
+            "team'local",
+            'team"local',
+            "team$(id)",
+            "team`id`",
+            "team&local",
+            "team|local",
+            "team<local",
+            "team>local",
+            "team.local",
+            "équipe",
+            "",
+        )
+        for name in unsafe_names:
+            with self.subTest(name=name):
+                self.write_marketplace(name)
+                result = self.run_script(
+                    "read_marketplace_name.py",
+                    "--marketplace-path",
+                    str(self.marketplace_path),
+                )
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual(result.stdout, "")
+
+    def test_marketplace_reader_rejects_missing_and_nonstring_names(self) -> None:
+        for payload in ({}, {"name": None}, {"name": 123}, {"name": ["team"]}, []):
+            with self.subTest(payload=payload):
+                self.marketplace_path.write_text(json.dumps(payload), encoding="utf-8")
+                result = self.run_script(
+                    "read_marketplace_name.py",
+                    "--marketplace-path",
+                    str(self.marketplace_path),
+                )
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual(result.stdout, "")
+
+    def test_marketplace_reader_rejects_malformed_json(self) -> None:
+        self.marketplace_path.write_text("{", encoding="utf-8")
+        result = self.run_script(
+            "read_marketplace_name.py",
+            "--marketplace-path",
+            str(self.marketplace_path),
+        )
+        self.assertNotEqual(result.returncode, 0)
+        self.assertEqual(result.stdout, "")
+
+    def test_plugin_validator_accepts_canonical_names(self) -> None:
+        for name in ("demo", "Team_Name-1", "team.tools", "team.tools_v2"):
+            with self.subTest(name=name):
+                self.assertEqual(self.plugin_validation_errors(name), [])
+
+    def test_plugin_validator_rejects_unsafe_names(self) -> None:
+        unsafe_names = (
+            "safe;id",
+            "$(id)",
+            "safe\nid",
+            "safe name",
+            "safe`id`",
+            ".hidden",
+            "trailing.",
+            "safe..name",
+            "équipe",
+        )
+        for name in unsafe_names:
+            with self.subTest(name=name):
+                errors = self.plugin_validation_errors(name)
+                self.assertTrue(errors)
+                self.assertTrue(any("name" in error for error in errors))
+
+    def test_cachebuster_rejects_unsafe_plugin_names_without_writing(self) -> None:
+        for name in ("safe;id", "$(id)", "safe\nid", ".hidden", "safe..name"):
+            with self.subTest(name=name):
+                manifest_path = self.write_plugin(name)
+                original = manifest_path.read_bytes()
+                result = self.run_script(
+                    "update_plugin_cachebuster.py", str(self.plugin_root)
+                )
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual(result.stdout, "")
+                self.assertEqual(manifest_path.read_bytes(), original)
+
+    def test_cachebuster_accepts_dotted_plugin_names(self) -> None:
+        manifest_path = self.write_plugin("demo.tools")
+        result = self.run_script(
+            "update_plugin_cachebuster.py",
+            str(self.plugin_root),
+            "--cachebuster",
+            "safe-token",
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        self.assertEqual(manifest["name"], "demo.tools")
+        self.assertEqual(manifest["version"], "1.0.0+codex.safe-token")
+
+    def test_scaffold_rejects_invalid_marketplace_before_creating_files(self) -> None:
+        self.write_marketplace("team;id")
+        original = self.marketplace_path.read_bytes()
+        result = self.run_script(
+            "create_basic_plugin.py",
+            "demo",
+            "--path",
+            str(self.root / "plugins"),
+            "--with-marketplace",
+            "--marketplace-path",
+            str(self.marketplace_path),
+        )
+        self.assertNotEqual(result.returncode, 0)
+        self.assertFalse(self.plugin_root.exists())
+        self.assertEqual(self.marketplace_path.read_bytes(), original)
+
+    def test_scaffold_force_preserves_files_when_marketplace_is_invalid(self) -> None:
+        self.write_marketplace("team;id")
+        plugin_manifest = self.write_plugin("demo")
+        mcp_manifest = self.plugin_root / ".mcp.json"
+        app_manifest = self.plugin_root / ".app.json"
+        mcp_manifest.write_text('{"mcpServers":{"existing":{}}}', encoding="utf-8")
+        app_manifest.write_text('{"apps":{"existing":{}}}', encoding="utf-8")
+        originals = {
+            path: path.read_bytes()
+            for path in (
+                self.marketplace_path,
+                plugin_manifest,
+                mcp_manifest,
+                app_manifest,
+            )
+        }
+
+        result = self.run_script(
+            "create_basic_plugin.py",
+            "demo",
+            "--path",
+            str(self.root / "plugins"),
+            "--with-marketplace",
+            "--marketplace-path",
+            str(self.marketplace_path),
+            "--with-mcp",
+            "--with-apps",
+            "--with-skills",
+            "--force",
+        )
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertFalse((self.plugin_root / "skills").exists())
+        for path, original in originals.items():
+            with self.subTest(path=path):
+                self.assertEqual(path.read_bytes(), original)
+
+    def test_scaffold_force_preserves_files_when_plugins_field_is_invalid(self) -> None:
+        self.marketplace_path.write_text(
+            json.dumps({"name": "team-local", "plugins": {}}),
+            encoding="utf-8",
+        )
+        plugin_manifest = self.write_plugin("demo")
+        mcp_manifest = self.plugin_root / ".mcp.json"
+        app_manifest = self.plugin_root / ".app.json"
+        mcp_manifest.write_text('{"mcpServers":{"existing":{}}}', encoding="utf-8")
+        app_manifest.write_text('{"apps":{"existing":{}}}', encoding="utf-8")
+        originals = {
+            path: path.read_bytes()
+            for path in (
+                self.marketplace_path,
+                plugin_manifest,
+                mcp_manifest,
+                app_manifest,
+            )
+        }
+
+        result = self.run_script(
+            "create_basic_plugin.py",
+            "demo",
+            "--path",
+            str(self.root / "plugins"),
+            "--with-marketplace",
+            "--marketplace-path",
+            str(self.marketplace_path),
+            "--with-mcp",
+            "--with-apps",
+            "--with-skills",
+            "--force",
+        )
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertFalse((self.plugin_root / "skills").exists())
+        for path, original in originals.items():
+            with self.subTest(path=path):
+                self.assertEqual(path.read_bytes(), original)
+
+    def test_scaffold_rejects_duplicate_marketplace_entry_before_creating_files(
+        self,
+    ) -> None:
+        self.marketplace_path.write_text(
+            json.dumps({"name": "team-local", "plugins": [{"name": "demo"}]}),
+            encoding="utf-8",
+        )
+        original = self.marketplace_path.read_bytes()
+        result = self.run_script(
+            "create_basic_plugin.py",
+            "demo",
+            "--path",
+            str(self.root / "plugins"),
+            "--with-marketplace",
+            "--marketplace-path",
+            str(self.marketplace_path),
+        )
+        self.assertNotEqual(result.returncode, 0)
+        self.assertFalse(self.plugin_root.exists())
+        self.assertEqual(self.marketplace_path.read_bytes(), original)
+
+    def test_scaffold_accepts_existing_valid_marketplace(self) -> None:
+        self.write_marketplace("team-local_123")
+        result = self.run_script(
+            "create_basic_plugin.py",
+            "demo",
+            "--path",
+            str(self.root / "plugins"),
+            "--with-marketplace",
+            "--marketplace-path",
+            str(self.marketplace_path),
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        marketplace = json.loads(self.marketplace_path.read_text(encoding="utf-8"))
+        self.assertEqual(marketplace["name"], "team-local_123")
+        self.assertEqual(marketplace["plugins"][0]["name"], "demo")
+
+    def test_scaffold_creates_missing_personal_marketplace(self) -> None:
+        self.assertFalse(self.marketplace_path.exists())
+        result = self.run_script(
+            "create_basic_plugin.py",
+            "demo",
+            "--path",
+            str(self.root / "plugins"),
+            "--with-marketplace",
+            "--marketplace-path",
+            str(self.marketplace_path),
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        marketplace = json.loads(self.marketplace_path.read_text(encoding="utf-8"))
+        self.assertEqual(marketplace["name"], "personal")
+        self.assertEqual(marketplace["plugins"][0]["name"], "demo")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/codex-rs/skills/tests/test_skill_installer.py b/codex-rs/skills/tests/test_skill_installer.py
new file mode 100644
index 0000000000000000000000000000000000000000..0265273eb8b2db80aec5ae2de2b07cb19ef6a5b3
--- /dev/null
+++ b/codex-rs/skills/tests/test_skill_installer.py
@@ -0,0 +1,137 @@
+"""Local-only regression tests for the bundled skill-installer script.
+
+Run manually; these tests are not wired into CI:
+    python3 -B -m unittest discover -s codex-rs/skills/tests -p 'test_*.py'
+"""
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+INSTALLER = (
+    Path(__file__).resolve().parents[1]
+    / "src"
+    / "assets"
+    / "samples"
+    / "skill-installer"
+    / "scripts"
+    / "install-skill-from-github.py"
+)
+
+
+class SkillInstallerSymlinkTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name)
+        self.repository = self.root / "repository"
+        self.skill = self.repository / "skill"
+        self.skill.mkdir(parents=True)
+        (self.skill / "SKILL.md").write_text("Synthetic test skill\n", encoding="utf-8")
+        self.destination = self.root / "installed"
+
+    def create_symlink(self, link: Path, target: Path | str) -> None:
+        try:
+            link.symlink_to(target)
+        except OSError as error:
+            self.skipTest(f"symlinks are unavailable: {error}")
+
+    def run_installer(self) -> subprocess.CompletedProcess[str]:
+        subprocess.run(
+            ["git", "init", "--initial-branch=main", str(self.repository)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        subprocess.run(
+            ["git", "-C", str(self.repository), "add", "."],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        subprocess.run(
+            [
+                "git",
+                "-C",
+                str(self.repository),
+                "-c",
+                "user.name=Skill Installer Test",
+                "-c",
+                "user.email=skill-installer@example.invalid",
+                "commit",
+                "-m",
+                "synthetic skill fixture",
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+        environment = os.environ.copy()
+        python_path = [str(INSTALLER.parent)]
+        if environment.get("PYTHONPATH"):
+            python_path.append(environment["PYTHONPATH"])
+        environment.update(
+            {
+                "GIT_CONFIG_COUNT": "2",
+                "GIT_CONFIG_KEY_0": f"url.{self.repository.as_uri()}.insteadOf",
+                "GIT_CONFIG_VALUE_0": "https://github.com/synthetic/fixture.git",
+                "GIT_CONFIG_KEY_1": "core.symlinks",
+                "GIT_CONFIG_VALUE_1": "true",
+                "GIT_TERMINAL_PROMPT": "0",
+                "PYTHONPATH": os.pathsep.join(python_path),
+            }
+        )
+        return subprocess.run(
+            [
+                sys.executable,
+                "-B",
+                str(INSTALLER),
+                "--repo",
+                "synthetic/fixture",
+                "--path",
+                "skill",
+                "--method",
+                "git",
+                "--dest",
+                str(self.destination),
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+            env=environment,
+        )
+
+    def test_rejects_symlink_to_file_outside_skill(self) -> None:
+        outside_file = self.root / "synthetic-secret.txt"
+        outside_file.write_text("synthetic secret\n", encoding="utf-8")
+        self.create_symlink(self.skill / "outside.txt", outside_file)
+
+        result = self.run_installer()
+
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("Unsupported symbolic link", result.stderr)
+        self.assertFalse((self.destination / "skill").exists())
+
+    def test_installs_symlink_to_regular_file_inside_skill(self) -> None:
+        (self.skill / "actual.txt").write_text(
+            "safe skill contents\n", encoding="utf-8"
+        )
+        self.create_symlink(self.skill / "alias.txt", "actual.txt")
+
+        result = self.run_installer()
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        installed_alias = self.destination / "skill" / "alias.txt"
+        self.assertFalse(installed_alias.is_symlink())
+        self.assertEqual(
+            installed_alias.read_text(encoding="utf-8"), "safe skill contents\n"
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/codex-rs/thread-store/src/error.rs b/codex-rs/thread-store/src/error.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bc5e8ed7c4f9c8692fb19f6d94c623f6bc0f3335
--- /dev/null
+++ b/codex-rs/thread-store/src/error.rs
@@ -0,0 +1,55 @@
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+
+/// Result type returned by thread-store operations.
+pub type ThreadStoreResult<T> = Result<T, ThreadStoreError>;
+
+pub(crate) fn reject_paginated_history_mode(
+    history_mode: ThreadHistoryMode,
+) -> ThreadStoreResult<()> {
+    if matches!(history_mode, ThreadHistoryMode::Paginated) {
+        return Err(ThreadStoreError::Unsupported {
+            operation: "paginated_threads",
+        });
+    }
+    Ok(())
+}
+
+/// Error type shared by thread-store implementations.
+#[derive(Debug, thiserror::Error)]
+pub enum ThreadStoreError {
+    /// The requested thread does not exist in this store.
+    #[error("thread {thread_id} not found")]
+    ThreadNotFound {
+        /// Thread id requested by the caller.
+        thread_id: ThreadId,
+    },
+
+    /// The caller supplied invalid request data.
+    #[error("invalid thread-store request: {message}")]
+    InvalidRequest {
+        /// User-facing explanation of the invalid request.
+        message: String,
+    },
+
+    /// The operation conflicted with current store state.
+    #[error("thread-store conflict: {message}")]
+    Conflict {
+        /// User-facing explanation of the conflict.
+        message: String,
+    },
+
+    /// The store implementation does not support this operation yet.
+    #[error("thread-store unsupported operation: {operation}")]
+    Unsupported {
+        /// Stable operation name for callers that need to map unsupported operations.
+        operation: &'static str,
+    },
+
+    /// Catch-all for implementation failures that do not fit a more specific category.
+    #[error("thread-store internal error: {message}")]
+    Internal {
+        /// User-facing explanation of the implementation failure.
+        message: String,
+    },
+}
diff --git a/codex-rs/thread-store/src/in_memory.rs b/codex-rs/thread-store/src/in_memory.rs
new file mode 100644
index 0000000000000000000000000000000000000000..955f87415672afc9b4bb34049af5f0f87d55e641
--- /dev/null
+++ b/codex-rs/thread-store/src/in_memory.rs
@@ -0,0 +1,1198 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::MutexGuard;
+use std::sync::OnceLock;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+
+use chrono::DateTime;
+use chrono::Utc;
+use codex_protocol::ThreadId;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::SessionContextWindow;
+use codex_protocol::protocol::SessionMeta;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_rollout::RolloutItem;
+use codex_rollout::persisted_rollout_items;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use crate::AppendThreadItemsParams;
+use crate::ArchiveThreadParams;
+use crate::CreateThreadParams;
+use crate::DeleteThreadParams;
+use crate::ListThreadsParams;
+use crate::LoadThreadHistoryParams;
+use crate::MoveThreadToSectionParams;
+use crate::PersistContext;
+use crate::ReadThreadByRolloutPathParams;
+use crate::ReadThreadParams;
+use crate::ResumeThreadParams;
+use crate::StoredModelContext;
+use crate::StoredThread;
+use crate::StoredThreadHistory;
+use crate::ThreadMetadataPatch;
+use crate::ThreadPage;
+use crate::ThreadRelationFilter;
+use crate::ThreadSortKey;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::ThreadStoreFuture;
+use crate::ThreadStoreResult;
+use crate::UpdateThreadMetadataParams;
+use crate::error::reject_paginated_history_mode;
+
+static IN_MEMORY_THREAD_STORES: OnceLock<Mutex<HashMap<String, Arc<InMemoryThreadStore>>>> =
+    OnceLock::new();
+
+fn stores() -> &'static Mutex<HashMap<String, Arc<InMemoryThreadStore>>> {
+    IN_MEMORY_THREAD_STORES.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ItemSortKey;
+    use crate::ListItemsParams;
+    use crate::ListTurnsParams;
+    use crate::SortDirection;
+    use crate::StoredTurnItemsView;
+    use crate::ThreadPersistenceMetadata;
+    use crate::ThreadSortKey;
+    use codex_protocol::models::BaseInstructions;
+    use codex_protocol::protocol::SessionSource;
+
+    #[tokio::test]
+    async fn deletion_cleans_associated_sqlite_and_shared_memory()
+    -> Result<(), Box<dyn std::error::Error>> {
+        use codex_utils_absolute_path::test_support::PathExt;
+        use pretty_assertions::assert_eq;
+
+        let home = tempfile::TempDir::new()?;
+        let state_db = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            "test".to_string(),
+        )
+        .await?;
+        let shared = InMemoryThreadStore::default();
+        let store = shared.with_state_db(Some(state_db.clone()));
+        let thread_id = ThreadId::new();
+        shared
+            .create_thread(create_thread_params(thread_id, ThreadHistoryMode::Legacy))
+            .await?;
+        let metadata = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            home.path().join("thread.jsonl"),
+            Utc::now(),
+            SessionSource::Cli,
+        )
+        .build("test");
+        state_db.upsert_thread(&metadata).await?;
+
+        store
+            .delete_thread(DeleteThreadParams { thread_id })
+            .await?;
+
+        assert_eq!(state_db.get_thread(thread_id).await?, None);
+        assert!(!shared.state.lock().await.histories.contains_key(&thread_id));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn default_turn_pagination_methods_return_unsupported() {
+        let store = InMemoryThreadStore::default();
+        let thread_id = ThreadId::default();
+
+        let turns_err = store
+            .list_turns(ListTurnsParams {
+                thread_id,
+                include_archived: true,
+                cursor: None,
+                page_size: 10,
+                sort_direction: SortDirection::Asc,
+                items_view: StoredTurnItemsView::Summary,
+            })
+            .await
+            .expect_err("default list_turns should be unsupported");
+        assert!(matches!(
+            turns_err,
+            ThreadStoreError::Unsupported {
+                operation: "list_turns"
+            }
+        ));
+
+        let items_err = store
+            .list_items(ListItemsParams {
+                thread_id,
+                turn_id: None,
+                include_archived: true,
+                cursor: None,
+                page_size: 10,
+                sort_direction: SortDirection::Asc,
+                sort_key: ItemSortKey::CreatedAtOrdinal,
+                after_updated_at_ordinal: None,
+            })
+            .await
+            .expect_err("default list_items should be unsupported");
+        assert!(matches!(
+            items_err,
+            ThreadStoreError::Unsupported {
+                operation: "list_items"
+            }
+        ));
+    }
+
+    #[tokio::test]
+    async fn list_threads_filters_by_spawn_relationship() {
+        let store = InMemoryThreadStore::default();
+        let parent_thread_id = ThreadId::default();
+        let child_thread_id =
+            ThreadId::from_string("00000000-0000-0000-0000-000000000001").expect("valid thread id");
+        let unrelated_thread_id =
+            ThreadId::from_string("00000000-0000-0000-0000-000000000002").expect("valid thread id");
+        let grandchild_thread_id =
+            ThreadId::from_string("00000000-0000-0000-0000-000000000003").expect("valid thread id");
+
+        for (thread_id, parent_thread_id) in [
+            (child_thread_id, Some(parent_thread_id)),
+            (unrelated_thread_id, None),
+            (grandchild_thread_id, Some(child_thread_id)),
+        ] {
+            store
+                .create_thread(CreateThreadParams {
+                    session_id: thread_id.into(),
+                    thread_id,
+                    extra_config: None,
+                    forked_from_id: None,
+                    parent_thread_id,
+                    source: SessionSource::Exec,
+                    thread_source: None,
+                    originator: "test_originator".to_string(),
+                    base_instructions: BaseInstructions::default(),
+                    dynamic_tools: Vec::new(),
+                    selected_capability_roots: Vec::new(),
+                    multi_agent_version: None,
+                    history_mode: ThreadHistoryMode::Legacy,
+                    history_base: None,
+                    subagent_history_start_ordinal: None,
+                    initial_window_id: uuid::Uuid::now_v7().to_string(),
+                    runtime_workspace_roots: None,
+                    metadata: ThreadPersistenceMetadata {
+                        cwd: None,
+                        model_provider: "test-provider".to_string(),
+                        memory_mode: ThreadMemoryMode::Enabled,
+                    },
+                })
+                .await
+                .expect("create thread");
+        }
+
+        store
+            .move_thread_to_section(MoveThreadToSectionParams {
+                thread_id: grandchild_thread_id,
+                section: Some(codex_state::PINNED_THREAD_SECTION_ID.to_string()),
+                before_thread_id: None,
+            })
+            .await
+            .expect("pin grandchild thread");
+
+        let page = ThreadStore::list_threads(
+            &store,
+            ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: Some(ThreadRelationFilter::DirectChildrenOf(parent_thread_id)),
+                use_state_db_only: false,
+            },
+        )
+        .await
+        .expect("list child threads");
+
+        assert_eq!(
+            page.items
+                .into_iter()
+                .map(|item| item.thread_id)
+                .collect::<Vec<_>>(),
+            vec![child_thread_id]
+        );
+
+        let page = ThreadStore::list_threads(
+            &store,
+            ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: Some(ThreadRelationFilter::DescendantsOf(parent_thread_id)),
+                use_state_db_only: false,
+            },
+        )
+        .await
+        .expect("list descendant threads");
+
+        assert_eq!(
+            page.items
+                .into_iter()
+                .map(|item| item.thread_id)
+                .collect::<HashSet<_>>(),
+            HashSet::from([child_thread_id, grandchild_thread_id])
+        );
+
+        let page = ThreadStore::list_threads(
+            &store,
+            ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: Some(Some(codex_state::PINNED_THREAD_SECTION_ID.to_string())),
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: Some(ThreadRelationFilter::DescendantsOf(parent_thread_id)),
+                use_state_db_only: false,
+            },
+        )
+        .await
+        .expect("list pinned descendant threads");
+
+        assert_eq!(
+            page.items
+                .into_iter()
+                .map(|item| item.thread_id)
+                .collect::<Vec<_>>(),
+            vec![grandchild_thread_id]
+        );
+
+        let page = ThreadStore::list_threads(
+            &store,
+            ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: Some(None),
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: Some(ThreadRelationFilter::DescendantsOf(parent_thread_id)),
+                use_state_db_only: false,
+            },
+        )
+        .await
+        .expect("list unsectioned descendant threads");
+
+        assert_eq!(
+            page.items
+                .into_iter()
+                .map(|item| item.thread_id)
+                .collect::<Vec<_>>(),
+            vec![child_thread_id]
+        );
+    }
+
+    #[tokio::test]
+    async fn paginated_threads_allow_metadata_reads_and_resume_but_reject_legacy_history_paths() {
+        let store = InMemoryThreadStore::default();
+        let thread_id = ThreadId::default();
+        let rollout_path = PathBuf::from("/tmp/paginated-thread.jsonl");
+
+        store
+            .create_thread(create_thread_params(thread_id, ThreadHistoryMode::Legacy))
+            .await
+            .expect("create legacy thread");
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path.clone()),
+                history: None,
+                include_archived: false,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("register rollout path");
+        {
+            let mut state = store.state.lock().await;
+            state
+                .created_threads
+                .get_mut(&thread_id)
+                .expect("created thread")
+                .history_mode = ThreadHistoryMode::Paginated;
+            let Some(RolloutItem::SessionMeta(meta_line)) = state
+                .histories
+                .get_mut(&thread_id)
+                .and_then(|history| history.first_mut())
+            else {
+                panic!("canonical session meta");
+            };
+            meta_line.meta.history_mode = ThreadHistoryMode::Paginated;
+        }
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("metadata read");
+        assert_eq!(thread.history_mode, ThreadHistoryMode::Paginated);
+        assert!(thread.history.is_none());
+
+        let thread = store
+            .read_thread_by_rollout_path(ReadThreadByRolloutPathParams {
+                rollout_path,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("metadata path read");
+        assert_eq!(thread.history_mode, ThreadHistoryMode::Paginated);
+        assert!(thread.history.is_none());
+
+        assert_paginated_threads_unsupported(
+            store
+                .read_thread(ReadThreadParams {
+                    thread_id,
+                    include_archived: false,
+                    include_history: true,
+                })
+                .await
+                .expect_err("full history read should fail"),
+        );
+        assert_paginated_threads_unsupported(
+            store
+                .read_thread_by_rollout_path(ReadThreadByRolloutPathParams {
+                    rollout_path: PathBuf::from("/tmp/paginated-thread.jsonl"),
+                    include_archived: false,
+                    include_history: true,
+                })
+                .await
+                .expect_err("full history path read should fail"),
+        );
+        assert_paginated_threads_unsupported(
+            store
+                .load_history(LoadThreadHistoryParams {
+                    thread_id,
+                    include_archived: false,
+                })
+                .await
+                .expect_err("history load should fail"),
+        );
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: None,
+                history: None,
+                include_archived: false,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("resume should succeed");
+        assert_paginated_threads_unsupported(
+            store
+                .create_thread(create_thread_params(
+                    ThreadId::default(),
+                    ThreadHistoryMode::Paginated,
+                ))
+                .await
+                .expect_err("paginated create should fail"),
+        );
+    }
+
+    #[tokio::test]
+    async fn metadata_update_returns_the_materialized_thread() {
+        let store = InMemoryThreadStore::default();
+        let thread_id = ThreadId::default();
+        store
+            .create_thread(create_thread_params(thread_id, ThreadHistoryMode::Legacy))
+            .await
+            .expect("create thread");
+
+        let updated = ThreadStore::update_thread_metadata(
+            &store,
+            UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("renamed".to_string())),
+                    ..Default::default()
+                },
+                include_archived: false,
+            },
+        )
+        .await
+        .expect("update metadata");
+        let updated = updated.expect("in-memory store returns updated thread");
+        assert_eq!(updated.thread_id, thread_id);
+        assert_eq!(updated.name.as_deref(), Some("renamed"));
+    }
+
+    fn create_thread_params(
+        thread_id: ThreadId,
+        history_mode: ThreadHistoryMode,
+    ) -> CreateThreadParams {
+        CreateThreadParams {
+            session_id: thread_id.into(),
+            thread_id,
+            extra_config: None,
+            forked_from_id: None,
+            parent_thread_id: None,
+            source: SessionSource::Exec,
+            thread_source: None,
+            originator: "test_originator".to_string(),
+            base_instructions: BaseInstructions::default(),
+            dynamic_tools: Vec::new(),
+            selected_capability_roots: Vec::new(),
+            multi_agent_version: None,
+            history_mode,
+            history_base: None,
+            subagent_history_start_ordinal: None,
+            initial_window_id: uuid::Uuid::now_v7().to_string(),
+            runtime_workspace_roots: None,
+            metadata: thread_metadata(),
+        }
+    }
+
+    fn thread_metadata() -> ThreadPersistenceMetadata {
+        ThreadPersistenceMetadata {
+            cwd: None,
+            model_provider: "test-provider".to_string(),
+            memory_mode: ThreadMemoryMode::Enabled,
+        }
+    }
+
+    fn assert_paginated_threads_unsupported(err: ThreadStoreError) {
+        assert!(matches!(
+            err,
+            ThreadStoreError::Unsupported {
+                operation: "paginated_threads"
+            }
+        ));
+    }
+}
+
+fn stores_guard() -> MutexGuard<'static, HashMap<String, Arc<InMemoryThreadStore>>> {
+    match stores().lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => poisoned.into_inner(),
+    }
+}
+
+/// Recorded call counts for [`InMemoryThreadStore`].
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct InMemoryThreadStoreCalls {
+    pub create_thread: usize,
+    pub resume_thread: usize,
+    pub append_items: usize,
+    pub persist_thread: usize,
+    pub flush_thread: usize,
+    pub shutdown_thread: usize,
+    pub discard_thread: usize,
+    pub load_history: usize,
+    pub load_latest_model_context: usize,
+    pub read_thread: usize,
+    pub read_thread_with_history: usize,
+    pub read_thread_by_rollout_path: usize,
+    pub list_threads: usize,
+    pub update_thread_metadata: usize,
+    pub archive_thread: usize,
+    pub unarchive_thread: usize,
+    pub delete_thread: usize,
+}
+
+/// In-memory [`ThreadStore`] implementation for tests and debug configs.
+///
+/// Test and debug configs can select this store by id, letting tests exercise
+/// config-driven non-local persistence without requiring the real remote gRPC
+/// service.
+#[derive(Default)]
+pub struct InMemoryThreadStore {
+    state: Arc<tokio::sync::Mutex<InMemoryThreadStoreState>>,
+    omit_metadata_update_result: Arc<AtomicBool>,
+    state_db: Option<codex_rollout::StateDbHandle>,
+}
+
+#[derive(Default)]
+struct InMemoryThreadStoreState {
+    calls: InMemoryThreadStoreCalls,
+    created_threads: HashMap<ThreadId, CreateThreadParams>,
+    histories: HashMap<ThreadId, Vec<RolloutItem>>,
+    metadata_updates: HashMap<ThreadId, ThreadMetadataPatch>,
+    sections: HashMap<ThreadId, String>,
+    section_positions: HashMap<ThreadId, i64>,
+    section_entered_at: HashMap<ThreadId, DateTime<Utc>>,
+    names: HashMap<ThreadId, Option<String>>,
+    rollout_paths: HashMap<PathBuf, ThreadId>,
+}
+
+impl InMemoryThreadStore {
+    /// Returns the store associated with `id`, creating it if needed.
+    pub fn for_id(id: impl Into<String>) -> Arc<Self> {
+        let id = id.into();
+        let mut stores = stores_guard();
+        stores
+            .entry(id)
+            .or_insert_with(|| Arc::new(Self::default()))
+            .clone()
+    }
+
+    /// Shares this debug store's thread data while owning cleanup of the caller's SQLite state.
+    pub fn with_state_db(&self, state_db: Option<codex_rollout::StateDbHandle>) -> Self {
+        Self {
+            state: Arc::clone(&self.state),
+            omit_metadata_update_result: Arc::clone(&self.omit_metadata_update_result),
+            state_db,
+        }
+    }
+
+    /// Removes a shared in-memory store for `id`.
+    pub fn remove_id(id: &str) -> Option<Arc<Self>> {
+        stores_guard().remove(id)
+    }
+
+    /// Returns the calls observed by this store.
+    pub async fn calls(&self) -> InMemoryThreadStoreCalls {
+        self.state.lock().await.calls.clone()
+    }
+
+    /// Makes metadata updates apply normally while returning no materialized thread.
+    pub fn omit_metadata_update_result_for_testing(&self) {
+        self.omit_metadata_update_result
+            .store(true, Ordering::Relaxed);
+    }
+
+    async fn create_thread(&self, params: CreateThreadParams) -> ThreadStoreResult<()> {
+        reject_paginated_history_mode(params.history_mode)?;
+        let mut state = self.state.lock().await;
+        state.calls.create_thread += 1;
+        let session_meta = SessionMeta {
+            session_id: params.session_id,
+            id: params.thread_id,
+            forked_from_id: params.forked_from_id,
+            parent_thread_id: params.parent_thread_id,
+            cwd: params.metadata.cwd.clone().unwrap_or_default(),
+            runtime_workspace_roots: params
+                .runtime_workspace_roots
+                .as_ref()
+                .map(|roots| roots.iter().map(AbsolutePathBuf::to_path_buf).collect()),
+            agent_nickname: params.source.get_nickname(),
+            agent_role: params.source.get_agent_role(),
+            agent_path: params.source.get_agent_path().map(Into::into),
+            originator: params.originator.clone(),
+            source: params.source.clone(),
+            thread_source: params.thread_source.clone(),
+            model_provider: Some(params.metadata.model_provider.clone()),
+            base_instructions: Some(params.base_instructions.clone()),
+            dynamic_tools: (!params.dynamic_tools.is_empty()).then(|| params.dynamic_tools.clone()),
+            selected_capability_roots: params.selected_capability_roots.clone(),
+            memory_mode: matches!(params.metadata.memory_mode, ThreadMemoryMode::Disabled)
+                .then_some("disabled".to_string()),
+            history_mode: params.history_mode,
+            history_base: params.history_base,
+            subagent_history_start_ordinal: params.subagent_history_start_ordinal,
+            multi_agent_version: params.multi_agent_version,
+            context_window: Some(SessionContextWindow::new(params.initial_window_id.clone())),
+            ..SessionMeta::default()
+        };
+        state
+            .histories
+            .entry(params.thread_id)
+            .or_default()
+            .push(RolloutItem::SessionMeta(SessionMetaLine {
+                meta: session_meta,
+                git: None,
+            }));
+        state.created_threads.insert(params.thread_id, params);
+        Ok(())
+    }
+
+    async fn resume_thread(&self, params: ResumeThreadParams) -> ThreadStoreResult<()> {
+        let mut state = self.state.lock().await;
+        state.calls.resume_thread += 1;
+        if let Some(history) = params.history {
+            state
+                .histories
+                .insert(params.thread_id, Arc::unwrap_or_clone(history));
+        } else {
+            state.histories.entry(params.thread_id).or_default();
+        }
+        if let Some(rollout_path) = params.rollout_path {
+            state.rollout_paths.insert(rollout_path, params.thread_id);
+        }
+        Ok(())
+    }
+
+    async fn append_items(&self, params: AppendThreadItemsParams) -> ThreadStoreResult<()> {
+        if params.items.is_empty() {
+            return Ok(());
+        }
+        let mut state = self.state.lock().await;
+        let history_mode = history_mode_from_state(&state, params.thread_id);
+        let persisted_items = persisted_rollout_items(params.items.as_slice(), history_mode);
+        if persisted_items.is_empty() {
+            return Ok(());
+        }
+        state.calls.append_items += 1;
+        state
+            .histories
+            .entry(params.thread_id)
+            .or_default()
+            .extend(persisted_items);
+        Ok(())
+    }
+
+    async fn load_history(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreResult<StoredThreadHistory> {
+        let mut state = self.state.lock().await;
+        state.calls.load_history += 1;
+        let items =
+            state
+                .histories
+                .get(&params.thread_id)
+                .ok_or(ThreadStoreError::ThreadNotFound {
+                    thread_id: params.thread_id,
+                })?;
+        let history_mode = history_mode_from_state(&state, params.thread_id);
+        reject_paginated_history_mode(history_mode)?;
+        Ok(StoredThreadHistory {
+            thread_id: params.thread_id,
+            items: items.clone(),
+        })
+    }
+
+    async fn load_latest_model_context(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreResult<StoredModelContext> {
+        let mut state = self.state.lock().await;
+        state.calls.load_latest_model_context += 1;
+        let items =
+            state
+                .histories
+                .get(&params.thread_id)
+                .ok_or(ThreadStoreError::ThreadNotFound {
+                    thread_id: params.thread_id,
+                })?;
+        Ok(StoredModelContext {
+            thread_id: params.thread_id,
+            items: items.clone(),
+        })
+    }
+
+    async fn read_thread(&self, params: ReadThreadParams) -> ThreadStoreResult<StoredThread> {
+        let mut state = self.state.lock().await;
+        state.calls.read_thread += 1;
+        if params.include_history {
+            state.calls.read_thread_with_history += 1;
+            reject_paginated_history_mode(history_mode_from_state(&state, params.thread_id))?;
+        }
+        let thread = stored_thread_from_state(&state, params.thread_id, params.include_history)?;
+        Ok(thread)
+    }
+
+    async fn read_thread_by_rollout_path(
+        &self,
+        params: ReadThreadByRolloutPathParams,
+    ) -> ThreadStoreResult<StoredThread> {
+        let mut state = self.state.lock().await;
+        state.calls.read_thread_by_rollout_path += 1;
+        let Some(thread_id) = state.rollout_paths.get(&params.rollout_path).copied() else {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!(
+                    "in-memory thread store does not know rollout path {}",
+                    params.rollout_path.display()
+                ),
+            });
+        };
+        if params.include_history {
+            reject_paginated_history_mode(history_mode_from_state(&state, thread_id))?;
+        }
+        let thread = stored_thread_from_state(&state, thread_id, params.include_history)?;
+        Ok(thread)
+    }
+
+    async fn list_threads(&self) -> ThreadStoreResult<ThreadPage> {
+        let mut state = self.state.lock().await;
+        state.calls.list_threads += 1;
+        let mut items = state
+            .created_threads
+            .keys()
+            .map(|thread_id| {
+                stored_thread_from_state(&state, *thread_id, /*include_history*/ false)
+            })
+            .collect::<ThreadStoreResult<Vec<_>>>()?;
+        items.sort_by_key(|item| item.thread_id.to_string());
+        Ok(ThreadPage {
+            items,
+            next_cursor: None,
+        })
+    }
+
+    async fn update_thread_metadata(
+        &self,
+        params: UpdateThreadMetadataParams,
+    ) -> ThreadStoreResult<StoredThread> {
+        if params.patch.project_id.is_some() {
+            return Err(ThreadStoreError::Unsupported {
+                operation: "projects",
+            });
+        }
+        let mut state = self.state.lock().await;
+        state.calls.update_thread_metadata += 1;
+        if !state.created_threads.contains_key(&params.thread_id) {
+            return Err(ThreadStoreError::ThreadNotFound {
+                thread_id: params.thread_id,
+            });
+        }
+        if let Some(name) = params.patch.name.clone() {
+            state.names.insert(params.thread_id, name);
+        }
+        state
+            .metadata_updates
+            .entry(params.thread_id)
+            .or_default()
+            .merge(params.patch);
+        stored_thread_from_state(&state, params.thread_id, /*include_history*/ false)
+    }
+
+    async fn move_thread_to_section(
+        &self,
+        params: MoveThreadToSectionParams,
+    ) -> ThreadStoreResult<()> {
+        if params
+            .section
+            .as_deref()
+            .is_some_and(|section| section.trim().is_empty())
+        {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: "section must not be empty".to_owned(),
+            });
+        }
+        if params.section.is_none() && params.before_thread_id.is_some() {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: "before thread cannot be specified without a section".to_owned(),
+            });
+        }
+
+        let mut state = self.state.lock().await;
+        if !state.created_threads.contains_key(&params.thread_id) {
+            return Err(ThreadStoreError::ThreadNotFound {
+                thread_id: params.thread_id,
+            });
+        }
+        let previous_section = state.sections.get(&params.thread_id).cloned();
+        let Some(section) = params.section.as_deref() else {
+            state.sections.remove(&params.thread_id);
+            state.section_positions.remove(&params.thread_id);
+            state.section_entered_at.remove(&params.thread_id);
+            return Ok(());
+        };
+        if let Some(before_thread_id) = params.before_thread_id {
+            if before_thread_id == params.thread_id {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: format!("thread {} cannot be moved before itself", params.thread_id),
+                });
+            }
+            let before_section = state.sections.get(&before_thread_id).map(String::as_str);
+            if before_section != Some(section) {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: format!(
+                        "before thread {before_thread_id} is not in section {section}"
+                    ),
+                });
+            }
+        }
+
+        let mut ordered_thread_ids = state
+            .sections
+            .iter()
+            .filter(|(thread_id, current_section)| {
+                **thread_id != params.thread_id && current_section.as_str() == section
+            })
+            .map(|(thread_id, _)| *thread_id)
+            .collect::<Vec<_>>();
+        ordered_thread_ids.sort_by_key(|thread_id| {
+            (
+                state
+                    .section_positions
+                    .get(thread_id)
+                    .copied()
+                    .unwrap_or(i64::MAX),
+                thread_id.to_string(),
+            )
+        });
+        let insert_at = params
+            .before_thread_id
+            .and_then(|before_thread_id| {
+                ordered_thread_ids
+                    .iter()
+                    .position(|thread_id| *thread_id == before_thread_id)
+            })
+            .unwrap_or(ordered_thread_ids.len());
+        ordered_thread_ids.insert(insert_at, params.thread_id);
+        for (index, thread_id) in ordered_thread_ids.into_iter().enumerate() {
+            let position = i64::try_from(index)
+                .unwrap_or(i64::MAX)
+                .saturating_add(1)
+                .saturating_mul(1_000_000);
+            state.section_positions.insert(thread_id, position);
+        }
+        if previous_section.as_deref() != Some(section) {
+            state
+                .section_entered_at
+                .insert(params.thread_id, Utc::now());
+            state.sections.insert(params.thread_id, section.to_owned());
+        }
+        Ok(())
+    }
+
+    async fn delete_thread(&self, params: DeleteThreadParams) -> ThreadStoreResult<()> {
+        self.state.lock().await.calls.delete_thread += 1;
+        let deleted_state_rows = if let Some(state_db) = &self.state_db {
+            state_db
+                .delete_threads_strict(&[params.thread_id])
+                .await
+                .map_err(|error| ThreadStoreError::Internal {
+                    message: format!("failed to delete thread state: {error}"),
+                })?
+        } else {
+            0
+        };
+        let mut state = self.state.lock().await;
+        let existed = state.histories.remove(&params.thread_id).is_some();
+        state.created_threads.remove(&params.thread_id);
+        state.names.remove(&params.thread_id);
+        state.metadata_updates.remove(&params.thread_id);
+        state.sections.remove(&params.thread_id);
+        state.section_positions.remove(&params.thread_id);
+        state.section_entered_at.remove(&params.thread_id);
+        state
+            .rollout_paths
+            .retain(|_, thread_id| *thread_id != params.thread_id);
+        if existed || deleted_state_rows > 0 {
+            Ok(())
+        } else {
+            Err(ThreadStoreError::ThreadNotFound {
+                thread_id: params.thread_id,
+            })
+        }
+    }
+}
+
+impl ThreadStore for InMemoryThreadStore {
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn create_thread(&self, params: CreateThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(InMemoryThreadStore::create_thread(self, params))
+    }
+
+    fn resume_thread(&self, params: ResumeThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(InMemoryThreadStore::resume_thread(self, params))
+    }
+
+    fn append_items(&self, params: AppendThreadItemsParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(InMemoryThreadStore::append_items(self, params))
+    }
+
+    fn persist_thread(
+        &self,
+        _thread_id: ThreadId,
+        _context: PersistContext,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state.lock().await.calls.persist_thread += 1;
+            Ok(())
+        })
+    }
+
+    fn flush_thread(&self, _thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state.lock().await.calls.flush_thread += 1;
+            Ok(())
+        })
+    }
+
+    fn shutdown_thread(&self, _thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state.lock().await.calls.shutdown_thread += 1;
+            Ok(())
+        })
+    }
+
+    fn discard_thread(&self, _thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state.lock().await.calls.discard_thread += 1;
+            Ok(())
+        })
+    }
+
+    fn load_history(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadHistory> {
+        Box::pin(InMemoryThreadStore::load_history(self, params))
+    }
+
+    fn load_latest_model_context(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreFuture<'_, StoredModelContext> {
+        Box::pin(InMemoryThreadStore::load_latest_model_context(self, params))
+    }
+
+    fn read_thread(&self, params: ReadThreadParams) -> ThreadStoreFuture<'_, StoredThread> {
+        Box::pin(InMemoryThreadStore::read_thread(self, params))
+    }
+
+    fn read_thread_by_rollout_path(
+        &self,
+        params: ReadThreadByRolloutPathParams,
+    ) -> ThreadStoreFuture<'_, StoredThread> {
+        Box::pin(InMemoryThreadStore::read_thread_by_rollout_path(
+            self, params,
+        ))
+    }
+
+    fn list_threads(&self, params: ListThreadsParams) -> ThreadStoreFuture<'_, ThreadPage> {
+        Box::pin(async move {
+            let mut page = InMemoryThreadStore::list_threads(self).await?;
+            match params.relation_filter {
+                Some(ThreadRelationFilter::DirectChildrenOf(parent_thread_id)) => {
+                    page.items
+                        .retain(|thread| thread.parent_thread_id == Some(parent_thread_id));
+                }
+                Some(ThreadRelationFilter::DescendantsOf(ancestor_thread_id)) => {
+                    let mut subtree = HashSet::from([ancestor_thread_id]);
+                    loop {
+                        let mut discovered = false;
+                        for thread in &page.items {
+                            if thread
+                                .parent_thread_id
+                                .is_some_and(|parent_thread_id| subtree.contains(&parent_thread_id))
+                            {
+                                discovered |= subtree.insert(thread.thread_id);
+                            }
+                        }
+                        if !discovered {
+                            break;
+                        }
+                    }
+                    page.items.retain(|thread| {
+                        thread.thread_id != ancestor_thread_id
+                            && subtree.contains(&thread.thread_id)
+                    });
+                }
+                None => {}
+            }
+            if let Some(section) = params.section.as_ref() {
+                page.items.retain(|thread| {
+                    thread.section.as_ref().map(|section| section.id.as_str()) == section.as_deref()
+                });
+            }
+            if params.sort_key == ThreadSortKey::SectionPosition {
+                page.items.sort_by_key(|thread| {
+                    (
+                        thread.section_position.unwrap_or(i64::MAX),
+                        thread.thread_id.to_string(),
+                    )
+                });
+                if params.sort_direction == crate::SortDirection::Desc {
+                    page.items.reverse();
+                }
+            }
+            Ok(page)
+        })
+    }
+
+    fn update_thread_metadata(
+        &self,
+        params: UpdateThreadMetadataParams,
+    ) -> ThreadStoreFuture<'_, Option<StoredThread>> {
+        Box::pin(async move {
+            let updated = InMemoryThreadStore::update_thread_metadata(self, params).await?;
+            Ok((!self.omit_metadata_update_result.load(Ordering::Relaxed)).then_some(updated))
+        })
+    }
+
+    fn move_thread_to_section(
+        &self,
+        params: MoveThreadToSectionParams,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(InMemoryThreadStore::move_thread_to_section(self, params))
+    }
+
+    fn archive_thread(&self, _params: ArchiveThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.state.lock().await.calls.archive_thread += 1;
+            Ok(())
+        })
+    }
+
+    fn unarchive_thread(&self, params: ArchiveThreadParams) -> ThreadStoreFuture<'_, StoredThread> {
+        Box::pin(async move {
+            let mut state = self.state.lock().await;
+            state.calls.unarchive_thread += 1;
+            stored_thread_from_state(&state, params.thread_id, /*include_history*/ false)
+        })
+    }
+
+    fn delete_thread(&self, params: DeleteThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(InMemoryThreadStore::delete_thread(self, params))
+    }
+}
+
+fn stored_thread_from_state(
+    state: &InMemoryThreadStoreState,
+    thread_id: ThreadId,
+    include_history: bool,
+) -> ThreadStoreResult<StoredThread> {
+    let created = state
+        .created_threads
+        .get(&thread_id)
+        .ok_or(ThreadStoreError::ThreadNotFound { thread_id })?;
+    let history_items = state.histories.get(&thread_id).cloned().unwrap_or_default();
+    let history = include_history.then(|| StoredThreadHistory {
+        thread_id,
+        items: history_items.clone(),
+    });
+    let name = state.names.get(&thread_id).cloned().flatten();
+    let metadata = state.metadata_updates.get(&thread_id);
+    let rollout_path = state
+        .rollout_paths
+        .iter()
+        .find_map(|(path, mapped_thread_id)| {
+            (*mapped_thread_id == thread_id).then(|| path.clone())
+        });
+
+    Ok(StoredThread {
+        originator: (!created.originator.is_empty()).then(|| created.originator.clone()),
+        thread_id,
+        extra_config: created.extra_config.clone(),
+        rollout_path: metadata
+            .and_then(|metadata| metadata.rollout_path.clone())
+            .or(rollout_path),
+        forked_from_id: created.forked_from_id,
+        parent_thread_id: created.parent_thread_id,
+        preview: metadata
+            .and_then(|metadata| metadata.preview.clone())
+            .unwrap_or_default(),
+        name,
+        model_provider: metadata
+            .and_then(|metadata| metadata.model_provider.clone())
+            .unwrap_or_else(|| "test".to_string()),
+        model: metadata.and_then(|metadata| metadata.model.clone()),
+        reasoning_effort: metadata
+            .and_then(|metadata| metadata.reasoning_effort.clone())
+            .flatten(),
+        created_at: metadata
+            .and_then(|metadata| metadata.created_at)
+            .unwrap_or_else(Utc::now),
+        updated_at: metadata
+            .and_then(|metadata| metadata.updated_at)
+            .unwrap_or_else(Utc::now),
+        recency_at: metadata
+            .and_then(|metadata| metadata.advance_recency_at.or(metadata.updated_at))
+            .unwrap_or_else(Utc::now),
+        archived_at: None,
+        section: state
+            .sections
+            .get(&thread_id)
+            .cloned()
+            .map(|id| codex_state::ThreadSection {
+                name: if id == codex_state::PINNED_THREAD_SECTION_ID {
+                    codex_state::PINNED_THREAD_SECTION_NAME.to_string()
+                } else {
+                    id.clone()
+                },
+                id,
+                appearance: None,
+            }),
+        section_position: state.section_positions.get(&thread_id).copied(),
+        section_entered_at: state.section_entered_at.get(&thread_id).copied(),
+        project_id: None,
+        daybreak_enabled: metadata.and_then(|metadata| metadata.daybreak_enabled),
+        cwd: metadata
+            .and_then(|metadata| metadata.cwd.clone())
+            .unwrap_or_default(),
+        cli_version: metadata
+            .and_then(|metadata| metadata.cli_version.clone())
+            .unwrap_or_else(|| "test".to_string()),
+        source: metadata
+            .and_then(|metadata| metadata.source.clone())
+            .unwrap_or_else(|| created.source.clone()),
+        history_mode: created.history_mode,
+        thread_source: metadata
+            .and_then(|metadata| metadata.thread_source.clone())
+            .unwrap_or_else(|| created.thread_source.clone()),
+        agent_nickname: metadata.and_then(|metadata| metadata.agent_nickname.clone().flatten()),
+        agent_role: metadata.and_then(|metadata| metadata.agent_role.clone().flatten()),
+        agent_path: metadata.and_then(|metadata| metadata.agent_path.clone().flatten()),
+        git_info: metadata.and_then(git_info_from_patch),
+        approval_mode: metadata
+            .and_then(|metadata| metadata.approval_mode)
+            .unwrap_or(AskForApproval::Never),
+        permission_profile: metadata
+            .and_then(|metadata| metadata.permission_profile.clone())
+            .unwrap_or_else(PermissionProfile::read_only),
+        token_usage: metadata.and_then(|metadata| metadata.token_usage.clone()),
+        first_user_message: metadata.and_then(|metadata| metadata.first_user_message.clone()),
+        history,
+    })
+}
+
+fn history_mode_from_state(
+    state: &InMemoryThreadStoreState,
+    thread_id: ThreadId,
+) -> ThreadHistoryMode {
+    state
+        .created_threads
+        .get(&thread_id)
+        .map(|thread| thread.history_mode)
+        .unwrap_or_default()
+}
+
+fn git_info_from_patch(patch: &ThreadMetadataPatch) -> Option<codex_protocol::protocol::GitInfo> {
+    let git_info = patch.git_info.as_ref()?;
+    let sha = git_info.sha.clone().flatten();
+    let branch = git_info.branch.clone().flatten();
+    let origin_url = git_info.origin_url.clone().flatten();
+    if sha.is_none() && branch.is_none() && origin_url.is_none() {
+        return None;
+    }
+    Some(codex_protocol::protocol::GitInfo {
+        commit_hash: sha.as_deref().map(codex_git_utils::GitSha::new),
+        branch,
+        repository_url: origin_url,
+    })
+}
diff --git a/codex-rs/thread-store/src/lib.rs b/codex-rs/thread-store/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2650a56f85e2c06e31c1a3e04bce72af370d52b2
--- /dev/null
+++ b/codex-rs/thread-store/src/lib.rs
@@ -0,0 +1,114 @@
+//! Storage-neutral thread persistence interfaces.
+//!
+//! Application code should treat [`codex_protocol::ThreadId`] as the only durable thread handle.
+//! Implementations are responsible for resolving that id to local rollout files, RPC requests, or
+//! any other backing store.
+
+mod error;
+mod in_memory;
+mod live_thread;
+mod local;
+mod projects;
+mod queue_store;
+mod store;
+mod thread_attachments;
+mod thread_metadata_sync;
+mod thread_sections;
+mod types;
+
+pub use codex_state::AddThreadAttachmentOutcome;
+pub use codex_state::MAX_QUEUE_ITEMS;
+pub use codex_state::MAX_THREAD_ATTACHMENT_PAYLOAD_BYTES;
+pub use codex_state::ProjectSortKey;
+pub use codex_state::QueuedUserSubmissionRecord;
+pub use codex_state::RemoveThreadAttachmentOutcome;
+pub use codex_state::ThreadAttachment;
+pub use codex_state::ThreadAttachmentPage;
+pub use error::ThreadStoreError;
+pub use error::ThreadStoreResult;
+pub use in_memory::InMemoryThreadStore;
+pub use in_memory::InMemoryThreadStoreCalls;
+pub use live_thread::LiveThread;
+pub use live_thread::LiveThreadInitGuard;
+pub use local::LocalThreadStore;
+pub use local::LocalThreadStoreConfig;
+pub use local::RolloutMigrationFailureReason;
+pub use local::RolloutMigrationMode;
+pub use local::RolloutMigrationOptions;
+pub use local::RolloutMigrationOutcome;
+pub use local::RolloutMigrationProgress;
+pub use local::RolloutMigrationReport;
+pub use local::RolloutMigrationStatus;
+pub use projects::CreateProjectParams;
+pub use projects::CreatedProject;
+pub use projects::DeletedProject;
+pub use projects::ListProjectsParams;
+pub use projects::MoveProjectParams;
+pub use projects::ProjectMoveOutcome;
+pub use projects::StoredProject;
+pub use projects::StoredProjectRoot;
+pub use projects::StoredProjectsPage;
+pub use projects::UpdateProjectParams;
+pub use projects::UpdatedProject;
+pub use queue_store::LocalQueueStore;
+pub use queue_store::QueueStore;
+pub use store::PersistContext;
+pub use store::ThreadStore;
+pub use store::ThreadStoreFuture;
+pub use thread_attachments::AddThreadAttachmentParams;
+pub use thread_attachments::ListThreadAttachmentsParams;
+pub use thread_attachments::RemoveThreadAttachmentParams;
+pub use thread_sections::CreateThreadSectionParams;
+pub use thread_sections::DeleteThreadSectionParams;
+pub use thread_sections::ListThreadSectionsParams;
+pub use thread_sections::RenameThreadSectionParams;
+pub use thread_sections::StoredThreadSection;
+pub use thread_sections::StoredThreadSectionsPage;
+pub use types::AppendThreadItemsParams;
+pub use types::ArchiveThreadParams;
+pub use types::ArchiveThreadsParams;
+pub use types::ClearableField;
+pub use types::CreateThreadParams;
+pub use types::DeleteThreadParams;
+pub use types::DeleteThreadsParams;
+pub use types::ExtraConfig;
+pub use types::ForkBoundary;
+pub use types::GitInfoPatch;
+pub use types::ItemPage;
+pub use types::ItemSortKey;
+pub use types::ListItemsParams;
+pub use types::ListThreadsParams;
+pub use types::ListTimelineParams;
+pub use types::ListTurnsParams;
+pub use types::LoadThreadHistoryParams;
+pub use types::MoveThreadToSectionParams;
+pub use types::PrepareForkParams;
+pub use types::PreparedFork;
+pub use types::ReadThreadByRolloutPathParams;
+pub use types::ReadThreadParams;
+pub use types::ResumeThreadParams;
+pub use types::RevertThreadParams;
+pub use types::SearchTextRange;
+pub use types::SearchThreadOccurrencesParams;
+pub use types::SearchThreadsParams;
+pub use types::SortDirection;
+pub use types::StoredModelContext;
+pub use types::StoredThread;
+pub use types::StoredThreadHistory;
+pub use types::StoredThreadItem;
+pub use types::StoredThreadOccurrence;
+pub use types::StoredThreadSearchResult;
+pub use types::StoredTurn;
+pub use types::StoredTurnError;
+pub use types::StoredTurnItemsView;
+pub use types::StoredTurnStatus;
+pub use types::ThreadMetadataPatch;
+pub use types::ThreadOccurrenceSearchPage;
+pub use types::ThreadPage;
+pub use types::ThreadPersistenceMetadata;
+pub use types::ThreadRelationFilter;
+pub use types::ThreadSearchPage;
+pub use types::ThreadSortKey;
+pub use types::TimelinePage;
+pub use types::TurnPage;
+pub use types::UpdateThreadMetadataParams;
diff --git a/codex-rs/thread-store/src/live_thread.rs b/codex-rs/thread-store/src/live_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5f75a30404376441af44c971985ef5855436dae5
--- /dev/null
+++ b/codex-rs/thread-store/src/live_thread.rs
@@ -0,0 +1,452 @@
+use std::future::Future;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutPersistenceTelemetry;
+use codex_rollout::measure_and_filter_rollout_items;
+use codex_rollout::persisted_rollout_items;
+use tokio::sync::Mutex;
+use tracing::warn;
+
+use crate::AppendThreadItemsParams;
+use crate::CreateThreadParams;
+use crate::LoadThreadHistoryParams;
+use crate::LocalThreadStore;
+use crate::PersistContext;
+use crate::ReadThreadParams;
+use crate::ResumeThreadParams;
+use crate::StoredThread;
+use crate::StoredThreadHistory;
+use crate::ThreadMetadataPatch;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::ThreadStoreFuture;
+use crate::ThreadStoreResult;
+use crate::UpdateThreadMetadataParams;
+use crate::thread_metadata_sync::ThreadMetadataSync;
+
+/// Handle for an active thread's persistence lifecycle.
+///
+/// `LiveThread` keeps lifecycle decisions with the caller while delegating storage details to
+/// [`ThreadStore`]. Local stores may use a rollout file internally and remote stores may use a
+/// service, but session code should only need this handle for the active thread.
+#[derive(Clone)]
+pub struct LiveThread {
+    thread_id: ThreadId,
+    history_mode: ThreadHistoryMode,
+    thread_store: Arc<dyn ThreadStore>,
+    metadata_sync: Arc<Mutex<ThreadMetadataSync>>,
+    persistence_telemetry: RolloutPersistenceTelemetry,
+}
+
+/// Owns persistence acquisition and its live thread while initialization is still fallible.
+///
+/// If initialization returns early after persistence has been opened, dropping this guard discards
+/// the live writer without forcing lazy in-memory state to become durable. Call [`commit`] once the
+/// session owns the live thread for normal operation. Cancellation leaves an in-flight acquisition
+/// owned by the guard: cleanup waits for it to finish before discarding any acquired writer.
+#[derive(Default)]
+pub struct LiveThreadInitGuard {
+    live_thread: Option<LiveThread>,
+    acquiring: Option<ThreadStoreFuture<'static, LiveThread>>,
+}
+
+impl LiveThreadInitGuard {
+    pub fn new(live_thread: Option<LiveThread>) -> Self {
+        Self {
+            live_thread,
+            acquiring: None,
+        }
+    }
+
+    /// Retains the operation even if the caller stops waiting. Store operations may install a
+    /// writer before returning or delegate to another runtime, so they cannot simply be dropped.
+    pub async fn acquire(
+        &mut self,
+        acquisition: impl Future<Output = ThreadStoreResult<LiveThread>> + Send + 'static,
+    ) -> ThreadStoreResult<LiveThread> {
+        assert!(self.live_thread.is_none() && self.acquiring.is_none());
+        self.acquiring = Some(Box::pin(acquisition));
+        self.finish_acquisition().await?;
+        self.live_thread
+            .clone()
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: "persistence acquisition returned no live thread".to_owned(),
+            })
+    }
+
+    async fn finish_acquisition(&mut self) -> ThreadStoreResult<()> {
+        if let Some(acquiring) = self.acquiring.as_mut() {
+            let result = acquiring.await;
+            self.acquiring = None;
+            self.live_thread = Some(result?);
+        }
+        Ok(())
+    }
+
+    pub fn as_ref(&self) -> Option<&LiveThread> {
+        self.live_thread.as_ref()
+    }
+
+    pub fn commit(&mut self) {
+        self.live_thread = None;
+    }
+
+    pub async fn discard(&mut self) {
+        let _ = self.finish_acquisition().await;
+        let Some(live_thread) = self.live_thread.take() else {
+            return;
+        };
+        if let Err(err) = live_thread.discard().await {
+            warn!("failed to discard thread persistence for failed session init: {err}");
+        }
+    }
+}
+
+impl Drop for LiveThreadInitGuard {
+    fn drop(&mut self) {
+        if self.live_thread.is_none() && self.acquiring.is_none() {
+            return;
+        }
+        let Ok(handle) = tokio::runtime::Handle::try_current() else {
+            warn!("failed to discard thread persistence for failed session init: no Tokio runtime");
+            return;
+        };
+        let acquiring = self.acquiring.take();
+        let live_thread = self.live_thread.take();
+        handle.spawn(async move {
+            let live_thread = match acquiring {
+                Some(acquiring) => acquiring.await.ok(),
+                None => live_thread,
+            };
+            if let Some(live_thread) = live_thread
+                && let Err(err) = live_thread.discard().await
+            {
+                warn!("failed to discard thread persistence for failed session init: {err}");
+            }
+        });
+    }
+}
+
+impl LiveThread {
+    pub async fn create(
+        thread_store: Arc<dyn ThreadStore>,
+        params: CreateThreadParams,
+    ) -> ThreadStoreResult<Self> {
+        let thread_id = params.thread_id;
+        let history_mode = params.history_mode;
+        let metadata_sync = ThreadMetadataSync::for_create(&params).await;
+        thread_store.create_thread(params).await?;
+        Ok(Self {
+            thread_id,
+            history_mode,
+            thread_store,
+            metadata_sync: Arc::new(Mutex::new(metadata_sync)),
+            persistence_telemetry: RolloutPersistenceTelemetry::new(thread_id),
+        })
+    }
+
+    /// Create a child thread with inherited model context already durable.
+    ///
+    /// The boundary belongs in session metadata before the copied prefix is written so history
+    /// projection can distinguish inherited context from the child's own records immediately.
+    pub async fn create_with_inherited_model_context(
+        thread_store: Arc<dyn ThreadStore>,
+        mut params: CreateThreadParams,
+        inherited_model_context: &[RolloutItem],
+        guard: &mut LiveThreadInitGuard,
+    ) -> ThreadStoreResult<Self> {
+        let persisted_prefix_item_count =
+            persisted_rollout_items(inherited_model_context, params.history_mode).len();
+        params.subagent_history_start_ordinal = Some(
+            u64::try_from(persisted_prefix_item_count)
+                .map_err(|_| ThreadStoreError::Internal {
+                    message: "inherited model context is too large".to_string(),
+                })?
+                .checked_add(1)
+                .ok_or_else(|| ThreadStoreError::Internal {
+                    message: "inherited model context is too large".to_string(),
+                })?,
+        );
+        let live_thread = guard.acquire(Self::create(thread_store, params)).await?;
+        live_thread
+            .persist_appended_items(inherited_model_context)
+            .await?;
+        Ok(live_thread)
+    }
+
+    pub async fn resume(
+        thread_store: Arc<dyn ThreadStore>,
+        history_mode: ThreadHistoryMode,
+        params: ResumeThreadParams,
+    ) -> ThreadStoreResult<Self> {
+        let thread_id = params.thread_id;
+        let should_load_history = params.history.is_none();
+        let include_archived = params.include_archived;
+        let metadata = if history_mode == ThreadHistoryMode::Paginated
+            && let Some(local_store) = thread_store.as_any().downcast_ref::<LocalThreadStore>()
+            && let Some(state_db) = local_store.state_db().await
+        {
+            state_db
+                .get_thread(thread_id)
+                .await
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to read thread metadata for {thread_id}: {err}"),
+                })?
+        } else {
+            None
+        };
+        let mut metadata_sync = ThreadMetadataSync::for_resume(&params, metadata.as_ref());
+        thread_store.resume_thread(params).await?;
+        if should_load_history {
+            match thread_store
+                .load_history(LoadThreadHistoryParams {
+                    thread_id,
+                    include_archived,
+                })
+                .await
+            {
+                Ok(history) => metadata_sync.record_resume_history(&history.items),
+                Err(err) => {
+                    if let Err(discard_err) = thread_store.discard_thread(thread_id).await {
+                        warn!(
+                            "failed to discard thread persistence after resume history load failed: {discard_err}"
+                        );
+                    }
+                    return Err(err);
+                }
+            }
+        }
+        Ok(Self {
+            thread_id,
+            history_mode,
+            thread_store,
+            metadata_sync: Arc::new(Mutex::new(metadata_sync)),
+            persistence_telemetry: RolloutPersistenceTelemetry::new(thread_id),
+        })
+    }
+
+    #[tracing::instrument(
+        level = "trace",
+        skip_all,
+        fields(item_count = raw_items.len())
+    )]
+    pub async fn append_items(&self, raw_items: &[RolloutItem]) -> ThreadStoreResult<()> {
+        let items = self.persist_appended_items(raw_items).await?;
+        if items.is_empty() {
+            return Ok(());
+        }
+        let update = self
+            .metadata_sync
+            .lock()
+            .await
+            .observe_appended_items(items.as_slice());
+        if let Some(update) = update {
+            self.thread_store
+                .update_thread_metadata(UpdateThreadMetadataParams {
+                    thread_id: self.thread_id,
+                    patch: update.patch.clone(),
+                    include_archived: true,
+                })
+                .await?;
+            self.metadata_sync
+                .lock()
+                .await
+                .mark_pending_update_applied(&update);
+        }
+        Ok(())
+    }
+
+    async fn persist_appended_items(
+        &self,
+        raw_items: &[RolloutItem],
+    ) -> ThreadStoreResult<Vec<RolloutItem>> {
+        // Empty appends are intentionally ignored rather than represented as zero-sized batches.
+        if raw_items.is_empty() {
+            return Ok(Vec::new());
+        }
+        let (items, measurement) = if self.persistence_telemetry.is_enabled() {
+            let (items, measurement) =
+                measure_and_filter_rollout_items(raw_items, self.history_mode);
+            (items, Some(measurement))
+        } else {
+            (persisted_rollout_items(raw_items, self.history_mode), None)
+        };
+        self.thread_store
+            .append_items(AppendThreadItemsParams {
+                thread_id: self.thread_id,
+                items: raw_items.to_vec(),
+            })
+            .await?;
+        if let Some(measurement) = measurement.as_ref() {
+            self.persistence_telemetry
+                .record_batch(raw_items, measurement);
+        }
+        Ok(items)
+    }
+
+    pub async fn persist(&self, context: PersistContext) -> ThreadStoreResult<()> {
+        if context.allows_background_persistence() {
+            self.flush_pending_metadata_update_for_existing_history()
+                .await?;
+        }
+        self.thread_store
+            .persist_thread(self.thread_id, context)
+            .await?;
+        self.flush_pending_metadata_update().await
+    }
+
+    pub async fn flush(&self) -> ThreadStoreResult<()> {
+        self.thread_store.flush_thread(self.thread_id).await?;
+        self.flush_pending_metadata_update_for_existing_history()
+            .await
+    }
+
+    pub async fn shutdown(&self) -> ThreadStoreResult<()> {
+        let metadata_result = self
+            .flush_pending_metadata_update_for_existing_history()
+            .await;
+        let shutdown_result = self.thread_store.shutdown_thread(self.thread_id).await;
+        match (metadata_result, shutdown_result) {
+            (Err(metadata_error), Err(shutdown_error)) => Err(ThreadStoreError::Internal {
+                message: format!(
+                    "thread metadata update failed: {metadata_error}; thread shutdown failed: {shutdown_error}"
+                ),
+            }),
+            (Err(metadata_error), Ok(())) => Err(metadata_error),
+            (Ok(()), result) => result,
+        }
+    }
+
+    pub async fn discard(&self) -> ThreadStoreResult<()> {
+        self.thread_store.discard_thread(self.thread_id).await
+    }
+
+    pub async fn load_history(
+        &self,
+        include_archived: bool,
+    ) -> ThreadStoreResult<StoredThreadHistory> {
+        self.thread_store
+            .load_history(LoadThreadHistoryParams {
+                thread_id: self.thread_id,
+                include_archived,
+            })
+            .await
+    }
+
+    pub async fn read_thread(
+        &self,
+        include_archived: bool,
+        include_history: bool,
+    ) -> ThreadStoreResult<StoredThread> {
+        self.thread_store
+            .read_thread(ReadThreadParams {
+                thread_id: self.thread_id,
+                include_archived,
+                include_history,
+            })
+            .await
+    }
+
+    pub async fn update_memory_mode(
+        &self,
+        mode: ThreadMemoryMode,
+        include_archived: bool,
+    ) -> ThreadStoreResult<()> {
+        self.flush_pending_metadata_update().await?;
+        self.thread_store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id: self.thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(mode),
+                    ..Default::default()
+                },
+                include_archived,
+            })
+            .await?;
+        Ok(())
+    }
+
+    /// Updates metadata while preserving this API's materialized-thread contract.
+    ///
+    /// Stores may successfully return no thread for a no-op update, so this reads the thread as a
+    /// fallback in that case.
+    pub async fn update_metadata(
+        &self,
+        patch: ThreadMetadataPatch,
+        include_archived: bool,
+    ) -> ThreadStoreResult<StoredThread> {
+        self.flush_pending_metadata_update().await?;
+        let updated = self
+            .thread_store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id: self.thread_id,
+                patch,
+                include_archived,
+            })
+            .await?;
+        match updated {
+            Some(thread) => Ok(thread),
+            None => {
+                self.read_thread(include_archived, /*include_history*/ false)
+                    .await
+            }
+        }
+    }
+
+    /// Returns the live local rollout path for legacy local-only callers.
+    ///
+    /// Remote stores do not expose rollout files, so they return `Ok(None)`.
+    pub async fn local_rollout_path(&self) -> ThreadStoreResult<Option<PathBuf>> {
+        let Some(local_store) = self
+            .thread_store
+            .as_any()
+            .downcast_ref::<LocalThreadStore>()
+        else {
+            return Ok(None);
+        };
+        local_store
+            .live_rollout_path(self.thread_id)
+            .await
+            .map(Some)
+    }
+
+    async fn flush_pending_metadata_update(&self) -> ThreadStoreResult<()> {
+        let update = self.metadata_sync.lock().await.take_pending_update();
+        self.apply_pending_metadata_update(update).await
+    }
+
+    async fn flush_pending_metadata_update_for_existing_history(&self) -> ThreadStoreResult<()> {
+        let update = self
+            .metadata_sync
+            .lock()
+            .await
+            .take_pending_update_for_existing_history();
+        self.apply_pending_metadata_update(update).await
+    }
+
+    async fn apply_pending_metadata_update(
+        &self,
+        update: Option<crate::thread_metadata_sync::PendingThreadMetadataPatch>,
+    ) -> ThreadStoreResult<()> {
+        let Some(update) = update else {
+            return Ok(());
+        };
+        self.thread_store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id: self.thread_id,
+                patch: update.patch.clone(),
+                include_archived: true,
+            })
+            .await?;
+        self.metadata_sync
+            .lock()
+            .await
+            .mark_pending_update_applied(&update);
+        Ok(())
+    }
+}
diff --git a/codex-rs/thread-store/src/local/archive_thread.rs b/codex-rs/thread-store/src/local/archive_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..397ab0f9e26dfcd811310b77ee882c775a28fbb4
--- /dev/null
+++ b/codex-rs/thread-store/src/local/archive_thread.rs
@@ -0,0 +1,371 @@
+use super::LocalThreadStore;
+use super::helpers::owned_rollout_paths_from_index;
+use super::helpers::restore_rollout_moves;
+use super::helpers::rollout_path_is_archived;
+use super::helpers::scoped_rollout_path;
+use super::helpers::validated_rollout_file_name;
+use crate::ArchiveThreadsParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use chrono::Utc;
+use codex_rollout::RolloutReferenceIndex;
+use tracing::warn;
+
+use super::thread_rollout_resolver;
+pub(super) async fn archive_threads(
+    store: &LocalThreadStore,
+    params: ArchiveThreadsParams,
+) -> ThreadStoreResult<Vec<codex_protocol::ThreadId>> {
+    let thread_ids = params.thread_ids;
+    if thread_ids.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let mut lock_thread_ids = params.writer_lock_thread_ids;
+    lock_thread_ids.extend(thread_ids.iter().copied());
+    lock_thread_ids.sort_unstable_by_key(ToString::to_string);
+    lock_thread_ids.dedup();
+    let mut _lifecycle_guards = Vec::with_capacity(lock_thread_ids.len());
+    for thread_id in &lock_thread_ids {
+        _lifecycle_guards.push(store.live_writer_locks.lock_lifecycle(*thread_id).await);
+    }
+    let mut _live_writer_guards = Vec::with_capacity(lock_thread_ids.len());
+    for thread_id in &lock_thread_ids {
+        _live_writer_guards.push(store.live_writer_locks.lock(*thread_id).await);
+        if store.live_recorders.lock().await.contains_key(thread_id) {
+            return Err(ThreadStoreError::Conflict {
+                message: format!("thread {thread_id} already has an active writer"),
+            });
+        }
+    }
+    let _writer_guards = store.acquire_writer_locks(&lock_thread_ids).await?;
+    // Only inspect active files whose names belong to the threads being archived.
+    let reference_index = RolloutReferenceIndex::scan_unarchived_threads(
+        store.config.codex_home.as_path(),
+        &thread_ids,
+    )
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to scan thread rollout files: {err}"),
+    })?;
+
+    let parent_thread_id = thread_ids[0];
+    let mut archived_thread_ids = Vec::new();
+    for thread_id in thread_ids {
+        let rollout_paths = owned_rollout_paths_from_index(&reference_index, thread_id);
+        match archive_thread_with_paths(store, thread_id, rollout_paths).await {
+            Ok(()) => archived_thread_ids.push(thread_id),
+            Err(err) if archived_thread_ids.is_empty() => return Err(err),
+            Err(err) => warn!(
+                "failed to archive spawned descendant thread {thread_id} while archiving {parent_thread_id}: {err}"
+            ),
+        }
+    }
+    Ok(archived_thread_ids)
+}
+
+async fn archive_thread_with_paths(
+    store: &LocalThreadStore,
+    thread_id: codex_protocol::ThreadId,
+    mut rollout_paths: Vec<std::path::PathBuf>,
+) -> ThreadStoreResult<()> {
+    let state_db_ctx = store.state_db().await;
+    let selected_rollout_path = thread_rollout_resolver::resolve_current(store, thread_id)
+        .await?
+        .map(|resolved| resolved.path)
+        .ok_or_else(|| ThreadStoreError::InvalidRequest {
+            message: format!("no rollout found for thread id {thread_id}"),
+        })?;
+
+    let archive_folder = store
+        .config
+        .codex_home
+        .join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR);
+    std::fs::create_dir_all(&archive_folder).map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to archive thread: {err}"),
+    })?;
+    if !rollout_paths.contains(&selected_rollout_path) {
+        rollout_paths.push(selected_rollout_path.clone());
+    }
+    let mut archived_path = None;
+    let mut rollout_moves = Vec::new();
+    for rollout_path in rollout_paths {
+        if rollout_path_is_archived(store.config.codex_home.as_path(), rollout_path.as_path()) {
+            continue;
+        }
+        let canonical_rollout_path = scoped_rollout_path(
+            store.config.codex_home.join(codex_rollout::SESSIONS_SUBDIR),
+            rollout_path.as_path(),
+            "sessions",
+        )?;
+        let file_name =
+            validated_rollout_file_name(canonical_rollout_path.as_path(), rollout_path.as_path())?;
+        let destination = archive_folder.join(&file_name);
+        if rollout_path == selected_rollout_path {
+            archived_path = Some(destination.clone());
+        }
+        if !rollout_moves
+            .iter()
+            .any(|(source, _)| source == &canonical_rollout_path)
+        {
+            rollout_moves.push((canonical_rollout_path, destination));
+        }
+    }
+    let archived_path = archived_path.ok_or_else(|| ThreadStoreError::Internal {
+        message: format!("failed to archive selected rollout for thread {thread_id}"),
+    })?;
+
+    for (index, (source, destination)) in rollout_moves.iter().enumerate() {
+        if let Err(err) = std::fs::rename(source, destination) {
+            if let Err(restore_err) = restore_rollout_moves(&rollout_moves[..index]) {
+                return Err(ThreadStoreError::Internal {
+                    message: format!(
+                        "failed to archive thread: {err}; failed to restore moved rollouts: {restore_err}"
+                    ),
+                });
+            }
+            return Err(ThreadStoreError::Internal {
+                message: format!("failed to archive thread: {err}"),
+            });
+        }
+    }
+
+    if let Some(ctx) = state_db_ctx
+        && let Err(err) = ctx
+            .mark_archived(thread_id, archived_path.as_path(), Utc::now())
+            .await
+    {
+        if let Err(restore_err) = restore_rollout_moves(&rollout_moves) {
+            return Err(ThreadStoreError::Internal {
+                message: format!(
+                    "failed to update archived thread metadata: {err}; failed to restore moved rollouts: {restore_err}"
+                ),
+            });
+        }
+        return Err(ThreadStoreError::Internal {
+            message: format!("failed to update archived thread metadata: {err}"),
+        });
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::Duration;
+
+    use chrono::Utc;
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::SessionSource;
+    use codex_protocol::protocol::ThreadHistoryMode;
+    use codex_rollout::ARCHIVED_SESSIONS_SUBDIR;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::ArchiveThreadParams;
+    use crate::ListThreadsParams;
+    use crate::ThreadSortKey;
+    use crate::ThreadStore;
+    use crate::local::LocalThreadStore;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_session_file;
+    use crate::local::test_support::write_session_file_with_history_mode;
+
+    #[tokio::test]
+    async fn archive_waits_for_fork_reservation_without_holding_writer_lock() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(205);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let reservation = store.live_writer_locks.reserve_lifecycle(thread_id).await;
+        let mut archive = Box::pin(store.archive_thread(ArchiveThreadParams { thread_id }));
+
+        tokio::select! {
+            biased;
+            result = &mut archive => panic!("archive completed while the source was reserved: {result:?}"),
+            _ = tokio::task::yield_now() => {}
+        }
+        let writer_guard = tokio::time::timeout(
+            Duration::from_secs(1),
+            store.live_writer_locks.lock(thread_id),
+        )
+        .await
+        .expect("pending archive should not hold the writer lock");
+        drop(writer_guard);
+        drop(reservation);
+
+        archive.await.expect("archive reserved thread");
+        assert!(!active_path.exists());
+    }
+
+    #[tokio::test]
+    async fn archive_threads_rejects_owned_descendants_before_archiving_anything() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let owner = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        for (parent_uuid, child_uuid, history_mode) in [
+            (
+                Uuid::from_u128(203),
+                Uuid::from_u128(204),
+                ThreadHistoryMode::Legacy,
+            ),
+            (
+                Uuid::from_u128(206),
+                Uuid::from_u128(207),
+                ThreadHistoryMode::Paginated,
+            ),
+        ] {
+            let parent_thread_id =
+                ThreadId::from_string(&parent_uuid.to_string()).expect("valid parent thread id");
+            let parent_path = write_session_file_with_history_mode(
+                home.path(),
+                "2025-01-03T12-00-00",
+                parent_uuid,
+                history_mode,
+            )
+            .expect("parent session file");
+            let child_thread_id =
+                ThreadId::from_string(&child_uuid.to_string()).expect("valid child thread id");
+            let child_path = write_session_file_with_history_mode(
+                home.path(),
+                "2025-01-03T12-00-01",
+                child_uuid,
+                history_mode,
+            )
+            .expect("child session file");
+            let _owner_guard = owner
+                .acquire_writer_lock(child_thread_id)
+                .expect("acquire child writer lock");
+
+            let error = store
+                .archive_threads(ArchiveThreadsParams {
+                    thread_ids: vec![parent_thread_id, child_thread_id],
+                    writer_lock_thread_ids: Vec::new(),
+                })
+                .await
+                .expect_err("owned descendant should block archive");
+
+            assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+            assert!(parent_path.exists());
+            assert!(child_path.exists());
+        }
+    }
+
+    #[tokio::test]
+    async fn archive_thread_moves_rollout_to_archived_collection() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(201);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+
+        store
+            .archive_thread(ArchiveThreadParams { thread_id })
+            .await
+            .expect("archive thread");
+
+        assert!(!active_path.exists());
+        let archived_path = home
+            .path()
+            .join(ARCHIVED_SESSIONS_SUBDIR)
+            .join(active_path.file_name().expect("file name"));
+        assert!(archived_path.exists());
+
+        let archived = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: crate::SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: true,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: false,
+            })
+            .await
+            .expect("archived listing");
+        assert_eq!(archived.items.len(), 1);
+        assert_eq!(archived.items[0].thread_id, thread_id);
+        assert_eq!(archived.items[0].rollout_path, Some(archived_path));
+        assert_eq!(
+            archived.items[0].archived_at,
+            Some(archived.items[0].updated_at)
+        );
+    }
+
+    #[tokio::test]
+    async fn archive_thread_deduplicates_rollout_paths_and_updates_sqlite_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(202);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let alternate_directory = active_path
+            .parent()
+            .expect("session directory")
+            .join("alternate");
+        std::fs::create_dir(&alternate_directory).expect("alternate session directory");
+        let selected_rollout_path = alternate_directory
+            .join("..")
+            .join(active_path.file_name().expect("file name"));
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        runtime
+            .mark_backfill_complete(/*last_watermark*/ None)
+            .await
+            .expect("backfill should be complete");
+        let mut builder = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            selected_rollout_path,
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        builder.cli_version = Some("test_version".to_string());
+        let metadata = builder.build(config.default_model_provider_id.as_str());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        store
+            .archive_thread(ArchiveThreadParams { thread_id })
+            .await
+            .expect("archive thread");
+
+        let archived_path = home
+            .path()
+            .join(ARCHIVED_SESSIONS_SUBDIR)
+            .join(active_path.file_name().expect("file name"));
+        let updated = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("state db read should succeed")
+            .expect("thread metadata should exist");
+        assert_eq!(updated.rollout_path, archived_path);
+        assert!(updated.archived_at.is_some());
+        assert_eq!(updated.recency_at, metadata.recency_at);
+    }
+}
diff --git a/codex-rs/thread-store/src/local/compression_writer_tests.rs b/codex-rs/thread-store/src/local/compression_writer_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..56ed82867a9a71ce083cf453aa56a7213719a981
--- /dev/null
+++ b/codex-rs/thread-store/src/local/compression_writer_tests.rs
@@ -0,0 +1,197 @@
+//! Exercises compression through local-store ownership, including detached recorder work.
+
+use std::fs;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Duration;
+use std::time::SystemTime;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::WriterLockCoordinator;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use tempfile::TempDir;
+use uuid::Uuid;
+
+use super::LocalThreadStore;
+use super::test_support::test_config;
+use super::test_support::write_session_file;
+use crate::ResumeThreadParams;
+use crate::ThreadMetadataPatch;
+use crate::ThreadPersistenceMetadata;
+use crate::ThreadStore;
+use crate::UpdateThreadMetadataParams;
+
+type TestResult<T = ()> = Result<T, Box<dyn std::error::Error>>;
+
+fn fixture() -> TestResult<(TempDir, ThreadId, PathBuf)> {
+    let home = TempDir::new()?;
+    let id = Uuid::new_v4();
+    let path = write_session_file(home.path(), "2025-01-03T12-00-00", id)?;
+    Ok((home, ThreadId::from_string(&id.to_string())?, path))
+}
+
+fn age(path: &Path) -> TestResult<()> {
+    fs::OpenOptions::new().write(true).open(path)?.set_times(
+        fs::FileTimes::new().set_modified(SystemTime::now() - Duration::from_secs(8 * 86400)),
+    )?;
+    Ok(())
+}
+
+fn resume(thread_id: ThreadId, path: &Path, home: &Path) -> ResumeThreadParams {
+    ResumeThreadParams {
+        thread_id,
+        rollout_path: Some(path.to_path_buf()),
+        history: None,
+        include_archived: true,
+        metadata: ThreadPersistenceMetadata {
+            cwd: Some(home.to_path_buf()),
+            model_provider: "test-provider".into(),
+            memory_mode: ThreadMemoryMode::Enabled,
+        },
+    }
+}
+
+fn message() -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::UserMessage(UserMessageEvent {
+        message: "acknowledged write".into(),
+        ..Default::default()
+    }))
+}
+
+async fn wait_until(ready: impl Fn() -> bool) {
+    tokio::time::timeout(Duration::from_secs(10), async {
+        while !ready() {
+            tokio::time::sleep(Duration::from_millis(1)).await;
+        }
+    })
+    .await
+    .expect("background file work completes");
+}
+
+async fn compress(home: &Path) -> TestResult<()> {
+    let marker = home.join(".tmp/rollout-compression.lock");
+    if marker.exists() {
+        fs::remove_file(&marker)?;
+    }
+    codex_rollout::spawn_rollout_compression_worker(home.to_path_buf());
+    // The marker proves startup; the maintenance lock proves every blocking job finished.
+    wait_until(|| {
+        marker.exists()
+            && codex_rollout::try_acquire_rollout_maintenance_lock(home)
+                .unwrap()
+                .is_some()
+    })
+    .await;
+    Ok(())
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn idle_recorder_retains_stable_thread_ownership_after_store_drop() -> TestResult<()> {
+    let (home, thread_id, old_path) = fixture()?;
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let path = old_path.with_file_name(format!(
+        "rollout-2025-01-03T12-00-00-{thread_id}_{}.jsonl",
+        Uuid::new_v4()
+    ));
+    fs::rename(old_path, &path)?;
+    let cold = write_session_file(home.path(), "2025-01-03T12-00-01", Uuid::new_v4())?;
+    age(&cold)?;
+    store
+        .resume_thread(resume(thread_id, &path, home.path()))
+        .await?;
+    let recorder = store
+        .live_recorders
+        .lock()
+        .await
+        .get(&thread_id)
+        .unwrap()
+        .recorder
+        .clone();
+    drop(store);
+    age(&path)?;
+    let (mut expected, _, _) = RolloutRecorder::load_rollout_items(&path).await?;
+    compress(home.path()).await?;
+    assert!(path.exists());
+    assert!(!path.with_extension("jsonl.zst").exists());
+    assert!(cold.with_extension("jsonl.zst").exists());
+
+    recorder.record_canonical_items(&[message()]).await?;
+    drop(recorder);
+    let locks = Arc::new(WriterLockCoordinator::new(home.path()));
+    // No yield since enqueueing: only the background task can own the pending write now.
+    assert!(
+        matches!(locks.acquire(thread_id), Err(err) if err.kind() == std::io::ErrorKind::WouldBlock)
+    );
+    wait_until(|| locks.acquire(thread_id).is_ok()).await;
+    age(&path)?;
+    compress(home.path()).await?;
+    assert!(!path.exists());
+    expected.push(message());
+    let (actual, _, _) = RolloutRecorder::load_rollout_items(&path).await?;
+    assert_eq!(json!(actual), json!(expected));
+    Ok(())
+}
+
+#[tokio::test]
+async fn metadata_updates_share_ownership_and_resume_compressed_rollouts() -> TestResult<()> {
+    let (home, thread_id, path) = fixture()?;
+    let config = test_config(home.path());
+    let db = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await?;
+    let owner = LocalThreadStore::new(config.clone(), Some(db.clone()));
+    owner
+        .resume_thread(resume(thread_id, &path, home.path()))
+        .await?;
+    let competitor = LocalThreadStore::new(config, Some(db.clone()));
+    let mut patch = UpdateThreadMetadataParams {
+        thread_id,
+        include_archived: true,
+        patch: ThreadMetadataPatch {
+            memory_mode: Some(ThreadMemoryMode::Enabled),
+            ..Default::default()
+        },
+    };
+    owner.update_thread_metadata(patch.clone()).await?;
+    let original = fs::read(&path)?;
+    let indexed_mode = db.get_thread_memory_mode(thread_id).await?;
+    patch.patch.memory_mode = Some(ThreadMemoryMode::Disabled);
+    let error = competitor
+        .update_thread_metadata(patch.clone())
+        .await
+        .unwrap_err();
+    assert!(matches!(error, crate::ThreadStoreError::Conflict { .. }));
+    assert_eq!(fs::read(&path)?, original);
+    assert_eq!(db.get_thread_memory_mode(thread_id).await?, indexed_mode);
+    owner.update_thread_metadata(patch.clone()).await?;
+    owner.shutdown_thread(thread_id).await?;
+    let (items, _, _) = RolloutRecorder::load_rollout_items(&path).await?;
+    let mut expected = codex_rollout::read_session_meta_line(&path).await?;
+    expected.meta.memory_mode = Some("disabled".into());
+    expected.git = None;
+    assert_eq!(
+        json!(items.last()),
+        json!(Some(RolloutItem::SessionMeta(expected.clone())))
+    );
+
+    age(&path)?;
+    compress(home.path()).await?;
+    patch.patch.memory_mode = Some(ThreadMemoryMode::Enabled);
+    competitor.update_thread_metadata(patch).await?;
+    expected.meta.memory_mode = Some("enabled".into());
+    let (items, _, _) = RolloutRecorder::load_rollout_items(&path).await?;
+    assert_eq!(
+        json!(items.last()),
+        json!(Some(RolloutItem::SessionMeta(expected)))
+    );
+    Ok(())
+}
diff --git a/codex-rs/thread-store/src/local/create_thread.rs b/codex-rs/thread-store/src/local/create_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..70b27e7efaa44bf7b8986df5c701270d9d3aba1d
--- /dev/null
+++ b/codex-rs/thread-store/src/local/create_thread.rs
@@ -0,0 +1,67 @@
+use super::LocalThreadStore;
+use crate::CreateThreadParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::RolloutRecorderParams;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+pub(super) async fn create_thread(
+    store: &LocalThreadStore,
+    params: CreateThreadParams,
+    writer_lock: super::WriterLockGuard,
+) -> ThreadStoreResult<RolloutRecorder> {
+    let cwd = params
+        .metadata
+        .cwd
+        .clone()
+        .ok_or_else(|| ThreadStoreError::InvalidRequest {
+            message: "local thread store requires a cwd".to_string(),
+        })?;
+    let config = RolloutConfig {
+        codex_home: store.config.codex_home.clone(),
+        sqlite: store.config.sqlite.clone(),
+        cwd,
+        model_provider_id: params.metadata.model_provider.clone(),
+        generate_memories: matches!(params.metadata.memory_mode, ThreadMemoryMode::Enabled),
+    };
+    RolloutRecorder::new_with_writer_lock(
+        &config,
+        RolloutRecorderParams::new(
+            params.thread_id,
+            params.forked_from_id,
+            params.parent_thread_id,
+            params.source,
+            params.thread_source,
+            params.originator,
+            params.base_instructions,
+            params.dynamic_tools,
+        )
+        .with_session_id(params.session_id)
+        .with_selected_capability_roots(params.selected_capability_roots)
+        .with_runtime_workspace_roots(params.runtime_workspace_roots.map(|roots| {
+            roots
+                .into_iter()
+                .map(AbsolutePathBuf::into_path_buf)
+                .collect()
+        }))
+        .with_multi_agent_version(params.multi_agent_version)
+        .with_history_mode(params.history_mode)
+        .with_history_base(params.history_base)
+        .with_forked_from_ordinal_exclusive(
+            params
+                .forked_from_id
+                .and(params.history_base)
+                .map(|base| base.end_ordinal_exclusive),
+        )
+        .with_subagent_history_start_ordinal(params.subagent_history_start_ordinal)
+        .with_initial_window_id(params.initial_window_id),
+        writer_lock,
+    )
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to initialize local thread recorder: {err}"),
+    })
+}
diff --git a/codex-rs/thread-store/src/local/daybreak_metadata_tests.rs b/codex-rs/thread-store/src/local/daybreak_metadata_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..197398c0f8f3e072f5bcf1d04f5e72222fa77093
--- /dev/null
+++ b/codex-rs/thread-store/src/local/daybreak_metadata_tests.rs
@@ -0,0 +1,105 @@
+//! Covers the saved Daybreak preference independently of transcript history.
+
+use codex_protocol::ThreadId;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use uuid::Uuid;
+
+use super::LocalThreadStore;
+use super::test_support::test_config;
+use super::test_support::write_session_file;
+use crate::ReadThreadParams;
+use crate::ThreadMetadataPatch;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::UpdateThreadMetadataParams;
+
+#[tokio::test]
+async fn daybreak_preference_survives_reconciliation_and_cold_reads()
+-> Result<(), Box<dyn std::error::Error>> {
+    let home = TempDir::new()?;
+    let config = test_config(home.path());
+    let uuid = Uuid::new_v4();
+    let thread_id = ThreadId::from_string(&uuid.to_string())?;
+    let rollout_path = write_session_file(home.path(), "2025-01-03T14-20-00", uuid)?;
+    let original_rollout = std::fs::read(&rollout_path)?;
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await?;
+    let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+    for daybreak_enabled in [true, false] {
+        let updated = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    daybreak_enabled: Some(daybreak_enabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await?
+            .expect("updated thread");
+        assert_eq!(updated.daybreak_enabled, Some(daybreak_enabled));
+    }
+    let mut stale_metadata = runtime
+        .get_thread(thread_id)
+        .await?
+        .expect("saved metadata");
+    stale_metadata.daybreak_enabled = Some(true);
+    runtime.upsert_thread(&stale_metadata).await?;
+    codex_rollout::state_db::reconcile_rollout(
+        Some(runtime.as_ref()),
+        &rollout_path,
+        &config.default_model_provider_id,
+        /*builder*/ None,
+        &[],
+        /*archived_only*/ None,
+        /*new_thread_memory_mode*/ None,
+    )
+    .await;
+    drop(store);
+    drop(runtime);
+
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await?;
+    let store = LocalThreadStore::new(config, Some(runtime));
+    for include_history in [false, true] {
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history,
+            })
+            .await?;
+        assert_eq!(thread.daybreak_enabled, Some(false));
+    }
+    assert_eq!(std::fs::read(rollout_path)?, original_rollout);
+    Ok(())
+}
+
+#[tokio::test]
+async fn daybreak_preference_requires_sqlite() -> Result<(), Box<dyn std::error::Error>> {
+    let home = TempDir::new()?;
+    let uuid = Uuid::new_v4();
+    let thread_id = ThreadId::from_string(&uuid.to_string())?;
+    write_session_file(home.path(), "2025-01-03T14-20-00", uuid)?;
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let result = store
+        .update_thread_metadata(UpdateThreadMetadataParams {
+            thread_id,
+            patch: ThreadMetadataPatch {
+                daybreak_enabled: Some(false),
+                ..Default::default()
+            },
+            include_archived: false,
+        })
+        .await;
+    assert!(matches!(result, Err(ThreadStoreError::Internal { .. })));
+    Ok(())
+}
diff --git a/codex-rs/thread-store/src/local/delete_thread.rs b/codex-rs/thread-store/src/local/delete_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..775344a783101bff14de7e532f8a063afe037be8
--- /dev/null
+++ b/codex-rs/thread-store/src/local/delete_thread.rs
@@ -0,0 +1,876 @@
+//! Local hard-delete support for persisted threads.
+//!
+//! Existing rollout files are deleted before this operation reports success. A rollout file that
+//! vanishes after discovery counts as already deleted. Main state DB rows are deleted after every
+//! associated rollout is removed, under the same lifecycle lock, so queued artifact mutations cannot
+//! use deleted thread metadata.
+
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::io::ErrorKind;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_rollout::ARCHIVED_SESSIONS_SUBDIR;
+use codex_rollout::RolloutReferenceIndex;
+use codex_rollout::SESSIONS_SUBDIR;
+use codex_rollout::find_archived_thread_path_by_id_str;
+use codex_rollout::find_thread_path_by_id_str;
+use codex_rollout::remove_thread_name_entries;
+
+use super::LocalThreadStore;
+use super::helpers::scoped_rollout_path;
+use super::helpers::validated_rollout_file_name;
+use crate::DeleteThreadParams;
+use crate::DeleteThreadsParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+struct ThreadRollouts {
+    thread_id: codex_protocol::ThreadId,
+    rollout_ids: HashSet<codex_protocol::ThreadId>,
+    paths: Vec<PathBuf>,
+}
+
+impl ThreadRollouts {
+    fn from_index(
+        reference_index: &RolloutReferenceIndex,
+        thread_id: codex_protocol::ThreadId,
+    ) -> Self {
+        let mut rollout_ids = HashSet::new();
+        let paths = reference_index
+            .rollouts_for_thread(thread_id)
+            .map(|(rollout_id, path)| {
+                rollout_ids.insert(rollout_id);
+                path.to_path_buf()
+            })
+            .collect();
+        Self {
+            thread_id,
+            rollout_ids,
+            paths,
+        }
+    }
+
+    fn add_path(&mut self, path: PathBuf) {
+        if let Some(rollout_id) = codex_rollout::rollout_id_from_path(path.as_path()) {
+            self.rollout_ids.insert(rollout_id);
+        }
+        if !self.paths.contains(&path) {
+            self.paths.push(path);
+        }
+    }
+}
+
+pub(super) async fn delete_thread(
+    store: &LocalThreadStore,
+    params: DeleteThreadParams,
+) -> ThreadStoreResult<()> {
+    let thread_id = params.thread_id;
+    let _lifecycle_guard = store.live_writer_locks.lock_lifecycle(thread_id).await;
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    let reference_index = scan_reference_index(store).await?;
+    let thread_rollouts = ThreadRollouts::from_index(&reference_index, thread_id);
+    ensure_no_external_references(&reference_index, std::slice::from_ref(&thread_rollouts))?;
+    let mut writer_guards = store.acquire_writer_locks(&[thread_id]).await?;
+    let found_rollout =
+        match delete_thread_after_reference_check(store, thread_rollouts, &mut writer_guards).await
+        {
+            Ok(()) => true,
+            Err(ThreadStoreError::ThreadNotFound { .. }) => false,
+            Err(err) => return Err(err),
+        };
+    let deleted_state_rows = delete_state_rows(store, &[thread_id]).await?;
+    if found_rollout || deleted_state_rows > 0 {
+        Ok(())
+    } else {
+        Err(ThreadStoreError::ThreadNotFound { thread_id })
+    }
+}
+
+pub(super) async fn delete_threads(
+    store: &LocalThreadStore,
+    params: DeleteThreadsParams,
+) -> ThreadStoreResult<()> {
+    let thread_ids = params.thread_ids;
+    if thread_ids.is_empty() {
+        return Ok(());
+    }
+
+    let mut lock_thread_ids = thread_ids.clone();
+    lock_thread_ids.sort_unstable_by_key(ToString::to_string);
+    lock_thread_ids.dedup();
+    let mut _lifecycle_guards = Vec::with_capacity(lock_thread_ids.len());
+    for thread_id in &lock_thread_ids {
+        _lifecycle_guards.push(store.live_writer_locks.lock_lifecycle(*thread_id).await);
+    }
+    let mut _live_writer_guards = Vec::with_capacity(lock_thread_ids.len());
+    for &thread_id in &lock_thread_ids {
+        _live_writer_guards.push(store.live_writer_locks.lock(thread_id).await);
+    }
+
+    let reference_index = scan_reference_index(store).await?;
+    let thread_rollouts = thread_ids
+        .iter()
+        .map(|thread_id| ThreadRollouts::from_index(&reference_index, *thread_id))
+        .collect::<Vec<_>>();
+    ensure_no_external_references(&reference_index, thread_rollouts.as_slice())?;
+
+    let mut writer_guards = store.acquire_writer_locks(&lock_thread_ids).await?;
+    for thread_rollouts in thread_rollouts {
+        match delete_thread_after_reference_check(store, thread_rollouts, &mut writer_guards).await
+        {
+            Ok(()) | Err(ThreadStoreError::ThreadNotFound { .. }) => {}
+            Err(err) => return Err(err),
+        }
+    }
+    // Retain the complete retry graph until every rollout has been removed.
+    delete_state_rows(store, &thread_ids).await?;
+    Ok(())
+}
+
+async fn delete_state_rows(
+    store: &LocalThreadStore,
+    thread_ids: &[codex_protocol::ThreadId],
+) -> ThreadStoreResult<u64> {
+    let Some(state_db) = store.state_db.as_ref() else {
+        return Ok(0);
+    };
+    state_db
+        .delete_threads_strict(thread_ids)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to delete thread state: {err}"),
+        })
+}
+
+fn ensure_no_external_references(
+    reference_index: &RolloutReferenceIndex,
+    thread_rollouts: &[ThreadRollouts],
+) -> ThreadStoreResult<()> {
+    let deletion_rollout_ids = thread_rollouts
+        .iter()
+        .flat_map(|thread_rollouts| thread_rollouts.rollout_ids.iter().copied())
+        .collect::<HashSet<_>>();
+    let mut internal_reference_counts = HashMap::new();
+    for source_rollout_id in &deletion_rollout_ids {
+        if let Some(history_base) = reference_index.history_base(*source_rollout_id)
+            && history_base.thread_id != *source_rollout_id
+            && deletion_rollout_ids.contains(&history_base.thread_id)
+        {
+            *internal_reference_counts
+                .entry(history_base.thread_id)
+                .or_default() += 1;
+        }
+    }
+    for thread_rollouts in thread_rollouts {
+        if thread_rollouts.rollout_ids.iter().any(|rollout_id| {
+            let internal_reference_count = internal_reference_counts
+                .get(rollout_id)
+                .copied()
+                .unwrap_or_default();
+            reference_index.reference_count(*rollout_id) > internal_reference_count
+        }) {
+            return Err(referenced_thread_error(thread_rollouts.thread_id));
+        }
+    }
+    Ok(())
+}
+
+async fn scan_reference_index(
+    store: &LocalThreadStore,
+) -> ThreadStoreResult<RolloutReferenceIndex> {
+    RolloutReferenceIndex::scan(store.config.codex_home.as_path())
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to scan fork history references: {err}"),
+        })
+}
+
+fn referenced_thread_error(thread_id: codex_protocol::ThreadId) -> ThreadStoreError {
+    ThreadStoreError::InvalidRequest {
+        message: format!("cannot delete thread {thread_id}: forked history still references it"),
+    }
+}
+
+async fn delete_thread_after_reference_check(
+    store: &LocalThreadStore,
+    mut thread_rollouts: ThreadRollouts,
+    writer_guards: &mut Vec<super::WriterLockGuard>,
+) -> ThreadStoreResult<()> {
+    let thread_id = thread_rollouts.thread_id;
+    let thread_id_str = thread_id.to_string();
+    let state_db_ctx = store.state_db().await;
+    match find_thread_path_by_id_str(
+        store.config.codex_home.as_path(),
+        thread_id_str.as_str(),
+        state_db_ctx.as_deref(),
+    )
+    .await
+    {
+        Ok(Some(path)) => thread_rollouts.add_path(path),
+        Ok(None) => {}
+        Err(err) => {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!("failed to locate thread id {thread_id}: {err}"),
+            });
+        }
+    }
+    match find_archived_thread_path_by_id_str(
+        store.config.codex_home.as_path(),
+        thread_id_str.as_str(),
+        state_db_ctx.as_deref(),
+    )
+    .await
+    {
+        Ok(Some(path)) => thread_rollouts.add_path(path),
+        Ok(None) => {}
+        Err(err) => {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!("failed to locate archived thread id {thread_id}: {err}"),
+            });
+        }
+    }
+    thread_rollouts.rollout_ids.insert(thread_id);
+    for rollout_id in thread_rollouts.rollout_ids {
+        super::thread_history::delete_thread(store, rollout_id).await?;
+    }
+
+    // Stop queued file work before removing files, retaining ownership until cleanup finishes.
+    let live_entry = store.live_recorders.lock().await.remove(&thread_id);
+    if let Some(entry) = live_entry {
+        writer_guards.push(entry.writer_lock);
+        entry
+            .recorder
+            .discard()
+            .await
+            .map_err(|err| ThreadStoreError::Internal {
+                message: format!("failed to stop thread writer before deletion: {err}"),
+            })?;
+    }
+    let found_rollout_path = !thread_rollouts.paths.is_empty();
+    for rollout_path in thread_rollouts.paths {
+        delete_rollout_file(store, rollout_path.as_path())?;
+    }
+    remove_thread_name_entries(store.config.codex_home.as_path(), thread_id)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to delete thread name index entries for {thread_id}: {err}"),
+        })?;
+
+    if !found_rollout_path {
+        return Err(ThreadStoreError::ThreadNotFound { thread_id });
+    }
+
+    Ok(())
+}
+
+fn delete_rollout_file(store: &LocalThreadStore, rollout_path: &Path) -> ThreadStoreResult<bool> {
+    let plain_path = codex_rollout::plain_rollout_path(rollout_path);
+    let compressed_path = plain_path.with_extension("jsonl.zst");
+    let deleted_plain = delete_rollout_path(store, plain_path.as_path())?;
+    let deleted_compressed = delete_rollout_path(store, compressed_path.as_path())?;
+    Ok(deleted_plain || deleted_compressed)
+}
+
+fn delete_rollout_path(store: &LocalThreadStore, rollout_path: &Path) -> ThreadStoreResult<bool> {
+    let canonical_rollout_path = scoped_rollout_path(
+        store.config.codex_home.join(SESSIONS_SUBDIR),
+        rollout_path,
+        "sessions",
+    )
+    .or_else(|_| {
+        scoped_rollout_path(
+            store.config.codex_home.join(ARCHIVED_SESSIONS_SUBDIR),
+            rollout_path,
+            "archived sessions",
+        )
+    })
+    .or_else(|err| match rollout_path.try_exists() {
+        Ok(false) => Ok(rollout_path.to_path_buf()),
+        Ok(true) | Err(_) => Err(err),
+    })?;
+    validated_rollout_file_name(&canonical_rollout_path, rollout_path)?;
+    match std::fs::remove_file(&canonical_rollout_path) {
+        Ok(()) => Ok(true),
+        Err(err) if err.kind() == ErrorKind::NotFound => Ok(false),
+        Err(err) => Err(ThreadStoreError::Internal {
+            message: format!(
+                "failed to delete rollout file `{}`: {err}",
+                canonical_rollout_path.display()
+            ),
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::HistoryPosition;
+    use codex_protocol::protocol::ThreadHistoryMode;
+    use codex_protocol::protocol::ThreadMemoryMode;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::ResumeThreadParams;
+    use crate::ThreadPersistenceMetadata;
+    use crate::ThreadStore;
+    use crate::local::LocalThreadStore;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_archived_session_file;
+    use crate::local::test_support::write_session_file;
+    use crate::local::test_support::write_session_file_with;
+    use crate::local::test_support::write_session_file_with_history_mode;
+
+    #[tokio::test]
+    async fn delete_thread_removes_active_and_archived_rollouts() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", Uuid::from_u128(301))
+                .expect("session file");
+        let compressed_path = active_path.with_extension("jsonl.zst");
+        std::fs::write(&compressed_path, b"compressed sibling").expect("compressed sibling");
+        let cases = [
+            (Uuid::from_u128(301), active_path),
+            (
+                Uuid::from_u128(302),
+                write_archived_session_file(
+                    home.path(),
+                    "2025-01-03T12-00-00",
+                    Uuid::from_u128(302),
+                )
+                .expect("archived session file"),
+            ),
+        ];
+
+        for (uuid, path) in cases {
+            let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+            store
+                .delete_thread(DeleteThreadParams { thread_id })
+                .await
+                .expect("delete thread");
+
+            assert!(!path.exists());
+        }
+        assert!(!compressed_path.exists());
+    }
+
+    #[tokio::test]
+    async fn delete_thread_rejects_referenced_paginated_history() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let source_uuid = Uuid::from_u128(303);
+        let source_thread_id =
+            ThreadId::from_string(&source_uuid.to_string()).expect("valid source thread id");
+        let source_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            source_uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("source session file");
+        let child_path = write_session_file_with(
+            home.path(),
+            home.path().join(ARCHIVED_SESSIONS_SUBDIR),
+            "2025-01-03T12-00-01",
+            Uuid::from_u128(304),
+            "Archived user message",
+            Some("test-provider"),
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("child session file");
+        set_history_base(
+            child_path.as_path(),
+            HistoryPosition {
+                thread_id: source_thread_id,
+                end_ordinal_exclusive: 1,
+                end_byte_offset: std::fs::metadata(source_path.as_path())
+                    .expect("source rollout metadata")
+                    .len(),
+            },
+        );
+
+        let err = store
+            .delete_thread(DeleteThreadParams {
+                thread_id: source_thread_id,
+            })
+            .await
+            .expect_err("referenced source should not be deleted");
+
+        assert_eq!(
+            err.to_string(),
+            format!(
+                "invalid thread-store request: cannot delete thread {source_thread_id}: forked history still references it"
+            )
+        );
+        assert!(source_path.exists());
+    }
+
+    #[tokio::test]
+    async fn delete_thread_rejects_reference_to_reverted_rollout() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_uuid = Uuid::from_u128(320);
+        let thread_id = ThreadId::from_string(&thread_uuid.to_string()).expect("thread id");
+        let source_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            thread_uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("source session file");
+        let replacement_uuid = Uuid::from_u128(321);
+        let replacement_rollout_id =
+            ThreadId::from_string(&replacement_uuid.to_string()).expect("replacement rollout id");
+        let replacement_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-01",
+            replacement_uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("replacement session file");
+        set_thread_id(replacement_path.as_path(), thread_id);
+        set_history_base(
+            replacement_path.as_path(),
+            HistoryPosition {
+                thread_id,
+                end_ordinal_exclusive: 1,
+                end_byte_offset: std::fs::metadata(source_path.as_path())
+                    .expect("source rollout metadata")
+                    .len(),
+            },
+        );
+        let child_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-02",
+            Uuid::from_u128(322),
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("child session file");
+        set_history_base(
+            child_path.as_path(),
+            HistoryPosition {
+                thread_id: replacement_rollout_id,
+                end_ordinal_exclusive: 1,
+                end_byte_offset: std::fs::metadata(replacement_path.as_path())
+                    .expect("replacement rollout metadata")
+                    .len(),
+            },
+        );
+
+        let err = store
+            .delete_thread(DeleteThreadParams { thread_id })
+            .await
+            .expect_err("referenced replacement should not be deleted");
+
+        assert_eq!(
+            err.to_string(),
+            format!(
+                "invalid thread-store request: cannot delete thread {thread_id}: forked history still references it"
+            )
+        );
+        assert!(source_path.exists());
+        assert!(replacement_path.exists());
+    }
+
+    #[tokio::test]
+    async fn delete_thread_ignores_unreadable_reference_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let source_uuid = Uuid::from_u128(305);
+        let source_thread_id =
+            ThreadId::from_string(&source_uuid.to_string()).expect("valid source thread id");
+        let source_path = write_session_file(home.path(), "2025-01-03T12-00-00", source_uuid)
+            .expect("source session file");
+        let unreadable_path = source_path.with_file_name(format!(
+            "rollout-2025-01-03T12-00-01-{}.jsonl",
+            Uuid::from_u128(306)
+        ));
+        std::fs::write(unreadable_path, "{not json}\n").expect("unreadable rollout metadata");
+
+        store
+            .delete_thread(DeleteThreadParams {
+                thread_id: source_thread_id,
+            })
+            .await
+            .expect("unreadable metadata should not block delete");
+
+        assert!(!source_path.exists());
+    }
+
+    #[tokio::test]
+    async fn delete_threads_allows_internal_history_references() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let source_uuid = Uuid::from_u128(307);
+        let source_thread_id =
+            ThreadId::from_string(&source_uuid.to_string()).expect("valid source thread id");
+        let source_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            source_uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("source session file");
+        let child_uuid = Uuid::from_u128(308);
+        let child_thread_id =
+            ThreadId::from_string(&child_uuid.to_string()).expect("valid child thread id");
+        let child_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-01",
+            child_uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("child session file");
+        set_history_base(
+            child_path.as_path(),
+            HistoryPosition {
+                thread_id: source_thread_id,
+                end_ordinal_exclusive: 1,
+                end_byte_offset: std::fs::metadata(source_path.as_path())
+                    .expect("source rollout metadata")
+                    .len(),
+            },
+        );
+
+        store
+            .delete_threads(DeleteThreadsParams {
+                thread_ids: vec![child_thread_id, source_thread_id],
+            })
+            .await
+            .expect("internal references should not block batch delete");
+
+        assert!(!source_path.exists());
+        assert!(!child_path.exists());
+    }
+
+    #[tokio::test]
+    async fn delete_threads_rejects_owned_descendants_before_deleting_anything() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let owner = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        for (parent_uuid, child_uuid, history_mode) in [
+            (
+                Uuid::from_u128(309),
+                Uuid::from_u128(310),
+                ThreadHistoryMode::Legacy,
+            ),
+            (
+                Uuid::from_u128(312),
+                Uuid::from_u128(313),
+                ThreadHistoryMode::Paginated,
+            ),
+        ] {
+            let parent_thread_id =
+                ThreadId::from_string(&parent_uuid.to_string()).expect("valid parent thread id");
+            let parent_path = write_session_file_with_history_mode(
+                home.path(),
+                "2025-01-03T12-00-00",
+                parent_uuid,
+                history_mode,
+            )
+            .expect("parent session file");
+            let child_thread_id =
+                ThreadId::from_string(&child_uuid.to_string()).expect("valid child thread id");
+            let child_path = write_session_file_with_history_mode(
+                home.path(),
+                "2025-01-03T12-00-01",
+                child_uuid,
+                history_mode,
+            )
+            .expect("child session file");
+            let _owner_guard = owner
+                .acquire_writer_lock(child_thread_id)
+                .expect("acquire child writer lock");
+
+            let error = store
+                .delete_threads(DeleteThreadsParams {
+                    thread_ids: vec![parent_thread_id, child_thread_id],
+                })
+                .await
+                .expect_err("owned descendant should block deletion");
+
+            assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+            assert!(parent_path.exists());
+            assert!(child_path.exists());
+        }
+    }
+
+    #[tokio::test]
+    async fn delete_threads_rejects_owned_thread_before_rollout_materializes() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let owner = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id = ThreadId::default();
+        let _owner_guard = owner
+            .acquire_writer_lock(thread_id)
+            .expect("acquire writer lock before rollout exists");
+
+        let error = store
+            .delete_threads(DeleteThreadsParams {
+                thread_ids: vec![thread_id],
+            })
+            .await
+            .expect_err("owned thread should block deletion before rollout exists");
+
+        assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+    }
+
+    #[tokio::test]
+    async fn delete_threads_removes_rollout_with_unreadable_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(311);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        std::fs::write(&rollout_path, "{not json}\n").expect("damage rollout metadata");
+
+        store
+            .delete_threads(DeleteThreadsParams {
+                thread_ids: vec![thread_id],
+            })
+            .await
+            .expect("delete rollout with unreadable metadata");
+
+        assert!(!rollout_path.exists());
+    }
+
+    #[tokio::test]
+    async fn delete_rollout_file_treats_vanished_path_as_already_deleted() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(305);
+        let path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        std::fs::remove_file(&path).expect("remove session file");
+
+        assert!(!delete_rollout_file(&store, path.as_path()).expect("delete rollout"));
+    }
+
+    #[tokio::test]
+    async fn delete_thread_without_state_db_preserves_materialized_thread_history() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let store = LocalThreadStore::new(config.clone(), /*state_db*/ None);
+        let uuid = Uuid::from_u128(312);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let pool = codex_state::open_thread_history_db(&config.sqlite)
+            .await
+            .expect("open existing thread history database");
+        let thread_id_string = thread_id.to_string();
+        sqlx::query(
+            "INSERT INTO thread_turns (thread_id, turn_id, rollout_ordinal, status) VALUES (?, 'turn-1', 1, 'completed')",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert turn");
+        sqlx::query(
+            "INSERT INTO thread_items (thread_id, turn_id, item_id, rollout_ordinal, created_at_ms, item_json) VALUES (?, 'turn-1', 'item-1', 2, 1, '{}')",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert item");
+        sqlx::query(
+            "INSERT INTO thread_realtime_items (thread_id, item_id, rollout_ordinal, created_at_ms, item_type, item_json) VALUES (?, 'realtime-1', 3, 1, 'realtime_session_started', '{}')",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert realtime item");
+        sqlx::query(
+            "INSERT INTO thread_history_projection_state (thread_id, next_rollout_byte_offset, next_rollout_ordinal) VALUES (?, 3, 3)",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert projection state");
+
+        let error = store
+            .delete_thread(DeleteThreadParams { thread_id })
+            .await
+            .expect_err("projected history without a state database should prevent deletion");
+
+        assert!(matches!(
+            error,
+            ThreadStoreError::Unsupported {
+                operation: "paginated_history"
+            }
+        ));
+        assert!(rollout_path.exists());
+        let counts = sqlx::query_as::<_, (i64, i64, i64, i64)>(
+            r#"
+SELECT
+    (SELECT COUNT(*) FROM thread_turns WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_items WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_realtime_items WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_history_projection_state WHERE thread_id = ?)
+            "#,
+        )
+        .bind(thread_id_string.as_str())
+        .bind(thread_id_string.as_str())
+        .bind(thread_id_string.as_str())
+        .bind(thread_id_string.as_str())
+        .fetch_one(&pool)
+        .await
+        .expect("read preserved history rows");
+        assert_eq!(counts, (1, 1, 1, 1));
+    }
+
+    #[tokio::test]
+    async fn delete_thread_removes_materialized_thread_history() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let state_db = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("initialize state database for materialized history");
+        let store = LocalThreadStore::new(config, Some(state_db));
+        let uuid = Uuid::from_u128(306);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let pool = codex_state::open_thread_history_db(
+            &codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+        )
+        .await
+        .expect("open thread history db");
+        let thread_id_string = thread_id.to_string();
+        sqlx::query(
+            "INSERT INTO thread_turns (thread_id, turn_id, rollout_ordinal, status) VALUES (?, 'turn-1', 1, 'completed')",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert turn");
+        sqlx::query(
+            "INSERT INTO thread_items (thread_id, turn_id, item_id, rollout_ordinal, created_at_ms, item_json) VALUES (?, 'turn-1', 'item-1', 2, 1, '{}')",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert item");
+        sqlx::query(
+            "INSERT INTO thread_realtime_items (thread_id, item_id, rollout_ordinal, created_at_ms, item_type, item_json) VALUES (?, 'realtime-1', 3, 1, 'realtime_session_started', '{}')",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert realtime item");
+        sqlx::query(
+            "INSERT INTO thread_history_projection_state (thread_id, next_rollout_byte_offset, next_rollout_ordinal) VALUES (?, 3, 3)",
+        )
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("insert projection state");
+
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: false,
+                metadata: ThreadPersistenceMetadata {
+                    cwd: Some(home.path().to_path_buf()),
+                    model_provider: "test-provider".to_string(),
+                    memory_mode: ThreadMemoryMode::Enabled,
+                },
+            })
+            .await
+            .expect("resume paginated writer before deletion");
+        let lock_path = home
+            .path()
+            .join("thread-writer-locks")
+            .join(format!("{thread_id}.lock"));
+        assert!(lock_path.exists());
+
+        store
+            .delete_thread(DeleteThreadParams { thread_id })
+            .await
+            .expect("delete thread");
+        assert!(!lock_path.exists());
+
+        let counts = sqlx::query_as::<_, (i64, i64, i64, i64)>(
+            r#"
+SELECT
+    (SELECT COUNT(*) FROM thread_turns WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_items WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_realtime_items WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_history_projection_state WHERE thread_id = ?)
+            "#,
+        )
+        .bind(thread_id_string.as_str())
+        .bind(thread_id_string.as_str())
+        .bind(thread_id_string.as_str())
+        .bind(thread_id_string.as_str())
+        .fetch_one(&pool)
+        .await
+        .expect("read remaining history rows");
+        assert_eq!(counts, (0, 0, 0, 0));
+    }
+
+    #[tokio::test]
+    async fn delete_thread_reports_missing_thread() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id =
+            ThreadId::from_string("00000000-0000-0000-0000-000000000304").expect("valid thread id");
+
+        let err = store
+            .delete_thread(DeleteThreadParams { thread_id })
+            .await
+            .expect_err("missing thread should fail");
+        assert_eq!(
+            err.to_string(),
+            "thread 00000000-0000-0000-0000-000000000304 not found"
+        );
+    }
+
+    fn set_history_base(path: &Path, history_base: HistoryPosition) {
+        let mut session_meta: serde_json::Value = serde_json::from_str(
+            std::fs::read_to_string(path)
+                .expect("read session file")
+                .lines()
+                .next()
+                .expect("session metadata"),
+        )
+        .expect("parse session metadata");
+        session_meta["payload"]["history_base"] =
+            serde_json::to_value(history_base).expect("serialize history base");
+        std::fs::write(path, format!("{session_meta}\n")).expect("write session file");
+    }
+
+    fn set_thread_id(path: &Path, thread_id: ThreadId) {
+        let mut session_meta: serde_json::Value = serde_json::from_str(
+            std::fs::read_to_string(path)
+                .expect("read session file")
+                .lines()
+                .next()
+                .expect("session metadata"),
+        )
+        .expect("parse session metadata");
+        session_meta["payload"]["id"] = serde_json::to_value(thread_id).expect("thread id");
+        std::fs::write(path, format!("{session_meta}\n")).expect("write session file");
+    }
+}
diff --git a/codex-rs/thread-store/src/local/helpers.rs b/codex-rs/thread-store/src/local/helpers.rs
new file mode 100644
index 0000000000000000000000000000000000000000..86fc9b9fd46940843f596af8ba710d98e1b61005
--- /dev/null
+++ b/codex-rs/thread-store/src/local/helpers.rs
@@ -0,0 +1,372 @@
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::ffi::OsStr;
+use std::fs::FileTimes;
+use std::fs::OpenOptions;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::SystemTime;
+
+use chrono::DateTime;
+use chrono::Utc;
+use codex_git_utils::GitSha;
+use codex_protocol::SanitizedGitUrl;
+use codex_protocol::ThreadId;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::GitInfo;
+use codex_protocol::protocol::NetworkAccess;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::ARCHIVED_SESSIONS_SUBDIR;
+use codex_rollout::RolloutReferenceIndex;
+use codex_rollout::ThreadItem;
+use codex_rollout::find_thread_names_by_ids;
+use codex_state::ThreadMetadata;
+
+use super::LocalThreadStore;
+use crate::StoredThread;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+pub(super) fn scoped_rollout_path(
+    root: PathBuf,
+    rollout_path: &Path,
+    root_name: &str,
+) -> ThreadStoreResult<PathBuf> {
+    let canonical_root =
+        std::fs::canonicalize(&root).map_err(|err| ThreadStoreError::Internal {
+            message: format!(
+                "failed to resolve {root_name} directory `{}`: {err}",
+                root.display()
+            ),
+        })?;
+    let canonical_rollout_path =
+        std::fs::canonicalize(rollout_path).map_err(|_| ThreadStoreError::InvalidRequest {
+            message: format!(
+                "rollout path `{}` must be in {root_name} directory",
+                rollout_path.display()
+            ),
+        })?;
+    if canonical_rollout_path.starts_with(&canonical_root) {
+        Ok(canonical_rollout_path)
+    } else {
+        Err(ThreadStoreError::InvalidRequest {
+            message: format!(
+                "rollout path `{}` must be in {root_name} directory",
+                rollout_path.display()
+            ),
+        })
+    }
+}
+
+pub(super) fn rollout_path_is_archived(codex_home: &Path, path: &Path) -> bool {
+    path.starts_with(codex_home.join(ARCHIVED_SESSIONS_SUBDIR))
+        || path
+            .components()
+            .any(|component| component.as_os_str() == OsStr::new(ARCHIVED_SESSIONS_SUBDIR))
+}
+
+/// Returns rollout files whose session metadata belongs to `thread_id`.
+pub(super) async fn owned_rollout_paths(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<Vec<PathBuf>> {
+    RolloutReferenceIndex::scan(store.config.codex_home.as_path())
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to scan thread rollout files: {err}"),
+        })
+        .map(|index| owned_rollout_paths_from_index(&index, thread_id))
+}
+
+pub(super) fn owned_rollout_paths_from_index(
+    index: &RolloutReferenceIndex,
+    thread_id: ThreadId,
+) -> Vec<PathBuf> {
+    index
+        .rollouts_for_thread(thread_id)
+        .map(|(_, path)| path.to_path_buf())
+        .collect()
+}
+
+pub(super) fn validated_rollout_file_name(
+    rollout_path: &Path,
+    display_path: &Path,
+) -> ThreadStoreResult<std::ffi::OsString> {
+    let Some(file_name) = rollout_path.file_name().map(OsStr::to_owned) else {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!(
+                "rollout path `{}` missing file name",
+                display_path.display()
+            ),
+        });
+    };
+    if codex_rollout::rollout_id_from_path(rollout_path).is_some() {
+        Ok(file_name)
+    } else {
+        Err(ThreadStoreError::InvalidRequest {
+            message: format!(
+                "rollout path `{}` has an invalid filename",
+                display_path.display()
+            ),
+        })
+    }
+}
+
+pub(super) fn touch_modified_time(path: &Path) -> std::io::Result<()> {
+    let times = FileTimes::new().set_modified(SystemTime::now());
+    OpenOptions::new().append(true).open(path)?.set_times(times)
+}
+
+pub(super) fn restore_rollout_moves(moves: &[(PathBuf, PathBuf)]) -> std::io::Result<()> {
+    for (source, destination) in moves.iter().rev() {
+        std::fs::rename(destination, source)?;
+    }
+    Ok(())
+}
+
+pub(super) fn stored_thread_from_rollout_item(
+    item: ThreadItem,
+    archived: bool,
+    default_provider: &str,
+) -> Option<StoredThread> {
+    let thread_id = item
+        .thread_id
+        .or_else(|| thread_id_from_rollout_path(item.path.as_path()))?;
+    let created_at = parse_rfc3339(item.created_at.as_deref()).unwrap_or_else(Utc::now);
+    let updated_at = parse_rfc3339(item.updated_at.as_deref()).unwrap_or(created_at);
+    let recency_at = parse_rfc3339(item.recency_at.as_deref()).unwrap_or(updated_at);
+    let archived_at = archived.then_some(updated_at);
+    let git_info = git_info_from_parts(
+        item.git_sha.clone(),
+        item.git_branch.clone(),
+        item.git_origin_url.clone(),
+    );
+    let source = item.source.unwrap_or(SessionSource::Unknown);
+    let preview = item
+        .preview
+        .clone()
+        .or_else(|| item.first_user_message.clone())
+        .unwrap_or_default();
+    let rollout_path = codex_rollout::plain_rollout_path(item.path.as_path());
+
+    Some(StoredThread {
+        thread_id,
+        extra_config: None,
+        rollout_path: Some(rollout_path),
+        forked_from_id: None,
+        parent_thread_id: item.parent_thread_id,
+        preview,
+        name: None,
+        model_provider: item
+            .model_provider
+            .filter(|provider| !provider.is_empty())
+            .unwrap_or_else(|| default_provider.to_string()),
+        model: item.model,
+        reasoning_effort: item.reasoning_effort,
+        created_at,
+        updated_at,
+        recency_at,
+        archived_at,
+        section: item.section,
+        section_position: None,
+        section_entered_at: None,
+        project_id: item.project_id,
+        daybreak_enabled: item.daybreak_enabled,
+        cwd: item.cwd.unwrap_or_default(),
+        cli_version: item.cli_version.unwrap_or_default(),
+        originator: item.originator,
+        source,
+        history_mode: item.history_mode,
+        thread_source: None,
+        agent_nickname: item.agent_nickname,
+        agent_role: item.agent_role,
+        agent_path: None,
+        git_info,
+        approval_mode: AskForApproval::OnRequest,
+        permission_profile: PermissionProfile::read_only(),
+        token_usage: None,
+        first_user_message: item.first_user_message,
+        history: None,
+    })
+}
+
+pub(super) fn permission_profile_from_metadata_value(value: &str, cwd: &Path) -> PermissionProfile {
+    serde_json::from_str::<PermissionProfile>(value)
+        .or_else(|_| {
+            parse_legacy_sandbox_policy(value)
+                .map(|policy| PermissionProfile::from_legacy_sandbox_policy_for_cwd(&policy, cwd))
+        })
+        .unwrap_or_else(|_| PermissionProfile::read_only())
+}
+
+pub(super) fn permission_profile_to_metadata_value(
+    permission_profile: &PermissionProfile,
+) -> String {
+    match serde_json::to_string(permission_profile) {
+        Ok(value) => value,
+        Err(err) => {
+            tracing::warn!("failed to serialize permission profile metadata: {err}");
+            String::new()
+        }
+    }
+}
+
+pub(super) fn sqlite_thread_name(metadata: &ThreadMetadata) -> Option<String> {
+    metadata
+        .name
+        .as_deref()
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(str::to_string)
+}
+
+pub(super) async fn resolve_thread_section_metadata(
+    state_db: &codex_state::StateRuntime,
+    thread_ids: &[ThreadId],
+) -> HashMap<ThreadId, (Option<i64>, Option<DateTime<Utc>>)> {
+    if thread_ids.is_empty() {
+        return HashMap::new();
+    }
+
+    state_db
+        .get_thread_section_ordering(thread_ids)
+        .await
+        .unwrap_or_default()
+}
+
+pub(super) async fn resolve_thread_names(
+    store: &LocalThreadStore,
+    thread_history_modes: &HashMap<ThreadId, ThreadHistoryMode>,
+) -> HashMap<ThreadId, String> {
+    let mut names = HashMap::<ThreadId, String>::with_capacity(thread_history_modes.len());
+    let legacy_thread_ids = thread_history_modes
+        .iter()
+        .filter_map(|(&thread_id, &history_mode)| {
+            (history_mode == ThreadHistoryMode::Legacy).then_some(thread_id)
+        })
+        .collect::<HashSet<_>>();
+    if let Some(state_db_ctx) = store.state_db().await {
+        for (&thread_id, &history_mode) in thread_history_modes {
+            let Ok(Some(metadata)) = state_db_ctx.get_thread(thread_id).await else {
+                continue;
+            };
+            let name = match history_mode {
+                ThreadHistoryMode::Legacy => distinct_thread_metadata_title(&metadata),
+                ThreadHistoryMode::Paginated => sqlite_thread_name(&metadata),
+            };
+            if let Some(name) = name {
+                names.insert(thread_id, name);
+            }
+        }
+    }
+    if let Ok(legacy_names) =
+        find_thread_names_by_ids(store.config.codex_home.as_path(), &legacy_thread_ids).await
+    {
+        // Legacy titles remain authoritative when present; the index only fills
+        // names for threads whose SQLite title is still derived from the preview.
+        for (thread_id, name) in legacy_names {
+            names.entry(thread_id).or_insert(name);
+        }
+    }
+    names
+}
+
+pub(super) fn distinct_thread_metadata_title(metadata: &ThreadMetadata) -> Option<String> {
+    let title = metadata.title.trim();
+    if title.is_empty() || metadata.first_user_message.as_deref().map(str::trim) == Some(title) {
+        None
+    } else {
+        Some(title.to_string())
+    }
+}
+
+pub(super) fn set_thread_name(thread: &mut StoredThread, name: String) {
+    if thread.history_mode == ThreadHistoryMode::Paginated || thread.preview.trim() != name.trim() {
+        thread.name = Some(name);
+    }
+}
+
+fn parse_rfc3339(value: Option<&str>) -> Option<DateTime<Utc>> {
+    DateTime::parse_from_rfc3339(value?)
+        .ok()
+        .map(|dt| dt.with_timezone(&Utc))
+}
+
+fn parse_legacy_sandbox_policy(value: &str) -> serde_json::Result<SandboxPolicy> {
+    serde_json::from_str(value)
+        .or_else(|_| serde_json::from_value(serde_json::Value::String(value.to_string())))
+        .or_else(|_| match value {
+            "danger-full-access" => Ok(SandboxPolicy::DangerFullAccess),
+            "read-only" => Ok(SandboxPolicy::new_read_only_policy()),
+            "workspace-write" => Ok(SandboxPolicy::new_workspace_write_policy()),
+            "external-sandbox" => Ok(SandboxPolicy::ExternalSandbox {
+                network_access: NetworkAccess::Restricted,
+            }),
+            _ => serde_json::from_value(serde_json::Value::String(value.to_string())),
+        })
+}
+
+pub(super) fn git_info_from_parts(
+    sha: Option<String>,
+    branch: Option<String>,
+    origin_url: Option<SanitizedGitUrl>,
+) -> Option<GitInfo> {
+    if sha.is_none() && branch.is_none() && origin_url.is_none() {
+        return None;
+    }
+    Some(GitInfo {
+        commit_hash: sha.as_deref().map(GitSha::new),
+        branch,
+        repository_url: origin_url,
+    })
+}
+
+fn thread_id_from_rollout_path(path: &Path) -> Option<ThreadId> {
+    let file_name = path.file_name()?.to_str()?;
+    let file_name = file_name.strip_suffix(".zst").unwrap_or(file_name);
+    let stem = file_name.strip_suffix(".jsonl")?;
+    if stem.len() < 37 {
+        return None;
+    }
+    let uuid_start = stem.len().saturating_sub(36);
+    if !stem[..uuid_start].ends_with('-') {
+        return None;
+    }
+    ThreadId::from_string(&stem[uuid_start..]).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_rollout::ThreadItem;
+    use pretty_assertions::assert_eq;
+    use uuid::Uuid;
+
+    use super::*;
+
+    #[test]
+    fn stored_thread_from_rollout_item_returns_logical_rollout_path() {
+        let uuid = Uuid::from_u128(1);
+        let compressed_path = PathBuf::from(format!(
+            "/tmp/sessions/2025/01/03/rollout-2025-01-03T12-00-00-{uuid}.jsonl.zst"
+        ));
+        let thread = stored_thread_from_rollout_item(
+            ThreadItem {
+                path: compressed_path.clone(),
+                ..Default::default()
+            },
+            /*archived*/ false,
+            "test-provider",
+        )
+        .expect("stored thread");
+
+        assert_eq!(
+            thread.rollout_path,
+            Some(
+                compressed_path.with_file_name(format!("rollout-2025-01-03T12-00-00-{uuid}.jsonl"))
+            )
+        );
+    }
+}
diff --git a/codex-rs/thread-store/src/local/list_threads.rs b/codex-rs/thread-store/src/local/list_threads.rs
new file mode 100644
index 0000000000000000000000000000000000000000..015d35f4dff5fcb583ae813e111d1c1a7120f654
--- /dev/null
+++ b/codex-rs/thread-store/src/local/list_threads.rs
@@ -0,0 +1,793 @@
+use std::collections::HashMap;
+
+use chrono::DateTime;
+use chrono::Utc;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::parse_cursor;
+use codex_state::ThreadFilterOptions;
+
+use super::LocalThreadStore;
+use super::helpers::resolve_thread_names;
+use super::helpers::resolve_thread_section_metadata;
+use super::helpers::set_thread_name;
+use super::helpers::stored_thread_from_rollout_item;
+use super::read_thread::stored_thread_from_state_metadata;
+use crate::ListThreadsParams;
+use crate::SortDirection;
+use crate::ThreadPage;
+use crate::ThreadRelationFilter;
+use crate::ThreadSortKey;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+pub(super) async fn list_threads(
+    store: &LocalThreadStore,
+    params: ListThreadsParams,
+) -> ThreadStoreResult<ThreadPage> {
+    if params.sort_key == ThreadSortKey::SectionPosition {
+        return list_section_threads(store, params).await;
+    }
+    let cursor = params
+        .cursor
+        .as_deref()
+        .map(|cursor| {
+            parse_cursor(cursor).ok_or_else(|| ThreadStoreError::InvalidRequest {
+                message: format!("invalid cursor: {cursor}"),
+            })
+        })
+        .transpose()?;
+    let sort_key = match params.sort_key {
+        ThreadSortKey::CreatedAt => codex_rollout::ThreadSortKey::CreatedAt,
+        ThreadSortKey::UpdatedAt => codex_rollout::ThreadSortKey::UpdatedAt,
+        ThreadSortKey::RecencyAt => codex_rollout::ThreadSortKey::RecencyAt,
+        ThreadSortKey::SectionPosition => unreachable!("section order uses the state database"),
+    };
+    let sort_direction = match params.sort_direction {
+        SortDirection::Asc => codex_rollout::SortDirection::Asc,
+        SortDirection::Desc => codex_rollout::SortDirection::Desc,
+    };
+    let state_db = store.state_db().await;
+    let rollout_config = RolloutConfig {
+        codex_home: store.config.codex_home.clone(),
+        sqlite: store.config.sqlite.clone(),
+        cwd: store.config.codex_home.clone(),
+        model_provider_id: store.config.default_model_provider_id.clone(),
+        generate_memories: false,
+    };
+    let page = list_rollout_threads(
+        state_db.clone(),
+        &rollout_config,
+        store.config.default_model_provider_id.as_str(),
+        &params,
+        cursor.as_ref(),
+        sort_key,
+        sort_direction,
+    )
+    .await?;
+
+    let next_cursor = page
+        .next_cursor
+        .as_ref()
+        .and_then(|cursor| serde_json::to_value(cursor).ok())
+        .and_then(|value| value.as_str().map(str::to_owned));
+    let mut items = page
+        .items
+        .into_iter()
+        .filter_map(|item| {
+            stored_thread_from_rollout_item(
+                item,
+                params.archived,
+                store.config.default_model_provider_id.as_str(),
+            )
+        })
+        .collect::<Vec<_>>();
+
+    let thread_history_modes = items
+        .iter()
+        .map(|thread| (thread.thread_id, thread.history_mode))
+        .collect::<HashMap<_, _>>();
+    let names = resolve_thread_names(store, &thread_history_modes).await;
+    for thread in &mut items {
+        if let Some(name) = names.get(&thread.thread_id).cloned() {
+            set_thread_name(thread, name);
+        }
+    }
+    if let Some(state_db) = state_db {
+        let sectioned_thread_ids = items
+            .iter()
+            .filter(|thread| thread.section.is_some())
+            .map(|thread| thread.thread_id)
+            .collect::<Vec<_>>();
+        let section_metadata =
+            resolve_thread_section_metadata(state_db.as_ref(), &sectioned_thread_ids).await;
+        for thread in items.iter_mut().filter(|thread| thread.section.is_some()) {
+            if let Some((section_position, section_entered_at)) =
+                section_metadata.get(&thread.thread_id)
+            {
+                thread.section_position = *section_position;
+                thread.section_entered_at = *section_entered_at;
+            }
+        }
+    }
+
+    if let Some(project_id) = params.project_id.as_ref() {
+        items.retain(|thread| &thread.project_id == project_id);
+    }
+
+    Ok(ThreadPage { items, next_cursor })
+}
+
+async fn list_section_threads(
+    store: &LocalThreadStore,
+    params: ListThreadsParams,
+) -> ThreadStoreResult<ThreadPage> {
+    let section = params
+        .section
+        .as_ref()
+        .and_then(Option::as_deref)
+        .ok_or_else(|| ThreadStoreError::InvalidRequest {
+            message: "section-position sorting requires a section filter".to_owned(),
+        })?;
+    let state_db = store
+        .state_db()
+        .await
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: "state DB unavailable for section-ordered thread listing".to_owned(),
+        })?;
+
+    let anchor = params
+        .cursor
+        .as_deref()
+        .map(|cursor| -> ThreadStoreResult<codex_state::Anchor> {
+            let (position, thread_id) =
+                cursor
+                    .split_once('|')
+                    .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                        message: format!("invalid cursor: {cursor}"),
+                    })?;
+            let timestamp = position
+                .parse::<i64>()
+                .ok()
+                .and_then(DateTime::<Utc>::from_timestamp_millis)
+                .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                    message: format!("invalid cursor: {cursor}"),
+                })?;
+            let thread_id = codex_protocol::ThreadId::from_string(thread_id).map_err(|_| {
+                ThreadStoreError::InvalidRequest {
+                    message: format!("invalid cursor: {cursor}"),
+                }
+            })?;
+            Ok(codex_state::Anchor {
+                ts: timestamp,
+                id: Some(thread_id),
+            })
+        })
+        .transpose()?;
+    let allowed_sources = params
+        .allowed_sources
+        .iter()
+        .map(|source| match serde_json::to_value(source) {
+            Ok(serde_json::Value::String(source)) => source,
+            Ok(source) => source.to_string(),
+            Err(_) => String::new(),
+        })
+        .collect::<Vec<_>>();
+    let normalized_cwd_filters = params.cwd_filters.as_ref().map(|filters| {
+        filters
+            .iter()
+            .map(|cwd| codex_rollout::state_db::normalize_cwd_for_state_db(cwd))
+            .collect::<Vec<_>>()
+    });
+    let filters = ThreadFilterOptions {
+        archived_only: params.archived,
+        allowed_sources: allowed_sources.as_slice(),
+        model_providers: params.model_providers.as_deref(),
+        cwd_filters: normalized_cwd_filters.as_deref(),
+        section: Some(Some(section)),
+        project_id: params
+            .project_id
+            .as_ref()
+            .map(|project_id| project_id.as_deref()),
+        anchor: anchor.as_ref(),
+        sort_key: codex_state::SortKey::SectionPosition,
+        sort_direction: match params.sort_direction {
+            SortDirection::Asc => codex_state::SortDirection::Asc,
+            SortDirection::Desc => codex_state::SortDirection::Desc,
+        },
+        search_term: params.search_term.as_deref(),
+    };
+    let page = match params.relation_filter {
+        Some(ThreadRelationFilter::DirectChildrenOf(thread_id)) => {
+            state_db
+                .list_threads_by_relation(
+                    params.page_size,
+                    codex_state::ThreadRelationFilter::DirectChildrenOf(thread_id),
+                    filters,
+                )
+                .await
+        }
+        Some(ThreadRelationFilter::DescendantsOf(thread_id)) => {
+            state_db
+                .list_threads_by_relation(
+                    params.page_size,
+                    codex_state::ThreadRelationFilter::DescendantsOf(thread_id),
+                    filters,
+                )
+                .await
+        }
+        None => state_db.list_threads(params.page_size, filters).await,
+    }
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to list section-ordered threads: {err}"),
+    })?;
+
+    let codex_state::ThreadsPage {
+        items: metadata_items,
+        parent_thread_ids,
+        next_anchor,
+        ..
+    } = page;
+    let items = metadata_items
+        .into_iter()
+        .map(|metadata| {
+            let parent_thread_id = parent_thread_ids.get(&metadata.id).copied();
+            stored_thread_from_state_metadata(store, metadata, parent_thread_id)
+        })
+        .collect();
+    let next_cursor = next_anchor.and_then(|anchor| {
+        anchor.id.map(|thread_id| {
+            let position = anchor.ts.timestamp_millis();
+            format!("{position}|{thread_id}")
+        })
+    });
+    Ok(ThreadPage { items, next_cursor })
+}
+
+pub(super) async fn list_rollout_threads(
+    state_db: Option<codex_rollout::StateDbHandle>,
+    config: &RolloutConfig,
+    default_model_provider_id: &str,
+    params: &ListThreadsParams,
+    cursor: Option<&codex_rollout::Cursor>,
+    sort_key: codex_rollout::ThreadSortKey,
+    sort_direction: codex_rollout::SortDirection,
+) -> ThreadStoreResult<codex_rollout::ThreadsPage> {
+    if params.relation_filter.is_some() || params.section.is_some() || params.project_id.is_some() {
+        let relation_filter = params
+            .relation_filter
+            .map(|relation_filter| match relation_filter {
+                ThreadRelationFilter::DirectChildrenOf(parent_thread_id) => {
+                    codex_state::ThreadRelationFilter::DirectChildrenOf(parent_thread_id)
+                }
+                ThreadRelationFilter::DescendantsOf(ancestor_thread_id) => {
+                    codex_state::ThreadRelationFilter::DescendantsOf(ancestor_thread_id)
+                }
+            });
+        let page = codex_rollout::state_db::list_threads_db(
+            state_db.as_deref(),
+            &config.sqlite,
+            params.page_size,
+            cursor,
+            sort_key,
+            sort_direction,
+            params.allowed_sources.as_slice(),
+            params.model_providers.as_deref(),
+            params.cwd_filters.as_deref(),
+            relation_filter,
+            params.archived,
+            params.section.as_ref().map(Option::as_deref),
+            params.project_id.as_ref().map(Option::as_deref),
+            params.search_term.as_deref(),
+        )
+        .await
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: "state DB unavailable for filtered thread listing".to_string(),
+        })?;
+        return Ok(page.into());
+    }
+
+    let page = if params.use_state_db_only && params.archived {
+        RolloutRecorder::list_archived_threads_from_state_db(
+            state_db,
+            config,
+            params.page_size,
+            cursor,
+            sort_key,
+            sort_direction,
+            params.allowed_sources.as_slice(),
+            params.model_providers.as_deref(),
+            params.cwd_filters.as_deref(),
+            default_model_provider_id,
+            params.search_term.as_deref(),
+        )
+        .await
+    } else if params.use_state_db_only {
+        RolloutRecorder::list_threads_from_state_db(
+            state_db,
+            config,
+            params.page_size,
+            cursor,
+            sort_key,
+            sort_direction,
+            params.allowed_sources.as_slice(),
+            params.model_providers.as_deref(),
+            params.cwd_filters.as_deref(),
+            default_model_provider_id,
+            params.search_term.as_deref(),
+        )
+        .await
+    } else if params.archived {
+        RolloutRecorder::list_archived_threads(
+            state_db,
+            config,
+            params.page_size,
+            cursor,
+            sort_key,
+            sort_direction,
+            params.allowed_sources.as_slice(),
+            params.model_providers.as_deref(),
+            params.cwd_filters.as_deref(),
+            default_model_provider_id,
+            params.search_term.as_deref(),
+        )
+        .await
+    } else {
+        RolloutRecorder::list_threads(
+            state_db,
+            config,
+            params.page_size,
+            cursor,
+            sort_key,
+            sort_direction,
+            params.allowed_sources.as_slice(),
+            params.model_providers.as_deref(),
+            params.cwd_filters.as_deref(),
+            default_model_provider_id,
+            params.search_term.as_deref(),
+        )
+        .await
+    };
+    page.map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to list threads: {err}"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use chrono::Utc;
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::SessionSource;
+    use codex_protocol::protocol::ThreadHistoryMode;
+    use codex_state::PINNED_THREAD_SECTION_ID;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::MoveThreadToSectionParams;
+    use crate::ThreadStore;
+    use crate::local::LocalThreadStore;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_archived_session_file;
+    use crate::local::test_support::write_session_file;
+    use crate::local::test_support::write_session_file_with;
+
+    #[tokio::test]
+    async fn list_threads_uses_default_provider_when_rollout_omits_provider() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        write_session_file_with(
+            home.path(),
+            home.path().join("sessions/2025/01/03"),
+            "2025-01-03T12-00-00",
+            Uuid::from_u128(102),
+            "Hello from user",
+            /*model_provider*/ None,
+            ThreadHistoryMode::Legacy,
+        )
+        .expect("session file");
+
+        let page = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: false,
+            })
+            .await
+            .expect("thread listing");
+
+        assert_eq!(page.items.len(), 1);
+        assert_eq!(page.items[0].model_provider, "test-provider");
+    }
+
+    #[tokio::test]
+    async fn list_threads_preserves_sqlite_title_search_results() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(103);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = home.path().join("rollout-title-search.jsonl");
+        fs::write(&rollout_path, "").expect("placeholder rollout file");
+
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        runtime
+            .mark_backfill_complete(/*last_watermark*/ None)
+            .await
+            .expect("backfill should be complete");
+        let created_at = Utc::now();
+        let mut builder = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path,
+            created_at,
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        builder.cli_version = Some("test_version".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.title = "needle title".to_string();
+        metadata.first_user_message = Some("plain preview".to_string());
+        metadata.preview = metadata.first_user_message.clone();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let page = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: Some("needle".to_string()),
+                relation_filter: None,
+                use_state_db_only: true,
+            })
+            .await
+            .expect("thread listing");
+
+        let ids = page
+            .items
+            .iter()
+            .map(|item| item.thread_id)
+            .collect::<Vec<_>>();
+        assert_eq!(ids, vec![thread_id]);
+        assert_eq!(
+            page.items[0].first_user_message.as_deref(),
+            Some("plain preview")
+        );
+    }
+
+    #[tokio::test]
+    async fn list_paginated_threads_uses_sqlite_name_over_legacy_compatibility() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(104);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = home.path().join("rollout-paginated-name-search.jsonl");
+        fs::write(&rollout_path, "").expect("placeholder rollout file");
+
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        runtime
+            .mark_backfill_complete(/*last_watermark*/ None)
+            .await
+            .expect("backfill should be complete");
+        let mut builder = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path,
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.history_mode = ThreadHistoryMode::Paginated;
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        builder.cli_version = Some("test_version".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.name = Some("canonical paginated name".to_string());
+        metadata.title = "stale title name".to_string();
+        metadata.first_user_message = Some("plain preview".to_string());
+        metadata.preview = metadata.first_user_message.clone();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+        codex_rollout::append_thread_name(home.path(), thread_id, "stale index name")
+            .await
+            .expect("append legacy thread name");
+
+        let page = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: Some("canonical".to_string()),
+                relation_filter: None,
+                use_state_db_only: true,
+            })
+            .await
+            .expect("thread listing");
+
+        assert_eq!(page.items.len(), 1);
+        assert_eq!(page.items[0].thread_id, thread_id);
+        assert_eq!(
+            page.items[0].name.as_deref(),
+            Some("canonical paginated name")
+        );
+    }
+
+    #[tokio::test]
+    async fn list_threads_selects_active_or_archived_collection() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let active_uuid = Uuid::from_u128(105);
+        let archived_uuid = Uuid::from_u128(106);
+        write_session_file(home.path(), "2025-01-03T12-00-00", active_uuid)
+            .expect("active session file");
+        write_archived_session_file(home.path(), "2025-01-03T13-00-00", archived_uuid)
+            .expect("archived session file");
+
+        let active = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: false,
+            })
+            .await
+            .expect("active listing");
+        let archived = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: true,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: false,
+            })
+            .await
+            .expect("archived listing");
+
+        let active_id = ThreadId::from_string(&active_uuid.to_string()).expect("valid thread id");
+        let archived_id =
+            ThreadId::from_string(&archived_uuid.to_string()).expect("valid thread id");
+        assert_eq!(
+            active
+                .items
+                .iter()
+                .map(|item| item.thread_id)
+                .collect::<Vec<_>>(),
+            vec![active_id]
+        );
+        assert_eq!(
+            archived
+                .items
+                .iter()
+                .map(|item| item.thread_id)
+                .collect::<Vec<_>>(),
+            vec![archived_id]
+        );
+        assert_eq!(active.items[0].archived_at, None);
+        assert_eq!(
+            archived.items[0].archived_at,
+            Some(archived.items[0].updated_at)
+        );
+    }
+
+    #[tokio::test]
+    async fn list_threads_returns_local_rollout_summary() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let store = LocalThreadStore::new(config, /*state_db*/ None);
+        let uuid = Uuid::from_u128(101);
+        let path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+
+        let page = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: vec![SessionSource::Cli],
+                model_providers: Some(vec!["test-provider".to_string()]),
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: false,
+            })
+            .await
+            .expect("thread listing");
+
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        assert_eq!(page.next_cursor, None);
+        assert_eq!(page.items.len(), 1);
+        assert_eq!(page.items[0].thread_id, thread_id);
+        assert_eq!(page.items[0].rollout_path, Some(path));
+        assert_eq!(page.items[0].preview, "Hello from user");
+        assert_eq!(
+            page.items[0].first_user_message.as_deref(),
+            Some("Hello from user")
+        );
+        assert_eq!(page.items[0].model_provider, "test-provider");
+        assert_eq!(page.items[0].cli_version, "test_version");
+        assert_eq!(page.items[0].source, SessionSource::Cli);
+    }
+
+    #[tokio::test]
+    async fn section_listing_uses_sqlite_metadata_without_reading_rollouts() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let state = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("initialize state");
+        let store = LocalThreadStore::new(config, Some(state.clone()));
+        let mut thread_ids = Vec::new();
+        let mut first_rollout_path = None;
+
+        for index in 0..3 {
+            let uuid = Uuid::from_u128(975 + index);
+            let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+            let timestamp = format!("2025-01-03T16-{index:02}-00");
+            let rollout_path =
+                write_session_file(home.path(), &timestamp, uuid).expect("write rollout");
+            codex_rollout::state_db::reconcile_rollout(
+                Some(state.as_ref()),
+                rollout_path.as_path(),
+                "test-provider",
+                /*builder*/ None,
+                &[],
+                /*archived_only*/ None,
+                /*new_thread_memory_mode*/ None,
+            )
+            .await;
+            store
+                .move_thread_to_section(MoveThreadToSectionParams {
+                    thread_id,
+                    section: Some(PINNED_THREAD_SECTION_ID.to_owned()),
+                    before_thread_id: None,
+                })
+                .await
+                .expect("append section member");
+            thread_ids.push(thread_id);
+            if index == 0 {
+                first_rollout_path = Some(rollout_path);
+            }
+        }
+        fs::remove_file(first_rollout_path.expect("first rollout path"))
+            .expect("remove rollout without invalidating SQLite metadata");
+
+        let params = ListThreadsParams {
+            page_size: 2,
+            cursor: None,
+            sort_key: ThreadSortKey::SectionPosition,
+            sort_direction: SortDirection::Asc,
+            allowed_sources: Vec::new(),
+            model_providers: None,
+            cwd_filters: None,
+            section: Some(Some(PINNED_THREAD_SECTION_ID.to_owned())),
+            project_id: None,
+            archived: false,
+            search_term: None,
+            relation_filter: None,
+            use_state_db_only: true,
+        };
+        let page = store
+            .list_threads(params.clone())
+            .await
+            .expect("section listing should use SQLite metadata");
+
+        assert_eq!(
+            page.items
+                .iter()
+                .map(|thread| thread.thread_id)
+                .collect::<Vec<_>>(),
+            vec![thread_ids[0], thread_ids[1]]
+        );
+        assert_eq!(page.next_cursor, Some(format!("2000000|{}", thread_ids[1])));
+
+        let next_page = store
+            .list_threads(ListThreadsParams {
+                cursor: page.next_cursor,
+                ..params
+            })
+            .await
+            .expect("section cursor should continue listing from SQLite metadata");
+
+        assert_eq!(
+            next_page
+                .items
+                .iter()
+                .map(|thread| thread.thread_id)
+                .collect::<Vec<_>>(),
+            vec![thread_ids[2]]
+        );
+        assert_eq!(next_page.next_cursor, None);
+    }
+
+    #[tokio::test]
+    async fn list_threads_rejects_invalid_cursor() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+        let err = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: Some("not-a-cursor".to_string()),
+                sort_key: ThreadSortKey::CreatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: false,
+            })
+            .await
+            .expect_err("invalid cursor should fail");
+
+        assert!(matches!(err, ThreadStoreError::InvalidRequest { .. }));
+    }
+}
diff --git a/codex-rs/thread-store/src/local/live_writer.rs b/codex-rs/thread-store/src/local/live_writer.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6a2d95f2b06813fe823b80cc1e22c68c88e2efc1
--- /dev/null
+++ b/codex-rs/thread-store/src/local/live_writer.rs
@@ -0,0 +1,374 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::RolloutRecorderParams;
+use codex_rollout::is_persisted_rollout_item;
+use tracing::warn;
+
+use super::LocalThreadStore;
+use super::create_thread;
+use crate::AppendThreadItemsParams;
+use crate::CreateThreadParams;
+use crate::ReadThreadParams;
+use crate::ResumeThreadParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::types::canonical_history_mode_from_rollout_items;
+
+const ROLLOUT_SIZE_BYTES_METRIC: &str = "codex.rollout.size_bytes";
+
+pub(super) async fn create_thread(
+    store: &LocalThreadStore,
+    params: CreateThreadParams,
+) -> ThreadStoreResult<()> {
+    let thread_id = params.thread_id;
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    let history_mode = params.history_mode;
+    store.ensure_live_recorder_absent(thread_id).await?;
+    let writer_lock = store.acquire_writer_lock(thread_id)?;
+    let recorder = create_thread::create_thread(store, params, writer_lock.clone()).await?;
+    store
+        .insert_live_recorder(thread_id, recorder, thread_id, history_mode, writer_lock)
+        .await
+}
+
+pub(super) async fn resume_thread(
+    store: &LocalThreadStore,
+    params: ResumeThreadParams,
+) -> ThreadStoreResult<()> {
+    let _live_writer_guard = store.live_writer_locks.lock(params.thread_id).await;
+    store.ensure_live_recorder_absent(params.thread_id).await?;
+    let writer_lock = store.acquire_writer_lock(params.thread_id)?;
+    let history_mode = if let Some(history) = params.history.as_deref() {
+        canonical_history_mode_from_rollout_items(history)
+    } else if let Some(rollout_path) = params.rollout_path.as_ref() {
+        super::read_thread::read_thread_by_rollout_path(
+            store,
+            rollout_path.clone(),
+            params.include_archived,
+            /*include_history*/ false,
+        )
+        .await?
+        .history_mode
+    } else {
+        super::read_thread::read_thread(
+            store,
+            ReadThreadParams {
+                thread_id: params.thread_id,
+                include_archived: params.include_archived,
+                include_history: false,
+            },
+        )
+        .await?
+        .history_mode
+    };
+    let rollout_path = match (params.rollout_path, params.history) {
+        (Some(rollout_path), _history) => rollout_path,
+        (None, history) => {
+            let thread = super::read_thread::read_thread(
+                store,
+                ReadThreadParams {
+                    thread_id: params.thread_id,
+                    include_archived: params.include_archived,
+                    include_history: history.is_none(),
+                },
+            )
+            .await?;
+            thread
+                .rollout_path
+                .ok_or_else(|| ThreadStoreError::Internal {
+                    message: format!("thread {} does not have a rollout path", params.thread_id),
+                })?
+        }
+    };
+    let cwd = params
+        .metadata
+        .cwd
+        .clone()
+        .ok_or_else(|| ThreadStoreError::InvalidRequest {
+            message: "local thread store requires a cwd".to_string(),
+        })?;
+    let config = RolloutConfig {
+        codex_home: store.config.codex_home.clone(),
+        sqlite: store.config.sqlite.clone(),
+        cwd,
+        model_provider_id: params.metadata.model_provider.clone(),
+        generate_memories: matches!(params.metadata.memory_mode, ThreadMemoryMode::Enabled),
+    };
+    let rollout_id = super::thread_rollout_resolver::rollout_id_from_path_or_legacy_thread_id(
+        rollout_path.as_path(),
+        params.thread_id,
+        history_mode,
+    )?;
+    let recorder = RolloutRecorder::new_with_writer_lock(
+        &config,
+        RolloutRecorderParams::resume(rollout_path),
+        writer_lock.clone(),
+    )
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to resume local thread recorder: {err}"),
+    })?;
+    store
+        .insert_live_recorder(
+            params.thread_id,
+            recorder,
+            rollout_id,
+            history_mode,
+            writer_lock,
+        )
+        .await
+}
+
+#[tracing::instrument(
+    level = "trace",
+    skip_all,
+    fields(item_count = params.items.len())
+)]
+pub(super) async fn append_items(
+    store: &LocalThreadStore,
+    params: AppendThreadItemsParams,
+) -> ThreadStoreResult<()> {
+    write_and_project(
+        store,
+        params.thread_id,
+        RolloutWriteOp::AppendItems(params.items),
+    )
+    .await
+}
+
+pub(super) async fn persist_thread(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<()> {
+    write_and_project(store, thread_id, RolloutWriteOp::Persist).await
+}
+
+pub(super) async fn flush_thread(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<()> {
+    write_and_project(store, thread_id, RolloutWriteOp::Flush).await
+}
+
+pub(super) async fn shutdown_thread(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<()> {
+    let mut pending_metadata = store.pending_thread_metadata.lock(thread_id).await;
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    let (recorder, rollout_id, history_mode) = live_writer_parts(store, thread_id).await?;
+    let rollout_path = recorder.rollout_path().to_path_buf();
+    if matches!(history_mode, ThreadHistoryMode::Legacy) {
+        recorder.shutdown().await.map_err(thread_store_io_error)?;
+    } else {
+        recorder.shutdown().await.map_err(thread_store_io_error)?;
+        if let Err(err) = super::thread_history_materialization::materialize_to_sqlite(
+            store,
+            rollout_id,
+            rollout_path.as_path(),
+        )
+        .await
+        {
+            warn!("failed to project durable rollout during shutdown for {thread_id}: {err}");
+        }
+    }
+    sync_materialized_rollout_path(store, thread_id, rollout_path.as_path()).await?;
+    if let Some(metrics) = codex_otel::global()
+        && let Ok(metadata) = tokio::fs::metadata(&rollout_path).await
+    {
+        let size_bytes = i64::try_from(metadata.len()).unwrap_or(i64::MAX);
+        let _ = metrics.histogram(ROLLOUT_SIZE_BYTES_METRIC, size_bytes, &[]);
+    }
+    let rollout_exists = match tokio::fs::try_exists(&rollout_path).await {
+        Ok(rollout_exists) => rollout_exists,
+        Err(err) => {
+            warn!(
+                "failed to check rollout path after shutdown for {thread_id}; preserving pending metadata: {err}"
+            );
+            true
+        }
+    };
+    store.live_recorders.lock().await.remove(&thread_id);
+    drop(_live_writer_guard);
+    if !rollout_exists && pending_metadata.take().is_some() {
+        store.pending_thread_metadata.remove(thread_id).await;
+    }
+    Ok(())
+}
+
+pub(super) async fn discard_thread(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<()> {
+    let mut pending_metadata = store.pending_thread_metadata.lock(thread_id).await;
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    if pending_metadata.take().is_some() {
+        store.pending_thread_metadata.remove(thread_id).await;
+    }
+    let entry = store
+        .live_recorders
+        .lock()
+        .await
+        .remove(&thread_id)
+        .ok_or(ThreadStoreError::ThreadNotFound { thread_id })?;
+    entry
+        .recorder
+        .discard()
+        .await
+        .map_err(thread_store_io_error)
+}
+
+pub(super) async fn rollout_path(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<PathBuf> {
+    Ok(store
+        .live_recorders
+        .lock()
+        .await
+        .get(&thread_id)
+        .ok_or(ThreadStoreError::ThreadNotFound { thread_id })?
+        .recorder
+        .rollout_path()
+        .to_path_buf())
+}
+
+async fn sync_materialized_rollout_path(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    rollout_path: &std::path::Path,
+) -> ThreadStoreResult<()> {
+    if codex_rollout::existing_rollout_path(rollout_path)
+        .await
+        .is_none()
+    {
+        return Ok(());
+    }
+    let Some(state_db) = store.state_db().await else {
+        return Ok(());
+    };
+    let result: ThreadStoreResult<()> = async {
+        let Some(mut metadata) =
+            state_db
+                .get_thread(thread_id)
+                .await
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to read thread metadata for {thread_id}: {err}"),
+                })?
+        else {
+            return Ok(());
+        };
+        if metadata.rollout_path != rollout_path {
+            metadata.rollout_path = rollout_path.to_path_buf();
+            state_db
+                .upsert_thread(&metadata)
+                .await
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to update thread metadata for {thread_id}: {err}"),
+                })?;
+        }
+        Ok(())
+    }
+    .await;
+    if let Err(err) = result {
+        warn!("failed to sync materialized rollout path for thread {thread_id}: {err}");
+    }
+    Ok(())
+}
+
+fn thread_store_io_error(err: std::io::Error) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: err.to_string(),
+    }
+}
+
+/// The rollout writer has three distinct lifecycle moments:
+/// - `AppendItems` is normal turn/event persistence and adds new rollout records.
+/// - `Persist` makes the thread durable before any turn items exist; locally this can write the
+///   initial `SessionMeta`.
+/// - `Flush` writes any rollout records already queued in the recorder and ensures they are
+///   durably persisted.
+///
+/// Each can advance the rollout JSONL file on disk, so we need to make sure we materialize the
+/// new data into the SQLite history tables (turns and items) as necessary.
+enum RolloutWriteOp {
+    AppendItems(Vec<RolloutItem>),
+    Persist,
+    Flush,
+}
+
+pub(super) async fn live_writer_parts(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<(RolloutRecorder, ThreadId, ThreadHistoryMode)> {
+    let live_recorders = store.live_recorders.lock().await;
+    let entry = live_recorders
+        .get(&thread_id)
+        .ok_or(ThreadStoreError::ThreadNotFound { thread_id })?;
+    Ok((entry.recorder.clone(), entry.rollout_id, entry.history_mode))
+}
+
+async fn write_and_project(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    write_op: RolloutWriteOp,
+) -> ThreadStoreResult<()> {
+    // Every live write should have a recorder: create/resume installs one, while
+    // shutdown/discard/delete removes it. Keep the lookup defensive so late writes fail after
+    // teardown.
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    let (recorder, rollout_id, history_mode) = live_writer_parts(store, thread_id).await?;
+    let sync_rollout_path = matches!(&write_op, RolloutWriteOp::Persist | RolloutWriteOp::Flush);
+    let write_op = match write_op {
+        RolloutWriteOp::AppendItems(mut items) => {
+            items.retain(|item| is_persisted_rollout_item(item, history_mode));
+            if items.is_empty() {
+                return Ok(());
+            }
+            RolloutWriteOp::AppendItems(items)
+        }
+        RolloutWriteOp::Persist => RolloutWriteOp::Persist,
+        RolloutWriteOp::Flush => RolloutWriteOp::Flush,
+    };
+    if matches!(history_mode, ThreadHistoryMode::Legacy) {
+        durable_write(&recorder, write_op).await?;
+    } else {
+        let rollout_path = recorder.rollout_path();
+        // SQLite is a rebuildable view. The flush barrier must win before projection starts so it
+        // can lag JSONL after failure, but can never get ahead of canonical history.
+        durable_write(&recorder, write_op).await?;
+        if let Err(err) = super::thread_history_materialization::materialize_to_sqlite(
+            store,
+            rollout_id,
+            rollout_path,
+        )
+        .await
+        {
+            warn!("failed to project durable rollout for {thread_id}: {err}");
+        }
+    }
+    if sync_rollout_path {
+        sync_materialized_rollout_path(store, thread_id, recorder.rollout_path()).await?;
+    }
+    Ok(())
+}
+
+async fn durable_write(recorder: &RolloutRecorder, write: RolloutWriteOp) -> ThreadStoreResult<()> {
+    match write {
+        RolloutWriteOp::AppendItems(items) => {
+            recorder
+                .record_canonical_items(items.as_slice())
+                .await
+                .map_err(thread_store_io_error)?;
+            recorder.flush().await.map_err(thread_store_io_error)
+        }
+        RolloutWriteOp::Persist => recorder.persist().await.map_err(thread_store_io_error),
+        RolloutWriteOp::Flush => recorder.flush().await.map_err(thread_store_io_error),
+    }
+}
diff --git a/codex-rs/thread-store/src/local/mod.rs b/codex-rs/thread-store/src/local/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0e170c24399089fe74c1088cf9a744e4d98ccfd3
--- /dev/null
+++ b/codex-rs/thread-store/src/local/mod.rs
@@ -0,0 +1,2111 @@
+mod archive_thread;
+mod create_thread;
+mod delete_thread;
+mod helpers;
+mod list_threads;
+mod live_writer;
+mod model_context;
+mod move_thread_to_section;
+mod paginated_fork;
+mod pending_thread_metadata;
+mod projects;
+mod read_thread;
+mod revert_thread;
+mod rollout_migration;
+// This lands before the reader PRs that consume the shared lineage resolver.
+#[allow(dead_code)]
+mod rollout_lineage;
+mod search_threads;
+mod thread_attachments;
+mod thread_history;
+mod thread_history_materialization;
+mod thread_rollout_resolver;
+mod thread_sections;
+mod unarchive_thread;
+mod update_thread_metadata;
+
+#[cfg(test)]
+#[path = "compression_writer_tests.rs"]
+mod compression_writer_tests;
+#[cfg(test)]
+#[path = "daybreak_metadata_tests.rs"]
+mod daybreak_metadata_tests;
+#[cfg(test)]
+#[path = "pending_thread_metadata_tests.rs"]
+mod pending_thread_metadata_tests;
+#[cfg(test)]
+mod test_support;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::StateDbHandle;
+use codex_rollout::WriterLockCoordinator;
+use codex_state::SqliteConfig;
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::path::PathBuf;
+use std::sync::Arc;
+use tokio::sync::Mutex;
+use tokio::sync::OnceCell;
+use tokio::sync::OwnedMutexGuard;
+use tokio::sync::OwnedRwLockReadGuard;
+use tokio::sync::OwnedRwLockWriteGuard;
+use tokio::sync::RwLock;
+
+use crate::AddThreadAttachmentOutcome;
+use crate::AddThreadAttachmentParams;
+use crate::AppendThreadItemsParams;
+use crate::ArchiveThreadParams;
+use crate::ArchiveThreadsParams;
+use crate::CreateProjectParams;
+use crate::CreateThreadParams;
+use crate::CreateThreadSectionParams;
+use crate::CreatedProject;
+use crate::DeleteThreadParams;
+use crate::DeleteThreadSectionParams;
+use crate::DeleteThreadsParams;
+use crate::DeletedProject;
+use crate::ItemPage;
+use crate::ListItemsParams;
+use crate::ListProjectsParams;
+use crate::ListThreadAttachmentsParams;
+use crate::ListThreadSectionsParams;
+use crate::ListThreadsParams;
+use crate::ListTimelineParams;
+use crate::ListTurnsParams;
+use crate::LoadThreadHistoryParams;
+use crate::MoveProjectParams;
+use crate::MoveThreadToSectionParams;
+use crate::PersistContext;
+use crate::PrepareForkParams;
+use crate::PreparedFork;
+use crate::ProjectMoveOutcome;
+use crate::ReadThreadByRolloutPathParams;
+use crate::ReadThreadParams;
+use crate::RemoveThreadAttachmentOutcome;
+use crate::RemoveThreadAttachmentParams;
+use crate::RenameThreadSectionParams;
+use crate::ResumeThreadParams;
+use crate::RevertThreadParams;
+use crate::SearchThreadOccurrencesParams;
+use crate::SearchThreadsParams;
+use crate::StoredModelContext;
+use crate::StoredProject;
+use crate::StoredProjectsPage;
+use crate::StoredThread;
+use crate::StoredThreadHistory;
+use crate::StoredThreadSection;
+use crate::StoredThreadSectionsPage;
+use crate::ThreadAttachmentPage;
+use crate::ThreadMetadataPatch;
+use crate::ThreadOccurrenceSearchPage;
+use crate::ThreadPage;
+use crate::ThreadSearchPage;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::ThreadStoreFuture;
+use crate::ThreadStoreResult;
+use crate::TimelinePage;
+use crate::TurnPage;
+use crate::UpdateProjectParams;
+use crate::UpdateThreadMetadataParams;
+use crate::UpdatedProject;
+
+pub use rollout_migration::RolloutMigrationFailureReason;
+pub use rollout_migration::RolloutMigrationMode;
+pub use rollout_migration::RolloutMigrationOptions;
+pub use rollout_migration::RolloutMigrationOutcome;
+pub use rollout_migration::RolloutMigrationProgress;
+pub use rollout_migration::RolloutMigrationReport;
+pub use rollout_migration::RolloutMigrationStatus;
+
+/// Local filesystem/SQLite-backed implementation of [`ThreadStore`].
+///
+/// Local storage has two compatibility surfaces. Rollout JSONL files are the
+/// durable replay format and remain readable without SQLite, including older
+/// files that encode metadata in `SessionMeta` items and name-index entries.
+/// The SQLite state DB, when available, is the queryable metadata index used by
+/// list/read paths for fast lookup.
+///
+/// Live appends still write canonical JSONL history, but append-derived
+/// metadata is observed above the store and applied through
+/// [`ThreadStore::update_thread_metadata`]. This implementation applies that
+/// patch literally to SQLite while keeping the JSONL/name-index compatibility
+/// behavior needed for SQLite-less reads, repair, and old local rollout files.
+#[derive(Clone)]
+pub struct LocalThreadStore {
+    pub(super) config: LocalThreadStoreConfig,
+    live_recorders: Arc<Mutex<HashMap<ThreadId, LiveRecorderEntry>>>,
+    pending_thread_metadata: pending_thread_metadata::PendingThreadMetadataRegistry,
+    live_writer_locks: Arc<LiveWriterLocks>,
+    writer_lock_coordinator: Arc<WriterLockCoordinator>,
+    state_db: Option<StateDbHandle>,
+    thread_history_db: Arc<OnceCell<sqlx::SqlitePool>>,
+}
+
+type WriterLockGuard = Arc<codex_rollout::WriterLockGuard>;
+
+struct LiveRecorderEntry {
+    recorder: RolloutRecorder,
+    // Rollout projection rows are keyed by immutable rollout ID, not the stable thread ID used
+    // to find this live writer.
+    rollout_id: ThreadId,
+    // Local rollout files are materialized lazily, but metadata updates can arrive before the
+    // canonical SessionMeta is durable. Retain the mode captured when live persistence was opened
+    // so missing SQLite rows can still be seeded.
+    history_mode: ThreadHistoryMode,
+    writer_lock: WriterLockGuard,
+}
+
+#[derive(Default)]
+struct LiveWriterLocks {
+    // Keep per-thread locks after a writer goes idle. Removing one while another caller is about
+    // to acquire it could let two operations for the same thread run at once.
+    by_thread: Mutex<HashMap<ThreadId, Arc<ThreadCoordination>>>,
+}
+
+#[derive(Default)]
+struct ThreadCoordination {
+    // Serialize writes and capture consistent fork snapshots.
+    writer: Arc<Mutex<()>>,
+    // Forks hold a shared lease until their child reference is durable; deletion, archive, and
+    // unarchive require exclusive access. Keeping this separate from `writer` lets the source
+    // accept writes during child initialization, including MCP startup that can take 30 seconds.
+    // Operations that need both locks must acquire `lifecycle` before `writer`.
+    lifecycle: Arc<RwLock<()>>,
+}
+
+impl LiveWriterLocks {
+    async fn coordination(&self, thread_id: ThreadId) -> Arc<ThreadCoordination> {
+        self.by_thread
+            .lock()
+            .await
+            .entry(thread_id)
+            .or_default()
+            .clone()
+    }
+
+    async fn lock(&self, thread_id: ThreadId) -> OwnedMutexGuard<()> {
+        self.coordination(thread_id)
+            .await
+            .writer
+            .clone()
+            .lock_owned()
+            .await
+    }
+
+    async fn reserve_lifecycle(&self, thread_id: ThreadId) -> OwnedRwLockReadGuard<()> {
+        self.coordination(thread_id)
+            .await
+            .lifecycle
+            .clone()
+            .read_owned()
+            .await
+    }
+
+    async fn lock_lifecycle(&self, thread_id: ThreadId) -> OwnedRwLockWriteGuard<()> {
+        self.coordination(thread_id)
+            .await
+            .lifecycle
+            .clone()
+            .write_owned()
+            .await
+    }
+}
+
+/// Process-scoped configuration for local thread storage.
+///
+/// This describes where local storage lives. New-thread rollout metadata such
+/// as cwd, provider, and memory mode is supplied when live persistence is opened.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct LocalThreadStoreConfig {
+    pub codex_home: PathBuf,
+    pub sqlite: SqliteConfig,
+    /// Provider used only when older local metadata does not contain one.
+    pub default_model_provider_id: String,
+}
+
+impl LocalThreadStoreConfig {
+    pub fn from_config(config: &impl codex_rollout::RolloutConfigView) -> Self {
+        Self {
+            codex_home: config.codex_home().to_path_buf(),
+            sqlite: config.sqlite_config().clone(),
+            default_model_provider_id: config.model_provider_id().to_string(),
+        }
+    }
+}
+
+impl std::fmt::Debug for LocalThreadStore {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LocalThreadStore")
+            .field("config", &self.config)
+            .finish_non_exhaustive()
+    }
+}
+
+impl LocalThreadStore {
+    /// Create a local store using an already initialized state DB handle.
+    pub fn new(config: LocalThreadStoreConfig, state_db: Option<StateDbHandle>) -> Self {
+        let writer_lock_coordinator = Arc::new(WriterLockCoordinator::new(&config.codex_home));
+        Self {
+            config,
+            live_recorders: Arc::new(Mutex::new(HashMap::new())),
+            pending_thread_metadata:
+                pending_thread_metadata::PendingThreadMetadataRegistry::default(),
+            live_writer_locks: Arc::new(LiveWriterLocks::default()),
+            writer_lock_coordinator,
+            state_db,
+            thread_history_db: Arc::new(OnceCell::new()),
+        }
+    }
+
+    /// Return the state DB handle used by local rollout writers.
+    pub async fn state_db(&self) -> Option<StateDbHandle> {
+        self.state_db.clone()
+    }
+
+    async fn thread_history_db(&self) -> ThreadStoreResult<&sqlx::SqlitePool> {
+        if self.state_db.is_none() {
+            return Err(ThreadStoreError::Unsupported {
+                operation: "paginated_history",
+            });
+        }
+        self.thread_history_db
+            .get_or_try_init(|| async {
+                codex_state::open_thread_history_db(&self.config.sqlite).await
+            })
+            .await
+            .map_err(|err| ThreadStoreError::Internal {
+                message: format!("failed to open thread history database: {err}"),
+            })
+    }
+
+    /// Read a local rollout-backed thread by path.
+    pub async fn read_thread_by_rollout_path(
+        &self,
+        rollout_path: PathBuf,
+        include_archived: bool,
+        include_history: bool,
+    ) -> ThreadStoreResult<StoredThread> {
+        read_thread::read_thread_by_rollout_path(
+            self,
+            rollout_path,
+            include_archived,
+            include_history,
+        )
+        .await
+    }
+
+    /// Return the live local rollout path for legacy local-only code paths.
+    pub async fn live_rollout_path(&self, thread_id: ThreadId) -> ThreadStoreResult<PathBuf> {
+        live_writer::rollout_path(self, thread_id).await
+    }
+
+    pub(super) async fn ensure_live_recorder_absent(
+        &self,
+        thread_id: ThreadId,
+    ) -> ThreadStoreResult<()> {
+        if self.live_recorders.lock().await.contains_key(&thread_id) {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!("thread {thread_id} already has a live local writer"),
+            });
+        }
+        Ok(())
+    }
+
+    fn acquire_writer_lock(&self, thread_id: ThreadId) -> ThreadStoreResult<WriterLockGuard> {
+        self.writer_lock_coordinator
+            .acquire(thread_id)
+            .map(Arc::new)
+            .map_err(|err| {
+                if err.kind() == std::io::ErrorKind::WouldBlock {
+                    ThreadStoreError::Conflict {
+                        message: err.to_string(),
+                    }
+                } else {
+                    ThreadStoreError::Internal {
+                        message: err.to_string(),
+                    }
+                }
+            })
+    }
+
+    async fn acquire_writer_locks(
+        &self,
+        thread_ids: &[ThreadId],
+    ) -> ThreadStoreResult<Vec<WriterLockGuard>> {
+        let mut writer_locks = Vec::with_capacity(thread_ids.len());
+        for &thread_id in thread_ids {
+            if self.live_recorders.lock().await.contains_key(&thread_id) {
+                continue;
+            }
+            writer_locks.push(self.acquire_writer_lock(thread_id)?);
+        }
+        Ok(writer_locks)
+    }
+
+    async fn insert_live_recorder(
+        &self,
+        thread_id: ThreadId,
+        recorder: RolloutRecorder,
+        rollout_id: ThreadId,
+        history_mode: ThreadHistoryMode,
+        writer_lock: WriterLockGuard,
+    ) -> ThreadStoreResult<()> {
+        match self.live_recorders.lock().await.entry(thread_id) {
+            Entry::Occupied(entry) => Err(ThreadStoreError::InvalidRequest {
+                message: format!("thread {} already has a live local writer", entry.key()),
+            }),
+            Entry::Vacant(entry) => {
+                entry.insert(LiveRecorderEntry {
+                    recorder,
+                    rollout_id,
+                    history_mode,
+                    writer_lock,
+                });
+                Ok(())
+            }
+        }
+    }
+
+    async fn load_history(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreResult<StoredThreadHistory> {
+        if let Ok(rollout_path) = live_writer::rollout_path(self, params.thread_id).await {
+            if !params.include_archived
+                && helpers::rollout_path_is_archived(
+                    self.config.codex_home.as_path(),
+                    rollout_path.as_path(),
+                )
+            {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: format!("thread {} is archived", params.thread_id),
+                });
+            }
+            return read_thread::read_thread_by_rollout_path(
+                self,
+                rollout_path,
+                /*include_archived*/ true,
+                /*include_history*/ true,
+            )
+            .await?
+            .history
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: format!("failed to load history for thread {}", params.thread_id),
+            });
+        }
+
+        read_thread::read_thread(
+            self,
+            ReadThreadParams {
+                thread_id: params.thread_id,
+                include_archived: params.include_archived,
+                include_history: true,
+            },
+        )
+        .await?
+        .history
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: format!("failed to load history for thread {}", params.thread_id),
+        })
+    }
+
+    async fn read_thread_by_rollout_path_params(
+        &self,
+        params: ReadThreadByRolloutPathParams,
+    ) -> ThreadStoreResult<StoredThread> {
+        read_thread::read_thread_by_rollout_path(
+            self,
+            params.rollout_path,
+            params.include_archived,
+            params.include_history,
+        )
+        .await
+    }
+
+    /// Lists projection-backed turns without enabling app-server routing yet.
+    pub async fn list_turns(&self, params: ListTurnsParams) -> ThreadStoreResult<TurnPage> {
+        thread_history::list_turns(self, params).await
+    }
+
+    /// Lists projection-backed items without enabling app-server routing yet.
+    pub async fn list_items(&self, params: ListItemsParams) -> ThreadStoreResult<ItemPage> {
+        thread_history::list_items(self, params).await
+    }
+
+    /// Lists bounded ordinary and realtime items from the rollout projection.
+    pub async fn list_timeline(
+        &self,
+        params: ListTimelineParams,
+    ) -> ThreadStoreResult<TimelinePage> {
+        thread_history::list_timeline(self, params).await
+    }
+
+    /// Searches projection-backed visible messages within one paginated thread.
+    pub async fn search_thread_occurrences(
+        &self,
+        params: SearchThreadOccurrencesParams,
+    ) -> ThreadStoreResult<ThreadOccurrenceSearchPage> {
+        thread_history::search_thread_occurrences(self, params).await
+    }
+}
+
+impl ThreadStore for LocalThreadStore {
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn create_thread(&self, params: CreateThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::create_thread(self, params).await })
+    }
+
+    fn stage_pending_thread_metadata(
+        &self,
+        thread_id: ThreadId,
+        patch: ThreadMetadataPatch,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            if self.state_db.is_none() {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: "pending thread metadata requires a state db".to_string(),
+                });
+            }
+            if patch.rollout_path.is_some() {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: "pending thread metadata cannot set rollout_path".to_string(),
+                });
+            }
+            self.pending_thread_metadata.stage(thread_id, patch).await
+        })
+    }
+
+    fn read_pending_thread_metadata(
+        &self,
+        thread_id: ThreadId,
+    ) -> ThreadStoreFuture<'_, Option<ThreadMetadataPatch>> {
+        Box::pin(async move {
+            Ok(self
+                .pending_thread_metadata
+                .lock(thread_id)
+                .await
+                .and_then(|metadata| metadata.clone()))
+        })
+    }
+
+    fn remove_pending_thread_metadata(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.pending_thread_metadata.remove(thread_id).await;
+            Ok(())
+        })
+    }
+
+    fn resume_thread(&self, params: ResumeThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::resume_thread(self, params).await })
+    }
+
+    fn append_items(&self, params: AppendThreadItemsParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::append_items(self, params).await })
+    }
+
+    fn persist_thread(
+        &self,
+        thread_id: ThreadId,
+        _context: PersistContext,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::persist_thread(self, thread_id).await })
+    }
+
+    fn flush_thread(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::flush_thread(self, thread_id).await })
+    }
+
+    fn shutdown_thread(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::shutdown_thread(self, thread_id).await })
+    }
+
+    fn discard_thread(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { live_writer::discard_thread(self, thread_id).await })
+    }
+
+    fn load_history(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadHistory> {
+        Box::pin(LocalThreadStore::load_history(self, params))
+    }
+
+    fn load_latest_model_context(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreFuture<'_, StoredModelContext> {
+        Box::pin(async move { model_context::load_latest_model_context(self, params).await })
+    }
+
+    fn prepare_fork(&self, params: PrepareForkParams) -> ThreadStoreFuture<'_, PreparedFork> {
+        Box::pin(async move { paginated_fork::prepare(self, params).await })
+    }
+
+    fn revert_thread(&self, params: RevertThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { revert_thread::revert(self, params).await })
+    }
+
+    fn read_thread(&self, params: ReadThreadParams) -> ThreadStoreFuture<'_, StoredThread> {
+        Box::pin(async move { read_thread::read_thread(self, params).await })
+    }
+
+    fn read_thread_by_rollout_path(
+        &self,
+        params: ReadThreadByRolloutPathParams,
+    ) -> ThreadStoreFuture<'_, StoredThread> {
+        Box::pin(LocalThreadStore::read_thread_by_rollout_path_params(
+            self, params,
+        ))
+    }
+
+    fn list_threads(&self, params: ListThreadsParams) -> ThreadStoreFuture<'_, ThreadPage> {
+        Box::pin(async move { list_threads::list_threads(self, params).await })
+    }
+
+    fn supports_thread_sections(&self) -> bool {
+        self.state_db.is_some()
+    }
+
+    fn list_thread_sections(
+        &self,
+        params: ListThreadSectionsParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadSectionsPage> {
+        Box::pin(async move { thread_sections::list_thread_sections(self, params).await })
+    }
+
+    fn create_thread_section(
+        &self,
+        params: CreateThreadSectionParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadSection> {
+        Box::pin(async move { thread_sections::create_thread_section(self, params).await })
+    }
+
+    fn rename_thread_section(
+        &self,
+        params: RenameThreadSectionParams,
+    ) -> ThreadStoreFuture<'_, Option<StoredThreadSection>> {
+        Box::pin(async move { thread_sections::rename_thread_section(self, params).await })
+    }
+
+    fn delete_thread_section(
+        &self,
+        params: DeleteThreadSectionParams,
+    ) -> ThreadStoreFuture<'_, bool> {
+        Box::pin(async move { thread_sections::delete_thread_section(self, params).await })
+    }
+
+    fn supports_thread_attachments(&self) -> bool {
+        self.state_db.is_some()
+    }
+
+    fn copy_thread_attachments(
+        &self,
+        source_thread_id: ThreadId,
+        destination_thread_id: ThreadId,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            thread_attachments::copy_thread_attachments(
+                self,
+                source_thread_id,
+                destination_thread_id,
+            )
+            .await
+        })
+    }
+
+    fn add_thread_attachment(
+        &self,
+        params: AddThreadAttachmentParams,
+    ) -> ThreadStoreFuture<'_, AddThreadAttachmentOutcome> {
+        Box::pin(async move { thread_attachments::add_thread_attachment(self, params).await })
+    }
+
+    fn list_thread_attachments(
+        &self,
+        params: ListThreadAttachmentsParams,
+    ) -> ThreadStoreFuture<'_, ThreadAttachmentPage> {
+        Box::pin(async move { thread_attachments::list_thread_attachments(self, params).await })
+    }
+
+    fn remove_thread_attachment(
+        &self,
+        params: RemoveThreadAttachmentParams,
+    ) -> ThreadStoreFuture<'_, RemoveThreadAttachmentOutcome> {
+        Box::pin(async move { thread_attachments::remove_thread_attachment(self, params).await })
+    }
+
+    fn supports_projects(&self) -> bool {
+        self.state_db.is_some()
+    }
+
+    fn list_projects(
+        &self,
+        params: ListProjectsParams,
+    ) -> ThreadStoreFuture<'_, StoredProjectsPage> {
+        Box::pin(async move { projects::list_projects(self, params).await })
+    }
+
+    fn read_project(&self, project_id: String) -> ThreadStoreFuture<'_, Option<StoredProject>> {
+        Box::pin(async move { projects::read_project(self, project_id).await })
+    }
+
+    fn create_project(&self, params: CreateProjectParams) -> ThreadStoreFuture<'_, CreatedProject> {
+        Box::pin(async move { projects::create_project(self, params).await })
+    }
+
+    fn update_project(
+        &self,
+        params: UpdateProjectParams,
+    ) -> ThreadStoreFuture<'_, Option<UpdatedProject>> {
+        Box::pin(async move { projects::update_project(self, params).await })
+    }
+
+    fn move_project(
+        &self,
+        params: MoveProjectParams,
+    ) -> ThreadStoreFuture<'_, Option<ProjectMoveOutcome>> {
+        Box::pin(async move { projects::move_project(self, params).await })
+    }
+
+    fn delete_project(&self, project_id: String) -> ThreadStoreFuture<'_, Option<DeletedProject>> {
+        Box::pin(async move { projects::delete_project(self, project_id).await })
+    }
+
+    fn supports_paginated_history_lists(&self) -> bool {
+        self.state_db.is_some()
+    }
+
+    fn list_turns(&self, params: ListTurnsParams) -> ThreadStoreFuture<'_, TurnPage> {
+        Box::pin(LocalThreadStore::list_turns(self, params))
+    }
+
+    fn list_items(&self, params: ListItemsParams) -> ThreadStoreFuture<'_, ItemPage> {
+        Box::pin(LocalThreadStore::list_items(self, params))
+    }
+
+    fn list_timeline(&self, params: ListTimelineParams) -> ThreadStoreFuture<'_, TimelinePage> {
+        Box::pin(LocalThreadStore::list_timeline(self, params))
+    }
+
+    fn search_threads(
+        &self,
+        params: SearchThreadsParams,
+    ) -> ThreadStoreFuture<'_, ThreadSearchPage> {
+        Box::pin(async move { search_threads::search_threads(self, params).await })
+    }
+
+    fn search_thread_occurrences(
+        &self,
+        params: SearchThreadOccurrencesParams,
+    ) -> ThreadStoreFuture<'_, ThreadOccurrenceSearchPage> {
+        Box::pin(LocalThreadStore::search_thread_occurrences(self, params))
+    }
+
+    fn update_thread_metadata(
+        &self,
+        params: UpdateThreadMetadataParams,
+    ) -> ThreadStoreFuture<'_, Option<StoredThread>> {
+        Box::pin(async move {
+            update_thread_metadata::update_thread_metadata(self, params)
+                .await
+                .map(Some)
+        })
+    }
+
+    fn move_thread_to_section(
+        &self,
+        params: MoveThreadToSectionParams,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { move_thread_to_section::move_thread_to_section(self, params).await })
+    }
+
+    fn archive_thread(&self, params: ArchiveThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            archive_thread::archive_threads(
+                self,
+                ArchiveThreadsParams {
+                    thread_ids: vec![params.thread_id],
+                    writer_lock_thread_ids: Vec::new(),
+                },
+            )
+            .await
+            .map(|_| ())
+        })
+    }
+
+    fn archive_threads(
+        &self,
+        params: ArchiveThreadsParams,
+    ) -> ThreadStoreFuture<'_, Vec<ThreadId>> {
+        Box::pin(async move { archive_thread::archive_threads(self, params).await })
+    }
+
+    fn unarchive_thread(&self, params: ArchiveThreadParams) -> ThreadStoreFuture<'_, StoredThread> {
+        Box::pin(async move { unarchive_thread::unarchive_thread(self, params).await })
+    }
+
+    fn delete_thread(&self, params: DeleteThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { delete_thread::delete_thread(self, params).await })
+    }
+
+    fn delete_threads(&self, params: DeleteThreadsParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move { delete_thread::delete_threads(self, params).await })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[path = "acquisition_tests.rs"]
+    mod acquisition_tests;
+    use std::sync::Arc;
+
+    use codex_protocol::ThreadId;
+    use codex_protocol::config_types::ReasoningSummary;
+    use codex_protocol::items::TurnItem;
+    use codex_protocol::items::UserMessageItem;
+    use codex_protocol::models::BaseInstructions;
+    use codex_protocol::models::FunctionCallOutputPayload;
+    use codex_protocol::models::MessagePhase;
+    use codex_protocol::models::ResponseItem;
+    use codex_protocol::protocol::AgentMessageEvent;
+    use codex_protocol::protocol::AskForApproval;
+    use codex_protocol::protocol::EventMsg;
+    use codex_protocol::protocol::ItemCompletedEvent;
+    use codex_protocol::protocol::SandboxPolicy;
+    use codex_protocol::protocol::SessionSource;
+    use codex_protocol::protocol::ThreadHistoryMode;
+    use codex_protocol::protocol::ThreadMemoryMode;
+    use codex_protocol::protocol::TurnCompleteEvent;
+    use codex_protocol::protocol::TurnContextItem;
+    use codex_protocol::protocol::TurnStartedEvent;
+    use codex_protocol::protocol::UserMessageEvent;
+    use codex_rollout::RolloutItem;
+    use tempfile::TempDir;
+
+    use super::*;
+    use crate::LiveThread;
+    use crate::ThreadPersistenceMetadata;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_archived_session_file;
+    use crate::local::test_support::write_session_file;
+    use crate::local::test_support::write_session_file_with_history_mode;
+
+    #[tokio::test]
+    async fn live_writer_lifecycle_writes_and_closes() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id = ThreadId::default();
+
+        store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("load rollout path");
+
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("first live write")],
+            })
+            .await
+            .expect("append live item");
+        store
+            .persist_thread(thread_id, PersistContext::Standard)
+            .await
+            .expect("persist live thread");
+        store
+            .flush_thread(thread_id)
+            .await
+            .expect("flush live thread");
+
+        assert_rollout_contains_message(rollout_path.as_path(), "first live write").await;
+
+        store
+            .shutdown_thread(thread_id)
+            .await
+            .expect("shutdown live thread");
+        let err = store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("write after shutdown")],
+            })
+            .await
+            .expect_err("shutdown should remove the live thread writer");
+        assert!(
+            matches!(err, ThreadStoreError::ThreadNotFound { thread_id: missing } if missing == thread_id)
+        );
+    }
+
+    #[tokio::test]
+    async fn raw_append_items_does_not_update_sqlite_metadata() {
+        // This pins the ThreadStore contract: raw appends are history-only. Callers that need
+        // metadata updates must use LiveThread or call update_thread_metadata explicitly.
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let thread_id = ThreadId::default();
+
+        store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("raw append")],
+            })
+            .await
+            .expect("append raw item");
+        store.flush_thread(thread_id).await.expect("flush thread");
+
+        assert_eq!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("sqlite metadata read"),
+            None
+        );
+    }
+
+    #[tokio::test]
+    async fn live_thread_observes_appended_items_into_sqlite_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let thread_id = ThreadId::default();
+        let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+
+        live_thread
+            .append_items(&[user_message_item("observed append")])
+            .await
+            .expect("append observed item");
+        live_thread.flush().await.expect("flush thread");
+
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(
+            metadata.first_user_message.as_deref(),
+            Some("observed append")
+        );
+        assert_eq!(metadata.preview.as_deref(), Some("observed append"));
+        assert_eq!(metadata.title, "observed append");
+    }
+
+    #[tokio::test]
+    async fn paginated_resume_prefers_explicit_rollout_path_over_stale_sqlite_path() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let uuid = uuid::Uuid::from_u128(228);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("paginated session file");
+        let stale_rollout_path = home.path().join("stale-rollout.jsonl");
+        tokio::fs::write(&stale_rollout_path, "malformed session metadata\n")
+            .await
+            .expect("write stale rollout");
+        let mut builder = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            stale_rollout_path,
+            chrono::Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.history_mode = ThreadHistoryMode::Paginated;
+        builder.cwd = home.path().to_path_buf();
+        let mut metadata = builder.build("test-provider");
+        metadata.preview = Some("original user message".to_string());
+        metadata.first_user_message = Some("original user message".to_string());
+        metadata.title = "original user message".to_string();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("update stale sqlite rollout path");
+
+        let resumed = LiveThread::resume(
+            store,
+            ThreadHistoryMode::Paginated,
+            ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path.clone()),
+                history: Some(Arc::new(vec![user_message_item("bounded suffix")])),
+                include_archived: false,
+                metadata: ThreadPersistenceMetadata {
+                    cwd: Some(home.path().to_path_buf()),
+                    model_provider: "test-provider".to_string(),
+                    memory_mode: ThreadMemoryMode::Enabled,
+                },
+            },
+        )
+        .await
+        .expect("resume paginated thread from its requested rollout");
+        assert_eq!(
+            resumed.local_rollout_path().await.expect("live rollout"),
+            Some(rollout_path)
+        );
+        resumed.shutdown().await.expect("shutdown resumed writer");
+
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(
+            (
+                metadata.preview.as_deref(),
+                metadata.title.as_str(),
+                metadata.first_user_message.as_deref(),
+            ),
+            (
+                Some("original user message"),
+                "original user message",
+                Some("original user message"),
+            )
+        );
+    }
+
+    #[tokio::test]
+    async fn live_thread_does_not_derive_metadata_from_inherited_items() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let thread_id = ThreadId::default();
+        let mut params = create_thread_params(thread_id);
+        params.history_mode = ThreadHistoryMode::Paginated;
+        let cwd = std::env::current_dir().expect("current directory");
+        let turn_context = |model: &str, approval_policy| {
+            RolloutItem::TurnContext(TurnContextItem {
+                turn_id: Some("turn-1".to_string()),
+                root_turn_id: None,
+                disabled_plugin_ids: None,
+                cwd: serde_json::from_value(serde_json::json!(cwd)).expect("absolute cwd"),
+                workspace_roots: None,
+                current_date: None,
+                timezone: None,
+                approval_policy,
+                approvals_reviewer: None,
+                sandbox_policy: SandboxPolicy::DangerFullAccess,
+                permission_profile: None,
+                active_permission_profile: None,
+                network: None,
+                file_system_sandbox_policy: None,
+                model: model.to_string(),
+                comp_hash: None,
+                personality: None,
+                collaboration_mode: None,
+                multi_agent_version: None,
+                multi_agent_mode: None,
+                realtime_active: None,
+                cyber_access_program: None,
+                effort: None,
+                summary: ReasoningSummary::Auto,
+            })
+        };
+
+        let mut guard = crate::LiveThreadInitGuard::default();
+        let live_thread = LiveThread::create_with_inherited_model_context(
+            store,
+            params,
+            &[turn_context("parent-model", AskForApproval::Never)],
+            &mut guard,
+        )
+        .await
+        .expect("create live thread with inherited context");
+        guard.commit();
+        live_thread
+            .persist(PersistContext::Standard)
+            .await
+            .expect("persist thread");
+        let inherited_metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(inherited_metadata.model, None);
+
+        live_thread
+            .append_items(&[turn_context("child-model", AskForApproval::OnRequest)])
+            .await
+            .expect("append child context");
+        let child_metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(child_metadata.model.as_deref(), Some("child-model"));
+        assert_eq!(child_metadata.approval_mode, "on-request");
+    }
+
+    #[tokio::test]
+    async fn live_thread_output_advances_updated_at_but_not_recency_at() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let thread_id = ThreadId::default();
+        let live_thread = LiveThread::create(store, create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+
+        live_thread
+            .append_items(&[user_message_item("start thread")])
+            .await
+            .expect("append initial user message");
+        live_thread.flush().await.expect("flush thread");
+        let before_turn_start = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+
+        live_thread
+            .append_items(&[RolloutItem::EventMsg(EventMsg::TurnStarted(
+                TurnStartedEvent {
+                    turn_id: "turn-1".to_string(),
+                    root_turn_id: None,
+                    trace_id: None,
+                    started_at: None,
+                    model_context_window: None,
+                    collaboration_mode_kind: Default::default(),
+                },
+            ))])
+            .await
+            .expect("append turn start");
+        live_thread.flush().await.expect("flush thread");
+        let after_turn_start = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert!(after_turn_start.recency_at > before_turn_start.recency_at);
+
+        live_thread
+            .append_items(&[
+                RolloutItem::EventMsg(EventMsg::AgentMessage(AgentMessageEvent {
+                    message: "commentary".to_string(),
+                    phase: Some(MessagePhase::Commentary),
+                    memory_citation: None,
+                    delivery: None,
+                    questions: None,
+                })),
+                RolloutItem::ResponseItem(
+                    ResponseItem::FunctionCallOutput {
+                        id: None,
+                        call_id: Some("call-1".to_string()),
+                        name: None,
+                        namespace: None,
+                        output: FunctionCallOutputPayload::from_text("tool output".to_string()),
+                        internal_chat_message_metadata_passthrough: None,
+                    }
+                    .into(),
+                ),
+                RolloutItem::EventMsg(EventMsg::TokenCount(
+                    codex_protocol::protocol::TokenCountEvent {
+                        info: None,
+                        rate_limits: None,
+                    },
+                )),
+                RolloutItem::EventMsg(EventMsg::TurnComplete(TurnCompleteEvent {
+                    turn_id: "turn-1".to_string(),
+                    started_at: None,
+                    last_agent_message: None,
+                    error: None,
+                    completed_at: None,
+                    duration_ms: None,
+                    time_to_first_token_ms: None,
+                })),
+            ])
+            .await
+            .expect("append post-start items");
+        live_thread.flush().await.expect("flush thread");
+        let completed = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+
+        assert!(completed.updated_at > after_turn_start.updated_at);
+        assert_eq!(completed.recency_at, after_turn_start.recency_at);
+    }
+
+    #[tokio::test]
+    async fn live_thread_shutdown_does_not_materialize_empty_thread_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let thread_id = ThreadId::default();
+        let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("live rollout path");
+
+        live_thread.shutdown().await.expect("shutdown thread");
+
+        assert!(
+            !tokio::fs::try_exists(rollout_path.as_path())
+                .await
+                .expect("rollout path should be checkable")
+        );
+        assert_eq!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("sqlite metadata read"),
+            None
+        );
+    }
+
+    #[tokio::test]
+    async fn live_thread_memory_mode_update_before_rollout_materializes_keeps_history_mode() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let thread_id = ThreadId::default();
+        let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+
+        live_thread
+            .update_memory_mode(ThreadMemoryMode::Disabled, /*include_archived*/ false)
+            .await
+            .expect("update memory mode");
+
+        assert_eq!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("sqlite metadata read")
+                .expect("sqlite metadata")
+                .history_mode,
+            ThreadHistoryMode::Legacy
+        );
+        assert_eq!(
+            runtime
+                .get_thread_memory_mode(thread_id)
+                .await
+                .expect("thread memory mode should be readable")
+                .as_deref(),
+            Some("disabled")
+        );
+    }
+
+    #[tokio::test]
+    async fn live_thread_shutdown_with_buffered_items_materializes_before_metadata_read() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let thread_id = ThreadId::default();
+        let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("live rollout path");
+
+        live_thread
+            .append_items(&[RolloutItem::EventMsg(EventMsg::TokenCount(
+                codex_protocol::protocol::TokenCountEvent {
+                    info: None,
+                    rate_limits: None,
+                },
+            ))])
+            .await
+            .expect("append metadata-only item");
+        live_thread.shutdown().await.expect("shutdown thread");
+
+        assert!(
+            tokio::fs::try_exists(rollout_path.as_path())
+                .await
+                .expect("rollout path should be checkable")
+        );
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(metadata.rollout_path, rollout_path);
+    }
+
+    #[tokio::test]
+    async fn live_thread_resume_loads_history_before_observing_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let uuid = uuid::Uuid::from_u128(401);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T17-00-00", uuid).expect("session file");
+        let live_thread = LiveThread::resume(
+            store,
+            ThreadHistoryMode::Legacy,
+            ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: false,
+                metadata: ThreadPersistenceMetadata {
+                    cwd: Some(home.path().to_path_buf()),
+                    model_provider: "different-provider".to_string(),
+                    memory_mode: ThreadMemoryMode::Enabled,
+                },
+            },
+        )
+        .await
+        .expect("resume live thread");
+
+        live_thread
+            .append_items(&[user_message_item("new live append")])
+            .await
+            .expect("append after resume");
+
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(
+            metadata.created_at.to_rfc3339(),
+            "2025-01-03T17:00:00+00:00"
+        );
+        assert_eq!(metadata.model_provider, "test-provider");
+        assert_eq!(
+            metadata.first_user_message.as_deref(),
+            Some("Hello from user")
+        );
+    }
+
+    #[tokio::test]
+    async fn live_thread_resume_loads_history_from_explicit_external_rollout_path() {
+        let home = TempDir::new().expect("temp dir");
+        let external_home = TempDir::new().expect("external temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+        let uuid = uuid::Uuid::from_u128(402);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file(external_home.path(), "2025-01-03T17-30-00", uuid)
+            .expect("external session file");
+        let live_thread = LiveThread::resume(
+            store,
+            ThreadHistoryMode::Legacy,
+            ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: false,
+                metadata: ThreadPersistenceMetadata {
+                    cwd: Some(home.path().to_path_buf()),
+                    model_provider: "different-provider".to_string(),
+                    memory_mode: ThreadMemoryMode::Enabled,
+                },
+            },
+        )
+        .await
+        .expect("resume external live thread");
+
+        live_thread
+            .append_items(&[user_message_item("new external append")])
+            .await
+            .expect("append after external resume");
+
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(
+            metadata.created_at.to_rfc3339(),
+            "2025-01-03T17:30:00+00:00"
+        );
+        assert_eq!(metadata.model_provider, "test-provider");
+        assert_eq!(
+            metadata.first_user_message.as_deref(),
+            Some("Hello from user")
+        );
+    }
+
+    #[tokio::test]
+    async fn create_thread_rejects_missing_cwd() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let competing_store =
+            LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        for history_mode in [ThreadHistoryMode::Legacy, ThreadHistoryMode::Paginated] {
+            let thread_id = ThreadId::default();
+            let mut params = create_thread_params(thread_id);
+            params.history_mode = history_mode;
+            params.metadata.cwd = None;
+
+            let err = store
+                .create_thread(params)
+                .await
+                .expect_err("local thread store should require cwd");
+
+            assert!(matches!(
+                err,
+                ThreadStoreError::InvalidRequest { message }
+                    if message == "local thread store requires a cwd"
+            ));
+
+            let mut valid_params = create_thread_params(thread_id);
+            valid_params.history_mode = history_mode;
+            competing_store
+                .create_thread(valid_params)
+                .await
+                .expect("failed initialization should release cross-process writer ownership");
+        }
+    }
+
+    #[tokio::test]
+    async fn discard_thread_drops_unmaterialized_live_writer() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        for history_mode in [ThreadHistoryMode::Legacy, ThreadHistoryMode::Paginated] {
+            let thread_id = ThreadId::default();
+            let mut params = create_thread_params(thread_id);
+            params.history_mode = history_mode;
+
+            store
+                .create_thread(params)
+                .await
+                .expect("create live thread");
+            let rollout_path = store
+                .live_rollout_path(thread_id)
+                .await
+                .expect("load rollout path");
+            {
+                let recorder = store
+                    .live_recorders
+                    .lock()
+                    .await
+                    .get(&thread_id)
+                    .expect("live recorder")
+                    .recorder
+                    .clone();
+                recorder
+                    .record_canonical_items(&[user_message_item("deferred item to discard")])
+                    .await
+                    .expect("queue deferred item without materializing it");
+            }
+            assert!(!rollout_path.exists());
+
+            let lock_path = home
+                .path()
+                .join("thread-writer-locks")
+                .join(format!("{thread_id}.lock"));
+            assert!(lock_path.exists());
+            store
+                .discard_thread(thread_id)
+                .await
+                .expect("discard live thread");
+
+            assert!(!rollout_path.exists());
+            assert!(!lock_path.exists());
+            let err = store
+                .append_items(AppendThreadItemsParams {
+                    thread_id,
+                    items: vec![user_message_item("write after discard")],
+                })
+                .await
+                .expect_err("discard should remove the live thread writer");
+            assert!(
+                matches!(err, ThreadStoreError::ThreadNotFound { thread_id: missing } if missing == thread_id)
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn resume_thread_reopens_live_writer_and_appends() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let thread_id = ThreadId::default();
+
+        let first_store = LocalThreadStore::new(config.clone(), /*state_db*/ None);
+        first_store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect("create initial thread");
+        first_store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("before resume")],
+            })
+            .await
+            .expect("append initial item");
+        first_store
+            .persist_thread(thread_id, PersistContext::Standard)
+            .await
+            .expect("persist initial thread");
+        first_store
+            .flush_thread(thread_id)
+            .await
+            .expect("flush initial thread");
+        let rollout_path = first_store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("load rollout path");
+        first_store
+            .shutdown_thread(thread_id)
+            .await
+            .expect("shutdown initial writer");
+
+        let resumed_store = LocalThreadStore::new(config, /*state_db*/ None);
+        resumed_store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: None,
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("resume live thread");
+        resumed_store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("after resume")],
+            })
+            .await
+            .expect("append resumed item");
+        resumed_store
+            .flush_thread(thread_id)
+            .await
+            .expect("flush resumed thread");
+
+        assert_rollout_contains_message(rollout_path.as_path(), "before resume").await;
+        assert_rollout_contains_message(rollout_path.as_path(), "after resume").await;
+    }
+
+    #[tokio::test]
+    async fn live_writers_reject_cross_process_create_and_resume() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let primary = LocalThreadStore::new(config.clone(), /*state_db*/ None);
+        let secondary = LocalThreadStore::new(config, /*state_db*/ None);
+
+        for history_mode in [ThreadHistoryMode::Legacy, ThreadHistoryMode::Paginated] {
+            let thread_id = ThreadId::default();
+            let mut create_params = create_thread_params(thread_id);
+            create_params.history_mode = history_mode;
+
+            primary
+                .create_thread(create_params.clone())
+                .await
+                .expect("create live thread");
+            primary
+                .persist_thread(thread_id, PersistContext::Standard)
+                .await
+                .expect("persist thread for resume");
+            let rollout_path = primary
+                .live_rollout_path(thread_id)
+                .await
+                .expect("load rollout path");
+            let resume_params = ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            };
+
+            let error = secondary
+                .create_thread(create_params)
+                .await
+                .expect_err("competing create should fail");
+            assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+
+            let error = secondary
+                .resume_thread(resume_params.clone())
+                .await
+                .expect_err("competing resume should fail");
+            assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+
+            primary
+                .shutdown_thread(thread_id)
+                .await
+                .expect("shutdown should release writer ownership");
+            secondary
+                .resume_thread(resume_params)
+                .await
+                .expect("resume after shutdown should acquire writer ownership");
+        }
+    }
+
+    #[tokio::test]
+    async fn create_thread_rejects_duplicate_live_writer() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id = ThreadId::default();
+
+        store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+
+        let err = store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect_err("duplicate live writer should fail");
+
+        assert!(matches!(err, ThreadStoreError::InvalidRequest { .. }));
+        assert!(err.to_string().contains("already has a live local writer"));
+    }
+
+    #[tokio::test]
+    async fn resume_thread_rejects_duplicate_live_writer() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id = ThreadId::default();
+
+        store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect("create live thread");
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("live rollout path");
+        let err = store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect_err("duplicate live resume should fail");
+        assert!(matches!(err, ThreadStoreError::InvalidRequest { .. }));
+        assert!(err.to_string().contains("already has a live local writer"));
+    }
+
+    #[tokio::test]
+    async fn resume_thread_rejects_missing_cwd() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let competing_store =
+            LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = uuid::Uuid::from_u128(408);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-04T11-30-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let err = store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path.clone()),
+                history: None,
+                include_archived: true,
+                metadata: ThreadPersistenceMetadata {
+                    cwd: None,
+                    model_provider: "test-provider".to_string(),
+                    memory_mode: ThreadMemoryMode::Enabled,
+                },
+            })
+            .await
+            .expect_err("missing cwd should fail");
+
+        assert!(matches!(err, ThreadStoreError::InvalidRequest { .. }));
+        assert!(err.to_string().contains("requires a cwd"));
+
+        competing_store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("failed initialization should release cross-process writer ownership");
+    }
+
+    #[tokio::test]
+    async fn load_history_uses_live_writer_rollout_path() {
+        let home = TempDir::new().expect("temp dir");
+        let external_home = TempDir::new().expect("external temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = uuid::Uuid::from_u128(404);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file(external_home.path(), "2025-01-04T10-00-00", uuid)
+            .expect("external session file");
+
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("resume live thread");
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("external history item")],
+            })
+            .await
+            .expect("append live item");
+        store
+            .flush_thread(thread_id)
+            .await
+            .expect("flush live thread");
+
+        let history = store
+            .load_history(LoadThreadHistoryParams {
+                thread_id,
+                include_archived: false,
+            })
+            .await
+            .expect("load external live history");
+
+        assert!(history.items.iter().any(|item| {
+            matches!(
+                item,
+                RolloutItem::EventMsg(EventMsg::UserMessage(event)) if event.message == "external history item"
+            )
+        }));
+    }
+
+    #[tokio::test]
+    async fn read_thread_uses_live_writer_rollout_path_for_external_resume() {
+        let home = TempDir::new().expect("temp dir");
+        let external_home = TempDir::new().expect("external temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = uuid::Uuid::from_u128(406);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file(external_home.path(), "2025-01-04T11-00-00", uuid)
+            .expect("external session file");
+
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path.clone()),
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("resume live thread");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: true,
+            })
+            .await
+            .expect("read external live thread");
+
+        assert_eq!(thread.rollout_path, Some(rollout_path));
+        assert!(thread.history.expect("history").items.iter().any(|item| {
+            matches!(
+                item,
+                RolloutItem::EventMsg(EventMsg::UserMessage(event)) if event.message == "Hello from user"
+            )
+        }));
+
+        let error = store
+            .prepare_fork(PrepareForkParams {
+                thread_id,
+                boundary: crate::ForkBoundary::Latest,
+            })
+            .await
+            .expect_err("external rollouts cannot be referenced by thread id");
+        assert!(error.to_string().contains("must be in Codex home"));
+    }
+
+    #[tokio::test]
+    async fn load_history_uses_live_writer_rollout_path_for_archived_source() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = uuid::Uuid::from_u128(405);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_archived_session_file(home.path(), "2025-01-04T10-30-00", uuid)
+            .expect("archived session file");
+
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: true,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("resume live archived thread");
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("archived live history item")],
+            })
+            .await
+            .expect("append live item");
+        store
+            .flush_thread(thread_id)
+            .await
+            .expect("flush live thread");
+
+        let err = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect_err("active-only read should reject archived live thread");
+        assert!(matches!(err, ThreadStoreError::InvalidRequest { .. }));
+
+        let err = store
+            .load_history(LoadThreadHistoryParams {
+                thread_id,
+                include_archived: false,
+            })
+            .await
+            .expect_err("active-only history should reject archived live thread");
+        assert!(matches!(err, ThreadStoreError::InvalidRequest { .. }));
+        assert!(err.to_string().contains("archived"));
+
+        let history = store
+            .load_history(LoadThreadHistoryParams {
+                thread_id,
+                include_archived: true,
+            })
+            .await
+            .expect("load archived live history");
+
+        assert!(history.items.iter().any(|item| {
+            matches!(
+                item,
+                RolloutItem::EventMsg(EventMsg::UserMessage(event)) if event.message == "archived live history item"
+            )
+        }));
+    }
+
+    #[tokio::test]
+    async fn read_thread_by_rollout_path_includes_history() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id = ThreadId::default();
+
+        store
+            .create_thread(create_thread_params(thread_id))
+            .await
+            .expect("create thread");
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![user_message_item("path read")],
+            })
+            .await
+            .expect("append item");
+        store.flush_thread(thread_id).await.expect("flush thread");
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("load rollout path");
+
+        let thread = store
+            .read_thread_by_rollout_path(
+                rollout_path,
+                /*include_archived*/ true,
+                /*include_history*/ true,
+            )
+            .await
+            .expect("read thread by rollout path");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.history_mode, ThreadHistoryMode::Legacy);
+        assert_eq!(
+            thread
+                .history
+                .as_ref()
+                .expect("history")
+                .items
+                .iter()
+                .filter(|item| matches!(item, RolloutItem::EventMsg(EventMsg::UserMessage(_))))
+                .count(),
+            1
+        );
+    }
+
+    #[tokio::test]
+    async fn paginated_threads_allow_metadata_reads_and_resume_but_reject_legacy_history_paths() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = uuid::Uuid::from_u128(408);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-04T12-00-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("metadata read");
+        assert_eq!(thread.history_mode, ThreadHistoryMode::Paginated);
+        assert!(thread.history.is_none());
+
+        let thread = store
+            .read_thread_by_rollout_path(
+                rollout_path.clone(),
+                /*include_archived*/ true,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("metadata path read");
+        assert_eq!(thread.history_mode, ThreadHistoryMode::Paginated);
+        assert!(thread.history.is_none());
+
+        assert_paginated_threads_unsupported(
+            store
+                .read_thread(ReadThreadParams {
+                    thread_id,
+                    include_archived: false,
+                    include_history: true,
+                })
+                .await
+                .expect_err("full history read should fail"),
+        );
+        assert_paginated_threads_unsupported(
+            store
+                .read_thread_by_rollout_path(
+                    rollout_path.clone(),
+                    /*include_archived*/ true,
+                    /*include_history*/ true,
+                )
+                .await
+                .expect_err("full history path read should fail"),
+        );
+        assert_paginated_threads_unsupported(
+            store
+                .load_history(LoadThreadHistoryParams {
+                    thread_id,
+                    include_archived: false,
+                })
+                .await
+                .expect_err("history load should fail"),
+        );
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(rollout_path),
+                history: None,
+                include_archived: false,
+                metadata: thread_metadata(),
+            })
+            .await
+            .expect("resume should succeed");
+    }
+
+    #[tokio::test]
+    async fn paginated_live_appends_use_paginated_history_mode() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let thread_id = ThreadId::default();
+        let mut create_params = create_thread_params(thread_id);
+        create_params.history_mode = ThreadHistoryMode::Paginated;
+        store
+            .create_thread(create_params)
+            .await
+            .expect("create paginated thread");
+        let paginated_item = RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+            thread_id,
+            turn_id: "turn-1".to_string(),
+            item: TurnItem::UserMessage(UserMessageItem {
+                id: "item-1".to_string(),
+                client_id: None,
+                content: Vec::new(),
+            }),
+            started_at_ms: Some(0),
+            completed_at_ms: 1,
+        }));
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![
+                    user_message_item("legacy event should not persist"),
+                    paginated_item,
+                ],
+            })
+            .await
+            .expect("append paginated item");
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("paginated rollout path");
+        let (items, _, _) = RolloutRecorder::load_rollout_items(rollout_path.as_path())
+            .await
+            .expect("load paginated rollout");
+        assert!(items.iter().any(|item| {
+            matches!(
+                item,
+                RolloutItem::EventMsg(EventMsg::ItemCompleted(event))
+                    if event.turn_id == "turn-1"
+            )
+        }));
+        assert!(!items.iter().any(|item| {
+            matches!(
+                item,
+                RolloutItem::EventMsg(EventMsg::UserMessage(event))
+                    if event.message == "legacy event should not persist"
+            )
+        }));
+    }
+
+    fn create_thread_params(thread_id: ThreadId) -> CreateThreadParams {
+        CreateThreadParams {
+            session_id: thread_id.into(),
+            thread_id,
+            extra_config: None,
+            forked_from_id: None,
+            parent_thread_id: None,
+            source: SessionSource::Exec,
+            thread_source: None,
+            originator: "test_originator".to_string(),
+            base_instructions: BaseInstructions::default(),
+            dynamic_tools: Vec::new(),
+            selected_capability_roots: Vec::new(),
+            multi_agent_version: None,
+            history_mode: ThreadHistoryMode::Legacy,
+            history_base: None,
+            subagent_history_start_ordinal: None,
+            initial_window_id: uuid::Uuid::now_v7().to_string(),
+            runtime_workspace_roots: None,
+            metadata: thread_metadata(),
+        }
+    }
+
+    fn assert_paginated_threads_unsupported(err: ThreadStoreError) {
+        assert!(matches!(
+            err,
+            ThreadStoreError::Unsupported {
+                operation: "paginated_threads"
+            }
+        ));
+    }
+
+    fn thread_metadata() -> ThreadPersistenceMetadata {
+        ThreadPersistenceMetadata {
+            cwd: Some(std::env::current_dir().expect("cwd")),
+            model_provider: "test-provider".to_string(),
+            memory_mode: ThreadMemoryMode::Enabled,
+        }
+    }
+
+    fn user_message_item(message: &str) -> RolloutItem {
+        RolloutItem::EventMsg(EventMsg::UserMessage(UserMessageEvent {
+            client_id: None,
+            message: message.to_string(),
+            images: None,
+            local_images: Vec::new(),
+            text_elements: Vec::new(),
+            ..Default::default()
+        }))
+    }
+
+    async fn assert_rollout_contains_message(path: &std::path::Path, expected: &str) {
+        let (items, _, _) = RolloutRecorder::load_rollout_items(path)
+            .await
+            .expect("load rollout items");
+        assert!(items.iter().any(|item| {
+            matches!(
+                item,
+                RolloutItem::EventMsg(EventMsg::UserMessage(event)) if event.message == expected
+            )
+        }));
+    }
+}
diff --git a/codex-rs/thread-store/src/local/model_context.rs b/codex-rs/thread-store/src/local/model_context.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c96883747d3b8269753a67827c135acb8cc476a1
--- /dev/null
+++ b/codex-rs/thread-store/src/local/model_context.rs
@@ -0,0 +1,200 @@
+//! Reconstructs model context and preserves source runtime metadata across fork cutoffs.
+
+use std::io;
+
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::ModelContextScan;
+use codex_rollout::ModelContextScanProgress;
+use codex_rollout::ReverseJsonlScanner;
+use codex_rollout::RolloutItem;
+use codex_rollout::ScanOutcome;
+
+use super::LocalThreadStore;
+use super::read_thread;
+use super::rollout_lineage::RolloutLineage;
+use super::thread_rollout_resolver;
+use crate::LoadThreadHistoryParams;
+use crate::StoredModelContext;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+#[cfg(test)]
+#[path = "model_context_tests.rs"]
+mod tests;
+
+/// Loads rollout items needed to reconstruct the latest model-visible context.
+///
+/// Paginated JSONL rollouts use a reverse scan. When it finds both a usable replacement-
+/// history checkpoint and the completed user-turn context needed for resume metadata, the returned
+/// replay starts with the canonical `SessionMeta` followed by that newest suffix. When no
+/// bounded cutoff is available, the scan continues to the beginning and returns the complete
+/// replay it already accumulated.
+///
+/// Compressed segments are decoded before applying their original JSONL offsets. Legacy rollouts
+/// keep the existing full-history path.
+pub(super) async fn load_latest_model_context(
+    store: &LocalThreadStore,
+    params: LoadThreadHistoryParams,
+) -> ThreadStoreResult<StoredModelContext> {
+    let resolved = if params.include_archived {
+        thread_rollout_resolver::resolve_current_including_archived(store, params.thread_id).await?
+    } else {
+        thread_rollout_resolver::resolve_current(store, params.thread_id).await?
+    };
+    let path =
+        resolved
+            .map(|resolved| resolved.path)
+            .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                message: format!("no rollout found for thread id {}", params.thread_id),
+            })?;
+
+    let session_meta = codex_rollout::read_session_meta_line(path.as_path())
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to read session metadata {}: {err}", path.display()),
+        })?;
+    if session_meta.meta.id != params.thread_id {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!(
+                "rollout at {} belongs to thread {}, not {}",
+                path.display(),
+                session_meta.meta.id,
+                params.thread_id
+            ),
+        });
+    }
+
+    let items = if matches!(session_meta.meta.history_mode, ThreadHistoryMode::Paginated) {
+        let lineage = store.resolve_rollout_lineage(params.thread_id).await?;
+        scan_model_context_from_lineage(lineage, session_meta).await?
+    } else {
+        read_thread::load_history_items(path.as_path()).await?
+    };
+
+    Ok(StoredModelContext {
+        thread_id: params.thread_id,
+        items,
+    })
+}
+
+/// Loads startup context from a fork's frozen inherited prefix.
+pub(super) async fn load_for_fork(
+    lineage: RolloutLineage,
+    history_base: Option<HistoryPosition>,
+) -> ThreadStoreResult<Vec<RolloutItem>> {
+    let source_path = lineage
+        .segments()
+        .last()
+        .map(|segment| segment.rollout_path.as_path())
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: "fork lineage has no source segment".to_string(),
+        })?;
+    let mut session_meta = codex_rollout::read_session_meta_line(source_path)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!(
+                "failed to read session metadata {}: {err}",
+                source_path.display()
+            ),
+        })?;
+    if session_meta.meta.multi_agent_version.is_none() {
+        // Recover only the runtime version before applying the fork cutoff. Stop at the
+        // newest version-bearing context instead of retaining the source's full replay.
+        let source_lineage = lineage.clone();
+        session_meta.meta.multi_agent_version = tokio::task::spawn_blocking(move || {
+            for segment in source_lineage.segments().iter().rev() {
+                let file =
+                    codex_rollout::open_rollout_seekable_reader(segment.rollout_path.as_path())?;
+                let mut scanner = match segment.end.map(|end| end.end_byte_offset) {
+                    Some(end_byte_offset) => ReverseJsonlScanner::new_at(file, end_byte_offset)?,
+                    None => ReverseJsonlScanner::new(file)?,
+                };
+                while let Some(outcome) = scanner.scan_next_rollout_line()? {
+                    let ScanOutcome::Parsed(line) = outcome else {
+                        continue;
+                    };
+                    if let RolloutItem::TurnContext(context) = &line.item
+                        && let Some(version) = context.multi_agent_version
+                    {
+                        return Ok(Some(version));
+                    }
+                    // Ancestor metadata does not describe the immediate source's runtime.
+                    if matches!(line.item, RolloutItem::SessionMeta(_)) {
+                        break;
+                    }
+                }
+            }
+            Ok::<_, io::Error>(None)
+        })
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to join fork runtime version scan: {err}"),
+        })?
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to read fork runtime version: {err}"),
+        })?;
+    }
+    match history_base {
+        Some(history_base) => {
+            let lineage = lineage.truncate_at(history_base).await?;
+            scan_model_context_from_lineage(lineage, session_meta).await
+        }
+        None => Ok(vec![RolloutItem::SessionMeta(session_meta)]),
+    }
+}
+
+async fn scan_model_context_from_lineage(
+    lineage: RolloutLineage,
+    session_meta: SessionMetaLine,
+) -> ThreadStoreResult<Vec<RolloutItem>> {
+    let scan = tokio::task::spawn_blocking(move || {
+        scan_model_context_from_lineage_blocking(&lineage, session_meta)
+    })
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to join model context scan: {err}"),
+    })?;
+    match scan {
+        Ok(items) => Ok(items),
+        Err(err) => Err(ThreadStoreError::Internal {
+            message: format!("failed to scan paginated model context lineage: {err}"),
+        }),
+    }
+}
+
+fn scan_model_context_from_lineage_blocking(
+    lineage: &RolloutLineage,
+    session_meta: SessionMetaLine,
+) -> io::Result<Vec<RolloutItem>> {
+    let mut scan = ModelContextScan::default();
+    'segments: for segment in lineage.segments().iter().rev() {
+        let file = codex_rollout::open_rollout_seekable_reader(segment.rollout_path.as_path())?;
+        let mut scanner = match segment.end.map(|end| end.end_byte_offset) {
+            Some(end_byte_offset) => ReverseJsonlScanner::new_at(file, end_byte_offset)?,
+            None => ReverseJsonlScanner::new(file)?,
+        };
+        while let Some(outcome) = scanner.scan_next_rollout_line()? {
+            let ScanOutcome::Parsed(line) = outcome else {
+                continue;
+            };
+            // Each rollout segment contributes only its local delta. Its session metadata is
+            // replaced with the requested thread's canonical SessionMeta after replay.
+            if matches!(&line.item, RolloutItem::SessionMeta(_)) {
+                break;
+            }
+            match scan.push(line.item) {
+                ModelContextScanProgress::Continue => {}
+                ModelContextScanProgress::Complete => break 'segments,
+            }
+        }
+    }
+
+    let canonical_meta = session_meta.clone();
+    let mut items = scan.finish(session_meta);
+    if !matches!(items.first(), Some(RolloutItem::SessionMeta(_))) {
+        items.insert(0, RolloutItem::SessionMeta(canonical_meta));
+    }
+    Ok(items)
+}
diff --git a/codex-rs/thread-store/src/local/model_context_tests.rs b/codex-rs/thread-store/src/local/model_context_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0d7d90a892e6a351e5247ebfdfe94a05291ae372
--- /dev/null
+++ b/codex-rs/thread-store/src/local/model_context_tests.rs
@@ -0,0 +1,895 @@
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::config_types::ReasoningSummary;
+use codex_protocol::items::TurnItem;
+use codex_protocol::items::UserMessageItem;
+use codex_protocol::models::AgentMessageInputContent;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::ItemCompletedEvent;
+use codex_protocol::protocol::MultiAgentVersion;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::TurnCompleteEvent;
+use codex_protocol::protocol::TurnContextItem;
+use codex_protocol::protocol::TurnStartedEvent;
+use codex_protocol::protocol::WorldStateItem;
+use codex_protocol::user_input::UserInput;
+use codex_rollout::CompactedItem;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use uuid::Uuid;
+
+use super::*;
+use crate::ThreadStore;
+use crate::local::test_support::test_config;
+use crate::local::test_support::write_session_file_with_history_mode;
+
+#[tokio::test]
+async fn loads_latest_checkpoint_with_required_turn_metadata() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1001);
+    let thread_id = codex_protocol::ThreadId::from_string(&uuid.to_string()).expect("thread id");
+    write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-00",
+        uuid,
+        [
+            turn_started("turn-1"),
+            user_message("older turn"),
+            completed_user_message("turn-1", "older turn"),
+            turn_context(home.path(), "turn-1"),
+            compacted("older checkpoint", Some(Vec::new())),
+            turn_complete("turn-1"),
+            turn_started("turn-2"),
+            user_message("latest turn"),
+            completed_user_message("turn-2", "latest turn"),
+            turn_context(home.path(), "turn-2"),
+            compacted("latest checkpoint", Some(Vec::new())),
+            turn_complete("turn-2"),
+        ],
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load model context");
+
+    assert!(matches!(
+        context.items.first(),
+        Some(RolloutItem::SessionMeta(_))
+    ));
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::Compacted(compacted) if compacted.message == "latest checkpoint")
+    }));
+    assert!(!context.items.iter().any(|item| {
+        matches!(item, RolloutItem::Compacted(compacted) if compacted.message == "older checkpoint")
+    }));
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::TurnContext(context) if context.turn_id.as_deref() == Some("turn-2"))
+    }));
+}
+
+#[tokio::test]
+async fn loads_recent_context_after_many_empty_wake_turns() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1008);
+    let thread_id = ThreadId::from_string(&uuid.to_string()).expect("thread id");
+    let path = write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-07",
+        uuid,
+        [
+            turn_started("user-turn"),
+            user_message("keep working"),
+            completed_user_message("user-turn", "keep working"),
+            turn_context(home.path(), "user-turn"),
+            turn_complete("user-turn"),
+        ],
+    );
+    let mut expected_suffix = Vec::new();
+    for index in 0..32 {
+        let turn_id = format!("wake-{index}");
+        let mut items = vec![turn_started(&turn_id)];
+        if index % 8 == 0 {
+            expected_suffix.clear();
+            items.extend([
+                compacted(&format!("checkpoint-{index}"), Some(Vec::new())),
+                RolloutItem::WorldState(WorldStateItem::full(Default::default())),
+            ]);
+        }
+        items.extend([
+            turn_context(home.path(), &turn_id),
+            contextual_user_message(),
+            turn_complete(&turn_id),
+        ]);
+        append_items(&path, items.clone());
+        expected_suffix.extend(items);
+    }
+    let session_meta = codex_rollout::read_session_meta_line(&path)
+        .await
+        .expect("read session metadata");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load model context");
+    expected_suffix.insert(0, RolloutItem::SessionMeta(session_meta));
+
+    assert_eq!(
+        serde_json::to_value(context.items).expect("serialize context"),
+        serde_json::to_value(expected_suffix).expect("serialize expected context")
+    );
+}
+
+#[tokio::test]
+async fn empty_wake_requires_surviving_full_world_state_and_matching_context() {
+    enum MissingBaseline {
+        SnapshotBeforeCompaction,
+        PatchOnly,
+        MissingContext,
+        IncompatibleContext,
+    }
+    for baseline in [
+        MissingBaseline::SnapshotBeforeCompaction,
+        MissingBaseline::PatchOnly,
+        MissingBaseline::MissingContext,
+        MissingBaseline::IncompatibleContext,
+    ] {
+        let home = TempDir::new().expect("temp dir");
+        let path = write_paginated_rollout(
+            home.path(),
+            "2025-01-03T13-00-08",
+            Uuid::from_u128(/*v*/ 1009),
+            [
+                turn_started("user-turn"),
+                completed_user_message("user-turn", "keep working"),
+                turn_context(home.path(), "user-turn"),
+                turn_complete("user-turn"),
+                turn_started("wake"),
+            ],
+        );
+        let full = RolloutItem::WorldState(WorldStateItem::full(Default::default()));
+        let checkpoint = compacted("checkpoint", Some(Vec::new()));
+        let context = turn_context(home.path(), "wake");
+        let items = match baseline {
+            MissingBaseline::SnapshotBeforeCompaction => vec![full, checkpoint, context],
+            MissingBaseline::PatchOnly => vec![
+                checkpoint,
+                RolloutItem::WorldState(WorldStateItem::patch(Default::default())),
+                context,
+            ],
+            MissingBaseline::MissingContext => vec![checkpoint, full],
+            MissingBaseline::IncompatibleContext => {
+                vec![
+                    checkpoint,
+                    full,
+                    turn_context(home.path(), "different-turn"),
+                ]
+            }
+        };
+        append_items(&path, items);
+        append_items(&path, [turn_complete("wake")]);
+
+        assert_reverse_scan_matches_full_history(home.path(), &path).await;
+    }
+}
+
+#[tokio::test]
+async fn fork_context_excludes_items_after_frozen_cutoff() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1007);
+    let thread_id = ThreadId::from_string(&uuid.to_string()).expect("thread id");
+    let path = write_ordinaled_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-06",
+        uuid,
+        [turn_started("frozen-turn"), user_message("frozen message")],
+    );
+    let history_base =
+        history_position(path.as_path(), thread_id, /*end_ordinal_exclusive*/ 3);
+    append_items(path.as_path(), [user_message("later message")]);
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let lineage = store
+        .resolve_rollout_lineage(thread_id)
+        .await
+        .expect("resolve source lineage");
+    let session_meta = codex_rollout::read_session_meta_line(path.as_path())
+        .await
+        .expect("read source metadata");
+
+    let context = load_for_fork(lineage, Some(history_base))
+        .await
+        .expect("load frozen fork context");
+
+    let expected = vec![
+        RolloutItem::SessionMeta(session_meta),
+        turn_started("frozen-turn"),
+        user_message("frozen message"),
+    ];
+    assert_eq!(
+        serde_json::to_value(context).expect("serialize fork context"),
+        serde_json::to_value(expected).expect("serialize expected fork context")
+    );
+}
+
+#[tokio::test]
+async fn fork_version_stops_before_older_segments_once_resolved() {
+    for stored_version in [None, Some(MultiAgentVersion::Disabled)] {
+        let home = TempDir::new().expect("temp dir");
+        let root_uuid = Uuid::from_u128(/*v*/ 3001);
+        let root_id = ThreadId::from_string(&root_uuid.to_string()).expect("root id");
+        let root_path = write_ordinaled_paginated_rollout(
+            home.path(),
+            "2025-01-03T13-02-00",
+            root_uuid,
+            [user_message("older history")],
+        );
+        let child_uuid = Uuid::from_u128(/*v*/ 3002);
+        let child_id = ThreadId::from_string(&child_uuid.to_string()).expect("child id");
+        let child_path =
+            write_ordinaled_paginated_rollout(home.path(), "2025-01-03T13-02-01", child_uuid, []);
+        let mut source_meta = codex_rollout::read_session_meta_line(&child_path)
+            .await
+            .expect("read child metadata");
+        source_meta.meta.multi_agent_version = stored_version;
+        source_meta.meta.history_base = Some(history_position(
+            &root_path, root_id, /*end_ordinal_exclusive*/ 2,
+        ));
+        let head = RolloutLine {
+            timestamp: "2025-01-03T13:02:01Z".to_string(),
+            ordinal: Some(0),
+            item: RolloutItem::SessionMeta(source_meta.clone()),
+        };
+        std::fs::write(
+            &child_path,
+            format!(
+                "{}\n",
+                serde_json::to_string(&head).expect("serialize head")
+            ),
+        )
+        .expect("write child metadata");
+        let RolloutItem::TurnContext(mut context) = turn_context(home.path(), "version-turn")
+        else {
+            unreachable!();
+        };
+        context.multi_agent_version = Some(MultiAgentVersion::V2);
+        append_items(
+            &child_path,
+            [
+                RolloutItem::TurnContext(context),
+                turn_context(home.path(), "unset-turn"),
+            ],
+        );
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let lineage = store
+            .resolve_rollout_lineage(child_id)
+            .await
+            .expect("resolve source lineage");
+        // No checkpoint exists. A full model-context read would reach this missing segment.
+        std::fs::remove_file(root_path).expect("remove older segment after resolving lineage");
+
+        let context = load_for_fork(lineage, /*history_base*/ None)
+            .await
+            .expect("resolve version without reading older segments");
+        source_meta.meta.multi_agent_version = stored_version.or(Some(MultiAgentVersion::V2));
+        assert_eq!(
+            serde_json::to_value(context).expect("serialize fork context"),
+            serde_json::to_value(vec![RolloutItem::SessionMeta(source_meta)])
+                .expect("serialize expected context")
+        );
+    }
+}
+
+#[tokio::test]
+async fn fork_version_respects_inherited_segment_cutoffs() {
+    let home = TempDir::new().expect("temp dir");
+    let root_uuid = Uuid::from_u128(/*v*/ 3003);
+    let root_id = ThreadId::from_string(&root_uuid.to_string()).expect("root id");
+    let RolloutItem::TurnContext(mut inherited) = turn_context(home.path(), "inherited") else {
+        unreachable!();
+    };
+    inherited.multi_agent_version = Some(MultiAgentVersion::V2);
+    let mut excluded = inherited.clone();
+    excluded.multi_agent_version = Some(MultiAgentVersion::V1);
+    let root_path = write_ordinaled_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-02-02",
+        root_uuid,
+        [
+            RolloutItem::TurnContext(inherited),
+            RolloutItem::TurnContext(excluded),
+        ],
+    );
+    let child_uuid = Uuid::from_u128(/*v*/ 3004);
+    let child_id = ThreadId::from_string(&child_uuid.to_string()).expect("child id");
+    let child_path = write_ordinaled_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-02-03",
+        child_uuid,
+        [turn_context(home.path(), "unset-child")],
+    );
+    set_history_base(
+        &child_path,
+        history_position(&root_path, root_id, /*end_ordinal_exclusive*/ 2),
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let lineage = store
+        .resolve_rollout_lineage(child_id)
+        .await
+        .expect("resolve source lineage");
+    let mut source_meta = codex_rollout::read_session_meta_line(&child_path)
+        .await
+        .expect("read child metadata");
+
+    let context = load_for_fork(lineage, /*history_base*/ None)
+        .await
+        .expect("recover version from inherited prefix");
+    source_meta.meta.multi_agent_version = Some(MultiAgentVersion::V2);
+    assert_eq!(
+        serde_json::to_value(context).expect("serialize fork context"),
+        serde_json::to_value(vec![RolloutItem::SessionMeta(source_meta)])
+            .expect("serialize expected context")
+    );
+}
+
+#[tokio::test]
+async fn loads_turn_metadata_across_an_older_checkpoint() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1006);
+    let thread_id = codex_protocol::ThreadId::from_string(&uuid.to_string()).expect("thread id");
+    write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-05",
+        uuid,
+        [
+            turn_started("turn-0"),
+            user_message("oldest turn"),
+            completed_user_message("turn-0", "oldest turn"),
+            turn_context(home.path(), "turn-0"),
+            turn_complete("turn-0"),
+            turn_started("turn-1"),
+            user_message("metadata turn"),
+            completed_user_message("turn-1", "metadata turn"),
+            turn_context(home.path(), "turn-1"),
+            compacted("older checkpoint", Some(Vec::new())),
+            turn_complete("turn-1"),
+            turn_started("turn-2"),
+            compacted("latest checkpoint", Some(Vec::new())),
+            turn_complete("turn-2"),
+        ],
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load model context");
+
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::Compacted(compacted) if compacted.message == "latest checkpoint")
+    }));
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::TurnContext(context) if context.turn_id.as_deref() == Some("turn-1"))
+    }));
+    assert!(!context.items.iter().any(|item| {
+        matches!(item, RolloutItem::TurnContext(context) if context.turn_id.as_deref() == Some("turn-0"))
+    }));
+}
+
+#[tokio::test]
+async fn returns_scanned_full_history_for_unsupported_compaction() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1002);
+    let path = write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-01",
+        uuid,
+        [
+            turn_started("turn-1"),
+            user_message("turn"),
+            completed_user_message("turn-1", "turn"),
+            turn_context(home.path(), "turn-1"),
+            compacted("usable checkpoint", Some(Vec::new())),
+            compacted("legacy checkpoint", /*replacement_history*/ None),
+            turn_complete("turn-1"),
+        ],
+    );
+
+    assert_reverse_scan_matches_full_history(home.path(), path.as_path()).await;
+}
+
+#[tokio::test]
+async fn returns_scanned_full_history_at_bof_without_checkpoint() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1003);
+    let path = write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-02",
+        uuid,
+        [
+            turn_started("turn-1"),
+            user_message("turn"),
+            completed_user_message("turn-1", "turn"),
+            turn_context(home.path(), "turn-1"),
+            turn_complete("turn-1"),
+        ],
+    );
+
+    assert_reverse_scan_matches_full_history(home.path(), path.as_path()).await;
+}
+
+#[tokio::test]
+async fn uses_agent_message_turn_context_without_scanning_older_turn() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1004);
+    let thread_id = codex_protocol::ThreadId::from_string(&uuid.to_string()).expect("thread id");
+    write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-03",
+        uuid,
+        [
+            turn_started("turn-1"),
+            user_message("older turn"),
+            completed_user_message("turn-1", "older turn"),
+            turn_context(home.path(), "turn-1"),
+            compacted("checkpoint", Some(Vec::new())),
+            turn_complete("turn-1"),
+            turn_started("turn-2"),
+            turn_context(home.path(), "turn-2"),
+            agent_message("child done"),
+            turn_complete("turn-2"),
+        ],
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load model context");
+
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::TurnContext(context) if context.turn_id.as_deref() == Some("turn-2"))
+    }));
+    assert!(!context.items.iter().any(|item| {
+        matches!(item, RolloutItem::TurnContext(context) if context.turn_id.as_deref() == Some("turn-1"))
+    }));
+}
+
+#[tokio::test]
+async fn ignores_contextual_user_messages_when_selecting_turn_context() {
+    let home = TempDir::new().expect("temp dir");
+    let uuid = Uuid::from_u128(/*v*/ 1005);
+    let thread_id = codex_protocol::ThreadId::from_string(&uuid.to_string()).expect("thread id");
+    write_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-00-04",
+        uuid,
+        [
+            turn_started("turn-1"),
+            user_message("real user turn"),
+            completed_user_message("turn-1", "real user turn"),
+            turn_context(home.path(), "turn-1"),
+            compacted("checkpoint", Some(Vec::new())),
+            turn_complete("turn-1"),
+            turn_started("turn-2"),
+            contextual_user_message(),
+            turn_context(home.path(), "turn-2"),
+            turn_complete("turn-2"),
+        ],
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load model context");
+
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::TurnContext(context) if context.turn_id.as_deref() == Some("turn-1"))
+    }));
+}
+
+#[tokio::test]
+async fn replays_nested_archived_lineage_from_frozen_prefix() {
+    let home = TempDir::new().expect("temp dir");
+    let root_uuid = Uuid::from_u128(/*v*/ 2001);
+    let root_id = ThreadId::from_string(&root_uuid.to_string()).expect("root id");
+    let root_path = write_ordinaled_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-01-00",
+        root_uuid,
+        [
+            user_message("root before checkpoint"),
+            compacted("root checkpoint", Some(Vec::new())),
+            turn_started("root-excluded"),
+            user_message("root after cutoff"),
+        ],
+    );
+    let archived_root = home
+        .path()
+        .join("archived_sessions")
+        .join(root_path.file_name().expect("root filename"));
+    std::fs::create_dir_all(archived_root.parent().expect("archive parent"))
+        .expect("create archive directory");
+    std::fs::rename(root_path, &archived_root).expect("archive root rollout");
+
+    let middle_uuid = Uuid::from_u128(/*v*/ 2002);
+    let middle_id = ThreadId::from_string(&middle_uuid.to_string()).expect("middle id");
+    let middle_path = write_ordinaled_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-01-01",
+        middle_uuid,
+        [
+            turn_started("middle-turn"),
+            user_message("middle inherited"),
+            completed_user_message("middle-turn", "middle inherited"),
+            turn_context(home.path(), "middle-turn"),
+            turn_complete("middle-turn"),
+        ],
+    );
+    set_history_base(
+        middle_path.as_path(),
+        history_position(
+            archived_root.as_path(),
+            root_id,
+            /*end_ordinal_exclusive*/ 3,
+        ),
+    );
+
+    let child_uuid = Uuid::from_u128(/*v*/ 2003);
+    let child_id = ThreadId::from_string(&child_uuid.to_string()).expect("child id");
+    let child_path = write_ordinaled_paginated_rollout(
+        home.path(),
+        "2025-01-03T13-01-02",
+        child_uuid,
+        [
+            turn_started("child-turn"),
+            user_message("child local"),
+            completed_user_message("child-turn", "child local"),
+            turn_context(home.path(), "child-turn"),
+            turn_complete("child-turn"),
+        ],
+    );
+    set_history_base(
+        child_path.as_path(),
+        history_position(
+            middle_path.as_path(),
+            middle_id,
+            /*end_ordinal_exclusive*/ 6,
+        ),
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id: child_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load lineage model context");
+
+    assert!(matches!(
+        context.items.first(),
+        Some(RolloutItem::SessionMeta(meta)) if meta.meta.id == child_id
+    ));
+    let child_meta = codex_rollout::read_session_meta_line(child_path.as_path())
+        .await
+        .expect("read child metadata");
+    let expected = vec![
+        RolloutItem::SessionMeta(child_meta),
+        compacted("root checkpoint", Some(Vec::new())),
+        turn_started("middle-turn"),
+        user_message("middle inherited"),
+        completed_user_message("middle-turn", "middle inherited"),
+        turn_context(home.path(), "middle-turn"),
+        turn_complete("middle-turn"),
+        turn_started("child-turn"),
+        user_message("child local"),
+        completed_user_message("child-turn", "child local"),
+        turn_context(home.path(), "child-turn"),
+        turn_complete("child-turn"),
+    ];
+    assert_eq!(
+        serde_json::to_value(&context.items).expect("serialize context"),
+        serde_json::to_value(&expected).expect("serialize expected context")
+    );
+    // The same frozen lineage must replay from compressed files, without materializing or
+    // accidentally including the archived root's records after the inherited cutoff.
+    for path in [&archived_root, &middle_path, &child_path] {
+        let input = std::fs::File::open(path).expect("open rollout");
+        let output = std::fs::File::create(path.with_extension("jsonl.zst"))
+            .expect("create compressed rollout");
+        zstd::stream::copy_encode(input, output, /*level*/ 3).expect("compress rollout");
+        std::fs::remove_file(path).expect("remove plain rollout");
+    }
+    let compressed_context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id: child_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load compressed lineage model context");
+    assert_eq!(
+        serde_json::to_value(compressed_context.items).expect("serialize compressed context"),
+        serde_json::to_value(expected).expect("serialize expected context")
+    );
+    assert!(
+        [archived_root, middle_path, child_path]
+            .iter()
+            .all(|path| !path.exists())
+    );
+}
+
+fn write_paginated_rollout<const N: usize>(
+    home: &Path,
+    timestamp: &str,
+    uuid: Uuid,
+    items: [RolloutItem; N],
+) -> PathBuf {
+    let path =
+        write_session_file_with_history_mode(home, timestamp, uuid, ThreadHistoryMode::Paginated)
+            .expect("write session file");
+    append_items(path.as_path(), items);
+    path
+}
+
+fn write_ordinaled_paginated_rollout<const N: usize>(
+    home: &Path,
+    timestamp: &str,
+    uuid: Uuid,
+    items: [RolloutItem; N],
+) -> PathBuf {
+    let path =
+        write_session_file_with_history_mode(home, timestamp, uuid, ThreadHistoryMode::Paginated)
+            .expect("write session file");
+    let mut file = OpenOptions::new()
+        .append(true)
+        .open(path.as_path())
+        .expect("open session file");
+    for (index, item) in items.into_iter().enumerate() {
+        let line = RolloutLine {
+            timestamp: "2025-01-03T13:00:01Z".to_string(),
+            ordinal: Some(u64::try_from(index).expect("fixture index fits u64") + 1),
+            item,
+        };
+        writeln!(
+            file,
+            "{}",
+            serde_json::to_string(&line).expect("serialize line")
+        )
+        .expect("append rollout line");
+    }
+    path
+}
+
+fn set_history_base(path: &Path, history_base: HistoryPosition) {
+    let contents = std::fs::read_to_string(path).expect("read rollout");
+    let mut lines = contents.lines();
+    let mut head: serde_json::Value =
+        serde_json::from_str(lines.next().expect("session meta line")).expect("parse head");
+    head["payload"]["history_base"] =
+        serde_json::to_value(history_base).expect("serialize history base");
+    let mut updated = serde_json::to_string(&head).expect("serialize head");
+    for line in lines {
+        updated.push('\n');
+        updated.push_str(line);
+    }
+    updated.push('\n');
+    std::fs::write(path, updated).expect("write history base");
+}
+
+fn history_position(
+    path: &Path,
+    thread_id: ThreadId,
+    end_ordinal_exclusive: u64,
+) -> HistoryPosition {
+    HistoryPosition {
+        thread_id,
+        end_ordinal_exclusive,
+        end_byte_offset: rollout_end_byte_offset(path, end_ordinal_exclusive),
+    }
+}
+
+fn rollout_end_byte_offset(path: &Path, end_ordinal_exclusive: u64) -> u64 {
+    let contents = std::fs::read(path).expect("read rollout");
+    let mut byte_offset = 0_u64;
+    for line in contents.split_inclusive(|byte| *byte == b'\n') {
+        let parsed = codex_rollout::parse_rollout_line_bytes(line)
+            .expect("parse rollout line for byte offset");
+        if parsed.ordinal == Some(end_ordinal_exclusive) {
+            return byte_offset;
+        }
+        byte_offset += u64::try_from(line.len()).expect("line length fits u64");
+    }
+    byte_offset
+}
+
+async fn assert_reverse_scan_matches_full_history(home: &Path, path: &Path) {
+    let session_meta = codex_rollout::read_session_meta_line(path)
+        .await
+        .expect("read session metadata");
+    let store = LocalThreadStore::new(test_config(home), /*state_db*/ None);
+    let items = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id: session_meta.meta.id,
+            include_archived: false,
+        })
+        .await
+        .expect("scan model context")
+        .items;
+    let full_items = read_thread::load_history_items(path)
+        .await
+        .expect("load full history");
+
+    assert_eq!(
+        serde_json::to_value(items).expect("serialize scanned items"),
+        serde_json::to_value(full_items).expect("serialize full items")
+    );
+}
+
+fn append_items(path: &Path, items: impl IntoIterator<Item = RolloutItem>) {
+    let mut file = OpenOptions::new()
+        .append(true)
+        .open(path)
+        .expect("open session file");
+    for item in items {
+        let line = RolloutLine {
+            timestamp: "2025-01-03T13:00:01Z".to_string(),
+            ordinal: None,
+            item,
+        };
+        writeln!(
+            file,
+            "{}",
+            serde_json::to_string(&line).expect("serialize line")
+        )
+        .expect("append rollout line");
+    }
+}
+
+fn turn_started(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnStarted(TurnStartedEvent {
+        turn_id: turn_id.to_string(),
+        root_turn_id: None,
+        trace_id: None,
+        started_at: None,
+        model_context_window: Some(128_000),
+        collaboration_mode_kind: Default::default(),
+    }))
+}
+
+fn turn_complete(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnComplete(TurnCompleteEvent {
+        turn_id: turn_id.to_string(),
+        last_agent_message: None,
+        error: None,
+        started_at: None,
+        completed_at: None,
+        duration_ms: None,
+        time_to_first_token_ms: None,
+    }))
+}
+
+fn user_message(message: &str) -> RolloutItem {
+    RolloutItem::ResponseItem(
+        ResponseItem::Message {
+            id: None,
+            role: "user".to_string(),
+            content: vec![ContentItem::InputText {
+                text: message.to_string(),
+            }],
+            phase: None,
+            internal_chat_message_metadata_passthrough: None,
+        }
+        .into(),
+    )
+}
+
+fn contextual_user_message() -> RolloutItem {
+    user_message("<environment_context>context only</environment_context>")
+}
+
+fn completed_user_message(turn_id: &str, message: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+        thread_id: codex_protocol::ThreadId::from_string("00000000-0000-0000-0000-000000000000")
+            .expect("fixture thread id"),
+        turn_id: turn_id.to_string(),
+        item: TurnItem::UserMessage(UserMessageItem {
+            id: format!("user-{turn_id}"),
+            client_id: None,
+            content: vec![UserInput::Text {
+                text: message.to_string(),
+                text_elements: Vec::new(),
+            }],
+        }),
+        started_at_ms: Some(0),
+        completed_at_ms: 0,
+    }))
+}
+
+fn agent_message(message: &str) -> RolloutItem {
+    RolloutItem::ResponseItem(
+        ResponseItem::AgentMessage {
+            id: None,
+            author: "worker".to_string(),
+            recipient: "root".to_string(),
+            content: vec![AgentMessageInputContent::InputText {
+                text: message.to_string(),
+            }],
+            internal_chat_message_metadata_passthrough: None,
+        }
+        .into(),
+    )
+}
+
+fn turn_context(root: &Path, turn_id: &str) -> RolloutItem {
+    RolloutItem::TurnContext(TurnContextItem {
+        turn_id: Some(turn_id.to_string()),
+        root_turn_id: None,
+        disabled_plugin_ids: None,
+        cwd: serde_json::from_value(serde_json::json!(root)).expect("absolute cwd"),
+        workspace_roots: None,
+        current_date: None,
+        timezone: None,
+        approval_policy: AskForApproval::Never,
+        approvals_reviewer: None,
+        sandbox_policy: SandboxPolicy::new_read_only_policy(),
+        permission_profile: None,
+        active_permission_profile: None,
+        network: None,
+        file_system_sandbox_policy: None,
+        model: "test-model".to_string(),
+        comp_hash: None,
+        personality: None,
+        collaboration_mode: None,
+        multi_agent_version: None,
+        multi_agent_mode: None,
+        realtime_active: None,
+        cyber_access_program: None,
+        effort: None,
+        summary: ReasoningSummary::Auto,
+    })
+}
+
+fn compacted(message: &str, replacement_history: Option<Vec<ResponseItem>>) -> RolloutItem {
+    RolloutItem::Compacted(CompactedItem {
+        message: message.to_string(),
+        replacement_history: replacement_history
+            .map(|items| items.into_iter().map(Into::into).collect()),
+        retained_context: None,
+        guardian_history: None,
+        mcp_resource_origins: None,
+        window_number: Some(1),
+        first_window_id: None,
+        previous_window_id: None,
+        window_id: None,
+        compaction_response_id: None,
+        latest_token_usage_record: None,
+    })
+}
diff --git a/codex-rs/thread-store/src/local/move_thread_to_section.rs b/codex-rs/thread-store/src/local/move_thread_to_section.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ef6d641d536b1899fa1c0af7e91702232b60b71f
--- /dev/null
+++ b/codex-rs/thread-store/src/local/move_thread_to_section.rs
@@ -0,0 +1,58 @@
+use super::LocalThreadStore;
+use crate::MoveThreadToSectionParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+pub(super) async fn move_thread_to_section(
+    store: &LocalThreadStore,
+    params: MoveThreadToSectionParams,
+) -> ThreadStoreResult<()> {
+    if params
+        .section
+        .as_deref()
+        .is_some_and(|section| section.trim().is_empty())
+    {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "section must not be empty".to_owned(),
+        });
+    }
+    if params.section.is_none() && params.before_thread_id.is_some() {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "before thread cannot be specified without a section".to_owned(),
+        });
+    }
+
+    let Some(state_db) = store.state_db().await else {
+        return Err(ThreadStoreError::Unsupported {
+            operation: "thread/section/move",
+        });
+    };
+
+    let updated = state_db
+        .move_thread_to_section(
+            params.thread_id,
+            params.section.as_deref(),
+            params.before_thread_id,
+        )
+        .await
+        .map_err(|err| {
+            let message = err.to_string();
+            if message.starts_with("before thread ")
+                || message.starts_with("thread ")
+                || message.starts_with("section ")
+            {
+                ThreadStoreError::InvalidRequest { message }
+            } else {
+                ThreadStoreError::Internal {
+                    message: format!("failed to move thread {}: {message}", params.thread_id),
+                }
+            }
+        })?;
+    if !updated {
+        return Err(ThreadStoreError::ThreadNotFound {
+            thread_id: params.thread_id,
+        });
+    }
+
+    Ok(())
+}
diff --git a/codex-rs/thread-store/src/local/paginated_fork.rs b/codex-rs/thread-store/src/local/paginated_fork.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0b14091267769ac55b5751e20ddb6798196f2431
--- /dev/null
+++ b/codex-rs/thread-store/src/local/paginated_fork.rs
@@ -0,0 +1,191 @@
+use codex_protocol::protocol::HistoryPosition;
+use std::sync::Arc;
+
+use super::LocalThreadStore;
+use super::live_writer;
+use super::model_context;
+use super::thread_history::find_source_turn;
+use super::thread_history::find_visible_turn;
+use crate::ForkBoundary;
+use crate::PrepareForkParams;
+use crate::PreparedFork;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+pub(super) async fn prepare(
+    store: &LocalThreadStore,
+    params: PrepareForkParams,
+) -> ThreadStoreResult<PreparedFork> {
+    let PrepareForkParams {
+        thread_id,
+        boundary,
+    } = params;
+    let source_reservation = store.live_writer_locks.reserve_lifecycle(thread_id).await;
+    // Keep the source reserved until persistence and lineage materialization finish, even if the
+    // caller cancels fork preparation.
+    let lineage_store = store.clone();
+    let (lineage, source_reservation) = tokio::spawn(async move {
+        match live_writer::persist_thread(&lineage_store, thread_id).await {
+            Ok(()) | Err(ThreadStoreError::ThreadNotFound { .. }) => {}
+            Err(err) => return Err(err),
+        }
+        let lineage = lineage_store
+            .resolve_rollout_lineage_for_reference(thread_id)
+            .await?;
+        Ok::<_, ThreadStoreError>((lineage, source_reservation))
+    })
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to resolve fork lineage: {err}"),
+    })??;
+    let source_segment = lineage
+        .segments()
+        .last()
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: "fork lineage has no source segment".to_string(),
+        })?;
+    if store.state_db.is_none() {
+        return Err(ThreadStoreError::Unsupported {
+            operation: "prepare_fork",
+        });
+    }
+    if !matches!(boundary, ForkBoundary::Latest) {
+        for segment in lineage
+            .segments()
+            .iter()
+            .take(lineage.segments().len().saturating_sub(1))
+        {
+            let _ancestor_writer_guard = store.live_writer_locks.lock(segment.rollout_id()).await;
+            super::thread_history_materialization::materialize_to_sqlite(
+                store,
+                segment.rollout_id(),
+                segment.rollout_path.as_path(),
+            )
+            .await?;
+        }
+    }
+    let source_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    super::thread_history_materialization::materialize_to_sqlite(
+        store,
+        source_segment.rollout_id(),
+        source_segment.rollout_path.as_path(),
+    )
+    .await?;
+
+    let history_base = history_base_at_boundary(store, thread_id, boundary, &lineage).await?;
+    drop(source_writer_guard);
+    let model_context = Arc::new(model_context::load_for_fork(lineage, history_base).await?);
+
+    Ok(PreparedFork::new(
+        thread_id,
+        history_base,
+        model_context,
+        source_reservation,
+    ))
+}
+
+pub(super) async fn history_base_at_boundary(
+    store: &LocalThreadStore,
+    thread_id: codex_protocol::ThreadId,
+    boundary: ForkBoundary,
+    lineage: &super::rollout_lineage::RolloutLineage,
+) -> ThreadStoreResult<Option<HistoryPosition>> {
+    let source_segment = lineage
+        .segments()
+        .last()
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: "fork lineage has no source segment".to_string(),
+        })?;
+    let latest_projection_state =
+        super::thread_history::projection_state(store, source_segment.rollout_id())
+            .await?
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: format!("missing projection state for paginated thread {thread_id}"),
+            })?;
+    let latest_position = HistoryPosition {
+        thread_id: source_segment.rollout_id(),
+        end_ordinal_exclusive: latest_projection_state.next_ordinal,
+        end_byte_offset: latest_projection_state.next_byte_offset,
+    };
+    let pool = store.thread_history_db().await?;
+    let position = match boundary {
+        ForkBoundary::Latest => latest_position,
+        ForkBoundary::ThroughTurn(turn_id) => {
+            let row = find_visible_turn(pool, lineage, turn_id.as_str()).await?;
+            if row.status == "inProgress" {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: format!("lastTurnId '{turn_id}' identifies an in-progress turn"),
+                });
+            }
+            let rollout_end_ordinal = row
+                .rollout_end_ordinal
+                .ok_or_else(|| missing_turn_position(turn_id.as_str()))?;
+            let rollout_end_byte_offset = row
+                .rollout_end_byte_offset
+                .ok_or_else(|| missing_turn_position(turn_id.as_str()))?;
+            HistoryPosition {
+                thread_id: row.rollout_id,
+                end_ordinal_exclusive: u64::try_from(rollout_end_ordinal)
+                    .map_err(|_| invalid_turn_position(turn_id.as_str()))?
+                    .checked_add(1)
+                    .ok_or_else(|| invalid_turn_position(turn_id.as_str()))?,
+                end_byte_offset: u64::try_from(rollout_end_byte_offset)
+                    .map_err(|_| invalid_turn_position(turn_id.as_str()))?,
+            }
+        }
+        ForkBoundary::BeforeTurn(turn_id) => {
+            let row = find_source_turn(pool, lineage, turn_id.as_str()).await?;
+            if row.rollout_end_ordinal == Some(row.rollout_ordinal) {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: format!("turn {turn_id} does not have a persisted start boundary"),
+                });
+            }
+            let rollout_byte_offset = row
+                .rollout_byte_offset
+                .ok_or_else(|| missing_turn_position(turn_id.as_str()))?;
+            HistoryPosition {
+                thread_id: row.rollout_id,
+                end_ordinal_exclusive: u64::try_from(row.rollout_ordinal)
+                    .map_err(|_| invalid_turn_position(turn_id.as_str()))?,
+                end_byte_offset: u64::try_from(rollout_byte_offset)
+                    .map_err(|_| invalid_turn_position(turn_id.as_str()))?,
+            }
+        }
+    };
+    let segment_index = lineage
+        .segments()
+        .iter()
+        .position(|segment| segment.rollout_id() == position.thread_id)
+        .ok_or_else(|| ThreadStoreError::Internal {
+            message: "fork position is outside the source lineage".to_string(),
+        })?;
+    if lineage.segments()[segment_index].end.is_some_and(|end| {
+        position.end_ordinal_exclusive > end.end_ordinal_exclusive
+            || position.end_byte_offset > end.end_byte_offset
+    }) {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "fork boundary exceeds inherited source history".to_string(),
+        });
+    }
+    let history_base =
+        if position.end_ordinal_exclusive == lineage.segments()[segment_index].start_ordinal() {
+            segment_index
+                .checked_sub(1)
+                .and_then(|index| lineage.segments()[index].end)
+        } else {
+            Some(position)
+        };
+    Ok(history_base)
+}
+
+fn missing_turn_position(turn_id: &str) -> ThreadStoreError {
+    ThreadStoreError::InvalidRequest {
+        message: format!("turn {turn_id} does not have persisted rollout positions"),
+    }
+}
+
+fn invalid_turn_position(turn_id: &str) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: format!("invalid rollout position for turn {turn_id}"),
+    }
+}
diff --git a/codex-rs/thread-store/src/local/pending_thread_metadata.rs b/codex-rs/thread-store/src/local/pending_thread_metadata.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5eb28660d423e416aabbf5163d8f6cf238cd2cdc
--- /dev/null
+++ b/codex-rs/thread-store/src/local/pending_thread_metadata.rs
@@ -0,0 +1,58 @@
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::sync::Arc;
+
+use codex_protocol::ThreadId;
+use tokio::sync::Mutex;
+use tokio::sync::OwnedMutexGuard;
+
+use crate::ThreadMetadataPatch;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+type PendingThreadMetadataEntry = Arc<Mutex<Option<ThreadMetadataPatch>>>;
+
+/// In-memory metadata staged before a reserved thread starts.
+///
+/// The registry lock is held only while looking up or removing an entry. Never await an entry
+/// lock while holding the registry lock. Callers may hold an entry lock before the live-writer
+/// lock.
+#[derive(Clone, Default)]
+pub(super) struct PendingThreadMetadataRegistry {
+    entries: Arc<Mutex<HashMap<ThreadId, PendingThreadMetadataEntry>>>,
+}
+
+pub(super) type LockedPendingThreadMetadata = OwnedMutexGuard<Option<ThreadMetadataPatch>>;
+
+impl PendingThreadMetadataRegistry {
+    pub(super) async fn stage(
+        &self,
+        thread_id: ThreadId,
+        patch: ThreadMetadataPatch,
+    ) -> ThreadStoreResult<()> {
+        if patch.is_empty() {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: "pending thread metadata cannot be empty".to_string(),
+            });
+        }
+        let mut entries = self.entries.lock().await;
+        match entries.entry(thread_id) {
+            Entry::Vacant(entry) => {
+                entry.insert(Arc::new(Mutex::new(Some(patch))));
+                Ok(())
+            }
+            Entry::Occupied(_) => Err(ThreadStoreError::InvalidRequest {
+                message: format!("pending thread metadata already exists: {thread_id}"),
+            }),
+        }
+    }
+
+    pub(super) async fn remove(&self, thread_id: ThreadId) {
+        self.entries.lock().await.remove(&thread_id);
+    }
+
+    pub(super) async fn lock(&self, thread_id: ThreadId) -> Option<LockedPendingThreadMetadata> {
+        let entry = self.entries.lock().await.get(&thread_id).cloned()?;
+        Some(entry.lock_owned().await)
+    }
+}
diff --git a/codex-rs/thread-store/src/local/pending_thread_metadata_tests.rs b/codex-rs/thread-store/src/local/pending_thread_metadata_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3e31298016184d7f018d79db60a9e3b9322d35d5
--- /dev/null
+++ b/codex-rs/thread-store/src/local/pending_thread_metadata_tests.rs
@@ -0,0 +1,298 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use codex_protocol::ThreadId;
+use codex_protocol::models::BaseInstructions;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutRecorder;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::*;
+use crate::CreateThreadParams;
+use crate::LiveThread;
+use crate::ThreadPersistenceMetadata;
+use crate::UpdateThreadMetadataParams;
+use crate::local::test_support::test_config;
+
+#[tokio::test]
+async fn pending_thread_metadata_is_consumed_by_first_metadata_update() {
+    let (_home, store, runtime) = store_with_runtime().await;
+    let thread_id = ThreadId::new();
+    let pending_patch = staged_model_patch();
+
+    store
+        .stage_pending_thread_metadata(thread_id, pending_patch.clone())
+        .await
+        .expect("stage pending metadata");
+    let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+        .await
+        .expect("create live thread");
+    live_thread
+        .append_items(&[user_message_item("materialize pending metadata")])
+        .await
+        .expect("append observed item");
+
+    let metadata = runtime
+        .get_thread(thread_id)
+        .await
+        .expect("sqlite metadata read")
+        .expect("sqlite metadata");
+    assert_eq!(metadata.model.as_deref(), Some("staged-model"));
+    assert_eq!(metadata.model_provider, "test-provider");
+    assert_eq!(metadata.source, "exec");
+    assert_eq!(
+        metadata.cwd.canonicalize().expect("canonical metadata cwd"),
+        std::env::current_dir()
+            .expect("current directory")
+            .canonicalize()
+            .expect("canonical current directory")
+    );
+    assert_pending_metadata_consumed(&store, thread_id).await;
+}
+
+#[tokio::test]
+async fn pending_rollout_compatible_metadata_does_not_deadlock() {
+    let (_home, store, runtime) = store_with_runtime().await;
+    let thread_id = ThreadId::new();
+
+    store
+        .stage_pending_thread_metadata(
+            thread_id,
+            ThreadMetadataPatch {
+                name: Some(Some("staged-name".to_string())),
+                model_provider: Some("staged-provider".to_string()),
+                ..Default::default()
+            },
+        )
+        .await
+        .expect("stage pending metadata");
+    let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+        .await
+        .expect("create live thread");
+    tokio::time::timeout(
+        Duration::from_secs(5),
+        live_thread.update_metadata(
+            ThreadMetadataPatch {
+                model: Some("updated-model".to_string()),
+                ..Default::default()
+            },
+            /*include_archived*/ false,
+        ),
+    )
+    .await
+    .expect("pending metadata update should not deadlock")
+    .expect("update metadata before rollout materialization");
+
+    let metadata = runtime
+        .get_thread(thread_id)
+        .await
+        .expect("sqlite metadata read")
+        .expect("sqlite metadata");
+    assert_eq!(metadata.title, "staged-name");
+    assert_eq!(metadata.model_provider, "test-provider");
+    assert_eq!(metadata.model.as_deref(), Some("updated-model"));
+    assert_pending_metadata_consumed(&store, thread_id).await;
+}
+
+#[tokio::test]
+async fn pending_rollout_compatible_metadata_is_written_with_observed_update() {
+    let (_home, store, _runtime) = store_with_runtime().await;
+    let thread_id = ThreadId::new();
+
+    store
+        .stage_pending_thread_metadata(
+            thread_id,
+            ThreadMetadataPatch {
+                memory_mode: Some(ThreadMemoryMode::Disabled),
+                ..Default::default()
+            },
+        )
+        .await
+        .expect("stage pending metadata");
+    let _live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+        .await
+        .expect("create live thread");
+    store
+        .update_thread_metadata(UpdateThreadMetadataParams {
+            thread_id,
+            patch: ThreadMetadataPatch {
+                model: Some("observed-model".to_string()),
+                ..Default::default()
+            },
+            include_archived: false,
+        })
+        .await
+        .expect("apply observed metadata");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let (items, _, _) = RolloutRecorder::load_rollout_items(rollout_path.as_path())
+        .await
+        .expect("load durable rollout");
+    let memory_mode = items.iter().rev().find_map(|item| match item {
+        RolloutItem::SessionMeta(session_meta) => session_meta.meta.memory_mode.as_deref(),
+        _ => None,
+    });
+
+    assert_eq!(memory_mode, Some("disabled"));
+    assert_pending_metadata_consumed(&store, thread_id).await;
+}
+
+#[tokio::test]
+async fn idle_shutdown_clears_pending_thread_metadata_without_materializing() {
+    let (_home, store, runtime) = store_with_runtime().await;
+    let thread_id = ThreadId::new();
+
+    store
+        .stage_pending_thread_metadata(thread_id, staged_model_patch())
+        .await
+        .expect("stage pending metadata");
+    let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+        .await
+        .expect("create live thread");
+    live_thread.shutdown().await.expect("shutdown idle thread");
+
+    assert_eq!(
+        runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read"),
+        None
+    );
+    assert_pending_metadata_consumed(&store, thread_id).await;
+}
+
+#[tokio::test]
+async fn discarding_live_thread_clears_pending_metadata() {
+    let (_home, store, _runtime) = store_with_runtime().await;
+    let thread_id = ThreadId::new();
+
+    store
+        .stage_pending_thread_metadata(thread_id, staged_model_patch())
+        .await
+        .expect("stage pending metadata");
+    let live_thread = LiveThread::create(store.clone(), create_thread_params(thread_id))
+        .await
+        .expect("create live thread");
+    live_thread.discard().await.expect("discard live thread");
+
+    assert_pending_metadata_consumed(&store, thread_id).await;
+}
+
+#[tokio::test]
+async fn pending_thread_metadata_requires_state_db() {
+    let home = TempDir::new().expect("temp dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let err = store
+        .stage_pending_thread_metadata(ThreadId::new(), staged_model_patch())
+        .await
+        .expect_err("reject pending metadata without state db");
+    assert!(matches!(
+        err,
+        ThreadStoreError::InvalidRequest { message }
+            if message == "pending thread metadata requires a state db"
+    ));
+}
+
+#[tokio::test]
+async fn pending_thread_metadata_rejects_rollout_path() {
+    let (home, store, _runtime) = store_with_runtime().await;
+
+    let err = store
+        .stage_pending_thread_metadata(
+            ThreadId::new(),
+            ThreadMetadataPatch {
+                rollout_path: Some(home.path().join("wrong-rollout.jsonl")),
+                ..Default::default()
+            },
+        )
+        .await
+        .expect_err("reject host-owned rollout path");
+    assert!(matches!(
+        err,
+        ThreadStoreError::InvalidRequest { message }
+            if message == "pending thread metadata cannot set rollout_path"
+    ));
+}
+
+async fn store_with_runtime() -> (
+    TempDir,
+    Arc<LocalThreadStore>,
+    Arc<codex_state::StateRuntime>,
+) {
+    let home = TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state db should initialize");
+    let store = Arc::new(LocalThreadStore::new(config, Some(runtime.clone())));
+    (home, store, runtime)
+}
+
+async fn assert_pending_metadata_consumed(store: &LocalThreadStore, thread_id: ThreadId) {
+    store
+        .stage_pending_thread_metadata(thread_id, staged_model_patch())
+        .await
+        .expect("restage metadata after consumption");
+    store
+        .remove_pending_thread_metadata(thread_id)
+        .await
+        .expect("remove restaged metadata");
+}
+
+fn staged_model_patch() -> ThreadMetadataPatch {
+    ThreadMetadataPatch {
+        model: Some("staged-model".to_string()),
+        ..Default::default()
+    }
+}
+
+fn create_thread_params(thread_id: ThreadId) -> CreateThreadParams {
+    CreateThreadParams {
+        session_id: thread_id.into(),
+        thread_id,
+        extra_config: None,
+        forked_from_id: None,
+        parent_thread_id: None,
+        source: SessionSource::Exec,
+        thread_source: None,
+        originator: "test_originator".to_string(),
+        base_instructions: BaseInstructions::default(),
+        dynamic_tools: Vec::new(),
+        selected_capability_roots: Vec::new(),
+        multi_agent_version: None,
+        history_mode: ThreadHistoryMode::Legacy,
+        history_base: None,
+        subagent_history_start_ordinal: None,
+        initial_window_id: uuid::Uuid::now_v7().to_string(),
+        runtime_workspace_roots: None,
+        metadata: ThreadPersistenceMetadata {
+            cwd: Some(std::env::current_dir().expect("cwd")),
+            model_provider: "test-provider".to_string(),
+            memory_mode: ThreadMemoryMode::Enabled,
+        },
+    }
+}
+
+fn user_message_item(message: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::UserMessage(UserMessageEvent {
+        client_id: None,
+        message: message.to_string(),
+        images: None,
+        local_images: Vec::new(),
+        text_elements: Vec::new(),
+        ..Default::default()
+    }))
+}
diff --git a/codex-rs/thread-store/src/local/projects.rs b/codex-rs/thread-store/src/local/projects.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c2fda89311489d247658f34bbd1ec050abd8e8ec
--- /dev/null
+++ b/codex-rs/thread-store/src/local/projects.rs
@@ -0,0 +1,192 @@
+use super::LocalThreadStore;
+use crate::CreateProjectParams;
+use crate::CreatedProject;
+use crate::DeletedProject;
+use crate::ListProjectsParams;
+use crate::MoveProjectParams;
+use crate::ProjectMoveOutcome;
+use crate::SortDirection;
+use crate::StoredProject;
+use crate::StoredProjectRoot;
+use crate::StoredProjectsPage;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::UpdateProjectParams;
+use crate::UpdatedProject;
+
+pub(super) async fn list_projects(
+    store: &LocalThreadStore,
+    params: ListProjectsParams,
+) -> ThreadStoreResult<StoredProjectsPage> {
+    let state = state(store)?;
+    let has_cursor = params.cursor.is_some();
+    let page = state
+        .list_projects(
+            params.cursor.as_deref(),
+            params.limit,
+            params.sort_key,
+            match params.sort_direction {
+                SortDirection::Asc => codex_state::SortDirection::Asc,
+                SortDirection::Desc => codex_state::SortDirection::Desc,
+            },
+        )
+        .await
+        .map_err(|error| {
+            if has_cursor && error.to_string().starts_with("invalid project cursor:") {
+                ThreadStoreError::InvalidRequest {
+                    message: error.to_string(),
+                }
+            } else {
+                internal(error)
+            }
+        })?;
+    Ok(StoredProjectsPage {
+        projects: page.projects.into_iter().map(stored_project).collect(),
+        next_cursor: page.next_cursor,
+    })
+}
+
+pub(super) async fn read_project(
+    store: &LocalThreadStore,
+    project_id: String,
+) -> ThreadStoreResult<Option<StoredProject>> {
+    state(store)?
+        .get_project(&project_id)
+        .await
+        .map(|project| project.map(stored_project))
+        .map_err(internal)
+}
+
+pub(super) async fn create_project(
+    store: &LocalThreadStore,
+    params: CreateProjectParams,
+) -> ThreadStoreResult<CreatedProject> {
+    state(store)?
+        .create_project(
+            params.name,
+            params.roots.into_iter().map(state_root).collect(),
+            params.metadata,
+            &params.thread_ids,
+            &params.idempotency_key,
+        )
+        .await
+        .map(|created| CreatedProject {
+            project: stored_project(created.project),
+            created: created.created,
+        })
+        .map_err(project_idempotency_error)
+}
+
+pub(super) async fn update_project(
+    store: &LocalThreadStore,
+    params: UpdateProjectParams,
+) -> ThreadStoreResult<Option<UpdatedProject>> {
+    state(store)?
+        .update_project(
+            &params.project_id,
+            params.name,
+            params
+                .roots
+                .map(|roots| roots.into_iter().map(state_root).collect()),
+            params.metadata,
+        )
+        .await
+        .map(|result| {
+            result.map(|(project, changed)| UpdatedProject {
+                project: stored_project(project),
+                changed,
+            })
+        })
+        .map_err(internal)
+}
+
+pub(super) async fn move_project(
+    store: &LocalThreadStore,
+    params: MoveProjectParams,
+) -> ThreadStoreResult<Option<ProjectMoveOutcome>> {
+    state(store)?
+        .move_project(&params.project_id, params.before_project_id.as_deref())
+        .await
+        .map(|result| {
+            result.map(|changed| {
+                if changed {
+                    ProjectMoveOutcome::Moved
+                } else {
+                    ProjectMoveOutcome::Unchanged
+                }
+            })
+        })
+        .map_err(|error| {
+            let message = error.to_string();
+            if message.starts_with("before project ")
+                || message.starts_with("project ") && message.contains("cannot be moved")
+            {
+                ThreadStoreError::InvalidRequest { message }
+            } else {
+                internal(message)
+            }
+        })
+}
+
+pub(super) async fn delete_project(
+    store: &LocalThreadStore,
+    project_id: String,
+) -> ThreadStoreResult<Option<DeletedProject>> {
+    state(store)?
+        .delete_project(&project_id)
+        .await
+        .map(|result| {
+            result.map(
+                |(affected_active_thread_ids, affected_archived_thread_ids)| DeletedProject {
+                    affected_active_thread_ids,
+                    affected_archived_thread_ids,
+                },
+            )
+        })
+        .map_err(internal)
+}
+
+fn state(store: &LocalThreadStore) -> ThreadStoreResult<&codex_rollout::StateDbHandle> {
+    store
+        .state_db
+        .as_ref()
+        .ok_or(ThreadStoreError::Unsupported {
+            operation: "projects",
+        })
+}
+
+fn internal(error: impl std::fmt::Display) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: error.to_string(),
+    }
+}
+
+fn project_idempotency_error(error: impl std::fmt::Display) -> ThreadStoreError {
+    let message = error.to_string();
+    if message.starts_with("idempotency key refers to deleted project:") {
+        ThreadStoreError::InvalidRequest { message }
+    } else {
+        internal(message)
+    }
+}
+
+fn state_root(root: StoredProjectRoot) -> codex_state::ProjectRoot {
+    codex_state::ProjectRoot { path: root.path }
+}
+
+fn stored_project(project: codex_state::Project) -> StoredProject {
+    StoredProject {
+        id: project.id,
+        name: project.name,
+        roots: project
+            .roots
+            .into_iter()
+            .map(|root| StoredProjectRoot { path: root.path })
+            .collect(),
+        metadata: project.metadata,
+        position: project.position,
+        created_at_ms: project.created_at_ms,
+        updated_at_ms: project.updated_at_ms,
+        recency_at_ms: project.recency_at_ms,
+    }
+}
diff --git a/codex-rs/thread-store/src/local/read_thread.rs b/codex-rs/thread-store/src/local/read_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a14dcd8c528306ae04e9ffce996c98bd3d902479
--- /dev/null
+++ b/codex-rs/thread-store/src/local/read_thread.rs
@@ -0,0 +1,1638 @@
+use chrono::DateTime;
+use chrono::Utc;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::find_thread_name_by_id;
+use codex_rollout::read_session_meta_line;
+use codex_rollout::read_thread_item_from_rollout;
+use codex_state::ThreadMetadata;
+
+use super::LocalThreadStore;
+use super::helpers::distinct_thread_metadata_title;
+use super::helpers::git_info_from_parts;
+use super::helpers::permission_profile_from_metadata_value;
+use super::helpers::rollout_path_is_archived;
+use super::helpers::set_thread_name;
+use super::helpers::sqlite_thread_name;
+use super::helpers::stored_thread_from_rollout_item;
+use super::thread_rollout_resolver;
+use crate::ReadThreadParams;
+use crate::StoredThread;
+use crate::StoredThreadHistory;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::error::reject_paginated_history_mode;
+
+pub(super) async fn read_thread(
+    store: &LocalThreadStore,
+    params: ReadThreadParams,
+) -> ThreadStoreResult<StoredThread> {
+    let thread_id = params.thread_id;
+    let sqlite_metadata = read_sqlite_metadata(store, thread_id).await;
+    let persisted_model_settings = sqlite_metadata
+        .as_ref()
+        .map(|metadata| (metadata.model.clone(), metadata.reasoning_effort.clone()));
+    let daybreak_enabled = sqlite_metadata
+        .as_ref()
+        .and_then(|metadata| metadata.daybreak_enabled);
+    if let Some(metadata) = sqlite_metadata
+        && (params.include_archived
+            || (metadata.archived_at.is_none()
+                && !rollout_path_is_archived(
+                    store.config.codex_home.as_path(),
+                    metadata.rollout_path.as_path(),
+                )))
+        && (!params.include_history
+            || sqlite_rollout_path_can_load_history_for_thread(&metadata.rollout_path, thread_id)
+                .await)
+    {
+        let metadata_sandbox_policy = metadata.sandbox_policy.clone();
+        let mut thread = stored_thread_from_sqlite_metadata(store, metadata).await?;
+        // Paginated history may contain only a suffix, so its display metadata lives in SQLite.
+        // Legacy display metadata remains rollout-derived.
+        if thread.history_mode == ThreadHistoryMode::Legacy
+            && !params.include_history
+            && let Some(rollout_path) = thread.rollout_path.clone()
+            && let Ok(mut rollout_thread) = read_thread_from_rollout_path(store, rollout_path).await
+            && rollout_thread.thread_id == thread_id
+            && (params.include_archived || rollout_thread.archived_at.is_none())
+            && !rollout_thread.preview.is_empty()
+        {
+            rollout_thread.recency_at = thread.recency_at;
+            rollout_thread.section = thread.section;
+            rollout_thread.section_position = thread.section_position;
+            rollout_thread.section_entered_at = thread.section_entered_at;
+            if !thread.cwd.as_os_str().is_empty() {
+                rollout_thread.cwd = thread.cwd;
+            }
+            if thread.name.is_some() {
+                rollout_thread.name = thread.name;
+            }
+            rollout_thread.project_id = thread.project_id;
+            rollout_thread.daybreak_enabled = thread.daybreak_enabled;
+            rollout_thread.model = thread.model;
+            rollout_thread.reasoning_effort = thread.reasoning_effort;
+            rollout_thread.git_info = thread.git_info;
+            rollout_thread.permission_profile = permission_profile_from_metadata_value(
+                &metadata_sandbox_policy,
+                rollout_thread.cwd.as_path(),
+            );
+            thread = rollout_thread;
+        }
+        reject_paginated_history(&thread, params.include_history)?;
+        attach_history_if_requested(&mut thread, params.include_history).await?;
+        return Ok(thread);
+    }
+
+    let resolved = if params.include_archived {
+        thread_rollout_resolver::resolve_current_including_archived(store, thread_id).await?
+    } else {
+        thread_rollout_resolver::resolve_current(store, thread_id).await?
+    };
+    let path =
+        resolved
+            .map(|resolved| resolved.path)
+            .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                message: format!("no rollout found for thread id {thread_id}"),
+            })?;
+
+    let mut thread = read_thread_from_rollout_path(store, path).await?;
+    thread.daybreak_enabled = daybreak_enabled;
+    if let Some((model, reasoning_effort)) = persisted_model_settings {
+        thread.model = model;
+        thread.reasoning_effort = reasoning_effort;
+    }
+    if !params.include_archived && thread.archived_at.is_some() {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!("thread {} is archived", thread.thread_id),
+        });
+    }
+    reject_paginated_history(&thread, params.include_history)?;
+    attach_history_if_requested(&mut thread, params.include_history).await?;
+    Ok(thread)
+}
+
+async fn sqlite_rollout_path_can_load_history_for_thread(
+    path: &std::path::Path,
+    thread_id: codex_protocol::ThreadId,
+) -> bool {
+    if codex_rollout::existing_rollout_path(path).await.is_none() {
+        return false;
+    }
+    // SQLite metadata can outlive a moved/recreated rollout path. When history is
+    // requested, verify the path still resolves to the requested thread before
+    // trusting it as the source replay.
+    read_session_meta_line(path)
+        .await
+        .is_ok_and(|metadata| metadata.meta.id == thread_id)
+}
+
+pub(super) async fn read_thread_by_rollout_path(
+    store: &LocalThreadStore,
+    rollout_path: std::path::PathBuf,
+    include_archived: bool,
+    include_history: bool,
+) -> ThreadStoreResult<StoredThread> {
+    let path = resolve_requested_rollout_path(store, rollout_path).await?;
+    let mut thread = read_thread_from_rollout_path(store, path.clone()).await?;
+    if !include_archived && thread.archived_at.is_some() {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!("thread {} is archived", thread.thread_id),
+        });
+    }
+    if let Some(mut metadata) = read_sqlite_metadata(store, thread.thread_id).await {
+        if thread.history_mode == ThreadHistoryMode::Paginated {
+            // Paginated display metadata lives in SQLite because rollout history may be partial.
+            metadata.rollout_path = path;
+            metadata.archived_at = thread.archived_at;
+            thread = stored_thread_from_sqlite_metadata(store, metadata).await?;
+        } else {
+            thread.recency_at = metadata.recency_at;
+            thread.section = metadata.section;
+            thread.section_position = metadata.section_position;
+            thread.section_entered_at = metadata.section_entered_at;
+            thread.project_id = metadata.project_id;
+            thread.daybreak_enabled = metadata.daybreak_enabled;
+            thread.model = metadata.model;
+            thread.reasoning_effort = metadata.reasoning_effort;
+            if !metadata.cwd.as_os_str().is_empty()
+                && resolve_requested_rollout_path(store, metadata.rollout_path.clone())
+                    .await
+                    .is_ok_and(|metadata_rollout_path| metadata_rollout_path == path)
+            {
+                thread.cwd = metadata.cwd;
+                thread.permission_profile = permission_profile_from_metadata_value(
+                    &metadata.sandbox_policy,
+                    thread.cwd.as_path(),
+                );
+            }
+            let (fallback_sha, fallback_branch, fallback_origin_url) = match thread.git_info.take()
+            {
+                Some(info) => (
+                    info.commit_hash.map(|sha| sha.0),
+                    info.branch,
+                    info.repository_url,
+                ),
+                None => (None, None, None),
+            };
+            thread.git_info = git_info_from_parts(
+                metadata.git_sha.or(fallback_sha),
+                metadata.git_branch.or(fallback_branch),
+                metadata.git_origin_url.or(fallback_origin_url),
+            );
+        }
+    }
+    reject_paginated_history(&thread, include_history)?;
+    attach_history_if_requested(&mut thread, include_history).await?;
+    Ok(thread)
+}
+
+fn reject_paginated_history(thread: &StoredThread, include_history: bool) -> ThreadStoreResult<()> {
+    if include_history {
+        reject_paginated_history_mode(thread.history_mode)?;
+    }
+    Ok(())
+}
+
+async fn resolve_requested_rollout_path(
+    store: &LocalThreadStore,
+    rollout_path: std::path::PathBuf,
+) -> ThreadStoreResult<std::path::PathBuf> {
+    let path = if rollout_path.is_relative() {
+        store.config.codex_home.join(rollout_path)
+    } else {
+        rollout_path
+    };
+    match tokio::fs::metadata(path.as_path()).await {
+        Ok(metadata) if metadata.is_dir() => {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!(
+                    "failed to resolve rollout path `{}`: path is a directory",
+                    path.display()
+                ),
+            });
+        }
+        Ok(metadata) if !metadata.is_file() => {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!(
+                    "failed to resolve rollout path `{}`: path is not a file",
+                    path.display()
+                ),
+            });
+        }
+        _ => {}
+    }
+    let Some(path) = codex_rollout::existing_rollout_path(path.as_path()).await else {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!(
+                "failed to resolve rollout path `{}`: file does not exist",
+                path.display()
+            ),
+        });
+    };
+    std::fs::canonicalize(path.as_path()).map_err(|err| ThreadStoreError::InvalidRequest {
+        message: format!("failed to resolve rollout path `{}`: {err}", path.display()),
+    })
+}
+
+async fn attach_history_if_requested(
+    thread: &mut StoredThread,
+    include_history: bool,
+) -> ThreadStoreResult<()> {
+    if !include_history {
+        return Ok(());
+    }
+    let thread_id = thread.thread_id;
+    let Some(path) = thread.rollout_path.clone() else {
+        return Err(ThreadStoreError::Internal {
+            message: format!("failed to load thread history for thread {thread_id}"),
+        });
+    };
+    let items = load_history_items(&path).await?;
+    thread.history = Some(StoredThreadHistory { thread_id, items });
+    Ok(())
+}
+
+async fn read_thread_from_rollout_path(
+    store: &LocalThreadStore,
+    path: std::path::PathBuf,
+) -> ThreadStoreResult<StoredThread> {
+    let Some(item) = read_thread_item_from_rollout(path.clone()).await else {
+        return stored_thread_from_session_meta(store, path).await;
+    };
+    let archived = rollout_path_is_archived(store.config.codex_home.as_path(), path.as_path());
+    let mut thread = stored_thread_from_rollout_item(
+        item,
+        archived,
+        store.config.default_model_provider_id.as_str(),
+    )
+    .ok_or_else(|| ThreadStoreError::Internal {
+        message: format!("failed to read thread id from {}", path.display()),
+    })?;
+    thread.rollout_path = Some(codex_rollout::plain_rollout_path(path.as_path()));
+    let meta_line = read_required_session_meta_line(path.as_path()).await?;
+    thread.forked_from_id = meta_line.meta.forked_from_id;
+    thread.parent_thread_id = meta_line.meta.parent_thread_id;
+    thread.history_mode = meta_line.meta.history_mode;
+    if let Some(model_provider) = meta_line
+        .meta
+        .model_provider
+        .filter(|provider| !provider.is_empty())
+    {
+        thread.model_provider = model_provider;
+    }
+    if thread.history_mode == ThreadHistoryMode::Legacy
+        && let Ok(Some(name)) =
+            find_thread_name_by_id(store.config.codex_home.as_path(), &thread.thread_id).await
+        && !name.trim().is_empty()
+    {
+        set_thread_name(&mut thread, name);
+    }
+    Ok(thread)
+}
+
+pub(super) async fn load_history_items(
+    path: &std::path::Path,
+) -> ThreadStoreResult<Vec<codex_rollout::RolloutItem>> {
+    let (items, _, _) = RolloutRecorder::load_rollout_items(path)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to load thread history {}: {err}", path.display()),
+        })?;
+    Ok(items)
+}
+
+async fn read_sqlite_metadata(
+    store: &LocalThreadStore,
+    thread_id: codex_protocol::ThreadId,
+) -> Option<ThreadMetadata> {
+    let runtime = store.state_db().await?;
+    runtime.get_thread(thread_id).await.ok().flatten()
+}
+
+pub(super) async fn stored_thread_from_sqlite_metadata(
+    store: &LocalThreadStore,
+    metadata: ThreadMetadata,
+) -> ThreadStoreResult<StoredThread> {
+    let session_meta = match read_required_session_meta_line(metadata.rollout_path.as_path()).await
+    {
+        Ok(meta_line) if meta_line.meta.id != metadata.id => {
+            return Err(ThreadStoreError::Internal {
+                message: format!(
+                    "session metadata {} belongs to thread {}, expected {}",
+                    metadata.rollout_path.display(),
+                    meta_line.meta.id,
+                    metadata.id
+                ),
+            });
+        }
+        Ok(meta_line) => Some(meta_line.meta),
+        Err(_)
+            if codex_rollout::existing_rollout_path(metadata.rollout_path.as_path())
+                .await
+                .is_none() =>
+        {
+            None
+        }
+        Err(err) => {
+            return Err(ThreadStoreError::Internal {
+                message: format!(
+                    "failed to read session metadata {}: {err}",
+                    metadata.rollout_path.display()
+                ),
+            });
+        }
+    };
+    let forked_from_id = session_meta.as_ref().and_then(|meta| meta.forked_from_id);
+    let parent_thread_id = session_meta.as_ref().and_then(|meta| meta.parent_thread_id);
+    let history_mode = session_meta
+        .as_ref()
+        .map(|meta| meta.history_mode)
+        .unwrap_or(metadata.history_mode);
+    let name = thread_name_from_metadata(store, &metadata, history_mode).await;
+    let mut thread = stored_thread_from_state_metadata(store, metadata, parent_thread_id);
+    thread.originator = thread.originator.or_else(|| {
+        session_meta
+            .map(|meta| meta.originator)
+            .filter(|originator| !originator.is_empty())
+    });
+    thread.forked_from_id = forked_from_id;
+    thread.history_mode = history_mode;
+    thread.name = name;
+    Ok(thread)
+}
+
+pub(super) fn stored_thread_from_state_metadata(
+    store: &LocalThreadStore,
+    metadata: ThreadMetadata,
+    parent_thread_id: Option<codex_protocol::ThreadId>,
+) -> StoredThread {
+    let name = match metadata.history_mode {
+        ThreadHistoryMode::Paginated => sqlite_thread_name(&metadata),
+        ThreadHistoryMode::Legacy => distinct_thread_metadata_title(&metadata),
+    };
+    let rollout_path = codex_rollout::plain_rollout_path(metadata.rollout_path.as_path());
+    let preview = metadata
+        .preview
+        .clone()
+        .or_else(|| metadata.first_user_message.clone())
+        .unwrap_or_default();
+    let permission_profile =
+        permission_profile_from_metadata_value(&metadata.sandbox_policy, metadata.cwd.as_path());
+    StoredThread {
+        thread_id: metadata.id,
+        extra_config: None,
+        rollout_path: Some(rollout_path),
+        forked_from_id: None,
+        parent_thread_id,
+        preview,
+        name,
+        model_provider: if metadata.model_provider.is_empty() {
+            store.config.default_model_provider_id.clone()
+        } else {
+            metadata.model_provider
+        },
+        model: metadata.model,
+        reasoning_effort: metadata.reasoning_effort,
+        created_at: metadata.created_at,
+        updated_at: metadata.updated_at,
+        recency_at: metadata.recency_at,
+        archived_at: metadata.archived_at,
+        section: metadata.section,
+        section_position: metadata.section_position,
+        section_entered_at: metadata.section_entered_at,
+        project_id: metadata.project_id,
+        daybreak_enabled: metadata.daybreak_enabled,
+        cwd: metadata.cwd,
+        cli_version: metadata.cli_version,
+        originator: metadata.originator,
+        source: parse_session_source(&metadata.source),
+        history_mode: metadata.history_mode,
+        thread_source: metadata.thread_source,
+        agent_nickname: metadata.agent_nickname,
+        agent_role: metadata.agent_role,
+        agent_path: metadata.agent_path,
+        git_info: git_info_from_parts(
+            metadata.git_sha,
+            metadata.git_branch,
+            metadata.git_origin_url,
+        ),
+        approval_mode: parse_or_default(&metadata.approval_mode, AskForApproval::OnRequest),
+        permission_profile,
+        token_usage: None,
+        first_user_message: metadata.first_user_message,
+        history: None,
+    }
+}
+
+async fn thread_name_from_metadata(
+    store: &LocalThreadStore,
+    metadata: &ThreadMetadata,
+    history_mode: ThreadHistoryMode,
+) -> Option<String> {
+    match history_mode {
+        ThreadHistoryMode::Paginated => sqlite_thread_name(metadata),
+        ThreadHistoryMode::Legacy => {
+            if let Some(title) = distinct_thread_metadata_title(metadata) {
+                Some(title)
+            } else {
+                find_thread_name_by_id(store.config.codex_home.as_path(), &metadata.id)
+                    .await
+                    .ok()
+                    .flatten()
+                    .filter(|name| !name.trim().is_empty())
+            }
+        }
+    }
+}
+
+async fn stored_thread_from_session_meta(
+    store: &LocalThreadStore,
+    path: std::path::PathBuf,
+) -> ThreadStoreResult<StoredThread> {
+    let meta_line = read_required_session_meta_line(path.as_path()).await?;
+    let archived = rollout_path_is_archived(store.config.codex_home.as_path(), path.as_path());
+    Ok(stored_thread_from_meta_line(
+        store, meta_line, path, archived,
+    ))
+}
+
+async fn read_required_session_meta_line(
+    path: &std::path::Path,
+) -> ThreadStoreResult<SessionMetaLine> {
+    read_session_meta_line(path)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to read session metadata {}: {err}", path.display()),
+        })
+}
+
+fn stored_thread_from_meta_line(
+    store: &LocalThreadStore,
+    meta_line: SessionMetaLine,
+    path: std::path::PathBuf,
+    archived: bool,
+) -> StoredThread {
+    let created_at = parse_rfc3339_non_optional(&meta_line.meta.timestamp).unwrap_or_else(Utc::now);
+    let updated_at = std::fs::metadata(path.as_path())
+        .ok()
+        .and_then(|meta| meta.modified().ok())
+        .map(DateTime::<Utc>::from)
+        .unwrap_or(created_at);
+    let rollout_path = codex_rollout::plain_rollout_path(path.as_path());
+    StoredThread {
+        thread_id: meta_line.meta.id,
+        extra_config: None,
+        rollout_path: Some(rollout_path),
+        forked_from_id: meta_line.meta.forked_from_id,
+        parent_thread_id: meta_line.meta.parent_thread_id,
+        preview: String::new(),
+        name: None,
+        model_provider: meta_line
+            .meta
+            .model_provider
+            .filter(|provider| !provider.is_empty())
+            .unwrap_or_else(|| store.config.default_model_provider_id.clone()),
+        model: None,
+        reasoning_effort: None,
+        created_at,
+        updated_at,
+        recency_at: updated_at,
+        archived_at: archived.then_some(updated_at),
+        section: None,
+        section_position: None,
+        section_entered_at: None,
+        project_id: None,
+        daybreak_enabled: None,
+        cwd: meta_line.meta.cwd,
+        cli_version: meta_line.meta.cli_version,
+        originator: (!meta_line.meta.originator.is_empty()).then_some(meta_line.meta.originator),
+        source: meta_line.meta.source,
+        history_mode: meta_line.meta.history_mode,
+        thread_source: meta_line.meta.thread_source,
+        agent_nickname: meta_line.meta.agent_nickname,
+        agent_role: meta_line.meta.agent_role,
+        agent_path: meta_line.meta.agent_path,
+        git_info: meta_line.git,
+        approval_mode: AskForApproval::OnRequest,
+        permission_profile: PermissionProfile::read_only(),
+        token_usage: None,
+        first_user_message: None,
+        history: None,
+    }
+}
+
+fn parse_session_source(source: &str) -> SessionSource {
+    serde_json::from_str(source)
+        .or_else(|_| serde_json::from_value(serde_json::Value::String(source.to_string())))
+        .unwrap_or(SessionSource::Unknown)
+}
+
+fn parse_or_default<T>(value: &str, default: T) -> T
+where
+    T: serde::de::DeserializeOwned,
+{
+    serde_json::from_str(value)
+        .or_else(|_| serde_json::from_value(serde_json::Value::String(value.to_string())))
+        .unwrap_or(default)
+}
+
+fn parse_rfc3339_non_optional(value: &str) -> Option<DateTime<Utc>> {
+    DateTime::parse_from_rfc3339(value)
+        .ok()
+        .map(|dt| dt.with_timezone(&Utc))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::io::Write;
+    use std::path::PathBuf;
+
+    use chrono::Utc;
+    use codex_protocol::ThreadId;
+    use codex_protocol::items::TurnItem;
+    use codex_protocol::items::UserMessageItem;
+    use codex_protocol::openai_models::ReasoningEffort;
+    use codex_protocol::protocol::EventMsg;
+    use codex_protocol::protocol::ItemCompletedEvent;
+    use codex_protocol::protocol::SandboxPolicy;
+    use codex_protocol::protocol::SessionSource;
+    use codex_protocol::protocol::ThreadHistoryMode;
+    use codex_protocol::user_input::UserInput;
+    use codex_rollout::RolloutItem;
+    use codex_state::ThreadMetadataBuilder;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::ThreadStore;
+    use crate::local::LocalThreadStore;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_archived_session_file;
+    use crate::local::test_support::write_session_file;
+    use crate::local::test_support::write_session_file_with_fork;
+    use crate::local::test_support::write_session_file_with_history_mode;
+
+    #[tokio::test]
+    async fn read_thread_returns_active_rollout_summary() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(205);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: true,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(active_path));
+        assert_eq!(thread.archived_at, None);
+        assert_eq!(thread.preview, "Hello from user");
+        assert_eq!(
+            thread.history.expect("history should load").thread_id,
+            thread_id
+        );
+    }
+
+    #[tokio::test]
+    async fn read_thread_returns_rollout_path_summary() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(211);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let relative_path = active_path
+            .strip_prefix(home.path())
+            .expect("path should be under codex home")
+            .to_path_buf();
+
+        let thread = store
+            .read_thread_by_rollout_path(
+                relative_path,
+                /*include_archived*/ false,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("read thread by rollout path");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(
+            thread.rollout_path,
+            Some(std::fs::canonicalize(active_path).expect("canonical path"))
+        );
+        assert_eq!(thread.preview, "Hello from user");
+    }
+
+    #[tokio::test]
+    async fn read_thread_by_rollout_path_preserves_legacy_name_and_sqlite_git_info() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(223);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            active_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.git_branch = Some("sqlite-branch".to_string());
+        let recency_at = chrono::DateTime::parse_from_rfc3339("2026-01-03T12:00:00Z")
+            .expect("timestamp should parse")
+            .with_timezone(&Utc);
+        builder.recency_at = Some(recency_at);
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.title = "Stale SQLite name".to_string();
+        metadata.section = Some(codex_state::ThreadSection {
+            id: codex_state::PINNED_THREAD_SECTION_ID.to_string(),
+            name: codex_state::PINNED_THREAD_SECTION_NAME.to_string(),
+            appearance: None,
+        });
+        metadata.section_position = Some(2_000_000);
+        metadata.section_entered_at = Some(recency_at);
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+        codex_rollout::append_thread_name(home.path(), thread_id, "Latest index name")
+            .await
+            .expect("append thread name");
+
+        let thread = store
+            .read_thread_by_rollout_path(
+                active_path,
+                /*include_archived*/ false,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("read thread by rollout path");
+
+        let git_info = thread.git_info.expect("git info should be present");
+        assert_eq!(thread.name.as_deref(), Some("Latest index name"));
+        assert_eq!(thread.recency_at, recency_at);
+        assert_eq!(
+            thread.section.as_ref().map(|section| section.id.as_str()),
+            Some(codex_state::PINNED_THREAD_SECTION_ID)
+        );
+        assert_eq!(thread.section_position, Some(2_000_000));
+        assert_eq!(thread.section_entered_at, Some(recency_at));
+        assert_eq!(git_info.branch.as_deref(), Some("sqlite-branch"));
+        assert_eq!(
+            git_info.commit_hash.as_ref().map(|sha| sha.0.as_str()),
+            Some("abcdef")
+        );
+        assert_eq!(
+            git_info.repository_url.as_deref(),
+            Some("https://example.com/repo.git")
+        );
+    }
+
+    #[tokio::test]
+    async fn read_thread_returns_archived_rollout_when_requested() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(207);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T12-00-00", uuid)
+            .expect("archived session file");
+
+        let active_only_err = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect_err("active-only read should fail for archived rollout");
+        let ThreadStoreError::InvalidRequest { message } = active_only_err else {
+            panic!("expected invalid request error");
+        };
+        assert_eq!(
+            message,
+            format!("no rollout found for thread id {thread_id}")
+        );
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: true,
+                include_history: false,
+            })
+            .await
+            .expect("read archived thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(archived_path));
+        assert!(thread.archived_at.is_some());
+        assert_eq!(thread.preview, "Archived user message");
+        assert!(thread.history.is_none());
+    }
+
+    #[tokio::test]
+    async fn read_thread_prefers_active_rollout_over_archived() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(208);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let active_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        write_archived_session_file(home.path(), "2025-01-03T12-00-00", uuid)
+            .expect("archived session file");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: true,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.rollout_path, Some(active_path));
+        assert_eq!(thread.archived_at, None);
+        assert_eq!(thread.preview, "Hello from user");
+    }
+
+    #[tokio::test]
+    async fn read_thread_returns_forked_from_id() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(209);
+        let parent_uuid = Uuid::from_u128(210);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let parent_thread_id =
+            ThreadId::from_string(&parent_uuid.to_string()).expect("valid parent thread id");
+        write_session_file_with_fork(
+            home.path(),
+            home.path().join("sessions/2025/01/03"),
+            "2025-01-03T12-00-00",
+            uuid,
+            "Forked user message",
+            Some("test-provider"),
+            Some(parent_uuid),
+            ThreadHistoryMode::Legacy,
+        )
+        .expect("forked session file");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.forked_from_id, Some(parent_thread_id));
+    }
+
+    #[tokio::test]
+    async fn read_thread_applies_sqlite_thread_name() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(212);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder =
+            ThreadMetadataBuilder::new(thread_id, rollout_path, Utc::now(), SessionSource::Cli);
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        builder.cli_version = Some("test_version".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.title = "Saved title".to_string();
+        metadata.first_user_message = Some("Hello from user".to_string());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.name, Some("Saved title".to_string()));
+    }
+
+    #[tokio::test]
+    async fn read_paginated_thread_prefers_sqlite_display_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(228);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T12-00-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        codex_rollout::append_rollout_item_to_path(
+            &rollout_path,
+            &RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+                thread_id,
+                turn_id: "turn-1".to_string(),
+                item: TurnItem::UserMessage(UserMessageItem::new(&[UserInput::Text {
+                    text: "Rollout user message".to_string(),
+                    text_elements: Vec::new(),
+                }])),
+                started_at_ms: Some(0),
+                completed_at_ms: 0,
+            })),
+        )
+        .await
+        .expect("append rollout user message");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.history_mode = ThreadHistoryMode::Paginated;
+        builder.model_provider = Some("Canonical SQLite provider".to_string());
+        builder.cwd = home.path().to_path_buf();
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.name = Some("Canonical SQLite name".to_string());
+        metadata.preview = Some("Canonical SQLite preview".to_string());
+        metadata.first_user_message = Some("Canonical SQLite first user message".to_string());
+        metadata.title = "Canonical SQLite derived title".to_string();
+        metadata.model = Some("Canonical SQLite model".to_string());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+        codex_rollout::append_thread_name(home.path(), thread_id, "Stale index name")
+            .await
+            .expect("append legacy thread name");
+
+        let thread_by_id = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+        let thread_by_path = store
+            .read_thread_by_rollout_path(
+                rollout_path,
+                /*include_archived*/ false,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("read thread by rollout path");
+
+        for thread in [thread_by_id, thread_by_path] {
+            assert_eq!(
+                (
+                    thread.name.as_deref(),
+                    thread.preview.as_str(),
+                    thread.first_user_message.as_deref(),
+                    thread.model_provider.as_str(),
+                    thread.model.as_deref(),
+                    thread.originator.as_deref(),
+                ),
+                (
+                    Some("Canonical SQLite name"),
+                    "Canonical SQLite preview",
+                    Some("Canonical SQLite first user message"),
+                    "Canonical SQLite provider",
+                    Some("Canonical SQLite model"),
+                    Some("test_originator"),
+                )
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn read_thread_returns_permission_profile_from_sqlite_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(225);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder =
+            ThreadMetadataBuilder::new(thread_id, rollout_path, Utc::now(), SessionSource::Cli);
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        let permission_profile: PermissionProfile = PermissionProfile::Disabled;
+        metadata.sandbox_policy =
+            serde_json::to_string(&permission_profile).expect("serialize profile");
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.preview, "Hello from user");
+        assert_eq!(thread.permission_profile, PermissionProfile::Disabled);
+    }
+
+    #[tokio::test]
+    async fn read_thread_accepts_legacy_sandbox_policy_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(226);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder =
+            ThreadMetadataBuilder::new(thread_id, rollout_path, Utc::now(), SessionSource::Cli);
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.sandbox_policy = "danger-full-access".to_string();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: true,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.permission_profile, PermissionProfile::Disabled);
+    }
+
+    #[tokio::test]
+    async fn read_thread_preserves_sqlite_cwd_when_rollout_metadata_is_stale() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let uuid = Uuid::from_u128(224);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let day_dir = home.path().join("sessions/2025/01/03");
+        std::fs::create_dir_all(&day_dir).expect("sessions dir");
+        let rollout_path = day_dir.join(format!("rollout-2025-01-03T12-00-00-{uuid}.jsonl"));
+        let mut file = std::fs::File::create(&rollout_path).expect("session file");
+        let rollout_cwd = PathBuf::from("/");
+        let meta = serde_json::json!({
+            "timestamp": "2025-01-03T12:00:00Z",
+            "type": "session_meta",
+            "payload": {
+                "session_id": uuid,
+                "id": uuid,
+                "timestamp": "2025-01-03T12:00:00Z",
+                "cwd": rollout_cwd,
+                "originator": "test_originator",
+                "cli_version": "test_version",
+                "source": "cli",
+                "model_provider": "rollout-provider"
+            },
+        });
+        writeln!(file, "{meta}").expect("write session meta");
+        let user_event = serde_json::json!({
+            "timestamp": "2025-01-03T12:00:00Z",
+            "type": "event_msg",
+            "payload": {
+                "type": "user_message",
+                "message": "Hello from rollout",
+                "kind": "plain",
+            },
+        });
+        writeln!(file, "{user_event}").expect("write user event");
+
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        let sqlite_cwd = home.path().join("sqlite-workspace");
+        builder.cwd = sqlite_cwd.clone();
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.title = "Saved title".to_string();
+        metadata.first_user_message = Some("Hello from sqlite".to_string());
+        metadata.sandbox_policy = "workspace-write".to_string();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(rollout_path.clone()));
+        assert_eq!(thread.preview, "Hello from rollout");
+        assert_eq!(thread.name, Some("Saved title".to_string()));
+        assert_eq!(thread.model_provider, "rollout-provider");
+        assert_eq!(thread.cwd, sqlite_cwd);
+        let legacy_policy = SandboxPolicy::WorkspaceWrite {
+            writable_roots: Vec::new(),
+            network_access: false,
+            exclude_tmpdir_env_var: false,
+            exclude_slash_tmp: false,
+        };
+        assert_eq!(
+            thread.permission_profile,
+            PermissionProfile::from_legacy_sandbox_policy_for_cwd(
+                &legacy_policy,
+                sqlite_cwd.as_path()
+            )
+        );
+
+        let thread_by_rollout_path = store
+            .read_thread_by_rollout_path(
+                rollout_path.clone(),
+                /*include_archived*/ false,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("read thread by rollout path");
+
+        assert_eq!(thread_by_rollout_path.cwd, sqlite_cwd);
+        assert_eq!(
+            thread_by_rollout_path.permission_profile,
+            thread.permission_profile
+        );
+
+        metadata.cwd = PathBuf::new();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("update state db with empty cwd");
+
+        for thread in [
+            store
+                .read_thread(ReadThreadParams {
+                    thread_id,
+                    include_archived: false,
+                    include_history: false,
+                })
+                .await
+                .expect("read thread with empty sqlite cwd"),
+            store
+                .read_thread_by_rollout_path(
+                    rollout_path.clone(),
+                    /*include_archived*/ false,
+                    /*include_history*/ false,
+                )
+                .await
+                .expect("read rollout path with empty sqlite cwd"),
+        ] {
+            assert_eq!(thread.cwd, rollout_cwd);
+        }
+
+        metadata.cwd = sqlite_cwd;
+        metadata.rollout_path =
+            write_session_file(home.path(), "2025-01-04T12-00-00", uuid).expect("newer rollout");
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("update state db with newer rollout");
+
+        let thread_from_requested_rollout = store
+            .read_thread_by_rollout_path(
+                rollout_path,
+                /*include_archived*/ false,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("read explicitly requested rollout");
+
+        assert_eq!(thread_from_requested_rollout.cwd, rollout_cwd);
+    }
+
+    #[tokio::test]
+    async fn read_thread_uses_legacy_thread_name_when_sqlite_title_is_missing() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(213);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        codex_rollout::append_thread_name(home.path(), thread_id, "Legacy title")
+            .await
+            .expect("append legacy thread name");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.name, Some("Legacy title".to_string()));
+    }
+
+    #[tokio::test]
+    async fn read_thread_uses_sqlite_metadata_for_rollout_without_user_preview() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(217);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let day_dir = home.path().join("sessions/2025/01/03");
+        std::fs::create_dir_all(&day_dir).expect("sessions dir");
+        let rollout_path = day_dir.join(format!("rollout-2025-01-03T12-00-00-{uuid}.jsonl"));
+        let mut file = std::fs::File::create(&rollout_path).expect("session file");
+        let mut meta = serde_json::json!({
+            "timestamp": "2025-01-03T12-00-00",
+            "type": "session_meta",
+            "payload": {
+                "session_id": uuid,
+                "id": uuid,
+                "timestamp": "2025-01-03T12-00-00",
+                "cwd": home.path(),
+                "originator": "test_originator",
+                "cli_version": "test_version",
+                "source": "cli",
+                "model_provider": "rollout-provider"
+            },
+        });
+        writeln!(file, "{meta}").expect("write session meta");
+
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some("sqlite-provider".to_string());
+        builder.cwd = home.path().join("workspace");
+        builder.cli_version = Some("sqlite-cli".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.title = "Command-only thread".to_string();
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: true,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(rollout_path));
+        assert_eq!(thread.preview, "");
+        assert_eq!(thread.name.as_deref(), Some("Command-only thread"));
+        assert_eq!(thread.model_provider, "sqlite-provider");
+        assert_eq!(thread.cwd, home.path().join("workspace"));
+        assert_eq!(thread.cli_version, "sqlite-cli");
+        assert_eq!(thread.originator.as_deref(), Some("test_originator"));
+        let history = thread.history.expect("history should load");
+        assert_eq!(history.thread_id, thread_id);
+        assert_eq!(history.items.len(), 1);
+
+        for (sqlite_originator, rollout_originator, expected_originator) in [
+            (
+                Some("saved_client"),
+                "test_originator",
+                Some("saved_client"),
+            ),
+            (None, "", None),
+        ] {
+            meta["payload"]["originator"] = serde_json::json!(rollout_originator);
+            std::fs::write(&metadata.rollout_path, format!("{meta}\n"))
+                .expect("write session meta");
+            metadata.originator = sqlite_originator.map(str::to_owned);
+            let thread = stored_thread_from_sqlite_metadata(&store, metadata.clone())
+                .await
+                .expect("read SQLite and session metadata");
+            assert_eq!(thread.originator.as_deref(), expected_originator);
+        }
+    }
+
+    #[tokio::test]
+    async fn read_thread_falls_back_to_rollout_search_when_sqlite_path_is_stale() {
+        let home = TempDir::new().expect("temp dir");
+        let external = TempDir::new().expect("external temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(220);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let stale_path = external.path().join("missing-rollout.jsonl");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            stale_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some("stale-sqlite-provider".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.first_user_message = Some("stale sqlite preview".to_string());
+        metadata.model = Some("persisted-model".to_string());
+        metadata.reasoning_effort = Some(ReasoningEffort::High);
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: true,
+                include_history: true,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(rollout_path));
+        assert_eq!(thread.preview, "Hello from user");
+        assert_eq!(thread.model_provider, config.default_model_provider_id);
+        assert_eq!(
+            (thread.model.as_deref(), thread.reasoning_effort),
+            (Some("persisted-model"), Some(ReasoningEffort::High))
+        );
+        let history = thread.history.expect("history should load");
+        assert_eq!(history.thread_id, thread_id);
+        assert_eq!(history.items.len(), 2);
+    }
+
+    #[tokio::test]
+    async fn read_thread_falls_back_when_sqlite_path_points_to_another_thread() {
+        let home = TempDir::new().expect("temp dir");
+        let external = TempDir::new().expect("external temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(221);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T12-00-00", uuid).expect("session file");
+        let other_uuid = Uuid::from_u128(222);
+        let stale_path = write_session_file(external.path(), "2025-01-04T12-00-00", other_uuid)
+            .expect("other session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder =
+            ThreadMetadataBuilder::new(thread_id, stale_path, Utc::now(), SessionSource::Cli);
+        builder.model_provider = Some("wrong-sqlite-provider".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.first_user_message = Some("wrong sqlite preview".to_string());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: true,
+                include_history: true,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(rollout_path));
+        assert_eq!(thread.preview, "Hello from user");
+        assert_eq!(thread.model_provider, config.default_model_provider_id);
+        let history = thread.history.expect("history should load");
+        assert_eq!(history.thread_id, thread_id);
+        assert_eq!(history.items.len(), 2);
+    }
+
+    #[tokio::test]
+    async fn read_thread_uses_session_meta_for_rollout_without_user_preview_or_sqlite_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(218);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let day_dir = home.path().join("sessions/2025/01/03");
+        std::fs::create_dir_all(&day_dir).expect("sessions dir");
+        let rollout_path = day_dir.join(format!("rollout-2025-01-03T12-00-00-{uuid}.jsonl"));
+        let mut file = std::fs::File::create(&rollout_path).expect("session file");
+        let meta = serde_json::json!({
+            "timestamp": "2025-01-03T12:00:00Z",
+            "type": "session_meta",
+            "payload": {
+                "session_id": uuid,
+                "id": uuid,
+                "timestamp": "2025-01-03T12:00:00Z",
+                "cwd": home.path(),
+                "originator": "test_originator",
+                "cli_version": "test_version",
+                "source": "cli",
+                "model_provider": "rollout-provider"
+            },
+        });
+        writeln!(file, "{meta}").expect("write session meta");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: true,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(rollout_path));
+        assert_eq!(thread.preview, "");
+        assert_eq!(thread.name, None);
+        assert_eq!(thread.model_provider, "rollout-provider");
+        assert_eq!(
+            thread.created_at,
+            parse_rfc3339_non_optional("2025-01-03T12:00:00Z").unwrap()
+        );
+        assert!(thread.updated_at >= thread.created_at);
+        assert_eq!(thread.archived_at, None);
+        assert_eq!(thread.cwd, home.path());
+        assert_eq!(thread.cli_version, "test_version");
+        assert_eq!(thread.source, SessionSource::Cli);
+        let history = thread.history.expect("history should load");
+        assert_eq!(history.thread_id, thread_id);
+        assert_eq!(history.items.len(), 1);
+    }
+
+    #[tokio::test]
+    async fn read_thread_falls_back_to_sqlite_summary() {
+        let home = TempDir::new().expect("temp dir");
+        let external = TempDir::new().expect("external temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(214);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = external
+            .path()
+            .join(format!("rollout-2025-01-03T12-00-00-{uuid}.jsonl"));
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path.clone(),
+            Utc::now(),
+            SessionSource::Exec,
+        );
+        builder.model_provider = Some("sqlite-provider".to_string());
+        builder.cwd = external.path().join("workspace");
+        builder.cli_version = Some("sqlite-cli".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.preview = Some("optimize the benchmark".to_string());
+        metadata.first_user_message = Some("next normal prompt".to_string());
+        metadata.title = "next normal prompt".to_string();
+        metadata.model = Some("sqlite-model".to_string());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(rollout_path));
+        assert_eq!(thread.preview, "optimize the benchmark");
+        assert_eq!(
+            thread.first_user_message.as_deref(),
+            Some("next normal prompt")
+        );
+        assert_eq!(thread.name, None);
+        assert_eq!(thread.model_provider, "sqlite-provider");
+        assert_eq!(thread.model.as_deref(), Some("sqlite-model"));
+        assert_eq!(thread.cwd, external.path().join("workspace"));
+        assert_eq!(thread.cli_version, "sqlite-cli");
+        assert_eq!(thread.source, SessionSource::Exec);
+        assert_eq!(thread.archived_at, None);
+        assert!(thread.history.is_none());
+    }
+
+    #[tokio::test]
+    async fn read_thread_sqlite_fallback_respects_include_archived() {
+        let home = TempDir::new().expect("temp dir");
+        let external = TempDir::new().expect("external temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(216);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path = external
+            .path()
+            .join(format!("rollout-2025-01-03T12-00-00-{uuid}.jsonl"));
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let mut builder =
+            ThreadMetadataBuilder::new(thread_id, rollout_path, Utc::now(), SessionSource::Cli);
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        builder.archived_at = Some(Utc::now());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.first_user_message = Some("Archived SQLite preview".to_string());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let active_only_err = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect_err("active-only read should fail for archived metadata");
+        let ThreadStoreError::InvalidRequest { message } = active_only_err else {
+            panic!("expected invalid request error");
+        };
+        assert_eq!(
+            message,
+            format!("no rollout found for thread id {thread_id}")
+        );
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: true,
+                include_history: false,
+            })
+            .await
+            .expect("read archived thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.preview, "Archived SQLite preview");
+        assert!(thread.archived_at.is_some());
+    }
+
+    #[tokio::test]
+    async fn read_thread_sqlite_fallback_loads_archived_history() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(219);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T12-00-00", uuid)
+            .expect("archived session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let mut builder = ThreadMetadataBuilder::new(
+            thread_id,
+            archived_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.archived_at = Some(Utc::now());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.first_user_message = Some("Archived SQLite preview".to_string());
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: true,
+                include_history: true,
+            })
+            .await
+            .expect("read archived thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(archived_path));
+        assert_eq!(thread.preview, "Archived SQLite preview");
+        assert!(thread.archived_at.is_some());
+        let history = thread.history.expect("history should load");
+        assert_eq!(history.thread_id, thread_id);
+        assert_eq!(history.items.len(), 2);
+    }
+
+    #[tokio::test]
+    async fn read_thread_fails_without_rollout() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(206);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+
+        let err = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect_err("read should fail without rollout");
+
+        let ThreadStoreError::InvalidRequest { message } = err else {
+            panic!("expected invalid request error");
+        };
+        assert_eq!(
+            message,
+            format!("no rollout found for thread id {thread_id}")
+        );
+    }
+}
diff --git a/codex-rs/thread-store/src/local/revert_thread.rs b/codex-rs/thread-store/src/local/revert_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9f6e8f139d11563c64b552951a51a157aeb57b98
--- /dev/null
+++ b/codex-rs/thread-store/src/local/revert_thread.rs
@@ -0,0 +1,199 @@
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::RolloutRecorderParams;
+
+use super::LocalThreadStore;
+use super::paginated_fork;
+use super::thread_rollout_resolver;
+use crate::ForkBoundary;
+use crate::RevertThreadParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+/// Revert an unloaded paginated thread by creating a new immutable rollout file.
+///
+/// Old rollouts stay intact. The new file references the retained prefix, and the only mutable
+/// cutover is the existing SQLite rollout-path pointer for the thread.
+pub(super) async fn revert(
+    store: &LocalThreadStore,
+    params: RevertThreadParams,
+) -> ThreadStoreResult<()> {
+    let RevertThreadParams {
+        thread_id,
+        before_turn_id,
+        multi_agent_version,
+    } = params;
+    let state_db = store
+        .state_db()
+        .await
+        .ok_or(ThreadStoreError::Unsupported {
+            operation: "revert_thread",
+        })?;
+    let _lifecycle_guard = store.live_writer_locks.lock_lifecycle(thread_id).await;
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    store.ensure_live_recorder_absent(thread_id).await?;
+    let writer_lock = store.acquire_writer_lock(thread_id)?;
+
+    // Resolution may return a compressed sibling. Keep SQLite's exact stored path for the CAS.
+    let expected_sqlite_path = state_db
+        .get_thread(thread_id)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to read thread metadata for {thread_id}: {err}"),
+        })?
+        .ok_or(ThreadStoreError::ThreadNotFound { thread_id })?
+        .rollout_path;
+    let current_rollout = thread_rollout_resolver::resolve_current(store, thread_id)
+        .await?
+        .ok_or(ThreadStoreError::ThreadNotFound { thread_id })?;
+    let source_path = current_rollout.path;
+    let mut source_meta = codex_rollout::read_session_meta_line(source_path.as_path())
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!(
+                "failed to read current paginated rollout {}: {err}",
+                source_path.display()
+            ),
+        })?
+        .meta;
+    if source_meta.id != current_rollout.thread_id {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!("current rollout for {thread_id} belongs to another thread"),
+        });
+    }
+    if source_meta.history_mode != ThreadHistoryMode::Paginated {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!("thread {thread_id} does not use paginated history"),
+        });
+    }
+
+    // Preserve old-reader compatibility when introducing the first reference to a standalone
+    // source. Already-shared ancestors stay read-only; their offsets address decoded JSONL bytes.
+    let mut lineage = store.resolve_rollout_lineage(thread_id).await?;
+    for segment in &mut lineage.segments {
+        if segment.rollout_id() == current_rollout.rollout_id && source_meta.history_base.is_none()
+        {
+            segment.rollout_path =
+                codex_rollout::materialize_rollout_for_reference(segment.rollout_path.as_path())
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!(
+                            "failed to materialize rollout {} for revert: {err}",
+                            segment.rollout_path.display()
+                        ),
+                    })?;
+        }
+        super::thread_history_materialization::materialize_to_sqlite(
+            store,
+            segment.rollout_id(),
+            segment.rollout_path.as_path(),
+        )
+        .await?;
+    }
+    let history_base = paginated_fork::history_base_at_boundary(
+        store,
+        thread_id,
+        ForkBoundary::BeforeTurn(before_turn_id),
+        &lineage,
+    )
+    .await?;
+
+    let forked_from_ordinal_exclusive =
+        codex_rollout::forked_from_ordinal_exclusive(&source_meta, Some(source_path.as_path()))
+            .map(|cutoff| {
+                // Reverting into inherited history can shrink, but never grow, the parent prefix.
+                cutoff.min(history_base.map_or(0, |base| base.end_ordinal_exclusive))
+            });
+
+    source_meta.multi_agent_version = multi_agent_version.or(source_meta.multi_agent_version);
+    let rollout_id = ThreadId::new();
+    let recorder = create_replacement_recorder(
+        store,
+        source_meta,
+        rollout_id,
+        history_base,
+        forked_from_ordinal_exclusive,
+        writer_lock,
+    )
+    .await?;
+    let replacement_path = recorder.rollout_path().to_path_buf();
+    recorder.persist().await.map_err(thread_store_io_error)?;
+    recorder.shutdown().await.map_err(thread_store_io_error)?;
+
+    let replaced = state_db
+        .replace_rollout_path_if_current(
+            thread_id,
+            expected_sqlite_path.as_path(),
+            replacement_path.as_path(),
+        )
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to switch thread {thread_id} to reverted rollout: {err}"),
+        })?;
+    if !replaced {
+        let _ = tokio::fs::remove_file(replacement_path.as_path()).await;
+        return Err(ThreadStoreError::Conflict {
+            message: format!("thread {thread_id} changed while it was being reverted"),
+        });
+    }
+    Ok(())
+}
+
+async fn create_replacement_recorder(
+    store: &LocalThreadStore,
+    source_meta: codex_rollout::SessionMeta,
+    rollout_id: ThreadId,
+    history_base: Option<codex_protocol::protocol::HistoryPosition>,
+    forked_from_ordinal_exclusive: Option<u64>,
+    writer_lock: super::WriterLockGuard,
+) -> ThreadStoreResult<RolloutRecorder> {
+    let config = RolloutConfig {
+        codex_home: store.config.codex_home.clone(),
+        sqlite: store.config.sqlite.clone(),
+        cwd: source_meta.cwd.clone(),
+        model_provider_id: source_meta
+            .model_provider
+            .clone()
+            .unwrap_or_else(|| store.config.default_model_provider_id.clone()),
+        generate_memories: source_meta.memory_mode.as_deref() != Some("disabled"),
+    };
+    let mut params = RolloutRecorderParams::new(
+        source_meta.id,
+        source_meta.forked_from_id,
+        source_meta.parent_thread_id,
+        source_meta.source,
+        source_meta.thread_source,
+        source_meta.originator,
+        source_meta.base_instructions.unwrap_or_default(),
+        source_meta.dynamic_tools.unwrap_or_default(),
+    )
+    .with_session_id(source_meta.session_id)
+    .with_rollout_id(rollout_id)
+    .with_selected_capability_roots(source_meta.selected_capability_roots)
+    .with_runtime_workspace_roots(source_meta.runtime_workspace_roots)
+    .with_multi_agent_version(source_meta.multi_agent_version)
+    .with_history_mode(ThreadHistoryMode::Paginated)
+    .with_history_base(history_base)
+    .with_forked_from_ordinal_exclusive(forked_from_ordinal_exclusive)
+    .with_subagent_history_start_ordinal(source_meta.subagent_history_start_ordinal);
+    if let Some(context_window) = source_meta.context_window {
+        params = params.with_initial_window_id(context_window.window_id);
+    }
+    RolloutRecorder::new_with_writer_lock(&config, params, writer_lock)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to create reverted rollout: {err}"),
+        })
+}
+
+fn thread_store_io_error(err: std::io::Error) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: err.to_string(),
+    }
+}
+
+#[cfg(test)]
+#[path = "revert_thread_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/revert_thread_tests.rs b/codex-rs/thread-store/src/local/revert_thread_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0b27ac1b825871bf5fcb2fd6476a6c33900f63c0
--- /dev/null
+++ b/codex-rs/thread-store/src/local/revert_thread_tests.rs
@@ -0,0 +1,307 @@
+use codex_protocol::ThreadId;
+use codex_protocol::models::BaseInstructions;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::MultiAgentVersion;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_protocol::protocol::TurnCompleteEvent;
+use codex_protocol::protocol::TurnStartedEvent;
+use codex_rollout::RolloutItem;
+use codex_utils_absolute_path::test_support::PathExt;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::super::LocalThreadStore;
+use super::super::test_support::test_config;
+use crate::AppendThreadItemsParams;
+use crate::ArchiveThreadParams;
+use crate::CreateThreadParams;
+use crate::DeleteThreadParams;
+use crate::ListTurnsParams;
+use crate::RevertThreadParams;
+use crate::SortDirection;
+use crate::StoredTurnItemsView;
+use crate::ThreadPersistenceMetadata;
+use crate::ThreadStore;
+
+#[tokio::test]
+async fn revert_keeps_thread_id_and_hides_suffix_across_repeated_reverts() {
+    let home = TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let state_db = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("initialize state database");
+    let store = LocalThreadStore::new(config, Some(state_db.clone()));
+    let thread_id = ThreadId::new();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-1"),
+                turn_completed("turn-1"),
+                turn_started("turn-2"),
+                turn_completed("turn-2"),
+            ],
+        })
+        .await
+        .expect("append turns");
+    let original_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("source rollout path");
+    store
+        .shutdown_thread(thread_id)
+        .await
+        .expect("close source writer");
+    codex_rollout::state_db::reconcile_rollout(
+        Some(state_db.as_ref()),
+        original_path.as_path(),
+        "test-provider",
+        /*builder*/ None,
+        &[],
+        /*archived_only*/ Some(false),
+        /*new_thread_memory_mode*/ None,
+    )
+    .await;
+    compress_rollout(original_path.as_path());
+
+    store
+        .revert_thread(RevertThreadParams {
+            thread_id,
+            before_turn_id: "turn-2".to_string(),
+            multi_agent_version: None,
+        })
+        .await
+        .expect("revert before second turn");
+    let first_replacement_path = state_db
+        .get_thread(thread_id)
+        .await
+        .expect("read metadata")
+        .expect("thread metadata")
+        .rollout_path;
+    assert_ne!(first_replacement_path, original_path);
+    assert_ne!(
+        codex_rollout::rollout_id_from_path(first_replacement_path.as_path()),
+        Some(thread_id)
+    );
+    let replacement_meta = codex_rollout::read_session_meta_line(first_replacement_path.as_path())
+        .await
+        .expect("read replacement metadata")
+        .meta;
+    assert_eq!(replacement_meta.id, thread_id);
+    assert_eq!(replacement_meta.memory_mode, None);
+    assert_eq!(
+        replacement_meta.runtime_workspace_roots,
+        Some(vec![home.path().join("workspace")])
+    );
+    assert_eq!(turn_ids(&store, thread_id).await, vec!["turn-1"]);
+
+    store
+        .revert_thread(RevertThreadParams {
+            thread_id,
+            before_turn_id: "turn-1".to_string(),
+            multi_agent_version: None,
+        })
+        .await
+        .expect("revert before first turn");
+    assert_eq!(turn_ids(&store, thread_id).await, Vec::<String>::new());
+
+    store
+        .archive_thread(ArchiveThreadParams { thread_id })
+        .await
+        .expect("archive reverted thread");
+    assert!(
+        rollout_paths_for_thread(home.path(), thread_id)
+            .await
+            .iter()
+            .all(|path| path.starts_with(home.path().join("archived_sessions")))
+    );
+    store
+        .unarchive_thread(ArchiveThreadParams { thread_id })
+        .await
+        .expect("unarchive reverted thread");
+    let owned_rollout_paths = rollout_paths_for_thread(home.path(), thread_id).await;
+    assert_eq!(owned_rollout_paths.len(), 3);
+    assert!(
+        owned_rollout_paths
+            .iter()
+            .all(|path| path.starts_with(home.path().join("sessions")))
+    );
+
+    store
+        .delete_thread(DeleteThreadParams { thread_id })
+        .await
+        .expect("delete reverted thread");
+    for rollout_path in owned_rollout_paths {
+        assert!(!rollout_path.exists());
+    }
+}
+
+#[tokio::test]
+async fn revert_preserves_resolved_multi_agent_version_in_session_metadata() {
+    let home = TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let state_db = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("initialize state database");
+    let store = LocalThreadStore::new(config, Some(state_db.clone()));
+
+    for version in [
+        MultiAgentVersion::V1,
+        MultiAgentVersion::V2,
+        MultiAgentVersion::Disabled,
+    ] {
+        let thread_id = ThreadId::new();
+        create_paginated_thread(&store, thread_id).await;
+        store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![
+                    turn_started("turn-1"),
+                    turn_completed("turn-1"),
+                    turn_started("turn-2"),
+                    turn_completed("turn-2"),
+                ],
+            })
+            .await
+            .expect("append turns");
+        let path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("source rollout path");
+        store
+            .shutdown_thread(thread_id)
+            .await
+            .expect("close source writer");
+        codex_rollout::state_db::reconcile_rollout(
+            Some(state_db.as_ref()),
+            path.as_path(),
+            "test-provider",
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ Some(false),
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+
+        // The second revert has no live version to supply and must keep the persisted one.
+        for (before_turn_id, multi_agent_version) in [("turn-2", Some(version)), ("turn-1", None)] {
+            store
+                .revert_thread(RevertThreadParams {
+                    thread_id,
+                    before_turn_id: before_turn_id.to_string(),
+                    multi_agent_version,
+                })
+                .await
+                .expect("revert thread");
+            let path = state_db
+                .get_thread(thread_id)
+                .await
+                .expect("read metadata")
+                .expect("thread metadata")
+                .rollout_path;
+            let meta = codex_rollout::read_session_meta_line(&path)
+                .await
+                .expect("read replacement metadata");
+            assert_eq!(meta.meta.multi_agent_version, Some(version));
+        }
+    }
+}
+
+async fn rollout_paths_for_thread(
+    home: &std::path::Path,
+    thread_id: ThreadId,
+) -> Vec<std::path::PathBuf> {
+    codex_rollout::RolloutReferenceIndex::scan(home)
+        .await
+        .expect("scan rollout references")
+        .rollouts_for_thread(thread_id)
+        .map(|(_, path)| path.to_path_buf())
+        .collect()
+}
+
+async fn create_paginated_thread(store: &LocalThreadStore, thread_id: ThreadId) {
+    store
+        .create_thread(CreateThreadParams {
+            session_id: thread_id.into(),
+            thread_id,
+            extra_config: None,
+            forked_from_id: None,
+            parent_thread_id: None,
+            source: SessionSource::Exec,
+            thread_source: None,
+            originator: "test_originator".to_string(),
+            base_instructions: BaseInstructions::default(),
+            dynamic_tools: Vec::new(),
+            selected_capability_roots: Vec::new(),
+            multi_agent_version: None,
+            history_mode: ThreadHistoryMode::Paginated,
+            history_base: None,
+            subagent_history_start_ordinal: None,
+            initial_window_id: "window-1".to_string(),
+            runtime_workspace_roots: Some(vec![store.config.codex_home.join("workspace").abs()]),
+            metadata: ThreadPersistenceMetadata {
+                cwd: Some(std::env::current_dir().expect("cwd")),
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        })
+        .await
+        .expect("create paginated thread");
+}
+
+async fn turn_ids(store: &LocalThreadStore, thread_id: ThreadId) -> Vec<String> {
+    store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::NotLoaded,
+        })
+        .await
+        .expect("list turns")
+        .turns
+        .into_iter()
+        .map(|turn| turn.turn_id)
+        .collect()
+}
+
+fn turn_started(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnStarted(TurnStartedEvent {
+        turn_id: turn_id.to_string(),
+        root_turn_id: None,
+        trace_id: None,
+        started_at: Some(10),
+        model_context_window: None,
+        collaboration_mode_kind: Default::default(),
+    }))
+}
+
+fn turn_completed(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnComplete(TurnCompleteEvent {
+        turn_id: turn_id.to_string(),
+        last_agent_message: None,
+        error: None,
+        started_at: Some(10),
+        completed_at: Some(20),
+        duration_ms: Some(10_000),
+        time_to_first_token_ms: None,
+    }))
+}
+
+fn compress_rollout(path: &std::path::Path) {
+    let contents = std::fs::read(path).expect("read rollout");
+    let compressed = zstd::stream::encode_all(contents.as_slice(), 3).expect("compress rollout");
+    std::fs::write(path.with_extension("jsonl.zst"), compressed).expect("write compressed rollout");
+    std::fs::remove_file(path).expect("remove plain rollout");
+}
diff --git a/codex-rs/thread-store/src/local/rollout_lineage.rs b/codex-rs/thread-store/src/local/rollout_lineage.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ae3e1bec62f9fa24b20348afc3b9fc638760c6f6
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_lineage.rs
@@ -0,0 +1,304 @@
+use std::collections::HashSet;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::ThreadHistoryMode;
+
+use super::LocalThreadStore;
+use super::thread_rollout_resolver;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+/// One immutable rollout range contributing to a paginated thread's history.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct RolloutLineageSegment {
+    pub(super) rollout_id: ThreadId,
+    pub(super) rollout_path: PathBuf,
+    pub(super) start_ordinal: u64,
+    pub(super) end: Option<HistoryPosition>,
+}
+
+/// Ordered rollout ranges contributing to one forked history.
+///
+/// This is the only local abstraction that follows SessionMeta.history_base pointers. Readers
+/// consume its bounded rollout segments without resolving or mutating fork pointers themselves.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct RolloutLineage {
+    pub(super) segments: Vec<RolloutLineageSegment>,
+}
+
+impl LocalThreadStore {
+    pub(super) async fn resolve_rollout_lineage(
+        &self,
+        requested_thread_id: ThreadId,
+    ) -> ThreadStoreResult<RolloutLineage> {
+        self.resolve_rollout_lineage_with_representation(
+            requested_thread_id,
+            LineageRepresentation::Existing,
+        )
+        .await
+    }
+
+    pub(super) async fn resolve_rollout_lineage_for_reference(
+        &self,
+        requested_thread_id: ThreadId,
+    ) -> ThreadStoreResult<RolloutLineage> {
+        self.resolve_rollout_lineage_with_representation(
+            requested_thread_id,
+            LineageRepresentation::PlainForReference,
+        )
+        .await
+    }
+
+    async fn resolve_rollout_lineage_with_representation(
+        &self,
+        requested_thread_id: ThreadId,
+        representation: LineageRepresentation,
+    ) -> ThreadStoreResult<RolloutLineage> {
+        let mut segments = Vec::new();
+        let mut seen = HashSet::new();
+        let mut next_rollout_id = None;
+        let mut end = None;
+
+        loop {
+            let coordination_id = next_rollout_id.unwrap_or(requested_thread_id);
+            let _writer_guard = match representation {
+                LineageRepresentation::Existing => None,
+                LineageRepresentation::PlainForReference => {
+                    Some(self.live_writer_locks.lock(coordination_id).await)
+                }
+            };
+            let (rollout_id, rollout_path) = match next_rollout_id {
+                Some(rollout_id) => {
+                    let rollout_path = resolve_rollout_path_by_id(self, rollout_id)
+                        .await?
+                        .ok_or_else(|| malformed_lineage(rollout_id, "missing source rollout"))?;
+                    (rollout_id, rollout_path)
+                }
+                None => {
+                    let resolved = thread_rollout_resolver::resolve_current_including_archived(
+                        self,
+                        requested_thread_id,
+                    )
+                    .await?
+                    .ok_or_else(|| {
+                        malformed_lineage(requested_thread_id, "missing source rollout")
+                    })?;
+                    (resolved.rollout_id, resolved.path)
+                }
+            };
+            if !seen.insert(rollout_id) {
+                return Err(malformed_lineage(requested_thread_id, "cycle detected"));
+            }
+            let rollout_path = match representation {
+                LineageRepresentation::Existing => rollout_path,
+                LineageRepresentation::PlainForReference => {
+                    let outside_codex_home = || ThreadStoreError::InvalidRequest {
+                        message: format!(
+                            "rollout path `{}` must be in Codex home directory",
+                            rollout_path.display()
+                        ),
+                    };
+                    let canonical_rollout_path = std::fs::canonicalize(rollout_path.as_path())
+                        .map_err(|_| outside_codex_home())?;
+                    // Resume can retain either the logical Codex home path or its canonical
+                    // target. Keep references inside canonical managed roots so nested symlinks
+                    // cannot escape them.
+                    let is_managed_rollout = [
+                        self.config.codex_home.join(codex_rollout::SESSIONS_SUBDIR),
+                        self.config
+                            .codex_home
+                            .join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR),
+                    ]
+                    .into_iter()
+                    .filter_map(|root| std::fs::canonicalize(root).ok())
+                    .any(|root| canonical_rollout_path.starts_with(root));
+                    if !is_managed_rollout {
+                        return Err(outside_codex_home());
+                    }
+                    canonical_rollout_path
+                }
+            };
+            let meta = codex_rollout::read_session_meta_line(rollout_path.as_path())
+                .await
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!(
+                        "failed to read lineage metadata {}: {err}",
+                        rollout_path.display()
+                    ),
+                })?;
+            if next_rollout_id.is_none() && meta.meta.id != requested_thread_id {
+                return Err(malformed_lineage(
+                    requested_thread_id,
+                    "source rollout belongs to another thread",
+                ));
+            }
+            if meta.meta.history_mode != ThreadHistoryMode::Paginated {
+                return Err(malformed_lineage(
+                    requested_thread_id,
+                    "source rollout is not paginated",
+                ));
+            }
+            let rollout_path = match representation {
+                LineageRepresentation::Existing => rollout_path,
+                LineageRepresentation::PlainForReference
+                    if next_rollout_id.is_none() && meta.meta.history_base.is_none() =>
+                {
+                    // A newly shared standalone source must remain readable by older binaries.
+                    codex_rollout::materialize_rollout_for_reference(rollout_path.as_path())
+                        .await
+                        .map_err(|err| ThreadStoreError::Internal {
+                            message: format!(
+                                "failed to materialize referenced rollout {}: {err}",
+                                rollout_path.display()
+                            ),
+                        })?
+                }
+                // Already-shared compressed history requires a compatible reader regardless of
+                // new forks. Read it without publishing decoded copies into ancestors' folders;
+                // their owners may concurrently archive or unarchive those immutable files.
+                LineageRepresentation::PlainForReference => rollout_path,
+            };
+            if let Some(end) = end {
+                validate_cutoff_bounds(requested_thread_id, rollout_path.as_path(), &end).await?;
+            }
+            let start_ordinal = match meta.meta.history_base {
+                Some(base) => base.end_ordinal_exclusive.checked_add(1).ok_or_else(|| {
+                    malformed_lineage(requested_thread_id, "source ordinal overflow")
+                })?,
+                None => 1,
+            };
+            segments.push(RolloutLineageSegment {
+                rollout_id,
+                rollout_path,
+                start_ordinal,
+                end,
+            });
+
+            let Some(base) = meta.meta.history_base else {
+                break;
+            };
+            next_rollout_id = Some(base.thread_id);
+            end = Some(base);
+        }
+
+        segments.reverse();
+        Ok(RolloutLineage { segments })
+    }
+}
+
+async fn resolve_rollout_path_by_id(
+    store: &LocalThreadStore,
+    rollout_id: ThreadId,
+) -> ThreadStoreResult<Option<PathBuf>> {
+    codex_rollout::find_rollout_path_by_rollout_id(store.config.codex_home.as_path(), rollout_id)
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to locate rollout {rollout_id}: {err}"),
+        })
+}
+
+#[derive(Clone, Copy)]
+enum LineageRepresentation {
+    Existing,
+    PlainForReference,
+}
+
+impl RolloutLineage {
+    pub(super) fn segments(&self) -> &[RolloutLineageSegment] {
+        self.segments.as_slice()
+    }
+
+    pub(super) fn segment_index_for_ordinal(&self, ordinal: u64) -> Option<usize> {
+        self.segments.iter().position(|segment| {
+            ordinal >= segment.start_ordinal()
+                && segment
+                    .end_ordinal()
+                    .is_none_or(|end_ordinal| ordinal < end_ordinal)
+        })
+    }
+
+    pub(super) async fn truncate_at(
+        mut self,
+        end: HistoryPosition,
+    ) -> ThreadStoreResult<RolloutLineage> {
+        let segment_index = self
+            .segments
+            .iter()
+            .position(|segment| segment.rollout_id == end.thread_id)
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: "fork position is outside the source lineage".to_string(),
+            })?;
+        self.segments.truncate(segment_index + 1);
+        let segment = self
+            .segments
+            .last_mut()
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: "rollout lineage has no segments".to_string(),
+            })?;
+        validate_cutoff_bounds(end.thread_id, segment.rollout_path.as_path(), &end).await?;
+        segment.end = Some(end);
+        Ok(self)
+    }
+}
+
+impl RolloutLineageSegment {
+    pub(super) fn rollout_id(&self) -> ThreadId {
+        self.rollout_id
+    }
+
+    pub(super) fn start_ordinal(&self) -> u64 {
+        self.start_ordinal
+    }
+
+    pub(super) fn end_ordinal(&self) -> Option<u64> {
+        self.end.map(|end| end.end_ordinal_exclusive)
+    }
+}
+
+async fn validate_cutoff_bounds(
+    requested_thread_id: ThreadId,
+    rollout_path: &Path,
+    end: &HistoryPosition,
+) -> ThreadStoreResult<()> {
+    if end.end_ordinal_exclusive == 0 {
+        return Err(malformed_lineage(
+            requested_thread_id,
+            "cutoff cannot include source session metadata",
+        ));
+    }
+    let path = rollout_path.to_path_buf();
+    let end_byte_offset = end.end_byte_offset;
+    let contains_prefix = tokio::task::spawn_blocking(move || {
+        codex_rollout::rollout_contains_prefix(&path, end_byte_offset)
+    })
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to join rollout prefix validation: {err}"),
+    })?
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!(
+            "failed to read lineage metadata {}: {err}",
+            rollout_path.display()
+        ),
+    })?;
+    if !contains_prefix {
+        return Err(malformed_lineage(
+            requested_thread_id,
+            "cutoff byte offset is past the source rollout",
+        ));
+    }
+    Ok(())
+}
+
+fn malformed_lineage(thread_id: ThreadId, detail: &str) -> ThreadStoreError {
+    ThreadStoreError::InvalidRequest {
+        message: format!("invalid paginated history lineage for {thread_id}: {detail}"),
+    }
+}
+
+#[cfg(test)]
+#[path = "rollout_lineage_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/rollout_lineage_tests.rs b/codex-rs/thread-store/src/local/rollout_lineage_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6b8c88d118e88f312af4a9810d7f91ce6122f357
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_lineage_tests.rs
@@ -0,0 +1,347 @@
+use std::fs;
+use std::path::Path;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::SessionMeta;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::super::LocalThreadStore;
+use super::super::test_support::test_config;
+use super::RolloutLineageSegment;
+
+#[cfg(unix)]
+#[tokio::test]
+async fn rejects_reference_lineage_escaping_symlinked_sessions_root() {
+    let home = TempDir::new().expect("temp dir");
+    let external = TempDir::new().expect("external temp dir");
+    let external_sessions = external.path().join("sessions");
+    fs::create_dir_all(external_sessions.as_path()).expect("create external sessions");
+    std::os::unix::fs::symlink(external_sessions.as_path(), home.path().join("sessions"))
+        .expect("symlink sessions");
+    let escaped = TempDir::new().expect("escaped temp dir");
+    let escaped_rollouts = escaped.path().join("rollouts");
+    fs::create_dir_all(escaped_rollouts.as_path()).expect("create escaped rollouts");
+    std::os::unix::fs::symlink(escaped_rollouts.as_path(), external_sessions.join("2026"))
+        .expect("symlink nested sessions directory");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let thread_id = ThreadId::default();
+    write_rollout(
+        home.path(),
+        thread_id,
+        /*history_base*/ None,
+        /*next_ordinal*/ 3,
+    );
+
+    let error = store
+        .resolve_rollout_lineage_for_reference(thread_id)
+        .await
+        .expect_err("escaping reference lineage should be rejected");
+
+    assert!(error.to_string().contains("must be in Codex home"));
+}
+
+#[tokio::test]
+async fn resolves_nested_lineage_with_empty_intermediate_segments() {
+    let home = TempDir::new().expect("temp dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let root = ThreadId::default();
+    let middle = ThreadId::default();
+    let child = ThreadId::default();
+    let root_path = write_rollout(
+        home.path(),
+        root,
+        /*history_base*/ None,
+        /*next_ordinal*/ 6,
+    );
+    let root_end = history_position(root_path.as_path(), root, /*end_ordinal_exclusive*/ 4);
+    let middle_path = write_rollout(home.path(), middle, Some(root_end), /*next_ordinal*/ 1);
+    let middle_end = history_position(
+        middle_path.as_path(),
+        middle,
+        /*end_ordinal_exclusive*/ 5,
+    );
+    let child_path = write_rollout(
+        home.path(),
+        child,
+        Some(middle_end),
+        /*next_ordinal*/ 3,
+    );
+
+    let lineage = store
+        .resolve_rollout_lineage(child)
+        .await
+        .expect("resolve nested lineage");
+
+    assert_eq!(
+        lineage.segments,
+        vec![
+            RolloutLineageSegment {
+                rollout_id: root,
+                rollout_path: root_path.clone(),
+                start_ordinal: 1,
+                end: Some(root_end),
+            },
+            RolloutLineageSegment {
+                rollout_id: middle,
+                rollout_path: middle_path.clone(),
+                start_ordinal: 5,
+                end: Some(middle_end),
+            },
+            RolloutLineageSegment {
+                rollout_id: child,
+                rollout_path: child_path,
+                start_ordinal: 6,
+                end: None,
+            },
+        ]
+    );
+}
+
+#[tokio::test]
+async fn resolves_archived_ancestors() {
+    let home = TempDir::new().expect("temp dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let root = ThreadId::default();
+    let child = ThreadId::default();
+    let root_path = write_rollout_under(
+        home.path().join("archived_sessions"),
+        root,
+        /*history_base*/ None,
+        /*next_ordinal*/ 3,
+    );
+    write_rollout(
+        home.path(),
+        child,
+        Some(history_position(
+            root_path.as_path(),
+            root,
+            /*end_ordinal_exclusive*/ 3,
+        )),
+        /*next_ordinal*/ 2,
+    );
+
+    let lineage = store
+        .resolve_rollout_lineage(child)
+        .await
+        .expect("resolve archived ancestor");
+
+    assert_eq!(lineage.segments[0].rollout_path, root_path);
+}
+
+#[tokio::test]
+async fn resolves_lineage_at_explicit_history_position() {
+    let home = TempDir::new().expect("temp dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let root = ThreadId::default();
+    let child = ThreadId::default();
+    let root_path = write_rollout(
+        home.path(),
+        root,
+        /*history_base*/ None,
+        /*next_ordinal*/ 6,
+    );
+    let root_end = history_position(root_path.as_path(), root, /*end_ordinal_exclusive*/ 4);
+    let child_path = write_rollout(home.path(), child, Some(root_end), /*next_ordinal*/ 4);
+    let end = history_position(
+        child_path.as_path(),
+        child,
+        /*end_ordinal_exclusive*/ 6,
+    );
+
+    let lineage = store
+        .resolve_rollout_lineage(child)
+        .await
+        .expect("resolve child lineage")
+        .truncate_at(end)
+        .await
+        .expect("resolve explicit position");
+
+    assert_eq!(
+        lineage.segments,
+        vec![
+            RolloutLineageSegment {
+                rollout_id: root,
+                rollout_path: root_path.clone(),
+                start_ordinal: 1,
+                end: Some(root_end),
+            },
+            RolloutLineageSegment {
+                rollout_id: child,
+                rollout_path: child_path.clone(),
+                start_ordinal: 5,
+                end: Some(end),
+            },
+        ]
+    );
+}
+
+#[tokio::test]
+async fn rejects_missing_cycles_and_out_of_bounds_offsets() {
+    let home = TempDir::new().expect("temp dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let missing_parent = ThreadId::default();
+    let missing_child = ThreadId::default();
+    write_rollout(
+        home.path(),
+        missing_child,
+        Some(unchecked_history_position(
+            missing_parent,
+            /*end_ordinal_exclusive*/ 1,
+        )),
+        /*next_ordinal*/ 2,
+    );
+    assert_invalid_lineage(&store, missing_child, "missing source rollout").await;
+
+    let cycle_a = ThreadId::default();
+    let cycle_b = ThreadId::default();
+    write_rollout(
+        home.path(),
+        cycle_a,
+        Some(unchecked_history_position(
+            cycle_b, /*end_ordinal_exclusive*/ 1,
+        )),
+        /*next_ordinal*/ 2,
+    );
+    write_rollout(
+        home.path(),
+        cycle_b,
+        Some(unchecked_history_position(
+            cycle_a, /*end_ordinal_exclusive*/ 1,
+        )),
+        /*next_ordinal*/ 2,
+    );
+    assert_invalid_lineage(&store, cycle_a, "cycle detected").await;
+
+    let root = ThreadId::default();
+    let invalid_child = ThreadId::default();
+    let root_path = write_rollout(
+        home.path(),
+        root,
+        /*history_base*/ None,
+        /*next_ordinal*/ 2,
+    );
+    write_rollout(
+        home.path(),
+        invalid_child,
+        Some(HistoryPosition {
+            thread_id: root,
+            end_ordinal_exclusive: 2,
+            end_byte_offset: fs::metadata(root_path).expect("root metadata").len() + 1,
+        }),
+        /*next_ordinal*/ 2,
+    );
+    assert_invalid_lineage(
+        &store,
+        invalid_child,
+        "cutoff byte offset is past the source rollout",
+    )
+    .await;
+}
+
+async fn assert_invalid_lineage(store: &LocalThreadStore, thread_id: ThreadId, detail: &str) {
+    let err = store
+        .resolve_rollout_lineage(thread_id)
+        .await
+        .expect_err("lineage should be invalid");
+    assert!(err.to_string().contains(detail), "{err}");
+}
+
+fn write_rollout(
+    home: &Path,
+    thread_id: ThreadId,
+    history_base: Option<HistoryPosition>,
+    next_ordinal: u64,
+) -> std::path::PathBuf {
+    write_rollout_under(
+        home.join("sessions/2026/07/16"),
+        thread_id,
+        history_base,
+        next_ordinal,
+    )
+}
+
+fn write_rollout_under(
+    directory: std::path::PathBuf,
+    thread_id: ThreadId,
+    history_base: Option<HistoryPosition>,
+    next_ordinal: u64,
+) -> std::path::PathBuf {
+    fs::create_dir_all(directory.as_path()).expect("create rollout directory");
+    let path = directory.join(format!("rollout-2026-07-16T00-00-00-{thread_id}.jsonl"));
+    let initial_ordinal = history_base.map_or(0, |base| base.end_ordinal_exclusive);
+    let mut lines = vec![rollout_line(
+        initial_ordinal,
+        RolloutItem::SessionMeta(SessionMetaLine {
+            meta: SessionMeta {
+                session_id: thread_id.into(),
+                id: thread_id,
+                history_mode: ThreadHistoryMode::Paginated,
+                history_base,
+                ..SessionMeta::default()
+            },
+            git: None,
+        }),
+    )];
+    for offset in 1..next_ordinal {
+        let ordinal = initial_ordinal
+            .checked_add(offset)
+            .expect("fixture ordinal");
+        lines.push(rollout_line(
+            ordinal,
+            RolloutItem::EventMsg(codex_protocol::protocol::EventMsg::ShutdownComplete),
+        ));
+    }
+    fs::write(path.as_path(), format!("{}\n", lines.join("\n"))).expect("write rollout");
+    path
+}
+
+fn rollout_line(ordinal: u64, item: RolloutItem) -> String {
+    serde_json::to_string(&RolloutLine {
+        timestamp: "2026-07-16T00:00:00.000Z".to_string(),
+        ordinal: Some(ordinal),
+        item,
+    })
+    .expect("serialize rollout line")
+}
+
+fn history_position(
+    path: &Path,
+    thread_id: ThreadId,
+    end_ordinal_exclusive: u64,
+) -> HistoryPosition {
+    HistoryPosition {
+        thread_id,
+        end_ordinal_exclusive,
+        end_byte_offset: rollout_end_byte_offset(path, end_ordinal_exclusive),
+    }
+}
+
+fn rollout_end_byte_offset(path: &Path, end_ordinal_exclusive: u64) -> u64 {
+    let bytes = fs::read(path).expect("read rollout");
+    let end_byte_offset = bytes
+        .split_inclusive(|byte| *byte == b'\n')
+        .take_while(|line| {
+            codex_rollout::parse_rollout_line_bytes(line)
+                .expect("parse rollout fixture")
+                .ordinal
+                .expect("paginated rollout ordinal")
+                < end_ordinal_exclusive
+        })
+        .map(<[u8]>::len)
+        .sum::<usize>();
+    u64::try_from(end_byte_offset).expect("rollout byte offset fits u64")
+}
+
+fn unchecked_history_position(thread_id: ThreadId, end_ordinal_exclusive: u64) -> HistoryPosition {
+    HistoryPosition {
+        thread_id,
+        end_ordinal_exclusive,
+        end_byte_offset: 0,
+    }
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration.rs b/codex-rs/thread-store/src/local/rollout_migration.rs
new file mode 100644
index 0000000000000000000000000000000000000000..59eaede0163ea29466b6aaa068cd78b5338b270b
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration.rs
@@ -0,0 +1,1387 @@
+//! Orchestrates legacy rollout migration into paginated history.
+//!
+//! This is the high-level migration state machine: find rollout files, decide whether each one is
+//! eligible, take the maintenance and writer locks, canonicalize into a staged JSONL file,
+//! project that staged file into SQLite, verify the projection, then atomically publish it.
+//!
+//! The important invariant is that we always leave behind either the original legacy rollout or a
+//! recoverable paginated rollout. Once the rollout path is replaced, the durable `.pending`
+//! journal must be enough for a later migration run to finish SQLite recovery safely.
+
+use std::collections::HashMap;
+use std::io;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use chrono::DateTime;
+use codex_app_server_protocol::project_rollout_line;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::InternalSessionSource;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::SubAgentSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadSource;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use serde::Serialize;
+use tokio::fs::File;
+use tokio::io::AsyncBufReadExt;
+use tokio::io::AsyncReadExt;
+use tokio::io::AsyncWriteExt;
+use tokio::io::BufReader;
+use tokio::io::BufWriter;
+use tokio::time::Instant;
+
+use super::LocalThreadStore;
+use super::helpers::distinct_thread_metadata_title;
+use super::thread_history;
+use super::thread_history::ProjectedRolloutLine;
+use super::thread_history::RolloutProjectionStep;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+mod canonicalizer;
+mod legacy_event;
+mod line_parser;
+mod publish;
+mod rollback;
+mod rollback_plan;
+mod rollback_replay;
+mod startup;
+mod subagent;
+mod telemetry;
+
+use canonicalizer::LegacyRolloutCanonicalizer;
+use publish::compress_rollout_to_path;
+use publish::compressed_staged_rollout_path;
+use publish::decompress_rollout_to_path;
+use publish::decompressed_staged_rollout_path;
+use publish::migration_journal_path;
+use publish::pending_migration_thread_ids;
+use publish::remove_file_if_present;
+use publish::rewrite_subagent_history_boundary;
+use publish::rewritten_staged_rollout_path;
+use publish::staged_rollout_path;
+use publish::sync_parent_directory;
+use publish::write_migration_journal;
+use rollback_plan::RollbackPlan;
+use rollback_plan::RollbackPlanner;
+use telemetry::RolloutMigrationTelemetry;
+use telemetry::RolloutMigrationTrigger;
+
+const PROJECTION_BATCH_BYTES: u64 = 256 * 1024;
+const MAX_ROLLOUT_LINE_BYTES: usize = 16 * 1024 * 1024;
+
+enum CanonicalizationAttempt {
+    Complete {
+        expected_length: u64,
+        expected_ordinal: u64,
+    },
+    NeedsRollbackPlan,
+}
+
+enum RolloutMigrationPaths {
+    Discover,
+    Known(Vec<PathBuf>),
+}
+
+struct CanonicalizationSource<'a> {
+    thread_id: ThreadId,
+    source_path: &'a Path,
+    staged_path: &'a Path,
+    source_permissions: &'a std::fs::Permissions,
+    canonical_session_meta: &'a RolloutLine,
+}
+
+/// Controls whether eligible rollouts are reported or migrated.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RolloutMigrationMode {
+    /// Report eligible files without modifying local storage.
+    #[default]
+    DryRun,
+    /// Publish paginated rollouts and materialize their SQLite history.
+    Apply,
+}
+
+/// Selection and throughput limits for a local rollout migration.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RolloutMigrationOptions {
+    pub mode: RolloutMigrationMode,
+    pub thread_ids: Vec<ThreadId>,
+    /// Optional aggregate rollout I/O limit. Without one, migration runs as fast as local I/O
+    /// allows while still yielding between projection-sized batches.
+    pub max_mib_per_second: Option<u64>,
+}
+
+impl Default for RolloutMigrationOptions {
+    fn default() -> Self {
+        Self {
+            mode: RolloutMigrationMode::DryRun,
+            thread_ids: Vec::new(),
+            max_mib_per_second: None,
+        }
+    }
+}
+
+/// The observable result of inspecting one local rollout.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RolloutMigrationStatus {
+    Eligible,
+    Migrated,
+    AlreadyPaginated,
+    SkippedEmpty,
+    SkippedBusy,
+    Failed,
+}
+
+/// A bounded explanation for why one rollout migration failed.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RolloutMigrationFailureReason {
+    MissingSqliteMetadata,
+    InvalidSessionMetadata,
+    RolloutReadFailed,
+    LegacyRolloutConversionFailed,
+    SqliteMaterializationFailed,
+    RolloutPublishFailed,
+    InterruptedMigrationRecoveryFailed,
+    Unknown,
+}
+
+/// The per-thread result of a rollout migration run.
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+pub struct RolloutMigrationOutcome {
+    pub thread_id: Option<ThreadId>,
+    pub rollout_path: PathBuf,
+    pub status: RolloutMigrationStatus,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub failure_reason: Option<RolloutMigrationFailureReason>,
+    pub bytes_processed: u64,
+    pub message: Option<String>,
+}
+
+/// The complete result of scanning active rollout files.
+#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
+pub struct RolloutMigrationReport {
+    pub outcomes: Vec<RolloutMigrationOutcome>,
+}
+
+/// Incremental progress emitted while rollout migration scans discovered paths.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct RolloutMigrationProgress {
+    pub processed_paths: usize,
+    pub total_paths: usize,
+    /// None means the scanned path was excluded by the requested thread filter.
+    pub outcome_status: Option<RolloutMigrationStatus>,
+}
+
+struct RolloutMigrationRateLimiter {
+    started_at: Instant,
+    bytes_processed: u64,
+    bytes_per_second: Option<u64>,
+    bytes_since_yield: u64,
+}
+
+struct RolloutRecord {
+    line: Option<RolloutLine>,
+    byte_count: u64,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum RolloutMigrationKind {
+    Ordinary,
+    Subagent,
+}
+
+struct RolloutMigrationFailure {
+    reason: RolloutMigrationFailureReason,
+    error: ThreadStoreError,
+}
+
+impl RolloutMigrationFailure {
+    fn new(reason: RolloutMigrationFailureReason, error: ThreadStoreError) -> Self {
+        Self { reason, error }
+    }
+}
+
+type ClassifiedMigrationResult<T> = Result<T, RolloutMigrationFailure>;
+
+fn with_failure_reason<T>(
+    result: ThreadStoreResult<T>,
+    reason: RolloutMigrationFailureReason,
+) -> ClassifiedMigrationResult<T> {
+    result.map_err(|error| RolloutMigrationFailure::new(reason, error))
+}
+
+impl RolloutMigrationRateLimiter {
+    fn new(max_mib_per_second: Option<u64>) -> ThreadStoreResult<Self> {
+        let bytes_per_second = max_mib_per_second
+            .map(|rate| {
+                rate.checked_mul(1024 * 1024)
+                    .filter(|rate| *rate > 0)
+                    .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                        message: "--max-mib-per-second must be a positive supported integer"
+                            .to_string(),
+                    })
+            })
+            .transpose()?;
+        Ok(Self {
+            started_at: Instant::now(),
+            bytes_processed: 0,
+            bytes_per_second,
+            bytes_since_yield: 0,
+        })
+    }
+
+    async fn account(&mut self, bytes: u64) {
+        self.bytes_processed = self.bytes_processed.saturating_add(bytes);
+        self.bytes_since_yield = self.bytes_since_yield.saturating_add(bytes);
+        if self.bytes_since_yield < PROJECTION_BATCH_BYTES {
+            return;
+        }
+        self.bytes_since_yield = 0;
+        let Some(bytes_per_second) = self.bytes_per_second else {
+            tokio::task::yield_now().await;
+            return;
+        };
+        let expected =
+            Duration::from_secs_f64(self.bytes_processed as f64 / bytes_per_second as f64);
+        if let Some(remaining) = expected.checked_sub(self.started_at.elapsed()) {
+            tokio::time::sleep(remaining).await;
+        } else {
+            tokio::task::yield_now().await;
+        }
+    }
+}
+
+impl LocalThreadStore {
+    /// Check whether startup needs to migrate legacy rollouts, then migrate in the background
+    /// when it does.
+    pub async fn migrate_rollouts_on_startup(&self) -> ThreadStoreResult<()> {
+        startup::migrate_rollouts_on_startup(self).await
+    }
+
+    /// Inspect or migrate eligible legacy rollout files beneath active and archived sessions.
+    pub async fn migrate_rollouts(
+        &self,
+        options: RolloutMigrationOptions,
+    ) -> ThreadStoreResult<RolloutMigrationReport> {
+        self.migrate_rollouts_with_progress_for_trigger(
+            options,
+            |_| {},
+            RolloutMigrationTrigger::Manual,
+            RolloutMigrationPaths::Discover,
+        )
+        .await
+    }
+
+    /// Inspect or migrate rollouts while reporting each discovered path after it is processed.
+    pub async fn migrate_rollouts_with_progress(
+        &self,
+        options: RolloutMigrationOptions,
+        on_progress: impl FnMut(RolloutMigrationProgress),
+    ) -> ThreadStoreResult<RolloutMigrationReport> {
+        self.migrate_rollouts_with_progress_for_trigger(
+            options,
+            on_progress,
+            RolloutMigrationTrigger::Manual,
+            RolloutMigrationPaths::Discover,
+        )
+        .await
+    }
+
+    async fn migrate_rollouts_with_progress_for_trigger(
+        &self,
+        options: RolloutMigrationOptions,
+        mut on_progress: impl FnMut(RolloutMigrationProgress),
+        trigger: RolloutMigrationTrigger,
+        paths: RolloutMigrationPaths,
+    ) -> ThreadStoreResult<RolloutMigrationReport> {
+        let telemetry = RolloutMigrationTelemetry::new(trigger, &options);
+        let result = self
+            .migrate_rollouts_with_progress_inner(options, &mut on_progress, paths)
+            .await;
+        telemetry.finish(&result);
+        result
+    }
+
+    async fn migrate_rollouts_with_progress_inner(
+        &self,
+        options: RolloutMigrationOptions,
+        on_progress: &mut impl FnMut(RolloutMigrationProgress),
+        paths: RolloutMigrationPaths,
+    ) -> ThreadStoreResult<RolloutMigrationReport> {
+        let mut limiter = RolloutMigrationRateLimiter::new(options.max_mib_per_second)?;
+        let _maintenance_guard = match options.mode {
+            RolloutMigrationMode::DryRun => None,
+            RolloutMigrationMode::Apply => Some(
+                codex_rollout::try_acquire_rollout_maintenance_lock(&self.config.codex_home)
+                    .map_err(migration_error)?
+                    .ok_or_else(|| ThreadStoreError::Conflict {
+                        message: "rollout compression or another migration is already running"
+                            .to_string(),
+                    })?,
+            ),
+        };
+        let mut paths = match paths {
+            RolloutMigrationPaths::Discover => {
+                find_all_rollout_paths(&self.config.codex_home).await?
+            }
+            RolloutMigrationPaths::Known(paths) => paths,
+        };
+        if options.mode == RolloutMigrationMode::Apply {
+            let pending_thread_ids = pending_migration_thread_ids(&self.config.codex_home).await?;
+            paths.sort_by_key(|path| {
+                !thread_id_from_rollout_filename(path)
+                    .is_some_and(|thread_id| pending_thread_ids.contains(&thread_id))
+            });
+        }
+        // The name index is global, so read it once before either migrating or repairing names.
+        let legacy_names = if options.mode == RolloutMigrationMode::Apply {
+            let thread_ids = paths
+                .iter()
+                .filter_map(|path| thread_id_from_rollout_filename(path))
+                .collect();
+            codex_rollout::find_thread_names_by_ids(&self.config.codex_home, &thread_ids)
+                .await
+                .unwrap_or_default()
+        } else {
+            HashMap::new()
+        };
+        let total_paths = paths.len();
+        let mut report = RolloutMigrationReport::default();
+
+        for (index, path) in paths.into_iter().enumerate() {
+            let outcome = self
+                .migrate_rollout_path(path, &options, &legacy_names, &mut limiter)
+                .await?;
+            let outcome_status = outcome.as_ref().map(|outcome| outcome.status);
+            if let Some(outcome) = outcome {
+                report.outcomes.push(outcome);
+            }
+            on_progress(RolloutMigrationProgress {
+                processed_paths: index + 1,
+                total_paths,
+                outcome_status,
+            });
+        }
+
+        Ok(report)
+    }
+
+    async fn migrate_rollout_path(
+        &self,
+        mut path: PathBuf,
+        options: &RolloutMigrationOptions,
+        legacy_names: &HashMap<ThreadId, String>,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<Option<RolloutMigrationOutcome>> {
+        let mut retried_moved_path = false;
+        let metadata = loop {
+            let error = match codex_rollout::read_session_meta_line(&path).await {
+                Ok(metadata) => break metadata,
+                Err(error) if !retried_moved_path && error.kind() == io::ErrorKind::NotFound => {
+                    // A different Codex process can archive or compress this rollout after path
+                    // discovery but before we take its writer lock. Retry the same rollout under
+                    // its current root/suffix before treating the missing snapshot path as failed.
+                    if let Some(current_path) =
+                        find_current_rollout_path(&self.config.codex_home, &path).await?
+                    {
+                        path = current_path;
+                        retried_moved_path = true;
+                        continue;
+                    }
+                    error
+                }
+                Err(error) => error,
+            };
+            let thread_id = thread_id_from_rollout_filename(&path);
+            if !matches_selection(&options.thread_ids, thread_id) {
+                return Ok(None);
+            }
+            let initially_empty = tokio::fs::metadata(&path)
+                .await
+                .is_ok_and(|metadata| metadata.len() == 0);
+            // Writers create the rollout path before SessionMeta is durable. Re-read under the
+            // writer lock so a writer that just finished does not become a permanent empty skip.
+            let error = if initially_empty
+                && options.mode == RolloutMigrationMode::Apply
+                && let Some(thread_id) = thread_id
+            {
+                let _writer_guard = match self.acquire_writer_lock(thread_id) {
+                    Ok(guard) => guard,
+                    Err(ThreadStoreError::Conflict { message }) => {
+                        return Ok(Some(skipped_busy_outcome(
+                            thread_id, path, message, /*bytes_processed*/ 0,
+                        )));
+                    }
+                    Err(error) => return Err(error),
+                };
+                match codex_rollout::read_session_meta_line(&path).await {
+                    Ok(metadata) => break metadata,
+                    Err(error) => error,
+                }
+            } else {
+                error
+            };
+            let empty = tokio::fs::metadata(&path)
+                .await
+                .is_ok_and(|metadata| metadata.len() == 0);
+            let failure_reason = if empty {
+                None
+            } else if error.kind() != io::ErrorKind::Other {
+                Some(RolloutMigrationFailureReason::RolloutReadFailed)
+            } else {
+                Some(RolloutMigrationFailureReason::InvalidSessionMetadata)
+            };
+            return Ok(Some(RolloutMigrationOutcome {
+                thread_id,
+                rollout_path: path,
+                status: if empty {
+                    RolloutMigrationStatus::SkippedEmpty
+                } else {
+                    RolloutMigrationStatus::Failed
+                },
+                failure_reason,
+                bytes_processed: 0,
+                message: (!empty).then(|| error.to_string()),
+            }));
+        };
+        let thread_id = metadata.meta.id;
+        if !matches_selection(&options.thread_ids, Some(thread_id)) {
+            return Ok(None);
+        }
+        let is_memory_consolidation = matches!(
+            metadata.meta.source,
+            SessionSource::Internal(InternalSessionSource::MemoryConsolidation)
+                | SessionSource::SubAgent(SubAgentSource::MemoryConsolidation)
+        ) || matches!(
+            metadata.meta.thread_source,
+            Some(ThreadSource::MemoryConsolidation)
+        );
+        let kind = if !is_memory_consolidation
+            && (matches!(metadata.meta.source, SessionSource::SubAgent(_))
+                || matches!(metadata.meta.thread_source, Some(ThreadSource::Subagent)))
+        {
+            RolloutMigrationKind::Subagent
+        } else {
+            RolloutMigrationKind::Ordinary
+        };
+
+        let journal_path = migration_journal_path(&self.config.codex_home, thread_id);
+        let pending_published_migration = metadata.meta.history_mode
+            == ThreadHistoryMode::Paginated
+            && options.mode == RolloutMigrationMode::Apply
+            && tokio::fs::try_exists(&journal_path)
+                .await
+                .map_err(migration_error)?;
+        if metadata.meta.history_mode == ThreadHistoryMode::Paginated {
+            let bytes_before = limiter.bytes_processed;
+            let result = if pending_published_migration {
+                let _live_writer_guard = self.live_writer_locks.lock(thread_id).await;
+                match self
+                    .recover_published_migration(
+                        thread_id,
+                        &path,
+                        &journal_path,
+                        legacy_names,
+                        limiter,
+                    )
+                    .await
+                {
+                    Ok(recovered_path) => {
+                        path = recovered_path;
+                        Ok(RolloutMigrationStatus::Migrated)
+                    }
+                    Err(ThreadStoreError::Conflict { message }) => {
+                        let bytes_processed = limiter.bytes_processed.saturating_sub(bytes_before);
+                        return Ok(Some(skipped_busy_outcome(
+                            thread_id,
+                            path,
+                            message,
+                            bytes_processed,
+                        )));
+                    }
+                    Err(error) => Err(RolloutMigrationFailure::new(
+                        RolloutMigrationFailureReason::InterruptedMigrationRecoveryFailed,
+                        error,
+                    )),
+                }
+            } else {
+                if options.mode == RolloutMigrationMode::Apply {
+                    self.promote_legacy_name(thread_id, legacy_names).await?;
+                }
+                Ok(RolloutMigrationStatus::AlreadyPaginated)
+            };
+            let bytes_processed = limiter.bytes_processed.saturating_sub(bytes_before);
+            return Ok(Some(migration_outcome(
+                thread_id,
+                path,
+                result,
+                bytes_processed,
+            )));
+        }
+
+        if options.mode == RolloutMigrationMode::DryRun {
+            return Ok(Some(migration_outcome(
+                thread_id,
+                path,
+                Ok(RolloutMigrationStatus::Eligible),
+                /*bytes_processed*/ 0,
+            )));
+        }
+
+        let _live_writer_guard = self.live_writer_locks.lock(thread_id).await;
+        let _writer_guard = match self.acquire_writer_lock(thread_id) {
+            Ok(guard) => guard,
+            Err(ThreadStoreError::Conflict { message }) => {
+                return Ok(Some(skipped_busy_outcome(
+                    thread_id, path, message, /*bytes_processed*/ 0,
+                )));
+            }
+            Err(error) => {
+                return Ok(Some(migration_outcome(
+                    thread_id,
+                    path,
+                    Err(RolloutMigrationFailure::new(
+                        RolloutMigrationFailureReason::Unknown,
+                        error,
+                    )),
+                    /*bytes_processed*/ 0,
+                )));
+            }
+        };
+        // SessionMeta gives us the writer-lock id, so archiving can win between that read and
+        // lock acquisition. Once the lock is ours, follow the same rollout to its current path.
+        if !tokio::fs::try_exists(&path)
+            .await
+            .map_err(migration_error)?
+            && let Some(current_path) =
+                find_current_rollout_path(&self.config.codex_home, &path).await?
+        {
+            path = current_path;
+        }
+        let bytes_before = limiter.bytes_processed;
+        let result = match self
+            .migrate_one_rollout(thread_id, &path, &journal_path, kind, legacy_names, limiter)
+            .await
+        {
+            Ok(()) => Ok(RolloutMigrationStatus::Migrated),
+            Err(failure) => {
+                if let Err(cleanup_error) = self
+                    .cleanup_failed_unpublished_migration(thread_id, &path, &journal_path)
+                    .await
+                {
+                    Err(RolloutMigrationFailure::new(
+                        failure.reason,
+                        migration_error(format!(
+                            "{}; failed to clean up unpublished migration: {cleanup_error}",
+                            failure.error
+                        )),
+                    ))
+                } else {
+                    Err(failure)
+                }
+            }
+        };
+        let bytes_processed = limiter.bytes_processed.saturating_sub(bytes_before);
+        Ok(Some(match result {
+            Err(RolloutMigrationFailure {
+                error: ThreadStoreError::Conflict { message },
+                ..
+            }) => skipped_busy_outcome(thread_id, path, message, bytes_processed),
+            result => migration_outcome(thread_id, path, result, bytes_processed),
+        }))
+    }
+
+    async fn migrate_one_rollout(
+        &self,
+        thread_id: ThreadId,
+        rollout_path: &Path,
+        journal_path: &Path,
+        kind: RolloutMigrationKind,
+        legacy_names: &HashMap<ThreadId, String>,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ClassifiedMigrationResult<()> {
+        if let Some(state_db) = &self.state_db
+            && with_failure_reason(
+                state_db
+                    .get_thread(thread_id)
+                    .await
+                    .map_err(migration_error),
+                RolloutMigrationFailureReason::Unknown,
+            )?
+            .is_none()
+        {
+            return Err(RolloutMigrationFailure::new(
+                RolloutMigrationFailureReason::MissingSqliteMetadata,
+                migration_error(format!("thread {thread_id} is missing its SQLite metadata")),
+            ));
+        }
+
+        let compressed = rollout_path_is_compressed(rollout_path);
+        let staged_path = with_failure_reason(
+            staged_rollout_path(rollout_path),
+            RolloutMigrationFailureReason::Unknown,
+        )?;
+        let decompressed_path = with_failure_reason(
+            compressed
+                .then(|| decompressed_staged_rollout_path(rollout_path))
+                .transpose(),
+            RolloutMigrationFailureReason::Unknown,
+        )?;
+        with_failure_reason(
+            thread_history::delete_thread(self, thread_id).await,
+            RolloutMigrationFailureReason::SqliteMaterializationFailed,
+        )?;
+        with_failure_reason(
+            write_migration_journal(journal_path).await,
+            RolloutMigrationFailureReason::RolloutPublishFailed,
+        )?;
+
+        let source_metadata = with_failure_reason(
+            tokio::fs::metadata(rollout_path)
+                .await
+                .map_err(migration_error),
+            RolloutMigrationFailureReason::RolloutReadFailed,
+        )?;
+        let source_modified = source_metadata.modified().ok();
+        let source_permissions = source_metadata.permissions();
+        let source_path = if let Some(decompressed_path) = decompressed_path.as_ref() {
+            with_failure_reason(
+                decompress_rollout_to_path(rollout_path, decompressed_path).await,
+                RolloutMigrationFailureReason::RolloutReadFailed,
+            )?;
+            let decompressed_bytes = with_failure_reason(
+                tokio::fs::metadata(decompressed_path)
+                    .await
+                    .map_err(migration_error),
+                RolloutMigrationFailureReason::RolloutReadFailed,
+            )?
+            .len();
+            limiter
+                .account(source_metadata.len().saturating_add(decompressed_bytes))
+                .await;
+            decompressed_path.as_path()
+        } else {
+            rollout_path
+        };
+        let source_file = with_failure_reason(
+            File::open(source_path).await.map_err(migration_error),
+            RolloutMigrationFailureReason::RolloutReadFailed,
+        )?;
+        let mut source = BufReader::with_capacity(PROJECTION_BATCH_BYTES as usize, source_file);
+        let mut bytes = Vec::new();
+
+        // Paginated rollouts always keep their canonical SessionMeta at ordinal zero. Legacy
+        // readers tolerate a pre-header prefix, so find that metadata before replaying the source
+        // instead of buffering the prefix in memory.
+        let canonical_session_meta = loop {
+            let record = with_failure_reason(
+                read_rollout_record(&mut source, &mut bytes).await,
+                RolloutMigrationFailureReason::RolloutReadFailed,
+            )?
+            .ok_or_else(|| {
+                RolloutMigrationFailure::new(
+                    RolloutMigrationFailureReason::InvalidSessionMetadata,
+                    migration_error("rollout contains no session metadata"),
+                )
+            })?;
+            limiter.account(record.byte_count).await;
+            let Some(line) = record.line else {
+                continue;
+            };
+            if matches!(&line.item, RolloutItem::SessionMeta(_)) {
+                break line;
+            }
+        };
+        drop(source);
+
+        let canonicalization_source = CanonicalizationSource {
+            thread_id,
+            source_path,
+            staged_path: &staged_path,
+            source_permissions: &source_permissions,
+            canonical_session_meta: &canonical_session_meta,
+        };
+
+        // Everything up through a durable staged file is one legacy-to-paginated conversion
+        // phase. Keep the individual operations readable and tag the phase once if it fails.
+        let conversion_result = async {
+            let bounded_subagent_context = if kind == RolloutMigrationKind::Subagent {
+                let RolloutItem::SessionMeta(session_meta) = &canonical_session_meta.item else {
+                    return Err(migration_error("canonical session metadata is missing"));
+                };
+                let context = subagent::select_bounded_context(
+                    source_path.to_path_buf(),
+                    session_meta.clone(),
+                )
+                .await?;
+                limiter.account(source_metadata.len()).await;
+                context
+            } else {
+                None
+            };
+            let (_, expected_ordinal) = if let Some(items) = bounded_subagent_context {
+                Self::write_bounded_subagent_rollout(&canonicalization_source, items, limiter)
+                    .await?
+            } else {
+                Self::write_rollout_with_rollback_plan(&canonicalization_source, limiter).await?
+            };
+
+            if kind == RolloutMigrationKind::Subagent {
+                rewrite_subagent_history_boundary(&staged_path, expected_ordinal).await?;
+            }
+            let expected_length = tokio::fs::metadata(&staged_path)
+                .await
+                .map_err(migration_error)?
+                .len();
+
+            // SQLite projection only starts after every staged-file mutation is durable.
+            let modified_at = source_modified;
+            let path = staged_path.clone();
+            tokio::task::spawn_blocking(move || {
+                let file = std::fs::OpenOptions::new().write(true).open(path)?;
+                if let Some(modified_at) = modified_at {
+                    file.set_times(std::fs::FileTimes::new().set_modified(modified_at))?;
+                }
+                file.sync_all()
+            })
+            .await
+            .map_err(migration_error)?
+            .map_err(migration_error)?;
+
+            Ok::<_, ThreadStoreError>((expected_length, expected_ordinal))
+        }
+        .await;
+        let (expected_length, expected_ordinal) = with_failure_reason(
+            conversion_result,
+            RolloutMigrationFailureReason::LegacyRolloutConversionFailed,
+        )?;
+
+        // SQLite sees only the final staged bytes, so all projection failures share one reason.
+        let projection_result = async {
+            self.project_rollout_in_batches(thread_id, &staged_path, limiter)
+                .await?;
+            let projection = thread_history::projection_state(self, thread_id)
+                .await?
+                .ok_or_else(|| migration_error("completed rollout has no SQLite projection"))?;
+            if projection.next_byte_offset != expected_length
+                || projection.next_ordinal != expected_ordinal
+            {
+                return Err(migration_error(
+                    "SQLite projection does not cover the complete staged rollout",
+                ));
+            }
+            Ok::<_, ThreadStoreError>(())
+        }
+        .await;
+        with_failure_reason(
+            projection_result,
+            RolloutMigrationFailureReason::SqliteMaterializationFailed,
+        )?;
+
+        // Once projection is verified, the remaining work publishes the replacement and clears
+        // the durable pending journal.
+        let publish_result = async {
+            let compressed_staged_path = if compressed {
+                let path = compressed_staged_rollout_path(rollout_path)?;
+                compress_rollout_to_path(&staged_path, &path, source_permissions, source_modified)
+                    .await?;
+                Some(path)
+            } else {
+                None
+            };
+
+            // Older writers do not know about migration locks. Keep the legacy path visible if
+            // its append-only source changed while the replacement rollout was being staged.
+            let current_source_metadata = tokio::fs::metadata(rollout_path)
+                .await
+                .map_err(migration_error)?;
+            if current_source_metadata.len() != source_metadata.len()
+                || current_source_metadata.modified().ok() != source_modified
+            {
+                return Err(ThreadStoreError::Conflict {
+                    message: "rollout changed while migration was staging it; close older Codex processes and retry".to_string(),
+                });
+            }
+
+            if let Some(compressed_staged_path) = compressed_staged_path {
+                tokio::fs::rename(compressed_staged_path, rollout_path)
+                    .await
+                    .map_err(migration_error)?;
+                remove_file_if_present(&staged_path).await?;
+                if let Some(decompressed_path) = decompressed_path.as_ref() {
+                    remove_file_if_present(decompressed_path).await?;
+                }
+            } else {
+                tokio::fs::rename(&staged_path, rollout_path)
+                    .await
+                    .map_err(migration_error)?;
+            }
+            sync_parent_directory(rollout_path).await?;
+            self.finish_published_migration(thread_id, journal_path, legacy_names)
+                .await
+        }
+        .await;
+        with_failure_reason(
+            publish_result,
+            RolloutMigrationFailureReason::RolloutPublishFailed,
+        )
+    }
+
+    async fn build_rollback_plan(
+        source_path: &Path,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<RollbackPlan> {
+        let source_file = File::open(source_path).await.map_err(migration_error)?;
+        let mut source = BufReader::with_capacity(PROJECTION_BATCH_BYTES as usize, source_file);
+        let mut bytes = Vec::new();
+        let mut planner = RollbackPlanner::new();
+        while let Some(record) = read_rollout_record(&mut source, &mut bytes).await? {
+            limiter.account(record.byte_count).await;
+            if let Some(line) = record.line {
+                planner.observe(&line)?;
+            }
+        }
+        Ok(planner.finish())
+    }
+
+    async fn write_rollout_with_rollback_plan(
+        input: &CanonicalizationSource<'_>,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<(u64, u64)> {
+        let attempt = Self::write_canonical_rollout(input, /*plan*/ None, limiter).await?;
+        match attempt {
+            CanonicalizationAttempt::Complete {
+                expected_length,
+                expected_ordinal,
+            } => Ok((expected_length, expected_ordinal)),
+            CanonicalizationAttempt::NeedsRollbackPlan => {
+                remove_file_if_present(input.staged_path).await?;
+                let plan = Self::build_rollback_plan(input.source_path, limiter).await?;
+                let CanonicalizationAttempt::Complete {
+                    expected_length,
+                    expected_ordinal,
+                } = Self::write_canonical_rollout(input, Some(&plan), limiter).await?
+                else {
+                    return Err(migration_error(
+                        "planned rollout still contains a rollback marker",
+                    ));
+                };
+                Ok((expected_length, expected_ordinal))
+            }
+        }
+    }
+
+    async fn write_bounded_subagent_rollout(
+        input: &CanonicalizationSource<'_>,
+        items: Vec<RolloutItem>,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<(u64, u64)> {
+        let staged_file = tokio::fs::OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .write(true)
+            .open(input.staged_path)
+            .await
+            .map_err(migration_error)?;
+        staged_file
+            .set_permissions(input.source_permissions.clone())
+            .await
+            .map_err(migration_error)?;
+        let mut staged = BufWriter::with_capacity(PROJECTION_BATCH_BYTES as usize, staged_file);
+        let mut canonicalizer = LegacyRolloutCanonicalizer::new(input.thread_id);
+        let written = canonicalizer
+            .write_head_session_meta(input.canonical_session_meta.clone(), &mut staged)
+            .await?;
+        limiter.account(written).await;
+        for item in items {
+            let line = RolloutLine {
+                timestamp: input.canonical_session_meta.timestamp.clone(),
+                ordinal: None,
+                item,
+            };
+            let written = canonicalizer.process_line(line, &mut staged).await?;
+            limiter.account(written).await;
+        }
+        let written = canonicalizer
+            .finish(&mut staged, &input.canonical_session_meta.timestamp)
+            .await?;
+        limiter.account(written).await;
+        staged.flush().await.map_err(migration_error)?;
+        Ok((
+            canonicalizer.output_byte_offset(),
+            canonicalizer.next_ordinal(),
+        ))
+    }
+
+    async fn write_canonical_rollout(
+        input: &CanonicalizationSource<'_>,
+        plan: Option<&RollbackPlan>,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<CanonicalizationAttempt> {
+        let source_file = File::open(input.source_path)
+            .await
+            .map_err(migration_error)?;
+        let staged_file = tokio::fs::OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .write(true)
+            .open(input.staged_path)
+            .await
+            .map_err(migration_error)?;
+        staged_file
+            .set_permissions(input.source_permissions.clone())
+            .await
+            .map_err(migration_error)?;
+        let mut source = BufReader::with_capacity(PROJECTION_BATCH_BYTES as usize, source_file);
+        let mut staged = BufWriter::with_capacity(PROJECTION_BATCH_BYTES as usize, staged_file);
+        let mut bytes = Vec::new();
+        let mut parsed_record_index = 0_usize;
+        let mut canonicalizer = LegacyRolloutCanonicalizer::new(input.thread_id);
+        let written = canonicalizer
+            .write_head_session_meta(input.canonical_session_meta.clone(), &mut staged)
+            .await?;
+        limiter.account(written).await;
+        let mut last_timestamp = input.canonical_session_meta.timestamp.clone();
+
+        while let Some(record) = read_rollout_record(&mut source, &mut bytes).await? {
+            limiter.account(record.byte_count).await;
+            let Some(line) = record.line else {
+                continue;
+            };
+            if plan.is_none()
+                && matches!(
+                    &line.item,
+                    RolloutItem::EventMsg(codex_protocol::protocol::EventMsg::ThreadRolledBack(_))
+                )
+            {
+                return Ok(CanonicalizationAttempt::NeedsRollbackPlan);
+            }
+            let line = if let Some(plan) = plan {
+                let planned = plan.apply(parsed_record_index, line)?;
+                parsed_record_index = parsed_record_index
+                    .checked_add(1)
+                    .ok_or_else(|| migration_error("legacy rollout record index overflow"))?;
+                let Some(line) = planned else {
+                    continue;
+                };
+                line
+            } else {
+                line
+            };
+            last_timestamp = line.timestamp.clone();
+            let written = canonicalizer.process_line(line, &mut staged).await?;
+            limiter.account(written).await;
+        }
+        if let Some(plan) = plan
+            && parsed_record_index != plan.record_count()
+        {
+            return Err(migration_error(
+                "rollback plan source length changed during replay",
+            ));
+        }
+
+        let written = canonicalizer.finish(&mut staged, &last_timestamp).await?;
+        limiter.account(written).await;
+        staged.flush().await.map_err(migration_error)?;
+        Ok(CanonicalizationAttempt::Complete {
+            expected_length: canonicalizer.output_byte_offset(),
+            expected_ordinal: canonicalizer.next_ordinal(),
+        })
+    }
+
+    async fn recover_published_migration(
+        &self,
+        thread_id: ThreadId,
+        rollout_path: &Path,
+        journal_path: &Path,
+        legacy_names: &HashMap<ThreadId, String>,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<PathBuf> {
+        let _writer_guard = self.acquire_writer_lock(thread_id)?;
+        let decompressed_path = rollout_path_is_compressed(rollout_path)
+            .then(|| decompressed_staged_rollout_path(rollout_path))
+            .transpose()?;
+        let projection_path = if let Some(decompressed_path) = decompressed_path.as_ref() {
+            decompress_rollout_to_path(rollout_path, decompressed_path).await?;
+            let decompressed_bytes = tokio::fs::metadata(decompressed_path)
+                .await
+                .map_err(migration_error)?
+                .len();
+            limiter
+                .account(
+                    tokio::fs::metadata(rollout_path)
+                        .await
+                        .map_err(migration_error)?
+                        .len()
+                        .saturating_add(decompressed_bytes),
+                )
+                .await;
+            decompressed_path.as_path()
+        } else {
+            rollout_path
+        };
+        let expected_length = tokio::fs::metadata(projection_path)
+            .await
+            .map_err(migration_error)?
+            .len();
+        let projection = thread_history::projection_state(self, thread_id).await?;
+        if projection.is_none_or(|state| state.next_byte_offset != expected_length) {
+            thread_history::delete_thread(self, thread_id).await?;
+            self.project_rollout_in_batches(thread_id, projection_path, limiter)
+                .await?;
+        }
+        remove_file_if_present(&staged_rollout_path(rollout_path)?).await?;
+        remove_file_if_present(&compressed_staged_rollout_path(rollout_path)?).await?;
+        if let Some(decompressed_path) = decompressed_path.as_ref() {
+            remove_file_if_present(decompressed_path).await?;
+        }
+        self.finish_published_migration(thread_id, journal_path, legacy_names)
+            .await?;
+        Ok(rollout_path.to_path_buf())
+    }
+
+    async fn cleanup_failed_unpublished_migration(
+        &self,
+        thread_id: ThreadId,
+        rollout_path: &Path,
+        journal_path: &Path,
+    ) -> ThreadStoreResult<()> {
+        let Ok(metadata) = codex_rollout::read_session_meta_line(rollout_path).await else {
+            return Ok(());
+        };
+        if metadata.meta.history_mode == ThreadHistoryMode::Paginated {
+            return Ok(());
+        }
+
+        thread_history::delete_thread(self, thread_id).await?;
+        let staged_path = staged_rollout_path(rollout_path)?;
+        remove_file_if_present(&staged_path).await?;
+        remove_file_if_present(&rewritten_staged_rollout_path(&staged_path)?).await?;
+        remove_file_if_present(&compressed_staged_rollout_path(rollout_path)?).await?;
+        remove_file_if_present(&decompressed_staged_rollout_path(rollout_path)?).await?;
+        remove_file_if_present(journal_path).await?;
+        sync_parent_directory(journal_path).await
+    }
+
+    async fn finish_published_migration(
+        &self,
+        thread_id: ThreadId,
+        journal_path: &Path,
+        legacy_names: &HashMap<ThreadId, String>,
+    ) -> ThreadStoreResult<()> {
+        self.promote_legacy_name(thread_id, legacy_names).await?;
+        tokio::fs::remove_file(journal_path)
+            .await
+            .map_err(migration_error)?;
+        sync_parent_directory(journal_path).await
+    }
+
+    async fn promote_legacy_name(
+        &self,
+        thread_id: ThreadId,
+        legacy_names: &HashMap<ThreadId, String>,
+    ) -> ThreadStoreResult<()> {
+        if let Some(state_db) = &self.state_db {
+            let metadata = state_db
+                .get_thread(thread_id)
+                .await
+                .map_err(migration_error)?
+                .ok_or_else(|| {
+                    migration_error(format!("thread {thread_id} is missing its SQLite metadata"))
+                })?;
+            if metadata.history_mode == ThreadHistoryMode::Paginated
+                && metadata
+                    .name
+                    .as_deref()
+                    .is_some_and(|name| !name.trim().is_empty())
+            {
+                return Ok(());
+            }
+            let legacy_name = distinct_thread_metadata_title(&metadata)
+                .or_else(|| legacy_names.get(&thread_id).cloned())
+                .filter(|name| !name.trim().is_empty());
+            if !state_db
+                .mark_thread_paginated(thread_id, legacy_name.as_deref())
+                .await
+                .map_err(migration_error)?
+            {
+                return Err(migration_error(format!(
+                    "thread {thread_id} is missing its SQLite metadata"
+                )));
+            }
+        }
+        Ok(())
+    }
+
+    async fn project_rollout_in_batches(
+        &self,
+        thread_id: ThreadId,
+        rollout_path: &Path,
+        limiter: &mut RolloutMigrationRateLimiter,
+    ) -> ThreadStoreResult<()> {
+        let subagent_history_start_ordinal = codex_rollout::read_session_meta_line(rollout_path)
+            .await
+            .map_err(migration_error)?
+            .meta
+            .subagent_history_start_ordinal;
+        let file = File::open(rollout_path).await.map_err(migration_error)?;
+        let mut reader = BufReader::with_capacity(PROJECTION_BATCH_BYTES as usize, file);
+        let mut line_bytes = Vec::new();
+        let mut batch = Vec::new();
+        let mut batch_start = 0_u64;
+        let mut offset = 0_u64;
+
+        while let Some(record) = read_rollout_record(&mut reader, &mut line_bytes).await? {
+            let next_offset = offset
+                .checked_add(record.byte_count)
+                .ok_or_else(|| migration_error("staged rollout byte offset overflow"))?;
+            limiter.account(record.byte_count).await;
+            let Some(line) = record.line else {
+                offset = next_offset;
+                continue;
+            };
+            let ordinal = line
+                .ordinal
+                .ok_or_else(|| migration_error("staged rollout line is missing its ordinal"))?;
+            let fallback_created_at_ms = DateTime::parse_from_rfc3339(&line.timestamp)
+                .map_err(migration_error)?
+                .timestamp_millis();
+            let is_inherited_subagent_history =
+                subagent_history_start_ordinal.is_some_and(|start| ordinal < start);
+            batch.push(RolloutProjectionStep::Line(Box::new(
+                ProjectedRolloutLine {
+                    ordinal,
+                    start_byte_offset: offset,
+                    end_byte_offset: next_offset,
+                    fallback_created_at_ms: Some(fallback_created_at_ms),
+                    changes: if is_inherited_subagent_history {
+                        Default::default()
+                    } else {
+                        project_rollout_line(&line)
+                    },
+                    realtime_item: match line.item {
+                        RolloutItem::RealtimeItem(item) if !is_inherited_subagent_history => {
+                            Some(item)
+                        }
+                        _ => None,
+                    },
+                },
+            )));
+            offset = next_offset;
+
+            if offset.saturating_sub(batch_start) >= PROJECTION_BATCH_BYTES {
+                thread_history::apply_projection(
+                    self,
+                    thread_id,
+                    batch_start,
+                    offset,
+                    /*initial_ordinal*/ 0,
+                    std::mem::take(&mut batch),
+                )
+                .await?;
+                batch_start = offset;
+            }
+        }
+
+        if batch_start != offset {
+            thread_history::apply_projection(
+                self,
+                thread_id,
+                batch_start,
+                offset,
+                /*initial_ordinal*/ 0,
+                batch,
+            )
+            .await?;
+        }
+        Ok(())
+    }
+}
+
+async fn read_rollout_record(
+    reader: &mut BufReader<File>,
+    bytes: &mut Vec<u8>,
+) -> ThreadStoreResult<Option<RolloutRecord>> {
+    bytes.clear();
+    let mut byte_count = reader
+        .take((MAX_ROLLOUT_LINE_BYTES + 1) as u64)
+        .read_until(b'\n', bytes)
+        .await
+        .map_err(migration_error)?;
+    if byte_count == 0 {
+        return Ok(None);
+    }
+    if byte_count > MAX_ROLLOUT_LINE_BYTES {
+        // Some historical tool outputs are too large to migrate safely in memory. Discard the
+        // whole record, including any unread suffix.
+        while bytes.last() != Some(&b'\n') {
+            bytes.clear();
+            let chunk_bytes = reader
+                .take((MAX_ROLLOUT_LINE_BYTES + 1) as u64)
+                .read_until(b'\n', bytes)
+                .await
+                .map_err(migration_error)?;
+            if chunk_bytes == 0 {
+                break;
+            }
+            byte_count = byte_count
+                .checked_add(chunk_bytes)
+                .ok_or_else(|| migration_error("rollout record byte count overflow"))?;
+        }
+        return Ok(Some(RolloutRecord {
+            line: None,
+            byte_count: byte_count as u64,
+        }));
+    }
+    // Legacy records do not have ordinals, so malformed complete records cannot be repaired.
+    // Skip them and let the next newline-delimited record resynchronize the stream.
+    let line = line_parser::parse_legacy_rollout_line(bytes).unwrap_or(None);
+    Ok(Some(RolloutRecord {
+        line,
+        byte_count: byte_count as u64,
+    }))
+}
+
+async fn find_rollout_paths(root: &Path) -> ThreadStoreResult<Vec<PathBuf>> {
+    let mut directories = vec![root.to_path_buf()];
+    let mut paths = Vec::new();
+
+    while let Some(directory) = directories.pop() {
+        let mut entries = match tokio::fs::read_dir(&directory).await {
+            Ok(entries) => entries,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(error) => return Err(migration_error(error)),
+        };
+        while let Some(entry) = entries.next_entry().await.map_err(migration_error)? {
+            let kind = entry.file_type().await.map_err(migration_error)?;
+            if kind.is_dir() {
+                directories.push(entry.path());
+                continue;
+            }
+            if !kind.is_file() {
+                continue;
+            }
+            let name = entry.file_name();
+            let Some(name) = name.to_str() else {
+                continue;
+            };
+            if name.starts_with("rollout-")
+                && (name.ends_with(".jsonl") || name.ends_with(".jsonl.zst"))
+            {
+                let path = entry.path();
+                if name.ends_with(".jsonl.zst")
+                    && tokio::fs::try_exists(codex_rollout::plain_rollout_path(&path))
+                        .await
+                        .map_err(migration_error)?
+                {
+                    continue;
+                }
+                paths.push(path);
+            }
+        }
+    }
+
+    paths.sort_by(|left, right| right.cmp(left));
+    Ok(paths)
+}
+
+async fn find_all_rollout_paths(codex_home: &Path) -> ThreadStoreResult<Vec<PathBuf>> {
+    let mut paths = find_rollout_paths(&codex_home.join(codex_rollout::SESSIONS_SUBDIR)).await?;
+    paths.extend(
+        find_rollout_paths(&codex_home.join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR)).await?,
+    );
+    Ok(paths)
+}
+
+async fn find_current_rollout_path(
+    codex_home: &Path,
+    stale_path: &Path,
+) -> ThreadStoreResult<Option<PathBuf>> {
+    let plain_path = codex_rollout::plain_rollout_path(stale_path);
+    let Some(file_name) = plain_path.file_name() else {
+        return Ok(None);
+    };
+    Ok(find_all_rollout_paths(codex_home)
+        .await?
+        .into_iter()
+        .find(|candidate| {
+            codex_rollout::plain_rollout_path(candidate).file_name() == Some(file_name)
+        }))
+}
+
+fn matches_selection(selected: &[ThreadId], actual: Option<ThreadId>) -> bool {
+    selected.is_empty() || actual.is_some_and(|thread_id| selected.contains(&thread_id))
+}
+
+fn rollout_path_is_compressed(path: &Path) -> bool {
+    path.file_name()
+        .and_then(|name| name.to_str())
+        .is_some_and(|name| name.ends_with(".jsonl.zst"))
+}
+
+fn thread_id_from_rollout_filename(path: &Path) -> Option<ThreadId> {
+    let name = path.file_name()?.to_str()?;
+    let stem = name
+        .strip_suffix(".jsonl.zst")
+        .or_else(|| name.strip_suffix(".jsonl"))?;
+    let start = stem.len().checked_sub(36)?;
+    ThreadId::from_string(stem.get(start..)?).ok()
+}
+
+fn migration_outcome(
+    thread_id: ThreadId,
+    rollout_path: PathBuf,
+    result: ClassifiedMigrationResult<RolloutMigrationStatus>,
+    bytes_processed: u64,
+) -> RolloutMigrationOutcome {
+    match result {
+        Ok(status) => RolloutMigrationOutcome {
+            thread_id: Some(thread_id),
+            rollout_path,
+            status,
+            failure_reason: None,
+            bytes_processed,
+            message: None,
+        },
+        Err(failure) => RolloutMigrationOutcome {
+            thread_id: Some(thread_id),
+            rollout_path,
+            status: RolloutMigrationStatus::Failed,
+            failure_reason: Some(failure.reason),
+            bytes_processed,
+            message: Some(failure.error.to_string()),
+        },
+    }
+}
+
+fn skipped_busy_outcome(
+    thread_id: ThreadId,
+    rollout_path: PathBuf,
+    message: String,
+    bytes_processed: u64,
+) -> RolloutMigrationOutcome {
+    RolloutMigrationOutcome {
+        thread_id: Some(thread_id),
+        rollout_path,
+        status: RolloutMigrationStatus::SkippedBusy,
+        failure_reason: None,
+        bytes_processed,
+        message: Some(message),
+    }
+}
+
+fn migration_error(error: impl std::fmt::Display) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: format!("rollout migration failed: {error}"),
+    }
+}
+
+#[cfg(test)]
+#[path = "rollout_migration_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/rollout_migration/canonicalizer.rs b/codex-rs/thread-store/src/local/rollout_migration/canonicalizer.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8c446ccc5cd7faf39515fc2055d10a3193dbf51c
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/canonicalizer.rs
@@ -0,0 +1,502 @@
+//! Replays normalized legacy rollout records into canonical paginated JSONL.
+//!
+//! `line_parser` makes old JSON shapes parseable, `legacy_event` converts obsolete completion
+//! events into modern turn items. Rollback planning happens before this writer sees a record, so
+//! this module only assigns stable ordinals, keeps `SessionMeta` at ordinal zero, and emits the
+//! already-selected surviving history.
+//!
+//! The goal is to preserve the model-visible conversation, not to preserve every legacy record
+//! byte-for-byte. Filesystem publishing and SQLite projection intentionally live outside this
+//! module.
+
+use chrono::DateTime;
+use codex_protocol::ThreadId;
+use codex_protocol::items::ReasoningItem;
+use codex_protocol::items::TurnItem;
+use codex_protocol::items::parse_hook_prompt_message;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::ItemCompletedEvent;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::TurnCompleteEvent;
+use codex_protocol::protocol::TurnStartedEvent;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use std::collections::HashSet;
+use tokio::fs::File;
+use tokio::io::AsyncWriteExt;
+use tokio::io::BufWriter;
+
+use super::legacy_event;
+use super::migration_error;
+use crate::ThreadStoreResult;
+
+#[derive(Clone)]
+struct ActiveTurn {
+    id: String,
+    explicit: bool,
+    saw_user: bool,
+}
+
+enum ReasoningTextKind {
+    Summary,
+    Raw,
+}
+
+pub(super) struct LegacyRolloutCanonicalizer {
+    thread_id: ThreadId,
+    next_ordinal: u64,
+    next_item_index: u64,
+    output_byte_offset: u64,
+    bytes_written: u64,
+    source_line_index: u64,
+    active_turn: Option<ActiveTurn>,
+    known_turn_ids: HashSet<String>,
+    reasoning: Option<ReasoningItem>,
+}
+
+impl LegacyRolloutCanonicalizer {
+    pub(super) fn new(thread_id: ThreadId) -> Self {
+        Self {
+            thread_id,
+            next_ordinal: 0,
+            next_item_index: 1,
+            output_byte_offset: 0,
+            bytes_written: 0,
+            source_line_index: 0,
+            active_turn: None,
+            known_turn_ids: HashSet::new(),
+            reasoning: None,
+        }
+    }
+
+    pub(super) fn next_ordinal(&self) -> u64 {
+        self.next_ordinal
+    }
+
+    pub(super) fn output_byte_offset(&self) -> u64 {
+        self.output_byte_offset
+    }
+
+    pub(super) async fn write_head_session_meta(
+        &mut self,
+        line: RolloutLine,
+        writer: &mut BufWriter<File>,
+    ) -> ThreadStoreResult<u64> {
+        let timestamp = line.timestamp;
+        let RolloutItem::SessionMeta(mut metadata) = line.item else {
+            return Err(migration_error("canonical session metadata is missing"));
+        };
+        if metadata.meta.id != self.thread_id {
+            return Err(migration_error("rollout metadata thread id changed"));
+        }
+        metadata.meta.history_mode = ThreadHistoryMode::Paginated;
+        metadata.meta.history_base = None;
+        metadata.meta.subagent_history_start_ordinal = None;
+
+        let bytes_before = self.bytes_written;
+        self.write_item(writer, &timestamp, RolloutItem::SessionMeta(metadata))
+            .await?;
+        Ok(self.bytes_written - bytes_before)
+    }
+
+    pub(super) async fn process_line(
+        &mut self,
+        line: RolloutLine,
+        writer: &mut BufWriter<File>,
+    ) -> ThreadStoreResult<u64> {
+        let source_index = self.source_line_index;
+        self.source_line_index = self
+            .source_line_index
+            .checked_add(1)
+            .ok_or_else(|| migration_error("legacy rollout line index overflow"))?;
+        let timestamp = line.timestamp;
+        let bytes_before = self.bytes_written;
+        match line.item {
+            RolloutItem::SessionMeta(_) => return Ok(0),
+            RolloutItem::ResponseItem(response) => {
+                if matches!(&response.item, ResponseItem::Other) {
+                    return Err(migration_error(
+                        "legacy rollout contains an unsupported response item",
+                    ));
+                }
+                let hook = match &response.item {
+                    ResponseItem::Message {
+                        role, content, id, ..
+                    } if role == "user" => parse_hook_prompt_message(id.as_deref(), content),
+                    _ => None,
+                };
+                self.write_item(writer, &timestamp, RolloutItem::ResponseItem(response))
+                    .await?;
+                if let Some(hook) = hook {
+                    self.ensure_turn(writer, &timestamp, source_index).await?;
+                    self.reasoning = None;
+                    self.write_completed_item(writer, &timestamp, TurnItem::HookPrompt(hook))
+                        .await?;
+                }
+            }
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(_)) => {
+                return Err(migration_error(
+                    "rollback marker reached canonical writer without a rollback plan",
+                ));
+            }
+            RolloutItem::EventMsg(EventMsg::TurnStarted(event)) => {
+                self.finish_implicit_turn(writer, &timestamp).await?;
+                self.known_turn_ids.insert(event.turn_id.clone());
+                self.active_turn = Some(ActiveTurn {
+                    id: event.turn_id.clone(),
+                    explicit: true,
+                    saw_user: false,
+                });
+                self.reasoning = None;
+                self.write_item(
+                    writer,
+                    &timestamp,
+                    RolloutItem::EventMsg(EventMsg::TurnStarted(event)),
+                )
+                .await?;
+            }
+            RolloutItem::EventMsg(EventMsg::TurnComplete(event)) => {
+                self.reasoning = None;
+                if self
+                    .active_turn
+                    .as_ref()
+                    .is_some_and(|turn| turn.id == event.turn_id)
+                {
+                    self.active_turn = None;
+                }
+                self.write_item(
+                    writer,
+                    &timestamp,
+                    RolloutItem::EventMsg(EventMsg::TurnComplete(event)),
+                )
+                .await?;
+            }
+            RolloutItem::EventMsg(EventMsg::TurnAborted(mut event)) => {
+                if event.turn_id.is_none() {
+                    event.turn_id = self.active_turn.as_ref().map(|turn| turn.id.clone());
+                }
+                if self
+                    .active_turn
+                    .as_ref()
+                    .is_some_and(|turn| event.turn_id.as_deref() == Some(turn.id.as_str()))
+                {
+                    self.active_turn = None;
+                }
+                self.reasoning = None;
+                self.write_item(
+                    writer,
+                    &timestamp,
+                    RolloutItem::EventMsg(EventMsg::TurnAborted(event)),
+                )
+                .await?;
+            }
+            RolloutItem::EventMsg(EventMsg::UserMessage(event)) => {
+                if self
+                    .active_turn
+                    .as_ref()
+                    .is_some_and(|turn| !turn.explicit && turn.saw_user)
+                {
+                    self.finish_implicit_turn(writer, &timestamp).await?;
+                }
+                self.ensure_turn(writer, &timestamp, source_index).await?;
+                let item = legacy_event::user_message_item(event, &mut || self.next_item_id())?;
+                if let Some(turn) = self.active_turn.as_mut() {
+                    turn.saw_user = true;
+                }
+                self.reasoning = None;
+                self.write_completed_item(writer, &timestamp, item).await?;
+            }
+            RolloutItem::EventMsg(EventMsg::AgentReasoning(event)) => {
+                self.write_reasoning(
+                    writer,
+                    &timestamp,
+                    source_index,
+                    event.text,
+                    ReasoningTextKind::Summary,
+                )
+                .await?;
+            }
+            RolloutItem::EventMsg(EventMsg::AgentReasoningRawContent(event)) => {
+                self.write_reasoning(
+                    writer,
+                    &timestamp,
+                    source_index,
+                    event.text,
+                    ReasoningTextKind::Raw,
+                )
+                .await?;
+            }
+            RolloutItem::EventMsg(EventMsg::ItemCompleted(mut event)) => {
+                event.thread_id = self.thread_id;
+                self.reasoning = None;
+                self.write_item(
+                    writer,
+                    &timestamp,
+                    RolloutItem::EventMsg(EventMsg::ItemCompleted(event)),
+                )
+                .await?;
+            }
+            RolloutItem::EventMsg(event) => {
+                if let Some((item, turn_id)) =
+                    legacy_event::completed_item(&event, &mut || self.next_item_id())?
+                {
+                    match turn_id {
+                        Some(turn_id)
+                            if self
+                                .active_turn
+                                .as_ref()
+                                .is_some_and(|turn| turn.id.as_str() != turn_id.as_str()) =>
+                        {
+                            self.write_completed_item_to_turn(writer, &timestamp, turn_id, item)
+                                .await?;
+                        }
+                        Some(turn_id) => {
+                            if self.active_turn.is_none()
+                                && self.known_turn_ids.contains(turn_id.as_str())
+                            {
+                                self.reasoning = None;
+                                self.write_completed_item_to_turn(
+                                    writer, &timestamp, turn_id, item,
+                                )
+                                .await?;
+                            } else if self.active_turn.is_none() {
+                                self.start_implicit_turn(writer, &timestamp, turn_id)
+                                    .await?;
+                                self.reasoning = None;
+                                self.write_completed_item(writer, &timestamp, item).await?;
+                            } else {
+                                self.reasoning = None;
+                                self.write_completed_item(writer, &timestamp, item).await?;
+                            }
+                        }
+                        None => {
+                            self.ensure_turn(writer, &timestamp, source_index).await?;
+                            self.reasoning = None;
+                            self.write_completed_item(writer, &timestamp, item).await?;
+                        }
+                    }
+                } else {
+                    let item = RolloutItem::EventMsg(event);
+                    if codex_rollout::is_persisted_rollout_item(&item, ThreadHistoryMode::Paginated)
+                    {
+                        self.write_item(writer, &timestamp, item).await?;
+                    }
+                }
+            }
+            item @ RolloutItem::InterAgentCommunication(_) => {
+                self.write_item(writer, &timestamp, item).await?;
+            }
+            item @ RolloutItem::Compacted(_) => {
+                self.write_item(writer, &timestamp, item).await?;
+            }
+            item @ (RolloutItem::InterAgentCommunicationMetadata { .. }
+            | RolloutItem::TurnContext(_)
+            | RolloutItem::TokenUsageRecord(_)
+            | RolloutItem::RealtimeItem(_)
+            | RolloutItem::RetainedContext(_)
+            | RolloutItem::SecurityRiskScore(_)
+            | RolloutItem::WorldState(_)) => {
+                self.write_item(writer, &timestamp, item).await?;
+            }
+        }
+
+        Ok(self.bytes_written - bytes_before)
+    }
+
+    pub(super) async fn finish(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+    ) -> ThreadStoreResult<u64> {
+        let bytes_before = self.bytes_written;
+        self.finish_implicit_turn(writer, timestamp).await?;
+        Ok(self.bytes_written - bytes_before)
+    }
+
+    async fn ensure_turn(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+        source_index: u64,
+    ) -> ThreadStoreResult<()> {
+        if self.active_turn.is_some() {
+            return Ok(());
+        }
+        let turn_id = format!("rollout-{source_index}");
+        self.start_implicit_turn(writer, timestamp, turn_id).await
+    }
+
+    async fn start_implicit_turn(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+        turn_id: String,
+    ) -> ThreadStoreResult<()> {
+        self.active_turn = Some(ActiveTurn {
+            id: turn_id.clone(),
+            explicit: false,
+            saw_user: false,
+        });
+        self.known_turn_ids.insert(turn_id.clone());
+        self.reasoning = None;
+        let started_at = DateTime::parse_from_rfc3339(timestamp)
+            .map_err(migration_error)?
+            .timestamp();
+        self.write_item(
+            writer,
+            timestamp,
+            RolloutItem::EventMsg(EventMsg::TurnStarted(TurnStartedEvent {
+                turn_id,
+                root_turn_id: None,
+                trace_id: None,
+                started_at: Some(started_at),
+                model_context_window: None,
+                collaboration_mode_kind: Default::default(),
+            })),
+        )
+        .await
+    }
+
+    async fn finish_implicit_turn(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+    ) -> ThreadStoreResult<()> {
+        let Some(turn) = self.active_turn.as_ref() else {
+            return Ok(());
+        };
+        if turn.explicit {
+            return Ok(());
+        }
+        let turn_id = turn.id.clone();
+        self.active_turn = None;
+        self.reasoning = None;
+        self.write_item(
+            writer,
+            timestamp,
+            RolloutItem::EventMsg(EventMsg::TurnComplete(TurnCompleteEvent {
+                turn_id,
+                last_agent_message: None,
+                error: None,
+                started_at: None,
+                completed_at: Some(
+                    DateTime::parse_from_rfc3339(timestamp)
+                        .map_err(migration_error)?
+                        .timestamp(),
+                ),
+                duration_ms: None,
+                time_to_first_token_ms: None,
+            })),
+        )
+        .await
+    }
+
+    async fn write_completed_item(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+        item: TurnItem,
+    ) -> ThreadStoreResult<()> {
+        let turn_id = self
+            .active_turn
+            .as_ref()
+            .map(|turn| turn.id.clone())
+            .ok_or_else(|| migration_error("completed rollout item has no active turn"))?;
+        self.write_completed_item_to_turn(writer, timestamp, turn_id, item)
+            .await
+    }
+
+    async fn write_completed_item_to_turn(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+        turn_id: String,
+        item: TurnItem,
+    ) -> ThreadStoreResult<()> {
+        let completed_at_ms = DateTime::parse_from_rfc3339(timestamp)
+            .map_err(migration_error)?
+            .timestamp_millis();
+        self.write_item(
+            writer,
+            timestamp,
+            RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+                thread_id: self.thread_id,
+                turn_id,
+                item,
+                started_at_ms: None,
+                completed_at_ms,
+            })),
+        )
+        .await
+    }
+
+    async fn write_reasoning(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+        source_index: u64,
+        text: String,
+        kind: ReasoningTextKind,
+    ) -> ThreadStoreResult<()> {
+        if text.is_empty() {
+            return Ok(());
+        }
+        self.ensure_turn(writer, timestamp, source_index).await?;
+        let mut item = match self.reasoning.take() {
+            Some(item) => item,
+            None => ReasoningItem {
+                id: self.next_item_id()?,
+                summary_text: Vec::new(),
+                raw_content: Vec::new(),
+            },
+        };
+        match kind {
+            ReasoningTextKind::Summary => item.summary_text.push(text),
+            ReasoningTextKind::Raw => item.raw_content.push(text),
+        }
+        self.reasoning = Some(item.clone());
+        self.write_completed_item(writer, timestamp, TurnItem::Reasoning(item))
+            .await
+    }
+
+    async fn write_item(
+        &mut self,
+        writer: &mut BufWriter<File>,
+        timestamp: &str,
+        item: RolloutItem,
+    ) -> ThreadStoreResult<()> {
+        let mut bytes = serde_json::to_vec(&RolloutLine {
+            timestamp: timestamp.to_string(),
+            ordinal: Some(self.next_ordinal),
+            item,
+        })
+        .map_err(migration_error)?;
+        bytes.push(b'\n');
+        writer.write_all(&bytes).await.map_err(migration_error)?;
+        let byte_count = u64::try_from(bytes.len())
+            .map_err(|_| migration_error("rollout record exceeds addressable size"))?;
+        self.output_byte_offset = self
+            .output_byte_offset
+            .checked_add(byte_count)
+            .ok_or_else(|| migration_error("paginated rollout byte offset overflow"))?;
+        self.bytes_written = self
+            .bytes_written
+            .checked_add(byte_count)
+            .ok_or_else(|| migration_error("paginated rollout byte count overflow"))?;
+        self.next_ordinal = self
+            .next_ordinal
+            .checked_add(1)
+            .ok_or_else(|| migration_error("paginated rollout ordinal overflow"))?;
+        Ok(())
+    }
+
+    fn next_item_id(&mut self) -> ThreadStoreResult<String> {
+        let item_id = format!("item-{}", self.next_item_index);
+        self.next_item_index = self
+            .next_item_index
+            .checked_add(1)
+            .ok_or_else(|| migration_error("legacy rollout item id overflow"))?;
+        Ok(item_id)
+    }
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/legacy_event.rs b/codex-rs/thread-store/src/local/rollout_migration/legacy_event.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ee0b5e82d846dcff77c88772161f08283b13289f
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/legacy_event.rs
@@ -0,0 +1,313 @@
+//! Converts legacy persisted events into modern paginated turn items.
+//!
+//! Legacy rollouts persisted events like `ExecCommandEnd`, `PatchApplyEnd`, and
+//! `McpToolCallEnd`. Paginated history instead persists `ItemCompleted(item)` records containing
+//! canonical `TurnItem`s.
+//!
+//! This module owns that old-event -> new-item mapping, including stable synthesized item IDs.
+//! It intentionally stays separate from live thread-history reduction because migration needs a
+//! frozen adapter for historical rollout payloads.
+
+use codex_extension_items::ExtensionItem;
+use codex_extension_items::image_generation::ImageGenerationItem;
+use codex_protocol::items::AgentMessageContent;
+use codex_protocol::items::AgentMessageItem;
+use codex_protocol::items::CommandExecutionItem;
+use codex_protocol::items::ContextCompactionItem;
+use codex_protocol::items::DynamicToolCallItem;
+use codex_protocol::items::DynamicToolCallStatus;
+use codex_protocol::items::EnteredReviewModeItem;
+use codex_protocol::items::ExitedReviewModeItem;
+use codex_protocol::items::FileChangeItem;
+use codex_protocol::items::McpToolCallError;
+use codex_protocol::items::McpToolCallItem;
+use codex_protocol::items::McpToolCallStatus;
+use codex_protocol::items::SubAgentActivityItem;
+use codex_protocol::items::TurnItem;
+use codex_protocol::items::UserMessageItem;
+use codex_protocol::items::WebSearchItem;
+use codex_protocol::models::ImageReference;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_protocol::protocol::UserMessageImageKind;
+use codex_protocol::user_input::UserInput;
+
+use crate::ThreadStoreResult;
+
+pub(super) fn user_message_item(
+    event: UserMessageEvent,
+    next_item_id: &mut impl FnMut() -> ThreadStoreResult<String>,
+) -> ThreadStoreResult<TurnItem> {
+    let mut content = Vec::new();
+    let has_image_order = event.has_complete_image_order();
+    if !event.message.trim().is_empty() {
+        content.push(UserInput::Text {
+            text: event.message,
+            text_elements: event.text_elements,
+        });
+    }
+    if has_image_order {
+        let mut inline_index = 0;
+        let mut file_index = 0;
+        for image_kind in event.image_order {
+            let (image, detail) = match image_kind {
+                UserMessageImageKind::Inline => {
+                    let Some(image_url) = event
+                        .images
+                        .as_deref()
+                        .and_then(|images| images.get(inline_index))
+                    else {
+                        continue;
+                    };
+                    let detail = event.image_details.get(inline_index).copied().flatten();
+                    inline_index += 1;
+                    (
+                        ImageReference::Inline {
+                            image_url: image_url.clone(),
+                        },
+                        detail,
+                    )
+                }
+                UserMessageImageKind::File => {
+                    let Some(file_id) = event
+                        .file_ids
+                        .as_deref()
+                        .and_then(|file_ids| file_ids.get(file_index))
+                    else {
+                        continue;
+                    };
+                    let detail = event.file_id_details.get(file_index).copied().flatten();
+                    file_index += 1;
+                    (
+                        ImageReference::File {
+                            file_id: file_id.clone(),
+                        },
+                        detail,
+                    )
+                }
+            };
+            content.push(UserInput::Image { image, detail });
+        }
+    } else if let Some(images) = event.images {
+        for (index, image_url) in images.into_iter().enumerate() {
+            content.push(UserInput::Image {
+                image: ImageReference::Inline { image_url },
+                detail: event.image_details.get(index).copied().flatten(),
+            });
+        }
+    }
+    if !has_image_order && let Some(file_ids) = event.file_ids {
+        for (index, file_id) in file_ids.into_iter().enumerate() {
+            content.push(UserInput::Image {
+                image: ImageReference::File { file_id },
+                detail: event.file_id_details.get(index).copied().flatten(),
+            });
+        }
+    }
+    for (index, path) in event.local_images.into_iter().enumerate() {
+        content.push(UserInput::LocalImage {
+            path,
+            detail: event.local_image_details.get(index).copied().flatten(),
+        });
+    }
+    if let Some(audio) = event.audio {
+        content.extend(
+            audio
+                .into_iter()
+                .map(|audio_url| UserInput::Audio { audio_url }),
+        );
+    }
+    content.extend(
+        event
+            .local_audio
+            .into_iter()
+            .map(|path| UserInput::LocalAudio { path }),
+    );
+    Ok(TurnItem::UserMessage(UserMessageItem {
+        id: next_item_id()?,
+        client_id: event.client_id,
+        content,
+    }))
+}
+
+/// Convert historical completion events into the canonical completed-item payloads
+/// that paginated rollouts persist. This deliberately remains a frozen migration
+/// adapter rather than sharing the live thread-history reducer: migration must
+/// preserve historical payloads while synthesizing stable item and turn IDs.
+pub(super) fn completed_item(
+    event: &EventMsg,
+    next_item_id: &mut impl FnMut() -> ThreadStoreResult<String>,
+) -> ThreadStoreResult<Option<(TurnItem, Option<String>)>> {
+    let result = match event {
+        EventMsg::AgentMessage(event) if !event.message.is_empty() => Some((
+            TurnItem::AgentMessage(AgentMessageItem {
+                id: next_item_id()?,
+                content: vec![AgentMessageContent::Text {
+                    text: event.message.clone(),
+                }],
+                phase: event.phase.clone(),
+                memory_citation: event.memory_citation.clone(),
+                delivery: event.delivery,
+                questions: event.questions.clone(),
+            }),
+            None,
+        )),
+        EventMsg::PatchApplyEnd(event) => Some((
+            TurnItem::FileChange(FileChangeItem {
+                id: event.call_id.clone(),
+                changes: event.changes.clone(),
+                status: Some(event.status.clone()),
+                auto_approved: None,
+                stdout: (!event.stdout.is_empty()).then(|| event.stdout.clone()),
+                stderr: (!event.stderr.is_empty()).then(|| event.stderr.clone()),
+            }),
+            (!event.turn_id.is_empty()).then(|| event.turn_id.clone()),
+        )),
+        EventMsg::McpToolCallEnd(event) => {
+            let (result, error) = match &event.result {
+                Ok(result) => (Some(result.clone()), None),
+                Err(message) => (
+                    None,
+                    Some(McpToolCallError {
+                        message: message.clone(),
+                    }),
+                ),
+            };
+            Some((
+                TurnItem::McpToolCall(McpToolCallItem {
+                    id: event.call_id.clone(),
+                    server: event.invocation.server.clone(),
+                    tool: event.invocation.tool.clone(),
+                    arguments: event
+                        .invocation
+                        .arguments
+                        .clone()
+                        .unwrap_or(serde_json::Value::Null),
+                    connector_id: event.connector_id.clone(),
+                    mcp_app_resource_uri: event.mcp_app_resource_uri.clone(),
+                    mcp_app_ui: event.mcp_app_ui.clone(),
+                    link_id: event.link_id.clone(),
+                    app_name: event.app_name.clone(),
+                    action_name: event.action_name.clone(),
+                    plugin_id: event.plugin_id.clone(),
+                    read_only_hint: event.read_only_hint,
+                    status: if event.is_success() {
+                        McpToolCallStatus::Completed
+                    } else {
+                        McpToolCallStatus::Failed
+                    },
+                    result,
+                    error,
+                    duration: Some(event.duration),
+                }),
+                (!event.turn_id.is_empty()).then(|| event.turn_id.clone()),
+            ))
+        }
+        EventMsg::WebSearchEnd(event) => Some((
+            TurnItem::WebSearch(WebSearchItem {
+                id: event.call_id.clone(),
+                query: event.query.clone(),
+                action: event.action.clone(),
+                results: event.results.clone(),
+            }),
+            None,
+        )),
+        EventMsg::ImageGenerationEnd(event) => Some((
+            TurnItem::Extension(ExtensionItem::ImageGeneration(ImageGenerationItem {
+                id: event.call_id.clone(),
+                status: event.status.clone(),
+                revised_prompt: event.revised_prompt.clone(),
+                result: event.result.clone(),
+                transparent_background: event.transparent_background,
+                failure: event.failure.clone(),
+                saved_path: event.saved_path.clone(),
+                imagegen_request_id: None,
+                generation_id: None,
+            })),
+            None,
+        )),
+        EventMsg::ContextCompacted(_) => Some((
+            TurnItem::ContextCompaction(ContextCompactionItem {
+                id: next_item_id()?,
+            }),
+            None,
+        )),
+        EventMsg::EnteredReviewMode(event) => Some((
+            TurnItem::EnteredReviewMode(EnteredReviewModeItem {
+                id: match event.item_id.clone() {
+                    Some(id) => id,
+                    None => next_item_id()?,
+                },
+                target: event.target.clone(),
+                user_facing_hint: event
+                    .user_facing_hint
+                    .clone()
+                    .unwrap_or_else(|| "Review requested.".to_string()),
+            }),
+            event.turn_id.clone(),
+        )),
+        EventMsg::ExitedReviewMode(event) => Some((
+            TurnItem::ExitedReviewMode(ExitedReviewModeItem {
+                id: match event.item_id.clone() {
+                    Some(id) => id,
+                    None => next_item_id()?,
+                },
+                review_output: event.review_output.clone(),
+            }),
+            event.turn_id.clone(),
+        )),
+        EventMsg::SubAgentActivity(event) => Some((
+            TurnItem::SubAgentActivity(SubAgentActivityItem {
+                id: event.event_id.clone(),
+                kind: event.kind,
+                agent_thread_id: event.agent_thread_id,
+                agent_path: event.agent_path.clone(),
+            }),
+            None,
+        )),
+        EventMsg::ExecCommandEnd(event) => Some((
+            TurnItem::CommandExecution(CommandExecutionItem {
+                model_context: None,
+                id: event.call_id.clone(),
+                plugin_id: event.plugin_id.clone(),
+                script_path: event.script_path.clone(),
+                process_id: event.process_id.clone(),
+                command: event.command.clone(),
+                cwd: event.cwd.clone(),
+                parsed_cmd: event.parsed_cmd.clone(),
+                source: event.source,
+                interaction_input: event.interaction_input.clone(),
+                status: event.status.clone().into(),
+                stdout: (!event.stdout.is_empty()).then(|| event.stdout.clone()),
+                stderr: (!event.stderr.is_empty()).then(|| event.stderr.clone()),
+                aggregated_output: (!event.aggregated_output.is_empty())
+                    .then(|| event.aggregated_output.clone()),
+                exit_code: Some(event.exit_code),
+                duration: Some(event.duration),
+                formatted_output: (!event.formatted_output.is_empty())
+                    .then(|| event.formatted_output.clone()),
+            }),
+            Some(event.turn_id.clone()),
+        )),
+        EventMsg::DynamicToolCallResponse(event) => Some((
+            TurnItem::DynamicToolCall(DynamicToolCallItem {
+                id: event.call_id.clone(),
+                namespace: event.namespace.clone(),
+                tool: event.tool.clone(),
+                arguments: event.arguments.clone(),
+                status: if event.success {
+                    DynamicToolCallStatus::Completed
+                } else {
+                    DynamicToolCallStatus::Failed
+                },
+                content_items: Some(event.content_items.clone()),
+                success: Some(event.success),
+                error: event.error.clone(),
+                duration: Some(event.duration),
+            }),
+            Some(event.turn_id.clone()),
+        )),
+        _ => None,
+    };
+    Ok(result)
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/line_parser.rs b/codex-rs/thread-store/src/local/rollout_migration/line_parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b8a50d044dd35578d7a43fb36de0b25f18d39df2
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/line_parser.rs
@@ -0,0 +1,201 @@
+//! Makes historical rollout JSON parse like today's protocol types.
+//!
+//! Legacy rollouts span a bunch of old wire shapes: renamed fields, old sandbox policy layouts,
+//! string timestamps, legacy command cwd paths, retired events, and payloads that only deserialize
+//! correctly after going through `serde_json::Value`.
+//!
+//! This module only applies narrowly scoped compatibility rewrites for shapes we know existed in
+//! persisted rollouts. It does not decide turn boundaries, rollback behavior, or what gets written
+//! into paginated history.
+
+use chrono::DateTime;
+use codex_rollout::RolloutLine;
+use codex_utils_path_uri::LegacyAppPathString;
+use codex_utils_path_uri::PathUri;
+use serde_json::Map;
+use serde_json::Value;
+
+/// Parse one legacy rollout line after applying narrowly scoped compatibility
+/// rewrites for historical wire shapes that current protocol types no longer
+/// accept.
+pub(super) fn parse_legacy_rollout_line(bytes: &[u8]) -> Result<Option<RolloutLine>, String> {
+    if bytes.iter().all(u8::is_ascii_whitespace) {
+        return Ok(None);
+    }
+
+    // Deserializing through Value is intentional. Some historical numeric
+    // payloads fail serde_json's streaming enum path but deserialize correctly
+    // once their tagged object shape has been materialized.
+    let value = serde_json::from_slice::<Value>(bytes).map_err(|error| error.to_string())?;
+    parse_legacy_rollout_value(value)
+}
+
+pub(super) fn parse_legacy_rollout_value(mut value: Value) -> Result<Option<RolloutLine>, String> {
+    if should_skip_retired_record(&value) {
+        return Ok(None);
+    }
+    normalize_legacy_turn_context(&mut value);
+    normalize_legacy_sandbox_policy(&mut value);
+    normalize_legacy_rate_limit_resets(&mut value);
+    normalize_legacy_review_entry(&mut value);
+    normalize_legacy_command_cwd(&mut value)?;
+    codex_rollout::decode_rollout_line(value)
+        .map(Some)
+        .map_err(|error| error.to_string())
+}
+
+fn should_skip_retired_record(value: &Value) -> bool {
+    matches!(
+        event_type(value),
+        Some("guardian_assessment" | "thread_name_updated" | "undo_completed")
+    ) || (rollout_type(value) == Some("response_item")
+        && value
+            .get("payload")
+            .and_then(Value::as_object)
+            .and_then(|payload| payload.get("type"))
+            .and_then(Value::as_str)
+            == Some("ghost_snapshot"))
+}
+
+fn normalize_legacy_turn_context(value: &mut Value) {
+    if rollout_type(value) != Some("turn_context") {
+        return;
+    }
+    let Some(payload) = payload_object_mut(value) else {
+        return;
+    };
+    let Some(collaboration_mode) = payload
+        .get_mut("collaboration_mode")
+        .and_then(Value::as_object_mut)
+    else {
+        return;
+    };
+    if collaboration_mode.contains_key("settings") {
+        return;
+    }
+
+    let mut settings = Map::new();
+    for key in ["model", "reasoning_effort", "developer_instructions"] {
+        if let Some(value) = collaboration_mode.get(key) {
+            settings.insert(key.to_string(), value.clone());
+        }
+    }
+    if !settings.is_empty() {
+        collaboration_mode.insert("settings".to_string(), Value::Object(settings));
+    }
+}
+
+fn normalize_legacy_review_entry(value: &mut Value) {
+    if event_type(value) != Some("entered_review_mode") {
+        return;
+    }
+    let Some(payload) = payload_object_mut(value) else {
+        return;
+    };
+    if payload.contains_key("target") {
+        return;
+    }
+    let Some(prompt) = payload.get("prompt").and_then(Value::as_str) else {
+        return;
+    };
+    payload.insert(
+        "target".to_string(),
+        serde_json::json!({
+            "type": "custom",
+            "instructions": prompt,
+        }),
+    );
+}
+
+fn normalize_legacy_rate_limit_resets(value: &mut Value) {
+    if event_type(value) != Some("token_count") {
+        return;
+    }
+    let Some(rate_limits) = payload_object_mut(value)
+        .and_then(|payload| payload.get_mut("rate_limits"))
+        .and_then(Value::as_object_mut)
+    else {
+        return;
+    };
+    for window_name in ["primary", "secondary"] {
+        let Some(window) = rate_limits
+            .get_mut(window_name)
+            .and_then(Value::as_object_mut)
+        else {
+            continue;
+        };
+        let Some(resets_at) = window.get("resets_at").and_then(Value::as_str) else {
+            continue;
+        };
+        let Ok(resets_at) = DateTime::parse_from_rfc3339(resets_at) else {
+            continue;
+        };
+        window.insert("resets_at".to_string(), Value::from(resets_at.timestamp()));
+    }
+}
+
+fn normalize_legacy_sandbox_policy(value: &mut Value) {
+    if rollout_type(value) != Some("turn_context") {
+        return;
+    }
+    let Some(sandbox_policy) = payload_object_mut(value)
+        .and_then(|payload| payload.get_mut("sandbox_policy"))
+        .and_then(Value::as_object_mut)
+    else {
+        return;
+    };
+    if sandbox_policy.contains_key("type") {
+        return;
+    }
+    if let Some(mode) = sandbox_policy.get("mode").cloned() {
+        sandbox_policy.insert("type".to_string(), mode);
+    }
+}
+
+fn normalize_legacy_command_cwd(value: &mut Value) -> Result<(), String> {
+    if !matches!(
+        event_type(value),
+        Some("exec_command_begin" | "exec_command_end")
+    ) {
+        return Ok(());
+    }
+    let Some(payload) = payload_object_mut(value) else {
+        return Ok(());
+    };
+    let Some(cwd) = payload.get("cwd").and_then(Value::as_str) else {
+        return Ok(());
+    };
+    if cwd.starts_with("file:") {
+        return Ok(());
+    }
+    let cwd = PathUri::try_from(LegacyAppPathString::from_string(cwd))
+        .map_err(|error| format!("invalid legacy command cwd: {error}"))?;
+    payload.insert(
+        "cwd".to_string(),
+        serde_json::to_value(cwd).map_err(|error| error.to_string())?,
+    );
+    Ok(())
+}
+
+fn rollout_type(value: &Value) -> Option<&str> {
+    value.get("type").and_then(Value::as_str)
+}
+
+fn event_type(value: &Value) -> Option<&str> {
+    if rollout_type(value) != Some("event_msg") {
+        return None;
+    }
+    value
+        .get("payload")
+        .and_then(Value::as_object)
+        .and_then(|payload| payload.get("type"))
+        .and_then(Value::as_str)
+}
+
+fn payload_object_mut(value: &mut Value) -> Option<&mut Map<String, Value>> {
+    value.get_mut("payload").and_then(Value::as_object_mut)
+}
+
+#[cfg(test)]
+#[path = "line_parser_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/rollout_migration/line_parser_tests.rs b/codex-rs/thread-store/src/local/rollout_migration/line_parser_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5b51ca99c88dfebe159638bf9c562b4e4c91a90c
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/line_parser_tests.rs
@@ -0,0 +1,228 @@
+use codex_protocol::protocol::EventMsg;
+use codex_rollout::RolloutItem;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+use super::parse_legacy_rollout_line;
+
+fn line(payload_type: &str, payload: serde_json::Value) -> Vec<u8> {
+    serde_json::to_vec(&json!({
+        "timestamp": "2025-01-03T12:00:00Z",
+        "type": payload_type,
+        "payload": payload,
+    }))
+    .expect("serialize fixture")
+}
+
+#[test]
+fn parses_legacy_numeric_event_payloads_through_value() {
+    let bytes = line(
+        "event_msg",
+        json!({
+            "type": "token_count",
+            "info": null,
+            "rate_limits": {
+                "primary": {
+                    "used_percent": 0.0,
+                    "window_minutes": 300,
+                    "resets_at": 1_770_414_841,
+                },
+                "secondary": {
+                    "used_percent": 12.5,
+                    "window_minutes": 10_080,
+                    "resets_at": 1_770_698_702,
+                },
+                "credits": {
+                    "has_credits": false,
+                    "unlimited": false,
+                    "balance": null,
+                },
+                "plan_type": null,
+            },
+        }),
+    );
+
+    let parsed = parse_legacy_rollout_line(&bytes)
+        .expect("parse legacy token count")
+        .expect("keep legacy token count");
+    assert!(matches!(
+        parsed.item,
+        RolloutItem::EventMsg(EventMsg::TokenCount(_))
+    ));
+}
+
+#[test]
+fn normalizes_legacy_rate_limit_reset_timestamps() {
+    let bytes = line(
+        "event_msg",
+        json!({
+            "type": "token_count",
+            "info": null,
+            "rate_limits": {
+                "primary": {
+                    "used_percent": 2,
+                    "window_minutes": 300,
+                    "resets_at": "2025-10-19T08:51:37.876641+00:00",
+                },
+                "secondary": null,
+                "credits": null,
+                "plan_type": null,
+            },
+        }),
+    );
+
+    let parsed = parse_legacy_rollout_line(&bytes)
+        .expect("parse legacy reset timestamp")
+        .expect("keep legacy token count");
+    assert!(matches!(
+        parsed.item,
+        RolloutItem::EventMsg(EventMsg::TokenCount(_))
+    ));
+}
+
+#[test]
+fn normalizes_legacy_turn_context_collaboration_mode() {
+    let cwd = std::env::temp_dir().to_string_lossy().into_owned();
+    let bytes = line(
+        "turn_context",
+        json!({
+            "cwd": cwd,
+            "approval_policy": "never",
+            "sandbox_policy": {"type": "danger-full-access"},
+            "model": "gpt-test",
+            "personality": null,
+            "collaboration_mode": {
+                "mode": "plan",
+                "model": "gpt-test",
+                "reasoning_effort": null,
+                "developer_instructions": null,
+            },
+            "effort": null,
+            "summary": "auto",
+        }),
+    );
+
+    let parsed = parse_legacy_rollout_line(&bytes)
+        .expect("parse legacy turn context")
+        .expect("keep legacy turn context");
+    let RolloutItem::TurnContext(context) = parsed.item else {
+        panic!("expected turn context");
+    };
+    assert_eq!(
+        context
+            .collaboration_mode
+            .expect("collaboration mode")
+            .model(),
+        "gpt-test"
+    );
+}
+
+#[test]
+fn normalizes_legacy_turn_context_sandbox_policy() {
+    let cwd = std::env::temp_dir().to_string_lossy().into_owned();
+    let bytes = line(
+        "turn_context",
+        json!({
+            "cwd": cwd,
+            "approval_policy": "never",
+            "sandbox_policy": {"mode": "danger-full-access"},
+            "model": "gpt-test",
+            "personality": null,
+            "effort": null,
+            "summary": "auto",
+        }),
+    );
+
+    let parsed = parse_legacy_rollout_line(&bytes)
+        .expect("parse legacy sandbox policy")
+        .expect("keep legacy turn context");
+    assert!(matches!(parsed.item, RolloutItem::TurnContext(_)));
+}
+
+#[test]
+fn normalizes_legacy_review_entry_prompt() {
+    let bytes = line(
+        "event_msg",
+        json!({
+            "type": "entered_review_mode",
+            "prompt": "review these changes",
+            "user_facing_hint": "Review requested.",
+        }),
+    );
+
+    let parsed = parse_legacy_rollout_line(&bytes)
+        .expect("parse legacy review entry")
+        .expect("keep legacy review entry");
+    assert!(matches!(
+        parsed.item,
+        RolloutItem::EventMsg(EventMsg::EnteredReviewMode(_))
+    ));
+}
+
+#[test]
+fn normalizes_legacy_plain_command_cwd() {
+    let cwd = std::env::temp_dir().to_string_lossy().into_owned();
+    let bytes = line(
+        "event_msg",
+        json!({
+            "type": "exec_command_end",
+            "call_id": "call-1",
+            "turn_id": "turn-1",
+            "command": ["echo", "ok"],
+            "cwd": cwd,
+            "parsed_cmd": [],
+            "source": "agent",
+            "stdout": "",
+            "stderr": "",
+            "aggregated_output": "",
+            "exit_code": 0,
+            "duration": {"secs": 0, "nanos": 0},
+            "formatted_output": "",
+            "status": "completed",
+        }),
+    );
+
+    let parsed = parse_legacy_rollout_line(&bytes)
+        .expect("parse legacy command")
+        .expect("keep legacy command");
+    assert!(matches!(
+        parsed.item,
+        RolloutItem::EventMsg(EventMsg::ExecCommandEnd(_))
+    ));
+}
+
+#[test]
+fn skips_only_known_retired_events() {
+    for event_type in [
+        "guardian_assessment",
+        "thread_name_updated",
+        "undo_completed",
+    ] {
+        let bytes = line("event_msg", json!({"type": event_type}));
+        assert!(
+            parse_legacy_rollout_line(&bytes)
+                .expect("inspect retired event")
+                .is_none()
+        );
+    }
+
+    let unknown = line("event_msg", json!({"type": "unknown_legacy_event"}));
+    assert!(parse_legacy_rollout_line(&unknown).is_err());
+}
+
+#[test]
+fn skips_legacy_ghost_snapshots() {
+    let ghost_snapshot = line(
+        "response_item",
+        json!({
+            "type": "ghost_snapshot",
+            "ghost_commit": {"id": "legacy"},
+        }),
+    );
+
+    assert!(
+        parse_legacy_rollout_line(&ghost_snapshot)
+            .expect("inspect ghost snapshot")
+            .is_none()
+    );
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/publish.rs b/codex-rs/thread-store/src/local/rollout_migration/publish.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4c0f9656fbcd9b4485abe34ba61efe36fdcedd25
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/publish.rs
@@ -0,0 +1,267 @@
+//! Filesystem helpers for safely publishing migrated rollouts.
+//!
+//! This module owns temporary rollout paths, durable `.pending` journals, compressed rollout
+//! staging, cleanup, and parent-directory syncs. The migration orchestrator decides when to call
+//! these helpers; this module keeps the low-level file operations in one place.
+//!
+//! A migration can crash between publishing JSONL and finishing SQLite metadata. The journal is
+//! the durable handoff between those steps, so cleanup must only remove it once the paginated
+//! rollout and SQLite state are both complete.
+
+use std::collections::HashSet;
+use std::fs::Permissions;
+use std::io;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::SystemTime;
+
+#[cfg(unix)]
+use std::os::unix::fs::OpenOptionsExt;
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+use codex_protocol::ThreadId;
+use codex_rollout::RolloutItem;
+use tokio::fs::File;
+use tokio::io::AsyncBufReadExt;
+use tokio::io::AsyncWriteExt;
+use tokio::io::BufReader;
+use tokio::io::BufWriter;
+
+use super::migration_error;
+use crate::ThreadStoreResult;
+
+const MIGRATION_JOURNAL_DIRECTORY: &str = "rollout-migrations";
+
+pub(super) fn migration_journal_path(codex_home: &Path, thread_id: ThreadId) -> PathBuf {
+    codex_home
+        .join(MIGRATION_JOURNAL_DIRECTORY)
+        .join(format!("{thread_id}.pending"))
+}
+
+pub(super) async fn pending_migration_thread_ids(
+    codex_home: &Path,
+) -> ThreadStoreResult<HashSet<ThreadId>> {
+    let mut entries = match tokio::fs::read_dir(codex_home.join(MIGRATION_JOURNAL_DIRECTORY)).await
+    {
+        Ok(entries) => entries,
+        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(HashSet::new()),
+        Err(error) => return Err(migration_error(error)),
+    };
+    let mut thread_ids = HashSet::new();
+    while let Some(entry) = entries.next_entry().await.map_err(migration_error)? {
+        if !entry.file_type().await.map_err(migration_error)?.is_file() {
+            continue;
+        }
+        let filename = entry.file_name();
+        let Some(thread_id) = filename
+            .to_str()
+            .and_then(|filename| filename.strip_suffix(".pending"))
+            .and_then(|thread_id| ThreadId::from_string(thread_id).ok())
+        else {
+            continue;
+        };
+        thread_ids.insert(thread_id);
+    }
+    Ok(thread_ids)
+}
+
+pub(super) fn staged_rollout_path(rollout_path: &Path) -> ThreadStoreResult<PathBuf> {
+    staged_path(rollout_path, "paginated")
+}
+
+pub(super) fn decompressed_staged_rollout_path(rollout_path: &Path) -> ThreadStoreResult<PathBuf> {
+    staged_path(rollout_path, "decompressed")
+}
+
+pub(super) fn compressed_staged_rollout_path(rollout_path: &Path) -> ThreadStoreResult<PathBuf> {
+    staged_path(rollout_path, "paginated.zst")
+}
+
+fn staged_path(rollout_path: &Path, suffix: &str) -> ThreadStoreResult<PathBuf> {
+    let filename = rollout_path
+        .file_name()
+        .and_then(|filename| filename.to_str())
+        .ok_or_else(|| migration_error("rollout path has no valid filename"))?;
+    Ok(rollout_path.with_file_name(format!(".{filename}.{suffix}.tmp")))
+}
+
+pub(super) async fn decompress_rollout_to_path(
+    compressed_path: &Path,
+    plain_path: &Path,
+) -> ThreadStoreResult<()> {
+    let compressed_path = compressed_path.to_path_buf();
+    let plain_path = plain_path.to_path_buf();
+    tokio::task::spawn_blocking(move || -> io::Result<()> {
+        let input = std::fs::File::open(compressed_path)?;
+        let mut decoder = zstd::stream::read::Decoder::new(input)?;
+        let mut options = std::fs::OpenOptions::new();
+        options.create(true).truncate(true).write(true);
+        #[cfg(unix)]
+        options.mode(0o600);
+        let mut output = options.open(plain_path)?;
+        #[cfg(unix)]
+        output.set_permissions(Permissions::from_mode(0o600))?;
+        io::copy(&mut decoder, &mut output)?;
+        output.flush()
+    })
+    .await
+    .map_err(migration_error)?
+    .map_err(migration_error)
+}
+
+pub(super) async fn compress_rollout_to_path(
+    plain_path: &Path,
+    compressed_path: &Path,
+    permissions: Permissions,
+    modified_at: Option<SystemTime>,
+) -> ThreadStoreResult<()> {
+    let plain_path = plain_path.to_path_buf();
+    let compressed_path = compressed_path.to_path_buf();
+    tokio::task::spawn_blocking(move || -> io::Result<()> {
+        let mut input = std::fs::File::open(plain_path)?;
+        let output = std::fs::OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .write(true)
+            .open(&compressed_path)?;
+        let mut encoder = zstd::stream::write::Encoder::new(output, 3)?;
+        io::copy(&mut input, &mut encoder)?;
+        let output = encoder.finish()?;
+        output.set_permissions(permissions)?;
+        if let Some(modified_at) = modified_at {
+            output.set_times(std::fs::FileTimes::new().set_modified(modified_at))?;
+        }
+        output.sync_all()?;
+
+        let input = std::fs::File::open(compressed_path)?;
+        let mut decoder = zstd::stream::read::Decoder::new(input)?;
+        io::copy(&mut decoder, &mut io::sink())?;
+        Ok(())
+    })
+    .await
+    .map_err(migration_error)?
+    .map_err(migration_error)
+}
+
+pub(super) fn rewritten_staged_rollout_path(staged_path: &Path) -> ThreadStoreResult<PathBuf> {
+    let filename = staged_path
+        .file_name()
+        .and_then(|filename| filename.to_str())
+        .ok_or_else(|| migration_error("staged rollout path has no valid filename"))?;
+    Ok(staged_path.with_file_name(format!("{filename}.head.tmp")))
+}
+
+pub(super) async fn rewrite_subagent_history_boundary(
+    staged_path: &Path,
+    boundary: u64,
+) -> ThreadStoreResult<()> {
+    let rewritten_path = rewritten_staged_rollout_path(staged_path)?;
+    let permissions = tokio::fs::metadata(staged_path)
+        .await
+        .map_err(migration_error)?
+        .permissions();
+    let source = File::open(staged_path).await.map_err(migration_error)?;
+    let mut source = BufReader::new(source);
+    let mut head_bytes = Vec::new();
+    source
+        .read_until(b'\n', &mut head_bytes)
+        .await
+        .map_err(migration_error)?;
+    let mut head = codex_rollout::parse_rollout_line_bytes(&head_bytes).map_err(migration_error)?;
+    let RolloutItem::SessionMeta(session_meta) = &mut head.item else {
+        return Err(migration_error(
+            "staged rollout head is not session metadata",
+        ));
+    };
+    session_meta.meta.subagent_history_start_ordinal = Some(boundary);
+
+    let rewritten = tokio::fs::OpenOptions::new()
+        .create(true)
+        .truncate(true)
+        .write(true)
+        .open(&rewritten_path)
+        .await
+        .map_err(migration_error)?;
+    rewritten
+        .set_permissions(permissions)
+        .await
+        .map_err(migration_error)?;
+    let mut rewritten = BufWriter::new(rewritten);
+    rewritten
+        .write_all(
+            serde_json::to_string(&head)
+                .map_err(migration_error)?
+                .as_bytes(),
+        )
+        .await
+        .map_err(migration_error)?;
+    rewritten.write_all(b"\n").await.map_err(migration_error)?;
+    tokio::io::copy(&mut source, &mut rewritten)
+        .await
+        .map_err(migration_error)?;
+    rewritten.flush().await.map_err(migration_error)?;
+    rewritten
+        .get_ref()
+        .sync_all()
+        .await
+        .map_err(migration_error)?;
+    drop(rewritten);
+    tokio::fs::rename(rewritten_path, staged_path)
+        .await
+        .map_err(migration_error)
+}
+
+pub(super) async fn remove_file_if_present(path: &Path) -> ThreadStoreResult<()> {
+    if tokio::fs::try_exists(path).await.map_err(migration_error)? {
+        tokio::fs::remove_file(path)
+            .await
+            .map_err(migration_error)?;
+    }
+    Ok(())
+}
+
+pub(super) async fn write_migration_journal(path: &Path) -> ThreadStoreResult<()> {
+    let parent = path
+        .parent()
+        .ok_or_else(|| migration_error("rollout migration journal has no parent directory"))?;
+    let parent_already_exists = tokio::fs::try_exists(parent)
+        .await
+        .map_err(migration_error)?;
+    tokio::fs::create_dir_all(parent)
+        .await
+        .map_err(migration_error)?;
+    if !parent_already_exists {
+        sync_parent_directory(parent).await?;
+    }
+    let file = tokio::fs::OpenOptions::new()
+        .create(true)
+        .truncate(true)
+        .write(true)
+        .open(path)
+        .await
+        .map_err(migration_error)?;
+    file.sync_all().await.map_err(migration_error)?;
+    drop(file);
+    sync_parent_directory(path).await
+}
+
+pub(super) async fn sync_parent_directory(path: &Path) -> ThreadStoreResult<()> {
+    #[cfg(unix)]
+    {
+        let parent = path
+            .parent()
+            .ok_or_else(|| migration_error("rollout path has no parent directory"))?
+            .to_path_buf();
+        tokio::task::spawn_blocking(move || std::fs::File::open(parent)?.sync_all())
+            .await
+            .map_err(migration_error)?
+            .map_err(migration_error)?;
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = path;
+    }
+    Ok(())
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/rollback.rs b/codex-rs/thread-store/src/local/rollout_migration/rollback.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7a0a5c108e2197554a68302e79109d07e430ef96
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/rollback.rs
@@ -0,0 +1,147 @@
+//! Defines which persisted history entries count as rollbackable user turns.
+//!
+//! Legacy `ThreadRolledBack { num_turns }` does not mean “drop the last N JSONL records.” A turn
+//! can include contextual user/developer messages, paired `ResponseItem` + `UserMessage` records,
+//! inter-agent communication, or compaction replacement history.
+//!
+//! This module mirrors the legacy cold-resume rollback boundary rules for persisted rollout shapes.
+//! It stays local to migration because core's live predicate also knows about dynamically
+//! registered contextual fragments that thread-store should not depend on.
+
+use codex_protocol::items::parse_hook_prompt_fragment;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::InterAgentCommunication;
+use std::borrow::Borrow;
+
+/// Match the rollback boundaries used by legacy history reconstruction without
+/// treating every persisted lifecycle as a user turn. This intentionally stays
+/// local to the frozen migration adapter: the full core predicate also knows
+/// about dynamically registered contextual fragments that thread-store cannot
+/// depend on.
+pub(super) fn counts_as_boundary(response: &ResponseItem) -> bool {
+    if matches!(response, ResponseItem::AgentMessage { .. }) {
+        return true;
+    }
+    let ResponseItem::Message { role, content, .. } = response else {
+        return false;
+    };
+    (role == "user" && !is_known_contextual_user_message_content(content))
+        || (role == "assistant" && InterAgentCommunication::is_message_content(content))
+}
+
+pub(super) fn is_pre_turn_context_update(response: &ResponseItem) -> bool {
+    let ResponseItem::Message { role, content, .. } = response else {
+        return false;
+    };
+    (role == "user" && is_known_contextual_user_message_content(content))
+        || (role == "developer" && is_known_contextual_developer_message_content(content))
+}
+
+/// Apply the same response-history cut used by legacy cold resume to a persisted
+/// compaction checkpoint. The migration adapter uses a frozen contextual-fragment
+/// matcher because thread-store cannot depend on core's runtime fragment registry.
+pub(super) fn drop_last_n_user_turns<T>(history: &mut Vec<T>, num_turns: u32)
+where
+    T: Borrow<ResponseItem>,
+{
+    if num_turns == 0 {
+        return;
+    }
+    let user_positions = history
+        .iter()
+        .enumerate()
+        .filter_map(|(index, item)| counts_as_boundary(item.borrow()).then_some(index))
+        .collect::<Vec<_>>();
+    let Some(&first_turn_index) = user_positions.first() else {
+        return;
+    };
+    let count = usize::try_from(num_turns).unwrap_or(usize::MAX);
+    let mut cut_index = if count >= user_positions.len() {
+        first_turn_index
+    } else {
+        user_positions[user_positions.len() - count]
+    };
+    while cut_index > first_turn_index
+        && is_pre_turn_context_update(history[cut_index - 1].borrow())
+    {
+        cut_index -= 1;
+    }
+    history.truncate(cut_index);
+}
+
+fn is_known_contextual_user_message_content(content: &[ContentItem]) -> bool {
+    content.iter().any(|item| {
+        let ContentItem::InputText { text } = item else {
+            return false;
+        };
+        is_known_contextual_user_text(text)
+    })
+}
+
+fn is_known_contextual_developer_message_content(content: &[ContentItem]) -> bool {
+    content.iter().any(|item| {
+        let ContentItem::InputText { text } = item else {
+            return false;
+        };
+        let text = text.trim_start();
+        [
+            "<permissions instructions>",
+            "<model_switch>",
+            "<managed_developer_instructions>",
+            "<apps_instructions>",
+            "<collaboration_mode>",
+            "<multi_agent_mode>",
+            "<environments_instructions>",
+            "<git_attribution>",
+            "<plugins_instructions>",
+            "<realtime_conversation>",
+            "<skills_instructions>",
+            "<tools>",
+            "<personality_spec>",
+            "<token_budget>",
+            "<context_window>",
+            "<context_window_guidance>",
+            "<rollout_budget>",
+        ]
+        .iter()
+        .any(|prefix| {
+            text.get(..prefix.len())
+                .is_some_and(|candidate| candidate.eq_ignore_ascii_case(prefix))
+        })
+    })
+}
+
+// Keep this frozen alongside the legacy migration adapter. Core's live predicate also knows
+// about dynamically registered fragments, but legacy rollouts only need these persisted shapes.
+fn is_known_contextual_user_text(text: &str) -> bool {
+    let text = text.trim();
+    parse_hook_prompt_fragment(text).is_some()
+        || [
+            ("# AGENTS.md instructions", "</INSTRUCTIONS>"),
+            ("<environment_context>", "</environment_context>"),
+            ("<skill>", "</skill>"),
+            ("<user_shell_command>", "</user_shell_command>"),
+            ("<turn_aborted>", "</turn_aborted>"),
+            ("<subagent_notification>", "</subagent_notification>"),
+            ("<recommended_plugins>", "</recommended_plugins>"),
+            ("<goal_context>", "</goal_context>"),
+        ]
+        .iter()
+        .any(|(start, end)| text.starts_with(start) && text.ends_with(end))
+        || (text.starts_with("<external_")
+            && text
+                .split_once('>')
+                .and_then(|(start, _)| start.strip_prefix("<external_"))
+                .is_some_and(|key| text.ends_with(&format!("</external_{key}>"))))
+        || (text.starts_with("<codex_internal_context")
+            && text.ends_with("</codex_internal_context>"))
+        || text.starts_with(
+            "Warning: The maximum number of unified exec processes you can keep open is",
+        )
+        || (text.starts_with("Warning: apply_patch was requested via ")
+            && text.ends_with("Use the apply_patch tool instead of exec_command."))
+        || text.starts_with(
+            "Warning: Your account was flagged for potentially high-risk cyber activity",
+        )
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/rollback_plan.rs b/codex-rs/thread-store/src/local/rollout_migration/rollback_plan.rs
new file mode 100644
index 0000000000000000000000000000000000000000..11a8c8d6d682d12c8d10f1dd1a485b8488c0afd3
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/rollback_plan.rs
@@ -0,0 +1,541 @@
+//! Decides which legacy records remain visible after historical rollback.
+//!
+//! Legacy rollback removes logical instruction turns, not a physical suffix of the rollout file.
+//! Most records happen to be ordered that way, but late completion events can target an older
+//! surviving turn after a newer turn has started. This planner keeps compact per-record ownership
+//! metadata for SQLite visibility, then combines it with `rollback_replay`'s cold-resume answer
+//! before the writer makes its second streaming pass. Retained checkpoints are reduced when
+//! rollback is encountered, never by reapplying old rollbacks to later checkpoints.
+
+use std::collections::HashMap;
+use std::collections::HashSet;
+
+use codex_protocol::ResponseItemId;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ImageReference;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_protocol::protocol::UserMessageImageKind;
+use codex_rollout::CompactedItem;
+use codex_rollout::RetainedContextEntry;
+use codex_rollout::RetainedInputSource;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+
+use super::migration_error;
+use super::rollback;
+use super::rollback_replay::ModelReplayPlanner;
+use crate::ThreadStoreResult;
+
+#[derive(Clone)]
+struct CompactionFrame {
+    record_index: usize,
+    boundary_depth: usize,
+    owner: Option<usize>,
+    item: CompactedItem,
+}
+
+#[derive(Clone)]
+struct PendingUserResponse {
+    boundary: usize,
+    content: Vec<ContentItem>,
+}
+
+struct InstructionBoundary {
+    record_index: usize,
+    message_id: Option<ResponseItemId>,
+    input_source: RetainedInputSource,
+    alive: bool,
+}
+
+struct RetainedFactSource {
+    record_index: usize,
+    turn_id: String,
+    acceptance_order: Option<u64>,
+}
+
+/// Compact plan keyed by parsed source-record index.
+pub(super) struct RollbackPlan {
+    record_boundaries: Vec<Option<usize>>,
+    boundary_alive: Vec<bool>,
+    compacted_items: HashMap<usize, CompactedItem>,
+}
+
+impl RollbackPlan {
+    pub(super) fn record_count(&self) -> usize {
+        self.record_boundaries.len()
+    }
+
+    pub(super) fn apply(
+        &self,
+        record_index: usize,
+        mut line: RolloutLine,
+    ) -> ThreadStoreResult<Option<RolloutLine>> {
+        let boundary = self
+            .record_boundaries
+            .get(record_index)
+            .ok_or_else(|| migration_error("rollback plan is shorter than source replay"))?;
+        if matches!(
+            &line.item,
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(_))
+        ) {
+            return Ok(None);
+        }
+        // A rolled-back turn can still own the empty checkpoint that keeps cold resume from
+        // replaying older history.
+        if let Some(compacted) = self.compacted_items.get(&record_index) {
+            line.item = RolloutItem::Compacted(compacted.clone());
+            return Ok(Some(line));
+        }
+        if boundary.is_some_and(|boundary| !self.boundary_alive[boundary]) {
+            return Ok(None);
+        }
+        Ok(Some(line))
+    }
+}
+
+/// Streaming builder for RollbackPlan.
+pub(super) struct RollbackPlanner {
+    record_boundaries: Vec<Option<usize>>,
+    boundaries: Vec<InstructionBoundary>,
+    boundary_stack: Vec<usize>,
+    active_turn_id: Option<String>,
+    pending_turn_records: Vec<usize>,
+    pending_context_records: Vec<usize>,
+    pending_user_response: Option<PendingUserResponse>,
+    pending_delivery_boundary: Option<usize>,
+    turn_boundaries: HashMap<String, usize>,
+    call_boundaries: HashMap<(String, String), Option<usize>>,
+    retained_fact_sources: Vec<RetainedFactSource>,
+    compactions: Vec<CompactionFrame>,
+    model_replay: ModelReplayPlanner,
+}
+
+impl RollbackPlanner {
+    pub(super) fn new() -> Self {
+        Self {
+            record_boundaries: Vec::new(),
+            boundaries: Vec::new(),
+            boundary_stack: Vec::new(),
+            active_turn_id: None,
+            pending_turn_records: Vec::new(),
+            pending_context_records: Vec::new(),
+            pending_user_response: None,
+            pending_delivery_boundary: None,
+            turn_boundaries: HashMap::new(),
+            call_boundaries: HashMap::new(),
+            retained_fact_sources: Vec::new(),
+            compactions: Vec::new(),
+            model_replay: ModelReplayPlanner::new(),
+        }
+    }
+
+    pub(super) fn observe(&mut self, line: &RolloutLine) -> ThreadStoreResult<()> {
+        let index = self.record_boundaries.len();
+        self.model_replay.observe(index, &line.item);
+        self.record_boundaries
+            .push(self.boundary_stack.last().copied());
+        let paired_user_boundary = match (&self.pending_user_response, &line.item) {
+            (Some(pending), RolloutItem::EventMsg(EventMsg::UserMessage(event)))
+                if user_response_matches_event(&pending.content, event) =>
+            {
+                Some(pending.boundary)
+            }
+            _ => None,
+        };
+        let paired_delivery_boundary = match (&self.pending_delivery_boundary, &line.item) {
+            (Some(boundary), RolloutItem::ResponseItem(response))
+                if matches!(&response.item, ResponseItem::AgentMessage { .. }) =>
+            {
+                Some(*boundary)
+            }
+            _ => None,
+        };
+        self.pending_user_response = None;
+        self.pending_delivery_boundary = None;
+
+        match &line.item {
+            RolloutItem::SessionMeta(_) => self.record_boundaries[index] = None,
+            RolloutItem::ResponseItem(response) => {
+                if let Some(boundary) = paired_delivery_boundary {
+                    self.record_boundaries[index] = Some(boundary);
+                    self.boundaries[boundary].message_id = response.id().cloned();
+                } else if rollback::counts_as_boundary(&response.item) {
+                    let boundary = self.start_boundary(index);
+                    self.boundaries[boundary].message_id = response.id().cloned();
+                    self.boundaries[boundary].input_source = response.metadata.as_ref().into();
+                    if let ResponseItem::Message { role, content, .. } = &response.item
+                        && role == "user"
+                    {
+                        self.pending_user_response = Some(PendingUserResponse {
+                            boundary,
+                            content: content.clone(),
+                        });
+                    }
+                } else if rollback::is_pre_turn_context_update(&response.item) {
+                    // Until another user boundary arrives, this is trailing context for the
+                    // previous turn. Keep that fallback owner so rollback drops it when there is
+                    // no later turn to attach it to.
+                    self.pending_context_records.push(index);
+                }
+                if let ResponseItem::FunctionCall { call_id, .. } = &response.item
+                    && let Some(turn_id) = response.turn_id().or(self.active_turn_id.as_deref())
+                {
+                    self.call_boundaries.insert(
+                        (turn_id.to_owned(), call_id.clone()),
+                        self.record_boundaries[index],
+                    );
+                }
+            }
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(rollback)) => {
+                self.apply_rollback(rollback.num_turns)?;
+            }
+            RolloutItem::EventMsg(EventMsg::TurnStarted(event)) => {
+                self.active_turn_id = Some(event.turn_id.clone());
+                self.pending_turn_records.clear();
+                self.pending_turn_records.push(index);
+            }
+            RolloutItem::EventMsg(EventMsg::TurnComplete(event)) => {
+                self.assign_targeted_record(index, Some(event.turn_id.as_str()));
+                if self.active_turn_id.as_deref() == Some(event.turn_id.as_str()) {
+                    self.active_turn_id = None;
+                    self.pending_turn_records.clear();
+                }
+            }
+            RolloutItem::EventMsg(EventMsg::TurnAborted(event)) => {
+                self.assign_targeted_record(index, event.turn_id.as_deref());
+                if event
+                    .turn_id
+                    .as_deref()
+                    .is_some_and(|turn_id| self.active_turn_id.as_deref() == Some(turn_id))
+                {
+                    self.active_turn_id = None;
+                    self.pending_turn_records.clear();
+                }
+            }
+            RolloutItem::EventMsg(EventMsg::UserMessage(_)) => {
+                let boundary = paired_user_boundary.unwrap_or_else(|| self.start_boundary(index));
+                self.record_boundaries[index] = Some(boundary);
+            }
+            RolloutItem::EventMsg(EventMsg::ItemCompleted(event)) => {
+                self.assign_targeted_record(index, Some(event.turn_id.as_str()));
+            }
+            RolloutItem::EventMsg(event) => {
+                self.assign_targeted_record(index, explicit_event_turn_id(event));
+            }
+            RolloutItem::InterAgentCommunication(_) => {
+                self.start_boundary(index);
+            }
+            RolloutItem::InterAgentCommunicationMetadata { .. } => {
+                let boundary = self.start_boundary(index);
+                self.pending_delivery_boundary = Some(boundary);
+            }
+            RolloutItem::Compacted(item) => {
+                let owner = self
+                    .active_turn_id
+                    .as_deref()
+                    .and_then(|turn_id| self.turn_boundaries.get(turn_id).copied());
+                self.record_boundaries[index] = owner;
+                self.compactions.push(CompactionFrame {
+                    record_index: index,
+                    boundary_depth: self.boundary_stack.len(),
+                    owner,
+                    item: item.clone(),
+                });
+            }
+            RolloutItem::TurnContext(_) => {
+                if self.active_turn_id.is_some()
+                    && self
+                        .active_turn_id
+                        .as_deref()
+                        .is_none_or(|turn_id| !self.turn_boundaries.contains_key(turn_id))
+                {
+                    self.pending_turn_records.push(index);
+                }
+            }
+            RolloutItem::TokenUsageRecord(record) => {
+                self.assign_targeted_record(index, Some(record.turn_id.as_str()));
+            }
+            RolloutItem::WorldState(_) | RolloutItem::RealtimeItem(_) => {}
+            RolloutItem::RetainedContext(codex_rollout::RetainedContextEvent::VerifiedAnswer {
+                answer,
+                acceptance_order,
+            }) => {
+                let source = (answer.turn_id.clone(), answer.call_id.clone());
+                // A late answer still belongs to its call's instruction boundary, even
+                // if the same running turn has since received another user steer.
+                if let Some(boundary) = self.call_boundaries.get(&source) {
+                    self.record_boundaries[index] = *boundary;
+                } else {
+                    self.assign_targeted_record(index, Some(&answer.turn_id));
+                }
+                self.call_boundaries
+                    .insert(source, self.record_boundaries[index]);
+                self.retained_fact_sources.push(RetainedFactSource {
+                    record_index: index,
+                    turn_id: answer.turn_id.clone(),
+                    acceptance_order: *acceptance_order,
+                });
+            }
+            RolloutItem::SecurityRiskScore(_) => self.record_boundaries[index] = None,
+        }
+
+        Ok(())
+    }
+
+    pub(super) fn finish(self) -> RollbackPlan {
+        let RollbackPlanner {
+            record_boundaries,
+            boundaries,
+            compactions,
+            model_replay,
+            ..
+        } = self;
+        let replay_anchor = model_replay.finish().empty_replacement_history_compaction;
+        let boundary_alive = boundaries
+            .into_iter()
+            .map(|boundary| boundary.alive)
+            .collect::<Vec<_>>();
+        let compacted_items = compactions
+            .into_iter()
+            .filter_map(|mut frame| {
+                if Some(frame.record_index) == replay_anchor {
+                    frame.item.replacement_history = Some(Vec::new());
+                    frame.item.mcp_resource_origins = None;
+                    return Some((frame.record_index, frame.item));
+                }
+                frame
+                    .owner
+                    .is_none_or(|boundary| boundary_alive[boundary])
+                    .then_some((frame.record_index, frame.item))
+            })
+            .collect::<HashMap<_, _>>();
+        RollbackPlan {
+            record_boundaries,
+            boundary_alive,
+            compacted_items,
+        }
+    }
+
+    fn start_boundary(&mut self, index: usize) -> usize {
+        let boundary = self.boundaries.len();
+        self.boundaries.push(InstructionBoundary {
+            record_index: index,
+            message_id: None,
+            input_source: RetainedInputSource::Local(None),
+            alive: true,
+        });
+        let had_prior_boundary = !self.boundary_stack.is_empty();
+        if had_prior_boundary {
+            for pending_index in self.pending_context_records.drain(..) {
+                self.record_boundaries[pending_index] = Some(boundary);
+            }
+        } else {
+            self.pending_context_records.clear();
+        }
+        for pending_index in self.pending_turn_records.drain(..) {
+            self.record_boundaries[pending_index] = Some(boundary);
+        }
+        self.record_boundaries[index] = Some(boundary);
+        self.boundary_stack.push(boundary);
+        self.bind_active_turn(boundary);
+        boundary
+    }
+
+    fn bind_active_turn(&mut self, boundary: usize) {
+        if let Some(turn_id) = self.active_turn_id.as_ref() {
+            self.turn_boundaries.insert(turn_id.clone(), boundary);
+        }
+    }
+
+    fn assign_targeted_record(&mut self, index: usize, turn_id: Option<&str>) {
+        if let Some(boundary) = turn_id.and_then(|turn_id| self.turn_boundaries.get(turn_id)) {
+            self.record_boundaries[index] = Some(*boundary);
+        } else if self.active_turn_id.is_some()
+            && self
+                .active_turn_id
+                .as_deref()
+                .is_none_or(|turn_id| !self.turn_boundaries.contains_key(turn_id))
+        {
+            self.pending_turn_records.push(index);
+        }
+    }
+
+    fn apply_rollback(&mut self, num_turns: u32) -> ThreadStoreResult<()> {
+        let count = usize::try_from(num_turns).unwrap_or(usize::MAX);
+        if count == 0 {
+            return Ok(());
+        }
+        let depth_before = self.boundary_stack.len();
+        let mut removed_boundaries = HashSet::new();
+        let mut first_removed_boundary = None;
+        for _ in 0..count {
+            let Some(boundary) = self.boundary_stack.pop() else {
+                break;
+            };
+            self.boundaries[boundary].alive = false;
+            removed_boundaries.insert(boundary);
+            first_removed_boundary = Some(boundary);
+        }
+        if let Some(boundary) = first_removed_boundary {
+            let source = &self.boundaries[boundary];
+            let acceptance_order = source.input_source.acceptance_order();
+            if let Some(order) = acceptance_order {
+                // An answer may have been persisted before the queued instruction
+                // accepted ahead of it. Both are removed at that acceptance boundary.
+                for fact in &self.retained_fact_sources {
+                    if fact
+                        .acceptance_order
+                        .is_some_and(|accepted| accepted >= order)
+                    {
+                        self.record_boundaries[fact.record_index] = Some(boundary);
+                    }
+                }
+            }
+            let removed_turns = self
+                .turn_boundaries
+                .iter()
+                .filter(|(_, boundary)| removed_boundaries.contains(*boundary))
+                .map(|(turn_id, _)| turn_id.as_str())
+                .chain(
+                    self.retained_fact_sources
+                        .iter()
+                        .filter(|fact| {
+                            self.record_boundaries[fact.record_index]
+                                .is_some_and(|boundary| removed_boundaries.contains(&boundary))
+                        })
+                        .map(|fact| fact.turn_id.as_str()),
+                )
+                .collect::<Vec<_>>();
+            // Accepted answers can precede a queued instruction in the rollout,
+            // including in checkpoints. Legacy evidence uses the recorded boundary.
+            // Later checkpoints have not been observed yet and already reflect this rollback.
+            for frame in self.compactions.iter_mut().rev().take_while(|frame| {
+                acceptance_order.is_some() || frame.record_index >= source.record_index
+            }) {
+                if let Some(context) = &mut frame.item.retained_context {
+                    if acceptance_order.is_some()
+                        || context
+                            .ordered_entries()
+                            .any(|(_, entry)| matches!(entry, RetainedContextEntry::UserMessage(_)))
+                    {
+                        context.rollback(
+                            &removed_turns,
+                            source.message_id.as_ref().map(ResponseItemId::as_str),
+                            source.input_source,
+                        );
+                    } else {
+                        // Checkpoints written without instruction retention keep the legacy
+                        // source-call boundary, including answers before a same-turn steer.
+                        context.retain_answers(|answer| {
+                            self.call_boundaries
+                                .get(&(answer.turn_id.clone(), answer.call_id.clone()))
+                                .map_or_else(
+                                    || !removed_turns.contains(&answer.turn_id.as_str()),
+                                    |boundary| {
+                                        boundary
+                                            .is_none_or(|boundary| self.boundaries[boundary].alive)
+                                    },
+                                )
+                        });
+                    }
+                }
+            }
+        }
+        let compaction_index = self.compactions.iter().rposition(|frame| {
+            frame
+                .owner
+                .is_none_or(|boundary| self.boundaries[boundary].alive)
+        });
+        if let Some(compaction_index) = compaction_index {
+            let frame = &mut self.compactions[compaction_index];
+            let post_compaction_turns = depth_before.saturating_sub(frame.boundary_depth);
+            let remaining = count.saturating_sub(post_compaction_turns);
+            if remaining > 0 {
+                frame.item.mcp_resource_origins = None;
+                let replacement_history =
+                    frame.item.replacement_history.as_mut().ok_or_else(|| {
+                        migration_error(
+                            "legacy rollback crosses a compaction without replacement history",
+                        )
+                    })?;
+                rollback::drop_last_n_user_turns(
+                    replacement_history,
+                    u32::try_from(remaining).unwrap_or(u32::MAX),
+                );
+            }
+        }
+        self.active_turn_id = None;
+        self.pending_turn_records.clear();
+        self.pending_context_records.clear();
+        self.pending_user_response = None;
+        self.pending_delivery_boundary = None;
+        Ok(())
+    }
+}
+
+fn explicit_event_turn_id(event: &EventMsg) -> Option<&str> {
+    match event {
+        EventMsg::ExecCommandEnd(event) => Some(event.turn_id.as_str()),
+        EventMsg::PatchApplyEnd(event) => Some(event.turn_id.as_str()),
+        EventMsg::DynamicToolCallResponse(event) => Some(event.turn_id.as_str()),
+        EventMsg::EnteredReviewMode(event) => event.turn_id.as_deref(),
+        EventMsg::ExitedReviewMode(event) => event.turn_id.as_deref(),
+        _ => None,
+    }
+    .filter(|turn_id| !turn_id.is_empty())
+}
+
+fn user_response_matches_event(content: &[ContentItem], event: &UserMessageEvent) -> bool {
+    let mut text = String::new();
+    let mut images = Vec::new();
+    let mut file_ids = Vec::new();
+    let mut image_order = Vec::new();
+    let mut audio = Vec::new();
+    for item in content {
+        match item {
+            ContentItem::InputText { text: item_text } => text.push_str(item_text),
+            ContentItem::InputImage { image, .. } => match image {
+                ImageReference::Inline { image_url } => {
+                    image_order.push(UserMessageImageKind::Inline);
+                    images.push(image_url.as_str());
+                }
+                ImageReference::File { file_id } => {
+                    image_order.push(UserMessageImageKind::File);
+                    file_ids.push(file_id.as_str());
+                }
+            },
+            ContentItem::InputAudio { audio_url } => audio.push(audio_url.as_str()),
+            ContentItem::OutputText { .. } => return false,
+        }
+    }
+    text == event.message
+        && (!event.has_complete_image_order() || image_order == event.image_order)
+        && images
+            == event
+                .images
+                .as_deref()
+                .unwrap_or_default()
+                .iter()
+                .map(String::as_str)
+                .collect::<Vec<_>>()
+        && file_ids
+            == event
+                .file_ids
+                .as_deref()
+                .unwrap_or_default()
+                .iter()
+                .map(String::as_str)
+                .collect::<Vec<_>>()
+        && audio
+            == event
+                .audio
+                .as_deref()
+                .unwrap_or_default()
+                .iter()
+                .map(String::as_str)
+                .collect::<Vec<_>>()
+        && event.local_images.is_empty()
+        && event.local_audio.is_empty()
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/rollback_replay.rs b/codex-rs/thread-store/src/local/rollout_migration/rollback_replay.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ac23e9c5772b99ab6fa812518891ea92e21e66de
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/rollback_replay.rs
@@ -0,0 +1,195 @@
+//! Mirrors the part of legacy cold resume that chooses the model-history checkpoint.
+//!
+//! Legacy rollback has two jobs. The forward history reducer decides which turns remain visible,
+//! while cold resume scans backward to find the newest surviving compaction base. Migration needs
+//! both answers because removing rollback markers must not change what the next resume sends to
+//! the model.
+
+use codex_protocol::protocol::EventMsg;
+use codex_rollout::RolloutItem;
+
+use super::rollback;
+
+enum ReplayRecord {
+    Compacted {
+        record_index: usize,
+        has_replacement_history: bool,
+    },
+    Rollback(u32),
+    TurnStarted(String),
+    TurnComplete(String),
+    TurnAborted(Option<String>),
+    TurnContext(Option<String>),
+    UserBoundary,
+}
+
+#[derive(Default)]
+struct ReverseSegment {
+    turn_id: Option<String>,
+    counts_as_user_turn: bool,
+    compaction_index: Option<usize>,
+}
+
+/// Rewrite needed when legacy reverse replay skips a compaction segment but still resumes from
+/// the suffix after that checkpoint.
+pub(super) struct ModelReplayPlan {
+    pub(super) empty_replacement_history_compaction: Option<usize>,
+}
+
+pub(super) struct ModelReplayPlanner {
+    records: Vec<ReplayRecord>,
+}
+
+impl ModelReplayPlanner {
+    pub(super) fn new() -> Self {
+        Self {
+            records: Vec::new(),
+        }
+    }
+
+    pub(super) fn observe(&mut self, record_index: usize, item: &RolloutItem) {
+        let record = match item {
+            RolloutItem::Compacted(compacted) => ReplayRecord::Compacted {
+                record_index,
+                has_replacement_history: compacted.replacement_history.is_some(),
+            },
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(rollback)) => {
+                ReplayRecord::Rollback(rollback.num_turns)
+            }
+            RolloutItem::EventMsg(EventMsg::TurnStarted(event)) => {
+                ReplayRecord::TurnStarted(event.turn_id.clone())
+            }
+            RolloutItem::EventMsg(EventMsg::TurnComplete(event)) => {
+                ReplayRecord::TurnComplete(event.turn_id.clone())
+            }
+            RolloutItem::EventMsg(EventMsg::TurnAborted(event)) => {
+                ReplayRecord::TurnAborted(event.turn_id.clone())
+            }
+            RolloutItem::TurnContext(context) => ReplayRecord::TurnContext(context.turn_id.clone()),
+            RolloutItem::EventMsg(EventMsg::UserMessage(_))
+            | RolloutItem::InterAgentCommunication(_) => ReplayRecord::UserBoundary,
+            RolloutItem::ResponseItem(response) if rollback::counts_as_boundary(&response.item) => {
+                ReplayRecord::UserBoundary
+            }
+            RolloutItem::SessionMeta(_)
+            | RolloutItem::ResponseItem(_)
+            | RolloutItem::EventMsg(_)
+            | RolloutItem::InterAgentCommunicationMetadata { .. }
+            | RolloutItem::RealtimeItem(_)
+            | RolloutItem::TokenUsageRecord(_)
+            | RolloutItem::RetainedContext(_)
+            | RolloutItem::SecurityRiskScore(_)
+            | RolloutItem::WorldState(_) => return,
+        };
+        self.records.push(record);
+    }
+
+    pub(super) fn finish(self) -> ModelReplayPlan {
+        let mut selected_compaction = None;
+        let mut suffix_start = None;
+        let mut pending_rollback_turns = 0usize;
+        let mut active_segment: Option<ReverseSegment> = None;
+
+        for record in self.records.iter().rev() {
+            match record {
+                ReplayRecord::Compacted {
+                    record_index,
+                    has_replacement_history,
+                } => {
+                    let segment = active_segment.get_or_insert_with(ReverseSegment::default);
+                    if segment.compaction_index.is_none() && *has_replacement_history {
+                        segment.compaction_index = Some(*record_index);
+                        suffix_start = record_index.checked_add(1);
+                    }
+                }
+                ReplayRecord::Rollback(num_turns) => {
+                    pending_rollback_turns = pending_rollback_turns
+                        .saturating_add(usize::try_from(*num_turns).unwrap_or(usize::MAX));
+                }
+                ReplayRecord::TurnComplete(turn_id) => {
+                    let segment = active_segment.get_or_insert_with(ReverseSegment::default);
+                    if segment.turn_id.is_none() {
+                        segment.turn_id = Some(turn_id.clone());
+                    }
+                }
+                ReplayRecord::TurnAborted(turn_id) => {
+                    if let Some(segment) = active_segment.as_mut() {
+                        if segment.turn_id.is_none() {
+                            segment.turn_id = turn_id.clone();
+                        }
+                    } else if turn_id.is_some() {
+                        active_segment = Some(ReverseSegment {
+                            turn_id: turn_id.clone(),
+                            ..Default::default()
+                        });
+                    }
+                }
+                ReplayRecord::TurnContext(turn_id) => {
+                    let segment = active_segment.get_or_insert_with(ReverseSegment::default);
+                    if segment.turn_id.is_none() {
+                        segment.turn_id = turn_id.clone();
+                    }
+                }
+                ReplayRecord::UserBoundary => {
+                    active_segment
+                        .get_or_insert_with(ReverseSegment::default)
+                        .counts_as_user_turn = true;
+                }
+                ReplayRecord::TurnStarted(turn_id) => {
+                    if active_segment.as_ref().is_some_and(|segment| {
+                        turn_ids_are_compatible(segment.turn_id.as_deref(), Some(turn_id.as_str()))
+                    }) && let Some(segment) = active_segment.take()
+                    {
+                        finalize_segment(
+                            segment,
+                            &mut selected_compaction,
+                            &mut pending_rollback_turns,
+                        );
+                    }
+                }
+            }
+        }
+
+        if let Some(segment) = active_segment {
+            finalize_segment(
+                segment,
+                &mut selected_compaction,
+                &mut pending_rollback_turns,
+            );
+        }
+
+        // If reverse replay saw a replacement-history checkpoint but rolled back its segment,
+        // it resumes from that checkpoint's suffix without using the checkpoint history. Keep an
+        // empty checkpoint in the paginated file so older SQLite-visible records do not leak back
+        // into model context after the rollback markers are gone.
+        let empty_replacement_history_compaction = selected_compaction
+            .is_none()
+            .then_some(suffix_start)
+            .flatten()
+            .and_then(|start| start.checked_sub(1));
+        ModelReplayPlan {
+            empty_replacement_history_compaction,
+        }
+    }
+}
+
+fn finalize_segment(
+    segment: ReverseSegment,
+    selected_compaction: &mut Option<usize>,
+    pending_rollback_turns: &mut usize,
+) {
+    if *pending_rollback_turns > 0 {
+        if segment.counts_as_user_turn {
+            *pending_rollback_turns -= 1;
+        }
+        return;
+    }
+    if selected_compaction.is_none() {
+        *selected_compaction = segment.compaction_index;
+    }
+}
+
+fn turn_ids_are_compatible(active_turn_id: Option<&str>, item_turn_id: Option<&str>) -> bool {
+    active_turn_id
+        .is_none_or(|turn_id| item_turn_id.is_none_or(|item_turn_id| item_turn_id == turn_id))
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/startup.rs b/codex-rs/thread-store/src/local/rollout_migration/startup.rs
new file mode 100644
index 0000000000000000000000000000000000000000..dbc48ed8c06fecaebf19b7f0e7b69d9985c103b2
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/startup.rs
@@ -0,0 +1,412 @@
+//! Decides whether startup needs to invoke legacy -> paginated rollout migration.
+//!
+//! It keeps startup cheap by storing a creation-ordered cursor in SQLite and checking only newer
+//! rollout files on later launches. When it finds legacy history or a pending recovery marker, it
+//! invokes the existing full migration path.
+//!
+//! Rollouts that background migration cannot finish are remembered so they do not hold the cursor
+//! back forever. Ordinary failures stay skipped until a manual migration retries them; busy
+//! rollouts are retried on later startups because the writer may have gone away.
+
+use std::collections::HashSet;
+use std::ffi::OsString;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+use std::time::SystemTime;
+
+use chrono::NaiveDateTime;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::StateDbHandle;
+use codex_state::RolloutMigrationCursor;
+use codex_state::RolloutMigrationSkippedRollout;
+
+use super::LocalThreadStore;
+use super::RolloutMigrationMode;
+use super::RolloutMigrationOptions;
+use super::RolloutMigrationReport;
+use super::RolloutMigrationStatus;
+use super::find_all_rollout_paths;
+use super::migration_error;
+use super::publish::migration_journal_path;
+use super::publish::pending_migration_thread_ids;
+use super::telemetry::RolloutMigrationTrigger;
+use super::thread_id_from_rollout_filename;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+const LEGACY_TO_PAGINATED_MIGRATION_ID: &str = "legacy_to_paginated_v1";
+const EMPTY_SKIP_REASON: &str = "empty";
+const FAILED_SKIP_REASON: &str = "failed";
+const MALFORMED_SESSION_META_SKIP_REASON: &str = "malformed_session_meta";
+const BUSY_SKIP_REASON: &str = "busy";
+const CURSOR_LOOKBACK_SECONDS: i64 = 48 * 60 * 60;
+const MAINTENANCE_RETRY_DELAY: Duration = Duration::from_secs(1);
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+struct RolloutFingerprint {
+    size_bytes: i64,
+    modified_at_ns: i64,
+}
+
+enum StartupInspection {
+    Paginated,
+    Legacy,
+    NeedsMigration,
+    Skipped,
+    Unresolved,
+}
+
+pub(super) async fn migrate_rollouts_on_startup(store: &LocalThreadStore) -> ThreadStoreResult<()> {
+    let Some(state_db) = store.state_db.as_ref() else {
+        return Ok(());
+    };
+    let paths = find_all_rollout_paths(&store.config.codex_home).await?;
+    let mut skipped_rollouts = state_db
+        .list_rollout_migration_skipped_rollouts(LEGACY_TO_PAGINATED_MIGRATION_ID)
+        .await
+        .map_err(migration_error)?;
+    retry_busy_rollouts(store, skipped_rollouts.as_slice(), paths.as_slice()).await?;
+    skipped_rollouts = state_db
+        .list_rollout_migration_skipped_rollouts(LEGACY_TO_PAGINATED_MIGRATION_ID)
+        .await
+        .map_err(migration_error)?;
+    if !pending_migration_thread_ids(&store.config.codex_home)
+        .await?
+        .is_empty()
+    {
+        return migrate_all_rollouts(store, paths, skipped_rollouts.as_slice()).await;
+    }
+    let skipped_file_names = skipped_rollout_file_names(store, skipped_rollouts.as_slice());
+    let state = state_db
+        .get_rollout_migration_state(LEGACY_TO_PAGINATED_MIGRATION_ID)
+        .await
+        .map_err(migration_error)?;
+
+    if state.is_none() {
+        return migrate_all_rollouts(store, paths, skipped_rollouts.as_slice()).await;
+    }
+
+    let last_checked_thread = state.and_then(|state| state.last_checked_thread);
+    let lookback_created_at = last_checked_thread.as_ref().map(|cursor| {
+        cursor
+            .thread_created_at
+            .saturating_sub(CURSOR_LOOKBACK_SECONDS)
+    });
+    let candidates = paths
+        .iter()
+        .filter(|path| {
+            !plain_rollout_file_name(path)
+                .is_some_and(|file_name| skipped_file_names.contains(&file_name))
+                && thread_creation_cursor(path).is_none_or(|cursor| {
+                    lookback_created_at.is_none_or(|lookback_created_at| {
+                        cursor.thread_created_at >= lookback_created_at
+                    })
+                })
+        })
+        .collect::<Vec<_>>();
+    if candidates.is_empty() {
+        return Ok(());
+    }
+
+    let mut unresolved = false;
+    for path in candidates {
+        match inspect_rollout_path(store, path).await? {
+            StartupInspection::Paginated | StartupInspection::Skipped => {}
+            StartupInspection::Legacy | StartupInspection::NeedsMigration => {
+                return migrate_all_rollouts(store, paths, skipped_rollouts.as_slice()).await;
+            }
+            StartupInspection::Unresolved => unresolved = true,
+        }
+    }
+    if unresolved {
+        return Ok(());
+    }
+
+    advance_last_checked_thread(store, paths.as_slice()).await
+}
+
+async fn migrate_all_rollouts(
+    store: &LocalThreadStore,
+    paths_before_migration: Vec<PathBuf>,
+    existing_skips: &[RolloutMigrationSkippedRollout],
+) -> ThreadStoreResult<()> {
+    let skipped_file_names = skipped_rollout_file_names(store, existing_skips);
+    let pending_thread_ids = pending_migration_thread_ids(&store.config.codex_home).await?;
+    let paths_to_migrate = paths_before_migration
+        .iter()
+        .filter(|path| {
+            !plain_rollout_file_name(path)
+                .is_some_and(|file_name| skipped_file_names.contains(&file_name))
+                || thread_id_from_rollout_filename(path)
+                    .is_some_and(|thread_id| pending_thread_ids.contains(&thread_id))
+        })
+        .cloned()
+        .collect();
+    let report = run_startup_migration(store, paths_to_migrate).await?;
+    for outcome in &report.outcomes {
+        update_skip_after_outcome(store, outcome).await?;
+    }
+    // Only mark the pre-migration snapshot; newer rollouts wait for the next startup check.
+    advance_last_checked_thread(store, paths_before_migration.as_slice()).await
+}
+
+async fn retry_busy_rollouts(
+    store: &LocalThreadStore,
+    skipped_rollouts: &[RolloutMigrationSkippedRollout],
+    discovered_paths: &[PathBuf],
+) -> ThreadStoreResult<()> {
+    let mut paths = Vec::new();
+    let mut moved_skip_paths = Vec::new();
+    for skipped_rollout in skipped_rollouts
+        .iter()
+        .filter(|skipped_rollout| skipped_rollout.skip_reason == BUSY_SKIP_REASON)
+    {
+        let stored_path = store.config.codex_home.join(&skipped_rollout.rollout_path);
+        let path = if tokio::fs::try_exists(&stored_path)
+            .await
+            .map_err(migration_error)?
+        {
+            Some(stored_path.clone())
+        } else {
+            // Archive/unarchive moves one rollout between roots, while compression swaps between
+            // its plain and compressed filenames. Match the plain basename across both.
+            let file_name = plain_rollout_file_name(&stored_path);
+            discovered_paths
+                .iter()
+                .find(|path| plain_rollout_file_name(path) == file_name)
+                .cloned()
+        };
+        let Some(path) = path else {
+            continue;
+        };
+        if path != stored_path {
+            moved_skip_paths.push(skipped_rollout.rollout_path.as_str());
+        }
+        paths.push(path);
+    }
+    if paths.is_empty() {
+        return Ok(());
+    }
+    let report = run_startup_migration(store, paths).await?;
+    for moved_skip_path in moved_skip_paths {
+        remove_skip(store, moved_skip_path).await?;
+    }
+    for outcome in &report.outcomes {
+        update_skip_after_outcome(store, outcome).await?;
+    }
+    Ok(())
+}
+
+async fn run_startup_migration(
+    store: &LocalThreadStore,
+    paths: Vec<PathBuf>,
+) -> ThreadStoreResult<RolloutMigrationReport> {
+    loop {
+        let Some(maintenance_guard) =
+            codex_rollout::try_acquire_rollout_maintenance_lock(&store.config.codex_home)
+                .map_err(migration_error)?
+        else {
+            tokio::time::sleep(MAINTENANCE_RETRY_DELAY).await;
+            continue;
+        };
+        // Avoid counting expected compression contention as a failed migration run. The migration
+        // path takes the real lock below, so retry if another maintainer wins this small gap.
+        drop(maintenance_guard);
+        match store
+            .migrate_rollouts_with_progress_for_trigger(
+                RolloutMigrationOptions {
+                    mode: RolloutMigrationMode::Apply,
+                    thread_ids: Vec::new(),
+                    max_mib_per_second: None,
+                },
+                |_| {},
+                RolloutMigrationTrigger::Startup,
+                super::RolloutMigrationPaths::Known(paths.clone()),
+            )
+            .await
+        {
+            Err(ThreadStoreError::Conflict { .. }) => continue,
+            result => return result,
+        }
+    }
+}
+
+async fn update_skip_after_outcome(
+    store: &LocalThreadStore,
+    outcome: &super::RolloutMigrationOutcome,
+) -> ThreadStoreResult<()> {
+    let relative_path = relative_rollout_path(store, &outcome.rollout_path);
+    match outcome.status {
+        RolloutMigrationStatus::Migrated | RolloutMigrationStatus::AlreadyPaginated => {
+            remove_skip(store, relative_path.as_str()).await
+        }
+        RolloutMigrationStatus::SkippedEmpty => {
+            record_current_skip(store, &outcome.rollout_path, EMPTY_SKIP_REASON).await
+        }
+        RolloutMigrationStatus::SkippedBusy => {
+            record_current_skip(store, &outcome.rollout_path, BUSY_SKIP_REASON).await
+        }
+        RolloutMigrationStatus::Failed => {
+            if outcome.thread_id.is_some_and(|thread_id| {
+                migration_journal_path(&store.config.codex_home, thread_id).exists()
+            }) {
+                return Ok(());
+            }
+            record_current_skip(store, &outcome.rollout_path, FAILED_SKIP_REASON).await
+        }
+        RolloutMigrationStatus::Eligible => Ok(()),
+    }
+}
+
+async fn inspect_rollout_path(
+    store: &LocalThreadStore,
+    path: &Path,
+) -> ThreadStoreResult<StartupInspection> {
+    let before = rollout_fingerprint(path).await?;
+    match codex_rollout::read_session_meta_line(path).await {
+        Ok(metadata) if metadata.meta.history_mode == ThreadHistoryMode::Legacy => {
+            Ok(StartupInspection::Legacy)
+        }
+        Ok(_) => Ok(StartupInspection::Paginated),
+        Err(_) => {
+            let after = rollout_fingerprint(path).await?;
+            if before != after {
+                return Ok(StartupInspection::Unresolved);
+            }
+            // The migration path re-reads empty files under the writer lock before deciding
+            // whether they are terminally empty or just waiting for SessionMeta.
+            if before.size_bytes == 0 {
+                return Ok(StartupInspection::NeedsMigration);
+            }
+            record_skip(store, path, before, MALFORMED_SESSION_META_SKIP_REASON).await?;
+            Ok(StartupInspection::Skipped)
+        }
+    }
+}
+
+async fn record_current_skip(
+    store: &LocalThreadStore,
+    path: &Path,
+    skip_reason: &str,
+) -> ThreadStoreResult<()> {
+    // These fields remain in the generic schema, but background skips are permanent now. Keep
+    // recording the best available fingerprint for humans inspecting SQLite.
+    let fingerprint = rollout_fingerprint(path).await.unwrap_or_default();
+    record_skip(store, path, fingerprint, skip_reason).await
+}
+
+async fn record_skip(
+    store: &LocalThreadStore,
+    path: &Path,
+    fingerprint: RolloutFingerprint,
+    skip_reason: &str,
+) -> ThreadStoreResult<()> {
+    let state_db = startup_state_db(store)?;
+    let skipped_rollout = RolloutMigrationSkippedRollout {
+        rollout_path: relative_rollout_path(store, path),
+        rollout_size_bytes: fingerprint.size_bytes,
+        rollout_modified_at_ns: fingerprint.modified_at_ns,
+        skip_reason: skip_reason.to_string(),
+    };
+    state_db
+        .record_rollout_migration_skip(LEGACY_TO_PAGINATED_MIGRATION_ID, &skipped_rollout)
+        .await
+        .map_err(migration_error)
+}
+
+async fn remove_skip(store: &LocalThreadStore, rollout_path: &str) -> ThreadStoreResult<()> {
+    startup_state_db(store)?
+        .remove_rollout_migration_skip(LEGACY_TO_PAGINATED_MIGRATION_ID, rollout_path)
+        .await
+        .map_err(migration_error)
+}
+
+async fn advance_last_checked_thread(
+    store: &LocalThreadStore,
+    paths: &[PathBuf],
+) -> ThreadStoreResult<()> {
+    let last_checked_thread = paths
+        .iter()
+        .filter_map(|path| thread_creation_cursor(path))
+        .max();
+    startup_state_db(store)?
+        .advance_rollout_migration_state(
+            LEGACY_TO_PAGINATED_MIGRATION_ID,
+            last_checked_thread.as_ref(),
+        )
+        .await
+        .map_err(migration_error)
+}
+
+fn startup_state_db(store: &LocalThreadStore) -> ThreadStoreResult<&StateDbHandle> {
+    store
+        .state_db
+        .as_ref()
+        .ok_or_else(|| migration_error("startup migration requires state db"))
+}
+
+fn thread_creation_cursor(path: &Path) -> Option<RolloutMigrationCursor> {
+    let name = path.file_name()?.to_str()?;
+    let stem = name
+        .strip_suffix(".jsonl.zst")
+        .or_else(|| name.strip_suffix(".jsonl"))?
+        .strip_prefix("rollout-")?;
+    let separator = stem.len().checked_sub(37)?;
+    let thread_id = stem.get(separator + 1..)?;
+    ThreadId::from_string(thread_id).ok()?;
+    let timestamp = NaiveDateTime::parse_from_str(stem.get(..separator)?, "%Y-%m-%dT%H-%M-%S")
+        .ok()?
+        .and_utc()
+        .timestamp();
+    Some(RolloutMigrationCursor {
+        thread_created_at: timestamp,
+        thread_id: thread_id.to_string(),
+    })
+}
+
+fn relative_rollout_path(store: &LocalThreadStore, path: &Path) -> String {
+    path.strip_prefix(&store.config.codex_home)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .replace('\\', "/")
+}
+
+fn skipped_rollout_file_names(
+    store: &LocalThreadStore,
+    skipped_rollouts: &[RolloutMigrationSkippedRollout],
+) -> HashSet<OsString> {
+    skipped_rollouts
+        .iter()
+        .filter_map(|skipped_rollout| {
+            plain_rollout_file_name(&store.config.codex_home.join(&skipped_rollout.rollout_path))
+        })
+        .collect()
+}
+
+fn plain_rollout_file_name(path: &Path) -> Option<OsString> {
+    codex_rollout::plain_rollout_path(path)
+        .file_name()
+        .map(std::ffi::OsStr::to_os_string)
+}
+
+async fn rollout_fingerprint(path: &Path) -> ThreadStoreResult<RolloutFingerprint> {
+    let metadata = tokio::fs::metadata(path).await.map_err(migration_error)?;
+    let size_bytes = i64::try_from(metadata.len()).map_err(migration_error)?;
+    let modified_at_ns = metadata
+        .modified()
+        .map_err(migration_error)?
+        .duration_since(SystemTime::UNIX_EPOCH)
+        .map_err(migration_error)?
+        .as_nanos();
+    let modified_at_ns = i64::try_from(modified_at_ns).map_err(migration_error)?;
+    Ok(RolloutFingerprint {
+        size_bytes,
+        modified_at_ns,
+    })
+}
+
+#[cfg(test)]
+#[path = "startup_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/rollout_migration/startup_tests.rs b/codex-rs/thread-store/src/local/rollout_migration/startup_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d2e144ca33aeb2881bb7d6bbd0c2977a6e5f4c11
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/startup_tests.rs
@@ -0,0 +1,548 @@
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::SessionMeta;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use codex_rollout::RolloutRecorder;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::super::publish::migration_journal_path;
+use super::super::publish::write_migration_journal;
+use super::super::thread_history;
+use super::LocalThreadStore;
+use crate::local::test_support::test_config;
+
+const TIMESTAMP: &str = "2025-01-03T12:00:00Z";
+
+fn write_rollout(home: &Path, thread_id: ThreadId, history_mode: ThreadHistoryMode) -> PathBuf {
+    let directory = home.join("sessions/2025/01/03");
+    fs::create_dir_all(&directory).expect("create rollout directory");
+    let path = directory.join(format!("rollout-2025-01-03T12-00-00-{thread_id}.jsonl"));
+    let mut file = fs::File::create(&path).expect("create legacy rollout");
+    let paginated = history_mode == ThreadHistoryMode::Paginated;
+    let metadata = SessionMeta {
+        session_id: thread_id.into(),
+        id: thread_id,
+        timestamp: TIMESTAMP.to_string(),
+        cwd: home.to_path_buf(),
+        originator: "test-originator".to_string(),
+        cli_version: "0.0.0".to_string(),
+        source: SessionSource::Cli,
+        model_provider: Some("test-provider".to_string()),
+        history_mode,
+        ..SessionMeta::default()
+    };
+    for (ordinal, item) in [
+        RolloutItem::SessionMeta(SessionMetaLine {
+            meta: metadata,
+            git: None,
+        }),
+        RolloutItem::EventMsg(EventMsg::UserMessage(UserMessageEvent {
+            message: "question".to_string(),
+            ..UserMessageEvent::default()
+        })),
+    ]
+    .into_iter()
+    .enumerate()
+    {
+        let line = RolloutLine {
+            timestamp: TIMESTAMP.to_string(),
+            ordinal: paginated.then_some(ordinal as u64),
+            item,
+        };
+        writeln!(
+            file,
+            "{}",
+            serde_json::to_string(&line).expect("serialize legacy record")
+        )
+        .expect("write legacy record");
+    }
+    path
+}
+
+fn move_to_timestamp(
+    home: &Path,
+    path: PathBuf,
+    session_day: &str,
+    filename_timestamp: &str,
+) -> PathBuf {
+    let directory = home.join(format!("sessions/{session_day}"));
+    fs::create_dir_all(&directory).expect("create rollout directory");
+    let stem = path
+        .file_name()
+        .and_then(|name| name.to_str())
+        .and_then(|name| name.strip_suffix(".jsonl"))
+        .expect("rollout filename");
+    let thread_id = stem
+        .get(stem.len().checked_sub(36).expect("thread id offset")..)
+        .expect("thread id in rollout filename");
+    let moved_path = directory.join(format!("rollout-{filename_timestamp}-{thread_id}.jsonl"));
+    fs::rename(path, &moved_path).expect("move rollout timestamp");
+    moved_path
+}
+
+async fn indexed_store(home: &Path) -> LocalThreadStore {
+    let config = test_config(home);
+    let rollout_config = RolloutConfig {
+        codex_home: config.codex_home.clone(),
+        sqlite: config.sqlite.clone(),
+        cwd: home.to_path_buf(),
+        model_provider_id: config.default_model_provider_id.clone(),
+        generate_memories: false,
+    };
+    let state_db = codex_rollout::state_db::try_init(&rollout_config)
+        .await
+        .expect("backfill legacy thread metadata");
+    LocalThreadStore::new(config, Some(state_db))
+}
+
+#[tokio::test]
+async fn records_and_advances_checked_thread() {
+    let home = TempDir::new().expect("create Codex home");
+    let legacy_thread_id = ThreadId::new();
+    let legacy_path = write_rollout(home.path(), legacy_thread_id, ThreadHistoryMode::Legacy);
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("migrate startup rollouts");
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&legacy_path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+
+    let newer_thread_id = ThreadId::new();
+    move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), newer_thread_id, ThreadHistoryMode::Paginated),
+        "2025/01/04",
+        "2025-01-04T12-00-00",
+    );
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("check newer paginated rollout");
+
+    let state = store
+        .state_db()
+        .await
+        .expect("state db")
+        .get_rollout_migration_state(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+        .await
+        .expect("read migration state")
+        .expect("migration state");
+    assert_eq!(
+        state
+            .last_checked_thread
+            .expect("last checked thread")
+            .thread_id,
+        newer_thread_id.to_string()
+    );
+}
+
+#[tokio::test]
+async fn checks_rollouts_within_the_cursor_lookback() {
+    let home = TempDir::new().expect("create Codex home");
+    let older_thread_id = ThreadId::new();
+    let older_path = move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), older_thread_id, ThreadHistoryMode::Legacy),
+        "2025/01/02",
+        "2025-01-02T12-00-00",
+    );
+    let newer_path = move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), ThreadId::new(), ThreadHistoryMode::Paginated),
+        "2025/01/03",
+        "2025-01-03T12-00-00",
+    );
+    let store = indexed_store(home.path()).await;
+    let cursor = super::thread_creation_cursor(&newer_path).expect("newer rollout cursor");
+    store
+        .state_db()
+        .await
+        .expect("state db")
+        .advance_rollout_migration_state(super::LEGACY_TO_PAGINATED_MIGRATION_ID, Some(&cursor))
+        .await
+        .expect("seed migration cursor");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("check rollout behind cursor");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&older_path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+}
+
+#[tokio::test]
+async fn recovers_pending_migrations_after_retrying_busy_rollouts() {
+    let home = TempDir::new().expect("create Codex home");
+    let pending_thread_id = ThreadId::new();
+    write_rollout(home.path(), pending_thread_id, ThreadHistoryMode::Legacy);
+    let busy_thread_id = ThreadId::new();
+    let busy_path = move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), busy_thread_id, ThreadHistoryMode::Legacy),
+        "2025/01/04",
+        "2025-01-04T12-00-00",
+    );
+    let store = indexed_store(home.path()).await;
+    let state_db = store.state_db().await.expect("state db");
+    let writer_guard = store
+        .acquire_writer_lock(busy_thread_id)
+        .expect("hold cross-process writer lock");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("migrate and record busy rollout");
+    drop(writer_guard);
+    thread_history::delete_thread(&store, pending_thread_id)
+        .await
+        .expect("simulate missing projection");
+    let journal_path = migration_journal_path(home.path(), pending_thread_id);
+    write_migration_journal(&journal_path)
+        .await
+        .expect("simulate pending migration marker");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("retry busy rollout before recovery");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&busy_path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+    assert!(!journal_path.exists());
+    assert!(
+        thread_history::projection_state(&store, pending_thread_id)
+            .await
+            .expect("read repaired projection")
+            .is_some()
+    );
+    assert!(
+        state_db
+            .list_rollout_migration_skipped_rollouts(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read skipped rollouts")
+            .is_empty()
+    );
+}
+
+#[tokio::test]
+async fn waits_for_a_live_writer_before_migrating() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(home.path(), thread_id, ThreadHistoryMode::Legacy);
+    let store = indexed_store(home.path()).await;
+    let live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    let migration_store = store.clone();
+    let mut migration = tokio::spawn(async move {
+        migration_store
+            .migrate_rollouts_on_startup()
+            .await
+            .expect("migrate startup rollouts");
+    });
+
+    assert!(
+        tokio::time::timeout(Duration::from_millis(50), &mut migration)
+            .await
+            .is_err(),
+        "migration should wait for the live writer"
+    );
+    drop(live_writer_guard);
+    migration.await.expect("join startup migration");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+}
+
+#[tokio::test]
+async fn waits_for_rollout_maintenance_before_migrating() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(home.path(), thread_id, ThreadHistoryMode::Legacy);
+    let store = indexed_store(home.path()).await;
+    let maintenance_guard = codex_rollout::try_acquire_rollout_maintenance_lock(home.path())
+        .expect("acquire rollout maintenance lock")
+        .expect("claim rollout maintenance lock");
+    let migration_store = store.clone();
+    let mut migration = tokio::spawn(async move {
+        migration_store
+            .migrate_rollouts_on_startup()
+            .await
+            .expect("migrate startup rollouts");
+    });
+
+    assert!(
+        tokio::time::timeout(Duration::from_millis(50), &mut migration)
+            .await
+            .is_err(),
+        "migration should wait for rollout maintenance"
+    );
+    drop(maintenance_guard);
+    tokio::time::timeout(Duration::from_secs(2), migration)
+        .await
+        .expect("migration should retry rollout maintenance")
+        .expect("join startup migration");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+}
+
+#[tokio::test]
+async fn permanently_skips_failed_rollouts_without_blocking_the_cursor() {
+    let home = TempDir::new().expect("create Codex home");
+    let failed_thread_id = ThreadId::new();
+    let failed_path = write_rollout(home.path(), failed_thread_id, ThreadHistoryMode::Legacy);
+    let store = indexed_store(home.path()).await;
+    let state_db = store.state_db().await.expect("state db");
+    let metadata = state_db
+        .get_thread(failed_thread_id)
+        .await
+        .expect("read thread metadata")
+        .expect("thread metadata");
+    state_db
+        .delete_thread(failed_thread_id)
+        .await
+        .expect("remove thread metadata");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("record failed rollout");
+    assert_eq!(
+        state_db
+            .get_rollout_migration_state(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read migration state")
+            .expect("migration state")
+            .last_checked_thread
+            .expect("checked thread")
+            .thread_id,
+        failed_thread_id.to_string()
+    );
+    assert_eq!(
+        state_db
+            .list_rollout_migration_skipped_rollouts(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read skipped rollouts")
+            .into_iter()
+            .map(|skipped_rollout| skipped_rollout.skip_reason)
+            .collect::<Vec<_>>(),
+        vec![super::FAILED_SKIP_REASON.to_string()]
+    );
+
+    state_db
+        .insert_thread_if_absent(&metadata)
+        .await
+        .expect("restore thread metadata");
+    let archived_directory = home.path().join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR);
+    fs::create_dir_all(&archived_directory).expect("create archived directory");
+    let archived_path = archived_directory.join(failed_path.file_name().expect("rollout filename"));
+    fs::rename(&failed_path, &archived_path).expect("archive failed rollout");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("skip failed rollout again");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&archived_path)
+            .await
+            .expect("read failed rollout metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Legacy
+    );
+}
+
+#[tokio::test]
+async fn retries_busy_rollouts_after_archive_and_compression_move() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), thread_id, ThreadHistoryMode::Legacy),
+        "2025/01/01",
+        "2025-01-01T12-00-00",
+    );
+    let newest_thread_id = ThreadId::new();
+    move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), newest_thread_id, ThreadHistoryMode::Paginated),
+        "2025/01/04",
+        "2025-01-04T12-00-00",
+    );
+    let store = indexed_store(home.path()).await;
+    let state_db = store.state_db().await.expect("state db");
+    let writer_guard = store
+        .acquire_writer_lock(thread_id)
+        .expect("hold cross-process writer lock");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("record busy rollout");
+    assert_eq!(
+        state_db
+            .get_rollout_migration_state(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read migration state")
+            .expect("migration state")
+            .last_checked_thread
+            .expect("checked thread")
+            .thread_id,
+        newest_thread_id.to_string()
+    );
+    assert_eq!(
+        state_db
+            .list_rollout_migration_skipped_rollouts(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read skipped rollouts")
+            .into_iter()
+            .map(|skipped_rollout| skipped_rollout.skip_reason)
+            .collect::<Vec<_>>(),
+        vec![super::BUSY_SKIP_REASON.to_string()]
+    );
+
+    drop(writer_guard);
+    let archived_directory = home.path().join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR);
+    fs::create_dir_all(&archived_directory).expect("create archived directory");
+    let archived_path = archived_directory.join(path.file_name().expect("rollout filename"));
+    fs::rename(&path, &archived_path).expect("archive busy rollout");
+    let compressed_path = archived_path.with_extension("jsonl.zst");
+    let mut input = fs::File::open(&archived_path).expect("open archived rollout");
+    let output = fs::File::create(&compressed_path).expect("create compressed rollout");
+    let mut encoder = zstd::stream::write::Encoder::new(output, 0).expect("create encoder");
+    std::io::copy(&mut input, &mut encoder).expect("compress archived rollout");
+    encoder.finish().expect("finish compressed rollout");
+    fs::remove_file(&archived_path).expect("remove plain archived rollout");
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("retry no-longer-busy rollout");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&compressed_path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+    assert!(
+        state_db
+            .list_rollout_migration_skipped_rollouts(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read skipped rollouts")
+            .is_empty()
+    );
+}
+
+#[tokio::test]
+async fn treats_writer_owned_empty_rollouts_as_busy() {
+    let home = TempDir::new().expect("create Codex home");
+    write_rollout(home.path(), ThreadId::new(), ThreadHistoryMode::Paginated);
+    let store = indexed_store(home.path()).await;
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("seed startup cursor");
+
+    let thread_id = ThreadId::new();
+    let path = move_to_timestamp(
+        home.path(),
+        write_rollout(home.path(), thread_id, ThreadHistoryMode::Legacy),
+        "2025/01/04",
+        "2025-01-04T12-00-00",
+    );
+    let (items, _, _) = RolloutRecorder::load_rollout_items(&path)
+        .await
+        .expect("load rollout items");
+    let metadata = codex_rollout::builder_from_items(items.as_slice(), &path)
+        .expect("build thread metadata")
+        .build("test-provider");
+    let contents = fs::read(&path).expect("read rollout before emptying");
+    fs::write(&path, []).expect("empty rollout");
+    let state_db = store.state_db().await.expect("state db");
+    state_db
+        .upsert_thread(&metadata)
+        .await
+        .expect("seed thread metadata");
+    let writer_guard = store
+        .acquire_writer_lock(thread_id)
+        .expect("hold cross-process writer lock");
+
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("record empty rollout as busy");
+    assert_eq!(
+        state_db
+            .list_rollout_migration_skipped_rollouts(super::LEGACY_TO_PAGINATED_MIGRATION_ID)
+            .await
+            .expect("read skipped rollouts")
+            .into_iter()
+            .map(|skipped_rollout| skipped_rollout.skip_reason)
+            .collect::<Vec<_>>(),
+        vec![super::BUSY_SKIP_REASON.to_string()]
+    );
+
+    fs::write(&path, contents).expect("restore rollout");
+    drop(writer_guard);
+    store
+        .migrate_rollouts_on_startup()
+        .await
+        .expect("retry no-longer-empty rollout");
+
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&path)
+            .await
+            .expect("read migrated metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/subagent.rs b/codex-rs/thread-store/src/local/rollout_migration/subagent.rs
new file mode 100644
index 0000000000000000000000000000000000000000..775b6f447d2cbbad02486307e9a161cdb47c01d9
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/subagent.rs
@@ -0,0 +1,59 @@
+//! Selects a smaller resume context for legacy subagent rollouts.
+//!
+//! Legacy subagents copied the parent's full rollout into every child rollout. Migrating those
+//! files verbatim can preserve gigabytes of duplicated history even though a resumed subagent only
+//! needs its latest bounded model context.
+//!
+//! This module reverse-scans the legacy rollout for a safe model-context checkpoint and returns the
+//! smallest replay needed to resume from there. Malformed reverse-scanned records are skipped. If
+//! we cannot prove that a bounded replay is safe, we return `None` and let the caller fall back to
+//! full tolerant replay.
+
+use std::fs::File;
+use std::path::PathBuf;
+
+use codex_protocol::protocol::SessionMetaLine;
+use codex_rollout::ModelContextScan;
+use codex_rollout::ModelContextScanProgress;
+use codex_rollout::ReverseJsonlScanner;
+use codex_rollout::RolloutItem;
+use codex_rollout::ScanOutcome;
+use serde_json::Value;
+
+use super::line_parser;
+use super::migration_error;
+use crate::ThreadStoreResult;
+
+/// Returns a bounded replay when the legacy child has enough durable context to reconstruct from
+/// a suffix. Without that proof, the caller streams the complete legacy replay instead.
+pub(super) async fn select_bounded_context(
+    rollout_path: PathBuf,
+    session_meta: SessionMetaLine,
+) -> ThreadStoreResult<Option<Vec<RolloutItem>>> {
+    tokio::task::spawn_blocking(move || {
+        let file = File::open(rollout_path).map_err(migration_error)?;
+        let mut scanner = ReverseJsonlScanner::new(file)
+            .map_err(migration_error)?
+            .with_max_record_bytes(super::MAX_ROLLOUT_LINE_BYTES);
+        let mut scan = ModelContextScan::default();
+
+        while let Some(outcome) = scanner.scan_next::<Value>().map_err(migration_error)? {
+            let value = match outcome {
+                ScanOutcome::Parsed(value) => value,
+                ScanOutcome::Rejected(_) => continue,
+            };
+            let Ok(Some(line)) = line_parser::parse_legacy_rollout_value(value) else {
+                continue;
+            };
+            if scan.push(line.item) == ModelContextScanProgress::Complete {
+                let mut items = scan.finish(session_meta);
+                items.retain(|item| !matches!(item, RolloutItem::SessionMeta(_)));
+                return Ok(Some(items));
+            }
+        }
+
+        Ok(None)
+    })
+    .await
+    .map_err(migration_error)?
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration/telemetry.rs b/codex-rs/thread-store/src/local/rollout_migration/telemetry.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e27c66b5779183ab9be068bd62247ad329566476
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration/telemetry.rs
@@ -0,0 +1,152 @@
+//! Records low-cardinality migration metrics shared by manual and startup runs.
+//!
+//! Migration owns the outcome stream, so it is the one place that can count successful,
+//! skipped, and failed rollouts consistently. Callers only tell it why the run started.
+
+use std::time::Instant;
+
+use super::RolloutMigrationFailureReason;
+use super::RolloutMigrationMode;
+use super::RolloutMigrationOptions;
+use super::RolloutMigrationReport;
+use super::RolloutMigrationStatus;
+use crate::ThreadStoreResult;
+
+const RUN_METRIC: &str = "codex.rollout_migration.run";
+const RUN_DURATION_METRIC: &str = "codex.rollout_migration.run.duration_ms";
+const RUN_IO_BYTES_METRIC: &str = "codex.rollout_migration.run.io_bytes";
+const THREAD_METRIC: &str = "codex.rollout_migration.thread";
+
+#[derive(Clone, Copy)]
+pub(super) enum RolloutMigrationTrigger {
+    Manual,
+    Startup,
+}
+
+#[derive(Clone, Copy)]
+enum RolloutMigrationScope {
+    All,
+    Selected,
+}
+
+pub(super) struct RolloutMigrationTelemetry {
+    trigger: RolloutMigrationTrigger,
+    mode: RolloutMigrationMode,
+    scope: RolloutMigrationScope,
+    started_at: Instant,
+}
+
+impl RolloutMigrationTelemetry {
+    pub(super) fn new(trigger: RolloutMigrationTrigger, options: &RolloutMigrationOptions) -> Self {
+        Self {
+            trigger,
+            mode: options.mode,
+            scope: if options.thread_ids.is_empty() {
+                RolloutMigrationScope::All
+            } else {
+                RolloutMigrationScope::Selected
+            },
+            started_at: Instant::now(),
+        }
+    }
+
+    pub(super) fn finish(&self, result: &ThreadStoreResult<RolloutMigrationReport>) {
+        let Some(metrics) = codex_otel::global() else {
+            return;
+        };
+        let mut io_bytes = 0_u64;
+        if let Ok(report) = result {
+            for outcome in &report.outcomes {
+                let mut tags = vec![
+                    ("trigger", self.trigger.tag()),
+                    ("mode", self.mode.tag()),
+                    ("scope", self.scope.tag()),
+                    ("status", outcome.status.tag()),
+                ];
+                if let Some(failure_reason) = outcome.failure_reason {
+                    tags.push(("failure_reason", failure_reason.tag()));
+                }
+                let _ = metrics.counter(THREAD_METRIC, /*inc*/ 1, &tags);
+                io_bytes = io_bytes.saturating_add(outcome.bytes_processed);
+            }
+        }
+        let result = match result {
+            Err(_) => "error",
+            Ok(report)
+                if report
+                    .outcomes
+                    .iter()
+                    .any(|outcome| outcome.status == RolloutMigrationStatus::Failed) =>
+            {
+                "partial_failure"
+            }
+            Ok(_) => "success",
+        };
+        let tags = [
+            ("trigger", self.trigger.tag()),
+            ("mode", self.mode.tag()),
+            ("scope", self.scope.tag()),
+            ("result", result),
+        ];
+        let duration_ms = i64::try_from(self.started_at.elapsed().as_millis()).unwrap_or(i64::MAX);
+        let io_bytes = i64::try_from(io_bytes).unwrap_or(i64::MAX);
+        let _ = metrics.counter(RUN_METRIC, /*inc*/ 1, &tags);
+        let _ = metrics.histogram(RUN_DURATION_METRIC, duration_ms, &tags);
+        let _ = metrics.histogram(RUN_IO_BYTES_METRIC, io_bytes, &tags);
+    }
+}
+
+impl RolloutMigrationTrigger {
+    fn tag(self) -> &'static str {
+        match self {
+            Self::Manual => "manual",
+            Self::Startup => "startup",
+        }
+    }
+}
+
+impl RolloutMigrationMode {
+    fn tag(self) -> &'static str {
+        match self {
+            Self::DryRun => "dry_run",
+            Self::Apply => "apply",
+        }
+    }
+}
+
+impl RolloutMigrationScope {
+    fn tag(self) -> &'static str {
+        match self {
+            Self::All => "all",
+            Self::Selected => "selected",
+        }
+    }
+}
+
+impl RolloutMigrationStatus {
+    fn tag(self) -> &'static str {
+        match self {
+            Self::Eligible => "eligible",
+            Self::Migrated => "migrated",
+            Self::AlreadyPaginated => "already_paginated",
+            Self::SkippedEmpty => "skipped_empty",
+            Self::SkippedBusy => "skipped_busy",
+            Self::Failed => "failed",
+        }
+    }
+}
+
+impl RolloutMigrationFailureReason {
+    fn tag(self) -> &'static str {
+        match self {
+            Self::MissingSqliteMetadata => "missing_sqlite_metadata",
+            Self::InvalidSessionMetadata => "invalid_session_metadata",
+            Self::RolloutReadFailed => "rollout_read_failed",
+            Self::LegacyRolloutConversionFailed => "legacy_rollout_conversion_failed",
+            Self::SqliteMaterializationFailed => "sqlite_materialization_failed",
+            Self::RolloutPublishFailed => "rollout_publish_failed",
+            Self::InterruptedMigrationRecoveryFailed => "interrupted_migration_recovery_failed",
+            Self::Unknown => "unknown",
+        }
+    }
+}
diff --git a/codex-rs/thread-store/src/local/rollout_migration_tests.rs b/codex-rs/thread-store/src/local/rollout_migration_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7c85b6b0803dd7872a7e04a671111deb504f74e7
--- /dev/null
+++ b/codex-rs/thread-store/src/local/rollout_migration_tests.rs
@@ -0,0 +1,2769 @@
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+use codex_app_server_protocol::build_turns_from_rollout_items;
+use codex_extension_items::ExtensionItem;
+use codex_extension_items::image_generation::ImageGenerationFailure;
+use codex_extension_items::image_generation::ImageGenerationItem;
+use codex_protocol::AgentPath;
+use codex_protocol::ResponseItemId;
+use codex_protocol::ThreadId;
+use codex_protocol::config_types::ReasoningSummary;
+use codex_protocol::items::ReasoningItem;
+use codex_protocol::items::TurnItem;
+use codex_protocol::mcp::McpResourceOrigin;
+use codex_protocol::mcp::McpResourceOriginCheckpoint;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::ContentItemKind;
+use codex_protocol::models::ImageDetail;
+use codex_protocol::models::ImageReference;
+use codex_protocol::models::InternalChatMessageMetadataPassthrough;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::AgentMessageEvent;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::ImageGenerationEndEvent;
+use codex_protocol::protocol::InterAgentCommunication;
+use codex_protocol::protocol::ItemCompletedEvent;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_protocol::protocol::SessionMeta;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::SubAgentSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadRolledBackEvent;
+use codex_protocol::protocol::TurnCompleteEvent;
+use codex_protocol::protocol::TurnContextItem;
+use codex_protocol::protocol::TurnStartedEvent;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_protocol::protocol::UserMessageImageKind;
+use codex_protocol::user_input::UserInput;
+use codex_rollout::CompactedItem;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use tempfile::TempDir;
+
+use super::LocalThreadStore;
+use super::RolloutMigrationFailureReason;
+use super::RolloutMigrationMode;
+use super::RolloutMigrationOptions;
+use super::RolloutMigrationPaths;
+use super::RolloutMigrationProgress;
+use super::RolloutMigrationStatus;
+#[cfg(unix)]
+use super::decompress_rollout_to_path;
+use super::migration_journal_path;
+use super::telemetry::RolloutMigrationTrigger;
+use super::thread_history;
+use super::write_migration_journal;
+use crate::ItemSortKey;
+use crate::ListItemsParams;
+use crate::ListThreadsParams;
+use crate::ListTurnsParams;
+use crate::LoadThreadHistoryParams;
+use crate::SortDirection;
+use crate::StoredTurnItemsView;
+use crate::ThreadMetadataPatch;
+use crate::ThreadSortKey;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::TurnPage;
+use crate::UpdateThreadMetadataParams;
+use crate::local::test_support::test_config;
+
+const TIMESTAMP: &str = "2025-01-03T12:00:00Z";
+
+fn write_rollout(
+    home: &Path,
+    thread_id: ThreadId,
+    source: SessionSource,
+    items: Vec<RolloutItem>,
+) -> PathBuf {
+    write_rollout_with_fork(home, thread_id, source, /*forked_from_id*/ None, items)
+}
+
+fn write_rollout_with_fork(
+    home: &Path,
+    thread_id: ThreadId,
+    source: SessionSource,
+    forked_from_id: Option<ThreadId>,
+    items: Vec<RolloutItem>,
+) -> PathBuf {
+    let directory = home.join("sessions/2025/01/03");
+    fs::create_dir_all(&directory).expect("create rollout directory");
+    let path = directory.join(format!("rollout-2025-01-03T12-00-00-{thread_id}.jsonl"));
+    let mut file = fs::File::create(&path).expect("create legacy rollout");
+    let metadata = SessionMeta {
+        session_id: thread_id.into(),
+        id: thread_id,
+        forked_from_id,
+        timestamp: TIMESTAMP.to_string(),
+        cwd: home.to_path_buf(),
+        originator: "test-originator".to_string(),
+        cli_version: "0.0.0".to_string(),
+        source,
+        model_provider: Some("test-provider".to_string()),
+        ..SessionMeta::default()
+    };
+    let items = std::iter::once(RolloutItem::SessionMeta(SessionMetaLine {
+        meta: metadata,
+        git: None,
+    }))
+    .chain(items);
+    for item in items {
+        let line = RolloutLine {
+            timestamp: TIMESTAMP.to_string(),
+            ordinal: None,
+            item,
+        };
+        writeln!(
+            file,
+            "{}",
+            serde_json::to_string(&line).expect("serialize legacy record")
+        )
+        .expect("write legacy record");
+    }
+    path
+}
+
+fn move_to_archived(home: &Path, path: PathBuf) -> PathBuf {
+    let directory = home.join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR);
+    fs::create_dir_all(&directory).expect("create archived rollout directory");
+    let archived_path = directory.join(path.file_name().expect("rollout filename"));
+    fs::rename(path, &archived_path).expect("archive rollout");
+    archived_path
+}
+
+fn compress_rollout(path: &Path) -> PathBuf {
+    let compressed_path = path.with_extension("jsonl.zst");
+    let compressed = zstd::stream::encode_all(
+        fs::File::open(path).expect("open rollout"),
+        /*level*/ 3,
+    )
+    .expect("compress rollout");
+    fs::write(&compressed_path, compressed).expect("write compressed rollout");
+    fs::remove_file(path).expect("remove plain rollout");
+    compressed_path
+}
+
+fn user_message(text: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::UserMessage(UserMessageEvent {
+        message: text.to_string(),
+        ..UserMessageEvent::default()
+    }))
+}
+
+fn agent_message(text: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::AgentMessage(AgentMessageEvent {
+        message: text.to_string(),
+        phase: None,
+        memory_citation: None,
+        delivery: None,
+        questions: None,
+    }))
+}
+
+fn input_response_message(role: &str, text: &str) -> ResponseItem {
+    ResponseItem::Message {
+        id: None,
+        role: role.to_string(),
+        content: vec![ContentItem::InputText {
+            text: text.to_string(),
+        }],
+        phase: None,
+        internal_chat_message_metadata_passthrough: None,
+    }
+}
+
+fn rollout_response_item(item: ResponseItem) -> RolloutItem {
+    RolloutItem::ResponseItem(item.into())
+}
+
+fn exec_completion(turn_id: &str, call_id: &str) -> RolloutItem {
+    serde_json::from_value(json!({
+        "type": "event_msg",
+        "payload": {
+            "type": "exec_command_end",
+            "call_id": call_id,
+            "turn_id": turn_id,
+            "command": ["echo", "ok"],
+            "cwd": "file:///tmp",
+            "parsed_cmd": [],
+            "source": "agent",
+            "stdout": "ok",
+            "stderr": "",
+            "aggregated_output": "ok",
+            "exit_code": 0,
+            "duration": {"secs": 0, "nanos": 0},
+            "formatted_output": "ok",
+            "status": "completed"
+        }
+    }))
+    .expect("build legacy exec completion")
+}
+
+fn item_completed(turn_id: &str, item_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+        thread_id: ThreadId::new(),
+        turn_id: turn_id.to_string(),
+        item: TurnItem::Reasoning(ReasoningItem {
+            id: item_id.to_string(),
+            summary_text: vec!["summary".to_string()],
+            raw_content: Vec::new(),
+        }),
+        started_at_ms: None,
+        completed_at_ms: 1_735_905_601_000,
+    }))
+}
+
+fn started(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnStarted(TurnStartedEvent {
+        turn_id: turn_id.to_string(),
+        root_turn_id: None,
+        trace_id: None,
+        started_at: Some(1_735_905_600),
+        model_context_window: None,
+        collaboration_mode_kind: Default::default(),
+    }))
+}
+
+fn compacted(replacement_history: Vec<ResponseItem>) -> RolloutItem {
+    RolloutItem::Compacted(CompactedItem {
+        message: "checkpoint".to_string(),
+        replacement_history: Some(replacement_history.into_iter().map(Into::into).collect()),
+        retained_context: None,
+        guardian_history: None,
+        mcp_resource_origins: None,
+        window_number: Some(1),
+        first_window_id: None,
+        previous_window_id: None,
+        window_id: None,
+        compaction_response_id: None,
+        latest_token_usage_record: None,
+    })
+}
+
+fn completed(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnComplete(TurnCompleteEvent {
+        turn_id: turn_id.to_string(),
+        last_agent_message: None,
+        error: None,
+        started_at: Some(1_735_905_600),
+        completed_at: Some(1_735_905_601),
+        duration_ms: Some(1_000),
+        time_to_first_token_ms: None,
+    }))
+}
+
+fn read_rollout(path: &Path) -> Vec<RolloutLine> {
+    fs::read_to_string(path)
+        .expect("read migrated rollout")
+        .lines()
+        .map(|line| codex_rollout::parse_rollout_line(line).expect("parse migrated rollout"))
+        .collect()
+}
+
+fn apply_options() -> RolloutMigrationOptions {
+    RolloutMigrationOptions {
+        mode: RolloutMigrationMode::Apply,
+        max_mib_per_second: Some(1024),
+        ..RolloutMigrationOptions::default()
+    }
+}
+
+fn assert_failed_with_reason(
+    outcome: &super::RolloutMigrationOutcome,
+    failure_reason: RolloutMigrationFailureReason,
+) {
+    assert_eq!(
+        (outcome.status, outcome.failure_reason),
+        (RolloutMigrationStatus::Failed, Some(failure_reason))
+    );
+}
+
+async fn indexed_store(home: &Path) -> LocalThreadStore {
+    let config = test_config(home);
+    let rollout_config = RolloutConfig {
+        codex_home: config.codex_home.clone(),
+        sqlite: config.sqlite.clone(),
+        cwd: home.to_path_buf(),
+        model_provider_id: config.default_model_provider_id.clone(),
+        generate_memories: false,
+    };
+    let state_db = codex_rollout::state_db::try_init(&rollout_config)
+        .await
+        .expect("backfill legacy thread metadata");
+    LocalThreadStore::new(config, Some(state_db))
+}
+
+async fn list_active_summary_turns(store: &LocalThreadStore, thread_id: ThreadId) -> TurnPage {
+    store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("read projected turns")
+}
+
+#[tokio::test]
+async fn migration_publishes_canonical_projected_history_and_is_idempotent() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let user_event = UserMessageEvent {
+        message: "first question".to_string(),
+        images: Some(vec!["https://example.com/image.png".to_string()]),
+        image_details: vec![Some(ImageDetail::Original)],
+        file_ids: Some(vec!["file_123".to_string()]),
+        file_id_details: vec![Some(ImageDetail::High)],
+        image_order: vec![UserMessageImageKind::File, UserMessageImageKind::Inline],
+        ..Default::default()
+    };
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            RolloutItem::EventMsg(EventMsg::UserMessage(user_event)),
+            agent_message("first answer"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate legacy rollout");
+    assert_eq!(report.outcomes.len(), 1);
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+
+    let lines = read_rollout(&path);
+    assert_eq!(
+        lines.iter().map(|line| line.ordinal).collect::<Vec<_>>(),
+        (0..lines.len() as u64).map(Some).collect::<Vec<_>>()
+    );
+    assert!(matches!(
+        &lines[0].item,
+        RolloutItem::SessionMeta(metadata)
+            if metadata.meta.history_mode == ThreadHistoryMode::Paginated
+                && metadata.meta.id == thread_id
+                && metadata.meta.history_base.is_none()
+    ));
+    assert_eq!(
+        lines
+            .iter()
+            .filter(|line| matches!(line.item, RolloutItem::EventMsg(EventMsg::ItemCompleted(_))))
+            .count(),
+        2
+    );
+    let user_item = lines.iter().find_map(|line| match &line.item {
+        RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+            item: TurnItem::UserMessage(item),
+            ..
+        })) => Some(item),
+        _ => None,
+    });
+    let expected_content = vec![
+        UserInput::Text {
+            text: "first question".to_string(),
+            text_elements: Vec::new(),
+        },
+        UserInput::Image {
+            image: ImageReference::File {
+                file_id: "file_123".to_string(),
+            },
+            detail: Some(ImageDetail::High),
+        },
+        UserInput::Image {
+            image: ImageReference::Inline {
+                image_url: "https://example.com/image.png".to_string(),
+            },
+            detail: Some(ImageDetail::Original),
+        },
+    ];
+    assert_eq!(user_item.map(|item| &item.content), Some(&expected_content));
+
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(turns.turns.len(), 1);
+    assert_eq!(turns.turns[0].items.len(), 2);
+
+    let bytes = fs::read(&path).expect("read first migration");
+    let second = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("rerun migration");
+    assert_eq!(
+        second.outcomes[0].status,
+        RolloutMigrationStatus::AlreadyPaginated
+    );
+    assert_eq!(fs::read(&path).expect("read idempotent rollout"), bytes);
+}
+
+#[tokio::test]
+async fn migration_projects_explicit_and_implicit_legacy_completed_items() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let exec = exec_completion("explicit", "call-1");
+    let reasoning = serde_json::from_value(json!({
+        "type": "event_msg",
+        "payload": {"type": "agent_reasoning", "text": "summary"}
+    }))
+    .expect("build legacy reasoning summary");
+    let raw_reasoning = serde_json::from_value(json!({
+        "type": "event_msg",
+        "payload": {"type": "agent_reasoning_raw_content", "text": "raw"}
+    }))
+    .expect("build legacy reasoning content");
+    write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("explicit"),
+            exec,
+            completed("explicit"),
+            reasoning,
+            raw_reasoning,
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate legacy completion events");
+
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(turns.turns.len(), 2);
+    assert_eq!(turns.turns[0].turn_id, "explicit");
+    let items = store
+        .list_items(ListItemsParams {
+            thread_id,
+            turn_id: None,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            sort_key: ItemSortKey::CreatedAtOrdinal,
+            after_updated_at_ordinal: None,
+        })
+        .await
+        .expect("read projected items");
+    assert_eq!(items.items.len(), 2);
+    assert_eq!(items.items[0].turn_id, "explicit");
+    assert_eq!(items.items[1].turn_id, turns.turns[1].turn_id);
+    let command: serde_json::Value =
+        serde_json::from_slice(&items.items[0].item_json).expect("parse projected command");
+    let reasoning: serde_json::Value =
+        serde_json::from_slice(&items.items[1].item_json).expect("parse projected reasoning");
+    assert_eq!(command["type"], "commandExecution");
+    assert_eq!(reasoning["type"], "reasoning");
+    assert_eq!(reasoning["summary"], json!(["summary"]));
+    assert_eq!(reasoning["content"], json!(["raw"]));
+}
+
+#[tokio::test]
+async fn migration_preserves_image_generation_failure_metadata() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let expected_item = ImageGenerationItem {
+        id: "image-call".to_string(),
+        status: "failed".to_string(),
+        revised_prompt: Some("paint a blue whale".to_string()),
+        result: String::new(),
+        transparent_background: None,
+        failure: Some(ImageGenerationFailure::UsageLimitExceeded {
+            limit_id: "image_gen".to_string(),
+            resets_at: Some(1_786_150_800),
+        }),
+        saved_path: None,
+        imagegen_request_id: None,
+        generation_id: None,
+    };
+    let image_completion =
+        RolloutItem::EventMsg(EventMsg::ImageGenerationEnd(ImageGenerationEndEvent {
+            call_id: expected_item.id.clone(),
+            status: expected_item.status.clone(),
+            revised_prompt: expected_item.revised_prompt.clone(),
+            result: expected_item.result.clone(),
+            transparent_background: expected_item.transparent_background,
+            failure: expected_item.failure.clone(),
+            saved_path: expected_item.saved_path.clone(),
+        }));
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("image-turn"),
+            image_completion,
+            completed("image-turn"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate legacy image completion");
+
+    let migrated_item = read_rollout(&path)
+        .into_iter()
+        .find_map(|line| match line.item {
+            RolloutItem::EventMsg(EventMsg::ItemCompleted(event)) => Some(event.item),
+            _ => None,
+        })
+        .expect("migrated image completion");
+    let TurnItem::Extension(ExtensionItem::ImageGeneration(migrated_item)) = migrated_item else {
+        panic!("expected migrated extension image-generation item");
+    };
+    assert_eq!(migrated_item, expected_item);
+}
+
+#[tokio::test]
+async fn migration_keeps_late_completions_in_their_original_turn() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("old"),
+            user_message("old question"),
+            started("current"),
+            user_message("current question"),
+            exec_completion("old", "call-old"),
+            serde_json::from_value(json!({
+                "type": "event_msg",
+                "payload": {
+                    "type": "mcp_tool_call_end",
+                    "call_id": "mcp-old",
+                    "turn_id": "old",
+                    "invocation": {"server": "slack", "tool": "search", "arguments": {}},
+                    "duration": {"secs": 0, "nanos": 0},
+                    "result": {"Ok": {"content": []}}
+                }
+            }))
+            .expect("build late legacy MCP completion"),
+            agent_message("current answer"),
+            completed("current"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate late completion");
+
+    let started_turn_ids = read_rollout(&path)
+        .into_iter()
+        .filter_map(|line| match line.item {
+            RolloutItem::EventMsg(EventMsg::TurnStarted(event)) => Some(event.turn_id),
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(started_turn_ids, vec!["old", "current"]);
+
+    let items = store
+        .list_items(ListItemsParams {
+            thread_id,
+            turn_id: None,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            sort_key: ItemSortKey::CreatedAtOrdinal,
+            after_updated_at_ordinal: None,
+        })
+        .await
+        .expect("read projected late completion");
+    let item_turn_ids = items
+        .items
+        .iter()
+        .map(|item| item.turn_id.as_str())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        item_turn_ids,
+        vec!["old", "current", "old", "old", "current"]
+    );
+}
+
+#[tokio::test]
+async fn migration_hoists_delayed_session_meta_before_paginated_history() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(home.path(), thread_id, SessionSource::Cli, Vec::new());
+    let existing = fs::read_to_string(&path).expect("read legacy rollout");
+    let pre_header = RolloutLine {
+        timestamp: TIMESTAMP.to_string(),
+        ordinal: None,
+        item: user_message("before metadata"),
+    };
+    fs::write(
+        &path,
+        format!(
+            "{}\n{existing}",
+            serde_json::to_string(&pre_header).expect("serialize pre-header record")
+        ),
+    )
+    .expect("write pre-header rollout");
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate delayed session metadata");
+
+    let lines = read_rollout(&path);
+    assert_eq!(lines[0].ordinal, Some(0));
+    assert!(matches!(
+        &lines[0].item,
+        RolloutItem::SessionMeta(metadata)
+            if metadata.meta.id == thread_id
+                && metadata.meta.history_mode == ThreadHistoryMode::Paginated
+    ));
+    let turns = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::NotLoaded,
+        })
+        .await
+        .expect("read migrated turns");
+    assert_eq!(turns.turns.len(), 1);
+
+    let second = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("rerun migration");
+    assert_eq!(
+        second.outcomes[0].status,
+        RolloutMigrationStatus::AlreadyPaginated
+    );
+}
+
+#[tokio::test]
+async fn migration_preserves_valid_final_record_without_newline() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("question")],
+    );
+    let final_line = RolloutLine {
+        timestamp: TIMESTAMP.to_string(),
+        ordinal: None,
+        item: agent_message("answer"),
+    };
+    fs::OpenOptions::new()
+        .append(true)
+        .open(&path)
+        .expect("open legacy rollout")
+        .write_all(
+            serde_json::to_string(&final_line)
+                .expect("serialize final record")
+                .as_bytes(),
+        )
+        .expect("append final record");
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate legacy rollout");
+
+    assert_eq!(
+        read_rollout(&path)
+            .iter()
+            .filter(|line| matches!(line.item, RolloutItem::EventMsg(EventMsg::ItemCompleted(_))))
+            .count(),
+        2
+    );
+}
+
+#[tokio::test]
+async fn migration_applies_historical_rollbacks_before_sqlite_projection() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("keep"),
+            user_message("keep question"),
+            agent_message("keep answer"),
+            completed("keep"),
+            started("remove"),
+            user_message("remove question"),
+            agent_message("remove answer"),
+            completed("remove"),
+            started("shell"),
+            completed("shell"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            started("replacement"),
+            user_message("replacement question"),
+            agent_message("replacement answer"),
+            completed("replacement"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate rolled-back thread");
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+
+    let lines = read_rollout(&path);
+    assert!(!lines.iter().any(|line| matches!(
+        line.item,
+        RolloutItem::EventMsg(EventMsg::ThreadRolledBack(_))
+    )));
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(
+        turns
+            .turns
+            .iter()
+            .map(|turn| turn.turn_id.as_str())
+            .collect::<Vec<_>>(),
+        vec!["keep", "replacement"]
+    );
+}
+
+#[tokio::test]
+async fn migration_rolls_back_response_and_inter_agent_user_boundaries() {
+    let home = TempDir::new().expect("create Codex home");
+    let response_thread_id = ThreadId::new();
+    let response_path = write_rollout(
+        home.path(),
+        response_thread_id,
+        SessionSource::Cli,
+        vec![
+            rollout_response_item(input_response_message("user", "remove response boundary")),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let communication_thread_id = ThreadId::new();
+    let communication_path = write_rollout(
+        home.path(),
+        communication_thread_id,
+        SessionSource::Cli,
+        vec![
+            RolloutItem::InterAgentCommunication(InterAgentCommunication::new(
+                AgentPath::root(),
+                AgentPath::root().join("worker").expect("worker path"),
+                Vec::new(),
+                "remove communication boundary".to_string(),
+                /*trigger_turn*/ true,
+            )),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let contextual_thread_id = ThreadId::new();
+    let contextual_path = write_rollout(
+        home.path(),
+        contextual_thread_id,
+        SessionSource::Cli,
+        vec![
+            rollout_response_item(input_response_message("user", "keep first boundary")),
+            rollout_response_item(input_response_message(
+                "developer",
+                "<managed_developer_instructions>context only</managed_developer_instructions>",
+            )),
+            rollout_response_item(input_response_message(
+                "developer",
+                "<permissions instructions>context only</permissions instructions>",
+            )),
+            rollout_response_item(input_response_message(
+                "user",
+                "<environment_context>context only</environment_context>",
+            )),
+            rollout_response_item(input_response_message("user", "remove real user boundary")),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate legacy rollback boundaries");
+
+    assert!(
+        !read_rollout(&response_path)
+            .iter()
+            .any(|line| matches!(line.item, RolloutItem::ResponseItem(_)))
+    );
+    assert!(
+        !read_rollout(&communication_path)
+            .iter()
+            .any(|line| matches!(line.item, RolloutItem::InterAgentCommunication(_)))
+    );
+    assert_eq!(
+        read_rollout(&contextual_path)
+            .into_iter()
+            .filter_map(|line| match line.item {
+                RolloutItem::ResponseItem(response) => Some(response.into_item()),
+                _ => None,
+            })
+            .collect::<Vec<_>>(),
+        vec![input_response_message("user", "keep first boundary")]
+    );
+}
+
+#[tokio::test]
+async fn migration_drops_trailing_context_when_rollback_arrives_before_next_turn() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            rollout_response_item(input_response_message("user", "keep question")),
+            rollout_response_item(input_response_message("user", "remove question")),
+            rollout_response_item(input_response_message(
+                "user",
+                "<turn_aborted>remove this context too</turn_aborted>",
+            )),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate trailing rollback context");
+
+    assert_eq!(
+        read_rollout(&path)
+            .into_iter()
+            .filter_map(|line| match line.item {
+                RolloutItem::ResponseItem(response) => Some(response.into_item()),
+                _ => None,
+            })
+            .collect::<Vec<_>>(),
+        vec![input_response_message("user", "keep question")]
+    );
+}
+
+#[tokio::test]
+async fn migration_coalesces_response_first_user_message_rollback_boundary() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let file_id = "file_123".to_string();
+    let response = ResponseItem::Message {
+        id: None,
+        role: "user".to_string(),
+        content: vec![
+            ContentItem::InputText {
+                text: "remove question".to_string(),
+            },
+            ContentItem::InputImage {
+                image: ImageReference::File {
+                    file_id: file_id.clone(),
+                },
+                detail: None,
+            },
+        ],
+        phase: None,
+        internal_chat_message_metadata_passthrough: None,
+    };
+    let event = UserMessageEvent {
+        message: "remove question".to_string(),
+        file_ids: Some(vec![file_id]),
+        ..Default::default()
+    };
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            rollout_response_item(response),
+            RolloutItem::EventMsg(EventMsg::UserMessage(event)),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate response-first rollback");
+
+    assert!(
+        !read_rollout(&path)
+            .iter()
+            .any(|line| matches!(line.item, RolloutItem::ResponseItem(_)))
+    );
+}
+
+#[tokio::test]
+async fn migration_does_not_coalesce_distinct_adjacent_user_records() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            rollout_response_item(input_response_message("user", "copied parent question")),
+            user_message("child question"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate distinct adjacent user records");
+
+    assert_eq!(
+        read_rollout(&path)
+            .into_iter()
+            .filter_map(|line| match line.item {
+                RolloutItem::ResponseItem(response) => Some(response.into_item()),
+                _ => None,
+            })
+            .collect::<Vec<_>>(),
+        vec![input_response_message("user", "copied parent question")]
+    );
+}
+
+#[tokio::test]
+async fn migration_keeps_late_completions_for_surviving_turns_across_rollback() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("old"),
+            user_message("old question"),
+            started("remove"),
+            user_message("remove question"),
+            completed("old"),
+            exec_completion("old", "call-old"),
+            item_completed("old", "reason-old"),
+            exec_completion("remove", "call-remove"),
+            completed("remove"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            started("replacement"),
+            user_message("replacement question"),
+            completed("replacement"),
+        ],
+    );
+    let legacy_turns = build_turns_from_rollout_items(
+        &read_rollout(&path)
+            .into_iter()
+            .map(|line| line.item)
+            .collect::<Vec<_>>(),
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate late completion rollback");
+
+    let lines = read_rollout(&path);
+    assert!(!lines.iter().any(|line| matches!(
+        &line.item,
+        RolloutItem::EventMsg(EventMsg::ItemCompleted(event))
+            if event.item.id() == "call-remove"
+    )));
+    assert!(lines.iter().any(|line| matches!(
+        &line.item,
+        RolloutItem::EventMsg(EventMsg::ItemCompleted(event))
+            if event.turn_id == "old" && event.item.id() == "call-old"
+    )));
+    assert!(lines.iter().any(|line| matches!(
+        &line.item,
+        RolloutItem::EventMsg(EventMsg::ItemCompleted(event))
+            if event.turn_id == "old" && event.item.id() == "reason-old"
+    )));
+    assert!(lines.iter().any(|line| matches!(
+        &line.item,
+        RolloutItem::EventMsg(EventMsg::TurnComplete(event)) if event.turn_id == "old"
+    )));
+    assert!(!lines.iter().any(|line| matches!(
+        &line.item,
+        RolloutItem::EventMsg(EventMsg::TurnComplete(event)) if event.turn_id == "remove"
+    )));
+    let turns = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("read late-completion rollback turns");
+    let turn_ids = turns
+        .turns
+        .iter()
+        .map(|turn| turn.turn_id.as_str())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        turn_ids,
+        legacy_turns
+            .iter()
+            .map(|turn| turn.id.as_str())
+            .collect::<Vec<_>>()
+    );
+    let items = store
+        .list_items(ListItemsParams {
+            thread_id,
+            turn_id: None,
+            include_archived: false,
+            cursor: None,
+            page_size: 20,
+            sort_direction: SortDirection::Asc,
+            sort_key: ItemSortKey::CreatedAtOrdinal,
+            after_updated_at_ordinal: None,
+        })
+        .await
+        .expect("read late-completion rollback items");
+    for legacy_turn in &legacy_turns {
+        for legacy_item in &legacy_turn.items {
+            if legacy_item.id().starts_with("item-") {
+                continue;
+            }
+            assert_eq!(
+                items
+                    .items
+                    .iter()
+                    .find(|item| item.item_id == legacy_item.id())
+                    .map(|item| item.turn_id.as_str()),
+                Some(legacy_turn.id.as_str())
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn migration_rolls_back_inter_agent_metadata_with_its_delivery() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let delivery = InterAgentCommunication::new(
+        AgentPath::root(),
+        AgentPath::root().join("worker").expect("worker path"),
+        Vec::new(),
+        "remove delivery".to_string(),
+        /*trigger_turn*/ true,
+    );
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            RolloutItem::InterAgentCommunicationMetadata { trigger_turn: true },
+            rollout_response_item(delivery.to_model_input_item()),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate rolled-back inter-agent delivery");
+
+    assert!(!read_rollout(&path).iter().any(|line| match &line.item {
+        RolloutItem::InterAgentCommunicationMetadata { .. } => true,
+        RolloutItem::ResponseItem(response_item) => {
+            matches!(&response_item.item, ResponseItem::AgentMessage { .. })
+        }
+        _ => false,
+    }));
+}
+
+#[tokio::test]
+async fn migration_rolls_back_pre_compaction_turns_from_sqlite_history() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let RolloutItem::Compacted(mut checkpoint) = compacted(vec![
+        input_response_message("user", "old question"),
+        ResponseItem::Message {
+            id: None,
+            role: "assistant".to_string(),
+            content: vec![ContentItem::OutputText {
+                text: "old answer".to_string(),
+            }],
+            phase: None,
+            internal_chat_message_metadata_passthrough: None,
+        },
+    ]) else {
+        unreachable!("compacted helper always creates a compaction checkpoint");
+    };
+    checkpoint.mcp_resource_origins = Some(McpResourceOriginCheckpoint {
+        origins: vec![McpResourceOrigin {
+            call_id: "widget-call".to_string(),
+            turn_id: Some("keep-before-compaction".to_string()),
+            tool: "_product_search".to_string(),
+            connector_id: "shopping".to_string(),
+            link_id: None,
+            uri: "ui://shopping/widget".to_string(),
+            ambiguous_account: false,
+        }],
+        turns: vec!["keep-before-compaction".to_string()],
+        current_turn_id: Some("keep-before-compaction".to_string()),
+    });
+    let answer_event = serde_json::from_value(serde_json::json!({
+        "type": "verified_answer", "turn_id": "keep-before-compaction", "call_id": "ask-1",
+        "questions": [{"question": "Publish?", "answer": "Only privately."}]
+    }))
+    .expect("verified answer fixture");
+    let wake_answer_event = serde_json::from_value(serde_json::json!({
+        "type": "verified_answer", "turn_id": "empty-answer-turn", "call_id": "ask-2",
+        "questions": [{"question": "Continue?", "answer": "Keep it private."}]
+    }))
+    .expect("empty-turn answer fixture");
+    checkpoint.retained_context = Some(Default::default());
+    let context = checkpoint
+        .retained_context
+        .as_mut()
+        .expect("retained context");
+    context.record(&answer_event);
+    context.record(&wake_answer_event);
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("keep-before-compaction"),
+            user_message("old question"),
+            RolloutItem::RetainedContext(answer_event),
+            completed("keep-before-compaction"),
+            started("empty-answer-turn"),
+            RolloutItem::RetainedContext(wake_answer_event),
+            completed("empty-answer-turn"),
+            RolloutItem::Compacted(checkpoint),
+            started("remove-after-compaction"),
+            user_message("new question"),
+            completed("remove-after-compaction"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 2,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate rollback through compaction");
+
+    let turns = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("read rollback-through-compaction turns");
+    assert_eq!(turns.turns.len(), 1);
+    let migrated = read_rollout(&path);
+    assert!(
+        !migrated
+            .iter()
+            .any(|line| matches!(line.item, RolloutItem::RetainedContext(_)))
+    );
+    let checkpoint = migrated
+        .into_iter()
+        .find_map(|line| match line.item {
+            RolloutItem::Compacted(item) => Some(item),
+            _ => None,
+        })
+        .expect("retained compaction");
+    assert_eq!(checkpoint.replacement_history, Some(Vec::new()));
+    assert_eq!(checkpoint.mcp_resource_origins, None);
+    assert_eq!(
+        checkpoint
+            .retained_context
+            .expect("retained context checkpoint")
+            .verified_answers()
+            .count(),
+        0
+    );
+}
+
+#[tokio::test]
+async fn migration_preserves_answers_before_a_rolled_back_steer() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let mut items = vec![started("shared-turn")];
+    let mut answers = Vec::new();
+    let RolloutItem::Compacted(mut checkpoint) = compacted(vec![
+        input_response_message("user", "before-steer"),
+        input_response_message("user", "after-steer"),
+    ]) else {
+        unreachable!()
+    };
+    checkpoint.retained_context = Some(Default::default());
+    for call_id in ["before-steer", "after-steer"] {
+        items.push(user_message(call_id));
+        let mut call: ResponseItem = serde_json::from_value(json!({
+            "type": "function_call", "call_id": call_id,
+            "name": "request_user_input", "arguments": "{}"
+        }))
+        .expect("request_user_input call");
+        call.set_turn_id_if_missing("shared-turn");
+        items.push(rollout_response_item(call));
+        let answer: codex_rollout::RetainedContextEvent = serde_json::from_value(json!({
+            "type": "verified_answer", "turn_id": "shared-turn", "call_id": call_id,
+            "questions": [{"question": "Publish?", "answer": "Only privately."}]
+        }))
+        .expect("verified answer");
+        checkpoint
+            .retained_context
+            .as_mut()
+            .expect("retained context")
+            .record(&answer);
+        answers.push(answer);
+    }
+    // Delayed delivery must use the original call boundary, not the turn's latest steer.
+    items.extend(answers.iter().cloned().map(RolloutItem::RetainedContext));
+    items.push(completed("shared-turn"));
+    items.push(RolloutItem::Compacted(checkpoint));
+    items.push(RolloutItem::EventMsg(EventMsg::ThreadRolledBack(
+        ThreadRolledBackEvent { num_turns: 1 },
+    )));
+    let path = write_rollout(home.path(), thread_id, SessionSource::Cli, items);
+    let store = indexed_store(home.path()).await;
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate rollback of a steer");
+    let migrated = read_rollout(&path);
+    let events = migrated
+        .iter()
+        .filter_map(|line| match &line.item {
+            RolloutItem::RetainedContext(event) => Some(event.clone()),
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(events, answers[..1]);
+    let checkpoint = migrated
+        .iter()
+        .find_map(|line| match &line.item {
+            RolloutItem::Compacted(checkpoint) => checkpoint.retained_context.as_ref(),
+            _ => None,
+        })
+        .expect("retained checkpoint");
+    assert_eq!(
+        checkpoint
+            .verified_answers()
+            .cloned()
+            .map(
+                |answer| codex_rollout::RetainedContextEvent::VerifiedAnswer {
+                    answer,
+                    acceptance_order: None,
+                }
+            )
+            .collect::<Vec<_>>(),
+        answers[..1]
+    );
+}
+
+#[tokio::test]
+async fn migration_preserves_reverse_replay_anchor_after_pre_compaction_rollback() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            rollout_response_item(input_response_message("user", "remove question")),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            compacted(vec![input_response_message("user", "old question")]),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate pre-compaction rollback");
+
+    let replacement_history = read_rollout(&path)
+        .into_iter()
+        .find_map(|line| match line.item {
+            RolloutItem::Compacted(item) => item.replacement_history,
+            _ => None,
+        })
+        .expect("retained compaction");
+    assert!(replacement_history.is_empty());
+}
+
+#[tokio::test]
+async fn migration_preserves_same_turn_evidence_across_rollback_checkpoints() {
+    assert_migrated_evidence_order(/*steer_order*/ None).await;
+}
+
+#[tokio::test]
+async fn migration_removes_answers_accepted_after_a_queued_steer() {
+    assert_migrated_evidence_order(Some(1)).await;
+}
+
+async fn assert_migrated_evidence_order(steer_order: Option<u64>) {
+    const INITIAL: &str = "Never publish publicly.";
+    const STEER: &str = "Also inspect the README.";
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let [initial, steer] =
+        [("initial", INITIAL), ("steer", STEER)].map(|(id, text)| ResponseItem::Message {
+            id: Some(ResponseItemId::with_suffix("msg", id)),
+            role: "user".to_owned(),
+            content: vec![ContentItem::InputText {
+                text: text.to_owned(),
+            }],
+            phase: None,
+            internal_chat_message_metadata_passthrough: Some(
+                InternalChatMessageMetadataPassthrough {
+                    turn_id: Some("shared-turn".to_owned()),
+                    content_item_kinds: Some(vec![ContentItemKind("user.text".to_owned())]),
+                    ..Default::default()
+                },
+            ),
+        });
+    let RolloutItem::Compacted(mut checkpoint) = compacted(vec![initial.clone(), steer.clone()])
+    else {
+        unreachable!("compacted helper creates a checkpoint");
+    };
+    let retained = json!({
+        "user_messages": [
+            {"order": 0, "turn_id": "shared-turn", "message_id": "msg_initial", "text": INITIAL, "complete": true},
+            {"order": steer_order.unwrap_or(2), "turn_id": "shared-turn", "message_id": "msg_steer", "text": STEER, "complete": true}
+        ],
+        "verified_answers": [
+            {"order": if steer_order.is_some() { 2 } else { 1 }, "turn_id": "shared-turn", "call_id": "before", "questions": [{"question": "Publish?", "answer": "Only privately."}]},
+            {"order": 3, "turn_id": "shared-turn", "call_id": "after", "questions": [{"question": "Publish the README?", "answer": "Do not publish it."}]}
+        ],
+        "incomplete": false, "user_messages_incomplete": false, "next_order": 4
+    });
+    checkpoint.retained_context =
+        Some(serde_json::from_value(retained.clone()).expect("retained fixture"));
+    let answers = checkpoint
+        .retained_context
+        .as_ref()
+        .expect("retained checkpoint")
+        .verified_answers()
+        .cloned()
+        .map(|answer| {
+            let acceptance_order =
+                steer_order.map(|_| if answer.call_id == "before" { 2 } else { 3 });
+            codex_rollout::RetainedContextEvent::VerifiedAnswer {
+                answer,
+                acceptance_order,
+            }
+        })
+        .collect::<Vec<_>>();
+    let mut before_retained = retained.clone();
+    before_retained["user_messages"]
+        .as_array_mut()
+        .expect("user messages")
+        .truncate(/*len*/ 1);
+    before_retained["verified_answers"]
+        .as_array_mut()
+        .expect("verified answers")
+        .truncate(/*len*/ 1);
+    before_retained["next_order"] = json!(if steer_order.is_some() { 3 } else { 2 });
+    let remaining_answers = usize::from(steer_order.is_none());
+    let mut expected = retained;
+    expected["user_messages"]
+        .as_array_mut()
+        .expect("user messages")
+        .truncate(/*len*/ 1);
+    expected["verified_answers"]
+        .as_array_mut()
+        .expect("verified answers")
+        .truncate(remaining_answers);
+    let mut before_expected = expected.clone();
+    before_expected["next_order"] = before_retained["next_order"].clone();
+    let mut before_steer = checkpoint.clone();
+    before_steer.replacement_history = Some(vec![initial.clone().into()]);
+    before_steer.retained_context =
+        Some(serde_json::from_value(before_retained).expect("pre-steer checkpoint"));
+    let mut after_rollback = before_steer.clone();
+    after_rollback.retained_context =
+        Some(serde_json::from_value(expected.clone()).expect("post-rollback checkpoint"));
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("shared-turn"),
+            rollout_response_item(initial.clone()),
+            user_message(INITIAL),
+            RolloutItem::RetainedContext(answers[0].clone()),
+            RolloutItem::Compacted(before_steer),
+            RolloutItem::ResponseItem(codex_rollout::ResponseItemEnvelope {
+                item: steer,
+                metadata: steer_order.map(|order| {
+                    serde_json::from_value(json!({
+                        "user_input_order": order
+                    }))
+                    .expect("acceptance metadata")
+                }),
+            }),
+            user_message(STEER),
+            RolloutItem::RetainedContext(answers[1].clone()),
+            completed("shared-turn"),
+            started("compaction-turn"),
+            RolloutItem::Compacted(checkpoint),
+            completed("compaction-turn"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            // This checkpoint already contains the correct live rollback result.
+            started("post-rollback-compaction"),
+            RolloutItem::Compacted(after_rollback),
+            completed("post-rollback-compaction"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate same-turn rollback");
+    let migrated = read_rollout(&path);
+    let checkpoints = migrated
+        .iter()
+        .filter_map(|line| match &line.item {
+            RolloutItem::Compacted(item) => Some(item),
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(
+        checkpoints
+            .iter()
+            .map(
+                |checkpoint| serde_json::to_value(&checkpoint.retained_context)
+                    .expect("retained context")
+            )
+            .collect::<Vec<_>>(),
+        vec![before_expected, expected.clone(), expected]
+    );
+    assert_eq!(
+        checkpoints
+            .last()
+            .expect("latest checkpoint")
+            .replacement_history,
+        Some(vec![initial.into()])
+    );
+    assert_eq!(
+        migrated
+            .into_iter()
+            .filter_map(|line| match line.item {
+                RolloutItem::RetainedContext(event) => Some(event),
+                _ => None,
+            })
+            .collect::<Vec<_>>(),
+        answers[..remaining_answers]
+    );
+}
+
+#[tokio::test]
+async fn migration_keeps_empty_replay_anchor_from_rolled_back_turn() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("keep"),
+            user_message("keep question"),
+            completed("keep"),
+            started("remove"),
+            user_message("remove question"),
+            compacted(vec![input_response_message("user", "old question")]),
+            completed("remove"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            started("replacement"),
+            user_message("replacement question"),
+            completed("replacement"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate rolled-back replay anchor");
+
+    let replacement_history = read_rollout(&path)
+        .into_iter()
+        .find_map(|line| match line.item {
+            RolloutItem::Compacted(item) => item.replacement_history,
+            _ => None,
+        })
+        .expect("retained compaction");
+    assert!(replacement_history.is_empty());
+}
+
+#[tokio::test]
+async fn migration_uses_turn_context_to_select_reverse_replay_anchor() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("keep"),
+            user_message("keep question"),
+            compacted(vec![input_response_message("user", "keep question")]),
+            completed("keep"),
+            started("remove"),
+            user_message("remove question"),
+            serde_json::from_value(json!({
+                "type": "event_msg",
+                "payload": {
+                    "type": "turn_aborted",
+                    "turn_id": "other",
+                    "reason": "interrupted"
+                }
+            }))
+            .expect("build mismatched turn abort"),
+            serde_json::from_value(json!({
+                "type": "turn_context",
+                "payload": {
+                    "turn_id": "remove",
+                    "cwd": home.path(),
+                    "approval_policy": "never",
+                    "sandbox_policy": {"type": "read-only"},
+                    "model": "test-model",
+                    "summary": "auto"
+                }
+            }))
+            .expect("build turn context"),
+            compacted(vec![input_response_message("user", "remove question")]),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            started("replacement"),
+            user_message("replacement question"),
+            completed("replacement"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate turn-context replay anchor");
+
+    let replacement_histories = read_rollout(&path)
+        .into_iter()
+        .filter_map(|line| match line.item {
+            RolloutItem::Compacted(item) => item.replacement_history.map(|items| {
+                items
+                    .into_iter()
+                    .map(codex_rollout::ResponseItemEnvelope::into_item)
+                    .collect::<Vec<_>>()
+            }),
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(
+        replacement_histories,
+        vec![vec![input_response_message("user", "keep question")]]
+    );
+}
+
+#[tokio::test]
+async fn migration_applies_cumulative_and_overflowing_rollbacks() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            started("first"),
+            user_message("first question"),
+            completed("first"),
+            started("second"),
+            user_message("second question"),
+            completed("second"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 1,
+            })),
+            started("third"),
+            user_message("third question"),
+            completed("third"),
+            RolloutItem::EventMsg(EventMsg::ThreadRolledBack(ThreadRolledBackEvent {
+                num_turns: 99,
+            })),
+            user_message("replacement question"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate cumulative rollbacks");
+
+    let turns = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("read cumulative rollback turns");
+    assert_eq!(turns.turns.len(), 1);
+    assert!(!read_rollout(&path).iter().any(|line| matches!(
+        line.item,
+        RolloutItem::EventMsg(EventMsg::ThreadRolledBack(_))
+    )));
+}
+
+#[tokio::test]
+async fn migration_drops_copied_user_fork_metadata_without_creating_a_history_base() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let parent_id = ThreadId::new();
+    let copied_metadata = SessionMeta {
+        session_id: parent_id.into(),
+        id: parent_id,
+        timestamp: TIMESTAMP.to_string(),
+        cwd: home.path().to_path_buf(),
+        source: SessionSource::Cli,
+        ..SessionMeta::default()
+    };
+    let copied_response =
+        rollout_response_item(input_response_message("user", "copied parent history"));
+    let path = write_rollout_with_fork(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        Some(parent_id),
+        vec![
+            RolloutItem::SessionMeta(SessionMetaLine {
+                meta: copied_metadata,
+                git: None,
+            }),
+            copied_response,
+            user_message("child question"),
+            agent_message("child answer"),
+        ],
+    );
+    let expected_responses = read_rollout(&path)
+        .into_iter()
+        .filter_map(|line| match line.item {
+            RolloutItem::ResponseItem(item) => {
+                Some(serde_json::to_value(item.item).expect("serialize copied response"))
+            }
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate copied user fork");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    let lines = read_rollout(&path);
+    assert!(matches!(
+        &lines[0].item,
+        RolloutItem::SessionMeta(metadata)
+            if metadata.meta.id == thread_id
+                && metadata.meta.forked_from_id == Some(parent_id)
+                && metadata.meta.history_mode == ThreadHistoryMode::Paginated
+                && metadata.meta.history_base.is_none()
+    ));
+    assert_eq!(
+        lines
+            .iter()
+            .filter(|line| matches!(line.item, RolloutItem::SessionMeta(_)))
+            .count(),
+        1
+    );
+    assert_eq!(
+        lines
+            .into_iter()
+            .filter_map(|line| match line.item {
+                RolloutItem::ResponseItem(item) => {
+                    Some(serde_json::to_value(item.item).expect("serialize migrated response"))
+                }
+                _ => None,
+            })
+            .collect::<Vec<_>>(),
+        expected_responses
+    );
+}
+
+#[tokio::test]
+async fn migration_compacts_subagent_prefix_and_does_not_project_it() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::SubAgent(SubAgentSource::Other("test".to_string())),
+        vec![
+            RolloutItem::Compacted(CompactedItem {
+                message: "superseded checkpoint".repeat(1024),
+                replacement_history: Some(Vec::new()),
+                retained_context: None,
+                guardian_history: None,
+                mcp_resource_origins: None,
+                window_number: Some(1),
+                first_window_id: None,
+                previous_window_id: None,
+                window_id: None,
+                compaction_response_id: None,
+                latest_token_usage_record: None,
+            }),
+            RolloutItem::Compacted(CompactedItem {
+                message: "latest checkpoint".to_string(),
+                replacement_history: Some(vec![
+                    ResponseItem::Message {
+                        id: None,
+                        role: "user".to_string(),
+                        content: vec![ContentItem::InputText {
+                            text: "latest compacted context".to_string(),
+                        }],
+                        phase: None,
+                        internal_chat_message_metadata_passthrough: None,
+                    }
+                    .into(),
+                ]),
+                retained_context: None,
+                guardian_history: None,
+                mcp_resource_origins: None,
+                window_number: Some(2),
+                first_window_id: None,
+                previous_window_id: None,
+                window_id: None,
+                compaction_response_id: None,
+                latest_token_usage_record: None,
+            }),
+            started("child-turn"),
+            RolloutItem::TurnContext(TurnContextItem {
+                turn_id: Some("child-turn".to_string()),
+                root_turn_id: None,
+                disabled_plugin_ids: None,
+                cwd: serde_json::from_value(json!(home.path())).expect("absolute cwd"),
+                workspace_roots: None,
+                current_date: None,
+                timezone: None,
+                approval_policy: AskForApproval::Never,
+                approvals_reviewer: None,
+                sandbox_policy: SandboxPolicy::new_read_only_policy(),
+                permission_profile: None,
+                active_permission_profile: None,
+                network: None,
+                file_system_sandbox_policy: None,
+                model: "test-model".to_string(),
+                comp_hash: None,
+                personality: None,
+                collaboration_mode: None,
+                multi_agent_version: None,
+                multi_agent_mode: None,
+                realtime_active: None,
+                cyber_access_program: None,
+                effort: None,
+                summary: ReasoningSummary::Auto,
+            }),
+            user_message("child question"),
+            agent_message("child answer"),
+            completed("child-turn"),
+        ],
+    );
+    writeln!(
+        fs::OpenOptions::new()
+            .append(true)
+            .open(&path)
+            .expect("open legacy subagent rollout"),
+        "{{not valid rollout json"
+    )
+    .expect("append malformed record");
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate legacy subagent");
+
+    let lines = read_rollout(&path);
+    let RolloutItem::SessionMeta(metadata) = &lines[0].item else {
+        panic!("migrated rollout should start with session metadata");
+    };
+    assert_eq!(
+        metadata.meta.subagent_history_start_ordinal,
+        Some(lines.len() as u64)
+    );
+    assert!(
+        !fs::read_to_string(&path)
+            .expect("read migrated rollout")
+            .contains("superseded checkpoint")
+    );
+    let context = store
+        .load_latest_model_context(LoadThreadHistoryParams {
+            thread_id,
+            include_archived: false,
+        })
+        .await
+        .expect("load migrated model context");
+    assert!(context.items.iter().any(|item| {
+        matches!(item, RolloutItem::Compacted(compacted) if compacted.message == "latest checkpoint")
+    }));
+    assert!(
+        list_active_summary_turns(&store, thread_id)
+            .await
+            .turns
+            .is_empty()
+    );
+}
+
+#[tokio::test]
+async fn migration_keeps_small_uncompacted_subagent_replay_as_prefix() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::SubAgent(SubAgentSource::Other("test".to_string())),
+        vec![
+            user_message("child question"),
+            agent_message("child answer"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate uncompacted legacy subagent");
+
+    let lines = read_rollout(&path);
+    let RolloutItem::SessionMeta(metadata) = &lines[0].item else {
+        panic!("migrated rollout should start with session metadata");
+    };
+    assert_eq!(
+        metadata.meta.subagent_history_start_ordinal,
+        Some(lines.len() as u64)
+    );
+    assert_eq!(
+        lines
+            .iter()
+            .filter(|line| matches!(line.item, RolloutItem::EventMsg(EventMsg::ItemCompleted(_))))
+            .count(),
+        2
+    );
+}
+
+#[tokio::test]
+async fn migration_projects_memory_consolidation_as_ordinary_history() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::SubAgent(SubAgentSource::MemoryConsolidation),
+        vec![
+            user_message("memory question"),
+            agent_message("memory answer"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate memory consolidation rollout");
+
+    let lines = read_rollout(&path);
+    assert!(matches!(
+        &lines[0].item,
+        RolloutItem::SessionMeta(metadata)
+            if metadata.meta.history_mode == ThreadHistoryMode::Paginated
+                && metadata.meta.subagent_history_start_ordinal.is_none()
+    ));
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(turns.turns.len(), 1);
+    assert_eq!(turns.turns[0].items.len(), 2);
+}
+
+#[tokio::test]
+async fn dry_run_reports_migration_order() {
+    let home = TempDir::new().expect("create Codex home");
+    let root_id = ThreadId::new();
+    let root = write_rollout(
+        home.path(),
+        root_id,
+        SessionSource::Cli,
+        vec![user_message("root question")],
+    );
+    let newest_directory = home.path().join("sessions/2025/01/04");
+    fs::create_dir_all(&newest_directory).expect("create newest rollout directory");
+    let newest_root = newest_directory.join(format!("rollout-2025-01-04T12-00-00-{root_id}.jsonl"));
+    fs::rename(&root, &newest_root).expect("move root rollout to newest date");
+    let root = newest_root;
+    let subagent_id = ThreadId::new();
+    let subagent = write_rollout(
+        home.path(),
+        subagent_id,
+        SessionSource::SubAgent(SubAgentSource::Other("test".to_string())),
+        vec![user_message("subagent question")],
+    );
+    let memory_id = ThreadId::new();
+    let memory = write_rollout(
+        home.path(),
+        memory_id,
+        SessionSource::SubAgent(SubAgentSource::MemoryConsolidation),
+        vec![user_message("memory question")],
+    );
+    let memory_directory = home.path().join("sessions/2025/01/01");
+    fs::create_dir_all(&memory_directory).expect("create memory rollout directory");
+    let moved_memory = memory_directory.join(memory.file_name().expect("memory filename"));
+    fs::rename(memory, &moved_memory).expect("move memory rollout");
+    let compressed_id = ThreadId::new();
+    let oldest_directory = home.path().join("sessions/2025/01/02");
+    fs::create_dir_all(&oldest_directory).expect("create oldest rollout directory");
+    let source_compressed_plain = write_rollout(
+        home.path(),
+        compressed_id,
+        SessionSource::Cli,
+        vec![user_message("compressed question")],
+    );
+    let compressed_plain =
+        oldest_directory.join(format!("rollout-2025-01-02T12-00-00-{compressed_id}.jsonl"));
+    fs::rename(source_compressed_plain, &compressed_plain).expect("move compressed rollout");
+    let compressed = compress_rollout(&compressed_plain);
+    let archived_id = ThreadId::new();
+    let archived = move_to_archived(
+        home.path(),
+        write_rollout(
+            home.path(),
+            archived_id,
+            SessionSource::Cli,
+            vec![user_message("archived question")],
+        ),
+    );
+    let original = fs::read(&root).expect("read original root rollout");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let mut progress = Vec::new();
+    let report = store
+        .migrate_rollouts_with_progress(RolloutMigrationOptions::default(), |update| {
+            progress.push(update);
+        })
+        .await
+        .expect("inspect legacy rollouts");
+
+    let expected = vec![
+        (root.clone(), root_id, RolloutMigrationStatus::Eligible),
+        (subagent, subagent_id, RolloutMigrationStatus::Eligible),
+        (compressed, compressed_id, RolloutMigrationStatus::Eligible),
+        (moved_memory, memory_id, RolloutMigrationStatus::Eligible),
+        (archived, archived_id, RolloutMigrationStatus::Eligible),
+    ];
+    assert_eq!(
+        report
+            .outcomes
+            .iter()
+            .map(|outcome| (
+                outcome.rollout_path.clone(),
+                outcome.thread_id.expect("rollout thread ID"),
+                outcome.status,
+            ))
+            .collect::<Vec<_>>(),
+        expected,
+    );
+    assert_eq!(
+        progress.last(),
+        Some(&RolloutMigrationProgress {
+            processed_paths: 5,
+            total_paths: 5,
+            outcome_status: Some(RolloutMigrationStatus::Eligible),
+        })
+    );
+    assert_eq!(fs::read(&root).expect("read inspected rollout"), original);
+
+    let selected = store
+        .migrate_rollouts(RolloutMigrationOptions {
+            thread_ids: vec![root_id],
+            ..RolloutMigrationOptions::default()
+        })
+        .await
+        .expect("inspect selected rollout");
+    assert_eq!(selected.outcomes.len(), 1);
+    assert_eq!(selected.outcomes[0].thread_id, Some(root_id));
+    assert_eq!(
+        selected.outcomes[0].status,
+        RolloutMigrationStatus::Eligible
+    );
+}
+
+#[tokio::test]
+async fn migration_preserves_compressed_rollouts_during_publish_and_recovery() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            user_message("compressed question"),
+            agent_message("compressed answer"),
+        ],
+    );
+    let compressed_path = compress_rollout(&path);
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate compressed rollout");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(!path.exists());
+    assert!(compressed_path.exists());
+    assert_eq!(
+        codex_rollout::read_session_meta_line(&compressed_path)
+            .await
+            .expect("read compressed metadata")
+            .meta
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(turns.turns.len(), 1);
+    assert_eq!(turns.turns[0].items.len(), 2);
+
+    thread_history::delete_thread(&store, thread_id)
+        .await
+        .expect("simulate missing projection");
+    let journal_path = migration_journal_path(home.path(), thread_id);
+    write_migration_journal(&journal_path)
+        .await
+        .expect("simulate pending migration journal");
+    let recovered = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("recover compressed rollout");
+
+    assert_eq!(
+        recovered.outcomes[0].status,
+        RolloutMigrationStatus::Migrated
+    );
+    assert!(recovered.outcomes[0].bytes_processed > 0);
+    assert!(compressed_path.exists());
+    assert!(!path.exists());
+    assert!(!journal_path.exists());
+}
+
+#[tokio::test]
+async fn migration_migrates_archived_rollouts_without_unarchiving_them() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let active_path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            user_message("archived question"),
+            agent_message("archived answer"),
+        ],
+    );
+    let archived_path = move_to_archived(home.path(), active_path.clone());
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate archived rollout");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(!active_path.exists());
+    assert!(archived_path.exists());
+    assert!(matches!(
+        &read_rollout(&archived_path)[0].item,
+        RolloutItem::SessionMeta(metadata)
+            if metadata.meta.history_mode == ThreadHistoryMode::Paginated
+    ));
+    let turns = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: true,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("read archived projected turns");
+    assert_eq!(turns.turns.len(), 1);
+    assert_eq!(turns.turns[0].items.len(), 2);
+}
+
+#[tokio::test]
+async fn migration_retries_a_rollout_moved_after_path_discovery() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let active_path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("question"), agent_message("answer")],
+    );
+    let store = indexed_store(home.path()).await;
+    let archived_path = move_to_archived(home.path(), active_path.clone());
+
+    let report = store
+        .migrate_rollouts_with_progress_for_trigger(
+            apply_options(),
+            |_| {},
+            RolloutMigrationTrigger::Startup,
+            RolloutMigrationPaths::Known(vec![active_path]),
+        )
+        .await
+        .expect("migrate moved rollout");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(matches!(
+        &read_rollout(&archived_path)[0].item,
+        RolloutItem::SessionMeta(metadata)
+            if metadata.meta.history_mode == ThreadHistoryMode::Paginated
+    ));
+}
+
+#[tokio::test]
+async fn migration_preserves_legacy_displayed_thread_names() {
+    let home = TempDir::new().expect("create Codex home");
+    let title_thread_id = ThreadId::new();
+    write_rollout(
+        home.path(),
+        title_thread_id,
+        SessionSource::Cli,
+        vec![user_message("title question")],
+    );
+    let index_thread_id = ThreadId::new();
+    write_rollout(
+        home.path(),
+        index_thread_id,
+        SessionSource::Cli,
+        vec![user_message("index question")],
+    );
+    let store = indexed_store(home.path()).await;
+    store
+        .update_thread_metadata(UpdateThreadMetadataParams {
+            thread_id: title_thread_id,
+            patch: ThreadMetadataPatch {
+                name: Some(Some("renamed title".to_string())),
+                ..Default::default()
+            },
+            include_archived: false,
+        })
+        .await
+        .expect("rename legacy thread");
+    codex_rollout::append_thread_name(home.path(), title_thread_id, "stale index title")
+        .await
+        .expect("write stale legacy index name");
+    codex_rollout::append_thread_name(home.path(), index_thread_id, "indexed title")
+        .await
+        .expect("write legacy index name");
+
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate named rollouts");
+
+    let page = store
+        .list_threads(ListThreadsParams {
+            page_size: 10,
+            cursor: None,
+            sort_key: ThreadSortKey::CreatedAt,
+            sort_direction: SortDirection::Desc,
+            allowed_sources: Vec::new(),
+            model_providers: None,
+            cwd_filters: None,
+            section: None,
+            project_id: None,
+            archived: false,
+            search_term: None,
+            relation_filter: None,
+            use_state_db_only: true,
+        })
+        .await
+        .expect("list migrated threads");
+    let title_thread = page
+        .items
+        .iter()
+        .find(|thread| thread.thread_id == title_thread_id)
+        .expect("renamed title thread");
+    let index_thread = page
+        .items
+        .iter()
+        .find(|thread| thread.thread_id == index_thread_id)
+        .expect("indexed title thread");
+
+    assert_eq!(title_thread.name.as_deref(), Some("renamed title"));
+    assert_eq!(index_thread.name.as_deref(), Some("indexed title"));
+}
+
+#[tokio::test]
+async fn migration_repairs_a_missing_paginated_name_when_rerun() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("question")],
+    );
+    let store = indexed_store(home.path()).await;
+    store
+        .update_thread_metadata(UpdateThreadMetadataParams {
+            thread_id,
+            patch: ThreadMetadataPatch {
+                name: Some(Some("renamed title".to_string())),
+                ..Default::default()
+            },
+            include_archived: false,
+        })
+        .await
+        .expect("rename legacy thread");
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate named rollout");
+    let state_db = store.state_db().await.expect("state runtime");
+    state_db
+        .update_thread_title(thread_id, "question")
+        .await
+        .expect("restore derived title");
+    state_db
+        .update_thread_name(thread_id, /*name*/ None)
+        .await
+        .expect("clear migrated name");
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("repair migrated name");
+
+    assert_eq!(
+        report.outcomes[0].status,
+        RolloutMigrationStatus::AlreadyPaginated
+    );
+    assert_eq!(
+        state_db
+            .get_thread(thread_id)
+            .await
+            .expect("read repaired metadata")
+            .expect("repaired thread")
+            .name
+            .as_deref(),
+        Some("renamed title")
+    );
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn decompression_temporaries_are_owner_only() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let compressed_path = compress_rollout(&write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("compressed question")],
+    ));
+    let plain_path = home.path().join("decompressed.tmp");
+
+    decompress_rollout_to_path(&compressed_path, &plain_path)
+        .await
+        .expect("decompress rollout");
+
+    assert_eq!(
+        fs::metadata(&plain_path)
+            .expect("read temporary metadata")
+            .permissions()
+            .mode()
+            & 0o777,
+        0o600
+    );
+}
+
+#[tokio::test]
+async fn migration_skips_threads_with_an_active_writer() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("active question")],
+    );
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let _writer = store
+        .acquire_writer_lock(thread_id)
+        .expect("acquire live writer lock");
+    let original = fs::read(&path).expect("read active rollout");
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("inspect active writer");
+
+    assert_eq!(
+        report.outcomes[0].status,
+        RolloutMigrationStatus::SkippedBusy
+    );
+    assert_eq!(fs::read(&path).expect("read unmodified rollout"), original);
+}
+
+#[tokio::test]
+async fn migration_apply_conflicts_with_rollout_maintenance() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("maintenance question")],
+    );
+    let original = fs::read(&path).expect("read legacy rollout");
+    let _maintenance_guard = codex_rollout::try_acquire_rollout_maintenance_lock(home.path())
+        .expect("acquire rollout maintenance lock")
+        .expect("claim rollout maintenance lock");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+
+    let error = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect_err("reject concurrent rollout maintenance");
+
+    assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+    assert_eq!(fs::read(&path).expect("read untouched rollout"), original);
+}
+
+#[tokio::test]
+async fn migration_recovers_a_published_rollout_with_missing_projection() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            user_message("recover question"),
+            agent_message("recover answer"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("publish canonical rollout");
+    thread_history::delete_thread(&store, thread_id)
+        .await
+        .expect("simulate interrupted projection");
+    let journal_path = migration_journal_path(home.path(), thread_id);
+    write_migration_journal(&journal_path)
+        .await
+        .expect("simulate pending migration journal");
+
+    let writer = store
+        .acquire_writer_lock(thread_id)
+        .expect("acquire live writer lock");
+    let busy = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("inspect busy published recovery");
+    assert_eq!(busy.outcomes[0].status, RolloutMigrationStatus::SkippedBusy);
+    assert!(journal_path.exists());
+    drop(writer);
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("recover published rollout");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(!journal_path.exists());
+    let projection = thread_history::projection_state(&store, thread_id)
+        .await
+        .expect("read repaired projection")
+        .expect("projection was rebuilt");
+    assert_eq!(
+        projection.next_byte_offset,
+        fs::metadata(&path).expect("read rollout metadata").len()
+    );
+}
+
+#[tokio::test]
+async fn migration_recovers_pending_rollouts_before_new_work() {
+    let home = TempDir::new().expect("create Codex home");
+    let pending_thread_id = ThreadId::new();
+    write_rollout(
+        home.path(),
+        pending_thread_id,
+        SessionSource::Cli,
+        vec![user_message("pending question")],
+    );
+    let new_thread_id = ThreadId::new();
+    let new_path = write_rollout(
+        home.path(),
+        new_thread_id,
+        SessionSource::Cli,
+        vec![user_message("new question")],
+    );
+    let newer_directory = home.path().join("sessions/2025/01/04");
+    fs::create_dir_all(&newer_directory).expect("create newer rollout directory");
+    fs::rename(
+        &new_path,
+        newer_directory.join(new_path.file_name().expect("rollout filename")),
+    )
+    .expect("move newer rollout");
+    let store = indexed_store(home.path()).await;
+
+    store
+        .migrate_rollouts(RolloutMigrationOptions {
+            thread_ids: vec![pending_thread_id],
+            ..apply_options()
+        })
+        .await
+        .expect("publish pending rollout");
+    thread_history::delete_thread(&store, pending_thread_id)
+        .await
+        .expect("simulate missing projection");
+    write_migration_journal(&migration_journal_path(home.path(), pending_thread_id))
+        .await
+        .expect("simulate pending migration journal");
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("recover pending rollout before new work");
+
+    assert_eq!(
+        report
+            .outcomes
+            .iter()
+            .map(|outcome| (
+                outcome.thread_id.expect("rollout thread ID"),
+                outcome.status
+            ))
+            .collect::<Vec<_>>(),
+        vec![
+            (pending_thread_id, RolloutMigrationStatus::Migrated),
+            (new_thread_id, RolloutMigrationStatus::Migrated),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn migration_recovers_a_compressed_published_rollout() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![
+            user_message("recover compressed question"),
+            agent_message("recover compressed answer"),
+        ],
+    );
+    let store = indexed_store(home.path()).await;
+    store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("publish canonical rollout");
+    thread_history::delete_thread(&store, thread_id)
+        .await
+        .expect("simulate interrupted projection");
+    let state_db = store.state_db.as_ref().expect("state db");
+    let mut legacy_metadata = state_db
+        .get_thread(thread_id)
+        .await
+        .expect("read thread metadata")
+        .expect("thread metadata");
+    legacy_metadata.history_mode = ThreadHistoryMode::Legacy;
+    state_db
+        .delete_thread(thread_id)
+        .await
+        .expect("remove paginated thread metadata");
+    assert!(
+        state_db
+            .insert_thread_if_absent(&legacy_metadata)
+            .await
+            .expect("restore legacy thread metadata")
+    );
+    let journal_path = migration_journal_path(home.path(), thread_id);
+    write_migration_journal(&journal_path)
+        .await
+        .expect("simulate pending migration journal");
+    let compressed_path = compress_rollout(&path);
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("recover compressed published rollout");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(!path.exists());
+    assert!(compressed_path.exists());
+    assert!(!journal_path.exists());
+    assert_eq!(
+        store
+            .state_db
+            .as_ref()
+            .expect("state db")
+            .get_thread(thread_id)
+            .await
+            .expect("read repaired thread metadata")
+            .expect("thread metadata")
+            .history_mode,
+        ThreadHistoryMode::Paginated
+    );
+    let projection = thread_history::projection_state(&store, thread_id)
+        .await
+        .expect("read repaired projection")
+        .expect("projection was rebuilt");
+    assert_eq!(
+        projection.next_byte_offset,
+        zstd::stream::decode_all(fs::File::open(&compressed_path).expect("open rollout"))
+            .expect("decompress rollout")
+            .len() as u64
+    );
+}
+
+#[tokio::test]
+async fn migration_skips_oversized_jsonl_records() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("kept question")],
+    );
+    let oversized_output = "x".repeat(super::MAX_ROLLOUT_LINE_BYTES);
+    let mut file = fs::OpenOptions::new()
+        .append(true)
+        .open(&path)
+        .expect("open legacy rollout");
+    writeln!(
+        file,
+        "{{\"timestamp\":\"{TIMESTAMP}\",\"type\":\"response_item\",\"payload\":{{\"type\":\"function_call_output\",\"call_id\":\"call-1\",\"output\":\"{oversized_output}\"}}}}"
+    )
+    .expect("write oversized rollout record");
+    drop(file);
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate oversized rollout record");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(
+        fs::metadata(&path)
+            .expect("read migrated rollout metadata")
+            .len()
+            < super::MAX_ROLLOUT_LINE_BYTES as u64
+    );
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(turns.turns.len(), 1);
+    assert_eq!(turns.turns[0].items.len(), 1);
+}
+
+#[tokio::test]
+async fn migration_skips_empty_rollout_files() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let directory = home.path().join("sessions/2025/01/03");
+    fs::create_dir_all(&directory).expect("create rollout directory");
+    let path = directory.join(format!("rollout-2025-01-03T12-00-00-{thread_id}.jsonl"));
+    fs::File::create(&path).expect("create empty rollout");
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("inspect empty rollout");
+
+    assert_eq!(
+        report.outcomes[0].status,
+        RolloutMigrationStatus::SkippedEmpty
+    );
+    assert_eq!(fs::metadata(&path).expect("read empty rollout").len(), 0);
+    assert!(
+        store
+            .state_db
+            .as_ref()
+            .expect("state db")
+            .get_thread(thread_id)
+            .await
+            .expect("read thread metadata")
+            .is_none()
+    );
+}
+
+#[tokio::test]
+async fn migration_reports_missing_sqlite_metadata() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("question")],
+    );
+    let store = indexed_store(home.path()).await;
+    store
+        .state_db
+        .as_ref()
+        .expect("state db")
+        .delete_thread(thread_id)
+        .await
+        .expect("remove thread metadata");
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("inspect rollout with missing metadata");
+
+    assert_failed_with_reason(
+        &report.outcomes[0],
+        RolloutMigrationFailureReason::MissingSqliteMetadata,
+    );
+}
+
+#[tokio::test]
+async fn migration_reports_invalid_session_metadata() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let directory = home.path().join("sessions/2025/01/03");
+    fs::create_dir_all(&directory).expect("create rollout directory");
+    let path = directory.join(format!("rollout-2025-01-03T12-00-00-{thread_id}.jsonl"));
+    fs::write(path, "not a rollout record\n").expect("write malformed rollout");
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("inspect rollout with invalid metadata");
+
+    assert_failed_with_reason(
+        &report.outcomes[0],
+        RolloutMigrationFailureReason::InvalidSessionMetadata,
+    );
+}
+
+#[tokio::test]
+async fn migration_skips_malformed_lines_and_trailing_partial_tail() {
+    let home = TempDir::new().expect("create Codex home");
+    let thread_id = ThreadId::new();
+    let path = write_rollout(
+        home.path(),
+        thread_id,
+        SessionSource::Cli,
+        vec![user_message("kept question")],
+    );
+    let mut file = fs::OpenOptions::new()
+        .append(true)
+        .open(&path)
+        .expect("open legacy rollout");
+    writeln!(file, "{{not valid rollout json").expect("append malformed record");
+    let later_valid_line = RolloutLine {
+        timestamp: TIMESTAMP.to_string(),
+        ordinal: None,
+        item: agent_message("kept answer"),
+    };
+    writeln!(
+        file,
+        "{}",
+        serde_json::to_string(&later_valid_line).expect("serialize later valid record")
+    )
+    .expect("append later valid record");
+    file.write_all(br#"{"timestamp":"unterminated""#)
+        .expect("append partial tail");
+    drop(file);
+    let store = indexed_store(home.path()).await;
+
+    let report = store
+        .migrate_rollouts(apply_options())
+        .await
+        .expect("migrate malformed legacy rollout");
+
+    assert_eq!(report.outcomes[0].status, RolloutMigrationStatus::Migrated);
+    assert!(!migration_journal_path(home.path(), thread_id).exists());
+    let turns = list_active_summary_turns(&store, thread_id).await;
+    assert_eq!(turns.turns.len(), 1);
+    assert_eq!(turns.turns[0].items.len(), 2);
+}
diff --git a/codex-rs/thread-store/src/local/search_threads.rs b/codex-rs/thread-store/src/local/search_threads.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7e8401aa036e168c595a4e1aee2018ffcd37a9d1
--- /dev/null
+++ b/codex-rs/thread-store/src/local/search_threads.rs
@@ -0,0 +1,257 @@
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_install_context::InstallContext;
+use codex_rollout::RolloutConfig;
+use codex_rollout::first_rollout_content_match_snippet;
+use codex_rollout::parse_cursor;
+use codex_rollout::search_rollout_matches;
+use codex_utils_absolute_path::normalize_windows_device_path;
+
+use super::LocalThreadStore;
+use super::helpers::resolve_thread_names;
+use super::helpers::resolve_thread_section_metadata;
+use super::helpers::set_thread_name;
+use super::helpers::stored_thread_from_rollout_item;
+use super::list_threads::list_rollout_threads;
+use crate::ListThreadsParams;
+use crate::SearchThreadsParams;
+use crate::SortDirection;
+use crate::StoredThreadSearchResult;
+use crate::ThreadSearchPage;
+use crate::ThreadSortKey;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+#[cfg(test)]
+#[path = "search_threads_tests.rs"]
+mod tests;
+
+struct ThreadSearchItem {
+    item: codex_rollout::ThreadItem,
+    snippet: String,
+}
+
+pub(super) async fn search_threads(
+    store: &LocalThreadStore,
+    params: SearchThreadsParams,
+) -> ThreadStoreResult<ThreadSearchPage> {
+    let search_term = params.search_term.as_str();
+    if search_term.is_empty() {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "thread/search requires search_term".to_string(),
+        });
+    }
+    let cursor = params
+        .cursor
+        .as_deref()
+        .map(|cursor| {
+            parse_cursor(cursor).ok_or_else(|| ThreadStoreError::InvalidRequest {
+                message: format!("invalid cursor: {cursor}"),
+            })
+        })
+        .transpose()?;
+    let sort_key = match params.sort_key {
+        ThreadSortKey::CreatedAt => codex_rollout::ThreadSortKey::CreatedAt,
+        ThreadSortKey::UpdatedAt => codex_rollout::ThreadSortKey::UpdatedAt,
+        ThreadSortKey::RecencyAt => codex_rollout::ThreadSortKey::RecencyAt,
+        ThreadSortKey::SectionPosition => {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: "section-position sorting requires a section filter".to_owned(),
+            });
+        }
+    };
+    let sort_direction = match params.sort_direction {
+        SortDirection::Asc => codex_rollout::SortDirection::Asc,
+        SortDirection::Desc => codex_rollout::SortDirection::Desc,
+    };
+    let state_db = store.state_db().await;
+    let rollout_config = RolloutConfig {
+        codex_home: store.config.codex_home.clone(),
+        sqlite: store.config.sqlite.clone(),
+        cwd: store.config.codex_home.clone(),
+        model_provider_id: store.config.default_model_provider_id.clone(),
+        generate_memories: false,
+    };
+    let rg_command = InstallContext::current().rg_command();
+    let matching_rollouts = search_rollout_matches(
+        rg_command.as_path(),
+        store.config.codex_home.as_path(),
+        params.archived,
+        search_term,
+    )
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to search rollout contents: {err}"),
+    })?;
+    if matching_rollouts.is_empty() {
+        return Ok(ThreadSearchPage {
+            items: Vec::new(),
+            next_cursor: None,
+        });
+    }
+    let mut matching_items = Vec::new();
+    let mut page_cursor = cursor;
+    let scan_page_size = params.page_size.saturating_mul(8).clamp(256, 2048);
+    let scan_params = ListThreadsParams {
+        page_size: scan_page_size,
+        cursor: None,
+        sort_key: params.sort_key,
+        sort_direction: params.sort_direction,
+        allowed_sources: params.allowed_sources.clone(),
+        model_providers: None,
+        cwd_filters: None,
+        section: None,
+        project_id: None,
+        archived: params.archived,
+        search_term: None,
+        relation_filter: None,
+        use_state_db_only: state_db.is_some(),
+    };
+    let mut remaining_rollouts = matching_rollouts
+        .into_iter()
+        .map(|(path, snippet)| (rollout_search_path(&path), snippet))
+        .collect::<HashMap<_, _>>();
+
+    loop {
+        let page = list_rollout_threads(
+            state_db.clone(),
+            &rollout_config,
+            store.config.default_model_provider_id.as_str(),
+            &scan_params,
+            page_cursor.as_ref(),
+            sort_key,
+            sort_direction,
+        )
+        .await?;
+        for item in page.items {
+            let logical_path = rollout_search_path(item.path.as_path());
+            let Some(snippet) = (match remaining_rollouts.remove(logical_path.as_path()) {
+                Some(Some(snippet)) => Some(snippet),
+                Some(None) => first_rollout_content_match_snippet(item.path.as_path(), search_term)
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!("failed to read rollout search match: {err}"),
+                    })?,
+                None => None,
+            }) else {
+                continue;
+            };
+            matching_items.push(ThreadSearchItem { item, snippet });
+            if matching_items.len() > params.page_size {
+                break;
+            }
+        }
+        page_cursor = page.next_cursor;
+        if matching_items.len() > params.page_size
+            || remaining_rollouts.is_empty()
+            || page_cursor.is_none()
+        {
+            break;
+        }
+    }
+
+    let more_matches_available = matching_items.len() > params.page_size;
+    matching_items.truncate(params.page_size);
+    let next_cursor = if more_matches_available {
+        matching_items
+            .last()
+            .and_then(|item| cursor_from_thread_search_item(item, params.sort_key))
+    } else {
+        None
+    }
+    .as_ref()
+    .and_then(|cursor| serde_json::to_value(cursor).ok())
+    .and_then(|value| value.as_str().map(str::to_owned));
+
+    let mut items = matching_items
+        .into_iter()
+        .filter_map(|item| {
+            stored_thread_from_rollout_item(
+                item.item,
+                params.archived,
+                store.config.default_model_provider_id.as_str(),
+            )
+            .map(|thread| StoredThreadSearchResult {
+                thread,
+                snippet: item.snippet,
+            })
+        })
+        .collect::<Vec<_>>();
+    if let Some(state_db) = state_db {
+        let sectioned_thread_ids = items
+            .iter()
+            .filter(|item| item.thread.section.is_some())
+            .map(|item| item.thread.thread_id)
+            .collect::<Vec<_>>();
+        let mut section_metadata =
+            resolve_thread_section_metadata(state_db.as_ref(), &sectioned_thread_ids).await;
+        for item in &mut items {
+            if let Some((section_position, section_entered_at)) =
+                section_metadata.remove(&item.thread.thread_id)
+            {
+                item.thread.section_position = section_position;
+                item.thread.section_entered_at = section_entered_at;
+            }
+        }
+    }
+    set_thread_search_result_names(store, &mut items).await;
+
+    Ok(ThreadSearchPage { items, next_cursor })
+}
+
+fn rollout_search_path(path: &Path) -> PathBuf {
+    let path = codex_rollout::plain_rollout_path(path);
+    // Resume can persist a Windows namespace prefix while filesystem search returns the
+    // ordinary spelling. Normalize both join keys without requiring the uncompressed file
+    // to exist, and retain the filename identifying the selected rollout after a revert.
+    if cfg!(windows)
+        && let Some(normalized) = path.to_str().and_then(normalize_windows_device_path)
+    {
+        return PathBuf::from(normalized);
+    }
+    path
+}
+
+fn cursor_from_thread_search_item(
+    item: &ThreadSearchItem,
+    sort_key: ThreadSortKey,
+) -> Option<codex_rollout::Cursor> {
+    let timestamp = match sort_key {
+        ThreadSortKey::CreatedAt => item.item.created_at.as_deref()?,
+        ThreadSortKey::UpdatedAt => item
+            .item
+            .updated_at
+            .as_deref()
+            .or(item.item.created_at.as_deref())?,
+        ThreadSortKey::RecencyAt => item
+            .item
+            .recency_at
+            .as_deref()
+            .or(item.item.updated_at.as_deref())
+            .or(item.item.created_at.as_deref())?,
+        ThreadSortKey::SectionPosition => return None,
+    };
+    match sort_key {
+        ThreadSortKey::RecencyAt => parse_cursor(&format!("{timestamp}|{}", item.item.thread_id?)),
+        ThreadSortKey::CreatedAt | ThreadSortKey::UpdatedAt => parse_cursor(timestamp),
+        ThreadSortKey::SectionPosition => None,
+    }
+}
+
+async fn set_thread_search_result_names(
+    store: &LocalThreadStore,
+    items: &mut [StoredThreadSearchResult],
+) {
+    let thread_history_modes = items
+        .iter()
+        .map(|item| (item.thread.thread_id, item.thread.history_mode))
+        .collect::<HashMap<_, _>>();
+    let names = resolve_thread_names(store, &thread_history_modes).await;
+    for item in items {
+        if let Some(name) = names.get(&item.thread.thread_id).cloned() {
+            set_thread_name(&mut item.thread, name);
+        }
+    }
+}
diff --git a/codex-rs/thread-store/src/local/search_threads_tests.rs b/codex-rs/thread-store/src/local/search_threads_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..959882e24384471cafaac4b9b8c095366d3d847e
--- /dev/null
+++ b/codex-rs/thread-store/src/local/search_threads_tests.rs
@@ -0,0 +1,163 @@
+use chrono::Utc;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::ThreadItem;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+use uuid::Uuid;
+
+use super::super::LocalThreadStore;
+use super::super::test_support::test_config;
+use super::super::test_support::write_session_file_with;
+use super::ThreadSearchItem;
+use super::cursor_from_thread_search_item;
+use crate::SearchThreadsParams;
+use crate::SortDirection;
+use crate::ThreadSortKey;
+use crate::ThreadStore;
+
+#[test]
+fn recency_cursor_includes_thread_id_tie_breaker() {
+    let thread_id = ThreadId::from_string("00000000-0000-0000-0000-000000000123")
+        .expect("thread ID should parse");
+    let item = ThreadSearchItem {
+        item: ThreadItem {
+            thread_id: Some(thread_id),
+            recency_at: Some("2026-01-27T12:34:56Z".to_string()),
+            ..Default::default()
+        },
+        snippet: String::new(),
+    };
+
+    let cursor = cursor_from_thread_search_item(&item, ThreadSortKey::RecencyAt)
+        .expect("cursor should build");
+
+    assert_eq!(
+        serde_json::to_string(&cursor).expect("cursor should serialize"),
+        format!("\"2026-01-27T12:34:56Z|{thread_id}\"")
+    );
+}
+
+#[tokio::test]
+async fn search_matches_selected_rollout_across_path_spellings_and_compression() {
+    for compressed in [false, true] {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let state_db = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("initialize state database");
+        let uuid = Uuid::new_v4();
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("thread ID should parse");
+        let selected_path = write_session_file_with(
+            home.path(),
+            home.path().join("sessions/2025/01/03"),
+            "2025-01-03T12-00-00",
+            uuid,
+            "needle in selected rollout",
+            Some("test-provider"),
+            ThreadHistoryMode::Legacy,
+        )
+        .expect("write selected rollout");
+        // Reverting a thread leaves its previous rollout on disk with the same thread ID.
+        write_session_file_with(
+            home.path(),
+            home.path().join("sessions/2025/01/03"),
+            "2025-01-03T11-00-00",
+            uuid,
+            "obsolete needle in previous rollout",
+            Some("test-provider"),
+            ThreadHistoryMode::Legacy,
+        )
+        .expect("write unselected rollout");
+
+        let home_paths = [home.path().to_path_buf()];
+        #[cfg(windows)]
+        let home_paths = {
+            let verbatim = std::fs::canonicalize(&home_paths[0]).expect("canonicalize home");
+            let ordinary =
+                codex_utils_absolute_path::AbsolutePathBuf::from_absolute_path(&verbatim)
+                    .expect("normalize home")
+                    .into_path_buf();
+            [ordinary, verbatim]
+        };
+        let relative_path = selected_path
+            .strip_prefix(home.path())
+            .expect("relative rollout path");
+        let selected_paths = home_paths.each_ref().map(|home| home.join(relative_path));
+        #[cfg(windows)]
+        assert_ne!(selected_paths[0], selected_paths[1]);
+
+        if compressed {
+            let contents = std::fs::read(&selected_path).expect("read selected rollout");
+            let contents = zstd::stream::encode_all(contents.as_slice(), /*level*/ 3)
+                .expect("compress selected rollout");
+            std::fs::write(selected_path.with_extension("jsonl.zst"), contents)
+                .expect("write compressed rollout");
+            std::fs::remove_file(&selected_path).expect("remove plain rollout");
+        }
+        let selected_paths = selected_paths
+            .into_iter()
+            .flat_map(|path| {
+                let compressed_path = compressed.then(|| path.with_extension("jsonl.zst"));
+                std::iter::once(path).chain(compressed_path)
+            })
+            .collect::<Vec<_>>();
+
+        for codex_home in home_paths {
+            let store = LocalThreadStore::new(
+                super::super::LocalThreadStoreConfig {
+                    codex_home,
+                    ..config.clone()
+                },
+                Some(state_db.clone()),
+            );
+            for selected_path in &selected_paths {
+                let mut metadata = codex_state::ThreadMetadataBuilder::new(
+                    thread_id,
+                    selected_path.clone(),
+                    Utc::now(),
+                    SessionSource::Cli,
+                )
+                .build("test-provider");
+                metadata.first_user_message = Some("needle in selected rollout".to_string());
+                state_db
+                    .upsert_thread(&metadata)
+                    .await
+                    .expect("select rollout in database");
+
+                for (search_term, expected) in [
+                    ("needle", vec![(thread_id, "needle in selected rollout")]),
+                    ("obsolete", Vec::new()),
+                ] {
+                    let page = store
+                        .search_threads(SearchThreadsParams {
+                            page_size: 10,
+                            cursor: None,
+                            sort_key: ThreadSortKey::CreatedAt,
+                            sort_direction: SortDirection::Desc,
+                            allowed_sources: vec![SessionSource::Cli],
+                            archived: false,
+                            search_term: search_term.to_string(),
+                        })
+                        .await
+                        .expect("search selected rollout");
+                    assert_eq!(
+                        (
+                            page.items
+                                .iter()
+                                .map(|item| (item.thread.thread_id, item.snippet.as_str()))
+                                .collect::<Vec<_>>(),
+                            page.next_cursor,
+                        ),
+                        (expected, None),
+                        "compressed={compressed}, selected_path={selected_path:?}",
+                    );
+                }
+            }
+        }
+    }
+}
diff --git a/codex-rs/thread-store/src/local/test_support.rs b/codex-rs/thread-store/src/local/test_support.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e7b014b43b073c475f4a9bf6f29fa7e8268f895d
--- /dev/null
+++ b/codex-rs/thread-store/src/local/test_support.rs
@@ -0,0 +1,131 @@
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::ARCHIVED_SESSIONS_SUBDIR;
+use codex_utils_absolute_path::test_support::PathExt;
+use uuid::Uuid;
+
+use super::LocalThreadStoreConfig;
+
+pub(super) fn test_config(codex_home: &Path) -> LocalThreadStoreConfig {
+    LocalThreadStoreConfig {
+        codex_home: codex_home.to_path_buf(),
+        sqlite: codex_state::SqliteConfig::new_for_testing(codex_home.abs()),
+        default_model_provider_id: "test-provider".to_string(),
+    }
+}
+
+pub(super) fn write_session_file(root: &Path, ts: &str, uuid: Uuid) -> std::io::Result<PathBuf> {
+    write_session_file_with_history_mode(root, ts, uuid, ThreadHistoryMode::Legacy)
+}
+
+pub(super) fn write_session_file_with_history_mode(
+    root: &Path,
+    ts: &str,
+    uuid: Uuid,
+    history_mode: ThreadHistoryMode,
+) -> std::io::Result<PathBuf> {
+    write_session_file_with(
+        root,
+        root.join("sessions/2025/01/03"),
+        ts,
+        uuid,
+        "Hello from user",
+        Some("test-provider"),
+        history_mode,
+    )
+}
+
+pub(super) fn write_archived_session_file(
+    root: &Path,
+    ts: &str,
+    uuid: Uuid,
+) -> std::io::Result<PathBuf> {
+    write_session_file_with(
+        root,
+        root.join(ARCHIVED_SESSIONS_SUBDIR),
+        ts,
+        uuid,
+        "Archived user message",
+        Some("test-provider"),
+        ThreadHistoryMode::Legacy,
+    )
+}
+
+pub(super) fn write_session_file_with(
+    root: &Path,
+    day_dir: PathBuf,
+    ts: &str,
+    uuid: Uuid,
+    first_user_message: &str,
+    model_provider: Option<&str>,
+    history_mode: ThreadHistoryMode,
+) -> std::io::Result<PathBuf> {
+    write_session_file_with_fork(
+        root,
+        day_dir,
+        ts,
+        uuid,
+        first_user_message,
+        model_provider,
+        /*forked_from_id*/ None,
+        history_mode,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(super) fn write_session_file_with_fork(
+    root: &Path,
+    day_dir: PathBuf,
+    ts: &str,
+    uuid: Uuid,
+    first_user_message: &str,
+    model_provider: Option<&str>,
+    forked_from_id: Option<Uuid>,
+    history_mode: ThreadHistoryMode,
+) -> std::io::Result<PathBuf> {
+    fs::create_dir_all(&day_dir)?;
+    let path = day_dir.join(format!("rollout-{ts}-{uuid}.jsonl"));
+    let mut file = fs::File::create(&path)?;
+    let mut meta = serde_json::json!({
+        "timestamp": ts,
+        "type": "session_meta",
+        "payload": {
+            "session_id": uuid,
+            "id": uuid,
+            "forked_from_id": forked_from_id,
+            "timestamp": ts,
+            "cwd": root,
+            "originator": "test_originator",
+            "cli_version": "test_version",
+            "source": "cli",
+            "model_provider": model_provider,
+            "history_mode": history_mode,
+            "git": {
+                "commit_hash": "abcdef",
+                "branch": "main",
+                "repository_url": "https://example.com/repo.git"
+            }
+        },
+    });
+    if matches!(history_mode, ThreadHistoryMode::Paginated) {
+        meta["ordinal"] = serde_json::json!(0);
+    }
+    writeln!(file, "{meta}")?;
+    if matches!(history_mode, ThreadHistoryMode::Legacy) {
+        let user_event = serde_json::json!({
+            "timestamp": ts,
+            "type": "event_msg",
+            "payload": {
+                "type": "user_message",
+                "message": first_user_message,
+                "kind": "plain",
+            },
+        });
+        writeln!(file, "{user_event}")?;
+    }
+    Ok(path)
+}
diff --git a/codex-rs/thread-store/src/local/tests/acquisition_tests.rs b/codex-rs/thread-store/src/local/tests/acquisition_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..db026605711db5811fe2d72a3682cced339bc90a
--- /dev/null
+++ b/codex-rs/thread-store/src/local/tests/acquisition_tests.rs
@@ -0,0 +1,51 @@
+//! Persistence acquisition stays owned when its caller is cancelled after writer installation.
+
+use super::*;
+use crate::LiveThreadInitGuard;
+use futures::poll;
+use tokio::sync::oneshot;
+
+#[tokio::test]
+async fn cancelled_acquisition_waits_for_writer_handoff_before_discarding() {
+    let home = TempDir::new().expect("temp dir");
+    let store = Arc::new(LocalThreadStore::new(
+        test_config(home.path()),
+        /*state_db*/ None,
+    ));
+    let thread_id = ThreadId::default();
+    let params = create_thread_params(thread_id);
+    let (installed, installation) = oneshot::channel();
+    let (release, released) = oneshot::channel();
+    let creating_store = Arc::clone(&store);
+    // Model the cloud wrapper: creation runs independently, installs its writer, then awaits
+    // initial metadata before returning. Dropping the JoinHandle would detach that work.
+    let creating = tokio::spawn(async move {
+        let live_thread = LiveThread::create(creating_store, params).await?;
+        installed.send(()).expect("installation observed");
+        released.await.expect("release acquisition");
+        Ok(live_thread)
+    });
+    let mut guard = LiveThreadInitGuard::default();
+    let mut start = Box::pin(guard.acquire(async move { creating.await.expect("creation task") }));
+    assert!(poll!(&mut start).is_pending());
+    installation
+        .await
+        .expect("writer installed before cancellation");
+    drop(start);
+    store
+        .flush_thread(thread_id)
+        .await
+        .expect("writer installed");
+
+    let mut cleanup = Box::pin(guard.discard());
+    assert!(
+        poll!(&mut cleanup).is_pending(),
+        "cleanup must retain the unfinished acquisition"
+    );
+    release.send(()).expect("creation still owned");
+    cleanup.await;
+    assert!(matches!(
+        store.flush_thread(thread_id).await,
+        Err(ThreadStoreError::ThreadNotFound { .. })
+    ));
+}
diff --git a/codex-rs/thread-store/src/local/thread_attachments.rs b/codex-rs/thread-store/src/local/thread_attachments.rs
new file mode 100644
index 0000000000000000000000000000000000000000..aa200552071f0de3b5394a7aad608291a02dea64
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_attachments.rs
@@ -0,0 +1,116 @@
+//! Local attachment adapter sharing lifecycle exclusion with thread deletion.
+
+use super::LocalThreadStore;
+use crate::AddThreadAttachmentOutcome;
+use crate::AddThreadAttachmentParams;
+use crate::ListThreadAttachmentsParams;
+use crate::RemoveThreadAttachmentOutcome;
+use crate::RemoveThreadAttachmentParams;
+use crate::ThreadAttachmentPage;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use codex_protocol::ThreadId;
+use codex_rollout::StateDbHandle;
+
+pub(super) async fn copy_thread_attachments(
+    store: &LocalThreadStore,
+    source_thread_id: ThreadId,
+    destination_thread_id: ThreadId,
+) -> ThreadStoreResult<()> {
+    let state_db = state_db(store, "copy_thread_attachments")?;
+    let _lifecycle_reservation = store
+        .live_writer_locks
+        .reserve_lifecycle(destination_thread_id)
+        .await;
+    // Reference-backed forks already reserve their source. Do not recursively acquire that
+    // reservation: a queued deletion could deadlock it. SQLite serializes the source snapshot.
+    state_db
+        .copy_thread_attachments(source_thread_id, destination_thread_id)
+        .await
+        .map_err(|error| attachment_error("copy", Some(destination_thread_id), error))
+}
+
+pub(super) async fn add_thread_attachment(
+    store: &LocalThreadStore,
+    params: AddThreadAttachmentParams,
+) -> ThreadStoreResult<AddThreadAttachmentOutcome> {
+    let state_db = state_db(store, "thread/attachment/add")?;
+    let _lifecycle_reservation = store
+        .live_writer_locks
+        .reserve_lifecycle(params.thread_id)
+        .await;
+    state_db
+        .add_thread_attachment(
+            params.thread_id,
+            &params.attachment_type,
+            &params.identity_key,
+            &params.payload,
+        )
+        .await
+        .map_err(|error| attachment_error("add", Some(params.thread_id), error))
+}
+
+pub(super) async fn list_thread_attachments(
+    store: &LocalThreadStore,
+    params: ListThreadAttachmentsParams,
+) -> ThreadStoreResult<ThreadAttachmentPage> {
+    let state_db = state_db(store, "thread/attachment/list")?;
+    state_db
+        .list_thread_attachments(params.thread_id, params.cursor.as_deref(), params.limit)
+        .await
+        .map_err(|error| attachment_error("list", /*thread_id*/ None, error))
+}
+
+pub(super) async fn remove_thread_attachment(
+    store: &LocalThreadStore,
+    params: RemoveThreadAttachmentParams,
+) -> ThreadStoreResult<RemoveThreadAttachmentOutcome> {
+    let state_db = state_db(store, "thread/attachment/remove")?;
+    let _lifecycle_reservation = store
+        .live_writer_locks
+        .reserve_lifecycle(params.thread_id)
+        .await;
+    state_db
+        .remove_thread_attachment(
+            params.thread_id,
+            &params.attachment_type,
+            &params.identity_key,
+        )
+        .await
+        .map_err(|error| attachment_error("remove", Some(params.thread_id), error))
+}
+
+fn state_db<'store>(
+    store: &'store LocalThreadStore,
+    operation: &'static str,
+) -> ThreadStoreResult<&'store StateDbHandle> {
+    store
+        .state_db
+        .as_ref()
+        .ok_or(ThreadStoreError::Unsupported { operation })
+}
+
+fn attachment_error(
+    operation: &str,
+    thread_id: Option<ThreadId>,
+    error: impl std::fmt::Display,
+) -> ThreadStoreError {
+    let message = error.to_string();
+    if let Some(message) = message.strip_prefix("invalid thread attachment request: ") {
+        return ThreadStoreError::InvalidRequest {
+            message: message.to_string(),
+        };
+    }
+    if message.starts_with("thread not found: ")
+        && let Some(thread_id) = thread_id
+    {
+        return ThreadStoreError::ThreadNotFound { thread_id };
+    }
+    ThreadStoreError::Internal {
+        message: format!("failed to {operation} thread attachment: {message}"),
+    }
+}
+
+#[cfg(test)]
+#[path = "thread_attachments_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/thread_attachments_tests.rs b/codex-rs/thread-store/src/local/thread_attachments_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..936447a73d2edd6fcf965b8fd7cb57f21efaabb8
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_attachments_tests.rs
@@ -0,0 +1,509 @@
+//! Coverage for unloaded attachment operations and thread deletion exclusion.
+
+use super::LocalThreadStore;
+use crate::AddThreadAttachmentOutcome;
+use crate::AddThreadAttachmentParams;
+use crate::DeleteThreadParams;
+use crate::DeleteThreadsParams;
+use crate::InMemoryThreadStore;
+use crate::ListThreadAttachmentsParams;
+use crate::RemoveThreadAttachmentOutcome;
+use crate::RemoveThreadAttachmentParams;
+use crate::ThreadAttachmentPage;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::local::test_support::test_config;
+use crate::local::test_support::write_session_file;
+use chrono::Utc;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::SessionSource;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::path::Path;
+use std::path::PathBuf;
+use uuid::Uuid;
+
+#[tokio::test]
+async fn thread_attachments_require_a_supported_sqlite_store() {
+    let thread_id = ThreadId::new();
+    let default_store = InMemoryThreadStore::default();
+    assert!(!default_store.supports_thread_attachments());
+    assert!(matches!(
+        default_store
+            .add_thread_attachment(AddThreadAttachmentParams {
+                thread_id,
+                attachment_type: "pull_request".to_string(),
+                identity_key: "openai/codex#1".to_string(),
+                payload: json!({"url": "https://github.com/openai/codex/pull/1"}),
+            })
+            .await,
+        Err(ThreadStoreError::Unsupported {
+            operation: "thread/attachment/add"
+        })
+    ));
+
+    let home = tempfile::TempDir::new().expect("temp dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    assert!(!store.supports_thread_attachments());
+    assert!(matches!(
+        store
+            .list_thread_attachments(ListThreadAttachmentsParams {
+                thread_id,
+                cursor: None,
+                limit: 10,
+            })
+            .await,
+        Err(ThreadStoreError::Unsupported {
+            operation: "thread/attachment/list"
+        })
+    ));
+    assert!(matches!(
+        store
+            .remove_thread_attachment(RemoveThreadAttachmentParams {
+                thread_id,
+                attachment_type: "pull_request".to_string(),
+                identity_key: "openai/codex#1".to_string(),
+            })
+            .await,
+        Err(ThreadStoreError::Unsupported {
+            operation: "thread/attachment/remove"
+        })
+    ));
+}
+
+#[tokio::test]
+async fn unloaded_thread_attachments_support_listing_and_removal() {
+    let home = tempfile::TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state db should initialize");
+    let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+    assert!(store.supports_thread_attachments());
+
+    let first_thread_id = ThreadId::new();
+    let second_thread_id = ThreadId::new();
+    for thread_id in [first_thread_id, second_thread_id] {
+        let metadata = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            home.path().join(format!("{thread_id}.jsonl")),
+            Utc::now(),
+            SessionSource::Cli,
+        )
+        .build(&config.default_model_provider_id);
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("persist unloaded thread metadata");
+    }
+
+    let params = AddThreadAttachmentParams {
+        thread_id: first_thread_id,
+        attachment_type: "pull_request".to_string(),
+        identity_key: "openai/codex#1".to_string(),
+        payload: json!({"url": "https://github.com/openai/codex/pull/1"}),
+    };
+    let AddThreadAttachmentOutcome::Created(first_attachment) = store
+        .add_thread_attachment(params.clone())
+        .await
+        .expect("attach attachment to unloaded persisted thread")
+    else {
+        panic!("first explicit attachment should create an attachment");
+    };
+    assert_eq!(
+        store
+            .add_thread_attachment(params.clone())
+            .await
+            .expect("repeat attachment attachment"),
+        AddThreadAttachmentOutcome::Existing(first_attachment.clone())
+    );
+
+    let second_params = AddThreadAttachmentParams {
+        thread_id: first_thread_id,
+        identity_key: "openai/codex#2".to_string(),
+        payload: json!({"url": "https://github.com/openai/codex/pull/2"}),
+        ..params.clone()
+    };
+    let AddThreadAttachmentOutcome::Created(second_attachment) = store
+        .add_thread_attachment(second_params)
+        .await
+        .expect("attach second thread attachment")
+    else {
+        panic!("second thread attachment should create an attachment");
+    };
+
+    let first_page = store
+        .list_thread_attachments(ListThreadAttachmentsParams {
+            thread_id: first_thread_id,
+            cursor: None,
+            limit: 1,
+        })
+        .await
+        .expect("list first page");
+    assert_eq!(first_page.attachments.len(), 1);
+    let second_page = store
+        .list_thread_attachments(ListThreadAttachmentsParams {
+            thread_id: first_thread_id,
+            cursor: first_page.next_cursor,
+            limit: 1,
+        })
+        .await
+        .expect("list second page");
+    assert_eq!(second_page.attachments.len(), 1);
+    assert_eq!(second_page.next_cursor, None);
+    let listed_ids = [
+        first_page.attachments[0].id.clone(),
+        second_page.attachments[0].id.clone(),
+    ];
+    assert!(listed_ids.contains(&first_attachment.id));
+    assert!(listed_ids.contains(&second_attachment.id));
+
+    let removal_params = RemoveThreadAttachmentParams {
+        thread_id: first_thread_id,
+        attachment_type: params.attachment_type.clone(),
+        identity_key: params.identity_key.clone(),
+    };
+    assert_eq!(
+        store
+            .remove_thread_attachment(removal_params.clone())
+            .await
+            .expect("remove existing attachment"),
+        RemoveThreadAttachmentOutcome::Removed(first_attachment)
+    );
+    assert_eq!(
+        store
+            .remove_thread_attachment(removal_params)
+            .await
+            .expect("repeat attachment removal"),
+        RemoveThreadAttachmentOutcome::NotFound
+    );
+    assert!(matches!(
+        store
+            .add_thread_attachment(params)
+            .await
+            .expect("reattach removed attachment"),
+        AddThreadAttachmentOutcome::Created(_)
+    ));
+}
+
+#[tokio::test]
+async fn attachment_state_errors_preserve_missing_thread_and_invalid_request_categories() {
+    let home = tempfile::TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state db should initialize");
+    let store = LocalThreadStore::new(config, Some(runtime));
+    let thread_id = ThreadId::new();
+
+    assert!(matches!(
+        store
+            .add_thread_attachment(AddThreadAttachmentParams {
+                thread_id,
+                attachment_type: "pull_request".to_string(),
+                identity_key: "openai/codex#1".to_string(),
+                payload: json!({}),
+            })
+            .await,
+        Err(ThreadStoreError::ThreadNotFound { thread_id: missing }) if missing == thread_id
+    ));
+    assert!(matches!(
+        store
+            .add_thread_attachment(AddThreadAttachmentParams {
+                thread_id,
+                attachment_type: " ".to_string(),
+                identity_key: "openai/codex#1".to_string(),
+                payload: json!({}),
+            })
+            .await,
+        Err(ThreadStoreError::InvalidRequest { message })
+            if message == "attachment type must not be empty"
+    ));
+    assert!(matches!(
+        store
+            .list_thread_attachments(ListThreadAttachmentsParams {
+                thread_id,
+                cursor: None,
+                limit: 0,
+            })
+            .await,
+        Err(ThreadStoreError::InvalidRequest { message })
+            if message == "page limit must be between 1 and 100"
+    ));
+}
+
+#[tokio::test]
+async fn attachment_mutations_wait_for_exclusive_thread_lifecycle_operations() {
+    let home = tempfile::TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state db should initialize");
+    let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+    let thread_id = ThreadId::new();
+    let metadata = codex_state::ThreadMetadataBuilder::new(
+        thread_id,
+        home.path().join(format!("{thread_id}.jsonl")),
+        Utc::now(),
+        SessionSource::Cli,
+    )
+    .build(&config.default_model_provider_id);
+    runtime
+        .upsert_thread(&metadata)
+        .await
+        .expect("persist attachment owner");
+
+    let lifecycle_guard = store.live_writer_locks.lock_lifecycle(thread_id).await;
+    let mut attachment = Box::pin(store.add_thread_attachment(AddThreadAttachmentParams {
+        thread_id,
+        attachment_type: "pull_request".to_string(),
+        identity_key: "openai/codex#1".to_string(),
+        payload: json!({"url": "https://github.com/openai/codex/pull/1"}),
+    }));
+    tokio::select! {
+        biased;
+        result = &mut attachment => panic!("attachment attached during lifecycle mutation: {result:?}"),
+        _ = tokio::task::yield_now() => {}
+    }
+    drop(lifecycle_guard);
+    assert!(matches!(
+        attachment.await,
+        Ok(AddThreadAttachmentOutcome::Created(_))
+    ));
+
+    let lifecycle_guard = store.live_writer_locks.lock_lifecycle(thread_id).await;
+    let mut removal = Box::pin(
+        store.remove_thread_attachment(RemoveThreadAttachmentParams {
+            thread_id,
+            attachment_type: "pull_request".to_string(),
+            identity_key: "openai/codex#1".to_string(),
+        }),
+    );
+    tokio::select! {
+        biased;
+        result = &mut removal => panic!("attachment removed during lifecycle mutation: {result:?}"),
+        _ = tokio::task::yield_now() => {}
+    }
+    drop(lifecycle_guard);
+    assert!(matches!(
+        removal.await,
+        Ok(RemoveThreadAttachmentOutcome::Removed(_))
+    ));
+}
+
+#[tokio::test]
+async fn attachment_mutations_queued_behind_deletion_reject_deleted_threads() {
+    enum DeleteMode {
+        Single,
+        Batch,
+    }
+
+    for mode in [DeleteMode::Single, DeleteMode::Batch] {
+        let home = tempfile::TempDir::new().expect("temp dir");
+        let thread_id = ThreadId::new();
+        let thread_ids = match mode {
+            DeleteMode::Single => vec![thread_id],
+            DeleteMode::Batch => vec![thread_id, ThreadId::new()],
+        };
+        let (store, _) = store_with_attachment_owners(home.path(), &thread_ids).await;
+        let runtime = store.state_db().await.expect("state db");
+
+        let reservation = store.live_writer_locks.reserve_lifecycle(thread_id).await;
+        let mut deletion = match mode {
+            DeleteMode::Single => store.delete_thread(DeleteThreadParams { thread_id }),
+            DeleteMode::Batch => store.delete_threads(DeleteThreadsParams {
+                thread_ids: thread_ids.clone(),
+            }),
+        };
+        assert!(futures::poll!(&mut deletion).is_pending());
+
+        // The queued exclusive delete must precede subsequent shared attachment reservations.
+        let mut attachment = store.add_thread_attachment(AddThreadAttachmentParams {
+            thread_id,
+            attachment_type: "pull_request".to_string(),
+            identity_key: "openai/codex#2".to_string(),
+            payload: json!({"url": "https://github.com/openai/codex/pull/2"}),
+        });
+        let mut removal = store.remove_thread_attachment(RemoveThreadAttachmentParams {
+            thread_id,
+            attachment_type: "pull_request".to_string(),
+            identity_key: "openai/codex#1".to_string(),
+        });
+        assert!(futures::poll!(&mut attachment).is_pending());
+        assert!(futures::poll!(&mut removal).is_pending());
+        drop(reservation);
+
+        let (deletion, attachment, removal) = tokio::join!(deletion, attachment, removal);
+        deletion.expect("delete attachment owners");
+        assert!(
+            matches!(attachment, Err(ThreadStoreError::ThreadNotFound { thread_id: missing }) if missing == thread_id),
+            "attachment resumed after deletion: {attachment:?}"
+        );
+        assert!(
+            matches!(removal, Err(ThreadStoreError::ThreadNotFound { thread_id: missing }) if missing == thread_id),
+            "removal resumed after deletion: {removal:?}"
+        );
+        for &owner_id in &thread_ids {
+            assert_eq!(
+                runtime
+                    .get_thread(owner_id)
+                    .await
+                    .expect("read deleted owner"),
+                None
+            );
+        }
+        for &owner_id in &thread_ids {
+            assert_eq!(
+                store
+                    .list_thread_attachments(ListThreadAttachmentsParams {
+                        thread_id: owner_id,
+                        cursor: None,
+                        limit: 10,
+                    })
+                    .await
+                    .expect("list attachments after deletion"),
+                ThreadAttachmentPage {
+                    attachments: Vec::new(),
+                    next_cursor: None,
+                }
+            );
+        }
+    }
+}
+
+#[tokio::test]
+async fn attachment_owner_deletion_can_retry_after_state_cleanup_fails() {
+    let home = tempfile::TempDir::new().expect("temp dir");
+    let parent_id = ThreadId::new();
+    let child_id = ThreadId::new();
+    let (store, rollout_paths) =
+        store_with_attachment_owners(home.path(), &[parent_id, child_id]).await;
+    let runtime = store.state_db().await.expect("state db");
+    runtime
+        .upsert_thread_spawn_edge(
+            parent_id,
+            child_id,
+            codex_state::DirectionalThreadSpawnEdgeStatus::Closed,
+        )
+        .await
+        .expect("persist child relation for deletion retry");
+    let pool = runtime
+        .sqlite()
+        .open_read_write_pool(&runtime.sqlite().state_db_path())
+        .await
+        .expect("open state db for failure injection");
+    sqlx::query(
+        "CREATE TRIGGER fail_thread_delete BEFORE DELETE ON threads BEGIN SELECT RAISE(ABORT, 'state cleanup failed'); END",
+    )
+    .execute(&pool)
+    .await
+    .expect("inject state cleanup failure");
+    let params = DeleteThreadsParams {
+        thread_ids: vec![child_id, parent_id],
+    };
+    let error = store
+        .delete_threads(params.clone())
+        .await
+        .expect_err("state cleanup failure must fail the delete");
+    assert!(matches!(error, ThreadStoreError::Internal { .. }));
+    assert!(rollout_paths.iter().all(|path| !path.exists()));
+    assert_eq!(
+        runtime
+            .list_thread_spawn_descendants(parent_id)
+            .await
+            .expect("read child relation after failed deletion"),
+        vec![child_id]
+    );
+
+    sqlx::query("DROP TRIGGER fail_thread_delete")
+        .execute(&pool)
+        .await
+        .expect("restore state cleanup");
+    store
+        .delete_thread(DeleteThreadParams {
+            thread_id: child_id,
+        })
+        .await
+        .expect("single-thread retry must remove the owner even without a rollout");
+    store
+        .delete_threads(params.clone())
+        .await
+        .expect("batch retry must tolerate missing rollouts and already-deleted members");
+    for &owner_id in &params.thread_ids {
+        assert_eq!(
+            store
+                .list_thread_attachments(ListThreadAttachmentsParams {
+                    thread_id: owner_id,
+                    cursor: None,
+                    limit: 10,
+                })
+                .await
+                .expect("list attachments after deletion retry"),
+            ThreadAttachmentPage {
+                attachments: Vec::new(),
+                next_cursor: None,
+            }
+        );
+    }
+    assert_eq!(
+        runtime
+            .delete_threads_strict(&params.thread_ids)
+            .await
+            .expect("repeated app-server state cleanup is idempotent"),
+        0
+    );
+}
+
+async fn store_with_attachment_owners(
+    home: &Path,
+    thread_ids: &[ThreadId],
+) -> (LocalThreadStore, Vec<PathBuf>) {
+    let config = test_config(home);
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state db should initialize");
+    let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+    let mut rollout_paths = Vec::new();
+    for &thread_id in thread_ids {
+        let rollout_path = write_session_file(
+            home,
+            "2025-01-03T12-00-00",
+            Uuid::parse_str(&thread_id.to_string()).expect("thread UUID"),
+        )
+        .expect("session file");
+        let metadata = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            rollout_path.clone(),
+            Utc::now(),
+            SessionSource::Cli,
+        )
+        .build(&config.default_model_provider_id);
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("persist attachment owner");
+        store
+            .add_thread_attachment(AddThreadAttachmentParams {
+                thread_id,
+                attachment_type: "pull_request".to_string(),
+                identity_key: "openai/codex#1".to_string(),
+                payload: json!({"url": "https://github.com/openai/codex/pull/1"}),
+            })
+            .await
+            .expect("attach attachment before deleting its owner");
+        rollout_paths.push(rollout_path);
+    }
+    (store, rollout_paths)
+}
diff --git a/codex-rs/thread-store/src/local/thread_history.rs b/codex-rs/thread-store/src/local/thread_history.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7b31841842672ec15cc14ff09349de04c5008136
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history.rs
@@ -0,0 +1,573 @@
+use codex_app_server_protocol::ThreadHistoryChangeSet;
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::TurnStatus;
+use codex_protocol::ThreadId;
+use codex_protocol::models::MessagePhase;
+use codex_protocol::realtime::RealtimeItem;
+
+use super::LocalThreadStore;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+mod read;
+mod realtime;
+mod search;
+mod segment_paging;
+mod turn_lookup;
+
+pub(super) use read::list_items;
+pub(super) use read::list_turns;
+pub(super) use realtime::list_timeline;
+pub(super) use search::search_thread_occurrences;
+pub(super) use turn_lookup::find_source_turn;
+pub(super) use turn_lookup::find_visible_turn;
+
+/// A valid complete rollout line with its absolute byte span in durable JSONL.
+///
+/// `start_byte_offset..end_byte_offset` includes the terminating newline.
+pub(super) struct ProjectedRolloutLine {
+    pub ordinal: u64,
+    pub start_byte_offset: u64,
+    pub end_byte_offset: u64,
+    pub fallback_created_at_ms: Option<i64>,
+    pub changes: ThreadHistoryChangeSet,
+    pub realtime_item: Option<RealtimeItem>,
+}
+
+/// One ordered update to apply while advancing a rollout projection checkpoint.
+///
+/// Skipped ordinal ranges keep the byte and ordinal checkpoints describing the same durable
+/// prefix even when a complete rollout line cannot be projected.
+pub(super) enum RolloutProjectionStep {
+    Line(Box<ProjectedRolloutLine>),
+    SkippedOrdinalRange {
+        start_ordinal: u64,
+        end_ordinal_exclusive: u64,
+    },
+}
+
+pub(super) struct RolloutProjectionState {
+    pub next_byte_offset: u64,
+    pub next_ordinal: u64,
+}
+
+pub(super) async fn projection_state(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<Option<RolloutProjectionState>> {
+    if store.state_db.is_none() {
+        return Ok(None);
+    }
+    let db_path = store.config.sqlite.thread_history_db_path();
+    if !tokio::fs::try_exists(db_path.as_path())
+        .await
+        .map_err(thread_history_error)?
+    {
+        return Ok(None);
+    }
+
+    let pool = store.thread_history_db().await?;
+    let state = sqlx::query_as::<_, (i64, i64)>(
+        r#"
+SELECT next_rollout_byte_offset, next_rollout_ordinal
+FROM thread_history_projection_state
+WHERE thread_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .fetch_optional(pool)
+    .await
+    .map_err(thread_history_error)?;
+    state
+        .map(|(next_byte_offset, next_ordinal)| {
+            Ok(RolloutProjectionState {
+                next_byte_offset: u64::try_from(next_byte_offset).map_err(|_| {
+                    ThreadStoreError::Internal {
+                        message: format!(
+                            "thread history projection for {thread_id} has a negative byte offset"
+                        ),
+                    }
+                })?,
+                next_ordinal: u64::try_from(next_ordinal).map_err(|_| {
+                    ThreadStoreError::Internal {
+                        message: format!(
+                            "thread history projection for {thread_id} has a negative ordinal"
+                        ),
+                    }
+                })?,
+            })
+        })
+        .transpose()
+}
+
+pub(super) async fn apply_projection(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    start_offset: u64,
+    next_offset: u64,
+    initial_ordinal: u64,
+    projections: Vec<RolloutProjectionStep>,
+) -> ThreadStoreResult<()> {
+    let pool = store.thread_history_db().await?;
+    // Write the projected rows and advance the JSONL offset and ordinal in one transaction. If
+    // SQLite fails, it stays behind the durable rollout instead of claiming data it did not
+    // materialize.
+    let mut transaction = pool
+        .begin_with("BEGIN IMMEDIATE")
+        .await
+        .map_err(thread_history_error)?;
+    let thread_id = thread_id.to_string();
+    let projection_state = sqlx::query_as::<_, (i64, i64)>(
+        r#"
+SELECT next_rollout_byte_offset, next_rollout_ordinal
+FROM thread_history_projection_state
+WHERE thread_id = ?
+        "#,
+    )
+    .bind(thread_id.as_str())
+    .fetch_optional(&mut *transaction)
+    .await
+    .map_err(thread_history_error)?;
+    let (expected_offset, mut next_ordinal) =
+        projection_state.unwrap_or((0, sqlite_integer(initial_ordinal, "rollout ordinal")?));
+    let start_offset = sqlite_integer(start_offset, "rollout byte offset")?;
+    if expected_offset != start_offset {
+        return Err(ThreadStoreError::Internal {
+            message: format!("thread history projection for {thread_id} is behind durable rollout"),
+        });
+    }
+
+    for projection in projections {
+        match projection {
+            RolloutProjectionStep::Line(projection) => {
+                let ordinal = sqlite_integer(projection.ordinal, "rollout ordinal")?;
+                if ordinal != next_ordinal {
+                    return Err(ThreadStoreError::Internal {
+                        message: format!(
+                            "thread history projection for {thread_id} expected ordinal {next_ordinal}, got {ordinal}"
+                        ),
+                    });
+                }
+                apply_change_set(
+                    &mut transaction,
+                    thread_id.as_str(),
+                    ordinal,
+                    sqlite_integer(projection.start_byte_offset, "rollout byte offset")?,
+                    sqlite_integer(projection.end_byte_offset, "rollout byte offset")?,
+                    projection.fallback_created_at_ms,
+                    projection.changes,
+                )
+                .await?;
+                if let Some(item) = projection.realtime_item {
+                    let item_json = serde_json::to_string(&item).map_err(thread_history_error)?;
+                    sqlx::query(
+                        r#"
+INSERT INTO thread_realtime_items (
+    thread_id,
+    item_id,
+    rollout_ordinal,
+    created_at_ms,
+    item_type,
+    item_json
+) VALUES (?, ?, ?, ?, json_extract(?, '$.type'), ?)
+ON CONFLICT(thread_id, item_id) DO NOTHING
+                        "#,
+                    )
+                    .bind(thread_id.as_str())
+                    .bind(item.id.as_str())
+                    .bind(ordinal)
+                    .bind(projection.fallback_created_at_ms.ok_or_else(|| {
+                        ThreadStoreError::Internal {
+                            message: "realtime rollout item is missing its timestamp".to_string(),
+                        }
+                    })?)
+                    .bind(item_json.as_str())
+                    .bind(item_json.as_str())
+                    .execute(&mut *transaction)
+                    .await
+                    .map_err(thread_history_error)?;
+                }
+                next_ordinal =
+                    next_ordinal
+                        .checked_add(1)
+                        .ok_or_else(|| ThreadStoreError::Internal {
+                            message: "rollout ordinal exceeds SQLite integer range".to_string(),
+                        })?;
+            }
+            RolloutProjectionStep::SkippedOrdinalRange {
+                start_ordinal,
+                end_ordinal_exclusive,
+            } => {
+                let start_ordinal = sqlite_integer(start_ordinal, "rollout ordinal")?;
+                if start_ordinal != next_ordinal {
+                    return Err(ThreadStoreError::Internal {
+                        message: format!(
+                            "thread history projection for {thread_id} expected ordinal {next_ordinal}, got {start_ordinal}"
+                        ),
+                    });
+                }
+                let end_ordinal_exclusive =
+                    sqlite_integer(end_ordinal_exclusive, "rollout ordinal")?;
+                if end_ordinal_exclusive <= start_ordinal {
+                    return Err(ThreadStoreError::Internal {
+                        message: format!(
+                            "thread history projection for {thread_id} has an empty skipped ordinal range"
+                        ),
+                    });
+                }
+                next_ordinal = end_ordinal_exclusive;
+            }
+        }
+    }
+
+    sqlx::query(
+        r#"
+INSERT INTO thread_history_projection_state (
+    thread_id,
+    next_rollout_byte_offset,
+    next_rollout_ordinal
+) VALUES (?, ?, ?)
+ON CONFLICT(thread_id) DO UPDATE SET
+    next_rollout_byte_offset = excluded.next_rollout_byte_offset,
+    next_rollout_ordinal = excluded.next_rollout_ordinal
+        "#,
+    )
+    .bind(thread_id.as_str())
+    .bind(sqlite_integer(next_offset, "rollout byte offset")?)
+    .bind(next_ordinal)
+    .execute(&mut *transaction)
+    .await
+    .map_err(thread_history_error)?;
+    transaction.commit().await.map_err(thread_history_error)
+}
+
+pub(super) async fn delete_thread(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<()> {
+    let db_path = store.config.sqlite.thread_history_db_path();
+    if !tokio::fs::try_exists(db_path.as_path())
+        .await
+        .map_err(thread_history_delete_error)?
+    {
+        return Ok(());
+    }
+
+    let pool = store.thread_history_db().await?;
+    let mut transaction = pool
+        .begin_with("BEGIN IMMEDIATE")
+        .await
+        .map_err(thread_history_delete_error)?;
+    let thread_id = thread_id.to_string();
+    sqlx::query("DELETE FROM thread_items WHERE thread_id = ?")
+        .bind(thread_id.as_str())
+        .execute(&mut *transaction)
+        .await
+        .map_err(thread_history_delete_error)?;
+    sqlx::query("DELETE FROM thread_realtime_items WHERE thread_id = ?")
+        .bind(thread_id.as_str())
+        .execute(&mut *transaction)
+        .await
+        .map_err(thread_history_delete_error)?;
+    sqlx::query("DELETE FROM thread_turns WHERE thread_id = ?")
+        .bind(thread_id.as_str())
+        .execute(&mut *transaction)
+        .await
+        .map_err(thread_history_delete_error)?;
+    sqlx::query("DELETE FROM thread_history_projection_state WHERE thread_id = ?")
+        .bind(thread_id.as_str())
+        .execute(&mut *transaction)
+        .await
+        .map_err(thread_history_delete_error)?;
+    transaction
+        .commit()
+        .await
+        .map_err(thread_history_delete_error)
+}
+
+async fn apply_change_set(
+    transaction: &mut sqlx::Transaction<'_, sqlx::Sqlite>,
+    thread_id: &str,
+    rollout_ordinal: i64,
+    rollout_byte_offset: i64,
+    rollout_end_byte_offset: i64,
+    fallback_created_at_ms: Option<i64>,
+    changes: ThreadHistoryChangeSet,
+) -> ThreadStoreResult<()> {
+    for turn in changes.changed_turns {
+        let turn_id = turn.turn_id;
+        let error_json = turn
+            .error
+            .as_ref()
+            .map(serde_json::to_string)
+            .transpose()
+            .map_err(thread_history_error)?;
+        let (terminal_ordinal, terminal_byte_offset) = match &turn.status {
+            TurnStatus::Completed | TurnStatus::Interrupted | TurnStatus::Failed => {
+                (Some(rollout_ordinal), Some(rollout_end_byte_offset))
+            }
+            TurnStatus::InProgress => (None, None),
+        };
+        // The same turn can appear again as it moves from started to completed. Update its latest
+        // status, error, and timestamps, but keep the rollout ordinal from the first record that
+        // created it.
+        sqlx::query(
+            r#"
+INSERT INTO thread_turns (
+    thread_id,
+    turn_id,
+    rollout_ordinal,
+    rollout_byte_offset,
+    rollout_end_ordinal,
+    rollout_end_byte_offset,
+    status,
+    error_json,
+    started_at,
+    completed_at,
+    duration_ms
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(thread_id, turn_id) DO UPDATE SET
+    rollout_end_ordinal = excluded.rollout_end_ordinal,
+    rollout_end_byte_offset = excluded.rollout_end_byte_offset,
+    status = excluded.status,
+    error_json = excluded.error_json,
+    started_at = excluded.started_at,
+    completed_at = excluded.completed_at,
+    duration_ms = excluded.duration_ms
+WHERE thread_turns.rollout_end_ordinal IS NULL
+  AND thread_turns.status = 'inProgress'
+            "#,
+        )
+        .bind(thread_id)
+        .bind(turn_id.as_str())
+        .bind(rollout_ordinal)
+        .bind(rollout_byte_offset)
+        .bind(terminal_ordinal)
+        .bind(terminal_byte_offset)
+        .bind(turn_status(&turn.status))
+        .bind(error_json)
+        .bind(turn.started_at)
+        .bind(turn.completed_at)
+        .bind(turn.duration_ms)
+        .execute(&mut **transaction)
+        .await
+        .map_err(thread_history_error)?;
+
+        // Review turns can persist completed items before their turn lifecycle record. Fill the
+        // summary IDs from those older item rows when the turn row finally arrives.
+        sqlx::query(
+            r#"
+UPDATE thread_turns
+SET
+    first_user_item_id = COALESCE(
+        first_user_item_id,
+        (
+            SELECT item_id
+            FROM thread_items
+            WHERE thread_id = ?
+              AND turn_id = ?
+              AND (
+                item_type = 'userMessage'
+                OR (item_type = '' AND json_extract(item_json, '$.type') = 'userMessage')
+              )
+            ORDER BY rollout_ordinal
+            LIMIT 1
+        )
+    ),
+    final_agent_item_id = COALESCE(
+        (
+            SELECT item_id
+            FROM thread_items
+            WHERE thread_id = ?
+              AND turn_id = ?
+              AND (
+                item_type = 'agentMessage'
+                OR (item_type = '' AND json_extract(item_json, '$.type') = 'agentMessage')
+              )
+              AND json_extract(item_json, '$.phase') = 'final_answer'
+            ORDER BY rollout_ordinal DESC
+            LIMIT 1
+        ),
+        CASE
+            WHEN status IN ('completed', 'interrupted', 'failed') THEN (
+                SELECT item_id
+                FROM thread_items
+                WHERE thread_id = ?
+                  AND turn_id = ?
+                  AND (
+                    item_type = 'agentMessage'
+                    OR (item_type = '' AND json_extract(item_json, '$.type') = 'agentMessage')
+                  )
+                  AND json_extract(item_json, '$.phase') IS NULL
+                ORDER BY rollout_ordinal DESC
+                LIMIT 1
+            )
+        END,
+        final_agent_item_id
+    )
+WHERE thread_id = ?
+  AND turn_id = ?
+  AND (
+    rollout_end_ordinal = ?
+    OR status = 'inProgress'
+  )
+            "#,
+        )
+        .bind(thread_id)
+        .bind(turn_id.as_str())
+        .bind(thread_id)
+        .bind(turn_id.as_str())
+        .bind(thread_id)
+        .bind(turn_id.as_str())
+        .bind(thread_id)
+        .bind(turn_id.as_str())
+        .bind(rollout_ordinal)
+        .execute(&mut **transaction)
+        .await
+        .map_err(thread_history_error)?;
+    }
+
+    for item in changes.changed_items {
+        let created_at_ms =
+            item.started_at_ms
+                .or(fallback_created_at_ms)
+                .ok_or_else(|| ThreadStoreError::Internal {
+                    message: format!(
+                        "thread history projection for {thread_id} is missing an item creation timestamp"
+                    ),
+                })?;
+        let item_id = item.item.id().to_string();
+        let item_json = serde_json::to_string(&item.item).map_err(thread_history_error)?;
+        // Completed items are immutable: local producers emit ItemCompleted exactly once per
+        // item. Tolerate an unexpected duplicate defensively so it cannot poison materialization,
+        // preserving the original creation ordinal and timestamp while updating its snapshot.
+        sqlx::query(
+            r#"
+INSERT INTO thread_items (
+    thread_id,
+    turn_id,
+    item_id,
+    rollout_ordinal,
+    updated_at_ordinal,
+    created_at_ms,
+    item_type,
+    item_json
+) VALUES (?, ?, ?, ?, ?, ?, json_extract(?, '$.type'), ?)
+ON CONFLICT(thread_id, turn_id, item_id) DO UPDATE SET
+    updated_at_ordinal = excluded.updated_at_ordinal,
+    item_type = excluded.item_type,
+    item_json = excluded.item_json
+            "#,
+        )
+        .bind(thread_id)
+        .bind(item.turn_id.as_str())
+        .bind(item_id.as_str())
+        .bind(rollout_ordinal)
+        .bind(rollout_ordinal)
+        .bind(created_at_ms)
+        .bind(item_json.as_str())
+        .bind(item_json)
+        .execute(&mut **transaction)
+        .await
+        .map_err(thread_history_error)?;
+
+        // Keep summary item IDs on the turn row so reads do not need to scan every item in the
+        // turn.
+        match item.item {
+            ThreadItem::UserMessage { .. } => {
+                sqlx::query(
+                    r#"
+UPDATE thread_turns
+SET first_user_item_id = COALESCE(first_user_item_id, ?)
+WHERE thread_id = ?
+  AND turn_id = ?
+  AND rollout_end_ordinal IS NULL
+  AND status = 'inProgress'
+                    "#,
+                )
+                .bind(item_id.as_str())
+                .bind(thread_id)
+                .bind(item.turn_id.as_str())
+                .execute(&mut **transaction)
+                .await
+                .map_err(thread_history_error)?;
+            }
+            ThreadItem::AgentMessage {
+                phase: Some(MessagePhase::FinalAnswer),
+                ..
+            } => {
+                sqlx::query(
+                    r#"
+UPDATE thread_turns
+SET final_agent_item_id = ?
+WHERE thread_id = ?
+  AND turn_id = ?
+  AND rollout_end_ordinal IS NULL
+  AND status = 'inProgress'
+                    "#,
+                )
+                .bind(item_id.as_str())
+                .bind(thread_id)
+                .bind(item.turn_id.as_str())
+                .execute(&mut **transaction)
+                .await
+                .map_err(thread_history_error)?;
+            }
+            ThreadItem::AgentMessage {
+                phase: Some(MessagePhase::Commentary) | None,
+                ..
+            }
+            | ThreadItem::HookPrompt { .. }
+            | ThreadItem::FunctionCallOutput { .. }
+            | ThreadItem::Plan { .. }
+            | ThreadItem::Reasoning { .. }
+            | ThreadItem::CommandExecution { .. }
+            | ThreadItem::FileChange { .. }
+            | ThreadItem::McpToolCall { .. }
+            | ThreadItem::DynamicToolCall { .. }
+            | ThreadItem::CollabAgentToolCall { .. }
+            | ThreadItem::SubAgentActivity { .. }
+            | ThreadItem::WebSearch(_)
+            | ThreadItem::ImageView { .. }
+            | ThreadItem::Sleep(_)
+            | ThreadItem::ImageGeneration(_)
+            | ThreadItem::EnteredReviewMode { .. }
+            | ThreadItem::ExitedReviewMode { .. }
+            | ThreadItem::ContextCompaction { .. } => {}
+        }
+    }
+    Ok(())
+}
+
+fn turn_status(status: &TurnStatus) -> &'static str {
+    match status {
+        TurnStatus::Completed => "completed",
+        TurnStatus::Interrupted => "interrupted",
+        TurnStatus::Failed => "failed",
+        TurnStatus::InProgress => "inProgress",
+    }
+}
+
+fn sqlite_integer(value: u64, field: &str) -> ThreadStoreResult<i64> {
+    i64::try_from(value).map_err(|_| ThreadStoreError::Internal {
+        message: format!("{field} exceeds SQLite integer range"),
+    })
+}
+
+fn thread_history_error(err: impl std::fmt::Display) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: format!("failed to access thread history: {err}"),
+    }
+}
+
+impl From<sqlx::Error> for ThreadStoreError {
+    fn from(err: sqlx::Error) -> Self {
+        thread_history_error(err)
+    }
+}
+
+fn thread_history_delete_error(err: impl std::fmt::Display) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: format!("failed to delete thread history: {err}"),
+    }
+}
diff --git a/codex-rs/thread-store/src/local/thread_history/read.rs b/codex-rs/thread-store/src/local/thread_history/read.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b2e3e6713ba93e7f37967a34ec3bd7e1b2a29f63
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history/read.rs
@@ -0,0 +1,418 @@
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use serde::Deserialize;
+use serde::Serialize;
+use sqlx::Row;
+
+use super::super::LocalThreadStore;
+use super::super::rollout_lineage::RolloutLineage;
+use super::segment_paging::page_item_rows;
+use super::segment_paging::page_turn_rows;
+use super::segment_paging::validate_page_size;
+use super::sqlite_integer;
+use super::turn_lookup::find_source_turn;
+use crate::ItemPage;
+use crate::ListItemsParams;
+use crate::ListTurnsParams;
+use crate::StoredThreadItem;
+use crate::StoredTurn;
+use crate::StoredTurnError;
+use crate::StoredTurnItemsView;
+use crate::StoredTurnStatus;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::TurnPage;
+
+#[cfg(test)]
+#[path = "read_tests.rs"]
+mod tests;
+
+#[derive(Clone, Deserialize, PartialEq, Eq, Serialize)]
+#[serde(tag = "kind", rename_all = "camelCase")]
+pub(super) enum CursorScope {
+    Turns,
+    ItemsByCreatedAtOrdinal,
+    ItemsByUpdatedAtOrdinal,
+}
+
+#[derive(Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct HistoryCursor {
+    pub requested_thread_id: ThreadId,
+    pub rollout_ordinal: u64,
+    pub include_anchor: bool,
+    pub scope: CursorScope,
+}
+
+#[derive(Clone, Copy)]
+pub(super) struct RolloutHistoryPosition {
+    pub rollout_ordinal: i64,
+}
+
+pub(super) struct StoredTurnRow {
+    pub position: RolloutHistoryPosition,
+    pub turn_id: String,
+    pub status: StoredTurnStatus,
+    pub error: Option<StoredTurnError>,
+    pub started_at: Option<i64>,
+    pub completed_at: Option<i64>,
+    pub duration_ms: Option<i64>,
+    pub first_user_item_id: Option<String>,
+    pub final_agent_item_id: Option<String>,
+    pub summary_items: Vec<StoredThreadItem>,
+}
+
+#[derive(sqlx::FromRow)]
+pub(super) struct StoredSummaryColumns {
+    summary_first_user_turn_id: Option<String>,
+    summary_first_user_item_id: Option<String>,
+    summary_first_user_rollout_ordinal: Option<i64>,
+    summary_first_user_updated_at_ordinal: Option<i64>,
+    summary_first_user_created_at_ms: Option<i64>,
+    summary_first_user_item_json: Option<String>,
+    summary_final_agent_turn_id: Option<String>,
+    summary_final_agent_item_id: Option<String>,
+    summary_final_agent_rollout_ordinal: Option<i64>,
+    summary_final_agent_updated_at_ordinal: Option<i64>,
+    summary_final_agent_created_at_ms: Option<i64>,
+    summary_final_agent_item_json: Option<String>,
+}
+
+struct StoredSummaryItemColumns {
+    turn_id: Option<String>,
+    item_id: Option<String>,
+    rollout_ordinal: Option<i64>,
+    updated_at_ordinal: Option<i64>,
+    created_at_ms: Option<i64>,
+    item_json: Option<String>,
+}
+
+pub(super) struct StoredThreadItemRow {
+    pub position: RolloutHistoryPosition,
+    pub item: StoredThreadItem,
+}
+
+pub(in crate::local) async fn list_turns(
+    store: &LocalThreadStore,
+    params: ListTurnsParams,
+) -> ThreadStoreResult<TurnPage> {
+    validate_thread_for_paginated_reads(
+        store,
+        params.thread_id,
+        params.include_archived,
+        "list_turns",
+    )
+    .await?;
+    validate_page_size(params.page_size)?;
+    let lineage = store.resolve_rollout_lineage(params.thread_id).await?;
+    let pool = store.thread_history_db().await?;
+    let page = page_turn_rows(
+        pool,
+        params.thread_id,
+        &lineage,
+        params.cursor.as_deref(),
+        params.page_size,
+        params.sort_direction,
+        params.items_view,
+    )
+    .await?;
+    let mut turns = Vec::with_capacity(page.rows.len());
+    for turn in page.rows {
+        let items = match params.items_view {
+            StoredTurnItemsView::NotLoaded => Vec::new(),
+            StoredTurnItemsView::Summary
+                if matches!(turn.status, StoredTurnStatus::Interrupted)
+                    && turn.first_user_item_id.is_none()
+                    && turn.final_agent_item_id.is_none() =>
+            {
+                // Synthetic fork-boundary rows are interrupted without local summary IDs.
+                // Load their summary from the earliest visible source turn.
+                load_inherited_summary_items(pool, &lineage, &turn).await?
+            }
+            StoredTurnItemsView::Summary => turn.summary_items,
+        };
+        turns.push(StoredTurn {
+            turn_id: turn.turn_id,
+            items,
+            items_view: params.items_view,
+            status: turn.status,
+            error: turn.error,
+            started_at: turn.started_at,
+            completed_at: turn.completed_at,
+            duration_ms: turn.duration_ms,
+        });
+    }
+
+    Ok(TurnPage {
+        turns,
+        next_cursor: page.next_cursor,
+        backwards_cursor: page.backwards_cursor,
+    })
+}
+
+pub(in crate::local) async fn list_items(
+    store: &LocalThreadStore,
+    params: ListItemsParams,
+) -> ThreadStoreResult<ItemPage> {
+    validate_thread_for_paginated_reads(
+        store,
+        params.thread_id,
+        params.include_archived,
+        "list_items",
+    )
+    .await?;
+    validate_page_size(params.page_size)?;
+    let lineage = store.resolve_rollout_lineage(params.thread_id).await?;
+    let pool = store.thread_history_db().await?;
+    let page = page_item_rows(pool, &lineage, &params).await?;
+
+    Ok(ItemPage {
+        items: page.rows.into_iter().map(|row| row.item).collect(),
+        next_cursor: page.next_cursor,
+        backwards_cursor: page.backwards_cursor,
+    })
+}
+
+pub(super) async fn validate_thread_for_paginated_reads(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    include_archived: bool,
+    operation: &'static str,
+) -> ThreadStoreResult<()> {
+    let Some(state_db) = store.state_db().await else {
+        return Err(ThreadStoreError::Unsupported { operation });
+    };
+    let Some(metadata) =
+        state_db
+            .get_thread(thread_id)
+            .await
+            .map_err(|err| ThreadStoreError::Internal {
+                message: format!("failed to read thread metadata: {err}"),
+            })?
+    else {
+        return Err(ThreadStoreError::Unsupported { operation });
+    };
+    if metadata.archived_at.is_some() && !include_archived {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: format!("thread {thread_id} is archived"),
+        });
+    }
+    match metadata.history_mode {
+        ThreadHistoryMode::Legacy => Err(ThreadStoreError::Unsupported { operation }),
+        ThreadHistoryMode::Paginated => Ok(()),
+    }
+}
+
+async fn load_inherited_summary_items(
+    pool: &sqlx::SqlitePool,
+    lineage: &RolloutLineage,
+    turn: &StoredTurnRow,
+) -> ThreadStoreResult<Vec<StoredThreadItem>> {
+    let source = find_source_turn(pool, lineage, turn.turn_id.as_str()).await?;
+    let Some(segment) = lineage
+        .segments()
+        .iter()
+        .find(|segment| segment.rollout_id() == source.rollout_id)
+    else {
+        return Ok(Vec::new());
+    };
+    let start_ordinal = sqlite_integer(segment.start_ordinal(), "rollout ordinal")?;
+    let end_ordinal = segment
+        .end_ordinal()
+        .map(|ordinal| sqlite_integer(ordinal, "rollout ordinal"))
+        .transpose()?;
+    let rows = sqlx::query(
+        r#"
+SELECT turn_id, item_id, updated_at_ordinal, created_at_ms, item_json
+FROM thread_items
+WHERE thread_id = ?
+  AND turn_id = ?
+  AND rollout_ordinal >= ?
+  AND (? IS NULL OR rollout_ordinal < ?)
+  AND (item_id = ? OR item_id = ?)
+ORDER BY rollout_ordinal ASC
+        "#,
+    )
+    .bind(source.rollout_id.to_string())
+    .bind(turn.turn_id.as_str())
+    .bind(start_ordinal)
+    .bind(end_ordinal)
+    .bind(end_ordinal)
+    .bind(source.first_user_item_id)
+    .bind(source.final_agent_item_id)
+    .fetch_all(pool)
+    .await
+    .map_err(super::thread_history_error)?;
+    rows.into_iter().map(stored_thread_item).collect()
+}
+
+pub(super) fn parse_cursor(
+    cursor: Option<&str>,
+    requested_thread_id: ThreadId,
+    scope: CursorScope,
+) -> ThreadStoreResult<Option<HistoryCursor>> {
+    let Some(cursor) = cursor else {
+        return Ok(None);
+    };
+    let cursor_value: HistoryCursor =
+        serde_json::from_str(cursor).map_err(|_| invalid_cursor(cursor))?;
+    if cursor_value.requested_thread_id != requested_thread_id || cursor_value.scope != scope {
+        return Err(invalid_cursor(cursor));
+    }
+    Ok(Some(cursor_value))
+}
+
+pub(super) fn serialize_cursor(
+    requested_thread_id: ThreadId,
+    scope: CursorScope,
+    rollout_ordinal: i64,
+    include_anchor: bool,
+) -> ThreadStoreResult<String> {
+    let rollout_ordinal =
+        u64::try_from(rollout_ordinal).map_err(|_| invalid_cursor("negative rollout ordinal"))?;
+    serde_json::to_string(&HistoryCursor {
+        requested_thread_id,
+        rollout_ordinal,
+        include_anchor,
+        scope,
+    })
+    .map_err(super::thread_history_error)
+}
+
+pub(super) fn stored_turn_row(row: sqlx::sqlite::SqliteRow) -> ThreadStoreResult<StoredTurnRow> {
+    let status = match row.try_get::<String, _>("status")?.as_str() {
+        "completed" => StoredTurnStatus::Completed,
+        "interrupted" => StoredTurnStatus::Interrupted,
+        "failed" => StoredTurnStatus::Failed,
+        "inProgress" => StoredTurnStatus::InProgress,
+        status => {
+            return Err(ThreadStoreError::Internal {
+                message: format!("unknown stored turn status: {status}"),
+            });
+        }
+    };
+    let error_json = row.try_get::<Option<String>, _>("error_json")?;
+    let error = error_json
+        .as_deref()
+        .map(serde_json::from_str)
+        .transpose()
+        .map_err(super::thread_history_error)?;
+    Ok(StoredTurnRow {
+        position: RolloutHistoryPosition {
+            rollout_ordinal: row.try_get("rollout_ordinal")?,
+        },
+        turn_id: row.try_get("turn_id")?,
+        status,
+        error,
+        started_at: row.try_get("started_at")?,
+        completed_at: row.try_get("completed_at")?,
+        duration_ms: row.try_get("duration_ms")?,
+        first_user_item_id: row.try_get("first_user_item_id")?,
+        final_agent_item_id: row.try_get("final_agent_item_id")?,
+        summary_items: Vec::new(),
+    })
+}
+
+impl StoredSummaryColumns {
+    pub(super) fn into_stored_items(self) -> ThreadStoreResult<Vec<StoredThreadItem>> {
+        let mut summary_items = [
+            StoredSummaryItemColumns {
+                turn_id: self.summary_first_user_turn_id,
+                item_id: self.summary_first_user_item_id,
+                rollout_ordinal: self.summary_first_user_rollout_ordinal,
+                updated_at_ordinal: self.summary_first_user_updated_at_ordinal,
+                created_at_ms: self.summary_first_user_created_at_ms,
+                item_json: self.summary_first_user_item_json,
+            }
+            .into_stored_item()?,
+            StoredSummaryItemColumns {
+                turn_id: self.summary_final_agent_turn_id,
+                item_id: self.summary_final_agent_item_id,
+                rollout_ordinal: self.summary_final_agent_rollout_ordinal,
+                updated_at_ordinal: self.summary_final_agent_updated_at_ordinal,
+                created_at_ms: self.summary_final_agent_created_at_ms,
+                item_json: self.summary_final_agent_item_json,
+            }
+            .into_stored_item()?,
+        ]
+        .into_iter()
+        .flatten()
+        .collect::<Vec<_>>();
+        summary_items.sort_by_key(|(rollout_ordinal, _)| *rollout_ordinal);
+        Ok(summary_items.into_iter().map(|(_, item)| item).collect())
+    }
+}
+
+impl StoredSummaryItemColumns {
+    fn into_stored_item(self) -> ThreadStoreResult<Option<(i64, StoredThreadItem)>> {
+        let Some(item_id) = self.item_id else {
+            return Ok(None);
+        };
+        let (
+            Some(turn_id),
+            Some(rollout_ordinal),
+            Some(updated_at_ordinal),
+            Some(created_at_ms),
+            Some(item_json),
+        ) = (
+            self.turn_id,
+            self.rollout_ordinal,
+            self.updated_at_ordinal,
+            self.created_at_ms,
+            self.item_json,
+        )
+        else {
+            return Err(ThreadStoreError::Internal {
+                message: "stored summary item is missing joined columns".to_string(),
+            });
+        };
+        Ok(Some((
+            rollout_ordinal,
+            StoredThreadItem {
+                turn_id,
+                item_id,
+                updated_at_ordinal: stored_updated_at_ordinal(updated_at_ordinal)?,
+                created_at_ms,
+                item_json: item_json.into_bytes(),
+            },
+        )))
+    }
+}
+
+pub(super) fn stored_thread_item_row(
+    row: sqlx::sqlite::SqliteRow,
+) -> ThreadStoreResult<StoredThreadItemRow> {
+    let rollout_ordinal = row.try_get::<i64, _>("rollout_ordinal")?;
+    if rollout_ordinal < 0 {
+        return Err(ThreadStoreError::Internal {
+            message: format!("invalid stored item rollout ordinal: {rollout_ordinal}"),
+        });
+    }
+    Ok(StoredThreadItemRow {
+        position: RolloutHistoryPosition { rollout_ordinal },
+        item: stored_thread_item(row)?,
+    })
+}
+
+fn stored_thread_item(row: sqlx::sqlite::SqliteRow) -> ThreadStoreResult<StoredThreadItem> {
+    let updated_at_ordinal = stored_updated_at_ordinal(row.try_get("updated_at_ordinal")?)?;
+    Ok(StoredThreadItem {
+        turn_id: row.try_get("turn_id")?,
+        item_id: row.try_get("item_id")?,
+        updated_at_ordinal,
+        created_at_ms: row.try_get("created_at_ms")?,
+        item_json: row.try_get::<String, _>("item_json")?.into_bytes(),
+    })
+}
+
+fn stored_updated_at_ordinal(updated_at_ordinal: i64) -> ThreadStoreResult<u64> {
+    u64::try_from(updated_at_ordinal).map_err(|_| ThreadStoreError::Internal {
+        message: format!("invalid stored item updated-at ordinal: {updated_at_ordinal}"),
+    })
+}
+
+pub(super) fn invalid_cursor(cursor: &str) -> ThreadStoreError {
+    ThreadStoreError::InvalidRequest {
+        message: format!("invalid cursor: {cursor}"),
+    }
+}
diff --git a/codex-rs/thread-store/src/local/thread_history/read_tests.rs b/codex-rs/thread-store/src/local/thread_history/read_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..06eaaca7035aba9352dfd5f5126c758015c4ad45
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history/read_tests.rs
@@ -0,0 +1,1561 @@
+use std::fs;
+use std::time::Duration;
+
+use chrono::Utc;
+use codex_app_server_protocol::CodexErrorInfo;
+use codex_app_server_protocol::ThreadTimelineEntry;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::SessionMeta;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::realtime::BemItemPresentation;
+use codex_protocol::realtime::RealtimeItem;
+use codex_protocol::realtime::RealtimeItemContent;
+use codex_protocol::realtime::RealtimeSessionOutcome;
+use codex_protocol::realtime::RealtimeTranscriptRole;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::*;
+use crate::ItemSortKey;
+use crate::ListTimelineParams;
+use crate::SearchThreadOccurrencesParams;
+use crate::SortDirection;
+use crate::StoredTurnError;
+use crate::StoredTurnStatus;
+use crate::local::test_support::test_config;
+
+#[tokio::test]
+async fn list_turns_pages_projected_rows_and_applies_item_views() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let db = history_db(&store).await;
+    for (turn_id, ordinal, status, error, first_user, final_agent) in [
+        (
+            "turn-1",
+            10,
+            "completed",
+            None,
+            Some("user-1"),
+            Some("agent-1"),
+        ),
+        (
+            "turn-2",
+            20,
+            "failed",
+            Some(
+                r#"{"message":"turn failed","codexErrorInfo":"serverOverloaded","additionalDetails":"retry later"}"#,
+            ),
+            None,
+            None,
+        ),
+        ("turn-3", 30, "inProgress", None, None, None),
+    ] {
+        insert_turn(
+            db,
+            thread_id,
+            turn_id,
+            ordinal,
+            status,
+            error,
+            first_user,
+            final_agent,
+        )
+        .await;
+    }
+    for (turn_id, item_id, ordinal) in [
+        ("turn-1", "user-1", 11),
+        ("turn-1", "middle-1", 12),
+        ("turn-1", "agent-1", 13),
+    ] {
+        insert_item(db, thread_id, turn_id, item_id, ordinal).await;
+    }
+
+    let first_page = store
+        .list_turns(turn_params(
+            thread_id,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+            StoredTurnItemsView::Summary,
+        ))
+        .await
+        .expect("first turns page");
+    assert_eq!(turn_ids(&first_page), vec!["turn-1", "turn-2"]);
+    assert_eq!(
+        first_page.turns[0].items,
+        vec![
+            expected_item("turn-1", "user-1", /*rollout_ordinal*/ 11),
+            expected_item("turn-1", "agent-1", /*rollout_ordinal*/ 13),
+        ]
+    );
+    assert_eq!(
+        first_page.turns[1].error,
+        Some(StoredTurnError {
+            message: "turn failed".to_string(),
+            codex_error_info: Some(CodexErrorInfo::ServerOverloaded),
+            additional_details: Some("retry later".to_string()),
+        })
+    );
+    let second_page = store
+        .list_turns(turn_params(
+            thread_id,
+            first_page.next_cursor,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("second turns page");
+    assert_eq!(turn_ids(&second_page), vec!["turn-3"]);
+    assert_eq!(second_page.turns[0].items, Vec::new());
+    assert_eq!(second_page.turns[0].status, StoredTurnStatus::InProgress);
+    let backwards_page = store
+        .list_turns(turn_params(
+            thread_id,
+            second_page.backwards_cursor,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("backwards turns page");
+    assert_eq!(turn_ids(&backwards_page), vec!["turn-3", "turn-2"]);
+}
+
+#[tokio::test]
+async fn list_items_pages_whole_thread_and_per_turn_rows() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let db = history_db(&store).await;
+    for (turn_id, ordinal) in [("turn-1", 10), ("turn-2", 20)] {
+        insert_turn(
+            db,
+            thread_id,
+            turn_id,
+            ordinal,
+            "completed",
+            /*error_json*/ None,
+            /*first_user_item_id*/ None,
+            /*final_agent_item_id*/ None,
+        )
+        .await;
+    }
+    for (turn_id, item_id, ordinal) in [
+        ("turn-1", "item-1", 11),
+        ("turn-1", "item-2", 12),
+        ("turn-2", "item-3", 21),
+        ("turn-2", "item-4", 22),
+        ("turn-2", "item-5", 23),
+    ] {
+        insert_item(db, thread_id, turn_id, item_id, ordinal).await;
+    }
+
+    let first_page = store
+        .list_items(item_params(
+            thread_id,
+            /*turn_id*/ None,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("first item page");
+    assert_eq!(
+        first_page.items,
+        vec![
+            expected_item("turn-1", "item-1", /*rollout_ordinal*/ 11),
+            expected_item("turn-1", "item-2", /*rollout_ordinal*/ 12),
+        ]
+    );
+    let second_page = store
+        .list_items(item_params(
+            thread_id,
+            /*turn_id*/ None,
+            first_page.next_cursor,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("second item page");
+    assert_eq!(item_ids(&second_page), vec!["item-3", "item-4"]);
+    let backwards_page = store
+        .list_items(item_params(
+            thread_id,
+            /*turn_id*/ None,
+            second_page.backwards_cursor,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+        ))
+        .await
+        .expect("backwards item page");
+    assert_eq!(item_ids(&backwards_page), vec!["item-3", "item-2"]);
+
+    let turn_page = store
+        .list_items(item_params(
+            thread_id,
+            Some("turn-2"),
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+        ))
+        .await
+        .expect("turn item page");
+    assert_eq!(item_ids(&turn_page), vec!["item-5", "item-4"]);
+    let whole_thread_from_turn_cursor = store
+        .list_items(item_params(
+            thread_id,
+            /*turn_id*/ None,
+            turn_page.backwards_cursor.clone(),
+            /*page_size*/ 2,
+            SortDirection::Desc,
+        ))
+        .await
+        .expect("whole-thread page from turn cursor");
+    assert_eq!(
+        item_ids(&whole_thread_from_turn_cursor),
+        vec!["item-5", "item-4"]
+    );
+    let next_turn_page = store
+        .list_items(item_params(
+            thread_id,
+            Some("turn-2"),
+            turn_page.next_cursor,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+        ))
+        .await
+        .expect("next turn item page");
+    assert_eq!(item_ids(&next_turn_page), vec!["item-3"]);
+}
+
+#[tokio::test]
+async fn timeline_interleaves_items_and_restores_page_boundary_session_state() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let db = history_db(&store).await;
+    for (item_id, ordinal) in [
+        ("before", 10),
+        ("middle", 20),
+        ("after", 30),
+        ("closed", 40),
+    ] {
+        insert_item(db, thread_id, "turn-1", item_id, ordinal).await;
+    }
+    for (ordinal, item) in [
+        (
+            11,
+            RealtimeItem {
+                id: "voice-1:started".to_string(),
+                realtime_session_id: "voice-1".to_string(),
+                content: RealtimeItemContent::RealtimeSessionStarted,
+            },
+        ),
+        (
+            12,
+            RealtimeItem {
+                id: "voice-1:source:0".to_string(),
+                realtime_session_id: "voice-1".to_string(),
+                content: RealtimeItemContent::TranscriptSegment {
+                    role: RealtimeTranscriptRole::Assistant,
+                    text: "Before the artifact".to_string(),
+                },
+            },
+        ),
+        (
+            21,
+            RealtimeItem {
+                id: "artifact".to_string(),
+                realtime_session_id: "voice-1".to_string(),
+                content: RealtimeItemContent::BemItemPromoted {
+                    turn_id: "turn-1".to_string(),
+                    item_id: "middle".to_string(),
+                    presentation: BemItemPresentation::InlineMarkdown,
+                },
+            },
+        ),
+        (
+            31,
+            RealtimeItem {
+                id: "voice-1:closed".to_string(),
+                realtime_session_id: "voice-1".to_string(),
+                content: RealtimeItemContent::RealtimeSessionClosed {
+                    outcome: RealtimeSessionOutcome::Ended,
+                },
+            },
+        ),
+    ] {
+        let item_json = serde_json::to_string(&item).expect("serialize realtime item");
+        sqlx::query(
+            r#"
+INSERT INTO thread_realtime_items (
+    thread_id, item_id, rollout_ordinal, created_at_ms, item_type, item_json
+) VALUES (?, ?, ?, ?, json_extract(?, '$.type'), ?)
+            "#,
+        )
+        .bind(thread_id.to_string())
+        .bind(&item.id)
+        .bind(ordinal)
+        .bind(ordinal * 1_000)
+        .bind(&item_json)
+        .bind(&item_json)
+        .execute(db)
+        .await
+        .expect("insert realtime item");
+    }
+
+    let latest = store
+        .list_timeline(ListTimelineParams {
+            thread_id,
+            cursor: None,
+            page_size: 3,
+        })
+        .await
+        .expect("list latest timeline page");
+    assert_eq!(
+        latest
+            .items
+            .iter()
+            .map(|item| match item {
+                ThreadTimelineEntry::Item { position, .. }
+                | ThreadTimelineEntry::Realtime { position, .. }
+                | ThreadTimelineEntry::TurnStarted { position, .. }
+                | ThreadTimelineEntry::TurnCompleted { position, .. } => *position,
+            })
+            .collect::<Vec<_>>(),
+        vec![30, 31, 40]
+    );
+    assert_eq!(
+        latest.active_realtime_session_at_page_start,
+        Some("voice-1".to_string())
+    );
+    let older = store
+        .list_timeline(ListTimelineParams {
+            thread_id,
+            cursor: latest.next_cursor,
+            page_size: 3,
+        })
+        .await
+        .expect("list older timeline page");
+    assert_eq!(
+        older
+            .items
+            .iter()
+            .map(|item| match item {
+                ThreadTimelineEntry::Item { position, .. }
+                | ThreadTimelineEntry::Realtime { position, .. }
+                | ThreadTimelineEntry::TurnStarted { position, .. }
+                | ThreadTimelineEntry::TurnCompleted { position, .. } => *position,
+            })
+            .collect::<Vec<_>>(),
+        vec![12, 20, 21]
+    );
+    assert_eq!(
+        older.active_realtime_session_at_page_start,
+        Some("voice-1".to_string())
+    );
+    let oldest = store
+        .list_timeline(ListTimelineParams {
+            thread_id,
+            cursor: older.next_cursor,
+            page_size: 3,
+        })
+        .await
+        .expect("list oldest timeline page");
+    assert_eq!(oldest.active_realtime_session_at_page_start, None);
+    assert!(matches!(
+        oldest.items.as_slice(),
+        [
+            ThreadTimelineEntry::Item { position: 10, .. },
+            ThreadTimelineEntry::Realtime { position: 11, .. }
+        ]
+    ));
+
+    let ordinary_items = store
+        .list_items(item_params(
+            thread_id,
+            /*turn_id*/ None,
+            /*cursor*/ None,
+            /*page_size*/ 10,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("existing item API excludes realtime facts");
+    assert_eq!(
+        item_ids(&ordinary_items),
+        vec!["before", "middle", "after", "closed"]
+    );
+}
+
+#[tokio::test]
+async fn timeline_turn_boundaries_page_through_shared_ordinals() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let db = history_db(&store).await;
+    let error = r#"{"message":"failed","codexErrorInfo":null,"additionalDetails":null}"#;
+    for (turn_id, start, end, status, error_json) in [
+        ("complete", 10, Some(20), "completed", None),
+        ("interrupt", 20, Some(30), "interrupted", None),
+        ("failed", 30, Some(40), "failed", Some(error)),
+        ("running", 40, None, "inProgress", None),
+    ] {
+        insert_turn(
+            db, thread_id, turn_id, start, status, error_json, /*first_user_item_id*/ None,
+            /*final_agent_item_id*/ None,
+        )
+        .await;
+        sqlx::query("UPDATE thread_turns SET rollout_end_ordinal = ?, started_at = ?, completed_at = ?, duration_ms = ? WHERE thread_id = ? AND turn_id = ?")
+            .bind(end)
+            .bind(start)
+            .bind(end)
+            .bind(end.map(|end| (end - start) * 1000))
+            .bind(thread_id.to_string())
+            .bind(turn_id)
+            .execute(db)
+            .await
+            .expect("set turn boundary");
+    }
+    insert_item(
+        db, thread_id, "complete", "item", /*rollout_ordinal*/ 20,
+    )
+    .await;
+
+    let all = store
+        .list_timeline(ListTimelineParams {
+            thread_id,
+            cursor: None,
+            page_size: 20,
+        })
+        .await
+        .expect("full timeline");
+    let mut cursor = None;
+    let mut paged = Vec::new();
+    loop {
+        let page = store
+            .list_timeline(ListTimelineParams {
+                thread_id,
+                cursor,
+                page_size: 1,
+            })
+            .await
+            .expect("single-entry timeline page");
+        assert_eq!(page.items.len(), 1);
+        paged.extend(page.items);
+        cursor = page.next_cursor;
+        if cursor.is_none() {
+            break;
+        }
+    }
+    paged.reverse();
+    assert_eq!(paged, all.items);
+    assert_eq!(
+        all.items
+            .iter()
+            .map(crate::local::thread_history::realtime::entry_key)
+            .collect::<Vec<_>>(),
+        vec![
+            (10, 0, "complete"),
+            (20, 0, "interrupt"),
+            (20, 1, "item"),
+            (20, 3, "complete"),
+            (30, 0, "failed"),
+            (30, 3, "interrupt"),
+            (40, 0, "running"),
+            (40, 3, "failed")
+        ]
+    );
+    let completed = all
+        .items
+        .into_iter()
+        .filter(|entry| matches!(entry, ThreadTimelineEntry::TurnCompleted { .. }))
+        .collect::<Vec<_>>();
+    let expected = [
+        ("complete", 10, 20, "completed", serde_json::Value::Null),
+        ("interrupt", 20, 30, "interrupted", serde_json::Value::Null),
+        (
+            "failed",
+            30,
+            40,
+            "failed",
+            serde_json::from_str(error).expect("error"),
+        ),
+    ]
+    .into_iter()
+    .map(|(id, start, end, status, error)| {
+        serde_json::from_value(
+            serde_json::json!({"type":"turnCompleted", "position":end, "turnId":id,
+                "status":status, "error":error, "startedAt":start, "completedAt":end,
+                "durationMs":10000}),
+        )
+        .expect("expected boundary")
+    })
+    .collect::<Vec<ThreadTimelineEntry>>();
+    assert_eq!(completed, expected);
+}
+
+#[tokio::test]
+async fn timeline_page_state_excludes_realtime_events_after_fork_cutoff() {
+    let (home, store, child_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let source_id = ThreadId::default();
+    let source_path = rollout_path(home.path(), source_id);
+    write_rollout_with_end(
+        source_path.as_path(),
+        source_id,
+        /*history_base*/ None,
+        /*next_ordinal*/ 5,
+    );
+    write_rollout_with_end(
+        rollout_path(home.path(), child_id).as_path(),
+        child_id,
+        Some(history_position(
+            source_path.as_path(),
+            source_id,
+            /*end_ordinal_exclusive*/ 3,
+        )),
+        /*next_ordinal*/ 2,
+    );
+
+    let db = history_db(&store).await;
+    insert_turn(
+        db,
+        source_id,
+        "source-turn",
+        /*rollout_ordinal*/ 1,
+        "completed",
+        /*error_json*/ None,
+        /*first_user_item_id*/ None,
+        /*final_agent_item_id*/ None,
+    )
+    .await;
+    sqlx::query("UPDATE thread_turns SET rollout_end_ordinal = 4 WHERE thread_id = ?")
+        .bind(source_id.to_string())
+        .execute(db)
+        .await
+        .expect("source turn end");
+    insert_item(
+        db,
+        child_id,
+        "child-turn",
+        "child-item",
+        /*rollout_ordinal*/ 4,
+    )
+    .await;
+    for (ordinal, item) in [
+        (
+            1,
+            RealtimeItem {
+                id: "voice:started".to_string(),
+                realtime_session_id: "voice".to_string(),
+                content: RealtimeItemContent::RealtimeSessionStarted,
+            },
+        ),
+        (
+            3,
+            RealtimeItem {
+                id: "voice:closed".to_string(),
+                realtime_session_id: "voice".to_string(),
+                content: RealtimeItemContent::RealtimeSessionClosed {
+                    outcome: RealtimeSessionOutcome::Ended,
+                },
+            },
+        ),
+    ] {
+        let item_json = serde_json::to_string(&item).expect("serialize realtime item");
+        sqlx::query(
+            r#"
+INSERT INTO thread_realtime_items (
+    thread_id, item_id, rollout_ordinal, created_at_ms, item_type, item_json
+) VALUES (?, ?, ?, ?, json_extract(?, '$.type'), ?)
+            "#,
+        )
+        .bind(source_id.to_string())
+        .bind(&item.id)
+        .bind(ordinal)
+        .bind(ordinal * 1_000)
+        .bind(&item_json)
+        .bind(&item_json)
+        .execute(db)
+        .await
+        .expect("insert realtime boundary");
+    }
+
+    let page = store
+        .list_timeline(ListTimelineParams {
+            thread_id: child_id,
+            cursor: None,
+            page_size: 1,
+        })
+        .await
+        .expect("list forked timeline page");
+
+    assert_eq!(
+        page.active_realtime_session_at_page_start,
+        Some("voice".to_string())
+    );
+    let inherited = store
+        .list_timeline(ListTimelineParams {
+            thread_id: child_id,
+            cursor: page.next_cursor,
+            page_size: 10,
+        })
+        .await
+        .expect("inherited timeline");
+    assert_eq!(
+        inherited
+            .items
+            .iter()
+            .map(crate::local::thread_history::realtime::entry_key)
+            .collect::<Vec<_>>(),
+        vec![(1, 0, "source-turn"), (1, 2, "voice:started")]
+    );
+}
+
+#[tokio::test]
+async fn list_items_filters_exclusive_update_ordinals_across_pages_and_turns() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let db = history_db(&store).await;
+    for (turn_id, item_id, ordinal) in [
+        ("turn-1", "item-1", 1),
+        ("turn-2", "item-2", 2),
+        ("turn-2", "item-3", 3),
+    ] {
+        insert_item(db, thread_id, turn_id, item_id, ordinal).await;
+    }
+    sqlx::query(
+        "UPDATE thread_items SET updated_at_ordinal = 4 WHERE thread_id = ? AND item_id = 'item-1'",
+    )
+    .bind(thread_id.to_string())
+    .execute(db)
+    .await
+    .expect("advance first item update ordinal");
+
+    let item_1 = StoredThreadItem {
+        updated_at_ordinal: 4,
+        ..expected_item("turn-1", "item-1", /*rollout_ordinal*/ 1)
+    };
+    let item_2 = expected_item("turn-2", "item-2", /*rollout_ordinal*/ 2);
+    let item_3 = expected_item("turn-2", "item-3", /*rollout_ordinal*/ 3);
+    let creation_page = store
+        .list_items(item_params(
+            thread_id,
+            /*turn_id*/ None,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("creation-ordered item page");
+    assert_eq!(creation_page.items, vec![item_1.clone(), item_2.clone()]);
+    for (sort_direction, expected) in [
+        (SortDirection::Asc, vec![item_1.clone(), item_3.clone()]),
+        (SortDirection::Desc, vec![item_3.clone(), item_1.clone()]),
+    ] {
+        let page = store
+            .list_items(ListItemsParams {
+                after_updated_at_ordinal: Some(2),
+                ..item_params(
+                    thread_id,
+                    /*turn_id*/ None,
+                    /*cursor*/ None,
+                    /*page_size*/ 2,
+                    sort_direction,
+                )
+            })
+            .await
+            .expect("creation-ordered filtered item page");
+        assert_eq!(page.items, expected);
+    }
+
+    let first_page = store
+        .list_items(updated_item_params(
+            thread_id, /*after_updated_at_ordinal*/ 0,
+        ))
+        .await
+        .expect("first filtered item page");
+    assert_eq!(first_page.items, vec![item_2.clone(), item_3.clone()]);
+    for params in [
+        ListItemsParams {
+            cursor: creation_page.next_cursor,
+            ..updated_item_params(thread_id, /*after_updated_at_ordinal*/ 0)
+        },
+        item_params(
+            thread_id,
+            /*turn_id*/ None,
+            first_page.next_cursor.clone(),
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ),
+    ] {
+        let error = store
+            .list_items(params)
+            .await
+            .expect_err("creation and update cursors should not be interchangeable");
+        assert!(matches!(error, ThreadStoreError::InvalidRequest { .. }));
+    }
+
+    let second_page = store
+        .list_items(ListItemsParams {
+            cursor: first_page.next_cursor,
+            ..updated_item_params(thread_id, /*after_updated_at_ordinal*/ 0)
+        })
+        .await
+        .expect("second filtered item page");
+    assert_eq!(second_page.items, vec![item_1.clone()]);
+    assert!(second_page.next_cursor.is_none());
+
+    let exclusive_page = store
+        .list_items(ListItemsParams {
+            turn_id: Some("turn-2".to_string()),
+            ..updated_item_params(thread_id, /*after_updated_at_ordinal*/ 2)
+        })
+        .await
+        .expect("exclusive filtered turn page");
+    assert_eq!(exclusive_page.items, vec![item_3.clone()]);
+
+    let descending_page = store
+        .list_items(ListItemsParams {
+            sort_direction: SortDirection::Desc,
+            ..updated_item_params(thread_id, /*after_updated_at_ordinal*/ 0)
+        })
+        .await
+        .expect("descending update-ordered item page");
+    assert_eq!(descending_page.items, vec![item_1, item_3]);
+    let descending_next_page = store
+        .list_items(ListItemsParams {
+            cursor: descending_page.next_cursor,
+            sort_direction: SortDirection::Desc,
+            ..updated_item_params(thread_id, /*after_updated_at_ordinal*/ 0)
+        })
+        .await
+        .expect("next descending update-ordered item page");
+    assert_eq!(descending_next_page.items, vec![item_2]);
+
+    let error = store
+        .list_items(ListItemsParams {
+            sort_key: ItemSortKey::UpdatedAtOrdinal,
+            ..item_params(
+                thread_id,
+                /*turn_id*/ None,
+                /*cursor*/ None,
+                /*page_size*/ 2,
+                SortDirection::Asc,
+            )
+        })
+        .await
+        .expect_err("update-ordinal sorting should require a watermark");
+    assert!(matches!(error, ThreadStoreError::InvalidRequest { .. }));
+}
+
+#[tokio::test]
+async fn list_items_rejects_update_ordinals_outside_sqlite_integer_range() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+
+    for sort_key in [ItemSortKey::CreatedAtOrdinal, ItemSortKey::UpdatedAtOrdinal] {
+        let error = store
+            .list_items(ListItemsParams {
+                sort_key,
+                ..updated_item_params(thread_id, /*after_updated_at_ordinal*/ u64::MAX)
+            })
+            .await
+            .expect_err("out-of-range SQLite update ordinal should fail");
+
+        assert!(matches!(error, ThreadStoreError::InvalidRequest { .. }));
+    }
+}
+
+#[tokio::test]
+async fn list_items_update_ordinals_use_selected_rollout_id() {
+    let (home, store, thread_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let rollout_id = ThreadId::new();
+    let selected_rollout_path = home.path().join(format!(
+        "sessions/2026/07/16/rollout-2026-07-16T00-00-00-{thread_id}_{rollout_id}.jsonl"
+    ));
+    write_rollout(
+        selected_rollout_path.as_path(),
+        thread_id,
+        /*history_base*/ None,
+    );
+    let state_db = store.state_db().await.expect("state runtime");
+    let mut metadata = state_db
+        .get_thread(thread_id)
+        .await
+        .expect("read metadata")
+        .expect("thread metadata");
+    metadata.rollout_path = selected_rollout_path;
+    state_db
+        .upsert_thread(&metadata)
+        .await
+        .expect("select replacement rollout");
+    insert_item(
+        history_db(&store).await,
+        rollout_id,
+        "turn-1",
+        "item-1",
+        /*rollout_ordinal*/ 1,
+    )
+    .await;
+
+    let page = store
+        .list_items(updated_item_params(
+            thread_id, /*after_updated_at_ordinal*/ 0,
+        ))
+        .await
+        .expect("update-ordered item page");
+
+    assert_eq!(
+        page.items,
+        vec![expected_item(
+            "turn-1", "item-1", /*rollout_ordinal*/ 1
+        )]
+    );
+}
+
+#[tokio::test]
+async fn list_history_keeps_legacy_threads_unsupported() {
+    let (_home, store, thread_id) = store_with_mode(ThreadHistoryMode::Legacy).await;
+
+    let error = store
+        .list_turns(turn_params(
+            thread_id,
+            /*cursor*/ None,
+            /*page_size*/ 1,
+            SortDirection::Asc,
+            StoredTurnItemsView::Summary,
+        ))
+        .await
+        .expect_err("legacy turns remain unsupported");
+    assert!(matches!(
+        error,
+        ThreadStoreError::Unsupported {
+            operation: "list_turns"
+        }
+    ));
+
+    let error = store
+        .list_turns(turn_params(
+            ThreadId::default(),
+            /*cursor*/ None,
+            /*page_size*/ 1,
+            SortDirection::Asc,
+            StoredTurnItemsView::Summary,
+        ))
+        .await
+        .expect_err("unindexed threads remain unsupported");
+    assert!(matches!(
+        error,
+        ThreadStoreError::Unsupported {
+            operation: "list_turns"
+        }
+    ));
+}
+
+#[tokio::test]
+async fn lineage_reads_page_across_parent_and_child_segments() {
+    let (home, store, child_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let root_id = ThreadId::default();
+    let root_path = rollout_path(home.path(), root_id);
+    write_rollout_with_end(
+        root_path.as_path(),
+        root_id,
+        /*history_base*/ None,
+        /*next_ordinal*/ 8,
+    );
+    write_rollout_with_end(
+        rollout_path(home.path(), child_id).as_path(),
+        child_id,
+        Some(history_position(
+            root_path.as_path(),
+            root_id,
+            /*end_ordinal_exclusive*/ 6,
+        )),
+        /*next_ordinal*/ 3,
+    );
+    let db = history_db(&store).await;
+    for (thread_id, turn_id, ordinal, first_user, final_agent) in [
+        (root_id, "root-1", 1, Some("root-user"), Some("root-agent")),
+        (root_id, "root-2", 4, None, None),
+        (root_id, "excluded-root", 6, None, None),
+        (child_id, "child-1", 7, None, None),
+    ] {
+        insert_turn(
+            db,
+            thread_id,
+            turn_id,
+            ordinal,
+            "completed",
+            /*error_json*/ None,
+            first_user,
+            final_agent,
+        )
+        .await;
+    }
+    for (thread_id, turn_id, item_id, ordinal) in [
+        (root_id, "root-1", "root-user", 2),
+        (root_id, "root-1", "root-agent", 3),
+        (root_id, "root-2", "root-2-item", 5),
+        (root_id, "excluded-root", "excluded-item", 7),
+        (child_id, "child-1", "child-item", 8),
+    ] {
+        insert_item(db, thread_id, turn_id, item_id, ordinal).await;
+    }
+
+    let first_turns = store
+        .list_turns(turn_params(
+            child_id,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+            StoredTurnItemsView::Summary,
+        ))
+        .await
+        .expect("first lineage turns page");
+    assert_eq!(turn_ids(&first_turns), vec!["root-1", "root-2"]);
+    assert_eq!(
+        first_turns.turns[0].items,
+        vec![
+            expected_item("root-1", "root-user", /*rollout_ordinal*/ 2),
+            expected_item("root-1", "root-agent", /*rollout_ordinal*/ 3),
+        ]
+    );
+    let second_turns = store
+        .list_turns(turn_params(
+            child_id,
+            first_turns.next_cursor,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("second lineage turns page");
+    assert_eq!(turn_ids(&second_turns), vec!["child-1"]);
+    let backwards_turns = store
+        .list_turns(turn_params(
+            child_id,
+            second_turns.backwards_cursor,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("backwards lineage turns page");
+    assert_eq!(turn_ids(&backwards_turns), vec!["child-1", "root-2"]);
+
+    let first_items = store
+        .list_items(item_params(
+            child_id,
+            /*turn_id*/ None,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("first lineage items page");
+    assert_eq!(item_ids(&first_items), vec!["root-user", "root-agent"]);
+    let second_items = store
+        .list_items(item_params(
+            child_id,
+            /*turn_id*/ None,
+            first_items.next_cursor,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("second lineage items page");
+    assert_eq!(item_ids(&second_items), vec!["root-2-item", "child-item"]);
+    let descending_items = store
+        .list_items(item_params(
+            child_id,
+            /*turn_id*/ None,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+        ))
+        .await
+        .expect("descending lineage items page");
+    assert_eq!(
+        item_ids(&descending_items),
+        vec!["child-item", "root-2-item"]
+    );
+    let inherited_turn_items = store
+        .list_items(item_params(
+            child_id,
+            Some("root-1"),
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect("inherited turn item page");
+    assert_eq!(
+        item_ids(&inherited_turn_items),
+        vec!["root-user", "root-agent"]
+    );
+
+    for sort_key in [ItemSortKey::CreatedAtOrdinal, ItemSortKey::UpdatedAtOrdinal] {
+        let error = store
+            .list_items(ListItemsParams {
+                sort_key,
+                ..updated_item_params(child_id, /*after_updated_at_ordinal*/ 0)
+            })
+            .await
+            .expect_err("incremental replay should reject forked lineages");
+        assert!(matches!(error, ThreadStoreError::InvalidRequest { .. }));
+    }
+
+    let first_occurrences = store
+        .search_thread_occurrences(SearchThreadOccurrencesParams {
+            thread_id: child_id,
+            search_term: "item".to_string(),
+            cursor: None,
+            page_size: 2,
+        })
+        .await
+        .expect("first inherited occurrence page");
+    assert_eq!(
+        first_occurrences
+            .items
+            .iter()
+            .map(|item| item.item_id.as_str())
+            .collect::<Vec<_>>(),
+        vec!["root-agent", "root-2-item"]
+    );
+    let inherited_turn = store
+        .list_turns(turn_params(
+            child_id,
+            Some(first_occurrences.items[0].turn_cursor.clone()),
+            /*page_size*/ 1,
+            SortDirection::Asc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("navigate to inherited occurrence turn");
+    assert_eq!(turn_ids(&inherited_turn), vec!["root-1"]);
+    let child_occurrences = store
+        .search_thread_occurrences(SearchThreadOccurrencesParams {
+            thread_id: child_id,
+            search_term: "item".to_string(),
+            cursor: first_occurrences.next_cursor,
+            page_size: 2,
+        })
+        .await
+        .expect("continue inherited occurrence search");
+    assert_eq!(child_occurrences.items[0].item_id, "child-item");
+    assert_eq!(child_occurrences.next_cursor, None);
+
+    let gap_cursor = serde_json::to_string(&HistoryCursor {
+        requested_thread_id: child_id,
+        rollout_ordinal: 6,
+        include_anchor: true,
+        scope: CursorScope::Turns,
+    })
+    .expect("serialize cursor in metadata gap");
+    let error = store
+        .list_turns(turn_params(
+            child_id,
+            Some(gap_cursor),
+            /*page_size*/ 1,
+            SortDirection::Asc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect_err("cursor cannot point to segment metadata");
+    assert!(matches!(error, ThreadStoreError::InvalidRequest { .. }));
+
+    let (_other_home, other_store, other_thread_id) =
+        store_with_mode(ThreadHistoryMode::Paginated).await;
+    let error = other_store
+        .list_items(item_params(
+            other_thread_id,
+            /*turn_id*/ None,
+            second_items.backwards_cursor,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        ))
+        .await
+        .expect_err("lineage cursor belongs to requested thread");
+    assert!(matches!(error, ThreadStoreError::InvalidRequest { .. }));
+}
+
+#[tokio::test]
+async fn inherited_search_excludes_turns_created_after_the_fork() {
+    let (home, store, child_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let source_id = ThreadId::default();
+    let source_path = rollout_path(home.path(), source_id);
+    write_rollout_with_end(
+        source_path.as_path(),
+        source_id,
+        /*history_base*/ None,
+        /*next_ordinal*/ 5,
+    );
+    write_rollout_with_end(
+        rollout_path(home.path(), child_id).as_path(),
+        child_id,
+        Some(history_position(
+            source_path.as_path(),
+            source_id,
+            /*end_ordinal_exclusive*/ 3,
+        )),
+        /*next_ordinal*/ 2,
+    );
+    let db = history_db(&store).await;
+    insert_turn(
+        db,
+        source_id,
+        "hidden-turn",
+        /*rollout_ordinal*/ 3,
+        "completed",
+        /*error_json*/ None,
+        /*first_user_item_id*/ Some("hidden-item"),
+        /*final_agent_item_id*/ None,
+    )
+    .await;
+    insert_item(
+        db,
+        source_id,
+        "hidden-turn",
+        "hidden-item",
+        /*rollout_ordinal*/ 2,
+    )
+    .await;
+
+    let occurrences = store
+        .search_thread_occurrences(SearchThreadOccurrencesParams {
+            thread_id: child_id,
+            search_term: "hidden".to_string(),
+            cursor: None,
+            page_size: 1,
+        })
+        .await
+        .expect("search inherited history");
+
+    assert!(occurrences.items.is_empty());
+    assert_eq!(occurrences.next_cursor, None);
+}
+
+#[tokio::test]
+async fn lineage_reads_nested_forks() {
+    let (home, store, child_id) = store_with_mode(ThreadHistoryMode::Paginated).await;
+    let root_id = ThreadId::default();
+    let middle_id = ThreadId::default();
+    let root_path = rollout_path(home.path(), root_id);
+    write_rollout_with_end(
+        root_path.as_path(),
+        root_id,
+        /*history_base*/ None,
+        /*next_ordinal*/ 5,
+    );
+    let middle_path = rollout_path(home.path(), middle_id);
+    write_rollout_with_end(
+        middle_path.as_path(),
+        middle_id,
+        Some(history_position(
+            root_path.as_path(),
+            root_id,
+            /*end_ordinal_exclusive*/ 4,
+        )),
+        /*next_ordinal*/ 3,
+    );
+    write_rollout_with_end(
+        rollout_path(home.path(), child_id).as_path(),
+        child_id,
+        Some(history_position(
+            middle_path.as_path(),
+            middle_id,
+            /*end_ordinal_exclusive*/ 7,
+        )),
+        /*next_ordinal*/ 2,
+    );
+    let db = history_db(&store).await;
+    for (thread_id, turn_id, ordinal, status, first_user_item_id) in [
+        (root_id, "root", 1, "completed", None),
+        (root_id, "shared", 2, "completed", Some("before-fork")),
+        (middle_id, "shared", 5, "interrupted", None),
+        (middle_id, "middle", 6, "completed", None),
+        (child_id, "child", 8, "completed", None),
+    ] {
+        insert_turn(
+            db,
+            thread_id,
+            turn_id,
+            ordinal,
+            status,
+            /*error_json*/ None,
+            first_user_item_id,
+            /*final_agent_item_id*/ None,
+        )
+        .await;
+    }
+    insert_item(
+        db,
+        root_id,
+        "shared",
+        "before-fork",
+        /*rollout_ordinal*/ 3,
+    )
+    .await;
+    insert_item(
+        db,
+        root_id,
+        "shared",
+        "after-fork",
+        /*rollout_ordinal*/ 4,
+    )
+    .await;
+
+    let first_descending_page = store
+        .list_turns(turn_params(
+            child_id,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("first nested descending page");
+    assert_eq!(turn_ids(&first_descending_page), vec!["child", "middle"]);
+    let second_descending_page = store
+        .list_turns(turn_params(
+            child_id,
+            first_descending_page.next_cursor,
+            /*page_size*/ 2,
+            SortDirection::Desc,
+            StoredTurnItemsView::Summary,
+        ))
+        .await
+        .expect("second nested descending page");
+    assert_eq!(turn_ids(&second_descending_page), vec!["shared", "root"]);
+    assert_eq!(
+        second_descending_page.turns[0].status,
+        StoredTurnStatus::Interrupted
+    );
+    assert_eq!(
+        second_descending_page.turns[0].items,
+        vec![expected_item(
+            "shared",
+            "before-fork",
+            /*rollout_ordinal*/ 3
+        )]
+    );
+
+    let ascending_page = store
+        .list_turns(turn_params(
+            child_id,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+            StoredTurnItemsView::Summary,
+        ))
+        .await
+        .expect("first nested ascending page");
+    assert_eq!(turn_ids(&ascending_page), vec!["root", "shared"]);
+
+    let mut held_connections = Vec::new();
+    for _ in 0..4 {
+        held_connections.push(db.acquire().await.expect("hold history connection"));
+    }
+    let occurrences = tokio::time::timeout(
+        Duration::from_secs(5),
+        store.search_thread_occurrences(SearchThreadOccurrencesParams {
+            thread_id: child_id,
+            search_term: "o".to_string(),
+            cursor: None,
+            page_size: 1,
+        }),
+    )
+    .await
+    .expect("inherited search releases its row connection")
+    .expect("search inherited occurrence");
+    assert_eq!(occurrences.items[0].item_id, "before-fork");
+    assert!(occurrences.next_cursor.is_some());
+
+    let occurrence_turn = store
+        .list_turns(turn_params(
+            child_id,
+            Some(occurrences.items[0].turn_cursor.clone()),
+            /*page_size*/ 1,
+            SortDirection::Asc,
+            StoredTurnItemsView::NotLoaded,
+        ))
+        .await
+        .expect("navigate to effective occurrence turn");
+    assert_eq!(turn_ids(&occurrence_turn), vec!["shared"]);
+}
+
+async fn store_with_mode(history_mode: ThreadHistoryMode) -> (TempDir, LocalThreadStore, ThreadId) {
+    let home = TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let thread_id = ThreadId::default();
+    let rollout_path = rollout_path(home.path(), thread_id);
+    if history_mode == ThreadHistoryMode::Paginated {
+        write_rollout(
+            rollout_path.as_path(),
+            thread_id,
+            /*history_base*/ None,
+        );
+    }
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state runtime");
+    let mut builder = codex_state::ThreadMetadataBuilder::new(
+        thread_id,
+        rollout_path,
+        Utc::now(),
+        SessionSource::Cli,
+    );
+    builder.history_mode = history_mode;
+    runtime
+        .upsert_thread(&builder.build(config.default_model_provider_id.as_str()))
+        .await
+        .expect("seed thread metadata");
+    let store = LocalThreadStore::new(config, Some(runtime));
+    (home, store, thread_id)
+}
+
+fn write_rollout(
+    path: &std::path::Path,
+    thread_id: ThreadId,
+    history_base: Option<HistoryPosition>,
+) {
+    write_rollout_with_end(path, thread_id, history_base, /*next_ordinal*/ 1);
+}
+
+fn write_rollout_with_end(
+    path: &std::path::Path,
+    thread_id: ThreadId,
+    history_base: Option<HistoryPosition>,
+    next_ordinal: u64,
+) {
+    fs::create_dir_all(path.parent().expect("rollout parent")).expect("create rollout parent");
+    let initial_ordinal = history_base.map_or(0, |base| base.end_ordinal_exclusive);
+    let mut lines = vec![RolloutLine {
+        timestamp: "2026-07-16T00:00:00.000Z".to_string(),
+        ordinal: Some(initial_ordinal),
+        item: RolloutItem::SessionMeta(SessionMetaLine {
+            meta: SessionMeta {
+                session_id: thread_id.into(),
+                id: thread_id,
+                history_mode: ThreadHistoryMode::Paginated,
+                history_base,
+                ..SessionMeta::default()
+            },
+            git: None,
+        }),
+    }];
+    for offset in 1..next_ordinal {
+        let ordinal = initial_ordinal
+            .checked_add(offset)
+            .expect("fixture ordinal");
+        lines.push(RolloutLine {
+            timestamp: "2026-07-16T00:00:00.000Z".to_string(),
+            ordinal: Some(ordinal),
+            item: RolloutItem::EventMsg(EventMsg::ShutdownComplete),
+        });
+    }
+    fs::write(
+        path,
+        format!(
+            "{}\n",
+            lines
+                .iter()
+                .map(|line| serde_json::to_string(line).expect("serialize rollout"))
+                .collect::<Vec<_>>()
+                .join("\n")
+        ),
+    )
+    .expect("write rollout");
+}
+
+fn rollout_path(home: &std::path::Path, thread_id: ThreadId) -> std::path::PathBuf {
+    home.join(format!(
+        "sessions/2026/07/16/rollout-2026-07-16T00-00-00-{thread_id}.jsonl"
+    ))
+}
+
+fn history_position(
+    path: &std::path::Path,
+    thread_id: ThreadId,
+    end_ordinal_exclusive: u64,
+) -> HistoryPosition {
+    HistoryPosition {
+        thread_id,
+        end_ordinal_exclusive,
+        end_byte_offset: rollout_end_byte_offset(path, end_ordinal_exclusive),
+    }
+}
+
+fn rollout_end_byte_offset(path: &std::path::Path, end_ordinal_exclusive: u64) -> u64 {
+    let bytes = fs::read(path).expect("read rollout");
+    let end_byte_offset = bytes
+        .split_inclusive(|byte| *byte == b'\n')
+        .take_while(|line| {
+            codex_rollout::parse_rollout_line_bytes(line)
+                .expect("parse rollout fixture")
+                .ordinal
+                .expect("paginated rollout ordinal")
+                < end_ordinal_exclusive
+        })
+        .map(<[u8]>::len)
+        .sum::<usize>();
+    u64::try_from(end_byte_offset).expect("rollout byte offset fits u64")
+}
+
+async fn history_db(store: &LocalThreadStore) -> &sqlx::SqlitePool {
+    store
+        .thread_history_db()
+        .await
+        .expect("open history fixture database")
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn insert_turn(
+    db: &sqlx::SqlitePool,
+    thread_id: ThreadId,
+    turn_id: &str,
+    rollout_ordinal: i64,
+    status: &str,
+    error_json: Option<&str>,
+    first_user_item_id: Option<&str>,
+    final_agent_item_id: Option<&str>,
+) {
+    sqlx::query(
+        r#"
+INSERT INTO thread_turns (
+    thread_id,
+    turn_id,
+    rollout_ordinal,
+    status,
+    error_json,
+    first_user_item_id,
+    final_agent_item_id
+) VALUES (?, ?, ?, ?, ?, ?, ?)
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .bind(turn_id)
+    .bind(rollout_ordinal)
+    .bind(status)
+    .bind(error_json)
+    .bind(first_user_item_id)
+    .bind(final_agent_item_id)
+    .execute(db)
+    .await
+    .expect("insert turn fixture");
+}
+
+async fn insert_item(
+    db: &sqlx::SqlitePool,
+    thread_id: ThreadId,
+    turn_id: &str,
+    item_id: &str,
+    rollout_ordinal: i64,
+) {
+    let (item_type, item_json) = fixture_item(item_id);
+    sqlx::query(
+        "INSERT INTO thread_items (thread_id, turn_id, item_id, rollout_ordinal, updated_at_ordinal, created_at_ms, item_type, item_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    )
+    .bind(thread_id.to_string())
+    .bind(turn_id)
+    .bind(item_id)
+    .bind(rollout_ordinal)
+    .bind(rollout_ordinal)
+    .bind(rollout_ordinal * 1_000)
+    .bind(item_type)
+    .bind(item_json)
+    .execute(db)
+    .await
+    .expect("insert item fixture");
+}
+
+fn turn_params(
+    thread_id: ThreadId,
+    cursor: Option<String>,
+    page_size: usize,
+    sort_direction: SortDirection,
+    items_view: StoredTurnItemsView,
+) -> ListTurnsParams {
+    ListTurnsParams {
+        thread_id,
+        include_archived: false,
+        cursor,
+        page_size,
+        sort_direction,
+        items_view,
+    }
+}
+
+fn item_params(
+    thread_id: ThreadId,
+    turn_id: Option<&str>,
+    cursor: Option<String>,
+    page_size: usize,
+    sort_direction: SortDirection,
+) -> ListItemsParams {
+    ListItemsParams {
+        thread_id,
+        turn_id: turn_id.map(str::to_owned),
+        include_archived: false,
+        cursor,
+        page_size,
+        sort_direction,
+        sort_key: ItemSortKey::CreatedAtOrdinal,
+        after_updated_at_ordinal: None,
+    }
+}
+
+fn updated_item_params(thread_id: ThreadId, after_updated_at_ordinal: u64) -> ListItemsParams {
+    ListItemsParams {
+        sort_key: ItemSortKey::UpdatedAtOrdinal,
+        after_updated_at_ordinal: Some(after_updated_at_ordinal),
+        ..item_params(
+            thread_id,
+            /*turn_id*/ None,
+            /*cursor*/ None,
+            /*page_size*/ 2,
+            SortDirection::Asc,
+        )
+    }
+}
+
+fn expected_item(turn_id: &str, item_id: &str, rollout_ordinal: u64) -> StoredThreadItem {
+    StoredThreadItem {
+        turn_id: turn_id.to_string(),
+        item_id: item_id.to_string(),
+        updated_at_ordinal: rollout_ordinal,
+        created_at_ms: i64::try_from(rollout_ordinal).expect("fixture ordinal fits i64") * 1_000,
+        item_json: fixture_item(item_id).1.into_bytes(),
+    }
+}
+
+fn fixture_item(item_id: &str) -> (&'static str, String) {
+    if item_id.contains("agent") {
+        (
+            "agentMessage",
+            format!(r#"{{"type":"agentMessage","id":"{item_id}","text":"{item_id} item"}}"#),
+        )
+    } else {
+        (
+            "userMessage",
+            format!(
+                r#"{{"type":"userMessage","id":"{item_id}","content":[{{"type":"text","text":"{item_id}"}}]}}"#
+            ),
+        )
+    }
+}
+
+fn turn_ids(page: &TurnPage) -> Vec<&str> {
+    page.turns
+        .iter()
+        .map(|turn| turn.turn_id.as_str())
+        .collect()
+}
+
+fn item_ids(page: &ItemPage) -> Vec<&str> {
+    page.items
+        .iter()
+        .map(|item| item.item_id.as_str())
+        .collect()
+}
diff --git a/codex-rs/thread-store/src/local/thread_history/realtime.rs b/codex-rs/thread-store/src/local/thread_history/realtime.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0dd233b7767094abd05c8a015bef61c7c3756d0e
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history/realtime.rs
@@ -0,0 +1,246 @@
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::ThreadTimelineEntry;
+use codex_protocol::ThreadId;
+use codex_protocol::realtime::RealtimeItem;
+use serde::Deserialize;
+use serde::Serialize;
+
+use super::super::LocalThreadStore;
+use super::read::validate_thread_for_paginated_reads;
+use super::segment_paging::validate_page_size;
+use super::sqlite_integer;
+use super::thread_history_error;
+use crate::ListTimelineParams;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::TimelinePage;
+
+#[derive(Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct TimelineCursor {
+    thread_id: ThreadId,
+    position: u64,
+    kind: u8,
+    id: String,
+}
+
+// A rollout record can materialize both an item and a turn boundary. Keep the
+// boundary order stable, including when the page cuts through one ordinal.
+pub(super) fn entry_key(entry: &ThreadTimelineEntry) -> (u64, u8, &str) {
+    match entry {
+        ThreadTimelineEntry::TurnStarted {
+            position, turn_id, ..
+        } => (*position, 0, turn_id),
+        ThreadTimelineEntry::Item { position, item, .. } => (*position, 1, item.id()),
+        ThreadTimelineEntry::Realtime { position, item } => (*position, 2, &item.id),
+        ThreadTimelineEntry::TurnCompleted {
+            position, turn_id, ..
+        } => (*position, 3, turn_id),
+    }
+}
+
+pub(in crate::local) async fn list_timeline(
+    store: &LocalThreadStore,
+    params: ListTimelineParams,
+) -> ThreadStoreResult<TimelinePage> {
+    validate_thread_for_paginated_reads(
+        store,
+        params.thread_id,
+        /*include_archived*/ false,
+        "thread/timeline/list",
+    )
+    .await?;
+    validate_page_size(params.page_size)?;
+
+    let lineage = store.resolve_rollout_lineage(params.thread_id).await?;
+    let pool = store.thread_history_db().await?;
+    let cursor = params
+        .cursor
+        .as_deref()
+        .map(serde_json::from_str::<TimelineCursor>)
+        .transpose()
+        .map_err(|_| ThreadStoreError::InvalidRequest {
+            message: "invalid thread timeline cursor".to_string(),
+        })?
+        .map(|cursor| {
+            if cursor.thread_id != params.thread_id {
+                Err(ThreadStoreError::InvalidRequest {
+                    message: "thread timeline cursor belongs to another thread".to_string(),
+                })
+            } else {
+                Ok(cursor)
+            }
+        })
+        .transpose()?;
+    let cursor_position = cursor.as_ref().map(|cursor| cursor.position);
+    let cursor_ordinal = cursor_position
+        .map(|position| sqlite_integer(position, "rollout ordinal"))
+        .transpose()?
+        .unwrap_or(i64::MAX);
+    let cursor_kind = cursor.as_ref().map_or(4, |cursor| cursor.kind);
+    let cursor_id = cursor.as_ref().map_or("", |cursor| cursor.id.as_str());
+
+    let mut rows = Vec::new();
+    let max_rows = params.page_size + 1;
+    for segment in lineage.segments().iter().rev() {
+        let remaining = max_rows.saturating_sub(rows.len());
+        if remaining == 0 {
+            break;
+        }
+        if cursor_position.is_some_and(|position| position < segment.start_ordinal()) {
+            continue;
+        }
+        let upper = segment
+            .end_ordinal()
+            .map(|value| sqlite_integer(value, "rollout ordinal"))
+            .transpose()?
+            .unwrap_or(i64::MAX);
+        let segment_rows = sqlx::query_as::<_, (i64, i64, String, Option<String>, String)>(
+            r#"
+WITH starts AS (
+SELECT rollout_ordinal, 0 AS kind, turn_id AS id, turn_id,
+       json_object('type', 'turnStarted', 'position', rollout_ordinal,
+                   'turnId', turn_id, 'startedAt', started_at) AS item_json
+FROM thread_turns
+WHERE thread_id = ?1 AND rollout_ordinal >= ?2
+  AND rollout_ordinal < ?3 AND rollout_ordinal <= ?4
+  AND (rollout_ordinal, 0, turn_id) < (?4, ?5, ?6)
+ORDER BY rollout_ordinal DESC, turn_id DESC LIMIT ?7
+), items AS (
+SELECT rollout_ordinal, 1 AS kind, item_id AS id, turn_id, item_json
+FROM thread_items
+WHERE thread_id = ?1 AND rollout_ordinal >= ?2
+  AND rollout_ordinal < ?3 AND rollout_ordinal <= ?4
+  AND (rollout_ordinal, 1, item_id) < (?4, ?5, ?6)
+ORDER BY rollout_ordinal DESC, item_id DESC LIMIT ?7
+), realtime AS (
+SELECT rollout_ordinal, 2 AS kind, item_id AS id, NULL AS turn_id, item_json
+FROM thread_realtime_items
+WHERE thread_id = ?1 AND rollout_ordinal >= ?2
+  AND rollout_ordinal < ?3 AND rollout_ordinal <= ?4
+  AND (rollout_ordinal, 2, item_id) < (?4, ?5, ?6)
+ORDER BY rollout_ordinal DESC, item_id DESC LIMIT ?7
+), ends AS (
+SELECT rollout_end_ordinal AS rollout_ordinal, 3 AS kind, turn_id AS id, turn_id,
+       json_object('type', 'turnCompleted', 'position', rollout_end_ordinal,
+                   'turnId', turn_id, 'status', status, 'error', json(error_json),
+                   'startedAt', started_at, 'completedAt', completed_at,
+                   'durationMs', duration_ms) AS item_json
+FROM thread_turns
+WHERE thread_id = ?1 AND rollout_end_ordinal >= ?2
+  AND rollout_end_ordinal < ?3 AND rollout_end_ordinal <= ?4
+  AND (rollout_end_ordinal, 3, turn_id) < (?4, ?5, ?6)
+ORDER BY rollout_end_ordinal DESC, turn_id DESC LIMIT ?7
+)
+SELECT * FROM starts
+UNION ALL SELECT * FROM items
+UNION ALL SELECT * FROM realtime
+UNION ALL SELECT * FROM ends
+ORDER BY rollout_ordinal DESC, kind DESC, id DESC
+LIMIT ?7
+            "#,
+        )
+        .bind(segment.rollout_id().to_string())
+        .bind(sqlite_integer(segment.start_ordinal(), "rollout ordinal")?)
+        .bind(upper)
+        .bind(cursor_ordinal)
+        .bind(i64::from(cursor_kind))
+        .bind(cursor_id)
+        .bind(i64::try_from(remaining).map_err(thread_history_error)?)
+        .fetch_all(pool)
+        .await
+        .map_err(thread_history_error)?;
+
+        for (position, kind, _id, turn_id, item_json) in segment_rows {
+            let position = u64::try_from(position).map_err(thread_history_error)?;
+            rows.push(match kind {
+                0 | 3 => serde_json::from_str::<ThreadTimelineEntry>(&item_json)
+                    .map_err(thread_history_error)?,
+                1 => ThreadTimelineEntry::Item {
+                    position,
+                    turn_id: turn_id.ok_or_else(|| thread_history_error("missing turn ID"))?,
+                    item: Box::new(
+                        serde_json::from_str::<ThreadItem>(&item_json)
+                            .map_err(thread_history_error)?,
+                    ),
+                },
+                2 => ThreadTimelineEntry::Realtime {
+                    position,
+                    item: serde_json::from_str::<RealtimeItem>(&item_json)
+                        .map_err(thread_history_error)?
+                        .into(),
+                },
+                _ => return Err(thread_history_error("invalid timeline entry kind")),
+            });
+        }
+    }
+
+    let has_more = rows.len() > params.page_size;
+    rows.truncate(params.page_size);
+    let next_cursor = if has_more {
+        rows.last()
+            .map(|entry| {
+                let (position, kind, id) = entry_key(entry);
+                serde_json::to_string(&TimelineCursor {
+                    thread_id: params.thread_id,
+                    position,
+                    kind,
+                    id: id.to_string(),
+                })
+                .map_err(thread_history_error)
+            })
+            .transpose()?
+    } else {
+        None
+    };
+
+    let (page_start, page_start_kind, page_start_id) =
+        rows.last().map(entry_key).unwrap_or_default();
+    let mut active_realtime_session_at_page_start = None;
+    for segment in lineage.segments().iter().rev() {
+        let upper = page_start.min(
+            segment
+                .end_ordinal()
+                .map(|ordinal| ordinal.saturating_sub(1))
+                .unwrap_or(u64::MAX),
+        );
+        if upper < segment.start_ordinal() {
+            continue;
+        }
+        let boundary = sqlx::query_as::<_, (String, String)>(
+            r#"
+SELECT item_type, json_extract(item_json, '$.realtime_session_id')
+FROM thread_realtime_items
+WHERE thread_id = ?
+  AND rollout_ordinal >= ?
+  AND rollout_ordinal <= ?
+  AND (rollout_ordinal, 2, item_id) < (?, ?, ?)
+  AND item_type IN ('realtime_session_started', 'realtime_session_closed')
+ORDER BY rollout_ordinal DESC
+LIMIT 1
+            "#,
+        )
+        .bind(segment.rollout_id().to_string())
+        .bind(sqlite_integer(segment.start_ordinal(), "rollout ordinal")?)
+        .bind(sqlite_integer(upper, "rollout ordinal")?)
+        .bind(sqlite_integer(page_start, "rollout ordinal")?)
+        .bind(i64::from(page_start_kind))
+        .bind(page_start_id)
+        .fetch_optional(pool)
+        .await
+        .map_err(thread_history_error)?;
+        if let Some((item_type, session_id)) = boundary {
+            if item_type == "realtime_session_started" {
+                active_realtime_session_at_page_start = Some(session_id);
+            }
+            break;
+        }
+    }
+
+    rows.reverse();
+    Ok(TimelinePage {
+        items: rows,
+        next_cursor,
+        active_realtime_session_at_page_start,
+    })
+}
diff --git a/codex-rs/thread-store/src/local/thread_history/search.rs b/codex-rs/thread-store/src/local/thread_history/search.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f93fe61eb30d2675a768e82abccfd476d40dd56c
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history/search.rs
@@ -0,0 +1,494 @@
+use std::borrow::Cow;
+use std::collections::HashMap;
+
+use codex_app_server_protocol::ThreadItem;
+use codex_app_server_protocol::UserInput;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::strip_user_message_prefix;
+use futures::TryStreamExt;
+use pulldown_cmark::Event;
+use pulldown_cmark::Parser;
+use pulldown_cmark::TagEnd;
+use serde::Deserialize;
+use serde::Serialize;
+use sqlx::Row;
+
+use super::super::LocalThreadStore;
+use super::read::CursorScope;
+use super::read::serialize_cursor;
+use super::read::validate_thread_for_paginated_reads;
+use super::sqlite_integer;
+use super::thread_history_error;
+use super::turn_lookup::find_visible_turn;
+use crate::SearchTextRange;
+use crate::SearchThreadOccurrencesParams;
+use crate::StoredThreadOccurrence;
+use crate::ThreadOccurrenceSearchPage;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+const SNIPPET_CONTEXT_BEFORE_CHARS: usize = 48;
+const SNIPPET_CONTEXT_AFTER_CHARS: usize = 96;
+
+#[derive(Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct SearchCursor {
+    thread_id: ThreadId,
+    search_term: String,
+    next_rollout_ordinal: i64,
+    next_occurrence_index: usize,
+}
+
+struct CandidateRow {
+    turn_id: String,
+    item_id: String,
+    rollout_ordinal: i64,
+    item_json: String,
+    turn_rollout_ordinal: i64,
+}
+
+pub(in crate::local) async fn search_thread_occurrences(
+    store: &LocalThreadStore,
+    params: SearchThreadOccurrencesParams,
+) -> ThreadStoreResult<ThreadOccurrenceSearchPage> {
+    if params.search_term.trim().is_empty() {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "thread/searchOccurrences requires search_term".to_string(),
+        });
+    }
+    if params.page_size == 0 {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "thread/searchOccurrences requires page_size greater than zero".to_string(),
+        });
+    }
+    validate_thread_for_paginated_reads(
+        store,
+        params.thread_id,
+        /*include_archived*/ true,
+        "thread/searchOccurrences",
+    )
+    .await?;
+    let cursor = parse_cursor(
+        params.cursor.as_deref(),
+        params.thread_id,
+        &params.search_term,
+    )?;
+    let matcher = LiteralMatcher::new(params.search_term.as_str());
+    let lineage = store.resolve_rollout_lineage(params.thread_id).await?;
+    let cursor_segment = cursor
+        .as_ref()
+        .map(|cursor| {
+            lineage
+                .segment_index_for_ordinal(
+                    u64::try_from(cursor.next_rollout_ordinal)
+                        .map_err(|_| invalid_cursor("negative rollout ordinal"))?,
+                )
+                .ok_or_else(|| invalid_cursor("position outside thread lineage"))
+        })
+        .transpose()?;
+    let pool = store.thread_history_db().await?;
+    let mut items = Vec::with_capacity(params.page_size);
+    let mut effective_turn_ordinals = HashMap::new();
+    for (segment_index, segment) in lineage
+        .segments()
+        .iter()
+        .enumerate()
+        .skip(cursor_segment.unwrap_or(0))
+    {
+        let segment_start_ordinal = sqlite_integer(segment.start_ordinal(), "rollout ordinal")?;
+        let next_rollout_ordinal = if Some(segment_index) == cursor_segment {
+            cursor
+                .as_ref()
+                .map_or(0, |cursor| cursor.next_rollout_ordinal)
+        } else {
+            segment_start_ordinal
+        };
+        let end_rollout_ordinal = segment
+            .end_ordinal()
+            .map(|ordinal| sqlite_integer(ordinal, "rollout ordinal"))
+            .transpose()?
+            .unwrap_or(i64::MAX);
+        let mut rows = sqlx::query(
+            r#"
+SELECT turn_id, item_id, rollout_ordinal, item_json, turn_rollout_ordinal
+FROM (
+    SELECT
+        items.turn_id,
+        items.item_id,
+        items.rollout_ordinal,
+        items.item_json,
+        turns.rollout_ordinal AS turn_rollout_ordinal
+    FROM thread_items AS items
+    JOIN thread_turns AS turns
+      ON turns.thread_id = items.thread_id
+     AND turns.turn_id = items.turn_id
+    WHERE items.thread_id = ?
+      AND items.item_type = 'userMessage'
+      AND items.rollout_ordinal >= ?
+      AND items.rollout_ordinal < ?
+      AND turns.rollout_ordinal >= ?
+      AND turns.rollout_ordinal < ?
+
+    UNION ALL
+
+    SELECT
+        items.turn_id,
+        items.item_id,
+        items.rollout_ordinal,
+        items.item_json,
+        turns.rollout_ordinal AS turn_rollout_ordinal
+    FROM thread_turns AS turns
+    JOIN thread_items AS items
+      ON items.thread_id = turns.thread_id
+     AND items.turn_id = turns.turn_id
+     AND items.item_id = turns.final_agent_item_id
+    WHERE turns.thread_id = ?
+      AND turns.final_agent_item_id IS NOT NULL
+      AND items.rollout_ordinal >= ?
+      AND items.rollout_ordinal < ?
+      AND turns.rollout_ordinal >= ?
+      AND turns.rollout_ordinal < ?
+)
+ORDER BY rollout_ordinal ASC
+        "#,
+        )
+        .bind(segment.rollout_id().to_string())
+        .bind(next_rollout_ordinal)
+        .bind(end_rollout_ordinal)
+        .bind(segment_start_ordinal)
+        .bind(end_rollout_ordinal)
+        .bind(segment.rollout_id().to_string())
+        .bind(next_rollout_ordinal)
+        .bind(end_rollout_ordinal)
+        .bind(segment_start_ordinal)
+        .bind(end_rollout_ordinal)
+        .fetch(pool);
+
+        let mut matching_rows = Vec::new();
+        let mut matching_occurrences = 0_usize;
+        while let Some(row) = rows.try_next().await.map_err(thread_history_error)? {
+            let row = candidate_row(row)?;
+            let item =
+                serde_json::from_str::<ThreadItem>(row.item_json.as_str()).map_err(|err| {
+                    ThreadStoreError::Internal {
+                        message: format!("failed to deserialize stored thread item: {err}"),
+                    }
+                })?;
+            let Some(text) = searchable_text(&item) else {
+                continue;
+            };
+            let first_occurrence_index = cursor
+                .as_ref()
+                .filter(|cursor| cursor.next_rollout_ordinal == row.rollout_ordinal)
+                .map_or(0, |cursor| cursor.next_occurrence_index);
+            let remaining = params
+                .page_size
+                .saturating_add(1)
+                .saturating_sub(items.len())
+                .saturating_sub(matching_occurrences);
+            let matches = matcher.find_ranges(
+                text.as_ref(),
+                first_occurrence_index.saturating_add(remaining),
+            );
+            if matches.len() <= first_occurrence_index {
+                continue;
+            }
+            matching_occurrences += matches.len() - first_occurrence_index;
+            matching_rows.push((row, text.into_owned(), matches, first_occurrence_index));
+            if matching_occurrences
+                == params
+                    .page_size
+                    .saturating_add(1)
+                    .saturating_sub(items.len())
+            {
+                break;
+            }
+        }
+        drop(rows);
+
+        for (row, text, matches, first_occurrence_index) in matching_rows {
+            let turn_rollout_ordinal = if segment_index + 1 == lineage.segments().len() {
+                row.turn_rollout_ordinal
+            } else if let Some(ordinal) = effective_turn_ordinals.get(&row.turn_id) {
+                *ordinal
+            } else {
+                let ordinal = find_visible_turn(pool, &lineage, row.turn_id.as_str())
+                    .await?
+                    .rollout_ordinal;
+                effective_turn_ordinals.insert(row.turn_id.clone(), ordinal);
+                ordinal
+            };
+            let turn_cursor = serialize_cursor(
+                params.thread_id,
+                CursorScope::Turns,
+                turn_rollout_ordinal,
+                /*include_anchor*/ true,
+            )?;
+            for (occurrence_index, matched) in
+                matches.into_iter().enumerate().skip(first_occurrence_index)
+            {
+                if items.len() == params.page_size {
+                    return Ok(ThreadOccurrenceSearchPage {
+                        items,
+                        next_cursor: Some(serialize_cursor_for_search(SearchCursor {
+                            thread_id: params.thread_id,
+                            search_term: params.search_term,
+                            next_rollout_ordinal: row.rollout_ordinal,
+                            next_occurrence_index: occurrence_index,
+                        })?),
+                    });
+                }
+                items.push(occurrence_in_item(
+                    row.turn_id.as_str(),
+                    row.item_id.as_str(),
+                    text.as_str(),
+                    matched,
+                    turn_cursor.as_str(),
+                ));
+            }
+        }
+    }
+
+    Ok(ThreadOccurrenceSearchPage {
+        items,
+        next_cursor: None,
+    })
+}
+
+fn candidate_row(row: sqlx::sqlite::SqliteRow) -> ThreadStoreResult<CandidateRow> {
+    let rollout_ordinal = row.try_get::<i64, _>("rollout_ordinal")?;
+    let turn_rollout_ordinal = row.try_get::<i64, _>("turn_rollout_ordinal")?;
+    if rollout_ordinal < 0 || turn_rollout_ordinal < 0 {
+        return Err(ThreadStoreError::Internal {
+            message: "invalid stored thread history ordinal".to_string(),
+        });
+    }
+    Ok(CandidateRow {
+        turn_id: row.try_get("turn_id")?,
+        item_id: row.try_get("item_id")?,
+        rollout_ordinal,
+        item_json: row.try_get("item_json")?,
+        turn_rollout_ordinal,
+    })
+}
+
+fn parse_cursor(
+    cursor: Option<&str>,
+    thread_id: ThreadId,
+    search_term: &str,
+) -> ThreadStoreResult<Option<SearchCursor>> {
+    let Some(cursor) = cursor else {
+        return Ok(None);
+    };
+    let cursor_value: SearchCursor =
+        serde_json::from_str(cursor).map_err(|_| invalid_cursor(cursor))?;
+    if cursor_value.thread_id != thread_id
+        || cursor_value.search_term != search_term
+        || cursor_value.next_rollout_ordinal < 0
+    {
+        return Err(invalid_cursor(cursor));
+    }
+    Ok(Some(cursor_value))
+}
+
+fn serialize_cursor_for_search(cursor: SearchCursor) -> ThreadStoreResult<String> {
+    serde_json::to_string(&cursor).map_err(thread_history_error)
+}
+
+fn invalid_cursor(cursor: &str) -> ThreadStoreError {
+    ThreadStoreError::InvalidRequest {
+        message: format!("invalid cursor: {cursor}"),
+    }
+}
+
+fn searchable_text(item: &ThreadItem) -> Option<Cow<'_, str>> {
+    match item {
+        ThreadItem::UserMessage { content, .. } => {
+            let mut text_parts = content
+                .iter()
+                .filter_map(|input| match input {
+                    UserInput::Text { text, .. } => Some(strip_user_message_prefix(text)),
+                    UserInput::Image { .. }
+                    | UserInput::LocalImage { .. }
+                    | UserInput::Audio { .. }
+                    | UserInput::LocalAudio { .. }
+                    | UserInput::Skill { .. }
+                    | UserInput::Mention { .. } => None,
+                })
+                .filter(|text| !text.is_empty())
+                .peekable();
+            let first = text_parts.next()?;
+            match text_parts.next() {
+                None => Some(Cow::Borrowed(first)),
+                Some(second) => {
+                    let mut parts = vec![first, second];
+                    parts.extend(text_parts);
+                    Some(Cow::Owned(parts.concat()))
+                }
+            }
+        }
+        ThreadItem::AgentMessage { text, .. } => {
+            let text = markdown_to_search_text(text);
+            (!text.is_empty()).then_some(Cow::Owned(text))
+        }
+        ThreadItem::HookPrompt { .. }
+        | ThreadItem::FunctionCallOutput { .. }
+        | ThreadItem::Plan { .. }
+        | ThreadItem::Reasoning { .. }
+        | ThreadItem::CommandExecution { .. }
+        | ThreadItem::FileChange { .. }
+        | ThreadItem::McpToolCall { .. }
+        | ThreadItem::DynamicToolCall { .. }
+        | ThreadItem::CollabAgentToolCall { .. }
+        | ThreadItem::SubAgentActivity { .. }
+        | ThreadItem::WebSearch(_)
+        | ThreadItem::ImageView { .. }
+        | ThreadItem::Sleep(_)
+        | ThreadItem::ImageGeneration(_)
+        | ThreadItem::EnteredReviewMode { .. }
+        | ThreadItem::ExitedReviewMode { .. }
+        | ThreadItem::ContextCompaction { .. } => None,
+    }
+}
+
+fn markdown_to_search_text(markdown: &str) -> String {
+    let mut text = String::new();
+    for event in Parser::new(markdown.trim()) {
+        match event {
+            Event::Text(value)
+            | Event::Code(value)
+            | Event::Html(value)
+            | Event::InlineHtml(value) => text.push_str(&value),
+            Event::SoftBreak | Event::HardBreak | Event::Rule => text.push(' '),
+            Event::End(
+                TagEnd::Paragraph
+                | TagEnd::Heading(_)
+                | TagEnd::BlockQuote
+                | TagEnd::CodeBlock
+                | TagEnd::List(_)
+                | TagEnd::Item
+                | TagEnd::Table
+                | TagEnd::TableHead
+                | TagEnd::TableRow
+                | TagEnd::TableCell,
+            ) => text.push(' '),
+            Event::Start(_)
+            | Event::End(
+                TagEnd::Emphasis
+                | TagEnd::Strong
+                | TagEnd::Strikethrough
+                | TagEnd::Link
+                | TagEnd::HtmlBlock
+                | TagEnd::FootnoteDefinition
+                | TagEnd::Image
+                | TagEnd::MetadataBlock(_),
+            )
+            | Event::FootnoteReference(_)
+            | Event::TaskListMarker(_) => {}
+        }
+    }
+    text.split_whitespace().collect::<Vec<_>>().join(" ")
+}
+
+struct LiteralMatcher {
+    lowercase_needle: String,
+}
+
+impl LiteralMatcher {
+    fn new(needle: &str) -> Self {
+        Self {
+            lowercase_needle: needle.to_lowercase(),
+        }
+    }
+
+    fn find_ranges(&self, text: &str, limit: usize) -> Vec<std::ops::Range<usize>> {
+        let lowercase_text = text.to_lowercase();
+        let mut spans = Vec::with_capacity(text.chars().count());
+        let mut lowercase_start = 0;
+        for (original_start, character) in text.char_indices() {
+            let lowercase_end =
+                lowercase_start + character.to_lowercase().map(char::len_utf8).sum::<usize>();
+            spans.push((
+                lowercase_start..lowercase_end,
+                original_start..original_start + character.len_utf8(),
+            ));
+            lowercase_start = lowercase_end;
+        }
+
+        // Use two-pointer method to find matches in linear time.
+        let mut start_span = 0;
+        let mut end_span = 0;
+        lowercase_text
+            .match_indices(self.lowercase_needle.as_str())
+            .take(limit)
+            .filter_map(|(start, matched)| {
+                let end = start.saturating_add(matched.len());
+                while spans.get(start_span)?.0.end <= start {
+                    start_span += 1;
+                }
+                while spans.get(end_span)?.0.end <= end.saturating_sub(1) {
+                    end_span += 1;
+                }
+                let original_start = spans.get(start_span)?.1.start;
+                let original_end = spans.get(end_span)?.1.end;
+                Some(original_start..original_end)
+            })
+            .collect()
+    }
+}
+
+fn occurrence_in_item(
+    turn_id: &str,
+    item_id: &str,
+    text: &str,
+    matched: std::ops::Range<usize>,
+    turn_cursor: &str,
+) -> StoredThreadOccurrence {
+    let snippet_start = char_start_before(text, matched.start, SNIPPET_CONTEXT_BEFORE_CHARS);
+    let snippet_end = char_end_after(text, matched.end, SNIPPET_CONTEXT_AFTER_CHARS);
+    let leading_ellipsis = snippet_start > 0;
+    let trailing_ellipsis = snippet_end < text.len();
+    let mut snippet = String::new();
+    if leading_ellipsis {
+        snippet.push_str("... ");
+    }
+    snippet.push_str(&text[snippet_start..snippet_end]);
+    if trailing_ellipsis {
+        snippet.push_str(" ...");
+    }
+    let snippet_match_start =
+        if leading_ellipsis { 4 } else { 0 } + utf16_len(&text[snippet_start..matched.start]);
+    let match_len = utf16_len(&text[matched]);
+
+    StoredThreadOccurrence {
+        turn_id: turn_id.to_string(),
+        item_id: item_id.to_string(),
+        snippet,
+        snippet_match_range: SearchTextRange {
+            start: snippet_match_start,
+            end: snippet_match_start.saturating_add(match_len),
+        },
+        turn_cursor: turn_cursor.to_string(),
+    }
+}
+
+fn utf16_len(text: &str) -> u32 {
+    u32::try_from(text.encode_utf16().count()).unwrap_or(u32::MAX)
+}
+
+fn char_start_before(text: &str, byte_index: usize, chars_before: usize) -> usize {
+    text[..byte_index]
+        .char_indices()
+        .rev()
+        .nth(chars_before)
+        .map(|(index, _)| index)
+        .unwrap_or(0)
+}
+
+fn char_end_after(text: &str, byte_index: usize, chars_after: usize) -> usize {
+    text[byte_index..]
+        .char_indices()
+        .nth(chars_after)
+        .map(|(offset, _)| byte_index.saturating_add(offset))
+        .unwrap_or(text.len())
+}
diff --git a/codex-rs/thread-store/src/local/thread_history/segment_paging.rs b/codex-rs/thread-store/src/local/thread_history/segment_paging.rs
new file mode 100644
index 0000000000000000000000000000000000000000..45b087b675156d7234dcb6ff4a0797917b055045
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history/segment_paging.rs
@@ -0,0 +1,502 @@
+use codex_protocol::ThreadId;
+use sqlx::FromRow;
+use sqlx::QueryBuilder;
+use sqlx::Sqlite;
+
+use super::super::rollout_lineage::RolloutLineage;
+use super::super::rollout_lineage::RolloutLineageSegment;
+use super::read::CursorScope;
+use super::read::HistoryCursor;
+use super::read::RolloutHistoryPosition;
+use super::read::StoredSummaryColumns;
+use super::read::StoredThreadItemRow;
+use super::read::StoredTurnRow;
+use super::read::invalid_cursor;
+use super::read::parse_cursor;
+use super::read::serialize_cursor;
+use super::read::stored_thread_item_row;
+use super::read::stored_turn_row;
+use super::thread_history_error;
+use crate::ItemSortKey;
+use crate::ListItemsParams;
+use crate::SortDirection;
+use crate::StoredTurnItemsView;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+pub(super) struct SegmentPage<T> {
+    pub rows: Vec<T>,
+    pub next_cursor: Option<String>,
+    pub backwards_cursor: Option<String>,
+}
+
+pub(super) fn validate_page_size(page_size: usize) -> ThreadStoreResult<()> {
+    if page_size == 0 {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "page size must be positive".to_string(),
+        });
+    }
+    let limit = page_size.checked_add(1).ok_or_else(page_size_too_large)?;
+    i64::try_from(limit).map_err(|_| page_size_too_large())?;
+    Ok(())
+}
+
+pub(super) async fn page_turn_rows(
+    pool: &sqlx::SqlitePool,
+    requested_thread_id: ThreadId,
+    lineage: &RolloutLineage,
+    cursor: Option<&str>,
+    page_size: usize,
+    direction: SortDirection,
+    items_view: StoredTurnItemsView,
+) -> ThreadStoreResult<SegmentPage<StoredTurnRow>> {
+    let cursor = parse_cursor(cursor, requested_thread_id, CursorScope::Turns)?;
+    let mut rows = Vec::new();
+    for (segment_index, segment, segment_cursor) in
+        segments_from_cursor(lineage, direction, cursor.as_ref())?
+    {
+        let remaining = remaining_limit(page_size, rows.len())?;
+        if remaining == 0 {
+            break;
+        }
+        let mut query =
+            QueryBuilder::<Sqlite>::new(if matches!(items_view, StoredTurnItemsView::Summary) {
+                r#"
+WITH page_turns AS (
+SELECT
+    turn_id,
+    rollout_ordinal,
+    status,
+    error_json,
+    started_at,
+    completed_at,
+    duration_ms,
+    first_user_item_id,
+    final_agent_item_id
+FROM thread_turns
+WHERE thread_id =
+            "#
+            } else {
+                r#"
+SELECT
+    turn_id,
+    rollout_ordinal,
+    status,
+    error_json,
+    started_at,
+    completed_at,
+    duration_ms,
+    first_user_item_id,
+    final_agent_item_id
+FROM thread_turns
+WHERE thread_id =
+            "#
+            });
+        query.push_bind(segment.rollout_id().to_string());
+        push_segment_range(&mut query, segment)?;
+        for newer_segment in &lineage.segments()[segment_index + 1..] {
+            query
+                .push(" AND NOT EXISTS (SELECT 1 FROM thread_turns AS newer_turn WHERE newer_turn.thread_id = ")
+                .push_bind(newer_segment.rollout_id().to_string())
+                .push(" AND newer_turn.turn_id = thread_turns.turn_id AND newer_turn.rollout_ordinal >= ")
+                .push_bind(sqlite_integer(newer_segment.start_ordinal())?);
+            if let Some(end_ordinal) = newer_segment.end_ordinal() {
+                query
+                    .push(" AND newer_turn.rollout_ordinal < ")
+                    .push_bind(sqlite_integer(end_ordinal)?);
+            }
+            query.push(")");
+        }
+        push_cursor_clause(&mut query, direction, segment_cursor)?;
+        push_order_and_limit(&mut query, direction, remaining);
+        if matches!(items_view, StoredTurnItemsView::Summary) {
+            query.push(
+                r#"
+)
+SELECT
+    page_turns.*,
+    first_user.turn_id AS summary_first_user_turn_id,
+    first_user.item_id AS summary_first_user_item_id,
+    first_user.rollout_ordinal AS summary_first_user_rollout_ordinal,
+    first_user.updated_at_ordinal AS summary_first_user_updated_at_ordinal,
+    first_user.created_at_ms AS summary_first_user_created_at_ms,
+    first_user.item_json AS summary_first_user_item_json,
+    final_agent.turn_id AS summary_final_agent_turn_id,
+    final_agent.item_id AS summary_final_agent_item_id,
+    final_agent.rollout_ordinal AS summary_final_agent_rollout_ordinal,
+    final_agent.updated_at_ordinal AS summary_final_agent_updated_at_ordinal,
+    final_agent.created_at_ms AS summary_final_agent_created_at_ms,
+    final_agent.item_json AS summary_final_agent_item_json
+FROM page_turns
+LEFT JOIN thread_items AS first_user
+  ON first_user.thread_id =
+                "#,
+            );
+            push_summary_item_join(&mut query, segment, "first_user", "first_user_item_id")?;
+            query.push(
+                r#"
+LEFT JOIN thread_items AS final_agent
+  ON final_agent.thread_id =
+                "#,
+            );
+            push_summary_item_join(&mut query, segment, "final_agent", "final_agent_item_id")?;
+            let order = match direction {
+                SortDirection::Asc => "ASC",
+                SortDirection::Desc => "DESC",
+            };
+            query
+                .push(" ORDER BY page_turns.rollout_ordinal ")
+                .push(order);
+        }
+        rows.extend(
+            query
+                .build()
+                .fetch_all(pool)
+                .await
+                .map_err(thread_history_error)?
+                .into_iter()
+                .map(|row| {
+                    let summary_items = if matches!(items_view, StoredTurnItemsView::Summary) {
+                        StoredSummaryColumns::from_row(&row)?.into_stored_items()?
+                    } else {
+                        Vec::new()
+                    };
+                    let mut turn = stored_turn_row(row)?;
+                    turn.summary_items = summary_items;
+                    Ok(turn)
+                })
+                .collect::<ThreadStoreResult<Vec<_>>>()?,
+        );
+    }
+    finish_page(requested_thread_id, CursorScope::Turns, rows, page_size)
+}
+
+fn push_summary_item_join(
+    query: &mut QueryBuilder<Sqlite>,
+    segment: &RolloutLineageSegment,
+    alias: &str,
+    item_id_column: &str,
+) -> ThreadStoreResult<()> {
+    query
+        .push_bind(segment.rollout_id().to_string())
+        .push(" AND ")
+        .push(alias)
+        .push(".turn_id = page_turns.turn_id AND ")
+        .push(alias)
+        .push(".item_id = page_turns.")
+        .push(item_id_column)
+        .push(" AND ")
+        .push(alias)
+        .push(".rollout_ordinal >= ")
+        .push_bind(sqlite_integer(segment.start_ordinal())?);
+    if let Some(end_ordinal) = segment.end_ordinal() {
+        query
+            .push(" AND ")
+            .push(alias)
+            .push(".rollout_ordinal < ")
+            .push_bind(sqlite_integer(end_ordinal)?);
+    }
+    Ok(())
+}
+
+pub(super) async fn page_item_rows(
+    pool: &sqlx::SqlitePool,
+    lineage: &RolloutLineage,
+    params: &ListItemsParams,
+) -> ThreadStoreResult<SegmentPage<StoredThreadItemRow>> {
+    // Update ordinals are local to a rollout. Forked lineages need a structured
+    // watermark before incremental replay can safely span their segments.
+    if params.after_updated_at_ordinal.is_some() && lineage.segments().len() > 1 {
+        return Err(ThreadStoreError::InvalidRequest {
+            message: "incremental item replay is not supported for forked threads".to_string(),
+        });
+    }
+    if matches!(params.sort_key, ItemSortKey::UpdatedAtOrdinal) {
+        let Some(after_updated_at_ordinal) = params.after_updated_at_ordinal else {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: "update-ordinal item sorting requires an update watermark".to_string(),
+            });
+        };
+        let [segment] = lineage.segments() else {
+            return Err(ThreadStoreError::Internal {
+                message: "update-ordinal item paging requires one rollout segment".to_string(),
+            });
+        };
+        return page_updated_item_rows(
+            pool,
+            segment.rollout_id(),
+            params,
+            after_updated_at_ordinal,
+        )
+        .await;
+    }
+    let cursor = parse_cursor(
+        params.cursor.as_deref(),
+        params.thread_id,
+        CursorScope::ItemsByCreatedAtOrdinal,
+    )?;
+    let mut rows = Vec::new();
+    for (_, segment, segment_cursor) in
+        segments_from_cursor(lineage, params.sort_direction, cursor.as_ref())?
+    {
+        let remaining = remaining_limit(params.page_size, rows.len())?;
+        if remaining == 0 {
+            break;
+        }
+        let mut query = QueryBuilder::<Sqlite>::new(
+            r#"
+SELECT turn_id, item_id, rollout_ordinal, updated_at_ordinal, created_at_ms, item_json
+FROM thread_items
+WHERE thread_id =
+            "#,
+        );
+        query.push_bind(segment.rollout_id().to_string());
+        push_segment_range(&mut query, segment)?;
+        if let Some(after_updated_at_ordinal) = params.after_updated_at_ordinal {
+            query
+                .push(" AND updated_at_ordinal > ")
+                .push_bind(sqlite_integer(after_updated_at_ordinal)?);
+        }
+        if let Some(turn_id) = params.turn_id.as_deref() {
+            query.push(" AND turn_id = ").push_bind(turn_id);
+        }
+        push_cursor_clause(&mut query, params.sort_direction, segment_cursor)?;
+        push_order_and_limit(&mut query, params.sort_direction, remaining);
+        rows.extend(
+            query
+                .build()
+                .fetch_all(pool)
+                .await
+                .map_err(thread_history_error)?
+                .into_iter()
+                .map(stored_thread_item_row)
+                .collect::<ThreadStoreResult<Vec<_>>>()?,
+        );
+    }
+    finish_page(
+        params.thread_id,
+        CursorScope::ItemsByCreatedAtOrdinal,
+        rows,
+        params.page_size,
+    )
+}
+
+async fn page_updated_item_rows(
+    pool: &sqlx::SqlitePool,
+    rollout_id: ThreadId,
+    params: &ListItemsParams,
+    after_updated_at_ordinal: u64,
+) -> ThreadStoreResult<SegmentPage<StoredThreadItemRow>> {
+    let cursor = parse_cursor(
+        params.cursor.as_deref(),
+        params.thread_id,
+        CursorScope::ItemsByUpdatedAtOrdinal,
+    )?;
+    let mut query = QueryBuilder::<Sqlite>::new(
+        r#"
+SELECT turn_id, item_id, updated_at_ordinal AS rollout_ordinal, updated_at_ordinal, created_at_ms, item_json
+FROM thread_items
+WHERE thread_id =
+        "#,
+    );
+    query
+        .push_bind(rollout_id.to_string())
+        .push(" AND updated_at_ordinal > ")
+        .push_bind(sqlite_integer(after_updated_at_ordinal)?);
+    if let Some(turn_id) = params.turn_id.as_deref() {
+        query.push(" AND turn_id = ").push_bind(turn_id);
+    }
+    if let Some(cursor) = cursor {
+        let comparator = match (params.sort_direction, cursor.include_anchor) {
+            (SortDirection::Asc, true) => ">=",
+            (SortDirection::Asc, false) => ">",
+            (SortDirection::Desc, true) => "<=",
+            (SortDirection::Desc, false) => "<",
+        };
+        query
+            .push(" AND updated_at_ordinal ")
+            .push(comparator)
+            .push(" ")
+            .push_bind(sqlite_integer(cursor.rollout_ordinal)?);
+    }
+    let order = match params.sort_direction {
+        SortDirection::Asc => "ASC",
+        SortDirection::Desc => "DESC",
+    };
+    query
+        .push(" ORDER BY updated_at_ordinal ")
+        .push(order)
+        .push(" LIMIT ")
+        .push_bind(remaining_limit(params.page_size, /*row_count*/ 0)?);
+    let rows = query
+        .build()
+        .fetch_all(pool)
+        .await
+        .map_err(thread_history_error)?
+        .into_iter()
+        .map(stored_thread_item_row)
+        .collect::<ThreadStoreResult<Vec<_>>>()?;
+    finish_page(
+        params.thread_id,
+        CursorScope::ItemsByUpdatedAtOrdinal,
+        rows,
+        params.page_size,
+    )
+}
+
+fn segments_from_cursor<'a>(
+    lineage: &'a RolloutLineage,
+    direction: SortDirection,
+    cursor: Option<&'a HistoryCursor>,
+) -> ThreadStoreResult<Vec<(usize, &'a RolloutLineageSegment, Option<&'a HistoryCursor>)>> {
+    let segments = lineage.segments();
+    let cursor_index = cursor
+        .map(|cursor| {
+            lineage
+                .segment_index_for_ordinal(cursor.rollout_ordinal)
+                .ok_or_else(|| invalid_cursor("position outside thread lineage"))
+        })
+        .transpose()?;
+    let indexes: Vec<usize> = match direction {
+        SortDirection::Asc => (cursor_index.unwrap_or(0)..segments.len()).collect(),
+        SortDirection::Desc => {
+            let end = cursor_index.unwrap_or_else(|| segments.len().saturating_sub(1));
+            (0..=end).rev().collect()
+        }
+    };
+    Ok(indexes
+        .into_iter()
+        .map(|index| {
+            let segment_cursor = if Some(index) == cursor_index {
+                cursor
+            } else {
+                None
+            };
+            (index, &segments[index], segment_cursor)
+        })
+        .collect())
+}
+
+fn push_segment_range(
+    query: &mut QueryBuilder<Sqlite>,
+    segment: &RolloutLineageSegment,
+) -> ThreadStoreResult<()> {
+    query
+        .push(" AND rollout_ordinal >= ")
+        .push_bind(sqlite_integer(segment.start_ordinal())?);
+    if let Some(end_ordinal) = segment.end_ordinal() {
+        query
+            .push(" AND rollout_ordinal < ")
+            .push_bind(sqlite_integer(end_ordinal)?);
+    }
+    Ok(())
+}
+
+fn push_cursor_clause(
+    query: &mut QueryBuilder<Sqlite>,
+    direction: SortDirection,
+    cursor: Option<&HistoryCursor>,
+) -> ThreadStoreResult<()> {
+    if let Some(cursor) = cursor {
+        let comparator = match (direction, cursor.include_anchor) {
+            (SortDirection::Asc, true) => ">=",
+            (SortDirection::Asc, false) => ">",
+            (SortDirection::Desc, true) => "<=",
+            (SortDirection::Desc, false) => "<",
+        };
+        query
+            .push(" AND rollout_ordinal ")
+            .push(comparator)
+            .push(" ")
+            .push_bind(sqlite_integer(cursor.rollout_ordinal)?);
+    }
+    Ok(())
+}
+
+fn push_order_and_limit(query: &mut QueryBuilder<Sqlite>, direction: SortDirection, limit: i64) {
+    let order = match direction {
+        SortDirection::Asc => "ASC",
+        SortDirection::Desc => "DESC",
+    };
+    query
+        .push(" ORDER BY rollout_ordinal ")
+        .push(order)
+        .push(" LIMIT ")
+        .push_bind(limit);
+}
+
+fn remaining_limit(page_size: usize, row_count: usize) -> ThreadStoreResult<i64> {
+    let limit = page_size
+        .checked_add(1)
+        .and_then(|limit| limit.checked_sub(row_count))
+        .ok_or_else(page_size_too_large)?;
+    i64::try_from(limit).map_err(|_| page_size_too_large())
+}
+
+fn finish_page<T: HasPosition>(
+    requested_thread_id: ThreadId,
+    scope: CursorScope,
+    mut rows: Vec<T>,
+    page_size: usize,
+) -> ThreadStoreResult<SegmentPage<T>> {
+    let has_more = rows.len() > page_size;
+    rows.truncate(page_size);
+    let backwards_cursor = rows
+        .first()
+        .map(|row| {
+            serialize_cursor(
+                requested_thread_id,
+                scope.clone(),
+                row.position().rollout_ordinal,
+                /*include_anchor*/ true,
+            )
+        })
+        .transpose()?;
+    let next_cursor = if has_more {
+        rows.last()
+            .map(|row| {
+                serialize_cursor(
+                    requested_thread_id,
+                    scope,
+                    row.position().rollout_ordinal,
+                    /*include_anchor*/ false,
+                )
+            })
+            .transpose()?
+    } else {
+        None
+    };
+    Ok(SegmentPage {
+        rows,
+        next_cursor,
+        backwards_cursor,
+    })
+}
+
+trait HasPosition {
+    fn position(&self) -> RolloutHistoryPosition;
+}
+
+impl HasPosition for StoredTurnRow {
+    fn position(&self) -> RolloutHistoryPosition {
+        self.position
+    }
+}
+
+impl HasPosition for StoredThreadItemRow {
+    fn position(&self) -> RolloutHistoryPosition {
+        self.position
+    }
+}
+
+fn sqlite_integer(value: u64) -> ThreadStoreResult<i64> {
+    i64::try_from(value).map_err(|_| ThreadStoreError::InvalidRequest {
+        message: "rollout ordinal exceeds SQLite integer range".to_string(),
+    })
+}
+
+fn page_size_too_large() -> ThreadStoreError {
+    ThreadStoreError::InvalidRequest {
+        message: "page size is too large".to_string(),
+    }
+}
diff --git a/codex-rs/thread-store/src/local/thread_history/turn_lookup.rs b/codex-rs/thread-store/src/local/thread_history/turn_lookup.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7fe20d68098024641cb5843d7d07a58739175bf1
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history/turn_lookup.rs
@@ -0,0 +1,100 @@
+use codex_protocol::ThreadId;
+use sqlx::Row;
+
+use super::super::rollout_lineage::RolloutLineage;
+use super::super::rollout_lineage::RolloutLineageSegment;
+use super::sqlite_integer;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+pub(in crate::local) struct TurnRow {
+    pub rollout_id: ThreadId,
+    pub rollout_ordinal: i64,
+    pub rollout_byte_offset: Option<i64>,
+    pub rollout_end_ordinal: Option<i64>,
+    pub rollout_end_byte_offset: Option<i64>,
+    pub status: String,
+    pub first_user_item_id: Option<String>,
+    pub final_agent_item_id: Option<String>,
+}
+
+pub(in crate::local) async fn find_source_turn(
+    pool: &sqlx::SqlitePool,
+    lineage: &RolloutLineage,
+    turn_id: &str,
+) -> ThreadStoreResult<TurnRow> {
+    find_turn(pool, lineage.segments().iter(), turn_id).await
+}
+
+pub(in crate::local) async fn find_visible_turn(
+    pool: &sqlx::SqlitePool,
+    lineage: &RolloutLineage,
+    turn_id: &str,
+) -> ThreadStoreResult<TurnRow> {
+    find_turn(pool, lineage.segments().iter().rev(), turn_id).await
+}
+
+async fn find_turn<'a>(
+    pool: &sqlx::SqlitePool,
+    segments: impl Iterator<Item = &'a RolloutLineageSegment>,
+    turn_id: &str,
+) -> ThreadStoreResult<TurnRow> {
+    for segment in segments {
+        if let Some(row) = query_turn_row(pool, segment, turn_id).await? {
+            return Ok(row);
+        }
+    }
+    Err(ThreadStoreError::InvalidRequest {
+        message: format!("turn not found: {turn_id}"),
+    })
+}
+
+async fn query_turn_row(
+    pool: &sqlx::SqlitePool,
+    segment: &RolloutLineageSegment,
+    turn_id: &str,
+) -> ThreadStoreResult<Option<TurnRow>> {
+    let end_ordinal = segment
+        .end_ordinal()
+        .map(|ordinal| sqlite_integer(ordinal, "rollout ordinal"))
+        .transpose()?;
+    sqlx::query(
+        r#"
+SELECT
+    rollout_ordinal,
+    rollout_byte_offset,
+    rollout_end_ordinal,
+    rollout_end_byte_offset,
+    status,
+    first_user_item_id,
+    final_agent_item_id
+FROM thread_turns
+WHERE thread_id = ?
+  AND turn_id = ?
+  AND rollout_ordinal >= ?
+  AND (? IS NULL OR rollout_ordinal < ?)
+        "#,
+    )
+    .bind(segment.rollout_id().to_string())
+    .bind(turn_id)
+    .bind(sqlite_integer(segment.start_ordinal(), "rollout ordinal")?)
+    .bind(end_ordinal)
+    .bind(end_ordinal)
+    .fetch_optional(pool)
+    .await
+    .map_err(|err| ThreadStoreError::Internal {
+        message: format!("failed to resolve logical turn: {err}"),
+    })
+    .map(|row| {
+        row.map(|row| TurnRow {
+            rollout_id: segment.rollout_id(),
+            rollout_ordinal: row.get("rollout_ordinal"),
+            rollout_byte_offset: row.get("rollout_byte_offset"),
+            rollout_end_ordinal: row.get("rollout_end_ordinal"),
+            rollout_end_byte_offset: row.get("rollout_end_byte_offset"),
+            status: row.get("status"),
+            first_user_item_id: row.get("first_user_item_id"),
+            final_agent_item_id: row.get("final_agent_item_id"),
+        })
+    })
+}
diff --git a/codex-rs/thread-store/src/local/thread_history_materialization.rs b/codex-rs/thread-store/src/local/thread_history_materialization.rs
new file mode 100644
index 0000000000000000000000000000000000000000..34eeede51b4169b0fc4978b2501a8216bcea9983
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history_materialization.rs
@@ -0,0 +1,366 @@
+use std::io::SeekFrom;
+use std::path::Path;
+
+use chrono::DateTime;
+use codex_app_server_protocol::ThreadHistoryChangeSet;
+use codex_app_server_protocol::project_rollout_line;
+use codex_protocol::ThreadId;
+use codex_rollout::RolloutItem;
+use tokio::io::AsyncReadExt;
+use tokio::io::AsyncSeekExt;
+use tracing::warn;
+
+use super::LocalThreadStore;
+use super::thread_history::ProjectedRolloutLine;
+use super::thread_history::RolloutProjectionStep;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+const SQLITE_PROJECTION_METRIC: &str = "codex.thread_history.sqlite_projection";
+const SQLITE_PROJECTION_ANOMALY_METRIC: &str = "codex.thread_history.sqlite_projection.anomaly";
+
+pub(super) async fn materialize_to_sqlite(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    rollout_path: &Path,
+) -> ThreadStoreResult<()> {
+    if store.state_db.is_none() {
+        return Ok(());
+    }
+    let result = materialize_to_sqlite_with_state_db(store, thread_id, rollout_path).await;
+    record_projection_outcome(&result);
+    result
+}
+
+async fn materialize_to_sqlite_with_state_db(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    rollout_path: &Path,
+) -> ThreadStoreResult<()> {
+    let projection_state = super::thread_history::projection_state(store, thread_id).await?;
+    let start_offset = projection_state
+        .as_ref()
+        .map_or(0, |state| state.next_byte_offset);
+    if projection_state.is_none()
+        && codex_rollout::existing_rollout_path(rollout_path)
+            .await
+            .is_none()
+    {
+        return Ok(());
+    }
+    let session_meta = codex_rollout::read_session_meta_line(rollout_path)
+        .await
+        .map_err(thread_store_io_error)?
+        .meta;
+    let initial_ordinal = session_meta
+        .history_base
+        .map_or(0, |base| base.end_ordinal_exclusive);
+    let subagent_history_start_ordinal = session_meta.subagent_history_start_ordinal;
+    let expected_ordinal = projection_state
+        .as_ref()
+        .map_or(initial_ordinal, |state| state.next_ordinal);
+    let (projections, next_offset) = read_projection_steps(
+        rollout_path,
+        start_offset,
+        expected_ordinal,
+        thread_id,
+        subagent_history_start_ordinal,
+    )
+    .await?;
+    // Empty valid records can still consume bytes through blank complete lines.
+    if projections.is_empty() && start_offset == next_offset {
+        return Ok(());
+    }
+    super::thread_history::apply_projection(
+        store,
+        thread_id,
+        start_offset,
+        next_offset,
+        initial_ordinal,
+        projections,
+    )
+    .await
+}
+
+async fn read_projection_steps(
+    rollout_path: &Path,
+    start_offset: u64,
+    expected_ordinal: u64,
+    thread_id: ThreadId,
+    subagent_history_start_ordinal: Option<u64>,
+) -> ThreadStoreResult<(Vec<RolloutProjectionStep>, u64)> {
+    let path = rollout_path.to_path_buf();
+    let file =
+        tokio::task::spawn_blocking(move || codex_rollout::open_rollout_seekable_reader(&path))
+            .await
+            .map_err(|err| ThreadStoreError::Internal {
+                message: format!("failed to join rollout projection read: {err}"),
+            })?;
+    let mut file = match file {
+        Ok(file) => tokio::fs::File::from_std(file),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound && start_offset == 0 => {
+            return Ok((Vec::new(), 0));
+        }
+        Err(err) => return Err(thread_store_io_error(err)),
+    };
+    let file_end_offset = file.metadata().await.map_err(thread_store_io_error)?.len();
+    let byte_count =
+        file_end_offset
+            .checked_sub(start_offset)
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: "durable rollout shrank before projection".to_string(),
+            })?;
+    let byte_count = usize::try_from(byte_count).map_err(|_| ThreadStoreError::Internal {
+        message: "durable rollout append exceeds addressable memory".to_string(),
+    })?;
+    let mut bytes = vec![0; byte_count];
+    file.seek(SeekFrom::Start(start_offset))
+        .await
+        .map_err(thread_store_io_error)?;
+    file.read_exact(bytes.as_mut_slice())
+        .await
+        .map_err(thread_store_io_error)?;
+    // Only project the newline-terminated prefix; leave a trailing partial record for the next
+    // pass.
+    let complete_byte_count = bytes
+        .iter()
+        .rposition(|byte| *byte == b'\n')
+        .map_or(0, |index| index + 1);
+    let mut projections = Vec::new();
+    let mut next_ordinal = expected_ordinal;
+    let mut next_offset = start_offset;
+    let mut line_start_offset = start_offset;
+    for line_bytes in bytes[..complete_byte_count].split_inclusive(|byte| *byte == b'\n') {
+        let line_end_offset = line_start_offset
+            .checked_add(u64::try_from(line_bytes.len()).map_err(|_| {
+                ThreadStoreError::Internal {
+                    message: "durable rollout byte offset overflow".to_string(),
+                }
+            })?)
+            .ok_or_else(|| ThreadStoreError::Internal {
+                message: "durable rollout byte offset overflow".to_string(),
+            })?;
+        if line_bytes.iter().all(u8::is_ascii_whitespace) {
+            next_offset = line_end_offset;
+            line_start_offset = line_end_offset;
+            continue;
+        }
+        let value = match serde_json::from_slice::<serde_json::Value>(line_bytes) {
+            Ok(value) => value,
+            Err(err) => {
+                warn!(
+                    thread_id = %thread_id,
+                    rollout_path = %rollout_path.display(),
+                    line_start_byte_offset = line_start_offset,
+                    line_end_byte_offset = line_end_offset,
+                    expected_ordinal = next_ordinal,
+                    error = %err,
+                    "skipping malformed rollout line during projection"
+                );
+                record_projection_anomaly(ProjectionAnomaly::MalformedJson);
+                next_offset = line_end_offset;
+                line_start_offset = line_end_offset;
+                continue;
+            }
+        };
+        let raw_ordinal = value.get("ordinal").and_then(serde_json::Value::as_u64);
+        let line = match codex_rollout::decode_rollout_line(value) {
+            Ok(line) => line,
+            Err(err) => {
+                warn!(
+                    thread_id = %thread_id,
+                    rollout_path = %rollout_path.display(),
+                    line_start_byte_offset = line_start_offset,
+                    line_end_byte_offset = line_end_offset,
+                    expected_ordinal = next_ordinal,
+                    line_ordinal = ?raw_ordinal,
+                    error = %err,
+                    "skipping unknown rollout line during projection"
+                );
+                record_projection_anomaly(ProjectionAnomaly::UnknownLine);
+                // Unknown records only advance the byte checkpoint. A writer that could not
+                // decode this line may have reused its ordinal, so let the next decoded line
+                // resolve reuse versus a gap.
+                next_offset = line_end_offset;
+                line_start_offset = line_end_offset;
+                continue;
+            }
+        };
+        let ordinal = match line.ordinal {
+            Some(ordinal) => ordinal,
+            None => {
+                warn!(
+                    thread_id = %thread_id,
+                    rollout_path = %rollout_path.display(),
+                    line_start_byte_offset = line_start_offset,
+                    line_end_byte_offset = line_end_offset,
+                    expected_ordinal = next_ordinal,
+                    "skipping paginated rollout line without an ordinal"
+                );
+                record_projection_anomaly(ProjectionAnomaly::MissingOrdinal);
+                next_offset = line_end_offset;
+                line_start_offset = line_end_offset;
+                continue;
+            }
+        };
+        if ordinal < next_ordinal {
+            warn!(
+                thread_id = %thread_id,
+                rollout_path = %rollout_path.display(),
+                line_start_byte_offset = line_start_offset,
+                line_end_byte_offset = line_end_offset,
+                expected_ordinal = next_ordinal,
+                line_ordinal = ordinal,
+                "skipping duplicate or regressed rollout ordinal during projection"
+            );
+            record_projection_anomaly(ProjectionAnomaly::DuplicateOrRegressedOrdinal);
+            next_offset = line_end_offset;
+            line_start_offset = line_end_offset;
+            continue;
+        }
+        let is_inherited_subagent_history =
+            subagent_history_start_ordinal.is_some_and(|start| ordinal < start);
+        let changes = if is_inherited_subagent_history {
+            ThreadHistoryChangeSet::default()
+        } else {
+            project_rollout_line(&line)
+        };
+        let fallback_created_at_ms = if changes
+            .changed_items
+            .iter()
+            .any(|item| item.started_at_ms.is_none())
+            || (!is_inherited_subagent_history
+                && matches!(&line.item, RolloutItem::RealtimeItem(_)))
+        {
+            match DateTime::parse_from_rfc3339(line.timestamp.as_str()) {
+                Ok(timestamp) => Some(timestamp.timestamp_millis()),
+                Err(err) => {
+                    warn!(
+                        thread_id = %thread_id,
+                        rollout_path = %rollout_path.display(),
+                        line_start_byte_offset = line_start_offset,
+                        line_end_byte_offset = line_end_offset,
+                        expected_ordinal = next_ordinal,
+                        line_ordinal = ordinal,
+                        error = %err,
+                        "skipping rollout line with invalid timestamp during projection"
+                    );
+                    record_projection_anomaly(ProjectionAnomaly::InvalidTimestamp);
+                    let end_ordinal_exclusive =
+                        ordinal
+                            .checked_add(1)
+                            .ok_or_else(|| ThreadStoreError::Internal {
+                                message: "rollout ordinal exceeds SQLite integer range".to_string(),
+                            })?;
+                    projections.push(RolloutProjectionStep::SkippedOrdinalRange {
+                        start_ordinal: next_ordinal,
+                        end_ordinal_exclusive,
+                    });
+                    next_ordinal = end_ordinal_exclusive;
+                    next_offset = line_end_offset;
+                    line_start_offset = line_end_offset;
+                    continue;
+                }
+            }
+        } else {
+            None
+        };
+        if ordinal > next_ordinal {
+            warn!(
+                thread_id = %thread_id,
+                rollout_path = %rollout_path.display(),
+                line_start_byte_offset = line_start_offset,
+                line_end_byte_offset = line_end_offset,
+                expected_ordinal = next_ordinal,
+                line_ordinal = ordinal,
+                skipped_ordinal_start = next_ordinal,
+                skipped_ordinal_end_exclusive = ordinal,
+                "skipping missing rollout ordinal range during projection"
+            );
+            record_projection_anomaly(ProjectionAnomaly::ForwardOrdinalGap);
+            projections.push(RolloutProjectionStep::SkippedOrdinalRange {
+                start_ordinal: next_ordinal,
+                end_ordinal_exclusive: ordinal,
+            });
+        }
+        let next_line_ordinal =
+            ordinal
+                .checked_add(1)
+                .ok_or_else(|| ThreadStoreError::Internal {
+                    message: "rollout ordinal exceeds SQLite integer range".to_string(),
+                })?;
+        projections.push(RolloutProjectionStep::Line(Box::new(
+            ProjectedRolloutLine {
+                ordinal,
+                start_byte_offset: line_start_offset,
+                end_byte_offset: line_end_offset,
+                fallback_created_at_ms,
+                changes,
+                realtime_item: match line.item {
+                    RolloutItem::RealtimeItem(item) if !is_inherited_subagent_history => Some(item),
+                    _ => None,
+                },
+            },
+        )));
+        next_ordinal = next_line_ordinal;
+        next_offset = line_end_offset;
+        line_start_offset = line_end_offset;
+    }
+    Ok((projections, next_offset))
+}
+
+#[derive(Clone, Copy)]
+enum ProjectionAnomaly {
+    MalformedJson,
+    UnknownLine,
+    MissingOrdinal,
+    DuplicateOrRegressedOrdinal,
+    ForwardOrdinalGap,
+    InvalidTimestamp,
+}
+
+impl ProjectionAnomaly {
+    fn tag(self) -> &'static str {
+        match self {
+            Self::MalformedJson => "malformed_json",
+            Self::UnknownLine => "unknown_line",
+            Self::MissingOrdinal => "missing_ordinal",
+            Self::DuplicateOrRegressedOrdinal => "duplicate_or_regressed_ordinal",
+            Self::ForwardOrdinalGap => "forward_ordinal_gap",
+            Self::InvalidTimestamp => "invalid_timestamp",
+        }
+    }
+}
+
+fn record_projection_outcome(result: &ThreadStoreResult<()>) {
+    let Some(metrics) = codex_otel::global() else {
+        return;
+    };
+    let outcome = if result.is_ok() { "success" } else { "error" };
+    let _ = metrics.counter(
+        SQLITE_PROJECTION_METRIC,
+        /*inc*/ 1,
+        &[("outcome", outcome)],
+    );
+}
+
+fn record_projection_anomaly(anomaly: ProjectionAnomaly) {
+    let Some(metrics) = codex_otel::global() else {
+        return;
+    };
+    let _ = metrics.counter(
+        SQLITE_PROJECTION_ANOMALY_METRIC,
+        /*inc*/ 1,
+        &[("kind", anomaly.tag())],
+    );
+}
+
+fn thread_store_io_error(err: std::io::Error) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: err.to_string(),
+    }
+}
+
+#[cfg(test)]
+#[path = "thread_history_materialization_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/thread_history_materialization_tests.rs b/codex-rs/thread-store/src/local/thread_history_materialization_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3f6fcbf6158e730135019e4f674f69d104e7bef0
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_history_materialization_tests.rs
@@ -0,0 +1,2738 @@
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+use std::time::Duration;
+
+use chrono::Utc;
+use codex_app_server_protocol::ThreadItem;
+use codex_protocol::ThreadId;
+use codex_protocol::items::AgentMessageContent;
+use codex_protocol::items::AgentMessageItem;
+use codex_protocol::items::TurnItem;
+use codex_protocol::items::UserMessageItem;
+use codex_protocol::models::BaseInstructions;
+use codex_protocol::models::ContentItem;
+use codex_protocol::models::MessagePhase;
+use codex_protocol::models::ResponseItem;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::ItemCompletedEvent;
+use codex_protocol::protocol::RateLimitSnapshot;
+use codex_protocol::protocol::RateLimitWindow;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_protocol::protocol::TokenCountEvent;
+use codex_protocol::protocol::TurnCompleteEvent;
+use codex_protocol::protocol::TurnStartedEvent;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_protocol::realtime::BemItemPresentation;
+use codex_protocol::realtime::RealtimeItem;
+use codex_protocol::realtime::RealtimeItemContent;
+use codex_protocol::realtime::RealtimeSessionOutcome;
+use codex_protocol::realtime::RealtimeTranscriptRole;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutLine;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::RolloutRecorderParams;
+use codex_utils_absolute_path::test_support::PathExt;
+use pretty_assertions::assert_eq;
+use tempfile::TempDir;
+
+use super::super::LocalThreadStore;
+use super::super::LocalThreadStoreConfig;
+use super::super::test_support::test_config;
+use crate::AppendThreadItemsParams;
+use crate::CreateThreadParams;
+use crate::DeleteThreadParams;
+use crate::ForkBoundary;
+use crate::ListThreadsParams;
+use crate::ListTurnsParams;
+use crate::PersistContext;
+use crate::PrepareForkParams;
+use crate::PreparedFork;
+use crate::ResumeThreadParams;
+use crate::SortDirection;
+use crate::StoredTurnItemsView;
+use crate::StoredTurnStatus;
+use crate::ThreadPersistenceMetadata;
+use crate::ThreadSortKey;
+use crate::ThreadStore;
+
+#[tokio::test]
+async fn paginated_history_without_state_db_does_not_initialize_sqlite() {
+    let home = TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let sqlite = config.sqlite.clone();
+    let store = LocalThreadStore::new(config, /*state_db*/ None);
+    let thread_id = ThreadId::default();
+
+    assert!(!store.supports_paginated_history_lists());
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect("append paginated rollout");
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist paginated rollout");
+    store
+        .flush_thread(thread_id)
+        .await
+        .expect("flush paginated rollout");
+    store
+        .shutdown_thread(thread_id)
+        .await
+        .expect("shutdown paginated rollout");
+
+    for runtime_db in sqlite.runtime_db_paths() {
+        assert!(
+            !runtime_db.path.exists(),
+            "expected no SQLite initialization for {}",
+            runtime_db.path.display()
+        );
+    }
+}
+
+/// Separate Codex and SQLite homes must work together across startup backfill,
+/// thread listing, and projection-backed paginated history reads.
+#[tokio::test]
+async fn split_homes_support_backfill_listing_and_paginated_history() {
+    let root = TempDir::new().expect("temp dir");
+    let codex_home = root.path().join("codex");
+    let sqlite_home = root.path().join("sqlite");
+    let thread_id = ThreadId::new();
+    let sqlite = codex_state::SqliteConfig::new_for_testing(sqlite_home.as_path().abs());
+    let rollout_config = RolloutConfig {
+        codex_home: codex_home.clone(),
+        sqlite: sqlite.clone(),
+        cwd: codex_home.clone(),
+        model_provider_id: "test-provider".to_string(),
+        generate_memories: false,
+    };
+    let recorder = RolloutRecorder::new(
+        &rollout_config,
+        RolloutRecorderParams::new(
+            thread_id,
+            /*forked_from_id*/ None,
+            /*parent_thread_id*/ None,
+            SessionSource::Exec,
+            /*thread_source*/ None,
+            "test-originator".to_string(),
+            BaseInstructions::default(),
+            Vec::new(),
+        )
+        .with_history_mode(ThreadHistoryMode::Paginated)
+        .with_initial_window_id("window-1".to_string()),
+    )
+    .await
+    .expect("create paginated rollout");
+    recorder
+        .record_canonical_items(&[RolloutItem::EventMsg(EventMsg::UserMessage(
+            UserMessageEvent {
+                message: "existing thread".to_string(),
+                ..Default::default()
+            },
+        ))])
+        .await
+        .expect("record existing user message");
+    recorder.persist().await.expect("persist paginated rollout");
+    let rollout_path = recorder.rollout_path().to_path_buf();
+    recorder.shutdown().await.expect("close paginated rollout");
+
+    let runtime = codex_rollout::state_db::try_init(&rollout_config)
+        .await
+        .expect("backfill state from Codex home");
+    assert!(
+        runtime
+            .get_thread(thread_id)
+            .await
+            .expect("read backfilled thread")
+            .is_some(),
+        "startup backfill should index the rollout"
+    );
+    let store = LocalThreadStore::new(
+        LocalThreadStoreConfig::from_config(&rollout_config),
+        Some(runtime),
+    );
+
+    let threads = store
+        .list_threads(ListThreadsParams {
+            page_size: 10,
+            cursor: None,
+            sort_key: ThreadSortKey::CreatedAt,
+            sort_direction: SortDirection::Desc,
+            allowed_sources: Vec::new(),
+            model_providers: None,
+            cwd_filters: None,
+            archived: false,
+            search_term: None,
+            relation_filter: None,
+            section: None,
+            project_id: None,
+            use_state_db_only: true,
+        })
+        .await
+        .expect("list backfilled threads");
+    assert_eq!(threads.items.len(), 1);
+    assert_eq!(
+        (
+            threads.items[0].thread_id,
+            threads.items[0].rollout_path.as_deref(),
+            threads.items[0].history_mode,
+        ),
+        (
+            thread_id,
+            Some(rollout_path.as_path()),
+            ThreadHistoryMode::Paginated,
+        )
+    );
+
+    store
+        .resume_thread(ResumeThreadParams {
+            thread_id,
+            rollout_path: Some(rollout_path),
+            history: None,
+            include_archived: false,
+            metadata: ThreadPersistenceMetadata {
+                cwd: Some(codex_home.clone()),
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        })
+        .await
+        .expect("resume backfilled thread");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-1"),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "user-1".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::AgentMessage(AgentMessageItem {
+                        id: "agent-1".to_string(),
+                        content: vec![AgentMessageContent::Text {
+                            text: "done".to_string(),
+                        }],
+                        phase: None,
+                        memory_citation: None,
+                        delivery: None,
+                        questions: None,
+                    }),
+                ),
+                turn_completed("turn-1"),
+            ],
+        })
+        .await
+        .expect("append paginated history");
+
+    let turns = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 10,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("list paginated history");
+    assert_eq!(
+        turns
+            .turns
+            .iter()
+            .map(|turn| {
+                (
+                    turn.turn_id.as_str(),
+                    turn.status,
+                    turn.items
+                        .iter()
+                        .map(|item| item.item_id.as_str())
+                        .collect::<Vec<_>>(),
+                )
+            })
+            .collect::<Vec<_>>(),
+        vec![(
+            "turn-1",
+            StoredTurnStatus::Completed,
+            vec!["user-1", "agent-1"],
+        )]
+    );
+
+    let state_db_path = sqlite.state_db_path();
+    let thread_history_db_path = sqlite.thread_history_db_path();
+    for sqlite_path in [&state_db_path, &thread_history_db_path] {
+        assert!(
+            sqlite_path.exists(),
+            "expected SQLite database at {}",
+            sqlite_path.display()
+        );
+        let filename = sqlite_path.file_name().expect("SQLite database filename");
+        assert!(
+            !codex_home.join(filename).exists(),
+            "SQLite database should not be created under Codex home"
+        );
+    }
+}
+
+#[tokio::test]
+async fn paginated_live_append_materializes_turn_items_and_state() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-1"),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "user-1".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::AgentMessage(AgentMessageItem {
+                        id: "agent-1".to_string(),
+                        content: vec![AgentMessageContent::Text {
+                            text: "done".to_string(),
+                        }],
+                        phase: None,
+                        memory_citation: None,
+                        delivery: None,
+                        questions: None,
+                    }),
+                ),
+                turn_completed("turn-1"),
+            ],
+        })
+        .await
+        .expect("append paginated items");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let (turn_start_byte_offset, _) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 1);
+    let (_, turn_end_byte_offset) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 4);
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let turn = sqlx::query_as::<
+        _,
+        (
+            i64,
+            Option<i64>,
+            Option<i64>,
+            Option<i64>,
+            String,
+            Option<i64>,
+            Option<i64>,
+            Option<i64>,
+            Option<String>,
+            Option<String>,
+        ),
+    >(
+        r#"
+SELECT
+    rollout_ordinal,
+    rollout_byte_offset,
+    rollout_end_ordinal,
+    rollout_end_byte_offset,
+    status,
+    started_at,
+    completed_at,
+    duration_ms,
+    first_user_item_id,
+    final_agent_item_id
+FROM thread_turns
+WHERE thread_id = ? AND turn_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected turn");
+    assert_eq!(
+        turn,
+        (
+            1,
+            Some(turn_start_byte_offset),
+            Some(4),
+            Some(turn_end_byte_offset),
+            "completed".to_string(),
+            Some(10),
+            Some(20),
+            Some(10_000),
+            Some("user-1".to_string()),
+            Some("agent-1".to_string()),
+        )
+    );
+
+    let items = sqlx::query_as::<_, (String, i64)>(
+        r#"
+SELECT item_id, rollout_ordinal
+FROM thread_items
+WHERE thread_id = ?
+ORDER BY rollout_ordinal
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read projected items");
+    assert_eq!(
+        items,
+        vec![("user-1".to_string(), 2), ("agent-1".to_string(), 3)]
+    );
+
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    let projection_state = sqlx::query_as::<_, (i64, i64)>(
+        r#"
+SELECT next_rollout_byte_offset, next_rollout_ordinal
+FROM thread_history_projection_state
+WHERE thread_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .fetch_one(&pool)
+    .await
+    .expect("read projection state");
+    assert_eq!(projection_state, (rollout_len, 5));
+}
+
+#[tokio::test]
+async fn paginated_realtime_items_materialize_separately_in_rollout_order() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist thread metadata");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                RolloutItem::RealtimeItem(RealtimeItem {
+                    id: "voice:started".to_string(),
+                    realtime_session_id: "voice".to_string(),
+                    content: RealtimeItemContent::RealtimeSessionStarted,
+                }),
+                RolloutItem::RealtimeItem(RealtimeItem {
+                    id: "voice:transcript:0".to_string(),
+                    realtime_session_id: "voice".to_string(),
+                    content: RealtimeItemContent::TranscriptSegment {
+                        role: RealtimeTranscriptRole::Assistant,
+                        text: "Here is the result.".to_string(),
+                    },
+                }),
+                turn_started("turn-1"),
+                RolloutItem::RealtimeItem(RealtimeItem {
+                    id: "voice:promoted:agent-1".to_string(),
+                    realtime_session_id: "voice".to_string(),
+                    content: RealtimeItemContent::BemItemPromoted {
+                        turn_id: "turn-1".to_string(),
+                        item_id: "agent-1".to_string(),
+                        presentation: BemItemPresentation::InlineMarkdown,
+                    },
+                }),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::AgentMessage(AgentMessageItem {
+                        id: "agent-1".to_string(),
+                        content: vec![AgentMessageContent::Text {
+                            text: "Result".to_string(),
+                        }],
+                        phase: None,
+                        memory_citation: None,
+                        delivery: None,
+                        questions: None,
+                    }),
+                ),
+                RolloutItem::RealtimeItem(RealtimeItem {
+                    id: "voice:closed".to_string(),
+                    realtime_session_id: "voice".to_string(),
+                    content: RealtimeItemContent::RealtimeSessionClosed {
+                        outcome: RealtimeSessionOutcome::Ended,
+                    },
+                }),
+            ],
+        })
+        .await
+        .expect("append interleaved realtime and ordinary rollout items");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let expected_rows = fs::read_to_string(rollout_path.as_path())
+        .expect("read canonical rollout")
+        .lines()
+        .map(|line| codex_rollout::parse_rollout_line(line).expect("parse rollout line"))
+        .filter_map(|line| match line.item {
+            RolloutItem::RealtimeItem(item) => Some((
+                item.id,
+                i64::try_from(line.ordinal.expect("paginated rollout ordinal"))
+                    .expect("ordinal fits SQLite integer"),
+                chrono::DateTime::parse_from_rfc3339(line.timestamp.as_str())
+                    .expect("valid rollout timestamp")
+                    .timestamp_millis(),
+                serde_json::to_value(item.content)
+                    .expect("serialize realtime content")
+                    .get("type")
+                    .and_then(serde_json::Value::as_str)
+                    .expect("realtime content discriminator")
+                    .to_string(),
+            )),
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+    assert_eq!(
+        expected_rows
+            .iter()
+            .map(|(id, ordinal, _, item_type)| (id.as_str(), *ordinal, item_type.as_str()))
+            .collect::<Vec<_>>(),
+        vec![
+            ("voice:started", 1, "realtime_session_started"),
+            ("voice:transcript:0", 2, "transcript_segment"),
+            ("voice:promoted:agent-1", 4, "bem_item_promoted"),
+            ("voice:closed", 6, "realtime_session_closed"),
+        ]
+    );
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let projected_rows = sqlx::query_as::<_, (String, i64, i64, String)>(
+        "SELECT item_id, rollout_ordinal, created_at_ms, item_type FROM thread_realtime_items WHERE thread_id = ? ORDER BY rollout_ordinal",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read separately projected realtime items");
+    assert_eq!(projected_rows, expected_rows);
+
+    let ordinary_items = sqlx::query_as::<_, (String, String)>(
+        "SELECT turn_id, item_id FROM thread_items WHERE thread_id = ? ORDER BY rollout_ordinal",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read ordinary turn items");
+    assert_eq!(
+        ordinary_items,
+        vec![("turn-1".to_string(), "agent-1".to_string())]
+    );
+
+    sqlx::query("DELETE FROM thread_history_projection_state WHERE thread_id = ?")
+        .bind(thread_id.to_string())
+        .execute(&pool)
+        .await
+        .expect("rewind projection checkpoint");
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("replay canonical rollout");
+
+    let replayed_rows = sqlx::query_as::<_, (String, i64, i64, String)>(
+        "SELECT item_id, rollout_ordinal, created_at_ms, item_type FROM thread_realtime_items WHERE thread_id = ? ORDER BY rollout_ordinal",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read replayed realtime items");
+    assert_eq!(replayed_rows, expected_rows);
+
+    let legacy_thread_id = ThreadId::new();
+    store
+        .create_thread(CreateThreadParams {
+            session_id: legacy_thread_id.into(),
+            thread_id: legacy_thread_id,
+            extra_config: None,
+            forked_from_id: None,
+            parent_thread_id: None,
+            source: SessionSource::Exec,
+            thread_source: None,
+            originator: "test_originator".to_string(),
+            base_instructions: BaseInstructions::default(),
+            dynamic_tools: Vec::new(),
+            selected_capability_roots: Vec::new(),
+            multi_agent_version: None,
+            history_mode: ThreadHistoryMode::Legacy,
+            history_base: None,
+            subagent_history_start_ordinal: None,
+            initial_window_id: "window-1".to_string(),
+            runtime_workspace_roots: None,
+            metadata: ThreadPersistenceMetadata {
+                cwd: Some(home.path().to_path_buf()),
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        })
+        .await
+        .expect("create legacy thread");
+    store
+        .persist_thread(legacy_thread_id, PersistContext::Standard)
+        .await
+        .expect("persist legacy thread metadata");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: legacy_thread_id,
+            items: vec![RolloutItem::RealtimeItem(RealtimeItem {
+                id: "legacy:started".to_string(),
+                realtime_session_id: "legacy".to_string(),
+                content: RealtimeItemContent::RealtimeSessionStarted,
+            })],
+        })
+        .await
+        .expect("ignore realtime item for legacy rollout");
+    let legacy_rollout_path = store
+        .live_rollout_path(legacy_thread_id)
+        .await
+        .expect("legacy rollout path");
+    let (legacy_items, _, _) = RolloutRecorder::load_rollout_items(legacy_rollout_path.as_path())
+        .await
+        .expect("load legacy rollout");
+    assert!(
+        !legacy_items
+            .iter()
+            .any(|item| matches!(item, RolloutItem::RealtimeItem(_)))
+    );
+    let legacy_realtime_count = sqlx::query_scalar::<_, i64>(
+        "SELECT COUNT(*) FROM thread_realtime_items WHERE thread_id = ?",
+    )
+    .bind(legacy_thread_id.to_string())
+    .fetch_one(&pool)
+    .await
+    .expect("count legacy realtime items");
+    assert_eq!(legacy_realtime_count, 0);
+}
+
+#[tokio::test]
+async fn referenced_paginated_rollout_projects_inherited_ordinal_range() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let source_id = ThreadId::default();
+    create_paginated_thread(&store, source_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: source_id,
+            items: vec![
+                turn_started("source-turn"),
+                user_message("source message"),
+                turn_completed("source-turn"),
+            ],
+        })
+        .await
+        .expect("append source history");
+    let source_path = store
+        .live_rollout_path(source_id)
+        .await
+        .expect("source rollout path");
+    let (_, source_end_byte_offset) =
+        rollout_line_byte_offsets(source_path.as_path(), /*ordinal*/ 3);
+    let child_id = ThreadId::default();
+    let history_base = HistoryPosition {
+        thread_id: source_id,
+        end_ordinal_exclusive: 4,
+        end_byte_offset: u64::try_from(source_end_byte_offset).expect("source byte offset"),
+    };
+    create_paginated_subagent_thread(
+        &store,
+        child_id,
+        Some(history_base),
+        /*subagent_history_start_ordinal*/ None,
+    )
+    .await;
+    store
+        .persist_thread(child_id, PersistContext::Standard)
+        .await
+        .expect("persist child metadata");
+    assert_eq!(
+        prepare_paginated_fork(&store, child_id, ForkBoundary::Latest)
+            .await
+            .history_base,
+        Some(history_base)
+    );
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: child_id,
+            items: vec![
+                turn_started("child-turn"),
+                user_message("child message"),
+                turn_completed("child-turn"),
+            ],
+        })
+        .await
+        .expect("append child history");
+    let latest_history_base = prepare_paginated_fork(&store, child_id, ForkBoundary::Latest)
+        .await
+        .history_base;
+    for (boundary, expected_base) in [
+        (ForkBoundary::Latest, latest_history_base),
+        (
+            ForkBoundary::ThroughTurn("source-turn".to_string()),
+            Some(history_base),
+        ),
+        (
+            ForkBoundary::BeforeTurn("child-turn".to_string()),
+            Some(history_base),
+        ),
+        (
+            ForkBoundary::ThroughTurn("child-turn".to_string()),
+            latest_history_base,
+        ),
+        (ForkBoundary::BeforeTurn("source-turn".to_string()), None),
+    ] {
+        let prepared = prepare_paginated_fork(&store, child_id, boundary).await;
+        assert_eq!(prepared.history_base, expected_base);
+        assert!(matches!(
+            prepared.model_context.first(),
+            Some(RolloutItem::SessionMeta(meta)) if meta.meta.id == child_id
+        ));
+        assert_eq!(
+            contains_user_message(&prepared.model_context, "source message"),
+            expected_base.is_some()
+        );
+        assert_eq!(
+            contains_user_message(&prepared.model_context, "child message"),
+            expected_base == latest_history_base
+        );
+    }
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let turn_ordinal = sqlx::query_scalar::<_, i64>(
+        "SELECT rollout_ordinal FROM thread_turns WHERE thread_id = ? AND turn_id = ?",
+    )
+    .bind(child_id.to_string())
+    .bind("child-turn")
+    .fetch_one(&pool)
+    .await
+    .expect("read child turn ordinal");
+    let next_ordinal = sqlx::query_scalar::<_, i64>(
+        "SELECT next_rollout_ordinal FROM thread_history_projection_state WHERE thread_id = ?",
+    )
+    .bind(child_id.to_string())
+    .fetch_one(&pool)
+    .await
+    .expect("read child projection ordinal");
+    assert_eq!((turn_ordinal, next_ordinal), (5, 8));
+}
+
+#[tokio::test]
+async fn named_fork_boundaries_reject_invisible_and_noncanonical_turns() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let source_id = ThreadId::default();
+    create_paginated_thread(&store, source_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: source_id,
+            items: vec![turn_started("inherited-turn"), user_message("before fork")],
+        })
+        .await
+        .expect("append inherited active turn");
+
+    let history_base = prepare_paginated_fork(&store, source_id, ForkBoundary::Latest)
+        .await
+        .history_base;
+    let child_id = ThreadId::default();
+    create_paginated_subagent_thread(
+        &store,
+        child_id,
+        history_base,
+        /*subagent_history_start_ordinal*/ None,
+    )
+    .await;
+    store
+        .persist_thread(child_id, PersistContext::Standard)
+        .await
+        .expect("persist child metadata");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: child_id,
+            items: vec![turn_started("child-turn"), turn_completed("child-turn")],
+        })
+        .await
+        .expect("append child turn after inherited active turn");
+    let error = store
+        .prepare_fork(PrepareForkParams {
+            thread_id: child_id,
+            boundary: ForkBoundary::ThroughTurn("inherited-turn".to_string()),
+        })
+        .await
+        .expect_err("cannot fork through an inherited active turn");
+    assert!(matches!(
+        error,
+        crate::ThreadStoreError::InvalidRequest { message }
+            if message == "lastTurnId 'inherited-turn' identifies an in-progress turn"
+    ));
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: source_id,
+            items: vec![
+                user_message("after fork"),
+                turn_completed("inherited-turn"),
+                turn_started("stale-turn"),
+                turn_started("replacement-turn"),
+                turn_completed("replacement-turn"),
+                completed_item(
+                    source_id,
+                    "review-turn",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "review-message".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                turn_completed("review-turn"),
+            ],
+        })
+        .await
+        .expect("append invisible, stale, and terminal-only turns");
+
+    for (thread_id, boundary, expected_error) in [
+        (
+            child_id,
+            ForkBoundary::ThroughTurn("inherited-turn".to_string()),
+            "fork boundary exceeds inherited source history",
+        ),
+        (
+            source_id,
+            ForkBoundary::ThroughTurn("stale-turn".to_string()),
+            "lastTurnId 'stale-turn' identifies an in-progress turn",
+        ),
+        (
+            source_id,
+            ForkBoundary::BeforeTurn("review-turn".to_string()),
+            "turn review-turn does not have a persisted start boundary",
+        ),
+    ] {
+        let error = store
+            .prepare_fork(PrepareForkParams {
+                thread_id,
+                boundary,
+            })
+            .await
+            .expect_err("reject an invalid fork boundary");
+        assert!(matches!(
+            error,
+            crate::ThreadStoreError::InvalidRequest { message } if message == expected_error
+        ));
+    }
+}
+
+#[tokio::test]
+async fn active_turn_stores_only_its_start_position() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect("append active turn");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let (turn_start_byte_offset, _) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 1);
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let turn_position = sqlx::query_as::<_, (Option<i64>, Option<i64>, Option<i64>)>(
+        "SELECT rollout_byte_offset, rollout_end_ordinal, rollout_end_byte_offset FROM thread_turns WHERE thread_id = ? AND turn_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read active turn position");
+    assert_eq!(turn_position, (Some(turn_start_byte_offset), None, None));
+
+    let (latest_byte_offset, latest_ordinal) = projection_state(&pool, thread_id).await;
+    let prepared = prepare_paginated_fork(&store, thread_id, ForkBoundary::Latest).await;
+    assert_eq!(
+        prepared.history_base,
+        Some(HistoryPosition {
+            thread_id,
+            end_ordinal_exclusive: u64::try_from(latest_ordinal).expect("latest ordinal"),
+            end_byte_offset: u64::try_from(latest_byte_offset).expect("latest byte offset"),
+        })
+    );
+    assert!(prepared.model_context.iter().any(|item| {
+        matches!(item, RolloutItem::EventMsg(EventMsg::TurnStarted(event)) if event.turn_id == "turn-1")
+    }));
+    // Another store may fork the persisted prefix while this store keeps the source writer open.
+    let other_store = projection_store(home.path()).await;
+    let other_prepared =
+        prepare_paginated_fork(&other_store, thread_id, ForkBoundary::Latest).await;
+    assert_eq!(
+        serde_json::to_value((
+            other_prepared.history_base,
+            other_prepared.model_context.as_ref()
+        ))
+        .expect("serialize other store's fork snapshot"),
+        serde_json::to_value((prepared.history_base, prepared.model_context.as_ref()))
+            .expect("serialize live store's fork snapshot"),
+    );
+    assert_eq!(
+        prepare_paginated_fork(
+            &store,
+            thread_id,
+            ForkBoundary::BeforeTurn("turn-1".to_string()),
+        )
+        .await
+        .history_base,
+        None
+    );
+}
+
+#[tokio::test]
+async fn paginated_fork_persists_empty_source() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    assert!(!rollout_path.exists());
+
+    let prepared = prepare_paginated_fork(&store, thread_id, ForkBoundary::Latest).await;
+
+    assert!(rollout_path.exists());
+    assert_eq!(prepared.history_base, None);
+    assert!(matches!(
+        prepared.model_context.as_slice(),
+        [RolloutItem::SessionMeta(meta)] if meta.meta.id == thread_id
+    ));
+}
+
+#[tokio::test]
+async fn paginated_fork_reads_compressed_shared_lineage_without_materializing() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let ancestor_thread_id = ThreadId::default();
+    create_paginated_thread(&store, ancestor_thread_id).await;
+    store
+        .persist_thread(ancestor_thread_id, PersistContext::Standard)
+        .await
+        .expect("persist ancestor meta");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: ancestor_thread_id,
+            items: vec![
+                turn_started("ancestor-turn"),
+                user_message("inherited ancestor message"),
+                turn_completed("ancestor-turn"),
+            ],
+        })
+        .await
+        .expect("append ancestor turn");
+    let ancestor_path = store
+        .live_rollout_path(ancestor_thread_id)
+        .await
+        .expect("ancestor rollout path");
+    let ancestor_base = prepare_paginated_fork(&store, ancestor_thread_id, ForkBoundary::Latest)
+        .await
+        .history_base
+        .expect("ancestor prefix");
+    store
+        .shutdown_thread(ancestor_thread_id)
+        .await
+        .expect("shutdown ancestor");
+
+    // A standalone source still becomes plain before its first shared reference, so the default
+    // mode does not introduce compressed lineages that older readers cannot follow.
+    compress_rollout(ancestor_path.as_path());
+    assert_eq!(
+        prepare_paginated_fork(&store, ancestor_thread_id, ForkBoundary::Latest)
+            .await
+            .history_base,
+        Some(ancestor_base)
+    );
+    assert!(ancestor_path.exists());
+
+    let source_thread_id = ThreadId::default();
+    create_paginated_subagent_thread(
+        &store,
+        source_thread_id,
+        Some(ancestor_base),
+        /*subagent_history_start_ordinal*/ None,
+    )
+    .await;
+    store
+        .persist_thread(source_thread_id, PersistContext::Standard)
+        .await
+        .expect("persist source meta");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: source_thread_id,
+            items: vec![
+                turn_started("source-turn"),
+                user_message("inherited source message"),
+                turn_completed("source-turn"),
+            ],
+        })
+        .await
+        .expect("append source turn");
+    let source_path = store
+        .live_rollout_path(source_thread_id)
+        .await
+        .expect("source rollout path");
+    store
+        .shutdown_thread(source_thread_id)
+        .await
+        .expect("shutdown source");
+    let ancestor_compressed_path = ancestor_path.with_extension("jsonl.zst");
+    let source_compressed_path = source_path.with_extension("jsonl.zst");
+    compress_rollout(ancestor_path.as_path());
+    compress_rollout(source_path.as_path());
+    let ancestor_modified = fs::metadata(&ancestor_compressed_path)
+        .and_then(|metadata| metadata.modified())
+        .expect("read compressed ancestor timestamp");
+    let source_modified = fs::metadata(&source_compressed_path)
+        .and_then(|metadata| metadata.modified())
+        .expect("read compressed source timestamp");
+
+    let (first, second) = tokio::join!(
+        prepare_paginated_fork(&store, source_thread_id, ForkBoundary::Latest),
+        prepare_paginated_fork(&store, source_thread_id, ForkBoundary::Latest),
+    );
+    assert!(!ancestor_path.exists());
+    assert!(!source_path.exists());
+    assert!(ancestor_compressed_path.exists());
+    assert!(source_compressed_path.exists());
+    assert_eq!(
+        fs::metadata(&ancestor_compressed_path)
+            .and_then(|metadata| metadata.modified())
+            .expect("read compressed ancestor timestamp"),
+        ancestor_modified
+    );
+    assert_eq!(
+        fs::metadata(&source_compressed_path)
+            .and_then(|metadata| metadata.modified())
+            .expect("read compressed source timestamp"),
+        source_modified
+    );
+    for prepared in [first, second] {
+        assert!(matches!(
+            prepared.model_context.first(),
+            Some(RolloutItem::SessionMeta(meta)) if meta.meta.id == source_thread_id
+        ));
+        for message in ["inherited ancestor message", "inherited source message"] {
+            assert!(contains_user_message(
+                prepared.model_context.as_slice(),
+                message
+            ));
+        }
+    }
+
+    // Skipping materialization must not allow a reference that cannot be resolved inside this home.
+    let external_home = TempDir::new().expect("external temp dir");
+    let external_path = external_home.path().join(
+        source_compressed_path
+            .file_name()
+            .expect("source rollout filename"),
+    );
+    fs::rename(&source_compressed_path, &external_path).expect("move shared source outside home");
+    store
+        .resume_thread(ResumeThreadParams {
+            thread_id: source_thread_id,
+            rollout_path: Some(external_path),
+            history: None,
+            include_archived: true,
+            metadata: ThreadPersistenceMetadata {
+                cwd: Some(home.path().to_path_buf()),
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        })
+        .await
+        .expect("resume external shared source");
+    let error = store
+        .prepare_fork(PrepareForkParams {
+            thread_id: source_thread_id,
+            boundary: ForkBoundary::Latest,
+        })
+        .await
+        .expect_err("external shared source cannot be referenced by rollout id");
+    assert!(matches!(
+        error,
+        crate::ThreadStoreError::InvalidRequest { message } if message.contains("must be in Codex home")
+    ));
+    store
+        .shutdown_thread(source_thread_id)
+        .await
+        .expect("shutdown external source");
+}
+
+#[tokio::test]
+async fn cancelled_fork_keeps_source_reserved_until_lineage_resolution_finishes() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let ancestor_thread_id = ThreadId::default();
+    create_paginated_thread(&store, ancestor_thread_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: ancestor_thread_id,
+            items: vec![
+                turn_started("ancestor-turn"),
+                turn_completed("ancestor-turn"),
+            ],
+        })
+        .await
+        .expect("append ancestor history");
+    let ancestor_base = prepare_paginated_fork(&store, ancestor_thread_id, ForkBoundary::Latest)
+        .await
+        .history_base
+        .expect("ancestor prefix");
+
+    let source_thread_id = ThreadId::default();
+    create_paginated_subagent_thread(
+        &store,
+        source_thread_id,
+        Some(ancestor_base),
+        /*subagent_history_start_ordinal*/ None,
+    )
+    .await;
+    store
+        .persist_thread(source_thread_id, PersistContext::Standard)
+        .await
+        .expect("persist source metadata");
+    let source_path = store
+        .live_rollout_path(source_thread_id)
+        .await
+        .expect("source rollout path");
+    store
+        .shutdown_thread(source_thread_id)
+        .await
+        .expect("shutdown source");
+    compress_rollout(source_path.as_path());
+
+    let ancestor_writer_guard = store.live_writer_locks.lock(ancestor_thread_id).await;
+    let source_coordination = store.live_writer_locks.coordination(source_thread_id).await;
+    let preparation_store = store.clone();
+    let preparation = tokio::spawn(async move {
+        preparation_store
+            .prepare_fork(PrepareForkParams {
+                thread_id: source_thread_id,
+                boundary: ForkBoundary::Latest,
+            })
+            .await
+    });
+    tokio::time::timeout(Duration::from_secs(10), async {
+        while source_coordination.lifecycle.try_write().is_ok() {
+            tokio::task::yield_now().await;
+        }
+    })
+    .await
+    .expect("fork preparation should reserve the source");
+    preparation.abort();
+    assert!(
+        preparation
+            .await
+            .expect_err("fork preparation should be cancelled")
+            .is_cancelled()
+    );
+
+    let mut delete = Box::pin(store.delete_thread(DeleteThreadParams {
+        thread_id: source_thread_id,
+    }));
+    tokio::select! {
+        biased;
+        result = &mut delete => {
+            panic!("source deletion completed while lineage resolution was active: {result:?}")
+        }
+        _ = tokio::task::yield_now() => {}
+    }
+    drop(ancestor_writer_guard);
+    delete
+        .await
+        .expect("delete source after lineage resolution finishes");
+}
+
+#[tokio::test]
+async fn prepared_fork_reserves_source_until_child_reference_is_durable() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let source_thread_id = ThreadId::default();
+    create_paginated_thread(&store, source_thread_id).await;
+    store
+        .persist_thread(source_thread_id, PersistContext::Standard)
+        .await
+        .expect("persist source metadata");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id: source_thread_id,
+            items: vec![turn_started("source-turn"), turn_completed("source-turn")],
+        })
+        .await
+        .expect("append source turn");
+    let prepared = store
+        .prepare_fork(PrepareForkParams {
+            thread_id: source_thread_id,
+            boundary: ForkBoundary::Latest,
+        })
+        .await
+        .expect("prepare referenced fork");
+    let history_base = prepared.history_base.expect("source history base");
+
+    let mut delete = Box::pin(store.delete_thread(DeleteThreadParams {
+        thread_id: source_thread_id,
+    }));
+    tokio::select! {
+        biased;
+        result = &mut delete => {
+            panic!("source deletion completed before its child reference was durable: {result:?}")
+        }
+        _ = tokio::task::yield_now() => {}
+    }
+    tokio::time::timeout(
+        Duration::from_secs(10),
+        store.append_items(AppendThreadItemsParams {
+            thread_id: source_thread_id,
+            items: vec![
+                turn_started("later-turn"),
+                user_message("later source message"),
+                turn_completed("later-turn"),
+            ],
+        }),
+    )
+    .await
+    .expect("source write should not wait behind deletion")
+    .expect("source writes remain available during fork preparation");
+    assert_eq!(prepared.history_base, Some(history_base));
+    assert!(!contains_user_message(
+        prepared.model_context.as_slice(),
+        "later source message"
+    ));
+
+    let child_thread_id = ThreadId::default();
+    create_paginated_subagent_thread(
+        &store,
+        child_thread_id,
+        Some(history_base),
+        /*subagent_history_start_ordinal*/ None,
+    )
+    .await;
+    store
+        .persist_thread(child_thread_id, PersistContext::Standard)
+        .await
+        .expect("persist child history reference");
+    drop(prepared);
+
+    let error = delete
+        .await
+        .expect_err("durable child reference protects its source");
+    assert!(
+        error
+            .to_string()
+            .contains("forked history still references")
+    );
+}
+
+#[tokio::test]
+async fn subagent_prefix_advances_projection_without_materializing_history() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_subagent_thread(
+        &store,
+        thread_id,
+        /*history_base*/ None,
+        /*subagent_history_start_ordinal*/ Some(5),
+    )
+    .await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                RolloutItem::RealtimeItem(RealtimeItem {
+                    id: "parent:started".to_string(),
+                    realtime_session_id: "parent".to_string(),
+                    content: RealtimeItemContent::RealtimeSessionStarted,
+                }),
+                turn_started("parent-turn"),
+                completed_item(
+                    thread_id,
+                    "parent-turn",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "parent-user".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                turn_completed("parent-turn"),
+                turn_started("child-turn"),
+                RolloutItem::RealtimeItem(RealtimeItem {
+                    id: "child:started".to_string(),
+                    realtime_session_id: "child".to_string(),
+                    content: RealtimeItemContent::RealtimeSessionStarted,
+                }),
+                completed_item(
+                    thread_id,
+                    "child-turn",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "child-user".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                turn_completed("child-turn"),
+            ],
+        })
+        .await
+        .expect("append inherited prefix and child history");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let (child_start_byte_offset, _) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 5);
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let turns = sqlx::query_as::<_, (String, i64, Option<i64>)>(
+        "SELECT turn_id, rollout_ordinal, rollout_byte_offset FROM thread_turns WHERE thread_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read projected turns");
+    assert_eq!(
+        turns,
+        vec![("child-turn".to_string(), 5, Some(child_start_byte_offset))]
+    );
+    let items = sqlx::query_as::<_, (String, i64)>(
+        "SELECT item_id, rollout_ordinal FROM thread_items WHERE thread_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read projected items");
+    assert_eq!(items, vec![("child-user".to_string(), 7)]);
+    let realtime_items = sqlx::query_as::<_, (String, i64)>(
+        "SELECT item_id, rollout_ordinal FROM thread_realtime_items WHERE thread_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read projected realtime items");
+    assert_eq!(realtime_items, vec![("child:started".to_string(), 6)]);
+    assert_eq!(projection_state(&pool, thread_id).await.1, 9);
+}
+
+#[tokio::test]
+async fn unexpected_duplicate_item_completion_does_not_poison_projection() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-1"),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "user-1".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+            ],
+        })
+        .await
+        .expect("append completed item");
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let first_created_at_ms = sqlx::query_scalar::<_, i64>(
+        "SELECT created_at_ms FROM thread_items WHERE thread_id = ? AND turn_id = ? AND item_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .bind("user-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read first item timestamp");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![completed_item(
+                thread_id,
+                "turn-1",
+                TurnItem::UserMessage(UserMessageItem {
+                    id: "user-1".to_string(),
+                    client_id: Some("updated".to_string()),
+                    content: Vec::new(),
+                }),
+            )],
+        })
+        .await
+        .expect("append unexpected duplicate item completion");
+
+    let item = sqlx::query_as::<_, (i64, i64, i64, String)>(
+        r#"
+SELECT rollout_ordinal, updated_at_ordinal, created_at_ms, item_json
+FROM thread_items
+WHERE thread_id = ? AND turn_id = ? AND item_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .bind("user-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected item");
+    assert_eq!((item.0, item.1, item.2), (2, 3, first_created_at_ms));
+    assert_eq!(
+        serde_json::from_str::<ThreadItem>(item.3.as_str()).expect("parse projected item"),
+        ThreadItem::UserMessage {
+            id: "user-1".to_string(),
+            client_id: Some("updated".to_string()),
+            content: Vec::new(),
+        }
+    );
+}
+
+#[tokio::test]
+async fn terminal_turn_does_not_change_after_later_records() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1"), turn_completed("turn-1")],
+        })
+        .await
+        .expect("append terminal turn");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-1"),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "late-user".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+            ],
+        })
+        .await
+        .expect("append later records");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let (turn_start_byte_offset, _) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 1);
+    let (_, turn_end_byte_offset) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 2);
+    let turn = sqlx::query_as::<
+        _,
+        (
+            i64,
+            Option<i64>,
+            Option<i64>,
+            Option<i64>,
+            String,
+            Option<String>,
+        ),
+    >(
+        r#"
+SELECT
+    rollout_ordinal,
+    rollout_byte_offset,
+    rollout_end_ordinal,
+    rollout_end_byte_offset,
+    status,
+    first_user_item_id
+FROM thread_turns
+WHERE thread_id = ? AND turn_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected turn");
+    assert_eq!(
+        turn,
+        (
+            1,
+            Some(turn_start_byte_offset),
+            Some(2),
+            Some(turn_end_byte_offset),
+            "completed".to_string(),
+            None,
+        )
+    );
+}
+
+#[tokio::test]
+async fn summary_items_use_final_answers_and_ignore_commentary() {
+    let home = TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let thread_id = ThreadId::default();
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state runtime");
+    let mut builder = codex_state::ThreadMetadataBuilder::new(
+        thread_id,
+        home.path().join("missing-rollout.jsonl"),
+        Utc::now(),
+        SessionSource::Cli,
+    );
+    builder.history_mode = ThreadHistoryMode::Paginated;
+    runtime
+        .upsert_thread(&builder.build(config.default_model_provider_id.as_str()))
+        .await
+        .expect("seed thread metadata");
+    let store = LocalThreadStore::new(config, Some(runtime));
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "user-1".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    agent_message("commentary-1", MessagePhase::Commentary),
+                ),
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    agent_message("final-1", MessagePhase::FinalAnswer),
+                ),
+            ],
+        })
+        .await
+        .expect("append items before turn lifecycle");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    sqlx::query(
+        r#"
+INSERT OR REPLACE INTO thread_items (
+    thread_id,
+    turn_id,
+    item_id,
+    rollout_ordinal,
+    created_at_ms,
+    item_json
+)
+SELECT thread_id, turn_id, item_id, rollout_ordinal, created_at_ms, item_json
+FROM thread_items
+WHERE thread_id = ? AND turn_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .execute(&pool)
+    .await
+    .expect("older writers can append items without a stored item type");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1"), turn_completed("turn-1")],
+        })
+        .await
+        .expect("append delayed turn lifecycle");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-2"),
+                completed_item(
+                    thread_id,
+                    "turn-2",
+                    TurnItem::UserMessage(UserMessageItem {
+                        id: "user-2".to_string(),
+                        client_id: None,
+                        content: Vec::new(),
+                    }),
+                ),
+                completed_item(
+                    thread_id,
+                    "turn-2",
+                    agent_message("commentary-2", MessagePhase::Commentary),
+                ),
+                turn_completed("turn-2"),
+            ],
+        })
+        .await
+        .expect("append commentary-only turn");
+
+    let summary = store
+        .list_turns(ListTurnsParams {
+            thread_id,
+            include_archived: false,
+            cursor: None,
+            page_size: 2,
+            sort_direction: SortDirection::Asc,
+            items_view: StoredTurnItemsView::Summary,
+        })
+        .await
+        .expect("list turn summaries");
+    assert_eq!(
+        summary
+            .turns
+            .iter()
+            .map(|turn| {
+                (
+                    turn.turn_id.as_str(),
+                    turn.items
+                        .iter()
+                        .map(|item| item.item_id.as_str())
+                        .collect::<Vec<_>>(),
+                )
+            })
+            .collect::<Vec<_>>(),
+        vec![
+            ("turn-1", vec!["user-1", "final-1"]),
+            ("turn-2", vec!["user-2"]),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn paginated_projection_accepts_float_rate_limits_and_later_final_answers() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect("append projected turn start");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let checkpoint = projection_state(&pool, thread_id).await;
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let token_count = |primary: Option<f64>, secondary: Option<f64>| {
+        RolloutItem::EventMsg(EventMsg::TokenCount(TokenCountEvent {
+            info: None,
+            rate_limits: Some(RateLimitSnapshot {
+                limit_id: None,
+                limit_name: None,
+                normal_model_slug: None,
+                primary: primary.map(|used_percent| RateLimitWindow {
+                    used_percent,
+                    window_minutes: Some(60),
+                    resets_at: Some(1_800_000_000),
+                }),
+                secondary: secondary.map(|used_percent| RateLimitWindow {
+                    used_percent,
+                    window_minutes: Some(10_080),
+                    resets_at: Some(1_800_100_000),
+                }),
+                credits: None,
+                individual_limit: None,
+                spend_control_reached: None,
+                plan_type: None,
+                rate_limit_reached_type: None,
+            }),
+        }))
+    };
+
+    let recorder = store
+        .live_recorders
+        .lock()
+        .await
+        .get(&thread_id)
+        .expect("live recorder")
+        .recorder
+        .clone();
+    recorder
+        .record_canonical_items(&[
+            token_count(Some(0.0), Some(1.0)),
+            completed_item(
+                thread_id,
+                "turn-1",
+                agent_message("final-1", MessagePhase::FinalAnswer),
+            ),
+            token_count(Some(12.5), None),
+            turn_completed("turn-1"),
+        ])
+        .await
+        .expect("queue unprojected history");
+    recorder.flush().await.expect("flush unprojected history");
+    assert_eq!(projection_state(&pool, thread_id).await, checkpoint);
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("project floating-point rate limits");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![
+                turn_started("turn-2"),
+                token_count(None, Some(87.25)),
+                completed_item(
+                    thread_id,
+                    "turn-2",
+                    agent_message("final-2", MessagePhase::FinalAnswer),
+                ),
+                token_count(Some(1e-12), Some(1_000_000.0)),
+                turn_completed("turn-2"),
+            ],
+        })
+        .await
+        .expect("append history after unprojected floating-point rate limits");
+
+    let final_answers = sqlx::query_as::<_, (String, String, String, i64)>(
+        r#"
+SELECT turns.turn_id, items.item_id, turns.status, items.rollout_ordinal
+FROM thread_turns AS turns
+JOIN thread_items AS items
+  ON items.thread_id = turns.thread_id
+ AND items.turn_id = turns.turn_id
+ AND items.item_id = turns.final_agent_item_id
+WHERE turns.thread_id = ?
+ORDER BY turns.rollout_ordinal
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read projected final answers");
+    assert_eq!(
+        final_answers,
+        vec![
+            (
+                "turn-1".to_string(),
+                "final-1".to_string(),
+                "completed".to_string(),
+                3,
+            ),
+            (
+                "turn-2".to_string(),
+                "final-2".to_string(),
+                "completed".to_string(),
+                8,
+            ),
+        ]
+    );
+
+    let rollout_len = i64::try_from(
+        fs::metadata(rollout_path.as_path())
+            .expect("rollout metadata")
+            .len(),
+    )
+    .expect("rollout length");
+    assert_eq!(projection_state(&pool, thread_id).await, (rollout_len, 11));
+}
+
+#[tokio::test]
+async fn next_write_catches_up_unprojected_durable_suffix() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let checkpoint = projection_state(&pool, thread_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect("append turn start");
+
+    let thread_id_string = thread_id.to_string();
+    sqlx::query("DELETE FROM thread_turns WHERE thread_id = ?")
+        .bind(thread_id_string.as_str())
+        .execute(&pool)
+        .await
+        .expect("remove projected turn");
+    sqlx::query(
+        r#"
+UPDATE thread_history_projection_state
+SET next_rollout_byte_offset = ?, next_rollout_ordinal = ?
+WHERE thread_id = ?
+        "#,
+    )
+    .bind(checkpoint.0)
+    .bind(checkpoint.1)
+    .bind(thread_id_string.as_str())
+    .execute(&pool)
+    .await
+    .expect("rewind projection state");
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![completed_item(
+                thread_id,
+                "turn-1",
+                TurnItem::UserMessage(UserMessageItem {
+                    id: "user-1".to_string(),
+                    client_id: None,
+                    content: Vec::new(),
+                }),
+            )],
+        })
+        .await
+        .expect("append after simulated projection failure");
+
+    let rows = sqlx::query_as::<_, (String, String)>(
+        r#"
+SELECT
+    (SELECT status FROM thread_turns WHERE thread_id = ? AND turn_id = 'turn-1'),
+    (SELECT item_id FROM thread_items WHERE thread_id = ? AND turn_id = 'turn-1')
+        "#,
+    )
+    .bind(thread_id_string.as_str())
+    .bind(thread_id_string.as_str())
+    .fetch_one(&pool)
+    .await
+    .expect("read recovered rows");
+    assert_eq!(rows, ("inProgress".to_string(), "user-1".to_string()));
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    assert_eq!(projection_state(&pool, thread_id).await, (rollout_len, 3));
+}
+
+#[tokio::test]
+async fn synchronized_catch_up_does_not_replay_old_rows() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect("append turn start");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let before = projection_state(&pool, thread_id).await;
+    sqlx::query("UPDATE thread_turns SET status = 'sentinel' WHERE thread_id = ?")
+        .bind(thread_id.to_string())
+        .execute(&pool)
+        .await
+        .expect("mark projected turn");
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("catch up synchronized rollout");
+
+    assert_eq!(projection_state(&pool, thread_id).await, before);
+    let status =
+        sqlx::query_scalar::<_, String>("SELECT status FROM thread_turns WHERE thread_id = ?")
+            .bind(thread_id.to_string())
+            .fetch_one(&pool)
+            .await
+            .expect("read projected turn");
+    assert_eq!(status, "sentinel");
+}
+
+#[tokio::test]
+async fn catch_up_preserves_trailing_partial_line_boundaries() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let before = projection_state(&pool, thread_id).await;
+    let complete_line = rollout_line(Some(1), turn_started("turn-1"));
+    let partial_line = rollout_line(Some(2), turn_completed("turn-1"));
+    let complete_suffix = format!("{complete_line}\n");
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    append_suffix(
+        rollout_path.as_path(),
+        format!("{complete_suffix}{partial_line}").as_str(),
+    );
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("catch up complete suffix");
+
+    let expected_offset =
+        before.0 + i64::try_from(complete_suffix.len()).expect("complete suffix byte count");
+    assert_eq!(
+        projection_state(&pool, thread_id).await,
+        (expected_offset, 2)
+    );
+    append_suffix(rollout_path.as_path(), "\n");
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("catch up completed partial suffix");
+
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    let turn_position = sqlx::query_as::<_, (Option<i64>, Option<i64>, Option<i64>)>(
+        "SELECT rollout_byte_offset, rollout_end_ordinal, rollout_end_byte_offset FROM thread_turns WHERE thread_id = ? AND turn_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read completed turn position");
+    assert_eq!(turn_position, (Some(before.0), Some(2), Some(rollout_len)));
+}
+
+#[tokio::test]
+async fn catch_up_skips_invalid_complete_suffixes_and_projects_later_history() {
+    let cases = [
+        (
+            "missing ordinal",
+            format!(
+                "{}\n",
+                rollout_line(/*ordinal*/ None, turn_started("turn-1"))
+            ),
+            1,
+            Vec::new(),
+        ),
+        (
+            "duplicate ordinal",
+            format!(
+                "{}\n{}\n{}\n",
+                rollout_line(Some(1), turn_started("turn-1")),
+                rollout_line(Some(1), turn_started("skipped-turn")),
+                rollout_line(Some(2), turn_started("turn-2")),
+            ),
+            3,
+            vec!["turn-1", "turn-2"],
+        ),
+        (
+            "forward ordinal gap",
+            format!("{}\n", rollout_line(Some(2), turn_started("turn-1"))),
+            3,
+            vec!["turn-1"],
+        ),
+    ];
+    for (name, suffix, expected_next_ordinal, expected_turn_ids) in cases {
+        let home = TempDir::new().expect("temp dir");
+        let store = projection_store(home.path()).await;
+        let thread_id = ThreadId::default();
+        create_paginated_thread(&store, thread_id).await;
+        store
+            .persist_thread(thread_id, PersistContext::Standard)
+            .await
+            .expect("persist session metadata");
+
+        let pool = codex_state::open_thread_history_db(
+            &codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+        )
+        .await
+        .expect("open thread history db");
+        let before = projection_state(&pool, thread_id).await;
+        let rollout_path = store
+            .live_rollout_path(thread_id)
+            .await
+            .expect("rollout path");
+        append_suffix(rollout_path.as_path(), suffix.as_str());
+
+        super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+            .await
+            .expect(name);
+
+        let expected_offset = before.0 + i64::try_from(suffix.len()).expect("suffix byte count");
+        assert_eq!(
+            projection_state(&pool, thread_id).await,
+            (expected_offset, expected_next_ordinal),
+            "{name} should advance projection state"
+        );
+        let turn_ids = sqlx::query_scalar::<_, String>(
+            "SELECT turn_id FROM thread_turns WHERE thread_id = ? ORDER BY rollout_ordinal",
+        )
+        .bind(thread_id.to_string())
+        .fetch_all(&pool)
+        .await
+        .expect("read projected turns");
+        assert_eq!(turn_ids, expected_turn_ids, "{name}");
+    }
+}
+
+#[tokio::test]
+async fn jsonl_failure_does_not_create_projection_database() {
+    let home = TempDir::new().expect("temp dir");
+    fs::write(home.path().join("sessions"), "not a directory").expect("block sessions dir");
+    let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect_err("JSONL append should fail");
+
+    assert!(
+        !codex_state::SqliteConfig::new_for_testing(home.path().abs())
+            .thread_history_db_path()
+            .exists()
+    );
+}
+
+#[tokio::test]
+async fn catch_up_rejects_missing_rollout_after_projection() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    store
+        .shutdown_thread(thread_id)
+        .await
+        .expect("close rollout");
+    fs::remove_file(rollout_path.as_path()).expect("remove rollout");
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect_err("missing projected rollout should fail");
+}
+
+#[tokio::test]
+async fn sqlite_failure_does_not_fail_durable_jsonl_write() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    fs::create_dir(store.config.sqlite.thread_history_db_path())
+        .expect("block thread history database");
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+
+    store
+        .append_items(AppendThreadItemsParams {
+            thread_id,
+            items: vec![turn_started("turn-1")],
+        })
+        .await
+        .expect("durable JSONL append should succeed");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let (items, _, _) = RolloutRecorder::load_rollout_items(rollout_path.as_path())
+        .await
+        .expect("load durable rollout");
+    assert!(items.iter().any(|item| {
+        matches!(
+            item,
+            RolloutItem::EventMsg(EventMsg::TurnStarted(event))
+                if event.turn_id == "turn-1"
+        )
+    }));
+}
+
+#[tokio::test]
+async fn blank_and_rejected_rollout_lines_advance_projection() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let before = projection_state(&pool, thread_id).await;
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let mut file = fs::OpenOptions::new()
+        .append(true)
+        .open(rollout_path.as_path())
+        .expect("open rollout for rejected line");
+    file.write_all(b"{not json}\n\n")
+        .expect("append blank and rejected lines");
+    file.flush().expect("flush rejected line");
+    let rejected_tail_len = i64::try_from(
+        fs::metadata(rollout_path.as_path())
+            .expect("rollout metadata")
+            .len(),
+    )
+    .expect("rollout length");
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("skip rejected tail");
+    assert_eq!(
+        projection_state(&pool, thread_id).await,
+        (rejected_tail_len, before.1)
+    );
+
+    let recorder = store
+        .live_recorders
+        .lock()
+        .await
+        .get(&thread_id)
+        .expect("live recorder")
+        .recorder
+        .clone();
+    recorder
+        .record_canonical_items(&[turn_started("turn-1")])
+        .await
+        .expect("queue valid retry");
+    recorder.flush().await.expect("flush valid retry");
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("project valid retry after rejected line");
+
+    let (expected_start_byte_offset, _) =
+        rollout_line_byte_offsets(rollout_path.as_path(), /*ordinal*/ 1);
+    let start_byte_offset = sqlx::query_scalar::<_, Option<i64>>(
+        "SELECT rollout_byte_offset FROM thread_turns WHERE thread_id = ? AND turn_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected turn byte offset");
+    assert_eq!(start_byte_offset, Some(expected_start_byte_offset));
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    assert_eq!(projection_state(&pool, thread_id).await, (rollout_len, 2));
+}
+
+#[tokio::test]
+async fn unknown_rollout_lines_leave_ordinals_pending_for_valid_retries() {
+    let unknown_line = |ordinal| {
+        format!(
+            concat!(
+                "{{\"timestamp\":\"2025-01-01T00:00:00.000Z\",\"ordinal\":{ordinal},",
+                "\"type\":\"future_item\",\"payload\":{{}}}}"
+            ),
+            ordinal = ordinal
+        )
+    };
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let before = projection_state(&pool, thread_id).await;
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    let pending_line = unknown_line(1);
+    append_suffix(rollout_path.as_path(), format!("{pending_line}\n").as_str());
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("skip unknown tail");
+    let expected_pending_offset =
+        before.0 + i64::try_from(pending_line.len() + 1).expect("pending line byte count");
+    assert_eq!(
+        projection_state(&pool, thread_id).await,
+        (expected_pending_offset, 1)
+    );
+
+    append_suffix(
+        rollout_path.as_path(),
+        format!(
+            "{}\n{}\n{}\n",
+            rollout_line(Some(1), turn_started("retry-turn")),
+            unknown_line(2),
+            rollout_line(Some(3), turn_started("turn-1")),
+        )
+        .as_str(),
+    );
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("project valid retry and later history");
+
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    assert_eq!(projection_state(&pool, thread_id).await, (rollout_len, 4));
+    let turn_ordinals = sqlx::query_as::<_, (String, i64)>(
+        "SELECT turn_id, rollout_ordinal FROM thread_turns WHERE thread_id = ? ORDER BY rollout_ordinal",
+    )
+    .bind(thread_id.to_string())
+    .fetch_all(&pool)
+    .await
+    .expect("read projected turns");
+    assert_eq!(
+        turn_ordinals,
+        vec![("retry-turn".to_string(), 1), ("turn-1".to_string(), 3)]
+    );
+}
+
+#[tokio::test]
+async fn event_timestamps_allow_invalid_rollout_timestamps() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    let invalid_timestamp_line = |ordinal, item| {
+        rollout_line(Some(ordinal), item).replace("2025-01-01T00:00:00.000Z", "not-a-timestamp")
+    };
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    append_suffix(
+        rollout_path.as_path(),
+        format!(
+            "{}\n{}\n",
+            invalid_timestamp_line(1, turn_started("turn-1")),
+            invalid_timestamp_line(
+                2,
+                completed_item(
+                    thread_id,
+                    "turn-1",
+                    agent_message("agent-1", MessagePhase::FinalAnswer),
+                ),
+            ),
+        )
+        .as_str(),
+    );
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("project records with event timestamps");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let created_at_ms = sqlx::query_scalar::<_, i64>(
+        "SELECT created_at_ms FROM thread_items WHERE thread_id = ? AND turn_id = ? AND item_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .bind("agent-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected item timestamp");
+    assert_eq!(created_at_ms, 0);
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    assert_eq!(projection_state(&pool, thread_id).await, (rollout_len, 3));
+}
+
+#[tokio::test]
+async fn malformed_rollout_lines_skip_inferred_ordinal_gaps() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+
+    let rollout_path = store
+        .live_rollout_path(thread_id)
+        .await
+        .expect("rollout path");
+    append_suffix(
+        rollout_path.as_path(),
+        format!(
+            "{{not json}}\n{}\n",
+            rollout_line(Some(2), turn_started("turn-1"))
+        )
+        .as_str(),
+    );
+
+    super::materialize_to_sqlite(&store, thread_id, rollout_path.as_path())
+        .await
+        .expect("skip malformed gap and project later history");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let rollout_len = i64::try_from(fs::metadata(rollout_path).expect("rollout metadata").len())
+        .expect("rollout length");
+    assert_eq!(projection_state(&pool, thread_id).await, (rollout_len, 3));
+    let turn_ordinal = sqlx::query_scalar::<_, i64>(
+        "SELECT rollout_ordinal FROM thread_turns WHERE thread_id = ? AND turn_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected turn");
+    assert_eq!(turn_ordinal, 2);
+}
+
+#[tokio::test]
+async fn shutdown_materializes_items_queued_without_a_flush() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    let recorder = store
+        .live_recorders
+        .lock()
+        .await
+        .get(&thread_id)
+        .expect("live recorder")
+        .recorder
+        .clone();
+    recorder
+        .record_canonical_items(&[turn_started("turn-1")])
+        .await
+        .expect("queue rollout item");
+
+    store
+        .shutdown_thread(thread_id)
+        .await
+        .expect("shutdown live thread");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let projected_turns = sqlx::query_scalar::<_, i64>(
+        "SELECT COUNT(*) FROM thread_turns WHERE thread_id = ? AND turn_id = ?",
+    )
+    .bind(thread_id.to_string())
+    .bind("turn-1")
+    .fetch_one(&pool)
+    .await
+    .expect("read projected turns");
+    assert_eq!(projected_turns, 1);
+}
+
+#[tokio::test]
+async fn delete_waits_for_in_flight_projection_before_removing_rows() {
+    let home = TempDir::new().expect("temp dir");
+    let store = projection_store(home.path()).await;
+    let thread_id = ThreadId::default();
+    create_paginated_thread(&store, thread_id).await;
+    store
+        .persist_thread(thread_id, PersistContext::Standard)
+        .await
+        .expect("persist session metadata");
+    let write_permit = store.live_writer_locks.lock(thread_id).await;
+
+    let append_store = store.clone();
+    let append = tokio::spawn(async move {
+        append_store
+            .append_items(AppendThreadItemsParams {
+                thread_id,
+                items: vec![turn_started("turn-1")],
+            })
+            .await
+    });
+    tokio::time::sleep(Duration::from_millis(/*millis*/ 10)).await;
+    let delete_store = store.clone();
+    let delete = tokio::spawn(async move {
+        delete_store
+            .delete_thread(DeleteThreadParams { thread_id })
+            .await
+    });
+    tokio::time::sleep(Duration::from_millis(/*millis*/ 10)).await;
+    assert!(!delete.is_finished());
+
+    drop(write_permit);
+    append
+        .await
+        .expect("join append")
+        .expect("finish in-flight append");
+    delete.await.expect("join delete").expect("delete thread");
+
+    let pool = codex_state::open_thread_history_db(&codex_state::SqliteConfig::new_for_testing(
+        home.path().abs(),
+    ))
+    .await
+    .expect("open thread history db");
+    let counts = sqlx::query_as::<_, (i64, i64, i64)>(
+        r#"
+SELECT
+    (SELECT COUNT(*) FROM thread_turns WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_items WHERE thread_id = ?),
+    (SELECT COUNT(*) FROM thread_history_projection_state WHERE thread_id = ?)
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .bind(thread_id.to_string())
+    .bind(thread_id.to_string())
+    .fetch_one(&pool)
+    .await
+    .expect("read history row counts");
+    assert_eq!(counts, (0, 0, 0));
+}
+
+async fn projection_store(codex_home: &Path) -> LocalThreadStore {
+    let config = test_config(codex_home);
+    let state_db = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("initialize state database for paginated history");
+    LocalThreadStore::new(config, Some(state_db))
+}
+
+async fn create_paginated_thread(store: &LocalThreadStore, thread_id: ThreadId) {
+    create_paginated_subagent_thread(
+        store, thread_id, /*history_base*/ None, /*subagent_history_start_ordinal*/ None,
+    )
+    .await;
+}
+
+async fn prepare_paginated_fork(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    boundary: ForkBoundary,
+) -> PreparedFork {
+    store
+        .prepare_fork(PrepareForkParams {
+            thread_id,
+            boundary,
+        })
+        .await
+        .expect("prepare paginated fork")
+}
+
+async fn create_paginated_subagent_thread(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    history_base: Option<HistoryPosition>,
+    subagent_history_start_ordinal: Option<u64>,
+) {
+    store
+        .create_thread(CreateThreadParams {
+            session_id: thread_id.into(),
+            thread_id,
+            extra_config: None,
+            forked_from_id: None,
+            parent_thread_id: None,
+            source: SessionSource::Exec,
+            thread_source: None,
+            originator: "test_originator".to_string(),
+            base_instructions: BaseInstructions::default(),
+            dynamic_tools: Vec::new(),
+            selected_capability_roots: Vec::new(),
+            multi_agent_version: None,
+            history_mode: ThreadHistoryMode::Paginated,
+            history_base,
+            subagent_history_start_ordinal,
+            initial_window_id: "window-1".to_string(),
+            runtime_workspace_roots: None,
+            metadata: ThreadPersistenceMetadata {
+                cwd: Some(std::env::current_dir().expect("cwd")),
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        })
+        .await
+        .expect("create paginated thread");
+}
+
+fn turn_started(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnStarted(TurnStartedEvent {
+        turn_id: turn_id.to_string(),
+        root_turn_id: None,
+        trace_id: None,
+        started_at: Some(10),
+        model_context_window: None,
+        collaboration_mode_kind: Default::default(),
+    }))
+}
+
+fn turn_completed(turn_id: &str) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::TurnComplete(TurnCompleteEvent {
+        turn_id: turn_id.to_string(),
+        last_agent_message: None,
+        error: None,
+        started_at: Some(10),
+        completed_at: Some(20),
+        duration_ms: Some(10_000),
+        time_to_first_token_ms: None,
+    }))
+}
+
+fn user_message(message: &str) -> RolloutItem {
+    RolloutItem::ResponseItem(
+        ResponseItem::Message {
+            id: None,
+            role: "user".to_string(),
+            content: vec![ContentItem::InputText {
+                text: message.to_string(),
+            }],
+            phase: None,
+            internal_chat_message_metadata_passthrough: None,
+        }
+        .into(),
+    )
+}
+
+fn contains_user_message(items: &[RolloutItem], expected: &str) -> bool {
+    items.iter().any(|item| {
+        let RolloutItem::ResponseItem(response_item) = item else {
+            return false;
+        };
+        let ResponseItem::Message { content, .. } = &response_item.item else {
+            return false;
+        };
+        content
+            .iter()
+            .any(|content| matches!(content, ContentItem::InputText { text } if text == expected))
+    })
+}
+
+fn completed_item(thread_id: ThreadId, turn_id: &str, item: TurnItem) -> RolloutItem {
+    RolloutItem::EventMsg(EventMsg::ItemCompleted(ItemCompletedEvent {
+        thread_id,
+        turn_id: turn_id.to_string(),
+        item,
+        started_at_ms: Some(0),
+        completed_at_ms: 1,
+    }))
+}
+
+fn agent_message(id: &str, phase: MessagePhase) -> TurnItem {
+    TurnItem::AgentMessage(AgentMessageItem {
+        id: id.to_string(),
+        content: vec![AgentMessageContent::Text {
+            text: id.to_string(),
+        }],
+        phase: Some(phase),
+        memory_citation: None,
+        delivery: None,
+        questions: None,
+    })
+}
+
+fn rollout_line_byte_offsets(path: &std::path::Path, ordinal: u64) -> (i64, i64) {
+    let bytes = fs::read(path).expect("read rollout");
+    let mut start_byte_offset = 0;
+    for line in bytes.split_inclusive(|byte| *byte == b'\n') {
+        let end_byte_offset = start_byte_offset + line.len();
+        if codex_rollout::parse_rollout_line_bytes(line)
+            .ok()
+            .and_then(|line| line.ordinal)
+            == Some(ordinal)
+        {
+            return (
+                i64::try_from(start_byte_offset).expect("start byte offset fits i64"),
+                i64::try_from(end_byte_offset).expect("end byte offset fits i64"),
+            );
+        }
+        start_byte_offset = end_byte_offset;
+    }
+    panic!("missing rollout ordinal {ordinal}");
+}
+
+fn compress_rollout(path: &Path) {
+    let mut compressed_path = path.as_os_str().to_os_string();
+    compressed_path.push(".zst");
+    let compressed = zstd::stream::encode_all(
+        fs::File::open(path).expect("open rollout for compression"),
+        /*level*/ 0,
+    )
+    .expect("compress rollout");
+    fs::write(compressed_path, compressed).expect("write compressed rollout");
+    fs::remove_file(path).expect("remove plain rollout");
+}
+
+async fn projection_state(pool: &sqlx::SqlitePool, thread_id: ThreadId) -> (i64, i64) {
+    sqlx::query_as::<_, (i64, i64)>(
+        r#"
+SELECT next_rollout_byte_offset, next_rollout_ordinal
+FROM thread_history_projection_state
+WHERE thread_id = ?
+        "#,
+    )
+    .bind(thread_id.to_string())
+    .fetch_one(pool)
+    .await
+    .expect("read projection state")
+}
+
+fn rollout_line(ordinal: Option<u64>, item: RolloutItem) -> String {
+    serde_json::to_string(&RolloutLine {
+        timestamp: "2025-01-01T00:00:00.000Z".to_string(),
+        ordinal,
+        item,
+    })
+    .expect("serialize rollout line")
+}
+
+fn append_suffix(rollout_path: &std::path::Path, suffix: &str) {
+    let mut file = fs::OpenOptions::new()
+        .append(true)
+        .open(rollout_path)
+        .expect("open rollout suffix");
+    file.write_all(suffix.as_bytes()).expect("append suffix");
+    file.flush().expect("flush suffix");
+}
diff --git a/codex-rs/thread-store/src/local/thread_rollout_resolver.rs b/codex-rs/thread-store/src/local/thread_rollout_resolver.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5fad0edd5074f570fb1d706b24f42f2383a339b2
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_rollout_resolver.rs
@@ -0,0 +1,216 @@
+//! Resolves a thread ID to the rollout file the thread currently uses.
+//!
+//! Most threads have one rollout file. `thread/revert` keeps the thread ID stable while switching
+//! the thread to a new rollout file, so callers cannot infer the selected path from the thread ID
+//! alone. This module centralizes live-writer, SQLite, and filesystem fallback resolution.
+
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_rollout::find_archived_thread_path_by_id_str;
+use codex_rollout::find_thread_path_by_id_str;
+
+use super::LocalThreadStore;
+use super::helpers::rollout_path_is_archived;
+use super::live_writer;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+
+/// One thread resolved to the concrete rollout file it currently uses.
+///
+/// For ordinary threads, `thread_id` and `rollout_id` are the same. After `thread/revert`,
+/// `thread_id` stays stable while `rollout_id` identifies the new immutable rollout file.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(super) struct ResolvedThreadRollout {
+    pub(super) thread_id: ThreadId,
+    pub(super) rollout_id: ThreadId,
+    pub(super) path: PathBuf,
+    pub(super) location: RolloutLocation,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum RolloutLocation {
+    Unarchived,
+    Archived,
+}
+
+pub(super) async fn resolve_current(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<Option<ResolvedThreadRollout>> {
+    resolve(store, thread_id, LookupScope::ExcludeArchived).await
+}
+
+pub(super) async fn resolve_current_including_archived(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+) -> ThreadStoreResult<Option<ResolvedThreadRollout>> {
+    resolve(store, thread_id, LookupScope::IncludeArchived).await
+}
+
+#[derive(Clone, Copy)]
+enum LookupScope {
+    ExcludeArchived,
+    IncludeArchived,
+}
+
+impl LookupScope {
+    fn accepts(self, location: RolloutLocation) -> bool {
+        match self {
+            Self::ExcludeArchived => location == RolloutLocation::Unarchived,
+            Self::IncludeArchived => true,
+        }
+    }
+}
+
+/// Resolves a thread's selected rollout in this order:
+///
+/// 1. The live writer, when one exists.
+/// 2. SQLite's selected rollout path.
+/// 3. Filesystem fallback for threads SQLite does not identify as paginated.
+/// 4. Archived filesystem fallback, when requested.
+async fn resolve(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    scope: LookupScope,
+) -> ThreadStoreResult<Option<ResolvedThreadRollout>> {
+    if let Ok(path) = live_writer::rollout_path(store, thread_id).await
+        && codex_rollout::existing_rollout_path(path.as_path())
+            .await
+            .is_some()
+        && let Some(resolved) = resolve_path_in_scope(store, thread_id, path, scope).await?
+    {
+        return Ok(Some(resolved));
+    }
+
+    let state_db_ctx = store.state_db().await;
+    if let Some(state_db_ctx) = state_db_ctx.as_deref() {
+        match state_db_ctx.get_thread(thread_id).await {
+            Ok(Some(metadata)) => {
+                // Once SQLite identifies a thread as paginated, its rollout path is
+                // authoritative: after `thread/revert`, a scan could find an older immutable
+                // rollout for the same thread. Filesystem fallback remains available when SQLite
+                // has no row or identifies the thread as legacy.
+                if let Some(path) =
+                    codex_rollout::existing_rollout_path(metadata.rollout_path.as_path()).await
+                {
+                    let belongs_to_thread =
+                        match codex_rollout::read_session_meta_line(path.as_path()).await {
+                            Ok(session_meta) => session_meta.meta.id == thread_id,
+                            Err(_) => true,
+                        };
+                    if belongs_to_thread {
+                        return resolve_path_in_scope(store, thread_id, path, scope).await;
+                    }
+                }
+                if metadata.history_mode == ThreadHistoryMode::Paginated {
+                    return Ok(None);
+                }
+            }
+            Ok(None) => {}
+            Err(err) => {
+                return Err(ThreadStoreError::Internal {
+                    message: format!("failed to read thread metadata for {thread_id}: {err}"),
+                });
+            }
+        }
+    }
+    if let Some(path) = find_thread_path_by_id_str(
+        store.config.codex_home.as_path(),
+        &thread_id.to_string(),
+        state_db_ctx.as_deref(),
+    )
+    .await
+    .map_err(|err| ThreadStoreError::InvalidRequest {
+        message: format!("failed to locate thread id {thread_id}: {err}"),
+    })? && let Some(resolved) = resolve_path_in_scope(store, thread_id, path, scope).await?
+    {
+        return Ok(Some(resolved));
+    }
+    if !scope.accepts(RolloutLocation::Archived) {
+        return Ok(None);
+    }
+    let path = find_archived_thread_path_by_id_str(
+        store.config.codex_home.as_path(),
+        &thread_id.to_string(),
+        state_db_ctx.as_deref(),
+    )
+    .await
+    .map_err(|err| ThreadStoreError::InvalidRequest {
+        message: format!("failed to locate archived thread id {thread_id}: {err}"),
+    })?;
+    match path {
+        Some(path) => resolve_path_in_scope(store, thread_id, path, scope).await,
+        None => Ok(None),
+    }
+}
+
+async fn resolve_path_in_scope(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    path: PathBuf,
+    scope: LookupScope,
+) -> ThreadStoreResult<Option<ResolvedThreadRollout>> {
+    let location = location_for_path(store, path.as_path());
+    if !scope.accepts(location) {
+        return Ok(None);
+    }
+    resolve_path(thread_id, path, location).await.map(Some)
+}
+
+fn location_for_path(store: &LocalThreadStore, path: &std::path::Path) -> RolloutLocation {
+    if rollout_path_is_archived(store.config.codex_home.as_path(), path) {
+        RolloutLocation::Archived
+    } else {
+        RolloutLocation::Unarchived
+    }
+}
+
+async fn resolve_path(
+    thread_id: ThreadId,
+    path: PathBuf,
+    location: RolloutLocation,
+) -> ThreadStoreResult<ResolvedThreadRollout> {
+    let rollout_id = match codex_rollout::rollout_id_from_path(path.as_path()) {
+        Some(rollout_id) => rollout_id,
+        None => {
+            let history_mode = codex_rollout::read_session_meta_line(path.as_path())
+                .await
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to read session metadata {}: {err}", path.display()),
+                })?
+                .meta
+                .history_mode;
+            rollout_id_from_path_or_legacy_thread_id(path.as_path(), thread_id, history_mode)?
+        }
+    };
+    Ok(ResolvedThreadRollout {
+        thread_id,
+        rollout_id,
+        path,
+        location,
+    })
+}
+
+/// Returns the immutable rollout ID for a path while preserving legacy noncanonical filenames.
+pub(super) fn rollout_id_from_path_or_legacy_thread_id(
+    path: &std::path::Path,
+    thread_id: ThreadId,
+    history_mode: ThreadHistoryMode,
+) -> ThreadStoreResult<ThreadId> {
+    Ok(match codex_rollout::rollout_id_from_path(path) {
+        Some(rollout_id) => rollout_id,
+        None => {
+            if history_mode == ThreadHistoryMode::Paginated {
+                return Err(ThreadStoreError::InvalidRequest {
+                    message: format!(
+                        "paginated rollout path `{}` does not have a canonical rollout filename",
+                        path.display()
+                    ),
+                });
+            }
+            thread_id
+        }
+    })
+}
diff --git a/codex-rs/thread-store/src/local/thread_sections.rs b/codex-rs/thread-store/src/local/thread_sections.rs
new file mode 100644
index 0000000000000000000000000000000000000000..acd6eae954b29ee7e4060aed68d2e2cec18b231a
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_sections.rs
@@ -0,0 +1,99 @@
+use super::LocalThreadStore;
+use crate::CreateThreadSectionParams;
+use crate::DeleteThreadSectionParams;
+use crate::ListThreadSectionsParams;
+use crate::RenameThreadSectionParams;
+use crate::StoredThreadSection;
+use crate::StoredThreadSectionsPage;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use codex_rollout::StateDbHandle;
+
+pub(super) async fn list_thread_sections(
+    store: &LocalThreadStore,
+    params: ListThreadSectionsParams,
+) -> ThreadStoreResult<StoredThreadSectionsPage> {
+    let state_db = state_db(store, "threadSection/list")?;
+    let page = state_db
+        .list_thread_sections(params.cursor.as_deref(), params.limit)
+        .await
+        .map_err(|err| section_error("list", err))?;
+
+    Ok(StoredThreadSectionsPage {
+        sections: page
+            .sections
+            .into_iter()
+            .map(|section| StoredThreadSection {
+                id: section.id,
+                name: section.name,
+                appearance: section.appearance,
+            })
+            .collect(),
+        next_cursor: page.next_cursor,
+    })
+}
+
+pub(super) async fn create_thread_section(
+    store: &LocalThreadStore,
+    params: CreateThreadSectionParams,
+) -> ThreadStoreResult<StoredThreadSection> {
+    let state_db = state_db(store, "threadSection/create")?;
+    let section = state_db
+        .create_thread_section(&params.name, params.appearance)
+        .await
+        .map_err(|err| section_error("create", err))?;
+
+    Ok(StoredThreadSection {
+        id: section.id,
+        name: section.name,
+        appearance: section.appearance,
+    })
+}
+
+pub(super) async fn rename_thread_section(
+    store: &LocalThreadStore,
+    params: RenameThreadSectionParams,
+) -> ThreadStoreResult<Option<StoredThreadSection>> {
+    let state_db = state_db(store, "threadSection/update")?;
+    let section = state_db
+        .rename_thread_section(&params.section_id, &params.name, params.appearance)
+        .await
+        .map_err(|err| section_error("update", err))?;
+
+    Ok(section.map(|section| StoredThreadSection {
+        id: section.id,
+        name: section.name,
+        appearance: section.appearance,
+    }))
+}
+
+pub(super) async fn delete_thread_section(
+    store: &LocalThreadStore,
+    params: DeleteThreadSectionParams,
+) -> ThreadStoreResult<bool> {
+    let state_db = state_db(store, "threadSection/delete")?;
+    state_db
+        .delete_thread_section(&params.section_id)
+        .await
+        .map_err(|err| section_error("delete", err))
+}
+
+fn state_db<'store>(
+    store: &'store LocalThreadStore,
+    operation: &'static str,
+) -> ThreadStoreResult<&'store StateDbHandle> {
+    store
+        .state_db
+        .as_ref()
+        .ok_or(ThreadStoreError::Unsupported { operation })
+}
+
+fn section_error(operation: &str, error: impl std::fmt::Display) -> ThreadStoreError {
+    ThreadStoreError::Internal {
+        message: format!("failed to {operation} thread section: {error}"),
+    }
+}
+
+#[cfg(test)]
+#[path = "thread_sections_tests.rs"]
+mod tests;
diff --git a/codex-rs/thread-store/src/local/thread_sections_tests.rs b/codex-rs/thread-store/src/local/thread_sections_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4bf4e5f12a609368a7b14d91a233eda3e0bb1c3c
--- /dev/null
+++ b/codex-rs/thread-store/src/local/thread_sections_tests.rs
@@ -0,0 +1,84 @@
+use super::LocalThreadStore;
+use crate::CreateThreadSectionParams;
+use crate::DeleteThreadSectionParams;
+use crate::ListThreadSectionsParams;
+use crate::RenameThreadSectionParams;
+use crate::StoredThreadSection;
+use crate::ThreadStore;
+use crate::ThreadStoreError;
+use crate::local::test_support::test_config;
+use pretty_assertions::assert_eq;
+
+#[tokio::test]
+async fn local_thread_sections_require_sqlite_and_preserve_section_identity() {
+    let home = tempfile::TempDir::new().expect("temp dir");
+    let config = test_config(home.path());
+    let unsupported_store = LocalThreadStore::new(config.clone(), /*state_db*/ None);
+    assert!(!unsupported_store.supports_thread_sections());
+    assert!(matches!(
+        unsupported_store
+            .create_thread_section(CreateThreadSectionParams {
+                name: "Research".to_string(),
+                appearance: None,
+            })
+            .await,
+        Err(ThreadStoreError::Unsupported {
+            operation: "threadSection/create"
+        })
+    ));
+
+    let runtime = codex_state::StateRuntime::init(
+        config.sqlite.clone(),
+        config.default_model_provider_id.clone(),
+    )
+    .await
+    .expect("state db should initialize");
+    let store = LocalThreadStore::new(config, Some(runtime));
+    assert!(store.supports_thread_sections());
+
+    let appearance = codex_state::ThreadSectionAppearance {
+        icon: Some("folder".to_string()),
+        color: Some("purple".to_string()),
+    };
+    let section = store
+        .create_thread_section(CreateThreadSectionParams {
+            name: "Research".to_string(),
+            appearance: Some(appearance.clone()),
+        })
+        .await
+        .expect("create section");
+    let sections = store
+        .list_thread_sections(ListThreadSectionsParams {
+            cursor: None,
+            limit: 10,
+        })
+        .await
+        .expect("list sections");
+    assert!(sections.sections.contains(&section));
+
+    let renamed = store
+        .rename_thread_section(RenameThreadSectionParams {
+            section_id: section.id.clone(),
+            name: "Planning".to_string(),
+            appearance: None,
+        })
+        .await
+        .expect("rename section");
+    assert_eq!(
+        renamed,
+        Some(StoredThreadSection {
+            id: section.id.clone(),
+            name: "Planning".to_string(),
+            appearance: Some(appearance),
+        })
+    );
+
+    assert!(
+        store
+            .delete_thread_section(DeleteThreadSectionParams {
+                section_id: section.id,
+            })
+            .await
+            .expect("delete section")
+    );
+}
diff --git a/codex-rs/thread-store/src/local/unarchive_thread.rs b/codex-rs/thread-store/src/local/unarchive_thread.rs
new file mode 100644
index 0000000000000000000000000000000000000000..017d18ad00a3739dbc1188dd4faee35d8957c1c7
--- /dev/null
+++ b/codex-rs/thread-store/src/local/unarchive_thread.rs
@@ -0,0 +1,286 @@
+use super::LocalThreadStore;
+use super::helpers::owned_rollout_paths;
+use super::helpers::restore_rollout_moves;
+use super::helpers::rollout_path_is_archived;
+use super::helpers::scoped_rollout_path;
+use super::helpers::touch_modified_time;
+use super::helpers::validated_rollout_file_name;
+use crate::ArchiveThreadParams;
+use crate::ReadThreadParams;
+use crate::StoredThread;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use codex_rollout::rollout_date_parts;
+
+use super::thread_rollout_resolver;
+use super::thread_rollout_resolver::RolloutLocation;
+
+pub(super) async fn unarchive_thread(
+    store: &LocalThreadStore,
+    params: ArchiveThreadParams,
+) -> ThreadStoreResult<StoredThread> {
+    let thread_id = params.thread_id;
+    let _lifecycle_guard = store.live_writer_locks.lock_lifecycle(thread_id).await;
+    // Archive, delete, and revert use the same cross-process lock while moving or selecting
+    // rollout files. Unarchive must participate before it moves those files back.
+    let _writer_lock = store.acquire_writer_lock(thread_id)?;
+    let state_db_ctx = store.state_db().await;
+    let selected_archived_path =
+        thread_rollout_resolver::resolve_current_including_archived(store, thread_id)
+            .await?
+            .filter(|resolved| resolved.location == RolloutLocation::Archived)
+            .map(|resolved| resolved.path)
+            .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                message: format!("no archived rollout found for thread id {thread_id}"),
+            })?;
+
+    let mut rollout_paths = owned_rollout_paths(store, thread_id).await?;
+    if !rollout_paths.contains(&selected_archived_path) {
+        rollout_paths.push(selected_archived_path.clone());
+    }
+    let mut restored_path = None;
+    let mut rollout_moves = Vec::new();
+    for rollout_path in rollout_paths {
+        if !rollout_path_is_archived(store.config.codex_home.as_path(), rollout_path.as_path()) {
+            continue;
+        }
+        let canonical_archived_path = scoped_rollout_path(
+            store
+                .config
+                .codex_home
+                .join(codex_rollout::ARCHIVED_SESSIONS_SUBDIR),
+            rollout_path.as_path(),
+            "archived",
+        )?;
+        let file_name =
+            validated_rollout_file_name(canonical_archived_path.as_path(), rollout_path.as_path())?;
+        let Some((year, month, day)) = rollout_date_parts(&file_name) else {
+            return Err(ThreadStoreError::InvalidRequest {
+                message: format!(
+                    "rollout path `{}` missing filename timestamp",
+                    rollout_path.display()
+                ),
+            });
+        };
+        let dest_dir = store
+            .config
+            .codex_home
+            .join(codex_rollout::SESSIONS_SUBDIR)
+            .join(year)
+            .join(month)
+            .join(day);
+        std::fs::create_dir_all(&dest_dir).map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to unarchive thread: {err}"),
+        })?;
+        let destination = dest_dir.join(&file_name);
+        if rollout_path == selected_archived_path {
+            restored_path = Some(destination.clone());
+        }
+        if !rollout_moves
+            .iter()
+            .any(|(source, _)| source == &canonical_archived_path)
+        {
+            rollout_moves.push((canonical_archived_path, destination));
+        }
+    }
+    let restored_path = restored_path.ok_or_else(|| ThreadStoreError::Internal {
+        message: format!("failed to unarchive selected rollout for thread {thread_id}"),
+    })?;
+
+    for (index, (source, destination)) in rollout_moves.iter().enumerate() {
+        if let Err(err) = std::fs::rename(source, destination) {
+            if let Err(restore_err) = restore_rollout_moves(&rollout_moves[..index]) {
+                return Err(ThreadStoreError::Internal {
+                    message: format!(
+                        "failed to unarchive thread: {err}; failed to restore moved rollouts: {restore_err}"
+                    ),
+                });
+            }
+            return Err(ThreadStoreError::Internal {
+                message: format!("failed to unarchive thread: {err}"),
+            });
+        }
+    }
+    if let Err(err) = touch_modified_time(restored_path.as_path()) {
+        if let Err(restore_err) = restore_rollout_moves(&rollout_moves) {
+            return Err(ThreadStoreError::Internal {
+                message: format!(
+                    "failed to update unarchived thread timestamp: {err}; failed to restore moved rollouts: {restore_err}"
+                ),
+            });
+        }
+        return Err(ThreadStoreError::Internal {
+            message: format!("failed to update unarchived thread timestamp: {err}"),
+        });
+    }
+
+    if let Some(ctx) = state_db_ctx
+        && let Err(err) = ctx
+            .mark_unarchived(thread_id, restored_path.as_path())
+            .await
+    {
+        if let Err(restore_err) = restore_rollout_moves(&rollout_moves) {
+            return Err(ThreadStoreError::Internal {
+                message: format!(
+                    "failed to update unarchived thread metadata: {err}; failed to restore moved rollouts: {restore_err}"
+                ),
+            });
+        }
+        return Err(ThreadStoreError::Internal {
+            message: format!("failed to update unarchived thread metadata: {err}"),
+        });
+    }
+
+    super::read_thread::read_thread(
+        store,
+        ReadThreadParams {
+            thread_id,
+            include_archived: false,
+            include_history: false,
+        },
+    )
+    .await
+}
+
+#[cfg(test)]
+mod tests {
+    use chrono::Utc;
+    use codex_protocol::ThreadId;
+    use codex_protocol::protocol::SessionSource;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::ThreadStore;
+    use crate::local::LocalThreadStore;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_archived_session_file;
+
+    #[tokio::test]
+    async fn unarchive_thread_restores_rollout_and_returns_updated_thread() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(203);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T13-00-00", uuid)
+            .expect("archived session file");
+
+        let thread = store
+            .unarchive_thread(ArchiveThreadParams { thread_id })
+            .await
+            .expect("unarchive thread");
+
+        assert!(!archived_path.exists());
+        let restored_path = home
+            .path()
+            .join("sessions/2025/01/03")
+            .join(archived_path.file_name().expect("file name"));
+        assert!(restored_path.exists());
+        assert_eq!(thread.thread_id, thread_id);
+        assert_eq!(thread.rollout_path, Some(restored_path));
+        assert_eq!(thread.archived_at, None);
+        assert_eq!(thread.preview, "Archived user message");
+        assert_eq!(
+            thread.first_user_message.as_deref(),
+            Some("Archived user message")
+        );
+    }
+
+    #[tokio::test]
+    async fn unarchive_thread_rejects_a_cross_process_writer() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let owner = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(205);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T13-00-00", uuid)
+            .expect("archived session file");
+        let writer_guard = owner
+            .acquire_writer_lock(thread_id)
+            .expect("acquire writer lock");
+
+        let error = store
+            .unarchive_thread(ArchiveThreadParams { thread_id })
+            .await
+            .expect_err("active writer should block unarchive");
+
+        assert!(matches!(error, ThreadStoreError::Conflict { .. }));
+        assert!(archived_path.exists());
+        drop(writer_guard);
+        store
+            .unarchive_thread(ArchiveThreadParams { thread_id })
+            .await
+            .expect("unarchive after writer exits");
+    }
+
+    #[tokio::test]
+    async fn unarchive_thread_deduplicates_rollout_paths_and_updates_sqlite_metadata() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(204);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T13-00-00", uuid)
+            .expect("archived session file");
+        let alternate_directory = archived_path
+            .parent()
+            .expect("archived session directory")
+            .join("alternate");
+        std::fs::create_dir(&alternate_directory).expect("alternate archived session directory");
+        let selected_archived_path = alternate_directory
+            .join("..")
+            .join(archived_path.file_name().expect("file name"));
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        runtime
+            .mark_backfill_complete(/*last_watermark*/ None)
+            .await
+            .expect("backfill should be complete");
+        let mut builder = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            selected_archived_path,
+            Utc::now(),
+            SessionSource::Cli,
+        );
+        builder.model_provider = Some(config.default_model_provider_id.clone());
+        builder.cwd = home.path().to_path_buf();
+        builder.cli_version = Some("test_version".to_string());
+        let mut metadata = builder.build(config.default_model_provider_id.as_str());
+        metadata.archived_at = Some(metadata.updated_at);
+        metadata.section = Some(codex_state::ThreadSection {
+            id: codex_state::PINNED_THREAD_SECTION_ID.to_string(),
+            name: codex_state::PINNED_THREAD_SECTION_NAME.to_string(),
+            appearance: None,
+        });
+        runtime
+            .upsert_thread(&metadata)
+            .await
+            .expect("state db upsert should succeed");
+
+        let unarchived = store
+            .unarchive_thread(ArchiveThreadParams { thread_id })
+            .await
+            .expect("unarchive thread");
+        assert_eq!(unarchived.section, metadata.section);
+
+        let restored_path = home
+            .path()
+            .join("sessions/2025/01/03")
+            .join(archived_path.file_name().expect("file name"));
+        let updated = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("state db read should succeed")
+            .expect("thread metadata should exist");
+        assert_eq!(updated.rollout_path, restored_path);
+        assert_eq!(updated.archived_at, None);
+        assert_eq!(updated.recency_at, metadata.recency_at);
+        assert_eq!(updated.section, metadata.section);
+    }
+}
diff --git a/codex-rs/thread-store/src/local/update_thread_metadata.rs b/codex-rs/thread-store/src/local/update_thread_metadata.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6caf5b294dd5a190a302fdbc49548fe5ff1ef718
--- /dev/null
+++ b/codex-rs/thread-store/src/local/update_thread_metadata.rs
@@ -0,0 +1,2427 @@
+use std::path::Path;
+use std::path::PathBuf;
+
+use chrono::Utc;
+use codex_protocol::SanitizedGitUrl;
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::GitInfo;
+use codex_protocol::protocol::SessionMetaLine;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_rollout::RolloutConfig;
+use codex_rollout::RolloutItem;
+use codex_rollout::RolloutRecorder;
+use codex_rollout::RolloutRecorderParams;
+use codex_rollout::append_thread_name;
+use codex_rollout::read_session_meta_line;
+use codex_state::ThreadMetadataBuilder;
+use tracing::warn;
+
+use super::LocalThreadStore;
+use super::helpers::git_info_from_parts;
+use super::helpers::permission_profile_to_metadata_value;
+use super::live_writer;
+use super::pending_thread_metadata;
+use super::thread_rollout_resolver;
+use super::thread_rollout_resolver::ResolvedThreadRollout;
+use super::thread_rollout_resolver::RolloutLocation;
+use crate::GitInfoPatch;
+use crate::ReadThreadParams;
+use crate::StoredThread;
+use crate::ThreadMetadataPatch;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::UpdateThreadMetadataParams;
+use crate::local::read_thread;
+
+pub(super) async fn update_thread_metadata(
+    store: &LocalThreadStore,
+    params: UpdateThreadMetadataParams,
+) -> ThreadStoreResult<StoredThread> {
+    let thread_id = params.thread_id;
+    let mut pending_metadata = store.pending_thread_metadata.lock(thread_id).await;
+    let pending_patch = pending_metadata
+        .as_ref()
+        .and_then(|metadata| metadata.as_ref().cloned());
+    let mut patch = params.patch;
+    if let Some(staged_patch) = pending_patch.as_ref() {
+        let mut merged_patch = staged_patch.clone();
+        merged_patch.merge(patch);
+        patch = merged_patch;
+    }
+    if patch.project_id.is_some() && store.state_db().await.is_none() {
+        return Err(ThreadStoreError::Unsupported {
+            operation: "projects",
+        });
+    }
+    if patch.is_empty() {
+        return read_thread::read_thread(
+            store,
+            ReadThreadParams {
+                thread_id,
+                include_archived: params.include_archived,
+                include_history: false,
+            },
+        )
+        .await;
+    }
+
+    let staged_requires_rollout_compat = pending_patch
+        .as_ref()
+        .is_some_and(|patch| patch.memory_mode.is_some() || patch.git_info.is_some());
+    let requires_rollout_compat =
+        staged_requires_rollout_compat || requires_rollout_compatibility_update(&patch);
+    let has_explicit_metadata = patch.name.is_some() || requires_rollout_compat;
+    let history_mode = if has_explicit_metadata {
+        match live_writer::live_writer_parts(store, thread_id).await {
+            Ok((_recorder, _rollout_id, history_mode)) => Some(history_mode),
+            Err(ThreadStoreError::ThreadNotFound { .. }) => Some(
+                read_thread::read_thread(
+                    store,
+                    ReadThreadParams {
+                        thread_id,
+                        include_archived: params.include_archived,
+                        include_history: false,
+                    },
+                )
+                .await?
+                .history_mode,
+            ),
+            Err(err) => return Err(err),
+        }
+    } else {
+        None
+    };
+    let paginated = matches!(history_mode, Some(ThreadHistoryMode::Paginated));
+    let needs_rollout_compat = requires_rollout_compat || patch.name.is_some();
+    // Reject competing writers before committing any part of a legacy rollout patch to SQLite.
+    let writer_lock = if !paginated
+        && needs_rollout_compat
+        && (patch.memory_mode.is_some() || patch.git_info.is_some())
+    {
+        let live = store
+            .live_recorders
+            .lock()
+            .await
+            .get(&thread_id)
+            .map(|entry| entry.writer_lock.clone());
+        Some(match live {
+            Some(guard) => guard,
+            None => store.acquire_writer_lock(thread_id)?,
+        })
+    } else {
+        None
+    };
+    let require_sqlite_write =
+        pending_patch.is_some() || sqlite_write_failure_should_block(&patch) || paginated;
+    let mut updated = apply_metadata_update(
+        store,
+        thread_id,
+        patch.clone(),
+        params.include_archived,
+        require_sqlite_write,
+        history_mode,
+    )
+    .await?;
+    if paginated
+        && requires_rollout_compat
+        && let Some(git_info) = patch.git_info.as_ref()
+    {
+        // The generic upsert preserves non-null Git fields for rollout reconciliation. Apply the
+        // explicit patch afterward so clears are written to SQLite too.
+        let Some(state_db) = store.state_db().await else {
+            return Err(ThreadStoreError::Internal {
+                message: format!("sqlite state db unavailable for thread {thread_id}"),
+            });
+        };
+        apply_thread_git_info_patch(state_db.as_ref(), thread_id, git_info).await?;
+        updated = read_thread::read_thread(
+            store,
+            ReadThreadParams {
+                thread_id,
+                include_archived: params.include_archived,
+                include_history: false,
+            },
+        )
+        .await?;
+    }
+    if paginated {
+        // Paginated metadata lives in SQLite. Keep the name index update, then stop before the
+        // legacy SessionMeta compatibility path below.
+        if let Some(name) = patch.name.as_ref()
+            && let Err(err) = append_thread_name(
+                store.config.codex_home.as_path(),
+                thread_id,
+                name.as_deref().unwrap_or_default(),
+            )
+            .await
+        {
+            warn!("failed to index paginated thread name for {thread_id}: {err}");
+        }
+        if pending_patch.is_some() {
+            remove_pending_thread_metadata(store, thread_id, &mut pending_metadata).await;
+        }
+        return Ok(updated);
+    }
+    if !needs_rollout_compat {
+        if pending_patch.is_some() {
+            remove_pending_thread_metadata(store, thread_id, &mut pending_metadata).await;
+        }
+        return Ok(updated);
+    }
+
+    if live_writer::rollout_path(store, thread_id).await.is_ok() {
+        live_writer::persist_thread(store, thread_id).await?;
+    }
+    let mut resolved_rollout = if params.include_archived {
+        thread_rollout_resolver::resolve_current_including_archived(store, thread_id).await?
+    } else {
+        thread_rollout_resolver::resolve_current(store, thread_id).await?
+    }
+    .ok_or_else(|| ThreadStoreError::InvalidRequest {
+        message: format!("thread not found: {thread_id}"),
+    })?;
+    let name = patch.name;
+    let git_info = patch.git_info;
+    if let Some(memory_mode) = patch.memory_mode
+        && let Some(writer_lock) = writer_lock.as_ref()
+    {
+        update_rollout_metadata(
+            store,
+            thread_id,
+            &resolved_rollout.path,
+            writer_lock,
+            |meta| {
+                // Replay retains prior git metadata when this marker omits it.
+                meta.git = None;
+                meta.meta.memory_mode = Some(memory_mode_as_str(memory_mode).to_string());
+            },
+        )
+        .await?;
+        refresh_resolved_rollout_path(&mut resolved_rollout).await;
+    }
+
+    let state_db_ctx = store.state_db().await;
+    codex_rollout::state_db::reconcile_rollout(
+        state_db_ctx.as_deref(),
+        resolved_rollout.path.as_path(),
+        store.config.default_model_provider_id.as_str(),
+        /*builder*/ None,
+        &[],
+        /*archived_only*/
+        (resolved_rollout.location == RolloutLocation::Archived).then_some(true),
+        /*new_thread_memory_mode*/ None,
+    )
+    .await;
+
+    if let Some(name) = name {
+        append_thread_name(
+            store.config.codex_home.as_path(),
+            thread_id,
+            &name.unwrap_or_default(),
+        )
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to index thread name: {err}"),
+        })?;
+    }
+
+    let resolved_git_info = match git_info {
+        Some(git_info) => {
+            let Some(state_db) = store.state_db().await else {
+                return Err(ThreadStoreError::Internal {
+                    message: format!("sqlite state db unavailable for thread {thread_id}"),
+                });
+            };
+            let metadata =
+                state_db
+                    .get_thread(thread_id)
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!(
+                            "failed to read git metadata for thread {thread_id}: {err}"
+                        ),
+                    })?;
+            let Some(metadata) = metadata else {
+                return Err(ThreadStoreError::Internal {
+                    message: format!("thread metadata unavailable before git update: {thread_id}"),
+                });
+            };
+            let memory_mode = state_db
+                .get_thread_memory_mode(thread_id)
+                .await
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to read memory mode for thread {thread_id}: {err}"),
+                })?;
+            let existing_git_info = git_info_from_parts(
+                metadata.git_sha,
+                metadata.git_branch,
+                metadata.git_origin_url,
+            );
+            Some((
+                resolve_git_info_patch(existing_git_info, git_info),
+                memory_mode,
+            ))
+        }
+        None => None,
+    };
+    if let Some(((sha, branch, origin_url), memory_mode)) = resolved_git_info.as_ref()
+        && let Some(writer_lock) = writer_lock.as_ref()
+    {
+        update_rollout_metadata(
+            store,
+            thread_id,
+            &resolved_rollout.path,
+            writer_lock,
+            |meta| {
+                meta.git = Some(GitInfo {
+                    commit_hash: sha.as_deref().map(codex_git_utils::GitSha::new),
+                    branch: branch.clone(),
+                    repository_url: origin_url.clone(),
+                });
+                meta.meta.memory_mode = memory_mode.clone();
+            },
+        )
+        .await?;
+        refresh_resolved_rollout_path(&mut resolved_rollout).await;
+        apply_thread_git_info(store, thread_id, sha, branch, origin_url).await?;
+    }
+
+    let mut thread = match read_thread::read_thread(
+        store,
+        ReadThreadParams {
+            thread_id,
+            include_archived: params.include_archived,
+            include_history: false,
+        },
+    )
+    .await
+    {
+        Ok(thread) => thread,
+        Err(_) => {
+            read_thread::read_thread_by_rollout_path(
+                store,
+                resolved_rollout.path,
+                params.include_archived,
+                /*include_history*/ false,
+            )
+            .await?
+        }
+    };
+    if let Some(((sha, branch, origin_url), _memory_mode)) = resolved_git_info {
+        thread.git_info = git_info_from_parts(sha, branch, origin_url);
+    }
+    if pending_patch.is_some() {
+        remove_pending_thread_metadata(store, thread_id, &mut pending_metadata).await;
+    }
+    Ok(thread)
+}
+
+async fn remove_pending_thread_metadata(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    pending_metadata: &mut Option<pending_thread_metadata::LockedPendingThreadMetadata>,
+) {
+    if let Some(mut metadata) = pending_metadata.take() {
+        *metadata = None;
+        drop(metadata);
+        store.pending_thread_metadata.remove(thread_id).await;
+    }
+}
+
+async fn refresh_resolved_rollout_path(resolved: &mut ResolvedThreadRollout) {
+    if let Some(path) = codex_rollout::existing_rollout_path(resolved.path.as_path()).await {
+        resolved.path = path;
+    }
+}
+
+async fn apply_metadata_update(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    patch: ThreadMetadataPatch,
+    include_archived: bool,
+    require_sqlite_write: bool,
+    history_mode: Option<ThreadHistoryMode>,
+) -> ThreadStoreResult<StoredThread> {
+    let live_rollout_path = live_writer::rollout_path(store, thread_id).await.ok();
+    let mut rollout_path = patch.rollout_path.clone().or(live_rollout_path);
+    let mut rollout_path_archived = rollout_path
+        .as_deref()
+        .is_some_and(|path| rollout_path_is_archived(store, path));
+    let state_db = store.state_db().await;
+    let sqlite_write_result: ThreadStoreResult<()> = if let Some(state_db) = state_db.as_ref() {
+        let patch = patch.clone();
+        async {
+            let existing =
+                state_db
+                    .get_thread(thread_id)
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!("failed to read thread metadata for {thread_id}: {err}"),
+                    })?;
+            let project_id = if existing.is_none()
+                && let Some(Some(project_id)) = patch.project_id.as_ref()
+                && state_db
+                    .get_project(project_id)
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!(
+                            "failed to read initial thread project for {thread_id}: {err}"
+                        ),
+                    })?
+                    .is_none()
+            {
+                Some(None)
+            } else {
+                patch.project_id.clone()
+            };
+            let advance_recency_at = patch.advance_recency_at;
+            if existing.is_none() && rollout_path.is_none() {
+                let resolved = if include_archived {
+                    thread_rollout_resolver::resolve_current_including_archived(store, thread_id)
+                        .await?
+                } else {
+                    thread_rollout_resolver::resolve_current(store, thread_id).await?
+                }
+                .ok_or_else(|| ThreadStoreError::InvalidRequest {
+                    message: format!("thread not found: {thread_id}"),
+                })?;
+                rollout_path_archived = resolved.location == RolloutLocation::Archived;
+                rollout_path = Some(resolved.path);
+            }
+            let mut metadata = match existing.clone() {
+                Some(metadata) => metadata,
+                None => {
+                    let rollout_path =
+                        rollout_path
+                            .as_deref()
+                            .ok_or_else(|| ThreadStoreError::Internal {
+                                message: format!(
+                                    "thread metadata missing rollout path for {thread_id}"
+                                ),
+                            })?;
+                    metadata_for_missing_sqlite_row(
+                        store,
+                        thread_id,
+                        rollout_path,
+                        rollout_path_archived,
+                        &patch,
+                    )
+                    .await?
+                }
+            };
+            if let Some(rollout_path) = rollout_path {
+                metadata.rollout_path = rollout_path;
+            }
+            if let Some(history_mode) = history_mode {
+                // The read above gets the canonical mode from the rollout. Persist it before an
+                // explicit paginated patch makes SQLite metadata authoritative.
+                metadata.history_mode = history_mode;
+            }
+            if let Some(preview) = patch.preview {
+                metadata.preview = Some(preview);
+            }
+            if let Some(title) = patch.title {
+                metadata.title = title;
+            }
+            if let Some(model_provider) = patch.model_provider {
+                metadata.model_provider = model_provider;
+            }
+            if let Some(model) = patch.model {
+                metadata.model = Some(model);
+            }
+            if let Some(reasoning_effort) = patch.reasoning_effort {
+                metadata.reasoning_effort = reasoning_effort;
+            }
+            if let Some(created_at) = patch.created_at {
+                metadata.created_at = created_at;
+            }
+            if let Some(updated_at) = patch.updated_at {
+                metadata.updated_at = updated_at;
+            }
+            if existing.is_none()
+                && let Some(recency_at) = advance_recency_at
+            {
+                metadata.recency_at = recency_at;
+            }
+            if let Some(source) = patch.source {
+                metadata.source = enum_to_string(&source);
+            }
+            metadata.originator = metadata.originator.or(patch.originator);
+            if let Some(thread_source) = patch.thread_source {
+                metadata.thread_source = thread_source;
+            }
+            if let Some(agent_nickname) = patch.agent_nickname {
+                metadata.agent_nickname = agent_nickname;
+            }
+            if let Some(agent_role) = patch.agent_role {
+                metadata.agent_role = agent_role;
+            }
+            if let Some(agent_path) = patch.agent_path {
+                metadata.agent_path = agent_path;
+            }
+            if let Some(cwd) = patch.cwd {
+                metadata.cwd = normalize_cwd(cwd);
+            }
+            if let Some(cli_version) = patch.cli_version {
+                metadata.cli_version = cli_version;
+            }
+            if let Some(approval_mode) = patch.approval_mode {
+                metadata.approval_mode = enum_to_string(&approval_mode);
+            }
+            if let Some(permission_profile) = patch.permission_profile {
+                metadata.sandbox_policy = permission_profile_to_metadata_value(&permission_profile);
+            }
+            if let Some(token_usage) = patch.token_usage {
+                metadata.tokens_used = token_usage.total_tokens.max(0);
+            }
+            if let Some(first_user_message) = patch.first_user_message {
+                metadata.first_user_message = Some(first_user_message);
+            }
+            if let Some(git_info) = patch.git_info {
+                let existing_git_info = git_info_from_parts(
+                    metadata.git_sha.clone(),
+                    metadata.git_branch.clone(),
+                    metadata.git_origin_url.clone(),
+                );
+                let (sha, branch, origin_url) = resolve_git_info_patch(existing_git_info, git_info);
+                metadata.git_sha = sha;
+                metadata.git_branch = branch;
+                metadata.git_origin_url = origin_url;
+            }
+            if let Some(project_id) = project_id.as_ref() {
+                metadata.project_id = project_id.clone();
+            }
+            if let Some(daybreak_enabled) = patch.daybreak_enabled {
+                metadata.daybreak_enabled = Some(daybreak_enabled);
+            }
+            let upsert_result = state_db.upsert_thread(&metadata).await;
+            if existing.is_none()
+                && metadata.project_id.is_some()
+                && matches!(&upsert_result, Err(err) if err.to_string().contains("FOREIGN KEY constraint failed"))
+            {
+                metadata.project_id = None;
+                state_db.upsert_thread(&metadata).await.map_err(|err| {
+                    ThreadStoreError::Internal {
+                        message: format!("failed to update thread metadata for {thread_id}: {err}"),
+                    }
+                })?;
+            } else {
+                upsert_result.map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to update thread metadata for {thread_id}: {err}"),
+                })?;
+            }
+            if existing.is_some()
+                && let Some(project_id) = project_id.as_ref()
+            {
+                state_db
+                    .set_thread_project(&thread_id.to_string(), project_id.as_deref())
+                    .await
+                    .map_err(|err| {
+                        let message = err.to_string();
+                        if message.contains("project not found") {
+                            ThreadStoreError::InvalidRequest { message }
+                        } else {
+                            ThreadStoreError::Internal {
+                                message: format!(
+                                    "failed to update thread project for {thread_id}: {err}"
+                                ),
+                            }
+                        }
+                    })?
+                    .ok_or_else(|| ThreadStoreError::Internal {
+                        message: format!(
+                            "thread metadata unavailable before project update: {thread_id}"
+                        ),
+                    })?;
+            }
+            if let Some(name) = patch.name.as_ref() {
+                let history_mode = history_mode.ok_or_else(|| ThreadStoreError::Internal {
+                    message: format!(
+                        "thread history mode unavailable before name update: {thread_id}"
+                    ),
+                })?;
+                let updated = match history_mode {
+                    ThreadHistoryMode::Legacy => {
+                        state_db
+                            .update_thread_title(thread_id, name.as_deref().unwrap_or_default())
+                            .await
+                    }
+                    ThreadHistoryMode::Paginated => {
+                        state_db
+                            .update_thread_name(thread_id, name.as_deref())
+                            .await
+                    }
+                }
+                .map_err(|err| ThreadStoreError::Internal {
+                    message: format!("failed to set thread name: {err}"),
+                })?;
+                if !updated {
+                    return Err(ThreadStoreError::Internal {
+                        message: format!(
+                            "thread metadata unavailable before name update: {thread_id}"
+                        ),
+                    });
+                }
+            }
+            if existing.is_some()
+                && let Some(recency_at) = advance_recency_at
+            {
+                state_db
+                    .touch_thread_recency_at(thread_id, recency_at)
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!(
+                            "failed to advance thread recency_at for {thread_id}: {err}"
+                        ),
+                    })?;
+            }
+            if let Some(memory_mode) = patch.memory_mode {
+                state_db
+                    .set_thread_memory_mode(thread_id, memory_mode_as_str(memory_mode))
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!("failed to update memory mode for {thread_id}: {err}"),
+                    })?;
+            }
+            if let Some(daybreak_enabled) = patch.daybreak_enabled
+                && !state_db
+                    .set_thread_daybreak_enabled(thread_id, daybreak_enabled)
+                    .await
+                    .map_err(|err| ThreadStoreError::Internal {
+                        message: format!(
+                            "failed to update Daybreak preference for {thread_id}: {err}"
+                        ),
+                    })?
+            {
+                return Err(ThreadStoreError::Internal {
+                    message: format!(
+                        "thread metadata unavailable before Daybreak update: {thread_id}"
+                    ),
+                });
+            }
+            Ok(())
+        }
+        .await
+    } else if require_sqlite_write {
+        Err(ThreadStoreError::Internal {
+            message: format!("sqlite state db unavailable for thread {thread_id}"),
+        })
+    } else {
+        Ok(())
+    };
+    match sqlite_write_result {
+        Ok(()) => {}
+        Err(err) if require_sqlite_write || !sqlite_write_error_is_best_effort(&err) => {
+            return Err(err);
+        }
+        Err(err) => {
+            warn!("state db update_thread_metadata failed for {thread_id}: {err}");
+        }
+    }
+
+    read_thread::read_thread(
+        store,
+        ReadThreadParams {
+            thread_id,
+            include_archived,
+            include_history: false,
+        },
+    )
+    .await
+}
+
+async fn metadata_for_missing_sqlite_row(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    rollout_path: &Path,
+    rollout_path_archived: bool,
+    patch: &ThreadMetadataPatch,
+) -> ThreadStoreResult<codex_state::ThreadMetadata> {
+    let created_at = patch
+        .created_at
+        .or(patch.updated_at)
+        .unwrap_or_else(Utc::now);
+    let mut builder = ThreadMetadataBuilder::new(
+        thread_id,
+        rollout_path.to_path_buf(),
+        created_at,
+        patch.source.clone().unwrap_or(SessionSource::Unknown),
+    );
+    builder.model_provider = patch.model_provider.clone();
+    builder.history_mode = canonical_history_mode(store, thread_id, rollout_path).await?;
+    builder.thread_source = patch.thread_source.clone().flatten();
+    builder.agent_nickname = patch.agent_nickname.clone().flatten();
+    builder.agent_role = patch.agent_role.clone().flatten();
+    builder.agent_path = patch.agent_path.clone().flatten();
+    builder.cwd = patch.cwd.clone().map(normalize_cwd).unwrap_or_default();
+    builder.cli_version = patch.cli_version.clone();
+    let mut metadata = builder.build(store.config.default_model_provider_id.as_str());
+    if rollout_path_archived {
+        metadata.archived_at = Some(metadata.updated_at);
+    }
+    Ok(metadata)
+}
+
+async fn canonical_history_mode(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    rollout_path: &Path,
+) -> ThreadStoreResult<ThreadHistoryMode> {
+    let session_meta = match read_session_meta_line(rollout_path).await {
+        Ok(session_meta) => session_meta,
+        Err(err) => {
+            if codex_rollout::existing_rollout_path(rollout_path)
+                .await
+                .is_none()
+                && let Some(history_mode) = store
+                    .live_recorders
+                    .lock()
+                    .await
+                    .get(&thread_id)
+                    .map(|entry| entry.history_mode)
+            {
+                // The live writer retains the canonical mode selected before its deferred
+                // SessionMeta reaches JSONL.
+                return Ok(history_mode);
+            }
+            return Err(ThreadStoreError::Internal {
+                message: format!(
+                    "failed to read canonical session metadata for {thread_id}: {err}"
+                ),
+            });
+        }
+    };
+    if session_meta.meta.id != thread_id {
+        return Err(ThreadStoreError::Internal {
+            message: format!(
+                "failed to rebuild thread metadata: rollout session metadata id mismatch: expected {thread_id}, found {}",
+                session_meta.meta.id
+            ),
+        });
+    }
+    Ok(session_meta.meta.history_mode)
+}
+
+fn requires_rollout_compatibility_update(patch: &ThreadMetadataPatch) -> bool {
+    if patch.memory_mode.is_none() && patch.git_info.is_none() {
+        return false;
+    }
+    !has_observed_metadata_facts(patch)
+}
+
+fn sqlite_write_failure_should_block(patch: &ThreadMetadataPatch) -> bool {
+    // Before live metadata sync moved above the rollout writer, SQLite sync failures for
+    // transcript-derived metadata, thread names, and memory-mode indexing were log-only. Keep that
+    // failure isolation so a corrupted optional state DB does not make JSONL transcript durability
+    // look broken. Explicit git-only updates still require SQLite because partial git patches need
+    // the existing SQLite value to preserve unspecified fields. Project and Daybreak updates
+    // require SQLite because those preferences only exist in the state database.
+    patch.project_id.is_some()
+        || patch.daybreak_enabled.is_some()
+        || (patch.git_info.is_some() && !has_observed_metadata_facts(patch))
+}
+
+fn sqlite_write_error_is_best_effort(err: &ThreadStoreError) -> bool {
+    matches!(err, ThreadStoreError::Internal { .. })
+}
+
+fn has_observed_metadata_facts(patch: &ThreadMetadataPatch) -> bool {
+    patch.rollout_path.is_some()
+        || patch.preview.is_some()
+        || patch.title.is_some()
+        || patch.model_provider.is_some()
+        || patch.model.is_some()
+        || patch.reasoning_effort.is_some()
+        || patch.created_at.is_some()
+        || patch.source.is_some()
+        || patch.originator.is_some()
+        || patch.thread_source.is_some()
+        || patch.agent_nickname.is_some()
+        || patch.agent_role.is_some()
+        || patch.agent_path.is_some()
+        || patch.cwd.is_some()
+        || patch.cli_version.is_some()
+        || patch.approval_mode.is_some()
+        || patch.permission_profile.is_some()
+        || patch.token_usage.is_some()
+        || patch.first_user_message.is_some()
+}
+
+fn enum_to_string<T: serde::Serialize>(value: &T) -> String {
+    match serde_json::to_value(value) {
+        Ok(serde_json::Value::String(value)) => value,
+        Ok(other) => other.to_string(),
+        Err(_) => String::new(),
+    }
+}
+
+fn normalize_cwd(cwd: PathBuf) -> PathBuf {
+    codex_utils_path::normalize_for_path_comparison(cwd.as_path()).unwrap_or(cwd)
+}
+
+async fn apply_thread_git_info_patch(
+    state_db: &codex_state::StateRuntime,
+    thread_id: ThreadId,
+    git_info: &GitInfoPatch,
+) -> ThreadStoreResult<()> {
+    let updated = state_db
+        .update_thread_git_info(
+            thread_id,
+            git_info.sha.as_ref().map(|sha| sha.as_deref()),
+            git_info.branch.as_ref().map(|branch| branch.as_deref()),
+            git_info
+                .origin_url
+                .as_ref()
+                .map(|origin_url| origin_url.as_ref()),
+        )
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to update git metadata for thread {thread_id}: {err}"),
+        })?;
+    if updated {
+        Ok(())
+    } else {
+        Err(ThreadStoreError::Internal {
+            message: format!("thread metadata unavailable before git update: {thread_id}"),
+        })
+    }
+}
+
+async fn apply_thread_git_info(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    sha: &Option<String>,
+    branch: &Option<String>,
+    origin_url: &Option<SanitizedGitUrl>,
+) -> ThreadStoreResult<()> {
+    let Some(state_db) = store.state_db().await else {
+        return Err(ThreadStoreError::Internal {
+            message: format!("sqlite state db unavailable for thread {thread_id}"),
+        });
+    };
+    let updated = state_db
+        .update_thread_git_info(
+            thread_id,
+            Some(sha.as_deref()),
+            Some(branch.as_deref()),
+            Some(origin_url.as_ref()),
+        )
+        .await
+        .map_err(|err| ThreadStoreError::Internal {
+            message: format!("failed to update git metadata for thread {thread_id}: {err}"),
+        })?;
+    if updated {
+        Ok(())
+    } else {
+        Err(ThreadStoreError::Internal {
+            message: format!("thread metadata disappeared before update completed: {thread_id}"),
+        })
+    }
+}
+
+fn resolve_git_info_patch(
+    existing: Option<GitInfo>,
+    git_info: GitInfoPatch,
+) -> (Option<String>, Option<String>, Option<SanitizedGitUrl>) {
+    let (existing_sha, existing_branch, existing_origin_url) = match existing {
+        Some(info) => (
+            info.commit_hash.map(|sha| sha.0),
+            info.branch,
+            info.repository_url,
+        ),
+        None => (None, None, None),
+    };
+    let sha = git_info.sha.unwrap_or(existing_sha);
+    let branch = git_info.branch.unwrap_or(existing_branch);
+    let origin_url = git_info.origin_url.unwrap_or(existing_origin_url);
+    (sha, branch, origin_url)
+}
+
+// Both metadata patches use the same owned recorder; temporary writers also survive cancellation.
+async fn update_rollout_metadata(
+    store: &LocalThreadStore,
+    thread_id: ThreadId,
+    path: &Path,
+    writer_lock: &super::WriterLockGuard,
+    patch: impl FnOnce(&mut SessionMetaLine),
+) -> ThreadStoreResult<()> {
+    // Keep shutdown from closing the selected recorder before its metadata append is flushed.
+    let _live_writer_guard = store.live_writer_locks.lock(thread_id).await;
+    let io_error = |err| ThreadStoreError::Internal {
+        message: format!("failed to update rollout metadata: {err}"),
+    };
+    let recorder = store
+        .live_recorders
+        .lock()
+        .await
+        .get(&thread_id)
+        .map(|entry| entry.recorder.clone());
+    let mut metadata = codex_rollout::read_session_meta_line(path)
+        .await
+        .map_err(io_error)?;
+    if metadata.meta.id != thread_id {
+        return Err(ThreadStoreError::Internal {
+            message: format!(
+                "rollout session metadata id mismatch: expected {thread_id}, found {}",
+                metadata.meta.id
+            ),
+        });
+    }
+    let temporary = recorder.is_none();
+    let recorder = match recorder {
+        Some(recorder) => recorder,
+        None => RolloutRecorder::new_with_writer_lock(
+            &RolloutConfig {
+                codex_home: store.config.codex_home.clone(),
+                sqlite: store.config.sqlite.clone(),
+                cwd: metadata.meta.cwd.clone(),
+                model_provider_id: store.config.default_model_provider_id.clone(),
+                generate_memories: metadata.meta.memory_mode.as_deref() != Some("disabled"),
+            },
+            RolloutRecorderParams::resume(path.to_path_buf()),
+            writer_lock.clone(),
+        )
+        .await
+        .map_err(io_error)?,
+    };
+    patch(&mut metadata);
+    recorder
+        .record_canonical_items(&[RolloutItem::SessionMeta(metadata)])
+        .await
+        .map_err(io_error)?;
+    recorder.flush().await.map_err(io_error)?;
+    if temporary {
+        recorder.shutdown().await.map_err(io_error)?;
+    }
+    Ok(())
+}
+
+fn memory_mode_as_str(mode: ThreadMemoryMode) -> &'static str {
+    match mode {
+        ThreadMemoryMode::Enabled => "enabled",
+        ThreadMemoryMode::Disabled => "disabled",
+    }
+}
+
+fn rollout_path_is_archived(store: &LocalThreadStore, path: &Path) -> bool {
+    super::helpers::rollout_path_is_archived(store.config.codex_home.as_path(), path)
+}
+
+#[cfg(test)]
+mod tests {
+    use codex_protocol::models::PermissionProfile;
+    use codex_protocol::openai_models::ReasoningEffort;
+    use codex_protocol::protocol::ThreadHistoryMode;
+    use codex_utils_absolute_path::test_support::PathExt;
+    use futures::FutureExt;
+    use pretty_assertions::assert_eq;
+    use serde_json::Value;
+    use serde_json::json;
+    use tempfile::TempDir;
+    use uuid::Uuid;
+
+    use super::*;
+    use crate::GitInfoPatch;
+    use crate::ListThreadsParams;
+    use crate::MoveThreadToSectionParams;
+    use crate::ResumeThreadParams;
+    use crate::SortDirection;
+    use crate::ThreadMetadataPatch;
+    use crate::ThreadPersistenceMetadata;
+    use crate::ThreadSortKey;
+    use crate::ThreadStore;
+    use crate::local::LocalThreadStore;
+    use crate::local::test_support::test_config;
+    use crate::local::test_support::write_archived_session_file;
+    use crate::local::test_support::write_session_file;
+    use crate::local::test_support::write_session_file_with_history_mode;
+
+    #[tokio::test]
+    async fn update_thread_metadata_sets_name_on_active_rollout_and_indexes_name() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(301);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T14-00-00", uuid).expect("session file");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("A sharper name".to_string())),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set thread name")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.name.as_deref(), Some("A sharper name"));
+        let latest_name = codex_rollout::find_thread_name_by_id(home.path(), &thread_id)
+            .await
+            .expect("find thread name");
+        assert_eq!(latest_name.as_deref(), Some("A sharper name"));
+    }
+
+    #[tokio::test]
+    async fn section_moves_persist_in_sqlite_without_changing_the_rollout() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(320);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let rollout_path =
+            write_session_file(home.path(), "2025-01-03T14-20-00", uuid).expect("session file");
+        let original_rollout = std::fs::read_to_string(&rollout_path).expect("read rollout");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            rollout_path.as_path(),
+            "test-provider",
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        store
+            .move_thread_to_section(MoveThreadToSectionParams {
+                thread_id,
+                section: Some(codex_state::PINNED_THREAD_SECTION_ID.to_string()),
+                before_thread_id: None,
+            })
+            .await
+            .expect("pin thread");
+
+        let pinned = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read pinned thread");
+
+        assert_eq!(
+            pinned.section,
+            Some(codex_state::ThreadSection {
+                id: codex_state::PINNED_THREAD_SECTION_ID.to_string(),
+                name: codex_state::PINNED_THREAD_SECTION_NAME.to_string(),
+                appearance: None,
+            })
+        );
+        let pinned_metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("read pinned metadata")
+            .expect("pinned metadata");
+        assert_eq!(
+            pinned_metadata.section,
+            Some(codex_state::ThreadSection {
+                id: codex_state::PINNED_THREAD_SECTION_ID.to_string(),
+                name: codex_state::PINNED_THREAD_SECTION_NAME.to_string(),
+                appearance: None,
+            })
+        );
+        assert_eq!(pinned_metadata.preview.as_deref(), Some("Hello from user"));
+        assert_eq!(pinned_metadata.source, "cli");
+        let pinned_page = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::RecencyAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: None,
+                cwd_filters: None,
+                section: Some(Some(codex_state::PINNED_THREAD_SECTION_ID.to_string())),
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: true,
+            })
+            .await
+            .expect("list pinned thread");
+        assert_eq!(
+            pinned_page
+                .items
+                .iter()
+                .map(|thread| thread.thread_id)
+                .collect::<Vec<_>>(),
+            vec![thread_id]
+        );
+        let read_by_path = store
+            .read_thread_by_rollout_path(
+                rollout_path.clone(),
+                /*include_archived*/ false,
+                /*include_history*/ false,
+            )
+            .await
+            .expect("read pinned thread by rollout path");
+        assert_eq!(
+            read_by_path.section,
+            Some(codex_state::ThreadSection {
+                id: codex_state::PINNED_THREAD_SECTION_ID.to_string(),
+                name: codex_state::PINNED_THREAD_SECTION_NAME.to_string(),
+                appearance: None,
+            })
+        );
+        assert_eq!(
+            std::fs::read_to_string(&rollout_path).expect("read rollout"),
+            original_rollout
+        );
+
+        store
+            .move_thread_to_section(MoveThreadToSectionParams {
+                thread_id,
+                section: None,
+                before_thread_id: None,
+            })
+            .await
+            .expect("clear thread section");
+
+        let unpinned = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read unpinned thread");
+
+        assert_eq!(unpinned.section, None);
+        assert_eq!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("read cleared metadata")
+                .expect("cleared metadata")
+                .section,
+            None
+        );
+        assert_eq!(
+            std::fs::read_to_string(&rollout_path).expect("read rollout"),
+            original_rollout
+        );
+    }
+
+    #[tokio::test]
+    async fn paginated_name_updates_use_sqlite_without_rollout_writes() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(318);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T14-15-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let original_rollout = std::fs::read_to_string(&path).expect("read rollout");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("Canonical paginated name".to_string())),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set paginated thread name")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.name.as_deref(), Some("Canonical paginated name"));
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("read metadata")
+            .expect("thread metadata");
+        assert_eq!(metadata.name.as_deref(), Some("Canonical paginated name"));
+        assert!(metadata.title.is_empty());
+        assert_eq!(
+            codex_rollout::find_thread_name_by_id(home.path(), &thread_id)
+                .await
+                .expect("find thread name")
+                .as_deref(),
+            Some("Canonical paginated name")
+        );
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    title: Some("Derived first message".to_string()),
+                    preview: Some("Derived first message".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("apply derived paginated metadata")
+            .expect("local store returns updated thread");
+        assert_eq!(thread.name.as_deref(), Some("Canonical paginated name"));
+
+        let session_index_path = home.path().join("session_index.jsonl");
+        std::fs::remove_file(&session_index_path).expect("remove session index");
+        std::fs::create_dir(&session_index_path).expect("block session index writes");
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("Updated SQLite name".to_string())),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set paginated thread name with unavailable index")
+            .expect("local store returns updated thread");
+        assert_eq!(thread.name.as_deref(), Some("Updated SQLite name"));
+
+        let err = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None)
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("Unpersistable name".to_string())),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect_err("paginated name update without sqlite should fail");
+
+        assert!(matches!(err, ThreadStoreError::Internal { .. }));
+        assert_eq!(
+            std::fs::read_to_string(&path).expect("read rollout"),
+            original_rollout
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_sets_memory_mode_on_active_rollout() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(302);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path =
+            write_session_file(home.path(), "2025-01-03T14-30-00", uuid).expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(ThreadMemoryMode::Disabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set thread memory mode")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"]["id"], thread_id.to_string());
+        assert_eq!(appended["payload"]["memory_mode"], "disabled");
+        let memory_mode = runtime
+            .get_thread_memory_mode(thread_id)
+            .await
+            .expect("thread memory mode should be readable");
+        assert_eq!(memory_mode.as_deref(), Some("disabled"));
+    }
+
+    #[tokio::test]
+    async fn metadata_patch_completes_before_concurrent_shutdown()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let home = TempDir::new()?;
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::new_v4();
+        let thread_id = ThreadId::from_string(&uuid.to_string())?;
+        let path = write_session_file(home.path(), "2025-01-03T12-00-00", uuid)?;
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(path.clone()),
+                history: None,
+                include_archived: true,
+                metadata: test_thread_metadata(),
+            })
+            .await?;
+        let writer_lock = store.live_recorders.lock().await[&thread_id]
+            .writer_lock
+            .clone();
+        let (mut expected, _, _) = RolloutRecorder::load_rollout_items(&path).await?;
+        let mut metadata = read_session_meta_line(&path).await?;
+        metadata.meta.memory_mode = Some("disabled".into());
+        expected.push(RolloutItem::SessionMeta(metadata));
+
+        let mut shutdown = Box::pin(store.shutdown_thread(thread_id));
+        update_rollout_metadata(&store, thread_id, &path, &writer_lock, |meta| {
+            meta.meta.memory_mode = Some("disabled".into());
+            // Poll shutdown in the read/append gap; the writer mutex must keep it pending.
+            assert!(
+                tokio::task::unconstrained(shutdown.as_mut())
+                    .now_or_never()
+                    .is_none()
+            );
+        })
+        .await?;
+        shutdown.await?;
+
+        let (actual, _, _) = RolloutRecorder::load_rollout_items(&path).await?;
+        assert_eq!(json!(actual), json!(expected));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_updates_paginated_git_info_in_sqlite_only() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(303);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path = write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T14-35-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let original_rollout = std::fs::read_to_string(&path).expect("read rollout");
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        let mut stale_metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("read metadata")
+            .expect("thread metadata");
+        stale_metadata.history_mode = ThreadHistoryMode::Legacy;
+        runtime
+            .upsert_thread(&stale_metadata)
+            .await
+            .expect("seed stale history mode");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        sha: Some(None),
+                        branch: Some(Some("feature".to_string())),
+                        ..Default::default()
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("paginated metadata update")
+            .expect("local store returns updated thread");
+
+        let git_info = thread.git_info.expect("git info");
+        assert_eq!(git_info.commit_hash, None);
+        assert_eq!(git_info.branch.as_deref(), Some("feature"));
+        assert_eq!(
+            git_info.repository_url.as_deref(),
+            Some("https://example.com/repo.git")
+        );
+        assert_eq!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("read metadata")
+                .expect("thread metadata")
+                .history_mode,
+            ThreadHistoryMode::Paginated
+        );
+        assert_eq!(
+            std::fs::read_to_string(&path).expect("read rollout"),
+            original_rollout
+        );
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        let thread = store
+            .read_thread_by_rollout_path(
+                path, /*include_archived*/ false, /*include_history*/ false,
+            )
+            .await
+            .expect("read paginated thread by rollout path");
+        let git_info = thread.git_info.expect("git info");
+        assert_eq!(git_info.commit_hash, None);
+        assert_eq!(git_info.branch.as_deref(), Some("feature"));
+        assert_eq!(
+            git_info.repository_url.as_deref(),
+            Some("https://example.com/repo.git")
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_preserves_memory_mode_when_updating_git_info() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(312);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path =
+            write_session_file(home.path(), "2025-01-03T18-30-00", uuid).expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(ThreadMemoryMode::Disabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set memory mode");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        branch: Some(Some("feature".to_string())),
+                        ..Default::default()
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set git metadata")
+            .expect("local store returns updated thread");
+
+        assert_eq!(
+            thread.git_info.expect("git info").branch.as_deref(),
+            Some("feature")
+        );
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"]["memory_mode"], "disabled");
+        assert_eq!(appended["payload"]["git"]["branch"], "feature");
+
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        let memory_mode = runtime
+            .get_thread_memory_mode(thread_id)
+            .await
+            .expect("thread memory mode should be readable");
+        assert_eq!(memory_mode.as_deref(), Some("disabled"));
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_uses_live_rollout_path_for_external_resume() {
+        let home = TempDir::new().expect("temp dir");
+        let external_home = TempDir::new().expect("external temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let uuid = Uuid::from_u128(307);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path = write_session_file(external_home.path(), "2025-01-03T14-45-00", uuid)
+            .expect("external session file");
+
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(path.clone()),
+                history: None,
+                include_archived: true,
+                metadata: test_thread_metadata(),
+            })
+            .await
+            .expect("resume external live thread");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(ThreadMemoryMode::Disabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set memory mode on external live thread")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.thread_id, thread_id);
+        assert!(thread.rollout_path.is_some());
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"]["memory_mode"], "disabled");
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_sets_git_info() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime));
+        let uuid = Uuid::from_u128(309);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T17-00-00", uuid).expect("session file");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        sha: Some(Some("abc123".to_string())),
+                        branch: Some(Some("main".to_string())),
+                        origin_url: Some(Some(
+                            SanitizedGitUrl::try_from("https://github.com/openai/codex")
+                                .expect("valid git remote URL"),
+                        )),
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set git metadata")
+            .expect("local store returns updated thread");
+
+        let git_info = thread.git_info.expect("git info should be present");
+        assert_eq!(
+            git_info.commit_hash.as_ref().map(|sha| sha.0.as_str()),
+            Some("abc123")
+        );
+        assert_eq!(git_info.branch.as_deref(), Some("main"));
+        assert_eq!(
+            git_info.repository_url.as_deref(),
+            Some("https://github.com/openai/codex")
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_updates_permission_profile_and_reasoning_effort() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let uuid = Uuid::from_u128(317);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T20-30-00", uuid).expect("session file");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    permission_profile: Some(PermissionProfile::Disabled),
+                    reasoning_effort: Some(Some(ReasoningEffort::Ultra)),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set permission profile")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.permission_profile, PermissionProfile::Disabled);
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    reasoning_effort: Some(None),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("clear reasoning effort")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.reasoning_effort, None);
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        let permission_profile: PermissionProfile = PermissionProfile::Disabled;
+        assert_eq!(
+            metadata.sandbox_policy,
+            serde_json::to_string(&permission_profile).expect("serialize profile")
+        );
+        assert_eq!(metadata.reasoning_effort, None);
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_partially_updates_git_info() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime));
+        let uuid = Uuid::from_u128(310);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T17-30-00", uuid).expect("session file");
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        sha: Some(Some("abc123".to_string())),
+                        branch: Some(Some("main".to_string())),
+                        origin_url: Some(Some(
+                            SanitizedGitUrl::try_from("https://github.com/openai/codex")
+                                .expect("valid git remote URL"),
+                        )),
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("seed git metadata");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        branch: Some(Some("feature".to_string())),
+                        ..Default::default()
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("partially update git metadata")
+            .expect("local store returns updated thread");
+
+        let git_info = thread.git_info.expect("git info should be present");
+        assert_eq!(
+            git_info.commit_hash.as_ref().map(|sha| sha.0.as_str()),
+            Some("abc123")
+        );
+        assert_eq!(git_info.branch.as_deref(), Some("feature"));
+        assert_eq!(
+            git_info.repository_url.as_deref(),
+            Some("https://github.com/openai/codex")
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_clears_git_info_fields() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            config.sqlite.clone(),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        let uuid = Uuid::from_u128(311);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path =
+            write_session_file(home.path(), "2025-01-03T18-00-00", uuid).expect("session file");
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        sha: Some(Some("abc123".to_string())),
+                        branch: Some(Some("main".to_string())),
+                        origin_url: Some(Some(
+                            SanitizedGitUrl::try_from("https://github.com/openai/codex")
+                                .expect("valid git remote URL"),
+                        )),
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("seed git metadata");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        sha: Some(None),
+                        branch: Some(None),
+                        origin_url: Some(None),
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("clear git metadata")
+            .expect("local store returns updated thread");
+
+        assert!(thread.git_info.is_none());
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"]["git"], json!({}));
+
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread after reconcile");
+        assert!(thread.git_info.is_none());
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(ThreadMemoryMode::Disabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set memory mode after git clear");
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"].get("git"), None);
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread after memory mode update with no git");
+        assert!(thread.git_info.is_none());
+
+        assert_eq!(
+            runtime
+                .delete_thread(thread_id)
+                .await
+                .expect("delete sqlite thread row"),
+            1
+        );
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    git_info: Some(GitInfoPatch {
+                        branch: Some(Some("feature".to_string())),
+                        ..Default::default()
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("partially update after clear with missing sqlite row")
+            .expect("local store returns updated thread");
+        let git_info = thread.git_info.expect("branch should be present");
+        assert_eq!(git_info.commit_hash, None);
+        assert_eq!(git_info.branch.as_deref(), Some("feature"));
+        assert_eq!(git_info.repository_url, None);
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(ThreadMemoryMode::Disabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set memory mode after git clear and partial update");
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"].get("git"), None);
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ None,
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        let thread = store
+            .read_thread(ReadThreadParams {
+                thread_id,
+                include_archived: false,
+                include_history: false,
+            })
+            .await
+            .expect("read thread after memory mode update");
+        let git_info = thread.git_info.expect("branch should remain present");
+        assert_eq!(git_info.commit_hash, None);
+        assert_eq!(git_info.branch.as_deref(), Some("feature"));
+        assert_eq!(git_info.repository_url, None);
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_rejects_mismatched_session_meta_id() {
+        let home = TempDir::new().expect("temp dir");
+        let store = LocalThreadStore::new(test_config(home.path()), /*state_db*/ None);
+        let filename_uuid = Uuid::from_u128(303);
+        let metadata_uuid = Uuid::from_u128(304);
+        let thread_id = ThreadId::from_string(&filename_uuid.to_string()).expect("valid thread id");
+        let path = write_session_file(home.path(), "2025-01-03T15-00-00", filename_uuid)
+            .expect("session file");
+        let content = std::fs::read_to_string(&path).expect("read rollout");
+        std::fs::write(
+            &path,
+            content.replace(&filename_uuid.to_string(), &metadata_uuid.to_string()),
+        )
+        .expect("rewrite rollout");
+
+        let err = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    memory_mode: Some(ThreadMemoryMode::Enabled),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect_err("mismatch should fail");
+
+        assert!(matches!(err, ThreadStoreError::Internal { .. }));
+        assert!(err.to_string().contains("metadata id mismatch"));
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_applies_combined_explicit_patch() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let uuid = Uuid::from_u128(305);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let path =
+            write_session_file(home.path(), "2025-01-03T15-30-00", uuid).expect("session file");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("Combined metadata".to_string())),
+                    memory_mode: Some(ThreadMemoryMode::Disabled),
+                    git_info: Some(GitInfoPatch {
+                        branch: Some(Some("combined".to_string())),
+                        ..Default::default()
+                    }),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("combined patch should apply")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.name.as_deref(), Some("Combined metadata"));
+        assert_eq!(
+            thread.git_info.expect("git info").branch.as_deref(),
+            Some("combined")
+        );
+        let appended = last_rollout_item(path.as_path());
+        assert_eq!(appended["type"], "session_meta");
+        assert_eq!(appended["payload"]["memory_mode"], "disabled");
+        assert_eq!(appended["payload"]["git"]["branch"], "combined");
+        let latest_name = codex_rollout::find_thread_name_by_id(home.path(), &thread_id)
+            .await
+            .expect("find thread name");
+        assert_eq!(latest_name.as_deref(), Some("Combined metadata"));
+        let memory_mode = runtime
+            .get_thread_memory_mode(thread_id)
+            .await
+            .expect("thread memory mode should be readable");
+        assert_eq!(memory_mode.as_deref(), Some("disabled"));
+    }
+
+    #[test]
+    fn sqlite_failures_are_best_effort_for_legacy_rollout_compat_updates() {
+        assert!(!sqlite_write_failure_should_block(&ThreadMetadataPatch {
+            name: Some(Some("User chosen name".to_string())),
+            ..Default::default()
+        }));
+        assert!(!sqlite_write_failure_should_block(&ThreadMetadataPatch {
+            memory_mode: Some(ThreadMemoryMode::Disabled),
+            ..Default::default()
+        }));
+    }
+
+    #[test]
+    fn sqlite_failures_are_best_effort_for_observed_metadata_updates() {
+        assert!(!sqlite_write_failure_should_block(&ThreadMetadataPatch {
+            updated_at: Some(Utc::now()),
+            ..Default::default()
+        }));
+        assert!(!sqlite_write_failure_should_block(&ThreadMetadataPatch {
+            preview: Some("Observed preview".to_string()),
+            git_info: Some(GitInfoPatch {
+                branch: Some(Some("main".to_string())),
+                ..Default::default()
+            }),
+            memory_mode: Some(ThreadMemoryMode::Enabled),
+            ..Default::default()
+        }));
+    }
+
+    #[test]
+    fn sqlite_failures_still_block_for_explicit_git_only_updates() {
+        assert!(sqlite_write_failure_should_block(&ThreadMetadataPatch {
+            git_info: Some(GitInfoPatch {
+                branch: Some(Some("main".to_string())),
+                ..Default::default()
+            }),
+            ..Default::default()
+        }));
+    }
+
+    #[tokio::test]
+    async fn metadata_patch_applies_title_over_existing_name() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime));
+        let uuid = Uuid::from_u128(306);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T15-45-00", uuid).expect("session file");
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("User chosen name".to_string())),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set explicit name");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    title: Some("Derived first message".to_string()),
+                    preview: Some("Derived first message".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("apply observed metadata")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.name.as_deref(), Some("Derived first message"));
+    }
+
+    #[tokio::test]
+    async fn metadata_patch_applies_latest_preview_and_first_user_message() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let uuid = Uuid::from_u128(313);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T19-00-00", uuid).expect("session file");
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    preview: Some("Original preview".to_string()),
+                    first_user_message: Some("Original first message".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("set observed metadata");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    preview: Some("Later preview".to_string()),
+                    first_user_message: Some("Later first message".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("apply later observed metadata")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.preview, "Hello from user");
+        assert_eq!(
+            thread.first_user_message.as_deref(),
+            Some("Hello from user")
+        );
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read")
+            .expect("sqlite metadata");
+        assert_eq!(metadata.preview.as_deref(), Some("Later preview"));
+        assert_eq!(
+            metadata.first_user_message.as_deref(),
+            Some("Later first message")
+        );
+    }
+
+    #[tokio::test]
+    async fn observed_metadata_rejects_unknown_thread_without_rollout() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let uuid = Uuid::from_u128(314);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+
+        let err = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    preview: Some("phantom".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect_err("metadata-only update should not create a missing thread");
+
+        assert!(matches!(
+            err,
+            ThreadStoreError::InvalidRequest { message }
+                if message == format!("thread not found: {thread_id}")
+        ));
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("sqlite metadata read");
+        assert!(metadata.is_none());
+    }
+
+    #[tokio::test]
+    async fn observed_metadata_rebuilds_history_mode_from_canonical_session_meta() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(317);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file_with_history_mode(
+            home.path(),
+            "2025-01-03T19-15-00",
+            uuid,
+            ThreadHistoryMode::Paginated,
+        )
+        .expect("session file");
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    preview: Some("Paginated preview".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("update paginated thread without sqlite row")
+            .expect("local store returns updated thread");
+
+        assert_eq!(thread.history_mode, ThreadHistoryMode::Paginated);
+        assert_eq!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("sqlite metadata read")
+                .expect("sqlite metadata")
+                .history_mode,
+            ThreadHistoryMode::Paginated
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_recreates_missing_archived_sqlite_row_as_archived() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(315);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_archived_session_file(home.path(), "2025-01-03T19-30-00", uuid)
+            .expect("archived session file");
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    preview: Some("Archived missing sqlite row".to_string()),
+                    ..Default::default()
+                },
+                include_archived: true,
+            })
+            .await
+            .expect("update archived thread without sqlite row")
+            .expect("local store returns updated thread");
+
+        assert!(thread.archived_at.is_some());
+        assert!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("get metadata")
+                .expect("metadata")
+                .archived_at
+                .is_some()
+        );
+    }
+
+    #[tokio::test]
+    async fn observed_metadata_normalizes_cwd_for_list_filters() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config, Some(runtime.clone()));
+        let uuid = Uuid::from_u128(316);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        write_session_file(home.path(), "2025-01-03T20-00-00", uuid).expect("session file");
+        let workspace = home.path().join("workspace");
+        let child = workspace.join("child");
+        std::fs::create_dir_all(child.as_path()).expect("create workspace");
+        let unnormalized_cwd = child.join("..");
+        let normalized_cwd = codex_utils_path::normalize_for_path_comparison(workspace.as_path())
+            .expect("normalize cwd");
+
+        store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    cwd: Some(unnormalized_cwd),
+                    preview: Some("cwd preview".to_string()),
+                    ..Default::default()
+                },
+                include_archived: false,
+            })
+            .await
+            .expect("update observed cwd");
+
+        let metadata = runtime
+            .get_thread(thread_id)
+            .await
+            .expect("get metadata")
+            .expect("metadata");
+        assert_eq!(metadata.cwd, normalized_cwd);
+        let page = store
+            .list_threads(ListThreadsParams {
+                page_size: 10,
+                cursor: None,
+                sort_key: ThreadSortKey::UpdatedAt,
+                sort_direction: SortDirection::Desc,
+                allowed_sources: Vec::new(),
+                model_providers: Some(Vec::new()),
+                cwd_filters: Some(vec![workspace]),
+                section: None,
+                project_id: None,
+                archived: false,
+                search_term: None,
+                relation_filter: None,
+                use_state_db_only: true,
+            })
+            .await
+            .expect("list threads by cwd");
+        assert_eq!(
+            page.items
+                .iter()
+                .map(|thread| thread.thread_id)
+                .collect::<Vec<_>>(),
+            vec![thread_id]
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_keeps_archived_thread_archived_in_sqlite() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(307);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T16-00-00", uuid)
+            .expect("archived session file");
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        runtime
+            .mark_backfill_complete(/*last_watermark*/ None)
+            .await
+            .expect("backfill should be complete");
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            archived_path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ Some(true),
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        assert!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("get metadata")
+                .expect("metadata")
+                .archived_at
+                .is_some()
+        );
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("Archived title".to_string())),
+                    ..Default::default()
+                },
+                include_archived: true,
+            })
+            .await
+            .expect("set archived thread name")
+            .expect("local store returns updated thread");
+
+        assert!(thread.archived_at.is_some());
+        assert!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("get metadata")
+                .expect("metadata")
+                .archived_at
+                .is_some()
+        );
+    }
+
+    #[tokio::test]
+    async fn update_thread_metadata_keeps_live_archived_thread_archived_in_sqlite() {
+        let home = TempDir::new().expect("temp dir");
+        let config = test_config(home.path());
+        let uuid = Uuid::from_u128(308);
+        let thread_id = ThreadId::from_string(&uuid.to_string()).expect("valid thread id");
+        let archived_path = write_archived_session_file(home.path(), "2025-01-03T16-30-00", uuid)
+            .expect("archived session file");
+        let runtime = codex_state::StateRuntime::init(
+            codex_state::SqliteConfig::new_for_testing(home.path().abs()),
+            config.default_model_provider_id.clone(),
+        )
+        .await
+        .expect("state db should initialize");
+        let store = LocalThreadStore::new(config.clone(), Some(runtime.clone()));
+        runtime
+            .mark_backfill_complete(/*last_watermark*/ None)
+            .await
+            .expect("backfill should be complete");
+        codex_rollout::state_db::reconcile_rollout(
+            Some(runtime.as_ref()),
+            archived_path.as_path(),
+            config.default_model_provider_id.as_str(),
+            /*builder*/ None,
+            &[],
+            /*archived_only*/ Some(true),
+            /*new_thread_memory_mode*/ None,
+        )
+        .await;
+        store
+            .resume_thread(ResumeThreadParams {
+                thread_id,
+                rollout_path: Some(archived_path.clone()),
+                history: None,
+                include_archived: true,
+                metadata: test_thread_metadata(),
+            })
+            .await
+            .expect("resume archived live thread");
+
+        let thread = store
+            .update_thread_metadata(UpdateThreadMetadataParams {
+                thread_id,
+                patch: ThreadMetadataPatch {
+                    name: Some(Some("Live archived title".to_string())),
+                    ..Default::default()
+                },
+                include_archived: true,
+            })
+            .await
+            .expect("set archived thread name")
+            .expect("local store returns updated thread");
+
+        assert!(thread.archived_at.is_some());
+        assert!(
+            runtime
+                .get_thread(thread_id)
+                .await
+                .expect("get metadata")
+                .expect("metadata")
+                .archived_at
+                .is_some()
+        );
+    }
+
+    fn test_thread_metadata() -> ThreadPersistenceMetadata {
+        ThreadPersistenceMetadata {
+            cwd: Some(std::env::current_dir().expect("cwd")),
+            model_provider: "test-provider".to_string(),
+            memory_mode: ThreadMemoryMode::Enabled,
+        }
+    }
+
+    fn last_rollout_item(path: &std::path::Path) -> Value {
+        let last_line = std::fs::read_to_string(path)
+            .expect("read rollout")
+            .lines()
+            .last()
+            .expect("last line")
+            .to_string();
+        serde_json::from_str(&last_line).expect("json line")
+    }
+}
diff --git a/codex-rs/thread-store/src/projects.rs b/codex-rs/thread-store/src/projects.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fd918b90f14ec975d3ffec17c97bb34e28221040
--- /dev/null
+++ b/codex-rs/thread-store/src/projects.rs
@@ -0,0 +1,81 @@
+use std::collections::BTreeMap;
+
+use crate::SortDirection;
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct StoredProjectRoot {
+    pub path: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct StoredProject {
+    pub id: String,
+    pub name: String,
+    pub roots: Vec<StoredProjectRoot>,
+    pub metadata: BTreeMap<String, String>,
+    pub position: i64,
+    pub created_at_ms: i64,
+    pub updated_at_ms: i64,
+    pub recency_at_ms: Option<i64>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct StoredProjectsPage {
+    pub projects: Vec<StoredProject>,
+    pub next_cursor: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ListProjectsParams {
+    pub cursor: Option<String>,
+    pub limit: usize,
+    pub sort_key: codex_state::ProjectSortKey,
+    pub sort_direction: SortDirection,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CreateProjectParams {
+    pub name: String,
+    pub roots: Vec<StoredProjectRoot>,
+    pub metadata: BTreeMap<String, String>,
+    pub thread_ids: Vec<String>,
+    pub idempotency_key: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CreatedProject {
+    pub project: StoredProject,
+    pub created: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct UpdateProjectParams {
+    pub project_id: String,
+    pub name: Option<String>,
+    pub roots: Option<Vec<StoredProjectRoot>>,
+    pub metadata: Option<BTreeMap<String, String>>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MoveProjectParams {
+    pub project_id: String,
+    pub before_project_id: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ProjectMoveOutcome {
+    Unchanged,
+    Moved,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct UpdatedProject {
+    pub project: StoredProject,
+    pub changed: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct DeletedProject {
+    pub affected_active_thread_ids: Vec<String>,
+    pub affected_archived_thread_ids: Vec<String>,
+}
diff --git a/codex-rs/thread-store/src/queue_store.rs b/codex-rs/thread-store/src/queue_store.rs
new file mode 100644
index 0000000000000000000000000000000000000000..74fc2fc9705017ac7cc6a41741e52738b87f27bc
--- /dev/null
+++ b/codex-rs/thread-store/src/queue_store.rs
@@ -0,0 +1,158 @@
+use std::fmt::Display;
+use std::future::Future;
+
+use codex_protocol::ThreadId;
+use codex_rollout::StateDbHandle;
+use codex_state::QueuedUserSubmissionRecord;
+use codex_state::SqliteQueueStore;
+
+use crate::MAX_QUEUE_ITEMS;
+use crate::ThreadStoreError;
+use crate::ThreadStoreFuture;
+
+/// Storage-neutral persistence for ordered, thread-scoped user messages.
+pub trait QueueStore: Send + Sync {
+    /// Return a stable revision that changes when another connection updates the queue.
+    fn change_version(&self) -> ThreadStoreFuture<'_, i64>;
+
+    /// Return changed, loaded thread IDs and their durable revisions after `revision`.
+    fn changes_since<'a>(
+        &'a self,
+        revision: i64,
+        thread_ids: &'a [ThreadId],
+    ) -> ThreadStoreFuture<'a, Vec<(ThreadId, i64)>>;
+
+    fn enqueue(
+        &self,
+        thread_id: ThreadId,
+        payload: String,
+    ) -> ThreadStoreFuture<'_, QueuedUserSubmissionRecord>;
+
+    fn list_page(
+        &self,
+        thread_id: ThreadId,
+        offset: usize,
+        limit: usize,
+    ) -> ThreadStoreFuture<'_, Vec<QueuedUserSubmissionRecord>>;
+
+    fn update(
+        &self,
+        thread_id: ThreadId,
+        item_id: String,
+        payload: String,
+    ) -> ThreadStoreFuture<'_, Option<QueuedUserSubmissionRecord>>;
+
+    fn delete(&self, thread_id: ThreadId, item_id: String) -> ThreadStoreFuture<'_, bool>;
+
+    /// Atomically replace queue order with every current item ID exactly once.
+    ///
+    /// Returns [`ThreadStoreError::InvalidRequest`] when `item_ids` is not a
+    /// permutation of the complete queue.
+    fn reorder(&self, thread_id: ThreadId, item_ids: Vec<String>) -> ThreadStoreFuture<'_, ()>;
+}
+
+/// Adapts the local state runtime to the shared queue-storage interface.
+#[derive(Clone)]
+pub struct LocalQueueStore {
+    state_db: StateDbHandle,
+}
+
+impl LocalQueueStore {
+    pub fn new(state_db: StateDbHandle) -> Self {
+        Self { state_db }
+    }
+
+    fn queue(&self) -> &SqliteQueueStore {
+        self.state_db.thread_queue()
+    }
+}
+
+fn queue_future<'a, T, E>(
+    future: impl Future<Output = Result<T, E>> + Send + 'a,
+) -> ThreadStoreFuture<'a, T>
+where
+    T: Send + 'a,
+    E: Display + Send + 'a,
+{
+    Box::pin(async move {
+        future.await.map_err(|error| ThreadStoreError::Internal {
+            message: format!("queue storage failed: {error}"),
+        })
+    })
+}
+
+impl QueueStore for LocalQueueStore {
+    fn change_version(&self) -> ThreadStoreFuture<'_, i64> {
+        queue_future(self.queue().change_version())
+    }
+
+    fn changes_since<'a>(
+        &'a self,
+        revision: i64,
+        thread_ids: &'a [ThreadId],
+    ) -> ThreadStoreFuture<'a, Vec<(ThreadId, i64)>> {
+        queue_future(self.queue().changes_since(revision, thread_ids))
+    }
+
+    fn enqueue(
+        &self,
+        thread_id: ThreadId,
+        payload: String,
+    ) -> ThreadStoreFuture<'_, QueuedUserSubmissionRecord> {
+        Box::pin(async move {
+            self.queue()
+                .enqueue(thread_id, &payload)
+                .await
+                .map_err(|error| match error.downcast_ref::<sqlx::Error>() {
+                    Some(sqlx::Error::RowNotFound) => ThreadStoreError::InvalidRequest {
+                        message: format!(
+                            "queue cannot contain more than {MAX_QUEUE_ITEMS} submissions"
+                        ),
+                    },
+                    _ => ThreadStoreError::Internal {
+                        message: format!("queue storage failed: {error}"),
+                    },
+                })
+        })
+    }
+
+    fn list_page(
+        &self,
+        thread_id: ThreadId,
+        offset: usize,
+        limit: usize,
+    ) -> ThreadStoreFuture<'_, Vec<QueuedUserSubmissionRecord>> {
+        queue_future(self.queue().list_page(thread_id, offset, limit))
+    }
+
+    fn update(
+        &self,
+        thread_id: ThreadId,
+        item_id: String,
+        payload: String,
+    ) -> ThreadStoreFuture<'_, Option<QueuedUserSubmissionRecord>> {
+        queue_future(async move { self.queue().update(thread_id, &item_id, &payload).await })
+    }
+
+    fn delete(&self, thread_id: ThreadId, item_id: String) -> ThreadStoreFuture<'_, bool> {
+        queue_future(async move { self.queue().delete(thread_id, &item_id).await })
+    }
+
+    fn reorder(&self, thread_id: ThreadId, item_ids: Vec<String>) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            self.queue()
+                .reorder(thread_id, &item_ids)
+                .await
+                .map_err(|error| match error.downcast_ref::<std::io::Error>() {
+                    Some(error) if error.kind() == std::io::ErrorKind::InvalidInput => {
+                        ThreadStoreError::InvalidRequest {
+                            message: error.to_string(),
+                        }
+                    }
+                    _ => ThreadStoreError::Internal {
+                        message: format!("queue storage failed: {error}"),
+                    },
+                })
+        })
+    }
+}
diff --git a/codex-rs/thread-store/src/store.rs b/codex-rs/thread-store/src/store.rs
new file mode 100644
index 0000000000000000000000000000000000000000..58c54db1561f9a7381ce7068a3a8076a9818dfc0
--- /dev/null
+++ b/codex-rs/thread-store/src/store.rs
@@ -0,0 +1,535 @@
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::ThreadHistoryMode;
+use std::any::Any;
+use std::future::Future;
+use std::pin::Pin;
+
+use crate::AddThreadAttachmentOutcome;
+use crate::AddThreadAttachmentParams;
+use crate::AppendThreadItemsParams;
+use crate::ArchiveThreadParams;
+use crate::ArchiveThreadsParams;
+use crate::CreateProjectParams;
+use crate::CreateThreadParams;
+use crate::CreateThreadSectionParams;
+use crate::CreatedProject;
+use crate::DeleteThreadParams;
+use crate::DeleteThreadSectionParams;
+use crate::DeleteThreadsParams;
+use crate::DeletedProject;
+use crate::ItemPage;
+use crate::ListItemsParams;
+use crate::ListProjectsParams;
+use crate::ListThreadAttachmentsParams;
+use crate::ListThreadSectionsParams;
+use crate::ListThreadsParams;
+use crate::ListTurnsParams;
+use crate::LoadThreadHistoryParams;
+use crate::MoveProjectParams;
+use crate::MoveThreadToSectionParams;
+use crate::PrepareForkParams;
+use crate::PreparedFork;
+use crate::ProjectMoveOutcome;
+use crate::ReadThreadByRolloutPathParams;
+use crate::ReadThreadParams;
+use crate::RemoveThreadAttachmentOutcome;
+use crate::RemoveThreadAttachmentParams;
+use crate::RenameThreadSectionParams;
+use crate::ResumeThreadParams;
+use crate::RevertThreadParams;
+use crate::SearchThreadOccurrencesParams;
+use crate::SearchThreadsParams;
+use crate::StoredModelContext;
+use crate::StoredProject;
+use crate::StoredProjectsPage;
+use crate::StoredThread;
+use crate::StoredThreadHistory;
+use crate::StoredThreadSection;
+use crate::StoredThreadSectionsPage;
+use crate::ThreadAttachmentPage;
+use crate::ThreadMetadataPatch;
+use crate::ThreadOccurrenceSearchPage;
+use crate::ThreadPage;
+use crate::ThreadSearchPage;
+use crate::ThreadStoreError;
+use crate::ThreadStoreResult;
+use crate::TurnPage;
+use crate::UpdateProjectParams;
+use crate::UpdateThreadMetadataParams;
+use crate::UpdatedProject;
+
+/// Future returned by [`ThreadStore`] operations.
+pub type ThreadStoreFuture<'a, T> = Pin<Box<dyn Future<Output = ThreadStoreResult<T>> + Send + 'a>>;
+
+/// Why thread persistence is being requested.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PersistContext {
+    /// Standard persistence makes the thread and all queued items durable and readable.
+    Standard,
+    /// A turn is about to begin sampling after its input has been recorded.
+    TurnStart,
+    /// Accepted user input is being recorded before an active turn's next sampling request.
+    /// This does not apply to tool outputs, cancellation, or task cleanup.
+    SteeredUserInput,
+}
+
+impl PersistContext {
+    /// Whether a store may enqueue this checkpoint before returning and fence it at a later
+    /// durability barrier. Stores may still choose to persist synchronously.
+    pub fn allows_background_persistence(self) -> bool {
+        match self {
+            Self::Standard => false,
+            Self::TurnStart | Self::SteeredUserInput => true,
+        }
+    }
+}
+
+/// Storage-neutral thread persistence boundary.
+pub trait ThreadStore: Any + Send + Sync {
+    /// Return this store as [`Any`] for implementation-owned escape hatches.
+    fn as_any(&self) -> &dyn Any;
+
+    /// Returns the history mode to use when history does not carry a persisted mode.
+    ///
+    /// The default is legacy so existing stores stay compatible. Stores whose durable contract is
+    /// already paginated should override this instead of relying on core to infer storage behavior.
+    fn default_history_mode(&self) -> ThreadHistoryMode {
+        ThreadHistoryMode::Legacy
+    }
+
+    /// Creates a new live thread.
+    fn create_thread(&self, params: CreateThreadParams) -> ThreadStoreFuture<'_, ()>;
+
+    /// Stages host-owned metadata for a thread ID reserved before Core starts the thread.
+    ///
+    /// The entry remains in memory until the first successful metadata update for that thread.
+    /// Callers must remove it if startup fails before the store opens a live thread.
+    fn stage_pending_thread_metadata(
+        &self,
+        _thread_id: ThreadId,
+        _patch: ThreadMetadataPatch,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "stage_pending_thread_metadata",
+            })
+        })
+    }
+
+    /// Reads metadata staged for a reserved thread without persisting it.
+    fn read_pending_thread_metadata(
+        &self,
+        _thread_id: ThreadId,
+    ) -> ThreadStoreFuture<'_, Option<ThreadMetadataPatch>> {
+        Box::pin(async { Ok(None) })
+    }
+
+    /// Removes host-owned metadata staged for a reserved thread ID.
+    fn remove_pending_thread_metadata(&self, _thread_id: ThreadId) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "remove_pending_thread_metadata",
+            })
+        })
+    }
+
+    /// Reopens an existing thread for live appends.
+    fn resume_thread(&self, params: ResumeThreadParams) -> ThreadStoreFuture<'_, ()>;
+
+    /// Appends raw rollout items to a live thread.
+    ///
+    /// Implementations should apply the shared rollout persistence policy before writing durable
+    /// replay history and before updating any implementation-owned projections.
+    fn append_items(&self, params: AppendThreadItemsParams) -> ThreadStoreFuture<'_, ()>;
+
+    /// Materializes the thread if persistence is lazy, then persists all queued items.
+    ///
+    /// Standard persistence must complete before returning. Contexts that allow background
+    /// persistence may complete asynchronously when the implementation enqueues the checkpoint
+    /// before returning, fences it with subsequent flush or shutdown operations, and surfaces
+    /// failures through those operations.
+    fn persist_thread(
+        &self,
+        thread_id: ThreadId,
+        context: PersistContext,
+    ) -> ThreadStoreFuture<'_, ()>;
+
+    /// Flushes all queued items and returns once they are durable/readable.
+    fn flush_thread(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()>;
+
+    /// Flushes pending items and closes the live thread writer.
+    fn shutdown_thread(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()>;
+
+    /// Discards the live thread writer without forcing pending in-memory items to become durable.
+    ///
+    /// Core calls this when session initialization fails after a live writer has been created.
+    /// Implementations should release any live writer resources for the thread while preserving
+    /// already-durable thread data.
+    fn discard_thread(&self, thread_id: ThreadId) -> ThreadStoreFuture<'_, ()>;
+
+    /// Loads persisted history for resume, fork, and memory jobs.
+    fn load_history(
+        &self,
+        params: LoadThreadHistoryParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadHistory>;
+
+    /// Loads the persisted rollout items needed to reconstruct the latest model-visible context.
+    ///
+    /// Implementations that cannot perform a targeted read may return the full persisted history.
+    fn load_latest_model_context(
+        &self,
+        _params: LoadThreadHistoryParams,
+    ) -> ThreadStoreFuture<'_, StoredModelContext> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "load_latest_model_context",
+            })
+        })
+    }
+
+    /// Freezes source history and model context used to initialize a referenced fork.
+    ///
+    /// Stores without reference-backed fork support can retain this default implementation.
+    fn prepare_fork(&self, _params: PrepareForkParams) -> ThreadStoreFuture<'_, PreparedFork> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "prepare_fork",
+            })
+        })
+    }
+
+    /// Reverts a paginated thread's durable history so it ends immediately before
+    /// `before_turn_id`.
+    ///
+    /// Callers must close the thread's live writer first. The logical thread id and semantic
+    /// metadata stay unchanged.
+    ///
+    /// Stores without paginated revert support can retain this default implementation.
+    fn revert_thread(&self, _params: RevertThreadParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "revert_thread",
+            })
+        })
+    }
+
+    /// Reads a thread summary and optionally its persisted history.
+    fn read_thread(&self, params: ReadThreadParams) -> ThreadStoreFuture<'_, StoredThread>;
+
+    /// Reads a rollout-backed thread by path when the store supports path-addressed lookups.
+    ///
+    /// Deprecated: new callers should use [`ThreadStore::read_thread`] instead.
+    fn read_thread_by_rollout_path(
+        &self,
+        params: ReadThreadByRolloutPathParams,
+    ) -> ThreadStoreFuture<'_, StoredThread>;
+
+    /// Lists stored threads matching the supplied filters.
+    fn list_threads(&self, params: ListThreadsParams) -> ThreadStoreFuture<'_, ThreadPage>;
+
+    /// Whether this store can discover and manage independently persisted thread sections.
+    fn supports_thread_sections(&self) -> bool {
+        false
+    }
+
+    /// Lists independently persisted thread sections.
+    fn list_thread_sections(
+        &self,
+        _params: ListThreadSectionsParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadSectionsPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "threadSection/list",
+            })
+        })
+    }
+
+    /// Creates a custom thread section with a stable, server-assigned identity.
+    fn create_thread_section(
+        &self,
+        _params: CreateThreadSectionParams,
+    ) -> ThreadStoreFuture<'_, StoredThreadSection> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "threadSection/create",
+            })
+        })
+    }
+
+    /// Renames a custom thread section, returning `None` when it does not exist.
+    fn rename_thread_section(
+        &self,
+        _params: RenameThreadSectionParams,
+    ) -> ThreadStoreFuture<'_, Option<StoredThreadSection>> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "threadSection/update",
+            })
+        })
+    }
+
+    /// Deletes a custom thread section and reports whether it existed.
+    fn delete_thread_section(
+        &self,
+        _params: DeleteThreadSectionParams,
+    ) -> ThreadStoreFuture<'_, bool> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "threadSection/delete",
+            })
+        })
+    }
+
+    /// Whether this store can persist and discover thread-owned attachments.
+    fn supports_thread_attachments(&self) -> bool {
+        false
+    }
+
+    /// Copies current attachment membership into a newly persisted fork.
+    ///
+    /// Copies must be atomic and use new attachment IDs. The destination must be empty;
+    /// subsequent membership changes on either thread must remain independent.
+    fn copy_thread_attachments(
+        &self,
+        _source_thread_id: ThreadId,
+        _destination_thread_id: ThreadId,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "copy_thread_attachments",
+            })
+        })
+    }
+
+    /// Attaches an attachment, returning an existing attachment for repeated requests.
+    fn add_thread_attachment(
+        &self,
+        _params: AddThreadAttachmentParams,
+    ) -> ThreadStoreFuture<'_, AddThreadAttachmentOutcome> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/attachment/add",
+            })
+        })
+    }
+
+    /// Lists attachments belonging to one persisted thread.
+    fn list_thread_attachments(
+        &self,
+        _params: ListThreadAttachmentsParams,
+    ) -> ThreadStoreFuture<'_, ThreadAttachmentPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/attachment/list",
+            })
+        })
+    }
+
+    /// Removes an attachment and reports whether it existed.
+    fn remove_thread_attachment(
+        &self,
+        _params: RemoveThreadAttachmentParams,
+    ) -> ThreadStoreFuture<'_, RemoveThreadAttachmentOutcome> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/attachment/remove",
+            })
+        })
+    }
+
+    /// Whether this store supports durable host-owned projects.
+    fn supports_projects(&self) -> bool {
+        false
+    }
+
+    fn list_projects(
+        &self,
+        _params: ListProjectsParams,
+    ) -> ThreadStoreFuture<'_, StoredProjectsPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "project/list",
+            })
+        })
+    }
+
+    fn read_project(&self, _project_id: String) -> ThreadStoreFuture<'_, Option<StoredProject>> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "project/read",
+            })
+        })
+    }
+
+    fn create_project(
+        &self,
+        _params: CreateProjectParams,
+    ) -> ThreadStoreFuture<'_, CreatedProject> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "project/create",
+            })
+        })
+    }
+
+    fn update_project(
+        &self,
+        _params: UpdateProjectParams,
+    ) -> ThreadStoreFuture<'_, Option<UpdatedProject>> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "project/update",
+            })
+        })
+    }
+
+    fn move_project(
+        &self,
+        _params: MoveProjectParams,
+    ) -> ThreadStoreFuture<'_, Option<ProjectMoveOutcome>> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "project/move",
+            })
+        })
+    }
+
+    fn delete_project(&self, _project_id: String) -> ThreadStoreFuture<'_, Option<DeletedProject>> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "project/delete",
+            })
+        })
+    }
+
+    /// Whether paginated threads can hydrate durable history through turn and item lists.
+    fn supports_paginated_history_lists(&self) -> bool {
+        false
+    }
+
+    /// Searches stored threads and returns search-only preview metadata.
+    fn search_threads(
+        &self,
+        _params: SearchThreadsParams,
+    ) -> ThreadStoreFuture<'_, ThreadSearchPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/search",
+            })
+        })
+    }
+
+    /// Searches visible message occurrences within one paginated thread.
+    fn search_thread_occurrences(
+        &self,
+        _params: SearchThreadOccurrencesParams,
+    ) -> ThreadStoreFuture<'_, ThreadOccurrenceSearchPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/searchOccurrences",
+            })
+        })
+    }
+
+    /// Lists turns within a stored thread.
+    fn list_turns(&self, _params: ListTurnsParams) -> ThreadStoreFuture<'_, TurnPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "list_turns",
+            })
+        })
+    }
+
+    /// Lists persisted items within a stored thread, optionally filtered to a turn.
+    fn list_items(&self, _params: ListItemsParams) -> ThreadStoreFuture<'_, ItemPage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "list_items",
+            })
+        })
+    }
+
+    /// Lists bounded ordinary and realtime thread history in rollout order.
+    fn list_timeline(
+        &self,
+        _params: crate::ListTimelineParams,
+    ) -> ThreadStoreFuture<'_, crate::TimelinePage> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/timeline/list",
+            })
+        })
+    }
+
+    /// Applies a literal metadata patch and returns the updated thread when one was materialized.
+    ///
+    /// `None` means the update succeeded without materializing a thread, for example because the
+    /// implementation filtered the patch to a no-op. Callers that require a `StoredThread` must
+    /// perform a fallback read.
+    ///
+    /// Implementations should apply the supplied fields directly. Policy such as deciding whether
+    /// an append-derived preview should be emitted belongs above the store.
+    fn update_thread_metadata(
+        &self,
+        params: UpdateThreadMetadataParams,
+    ) -> ThreadStoreFuture<'_, Option<StoredThread>>;
+
+    /// Moves a thread to, within, or out of a server-ordered section.
+    fn move_thread_to_section(
+        &self,
+        _params: MoveThreadToSectionParams,
+    ) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async {
+            Err(ThreadStoreError::Unsupported {
+                operation: "thread/section/move",
+            })
+        })
+    }
+
+    /// Archives a thread.
+    fn archive_thread(&self, params: ArchiveThreadParams) -> ThreadStoreFuture<'_, ()>;
+
+    /// Archives threads in order, returning the successfully archived thread ids.
+    ///
+    /// The first thread must archive successfully; later failures are best effort.
+    fn archive_threads(
+        &self,
+        params: ArchiveThreadsParams,
+    ) -> ThreadStoreFuture<'_, Vec<ThreadId>> {
+        Box::pin(async move {
+            let mut archived_thread_ids = Vec::new();
+            for thread_id in params.thread_ids {
+                match self.archive_thread(ArchiveThreadParams { thread_id }).await {
+                    Ok(()) => archived_thread_ids.push(thread_id),
+                    Err(err) if archived_thread_ids.is_empty() => return Err(err),
+                    Err(err) => tracing::warn!("failed to archive thread {thread_id}: {err}"),
+                }
+            }
+            Ok(archived_thread_ids)
+        })
+    }
+
+    /// Unarchives a thread and returns its updated metadata.
+    fn unarchive_thread(&self, params: ArchiveThreadParams) -> ThreadStoreFuture<'_, StoredThread>;
+
+    /// Deletes a thread's persisted rollout data and associated metadata.
+    /// Success includes cleanup of associated persisted state; callers must not repeat it.
+    fn delete_thread(&self, params: DeleteThreadParams) -> ThreadStoreFuture<'_, ()>;
+
+    /// Deletes threads and their associated persisted state in order, treating already-missing
+    /// members as deleted.
+    ///
+    /// Stores with request-scoped delete preflight should override this instead of repeating
+    /// that work through [`ThreadStore::delete_thread`].
+    fn delete_threads(&self, params: DeleteThreadsParams) -> ThreadStoreFuture<'_, ()> {
+        Box::pin(async move {
+            for thread_id in params.thread_ids {
+                match self.delete_thread(DeleteThreadParams { thread_id }).await {
+                    Ok(()) | Err(ThreadStoreError::ThreadNotFound { .. }) => {}
+                    Err(err) => return Err(err),
+                }
+            }
+            Ok(())
+        })
+    }
+}
diff --git a/codex-rs/thread-store/src/thread_attachments.rs b/codex-rs/thread-store/src/thread_attachments.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4abe2d17c200967d40d9bdbb9eb129f320ca4625
--- /dev/null
+++ b/codex-rs/thread-store/src/thread_attachments.rs
@@ -0,0 +1,39 @@
+//! Typed parameters for attachment operations on stored threads.
+
+use codex_protocol::ThreadId;
+use serde_json::Value;
+
+/// Parameters for attaching a thread-owned attachment.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct AddThreadAttachmentParams {
+    /// Thread that owns the attachment.
+    pub thread_id: ThreadId,
+    /// Client-defined attachment type.
+    pub attachment_type: String,
+    /// Stable attachment identity within its thread and type.
+    pub identity_key: String,
+    /// Bounded, client-defined attachment metadata.
+    pub payload: Value,
+}
+
+/// Parameters for listing attachments owned by one thread.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ListThreadAttachmentsParams {
+    /// Thread whose attachments should be returned.
+    pub thread_id: ThreadId,
+    /// Opaque cursor returned by a previous attachment listing.
+    pub cursor: Option<String>,
+    /// Maximum number of attachments to return.
+    pub limit: usize,
+}
+
+/// Parameters for removing a thread-owned attachment.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RemoveThreadAttachmentParams {
+    /// Thread that owns the attachment.
+    pub thread_id: ThreadId,
+    /// Client-defined attachment type.
+    pub attachment_type: String,
+    /// Stable attachment identity within its thread and type.
+    pub identity_key: String,
+}
diff --git a/codex-rs/thread-store/src/thread_metadata_sync.rs b/codex-rs/thread-store/src/thread_metadata_sync.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fb7d4d8c78c822ac4691b33bcf9b8889b56b5729
--- /dev/null
+++ b/codex-rs/thread-store/src/thread_metadata_sync.rs
@@ -0,0 +1,856 @@
+use std::time::Duration;
+use std::time::Instant;
+
+use chrono::DateTime;
+use chrono::NaiveDateTime;
+use chrono::Utc;
+use codex_git_utils::collect_git_info;
+use codex_git_utils::get_git_repo_root;
+use codex_protocol::ThreadId;
+use codex_protocol::items::TurnItem;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::GitInfo;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode;
+use codex_protocol::protocol::UserMessageEvent;
+use codex_protocol::protocol::strip_user_message_prefix;
+use codex_protocol::protocol::user_message_preview;
+use codex_rollout::RolloutItem;
+use codex_state::ThreadMetadata;
+
+use crate::CreateThreadParams;
+use crate::GitInfoPatch;
+use crate::ResumeThreadParams;
+use crate::ThreadMetadataPatch;
+use crate::types::canonical_history_mode_from_rollout_items;
+
+const THREAD_UPDATED_AT_TOUCH_INTERVAL: Duration = Duration::from_secs(5);
+
+/// Live-thread helper that derives metadata updates from appended rollout items.
+///
+/// Stores receive raw rollout items plus explicit metadata patches. This helper
+/// keeps append-derived metadata observation in the live layer without owning persistence-policy
+/// filtering or making `append_items` infer metadata inside a `ThreadStore` implementation.
+pub(crate) struct ThreadMetadataSync {
+    thread_id: ThreadId,
+    cwd_seen: bool,
+    preview_seen: bool,
+    first_user_message_seen: bool,
+    title_seen: bool,
+    pending_update: Option<ThreadMetadataPatch>,
+    pending_update_generation: u64,
+    last_touch_persisted_at: Option<Instant>,
+    defer_create_update_until_history_exists: bool,
+    defer_resume_update_until_append: bool,
+}
+
+pub(crate) struct PendingThreadMetadataPatch {
+    pub(crate) patch: ThreadMetadataPatch,
+    generation: u64,
+}
+
+impl ThreadMetadataSync {
+    pub(crate) async fn for_create(params: &CreateThreadParams) -> Self {
+        let created_at = Utc::now();
+        let cwd = params.metadata.cwd.clone().unwrap_or_default();
+        let git_info = if get_git_repo_root(cwd.as_path()).is_some() {
+            collect_git_info(cwd.as_path()).await.map(|info| GitInfo {
+                commit_hash: info.commit_hash,
+                branch: info.branch,
+                repository_url: info.repository_url,
+            })
+        } else {
+            None
+        };
+        let update = ThreadMetadataPatch {
+            model_provider: Some(params.metadata.model_provider.clone()),
+            created_at: Some(created_at),
+            updated_at: Some(created_at),
+            source: Some(params.source.clone()),
+            originator: (!params.originator.is_empty()).then(|| params.originator.clone()),
+            thread_source: Some(params.thread_source.clone()),
+            agent_nickname: Some(params.source.get_nickname()),
+            agent_role: Some(params.source.get_agent_role()),
+            agent_path: Some(params.source.get_agent_path().map(Into::into)),
+            cwd: Some(cwd.clone()),
+            cli_version: Some(env!("CARGO_PKG_VERSION").to_string()),
+            git_info: git_info.map(git_info_patch_from_observation),
+            memory_mode: Some(params.metadata.memory_mode),
+            ..Default::default()
+        };
+        Self {
+            thread_id: params.thread_id,
+            cwd_seen: !cwd.as_os_str().is_empty(),
+            preview_seen: false,
+            first_user_message_seen: false,
+            title_seen: false,
+            pending_update: Some(update),
+            pending_update_generation: 1,
+            last_touch_persisted_at: None,
+            defer_create_update_until_history_exists: true,
+            defer_resume_update_until_append: false,
+        }
+    }
+
+    pub(crate) fn for_resume(
+        params: &ResumeThreadParams,
+        metadata: Option<&ThreadMetadata>,
+    ) -> Self {
+        let mut sync = Self {
+            thread_id: params.thread_id,
+            cwd_seen: params
+                .metadata
+                .cwd
+                .as_ref()
+                .is_some_and(|cwd| !cwd.as_os_str().is_empty()),
+            preview_seen: metadata
+                .and_then(|metadata| metadata.preview.as_deref())
+                .is_some_and(|preview| !preview.is_empty()),
+            first_user_message_seen: metadata
+                .is_some_and(|metadata| metadata.first_user_message.is_some()),
+            title_seen: metadata.is_some_and(|metadata| !metadata.title.is_empty()),
+            pending_update: None,
+            pending_update_generation: 0,
+            last_touch_persisted_at: None,
+            defer_create_update_until_history_exists: false,
+            defer_resume_update_until_append: false,
+        };
+        if let Some(history) = params.history.as_deref() {
+            sync.record_resume_history(history);
+        }
+        sync
+    }
+
+    pub(crate) fn record_resume_history(&mut self, history: &[RolloutItem]) {
+        let update = self.observe_resume_history(history);
+        self.merge_pending_update(update);
+        self.defer_resume_update_until_append = self.pending_update.is_some();
+    }
+
+    pub(crate) fn take_pending_update(&self) -> Option<PendingThreadMetadataPatch> {
+        self.pending_update
+            .clone()
+            .map(|patch| PendingThreadMetadataPatch {
+                patch,
+                generation: self.pending_update_generation,
+            })
+    }
+
+    pub(crate) fn take_pending_update_for_existing_history(
+        &self,
+    ) -> Option<PendingThreadMetadataPatch> {
+        if self.defer_create_update_until_history_exists {
+            return None;
+        }
+        if self.defer_resume_update_until_append {
+            return None;
+        }
+        self.take_pending_update()
+    }
+
+    pub(crate) fn mark_pending_update_applied(&mut self, update: &PendingThreadMetadataPatch) {
+        if self.pending_update_generation == update.generation {
+            self.pending_update = None;
+        }
+        if update.patch.updated_at.is_some() {
+            self.last_touch_persisted_at = Some(Instant::now());
+        }
+    }
+
+    pub(crate) fn observe_appended_items(
+        &mut self,
+        items: &[RolloutItem],
+    ) -> Option<PendingThreadMetadataPatch> {
+        self.defer_create_update_until_history_exists = false;
+        self.defer_resume_update_until_append = false;
+        let affects_metadata = items
+            .iter()
+            .any(codex_state::rollout_item_affects_thread_metadata);
+        let advances_recency = items
+            .iter()
+            .any(|item| matches!(item, RolloutItem::EventMsg(EventMsg::TurnStarted(_))));
+        let mut update = if affects_metadata {
+            self.observe_items(items)?
+        } else {
+            thread_updated_at_touch()
+        };
+        if advances_recency {
+            update.advance_recency_at = Some(Utc::now());
+        }
+        self.merge_pending_update(Some(update));
+        if !affects_metadata
+            && !self
+                .pending_update
+                .as_ref()
+                .is_some_and(update_has_metadata_facts)
+            && self.last_touch_persisted_at.is_some_and(|last_touch| {
+                Instant::now().duration_since(last_touch) < THREAD_UPDATED_AT_TOUCH_INTERVAL
+            })
+        {
+            return None;
+        }
+        self.take_pending_update()
+    }
+
+    fn observe_items(&mut self, items: &[RolloutItem]) -> Option<ThreadMetadataPatch> {
+        self.observe_items_with_update(
+            items,
+            ThreadMetadataPatch {
+                updated_at: Some(Utc::now()),
+                ..Default::default()
+            },
+        )
+    }
+
+    fn observe_resume_history(&mut self, items: &[RolloutItem]) -> Option<ThreadMetadataPatch> {
+        let mut update = self.observe_items_with_update(items, ThreadMetadataPatch::default())?;
+        if matches!(
+            canonical_history_mode_from_rollout_items(items),
+            ThreadHistoryMode::Paginated
+        ) {
+            // Paginated rollouts never append metadata-only SessionMeta updates. Do not reapply
+            // initial metadata when resume history is flushed after the first append.
+            update.git_info = None;
+            update.memory_mode = None;
+        }
+        Some(update)
+    }
+
+    fn observe_items_with_update(
+        &mut self,
+        items: &[RolloutItem],
+        mut update: ThreadMetadataPatch,
+    ) -> Option<ThreadMetadataPatch> {
+        if items.is_empty() {
+            return None;
+        }
+        for item in items {
+            match item {
+                RolloutItem::SessionMeta(meta_line) if meta_line.meta.id == self.thread_id => {
+                    update.created_at = parse_session_timestamp(meta_line.meta.timestamp.as_str());
+                    update.source = Some(meta_line.meta.source.clone());
+                    if !meta_line.meta.originator.is_empty() {
+                        update.originator = Some(meta_line.meta.originator.clone());
+                    }
+                    update.thread_source = Some(meta_line.meta.thread_source.clone());
+                    update.agent_nickname = Some(meta_line.meta.agent_nickname.clone());
+                    update.agent_role = Some(meta_line.meta.agent_role.clone());
+                    update.agent_path = Some(meta_line.meta.agent_path.clone());
+                    if let Some(model_provider) = meta_line.meta.model_provider.clone()
+                        && !model_provider.is_empty()
+                    {
+                        update.model_provider = Some(model_provider);
+                    }
+                    if !meta_line.meta.cli_version.is_empty() {
+                        update.cli_version = Some(meta_line.meta.cli_version.clone());
+                    }
+                    if !meta_line.meta.cwd.as_os_str().is_empty() {
+                        self.cwd_seen = true;
+                        update.cwd = Some(meta_line.meta.cwd.clone());
+                    }
+                    if let Some(git_info) = meta_line.git.clone() {
+                        update.git_info = Some(git_info_patch_from_observation(git_info));
+                    }
+                    if let Some(memory_mode) = meta_line.meta.memory_mode.as_deref()
+                        && let Some(memory_mode) = parse_memory_mode(memory_mode)
+                    {
+                        update.memory_mode = Some(memory_mode);
+                    }
+                }
+                RolloutItem::TurnContext(turn_ctx) => {
+                    if !self.cwd_seen {
+                        self.cwd_seen = true;
+                        update.cwd = Some(turn_ctx.cwd.clone().into_path_buf());
+                    }
+                    update.model = Some(turn_ctx.model.clone());
+                    update.reasoning_effort = Some(turn_ctx.effort.clone());
+                    update.approval_mode = Some(turn_ctx.approval_policy);
+                    update.permission_profile = Some(turn_ctx.permission_profile());
+                }
+                RolloutItem::EventMsg(EventMsg::UserMessage(user)) => {
+                    self.observe_user_message(user, &mut update);
+                }
+                RolloutItem::EventMsg(EventMsg::ItemCompleted(event)) => {
+                    if let TurnItem::UserMessage(user) = &event.item {
+                        self.observe_user_message(
+                            &user.as_legacy_user_message_event(),
+                            &mut update,
+                        );
+                    }
+                }
+                RolloutItem::EventMsg(EventMsg::TokenCount(token_count)) => {
+                    if let Some(info) = token_count.info.as_ref() {
+                        update.token_usage = Some(info.total_token_usage.clone());
+                    }
+                }
+                RolloutItem::EventMsg(EventMsg::ThreadGoalUpdated(event)) => {
+                    if !self.preview_seen {
+                        let objective = event.goal.objective.trim();
+                        if !objective.is_empty() {
+                            self.preview_seen = true;
+                            update.preview = Some(objective.to_string());
+                        }
+                    }
+                }
+                RolloutItem::EventMsg(EventMsg::ThreadSettingsApplied(event)) => {
+                    let settings = &event.thread_settings;
+                    self.cwd_seen = true;
+                    update.model = Some(settings.model.clone());
+                    update.model_provider = Some(settings.model_provider_id.clone());
+                    update.reasoning_effort = Some(settings.reasoning_effort.clone());
+                    update.cwd = Some(settings.cwd.clone().into_path_buf());
+                    update.approval_mode = Some(settings.approval_policy);
+                    update.permission_profile = Some(settings.permission_profile.clone());
+                }
+                RolloutItem::SessionMeta(_)
+                | RolloutItem::EventMsg(_)
+                | RolloutItem::ResponseItem(_)
+                | RolloutItem::InterAgentCommunication(_)
+                | RolloutItem::InterAgentCommunicationMetadata { .. }
+                | RolloutItem::Compacted(_)
+                | RolloutItem::RealtimeItem(_)
+                | RolloutItem::TokenUsageRecord(_)
+                | RolloutItem::RetainedContext(_)
+                | RolloutItem::SecurityRiskScore(_)
+                | RolloutItem::WorldState(_) => {}
+            }
+        }
+        Some(update)
+    }
+
+    fn observe_user_message(&mut self, user: &UserMessageEvent, update: &mut ThreadMetadataPatch) {
+        if let Some(preview) = user_message_preview(user) {
+            if !self.first_user_message_seen {
+                self.first_user_message_seen = true;
+                update.first_user_message = Some(preview.clone());
+            }
+            if !self.preview_seen {
+                self.preview_seen = true;
+                update.preview = Some(preview);
+            }
+        }
+        if !self.title_seen {
+            let title = strip_user_message_prefix(user.message.as_str());
+            if !title.is_empty() {
+                self.title_seen = true;
+                update.title = Some(title.to_string());
+            }
+        }
+    }
+
+    fn merge_pending_update(&mut self, update: Option<ThreadMetadataPatch>) {
+        let Some(update) = update else {
+            return;
+        };
+        match self.pending_update.as_mut() {
+            Some(pending_update) => pending_update.merge(update),
+            None => self.pending_update = Some(update),
+        }
+        self.pending_update_generation = self.pending_update_generation.wrapping_add(1);
+    }
+}
+
+fn parse_memory_mode(value: &str) -> Option<ThreadMemoryMode> {
+    match value {
+        "enabled" => Some(ThreadMemoryMode::Enabled),
+        "disabled" => Some(ThreadMemoryMode::Disabled),
+        _ => None,
+    }
+}
+
+fn parse_session_timestamp(value: &str) -> Option<DateTime<Utc>> {
+    DateTime::parse_from_rfc3339(value)
+        .map(|timestamp| timestamp.with_timezone(&Utc))
+        .or_else(|_| {
+            NaiveDateTime::parse_from_str(value, "%Y-%m-%dT%H-%M-%S")
+                .map(|timestamp| DateTime::from_naive_utc_and_offset(timestamp, Utc))
+        })
+        .ok()
+}
+
+fn thread_updated_at_touch() -> ThreadMetadataPatch {
+    ThreadMetadataPatch {
+        updated_at: Some(Utc::now()),
+        ..Default::default()
+    }
+}
+
+fn update_has_metadata_facts(update: &ThreadMetadataPatch) -> bool {
+    update.rollout_path.is_some()
+        || update.preview.is_some()
+        || update.title.is_some()
+        || update.model_provider.is_some()
+        || update.model.is_some()
+        || update.reasoning_effort.is_some()
+        || update.created_at.is_some()
+        || update.advance_recency_at.is_some()
+        || update.source.is_some()
+        || update.originator.is_some()
+        || update.thread_source.is_some()
+        || update.agent_nickname.is_some()
+        || update.agent_role.is_some()
+        || update.agent_path.is_some()
+        || update.cwd.is_some()
+        || update.cli_version.is_some()
+        || update.approval_mode.is_some()
+        || update.permission_profile.is_some()
+        || update.token_usage.is_some()
+        || update.first_user_message.is_some()
+        || update.git_info.is_some()
+        || update.memory_mode.is_some()
+}
+
+fn git_info_patch_from_observation(git_info: GitInfo) -> GitInfoPatch {
+    GitInfoPatch {
+        sha: git_info.commit_hash.map(|sha| Some(sha.0)),
+        branch: git_info.branch.map(Some),
+        origin_url: git_info.repository_url.map(Some),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use codex_protocol::config_types::ApprovalsReviewer;
+    use codex_protocol::config_types::CollaborationMode;
+    use codex_protocol::config_types::ModeKind;
+    use codex_protocol::config_types::ReasoningSummary;
+    use codex_protocol::config_types::Settings;
+    use codex_protocol::items::UserMessageItem;
+    use codex_protocol::models::PermissionProfile;
+    use codex_protocol::openai_models::ReasoningEffort;
+    use codex_protocol::protocol::AskForApproval;
+    use codex_protocol::protocol::ItemCompletedEvent;
+    use codex_protocol::protocol::SessionMeta;
+    use codex_protocol::protocol::SessionMetaLine;
+    use codex_protocol::protocol::SessionSource;
+    use codex_protocol::protocol::ThreadGoal;
+    use codex_protocol::protocol::ThreadGoalStatus;
+    use codex_protocol::protocol::ThreadGoalUpdatedEvent;
+    use codex_protocol::protocol::ThreadSettingsAppliedEvent;
+    use codex_protocol::protocol::ThreadSettingsSnapshot;
+    use codex_protocol::protocol::TurnStartedEvent;
+    use codex_protocol::protocol::UserMessageEvent;
+    use codex_protocol::user_input::UserInput;
+    use codex_rollout::CompactedItem;
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+    use crate::CreateThreadParams;
+    use crate::ThreadPersistenceMetadata;
+
+    #[tokio::test]
+    async fn create_metadata_records_originator_without_project() {
+        let thread_id = ThreadId::new();
+        let sync = ThreadMetadataSync::for_create(&CreateThreadParams {
+            session_id: thread_id.into(),
+            thread_id,
+            extra_config: None,
+            forked_from_id: None,
+            parent_thread_id: None,
+            source: SessionSource::Exec,
+            thread_source: None,
+            originator: "test_originator".to_string(),
+            base_instructions: codex_protocol::models::BaseInstructions::default(),
+            dynamic_tools: Vec::new(),
+            selected_capability_roots: Vec::new(),
+            multi_agent_version: None,
+            history_mode: ThreadHistoryMode::Legacy,
+            history_base: None,
+            subagent_history_start_ordinal: None,
+            initial_window_id: uuid::Uuid::now_v7().to_string(),
+            runtime_workspace_roots: None,
+            metadata: ThreadPersistenceMetadata {
+                cwd: None,
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        })
+        .await;
+
+        let update = sync.take_pending_update().expect("pending metadata update");
+        assert_eq!(
+            (update.patch.project_id, update.patch.originator.as_deref()),
+            (None, Some("test_originator")),
+        );
+    }
+
+    #[test]
+    fn resume_history_keeps_derived_metadata_pending_until_applied() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(
+            thread_id,
+            vec![
+                RolloutItem::SessionMeta(session_meta(thread_id)),
+                RolloutItem::EventMsg(EventMsg::UserMessage(user_message("hello metadata"))),
+            ],
+        );
+
+        let update = sync.take_pending_update().expect("pending metadata update");
+        assert_eq!(
+            update
+                .patch
+                .created_at
+                .expect("created_at should come from session metadata")
+                .to_rfc3339(),
+            "2025-01-03T12:00:00+00:00"
+        );
+        assert_eq!(update.patch.preview.as_deref(), Some("hello metadata"));
+        assert_eq!(update.patch.originator.as_deref(), Some("test_originator"));
+        assert_eq!(update.patch.title.as_deref(), Some("hello metadata"));
+        assert_eq!(
+            update.patch.first_user_message.as_deref(),
+            Some("hello metadata")
+        );
+        assert_eq!(update.patch.updated_at, None);
+        assert!(
+            sync.take_pending_update().is_some(),
+            "taking the pending update should not drop retry state"
+        );
+
+        sync.mark_pending_update_applied(&update);
+        assert!(sync.take_pending_update().is_none());
+    }
+
+    #[test]
+    fn goal_update_sets_preview_without_overriding_existing_preview() {
+        let thread_id = ThreadId::new();
+        let sync = resume_sync(
+            thread_id,
+            vec![
+                RolloutItem::EventMsg(EventMsg::ThreadGoalUpdated(goal_update(
+                    thread_id,
+                    "ship the refactor",
+                ))),
+                RolloutItem::EventMsg(EventMsg::UserMessage(user_message("first user text"))),
+            ],
+        );
+
+        let update = sync.take_pending_update().expect("pending metadata update");
+        assert_eq!(update.patch.preview.as_deref(), Some("ship the refactor"));
+        assert_eq!(update.patch.title.as_deref(), Some("first user text"));
+        assert_eq!(
+            update.patch.first_user_message.as_deref(),
+            Some("first user text")
+        );
+    }
+
+    #[test]
+    fn later_user_messages_do_not_emit_existing_preview_fields() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(
+            thread_id,
+            vec![RolloutItem::EventMsg(EventMsg::UserMessage(user_message(
+                "first user text",
+            )))],
+        );
+        let pending = sync.take_pending_update().expect("pending resume metadata");
+        sync.mark_pending_update_applied(&pending);
+
+        let update = sync
+            .observe_appended_items(&[RolloutItem::EventMsg(EventMsg::UserMessage(user_message(
+                "later user text",
+            )))])
+            .expect("updated_at touch");
+
+        assert_eq!(update.patch.preview, None);
+        assert_eq!(update.patch.title, None);
+        assert_eq!(update.patch.first_user_message, None);
+        assert!(update.patch.updated_at.is_some());
+    }
+
+    #[test]
+    fn completed_user_message_items_emit_metadata_fields() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(thread_id, Vec::new());
+        let update = sync
+            .observe_appended_items(&[RolloutItem::EventMsg(EventMsg::ItemCompleted(
+                ItemCompletedEvent {
+                    thread_id,
+                    turn_id: "turn-1".to_string(),
+                    item: TurnItem::UserMessage(UserMessageItem::new(&[UserInput::Text {
+                        text: "first user text".to_string(),
+                        text_elements: Vec::new(),
+                    }])),
+                    started_at_ms: Some(0),
+                    completed_at_ms: 0,
+                },
+            ))])
+            .expect("completed user message metadata update");
+
+        assert_eq!(update.patch.preview.as_deref(), Some("first user text"));
+        assert_eq!(update.patch.title.as_deref(), Some("first user text"));
+        assert_eq!(
+            update.patch.first_user_message.as_deref(),
+            Some("first user text")
+        );
+    }
+
+    #[test]
+    fn metadata_irrelevant_items_coalesce_updated_at_touches() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(thread_id, Vec::new());
+        let item = RolloutItem::Compacted(CompactedItem {
+            message: "compacted".to_string(),
+            replacement_history: None,
+            retained_context: None,
+            guardian_history: None,
+            mcp_resource_origins: None,
+            window_number: None,
+            first_window_id: None,
+            previous_window_id: None,
+            window_id: None,
+            compaction_response_id: None,
+            latest_token_usage_record: None,
+        });
+
+        let first = sync
+            .observe_appended_items(std::slice::from_ref(&item))
+            .expect("first touch should apply immediately");
+        assert!(first.patch.updated_at.is_some());
+        sync.mark_pending_update_applied(&first);
+
+        assert!(
+            sync.observe_appended_items(std::slice::from_ref(&item))
+                .is_none(),
+            "second touch inside the coalescing window should wait for a barrier"
+        );
+        assert!(
+            sync.take_pending_update().is_some(),
+            "coalesced touches still flush at the next barrier"
+        );
+    }
+
+    #[test]
+    fn turn_start_advances_recency_at_without_changing_updated_at_behavior() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(thread_id, Vec::new());
+
+        let update = sync
+            .observe_appended_items(&[RolloutItem::EventMsg(EventMsg::TurnStarted(
+                TurnStartedEvent {
+                    turn_id: "turn-1".to_string(),
+                    root_turn_id: None,
+                    trace_id: None,
+                    started_at: None,
+                    model_context_window: None,
+                    collaboration_mode_kind: Default::default(),
+                },
+            ))])
+            .expect("turn start metadata update");
+
+        assert!(update.patch.updated_at.is_some());
+        assert!(update.patch.advance_recency_at.is_some());
+    }
+
+    #[test]
+    fn thread_settings_applied_updates_live_metadata() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(thread_id, Vec::new());
+        let permission_profile = PermissionProfile::workspace_write();
+        let cwd = std::env::current_dir()
+            .expect("current directory")
+            .join("updated/workspace");
+
+        let mut item = RolloutItem::EventMsg(EventMsg::ThreadSettingsApplied(
+            ThreadSettingsAppliedEvent {
+                thread_id: None,
+                thread_settings: ThreadSettingsSnapshot {
+                    disabled_plugin_ids: Vec::new(),
+                    model: "gpt-5.2-codex".to_string(),
+                    model_provider_id: "updated-provider".to_string(),
+                    service_tier: None,
+                    approval_policy: AskForApproval::Never,
+                    approvals_reviewer: ApprovalsReviewer::User,
+                    permission_profile: permission_profile.clone(),
+                    active_permission_profile: None,
+                    cwd: cwd.clone().try_into().expect("absolute settings cwd"),
+                    runtime_workspace_roots: None,
+                    reasoning_effort: Some(ReasoningEffort::Ultra),
+                    reasoning_summary: Some(ReasoningSummary::Auto),
+                    personality: None,
+                    collaboration_mode: CollaborationMode {
+                        mode: ModeKind::Default,
+                        settings: Settings {
+                            model: "gpt-5.2-codex".to_string(),
+                            reasoning_effort: Some(ReasoningEffort::Ultra),
+                            developer_instructions: None,
+                        },
+                    },
+                },
+            },
+        ));
+
+        let update = sync
+            .observe_appended_items(&[item.clone()])
+            .expect("thread settings metadata update");
+
+        assert_eq!(update.patch.model.as_deref(), Some("gpt-5.2-codex"));
+        assert_eq!(
+            update.patch.model_provider.as_deref(),
+            Some("updated-provider")
+        );
+        assert_eq!(
+            update.patch.reasoning_effort,
+            Some(Some(ReasoningEffort::Ultra))
+        );
+        assert_eq!(update.patch.cwd, Some(cwd));
+        assert_eq!(update.patch.approval_mode, Some(AskForApproval::Never));
+        assert_eq!(update.patch.permission_profile, Some(permission_profile));
+
+        let RolloutItem::EventMsg(EventMsg::ThreadSettingsApplied(event)) = &mut item else {
+            panic!("thread settings applied item");
+        };
+        event.thread_settings.reasoning_effort = None;
+        event
+            .thread_settings
+            .collaboration_mode
+            .settings
+            .reasoning_effort = None;
+
+        let update = sync
+            .observe_appended_items(&[item])
+            .expect("thread settings clear metadata update");
+        assert_eq!(update.patch.reasoning_effort, Some(None));
+    }
+
+    #[test]
+    fn resume_history_waits_for_append_before_flushing_metadata() {
+        let thread_id = ThreadId::new();
+        let mut sync = resume_sync(
+            thread_id,
+            vec![
+                RolloutItem::SessionMeta(session_meta(thread_id)),
+                RolloutItem::EventMsg(EventMsg::UserMessage(user_message("hello metadata"))),
+            ],
+        );
+
+        assert!(
+            sync.take_pending_update_for_existing_history().is_none(),
+            "resume-only metadata should not flush without a new append"
+        );
+        assert!(
+            sync.observe_appended_items(&[RolloutItem::EventMsg(EventMsg::UserMessage(
+                user_message("new append"),
+            ))])
+            .is_some(),
+            "the first append should flush resume metadata together with append metadata"
+        );
+    }
+
+    #[test]
+    fn paginated_resume_history_does_not_reapply_initial_metadata() {
+        let thread_id = ThreadId::new();
+        let mut meta = session_meta(thread_id);
+        meta.meta.history_mode = ThreadHistoryMode::Paginated;
+        meta.meta.memory_mode = Some("disabled".to_string());
+        meta.git = Some(GitInfo {
+            commit_hash: None,
+            branch: Some("stale-branch".to_string()),
+            repository_url: None,
+        });
+        let sync = resume_sync(
+            thread_id,
+            vec![
+                RolloutItem::SessionMeta(meta),
+                RolloutItem::EventMsg(EventMsg::UserMessage(user_message("hello metadata"))),
+            ],
+        );
+
+        let update = sync.take_pending_update().expect("pending metadata update");
+        assert_eq!(update.patch.git_info, None);
+        assert_eq!(update.patch.memory_mode, None);
+        assert_eq!(update.patch.preview.as_deref(), Some("hello metadata"));
+    }
+
+    #[test]
+    fn resume_preserves_existing_display_metadata_and_initializes_missing_title() {
+        let thread_id = ThreadId::new();
+        let mut metadata = codex_state::ThreadMetadataBuilder::new(
+            thread_id,
+            Default::default(),
+            Utc::now(),
+            SessionSource::Exec,
+        )
+        .build("test-provider");
+        metadata.preview = Some("goal-first preview".to_string());
+        metadata.first_user_message = Some("[Image]".to_string());
+        let params = resume_params(
+            thread_id,
+            vec![RolloutItem::EventMsg(EventMsg::UserMessage(user_message(
+                "first textual user message",
+            )))],
+        );
+
+        let sync = ThreadMetadataSync::for_resume(&params, Some(&metadata));
+        let update = sync.take_pending_update().expect("pending metadata update");
+
+        assert_eq!(update.patch.preview, None);
+        assert_eq!(update.patch.first_user_message, None);
+        assert_eq!(
+            update.patch.title.as_deref(),
+            Some("first textual user message")
+        );
+    }
+
+    fn resume_sync(thread_id: ThreadId, history: Vec<RolloutItem>) -> ThreadMetadataSync {
+        ThreadMetadataSync::for_resume(&resume_params(thread_id, history), /*metadata*/ None)
+    }
+
+    fn resume_params(thread_id: ThreadId, history: Vec<RolloutItem>) -> ResumeThreadParams {
+        ResumeThreadParams {
+            thread_id,
+            rollout_path: None,
+            history: Some(Arc::new(history)),
+            include_archived: false,
+            metadata: ThreadPersistenceMetadata {
+                cwd: None,
+                model_provider: "test-provider".to_string(),
+                memory_mode: ThreadMemoryMode::Enabled,
+            },
+        }
+    }
+
+    fn user_message(message: &str) -> UserMessageEvent {
+        UserMessageEvent {
+            client_id: None,
+            message: message.to_string(),
+            images: None,
+            local_images: Vec::new(),
+            text_elements: Vec::new(),
+            ..Default::default()
+        }
+    }
+
+    fn session_meta(thread_id: ThreadId) -> SessionMetaLine {
+        SessionMetaLine {
+            meta: SessionMeta {
+                session_id: thread_id.into(),
+                id: thread_id,
+                timestamp: "2025-01-03T12:00:00Z".to_string(),
+                source: SessionSource::Exec,
+                originator: "test_originator".to_string(),
+                ..Default::default()
+            },
+            git: None,
+        }
+    }
+
+    fn goal_update(thread_id: ThreadId, objective: &str) -> ThreadGoalUpdatedEvent {
+        ThreadGoalUpdatedEvent {
+            thread_id,
+            turn_id: None,
+            goal: ThreadGoal {
+                thread_id,
+                objective: objective.to_string(),
+                status: ThreadGoalStatus::Active,
+                token_budget: None,
+                tokens_used: 0,
+                time_used_seconds: 0,
+                created_at: 0,
+                updated_at: 0,
+            },
+        }
+    }
+}
diff --git a/codex-rs/thread-store/src/thread_sections.rs b/codex-rs/thread-store/src/thread_sections.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0fda4a655ee747fc8f50c27ebe067c44cdd0d533
--- /dev/null
+++ b/codex-rs/thread-store/src/thread_sections.rs
@@ -0,0 +1,52 @@
+/// Parameters for listing independently persisted thread sections.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ListThreadSectionsParams {
+    /// Opaque cursor returned by a previous section listing.
+    pub cursor: Option<String>,
+    /// Maximum number of sections to return.
+    pub limit: usize,
+}
+
+/// Parameters for creating a thread section.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CreateThreadSectionParams {
+    /// User-facing section name.
+    pub name: String,
+    pub appearance: Option<codex_state::ThreadSectionAppearance>,
+}
+
+/// Parameters for renaming a thread section.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RenameThreadSectionParams {
+    /// Stable identifier of the section to rename.
+    pub section_id: String,
+    /// Replacement user-facing section name.
+    pub name: String,
+    pub appearance: Option<Option<codex_state::ThreadSectionAppearance>>,
+}
+
+/// Parameters for deleting a thread section.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct DeleteThreadSectionParams {
+    /// Stable identifier of the section to delete.
+    pub section_id: String,
+}
+
+/// An independently persisted thread section and its user-facing name.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct StoredThreadSection {
+    /// Stable, server-owned section identifier.
+    pub id: String,
+    /// User-facing section name.
+    pub name: String,
+    pub appearance: Option<codex_state::ThreadSectionAppearance>,
+}
+
+/// A cursor-paginated page of independently persisted thread sections.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct StoredThreadSectionsPage {
+    /// Sections returned for this page.
+    pub sections: Vec<StoredThreadSection>,
+    /// Opaque cursor to continue listing sections.
+    pub next_cursor: Option<String>,
+}
diff --git a/codex-rs/thread-store/src/types.rs b/codex-rs/thread-store/src/types.rs
new file mode 100644
index 0000000000000000000000000000000000000000..28568b3e2b834e064fb320e57e5608e827720bd6
--- /dev/null
+++ b/codex-rs/thread-store/src/types.rs
@@ -0,0 +1,1105 @@
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use chrono::DateTime;
+use chrono::Utc;
+use codex_app_server_protocol::CodexErrorInfo;
+use codex_app_server_protocol::ThreadTimelineEntry;
+use codex_protocol::SanitizedGitUrl;
+use codex_protocol::SessionId;
+use codex_protocol::ThreadId;
+use codex_protocol::capabilities::SelectedCapabilityRoot;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
+use codex_protocol::models::BaseInstructions;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::openai_models::ReasoningEffort;
+use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::GitInfo;
+use codex_protocol::protocol::HistoryPosition;
+use codex_protocol::protocol::MultiAgentVersion;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::ThreadHistoryMode;
+use codex_protocol::protocol::ThreadMemoryMode as MemoryMode;
+use codex_protocol::protocol::ThreadSource;
+use codex_protocol::protocol::TokenUsage;
+use codex_rollout::RolloutItem;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
+use serde::Deserializer;
+use serde::Serialize;
+use serde::Serializer;
+
+mod optional_option {
+    use super::*;
+
+    pub fn serialize<T, S>(value: &Option<Option<T>>, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        T: Serialize,
+        S: Serializer,
+    {
+        match value {
+            Some(value) => value.serialize(serializer),
+            None => serializer.serialize_none(),
+        }
+    }
+
+    pub fn deserialize<'de, T, D>(deserializer: D) -> Result<Option<Option<T>>, D::Error>
+    where
+        T: Deserialize<'de>,
+        D: Deserializer<'de>,
+    {
+        Option::<T>::deserialize(deserializer).map(Some)
+    }
+}
+
+/// Thread-scoped metadata used when opening live persistence.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ThreadPersistenceMetadata {
+    /// Effective working directory for environment-backed threads.
+    ///
+    /// `None` means the thread has no filesystem/environment context.
+    pub cwd: Option<PathBuf>,
+    /// Model provider associated with the thread.
+    pub model_provider: String,
+    /// Memory mode associated with the live thread.
+    pub memory_mode: MemoryMode,
+}
+
+/// Extra configuration fields for a thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ExtraConfig {}
+
+/// Parameters required to create a persisted thread.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CreateThreadParams {
+    /// Session id shared by the root thread and all of its subagents.
+    pub session_id: SessionId,
+    /// Thread id generated by Codex before opening persistence.
+    pub thread_id: ThreadId,
+    /// Optional extra configuration fields for the thread.
+    pub extra_config: Option<ExtraConfig>,
+    /// Source thread id when this thread is created as a fork.
+    pub forked_from_id: Option<ThreadId>,
+    /// The ID of the parent thread. This will only be set if this thread is a subagent.
+    pub parent_thread_id: Option<ThreadId>,
+    /// Runtime source for the thread.
+    pub source: SessionSource,
+    /// Optional analytics source classification for this thread.
+    pub thread_source: Option<ThreadSource>,
+    /// Effective originator used for this thread's Responses requests and analytics events.
+    pub originator: String,
+    /// Base instructions persisted in session metadata.
+    pub base_instructions: BaseInstructions,
+    /// Dynamic tools available to the thread at startup.
+    pub dynamic_tools: Vec<DynamicToolSpec>,
+    /// Environment-qualified capability roots selected for this thread.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub selected_capability_roots: Vec<SelectedCapabilityRoot>,
+    /// Multi-agent runtime selected when the thread was created.
+    pub multi_agent_version: Option<MultiAgentVersion>,
+    /// Persisted thread history contract selected when the thread was created.
+    pub history_mode: ThreadHistoryMode,
+    /// Exclusive prefix of another paginated rollout inherited by this thread.
+    pub history_base: Option<HistoryPosition>,
+    /// First rollout ordinal that belongs to this subagent's projected history.
+    pub subagent_history_start_ordinal: Option<u64>,
+    /// Initial context-window identity captured when the thread was created.
+    pub initial_window_id: String,
+    /// Runtime workspace roots at creation, excluding permission-profile roots.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub runtime_workspace_roots: Option<Vec<AbsolutePathBuf>>,
+    /// Metadata captured for the newly created thread.
+    pub metadata: ThreadPersistenceMetadata,
+}
+
+/// Parameters required to reopen persistence for an existing thread.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ResumeThreadParams {
+    /// Existing thread id whose future items should be appended.
+    pub thread_id: ThreadId,
+    /// Known local rollout path when the caller resumed from a specific file.
+    pub rollout_path: Option<PathBuf>,
+    /// Known replay history for the resumed thread, if already loaded by the caller.
+    pub history: Option<Arc<Vec<RolloutItem>>>,
+    /// Whether archived threads may be reopened.
+    pub include_archived: bool,
+    /// Metadata for future writes appended to the resumed live thread.
+    pub metadata: ThreadPersistenceMetadata,
+}
+
+pub(crate) fn canonical_history_mode_from_rollout_items(
+    items: &[RolloutItem],
+) -> ThreadHistoryMode {
+    // Forked rollouts keep copied source SessionMeta items after the new thread's
+    // canonical SessionMeta, so the thread contract comes from the first one.
+    items
+        .iter()
+        .find_map(|item| match item {
+            RolloutItem::SessionMeta(meta_line) => Some(meta_line.meta.history_mode),
+            _ => None,
+        })
+        .unwrap_or_default()
+}
+
+/// Parameters for appending rollout items to a live thread.
+#[derive(Clone, Debug)]
+pub struct AppendThreadItemsParams {
+    /// Thread id to append to.
+    pub thread_id: ThreadId,
+    /// Raw rollout items to append in order.
+    ///
+    /// Store implementations are responsible for applying the shared rollout persistence policy
+    /// before writing durable replay history or any implementation-owned projections.
+    pub items: Vec<RolloutItem>,
+}
+
+/// Parameters for loading persisted history for resume, fork, and memory jobs.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LoadThreadHistoryParams {
+    /// Thread id to load.
+    pub thread_id: ThreadId,
+    /// Whether archived threads are eligible.
+    pub include_archived: bool,
+}
+
+/// Persisted rollout history for a thread, without any filesystem path requirement.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct StoredThreadHistory {
+    /// Thread id represented by the history.
+    pub thread_id: ThreadId,
+    /// Persisted rollout items in replay order.
+    pub items: Vec<RolloutItem>,
+}
+
+/// Persisted rollout items needed to reconstruct the latest model-visible context.
+///
+/// Local stores may return only a resumable suffix while stores without targeted reads may return
+/// the full persisted history. In either case, `items` remain in replay order and are suitable for
+/// the existing rollout reconstruction path.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct StoredModelContext {
+    /// Thread id represented by the model context.
+    pub thread_id: ThreadId,
+    /// Persisted rollout items in replay order.
+    pub items: Vec<RolloutItem>,
+}
+
+/// Requested boundary for inheriting a paginated thread's history.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ForkBoundary {
+    /// Inherit the source thread's latest durable state.
+    Latest,
+    /// Inherit history through the newest visible occurrence of this turn.
+    ThroughTurn(String),
+    /// Inherit history preceding the original visible occurrence of this turn.
+    BeforeTurn(String),
+}
+
+/// Parameters for freezing the source history used to initialize a fork.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PrepareForkParams {
+    /// Immediate source thread whose metadata and approval settings are inherited.
+    pub thread_id: ThreadId,
+    /// Requested inclusive or exclusive fork boundary.
+    pub boundary: ForkBoundary,
+}
+
+/// Parameters for reverting a paginated thread's durable history.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct RevertThreadParams {
+    /// Stable logical thread to revert.
+    pub thread_id: ThreadId,
+    /// First turn excluded from the retained history.
+    pub before_turn_id: String,
+    /// Resolved runtime version to preserve when its turn context is removed.
+    /// When absent, keep the version in the existing session metadata.
+    pub multi_agent_version: Option<MultiAgentVersion>,
+}
+
+/// Frozen source history and model context for a reference-backed fork.
+#[derive(Debug)]
+pub struct PreparedFork {
+    /// Immediate source thread, even when the normalized history base names an ancestor.
+    pub source_thread_id: ThreadId,
+    /// Frozen physical rollout prefix inherited by the child.
+    pub history_base: Option<HistoryPosition>,
+    /// Bounded model context selected by the requested fork boundary.
+    pub model_context: Arc<Vec<RolloutItem>>,
+    /// Blocks source deletion until the child's history reference is durable.
+    _source_reservation: Box<dyn std::fmt::Debug + Send>,
+}
+
+impl PreparedFork {
+    /// Creates a frozen fork snapshot while retaining a backend-owned source reservation.
+    pub fn new(
+        source_thread_id: ThreadId,
+        history_base: Option<HistoryPosition>,
+        model_context: Arc<Vec<RolloutItem>>,
+        source_reservation: impl std::fmt::Debug + Send + 'static,
+    ) -> Self {
+        Self {
+            source_thread_id,
+            history_base,
+            model_context,
+            _source_reservation: Box::new(source_reservation),
+        }
+    }
+}
+
+/// Parameters for reading a thread summary and optionally its replay history.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ReadThreadParams {
+    /// Thread id to read.
+    pub thread_id: ThreadId,
+    /// Whether archived threads are eligible.
+    pub include_archived: bool,
+    /// Whether persisted rollout items should be included in the response.
+    pub include_history: bool,
+}
+
+/// Parameters for reading a local rollout-backed thread by path.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ReadThreadByRolloutPathParams {
+    /// Local rollout JSONL path to read.
+    pub rollout_path: PathBuf,
+    /// Whether archived threads are eligible.
+    pub include_archived: bool,
+    /// Whether persisted rollout items should be included in the response.
+    pub include_history: bool,
+}
+
+/// The sort key to use when listing stored threads.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ThreadSortKey {
+    /// Sort by the thread creation timestamp.
+    #[default]
+    CreatedAt,
+    /// Sort by the thread last-update timestamp.
+    UpdatedAt,
+    /// Sort by the thread's product recency timestamp.
+    RecencyAt,
+    /// Sort by the thread's persisted position within its section.
+    SectionPosition,
+}
+
+/// The direction to use when listing stored threads.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SortDirection {
+    /// Return older threads before newer threads.
+    Asc,
+    /// Return newer threads before older threads.
+    #[default]
+    Desc,
+}
+
+/// Spawn-graph relationship used to filter thread listings.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ThreadRelationFilter {
+    /// Return only threads whose immediate parent is the given thread.
+    DirectChildrenOf(ThreadId),
+    /// Return every thread transitively descended from the given thread.
+    DescendantsOf(ThreadId),
+}
+
+/// Parameters for listing threads.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ListThreadsParams {
+    /// Maximum number of threads to return.
+    pub page_size: usize,
+    /// Opaque cursor returned by a previous list call.
+    pub cursor: Option<String>,
+    /// Sort order requested by the caller.
+    pub sort_key: ThreadSortKey,
+    /// Sort direction requested by the caller.
+    pub sort_direction: SortDirection,
+    /// Allowed session sources. Empty means implementation default.
+    pub allowed_sources: Vec<SessionSource>,
+    /// Optional model provider filter. `None` means implementation default, while an empty vector
+    /// means all providers.
+    pub model_providers: Option<Vec<String>>,
+    /// Optional cwd filters. `None` means all working directories, while an empty vector matches no
+    /// threads.
+    pub cwd_filters: Option<Vec<PathBuf>>,
+    /// Omit to include every section, set to `None` to match unsectioned
+    /// threads, or provide a section ID to match that section.
+    pub section: Option<Option<String>>,
+    /// Omit to include every project, set to None for unassigned threads,
+    /// or provide a project ID to match that project.
+    pub project_id: ClearableField<String>,
+    /// Whether archived threads should be listed instead of active threads.
+    pub archived: bool,
+    /// Optional substring/full-text search term for thread title/preview.
+    pub search_term: Option<String>,
+    /// Optional spawn-graph relationship filter.
+    pub relation_filter: Option<ThreadRelationFilter>,
+    /// Return directly from the state DB without scanning JSONL rollouts to repair metadata.
+    pub use_state_db_only: bool,
+}
+
+/// Parameters for searching thread content.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SearchThreadsParams {
+    /// Maximum number of threads to return.
+    pub page_size: usize,
+    /// Opaque cursor returned by a previous search call.
+    pub cursor: Option<String>,
+    /// Sort order requested by the caller.
+    pub sort_key: ThreadSortKey,
+    /// Sort direction requested by the caller.
+    pub sort_direction: SortDirection,
+    /// Allowed session sources. Empty means implementation default.
+    pub allowed_sources: Vec<SessionSource>,
+    /// Whether archived threads should be searched instead of active threads.
+    pub archived: bool,
+    /// Visible thread content to search for.
+    pub search_term: String,
+}
+
+/// A page of stored thread records.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ThreadPage {
+    /// Threads returned for this page.
+    pub items: Vec<StoredThread>,
+    /// Opaque cursor to continue listing.
+    pub next_cursor: Option<String>,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct StoredThreadSearchResult {
+    pub thread: StoredThread,
+    pub snippet: String,
+}
+
+/// A page of thread-search results.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ThreadSearchPage {
+    /// Search results returned for this page.
+    pub items: Vec<StoredThreadSearchResult>,
+    /// Opaque cursor to continue searching.
+    pub next_cursor: Option<String>,
+}
+
+/// Requested amount of item detail for stored turns.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub enum StoredTurnItemsView {
+    /// Return turn metadata only.
+    NotLoaded,
+    /// Return display summary items for each turn.
+    #[default]
+    Summary,
+}
+
+/// Store-owned status for a persisted turn.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum StoredTurnStatus {
+    /// The turn completed normally.
+    Completed,
+    /// The turn was interrupted before normal completion.
+    Interrupted,
+    /// The turn failed.
+    Failed,
+    /// The turn is still in progress.
+    InProgress,
+}
+
+/// Store-owned error details for a failed persisted turn.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct StoredTurnError {
+    /// User-visible error message.
+    pub message: String,
+    /// Structured Codex error classification, when available.
+    pub codex_error_info: Option<CodexErrorInfo>,
+    /// Optional additional detail for clients that expose expanded error context.
+    pub additional_details: Option<String>,
+}
+
+/// Parameters for listing turns within a stored thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ListTurnsParams {
+    /// Thread id to read.
+    pub thread_id: ThreadId,
+    /// Whether archived threads are eligible.
+    pub include_archived: bool,
+    /// Opaque cursor returned by a previous list call.
+    pub cursor: Option<String>,
+    /// Maximum number of turns to return.
+    pub page_size: usize,
+    /// Sort direction requested by the caller.
+    pub sort_direction: SortDirection,
+    /// Requested amount of item detail for each returned turn.
+    pub items_view: StoredTurnItemsView,
+}
+
+/// Store-owned turn representation used by turn pagination APIs.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct StoredTurn {
+    /// Turn id.
+    pub turn_id: String,
+    /// Projected app-server item snapshots associated with this turn, according to `items_view`.
+    pub items: Vec<StoredThreadItem>,
+    /// Amount of item detail included in `items`.
+    pub items_view: StoredTurnItemsView,
+    /// Store-owned status for API layer projection.
+    pub status: StoredTurnStatus,
+    /// Error message when the turn failed.
+    pub error: Option<StoredTurnError>,
+    /// Unix timestamp (seconds) when the turn started.
+    pub started_at: Option<i64>,
+    /// Unix timestamp (seconds) when the turn completed.
+    pub completed_at: Option<i64>,
+    /// Duration between turn start and completion in milliseconds, if known.
+    pub duration_ms: Option<i64>,
+}
+
+/// A page of stored turns.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TurnPage {
+    /// Turns returned for this page.
+    pub turns: Vec<StoredTurn>,
+    /// Opaque cursor to continue listing.
+    pub next_cursor: Option<String>,
+    /// Opaque cursor for fetching in the opposite direction.
+    pub backwards_cursor: Option<String>,
+}
+
+/// Parameters for listing persisted items within a thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ListItemsParams {
+    /// Thread id to read.
+    pub thread_id: ThreadId,
+    /// Optional turn id to filter by. When omitted, returns items across the thread.
+    pub turn_id: Option<String>,
+    /// Whether archived threads are eligible.
+    pub include_archived: bool,
+    /// Opaque cursor returned by a previous list call.
+    pub cursor: Option<String>,
+    /// Maximum number of items to return.
+    pub page_size: usize,
+    /// Direction to sort items by the selected ordinal.
+    pub sort_direction: SortDirection,
+    /// Ordinal to sort items by. Update-ordinal sorting requires an update watermark.
+    pub sort_key: ItemSortKey,
+    /// Filters out items with an update ordinal less than or equal to the provided value.
+    pub after_updated_at_ordinal: Option<u64>,
+}
+
+/// The ordinal to use when listing persisted items.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ItemSortKey {
+    /// Sort by the ordinal where the item was first projected.
+    CreatedAtOrdinal,
+    /// Sort by the ordinal where the item was last updated.
+    UpdatedAtOrdinal,
+}
+
+/// A projected app-server `ThreadItem` snapshot within a turn.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct StoredThreadItem {
+    /// Turn containing this item.
+    pub turn_id: String,
+    /// Stable item identifier within the turn.
+    pub item_id: String,
+    /// Rollout ordinal of the latest persisted update to this item.
+    pub updated_at_ordinal: u64,
+    /// Unix timestamp (milliseconds) when this logical item was first projected.
+    pub created_at_ms: i64,
+    /// Serialized app-server ThreadItem snapshot.
+    pub item_json: Vec<u8>,
+}
+
+/// A page of persisted items within a thread, optionally filtered to a turn.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ItemPage {
+    /// Items returned for this page.
+    pub items: Vec<StoredThreadItem>,
+    /// Opaque cursor to continue listing.
+    pub next_cursor: Option<String>,
+    /// Opaque cursor for fetching in the opposite direction.
+    pub backwards_cursor: Option<String>,
+}
+
+/// Parameters for reading a bounded mixed thread timeline.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ListTimelineParams {
+    pub thread_id: ThreadId,
+    pub cursor: Option<String>,
+    pub page_size: usize,
+}
+
+/// Ordinary items, realtime facts, and the session state preceding their page.
+#[derive(Clone, Debug, PartialEq)]
+pub struct TimelinePage {
+    pub items: Vec<ThreadTimelineEntry>,
+    pub next_cursor: Option<String>,
+    pub active_realtime_session_at_page_start: Option<String>,
+}
+
+/// Parameters for searching visible message occurrences within one paginated thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SearchThreadOccurrencesParams {
+    /// Thread id to search.
+    pub thread_id: ThreadId,
+    /// Case-insensitive literal substring to find.
+    pub search_term: String,
+    /// Opaque cursor returned by a previous search call.
+    pub cursor: Option<String>,
+    /// Maximum number of occurrences to return.
+    pub page_size: usize,
+}
+
+/// UTF-16 code-unit range within `snippet`.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SearchTextRange {
+    pub start: u32,
+    pub end: u32,
+}
+
+/// One visible message occurrence within a stored thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct StoredThreadOccurrence {
+    pub turn_id: String,
+    pub item_id: String,
+    pub snippet: String,
+    pub snippet_match_range: SearchTextRange,
+    /// Inclusive cursor accepted by `thread/turns/list` for this turn.
+    pub turn_cursor: String,
+}
+
+/// A page of visible message occurrences within one stored thread.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ThreadOccurrenceSearchPage {
+    pub items: Vec<StoredThreadOccurrence>,
+    pub next_cursor: Option<String>,
+}
+
+/// Store-owned thread metadata used by list/read/resume responses.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct StoredThread {
+    /// Originator recorded at creation, if available from the backing store.
+    #[serde(default)]
+    pub originator: Option<String>,
+    /// Thread id.
+    pub thread_id: ThreadId,
+    /// Optional extra configuration fields for the thread.
+    pub extra_config: Option<ExtraConfig>,
+    /// Local rollout path when the backing store is filesystem-based.
+    pub rollout_path: Option<PathBuf>,
+    /// Source thread id when this thread was forked from another thread.
+    pub forked_from_id: Option<ThreadId>,
+    /// The ID of the parent thread. This will only be set if this thread is a subagent.
+    pub parent_thread_id: Option<ThreadId>,
+    /// Best available user-facing preview, usually the first user message.
+    pub preview: String,
+    /// Optional user-facing thread name/title.
+    pub name: Option<String>,
+    /// Model provider id associated with the thread.
+    pub model_provider: String,
+    /// Latest observed model, if known.
+    pub model: Option<String>,
+    /// Latest observed reasoning effort, if known.
+    pub reasoning_effort: Option<ReasoningEffort>,
+    /// Thread creation timestamp.
+    pub created_at: DateTime<Utc>,
+    /// Thread last-update timestamp.
+    pub updated_at: DateTime<Utc>,
+    /// Thread product-recency timestamp.
+    pub recency_at: DateTime<Utc>,
+    /// Thread archive timestamp, if archived.
+    pub archived_at: Option<DateTime<Utc>>,
+    /// The user-selected section for this thread, if any.
+    pub section: Option<codex_state::ThreadSection>,
+    /// The server-owned ordering position within the thread's section.
+    #[serde(default)]
+    pub section_position: Option<i64>,
+    /// The time when the thread most recently entered its current section.
+    #[serde(default)]
+    pub section_entered_at: Option<DateTime<Utc>>,
+    /// Canonical project assignment owned by app-server, if any.
+    #[serde(default)]
+    pub project_id: Option<String>,
+    /// User-selected Daybreak preference, absent until explicitly set.
+    #[serde(default)]
+    pub daybreak_enabled: Option<bool>,
+    /// Working directory captured for the thread.
+    pub cwd: PathBuf,
+    /// CLI version captured for the thread.
+    pub cli_version: String,
+    /// Runtime source for the thread.
+    pub source: SessionSource,
+    /// Persisted thread history contract selected when this thread was created.
+    pub history_mode: ThreadHistoryMode,
+    /// Optional analytics source classification for this thread.
+    pub thread_source: Option<ThreadSource>,
+    /// Optional random nickname for thread-spawn sub-agents.
+    pub agent_nickname: Option<String>,
+    /// Optional role for thread-spawn sub-agents.
+    pub agent_role: Option<String>,
+    /// Optional canonical path for thread-spawn sub-agents.
+    pub agent_path: Option<String>,
+    /// Optional Git metadata captured for the thread.
+    pub git_info: Option<GitInfo>,
+    /// Approval mode captured for the thread.
+    pub approval_mode: AskForApproval,
+    /// Canonical runtime permissions captured for the thread.
+    pub permission_profile: PermissionProfile,
+    /// Last observed token usage.
+    pub token_usage: Option<TokenUsage>,
+    /// First user message observed for this thread, if any.
+    pub first_user_message: Option<String>,
+    /// Persisted history, populated only when requested.
+    pub history: Option<StoredThreadHistory>,
+}
+
+/// Optional field patch where omission leaves a value unchanged and `Some(None)` clears it.
+pub type ClearableField<T> = Option<Option<T>>;
+
+/// Patch for thread Git metadata.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct GitInfoPatch {
+    /// Replacement commit SHA, clear request, or no-op.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub sha: ClearableField<String>,
+    /// Replacement branch name, clear request, or no-op.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub branch: ClearableField<String>,
+    /// Replacement origin URL, clear request, or no-op.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub origin_url: ClearableField<SanitizedGitUrl>,
+}
+
+impl GitInfoPatch {
+    /// Merges another patch into this one using field-presence semantics.
+    ///
+    /// Omitted fields in `next` leave the current patch unchanged. Present fields replace the
+    /// current value, including clear requests like `Some(None)`.
+    pub fn merge(&mut self, next: Self) {
+        if next.sha.is_some() {
+            self.sha = next.sha;
+        }
+        if next.branch.is_some() {
+            self.branch = next.branch;
+        }
+        if next.origin_url.is_some() {
+            self.origin_url = next.origin_url;
+        }
+    }
+}
+
+/// Patch for thread metadata.
+///
+/// Unless noted otherwise, `None` leaves a field unchanged, while `Some`
+/// applies the supplied value. Fields whose value may itself be cleared use an
+/// inner `Option`, where `Some(None)` clears the field.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct ThreadMetadataPatch {
+    /// Replacement user-facing thread name.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub name: ClearableField<String>,
+    /// Known local rollout path for stores that expose one.
+    pub rollout_path: Option<PathBuf>,
+    /// Best available preview text for discovery/listing.
+    pub preview: Option<String>,
+    /// Best-effort title derived from history.
+    pub title: Option<String>,
+    /// Model provider associated with the thread.
+    pub model_provider: Option<String>,
+    /// Latest observed model.
+    pub model: Option<String>,
+    /// Latest observed reasoning effort.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub reasoning_effort: ClearableField<ReasoningEffort>,
+    /// Creation timestamp when known.
+    pub created_at: Option<DateTime<Utc>>,
+    /// Last update timestamp for this metadata observation.
+    pub updated_at: Option<DateTime<Utc>>,
+    /// Advance product recency to at least this timestamp.
+    pub advance_recency_at: Option<DateTime<Utc>>,
+    /// Session source.
+    pub source: Option<SessionSource>,
+    /// Recorded creation-time originator. Only fills a missing stored value.
+    pub originator: Option<String>,
+    /// Optional analytics source classification.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub thread_source: ClearableField<ThreadSource>,
+    /// Optional agent nickname.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub agent_nickname: ClearableField<String>,
+    /// Optional agent role.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub agent_role: ClearableField<String>,
+    /// Optional canonical agent path.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub agent_path: ClearableField<String>,
+    /// Working directory.
+    pub cwd: Option<PathBuf>,
+    /// CLI version that created the thread.
+    pub cli_version: Option<String>,
+    /// Approval mode.
+    pub approval_mode: Option<AskForApproval>,
+    /// Canonical runtime permissions.
+    pub permission_profile: Option<PermissionProfile>,
+    /// Last observed token usage.
+    pub token_usage: Option<TokenUsage>,
+    /// First user message observed for this thread.
+    pub first_user_message: Option<String>,
+    /// Git metadata patch.
+    pub git_info: Option<GitInfoPatch>,
+    /// Thread memory behavior.
+    pub memory_mode: Option<MemoryMode>,
+    /// Initial project assignment supplied with thread creation.
+    #[serde(
+        default,
+        skip_serializing_if = "Option::is_none",
+        with = "optional_option"
+    )]
+    pub project_id: ClearableField<String>,
+    /// User-selected Daybreak preference; omission leaves it unchanged.
+    pub daybreak_enabled: Option<bool>,
+}
+
+impl ThreadMetadataPatch {
+    /// Merges another patch into this one using field-presence semantics.
+    ///
+    /// Omitted fields in `next` leave the current patch unchanged. Present fields replace the
+    /// current value, including clear requests like `Some(None)`. Nested patches use the same
+    /// semantics.
+    pub fn merge(&mut self, next: Self) {
+        if next.name.is_some() {
+            self.name = next.name;
+        }
+        if next.rollout_path.is_some() {
+            self.rollout_path = next.rollout_path;
+        }
+        if next.preview.is_some() {
+            self.preview = next.preview;
+        }
+        if next.title.is_some() {
+            self.title = next.title;
+        }
+        if next.model_provider.is_some() {
+            self.model_provider = next.model_provider;
+        }
+        if next.model.is_some() {
+            self.model = next.model;
+        }
+        if next.reasoning_effort.is_some() {
+            self.reasoning_effort = next.reasoning_effort;
+        }
+        if next.created_at.is_some() {
+            self.created_at = next.created_at;
+        }
+        if next.updated_at.is_some() {
+            self.updated_at = next.updated_at;
+        }
+        if next.advance_recency_at.is_some() {
+            self.advance_recency_at = next.advance_recency_at;
+        }
+        if next.source.is_some() {
+            self.source = next.source;
+        }
+        if next.originator.is_some() {
+            self.originator = next.originator;
+        }
+        if next.thread_source.is_some() {
+            self.thread_source = next.thread_source;
+        }
+        if next.agent_nickname.is_some() {
+            self.agent_nickname = next.agent_nickname;
+        }
+        if next.agent_role.is_some() {
+            self.agent_role = next.agent_role;
+        }
+        if next.agent_path.is_some() {
+            self.agent_path = next.agent_path;
+        }
+        if next.cwd.is_some() {
+            self.cwd = next.cwd;
+        }
+        if next.cli_version.is_some() {
+            self.cli_version = next.cli_version;
+        }
+        if next.approval_mode.is_some() {
+            self.approval_mode = next.approval_mode;
+        }
+        if next.permission_profile.is_some() {
+            self.permission_profile = next.permission_profile;
+        }
+        if next.token_usage.is_some() {
+            self.token_usage = next.token_usage;
+        }
+        if next.first_user_message.is_some() {
+            self.first_user_message = next.first_user_message;
+        }
+        if let Some(git_info) = next.git_info {
+            self.git_info
+                .get_or_insert_with(GitInfoPatch::default)
+                .merge(git_info);
+        }
+        if next.memory_mode.is_some() {
+            self.memory_mode = next.memory_mode;
+        }
+        if next.project_id.is_some() {
+            self.project_id = next.project_id;
+        }
+        if next.daybreak_enabled.is_some() {
+            self.daybreak_enabled = next.daybreak_enabled;
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.name.is_none()
+            && self.rollout_path.is_none()
+            && self.preview.is_none()
+            && self.title.is_none()
+            && self.model_provider.is_none()
+            && self.model.is_none()
+            && self.reasoning_effort.is_none()
+            && self.created_at.is_none()
+            && self.updated_at.is_none()
+            && self.advance_recency_at.is_none()
+            && self.source.is_none()
+            && self.originator.is_none()
+            && self.thread_source.is_none()
+            && self.agent_nickname.is_none()
+            && self.agent_role.is_none()
+            && self.agent_path.is_none()
+            && self.cwd.is_none()
+            && self.cli_version.is_none()
+            && self.approval_mode.is_none()
+            && self.permission_profile.is_none()
+            && self.token_usage.is_none()
+            && self.first_user_message.is_none()
+            && self.git_info.is_none()
+            && self.memory_mode.is_none()
+            && self.project_id.is_none()
+            && self.daybreak_enabled.is_none()
+    }
+}
+
+/// Parameters for patching mutable thread metadata.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct UpdateThreadMetadataParams {
+    /// Thread id to update.
+    pub thread_id: ThreadId,
+    /// Patch to apply.
+    pub patch: ThreadMetadataPatch,
+    /// Whether archived threads are eligible.
+    pub include_archived: bool,
+}
+
+/// Parameters for moving a thread to, within, or out of a server-ordered section.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct MoveThreadToSectionParams {
+    /// Thread to move.
+    pub thread_id: ThreadId,
+    /// Destination section, or `None` to remove the thread from its section.
+    pub section: Option<String>,
+    /// Existing section member to insert before, or `None` to append.
+    pub before_thread_id: Option<ThreadId>,
+}
+
+/// Parameters for archiving or unarchiving a thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ArchiveThreadParams {
+    /// Thread id to archive or unarchive.
+    pub thread_id: ThreadId,
+}
+
+/// Parameters for archiving a set of threads as one store operation.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ArchiveThreadsParams {
+    /// Thread ids to archive, in the order their persisted data should be moved.
+    pub thread_ids: Vec<ThreadId>,
+    /// Thread ids whose paginated writer ownership must be checked before archiving, including
+    /// descendants whose rollout has not materialized yet.
+    #[serde(default)]
+    pub writer_lock_thread_ids: Vec<ThreadId>,
+}
+
+/// Parameters for deleting a thread.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeleteThreadParams {
+    /// Thread id to delete.
+    pub thread_id: ThreadId,
+}
+
+/// Parameters for deleting a set of threads as one store operation.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DeleteThreadsParams {
+    /// Thread ids to delete, in the order their persisted data should be removed.
+    pub thread_ids: Vec<ThreadId>,
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn thread_metadata_patch_round_trips_optional_clears() {
+        let patch = ThreadMetadataPatch {
+            name: Some(None),
+            reasoning_effort: Some(None),
+            thread_source: Some(None),
+            agent_nickname: Some(None),
+            agent_role: Some(None),
+            agent_path: Some(None),
+            ..Default::default()
+        };
+
+        let value = serde_json::to_value(&patch).expect("serialize patch");
+        assert_eq!(value["name"], json!(null));
+        assert_eq!(value["reasoning_effort"], json!(null));
+        assert_eq!(value["thread_source"], json!(null));
+        assert_eq!(value["agent_nickname"], json!(null));
+        assert_eq!(value["agent_role"], json!(null));
+        assert_eq!(value["agent_path"], json!(null));
+
+        let decoded: ThreadMetadataPatch =
+            serde_json::from_value(value).expect("deserialize patch");
+        assert_eq!(decoded.name, Some(None));
+        assert_eq!(decoded.reasoning_effort, Some(None));
+        assert_eq!(decoded.thread_source, Some(None));
+        assert_eq!(decoded.agent_nickname, Some(None));
+        assert_eq!(decoded.agent_role, Some(None));
+        assert_eq!(decoded.agent_path, Some(None));
+    }
+
+    #[test]
+    fn git_info_patch_round_trips_optional_clears() {
+        let patch = ThreadMetadataPatch {
+            git_info: Some(GitInfoPatch {
+                sha: None,
+                branch: Some(Some("main".to_string())),
+                origin_url: Some(None),
+            }),
+            ..Default::default()
+        };
+
+        let value = serde_json::to_value(&patch).expect("serialize patch");
+        assert_eq!(
+            value["git_info"],
+            json!({
+                "branch": "main",
+                "origin_url": null,
+            })
+        );
+
+        let decoded: ThreadMetadataPatch =
+            serde_json::from_value(value).expect("deserialize patch");
+        assert_eq!(
+            decoded.git_info,
+            Some(GitInfoPatch {
+                sha: None,
+                branch: Some(Some("main".to_string())),
+                origin_url: Some(None),
+            })
+        );
+    }
+
+    #[test]
+    fn thread_metadata_patch_accepts_missing_fields() {
+        let decoded: ThreadMetadataPatch =
+            serde_json::from_value(json!({})).expect("deserialize legacy patch");
+
+        assert!(decoded.is_empty());
+    }
+
+    #[test]
+    fn canonical_history_mode_uses_first_session_meta() {
+        assert_eq!(
+            canonical_history_mode_from_rollout_items(&[
+                session_meta(ThreadHistoryMode::Legacy),
+                session_meta(ThreadHistoryMode::Paginated),
+            ]),
+            ThreadHistoryMode::Legacy
+        );
+    }
+
+    #[test]
+    fn thread_metadata_patch_merge_uses_presence_semantics() {
+        let mut current = ThreadMetadataPatch {
+            name: Some(Some("old name".to_string())),
+            preview: Some("old preview".to_string()),
+            git_info: Some(GitInfoPatch {
+                sha: Some(Some("abc123".to_string())),
+                branch: Some(Some("main".to_string())),
+                origin_url: None,
+            }),
+            ..Default::default()
+        };
+
+        current.merge(ThreadMetadataPatch {
+            name: Some(None),
+            preview: None,
+            title: Some("new title".to_string()),
+            git_info: Some(GitInfoPatch {
+                sha: None,
+                branch: Some(Some("feature".to_string())),
+                origin_url: Some(None),
+            }),
+            ..Default::default()
+        });
+
+        assert_eq!(current.name, Some(None));
+        assert_eq!(current.preview.as_deref(), Some("old preview"));
+        assert_eq!(current.title.as_deref(), Some("new title"));
+        assert_eq!(
+            current.git_info,
+            Some(GitInfoPatch {
+                sha: Some(Some("abc123".to_string())),
+                branch: Some(Some("feature".to_string())),
+                origin_url: Some(None),
+            })
+        );
+    }
+
+    fn session_meta(history_mode: ThreadHistoryMode) -> RolloutItem {
+        RolloutItem::SessionMeta(codex_protocol::protocol::SessionMetaLine {
+            meta: codex_protocol::protocol::SessionMeta {
+                history_mode,
+                ..Default::default()
+            },
+            git: None,
+        })
+    }
+}
diff --git a/codex-rs/uds/src/lib.rs b/codex-rs/uds/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a237d1060b112fadf9b10514771189f8cdcf1dc6
--- /dev/null
+++ b/codex-rs/uds/src/lib.rs
@@ -0,0 +1,361 @@
+//! Cross-platform async Unix domain socket helpers.
+
+use std::io::Result as IoResult;
+use std::path::Path;
+use std::pin::Pin;
+use std::task::Context;
+use std::task::Poll;
+
+use tokio::io::AsyncRead;
+use tokio::io::AsyncWrite;
+use tokio::io::ReadBuf;
+
+/// Creates `socket_dir` if needed and restricts it to the current user as
+/// supported by the platform (0700 on Unix, a protected user-only DACL on Windows).
+/// Windows rejects existing directories unless they already have that owner and DACL;
+/// changing permissions cannot revoke access held through preexisting handles.
+pub async fn prepare_private_socket_directory(socket_dir: impl AsRef<Path>) -> IoResult<()> {
+    platform::prepare_private_socket_directory(socket_dir.as_ref()).await
+}
+
+/// Returns whether `socket_path` points at a stale Unix socket rendezvous path.
+///
+/// On Unix this checks the file type. On Windows, `uds_windows` represents the
+/// rendezvous as a regular path, so existence is the only useful stale-path
+/// signal available.
+pub async fn is_stale_socket_path(socket_path: impl AsRef<Path>) -> IoResult<bool> {
+    platform::is_stale_socket_path(socket_path.as_ref()).await
+}
+
+/// Async Unix domain socket listener.
+pub struct UnixListener {
+    inner: platform::Listener,
+}
+
+impl UnixListener {
+    /// Binds a new listener at `socket_path`.
+    pub async fn bind(socket_path: impl AsRef<Path>) -> IoResult<Self> {
+        platform::bind_listener(socket_path.as_ref())
+            .await
+            .map(|inner| Self { inner })
+    }
+
+    /// Accepts the next incoming stream.
+    pub async fn accept(&mut self) -> IoResult<UnixStream> {
+        self.inner.accept().await.map(|inner| UnixStream { inner })
+    }
+}
+
+/// Async Unix domain socket stream.
+pub struct UnixStream {
+    inner: platform::Stream,
+}
+
+impl UnixStream {
+    /// Requires the Windows peer to belong to the current user, with neither
+    /// process elevated. Call before sending any application data.
+    #[cfg(windows)]
+    pub fn ensure_non_elevated_peer(&self) -> IoResult<()> {
+        self.inner.ensure_non_elevated_peer()
+    }
+
+    /// Connects to `socket_path`.
+    pub async fn connect(socket_path: impl AsRef<Path>) -> IoResult<Self> {
+        platform::connect_stream(socket_path.as_ref())
+            .await
+            .map(|inner| Self { inner })
+    }
+}
+
+impl AsyncRead for UnixStream {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<IoResult<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_read(cx, buf)
+    }
+}
+
+impl AsyncWrite for UnixStream {
+    fn poll_write(self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8]) -> Poll<IoResult<usize>> {
+        Pin::new(&mut self.get_mut().inner).poll_write(cx, buf)
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_shutdown(cx)
+    }
+}
+
+#[cfg(unix)]
+mod platform {
+    use std::io;
+    use std::io::ErrorKind;
+    use std::io::Result as IoResult;
+    use std::os::unix::fs::FileTypeExt;
+    use std::os::unix::fs::PermissionsExt;
+    use std::path::Path;
+
+    use tokio::fs;
+    use tokio::net::UnixListener;
+    use tokio::net::UnixStream;
+
+    /// Owner-only access keeps the control socket directory private while
+    /// preserving owner traversal and socket path creation.
+    const SOCKET_DIR_MODE: u32 = 0o700;
+    const SOCKET_DIR_PERMISSION_BITS: u32 = 0o777;
+
+    pub(super) type Stream = UnixStream;
+
+    pub(super) struct Listener(UnixListener);
+
+    pub(super) async fn prepare_private_socket_directory(socket_dir: &Path) -> IoResult<()> {
+        let mut dir_builder = fs::DirBuilder::new();
+        dir_builder.mode(SOCKET_DIR_MODE);
+        match dir_builder.create(socket_dir).await {
+            Ok(()) => return Ok(()),
+            Err(err) if err.kind() == ErrorKind::AlreadyExists => {}
+            Err(err) => return Err(err),
+        }
+
+        let metadata = fs::symlink_metadata(socket_dir).await?;
+        if !metadata.is_dir() {
+            return Err(io::Error::new(
+                ErrorKind::AlreadyExists,
+                format!(
+                    "socket directory path exists and is not a directory: {}",
+                    socket_dir.display()
+                ),
+            ));
+        }
+
+        let permissions = metadata.permissions();
+        // The SSH-over-UDS control socket is reachable by path, so the
+        // rendezvous directory must be owner-traversable while denying
+        // group/other access; exact 0700 fixes insecure modes and unusable
+        // owner-only modes like 0600.
+        if permissions.mode() & SOCKET_DIR_PERMISSION_BITS != SOCKET_DIR_MODE {
+            fs::set_permissions(socket_dir, std::fs::Permissions::from_mode(SOCKET_DIR_MODE))
+                .await?;
+        }
+
+        Ok(())
+    }
+
+    pub(super) async fn bind_listener(socket_path: &Path) -> IoResult<Listener> {
+        UnixListener::bind(socket_path).map(Listener)
+    }
+
+    impl Listener {
+        pub(super) async fn accept(&mut self) -> IoResult<Stream> {
+            self.0.accept().await.map(|(stream, _addr)| stream)
+        }
+    }
+
+    pub(super) async fn connect_stream(socket_path: &Path) -> IoResult<Stream> {
+        UnixStream::connect(socket_path).await
+    }
+
+    pub(super) async fn is_stale_socket_path(socket_path: &Path) -> IoResult<bool> {
+        Ok(fs::symlink_metadata(socket_path)
+            .await?
+            .file_type()
+            .is_socket())
+    }
+}
+
+#[cfg(windows)]
+mod platform {
+    use std::io;
+    use std::io::Result as IoResult;
+    use std::net::Shutdown;
+    use std::ops::Deref;
+    use std::os::windows::io::AsRawSocket;
+    use std::os::windows::io::AsSocket;
+    use std::os::windows::io::BorrowedSocket;
+    use std::path::Path;
+    use std::pin::Pin;
+    use std::task::Context;
+    use std::task::Poll;
+    use std::task::ready;
+
+    use async_io::Async;
+    use tokio::io::AsyncRead;
+    use tokio::io::AsyncWrite;
+    use tokio::io::ReadBuf;
+    use tokio::task;
+    use tokio_util::compat::Compat;
+    use tokio_util::compat::FuturesAsyncReadCompatExt;
+
+    pub(super) struct Stream(Compat<Async<WindowsUnixStream>>);
+
+    impl Stream {
+        pub(super) fn ensure_non_elevated_peer(&self) -> IoResult<()> {
+            crate::windows_peer::ensure_non_elevated_peer(
+                self.0.get_ref().get_ref().as_raw_socket(),
+            )
+        }
+    }
+
+    pub(super) async fn prepare_private_socket_directory(socket_dir: &Path) -> IoResult<()> {
+        let socket_dir = socket_dir.to_path_buf();
+        spawn_blocking_io(move || crate::windows_security::prepare_private_directory(&socket_dir))
+            .await
+    }
+
+    pub(super) struct Listener(Async<WindowsUnixListener>);
+
+    pub(super) async fn bind_listener(socket_path: &Path) -> IoResult<Listener> {
+        let socket_path = socket_path.to_path_buf();
+        let listener =
+            spawn_blocking_io(move || uds_windows::UnixListener::bind(socket_path)).await?;
+        Async::new(WindowsUnixListener::from(listener)).map(Listener)
+    }
+
+    impl Listener {
+        pub(super) async fn accept(&mut self) -> IoResult<Stream> {
+            let (stream, _addr) = self.0.read_with(|listener| listener.accept()).await?;
+            Async::new(WindowsUnixStream::from(stream))
+                .map(FuturesAsyncReadCompatExt::compat)
+                .map(Stream)
+        }
+    }
+
+    pub(super) async fn connect_stream(socket_path: &Path) -> IoResult<Stream> {
+        let socket_path = socket_path.to_path_buf();
+        let stream =
+            spawn_blocking_io(move || uds_windows::UnixStream::connect(socket_path)).await?;
+        Async::new(WindowsUnixStream::from(stream))
+            .map(FuturesAsyncReadCompatExt::compat)
+            .map(Stream)
+    }
+
+    pub(super) async fn is_stale_socket_path(socket_path: &Path) -> IoResult<bool> {
+        tokio::fs::try_exists(socket_path).await
+    }
+
+    async fn spawn_blocking_io<T>(
+        operation: impl FnOnce() -> IoResult<T> + Send + 'static,
+    ) -> IoResult<T>
+    where
+        T: Send + 'static,
+    {
+        task::spawn_blocking(operation)
+            .await
+            .map_err(|err| io::Error::other(format!("blocking socket task failed: {err}")))?
+    }
+
+    pub(super) struct WindowsUnixListener(uds_windows::UnixListener);
+
+    impl From<uds_windows::UnixListener> for WindowsUnixListener {
+        fn from(listener: uds_windows::UnixListener) -> Self {
+            Self(listener)
+        }
+    }
+
+    impl Deref for WindowsUnixListener {
+        type Target = uds_windows::UnixListener;
+
+        fn deref(&self) -> &Self::Target {
+            &self.0
+        }
+    }
+
+    impl AsSocket for WindowsUnixListener {
+        fn as_socket(&self) -> BorrowedSocket<'_> {
+            unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) }
+        }
+    }
+
+    pub(super) struct WindowsUnixStream(uds_windows::UnixStream);
+
+    impl From<uds_windows::UnixStream> for WindowsUnixStream {
+        fn from(stream: uds_windows::UnixStream) -> Self {
+            Self(stream)
+        }
+    }
+
+    impl Deref for WindowsUnixStream {
+        type Target = uds_windows::UnixStream;
+
+        fn deref(&self) -> &Self::Target {
+            &self.0
+        }
+    }
+
+    impl AsSocket for WindowsUnixStream {
+        fn as_socket(&self) -> BorrowedSocket<'_> {
+            unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) }
+        }
+    }
+
+    impl io::Read for WindowsUnixStream {
+        fn read(&mut self, buf: &mut [u8]) -> IoResult<usize> {
+            io::Read::read(&mut self.0, buf)
+        }
+    }
+
+    impl io::Write for WindowsUnixStream {
+        fn write(&mut self, buf: &[u8]) -> IoResult<usize> {
+            io::Write::write(&mut self.0, buf)
+        }
+
+        fn flush(&mut self) -> IoResult<()> {
+            io::Write::flush(&mut self.0)
+        }
+    }
+
+    impl AsyncRead for Stream {
+        fn poll_read(
+            self: Pin<&mut Self>,
+            cx: &mut Context<'_>,
+            buf: &mut ReadBuf<'_>,
+        ) -> Poll<IoResult<()>> {
+            Pin::new(&mut self.get_mut().0).poll_read(cx, buf)
+        }
+    }
+
+    impl AsyncWrite for Stream {
+        fn poll_write(
+            self: Pin<&mut Self>,
+            cx: &mut Context<'_>,
+            buf: &[u8],
+        ) -> Poll<IoResult<usize>> {
+            Pin::new(&mut self.get_mut().0).poll_write(cx, buf)
+        }
+
+        fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>> {
+            Pin::new(&mut self.get_mut().0).poll_flush(cx)
+        }
+
+        fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<IoResult<()>> {
+            let stream = &mut self.get_mut().0;
+            ready!(Pin::new(&mut *stream).poll_flush(cx))?;
+            // `Compat<Async<_>>` maps shutdown to `poll_close()`, which only
+            // flushes for `async_io::Async`; call the socket shutdown directly.
+            stream.get_ref().get_ref().shutdown(Shutdown::Write)?;
+            Poll::Ready(Ok(()))
+        }
+    }
+
+    unsafe impl async_io::IoSafe for WindowsUnixListener {}
+    unsafe impl async_io::IoSafe for WindowsUnixStream {}
+}
+
+#[cfg(test)]
+mod lib_tests;
+
+#[cfg(windows)]
+mod windows_security;
+
+#[cfg(windows)]
+mod windows_socket_validation;
+#[cfg(windows)]
+pub use windows_socket_validation::validate_private_socket_path;
+
+#[cfg(windows)]
+mod windows_peer;
diff --git a/codex-rs/uds/src/lib_tests.rs b/codex-rs/uds/src/lib_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..91040b1253789125fe603205b5e3ad002178c400
--- /dev/null
+++ b/codex-rs/uds/src/lib_tests.rs
@@ -0,0 +1,307 @@
+use std::io::ErrorKind;
+
+use pretty_assertions::assert_eq;
+use tokio::io::AsyncReadExt;
+use tokio::io::AsyncWriteExt;
+
+use super::*;
+
+#[cfg(windows)]
+#[tokio::test]
+async fn private_directory_rejects_volume_roots() {
+    // A nonexistent volume keeps this regression safe even if root validation breaks.
+    let root = Path::new(r"\\?\Volume{00000000-0000-0000-0000-000000000000}\");
+    assert_eq!(
+        prepare_private_socket_directory(root)
+            .await
+            .unwrap_err()
+            .kind(),
+        ErrorKind::InvalidInput,
+    );
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn private_directory_rejects_junctions() {
+    let temp = tempfile::TempDir::new().expect("temp directory");
+    let target = temp.path().join("target");
+    let junction = temp.path().join("junction");
+    std::fs::create_dir(&target).expect("target");
+    let output = std::process::Command::new("powershell.exe")
+        .args(["-NoProfile", "-NonInteractive", "-Command", "$ErrorActionPreference = 'Stop'; New-Item -ItemType Junction -Path $env:CODEX_TEST_LINK -Target $env:CODEX_TEST_TARGET | Out-Null"])
+        .env("CODEX_TEST_LINK", &junction)
+        .env("CODEX_TEST_TARGET", &target)
+        .output().expect("create junction");
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    assert_eq!(
+        prepare_private_socket_directory(&junction)
+            .await
+            .unwrap_err()
+            .kind(),
+        ErrorKind::PermissionDenied,
+    );
+    assert_eq!(
+        validate_private_socket_path(&junction.join("socket"))
+            .unwrap_err()
+            .kind(),
+        ErrorKind::PermissionDenied,
+    );
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn socket_validation_pins_private_directory_without_creating_missing_paths() {
+    let temp = tempfile::TempDir::new().expect("temp directory");
+    let directory = temp.path().join("private");
+    let socket_path = directory.join("socket");
+    assert!(validate_private_socket_path(&socket_path).is_err());
+    assert!(!directory.exists());
+    prepare_private_socket_directory(&directory).await.unwrap();
+    let (_validated_path, _guard) = validate_private_socket_path(&socket_path).unwrap();
+    assert!(std::fs::rename(&directory, temp.path().join("moved")).is_err());
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn socket_validation_rejects_broad_acl_without_repairing_it() {
+    let temp = tempfile::TempDir::new().expect("temp directory");
+    let directory = temp.path().join("private");
+    prepare_private_socket_directory(&directory).await.unwrap();
+    let inspect = |script: &str| {
+        let output = std::process::Command::new("powershell.exe")
+            .args(["-NoProfile", "-NonInteractive", "-Command", script])
+            .env("CODEX_TEST_DIRECTORY", &directory)
+            .output()
+            .unwrap();
+        assert!(
+            output.status.success(),
+            "{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        output.stdout
+    };
+    let before = inspect(
+        r#"
+$ErrorActionPreference = 'Stop'
+$acl = Get-Acl -LiteralPath $env:CODEX_TEST_DIRECTORY
+$everyone = [System.Security.Principal.SecurityIdentifier]::new('S-1-1-0')
+$rule = [System.Security.AccessControl.FileSystemAccessRule]::new($everyone, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
+$acl.AddAccessRule($rule)
+Set-Acl -LiteralPath $env:CODEX_TEST_DIRECTORY -AclObject $acl
+(Get-Acl -LiteralPath $env:CODEX_TEST_DIRECTORY).Sddl
+"#,
+    );
+    assert_eq!(
+        validate_private_socket_path(&directory.join("socket"))
+            .unwrap_err()
+            .kind(),
+        ErrorKind::PermissionDenied,
+    );
+    assert_eq!(
+        prepare_private_socket_directory(&directory)
+            .await
+            .unwrap_err()
+            .kind(),
+        ErrorKind::PermissionDenied,
+    );
+    assert_eq!(
+        before,
+        inspect(
+            "$ErrorActionPreference = 'Stop'; (Get-Acl -LiteralPath $env:CODEX_TEST_DIRECTORY).Sddl"
+        )
+    );
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn private_directory_supports_extended_length_paths() {
+    let temp = tempfile::TempDir::new().expect("temp directory");
+    let directory = temp.path().join("a".repeat(150)).join("b".repeat(150));
+    prepare_private_socket_directory(&directory)
+        .await
+        .expect("create long private directory");
+    prepare_private_socket_directory(&directory)
+        .await
+        .expect("validate long private directory");
+    assert!(directory.is_dir());
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn private_directory_acl_is_user_only_and_inherited_by_files() {
+    let temp = tempfile::TempDir::new().expect("temp directory");
+    let directory = temp.path().join("private");
+    // Cover reusing an existing private directory as well as inheriting its DACL.
+    prepare_private_socket_directory(&directory)
+        .await
+        .expect("create user-owned directory");
+    prepare_private_socket_directory(&directory)
+        .await
+        .expect("private directory");
+    std::fs::write(directory.join("child"), b"").expect("child file");
+    let _listener = UnixListener::bind(directory.join("socket"))
+        .await
+        .expect("private socket");
+    let output = std::process::Command::new("powershell.exe")
+        .args(["-NoProfile", "-NonInteractive", "-Command", r#"
+$ErrorActionPreference = 'Stop'
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$directory = Get-Acl -LiteralPath $env:CODEX_TEST_PRIVATE_DIRECTORY
+if (-not $directory.AreAccessRulesProtected) { throw 'directory inherits broad access' }
+foreach ($acl in @($directory, (Get-Acl -LiteralPath (Join-Path $env:CODEX_TEST_PRIVATE_DIRECTORY 'child')), (Get-Acl -LiteralPath (Join-Path $env:CODEX_TEST_PRIVATE_DIRECTORY 'socket')))) {
+    $rules = @($acl.Access)
+    if ($rules.Count -ne 1) { throw 'unexpected access rules' }
+    if ($rules[0].IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value -ne $sid) { throw 'wrong user' }
+    if ($rules[0].AccessControlType -ne 'Allow') { throw 'user is denied access' }
+}
+"#])
+        .env("CODEX_TEST_PRIVATE_DIRECTORY", &directory)
+        .output().expect("inspect ACLs");
+    assert!(
+        output.status.success(),
+        "{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+}
+
+#[tokio::test]
+async fn prepare_private_socket_directory_creates_directory() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_dir = temp_dir.path().join("app-server-control");
+
+    prepare_private_socket_directory(&socket_dir)
+        .await
+        .expect("socket dir should be created");
+
+    assert!(socket_dir.is_dir());
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn prepare_private_socket_directory_sets_existing_permissions_to_owner_only() {
+    use std::os::unix::fs::PermissionsExt;
+
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    for mode in [0o755, 0o600] {
+        let socket_dir = temp_dir.path().join(format!("app-server-control-{mode:o}"));
+        std::fs::create_dir(&socket_dir).expect("socket dir should be created");
+        std::fs::set_permissions(&socket_dir, std::fs::Permissions::from_mode(mode))
+            .expect("socket dir permissions should be changed");
+
+        prepare_private_socket_directory(&socket_dir)
+            .await
+            .expect("socket dir permissions should be set exactly");
+
+        let mode = std::fs::metadata(&socket_dir)
+            .expect("socket dir metadata")
+            .permissions()
+            .mode();
+        assert_eq!(mode & 0o777, 0o700);
+    }
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn regular_file_path_is_not_stale_socket_path() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let regular_file = temp_dir.path().join("not-a-socket");
+    std::fs::write(&regular_file, b"not a socket").expect("regular file should be created");
+
+    assert!(
+        !is_stale_socket_path(&regular_file)
+            .await
+            .expect("stale socket check should succeed")
+    );
+}
+
+#[tokio::test]
+async fn bound_listener_path_is_stale_socket_path() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_path = temp_dir.path().join("socket");
+    let _listener = match UnixListener::bind(&socket_path).await {
+        Ok(listener) => listener,
+        Err(err) if err.kind() == ErrorKind::PermissionDenied => {
+            eprintln!("skipping test: failed to bind unix socket: {err}");
+            return;
+        }
+        Err(err) => panic!("failed to bind test socket: {err}"),
+    };
+
+    assert!(
+        is_stale_socket_path(&socket_path)
+            .await
+            .expect("stale socket check should succeed")
+    );
+}
+
+#[tokio::test]
+async fn stream_round_trips_data_between_listener_and_client() {
+    let temp_dir = tempfile::TempDir::new().expect("temp dir");
+    let socket_path = temp_dir.path().join("socket");
+    let mut listener = match UnixListener::bind(&socket_path).await {
+        Ok(listener) => listener,
+        Err(err) if err.kind() == ErrorKind::PermissionDenied => {
+            eprintln!("skipping test: failed to bind unix socket: {err}");
+            return;
+        }
+        Err(err) => panic!("failed to bind test socket: {err}"),
+    };
+
+    let server_task = tokio::spawn(async move {
+        let mut server_stream = listener.accept().await.expect("connection should accept");
+        let mut request = [0; 7];
+        server_stream
+            .read_exact(&mut request)
+            .await
+            .expect("server should read request");
+        assert_eq!(&request, b"request");
+        server_stream
+            .write_all(b"response")
+            .await
+            .expect("server should write response");
+    });
+
+    let mut client_stream = UnixStream::connect(&socket_path)
+        .await
+        .expect("client should connect");
+    client_stream
+        .write_all(b"request")
+        .await
+        .expect("client should write request");
+    let mut response = [0; 8];
+    client_stream
+        .read_exact(&mut response)
+        .await
+        .expect("client should read response");
+    assert_eq!(&response, b"response");
+
+    server_task.await.expect("server task should join");
+}
+
+#[cfg(windows)]
+#[tokio::test]
+async fn implicit_peer_validation_rejects_elevated_listener() {
+    let temp = tempfile::TempDir::new().unwrap();
+    let path = temp.path().join("socket");
+    let mut listener = UnixListener::bind(&path).await.unwrap();
+    let client = UnixStream::connect(&path).await.unwrap();
+    let _server = listener.accept().await.unwrap();
+    // PowerShell inherits our token and supplies an independent elevation oracle.
+    let output = std::process::Command::new("powershell.exe")
+        .args(["-NoProfile", "-NonInteractive", "-Command", "([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)"])
+        .output().unwrap();
+    assert!(output.status.success());
+    let expected = match String::from_utf8(output.stdout).unwrap().trim() {
+        "True" => Err(ErrorKind::PermissionDenied),
+        "False" => Ok(()),
+        other => panic!("unexpected elevation result: {other}"),
+    };
+    assert_eq!(
+        client.ensure_non_elevated_peer().map_err(|err| err.kind()),
+        expected
+    );
+}
diff --git a/codex-rs/uds/src/windows_peer.rs b/codex-rs/uds/src/windows_peer.rs
new file mode 100644
index 0000000000000000000000000000000000000000..722133365b21ded9b33a5460900156928929a663
--- /dev/null
+++ b/codex-rs/uds/src/windows_peer.rs
@@ -0,0 +1,103 @@
+//! Authenticate implicitly discovered Windows socket peers before sending data.
+//! The socket's kernel-reported PID, rather than a PID file, identifies the token.
+
+use std::io;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::os::windows::io::RawSocket;
+use std::ptr;
+
+use windows_sys::Win32::Networking::WinSock::SIO_AF_UNIX_GETPEERPID;
+use windows_sys::Win32::Networking::WinSock::SOCKET_ERROR;
+use windows_sys::Win32::Networking::WinSock::WSAGetLastError;
+use windows_sys::Win32::Networking::WinSock::WSAIoctl;
+use windows_sys::Win32::Security::EqualSid;
+use windows_sys::Win32::Security::GetTokenInformation;
+use windows_sys::Win32::Security::TOKEN_ELEVATION;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::Security::TOKEN_USER;
+use windows_sys::Win32::Security::TokenElevation;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::OpenProcess;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+use windows_sys::Win32::System::Threading::PROCESS_QUERY_LIMITED_INFORMATION;
+
+pub(super) fn ensure_non_elevated_peer(socket: RawSocket) -> io::Result<()> {
+    let mut pid = 0u32;
+    let mut returned = 0;
+    if unsafe {
+        WSAIoctl(
+            socket as _,
+            SIO_AF_UNIX_GETPEERPID,
+            ptr::null(),
+            /*cbinbuffer*/ 0,
+            ptr::addr_of_mut!(pid).cast(),
+            std::mem::size_of_val(&pid) as u32,
+            &mut returned,
+            ptr::null_mut(),
+            /*lpcompletionroutine*/ None,
+        )
+    } == SOCKET_ERROR
+    {
+        return Err(io::Error::from_raw_os_error(unsafe { WSAGetLastError() }));
+    }
+    // Older Windows versions can return a valid PID with zero bytes reported.
+    if pid == 0 {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            "socket peer PID unavailable",
+        ));
+    }
+    let process = unsafe {
+        OpenProcess(
+            PROCESS_QUERY_LIMITED_INFORMATION,
+            /*binherithandle*/ 0,
+            pid,
+        )
+    };
+    if process == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let _process = unsafe { OwnedHandle::from_raw_handle(process as _) };
+    let mut token = 0;
+    if unsafe { OpenProcessToken(process, TOKEN_QUERY, &mut token) } == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let _token = unsafe { OwnedHandle::from_raw_handle(token as _) };
+    let mut current_token = 0;
+    if unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut current_token) } == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let _current_token = unsafe { OwnedHandle::from_raw_handle(current_token as _) };
+    let current_user = crate::windows_security::token_user(current_token)?;
+    let peer_user = crate::windows_security::token_user(token)?;
+    let same_user = unsafe {
+        EqualSid(
+            (*(current_user.as_ptr().cast::<TOKEN_USER>())).User.Sid,
+            (*(peer_user.as_ptr().cast::<TOKEN_USER>())).User.Sid,
+        ) != 0
+    };
+    // Implicit reuse must not change either side's elevation context.
+    for token in [current_token, token] {
+        let mut elevation: TOKEN_ELEVATION = unsafe { std::mem::zeroed() };
+        if unsafe {
+            GetTokenInformation(
+                token,
+                TokenElevation,
+                ptr::addr_of_mut!(elevation).cast(),
+                std::mem::size_of_val(&elevation) as u32,
+                &mut returned,
+            )
+        } == 0
+        {
+            return Err(io::Error::last_os_error());
+        }
+        if !same_user || elevation.TokenIsElevated != 0 {
+            return Err(io::Error::new(
+                io::ErrorKind::PermissionDenied,
+                "implicit daemon connection requires non-elevated current-user tokens",
+            ));
+        }
+    }
+    Ok(())
+}
diff --git a/codex-rs/uds/src/windows_security.rs b/codex-rs/uds/src/windows_security.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9b818d8411d0a5ee78036d9be275c0fda2dc168c
--- /dev/null
+++ b/codex-rs/uds/src/windows_security.rs
@@ -0,0 +1,128 @@
+//! Protect Windows socket rendezvous directories with an inheritable user-only
+//! DACL at creation time. Reject unsafe existing directories instead of repairing them.
+
+use std::io;
+use std::os::windows::ffi::OsStrExt;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::ptr;
+
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::Authorization::ConvertSidToStringSidW;
+use windows_sys::Win32::Security::Authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW;
+use windows_sys::Win32::Security::GetTokenInformation;
+use windows_sys::Win32::Security::SECURITY_ATTRIBUTES;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::Security::TOKEN_USER;
+use windows_sys::Win32::Security::TokenUser;
+use windows_sys::Win32::Storage::FileSystem::CreateDirectoryW;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+
+pub(super) fn prepare_private_directory(path: &Path) -> io::Result<()> {
+    let user = current_user()?;
+    let user_sid = unsafe { (*(user.as_ptr().cast::<TOKEN_USER>())).User.Sid };
+    let mut sid_string = ptr::null_mut();
+    if unsafe { ConvertSidToStringSidW(user_sid, &mut sid_string) } == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let mut sid_length = 0;
+    while unsafe { *sid_string.add(sid_length) } != 0 {
+        sid_length += 1;
+    }
+    let sid =
+        String::from_utf16_lossy(unsafe { std::slice::from_raw_parts(sid_string, sid_length) });
+    unsafe { LocalFree(sid_string as _) };
+    let sddl: Vec<u16> = format!("O:{sid}D:P(A;OICI;FA;;;{sid})")
+        .encode_utf16()
+        .chain(Some(0))
+        .collect();
+    let mut descriptor = ptr::null_mut();
+    if unsafe {
+        ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            sddl.as_ptr(),
+            /*stringsdrevision*/ 1,
+            &mut descriptor,
+            ptr::null_mut(),
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error());
+    }
+    let result = (|| {
+        // Canonicalize only the parent: this supplies Win32's extended-length
+        // prefix without following a reparse point at the directory being secured.
+        let absolute = std::path::absolute(path)?;
+        let path = match (absolute.parent(), absolute.file_name()) {
+            (Some(parent), Some(name)) => {
+                std::fs::create_dir_all(parent)?;
+                std::fs::canonicalize(parent)?.join(name)
+            }
+            _ => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "private directory must not be a filesystem root",
+                ));
+            }
+        };
+        let path_wide: Vec<u16> = path.as_os_str().encode_wide().chain(Some(0)).collect();
+        let attributes = SECURITY_ATTRIBUTES {
+            nLength: std::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
+            lpSecurityDescriptor: descriptor,
+            bInheritHandle: 0,
+        };
+        if unsafe { CreateDirectoryW(path_wide.as_ptr(), &attributes) } != 0 {
+            return Ok(());
+        }
+        let err = io::Error::last_os_error();
+        if err.kind() != io::ErrorKind::AlreadyExists {
+            return Err(err);
+        }
+        // Changing a DACL cannot revoke handles already held by another user.
+        // Existing directories must already meet our private-directory contract.
+        let _guard = crate::windows_socket_validation::validate_private_directory(&path)?;
+        Ok(())
+    })();
+    unsafe { LocalFree(descriptor as _) };
+    result
+}
+
+// Keep the pointer-aligned buffer alive while using its TOKEN_USER SID.
+pub(super) fn current_user() -> io::Result<Vec<usize>> {
+    // Token information contains pointers, so allocate pointer-aligned storage.
+    let mut token = 0;
+    if unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token) } == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let _token = unsafe { OwnedHandle::from_raw_handle(token as _) };
+    token_user(token)
+}
+
+pub(super) fn token_user(token: HANDLE) -> io::Result<Vec<usize>> {
+    let mut length = 0;
+    unsafe {
+        GetTokenInformation(
+            token,
+            TokenUser,
+            ptr::null_mut(),
+            /*tokeninformationlength*/ 0,
+            &mut length,
+        )
+    };
+    let mut user = vec![0usize; (length as usize).div_ceil(std::mem::size_of::<usize>())];
+    if unsafe {
+        GetTokenInformation(
+            token,
+            TokenUser,
+            user.as_mut_ptr().cast(),
+            length,
+            &mut length,
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error());
+    }
+    Ok(user)
+}
diff --git a/codex-rs/uds/src/windows_socket_validation.rs b/codex-rs/uds/src/windows_socket_validation.rs
new file mode 100644
index 0000000000000000000000000000000000000000..26a955bc280438c35d1a65c5396ffabefb1cd895
--- /dev/null
+++ b/codex-rs/uds/src/windows_socket_validation.rs
@@ -0,0 +1,138 @@
+//! Read-only validation of Windows daemon rendezvous directories. Pin the
+//! validated directory while connecting; never repair an untrusted listener's ACL.
+
+use std::io;
+use std::os::windows::ffi::OsStrExt;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::path::PathBuf;
+use std::ptr;
+
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::ACCESS_ALLOWED_ACE;
+use windows_sys::Win32::Security::ACE_HEADER;
+use windows_sys::Win32::Security::Authorization::GetSecurityInfo;
+use windows_sys::Win32::Security::Authorization::SE_FILE_OBJECT;
+use windows_sys::Win32::Security::CONTAINER_INHERIT_ACE;
+use windows_sys::Win32::Security::DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Security::EqualSid;
+use windows_sys::Win32::Security::GetAce;
+use windows_sys::Win32::Security::GetSecurityDescriptorControl;
+use windows_sys::Win32::Security::OBJECT_INHERIT_ACE;
+use windows_sys::Win32::Security::OWNER_SECURITY_INFORMATION;
+use windows_sys::Win32::Security::SE_DACL_PROTECTED;
+use windows_sys::Win32::Security::TOKEN_USER;
+use windows_sys::Win32::Storage::FileSystem::BY_HANDLE_FILE_INFORMATION;
+use windows_sys::Win32::Storage::FileSystem::CreateFileW;
+use windows_sys::Win32::Storage::FileSystem::FILE_ALL_ACCESS;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_DIRECTORY;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_REPARSE_POINT;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_BACKUP_SEMANTICS;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_OPEN_REPARSE_POINT;
+use windows_sys::Win32::Storage::FileSystem::FILE_LIST_DIRECTORY;
+use windows_sys::Win32::Storage::FileSystem::FILE_READ_ATTRIBUTES;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::Storage::FileSystem::GetFileInformationByHandle;
+use windows_sys::Win32::Storage::FileSystem::OPEN_EXISTING;
+use windows_sys::Win32::Storage::FileSystem::READ_CONTROL;
+use windows_sys::Win32::System::SystemServices::ACCESS_ALLOWED_ACE_TYPE;
+
+/// Validates an existing daemon socket directory without creating or changing it.
+/// Connect using the returned path and retain the handle through connection setup
+/// to prevent replacement of the validated directory. Ancestor junctions are
+/// resolved before validation; the socket directory itself must not be a reparse point.
+pub fn validate_private_socket_path(socket_path: &Path) -> io::Result<(PathBuf, OwnedHandle)> {
+    let absolute = std::path::absolute(socket_path)?;
+    let directory = absolute.parent().ok_or(io::ErrorKind::InvalidInput)?;
+    let socket_name = absolute.file_name().ok_or(io::ErrorKind::InvalidInput)?;
+    let (directory, guard) = validate_private_directory(directory)?;
+    Ok((directory.join(socket_name), guard))
+}
+
+pub(super) fn validate_private_directory(directory: &Path) -> io::Result<(PathBuf, OwnedHandle)> {
+    let parent = directory.parent().ok_or(io::ErrorKind::InvalidInput)?;
+    let directory_name = directory.file_name().ok_or(io::ErrorKind::InvalidInput)?;
+    let directory = std::fs::canonicalize(parent)?.join(directory_name);
+    let path_wide: Vec<u16> = directory.as_os_str().encode_wide().chain(Some(0)).collect();
+    // Metadata-only access does not enforce sharing restrictions on Windows.
+    // Directory listing access makes omission of FILE_SHARE_DELETE pin the path.
+    let handle = unsafe {
+        CreateFileW(
+            path_wide.as_ptr(),
+            READ_CONTROL | FILE_READ_ATTRIBUTES | FILE_LIST_DIRECTORY,
+            FILE_SHARE_READ | FILE_SHARE_WRITE,
+            ptr::null(),
+            OPEN_EXISTING,
+            FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT,
+            /*htemplatefile*/ 0,
+        )
+    };
+    if handle == INVALID_HANDLE_VALUE {
+        return Err(io::Error::last_os_error());
+    }
+    let guard = unsafe { OwnedHandle::from_raw_handle(handle as _) };
+    let mut info: BY_HANDLE_FILE_INFORMATION = unsafe { std::mem::zeroed() };
+    if unsafe { GetFileInformationByHandle(handle, &mut info) } == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    if info.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY == 0
+        || info.dwFileAttributes & FILE_ATTRIBUTE_REPARSE_POINT != 0
+    {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            "untrusted socket directory",
+        ));
+    }
+    let user = crate::windows_security::current_user()?;
+    let user_sid = unsafe { (*(user.as_ptr().cast::<TOKEN_USER>())).User.Sid };
+    let mut owner = ptr::null_mut();
+    let mut dacl = ptr::null_mut();
+    let mut descriptor = ptr::null_mut();
+    let status = unsafe {
+        GetSecurityInfo(
+            handle,
+            SE_FILE_OBJECT,
+            OWNER_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION,
+            &mut owner,
+            ptr::null_mut(),
+            &mut dacl,
+            ptr::null_mut(),
+            &mut descriptor,
+        )
+    };
+    if status != 0 {
+        return Err(io::Error::from_raw_os_error(status as i32));
+    }
+    // Accept exactly the protected, inheritable user-only ACL set at daemon bind.
+    let trusted = unsafe {
+        let mut control = 0;
+        let mut revision = 0;
+        let mut ace = ptr::null_mut();
+        !owner.is_null()
+            && EqualSid(owner, user_sid) != 0
+            && GetSecurityDescriptorControl(descriptor, &mut control, &mut revision) != 0
+            && control & SE_DACL_PROTECTED != 0
+            && !dacl.is_null()
+            && (*dacl).AceCount == 1
+            && GetAce(dacl, /*dwaceindex*/ 0, &mut ace) != 0
+            && (*ace.cast::<ACE_HEADER>()).AceType == ACCESS_ALLOWED_ACE_TYPE as u8
+            && (*ace.cast::<ACE_HEADER>()).AceFlags
+                == (CONTAINER_INHERIT_ACE | OBJECT_INHERIT_ACE) as u8
+            && (*ace.cast::<ACCESS_ALLOWED_ACE>()).Mask == FILE_ALL_ACCESS
+            && EqualSid(
+                ptr::addr_of_mut!((*ace.cast::<ACCESS_ALLOWED_ACE>()).SidStart).cast(),
+                user_sid,
+            ) != 0
+    };
+    unsafe { LocalFree(descriptor as _) };
+    if !trusted {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            "socket directory is not private to the current user",
+        ));
+    }
+    Ok((directory, guard))
+}
diff --git a/codex-rs/v8-poc/src/lib.rs b/codex-rs/v8-poc/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5103cdeb39d5e7f28442c7adaef4969e5a008ea4
--- /dev/null
+++ b/codex-rs/v8-poc/src/lib.rs
@@ -0,0 +1,92 @@
+//! Bazel-wired proof-of-concept crate reserved for future V8 experiments.
+
+/// Returns the Bazel label for this proof-of-concept crate.
+#[must_use]
+pub fn bazel_target() -> &'static str {
+    "//codex-rs/v8-poc:v8-poc"
+}
+
+/// Returns the embedded V8 version.
+#[must_use]
+pub fn embedded_v8_version() -> &'static str {
+    v8::V8::get_version()
+}
+
+/// Returns whether the linked V8 library was built with the in-process sandbox.
+#[must_use]
+pub fn linked_v8_has_sandbox() -> bool {
+    unsafe extern "C" {
+        fn v8__V8__IsSandboxEnabled() -> bool;
+    }
+
+    // `rusty_v8` exposes this symbol for its own sandbox verification tests.
+    unsafe { v8__V8__IsSandboxEnabled() }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use std::sync::Once;
+
+    use super::bazel_target;
+
+    fn initialize_v8() {
+        static INIT: Once = Once::new();
+
+        INIT.call_once(|| {
+            v8::V8::initialize_platform(v8::new_default_platform(0, false).make_shared());
+            v8::V8::initialize();
+        });
+    }
+
+    fn evaluate_expression(expression: &str) -> String {
+        initialize_v8();
+
+        let isolate = &mut v8::Isolate::new(Default::default());
+        v8::scope!(let scope, isolate);
+
+        let context = v8::Context::new(scope, Default::default());
+        let scope = &mut v8::ContextScope::new(scope, context);
+        let source = v8::String::new(scope, expression).expect("expression should be valid UTF-8");
+        let script = v8::Script::compile(scope, source, None).expect("expression should compile");
+        let result = script.run(scope).expect("expression should evaluate");
+
+        result.to_rust_string_lossy(scope)
+    }
+
+    #[test]
+    fn exposes_expected_bazel_target() {
+        assert_eq!(bazel_target(), "//codex-rs/v8-poc:v8-poc");
+    }
+
+    #[test]
+    fn exposes_embedded_v8_version() {
+        assert!(!super::embedded_v8_version().is_empty());
+    }
+
+    #[test]
+    fn sandbox_feature_matches_linked_v8() {
+        assert_eq!(super::linked_v8_has_sandbox(), cfg!(feature = "sandbox"));
+    }
+
+    #[test]
+    fn evaluates_integer_addition() {
+        assert_eq!(evaluate_expression("1 + 2"), "3");
+    }
+
+    #[test]
+    fn evaluates_string_concatenation() {
+        assert_eq!(evaluate_expression("'hello ' + 'world'"), "hello world");
+    }
+
+    #[test]
+    fn parses_crdtp_dispatchable_messages() {
+        let cbor = v8::crdtp::json_to_cbor(br#"{"id":7,"method":"Runtime.evaluate","params":{}}"#)
+            .expect("JSON should convert to CBOR");
+        let dispatchable = v8::crdtp::Dispatchable::new(&cbor);
+
+        assert!(dispatchable.ok());
+        assert_eq!(dispatchable.call_id(), 7);
+        assert_eq!(dispatchable.method(), b"Runtime.evaluate");
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/acl.rs b/codex-rs/windows-sandbox-rs/src/acl.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ace264360d67fad3714452a772b19b068edaf483
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/acl.rs
@@ -0,0 +1,1042 @@
+use crate::winutil::resolve_sid;
+use crate::winutil::sid_bytes_from_string;
+use crate::winutil::to_wide;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::ensure;
+use std::ffi::c_void;
+use std::fs::OpenOptions;
+use std::os::windows::fs::OpenOptionsExt;
+use std::os::windows::io::AsRawHandle;
+use std::path::Path;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::ACCESS_ALLOWED_ACE;
+use windows_sys::Win32::Security::ACCESS_DENIED_ACE;
+use windows_sys::Win32::Security::ACE_HEADER;
+use windows_sys::Win32::Security::ACL;
+use windows_sys::Win32::Security::ACL_SIZE_INFORMATION;
+use windows_sys::Win32::Security::AclSizeInformation;
+use windows_sys::Win32::Security::Authorization::EXPLICIT_ACCESS_W;
+use windows_sys::Win32::Security::Authorization::GetNamedSecurityInfoW;
+use windows_sys::Win32::Security::Authorization::GetSecurityInfo;
+use windows_sys::Win32::Security::Authorization::SetEntriesInAclW;
+use windows_sys::Win32::Security::Authorization::SetNamedSecurityInfoW;
+use windows_sys::Win32::Security::Authorization::SetSecurityInfo;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_SID;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_UNKNOWN;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_W;
+use windows_sys::Win32::Security::DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Security::EqualSid;
+use windows_sys::Win32::Security::GENERIC_MAPPING;
+use windows_sys::Win32::Security::GetAce;
+use windows_sys::Win32::Security::GetAclInformation;
+use windows_sys::Win32::Security::IsValidAcl;
+use windows_sys::Win32::Security::MapGenericMask;
+use windows_sys::Win32::Security::OWNER_SECURITY_INFORMATION;
+use windows_sys::Win32::Storage::FileSystem::CreateFileW;
+use windows_sys::Win32::Storage::FileSystem::DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_ALL_ACCESS;
+use windows_sys::Win32::Storage::FileSystem::FILE_APPEND_DATA;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_NORMAL;
+use windows_sys::Win32::Storage::FileSystem::FILE_DELETE_CHILD;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_BACKUP_SEMANTICS;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_EXECUTE;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_WRITE;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_ATTRIBUTES;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_DATA;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_EA;
+use windows_sys::Win32::Storage::FileSystem::GetFinalPathNameByHandleW;
+use windows_sys::Win32::Storage::FileSystem::OPEN_EXISTING;
+use windows_sys::Win32::Storage::FileSystem::READ_CONTROL;
+use windows_sys::Win32::Storage::FileSystem::VOLUME_NAME_NONE;
+use windows_sys::Win32::Storage::FileSystem::WRITE_DAC;
+use windows_sys::Win32::Storage::FileSystem::WRITE_OWNER;
+const SE_KERNEL_OBJECT: u32 = 6;
+const OBJECT_INHERIT_ACE_FLAG: u8 = 0x01;
+const INHERIT_ONLY_ACE: u8 = 0x08;
+const INHERITED_ACE: u8 = 0x10;
+const ACCESS_ALLOWED_ACE_TYPE: u8 = 0;
+const ACCESS_DENIED_ACE_TYPE: u8 = 1;
+const GENERIC_READ_MASK: u32 = 0x8000_0000;
+const GENERIC_WRITE_MASK: u32 = 0x4000_0000;
+const DENY_ACCESS: i32 = 3;
+// TrustedInstaller is a deterministic service SID, not a machine-local account SID.
+const TRUSTED_INSTALLER_SID: &str =
+    "S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464";
+const STANDARD_USER_MUTATION_MASK: u32 = FILE_WRITE_DATA
+    | FILE_APPEND_DATA
+    | FILE_WRITE_EA
+    | FILE_WRITE_ATTRIBUTES
+    | DELETE
+    | FILE_DELETE_CHILD
+    | WRITE_DAC
+    | WRITE_OWNER;
+
+fn acl_api_result(path: &Path, operation: &str, code: u32) -> Result<()> {
+    if code == ERROR_SUCCESS {
+        Ok(())
+    } else {
+        Err(anyhow!("{operation} failed for {}: {code}", path.display()))
+    }
+}
+
+/// Fetch DACL via handle-based query; caller must LocalFree the returned SD.
+///
+/// # Safety
+/// Caller must free the returned security descriptor with `LocalFree` and pass an existing path.
+pub unsafe fn fetch_dacl_handle(path: &Path) -> Result<(*mut ACL, *mut c_void)> {
+    let wpath = to_wide(path);
+    let h = CreateFileW(
+        wpath.as_ptr(),
+        READ_CONTROL,
+        FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+        std::ptr::null_mut(),
+        OPEN_EXISTING,
+        FILE_FLAG_BACKUP_SEMANTICS,
+        0,
+    );
+    if h == INVALID_HANDLE_VALUE {
+        return Err(anyhow!("CreateFileW failed for {}", path.display()));
+    }
+    let mut p_sd: *mut c_void = std::ptr::null_mut();
+    let mut p_dacl: *mut ACL = std::ptr::null_mut();
+    let code = GetSecurityInfo(
+        h,
+        1, // SE_FILE_OBJECT
+        DACL_SECURITY_INFORMATION,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut p_dacl,
+        std::ptr::null_mut(),
+        &mut p_sd,
+    );
+    CloseHandle(h);
+    if code != ERROR_SUCCESS {
+        return Err(anyhow!(
+            "GetSecurityInfo failed for {}: {}",
+            path.display(),
+            code
+        ));
+    }
+    Ok((p_dacl, p_sd))
+}
+
+/// Fast mask-based check: does an ACE for provided SIDs grant the desired mask? Skips inherit-only.
+/// When `require_all_bits` is true, all bits in `desired_mask` must be present; otherwise any bit suffices.
+pub unsafe fn dacl_mask_allows(
+    p_dacl: *mut ACL,
+    psids: &[*mut c_void],
+    desired_mask: u32,
+    require_all_bits: bool,
+) -> bool {
+    dacl_mask_allows_with_scope(
+        p_dacl,
+        psids,
+        desired_mask,
+        require_all_bits,
+        AceScope::Effective,
+    )
+}
+
+#[derive(Clone, Copy)]
+enum AceScope {
+    Effective,
+    Explicit,
+    EffectiveOrChildFile,
+}
+
+unsafe fn dacl_mask_allows_with_scope(
+    p_dacl: *mut ACL,
+    psids: &[*mut c_void],
+    desired_mask: u32,
+    require_all_bits: bool,
+    scope: AceScope,
+) -> bool {
+    if p_dacl.is_null() {
+        return false;
+    }
+    let mut info: ACL_SIZE_INFORMATION = std::mem::zeroed();
+    let ok = GetAclInformation(
+        p_dacl as *const ACL,
+        &mut info as *mut _ as *mut c_void,
+        std::mem::size_of::<ACL_SIZE_INFORMATION>() as u32,
+        AclSizeInformation,
+    );
+    if ok == 0 {
+        return false;
+    }
+    let mapping = GENERIC_MAPPING {
+        GenericRead: FILE_GENERIC_READ,
+        GenericWrite: FILE_GENERIC_WRITE,
+        GenericExecute: FILE_GENERIC_EXECUTE,
+        GenericAll: FILE_ALL_ACCESS,
+    };
+    for i in 0..(info.AceCount as usize) {
+        let mut p_ace: *mut c_void = std::ptr::null_mut();
+        if GetAce(p_dacl as *const ACL, i as u32, &mut p_ace) == 0 {
+            continue;
+        }
+        let hdr = &*(p_ace as *const ACE_HEADER);
+        if hdr.AceType != ACCESS_ALLOWED_ACE_TYPE {
+            continue; // not ACCESS_ALLOWED
+        }
+        if (hdr.AceFlags & INHERIT_ONLY_ACE) != 0
+            && (!matches!(scope, AceScope::EffectiveOrChildFile)
+                || (hdr.AceFlags & OBJECT_INHERIT_ACE_FLAG) == 0)
+        {
+            continue;
+        }
+        // SET_ACCESS cannot replace an ACE inherited from an ancestor, so it cannot make
+        // an explicit-only repair converge when that inherited ACE contains stale rights.
+        if matches!(scope, AceScope::Explicit) && (hdr.AceFlags & INHERITED_ACE) != 0 {
+            continue;
+        }
+        let base = p_ace as usize;
+        let sid_ptr =
+            (base + std::mem::size_of::<ACE_HEADER>() + std::mem::size_of::<u32>()) as *mut c_void;
+        let mut matched = false;
+        for sid in psids {
+            if EqualSid(sid_ptr, *sid) != 0 {
+                matched = true;
+                break;
+            }
+        }
+        if !matched {
+            continue;
+        }
+        let ace = &*(p_ace as *const ACCESS_ALLOWED_ACE);
+        let mut mask = ace.Mask;
+        MapGenericMask(&mut mask, &mapping);
+        if (require_all_bits && (mask & desired_mask) == desired_mask)
+            || (!require_all_bits && (mask & desired_mask) != 0)
+        {
+            return true;
+        }
+    }
+    false
+}
+
+/// Path-based wrapper around the mask check (single DACL fetch).
+pub fn path_mask_allows(
+    path: &Path,
+    psids: &[*mut c_void],
+    desired_mask: u32,
+    require_all_bits: bool,
+) -> Result<bool> {
+    path_mask_allows_with_scope(
+        path,
+        psids,
+        desired_mask,
+        require_all_bits,
+        AceScope::Effective,
+    )
+}
+
+/// Whether a broad standard-user principal has an allow ACE that can mutate
+/// the path. This is intentionally conservative and does not evaluate deny
+/// ACEs against a concrete token.
+pub fn path_has_standard_user_mutation_allow(path: &Path) -> Result<bool> {
+    path_has_standard_user_mutation_allow_with_scope(path, AceScope::Effective)
+}
+
+/// Whether a broad standard-user principal has an allow ACE that can mutate
+/// the path or a directly inherited child file.
+pub fn path_or_child_file_has_standard_user_mutation_allow(path: &Path) -> Result<bool> {
+    path_has_standard_user_mutation_allow_with_scope(path, AceScope::EffectiveOrChildFile)
+}
+
+fn path_has_standard_user_mutation_allow_with_scope(path: &Path, scope: AceScope) -> Result<bool> {
+    // These canonical labels map to fixed SIDs before any localized account lookup.
+    let mut users = resolve_sid("Users")?;
+    let mut authenticated_users = resolve_sid("Authenticated Users")?;
+    let mut everyone = resolve_sid("Everyone")?;
+    let sids = [
+        users.as_mut_ptr().cast(),
+        authenticated_users.as_mut_ptr().cast(),
+        everyone.as_mut_ptr().cast(),
+    ];
+    unsafe {
+        let (dacl, descriptor) = fetch_dacl_handle(path)?;
+        let result = if dacl.is_null() {
+            Ok(true)
+        } else if IsValidAcl(dacl) == 0 {
+            Err(anyhow!("invalid DACL for {}", path.display()))
+        } else {
+            Ok(dacl_mask_allows_with_scope(
+                dacl,
+                &sids,
+                STANDARD_USER_MUTATION_MASK,
+                /*require_all_bits*/ false,
+                scope,
+            ))
+        };
+        if !descriptor.is_null() {
+            LocalFree(descriptor as HLOCAL);
+        }
+        result
+    }
+}
+
+/// Whether the path owner is one of the conservative administrator-controlled
+/// principals used by the Windows system-config shadow check.
+pub fn path_has_trusted_system_owner(path: &Path) -> Result<bool> {
+    // These canonical labels map to fixed SIDs before any localized account lookup.
+    let mut administrators = resolve_sid("Administrators")?;
+    let mut system = resolve_sid("SYSTEM")?;
+    let mut trusted_installer = sid_bytes_from_string(TRUSTED_INSTALLER_SID)?;
+    let trusted_sids = [
+        administrators.as_mut_ptr().cast(),
+        system.as_mut_ptr().cast(),
+        trusted_installer.as_mut_ptr().cast(),
+    ];
+    path_owner_matches(path, &trusted_sids)
+}
+
+fn path_owner_matches(path: &Path, trusted_sids: &[*mut c_void]) -> Result<bool> {
+    let mut owner = std::ptr::null_mut();
+    let mut descriptor = std::ptr::null_mut();
+    let code = unsafe {
+        GetNamedSecurityInfoW(
+            to_wide(path).as_ptr(),
+            1, // SE_FILE_OBJECT
+            OWNER_SECURITY_INFORMATION,
+            &mut owner,
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            &mut descriptor,
+        )
+    };
+    if code != ERROR_SUCCESS {
+        if !descriptor.is_null() {
+            unsafe { LocalFree(descriptor as HLOCAL) };
+        }
+        return Err(anyhow!(
+            "GetNamedSecurityInfoW failed for {}: {code}",
+            path.display()
+        ));
+    }
+    if owner.is_null() {
+        if !descriptor.is_null() {
+            unsafe { LocalFree(descriptor as HLOCAL) };
+        }
+        return Err(anyhow!("missing owner for {}", path.display()));
+    }
+    let matches = trusted_sids
+        .iter()
+        .any(|trusted_sid| unsafe { EqualSid(owner, *trusted_sid) } != 0);
+    if !descriptor.is_null() {
+        unsafe { LocalFree(descriptor as HLOCAL) };
+    }
+    Ok(matches)
+}
+
+fn path_mask_allows_with_scope(
+    path: &Path,
+    psids: &[*mut c_void],
+    desired_mask: u32,
+    require_all_bits: bool,
+    scope: AceScope,
+) -> Result<bool> {
+    unsafe {
+        let (p_dacl, sd) = fetch_dacl_handle(path)?;
+        let has = dacl_mask_allows_with_scope(p_dacl, psids, desired_mask, require_all_bits, scope);
+        if !sd.is_null() {
+            LocalFree(sd as HLOCAL);
+        }
+        Ok(has)
+    }
+}
+
+pub unsafe fn dacl_has_write_allow_for_sid(p_dacl: *mut ACL, psid: *mut c_void) -> bool {
+    if p_dacl.is_null() {
+        return false;
+    }
+    let mut info: ACL_SIZE_INFORMATION = std::mem::zeroed();
+    let ok = GetAclInformation(
+        p_dacl as *const ACL,
+        &mut info as *mut _ as *mut c_void,
+        std::mem::size_of::<ACL_SIZE_INFORMATION>() as u32,
+        AclSizeInformation,
+    );
+    if ok == 0 {
+        return false;
+    }
+    let count = info.AceCount as usize;
+    for i in 0..count {
+        let mut p_ace: *mut c_void = std::ptr::null_mut();
+        if GetAce(p_dacl as *const ACL, i as u32, &mut p_ace) == 0 {
+            continue;
+        }
+        let hdr = &*(p_ace as *const ACE_HEADER);
+        if hdr.AceType != ACCESS_ALLOWED_ACE_TYPE {
+            continue; // ACCESS_ALLOWED_ACE_TYPE
+        }
+        // Ignore ACEs that are inherit-only (do not apply to the current object)
+        if (hdr.AceFlags & INHERIT_ONLY_ACE) != 0 {
+            continue;
+        }
+        let ace = &*(p_ace as *const ACCESS_ALLOWED_ACE);
+        let mask = ace.Mask;
+        let base = p_ace as usize;
+        let sid_ptr =
+            (base + std::mem::size_of::<ACE_HEADER>() + std::mem::size_of::<u32>()) as *mut c_void;
+        let eq = EqualSid(sid_ptr, psid);
+        if eq != 0 && (mask & FILE_GENERIC_WRITE) != 0 {
+            return true;
+        }
+    }
+    false
+}
+
+pub unsafe fn dacl_has_write_deny_for_sid(p_dacl: *mut ACL, psid: *mut c_void) -> bool {
+    if p_dacl.is_null() {
+        return false;
+    }
+    let mut info: ACL_SIZE_INFORMATION = std::mem::zeroed();
+    let ok = GetAclInformation(
+        p_dacl as *const ACL,
+        &mut info as *mut _ as *mut c_void,
+        std::mem::size_of::<ACL_SIZE_INFORMATION>() as u32,
+        AclSizeInformation,
+    );
+    if ok == 0 {
+        return false;
+    }
+    let deny_write_mask = FILE_GENERIC_WRITE
+        | FILE_WRITE_DATA
+        | FILE_APPEND_DATA
+        | FILE_WRITE_EA
+        | FILE_WRITE_ATTRIBUTES
+        | GENERIC_WRITE_MASK
+        | DELETE
+        | FILE_DELETE_CHILD;
+    for i in 0..info.AceCount {
+        let mut p_ace: *mut c_void = std::ptr::null_mut();
+        if GetAce(p_dacl as *const ACL, i, &mut p_ace) == 0 {
+            continue;
+        }
+        let hdr = &*(p_ace as *const ACE_HEADER);
+        if hdr.AceType != ACCESS_DENIED_ACE_TYPE {
+            continue; // ACCESS_DENIED_ACE_TYPE
+        }
+        if (hdr.AceFlags & INHERIT_ONLY_ACE) != 0 {
+            continue;
+        }
+        let ace = &*(p_ace as *const ACCESS_DENIED_ACE);
+        let base = p_ace as usize;
+        let sid_ptr =
+            (base + std::mem::size_of::<ACE_HEADER>() + std::mem::size_of::<u32>()) as *mut c_void;
+        if EqualSid(sid_ptr, psid) != 0 && (ace.Mask & deny_write_mask) != 0 {
+            return true;
+        }
+    }
+    false
+}
+
+pub unsafe fn dacl_has_read_deny_for_sid(p_dacl: *mut ACL, psid: *mut c_void) -> bool {
+    if p_dacl.is_null() {
+        return false;
+    }
+    let mut info: ACL_SIZE_INFORMATION = std::mem::zeroed();
+    let ok = GetAclInformation(
+        p_dacl as *const ACL,
+        &mut info as *mut _ as *mut c_void,
+        std::mem::size_of::<ACL_SIZE_INFORMATION>() as u32,
+        AclSizeInformation,
+    );
+    if ok == 0 {
+        return false;
+    }
+    let deny_read_mask = FILE_GENERIC_READ | GENERIC_READ_MASK;
+    for i in 0..info.AceCount {
+        let mut p_ace: *mut c_void = std::ptr::null_mut();
+        if GetAce(p_dacl as *const ACL, i, &mut p_ace) == 0 {
+            continue;
+        }
+        let hdr = &*(p_ace as *const ACE_HEADER);
+        if hdr.AceType != ACCESS_DENIED_ACE_TYPE {
+            continue; // ACCESS_DENIED_ACE_TYPE
+        }
+        if (hdr.AceFlags & INHERIT_ONLY_ACE) != 0 {
+            continue;
+        }
+        let ace = &*(p_ace as *const ACCESS_DENIED_ACE);
+        let base = p_ace as usize;
+        let sid_ptr =
+            (base + std::mem::size_of::<ACE_HEADER>() + std::mem::size_of::<u32>()) as *mut c_void;
+        if EqualSid(sid_ptr, psid) != 0 && (ace.Mask & deny_read_mask) != 0 {
+            return true;
+        }
+    }
+    false
+}
+
+// Grant DELETE on each inheriting descendant instead of FILE_DELETE_CHILD on
+// its parent. A parent delete-child grant would bypass a direct deny-write ACE
+// on protected children such as `.git` or an explicit read-only subpath.
+const WRITE_ALLOW_MASK: u32 =
+    FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE;
+
+unsafe fn dacl_allow_mask_needs_refresh(
+    p_dacl: *mut ACL,
+    psid: *mut c_void,
+    allow_mask: u32,
+    disallow_mask: u32,
+) -> bool {
+    !dacl_mask_allows(p_dacl, &[psid], allow_mask, /*require_all_bits*/ true)
+        || dacl_mask_allows_with_scope(
+            p_dacl,
+            &[psid],
+            disallow_mask,
+            /*require_all_bits*/ false,
+            AceScope::Explicit,
+        )
+}
+
+/// Returns whether any provided SID needs its writable-root allow ACE refreshed.
+pub fn path_write_aces_need_refresh(path: &Path, psids: &[*mut c_void]) -> Result<bool> {
+    unsafe {
+        let (p_dacl, p_sd) = fetch_dacl_handle(path)?;
+        let needs_refresh = psids.iter().any(|psid| {
+            dacl_allow_mask_needs_refresh(p_dacl, *psid, WRITE_ALLOW_MASK, FILE_DELETE_CHILD)
+        });
+        if !p_sd.is_null() {
+            LocalFree(p_sd as HLOCAL);
+        }
+        Ok(needs_refresh)
+    }
+}
+
+unsafe fn ensure_allow_mask_aces_with_inheritance_impl(
+    path: &Path,
+    sids: &[*mut c_void],
+    allow_mask: u32,
+    disallow_mask: u32,
+    inheritance: u32,
+) -> Result<bool> {
+    let (p_dacl, p_sd) = fetch_dacl_handle(path)?;
+    let mut entries: Vec<EXPLICIT_ACCESS_W> = Vec::new();
+    for sid in sids {
+        if !dacl_allow_mask_needs_refresh(p_dacl, *sid, allow_mask, disallow_mask) {
+            continue;
+        }
+        entries.push(EXPLICIT_ACCESS_W {
+            grfAccessPermissions: allow_mask,
+            grfAccessMode: 2, // SET_ACCESS
+            grfInheritance: inheritance,
+            Trustee: TRUSTEE_W {
+                pMultipleTrustee: std::ptr::null_mut(),
+                MultipleTrusteeOperation: 0,
+                TrusteeForm: TRUSTEE_IS_SID,
+                TrusteeType: TRUSTEE_IS_UNKNOWN,
+                ptstrName: *sid as *mut u16,
+            },
+        });
+    }
+    let mut added = false;
+    if !entries.is_empty() {
+        let mut p_new_dacl: *mut ACL = std::ptr::null_mut();
+        let code2 = SetEntriesInAclW(
+            entries.len() as u32,
+            entries.as_ptr(),
+            p_dacl,
+            &mut p_new_dacl,
+        );
+        if code2 == ERROR_SUCCESS {
+            let code3 = SetNamedSecurityInfoW(
+                to_wide(path).as_ptr() as *mut u16,
+                1,
+                DACL_SECURITY_INFORMATION,
+                std::ptr::null_mut(),
+                std::ptr::null_mut(),
+                p_new_dacl,
+                std::ptr::null_mut(),
+            );
+            if code3 == ERROR_SUCCESS {
+                added = true;
+                if !p_new_dacl.is_null() {
+                    LocalFree(p_new_dacl as HLOCAL);
+                }
+            } else {
+                if !p_new_dacl.is_null() {
+                    LocalFree(p_new_dacl as HLOCAL);
+                }
+                if !p_sd.is_null() {
+                    LocalFree(p_sd as HLOCAL);
+                }
+                return Err(anyhow!("SetNamedSecurityInfoW failed: {code3}"));
+            }
+        } else {
+            if !p_sd.is_null() {
+                LocalFree(p_sd as HLOCAL);
+            }
+            return Err(anyhow!("SetEntriesInAclW failed: {code2}"));
+        }
+    }
+    if !p_sd.is_null() {
+        LocalFree(p_sd as HLOCAL);
+    }
+    Ok(added)
+}
+
+/// Ensure all provided SIDs have an allow ACE with the requested mask on the path.
+/// Returns true if any ACE was added.
+///
+/// # Safety
+/// Caller must pass valid SID pointers and an existing path; free the returned security descriptor with `LocalFree`.
+pub unsafe fn ensure_allow_mask_aces_with_inheritance(
+    path: &Path,
+    sids: &[*mut c_void],
+    allow_mask: u32,
+    inheritance: u32,
+) -> Result<bool> {
+    ensure_allow_mask_aces_with_inheritance_impl(
+        path,
+        sids,
+        allow_mask,
+        /*disallow_mask*/ 0,
+        inheritance,
+    )
+}
+
+/// Ensure all provided SIDs have an allow ACE with the requested mask on the path.
+/// Returns true if any ACE was added.
+///
+/// # Safety
+/// Caller must pass valid SID pointers and an existing path; free the returned security descriptor with `LocalFree`.
+pub unsafe fn ensure_allow_mask_aces(
+    path: &Path,
+    sids: &[*mut c_void],
+    allow_mask: u32,
+) -> Result<bool> {
+    ensure_allow_mask_aces_with_inheritance(
+        path,
+        sids,
+        allow_mask,
+        CONTAINER_INHERIT_ACE | OBJECT_INHERIT_ACE,
+    )
+}
+
+/// Ensure all provided SIDs have a write-capable allow ACE on the path.
+/// Returns true if any ACE was added.
+///
+/// # Safety
+/// Caller must pass valid SID pointers and an existing path; free the returned security descriptor with `LocalFree`.
+pub unsafe fn ensure_allow_write_aces(path: &Path, sids: &[*mut c_void]) -> Result<bool> {
+    ensure_allow_mask_aces_with_inheritance_impl(
+        path,
+        sids,
+        WRITE_ALLOW_MASK,
+        FILE_DELETE_CHILD,
+        CONTAINER_INHERIT_ACE | OBJECT_INHERIT_ACE,
+    )
+}
+
+/// Adds an allow ACE granting read/write/execute to the given SID on the target path.
+///
+/// # Safety
+/// Caller must ensure `psid` points to a valid SID and `path` refers to an existing file or directory.
+pub unsafe fn add_allow_ace(path: &Path, psid: *mut c_void) -> Result<bool> {
+    let mut p_sd: *mut c_void = std::ptr::null_mut();
+    let mut p_dacl: *mut ACL = std::ptr::null_mut();
+    let code = GetNamedSecurityInfoW(
+        to_wide(path).as_ptr(),
+        1,
+        DACL_SECURITY_INFORMATION,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut p_dacl,
+        std::ptr::null_mut(),
+        &mut p_sd,
+    );
+    if code != ERROR_SUCCESS {
+        return Err(anyhow!("GetNamedSecurityInfoW failed: {code}"));
+    }
+    // Already has write? Skip costly DACL rewrite.
+    if dacl_has_write_allow_for_sid(p_dacl, psid) {
+        if !p_sd.is_null() {
+            LocalFree(p_sd as HLOCAL);
+        }
+        return Ok(false);
+    }
+    let mut added = false;
+    // Always ensure write is present: if an allow ACE exists without write, add one with write+RX.
+    let trustee = TRUSTEE_W {
+        pMultipleTrustee: std::ptr::null_mut(),
+        MultipleTrusteeOperation: 0,
+        TrusteeForm: TRUSTEE_IS_SID,
+        TrusteeType: TRUSTEE_IS_UNKNOWN,
+        ptstrName: psid as *mut u16,
+    };
+    let mut explicit: EXPLICIT_ACCESS_W = std::mem::zeroed();
+    explicit.grfAccessPermissions = FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE;
+    explicit.grfAccessMode = 2; // SET_ACCESS
+    explicit.grfInheritance = CONTAINER_INHERIT_ACE | OBJECT_INHERIT_ACE;
+    explicit.Trustee = trustee;
+    let mut p_new_dacl: *mut ACL = std::ptr::null_mut();
+    let code2 = SetEntriesInAclW(1, &explicit, p_dacl, &mut p_new_dacl);
+    if code2 == ERROR_SUCCESS {
+        let code3 = SetNamedSecurityInfoW(
+            to_wide(path).as_ptr() as *mut u16,
+            1,
+            DACL_SECURITY_INFORMATION,
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            p_new_dacl,
+            std::ptr::null_mut(),
+        );
+        if code3 == ERROR_SUCCESS {
+            added = !dacl_has_write_allow_for_sid(p_dacl, psid);
+        }
+        if !p_new_dacl.is_null() {
+            LocalFree(p_new_dacl as HLOCAL);
+        }
+    }
+    if !p_sd.is_null() {
+        LocalFree(p_sd as HLOCAL);
+    }
+    Ok(added)
+}
+
+/// Adds a deny ACE to prevent write/append/delete for the given SID on the target path.
+///
+/// # Safety
+/// Caller must ensure `psid` points to a valid SID and `path` refers to an existing file or directory.
+pub unsafe fn add_deny_write_ace(path: &Path, psid: *mut c_void) -> Result<bool> {
+    add_deny_ace(path, psid, DenyAceKind::Write)
+}
+
+#[derive(Clone, Copy)]
+enum DenyAceKind {
+    Read,
+    Write,
+}
+
+impl DenyAceKind {
+    fn mask(self) -> u32 {
+        match self {
+            Self::Read => FILE_GENERIC_READ | GENERIC_READ_MASK,
+            Self::Write => {
+                FILE_GENERIC_WRITE
+                    | FILE_WRITE_DATA
+                    | FILE_APPEND_DATA
+                    | FILE_WRITE_EA
+                    | FILE_WRITE_ATTRIBUTES
+                    | GENERIC_WRITE_MASK
+                    | DELETE
+                    | FILE_DELETE_CHILD
+            }
+        }
+    }
+
+    unsafe fn already_present(self, p_dacl: *mut ACL, psid: *mut c_void) -> bool {
+        match self {
+            Self::Read => dacl_has_read_deny_for_sid(p_dacl, psid),
+            Self::Write => dacl_has_write_deny_for_sid(p_dacl, psid),
+        }
+    }
+}
+
+unsafe fn deny_ace_already_present(
+    handle: &std::fs::File,
+    path: &Path,
+    psid: *mut c_void,
+    kind: DenyAceKind,
+) -> Result<bool> {
+    let (mut p_dacl, mut p_sd) = (std::ptr::null_mut(), std::ptr::null_mut());
+    let code = GetSecurityInfo(
+        handle.as_raw_handle() as _,
+        1,
+        DACL_SECURITY_INFORMATION,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut p_dacl,
+        std::ptr::null_mut(),
+        &mut p_sd,
+    );
+    let result =
+        acl_api_result(path, "GetSecurityInfo", code).map(|()| kind.already_present(p_dacl, psid));
+    if !p_sd.is_null() {
+        LocalFree(p_sd as HLOCAL);
+    }
+    result
+}
+
+unsafe fn add_deny_ace(path: &Path, psid: *mut c_void, kind: DenyAceKind) -> Result<bool> {
+    let handle = match OpenOptions::new()
+        .access_mode(READ_CONTROL | WRITE_DAC)
+        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS)
+        .open(path)
+    {
+        Ok(handle) => handle,
+        Err(write_error) => {
+            let read_handle = OpenOptions::new()
+                .access_mode(READ_CONTROL)
+                .custom_flags(FILE_FLAG_BACKUP_SEMANTICS)
+                .open(path)
+                .with_context(|| format!("open deny ACL target {}", path.display()))?;
+            if matches!(kind, DenyAceKind::Read) {
+                ensure_handle_is_not_filesystem_root(&read_handle, path)?;
+            }
+            if deny_ace_already_present(&read_handle, path, psid, kind)? {
+                return Ok(false);
+            }
+            return Err(write_error).context("open deny ACL target for update");
+        }
+    };
+    if matches!(kind, DenyAceKind::Read) {
+        ensure_handle_is_not_filesystem_root(&handle, path)?;
+    }
+    let mut p_sd: *mut c_void = std::ptr::null_mut();
+    let mut p_dacl: *mut ACL = std::ptr::null_mut();
+    let code = GetSecurityInfo(
+        handle.as_raw_handle() as _,
+        1,
+        DACL_SECURITY_INFORMATION,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut p_dacl,
+        std::ptr::null_mut(),
+        &mut p_sd,
+    );
+    if code != ERROR_SUCCESS {
+        if !p_sd.is_null() {
+            LocalFree(p_sd as HLOCAL);
+        }
+        return Err(anyhow!(
+            "GetSecurityInfo failed for {}: {code}",
+            path.display()
+        ));
+    }
+    let result = if kind.already_present(p_dacl, psid) {
+        Ok(false)
+    } else {
+        let trustee = TRUSTEE_W {
+            pMultipleTrustee: std::ptr::null_mut(),
+            MultipleTrusteeOperation: 0,
+            TrusteeForm: TRUSTEE_IS_SID,
+            TrusteeType: TRUSTEE_IS_UNKNOWN,
+            ptstrName: psid as *mut u16,
+        };
+        let mut explicit: EXPLICIT_ACCESS_W = std::mem::zeroed();
+        explicit.grfAccessPermissions = kind.mask();
+        explicit.grfAccessMode = DENY_ACCESS;
+        explicit.grfInheritance = CONTAINER_INHERIT_ACE | OBJECT_INHERIT_ACE;
+        explicit.Trustee = trustee;
+        let mut p_new_dacl: *mut ACL = std::ptr::null_mut();
+        let code2 = SetEntriesInAclW(1, &explicit, p_dacl, &mut p_new_dacl);
+        let result = if let Err(err) = acl_api_result(path, "SetEntriesInAclW", code2) {
+            Err(err)
+        } else {
+            let code3 = SetSecurityInfo(
+                handle.as_raw_handle() as _,
+                1,
+                DACL_SECURITY_INFORMATION,
+                std::ptr::null_mut(),
+                std::ptr::null_mut(),
+                p_new_dacl,
+                std::ptr::null_mut(),
+            );
+            acl_api_result(path, "SetSecurityInfo", code3).map(|()| true)
+        };
+        if !p_new_dacl.is_null() {
+            LocalFree(p_new_dacl as HLOCAL);
+        }
+        result
+    };
+    if !p_sd.is_null() {
+        LocalFree(p_sd as HLOCAL);
+    }
+    result
+}
+
+fn ensure_handle_is_not_filesystem_root(handle: &std::fs::File, path: &Path) -> Result<()> {
+    let mut buffer = [0_u16; 2];
+    let length = unsafe {
+        GetFinalPathNameByHandleW(
+            handle.as_raw_handle() as _,
+            buffer.as_mut_ptr(),
+            buffer.len() as u32,
+            VOLUME_NAME_NONE,
+        )
+    };
+    if length == 0 {
+        return Err(std::io::Error::last_os_error())
+            .with_context(|| format!("resolve deny-read ACL target {}", path.display()));
+    }
+    ensure!(
+        length != 1 || buffer[0] != b'\\' as u16,
+        "refusing to apply a deny-read ACE to filesystem root {}",
+        path.display()
+    );
+    Ok(())
+}
+
+/// Adds a deny ACE to prevent reads for the given SID on the target path.
+///
+/// `SetEntriesInAclW` places newly-created deny ACEs before allow ACEs, which
+/// keeps the resulting DACL in the order Windows expects for denies to win.
+/// The ACE is inheritable so a deny applied to a materialized directory also
+/// covers files and directories later created underneath it.
+///
+/// # Safety
+/// Caller must ensure `psid` points to a valid SID and `path` refers to an existing file or directory.
+pub unsafe fn add_deny_read_ace(path: &Path, psid: *mut c_void) -> Result<bool> {
+    add_deny_ace(path, psid, DenyAceKind::Read)
+}
+
+#[cfg(test)]
+#[path = "acl_tests.rs"]
+mod tests;
+
+/// Removes explicit ACEs for one SID and propagates the updated inherited ACL.
+///
+/// # Safety
+/// Caller must pass a valid SID pointer and have authority to edit the target DACL.
+pub unsafe fn revoke_ace(path: &Path, psid: *mut c_void) -> Result<()> {
+    let mut p_sd: *mut c_void = std::ptr::null_mut();
+    let mut p_dacl: *mut ACL = std::ptr::null_mut();
+    let code = GetNamedSecurityInfoW(
+        to_wide(path).as_ptr(),
+        1,
+        DACL_SECURITY_INFORMATION,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut p_dacl,
+        std::ptr::null_mut(),
+        &mut p_sd,
+    );
+    if code != ERROR_SUCCESS {
+        if !p_sd.is_null() {
+            LocalFree(p_sd as HLOCAL);
+        }
+        return acl_api_result(path, "GetNamedSecurityInfoW", code);
+    }
+    if p_dacl.is_null() {
+        // A null DACL has no ACE to revoke; replacing it with an empty ACL would deny access.
+        if !p_sd.is_null() {
+            LocalFree(p_sd as HLOCAL);
+        }
+        return Ok(());
+    }
+    let trustee = TRUSTEE_W {
+        pMultipleTrustee: std::ptr::null_mut(),
+        MultipleTrusteeOperation: 0,
+        TrusteeForm: TRUSTEE_IS_SID,
+        TrusteeType: TRUSTEE_IS_UNKNOWN,
+        ptstrName: psid as *mut u16,
+    };
+    let mut explicit: EXPLICIT_ACCESS_W = std::mem::zeroed();
+    explicit.grfAccessPermissions = 0;
+    explicit.grfAccessMode = 4; // REVOKE_ACCESS
+    explicit.grfInheritance = CONTAINER_INHERIT_ACE | OBJECT_INHERIT_ACE;
+    explicit.Trustee = trustee;
+    let mut p_new_dacl: *mut ACL = std::ptr::null_mut();
+    let result = acl_api_result(
+        path,
+        "SetEntriesInAclW",
+        SetEntriesInAclW(1, &explicit, p_dacl, &mut p_new_dacl),
+    )
+    .and_then(|()| {
+        // REVOKE_ACCESS only removes ACEs. An unchanged ACL must not propagate inheritance.
+        if (*p_new_dacl).AceCount == (*p_dacl).AceCount {
+            return Ok(());
+        }
+        let code = SetNamedSecurityInfoW(
+            to_wide(path).as_ptr() as *mut u16,
+            1,
+            DACL_SECURITY_INFORMATION,
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            p_new_dacl,
+            std::ptr::null_mut(),
+        );
+        acl_api_result(path, "SetNamedSecurityInfoW", code)
+    });
+    if !p_new_dacl.is_null() {
+        LocalFree(p_new_dacl as HLOCAL);
+    }
+    if !p_sd.is_null() {
+        LocalFree(p_sd as HLOCAL);
+    }
+    result
+}
+
+/// Grants RX to the null device for the given SID to support stdout/stderr redirection.
+///
+/// # Safety
+/// Caller must ensure `psid` is a valid SID pointer.
+pub unsafe fn allow_null_device(psid: *mut c_void) {
+    let desired = 0x00020000 | 0x00040000; // READ_CONTROL | WRITE_DAC
+    let h = CreateFileW(
+        to_wide(r"\\\\.\\NUL").as_ptr(),
+        desired,
+        FILE_SHARE_READ | FILE_SHARE_WRITE,
+        std::ptr::null_mut(),
+        OPEN_EXISTING,
+        FILE_ATTRIBUTE_NORMAL,
+        0,
+    );
+    if h == 0 || h == INVALID_HANDLE_VALUE {
+        return;
+    }
+    let mut p_sd: *mut c_void = std::ptr::null_mut();
+    let mut p_dacl: *mut ACL = std::ptr::null_mut();
+    let code = GetSecurityInfo(
+        h,
+        SE_KERNEL_OBJECT as i32,
+        DACL_SECURITY_INFORMATION,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut p_dacl,
+        std::ptr::null_mut(),
+        &mut p_sd,
+    );
+    if code == ERROR_SUCCESS {
+        let trustee = TRUSTEE_W {
+            pMultipleTrustee: std::ptr::null_mut(),
+            MultipleTrusteeOperation: 0,
+            TrusteeForm: TRUSTEE_IS_SID,
+            TrusteeType: TRUSTEE_IS_UNKNOWN,
+            ptstrName: psid as *mut u16,
+        };
+        let mut explicit: EXPLICIT_ACCESS_W = std::mem::zeroed();
+        explicit.grfAccessPermissions =
+            FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE;
+        explicit.grfAccessMode = 2; // SET_ACCESS
+        explicit.grfInheritance = 0;
+        explicit.Trustee = trustee;
+        let mut p_new_dacl: *mut ACL = std::ptr::null_mut();
+        let code2 = SetEntriesInAclW(1, &explicit, p_dacl, &mut p_new_dacl);
+        if code2 == ERROR_SUCCESS {
+            let _ = SetSecurityInfo(
+                h,
+                SE_KERNEL_OBJECT as i32,
+                DACL_SECURITY_INFORMATION,
+                std::ptr::null_mut(),
+                std::ptr::null_mut(),
+                p_new_dacl,
+                std::ptr::null_mut(),
+            );
+            if !p_new_dacl.is_null() {
+                LocalFree(p_new_dacl as HLOCAL);
+            }
+        }
+    }
+    if !p_sd.is_null() {
+        LocalFree(p_sd as HLOCAL);
+    }
+    CloseHandle(h);
+}
+const CONTAINER_INHERIT_ACE: u32 = 0x2;
+const OBJECT_INHERIT_ACE: u32 = 0x1;
diff --git a/codex-rs/windows-sandbox-rs/src/acl_tests.rs b/codex-rs/windows-sandbox-rs/src/acl_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4a1cd62444e0471f52189aeaa6d652de7f89c7db
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/acl_tests.rs
@@ -0,0 +1,112 @@
+use super::acl_api_result;
+use super::deny_ace_already_present;
+use super::ensure_handle_is_not_filesystem_root;
+use crate::token::LocalSid;
+use pretty_assertions::assert_eq;
+use std::fs::OpenOptions;
+use std::os::windows::fs::OpenOptionsExt;
+use windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::Authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW;
+use windows_sys::Win32::Security::Authorization::SDDL_REVISION_1;
+use windows_sys::Win32::Security::DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Security::GetSecurityDescriptorControl;
+use windows_sys::Win32::Security::SE_DACL_PROTECTED;
+use windows_sys::Win32::Security::SetFileSecurityW;
+use windows_sys::Win32::Security::UNPROTECTED_DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_BACKUP_SEMANTICS;
+use windows_sys::Win32::Storage::FileSystem::READ_CONTROL;
+
+#[test]
+fn deny_ace_update_failure_is_an_error() {
+    let path = std::path::Path::new(r"C:\world-writable");
+    let error = acl_api_result(path, "SetNamedSecurityInfoW", ERROR_ACCESS_DENIED)
+        .expect_err("access denied must not look like an already-present ACE");
+
+    assert_eq!(
+        error.to_string(),
+        r"SetNamedSecurityInfoW failed for C:\world-writable: 5"
+    );
+}
+
+#[test]
+fn deny_read_root_check_uses_the_open_handle() {
+    let cwd = std::env::current_dir().expect("current directory");
+    let root = cwd.ancestors().last().expect("filesystem root");
+    let root_directory = OpenOptions::new()
+        .access_mode(READ_CONTROL)
+        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS)
+        .open(root)
+        .expect("open filesystem root");
+    let diagnostic_path = std::path::Path::new(r"C:\not-a-root");
+
+    let error = ensure_handle_is_not_filesystem_root(&root_directory, diagnostic_path)
+        .expect_err("classification must follow the root handle, not the diagnostic path");
+
+    assert_eq!(
+        error.to_string(),
+        r"refusing to apply a deny-read ACE to filesystem root C:\not-a-root"
+    );
+}
+
+#[test]
+fn existing_deny_ace_is_visible_without_write_dac() {
+    let target = tempfile::NamedTempFile::new().expect("temporary file");
+    let sid = LocalSid::from_string("S-1-5-21-10-20-30-40").expect("test SID");
+    let path = target.path();
+    let psid = sid.as_ptr();
+    assert!(unsafe { super::add_deny_read_ace(path, psid) }.expect("add deny ACE"));
+    let already_present =
+        unsafe { deny_ace_already_present(target.as_file(), path, psid, super::DenyAceKind::Read) }
+            .expect("read existing deny ACE");
+    assert!(already_present);
+}
+
+#[test]
+fn revoking_absent_sid_preserves_child_null_dacl() {
+    let parent = tempfile::tempdir().expect("parent directory");
+    let child = parent.path().join("child");
+    std::fs::create_dir(&child).expect("child directory");
+    let sid = LocalSid::from_string("S-1-5-21-10-20-30-40").expect("absent SID");
+    let other_sid = LocalSid::from_string("S-1-5-21-10-20-30-41").expect("inherited SID");
+
+    unsafe {
+        super::add_allow_ace(parent.path(), other_sid.as_ptr()).expect("inheritable parent ACE");
+        let mut descriptor = std::ptr::null_mut();
+        assert_ne!(
+            ConvertStringSecurityDescriptorToSecurityDescriptorW(
+                crate::winutil::to_wide("D:NO_ACCESS_CONTROL").as_ptr(),
+                SDDL_REVISION_1,
+                &mut descriptor,
+                std::ptr::null_mut(),
+            ),
+            0,
+        );
+        // The legacy setter preserves a null DACL without applying automatic inheritance.
+        let set = SetFileSecurityW(
+            crate::winutil::to_wide(&child).as_ptr(),
+            DACL_SECURITY_INFORMATION | UNPROTECTED_DACL_SECURITY_INFORMATION,
+            descriptor,
+        );
+        LocalFree(descriptor as HLOCAL);
+        assert_ne!(set, 0, "set an unprotected null DACL");
+        for revoke in [false, true] {
+            if revoke {
+                super::revoke_ace(parent.path(), sid.as_ptr()).expect("revoke absent SID");
+            }
+            let (dacl, descriptor) = super::fetch_dacl_handle(&child).expect("child permissions");
+            let mut control = 0;
+            let mut revision = 0;
+            let valid = GetSecurityDescriptorControl(descriptor, &mut control, &mut revision);
+            LocalFree(descriptor as HLOCAL);
+
+            assert_ne!(valid, 0, "read child inheritance flags");
+            assert_eq!(control & SE_DACL_PROTECTED, 0, "child permits inheritance");
+            assert!(
+                dacl.is_null(),
+                "revocation must preserve the child's null DACL"
+            );
+        }
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/allow.rs b/codex-rs/windows-sandbox-rs/src/allow.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5a10261d0c5e82f5987df16c86680d68e7a6d705
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/allow.rs
@@ -0,0 +1,380 @@
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use dunce::canonicalize;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::path::Path;
+use std::path::PathBuf;
+
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct AllowDenyPaths {
+    pub allow: HashSet<PathBuf>,
+    pub deny: HashSet<PathBuf>,
+}
+
+pub(crate) fn compute_allow_paths_for_permissions(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+) -> AllowDenyPaths {
+    let mut allow: HashSet<PathBuf> = HashSet::new();
+    let mut deny: HashSet<PathBuf> = HashSet::new();
+
+    let mut add_allow_path = |p: PathBuf| {
+        if p.exists() {
+            allow.insert(p);
+        }
+    };
+    let mut add_deny_path = |p: PathBuf| {
+        if p.exists() {
+            deny.insert(p);
+        }
+    };
+
+    for writable_root in permissions.writable_roots_for_cwd(command_cwd, env_map) {
+        let canonical = canonicalize(&writable_root.root).unwrap_or(writable_root.root);
+        add_allow_path(canonical);
+        for read_only_subpath in writable_root.read_only_subpaths {
+            add_deny_path(read_only_subpath);
+        }
+    }
+
+    AllowDenyPaths { allow, deny }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_protocol::models::PermissionProfile;
+    use codex_protocol::permissions::NetworkSandboxPolicy;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use std::fs;
+    use tempfile::TempDir;
+
+    fn workspace_write_profile(
+        writable_roots: &[AbsolutePathBuf],
+        exclude_tmpdir_env_var: bool,
+        exclude_slash_tmp: bool,
+    ) -> PermissionProfile {
+        PermissionProfile::workspace_write_with(
+            writable_roots,
+            NetworkSandboxPolicy::Restricted,
+            exclude_tmpdir_env_var,
+            exclude_slash_tmp,
+        )
+    }
+
+    fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf> {
+        vec![AbsolutePathBuf::from_absolute_path(root).expect("absolute workspace root")]
+    }
+
+    fn compute_allow_paths(
+        permission_profile: &PermissionProfile,
+        workspace_roots: &[AbsolutePathBuf],
+        command_cwd: &Path,
+        env_map: &HashMap<String, String>,
+    ) -> AllowDenyPaths {
+        let permissions =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                permission_profile,
+                workspace_roots,
+            )
+            .expect("managed permission profile");
+        compute_allow_paths_for_permissions(&permissions, command_cwd, env_map)
+    }
+
+    #[test]
+    fn includes_additional_writable_roots() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let extra_root = tmp.path().join("extra");
+        let _ = fs::create_dir_all(&command_cwd);
+        let _ = fs::create_dir_all(&extra_root);
+
+        let writable_roots = vec![AbsolutePathBuf::try_from(extra_root.as_path()).unwrap()];
+        let permission_profile = workspace_write_profile(
+            &writable_roots,
+            /*exclude_tmpdir_env_var*/ false,
+            /*exclude_slash_tmp*/ false,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+
+        assert!(
+            paths
+                .allow
+                .contains(&dunce::canonicalize(&command_cwd).unwrap())
+        );
+        assert!(
+            paths
+                .allow
+                .contains(&dunce::canonicalize(&extra_root).unwrap())
+        );
+        assert!(paths.deny.is_empty(), "no deny paths expected");
+    }
+
+    #[test]
+    fn uses_runtime_workspace_roots_for_workspace_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let workspace_root = tmp.path().join("workspace");
+        let command_cwd = workspace_root.join("subdir");
+        fs::create_dir_all(&command_cwd).expect("create command cwd");
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(workspace_root.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+
+        assert!(
+            paths
+                .allow
+                .contains(&dunce::canonicalize(&workspace_root).unwrap())
+        );
+        assert!(
+            !paths
+                .allow
+                .contains(&dunce::canonicalize(&command_cwd).unwrap())
+        );
+        assert!(paths.deny.is_empty(), "no deny paths expected");
+    }
+
+    #[test]
+    fn excludes_tmp_env_vars_when_requested() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let temp_dir = tmp.path().join("temp");
+        let _ = fs::create_dir_all(&command_cwd);
+        let _ = fs::create_dir_all(&temp_dir);
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ false,
+        );
+        let mut env_map = HashMap::new();
+        env_map.insert("TEMP".into(), temp_dir.to_string_lossy().to_string());
+        env_map.insert("TMP".into(), temp_dir.to_string_lossy().to_string());
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &env_map,
+        );
+
+        assert!(
+            paths
+                .allow
+                .contains(&dunce::canonicalize(&command_cwd).unwrap())
+        );
+        assert!(
+            !paths
+                .allow
+                .contains(&dunce::canonicalize(&temp_dir).unwrap())
+        );
+        assert!(paths.deny.is_empty(), "no deny paths expected");
+    }
+
+    #[test]
+    fn includes_tmp_env_vars_when_requested() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let temp_dir = tmp.path().join("temp");
+        let _ = fs::create_dir_all(&command_cwd);
+        let _ = fs::create_dir_all(&temp_dir);
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ false,
+            /*exclude_slash_tmp*/ false,
+        );
+        let mut env_map = HashMap::new();
+        env_map.insert("TEMP".into(), temp_dir.to_string_lossy().to_string());
+        env_map.insert("TMP".into(), temp_dir.to_string_lossy().to_string());
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &env_map,
+        );
+
+        let expected_allow: HashSet<PathBuf> = [
+            dunce::canonicalize(&command_cwd).unwrap(),
+            dunce::canonicalize(&temp_dir).unwrap(),
+        ]
+        .into_iter()
+        .collect();
+
+        assert_eq!(expected_allow, paths.allow);
+        assert!(paths.deny.is_empty(), "no deny paths expected");
+    }
+
+    #[test]
+    fn ignores_unix_slash_tmp_for_windows_allow_roots() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let _ = fs::create_dir_all(&command_cwd);
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ false,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+        let expected_allow: HashSet<PathBuf> = [dunce::canonicalize(&command_cwd).unwrap()]
+            .into_iter()
+            .collect();
+
+        assert_eq!(expected_allow, paths.allow);
+        assert!(paths.deny.is_empty(), "no deny paths expected");
+    }
+
+    #[test]
+    fn denies_git_dir_inside_writable_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let git_dir = command_cwd.join(".git");
+        let _ = fs::create_dir_all(&git_dir);
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ false,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+        let expected_allow: HashSet<PathBuf> = [dunce::canonicalize(&command_cwd).unwrap()]
+            .into_iter()
+            .collect();
+        let expected_deny: HashSet<PathBuf> = [dunce::canonicalize(&git_dir).unwrap()]
+            .into_iter()
+            .collect();
+
+        assert_eq!(expected_allow, paths.allow);
+        assert_eq!(expected_deny, paths.deny);
+    }
+
+    #[test]
+    fn denies_git_file_inside_writable_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let git_file = command_cwd.join(".git");
+        let _ = fs::create_dir_all(&command_cwd);
+        let _ = fs::write(&git_file, "gitdir: .git/worktrees/example");
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ false,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+        let expected_allow: HashSet<PathBuf> = [dunce::canonicalize(&command_cwd).unwrap()]
+            .into_iter()
+            .collect();
+        let expected_deny: HashSet<PathBuf> = [dunce::canonicalize(&git_file).unwrap()]
+            .into_iter()
+            .collect();
+
+        assert_eq!(expected_allow, paths.allow);
+        assert_eq!(expected_deny, paths.deny);
+    }
+
+    #[test]
+    fn denies_codex_and_agents_inside_writable_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let codex_dir = command_cwd.join(".codex");
+        let agents_dir = command_cwd.join(".agents");
+        let _ = fs::create_dir_all(&codex_dir);
+        let _ = fs::create_dir_all(&agents_dir);
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ false,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+        let expected_allow: HashSet<PathBuf> = [dunce::canonicalize(&command_cwd).unwrap()]
+            .into_iter()
+            .collect();
+        let expected_deny: HashSet<PathBuf> = [
+            dunce::canonicalize(&codex_dir).unwrap(),
+            dunce::canonicalize(&agents_dir).unwrap(),
+        ]
+        .into_iter()
+        .collect();
+
+        assert_eq!(expected_allow, paths.allow);
+        assert_eq!(expected_deny, paths.deny);
+    }
+
+    #[test]
+    fn skips_protected_subdirs_when_missing() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let _ = fs::create_dir_all(&command_cwd);
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ false,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        let paths = compute_allow_paths(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &command_cwd,
+            &HashMap::new(),
+        );
+        assert_eq!(paths.allow.len(), 1);
+        assert!(
+            paths.deny.is_empty(),
+            "no deny when protected dirs are absent"
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/app_package.rs b/codex-rs/windows-sandbox-rs/src/app_package.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3e4d5d09d3d8d47b3b1aba27f46f229187671e77
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/app_package.rs
@@ -0,0 +1,243 @@
+//! Select the requested runtime without inferring authority from directory or manifest text.
+//! Registered runners still require OS package identity and the exact staged runner image.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use anyhow::ensure;
+use std::ffi::OsStr;
+use std::ffi::OsString;
+use std::os::windows::ffi::OsStringExt;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::OnceLock;
+use windows_sys::Win32::Foundation::APPMODEL_ERROR_NO_PACKAGE;
+use windows_sys::Win32::Foundation::ERROR_INSUFFICIENT_BUFFER;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_ACCOUNTDISABLE;
+use windows_sys::Win32::Storage::Packaging::Appx::GetPackageFullName;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::QueryFullProcessImageNameW;
+
+#[link(name = "kernel32")]
+unsafe extern "system" {
+    fn GetStagedPackagePathByFullName(
+        package_full_name: *const u16,
+        path_length: *mut u32,
+        path: *mut u16,
+    ) -> i32;
+}
+
+/// Capture the startup request once; this flag never authorizes a package or process.
+pub fn registered_core_requested() -> bool {
+    static REQUESTED: OnceLock<bool> = OnceLock::new();
+    *REQUESTED.get_or_init(|| {
+        requested_value(std::env::var_os("CODEX_WINDOWS_REGISTERED_CORE").as_deref())
+    })
+}
+
+fn requested_value(value: Option<&OsStr>) -> bool {
+    value == Some(OsStr::new("1"))
+}
+
+fn current_package_full_name() -> Result<Option<String>> {
+    process_package_name(unsafe { GetCurrentProcess() })
+}
+
+fn process_package_name(process: HANDLE) -> Result<Option<String>> {
+    query_package_name(
+        |length, buffer| unsafe { GetPackageFullName(process, length, buffer) },
+        /*max_length*/ 32768,
+    )
+}
+
+pub(crate) fn query_package_name(
+    mut query: impl FnMut(*mut u32, *mut u16) -> u32,
+    max_length: u32,
+) -> Result<Option<String>> {
+    let mut length = 0;
+    let status = query(&mut length, std::ptr::null_mut());
+    if status == APPMODEL_ERROR_NO_PACKAGE {
+        return Ok(None);
+    }
+    ensure!(
+        status == ERROR_INSUFFICIENT_BUFFER && length > 1 && length <= max_length,
+        "package name query failed: {status}"
+    );
+    let mut family = vec![0u16; length as usize];
+    let status = query(&mut length, family.as_mut_ptr());
+    ensure!(
+        status == ERROR_SUCCESS && length > 1 && length as usize <= family.len(),
+        "package name read failed: {status}"
+    );
+    let family = family[..length as usize]
+        .strip_suffix(&[0])
+        .context("unterminated package name")?;
+    ensure!(!family.contains(&0), "invalid package name");
+    Ok(Some(String::from_utf16(family)?))
+}
+
+/// Only an OS-verified packaged runner may propagate package context to sandbox children.
+pub(crate) fn current_process_is_registered_core_runner() -> Result<bool> {
+    let executable = std::env::current_exe().context("resolve current Core runner image")?;
+    if !executable
+        .file_name()
+        .is_some_and(|name| name.eq_ignore_ascii_case("codex-command-runner.exe"))
+    {
+        return Ok(false);
+    }
+    let process = unsafe { GetCurrentProcess() };
+    if process_package_name(process)?.is_none() {
+        ensure!(
+            !registered_core_requested(),
+            "registered Core runner has no package identity"
+        );
+        return Ok(false);
+    }
+    verify_registered_core_runner(process, &executable)?;
+    Ok(true)
+}
+
+fn staged_package_root(name: &[u16]) -> Result<PathBuf> {
+    let mut staged = vec![0u16; 32768];
+    let mut length = staged.len() as u32;
+    let status =
+        unsafe { GetStagedPackagePathByFullName(name.as_ptr(), &mut length, staged.as_mut_ptr()) };
+    ensure!(
+        status == 0 && length > 1 && length as usize <= staged.len(),
+        "registered Core staged package query failed: {status}"
+    );
+    let staged = &staged[..length as usize];
+    ensure!(
+        staged.last() == Some(&0) && !staged[..staged.len() - 1].contains(&0),
+        "invalid registered Core staged package path"
+    );
+    dunce::canonicalize(OsString::from_wide(&staged[..staged.len() - 1]))
+        .context("resolve OS-staged package root")
+}
+
+pub(crate) fn verify_registered_core_runner(process: HANDLE, expected_runner: &Path) -> Result<()> {
+    let name =
+        process_package_name(process)?.context("registered Core runner has no package identity")?;
+    let staged = staged_package_root(&crate::winutil::to_wide(name))?;
+    let expected =
+        dunce::canonicalize(expected_runner).context("resolve registered Core runner")?;
+    ensure!(
+        expected.as_os_str().eq_ignore_ascii_case(
+            staged
+                .join("app")
+                .join("resources")
+                .join("codex-command-runner.exe")
+                .as_os_str()
+        ),
+        "registered alias selected a different package identity"
+    );
+    let mut image = vec![0u16; 32768];
+    let mut length = image.len() as u32;
+    if unsafe { QueryFullProcessImageNameW(process, 0, image.as_mut_ptr(), &mut length) } == 0 {
+        return Err(std::io::Error::last_os_error())
+            .context("inspect registered Core runner image");
+    }
+    ensure!(
+        length > 0 && length as usize <= image.len(),
+        "invalid registered Core image length"
+    );
+    let image = dunce::canonicalize(OsString::from_wide(&image[..length as usize]))?;
+    ensure!(
+        image.as_os_str().eq_ignore_ascii_case(expected.as_os_str()),
+        "registered alias selected a different runner image"
+    );
+    Ok(())
+}
+
+/// Checks the service's committed receipt without provisioning or mutating either account.
+pub(crate) fn registered_setup_is_ready(codex_home: &Path) -> Result<bool> {
+    for account in [
+        crate::setup::OFFLINE_USERNAME,
+        crate::setup::ONLINE_USERNAME,
+    ] {
+        if crate::winutil::local_user_flags(account)?
+            .is_none_or(|flags| flags & UF_ACCOUNTDISABLE != 0)
+        {
+            return Ok(false);
+        }
+    }
+    let Some(package) = current_package_full_name()? else {
+        return Ok(false);
+    };
+    let Some(record) = crate::runtime_ownership::load_installation()? else {
+        return Ok(false);
+    };
+    Ok(record.codex_home == codex_home.canonicalize()?
+        && record.runtime()?.ready_for_package(&package))
+}
+
+/// A startup hint only; the service rechecks ownership and readiness under its setup lock.
+#[doc(hidden)]
+pub fn registered_core_needs_refresh(codex_home: &Path) -> Result<bool> {
+    let Some(package) = current_package_full_name()? else {
+        return Ok(false);
+    };
+    let Some(record) = crate::runtime_ownership::load_installation()? else {
+        return Ok(false);
+    };
+    let runtime = record.runtime()?;
+    Ok(record.codex_home == codex_home.canonicalize()?
+        && runtime
+            .ready_package
+            .as_deref()
+            .is_some_and(|ready| ready != package && runtime.ready_for_package(ready)))
+}
+
+/// Consume the service's setup receipt; launching a command never installs a package.
+pub(crate) fn registered_runner_alias(
+    codex_home: &Path,
+    sandbox_username: &str,
+) -> anyhow::Result<PathBuf> {
+    let account = if sandbox_username.eq_ignore_ascii_case(crate::setup::OFFLINE_USERNAME) {
+        crate::SandboxRuntimeAccount::Offline
+    } else if sandbox_username.eq_ignore_ascii_case(crate::setup::ONLINE_USERNAME) {
+        crate::SandboxRuntimeAccount::Online
+    } else {
+        bail!("app runtime registration requires a managed sandbox account");
+    };
+    let record = crate::runtime_ownership::load_installation()?
+        .context("registered Core setup has not completed")?;
+    let package =
+        current_package_full_name()?.context("registered Core launch requires an installed app")?;
+    let owner = crate::winutil::resolve_sid(&crate::runtime_ownership::current_setup_user()?)?;
+    anyhow::ensure!(
+        record.user_sid
+            == crate::winutil::string_from_sid_bytes(&owner).map_err(anyhow::Error::msg)?
+            && record.codex_home == codex_home.canonicalize()?
+            && record.runtime()?.ready_for_package(&package),
+        "registered Core setup belongs to another owner or is being removed"
+    );
+    let entry = record
+        .runtime()?
+        .accounts
+        .iter()
+        .find(|entry| entry.account == account)
+        .context("managed account registration is not ready; retry setup")?;
+    let sid = crate::winutil::resolve_sid(sandbox_username)?;
+    anyhow::ensure!(
+        entry.user_sid
+            == crate::winutil::string_from_sid_bytes(&sid).map_err(anyhow::Error::msg)?,
+        "managed runtime account changed; retry setup"
+    );
+    let path = entry
+        .alias_path
+        .as_ref()
+        .context("registered Core alias is not ready; retry setup")?;
+    anyhow::ensure!(
+        path.is_absolute()
+            && path.file_name() == Some(std::ffi::OsStr::new(crate::APP_CORE_RUNNER_ALIAS)),
+        "registered Core setup contains an invalid alias"
+    );
+    Ok(path.clone())
+}
+
+#[cfg(test)]
+#[path = "app_package_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/app_package_tests.rs b/codex-rs/windows-sandbox-rs/src/app_package_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..015acffcf88c0f0df1cf98d72d0b58f8f1f6da28
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/app_package_tests.rs
@@ -0,0 +1,98 @@
+//! Runtime opt-in and bounded OS package-name results, without installed-state changes.
+
+use super::query_package_name;
+use super::requested_value;
+use pretty_assertions::assert_eq;
+use std::ffi::OsStr;
+use std::ffi::OsString;
+use std::os::windows::ffi::OsStringExt;
+use windows_sys::Win32::Foundation::APPMODEL_ERROR_NO_PACKAGE;
+use windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED;
+use windows_sys::Win32::Foundation::ERROR_INSUFFICIENT_BUFFER;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+
+#[test]
+fn only_exact_opt_in_requests_registered_core() {
+    let values = [
+        None,
+        Some(""),
+        Some("0"),
+        Some("1"),
+        Some("true"),
+        Some(" 1"),
+        Some("1 "),
+    ];
+    assert_eq!(
+        values.map(|value| requested_value(value.map(OsStr::new))),
+        [false, false, false, true, false, false, false]
+    );
+    assert!(!requested_value(Some(&OsString::from_wide(&[0xd800]))));
+}
+
+#[test]
+fn package_query_distinguishes_absence_from_failure_and_bounds_allocation() {
+    assert_eq!(
+        query_package_name(|_, _| APPMODEL_ERROR_NO_PACKAGE, /*max_length*/ 256).unwrap(),
+        None
+    );
+    assert!(query_package_name(|_, _| ERROR_ACCESS_DENIED, /*max_length*/ 256).is_err());
+    for max_length in [256, 32768] {
+        assert!(
+            query_package_name(
+                |length, buffer| {
+                    assert!(buffer.is_null());
+                    unsafe { *length = max_length + 1 };
+                    ERROR_INSUFFICIENT_BUFFER
+                },
+                max_length
+            )
+            .is_err()
+        );
+    }
+}
+
+#[test]
+fn package_query_validates_returned_length_termination_and_utf16() {
+    for (value, returned, expected) in [
+        (vec![65, 0], 2, Some("A")),
+        (vec![65, 0], 0, None),
+        (vec![65, 0], 3, None),
+        (vec![65, 66], 2, None),
+        (vec![65, 0, 66, 0], 4, None),
+        (vec![0xd800, 0], 2, None),
+    ] {
+        let actual = query_package_name(
+            |length, buffer| {
+                if buffer.is_null() {
+                    unsafe { *length = value.len() as u32 };
+                    ERROR_INSUFFICIENT_BUFFER
+                } else {
+                    unsafe {
+                        std::ptr::copy_nonoverlapping(value.as_ptr(), buffer, value.len());
+                        *length = returned;
+                    }
+                    ERROR_SUCCESS
+                }
+            },
+            /*max_length*/ 256,
+        );
+        match expected {
+            Some(name) => assert_eq!(actual.unwrap(), Some(name.to_owned())),
+            None => assert!(actual.is_err()),
+        }
+    }
+    assert!(
+        query_package_name(
+            |length, buffer| {
+                unsafe { *length = 2 };
+                if buffer.is_null() {
+                    ERROR_INSUFFICIENT_BUFFER
+                } else {
+                    ERROR_ACCESS_DENIED
+                }
+            },
+            /*max_length*/ 256
+        )
+        .is_err()
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/audit.rs b/codex-rs/windows-sandbox-rs/src/audit.rs
new file mode 100644
index 0000000000000000000000000000000000000000..5a9fb5a3a9ae4ea9016cf0df4760a9e6f2797bf2
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/audit.rs
@@ -0,0 +1,404 @@
+use crate::acl::add_deny_write_ace;
+use crate::acl::path_mask_allows;
+use crate::cap::cap_sid_file;
+use crate::cap::load_or_create_cap_sids;
+use crate::cap::workspace_write_cap_sid_for_root;
+use crate::cap::workspace_write_root_contains_path;
+use crate::logging::debug_log;
+use crate::logging::log_note;
+use crate::path_normalization::canonical_path_key;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::setup::effective_write_roots_for_permissions;
+use crate::token::LocalSid;
+use crate::token::world_sid;
+use anyhow::Result;
+use anyhow::anyhow;
+use std::collections::HashSet;
+use std::ffi::OsStr;
+use std::ffi::c_void;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+use std::time::Instant;
+use windows_sys::Win32::Storage::FileSystem::FILE_APPEND_DATA;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_ATTRIBUTES;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_DATA;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_EA;
+
+// Preflight scan limits
+const MAX_ITEMS_PER_DIR: i32 = 1000;
+const AUDIT_TIME_LIMIT_SECS: i64 = 2;
+const MAX_CHECKED_LIMIT: i32 = 50000;
+// Case-insensitive suffixes (normalized to forward slashes) to skip during one-level child scan
+const SKIP_DIR_SUFFIXES: &[&str] = &[
+    "/windows/installer",
+    "/windows/registration",
+    "/programdata",
+];
+
+fn unique_push(set: &mut HashSet<PathBuf>, out: &mut Vec<PathBuf>, p: PathBuf) {
+    if let Ok(abs) = p.canonicalize()
+        && set.insert(abs.clone())
+    {
+        out.push(abs);
+    }
+}
+
+fn gather_candidates(cwd: &Path, env: &std::collections::HashMap<String, String>) -> Vec<PathBuf> {
+    let mut set: HashSet<PathBuf> = HashSet::new();
+    let mut out: Vec<PathBuf> = Vec::new();
+    // 1) CWD first (so immediate children get scanned early)
+    unique_push(&mut set, &mut out, cwd.to_path_buf());
+    // 2) TEMP/TMP next (often small, quick to scan)
+    for k in ["TEMP", "TMP"] {
+        if let Some(v) = env.get(k).cloned().or_else(|| std::env::var(k).ok()) {
+            unique_push(&mut set, &mut out, PathBuf::from(v));
+        }
+    }
+    // 3) User roots
+    if let Some(up) = std::env::var_os("USERPROFILE") {
+        unique_push(&mut set, &mut out, PathBuf::from(up));
+    }
+    if let Some(pubp) = std::env::var_os("PUBLIC") {
+        unique_push(&mut set, &mut out, PathBuf::from(pubp));
+    }
+    // 4) PATH entries (best-effort)
+    if let Some(path) = env
+        .get("PATH")
+        .cloned()
+        .or_else(|| std::env::var("PATH").ok())
+    {
+        for part in std::env::split_paths(OsStr::new(&path)) {
+            if !part.as_os_str().is_empty() {
+                unique_push(&mut set, &mut out, part);
+            }
+        }
+    }
+    // 5) Core system roots last
+    for p in [PathBuf::from("C:/"), PathBuf::from("C:/Windows")] {
+        unique_push(&mut set, &mut out, p);
+    }
+    out
+}
+
+unsafe fn path_has_world_write_allow(path: &Path) -> Result<bool> {
+    let mut world = world_sid()?;
+    let psid_world = world.as_mut_ptr() as *mut c_void;
+    let write_mask = FILE_WRITE_DATA | FILE_APPEND_DATA | FILE_WRITE_EA | FILE_WRITE_ATTRIBUTES;
+    path_mask_allows(
+        path,
+        &[psid_world],
+        write_mask,
+        /*require_all_bits*/ false,
+    )
+}
+
+pub fn audit_everyone_writable(
+    cwd: &Path,
+    env: &std::collections::HashMap<String, String>,
+    logs_base_dir: Option<&Path>,
+) -> Result<Vec<PathBuf>> {
+    let start = Instant::now();
+    let mut flagged: Vec<PathBuf> = Vec::new();
+    let mut seen: HashSet<String> = HashSet::new();
+    let mut checked = 0usize;
+    let check_world_writable = |path: &Path| -> bool {
+        match unsafe { path_has_world_write_allow(path) } {
+            Ok(has) => has,
+            Err(err) => {
+                debug_log(
+                    &format!(
+                        "AUDIT: treating unreadable ACL as not world-writable: {} ({err})",
+                        path.display()
+                    ),
+                    logs_base_dir,
+                );
+                false
+            }
+        }
+    };
+    // Fast path: check CWD immediate children first so workspace issues are caught early.
+    if let Ok(read) = std::fs::read_dir(cwd) {
+        for ent in read.flatten().take(MAX_ITEMS_PER_DIR as usize) {
+            if start.elapsed() > Duration::from_secs(AUDIT_TIME_LIMIT_SECS as u64)
+                || checked > MAX_CHECKED_LIMIT as usize
+            {
+                break;
+            }
+            let ft = match ent.file_type() {
+                Ok(ft) => ft,
+                Err(_) => continue,
+            };
+            if ft.is_symlink() || !ft.is_dir() {
+                continue;
+            }
+            let p = ent.path();
+            checked += 1;
+            let has = check_world_writable(&p);
+            if has {
+                let key = canonical_path_key(&p);
+                if seen.insert(key) {
+                    flagged.push(p);
+                }
+            }
+        }
+    }
+    // Continue with broader candidate sweep
+    let candidates = gather_candidates(cwd, env);
+    for root in candidates {
+        if start.elapsed() > Duration::from_secs(AUDIT_TIME_LIMIT_SECS as u64)
+            || checked > MAX_CHECKED_LIMIT as usize
+        {
+            break;
+        }
+        checked += 1;
+        let has_root = check_world_writable(&root);
+        if has_root {
+            let key = canonical_path_key(&root);
+            if seen.insert(key) {
+                flagged.push(root.clone());
+            }
+        }
+        // one level down best-effort
+        if let Ok(read) = std::fs::read_dir(&root) {
+            for ent in read.flatten().take(MAX_ITEMS_PER_DIR as usize) {
+                let p = ent.path();
+                if start.elapsed() > Duration::from_secs(AUDIT_TIME_LIMIT_SECS as u64)
+                    || checked > MAX_CHECKED_LIMIT as usize
+                {
+                    break;
+                }
+                // Skip reparse points (symlinks/junctions) to avoid auditing link ACLs
+                let ft = match ent.file_type() {
+                    Ok(ft) => ft,
+                    Err(_) => continue,
+                };
+                if ft.is_symlink() {
+                    continue;
+                }
+                // Skip noisy/irrelevant Windows system subdirectories
+                let pl = p.to_string_lossy().to_ascii_lowercase();
+                let norm = pl.replace('\\', "/");
+                if SKIP_DIR_SUFFIXES.iter().any(|s| norm.ends_with(s)) {
+                    continue;
+                }
+                if ft.is_dir() {
+                    checked += 1;
+                    let has_child = check_world_writable(&p);
+                    if has_child {
+                        let key = canonical_path_key(&p);
+                        if seen.insert(key) {
+                            flagged.push(p);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    let elapsed_ms = start.elapsed().as_millis();
+    if !flagged.is_empty() {
+        let mut list = String::new();
+        for p in &flagged {
+            list.push_str(&format!("\n - {}", p.display()));
+        }
+        crate::logging::log_note(
+            &format!(
+                "AUDIT: world-writable scan FAILED; cwd={cwd:?}; checked={checked}; duration_ms={elapsed_ms}; flagged:{list}",
+            ),
+            logs_base_dir,
+        );
+
+        return Ok(flagged);
+    }
+    // Log success once if nothing flagged
+    crate::logging::log_note(
+        &format!("AUDIT: world-writable scan OK; checked={checked}; duration_ms={elapsed_ms}"),
+        logs_base_dir,
+    );
+    Ok(Vec::new())
+}
+
+pub fn apply_world_writable_scan_and_denies_for_permissions(
+    codex_home: &Path,
+    cwd: &Path,
+    env_map: &std::collections::HashMap<String, String>,
+    permissions: &ResolvedWindowsSandboxPermissions,
+    logs_base_dir: Option<&Path>,
+) -> Result<usize> {
+    let flagged = audit_everyone_writable(cwd, env_map, logs_base_dir)?;
+    if flagged.is_empty() {
+        return Ok(0);
+    }
+    let flagged_count = flagged.len();
+    let result = apply_capability_denies_for_world_writable_for_permissions(
+        codex_home,
+        &flagged,
+        permissions,
+        cwd,
+        env_map,
+        logs_base_dir,
+    );
+    if let Err(err) = &result {
+        log_note(
+            &format!("AUDIT: failed to apply capability deny ACEs: {err}"),
+            logs_base_dir,
+        );
+    }
+    result.map(|()| flagged_count)
+}
+
+fn apply_capability_denies_for_world_writable_for_permissions(
+    codex_home: &Path,
+    flagged: &[PathBuf],
+    permissions: &ResolvedWindowsSandboxPermissions,
+    cwd: &Path,
+    env_map: &std::collections::HashMap<String, String>,
+    logs_base_dir: Option<&Path>,
+) -> Result<()> {
+    if flagged.is_empty() {
+        return Ok(());
+    }
+    std::fs::create_dir_all(codex_home)?;
+    let cap_path = cap_sid_file(codex_home);
+    let caps = load_or_create_cap_sids(codex_home)?;
+    std::fs::write(&cap_path, serde_json::to_string(&caps)?)?;
+    if permissions
+        .validate_elevated_filesystem_policy(cwd)
+        .is_err()
+    {
+        return Ok(());
+    }
+    let (active_sids, workspace_roots): (Vec<LocalSid>, Vec<PathBuf>) =
+        if permissions.uses_write_capabilities_for_cwd(cwd, env_map) {
+            let roots = effective_write_roots_for_permissions(
+                permissions,
+                cwd,
+                env_map,
+                codex_home,
+                /*write_roots_override*/ None,
+            );
+            let active_sids = roots
+                .iter()
+                .map(|root| {
+                    workspace_write_cap_sid_for_root(codex_home, cwd, root)
+                        .and_then(|sid| LocalSid::from_string(&sid))
+                })
+                .collect::<Result<Vec<_>>>()?;
+            (active_sids, roots)
+        } else {
+            (vec![LocalSid::from_string(&caps.readonly)?], Vec::new())
+        };
+    apply_capability_denies_to_paths(
+        flagged,
+        &workspace_roots,
+        &active_sids,
+        logs_base_dir,
+        |path, sid| unsafe { add_deny_write_ace(path, sid) },
+    )
+}
+
+fn apply_capability_denies_to_paths(
+    flagged: &[PathBuf],
+    workspace_roots: &[PathBuf],
+    active_sids: &[LocalSid],
+    logs_base_dir: Option<&Path>,
+    mut apply_deny: impl FnMut(&Path, *mut c_void) -> Result<bool>,
+) -> Result<()> {
+    let mut errors = Vec::new();
+    for path in flagged {
+        if workspace_roots
+            .iter()
+            .any(|root| workspace_write_root_contains_path(root, path))
+        {
+            continue;
+        }
+        for active_sid in active_sids {
+            match apply_deny(path, active_sid.as_ptr()) {
+                Ok(true) => log_note(
+                    &format!("AUDIT: applied capability deny ACE to {}", path.display()),
+                    logs_base_dir,
+                ),
+                Ok(false) => {}
+                Err(err) => {
+                    let error = format!(
+                        "AUDIT: failed to apply capability deny ACE to {}: {}",
+                        path.display(),
+                        err
+                    );
+                    log_note(&error, logs_base_dir);
+                    errors.push(error);
+                }
+            }
+        }
+    }
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(anyhow!(errors.join("; ")))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::apply_capability_denies_to_paths;
+    use super::gather_candidates;
+    use crate::token::LocalSid;
+    use anyhow::anyhow;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashMap;
+    use std::fs;
+
+    #[test]
+    fn gathers_path_entries_by_list_separator() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let dir_a = tmp.path().join("Tools");
+        let dir_b = tmp.path().join("Bin");
+        let dir_space = tmp.path().join("Program Files");
+        fs::create_dir_all(&dir_a).expect("dir a");
+        fs::create_dir_all(&dir_b).expect("dir b");
+        fs::create_dir_all(&dir_space).expect("dir space");
+
+        let mut env_map = HashMap::new();
+        env_map.insert(
+            "PATH".to_string(),
+            format!(
+                "{};{};{}",
+                dir_a.display(),
+                dir_b.display(),
+                dir_space.display()
+            ),
+        );
+
+        let candidates = gather_candidates(tmp.path(), &env_map);
+        let canon_a = dir_a.canonicalize().expect("canon a");
+        let canon_b = dir_b.canonicalize().expect("canon b");
+        let canon_space = dir_space.canonicalize().expect("canon space");
+
+        assert!(candidates.contains(&canon_a));
+        assert!(candidates.contains(&canon_b));
+        assert!(candidates.contains(&canon_space));
+    }
+
+    #[test]
+    fn deny_ace_failure_is_propagated_after_other_paths_are_attempted() {
+        let failed_path = std::path::PathBuf::from(r"C:\failed");
+        let successful_path = std::path::PathBuf::from(r"C:\protected");
+        let flagged = vec![failed_path.clone(), successful_path];
+        let active_sids = vec![LocalSid::from_string("S-1-1-0").expect("world SID")];
+        let mut attempted = Vec::new();
+
+        let error =
+            apply_capability_denies_to_paths(&flagged, &[], &active_sids, None, |path, _sid| {
+                attempted.push(path.to_path_buf());
+                if path == failed_path {
+                    Err(anyhow!("access denied"))
+                } else {
+                    Ok(true)
+                }
+            })
+            .expect_err("a failed deny ACE must fail preflight");
+
+        assert_eq!(attempted, flagged);
+        assert!(error.to_string().contains(r"C:\failed"));
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/bin/command_runner/main.rs b/codex-rs/windows-sandbox-rs/src/bin/command_runner/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1e3c88b4436595940983984e30935cf84ee95cc8
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/bin/command_runner/main.rs
@@ -0,0 +1,14 @@
+#![cfg_attr(all(target_os = "windows", not(test)), windows_subsystem = "windows")]
+
+#[cfg(target_os = "windows")]
+mod win;
+
+#[cfg(target_os = "windows")]
+fn main() -> anyhow::Result<()> {
+    win::main()
+}
+
+#[cfg(not(target_os = "windows"))]
+fn main() {
+    panic!("codex-command-runner is Windows-only");
+}
diff --git a/codex-rs/windows-sandbox-rs/src/bin/command_runner/win.rs b/codex-rs/windows-sandbox-rs/src/bin/command_runner/win.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b380aa0af9dabddc8d5f4aa774baf53b934d0ee4
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/bin/command_runner/win.rs
@@ -0,0 +1,730 @@
+//! Windows command runner used by the **elevated** sandbox path.
+//!
+//! The CLI launches this binary under the sandbox user when Windows sandbox level is
+//! Elevated. It connects to the IPC pipes, reads the framed `SpawnRequest`, derives a
+//! restricted token from the sandbox user, and spawns the child process via ConPTY
+//! (`tty=true`) or pipes (`tty=false`). It then streams output frames back to the parent,
+//! accepts stdin/terminate frames, and emits a final exit frame. The legacy restricted‑token
+//! path spawns the child directly and does not use this runner.
+
+#![allow(unsafe_op_in_unsafe_fn)]
+
+mod cwd_junction;
+#[cfg(test)]
+#[path = "win/input_loop_tests.rs"]
+mod input_loop_tests;
+
+use anyhow::Context;
+use anyhow::Result;
+use codex_utils_pty::JobObject;
+use codex_windows_sandbox::ConsoleMode;
+use codex_windows_sandbox::ErrorPayload;
+use codex_windows_sandbox::ErrorStage;
+use codex_windows_sandbox::ExitPayload;
+use codex_windows_sandbox::FramedMessage;
+use codex_windows_sandbox::IPC_PROTOCOL_VERSION;
+use codex_windows_sandbox::LaunchDesktop;
+use codex_windows_sandbox::LocalSid;
+use codex_windows_sandbox::Message;
+use codex_windows_sandbox::OutputPayload;
+use codex_windows_sandbox::OutputStream;
+use codex_windows_sandbox::PipeSpawnHandles;
+use codex_windows_sandbox::ResizePayload;
+use codex_windows_sandbox::SpawnReady;
+use codex_windows_sandbox::SpawnRequest;
+use codex_windows_sandbox::StderrMode;
+use codex_windows_sandbox::StdinMode;
+use codex_windows_sandbox::WindowsSandboxTokenMode;
+use codex_windows_sandbox::allow_null_device;
+use codex_windows_sandbox::create_readonly_token_with_caps_and_user_from;
+use codex_windows_sandbox::create_workspace_write_token_with_caps_and_user_from;
+use codex_windows_sandbox::decode_bytes;
+use codex_windows_sandbox::encode_bytes;
+use codex_windows_sandbox::get_current_token_for_restriction;
+use codex_windows_sandbox::hide_current_user_profile_dir;
+use codex_windows_sandbox::log_note;
+use codex_windows_sandbox::read_frame;
+use codex_windows_sandbox::read_handle_loop;
+use codex_windows_sandbox::spawn_process_with_pipes;
+use codex_windows_sandbox::to_wide;
+use codex_windows_sandbox::token_mode_for_permission_profile;
+use codex_windows_sandbox::write_frame;
+use std::ffi::OsStr;
+use std::fs::File;
+use std::os::windows::io::FromRawHandle;
+use std::path::Path;
+use std::path::PathBuf;
+use std::ptr;
+use std::sync::Arc;
+use std::sync::Mutex as StdMutex;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Storage::FileSystem::CreateFileW;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_WRITE;
+use windows_sys::Win32::Storage::FileSystem::OPEN_EXISTING;
+use windows_sys::Win32::System::Console::COORD;
+use windows_sys::Win32::System::Console::ResizePseudoConsole;
+use windows_sys::Win32::System::Threading::GetExitCodeProcess;
+use windows_sys::Win32::System::Threading::GetProcessId;
+use windows_sys::Win32::System::Threading::INFINITE;
+use windows_sys::Win32::System::Threading::MUTEX_ALL_ACCESS;
+use windows_sys::Win32::System::Threading::OpenMutexW;
+use windows_sys::Win32::System::Threading::PROCESS_INFORMATION;
+use windows_sys::Win32::System::Threading::TerminateProcess;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+const READ_ACL_MUTEX_NAME: &str = "Local\\CodexSandboxReadAcl";
+const TERMINATION_WAIT_MS: u32 = 5_000;
+const WAIT_TIMEOUT: u32 = 0x0000_0102;
+
+struct IpcSpawnedProcess {
+    log_dir: PathBuf,
+    pi: PROCESS_INFORMATION,
+    job: Arc<JobObject>,
+    stdout_handle: HANDLE,
+    stderr_handle: HANDLE,
+    stdin_handle: Option<HANDLE>,
+    conpty_owner: Option<codex_windows_sandbox::ConptyInstance>,
+    hpc_handle: Option<HANDLE>,
+    _pipe_handles: Option<PipeSpawnHandles>,
+}
+
+/// Small RAII wrapper for raw Win32 handles.
+///
+/// The elevated runner has a few early-return paths where we acquire a token, job, or pipe
+/// handle and then may fail while preparing the child. Keeping those handles in a guard makes
+/// the error paths read more directly and closes the gaps that were previously leaking them.
+struct OwnedWinHandle(HANDLE);
+
+impl OwnedWinHandle {
+    fn new(handle: HANDLE) -> Self {
+        Self(handle)
+    }
+
+    fn raw(&self) -> HANDLE {
+        self.0
+    }
+
+    fn into_raw(mut self) -> HANDLE {
+        // Transfer ownership to the caller. After this point the caller is responsible for
+        // eventually closing the returned HANDLE.
+        let handle = self.0;
+        self.0 = 0;
+        handle
+    }
+}
+
+impl Drop for OwnedWinHandle {
+    fn drop(&mut self) {
+        if self.0 != 0 && self.0 != INVALID_HANDLE_VALUE {
+            unsafe {
+                CloseHandle(self.0);
+            }
+        }
+    }
+}
+
+/// Open a named pipe created by the parent process.
+fn open_pipe(name: &str, access: u32) -> Result<HANDLE> {
+    let path = to_wide(name);
+    let handle = unsafe {
+        CreateFileW(
+            path.as_ptr(),
+            access,
+            0,
+            std::ptr::null_mut(),
+            OPEN_EXISTING,
+            0,
+            0,
+        )
+    };
+    if handle == windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE {
+        let err = unsafe { GetLastError() };
+        return Err(anyhow::anyhow!("CreateFileW failed for pipe {name}: {err}"));
+    }
+    Ok(handle)
+}
+
+/// Send an error frame back to the parent process.
+fn send_error(
+    writer: &Arc<StdMutex<File>>,
+    stage: ErrorStage,
+    windows_error_code: Option<u32>,
+    message: String,
+) -> Result<()> {
+    let msg = FramedMessage {
+        version: IPC_PROTOCOL_VERSION,
+        message: Message::Error {
+            payload: ErrorPayload {
+                message,
+                stage,
+                windows_error_code,
+            },
+        },
+    };
+    if let Ok(mut guard) = writer.lock() {
+        write_frame(&mut *guard, &msg)?;
+    }
+    Ok(())
+}
+
+fn windows_error_code(err: &anyhow::Error) -> Option<u32> {
+    err.chain().find_map(|cause| {
+        cause
+            .downcast_ref::<std::io::Error>()
+            .and_then(std::io::Error::raw_os_error)
+            .and_then(|code| u32::try_from(code).ok())
+    })
+}
+
+/// Read and validate the initial spawn request frame.
+fn read_spawn_request(reader: &mut File) -> Result<SpawnRequest> {
+    let Some(msg) = read_frame(reader)? else {
+        anyhow::bail!("runner: pipe closed before spawn_request");
+    };
+    if msg.version != IPC_PROTOCOL_VERSION {
+        anyhow::bail!("runner: unsupported protocol version {}", msg.version);
+    }
+    match msg.message {
+        Message::SpawnRequest { payload } => Ok(*payload),
+        other => anyhow::bail!("runner: expected spawn_request, got {other:?}"),
+    }
+}
+
+fn read_acl_mutex_exists() -> Result<bool> {
+    let name = to_wide(OsStr::new(READ_ACL_MUTEX_NAME));
+    let handle = unsafe { OpenMutexW(MUTEX_ALL_ACCESS, 0, name.as_ptr()) };
+    if handle == 0 {
+        let err = unsafe { GetLastError() };
+        if err == ERROR_FILE_NOT_FOUND {
+            return Ok(false);
+        }
+        return Err(anyhow::anyhow!("OpenMutexW failed: {err}"));
+    }
+    unsafe {
+        CloseHandle(handle);
+    }
+    Ok(true)
+}
+
+/// Pick an effective CWD, using a junction if the ACL helper is active.
+fn effective_cwd(req_cwd: &Path, log_dir: Option<&Path>) -> PathBuf {
+    let use_junction = match read_acl_mutex_exists() {
+        Ok(exists) => exists,
+        Err(err) => {
+            log_note(
+                &format!(
+                    "junction: failed to probe ACL mutex state: {err}; defaulting to junction cwd"
+                ),
+                log_dir,
+            );
+            true
+        }
+    };
+    if use_junction {
+        cwd_junction::create_cwd_junction(req_cwd, log_dir).unwrap_or_else(|| req_cwd.to_path_buf())
+    } else {
+        req_cwd.to_path_buf()
+    }
+}
+
+fn spawn_ipc_process(req: &SpawnRequest) -> Result<IpcSpawnedProcess> {
+    let log_dir = req.codex_home.clone();
+    hide_current_user_profile_dir(req.codex_home.as_path());
+    let token_mode = token_mode_for_permission_profile(
+        &req.permission_profile,
+        &req.workspace_roots,
+        &req.cwd,
+        &req.env,
+    )
+    .context("resolve permission profile token mode")?;
+    let mut cap_psids: Vec<LocalSid> = Vec::new();
+    for sid in &req.cap_sids {
+        cap_psids.push(
+            LocalSid::from_string(sid)
+                .context("ConvertStringSidToSidW failed for capability SID")?,
+        );
+    }
+    if cap_psids.is_empty() {
+        anyhow::bail!("runner: empty capability SID list");
+    }
+    let network_proxy_restricting_sid = req
+        .network_proxy_restricting_sid
+        .as_deref()
+        .map(LocalSid::from_string)
+        .transpose()
+        .context("ConvertStringSidToSidW failed for network proxy restricting SID")?;
+
+    // The token helpers still take raw SID pointers, but we keep ownership in `LocalSid`
+    // wrappers for as long as possible. That way any failure after SID parsing but before the
+    // child is fully spawned still releases the backing LocalAlloc memory automatically.
+    let cap_psid_ptrs: Vec<*mut _> = cap_psids.iter().map(LocalSid::as_ptr).collect();
+    let additional_restricting_sid_ptrs: Vec<*mut _> = network_proxy_restricting_sid
+        .iter()
+        .map(LocalSid::as_ptr)
+        .collect();
+    let base = OwnedWinHandle::new(unsafe { get_current_token_for_restriction()? });
+    let h_token = OwnedWinHandle::new(unsafe {
+        match token_mode {
+            WindowsSandboxTokenMode::ReadOnlyCapability => {
+                create_readonly_token_with_caps_and_user_from(
+                    base.raw(),
+                    &cap_psid_ptrs,
+                    &additional_restricting_sid_ptrs,
+                )
+            }
+            WindowsSandboxTokenMode::WritableRootsCapability => {
+                create_workspace_write_token_with_caps_and_user_from(
+                    base.raw(),
+                    &cap_psid_ptrs,
+                    &additional_restricting_sid_ptrs,
+                )
+            }
+        }
+    }?);
+    unsafe {
+        // These ACL adjustments need the raw SID values, but ownership stays with `cap_psids`.
+        // We do not manually `LocalFree` anything here; the wrappers handle every return path.
+        allow_null_device(cap_psid_ptrs[0]);
+        for psid in &cap_psid_ptrs {
+            allow_null_device(*psid);
+        }
+    }
+
+    let effective_cwd = effective_cwd(&req.cwd, Some(log_dir.as_path()));
+    let desktop = if req.use_private_desktop {
+        LaunchDesktop::open_private(
+            req.private_desktop_name
+                .as_deref()
+                .context("runner: missing parent-owned private desktop")?,
+        )?
+    } else {
+        LaunchDesktop::prepare(/*use_private_desktop*/ false, Some(log_dir.as_path()))?
+    };
+
+    let mut conpty_owner = None;
+    let mut hpc_handle: Option<HANDLE> = None;
+    let mut pipe_handles = None;
+    let (pi, job, stdout_handle, stderr_handle, stdin_handle) = if req.tty {
+        let (pi, mut conpty) = codex_windows_sandbox::spawn_conpty_process_as_user(
+            h_token.raw(),
+            &req.command,
+            &effective_cwd,
+            &req.env,
+            desktop,
+        )?;
+        let job = conpty
+            .job()
+            .context("spawned ConPTY is missing its process job")?;
+        hpc_handle = conpty.raw_handle();
+        let input_write = conpty.take_input_write();
+        let output_read = conpty.take_output_read();
+        conpty_owner = Some(conpty);
+        let stdin_handle = if req.stdin_open {
+            Some(input_write)
+        } else {
+            unsafe {
+                CloseHandle(input_write);
+            }
+            None
+        };
+        (
+            pi,
+            job,
+            output_read,
+            windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE,
+            stdin_handle,
+        )
+    } else {
+        let stdin_mode = if req.stdin_open {
+            StdinMode::Open
+        } else {
+            StdinMode::Closed
+        };
+        let spawned_pipes: PipeSpawnHandles = spawn_process_with_pipes(
+            h_token.raw(),
+            &req.command,
+            &effective_cwd,
+            &req.env,
+            stdin_mode,
+            StderrMode::Separate,
+            ConsoleMode::NoWindow,
+            desktop,
+            Some(log_dir.as_path()),
+        )?;
+        let pi = spawned_pipes.process;
+        let stdout_handle = spawned_pipes.stdout_read;
+        let stderr_handle = spawned_pipes
+            .stderr_read
+            .unwrap_or(windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE);
+        let stdin_handle = spawned_pipes.stdin_write;
+        let job = spawned_pipes.job();
+        pipe_handles = Some(spawned_pipes);
+        (pi, job, stdout_handle, stderr_handle, stdin_handle)
+    };
+    Ok(IpcSpawnedProcess {
+        log_dir,
+        pi,
+        job,
+        stdout_handle,
+        stderr_handle,
+        stdin_handle,
+        conpty_owner,
+        hpc_handle,
+        _pipe_handles: pipe_handles,
+    })
+}
+
+/// Stream stdout/stderr from the child into Output frames.
+fn spawn_output_reader(
+    writer: Arc<StdMutex<File>>,
+    handle: HANDLE,
+    stream: OutputStream,
+    log_dir: Option<PathBuf>,
+) -> std::thread::JoinHandle<()> {
+    read_handle_loop(handle, move |chunk| {
+        let msg = FramedMessage {
+            version: IPC_PROTOCOL_VERSION,
+            message: Message::Output {
+                payload: OutputPayload {
+                    data_b64: encode_bytes(chunk),
+                    stream,
+                },
+            },
+        };
+        if let Ok(mut guard) = writer.lock()
+            && let Err(err) = write_frame(&mut *guard, &msg)
+        {
+            log_note(
+                &format!("runner output write failed: {err}"),
+                log_dir.as_deref(),
+            );
+        }
+    })
+}
+
+fn terminate_job_or_process(job: &JobObject, process: HANDLE, log_dir: Option<&Path>) {
+    if let Err(job_err) = job.terminate() {
+        log_note(
+            &format!("runner failed to terminate process tree: {job_err}"),
+            log_dir,
+        );
+        if unsafe { TerminateProcess(process, 1) } == 0 {
+            log_note(
+                &format!("runner failed to terminate root process: {}", unsafe {
+                    GetLastError()
+                }),
+                log_dir,
+            );
+        }
+    }
+}
+
+/// Read stdin/terminate frames and forward to the child process.
+fn spawn_input_loop(
+    mut reader: File,
+    stdin_handle: Option<HANDLE>,
+    hpc_handle: Arc<StdMutex<Option<HANDLE>>>,
+    job: Arc<JobObject>,
+    process: HANDLE,
+    log_dir: Option<PathBuf>,
+) -> std::thread::JoinHandle<()> {
+    std::thread::spawn(move || {
+        let mut stdin_handle = stdin_handle;
+        loop {
+            let msg = match read_frame(&mut reader) {
+                Ok(Some(v)) => v,
+                Ok(None) | Err(_) => {
+                    terminate_job_or_process(&job, process, log_dir.as_deref());
+                    break;
+                }
+            };
+            match msg.message {
+                Message::Stdin { payload } => {
+                    let Ok(bytes) = decode_bytes(&payload.data_b64) else {
+                        continue;
+                    };
+                    if let Some(handle) = stdin_handle {
+                        let mut offset = 0usize;
+                        // `WriteFile` can report success after consuming only part of the buffer
+                        // when the target is a pipe. Treat this like a normal partial write and
+                        // keep advancing until every decoded stdin byte has been forwarded.
+                        //
+                        // If the child closes stdin or the pipe enters an error state, we log
+                        // that fact, close our local HANDLE, and stop trying to forward later
+                        // `Stdin` frames. That prevents silent truncation while also avoiding an
+                        // endless stream of failing writes after the child is already gone.
+                        while offset < bytes.len() {
+                            let chunk = &bytes[offset..];
+                            let chunk_len = chunk.len().min(u32::MAX as usize);
+                            let mut written = 0u32;
+                            let ok = unsafe {
+                                windows_sys::Win32::Storage::FileSystem::WriteFile(
+                                    handle,
+                                    chunk.as_ptr(),
+                                    chunk_len as u32,
+                                    &mut written,
+                                    ptr::null_mut(),
+                                )
+                            };
+                            if ok == 0 {
+                                log_note(
+                                    &format!(
+                                        "runner stdin write failed after {offset} bytes: {}",
+                                        unsafe { GetLastError() }
+                                    ),
+                                    log_dir.as_deref(),
+                                );
+                                unsafe {
+                                    CloseHandle(handle);
+                                }
+                                stdin_handle = None;
+                                break;
+                            }
+                            if written == 0 {
+                                log_note(
+                                    "runner stdin write made no progress; closing child stdin",
+                                    log_dir.as_deref(),
+                                );
+                                unsafe {
+                                    CloseHandle(handle);
+                                }
+                                stdin_handle = None;
+                                break;
+                            }
+                            offset += written as usize;
+                        }
+                    }
+                }
+                Message::CloseStdin { .. } => {
+                    if let Some(handle) = stdin_handle.take() {
+                        unsafe {
+                            CloseHandle(handle);
+                        }
+                    }
+                }
+                Message::Resize {
+                    payload: ResizePayload { rows, cols },
+                } => {
+                    if let Ok(guard) = hpc_handle.lock()
+                        && let Some(hpc) = guard.as_ref()
+                    {
+                        unsafe {
+                            let _ = ResizePseudoConsole(
+                                *hpc,
+                                COORD {
+                                    X: cols as i16,
+                                    Y: rows as i16,
+                                },
+                            );
+                        }
+                    }
+                }
+                Message::Terminate { .. } => {
+                    terminate_job_or_process(&job, process, log_dir.as_deref());
+                }
+                Message::SpawnRequest { .. } => {}
+                Message::SpawnReady { .. } => {}
+                Message::Output { .. } => {}
+                Message::Exit { .. } => {}
+                Message::Error { .. } => {}
+            }
+        }
+        if let Some(handle) = stdin_handle {
+            unsafe {
+                CloseHandle(handle);
+            }
+        }
+    })
+}
+
+/// Entry point for the Windows command runner process.
+pub fn main() -> Result<()> {
+    let mut pipe_in = None;
+    let mut pipe_out = None;
+    for arg in std::env::args().skip(1) {
+        if let Some(rest) = arg.strip_prefix("--pipe-in=") {
+            pipe_in = Some(rest.to_string());
+        } else if let Some(rest) = arg.strip_prefix("--pipe-out=") {
+            pipe_out = Some(rest.to_string());
+        }
+    }
+
+    let Some(pipe_in) = pipe_in else {
+        anyhow::bail!("runner: no pipe-in provided");
+    };
+    let Some(pipe_out) = pipe_out else {
+        anyhow::bail!("runner: no pipe-out provided");
+    };
+
+    // Open both pipe ends under guards first so a failure on the second open cannot leak the
+    // first HANDLE. Only after both opens succeed do we transfer ownership into `File`, which
+    // then becomes responsible for closing them.
+    let h_pipe_in = OwnedWinHandle::new(open_pipe(&pipe_in, FILE_GENERIC_READ)?);
+    let h_pipe_out = OwnedWinHandle::new(open_pipe(&pipe_out, FILE_GENERIC_WRITE)?);
+    let mut pipe_read = unsafe { File::from_raw_handle(h_pipe_in.into_raw() as _) };
+    let pipe_write = Arc::new(StdMutex::new(unsafe {
+        File::from_raw_handle(h_pipe_out.into_raw() as _)
+    }));
+
+    let req = match read_spawn_request(&mut pipe_read) {
+        Ok(v) => v,
+        Err(err) => {
+            let _ = send_error(
+                &pipe_write,
+                ErrorStage::ReadSpawnRequest,
+                /*windows_error_code*/ None,
+                err.to_string(),
+            );
+            return Err(err);
+        }
+    };
+
+    let ipc_spawn = match spawn_ipc_process(&req) {
+        Ok(value) => value,
+        Err(err) => {
+            let _ = send_error(
+                &pipe_write,
+                ErrorStage::SpawnChild,
+                windows_error_code(&err),
+                err.to_string(),
+            );
+            return Err(err);
+        }
+    };
+    let log_dir = Some(ipc_spawn.log_dir.as_path());
+    let pi = ipc_spawn.pi;
+    let stdout_handle = ipc_spawn.stdout_handle;
+    let stderr_handle = ipc_spawn.stderr_handle;
+    let job = Arc::clone(&ipc_spawn.job);
+    let mut conpty_owner = ipc_spawn.conpty_owner;
+    let stdin_handle = ipc_spawn.stdin_handle;
+    let hpc_handle = Arc::new(StdMutex::new(ipc_spawn.hpc_handle));
+
+    let msg = FramedMessage {
+        version: IPC_PROTOCOL_VERSION,
+        message: Message::SpawnReady {
+            payload: SpawnReady {
+                process_id: unsafe { GetProcessId(pi.hProcess) },
+            },
+        },
+    };
+    if let Err(err) = if let Ok(mut guard) = pipe_write.lock() {
+        write_frame(&mut *guard, &msg)
+    } else {
+        anyhow::bail!("runner spawn_ready write failed: pipe_write lock poisoned");
+    } {
+        let _ = send_error(
+            &pipe_write,
+            ErrorStage::WriteSpawnReady,
+            /*windows_error_code*/ None,
+            err.to_string(),
+        );
+        return Err(err);
+    }
+    let log_dir_owned = log_dir.map(Path::to_path_buf);
+    let out_thread = spawn_output_reader(
+        Arc::clone(&pipe_write),
+        stdout_handle,
+        OutputStream::Stdout,
+        log_dir_owned.clone(),
+    );
+    let err_thread = if stderr_handle != windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE {
+        Some(spawn_output_reader(
+            Arc::clone(&pipe_write),
+            stderr_handle,
+            OutputStream::Stderr,
+            log_dir_owned.clone(),
+        ))
+    } else {
+        None
+    };
+
+    let _input_thread = spawn_input_loop(
+        pipe_read,
+        stdin_handle,
+        Arc::clone(&hpc_handle),
+        Arc::clone(&job),
+        pi.hProcess,
+        log_dir_owned,
+    );
+
+    let timeout = req.timeout_ms.map(|ms| ms as u32).unwrap_or(INFINITE);
+    let wait_res = unsafe { WaitForSingleObject(pi.hProcess, timeout) };
+    let timed_out = wait_res == WAIT_TIMEOUT;
+    let child_stopped = if timed_out {
+        terminate_job_or_process(&job, pi.hProcess, log_dir);
+        let termination_wait = unsafe { WaitForSingleObject(pi.hProcess, TERMINATION_WAIT_MS) };
+        if termination_wait == WAIT_TIMEOUT {
+            log_note(
+                "runner root process did not exit after termination",
+                log_dir,
+            );
+            false
+        } else {
+            true
+        }
+    } else {
+        if let Err(err) = job.preserve_descendants() {
+            log_note(
+                &format!("runner failed to preserve descendants after root exit: {err}"),
+                log_dir,
+            );
+        }
+        true
+    };
+
+    let exit_code: i32;
+    unsafe {
+        if timed_out {
+            exit_code = 128 + 64;
+        } else {
+            let mut raw_exit: u32 = 1;
+            GetExitCodeProcess(pi.hProcess, &mut raw_exit);
+            exit_code = raw_exit as i32;
+        }
+        if pi.hThread != 0 {
+            CloseHandle(pi.hThread);
+        }
+        if pi.hProcess != 0 {
+            CloseHandle(pi.hProcess);
+        }
+    }
+
+    if let Ok(mut guard) = hpc_handle.lock() {
+        let _ = guard.take();
+    }
+    drop(conpty_owner.take());
+
+    if child_stopped {
+        if out_thread.join().is_err() {
+            log_note("runner stdout reader thread panicked", log_dir);
+        }
+        if let Some(thread) = err_thread
+            && thread.join().is_err()
+        {
+            log_note("runner stderr reader thread panicked", log_dir);
+        }
+    }
+
+    let exit_msg = FramedMessage {
+        version: IPC_PROTOCOL_VERSION,
+        message: Message::Exit {
+            payload: ExitPayload {
+                exit_code,
+                timed_out,
+            },
+        },
+    };
+    if let Ok(mut guard) = pipe_write.lock()
+        && let Err(err) = write_frame(&mut *guard, &exit_msg)
+    {
+        log_note(&format!("runner exit write failed: {err}"), log_dir);
+    }
+
+    std::process::exit(exit_code);
+}
diff --git a/codex-rs/windows-sandbox-rs/src/bin/command_runner/win/cwd_junction.rs b/codex-rs/windows-sandbox-rs/src/bin/command_runner/win/cwd_junction.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7ddd391c3498c611b47c15b858d59b2eda1cce41
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/bin/command_runner/win/cwd_junction.rs
@@ -0,0 +1,140 @@
+use codex_windows_sandbox::log_note;
+use std::collections::hash_map::DefaultHasher;
+use std::hash::Hash;
+use std::hash::Hasher;
+use std::os::windows::fs::MetadataExt as _;
+use std::os::windows::process::CommandExt as _;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_REPARSE_POINT;
+
+fn junction_name_for_path(path: &Path) -> String {
+    let mut hasher = DefaultHasher::new();
+    path.to_string_lossy().hash(&mut hasher);
+    format!("{:x}", hasher.finish())
+}
+
+fn junction_root_for_userprofile(userprofile: &str) -> PathBuf {
+    PathBuf::from(userprofile)
+        .join(".codex")
+        .join(".sandbox")
+        .join("cwd")
+}
+
+pub fn create_cwd_junction(requested_cwd: &Path, log_dir: Option<&Path>) -> Option<PathBuf> {
+    let userprofile = std::env::var("USERPROFILE").ok()?;
+    let junction_root = junction_root_for_userprofile(&userprofile);
+    if let Err(err) = std::fs::create_dir_all(&junction_root) {
+        log_note(
+            &format!(
+                "junction: failed to create {}: {err}",
+                junction_root.display()
+            ),
+            log_dir,
+        );
+        return None;
+    }
+
+    let junction_path = junction_root.join(junction_name_for_path(requested_cwd));
+    if junction_path.exists() {
+        // Reuse an existing junction if it looks like a reparse point; this keeps the hot path
+        // cheap and avoids repeatedly shelling out to mklink.
+        match std::fs::symlink_metadata(&junction_path) {
+            Ok(md) if (md.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT) != 0 => {
+                log_note(
+                    &format!("junction: reusing existing {}", junction_path.display()),
+                    log_dir,
+                );
+                return Some(junction_path);
+            }
+            Ok(_) => {
+                // Unexpected: something else exists at this path (regular directory/file). We'll
+                // try to remove it if possible and recreate the junction.
+                log_note(
+                    &format!(
+                        "junction: existing path is not a reparse point, recreating {}",
+                        junction_path.display()
+                    ),
+                    log_dir,
+                );
+            }
+            Err(err) => {
+                log_note(
+                    &format!(
+                        "junction: failed to stat existing {}: {err}",
+                        junction_path.display()
+                    ),
+                    log_dir,
+                );
+                return None;
+            }
+        }
+
+        if let Err(err) = std::fs::remove_dir(&junction_path) {
+            log_note(
+                &format!(
+                    "junction: failed to remove existing {}: {err}",
+                    junction_path.display()
+                ),
+                log_dir,
+            );
+            return None;
+        }
+    }
+
+    let link = junction_path.to_string_lossy().to_string();
+    let target = requested_cwd.to_string_lossy().to_string();
+
+    // Use `cmd /c` so we can call `mklink` (a cmd builtin). We must quote paths so CWDs
+    // containing spaces work reliably.
+    //
+    // IMPORTANT: `std::process::Command::args()` will apply Windows quoting/escaping rules when
+    // constructing the command line. Passing a single argument that itself contains quotes can
+    // confuse `cmd.exe` and cause mklink to fail with "syntax is incorrect". We avoid that by
+    // using `raw_arg` to pass the tokens exactly as `cmd.exe` expects to parse them.
+    //
+    // Paths cannot contain quotes on Windows, so no extra escaping is needed here.
+    let link_quoted = format!("\"{link}\"");
+    let target_quoted = format!("\"{target}\"");
+    log_note(
+        &format!("junction: creating via cmd /c mklink /J {link_quoted} {target_quoted}"),
+        log_dir,
+    );
+    let output = match std::process::Command::new("cmd")
+        .raw_arg("/c")
+        .raw_arg("mklink")
+        .raw_arg("/J")
+        .raw_arg(&link_quoted)
+        .raw_arg(&target_quoted)
+        .output()
+    {
+        Ok(output) => output,
+        Err(err) => {
+            log_note(&format!("junction: mklink failed to run: {err}"), log_dir);
+            return None;
+        }
+    };
+    if output.status.success() && junction_path.exists() {
+        log_note(
+            &format!(
+                "junction: created {} -> {}",
+                junction_path.display(),
+                requested_cwd.display()
+            ),
+            log_dir,
+        );
+        return Some(junction_path);
+    }
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    log_note(
+        &format!(
+            "junction: mklink failed status={:?} stdout={} stderr={}",
+            output.status,
+            stdout.trim(),
+            stderr.trim()
+        ),
+        log_dir,
+    );
+    None
+}
diff --git a/codex-rs/windows-sandbox-rs/src/bin/managed_deny_probe/main.rs b/codex-rs/windows-sandbox-rs/src/bin/managed_deny_probe/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4535c9b9579c866d0a9dc4f4ef0f045a2b420a8e
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/bin/managed_deny_probe/main.rs
@@ -0,0 +1,13 @@
+// Keep the ACL probe independent of test-harness startup, which writes CODEX_HOME.
+#[cfg(target_os = "windows")]
+mod win;
+
+#[cfg(target_os = "windows")]
+fn main() {
+    win::main();
+}
+
+#[cfg(not(target_os = "windows"))]
+fn main() {
+    panic!("codex-windows-managed-deny-probe is Windows-only");
+}
diff --git a/codex-rs/windows-sandbox-rs/src/bin/managed_deny_probe/win.rs b/codex-rs/windows-sandbox-rs/src/bin/managed_deny_probe/win.rs
new file mode 100644
index 0000000000000000000000000000000000000000..159268d84cc680194f1c56b98adcb6d2fc26292c
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/bin/managed_deny_probe/win.rs
@@ -0,0 +1,101 @@
+use std::ffi::c_void;
+use std::io::Write as _;
+use std::os::windows::ffi::OsStrExt;
+use std::path::Path;
+use std::path::PathBuf;
+
+#[link(name = "kernel32")]
+unsafe extern "system" {
+    #[link_name = "LoadLibraryW"]
+    fn load_library_w(file_name: *const u16) -> *mut c_void;
+    #[link_name = "FreeLibrary"]
+    fn free_library(module: *mut c_void) -> i32;
+}
+
+fn load_library(path: &Path) -> std::io::Result<()> {
+    let wide_path: Vec<u16> = path
+        .as_os_str()
+        .encode_wide()
+        .chain(std::iter::once(0))
+        .collect();
+    // SAFETY: `wide_path` is NUL-terminated and remains alive for the call.
+    let module = unsafe { load_library_w(wide_path.as_ptr()) };
+    if module.is_null() {
+        return Err(std::io::Error::last_os_error());
+    }
+    // SAFETY: `module` is a non-null handle returned by `LoadLibraryW` above.
+    if unsafe { free_library(module) } == 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    Ok(())
+}
+
+fn access_was_denied(err: &std::io::Error) -> bool {
+    err.kind() == std::io::ErrorKind::PermissionDenied || err.raw_os_error() == Some(5)
+}
+
+fn probe_path(key: &str) -> PathBuf {
+    let Some(value) = std::env::var_os(key) else {
+        eprintln!("managed deny probe is missing {key}");
+        probe_exit(/*code*/ 21);
+    };
+    PathBuf::from(value)
+}
+
+fn probe_exit(code: i32) -> ! {
+    let _ = std::io::stdout().flush();
+    let _ = std::io::stderr().flush();
+    std::process::exit(code);
+}
+
+pub(super) fn main() {
+    let allowed_text = probe_path("CODEX_WINDOWS_ALLOWED_TEXT");
+    let denied_text = probe_path("CODEX_WINDOWS_DENIED_TEXT");
+    let allowed_module = probe_path("CODEX_WINDOWS_ALLOWED_MODULE");
+    let denied_module = probe_path("CODEX_WINDOWS_DENIED_MODULE");
+
+    match std::fs::read_to_string(&allowed_text) {
+        Ok(contents) if contents.trim() == "ALLOW-CONTROL" => println!("allowed-read:OK"),
+        Ok(_) => {
+            eprintln!("allowed read returned unexpected contents");
+            probe_exit(/*code*/ 21);
+        }
+        Err(err) => {
+            eprintln!("allowed read failed: {err}");
+            probe_exit(/*code*/ 21);
+        }
+    }
+    if let Err(err) = load_library(&allowed_module) {
+        eprintln!("allowed import failed: {err}");
+        probe_exit(/*code*/ 21);
+    }
+    println!("allowed-import:OK");
+
+    let mut failures = 0;
+    match std::fs::read(&denied_text) {
+        Ok(_) => {
+            println!("denied-read:UNEXPECTED_SUCCESS");
+            failures += 1;
+        }
+        Err(err) if access_was_denied(&err) => println!("denied-read:DENIED"),
+        Err(err) => {
+            eprintln!("denied read failed for a non-access reason: {err}");
+            probe_exit(/*code*/ 21);
+        }
+    }
+    match load_library(&denied_module) {
+        Ok(()) => {
+            println!("denied-import:UNEXPECTED_SUCCESS");
+            failures += 1;
+        }
+        Err(err) if access_was_denied(&err) => println!("denied-import:DENIED"),
+        Err(err) => {
+            eprintln!("denied import failed for a non-access reason: {err}");
+            probe_exit(/*code*/ 21);
+        }
+    }
+
+    if failures != 0 {
+        probe_exit(/*code*/ 20);
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/bin/setup_main/main.rs b/codex-rs/windows-sandbox-rs/src/bin/setup_main/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0f2ff98deee43aa819ac0c6b1d7278a49f651681
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/bin/setup_main/main.rs
@@ -0,0 +1,9 @@
+#[cfg(target_os = "windows")]
+fn main() -> anyhow::Result<()> {
+    codex_windows_sandbox::setup_helper_main()
+}
+
+#[cfg(not(target_os = "windows"))]
+fn main() {
+    panic!("codex-windows-sandbox-setup is Windows-only");
+}
diff --git a/codex-rs/windows-sandbox-rs/src/cap.rs b/codex-rs/windows-sandbox-rs/src/cap.rs
new file mode 100644
index 0000000000000000000000000000000000000000..41b33b63fda6f9bbc648fef98e5c9065f8f17b5e
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/cap.rs
@@ -0,0 +1,203 @@
+use crate::path_normalization::canonical_path_key;
+use crate::path_normalization::canonicalize_path;
+use anyhow::Context;
+use anyhow::Result;
+use rand::RngCore;
+use rand::SeedableRng;
+use rand::rngs::SmallRng;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::fs;
+use std::path::Path;
+use std::path::PathBuf;
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct CapSids {
+    pub workspace: String,
+    pub readonly: String,
+    /// Per-workspace capability SIDs keyed by canonicalized CWD string.
+    ///
+    /// This is used to isolate workspaces from other workspace sandbox writes and to
+    /// apply per-workspace denies (e.g. protect `CWD/.codex`)
+    /// without permanently affecting other workspaces.
+    #[serde(default)]
+    pub workspace_by_cwd: HashMap<String, String>,
+    /// Per-write-root capability SIDs keyed by canonicalized write-root path.
+    ///
+    /// These are included in a workspace-write token only when the root is
+    /// currently allowed, so stale ACLs from earlier extra roots do not expand
+    /// later workspace sandboxes.
+    #[serde(default)]
+    pub writable_root_by_path: HashMap<String, String>,
+}
+
+pub fn cap_sid_file(codex_home: &Path) -> PathBuf {
+    codex_home.join("cap_sid")
+}
+
+fn make_random_cap_sid_string() -> String {
+    let mut rng = SmallRng::from_entropy();
+    let a = rng.next_u32();
+    let b = rng.next_u32();
+    let c = rng.next_u32();
+    let d = rng.next_u32();
+    format!("S-1-5-21-{a}-{b}-{c}-{d}")
+}
+
+fn persist_caps(path: &Path, caps: &CapSids) -> Result<()> {
+    if let Some(dir) = path.parent() {
+        fs::create_dir_all(dir).with_context(|| format!("create cap sid dir {}", dir.display()))?;
+    }
+    let json = serde_json::to_string(caps)?;
+    fs::write(path, json).with_context(|| format!("write cap sid file {}", path.display()))?;
+    Ok(())
+}
+
+pub fn load_or_create_cap_sids(codex_home: &Path) -> Result<CapSids> {
+    let path = cap_sid_file(codex_home);
+    if path.exists() {
+        let txt = fs::read_to_string(&path)
+            .with_context(|| format!("read cap sid file {}", path.display()))?;
+        let t = txt.trim();
+        if t.starts_with('{') && t.ends_with('}') {
+            if let Ok(obj) = serde_json::from_str::<CapSids>(t) {
+                return Ok(obj);
+            }
+        } else if !t.is_empty() {
+            let caps = CapSids {
+                workspace: t.to_string(),
+                readonly: make_random_cap_sid_string(),
+                workspace_by_cwd: HashMap::new(),
+                writable_root_by_path: HashMap::new(),
+            };
+            persist_caps(&path, &caps)?;
+            return Ok(caps);
+        }
+    }
+    let caps = CapSids {
+        workspace: make_random_cap_sid_string(),
+        readonly: make_random_cap_sid_string(),
+        workspace_by_cwd: HashMap::new(),
+        writable_root_by_path: HashMap::new(),
+    };
+    persist_caps(&path, &caps)?;
+    Ok(caps)
+}
+
+/// Returns the workspace-specific capability SID for `cwd`, creating and persisting it if missing.
+pub fn workspace_cap_sid_for_cwd(codex_home: &Path, cwd: &Path) -> Result<String> {
+    let path = cap_sid_file(codex_home);
+    let mut caps = load_or_create_cap_sids(codex_home)?;
+    let key = canonical_path_key(cwd);
+    if let Some(sid) = caps.workspace_by_cwd.get(&key) {
+        return Ok(sid.clone());
+    }
+    let sid = make_random_cap_sid_string();
+    caps.workspace_by_cwd.insert(key, sid.clone());
+    persist_caps(&path, &caps)?;
+    Ok(sid)
+}
+
+/// Returns the capability SID for an additional writable root, creating and persisting it if missing.
+pub fn writable_root_cap_sid_for_path(codex_home: &Path, root: &Path) -> Result<String> {
+    let path = cap_sid_file(codex_home);
+    let mut caps = load_or_create_cap_sids(codex_home)?;
+    let key = canonical_path_key(root);
+    if let Some(sid) = caps.writable_root_by_path.get(&key) {
+        return Ok(sid.clone());
+    }
+    let sid = make_random_cap_sid_string();
+    caps.writable_root_by_path.insert(key, sid.clone());
+    persist_caps(&path, &caps)?;
+    Ok(sid)
+}
+
+pub fn workspace_write_cap_sid_for_root(
+    codex_home: &Path,
+    cwd: &Path,
+    root: &Path,
+) -> Result<String> {
+    if canonical_path_key(root) == canonical_path_key(cwd) {
+        workspace_cap_sid_for_cwd(codex_home, cwd)
+    } else {
+        writable_root_cap_sid_for_path(codex_home, root)
+    }
+}
+
+pub fn workspace_write_root_contains_path(root: &Path, path: &Path) -> bool {
+    canonicalize_path(path).starts_with(canonicalize_path(root))
+}
+
+pub fn workspace_write_root_overlaps_path(root: &Path, path: &Path) -> bool {
+    workspace_write_root_contains_path(root, path) || workspace_write_root_contains_path(path, root)
+}
+
+pub fn workspace_write_root_specificity(root: &Path) -> usize {
+    canonicalize_path(root).components().count()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::load_or_create_cap_sids;
+    use super::workspace_cap_sid_for_cwd;
+    use super::workspace_write_cap_sid_for_root;
+    use super::writable_root_cap_sid_for_path;
+    use pretty_assertions::assert_eq;
+    use std::path::PathBuf;
+
+    #[test]
+    fn equivalent_cwd_spellings_share_workspace_sid_key() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        std::fs::create_dir_all(&codex_home).expect("create codex home");
+
+        let workspace = temp.path().join("WorkspaceRoot");
+        std::fs::create_dir_all(&workspace).expect("create workspace root");
+
+        let canonical = dunce::canonicalize(&workspace).expect("canonical workspace root");
+        let alt_spelling = PathBuf::from(
+            canonical
+                .to_string_lossy()
+                .replace('\\', "/")
+                .to_ascii_uppercase(),
+        );
+
+        let first_sid =
+            workspace_cap_sid_for_cwd(&codex_home, canonical.as_path()).expect("first sid");
+        let second_sid =
+            workspace_cap_sid_for_cwd(&codex_home, alt_spelling.as_path()).expect("second sid");
+
+        assert_eq!(first_sid, second_sid);
+
+        let caps = load_or_create_cap_sids(&codex_home).expect("load caps");
+        assert_eq!(caps.workspace_by_cwd.len(), 1);
+    }
+
+    #[test]
+    fn write_roots_get_path_scoped_sids() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        std::fs::create_dir_all(&codex_home).expect("create codex home");
+
+        let workspace = temp.path().join("workspace");
+        let extra_root = temp.path().join("extra-root");
+        std::fs::create_dir_all(&workspace).expect("create workspace");
+        std::fs::create_dir_all(&extra_root).expect("create extra root");
+
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let extra_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &extra_root)
+            .expect("extra root sid");
+
+        assert_ne!(workspace_sid, extra_sid);
+        assert_eq!(
+            extra_sid,
+            writable_root_cap_sid_for_path(&codex_home, &extra_root).expect("extra root sid again")
+        );
+
+        let caps = load_or_create_cap_sids(&codex_home).expect("load caps");
+        assert_eq!(caps.workspace_by_cwd.len(), 1);
+        assert_eq!(caps.writable_root_by_path.len(), 1);
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/conpty/mod.rs b/codex-rs/windows-sandbox-rs/src/conpty/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..363421ec19a74f1c795ef4be0febdf1743c18454
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/conpty/mod.rs
@@ -0,0 +1,175 @@
+//! ConPTY helpers for spawning sandboxed processes with a PTY on Windows.
+//!
+//! This module encapsulates ConPTY creation and process spawn with the required
+//! `PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE` plumbing. It is shared by both the legacy
+//! restricted‑token path and the elevated runner path when unified_exec runs with
+//! `tty=true`. The helpers are not tied to the IPC layer and can be reused by other
+//! Windows sandbox flows that need a PTY.
+
+use crate::desktop::LaunchDesktop;
+use crate::proc_thread_attr::ProcThreadAttributeList;
+use crate::winutil::format_last_error;
+use crate::winutil::quote_windows_arg;
+use crate::winutil::to_wide;
+use anyhow::Context;
+use anyhow::Result;
+use codex_utils_pty::JobObject;
+use codex_utils_pty::PsuedoCon;
+use codex_utils_pty::RawConPty;
+use std::collections::HashMap;
+use std::ffi::c_void;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::IntoRawHandle;
+use std::path::Path;
+use std::sync::Arc;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::System::Threading::CREATE_UNICODE_ENVIRONMENT;
+use windows_sys::Win32::System::Threading::CreateProcessAsUserW;
+use windows_sys::Win32::System::Threading::EXTENDED_STARTUPINFO_PRESENT;
+use windows_sys::Win32::System::Threading::PROCESS_INFORMATION;
+use windows_sys::Win32::System::Threading::STARTF_USESTDHANDLES;
+use windows_sys::Win32::System::Threading::STARTUPINFOEXW;
+
+use crate::process::make_env_block;
+
+/// Owns a ConPTY handle and its backing pipe handles.
+pub struct ConptyInstance {
+    pseudoconsole: Option<PsuedoCon>,
+    input_write: HANDLE,
+    output_read: HANDLE,
+    job: Option<Arc<JobObject>>,
+    _desktop: Option<LaunchDesktop>,
+}
+
+impl Drop for ConptyInstance {
+    fn drop(&mut self) {
+        unsafe {
+            if self.input_write != 0 && self.input_write != INVALID_HANDLE_VALUE {
+                CloseHandle(self.input_write);
+            }
+            if self.output_read != 0 && self.output_read != INVALID_HANDLE_VALUE {
+                CloseHandle(self.output_read);
+            }
+        }
+        let _ = self.pseudoconsole.take();
+    }
+}
+
+impl ConptyInstance {
+    pub fn raw_handle(&self) -> Option<HANDLE> {
+        self.pseudoconsole
+            .as_ref()
+            .map(|pseudoconsole| pseudoconsole.raw_handle() as HANDLE)
+    }
+
+    pub fn take_input_write(&mut self) -> HANDLE {
+        std::mem::replace(&mut self.input_write, 0)
+    }
+
+    pub fn take_output_read(&mut self) -> HANDLE {
+        std::mem::replace(&mut self.output_read, 0)
+    }
+
+    /// Returns the Job Object containing the spawned process, if this instance owns one.
+    pub fn job(&self) -> Option<Arc<JobObject>> {
+        self.job.as_ref().map(Arc::clone)
+    }
+}
+
+/// Create a ConPTY with backing pipes.
+///
+/// This is public so callers that need lower-level PTY setup can build on the same
+/// primitive, although the common entry point is `spawn_conpty_process_as_user`.
+#[allow(dead_code)]
+pub fn create_conpty(cols: i16, rows: i16) -> Result<ConptyInstance> {
+    let raw = RawConPty::new(cols, rows)?;
+    let (pseudoconsole, input_write, output_read) = raw.into_handles();
+
+    Ok(ConptyInstance {
+        pseudoconsole: Some(pseudoconsole),
+        input_write: input_write.into_raw_handle() as HANDLE,
+        output_read: output_read.into_raw_handle() as HANDLE,
+        job: None,
+        _desktop: None,
+    })
+}
+
+/// Spawn a process under `h_token` with ConPTY attached.
+///
+/// This is the main shared ConPTY entry point and is used by both the legacy/direct path
+/// and the elevated runner path whenever a PTY-backed sandboxed process is needed.
+pub fn spawn_conpty_process_as_user(
+    h_token: HANDLE,
+    argv: &[String],
+    cwd: &Path,
+    env_map: &HashMap<String, String>,
+    desktop: LaunchDesktop,
+) -> Result<(PROCESS_INFORMATION, ConptyInstance)> {
+    let cmdline_str = argv
+        .iter()
+        .map(|arg| quote_windows_arg(arg))
+        .collect::<Vec<_>>()
+        .join(" ");
+    let mut cmdline: Vec<u16> = to_wide(&cmdline_str);
+    let env_block = make_env_block(env_map);
+    let mut si: STARTUPINFOEXW = unsafe { std::mem::zeroed() };
+    si.StartupInfo.cb = std::mem::size_of::<STARTUPINFOEXW>() as u32;
+    si.StartupInfo.dwFlags = STARTF_USESTDHANDLES;
+    si.StartupInfo.hStdInput = INVALID_HANDLE_VALUE;
+    si.StartupInfo.hStdOutput = INVALID_HANDLE_VALUE;
+    si.StartupInfo.hStdError = INVALID_HANDLE_VALUE;
+    si.StartupInfo.lpDesktop = desktop.startup_info_desktop();
+    let job = Arc::new(JobObject::create().context("create process job")?);
+
+    let raw = RawConPty::new(/*cols*/ 80, /*rows*/ 24)?;
+    let (pseudoconsole, input_write, output_read) = raw.into_handles();
+    let hpc = pseudoconsole.raw_handle() as HANDLE;
+    let conpty = ConptyInstance {
+        pseudoconsole: Some(pseudoconsole),
+        input_write: input_write.into_raw_handle() as HANDLE,
+        output_read: output_read.into_raw_handle() as HANDLE,
+        job: Some(Arc::clone(&job)),
+        _desktop: Some(desktop),
+    };
+    let preserve_app_context = crate::app_package::current_process_is_registered_core_runner()?;
+    let mut attrs = ProcThreadAttributeList::new(2 + u32::from(preserve_app_context))?;
+    attrs.set_pseudoconsole(hpc)?;
+    attrs.set_job(job.as_raw_handle() as HANDLE)?;
+    if preserve_app_context {
+        attrs.preserve_desktop_app_context()?;
+    }
+    si.lpAttributeList = attrs.as_mut_ptr();
+
+    let mut pi: PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
+    let ok = unsafe {
+        CreateProcessAsUserW(
+            h_token,
+            std::ptr::null(),
+            cmdline.as_mut_ptr(),
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            0,
+            EXTENDED_STARTUPINFO_PRESENT | CREATE_UNICODE_ENVIRONMENT,
+            env_block.as_ptr() as *mut c_void,
+            to_wide(cwd).as_ptr(),
+            &si.StartupInfo,
+            &mut pi,
+        )
+    };
+    if ok == 0 {
+        let err = unsafe { GetLastError() } as i32;
+        let message = format!(
+            "CreateProcessAsUserW failed: {} ({}) | cwd={} | cmd={} | env_u16_len={}",
+            err,
+            format_last_error(err),
+            cwd.display(),
+            cmdline_str,
+            env_block.len()
+        );
+        return Err(std::io::Error::from_raw_os_error(err)).context(message);
+    }
+    Ok((pi, conpty))
+}
diff --git a/codex-rs/windows-sandbox-rs/src/deny_read_acl.rs b/codex-rs/windows-sandbox-rs/src/deny_read_acl.rs
new file mode 100644
index 0000000000000000000000000000000000000000..06eda3b6effad296d4cd5130a2f19bb5495f03f6
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/deny_read_acl.rs
@@ -0,0 +1,152 @@
+use crate::acl::add_deny_read_ace;
+use crate::acl::revoke_ace;
+use anyhow::Context;
+use anyhow::Result;
+use std::collections::HashSet;
+use std::ffi::c_void;
+use std::path::Path;
+use std::path::PathBuf;
+
+/// Build the exact ACL paths that should receive a deny-read ACE.
+///
+/// We keep both the lexical policy path and, when it already exists, the
+/// canonical target. The lexical path covers the path users configured and lets
+/// missing exact denies be materialized later; the canonical path also covers
+/// an existing reparse-point target so a sandbox cannot read the same object
+/// through the resolved location. Filesystem roots are rejected after this
+/// canonicalization so aliases cannot install a root deny ACE.
+pub fn plan_deny_read_acl_paths(paths: &[PathBuf]) -> Result<Vec<PathBuf>> {
+    let mut planned = Vec::new();
+    let mut seen = HashSet::new();
+    for path in paths {
+        push_planned_path(&mut planned, &mut seen, path.to_path_buf());
+        let canonical = match dunce::canonicalize(path) {
+            Ok(canonical) => canonical,
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(err) => {
+                return Err(err)
+                    .with_context(|| format!("canonicalize deny-read path {}", path.display()));
+            }
+        };
+        push_planned_path(&mut planned, &mut seen, canonical);
+    }
+    if let Some(root) = planned
+        .iter()
+        .find(|path| path.is_absolute() && path.parent().is_none())
+    {
+        anyhow::bail!(
+            "refusing to apply a deny-read ACE to filesystem root {}",
+            root.display()
+        );
+    }
+    Ok(planned)
+}
+
+fn push_planned_path(planned: &mut Vec<PathBuf>, seen: &mut HashSet<String>, path: PathBuf) {
+    if seen.insert(lexical_path_key(&path)) {
+        planned.push(path);
+    }
+}
+
+pub(crate) fn lexical_path_key(path: &Path) -> String {
+    path.to_string_lossy()
+        .replace('\\', "/")
+        .trim_end_matches('/')
+        .to_ascii_lowercase()
+}
+
+/// Applies deny-read ACEs to explicit paths. Missing paths are materialized as
+/// directories before the ACE is applied so a sandboxed command cannot create a
+/// previously absent denied path and then read from it in the same run.
+/// If any path fails, deny ACEs applied by this call are revoked before the
+/// error is returned so a one-shot sandbox run does not leave partial state.
+///
+/// # Safety
+/// Caller must pass a valid SID pointer for the sandbox principal being denied.
+pub unsafe fn apply_deny_read_acls(paths: &[PathBuf], psid: *mut c_void) -> Result<Vec<PathBuf>> {
+    let planned = plan_deny_read_acl_paths(paths)?;
+    let mut applied = Vec::new();
+    let mut seen = HashSet::new();
+    let mut added_in_this_call: Vec<PathBuf> = Vec::new();
+    for path in planned {
+        let result = (|| -> Result<bool> {
+            if !path.exists() {
+                std::fs::create_dir_all(&path)
+                    .with_context(|| format!("create deny-read path {}", path.display()))?;
+            }
+            add_deny_read_ace(&path, psid)
+                .with_context(|| format!("apply deny-read ACE to {}", path.display()))
+        })();
+        let added = match result {
+            Ok(added) => added,
+            Err(err) => {
+                for added_path in &added_in_this_call {
+                    let _ = revoke_ace(added_path, psid);
+                }
+                return Err(err);
+            }
+        };
+        if added {
+            added_in_this_call.push(path.clone());
+        }
+        push_planned_path(&mut applied, &mut seen, path);
+    }
+    Ok(applied)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::plan_deny_read_acl_paths;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashSet;
+    use std::path::PathBuf;
+    use tempfile::TempDir;
+
+    #[test]
+    fn plan_preserves_missing_paths() {
+        let tmp = TempDir::new().expect("tempdir");
+        let missing = tmp.path().join("future-secret.env");
+
+        assert_eq!(
+            plan_deny_read_acl_paths(std::slice::from_ref(&missing)).expect("plan deny-read ACL"),
+            vec![missing]
+        );
+    }
+
+    #[test]
+    fn plan_includes_existing_canonical_targets() {
+        let tmp = TempDir::new().expect("tempdir");
+        let existing = tmp.path().join("secret.env");
+        std::fs::write(&existing, "secret").expect("write secret");
+
+        let planned: HashSet<PathBuf> = plan_deny_read_acl_paths(std::slice::from_ref(&existing))
+            .expect("plan deny-read ACL")
+            .into_iter()
+            .collect();
+        let expected: HashSet<PathBuf> = [
+            existing.clone(),
+            dunce::canonicalize(&existing).expect("canonical path"),
+        ]
+        .into_iter()
+        .collect();
+
+        assert_eq!(planned, expected);
+    }
+
+    #[test]
+    fn plan_rejects_file_system_root() {
+        let cwd = std::env::current_dir().expect("current directory");
+        let root = cwd.ancestors().last().expect("filesystem root");
+
+        let err = plan_deny_read_acl_paths(&[root.to_path_buf()])
+            .expect_err("filesystem root must not receive a deny-read ACE");
+
+        assert_eq!(
+            err.to_string(),
+            format!(
+                "refusing to apply a deny-read ACE to filesystem root {}",
+                root.display()
+            )
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/deny_read_resolver.rs b/codex-rs/windows-sandbox-rs/src/deny_read_resolver.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f7b39839f9191dffd62e7f6b005a7852b46fb86d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/deny_read_resolver.rs
@@ -0,0 +1,744 @@
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::ReadDenyMatcher;
+use codex_protocol::permissions::windows_deny_read_glob_scan;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::collections::HashSet;
+use std::path::PathBuf;
+use std::process::Command;
+
+#[path = "deny_read_walker.rs"]
+mod walker;
+
+use walker::DirectoryScanMode;
+use walker::collect_existing_glob_directory_matches;
+
+#[derive(Debug, Eq, PartialEq)]
+struct GlobScanPlan {
+    root: PathBuf,
+    max_depth: Option<usize>,
+    globs: Vec<String>,
+}
+
+/// Resolve split filesystem `None` read entries into concrete Windows ACL targets.
+///
+/// Windows ACLs do not understand Codex filesystem glob patterns directly. Exact
+/// unreadable roots can be passed through as-is, including paths that do not
+/// exist yet. Glob entries are snapshot-expanded to the files/directories that
+/// already exist under their literal scan root; future exact paths are handled
+/// later by materializing them before the deny ACE is applied.
+pub fn resolve_windows_deny_read_paths(
+    file_system_sandbox_policy: &FileSystemSandboxPolicy,
+    cwd: &AbsolutePathBuf,
+) -> Result<Vec<AbsolutePathBuf>, String> {
+    let mut paths = Vec::new();
+    let mut seen = HashSet::new();
+
+    for path in file_system_sandbox_policy.get_unreadable_roots_with_cwd(cwd.as_path()) {
+        push_absolute_path(&mut paths, &mut seen, path.into_path_buf())?;
+    }
+
+    let unreadable_globs = file_system_sandbox_policy.get_unreadable_globs_with_cwd(cwd.as_path());
+    if unreadable_globs.is_empty() {
+        return Ok(paths);
+    }
+
+    let glob_policy = FileSystemSandboxPolicy::restricted(
+        unreadable_globs
+            .iter()
+            .map(|pattern| FileSystemSandboxEntry {
+                path: FileSystemPath::GlobPattern {
+                    pattern: pattern.clone(),
+                },
+                access: FileSystemAccessMode::Deny,
+                missing_path_behavior: None,
+            })
+            .collect(),
+    );
+    let Some(matcher) = ReadDenyMatcher::try_new_for_local_paths(&glob_policy, cwd.as_path())?
+    else {
+        return Ok(paths);
+    };
+
+    let scan_plans = glob_scan_plans(
+        &unreadable_globs,
+        file_system_sandbox_policy.glob_scan_max_depth,
+    )?;
+
+    for scan_plan in scan_plans {
+        if !scan_plan.root.exists() {
+            continue;
+        }
+
+        let directory_scan_mode = if let Some(file_paths) = ripgrep_files(&scan_plan)? {
+            for path in file_paths {
+                if matcher.is_local_path_read_denied(&path) {
+                    push_absolute_path(&mut paths, &mut seen, path)?;
+                }
+            }
+            DirectoryScanMode::DirectoriesOnly
+        } else {
+            // Rebuild the complete accessible snapshot with the policy matcher
+            // when ripgrep is missing or reports an incomplete traversal. Never
+            // apply ACLs from a failed scan's partial stdout.
+            DirectoryScanMode::IncludeAllFiles
+        };
+
+        collect_existing_glob_directory_matches(
+            &scan_plan.root,
+            &matcher,
+            &mut paths,
+            &mut seen,
+            scan_plan.max_depth,
+            directory_scan_mode,
+        )?;
+    }
+
+    Ok(paths)
+}
+
+fn ripgrep_files(scan_plan: &GlobScanPlan) -> Result<Option<Vec<PathBuf>>, String> {
+    let mut command = Command::new("rg");
+    command
+        .arg("--files")
+        .arg("--hidden")
+        .arg("--no-ignore")
+        .arg("--glob-case-insensitive")
+        .arg("--null");
+    if let Some(max_depth) = scan_plan.max_depth {
+        command.arg("--max-depth").arg(max_depth.to_string());
+    }
+    for glob in &scan_plan.globs {
+        command.arg("--glob").arg(glob);
+    }
+    command.arg("--").arg(&scan_plan.root);
+
+    let output = match command.output() {
+        Ok(output) => output,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(err) => {
+            return Err(format!(
+                "failed to run bundled ripgrep for unreadable glob scan under {}: {err}",
+                scan_plan.root.display()
+            ));
+        }
+    };
+    if !output.status.success() {
+        if output.status.code() == Some(1) && output.stderr.is_empty() {
+            return Ok(Some(Vec::new()));
+        }
+        if output.status.code() == Some(2) {
+            // Ripgrep uses exit 2 for traversal errors, including protected
+            // Windows directories. Its output may be incomplete. The caller
+            // must enumerate again using the matcher-backed walker; policy
+            // syntax has already been validated by
+            // ReadDenyMatcher::try_new_for_local_paths.
+            return Ok(None);
+        }
+
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!(
+            "ripgrep unreadable glob scan failed under {}: {stderr}",
+            scan_plan.root.display()
+        ));
+    }
+
+    output
+        .stdout
+        .split(|byte| *byte == b'\0')
+        .filter(|path| !path.is_empty())
+        .map(|path| {
+            let path = std::str::from_utf8(path).map_err(|err| {
+                format!(
+                    "ripgrep returned a non-UTF-8 path under {}: {err}",
+                    scan_plan.root.display()
+                )
+            })?;
+            let path = PathBuf::from(path);
+            Ok(if path.is_absolute() {
+                path
+            } else {
+                scan_plan.root.join(path)
+            })
+        })
+        .collect::<Result<Vec<_>, _>>()
+        .map(Some)
+}
+
+fn push_absolute_path(
+    paths: &mut Vec<AbsolutePathBuf>,
+    seen: &mut HashSet<PathBuf>,
+    path: PathBuf,
+) -> Result<(), String> {
+    let absolute_path = AbsolutePathBuf::from_absolute_path(dunce::simplified(&path))
+        .map_err(|err| err.to_string())?;
+    if seen.insert(absolute_path.to_path_buf()) {
+        paths.push(absolute_path);
+    }
+    Ok(())
+}
+
+fn glob_scan_plans(
+    patterns: &[String],
+    configured_max_depth: Option<usize>,
+) -> Result<Vec<GlobScanPlan>, String> {
+    let mut scan_plans: Vec<GlobScanPlan> = Vec::new();
+
+    for pattern in patterns {
+        let mut scan_plan = glob_scan_plan(pattern, configured_max_depth);
+        if scan_plan.max_depth.is_none() && scan_plan.root.parent().is_none() {
+            return Err(format!(
+                "unreadable glob `{pattern}` cannot be safely expanded from a filesystem root without `glob_scan_max_depth`; configure `glob_scan_max_depth` or use a non-root directory prefix"
+            ));
+        }
+
+        if let Some(existing) = scan_plans
+            .iter_mut()
+            .find(|existing| existing.root == scan_plan.root)
+        {
+            existing.max_depth = match (existing.max_depth, scan_plan.max_depth) {
+                (Some(existing_depth), Some(new_depth)) => Some(existing_depth.max(new_depth)),
+                _ => None,
+            };
+            existing.globs.append(&mut scan_plan.globs);
+        } else {
+            scan_plans.push(scan_plan);
+        }
+    }
+
+    Ok(scan_plans)
+}
+
+fn glob_scan_plan(pattern: &str, configured_max_depth: Option<usize>) -> GlobScanPlan {
+    let scan = windows_deny_read_glob_scan(pattern, configured_max_depth);
+    GlobScanPlan {
+        root: PathBuf::from(scan.root),
+        max_depth: scan.max_depth,
+        globs: vec![ripgrep_glob(scan.pattern_suffix)],
+    }
+}
+
+fn ripgrep_glob(pattern: &str) -> String {
+    let pattern = pattern.replace('\\', "/");
+    let mut escaped = String::with_capacity(pattern.len());
+    let mut chars = pattern.chars();
+
+    while let Some(ch) = chars.next() {
+        if ch != '[' {
+            escaped.push(ch);
+            continue;
+        }
+
+        let mut class = String::new();
+        let mut closed = false;
+        for class_ch in chars.by_ref() {
+            if class_ch == ']' {
+                closed = true;
+                break;
+            }
+            class.push(class_ch);
+        }
+
+        if closed {
+            escaped.push('[');
+            escaped.push_str(&class);
+            escaped.push(']');
+        } else {
+            escaped.push_str(r"\[");
+            escaped.push_str(&class);
+        }
+    }
+
+    if escaped.starts_with("**/") {
+        escaped
+    } else {
+        format!("**/{escaped}")
+    }
+}
+
+#[cfg(test)]
+#[path = "deny_read_resolver_access_tests.rs"]
+mod access_tests;
+
+#[cfg(test)]
+mod tests {
+    use super::GlobScanPlan;
+    use super::glob_scan_plan;
+    use super::glob_scan_plans;
+    use super::resolve_windows_deny_read_paths;
+    use super::ripgrep_glob;
+    use codex_protocol::permissions::FileSystemAccessMode;
+    use codex_protocol::permissions::FileSystemPath;
+    use codex_protocol::permissions::FileSystemSandboxEntry;
+    use codex_protocol::permissions::FileSystemSandboxPolicy;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashSet;
+    use std::path::PathBuf;
+    use tempfile::TempDir;
+
+    #[cfg(unix)]
+    use std::os::unix::fs::symlink;
+
+    fn unreadable_glob_entry(pattern: String) -> FileSystemSandboxEntry {
+        FileSystemSandboxEntry {
+            path: FileSystemPath::GlobPattern { pattern },
+            access: FileSystemAccessMode::Deny,
+            missing_path_behavior: None,
+        }
+    }
+
+    fn unreadable_path_entry(path: PathBuf) -> FileSystemSandboxEntry {
+        FileSystemSandboxEntry {
+            path: FileSystemPath::Path {
+                path: AbsolutePathBuf::from_absolute_path(path)
+                    .expect("absolute path")
+                    .into(),
+            },
+            access: FileSystemAccessMode::Deny,
+            missing_path_behavior: None,
+        }
+    }
+
+    #[test]
+    fn scan_root_uses_literal_prefix_before_glob() {
+        assert_eq!(
+            glob_scan_plan("/tmp/work/**/*.env", /*configured_max_depth*/ None).root,
+            PathBuf::from("/tmp/work")
+        );
+        assert_eq!(
+            glob_scan_plan(
+                r"C:\Users\dev\repo\**\*.env",
+                /*configured_max_depth*/ None,
+            )
+            .root,
+            PathBuf::from(r"C:\Users\dev\repo")
+        );
+        assert_eq!(
+            glob_scan_plan(r"C:\*.env", /*configured_max_depth*/ None).root,
+            PathBuf::from(r"C:\")
+        );
+    }
+
+    #[test]
+    fn scan_depth_is_bounded_for_non_recursive_globs() {
+        assert_eq!(
+            glob_scan_plan("/tmp/work/*.env", /*configured_max_depth*/ None).max_depth,
+            Some(1)
+        );
+        assert_eq!(
+            glob_scan_plan("/tmp/work/*/*.env", /*configured_max_depth*/ None).max_depth,
+            Some(2)
+        );
+        assert_eq!(
+            glob_scan_plan("/tmp/work/**/*.env", /*configured_max_depth*/ None).max_depth,
+            None
+        );
+    }
+
+    #[test]
+    fn configured_depth_caps_recursive_glob_scans() {
+        assert_eq!(
+            glob_scan_plan("/tmp/work/**/*.env", Some(2)).max_depth,
+            Some(2)
+        );
+        assert_eq!(
+            glob_scan_plan("/tmp/work/*/*.env", Some(1)).max_depth,
+            Some(1)
+        );
+    }
+
+    #[test]
+    fn glob_patterns_with_the_same_root_and_depth_share_one_scan() {
+        assert_eq!(
+            glob_scan_plans(
+                &[
+                    "/tmp/work/**/*.env".to_string(),
+                    "/tmp/work/**/*.pem".to_string(),
+                    "/tmp/work/**/*.secret".to_string(),
+                ],
+                /*configured_max_depth*/ Some(3),
+            )
+            .expect("combined scan plans"),
+            vec![GlobScanPlan {
+                root: PathBuf::from("/tmp/work"),
+                max_depth: Some(3),
+                globs: vec![
+                    "**/*.env".to_string(),
+                    "**/*.pem".to_string(),
+                    "**/*.secret".to_string(),
+                ],
+            }]
+        );
+    }
+
+    #[test]
+    fn bounded_globs_with_the_same_root_share_the_deepest_scan() {
+        assert_eq!(
+            glob_scan_plans(
+                &[
+                    "/tmp/work/*.env".to_string(),
+                    "/tmp/work/*/*.pem".to_string(),
+                ],
+                /*configured_max_depth*/ None,
+            )
+            .expect("combined scan plans"),
+            vec![GlobScanPlan {
+                root: PathBuf::from("/tmp/work"),
+                max_depth: Some(2),
+                globs: vec!["**/*.env".to_string(), "**/*/*.pem".to_string()],
+            }]
+        );
+    }
+
+    #[test]
+    fn recursive_and_bounded_globs_with_the_same_root_share_one_scan() {
+        assert_eq!(
+            glob_scan_plans(
+                &[
+                    "/tmp/work/*.env".to_string(),
+                    "/tmp/work/**/*.pem".to_string(),
+                ],
+                /*configured_max_depth*/ None,
+            )
+            .expect("combined scan plans"),
+            vec![GlobScanPlan {
+                root: PathBuf::from("/tmp/work"),
+                max_depth: None,
+                globs: vec!["**/*.env".to_string(), "**/*.pem".to_string()],
+            }]
+        );
+    }
+
+    #[test]
+    fn project_recursive_globs_without_depth_expand_existing_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let secret = tmp.path().join("nested").join("secret.env");
+        std::fs::create_dir_all(secret.parent().expect("secret parent")).expect("create parent");
+        std::fs::write(&secret, "secret").expect("write secret");
+        let pattern = tmp.path().join("**").join("*.env").display().to_string();
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(pattern)]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("unbounded project glob"),
+            vec![AbsolutePathBuf::from_absolute_path(secret).expect("absolute secret")]
+        );
+    }
+
+    #[test]
+    fn relative_recursive_globs_without_depth_expand_existing_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let secret = tmp.path().join("nested").join("secret.env");
+        std::fs::create_dir_all(secret.parent().expect("secret parent")).expect("create parent");
+        std::fs::write(&secret, "secret").expect("write secret");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(
+            "**/*.env".to_string(),
+        )]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd)
+                .expect("unbounded relative project glob"),
+            vec![AbsolutePathBuf::from_absolute_path(secret).expect("absolute secret")]
+        );
+    }
+
+    #[test]
+    fn root_recursive_globs_without_depth_fail_before_expansion() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let root = cwd.as_path().ancestors().last().expect("filesystem root");
+        let pattern = root.join("**").join("*.env").display().to_string();
+        let policy =
+            FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(pattern.clone())]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect_err("unbounded root glob"),
+            format!(
+                "unreadable glob `{pattern}` cannot be safely expanded from a filesystem root without `glob_scan_max_depth`; configure `glob_scan_max_depth` or use a non-root directory prefix"
+            )
+        );
+    }
+
+    #[test]
+    fn configured_depth_bounds_root_recursive_glob_scans() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let root = cwd.as_path().ancestors().last().expect("filesystem root");
+        let pattern = root.join("**").join("*.env").display().to_string();
+        let scan_plan = glob_scan_plan(&pattern, Some(2));
+
+        assert_eq!(scan_plan.root, root);
+        assert_eq!(scan_plan.max_depth, Some(2));
+    }
+
+    #[test]
+    fn exact_missing_paths_are_preserved() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let missing = tmp.path().join("missing.env");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_path_entry(missing)]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("resolve"),
+            vec![
+                AbsolutePathBuf::from_absolute_path(
+                    dunce::canonicalize(tmp.path())
+                        .expect("canonical tempdir")
+                        .join("missing.env")
+                )
+                .expect("absolute missing")
+            ]
+        );
+    }
+
+    #[test]
+    fn glob_patterns_expand_to_existing_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let root_env = tmp.path().join(".env");
+        let nested_env = tmp.path().join("app").join(".env");
+        let uppercase_env = tmp.path().join("app").join("SECRET.ENV");
+        let notes = tmp.path().join("app").join("notes.txt");
+        std::fs::create_dir_all(notes.parent().expect("parent")).expect("create parent");
+        std::fs::write(&root_env, "secret").expect("write root env");
+        std::fs::write(&nested_env, "secret").expect("write nested env");
+        std::fs::write(&uppercase_env, "secret").expect("write uppercase env");
+        std::fs::write(&notes, "notes").expect("write notes");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(format!(
+            "{}/**/*.env",
+            tmp.path().display()
+        ))]);
+
+        if let Some(paths) = super::ripgrep_files(&GlobScanPlan {
+            root: tmp.path().to_path_buf(),
+            max_depth: None,
+            globs: vec!["**/*.env".to_string()],
+        })
+        .expect("case-insensitive ripgrep scan")
+        {
+            assert!(paths.contains(&uppercase_env));
+        }
+        let actual: HashSet<PathBuf> = resolve_windows_deny_read_paths(&policy, &cwd)
+            .expect("resolve")
+            .into_iter()
+            .map(AbsolutePathBuf::into_path_buf)
+            .collect();
+        let mut expected = [root_env, nested_env].into_iter().collect::<HashSet<_>>();
+        if cfg!(windows) {
+            expected.insert(uppercase_env);
+        }
+
+        assert_eq!(actual, expected);
+    }
+
+    #[test]
+    fn recursive_globs_include_hidden_and_ignored_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let hidden_secret = tmp.path().join("nested").join(".env");
+        let ignored_secret = tmp.path().join("nested").join("ignored.env");
+        std::fs::create_dir_all(hidden_secret.parent().expect("secret parent"))
+            .expect("create parent");
+        std::fs::write(tmp.path().join(".ignore"), "ignored.env\n").expect("write ignore file");
+        std::fs::write(&hidden_secret, "secret").expect("write hidden secret");
+        std::fs::write(&ignored_secret, "secret").expect("write ignored secret");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(
+            "**/*.env".to_string(),
+        )]);
+
+        let actual: HashSet<PathBuf> = resolve_windows_deny_read_paths(&policy, &cwd)
+            .expect("resolve hidden and ignored matches")
+            .into_iter()
+            .map(AbsolutePathBuf::into_path_buf)
+            .collect();
+
+        assert_eq!(
+            actual,
+            [hidden_secret, ignored_secret].into_iter().collect()
+        );
+    }
+
+    #[test]
+    fn recursive_globs_preserve_matching_empty_directories() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let root_secret = tmp.path().join("root.env");
+        let nested_secret = tmp.path().join("nested").join("empty.env");
+        std::fs::create_dir_all(&root_secret).expect("create root secret directory");
+        std::fs::create_dir_all(&nested_secret).expect("create nested secret directory");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(
+            "**/*.env".to_string(),
+        )]);
+
+        let actual: HashSet<PathBuf> = resolve_windows_deny_read_paths(&policy, &cwd)
+            .expect("resolve matching directories")
+            .into_iter()
+            .map(AbsolutePathBuf::into_path_buf)
+            .collect();
+
+        assert_eq!(actual, [root_secret, nested_secret].into_iter().collect());
+    }
+
+    #[test]
+    fn configured_depth_excludes_deeper_recursive_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let shallow_secret = tmp.path().join("shallow.env");
+        let deep_secret = tmp.path().join("nested").join("deep.env");
+        std::fs::create_dir_all(deep_secret.parent().expect("secret parent"))
+            .expect("create parent");
+        std::fs::write(&shallow_secret, "secret").expect("write shallow secret");
+        std::fs::write(&deep_secret, "secret").expect("write deep secret");
+        let mut policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(
+            "**/*.env".to_string(),
+        )]);
+        policy.glob_scan_max_depth = Some(1);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("resolve depth-limited glob"),
+            vec![AbsolutePathBuf::from_absolute_path(shallow_secret).expect("absolute secret")]
+        );
+    }
+
+    #[test]
+    fn recursive_globs_rescan_for_new_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        std::fs::write(tmp.path().join("notes.txt"), "notes").expect("write notes");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(
+            "**/*.env".to_string(),
+        )]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("resolve unmatched glob"),
+            Vec::<AbsolutePathBuf>::new()
+        );
+        let secret = tmp.path().join("new.env");
+        std::fs::write(&secret, "new secret").expect("create matching file");
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("fresh resolution"),
+            vec![AbsolutePathBuf::from_absolute_path(secret).expect("secret path")]
+        );
+    }
+
+    #[test]
+    fn ripgrep_globs_normalize_windows_separators_and_unclosed_classes() {
+        assert_eq!(ripgrep_glob(r"**\*.env"), "**/*.env");
+        assert_eq!(ripgrep_glob("nested/*.env"), "**/nested/*.env");
+        assert_eq!(ripgrep_glob("[*.env"), r"**/\[*.env");
+    }
+
+    #[test]
+    fn shared_scan_roots_preserve_matches_at_each_required_depth() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let env = tmp.path().join(".env");
+        let pem = tmp.path().join("nested").join("credentials.pem");
+        std::fs::create_dir_all(pem.parent().expect("pem parent")).expect("create pem parent");
+        std::fs::write(&env, "secret").expect("write env");
+        std::fs::write(&pem, "secret").expect("write pem");
+        let policy = FileSystemSandboxPolicy::restricted(vec![
+            unreadable_glob_entry(format!("{}/*.env", tmp.path().display())),
+            unreadable_glob_entry(format!("{}/*/*.pem", tmp.path().display())),
+        ]);
+
+        let actual: HashSet<PathBuf> = resolve_windows_deny_read_paths(&policy, &cwd)
+            .expect("resolve shared root")
+            .into_iter()
+            .map(AbsolutePathBuf::into_path_buf)
+            .collect();
+        let expected = [env, pem].into_iter().collect();
+
+        assert_eq!(actual, expected);
+    }
+
+    #[test]
+    fn invalid_glob_patterns_fail_before_expansion() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(format!(
+            "{}/**/[z-a]",
+            tmp.path().display()
+        ))]);
+
+        let err = resolve_windows_deny_read_paths(&policy, &cwd).expect_err("invalid glob");
+        assert!(
+            err.contains("invalid deny-read glob pattern"),
+            "unexpected error: {err}"
+        );
+        assert!(err.contains("invalid range"), "unexpected error: {err}");
+    }
+
+    #[test]
+    fn non_recursive_globs_do_not_expand_nested_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let root_env = tmp.path().join(".env");
+        let nested_env = tmp.path().join("app").join(".env");
+        std::fs::create_dir_all(nested_env.parent().expect("parent")).expect("create parent");
+        std::fs::write(&root_env, "secret").expect("write root env");
+        std::fs::write(&nested_env, "secret").expect("write nested env");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(format!(
+            "{}/*.env",
+            tmp.path().display()
+        ))]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("resolve"),
+            vec![AbsolutePathBuf::from_absolute_path(root_env).expect("absolute root env")]
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn aliased_glob_roots_each_preserve_their_lexical_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let target = tmp.path().join("target");
+        let alias_a = tmp.path().join("alias-a");
+        let alias_b = tmp.path().join("alias-b");
+        let secret = target.join("secret.env");
+        std::fs::create_dir_all(&target).expect("create target");
+        std::fs::write(&secret, "secret").expect("write secret");
+        symlink(&target, &alias_a).expect("create alias a");
+        symlink(&target, &alias_b).expect("create alias b");
+        let policy = FileSystemSandboxPolicy::restricted(vec![
+            unreadable_glob_entry(format!("{}/**/*.env", alias_a.display())),
+            unreadable_glob_entry(format!("{}/**/*.env", alias_b.display())),
+        ]);
+
+        let actual: HashSet<PathBuf> = resolve_windows_deny_read_paths(&policy, &cwd)
+            .expect("resolve")
+            .into_iter()
+            .map(AbsolutePathBuf::into_path_buf)
+            .collect();
+        let expected = [alias_a.join("secret.env"), alias_b.join("secret.env")]
+            .into_iter()
+            .collect();
+
+        assert_eq!(actual, expected);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn recursive_globs_preserve_symlinked_file_matches() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = AbsolutePathBuf::from_absolute_path(tmp.path()).expect("absolute cwd");
+        let target = tmp.path().join("target.txt");
+        let alias = tmp.path().join("linked.env");
+        std::fs::write(&target, "secret").expect("write symlink target");
+        symlink(&target, &alias).expect("create symlink");
+        let policy = FileSystemSandboxPolicy::restricted(vec![unreadable_glob_entry(
+            "**/*.env".to_string(),
+        )]);
+
+        assert_eq!(
+            resolve_windows_deny_read_paths(&policy, &cwd).expect("resolve symlinked secret"),
+            vec![AbsolutePathBuf::from_absolute_path(alias).expect("absolute symlink")]
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/deny_read_resolver_access_tests.rs b/codex-rs/windows-sandbox-rs/src/deny_read_resolver_access_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4e5b7c17764a9680c197c66eb233ffe0494fe722
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/deny_read_resolver_access_tests.rs
@@ -0,0 +1,250 @@
+use super::resolve_windows_deny_read_paths;
+use super::walker::DirectoryScanMode;
+use super::walker::collect_existing_glob_directory_matches;
+use codex_protocol::permissions::FileSystemAccessMode;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::ReadDenyMatcher;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use std::collections::HashSet;
+use std::path::Path;
+use std::path::PathBuf;
+use tempfile::TempDir;
+
+fn policy() -> FileSystemSandboxPolicy {
+    FileSystemSandboxPolicy::restricted(vec![FileSystemSandboxEntry {
+        path: FileSystemPath::GlobPattern {
+            pattern: "**/*.env".to_string(),
+        },
+        access: FileSystemAccessMode::Deny,
+        missing_path_behavior: None,
+    }])
+}
+
+struct ProtectedDirectory {
+    path: PathBuf,
+    #[cfg(unix)]
+    permissions: std::fs::Permissions,
+}
+
+impl ProtectedDirectory {
+    fn new(path: &Path) -> Self {
+        #[cfg(unix)]
+        let permissions = {
+            use std::os::unix::fs::PermissionsExt;
+
+            let permissions = path.metadata().expect("directory metadata").permissions();
+            std::fs::set_permissions(path, std::fs::Permissions::from_mode(/*mode*/ 0o000))
+                .expect("protect directory");
+            permissions
+        };
+        #[cfg(windows)]
+        assert!(
+            std::process::Command::new("icacls.exe")
+                .arg(path)
+                .args(["/deny", "*S-1-1-0:(OI)(CI)R"])
+                .output()
+                .expect("protect directory for every account")
+                .status
+                .success()
+        );
+        Self {
+            path: path.to_path_buf(),
+            #[cfg(unix)]
+            permissions,
+        }
+    }
+}
+
+impl Drop for ProtectedDirectory {
+    fn drop(&mut self) {
+        #[cfg(unix)]
+        std::fs::set_permissions(&self.path, self.permissions.clone())
+            .expect("restore directory permissions");
+        #[cfg(windows)]
+        assert!(
+            std::process::Command::new("icacls.exe")
+                .arg(&self.path)
+                .args(["/remove:d", "*S-1-1-0"])
+                .output()
+                .expect("restore directory permissions")
+                .status
+                .success()
+        );
+    }
+}
+
+#[test]
+fn protected_directory_does_not_discard_accessible_deny_matches() {
+    #[cfg(windows)]
+    if let Some(root) = std::env::var_os("CODEX_TEST_DENY_READ_RESTRICTED_ROOT") {
+        assert_accessible_deny_matches(Path::new(&root));
+        return;
+    }
+
+    let temp = TempDir::new().expect("tempdir");
+    let protected = temp.path().join("protected");
+    let readable = temp.path().join("readable");
+    std::fs::create_dir(&protected).expect("protected directory");
+    std::fs::create_dir(&readable).expect("readable directory");
+    std::fs::write(protected.join("hidden.env"), "protected").expect("protected file");
+    std::fs::write(readable.join("secret.env"), "secret").expect("readable secret");
+    std::fs::create_dir(readable.join("empty.env")).expect("matching empty directory");
+    std::fs::write(readable.join("public.txt"), "public").expect("public file");
+    let guard = ProtectedDirectory::new(&protected);
+
+    #[cfg(windows)]
+    {
+        // CI enables backup privileges, which let directory enumeration bypass
+        // this fixture's ACL. Restrict a separate process, including its rg child,
+        // rather than changing the shared test process's privileges. The parent
+        // owns ACL setup and cleanup, which the restricted child cannot perform.
+        let codex_home = TempDir::new().expect("restricted codex home");
+        let cwd = AbsolutePathBuf::from_absolute_path(temp.path()).expect("workspace");
+        let mut env = std::collections::HashMap::from([
+            (
+                "CODEX_TEST_DENY_READ_RESTRICTED_ROOT".to_string(),
+                cwd.display().to_string(),
+            ),
+            ("TEMP".to_string(), cwd.display().to_string()),
+            ("TMP".to_string(), cwd.display().to_string()),
+        ]);
+        for name in ["PATH", "SystemRoot", "COMSPEC", "USERPROFILE"] {
+            if let Ok(value) = std::env::var(name) {
+                env.insert(name.to_string(), value);
+            }
+        }
+        let result = crate::run_windows_sandbox_capture(
+            &codex_protocol::models::PermissionProfile::workspace_write(),
+            std::slice::from_ref(&cwd),
+            codex_home.path(),
+            vec![
+                std::env::current_exe()
+                    .expect("test binary")
+                    .display()
+                    .to_string(),
+                "--exact".to_string(),
+                std::thread::current()
+                    .name()
+                    .expect("test name")
+                    .to_string(),
+            ],
+            cwd.as_path(),
+            env,
+            /*timeout_ms*/ Some(30_000),
+            /*cancellation*/ None,
+            /*use_private_desktop*/ true,
+        )
+        .expect("run protected-directory regression without backup privileges");
+        let stdout = String::from_utf8_lossy(&result.stdout);
+        let stderr = String::from_utf8_lossy(&result.stderr);
+        assert_eq!(
+            (result.exit_code, result.timed_out),
+            (0, false),
+            "{stdout}\n{stderr}"
+        );
+        assert!(stdout.contains("test result: ok. 1 passed"), "{stdout}");
+    }
+
+    #[cfg(not(windows))]
+    assert_accessible_deny_matches(temp.path());
+    drop(guard);
+}
+
+fn assert_accessible_deny_matches(root: &Path) {
+    let cwd = AbsolutePathBuf::from_absolute_path(root).expect("cwd");
+    let protected = root.join("protected");
+    let enumeration = std::fs::read_dir(&protected)
+        .and_then(std::iter::Iterator::collect::<std::io::Result<Vec<_>>>);
+    assert_eq!(
+        enumeration
+            .expect_err("fixture must deny directory enumeration")
+            .kind(),
+        std::io::ErrorKind::PermissionDenied
+    );
+
+    let actual = resolve_windows_deny_read_paths(&policy(), &cwd)
+        .expect("protected branches must not abort expansion of accessible paths")
+        .into_iter()
+        .map(AbsolutePathBuf::into_path_buf)
+        .collect::<HashSet<_>>();
+    assert_eq!(
+        actual,
+        HashSet::from([
+            root.join("readable/secret.env"),
+            root.join("readable/empty.env"),
+        ])
+    );
+}
+
+#[test]
+fn native_walk_preserves_canonical_matches_through_directory_links_and_cycles() {
+    let temp = TempDir::new().expect("tempdir");
+    let cwd = AbsolutePathBuf::from_absolute_path(temp.path()).expect("cwd");
+    let walk = temp.path().join("walk");
+    let target = temp.path().join("target");
+    std::fs::create_dir(&walk).expect("walk root");
+    std::fs::create_dir(&target).expect("link target");
+    std::fs::write(target.join("secret.env"), "secret").expect("secret");
+    std::fs::write(target.join("public.txt"), "public").expect("public");
+    let alias = walk.join("alias");
+    let cycle = target.join("cycle");
+    for (link, destination) in [(&alias, &target), (&cycle, &walk)] {
+        #[cfg(unix)]
+        std::os::unix::fs::symlink(destination, link).expect("directory symlink");
+        #[cfg(windows)]
+        assert!(
+            std::process::Command::new("cmd.exe")
+                .args(["/d", "/c", "mklink", "/J"])
+                .arg(link)
+                .arg(destination)
+                .output()
+                .expect("directory junction")
+                .status
+                .success()
+        );
+    }
+    let policy = FileSystemSandboxPolicy::restricted(vec![FileSystemSandboxEntry {
+        path: FileSystemPath::GlobPattern {
+            pattern: target
+                .canonicalize()
+                .expect("canonical target")
+                .join("**")
+                .join("*.env")
+                .display()
+                .to_string(),
+        },
+        access: FileSystemAccessMode::Deny,
+        missing_path_behavior: None,
+    }]);
+    let matcher = ReadDenyMatcher::try_new_for_local_paths(&policy, cwd.as_path())
+        .expect("valid matcher")
+        .expect("deny restriction");
+    assert!(
+        matcher.is_local_path_read_denied_with_canonical_path(
+            &alias.join("secret.env"),
+            &target
+                .canonicalize()
+                .expect("canonical target")
+                .join("secret.env"),
+        )
+    );
+    let mut paths = Vec::new();
+    collect_existing_glob_directory_matches(
+        &walk,
+        &matcher,
+        &mut paths,
+        &mut HashSet::new(),
+        /*max_depth*/ None,
+        DirectoryScanMode::IncludeAllFiles,
+    )
+    .expect("walk through directory alias and cycle");
+    assert_eq!(
+        paths,
+        vec![
+            AbsolutePathBuf::from_absolute_path(alias.join("secret.env")).expect("lexical target")
+        ]
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/deny_read_state.rs b/codex-rs/windows-sandbox-rs/src/deny_read_state.rs
new file mode 100644
index 0000000000000000000000000000000000000000..274ff004e9f580f9d6e00ba54263c901b421d79e
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/deny_read_state.rs
@@ -0,0 +1,87 @@
+use crate::acl::revoke_ace;
+use crate::deny_read_acl::apply_deny_read_acls;
+use crate::deny_read_acl::lexical_path_key;
+use crate::setup::sandbox_dir;
+use anyhow::Context;
+use anyhow::Result;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::BTreeMap;
+use std::collections::HashSet;
+use std::ffi::c_void;
+use std::path::Path;
+use std::path::PathBuf;
+
+const DENY_READ_ACL_STATE_FILE: &str = "deny_read_acl_state.json";
+
+#[derive(Default, Deserialize, Serialize)]
+struct PersistentDenyReadAclState {
+    principals: BTreeMap<String, Vec<PathBuf>>,
+}
+
+/// Reconciles the persistent deny-read ACEs owned by one sandbox principal.
+///
+/// Workspace-write and elevated sandbox sessions intentionally leave ACLs in
+/// place after a command exits, because descendants may outlive the launcher.
+/// That makes the ACL set stateful across runs. Persist the paths applied for
+/// each SID, apply the new desired set first, and only then revoke stale paths
+/// from the same SID so profile changes do not leave old deny-read ACEs behind.
+///
+/// # Safety
+/// Caller must pass a valid SID pointer matching `principal_sid`.
+pub unsafe fn sync_persistent_deny_read_acls(
+    codex_home: &Path,
+    principal_sid: &str,
+    desired_paths: &[PathBuf],
+    psid: *mut c_void,
+) -> Result<Vec<PathBuf>> {
+    let state_path = sandbox_dir(codex_home).join(DENY_READ_ACL_STATE_FILE);
+    let mut state = load_state(&state_path)?;
+    let previous_paths = state
+        .principals
+        .get(principal_sid)
+        .cloned()
+        .unwrap_or_default();
+
+    let applied_paths = unsafe { apply_deny_read_acls(desired_paths, psid) }?;
+    let desired_keys = applied_paths
+        .iter()
+        .map(|path| lexical_path_key(path))
+        .collect::<HashSet<_>>();
+
+    for path in previous_paths {
+        if !desired_keys.contains(&lexical_path_key(&path)) {
+            let _ = revoke_ace(&path, psid);
+        }
+    }
+
+    if applied_paths.is_empty() {
+        state.principals.remove(principal_sid);
+    } else {
+        state
+            .principals
+            .insert(principal_sid.to_string(), applied_paths.clone());
+    }
+    store_state(&state_path, &state)?;
+
+    Ok(applied_paths)
+}
+
+fn load_state(path: &Path) -> Result<PersistentDenyReadAclState> {
+    match std::fs::read(path) {
+        Ok(bytes) => serde_json::from_slice(&bytes)
+            .with_context(|| format!("parse deny-read ACL state {}", path.display())),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
+            Ok(PersistentDenyReadAclState::default())
+        }
+        Err(err) => {
+            Err(err).with_context(|| format!("read deny-read ACL state {}", path.display()))
+        }
+    }
+}
+
+fn store_state(path: &Path, state: &PersistentDenyReadAclState) -> Result<()> {
+    let bytes = serde_json::to_vec_pretty(state).context("serialize deny-read ACL state")?;
+    std::fs::write(path, bytes)
+        .with_context(|| format!("write deny-read ACL state {}", path.display()))
+}
diff --git a/codex-rs/windows-sandbox-rs/src/deny_read_walker.rs b/codex-rs/windows-sandbox-rs/src/deny_read_walker.rs
new file mode 100644
index 0000000000000000000000000000000000000000..dd1b6e3cca3df6a02bda0600f2c54627af798877
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/deny_read_walker.rs
@@ -0,0 +1,151 @@
+//! Matcher-backed snapshot traversal for Windows deny-read ACL targets.
+//!
+//! The accessible-directory behavior is the same as the original native
+//! resolver: disappearing and inaccessible branches cannot be enumerated, but
+//! a matching directory is retained before reading its children. This does not
+//! grant access to a skipped branch. Unexpected I/O errors abort the snapshot.
+//! Canonical parents are reused only within this walk; links are resolved anew.
+
+use super::push_absolute_path;
+use codex_protocol::permissions::ReadDenyMatcher;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::collections::HashSet;
+use std::fs::FileType;
+use std::io;
+use std::path::Path;
+use std::path::PathBuf;
+
+#[derive(Clone, Copy)]
+pub(super) enum DirectoryScanMode {
+    DirectoriesOnly,
+    IncludeAllFiles,
+}
+
+pub(super) fn collect_existing_glob_directory_matches(
+    root: &Path,
+    matcher: &ReadDenyMatcher,
+    paths: &mut Vec<AbsolutePathBuf>,
+    seen_paths: &mut HashSet<PathBuf>,
+    max_depth: Option<usize>,
+    mode: DirectoryScanMode,
+) -> Result<(), String> {
+    let Some(metadata) = accessible_entry(root.metadata(), root)? else {
+        return Ok(());
+    };
+    let canonical = accessible_entry(root.canonicalize(), root)?;
+    let mut walker = GlobWalker {
+        matcher,
+        paths,
+        seen_paths,
+        seen_directories: HashSet::new(),
+        max_depth,
+    };
+    walker.visit(
+        root,
+        canonical.as_deref(),
+        metadata.file_type(),
+        /*depth*/ 0,
+        mode,
+    )
+}
+
+struct GlobWalker<'a> {
+    matcher: &'a ReadDenyMatcher,
+    paths: &'a mut Vec<AbsolutePathBuf>,
+    seen_paths: &'a mut HashSet<PathBuf>,
+    seen_directories: HashSet<PathBuf>,
+    max_depth: Option<usize>,
+}
+
+impl GlobWalker<'_> {
+    fn visit(
+        &mut self,
+        path: &Path,
+        canonical: Option<&Path>,
+        file_type: FileType,
+        depth: usize,
+        mode: DirectoryScanMode,
+    ) -> Result<(), String> {
+        let denied = match canonical {
+            Some(canonical) => self
+                .matcher
+                .is_local_path_read_denied_with_canonical_path(path, canonical),
+            None => self.matcher.is_local_path_read_denied(path),
+        };
+        if denied {
+            push_absolute_path(self.paths, self.seen_paths, path.to_path_buf())?;
+        }
+        if !file_type.is_dir()
+            || self.max_depth.is_some_and(|limit| depth >= limit)
+            || !self
+                .seen_directories
+                .insert(canonical.unwrap_or(path).to_path_buf())
+        {
+            return Ok(());
+        }
+        let Some(entries) = accessible_entry(std::fs::read_dir(path), path)? else {
+            return Ok(());
+        };
+        for entry in entries {
+            let Some(entry) = accessible_entry(entry, path)? else {
+                continue;
+            };
+            let entry_path = entry.path();
+            let Some(file_type) = accessible_entry(entry.file_type(), &entry_path)? else {
+                continue;
+            };
+            if file_type.is_symlink() {
+                // Name-surrogate reparse points (including Windows junctions)
+                // cannot inherit the parent's canonical location. Resolve the
+                // target, then retain lexical matches and detect target cycles.
+                let target = accessible_entry(entry_path.canonicalize(), &entry_path)?;
+                let Some(metadata) = accessible_entry(entry_path.metadata(), &entry_path)? else {
+                    continue;
+                };
+                self.visit(
+                    &entry_path,
+                    target.as_deref(),
+                    metadata.file_type(),
+                    depth + 1,
+                    DirectoryScanMode::IncludeAllFiles,
+                )?;
+            } else if file_type.is_dir() || matches!(mode, DirectoryScanMode::IncludeAllFiles) {
+                // Directory entries already carry their type on Windows. A
+                // normal child has the resolved parent's location plus its
+                // enumerated name; do not stat/canonicalize every ordinary file.
+                self.visit(
+                    &entry_path,
+                    canonical
+                        .map(|parent| parent.join(entry.file_name()))
+                        .as_deref(),
+                    file_type,
+                    depth + 1,
+                    mode,
+                )?;
+            }
+        }
+        Ok(())
+    }
+}
+
+fn accessible_entry<T>(result: io::Result<T>, path: &Path) -> Result<Option<T>, String> {
+    match result {
+        Ok(value) => Ok(Some(value)),
+        Err(err)
+            if matches!(
+                err.kind(),
+                io::ErrorKind::NotFound | io::ErrorKind::PermissionDenied
+            ) =>
+        {
+            Ok(None)
+        }
+        Err(err) => Err(format!(
+            "failed to enumerate unreadable glob paths under {}: {err}",
+            path.display()
+        )),
+    }
+}
+
+#[cfg(test)]
+#[path = "deny_read_walker_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/deny_read_walker_tests.rs b/codex-rs/windows-sandbox-rs/src/deny_read_walker_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8836197762be94a5181b37ba8cb827a3fdd7b816
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/deny_read_walker_tests.rs
@@ -0,0 +1,17 @@
+use super::accessible_entry;
+use pretty_assertions::assert_eq;
+use std::io;
+use std::path::Path;
+
+#[test]
+fn unexpected_io_errors_abort_the_snapshot() {
+    let error = io::Error::other("directory read interrupted");
+
+    assert_eq!(
+        accessible_entry::<()>(Err(error), Path::new("scan-root")),
+        Err(
+            "failed to enumerate unreadable glob paths under scan-root: directory read interrupted"
+                .to_string()
+        )
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/desktop.rs b/codex-rs/windows-sandbox-rs/src/desktop.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4311ba07036e6fca1fe8ab14e3c458c10d48cd79
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/desktop.rs
@@ -0,0 +1,477 @@
+use crate::allow::compute_allow_paths_for_permissions;
+use crate::deny_read_acl::plan_deny_read_acl_paths;
+use crate::logging;
+use crate::path_normalization::canonicalize_path;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::setup::SandboxSetupRequest;
+use crate::setup::SetupRootOverrides;
+use crate::setup::build_payload_deny_write_paths;
+use crate::setup::build_payload_roots;
+use crate::setup::gather_read_roots;
+use crate::spawn_prep::LegacySessionSecurity;
+use crate::token::get_current_token_for_restriction;
+use crate::token::get_logon_sid_bytes;
+use crate::token::get_user_sid_bytes;
+use crate::winutil::format_last_error;
+use crate::winutil::resolve_sid;
+use crate::winutil::sid_bytes_from_string;
+use crate::winutil::string_from_sid_bytes;
+use crate::winutil::to_wide;
+use anyhow::Result;
+use rand::Rng;
+use rand::SeedableRng;
+use rand::rngs::SmallRng;
+use std::collections::BTreeSet;
+use std::collections::HashMap;
+use std::ffi::c_void;
+use std::path::Path;
+use std::path::PathBuf;
+use std::ptr;
+use std::sync::Mutex;
+use std::sync::OnceLock;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::Authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW;
+use windows_sys::Win32::Security::Authorization::EXPLICIT_ACCESS_W;
+use windows_sys::Win32::Security::Authorization::GRANT_ACCESS;
+use windows_sys::Win32::Security::Authorization::SE_WINDOW_OBJECT;
+use windows_sys::Win32::Security::Authorization::SetEntriesInAclW;
+use windows_sys::Win32::Security::Authorization::SetSecurityInfo;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_SID;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_UNKNOWN;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_W;
+use windows_sys::Win32::Security::DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Security::PSECURITY_DESCRIPTOR;
+use windows_sys::Win32::Security::SECURITY_ATTRIBUTES;
+use windows_sys::Win32::System::StationsAndDesktops::CloseDesktop;
+use windows_sys::Win32::System::StationsAndDesktops::CreateDesktopW;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_CREATEMENU;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_CREATEWINDOW;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_DELETE;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_ENUMERATE;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_HOOKCONTROL;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_JOURNALPLAYBACK;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_JOURNALRECORD;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_READ_CONTROL;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_READOBJECTS;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_SWITCHDESKTOP;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_WRITE_DAC;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_WRITE_OWNER;
+use windows_sys::Win32::System::StationsAndDesktops::DESKTOP_WRITEOBJECTS;
+use windows_sys::Win32::System::StationsAndDesktops::OpenDesktopW;
+
+const PRIVATE_DESKTOP_PREFIX: &str = "CodexSandboxDesktop-";
+
+const DESKTOP_ALL_ACCESS: u32 = DESKTOP_READOBJECTS
+    | DESKTOP_CREATEWINDOW
+    | DESKTOP_CREATEMENU
+    | DESKTOP_HOOKCONTROL
+    | DESKTOP_JOURNALRECORD
+    | DESKTOP_JOURNALPLAYBACK
+    | DESKTOP_ENUMERATE
+    | DESKTOP_WRITEOBJECTS
+    | DESKTOP_SWITCHDESKTOP
+    | DESKTOP_DELETE
+    | DESKTOP_READ_CONTROL
+    | DESKTOP_WRITE_DAC
+    | DESKTOP_WRITE_OWNER;
+
+const DESKTOP_PARTICIPANT_ACCESS: u32 =
+    DESKTOP_ALL_ACCESS & !(DESKTOP_WRITE_DAC | DESKTOP_WRITE_OWNER | DESKTOP_DELETE);
+
+static SHARED_PRIVATE_DESKTOPS: OnceLock<Mutex<HashMap<(String, DesktopPolicy), PrivateDesktop>>> =
+    OnceLock::new();
+
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub(crate) struct DesktopPolicy {
+    uses_write_capabilities: bool,
+    capability_sids: BTreeSet<Vec<u8>>,
+    network_enabled: bool,
+    network_proxy_restricting_sid: Option<Vec<u8>>,
+    // None denotes the legacy backend's unrestricted reads and different desktop ACLs.
+    read_roots: Option<BTreeSet<PathBuf>>,
+    write_roots: BTreeSet<PathBuf>,
+    deny_read_paths: BTreeSet<PathBuf>,
+    deny_write_paths: BTreeSet<PathBuf>,
+}
+
+impl DesktopPolicy {
+    pub(crate) fn elevated(
+        request: SandboxSetupRequest<'_>,
+        mut overrides: SetupRootOverrides,
+        capability_sids: &[String],
+        network_proxy_restricting_sid: Option<&str>,
+    ) -> Result<Self> {
+        // Match the complete read override passed by credential setup to the ACL helper.
+        let runtime = crate::setup::current_setup_runtime();
+        overrides.read_roots.get_or_insert_with(|| {
+            gather_read_roots(
+                request.command_cwd,
+                request.permissions,
+                request.env_map,
+                request.codex_home,
+                runtime,
+            )
+        });
+        let (read_roots, write_roots) = build_payload_roots(&request, &overrides, runtime);
+        Ok(Self {
+            uses_write_capabilities: request
+                .permissions
+                .uses_write_capabilities_for_cwd(request.command_cwd, request.env_map),
+            capability_sids: capability_sids
+                .iter()
+                .map(|sid| sid_bytes_from_string(sid))
+                .collect::<Result<_>>()?,
+            network_enabled: request.permissions.network_policy().is_enabled(),
+            network_proxy_restricting_sid: network_proxy_restricting_sid
+                .map(sid_bytes_from_string)
+                .transpose()?,
+            read_roots: Some(read_roots.into_iter().collect()),
+            write_roots: write_roots.into_iter().collect(),
+            deny_read_paths: plan_deny_read_acl_paths(
+                overrides.deny_read_paths.as_deref().unwrap_or_default(),
+            )?
+            .into_iter()
+            .collect(),
+            deny_write_paths: build_payload_deny_write_paths(&request, overrides.deny_write_paths)
+                .into_iter()
+                .map(|path| canonicalize_path(&path))
+                .collect(),
+        })
+    }
+}
+
+pub struct LaunchDesktop {
+    _private_desktop: Option<PrivateDesktop>,
+    startup_name: Vec<u16>,
+}
+
+impl LaunchDesktop {
+    pub(crate) fn prepare_legacy(
+        use_private_desktop: bool,
+        permissions: &ResolvedWindowsSandboxPermissions,
+        cwd: &Path,
+        env: &HashMap<String, String>,
+        security: &LegacySessionSecurity,
+        additional_deny_write_paths: &[PathBuf],
+        logs_base_dir: Option<&Path>,
+    ) -> Result<Self> {
+        if !use_private_desktop {
+            return Self::prepare(/*use_private_desktop*/ false, logs_base_dir);
+        }
+        Self::open_private(&Self::shared_legacy_name(
+            permissions,
+            cwd,
+            env,
+            security,
+            additional_deny_write_paths,
+            logs_base_dir,
+        )?)
+    }
+
+    pub(crate) fn shared_legacy_name(
+        permissions: &ResolvedWindowsSandboxPermissions,
+        cwd: &Path,
+        env: &HashMap<String, String>,
+        security: &LegacySessionSecurity,
+        additional_deny_write_paths: &[PathBuf],
+        logs_base_dir: Option<&Path>,
+    ) -> Result<String> {
+        let sandbox_sid = unsafe { get_user_sid_bytes(security.h_token)? };
+        let sandbox_sid = string_from_sid_bytes(&sandbox_sid).map_err(anyhow::Error::msg)?;
+        let paths = compute_allow_paths_for_permissions(permissions, cwd, env);
+        let policy = DesktopPolicy {
+            uses_write_capabilities: security.readonly_sid.is_none(),
+            capability_sids: security
+                .readonly_sid_str
+                .iter()
+                .chain(security.write_root_sids.iter().map(|root| &root.sid_str))
+                .map(|sid| sid_bytes_from_string(sid))
+                .collect::<Result<_>>()?,
+            network_enabled: permissions.network_policy().is_enabled(),
+            network_proxy_restricting_sid: None,
+            read_roots: None,
+            write_roots: paths.allow.into_iter().collect(),
+            deny_read_paths: BTreeSet::new(),
+            deny_write_paths: paths
+                .deny
+                .into_iter()
+                .chain(additional_deny_write_paths.iter().cloned())
+                .map(|path| canonicalize_path(&path))
+                .collect(),
+        };
+        let mut desktops = SHARED_PRIVATE_DESKTOPS
+            .get_or_init(|| Mutex::new(HashMap::new()))
+            .lock()
+            .map_err(|_| anyhow::anyhow!("shared private desktop cache was poisoned"))?;
+        let desktop = match desktops.entry((sandbox_sid, policy)) {
+            std::collections::hash_map::Entry::Occupied(entry) => entry.into_mut(),
+            std::collections::hash_map::Entry::Vacant(entry) => {
+                entry.insert(PrivateDesktop::create(logs_base_dir)?)
+            }
+        };
+        Ok(desktop.name.clone())
+    }
+
+    pub fn prepare(use_private_desktop: bool, logs_base_dir: Option<&Path>) -> Result<Self> {
+        if use_private_desktop {
+            let private_desktop = PrivateDesktop::create(logs_base_dir)?;
+            let startup_name = to_wide(format!("Winsta0\\{}", private_desktop.name));
+            Ok(Self {
+                _private_desktop: Some(private_desktop),
+                startup_name,
+            })
+        } else {
+            Ok(Self {
+                _private_desktop: None,
+                startup_name: to_wide("Winsta0\\Default"),
+            })
+        }
+    }
+
+    /// Opens the caller-owned private desktop without creating one or falling back to Default.
+    pub fn open_private(name: &str) -> Result<Self> {
+        if !name
+            .strip_prefix(PRIVATE_DESKTOP_PREFIX)
+            .is_some_and(|nonce| {
+                !nonce.is_empty()
+                    && nonce.len() <= 32
+                    && nonce.bytes().all(|byte| byte.is_ascii_hexdigit())
+            })
+        {
+            anyhow::bail!("invalid private desktop name");
+        }
+        let name_wide = to_wide(name);
+        let handle = unsafe {
+            OpenDesktopW(
+                name_wide.as_ptr(),
+                /*dwflags*/ 0,
+                /*finherit*/ 0,
+                DESKTOP_PARTICIPANT_ACCESS,
+            )
+        };
+        if handle == 0 {
+            anyhow::bail!("OpenDesktopW failed: {}", unsafe { GetLastError() });
+        }
+        Ok(Self {
+            _private_desktop: Some(PrivateDesktop {
+                handle,
+                name: name.to_owned(),
+            }),
+            startup_name: to_wide(format!("Winsta0\\{name}")),
+        })
+    }
+
+    pub fn startup_info_desktop(&self) -> *mut u16 {
+        self.startup_name.as_ptr() as *mut u16
+    }
+}
+
+/// Reuses a private desktop only for the same sandbox account and effective permissions.
+pub(crate) fn shared_private_desktop_for_user(
+    sandbox_username: &str,
+    policy: &DesktopPolicy,
+    logs_base_dir: Option<&Path>,
+) -> Result<String> {
+    let sandbox_sid =
+        string_from_sid_bytes(&resolve_sid(sandbox_username)?).map_err(anyhow::Error::msg)?;
+    let mut desktops = SHARED_PRIVATE_DESKTOPS
+        .get_or_init(|| Mutex::new(HashMap::new()))
+        .lock()
+        .map_err(|_| anyhow::anyhow!("shared private desktop cache was poisoned"))?;
+    let key = (sandbox_sid.clone(), policy.clone());
+    if let Some(desktop) = desktops.get(&key) {
+        return Ok(desktop.name.clone());
+    }
+
+    let owner_user_sid = unsafe {
+        let token = get_current_token_for_restriction()?;
+        let sid = get_user_sid_bytes(token);
+        CloseHandle(token);
+        sid?
+    };
+    let owner_user_sid = string_from_sid_bytes(&owner_user_sid).map_err(anyhow::Error::msg)?;
+    // CreateProcessWithLogonW shares the caller's logon SID with the sandbox account.
+    // Grant ACL-management rights to the caller's user SID instead.
+    // https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createprocesswithlogonw
+    let sddl = to_wide(format!(
+        "D:P(A;;0x{DESKTOP_ALL_ACCESS:x};;;{owner_user_sid})(A;;0x{DESKTOP_PARTICIPANT_ACCESS:x};;;{sandbox_sid})"
+    ));
+    let mut security_descriptor: PSECURITY_DESCRIPTOR = ptr::null_mut();
+    if unsafe {
+        ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            sddl.as_ptr(),
+            /*stringsdrevision*/ 1,
+            &mut security_descriptor,
+            ptr::null_mut(),
+        )
+    } == 0
+    {
+        anyhow::bail!(
+            "ConvertStringSecurityDescriptorToSecurityDescriptorW failed: {}",
+            unsafe { GetLastError() }
+        );
+    }
+
+    let attributes = SECURITY_ATTRIBUTES {
+        nLength: std::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
+        lpSecurityDescriptor: security_descriptor,
+        bInheritHandle: 0,
+    };
+    let mut rng = SmallRng::from_entropy();
+    let name = format!("{PRIVATE_DESKTOP_PREFIX}{:032x}", rng.r#gen::<u128>());
+    let name_wide = to_wide(&name);
+    let handle = unsafe {
+        CreateDesktopW(
+            name_wide.as_ptr(),
+            ptr::null(),
+            ptr::null_mut(),
+            /*dwflags*/ 0,
+            DESKTOP_ALL_ACCESS,
+            &attributes,
+        )
+    };
+    let error = unsafe { GetLastError() };
+    unsafe {
+        LocalFree(security_descriptor as HLOCAL);
+    }
+    if handle == 0 {
+        logging::debug_log(
+            &format!("CreateDesktopW failed for shared private desktop: {error}"),
+            logs_base_dir,
+        );
+        anyhow::bail!("CreateDesktopW failed for shared private desktop: {error}");
+    }
+
+    // Retain ownership across runner exits and idle gaps; different policies stay on separate
+    // desktops so GUI hooks do not automatically cross those policies.
+    desktops.insert(
+        key,
+        PrivateDesktop {
+            handle,
+            name: name.clone(),
+        },
+    );
+    Ok(name)
+}
+
+struct PrivateDesktop {
+    handle: isize,
+    name: String,
+}
+
+impl PrivateDesktop {
+    fn create(logs_base_dir: Option<&Path>) -> Result<Self> {
+        let mut rng = SmallRng::from_entropy();
+        let name = format!("CodexSandboxDesktop-{:x}", rng.r#gen::<u128>());
+        let name_wide = to_wide(&name);
+        let handle = unsafe {
+            CreateDesktopW(
+                name_wide.as_ptr(),
+                ptr::null(),
+                ptr::null_mut(),
+                0,
+                DESKTOP_ALL_ACCESS,
+                ptr::null_mut(),
+            )
+        };
+        if handle == 0 {
+            let err = unsafe { GetLastError() } as i32;
+            logging::debug_log(
+                &format!(
+                    "CreateDesktopW failed for {name}: {} ({})",
+                    err,
+                    format_last_error(err),
+                ),
+                logs_base_dir,
+            );
+            return Err(anyhow::anyhow!("CreateDesktopW failed: {err}"));
+        }
+
+        unsafe {
+            if let Err(err) = grant_desktop_access(handle, logs_base_dir) {
+                let _ = CloseDesktop(handle);
+                return Err(err);
+            }
+        }
+
+        Ok(Self { handle, name })
+    }
+}
+
+unsafe fn grant_desktop_access(handle: isize, logs_base_dir: Option<&Path>) -> Result<()> {
+    let token = get_current_token_for_restriction()?;
+    let mut logon_sid = get_logon_sid_bytes(token)?;
+    CloseHandle(token);
+
+    let entries = [EXPLICIT_ACCESS_W {
+        grfAccessPermissions: DESKTOP_ALL_ACCESS,
+        grfAccessMode: GRANT_ACCESS,
+        grfInheritance: 0,
+        Trustee: TRUSTEE_W {
+            pMultipleTrustee: ptr::null_mut(),
+            MultipleTrusteeOperation: 0,
+            TrusteeForm: TRUSTEE_IS_SID,
+            TrusteeType: TRUSTEE_IS_UNKNOWN,
+            ptstrName: logon_sid.as_mut_ptr() as *mut c_void as *mut u16,
+        },
+    }];
+
+    let mut updated_dacl = ptr::null_mut();
+    let set_entries_code = SetEntriesInAclW(
+        entries.len() as u32,
+        entries.as_ptr(),
+        ptr::null_mut(),
+        &mut updated_dacl,
+    );
+    if set_entries_code != ERROR_SUCCESS {
+        logging::debug_log(
+            &format!("SetEntriesInAclW failed for private desktop: {set_entries_code}"),
+            logs_base_dir,
+        );
+        return Err(anyhow::anyhow!(
+            "SetEntriesInAclW failed for private desktop: {set_entries_code}"
+        ));
+    }
+
+    let set_security_code = SetSecurityInfo(
+        handle,
+        SE_WINDOW_OBJECT,
+        DACL_SECURITY_INFORMATION,
+        ptr::null_mut(),
+        ptr::null_mut(),
+        updated_dacl,
+        ptr::null_mut(),
+    );
+    if !updated_dacl.is_null() {
+        LocalFree(updated_dacl as HLOCAL);
+    }
+    if set_security_code != ERROR_SUCCESS {
+        logging::debug_log(
+            &format!("SetSecurityInfo failed for private desktop: {set_security_code}"),
+            logs_base_dir,
+        );
+        return Err(anyhow::anyhow!(
+            "SetSecurityInfo failed for private desktop: {set_security_code}"
+        ));
+    }
+
+    Ok(())
+}
+
+impl Drop for PrivateDesktop {
+    fn drop(&mut self) {
+        unsafe {
+            if self.handle != 0 {
+                let _ = CloseDesktop(self.handle);
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "desktop_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/desktop_tests.rs b/codex-rs/windows-sandbox-rs/src/desktop_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2c8f35c9616ca1993e987601e1ed32a7603dd512
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/desktop_tests.rs
@@ -0,0 +1,242 @@
+use super::DesktopPolicy;
+use super::LaunchDesktop;
+use super::PRIVATE_DESKTOP_PREFIX;
+use super::shared_private_desktop_for_user;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::setup::SandboxSetupRequest;
+use crate::setup::SetupRootOverrides;
+use crate::spawn_prep::legacy_session_capability_roots;
+use crate::spawn_prep::prepare_legacy_session_security;
+use anyhow::Result;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use rand::Rng;
+use rand::SeedableRng;
+use rand::rngs::SmallRng;
+use std::collections::HashMap;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use tempfile::TempDir;
+use windows_sys::Win32::NetworkManagement::NetManagement::DNLEN;
+use windows_sys::Win32::NetworkManagement::NetManagement::UNLEN;
+use windows_sys::Win32::Security::Authentication::Identity::GetUserNameExW;
+use windows_sys::Win32::Security::Authentication::Identity::NameSamCompatible;
+
+#[test]
+fn private_desktop_rejects_interactive_and_injected_names() {
+    for name in [
+        "Default",
+        r"Winsta0\Default",
+        "CodexSandboxDesktop-",
+        r"CodexSandboxDesktop-abcd\Default",
+        "CodexSandboxDesktop-abcd\0Default",
+        "CodexSandboxDesktop-0123456789abcdef0123456789abcdef0",
+    ] {
+        assert!(LaunchDesktop::open_private(name).is_err(), "{name:?}");
+    }
+}
+
+#[test]
+fn opening_missing_private_desktop_does_not_create_or_fall_back() {
+    let name = format!(
+        "{PRIVATE_DESKTOP_PREFIX}{:032x}",
+        SmallRng::from_entropy().r#gen::<u128>(),
+    );
+    assert!(LaunchDesktop::open_private(&name).is_err());
+}
+
+#[test]
+fn shared_desktop_survives_launch_handles_and_concurrent_requests() -> Result<()> {
+    let policy = DesktopPolicy {
+        uses_write_capabilities: false,
+        capability_sids: Default::default(),
+        network_enabled: false,
+        network_proxy_restricting_sid: None,
+        read_roots: Some(Default::default()),
+        write_roots: Default::default(),
+        deny_read_paths: Default::default(),
+        deny_write_paths: Default::default(),
+    };
+    let account = current_account_name()?;
+    let names = std::thread::scope(|scope| {
+        let workers = [(); 4].map(|_| {
+            let account = &account;
+            let policy = &policy;
+            scope.spawn(move || {
+                shared_private_desktop_for_user(account, policy, /*logs_base_dir*/ None)
+            })
+        });
+        workers
+            .into_iter()
+            .map(|worker| worker.join().expect("desktop request panicked"))
+            .collect::<Result<Vec<_>>>()
+    })?;
+    let name = names[0].clone();
+    assert_eq!(names, vec![name.clone(); 4]);
+    drop(LaunchDesktop::open_private(&name)?);
+    assert_eq!(
+        shared_private_desktop_for_user(
+            &account.to_ascii_lowercase(),
+            &policy,
+            /*logs_base_dir*/ None
+        )?,
+        name,
+    );
+    drop(LaunchDesktop::open_private(&name)?);
+    Ok(())
+}
+
+#[test]
+fn shared_desktop_reuses_only_equivalent_permissions() -> Result<()> {
+    let temp = TempDir::new()?;
+    let workspace = temp.path().join("workspace");
+    let readable = temp.path().join("readable");
+    let writable = temp.path().join("writable");
+    for path in [&workspace, &readable, &writable] {
+        std::fs::create_dir(path)?;
+    }
+    let codex_home = temp.path().join("codex-home");
+    let permissions = workspace_permissions(&workspace)?;
+    let env = HashMap::new();
+    let account = current_account_name()?;
+    let sids = ["S-1-5-21-10-20-30-40".into(), "S-1-5-21-10-20-30-41".into()];
+    let proxy_sid = "S-1-5-21-50-60-70-80";
+    let overrides = || SetupRootOverrides {
+        read_roots: Some(vec![readable.clone()]),
+        write_roots: Some(vec![workspace.clone(), writable.clone()]),
+        ..Default::default()
+    };
+    let desktop = |overrides, capability_sids: &[String], network_proxy_restricting_sid| {
+        let policy = DesktopPolicy::elevated(
+            SandboxSetupRequest {
+                permissions: &permissions,
+                command_cwd: &workspace,
+                env_map: &env,
+                codex_home: &codex_home,
+                proxy_enforced: true,
+            },
+            overrides,
+            capability_sids,
+            Some(network_proxy_restricting_sid),
+        )?;
+        shared_private_desktop_for_user(&account, &policy, /*logs_base_dir*/ None)
+    };
+    let name = desktop(overrides(), &sids, proxy_sid)?;
+    assert_eq!(
+        desktop(
+            SetupRootOverrides {
+                read_roots: Some(vec![readable.clone(), readable.clone()]),
+                write_roots: Some(vec![
+                    writable.join("..").join("writable"),
+                    workspace.clone(),
+                    writable.clone(),
+                ]),
+                ..Default::default()
+            },
+            &[sids[1].clone(), sids[0].clone(), sids[1].clone()],
+            proxy_sid,
+        )?,
+        name,
+    );
+    for (reason, changed) in [
+        (
+            "read roots",
+            SetupRootOverrides {
+                read_roots: Some(vec![workspace.clone()]),
+                ..overrides()
+            },
+        ),
+        (
+            "write roots",
+            SetupRootOverrides {
+                write_roots: Some(vec![workspace.clone()]),
+                ..overrides()
+            },
+        ),
+        (
+            "deny reads",
+            SetupRootOverrides {
+                deny_read_paths: Some(vec![readable.clone()]),
+                ..overrides()
+            },
+        ),
+        (
+            "deny writes",
+            SetupRootOverrides {
+                deny_write_paths: Some(vec![writable.clone()]),
+                ..overrides()
+            },
+        ),
+    ] {
+        let changed_name = desktop(changed, &sids, proxy_sid)?;
+        assert_ne!(changed_name, name, "{reason}");
+        drop(LaunchDesktop::open_private(&changed_name)?);
+    }
+    assert_ne!(desktop(overrides(), &sids[..1], proxy_sid)?, name);
+    assert_ne!(desktop(overrides(), &sids, "S-1-5-21-50-60-70-81")?, name,);
+    assert_eq!(desktop(overrides(), &sids, proxy_sid)?, name);
+    Ok(())
+}
+
+#[test]
+fn legacy_desktop_reuses_only_equivalent_permissions() -> Result<()> {
+    let temp = TempDir::new()?;
+    let workspace = temp.path().join("workspace");
+    std::fs::create_dir(&workspace)?;
+    let codex_home = temp.path().join("codex-home");
+    let permissions = workspace_permissions(&workspace)?;
+    let env = HashMap::new();
+    let security = prepare_legacy_session_security(
+        /*uses_write_capabilities*/ true,
+        &codex_home,
+        &workspace,
+        legacy_session_capability_roots(&permissions, &workspace, &env, &codex_home),
+    )?;
+    let _token = unsafe { OwnedHandle::from_raw_handle(security.h_token as *mut _) };
+    let desktop = |deny_write_paths| {
+        LaunchDesktop::prepare_legacy(
+            /*use_private_desktop*/ true,
+            &permissions,
+            &workspace,
+            &env,
+            &security,
+            deny_write_paths,
+            /*logs_base_dir*/ None,
+        )
+    };
+    let first = desktop(&[])?;
+    let name = first.startup_name.clone();
+    drop(first);
+    assert_eq!(desktop(&[])?.startup_name, name);
+    assert_ne!(
+        desktop(std::slice::from_ref(&workspace))?.startup_name,
+        name
+    );
+    assert_eq!(desktop(&[])?.startup_name, name);
+    Ok(())
+}
+
+fn current_account_name() -> Result<String> {
+    // Bazel does not provide USERDOMAIN or USERNAME in the test environment.
+    let mut account = [0; (DNLEN + UNLEN + 2) as usize];
+    let mut length = account.len() as u32;
+    if unsafe { GetUserNameExW(NameSamCompatible, account.as_mut_ptr(), &mut length) } == 0 {
+        return Err(std::io::Error::last_os_error().into());
+    }
+    Ok(String::from_utf16(&account[..length as usize])?)
+}
+
+fn workspace_permissions(workspace: &Path) -> Result<ResolvedWindowsSandboxPermissions> {
+    ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+        &PermissionProfile::workspace_write_with(
+            &[],
+            NetworkSandboxPolicy::Restricted,
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        ),
+        &[AbsolutePathBuf::from_absolute_path(workspace)?],
+    )
+}
diff --git a/codex-rs/windows-sandbox-rs/src/dpapi.rs b/codex-rs/windows-sandbox-rs/src/dpapi.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3a90704127e2fd7c71131492aa0d25f70dfba114
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/dpapi.rs
@@ -0,0 +1,85 @@
+use anyhow::Result;
+use anyhow::anyhow;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::Cryptography::CRYPT_INTEGER_BLOB;
+use windows_sys::Win32::Security::Cryptography::CRYPTPROTECT_LOCAL_MACHINE;
+use windows_sys::Win32::Security::Cryptography::CRYPTPROTECT_UI_FORBIDDEN;
+use windows_sys::Win32::Security::Cryptography::CryptProtectData;
+use windows_sys::Win32::Security::Cryptography::CryptUnprotectData;
+
+fn make_blob(data: &[u8]) -> CRYPT_INTEGER_BLOB {
+    CRYPT_INTEGER_BLOB {
+        cbData: data.len() as u32,
+        pbData: data.as_ptr() as *mut u8,
+    }
+}
+
+#[allow(clippy::unnecessary_mut_passed)]
+pub fn protect(data: &[u8]) -> Result<Vec<u8>> {
+    let mut in_blob = make_blob(data);
+    let mut out_blob = CRYPT_INTEGER_BLOB {
+        cbData: 0,
+        pbData: std::ptr::null_mut(),
+    };
+    let ok = unsafe {
+        CryptProtectData(
+            &mut in_blob,
+            std::ptr::null(),
+            std::ptr::null(),
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            // Use machine scope so elevated and non-elevated processes can decrypt.
+            CRYPTPROTECT_UI_FORBIDDEN | CRYPTPROTECT_LOCAL_MACHINE,
+            &mut out_blob,
+        )
+    };
+    if ok == 0 {
+        return Err(anyhow!("CryptProtectData failed: {}", unsafe {
+            GetLastError()
+        }));
+    }
+    let slice =
+        unsafe { std::slice::from_raw_parts(out_blob.pbData, out_blob.cbData as usize) }.to_vec();
+    unsafe {
+        if !out_blob.pbData.is_null() {
+            LocalFree(out_blob.pbData as HLOCAL);
+        }
+    }
+    Ok(slice)
+}
+
+#[allow(clippy::unnecessary_mut_passed)]
+pub fn unprotect(blob: &[u8]) -> Result<Vec<u8>> {
+    let mut in_blob = make_blob(blob);
+    let mut out_blob = CRYPT_INTEGER_BLOB {
+        cbData: 0,
+        pbData: std::ptr::null_mut(),
+    };
+    let ok = unsafe {
+        CryptUnprotectData(
+            &mut in_blob,
+            std::ptr::null_mut(),
+            std::ptr::null(),
+            std::ptr::null_mut(),
+            std::ptr::null_mut(),
+            // Use machine scope so elevated and non-elevated processes can decrypt.
+            CRYPTPROTECT_UI_FORBIDDEN | CRYPTPROTECT_LOCAL_MACHINE,
+            &mut out_blob,
+        )
+    };
+    if ok == 0 {
+        return Err(anyhow!("CryptUnprotectData failed: {}", unsafe {
+            GetLastError()
+        }));
+    }
+    let slice =
+        unsafe { std::slice::from_raw_parts(out_blob.pbData, out_blob.cbData as usize) }.to_vec();
+    unsafe {
+        if !out_blob.pbData.is_null() {
+            LocalFree(out_blob.pbData as HLOCAL);
+        }
+    }
+    Ok(slice)
+}
diff --git a/codex-rs/windows-sandbox-rs/src/elevated/ipc_framed.rs b/codex-rs/windows-sandbox-rs/src/elevated/ipc_framed.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1b1766ac79c90709fdafec1d4c9597dec585d9fe
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated/ipc_framed.rs
@@ -0,0 +1,265 @@
+//! Framed IPC protocol used between the parent (CLI) and the elevated command runner.
+//!
+//! This module defines the JSON message schema (spawn request/ready, output, stdin,
+//! exit, error, terminate) plus length‑prefixed framing helpers for a byte stream.
+//! It is **elevated-path only**: the parent uses it to bootstrap the runner and
+//! stream unified_exec I/O over named pipes. The legacy restricted‑token path does
+//! not use this protocol, and non‑unified exec capture uses it only when running
+//! through the elevated runner.
+
+use anyhow::Result;
+use base64::Engine as _;
+use base64::engine::general_purpose::STANDARD;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::io::Read;
+use std::io::Write;
+use std::path::PathBuf;
+
+/// Protocol version shared by the parent process and elevated command runner.
+pub const IPC_PROTOCOL_VERSION: u8 = 6;
+
+/// Length-prefixed, JSON-encoded frame.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct FramedMessage {
+    pub version: u8,
+    #[serde(flatten)]
+    pub message: Message,
+}
+
+/// IPC message variants exchanged between parent and runner.
+///
+/// `SpawnRequest`, `Stdin`, `CloseStdin`, `Resize`, and `Terminate` are parent->runner commands.
+/// `SpawnReady`, `Output`, `Exit`, and `Error` are runner->parent events/results.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum Message {
+    SpawnRequest { payload: Box<SpawnRequest> },
+    SpawnReady { payload: SpawnReady },
+    Output { payload: OutputPayload },
+    Stdin { payload: StdinPayload },
+    CloseStdin { payload: EmptyPayload },
+    Resize { payload: ResizePayload },
+    Exit { payload: ExitPayload },
+    Error { payload: ErrorPayload },
+    Terminate { payload: EmptyPayload },
+}
+
+/// Spawn parameters sent from parent to runner.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct SpawnRequest {
+    pub command: Vec<String>,
+    pub cwd: PathBuf,
+    pub env: HashMap<String, String>,
+    pub permission_profile: PermissionProfile,
+    pub workspace_roots: Vec<AbsolutePathBuf>,
+    pub codex_home: PathBuf,
+    pub real_codex_home: PathBuf,
+    pub cap_sids: Vec<String>,
+    /// Optional managed-network identity added only to the child's restricting SID set.
+    #[serde(default)]
+    pub network_proxy_restricting_sid: Option<String>,
+    pub timeout_ms: Option<u64>,
+    pub tty: bool,
+    #[serde(default)]
+    pub stdin_open: bool,
+    #[serde(default)]
+    pub use_private_desktop: bool,
+    /// Private desktop kept alive by the parent across command runners.
+    pub private_desktop_name: Option<String>,
+}
+
+/// Ack from runner after it spawns the child process.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct SpawnReady {
+    pub process_id: u32,
+}
+
+/// Output data sent from runner to parent.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct OutputPayload {
+    pub data_b64: String,
+    pub stream: OutputStream,
+}
+
+/// Output stream identifier for `OutputPayload`.
+#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum OutputStream {
+    Stdout,
+    Stderr,
+}
+
+/// Stdin bytes sent from parent to runner.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct StdinPayload {
+    pub data_b64: String,
+}
+
+/// PTY resize request sent from parent to runner.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct ResizePayload {
+    pub rows: u16,
+    pub cols: u16,
+}
+
+/// Exit status sent from runner to parent.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct ExitPayload {
+    pub exit_code: i32,
+    pub timed_out: bool,
+}
+
+/// Error payload sent when the runner fails to spawn or stream.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct ErrorPayload {
+    pub message: String,
+    pub stage: ErrorStage,
+    pub windows_error_code: Option<u32>,
+}
+
+/// Runner startup stage that produced an error.
+#[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ErrorStage {
+    ReadSpawnRequest,
+    SpawnChild,
+    WriteSpawnReady,
+}
+
+/// Empty payload for control messages.
+#[derive(Debug, Serialize, Deserialize, Clone, Default)]
+pub struct EmptyPayload {}
+
+/// Base64-encode raw bytes for IPC payloads.
+pub fn encode_bytes(data: &[u8]) -> String {
+    STANDARD.encode(data)
+}
+
+/// Decode base64 payload data into raw bytes.
+pub fn decode_bytes(data: &str) -> Result<Vec<u8>> {
+    Ok(STANDARD.decode(data.as_bytes())?)
+}
+
+/// Write a length-prefixed JSON frame.
+pub fn write_frame<W: Write>(writer: W, msg: &FramedMessage) -> Result<()> {
+    crate::framed_io::write_frame(writer, msg)
+}
+
+/// Read a length-prefixed JSON frame; returns `Ok(None)` on EOF.
+pub fn read_frame<R: Read>(reader: R) -> Result<Option<FramedMessage>> {
+    crate::framed_io::read_frame(reader)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn framed_round_trip() {
+        let msg = FramedMessage {
+            version: IPC_PROTOCOL_VERSION,
+            message: Message::Output {
+                payload: OutputPayload {
+                    data_b64: encode_bytes(b"hello"),
+                    stream: OutputStream::Stdout,
+                },
+            },
+        };
+        let mut buf = Vec::new();
+        write_frame(&mut buf, &msg).expect("write");
+        let decoded = read_frame(buf.as_slice()).expect("read").expect("some");
+        assert_eq!(decoded.version, IPC_PROTOCOL_VERSION);
+        match decoded.message {
+            Message::Output { payload } => {
+                assert_eq!(payload.stream, OutputStream::Stdout);
+                let data = decode_bytes(&payload.data_b64).expect("decode");
+                assert_eq!(data, b"hello");
+            }
+            other => panic!("unexpected message: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn spawn_request_serializes_permission_profile() {
+        let workspace_roots = vec![
+            AbsolutePathBuf::from_absolute_path(PathBuf::from(r"C:\workspace"))
+                .expect("absolute workspace root"),
+        ];
+        let msg = FramedMessage {
+            version: IPC_PROTOCOL_VERSION,
+            message: Message::SpawnRequest {
+                payload: Box::new(SpawnRequest {
+                    command: vec!["cmd.exe".to_string(), "/c".to_string(), "ver".to_string()],
+                    cwd: PathBuf::from(r"C:\workspace"),
+                    env: HashMap::new(),
+                    permission_profile: PermissionProfile::read_only(),
+                    workspace_roots: workspace_roots.clone(),
+                    codex_home: PathBuf::from(r"C:\codex"),
+                    real_codex_home: PathBuf::from(r"C:\Users\codex"),
+                    cap_sids: vec!["S-1-15-3-1024-1".to_string()],
+                    network_proxy_restricting_sid: Some("S-1-5-21-100-200-300-400".to_string()),
+                    timeout_ms: Some(1000),
+                    tty: false,
+                    stdin_open: false,
+                    use_private_desktop: true,
+                    private_desktop_name: Some("CodexSandboxDesktop-1234".to_string()),
+                }),
+            },
+        };
+
+        let encoded = serde_json::to_value(&msg).expect("serialize");
+        assert_eq!("spawn_request", encoded["type"]);
+        assert_eq!("managed", encoded["payload"]["permission_profile"]["type"]);
+        assert_eq!(None, encoded["payload"].get("policy_json_or_preset"));
+        assert_eq!(None, encoded["payload"].get("sandbox_policy_cwd"));
+        assert_eq!(None, encoded["payload"].get("permission_profile_cwd"));
+
+        let decoded: FramedMessage = serde_json::from_value(encoded).expect("deserialize");
+        let Message::SpawnRequest { payload } = decoded.message else {
+            panic!("unexpected message");
+        };
+        assert_eq!(PermissionProfile::read_only(), payload.permission_profile);
+        assert_eq!(workspace_roots, payload.workspace_roots);
+        assert_eq!(
+            Some("CodexSandboxDesktop-1234"),
+            payload.private_desktop_name.as_deref()
+        );
+        assert_eq!(
+            Some("S-1-5-21-100-200-300-400"),
+            payload.network_proxy_restricting_sid.as_deref()
+        );
+    }
+
+    #[test]
+    fn error_payload_serializes_stage_and_windows_error_code() {
+        let msg = FramedMessage {
+            version: IPC_PROTOCOL_VERSION,
+            message: Message::Error {
+                payload: ErrorPayload {
+                    message: "CreateProcessAsUserW failed".to_string(),
+                    stage: ErrorStage::SpawnChild,
+                    windows_error_code: Some(1312),
+                },
+            },
+        };
+
+        let encoded = serde_json::to_value(&msg).expect("serialize");
+        assert_eq!(
+            serde_json::json!({
+                "version": IPC_PROTOCOL_VERSION,
+                "type": "error",
+                "payload": {
+                    "message": "CreateProcessAsUserW failed",
+                    "stage": "spawn_child",
+                    "windows_error_code": 1312,
+                }
+            }),
+            encoded
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/elevated/mod.rs b/codex-rs/windows-sandbox-rs/src/elevated/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..70d1ad9ccdd58dbf724a05ac27ceba556c43beb0
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated/mod.rs
@@ -0,0 +1,4 @@
+pub(crate) mod ipc_framed;
+pub(crate) mod runner_client;
+pub(crate) mod runner_metrics;
+pub(crate) mod runner_pipe;
diff --git a/codex-rs/windows-sandbox-rs/src/elevated/runner_client.rs b/codex-rs/windows-sandbox-rs/src/elevated/runner_client.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6f688f166d347a4d86e26c7b5ce8688125652b5f
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated/runner_client.rs
@@ -0,0 +1,527 @@
+use crate::app_package::registered_core_requested;
+use crate::app_package::verify_registered_core_runner;
+use crate::desktop::DesktopPolicy;
+use crate::desktop::shared_private_desktop_for_user;
+use crate::identity::SandboxCreds;
+use crate::ipc_framed::ErrorPayload;
+use crate::ipc_framed::ErrorStage;
+use crate::ipc_framed::FramedMessage;
+use crate::ipc_framed::IPC_PROTOCOL_VERSION;
+use crate::ipc_framed::Message;
+use crate::ipc_framed::SpawnRequest;
+use crate::ipc_framed::read_frame;
+use crate::ipc_framed::write_frame;
+use crate::runner_pipe::PIPE_ACCESS_INBOUND;
+use crate::runner_pipe::PIPE_ACCESS_OUTBOUND;
+use crate::runner_pipe::connect_pipe;
+use crate::runner_pipe::create_named_pipe;
+use crate::runner_pipe::find_runner_exe;
+use crate::runner_pipe::pipe_pair;
+use crate::winutil::quote_windows_arg;
+use crate::winutil::to_wide;
+use anyhow::Context;
+use anyhow::Result;
+use std::fs::File;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::ptr;
+use std::sync::mpsc;
+use std::thread;
+use std::time::Duration;
+use std::time::Instant;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::DUPLICATE_SAME_ACCESS;
+use windows_sys::Win32::Foundation::DuplicateHandle;
+use windows_sys::Win32::Foundation::ERROR_ACCOUNT_DISABLED;
+use windows_sys::Win32::Foundation::ERROR_LOGON_FAILURE;
+use windows_sys::Win32::Foundation::ERROR_NO_SUCH_LOGON_SESSION;
+use windows_sys::Win32::Foundation::ERROR_NOT_FOUND;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::System::Diagnostics::Debug::SetErrorMode;
+use windows_sys::Win32::System::IO::CancelSynchronousIo;
+use windows_sys::Win32::System::Threading::CreateProcessWithLogonW;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::GetCurrentThread;
+use windows_sys::Win32::System::Threading::LOGON_WITH_PROFILE;
+use windows_sys::Win32::System::Threading::PROCESS_INFORMATION;
+use windows_sys::Win32::System::Threading::STARTF_FORCEOFFFEEDBACK;
+use windows_sys::Win32::System::Threading::STARTUPINFOW;
+use windows_sys::Win32::System::Threading::TerminateProcess;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+const RUNNER_SPAWN_READY_TIMEOUT: Duration = Duration::from_secs(15);
+const RUNNER_PIPE_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
+const RUNNER_ERROR_MODE_FLAGS: u32 = 0x0001 | 0x0002;
+const WAIT_OBJECT_0: u32 = 0;
+
+#[derive(Debug)]
+struct RunnerLogonError {
+    code: u32,
+}
+
+impl std::fmt::Display for RunnerLogonError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "CreateProcessWithLogonW failed: {}", self.code)
+    }
+}
+
+impl std::error::Error for RunnerLogonError {}
+
+#[derive(Debug)]
+pub(crate) struct RunnerStartupError {
+    payload: ErrorPayload,
+}
+
+impl RunnerStartupError {
+    pub(crate) fn new(payload: ErrorPayload) -> Self {
+        Self { payload }
+    }
+}
+
+impl std::fmt::Display for RunnerStartupError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "runner failed during {:?}: {}",
+            self.payload.stage, self.payload.message
+        )?;
+        if let Some(code) = self.payload.windows_error_code {
+            write!(f, " (Windows error {code})")?;
+        }
+        Ok(())
+    }
+}
+
+impl std::error::Error for RunnerStartupError {}
+
+pub(crate) struct RunnerTransport {
+    pipe_write: File,
+    pipe_read: File,
+}
+
+fn is_refreshable_windows_error(code: u32) -> bool {
+    matches!(
+        code,
+        ERROR_ACCOUNT_DISABLED | ERROR_LOGON_FAILURE | ERROR_NO_SUCH_LOGON_SESSION
+    )
+}
+
+fn command_targets_windows_apps(command: &[String]) -> bool {
+    command.first().is_some_and(|program| {
+        Path::new(program).components().any(|component| {
+            component
+                .as_os_str()
+                .to_string_lossy()
+                .eq_ignore_ascii_case("WindowsApps")
+        })
+    })
+}
+
+pub(crate) fn is_refreshable_sandbox_creds_error(err: &anyhow::Error, command: &[String]) -> bool {
+    if err
+        .downcast_ref::<RunnerLogonError>()
+        .is_some_and(|err| is_refreshable_windows_error(err.code))
+    {
+        return true;
+    }
+
+    err.downcast_ref::<RunnerStartupError>().is_some_and(|err| {
+        err.payload.stage == ErrorStage::SpawnChild
+            && err.payload.windows_error_code.is_some_and(|code| {
+                // AppX activation can return 1312 for a healthy sandbox token. Rotating the
+                // account password cannot make the same WindowsApps command launch.
+                is_refreshable_windows_error(code)
+                    && (code != ERROR_NO_SUCH_LOGON_SESSION
+                        || !command_targets_windows_apps(command))
+            })
+    })
+}
+
+pub(crate) fn retry_runner_spawn_once<T>(
+    sandbox_creds: SandboxCreds,
+    command: &[String],
+    mut spawn: impl FnMut(SandboxCreds) -> Result<T>,
+    refresh: impl FnOnce() -> Result<SandboxCreds>,
+) -> Result<T> {
+    let result = match spawn(sandbox_creds) {
+        Ok(result) => Ok(result),
+        Err(err) if is_refreshable_sandbox_creds_error(&err, command) => refresh().and_then(spawn),
+        Err(err) => Err(err),
+    };
+    super::runner_metrics::record("startup", if result.is_ok() { "success" } else { "error" });
+    result
+}
+
+impl RunnerTransport {
+    pub(crate) fn send_spawn_request(&mut self, request: SpawnRequest) -> Result<()> {
+        let spawn_request = FramedMessage {
+            version: IPC_PROTOCOL_VERSION,
+            message: Message::SpawnRequest {
+                payload: Box::new(request),
+            },
+        };
+        write_frame(&mut self.pipe_write, &spawn_request)
+    }
+
+    pub(crate) fn read_spawn_ready(&mut self) -> Result<()> {
+        crate::framed_io::wait_for_complete_frame(
+            &self.pipe_read,
+            Instant::now() + RUNNER_SPAWN_READY_TIMEOUT,
+        )
+        .context("wait for runner spawn_ready")?;
+        let msg = read_frame(&mut self.pipe_read)?
+            .ok_or_else(|| anyhow::anyhow!("runner pipe closed before spawn_ready"))?;
+        match msg.message {
+            Message::SpawnReady { .. } => Ok(()),
+            Message::Error { payload } => Err(RunnerStartupError::new(payload).into()),
+            other => Err(anyhow::anyhow!(
+                "expected spawn_ready from runner, got {other:?}"
+            )),
+        }
+    }
+
+    pub(crate) fn into_files(self) -> (File, File) {
+        (self.pipe_write, self.pipe_read)
+    }
+}
+
+fn try_take_completed_connect_result(
+    connect_thread: &mut Option<thread::JoinHandle<()>>,
+    connect_result_rx: &mpsc::Receiver<Result<()>>,
+    thread_handle: HANDLE,
+    pipe_label: &str,
+) -> Result<Option<Result<()>>> {
+    let thread_wait = unsafe { WaitForSingleObject(thread_handle, 0) };
+    if thread_wait != WAIT_OBJECT_0 {
+        return Ok(None);
+    }
+
+    if let Some(connect_thread) = connect_thread.take() {
+        let _ = connect_thread.join();
+    }
+
+    let result = connect_result_rx.recv().map_err(|_| {
+        anyhow::anyhow!("runner {pipe_label} connect thread exited before reporting its result")
+    })?;
+    Ok(Some(result))
+}
+
+fn connect_pipe_with_timeout(
+    h_pipe: HANDLE,
+    expected_runner_pid: u32,
+    pipe_label: &str,
+) -> Result<()> {
+    let pipe_label = pipe_label.to_string();
+    let pipe_label_for_thread = pipe_label.clone();
+    let (thread_handle_tx, thread_handle_rx) = mpsc::sync_channel(1);
+    let (connect_result_tx, connect_result_rx) = mpsc::sync_channel(1);
+    let mut connect_thread = Some(
+        thread::Builder::new()
+            .name(format!("codex-runner-connect-{pipe_label}"))
+            .spawn(move || {
+                let current_process = unsafe { GetCurrentProcess() };
+                let mut thread_handle = 0;
+                let duplicate_ok = unsafe {
+                    DuplicateHandle(
+                        current_process,
+                        GetCurrentThread(),
+                        current_process,
+                        &mut thread_handle,
+                        0,
+                        0,
+                        DUPLICATE_SAME_ACCESS,
+                    )
+                };
+                if duplicate_ok == 0 {
+                    let _ = thread_handle_tx.send(Err(anyhow::anyhow!(
+                        "DuplicateHandle failed for runner {pipe_label_for_thread} connect thread: {}",
+                        unsafe { GetLastError() }
+                    )));
+                    return;
+                }
+
+                // Publish the helper thread HANDLE before the blocking pipe connect so the
+                // parent can cancel this specific operation if it times out.
+                let _ = thread_handle_tx.send(Ok(thread_handle));
+
+                let result = connect_pipe(h_pipe, expected_runner_pid)
+                    .map_err(anyhow::Error::from)
+                    .context(format!("connect {pipe_label_for_thread}"));
+                let _ = connect_result_tx.send(result);
+            })?,
+    );
+    let thread_handle = thread_handle_rx.recv().map_err(|_| {
+        anyhow::anyhow!("runner {pipe_label} connect thread exited before publishing its handle")
+    })??;
+
+    let result = match connect_result_rx.recv_timeout(RUNNER_PIPE_CONNECT_TIMEOUT) {
+        Ok(result) => {
+            if let Some(connect_thread) = connect_thread.take() {
+                let _ = connect_thread.join();
+            }
+            result
+        }
+        Err(mpsc::RecvTimeoutError::Timeout) => {
+            if let Some(result) = try_take_completed_connect_result(
+                &mut connect_thread,
+                &connect_result_rx,
+                thread_handle,
+                &pipe_label,
+            )? {
+                result
+            } else {
+                let cancel_ok = unsafe { CancelSynchronousIo(thread_handle) };
+                if cancel_ok == 0 {
+                    let err = unsafe { GetLastError() };
+                    if err != ERROR_NOT_FOUND {
+                        Err(anyhow::anyhow!(
+                            "CancelSynchronousIo failed for runner {pipe_label} connect thread: {err}"
+                        ))
+                    } else if let Some(result) = try_take_completed_connect_result(
+                        &mut connect_thread,
+                        &connect_result_rx,
+                        thread_handle,
+                        &pipe_label,
+                    )? {
+                        result
+                    } else {
+                        Err(anyhow::anyhow!(
+                            "timed out after {}ms connecting runner {pipe_label}",
+                            RUNNER_PIPE_CONNECT_TIMEOUT.as_millis()
+                        ))
+                    }
+                } else {
+                    // Do not join the helper thread on the timeout path. Parent-side cleanup will
+                    // close the pipe handles, which lets the blocked connect unwind without
+                    // risking another indefinite wait here.
+                    Err(anyhow::anyhow!(
+                        "timed out after {}ms connecting runner {pipe_label}",
+                        RUNNER_PIPE_CONNECT_TIMEOUT.as_millis()
+                    ))
+                }
+            }
+        }
+        Err(mpsc::RecvTimeoutError::Disconnected) => {
+            if let Some(connect_thread) = connect_thread.take() {
+                let _ = connect_thread.join();
+            }
+            Err(anyhow::anyhow!(
+                "runner {pipe_label} connect thread exited before reporting its result"
+            ))
+        }
+    };
+
+    unsafe {
+        CloseHandle(thread_handle);
+    }
+
+    result
+}
+
+pub(crate) fn spawn_runner_transport(
+    codex_home: &Path,
+    cwd: &Path,
+    sandbox_creds: &SandboxCreds,
+    log_dir: Option<&Path>,
+    mut spawn_request: SpawnRequest,
+    desktop_policy: Option<&DesktopPolicy>,
+) -> Result<RunnerTransport> {
+    let runner_exe = find_runner_exe(codex_home, log_dir)?;
+    let registered_alias = if registered_core_requested() {
+        Some(crate::app_package::registered_runner_alias(
+            codex_home,
+            &sandbox_creds.username,
+        )?)
+    } else {
+        None
+    };
+    if let Some(policy) = desktop_policy {
+        spawn_request.private_desktop_name = Some(shared_private_desktop_for_user(
+            &sandbox_creds.username,
+            policy,
+            log_dir,
+        )?);
+    }
+    let (pipe_in_name, pipe_out_name) = pipe_pair();
+    let pipe_write = unsafe {
+        File::from_raw_handle(create_named_pipe(
+            &pipe_in_name,
+            PIPE_ACCESS_OUTBOUND,
+            &sandbox_creds.username,
+        )? as _)
+    };
+    let pipe_read = unsafe {
+        File::from_raw_handle(create_named_pipe(
+            &pipe_out_name,
+            PIPE_ACCESS_INBOUND,
+            &sandbox_creds.username,
+        )? as _)
+    };
+    let h_pipe_in = pipe_write.as_raw_handle() as HANDLE;
+    let h_pipe_out = pipe_read.as_raw_handle() as HANDLE;
+
+    let runner_cmdline = registered_alias
+        .as_deref()
+        .unwrap_or(&runner_exe)
+        .to_str()
+        .map(str::to_owned)
+        .unwrap_or_else(|| "codex-command-runner.exe".to_string());
+    let runner_full_cmd = format!(
+        "{} {} {}",
+        quote_windows_arg(&runner_cmdline),
+        quote_windows_arg(&format!("--pipe-in={pipe_in_name}")),
+        quote_windows_arg(&format!("--pipe-out={pipe_out_name}"))
+    );
+    let mut cmdline_vec = to_wide(&runner_full_cmd);
+    let exe_w = to_wide(&runner_cmdline);
+    let cwd_w = to_wide(cwd);
+    let user_w = to_wide(&sandbox_creds.username);
+    let domain_w = to_wide(".");
+    let password_w = to_wide(&sandbox_creds.password);
+    let mut si: STARTUPINFOW = unsafe { std::mem::zeroed() };
+    si.cb = std::mem::size_of::<STARTUPINFOW>() as u32;
+    si.dwFlags = STARTF_FORCEOFFFEEDBACK;
+    let mut pi: PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
+
+    let previous_error_mode = unsafe { SetErrorMode(RUNNER_ERROR_MODE_FLAGS) };
+    // Execution aliases require the registered account's profile.
+    // Other launches retain their existing profile-free behavior.
+    let spawn_res = unsafe {
+        CreateProcessWithLogonW(
+            user_w.as_ptr(),
+            domain_w.as_ptr(),
+            password_w.as_ptr(),
+            if registered_alias.is_some() {
+                LOGON_WITH_PROFILE
+            } else {
+                0
+            },
+            exe_w.as_ptr(),
+            cmdline_vec.as_mut_ptr(),
+            windows_sys::Win32::System::Threading::CREATE_NO_WINDOW
+                | windows_sys::Win32::System::Threading::CREATE_UNICODE_ENVIRONMENT,
+            ptr::null(),
+            cwd_w.as_ptr(),
+            &si,
+            &mut pi,
+        )
+    };
+    unsafe {
+        SetErrorMode(previous_error_mode);
+    }
+    if spawn_res == 0 {
+        let err = unsafe { GetLastError() };
+        return Err(RunnerLogonError { code: err }.into());
+    }
+    // Keep the process pinned through the entire startup handshake. Pipes close
+    // automatically on every error, including failure to create the second pipe.
+    let _runner_process = unsafe { OwnedHandle::from_raw_handle(pi.hProcess as _) };
+    let _runner_thread = unsafe { OwnedHandle::from_raw_handle(pi.hThread as _) };
+    let expected_runner_pid = pi.dwProcessId;
+    let mut transport = RunnerTransport {
+        pipe_write,
+        pipe_read,
+    };
+    let startup_result = (|| -> Result<()> {
+        // An update can retarget the alias after setup. Check the selected image
+        // and authenticate its pipes before sending it the command.
+        if registered_alias.is_some() {
+            verify_registered_core_runner(pi.hProcess, &runner_exe)?;
+        }
+        connect_pipe_with_timeout(h_pipe_in, expected_runner_pid, "pipe-in")?;
+        connect_pipe_with_timeout(h_pipe_out, expected_runner_pid, "pipe-out")?;
+        transport.send_spawn_request(spawn_request)?;
+        transport.read_spawn_ready()?;
+        Ok(())
+    })();
+    if let Err(err) = startup_result {
+        unsafe {
+            let _ = TerminateProcess(pi.hProcess, 1);
+        }
+        return Err(err);
+    }
+
+    if registered_alias.is_some() {
+        crate::logging::debug_log(
+            &format!(
+                "registered_core_runner_ready pid={expected_runner_pid} package_verified=true pipes_authenticated=true"
+            ),
+            log_dir,
+        );
+    }
+
+    Ok(transport)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::RunnerLogonError;
+    use super::RunnerStartupError;
+    use super::is_refreshable_sandbox_creds_error;
+    use crate::ipc_framed::ErrorPayload;
+    use crate::ipc_framed::ErrorStage;
+    use pretty_assertions::assert_eq;
+    use windows_sys::Win32::Foundation::ERROR_ACCOUNT_DISABLED;
+    use windows_sys::Win32::Foundation::ERROR_LOGON_FAILURE;
+    use windows_sys::Win32::Foundation::ERROR_NO_SUCH_LOGON_SESSION;
+    use windows_sys::Win32::Foundation::ERROR_NOT_FOUND;
+
+    #[test]
+    fn refreshable_sandbox_creds_error_recognizes_credential_and_child_start_failures() {
+        assert_eq!(
+            [
+                ERROR_ACCOUNT_DISABLED,
+                ERROR_LOGON_FAILURE,
+                ERROR_NO_SUCH_LOGON_SESSION,
+                ERROR_NOT_FOUND,
+            ]
+            .map(|code| {
+                let err =
+                    anyhow::Error::new(RunnerLogonError { code }).context("runner launch failed");
+                is_refreshable_sandbox_creds_error(&err, &[])
+            }),
+            [true, true, true, false]
+        );
+
+        assert_eq!(
+            [
+                (ErrorStage::SpawnChild, ERROR_NO_SUCH_LOGON_SESSION),
+                (ErrorStage::SpawnChild, ERROR_NOT_FOUND),
+                (ErrorStage::ReadSpawnRequest, ERROR_NO_SUCH_LOGON_SESSION),
+            ]
+            .map(|(stage, windows_error_code)| {
+                let err = anyhow::Error::new(RunnerStartupError::new(ErrorPayload {
+                    message: "runner startup failed".to_string(),
+                    stage,
+                    windows_error_code: Some(windows_error_code),
+                }));
+                is_refreshable_sandbox_creds_error(&err, &["cmd.exe".to_string()])
+            }),
+            [true, false, false]
+        );
+
+        let windows_apps_commands = [
+            vec![
+                r"C:\Users\user\AppData\Local\Microsoft\WindowsApps\pwsh.exe".to_string(),
+            ],
+            vec![
+                r"C:\Program Files\WindowsApps\Microsoft.PowerShell_7.6.3.0_x64__8wekyb3d8bbwe\pwsh.exe"
+                    .to_string(),
+            ],
+        ];
+        assert_eq!(
+            windows_apps_commands.map(|command| {
+                let err = anyhow::Error::new(RunnerStartupError::new(ErrorPayload {
+                    message: "runner startup failed".to_string(),
+                    stage: ErrorStage::SpawnChild,
+                    windows_error_code: Some(ERROR_NO_SUCH_LOGON_SESSION),
+                }));
+                is_refreshable_sandbox_creds_error(&err, &command)
+            }),
+            [false, false]
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/elevated/runner_metrics.rs b/codex-rs/windows-sandbox-rs/src/elevated/runner_metrics.rs
new file mode 100644
index 0000000000000000000000000000000000000000..460e5317ed2f21d3dc32032f9432101c856f9e1e
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated/runner_metrics.rs
@@ -0,0 +1,35 @@
+//! Compare registered and legacy runner outcomes at the actual local execution boundary.
+//! Startup is counted once after credential retry; commands are counted on exit or pipe failure.
+
+pub(crate) fn record(phase: &'static str, outcome: &'static str) {
+    let runtime = if crate::app_package::registered_core_requested() {
+        "registered"
+    } else {
+        "legacy"
+    };
+    if let Some(metrics) = codex_otel::global() {
+        // Fixed labels only: never send command text, paths, or arbitrary error messages.
+        let _ = metrics.counter(
+            "codex.windows_sandbox.runner_result",
+            /*inc*/ 1,
+            &[("runtime", runtime), ("phase", phase), ("outcome", outcome)],
+        );
+    }
+}
+
+pub(crate) fn record_command(exit: Option<(i32, bool)>) {
+    record("command", command_outcome(exit));
+}
+
+fn command_outcome(exit: Option<(i32, bool)>) -> &'static str {
+    match exit {
+        Some((_, true)) => "timeout",
+        Some((0, false)) => "success",
+        Some((_, false)) => "nonzero_exit",
+        None => "transport_error",
+    }
+}
+
+#[cfg(test)]
+#[path = "runner_metrics_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/elevated/runner_metrics_tests.rs b/codex-rs/windows-sandbox-rs/src/elevated/runner_metrics_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7d7e17ee49c6d54e075138ceb30a45c8120b73a4
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated/runner_metrics_tests.rs
@@ -0,0 +1,27 @@
+//! Keep command outcomes distinct without publishing arbitrary exit-code metric labels.
+
+use super::command_outcome;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn command_results_distinguish_timeouts_transport_errors_and_nonzero_exits() {
+    assert_eq!(
+        [
+            Some((0, false)),
+            Some((1, false)),
+            Some((0xc0000135u32 as i32, false)), // Windows DLL-not-found status.
+            Some((0, true)),
+            Some((1, true)),
+            None,
+        ]
+        .map(command_outcome),
+        [
+            "success",
+            "nonzero_exit",
+            "nonzero_exit",
+            "timeout",
+            "timeout",
+            "transport_error",
+        ]
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/elevated/runner_pipe.rs b/codex-rs/windows-sandbox-rs/src/elevated/runner_pipe.rs
new file mode 100644
index 0000000000000000000000000000000000000000..463005ce7735eb9b9557733651b191aaff04afba
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated/runner_pipe.rs
@@ -0,0 +1,133 @@
+//! Named pipe helpers for the elevated Windows sandbox runner.
+//!
+//! This module generates paired pipe names, creates server‑side pipes with
+//! sandbox-user-scoped ACLs, and waits for the runner to connect. It is
+//! **elevated-path only** and is
+//! used by the parent to establish the IPC channel for both unified_exec sessions
+//! and elevated capture. The legacy restricted‑token path spawns the child directly
+//! and does not use these helpers.
+
+use crate::helper_materialization::resolve_command_runner;
+use crate::winutil::resolve_sid;
+use crate::winutil::string_from_sid_bytes;
+use crate::winutil::to_wide;
+use rand::Rng;
+use rand::SeedableRng;
+use rand::rngs::SmallRng;
+use std::io;
+use std::path::Path;
+use std::path::PathBuf;
+use std::ptr;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::Authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW;
+use windows_sys::Win32::Security::PSECURITY_DESCRIPTOR;
+use windows_sys::Win32::Security::SECURITY_ATTRIBUTES;
+use windows_sys::Win32::System::Pipes::ConnectNamedPipe;
+use windows_sys::Win32::System::Pipes::CreateNamedPipeW;
+use windows_sys::Win32::System::Pipes::GetNamedPipeClientProcessId;
+use windows_sys::Win32::System::Pipes::PIPE_READMODE_BYTE;
+use windows_sys::Win32::System::Pipes::PIPE_TYPE_BYTE;
+use windows_sys::Win32::System::Pipes::PIPE_WAIT;
+
+/// PIPE_ACCESS_INBOUND (win32 constant), not exposed in windows-sys 0.52.
+pub const PIPE_ACCESS_INBOUND: u32 = 0x0000_0001;
+/// PIPE_ACCESS_OUTBOUND (win32 constant), not exposed in windows-sys 0.52.
+pub const PIPE_ACCESS_OUTBOUND: u32 = 0x0000_0002;
+
+/// Resolve the installed runner for registered Core; otherwise use the legacy copy path.
+pub fn find_runner_exe(codex_home: &Path, log_dir: Option<&Path>) -> anyhow::Result<PathBuf> {
+    resolve_command_runner(codex_home, log_dir)
+}
+
+/// Generates a unique named-pipe path used to communicate with the runner process.
+pub fn pipe_pair() -> (String, String) {
+    let mut rng = SmallRng::from_entropy();
+    let nonce: u128 = rng.r#gen();
+    let base = format!(r"\\.\pipe\codex-runner-{nonce:x}");
+    (format!("{base}-in"), format!("{base}-out"))
+}
+
+/// Creates a named pipe whose DACL only allows the sandbox user to connect.
+pub fn create_named_pipe(name: &str, access: u32, sandbox_username: &str) -> io::Result<HANDLE> {
+    let sandbox_sid = resolve_sid(sandbox_username)
+        .map_err(|err| io::Error::new(io::ErrorKind::PermissionDenied, err.to_string()))?;
+    let sandbox_sid = string_from_sid_bytes(&sandbox_sid)
+        .map_err(|err| io::Error::new(io::ErrorKind::PermissionDenied, err))?;
+    let sddl = to_wide(format!("D:(A;;GA;;;{sandbox_sid})"));
+    let mut sd: PSECURITY_DESCRIPTOR = ptr::null_mut();
+    let ok = unsafe {
+        ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            sddl.as_ptr(),
+            1, // SDDL_REVISION_1
+            &mut sd,
+            ptr::null_mut(),
+        )
+    };
+    if ok == 0 {
+        return Err(io::Error::from_raw_os_error(unsafe {
+            GetLastError() as i32
+        }));
+    }
+    let mut sa = SECURITY_ATTRIBUTES {
+        nLength: std::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
+        lpSecurityDescriptor: sd,
+        bInheritHandle: 0,
+    };
+    let wide = to_wide(name);
+    let h = unsafe {
+        CreateNamedPipeW(
+            wide.as_ptr(),
+            access,
+            PIPE_TYPE_BYTE | PIPE_READMODE_BYTE | PIPE_WAIT,
+            1,
+            65536,
+            65536,
+            0,
+            &mut sa as *mut SECURITY_ATTRIBUTES,
+        )
+    };
+    unsafe {
+        LocalFree(sd as HLOCAL);
+    }
+    if h == 0 || h == windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE {
+        return Err(io::Error::from_raw_os_error(unsafe {
+            GetLastError() as i32
+        }));
+    }
+    Ok(h)
+}
+
+/// Waits for the runner to connect to a parent-created server pipe.
+///
+/// This is parent-side only: the runner opens the pipe with `CreateFileW`, while the
+/// parent calls `ConnectNamedPipe`, tolerates the already-connected case, and
+/// verifies that the connected client is the runner process we just spawned.
+pub fn connect_pipe(h: HANDLE, expected_runner_pid: u32) -> io::Result<()> {
+    let ok = unsafe { ConnectNamedPipe(h, ptr::null_mut()) };
+    if ok == 0 {
+        let err = unsafe { GetLastError() };
+        const ERROR_PIPE_CONNECTED: u32 = 535;
+        if err != ERROR_PIPE_CONNECTED {
+            return Err(io::Error::from_raw_os_error(err as i32));
+        }
+    }
+    let mut client_pid = 0;
+    let ok = unsafe { GetNamedPipeClientProcessId(h, &mut client_pid) };
+    if ok == 0 {
+        return Err(io::Error::from_raw_os_error(unsafe {
+            GetLastError() as i32
+        }));
+    }
+    if client_pid != expected_runner_pid {
+        return Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            format!(
+                "named pipe client pid {client_pid} did not match runner pid {expected_runner_pid}"
+            ),
+        ));
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/elevated_impl.rs b/codex-rs/windows-sandbox-rs/src/elevated_impl.rs
new file mode 100644
index 0000000000000000000000000000000000000000..01368975c1413184d03773891ee83c2f404c4d9d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/elevated_impl.rs
@@ -0,0 +1,341 @@
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+pub struct ElevatedSandboxProfileCaptureRequest<'a> {
+    pub permission_profile: &'a PermissionProfile,
+    pub workspace_roots: &'a [AbsolutePathBuf],
+    pub codex_home: &'a Path,
+    pub command: Vec<String>,
+    pub cwd: &'a Path,
+    pub env_map: HashMap<String, String>,
+    pub timeout_ms: Option<u64>,
+    pub cancellation: Option<crate::WindowsSandboxCancellationToken>,
+    // TODO(anp): Reconcile this private-desktop copy with the supplied sandbox context
+    // (TurnEnvironment::sandbox_context for turns), preserving this launch snapshot.
+    pub use_private_desktop: bool,
+    pub proxy_enforced: bool,
+    pub network_proxy_restricting_sid: Option<String>,
+    pub read_roots_override: Option<&'a [PathBuf]>,
+    pub read_roots_include_platform_defaults: bool,
+    pub write_roots_override: Option<&'a [PathBuf]>,
+    pub deny_read_paths_override: &'a [AbsolutePathBuf],
+    pub deny_write_paths_override: &'a [AbsolutePathBuf],
+}
+
+mod windows_impl {
+    use super::ElevatedSandboxProfileCaptureRequest;
+    use crate::acl::allow_null_device;
+    use crate::cap::load_or_create_cap_sids;
+    use crate::cap::workspace_write_cap_sid_for_root;
+    use crate::env::ensure_non_interactive_pager;
+    use crate::env::inherit_path_env;
+    use crate::env::normalize_null_device_env;
+    use crate::identity::refresh_logon_sandbox_creds;
+    use crate::identity::require_logon_sandbox_creds;
+    use crate::ipc_framed::EmptyPayload;
+    use crate::ipc_framed::FramedMessage;
+    use crate::ipc_framed::Message;
+    use crate::ipc_framed::OutputStream;
+    use crate::ipc_framed::SpawnRequest;
+    use crate::ipc_framed::decode_bytes;
+    use crate::ipc_framed::read_frame;
+    use crate::ipc_framed::write_frame;
+    use crate::logging::log_failure;
+    use crate::logging::log_start;
+    use crate::logging::log_success;
+    use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+    use crate::runner_client::retry_runner_spawn_once;
+    use crate::runner_client::spawn_runner_transport;
+    use crate::sandbox_utils::ensure_codex_home_exists;
+    use crate::sandbox_utils::inject_git_safe_directory;
+    use crate::setup::effective_write_roots_for_permissions;
+    use crate::token::LocalSid;
+    use anyhow::Result;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use std::fs::File;
+    use std::path::Path;
+    use std::path::PathBuf;
+    use std::sync::Arc;
+    use std::sync::atomic::AtomicBool;
+    use std::sync::atomic::Ordering;
+    use std::time::Duration;
+
+    pub use crate::windows_impl::CaptureResult;
+
+    /// Polls for cancellation and sends the runner's terminate IPC frame when requested.
+    ///
+    /// The 50 ms park bounds cancellation latency without busy-waiting.
+    fn spawn_cancel_writer(
+        pipe_write: &File,
+        cancellation: Option<crate::WindowsSandboxCancellationToken>,
+    ) -> Result<Option<(std::thread::JoinHandle<()>, Arc<AtomicBool>)>> {
+        let Some(cancellation) = cancellation else {
+            return Ok(None);
+        };
+        let mut pipe_write = pipe_write.try_clone()?;
+        let done = Arc::new(AtomicBool::new(false));
+        let done_for_thread = Arc::clone(&done);
+        let handle = std::thread::spawn(move || {
+            while !done_for_thread.load(Ordering::SeqCst) {
+                if cancellation.is_cancelled() {
+                    let _ = write_frame(
+                        &mut pipe_write,
+                        &FramedMessage {
+                            version: 1,
+                            message: Message::Terminate {
+                                payload: EmptyPayload::default(),
+                            },
+                        },
+                    );
+                    break;
+                }
+                std::thread::park_timeout(Duration::from_millis(50));
+            }
+        });
+        Ok(Some((handle, done)))
+    }
+
+    /// Launches the command runner under the sandbox user and captures its output.
+    #[allow(clippy::too_many_arguments)]
+    pub fn run_windows_sandbox_capture_for_permission_profile(
+        request: ElevatedSandboxProfileCaptureRequest<'_>,
+    ) -> Result<CaptureResult> {
+        let ElevatedSandboxProfileCaptureRequest {
+            permission_profile,
+            workspace_roots,
+            codex_home,
+            command,
+            cwd,
+            mut env_map,
+            timeout_ms,
+            cancellation,
+            use_private_desktop,
+            proxy_enforced,
+            network_proxy_restricting_sid,
+            read_roots_override,
+            read_roots_include_platform_defaults,
+            write_roots_override,
+            deny_read_paths_override,
+            deny_write_paths_override,
+        } = request;
+        let permissions =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                permission_profile,
+                workspace_roots,
+            )?;
+        let deny_read_paths_override = deny_read_paths_override
+            .iter()
+            .map(AbsolutePathBuf::to_path_buf)
+            .collect::<Vec<_>>();
+        let deny_write_paths_override = deny_write_paths_override
+            .iter()
+            .map(AbsolutePathBuf::to_path_buf)
+            .collect::<Vec<_>>();
+        normalize_null_device_env(&mut env_map);
+        ensure_non_interactive_pager(&mut env_map);
+        inherit_path_env(&mut env_map);
+        inject_git_safe_directory(&mut env_map, cwd);
+        // Use a temp-based log dir that the sandbox user can write.
+        let sandbox_base = codex_home.join(".sandbox");
+        ensure_codex_home_exists(&sandbox_base)?;
+
+        let logs_base_dir: Option<&Path> = Some(sandbox_base.as_path());
+        log_start(&command, logs_base_dir);
+        let sandbox_creds = require_logon_sandbox_creds(
+            &permissions,
+            cwd,
+            &env_map,
+            codex_home,
+            read_roots_override,
+            read_roots_include_platform_defaults,
+            write_roots_override,
+            &deny_read_paths_override,
+            &deny_write_paths_override,
+            proxy_enforced,
+            crate::WindowsSandboxProxySettingsMode::Reconcile,
+        )?;
+        // Build capability SID for ACL grants.
+        let caps = load_or_create_cap_sids(codex_home)?;
+        let (sid_for_null, cap_sids) = if permissions.uses_write_capabilities_for_cwd(cwd, &env_map)
+        {
+            let write_roots = effective_write_roots_for_permissions(
+                &permissions,
+                cwd,
+                &env_map,
+                codex_home,
+                write_roots_override,
+            );
+            let cap_sids = write_roots
+                .iter()
+                .map(|root| workspace_write_cap_sid_for_root(codex_home, cwd, root))
+                .collect::<Result<Vec<_>>>()?;
+            if cap_sids.is_empty() {
+                anyhow::bail!("workspace-write sandbox has no writable root capability SIDs");
+            }
+            (LocalSid::from_string(&cap_sids[0])?, cap_sids)
+        } else {
+            let sid = LocalSid::from_string(&caps.readonly)?;
+            (sid, vec![caps.readonly])
+        };
+
+        unsafe {
+            allow_null_device(sid_for_null.as_ptr());
+        }
+
+        (|| -> Result<CaptureResult> {
+            let desktop_policy = use_private_desktop
+                .then(|| {
+                    crate::desktop::DesktopPolicy::elevated(
+                        crate::setup::SandboxSetupRequest {
+                            permissions: &permissions,
+                            command_cwd: cwd,
+                            env_map: &env_map,
+                            codex_home,
+                            proxy_enforced,
+                        },
+                        crate::setup::SetupRootOverrides {
+                            read_roots: read_roots_override.map(<[PathBuf]>::to_vec),
+                            read_roots_include_platform_defaults,
+                            write_roots: write_roots_override.map(<[PathBuf]>::to_vec),
+                            deny_read_paths: Some(deny_read_paths_override.clone()),
+                            deny_write_paths: Some(deny_write_paths_override.clone()),
+                        },
+                        &cap_sids,
+                        network_proxy_restricting_sid.as_deref(),
+                    )
+                })
+                .transpose()?;
+            let spawn_request = SpawnRequest {
+                command: command.clone(),
+                cwd: cwd.to_path_buf(),
+                env: env_map.clone(),
+                permission_profile: permission_profile.clone(),
+                workspace_roots: workspace_roots.to_vec(),
+                codex_home: sandbox_base.clone(),
+                real_codex_home: codex_home.to_path_buf(),
+                cap_sids,
+                network_proxy_restricting_sid,
+                timeout_ms,
+                tty: false,
+                stdin_open: false,
+                use_private_desktop,
+                private_desktop_name: None,
+            };
+            let transport = retry_runner_spawn_once(
+                sandbox_creds,
+                &spawn_request.command,
+                |sandbox_creds| {
+                    spawn_runner_transport(
+                        codex_home,
+                        cwd,
+                        &sandbox_creds,
+                        logs_base_dir,
+                        spawn_request.clone(),
+                        desktop_policy.as_ref(),
+                    )
+                },
+                || {
+                    refresh_logon_sandbox_creds(
+                        &permissions,
+                        cwd,
+                        &env_map,
+                        codex_home,
+                        read_roots_override,
+                        read_roots_include_platform_defaults,
+                        write_roots_override,
+                        &deny_read_paths_override,
+                        &deny_write_paths_override,
+                        proxy_enforced,
+                        crate::WindowsSandboxProxySettingsMode::Reconcile,
+                    )
+                },
+            )?;
+            let (pipe_write, mut pipe_read) = transport.into_files();
+            let cancel_writer = spawn_cancel_writer(&pipe_write, cancellation)?;
+
+            let mut stdout = Vec::new();
+            let mut stderr = Vec::new();
+            let result = loop {
+                let msg = match read_frame(&mut pipe_read) {
+                    Ok(Some(msg)) => msg,
+                    Ok(None) => break Err(anyhow::anyhow!("runner pipe closed before exit")),
+                    Err(err) => break Err(err),
+                };
+                match msg.message {
+                    Message::SpawnReady { .. } => {}
+                    Message::Output { payload } => match decode_bytes(&payload.data_b64) {
+                        Ok(bytes) => match payload.stream {
+                            OutputStream::Stdout => stdout.extend_from_slice(&bytes),
+                            OutputStream::Stderr => stderr.extend_from_slice(&bytes),
+                        },
+                        Err(err) => {
+                            break Err(err);
+                        }
+                    },
+                    Message::Exit { payload } => break Ok((payload.exit_code, payload.timed_out)),
+                    Message::Error { payload } => {
+                        break Err(anyhow::anyhow!("runner error: {}", payload.message));
+                    }
+                    other => {
+                        break Err(anyhow::anyhow!(
+                            "unexpected runner message during capture: {other:?}"
+                        ));
+                    }
+                }
+            };
+            if let Some((cancel_handle, done)) = cancel_writer {
+                done.store(true, Ordering::SeqCst);
+                cancel_handle.thread().unpark();
+                let _ = cancel_handle.join();
+            }
+            drop(pipe_write);
+            crate::elevated::runner_metrics::record_command(result.as_ref().ok().copied());
+            let (exit_code, timed_out) = result?;
+
+            if exit_code == 0 {
+                log_success(&command, logs_base_dir);
+            } else {
+                log_failure(&command, &format!("exit code {exit_code}"), logs_base_dir);
+            }
+
+            Ok(CaptureResult {
+                exit_code,
+                stdout,
+                stderr,
+                timed_out,
+            })
+        })()
+    }
+}
+
+#[cfg(target_os = "windows")]
+pub use windows_impl::run_windows_sandbox_capture_for_permission_profile;
+
+#[cfg(not(target_os = "windows"))]
+mod stub {
+    use super::ElevatedSandboxProfileCaptureRequest;
+    use anyhow::Result;
+    use anyhow::bail;
+
+    #[derive(Debug, Default)]
+    pub struct CaptureResult {
+        pub exit_code: i32,
+        pub stdout: Vec<u8>,
+        pub stderr: Vec<u8>,
+        pub timed_out: bool,
+    }
+
+    /// Stub implementation for non-Windows targets; sandboxing only works on Windows.
+    #[allow(clippy::too_many_arguments)]
+    pub fn run_windows_sandbox_capture_for_permission_profile(
+        _request: ElevatedSandboxProfileCaptureRequest<'_>,
+    ) -> Result<CaptureResult> {
+        bail!("Windows sandbox is only available on Windows")
+    }
+}
+
+#[cfg(not(target_os = "windows"))]
+pub use stub::run_windows_sandbox_capture_for_permission_profile;
diff --git a/codex-rs/windows-sandbox-rs/src/env.rs b/codex-rs/windows-sandbox-rs/src/env.rs
new file mode 100644
index 0000000000000000000000000000000000000000..bdf7a76ab2efa345664b6467aed6e7550a80be0d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/env.rs
@@ -0,0 +1,177 @@
+use anyhow::Result;
+use anyhow::anyhow;
+use dirs_next::home_dir;
+use std::collections::HashMap;
+use std::env;
+use std::fs::File;
+use std::fs::{self};
+use std::io::Write;
+use std::path::Path;
+use std::path::PathBuf;
+
+pub fn normalize_null_device_env(env_map: &mut HashMap<String, String>) {
+    let keys: Vec<String> = env_map.keys().cloned().collect();
+    for k in keys {
+        if let Some(v) = env_map.get(&k).cloned() {
+            let t = v.trim().to_ascii_lowercase();
+            if t == "/dev/null" || t == "\\\\\\\\dev\\\\\\\\null" {
+                env_map.insert(k, "NUL".to_string());
+            }
+        }
+    }
+}
+
+pub fn ensure_non_interactive_pager(env_map: &mut HashMap<String, String>) {
+    env_map
+        .entry("GIT_PAGER".into())
+        .or_insert_with(|| "more.com".into());
+    env_map
+        .entry("PAGER".into())
+        .or_insert_with(|| "more.com".into());
+    env_map.entry("LESS".into()).or_insert_with(|| "".into());
+}
+
+// Keep PATH and PATHEXT stable for callers that rely on inheriting the parent process env.
+pub fn inherit_path_env(env_map: &mut HashMap<String, String>) {
+    if !env_map.contains_key("PATH")
+        && let Ok(path) = env::var("PATH")
+    {
+        env_map.insert("PATH".into(), path);
+    }
+    if !env_map.contains_key("PATHEXT")
+        && let Ok(pathext) = env::var("PATHEXT")
+    {
+        env_map.insert("PATHEXT".into(), pathext);
+    }
+}
+
+fn prepend_path(env_map: &mut HashMap<String, String>, prefix: &str) {
+    let existing = env_map
+        .get("PATH")
+        .cloned()
+        .or_else(|| env::var("PATH").ok())
+        .unwrap_or_default();
+    let parts: Vec<String> = existing.split(';').map(ToString::to_string).collect();
+    if parts
+        .first()
+        .map(|p| p.eq_ignore_ascii_case(prefix))
+        .unwrap_or(false)
+    {
+        return;
+    }
+    let mut new_path = String::new();
+    new_path.push_str(prefix);
+    if !existing.is_empty() {
+        new_path.push(';');
+        new_path.push_str(&existing);
+    }
+    env_map.insert("PATH".into(), new_path);
+}
+
+fn reorder_pathext_for_stubs(env_map: &mut HashMap<String, String>) {
+    let default = env_map
+        .get("PATHEXT")
+        .cloned()
+        .or_else(|| env::var("PATHEXT").ok())
+        .unwrap_or(".COM;.EXE;.BAT;.CMD".to_string());
+    let exts: Vec<String> = default
+        .split(';')
+        .filter(|e| !e.is_empty())
+        .map(ToString::to_string)
+        .collect();
+    let exts_norm: Vec<String> = exts.iter().map(|e| e.to_ascii_uppercase()).collect();
+    let want = [".BAT", ".CMD"];
+    let mut front: Vec<String> = Vec::new();
+    for w in want {
+        if let Some(idx) = exts_norm.iter().position(|e| e == w) {
+            front.push(exts[idx].clone());
+        }
+    }
+    let rest: Vec<String> = exts
+        .into_iter()
+        .enumerate()
+        .filter(|(i, _)| {
+            let up = &exts_norm[*i];
+            up != ".BAT" && up != ".CMD"
+        })
+        .map(|(_, e)| e)
+        .collect();
+    let mut combined = Vec::new();
+    combined.extend(front);
+    combined.extend(rest);
+    env_map.insert("PATHEXT".into(), combined.join(";"));
+}
+
+fn ensure_denybin(tools: &[&str], denybin_dir: Option<&Path>) -> Result<PathBuf> {
+    let base = match denybin_dir {
+        Some(p) => p.to_path_buf(),
+        None => {
+            let home = home_dir().ok_or_else(|| anyhow!("no home dir"))?;
+            home.join(".sbx-denybin")
+        }
+    };
+    fs::create_dir_all(&base)?;
+    for tool in tools {
+        for ext in [".bat", ".cmd"] {
+            let path = base.join(format!("{tool}{ext}"));
+            if !path.exists() {
+                let mut f = File::create(&path)?;
+                f.write_all(b"@echo off\\r\\nexit /b 1\\r\\n")?;
+            }
+        }
+    }
+    Ok(base)
+}
+
+pub fn apply_no_network_to_env(env_map: &mut HashMap<String, String>) -> Result<()> {
+    env_map.insert("SBX_NONET_ACTIVE".into(), "1".into());
+    env_map
+        .entry("HTTP_PROXY".into())
+        .or_insert_with(|| "http://127.0.0.1:9".into());
+    env_map
+        .entry("HTTPS_PROXY".into())
+        .or_insert_with(|| "http://127.0.0.1:9".into());
+    env_map
+        .entry("ALL_PROXY".into())
+        .or_insert_with(|| "http://127.0.0.1:9".into());
+    env_map
+        .entry("NO_PROXY".into())
+        .or_insert_with(|| "localhost,127.0.0.1,::1".into());
+    env_map
+        .entry("PIP_NO_INDEX".into())
+        .or_insert_with(|| "1".into());
+    env_map
+        .entry("PIP_DISABLE_PIP_VERSION_CHECK".into())
+        .or_insert_with(|| "1".into());
+    env_map
+        .entry("NPM_CONFIG_OFFLINE".into())
+        .or_insert_with(|| "true".into());
+    env_map
+        .entry("CARGO_NET_OFFLINE".into())
+        .or_insert_with(|| "true".into());
+    env_map
+        .entry("GIT_HTTP_PROXY".into())
+        .or_insert_with(|| "http://127.0.0.1:9".into());
+    env_map
+        .entry("GIT_HTTPS_PROXY".into())
+        .or_insert_with(|| "http://127.0.0.1:9".into());
+    env_map
+        .entry("GIT_SSH_COMMAND".into())
+        .or_insert_with(|| "cmd /c exit 1".into());
+    env_map
+        .entry("GIT_ALLOW_PROTOCOLS".into())
+        .or_insert_with(|| "".into());
+
+    let base = ensure_denybin(&["ssh", "scp"], /*denybin_dir*/ None)?;
+    for tool in ["curl", "wget"] {
+        for ext in [".bat", ".cmd"] {
+            let p = base.join(format!("{tool}{ext}"));
+            if p.exists() {
+                let _ = fs::remove_file(&p);
+            }
+        }
+    }
+    prepend_path(env_map, &base.to_string_lossy());
+    reorder_pathext_for_stubs(env_map);
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/file_write.rs b/codex-rs/windows-sandbox-rs/src/file_write.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e8a2932bcff640c55a46dd354ac809fe247cb760
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/file_write.rs
@@ -0,0 +1,149 @@
+//! Writes helper outputs through fresh handles, replacing directory entries
+//! without opening caller-supplied destination files or copying their ACLs.
+
+use anyhow::Context;
+use anyhow::Result;
+use rand::RngCore;
+use std::ffi::OsStr;
+use std::ffi::c_void;
+use std::fs::File;
+use std::io::Write;
+use std::mem::offset_of;
+use std::os::windows::ffi::OsStrExt;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::NTSTATUS;
+use windows_sys::Win32::Foundation::RtlNtStatusToDosError;
+use windows_sys::Win32::Storage::FileSystem::DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_DISPOSITION_INFO;
+use windows_sys::Win32::Storage::FileSystem::FILE_READ_ATTRIBUTES;
+use windows_sys::Win32::Storage::FileSystem::FILE_RENAME_INFO;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::Storage::FileSystem::FILE_TRAVERSE;
+use windows_sys::Win32::Storage::FileSystem::FILE_WRITE_DATA;
+use windows_sys::Win32::Storage::FileSystem::FileDispositionInfo;
+use windows_sys::Win32::Storage::FileSystem::SYNCHRONIZE;
+use windows_sys::Win32::Storage::FileSystem::SetFileInformationByHandle;
+use windows_sys::Win32::System::IO::IO_STATUS_BLOCK;
+use windows_sys::Win32::System::IO::IO_STATUS_BLOCK_0;
+
+use crate::no_reparse_dir::DirectoryOpenDisposition;
+use crate::no_reparse_dir::open_directory_no_reparse;
+use crate::no_reparse_dir::open_no_reparse;
+use crate::no_reparse_dir::validate_local_directory_path;
+
+const FILE_CREATE: u32 = 2;
+const FILE_SYNCHRONOUS_IO_NONALERT: u32 = 0x20;
+const FILE_NON_DIRECTORY_FILE: u32 = 0x40;
+const FILE_RENAME_INFORMATION: i32 = 10;
+
+#[link(name = "ntdll")]
+unsafe extern "system" {
+    fn NtSetInformationFile(
+        file_handle: HANDLE,
+        io_status_block: *mut IO_STATUS_BLOCK,
+        file_information: *const c_void,
+        length: u32,
+        file_information_class: i32,
+    ) -> NTSTATUS;
+}
+
+/// Replaces an output with a fresh file that inherits its parent directory's ACL.
+/// The destination is never opened for writing, even if replacement fails.
+pub fn write_file_atomically(path: &Path, contents: &[u8]) -> Result<()> {
+    validate_local_directory_path(path)?;
+    let parent = path
+        .parent()
+        .context("output must have a parent directory")?;
+    let name: Vec<u16> = path
+        .file_name()
+        .context("output must have a file name")?
+        .encode_wide()
+        .collect();
+    let (mut file, directory) = create_temporary_file(parent, ".tmp")?;
+    let result: Result<()> = (|| {
+        file.write_all(contents)?;
+
+        // FILE_RENAME_INFO ends in a variable-length UTF-16 name. Allocate
+        // enough aligned storage for both the fixed header and that name.
+        let size = size_of::<FILE_RENAME_INFO>() + size_of_val(name.as_slice());
+        let mut buffer = vec![0_usize; size.div_ceil(size_of::<usize>())];
+        let info = buffer.as_mut_ptr().cast::<FILE_RENAME_INFO>();
+        let mut io_status = IO_STATUS_BLOCK {
+            Anonymous: IO_STATUS_BLOCK_0 { Status: 0 },
+            Information: 0,
+        };
+        unsafe {
+            (*info).Anonymous.ReplaceIfExists = 1;
+            (*info).RootDirectory = directory.as_raw_handle() as HANDLE;
+            (*info).FileNameLength = u32::try_from(size_of_val(name.as_slice()))?;
+            let filename = buffer
+                .as_mut_ptr()
+                .cast::<u8>()
+                .add(offset_of!(FILE_RENAME_INFO, FileName))
+                .cast::<u16>();
+            std::ptr::copy_nonoverlapping(name.as_ptr(), filename, name.len());
+            // The Win32 wrapper rejects RootDirectory on some Windows versions.
+            // The native rename accepts the pinned parent and has the same layout.
+            let status = NtSetInformationFile(
+                file.as_raw_handle() as HANDLE,
+                &mut io_status,
+                info.cast(),
+                u32::try_from(size)?,
+                FILE_RENAME_INFORMATION,
+            );
+            if status < 0 {
+                return Err(
+                    std::io::Error::from_raw_os_error(RtlNtStatusToDosError(status) as i32).into(),
+                );
+            }
+        }
+        Ok(())
+    })();
+    if result.is_err() {
+        // Clean up only the file we created, not a pathname the caller could
+        // have replaced. Preserve the original write/rename error.
+        let disposition = FILE_DISPOSITION_INFO { DeleteFile: 1 };
+        unsafe {
+            SetFileInformationByHandle(
+                file.as_raw_handle() as HANDLE,
+                FileDispositionInfo,
+                (&raw const disposition).cast(),
+                size_of::<FILE_DISPOSITION_INFO>() as u32,
+            );
+        }
+    }
+    result.with_context(|| format!("replace output {}", path.display()))
+}
+
+pub(crate) fn create_temporary_file(parent: &Path, suffix: &str) -> Result<(File, OwnedHandle)> {
+    let directory = open_directory_no_reparse(
+        parent,
+        FILE_TRAVERSE | FILE_READ_ATTRIBUTES,
+        FILE_SHARE_READ | FILE_SHARE_WRITE,
+        DirectoryOpenDisposition::OpenExisting,
+    )?;
+    let mut random = [0_u8; 8];
+    rand::rngs::OsRng
+        .try_fill_bytes(&mut random)
+        .context("generate sandbox output name")?;
+    let id = u64::from_le_bytes(random);
+    let name = format!("sandbox-{id:016x}{suffix}");
+    let mut name: Vec<u16> = OsStr::new(&name).encode_wide().chain(Some(0)).collect();
+    let file = open_no_reparse(
+        directory.as_raw_handle() as HANDLE,
+        &mut name,
+        FILE_WRITE_DATA | DELETE | SYNCHRONIZE,
+        FILE_SHARE_READ,
+        FILE_CREATE,
+        FILE_NON_DIRECTORY_FILE | FILE_SYNCHRONOUS_IO_NONALERT,
+    )?;
+    Ok((File::from(file), directory))
+}
+
+#[cfg(test)]
+#[path = "file_write_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/file_write_tests.rs b/codex-rs/windows-sandbox-rs/src/file_write_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6711c8050c87dbffdfd500df93cd0014643150da
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/file_write_tests.rs
@@ -0,0 +1,70 @@
+//! Checks fresh output handles and safe replacement of caller-controlled entries.
+
+use super::create_temporary_file;
+use super::write_file_atomically;
+use anyhow::Result;
+use pretty_assertions::assert_eq;
+use std::fs;
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::os::windows::fs::OpenOptionsExt;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+
+#[test]
+fn replaces_hard_link_without_writing_to_its_target() -> Result<()> {
+    let temp = tempfile::tempdir()?;
+    let victim = temp.path().join("victim");
+    let output = temp.path().join("sandbox_users.json");
+    fs::write(&victim, b"unchanged")?;
+    fs::hard_link(&victim, &output)?;
+
+    write_file_atomically(&output, b"new contents")?;
+
+    assert_eq!(fs::read(&victim)?, b"unchanged");
+    assert_eq!(fs::read(&output)?, b"new contents");
+    assert_eq!(fs::read_dir(temp.path())?.count(), 2);
+    Ok(())
+}
+
+#[test]
+fn failed_replacement_does_not_truncate_target_or_leave_temporary_file() -> Result<()> {
+    let temp = tempfile::tempdir()?;
+    let victim = temp.path().join("victim");
+    let output = temp.path().join("setup_error.json");
+    fs::write(&victim, b"unchanged")?;
+    fs::hard_link(&victim, &output)?;
+    let _held = OpenOptions::new()
+        .read(true)
+        .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE)
+        .open(&output)?;
+
+    assert!(write_file_atomically(&output, b"new contents").is_err());
+
+    assert_eq!(fs::read(&victim)?, b"unchanged");
+    assert_eq!(fs::read(&output)?, b"unchanged");
+    assert_eq!(fs::read_dir(temp.path())?.count(), 2);
+    Ok(())
+}
+
+#[test]
+fn fresh_output_cannot_be_written_or_replaced_while_held() -> Result<()> {
+    let temp = tempfile::tempdir()?;
+    let (mut file, _directory) = create_temporary_file(temp.path(), ".log")?;
+    let path = fs::read_dir(temp.path())?.next().unwrap()?.path();
+
+    assert!(
+        OpenOptions::new()
+            .write(true)
+            .truncate(true)
+            .open(&path)
+            .is_err()
+    );
+    assert!(fs::remove_file(&path).is_err());
+    assert!(fs::rename(&path, temp.path().join("moved")).is_err());
+    file.write_all(b"log contents")?;
+    drop(file);
+
+    assert_eq!(fs::read(path)?, b"log contents");
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/framed_io.rs b/codex-rs/windows-sandbox-rs/src/framed_io.rs
new file mode 100644
index 0000000000000000000000000000000000000000..537257f522d21aded0107c76436e1282805b5fa2
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/framed_io.rs
@@ -0,0 +1,91 @@
+//! Shared length-prefixed JSON framing for independent Windows sandbox IPC protocols.
+
+use anyhow::Result;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use std::fs::File;
+use std::io;
+use std::io::Read;
+use std::io::Write;
+use std::os::windows::io::AsRawHandle;
+use std::ptr;
+use std::time::Duration;
+use std::time::Instant;
+use windows_sys::Win32::System::Pipes::PeekNamedPipe;
+
+/// Bound the memory used by an individual untrusted IPC frame.
+const MAX_FRAME_LEN: usize = 8 * 1024 * 1024;
+const FRAME_POLL_INTERVAL: Duration = Duration::from_millis(5);
+
+pub(crate) fn write_frame<W: Write, T: Serialize>(mut writer: W, message: &T) -> Result<()> {
+    let payload = serde_json::to_vec(message)?;
+    if payload.len() > MAX_FRAME_LEN {
+        anyhow::bail!("frame too large: {}", payload.len());
+    }
+    let len = payload.len() as u32;
+    writer.write_all(&len.to_le_bytes())?;
+    writer.write_all(&payload)?;
+    writer.flush()?;
+    Ok(())
+}
+
+pub(crate) fn read_frame<R: Read, T: DeserializeOwned>(mut reader: R) -> Result<Option<T>> {
+    let mut len_buf = [0u8; 4];
+    match reader.read_exact(&mut len_buf) {
+        Ok(()) => {}
+        Err(err) if err.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
+        Err(err) => return Err(err.into()),
+    }
+    let len = u32::from_le_bytes(len_buf) as usize;
+    if len > MAX_FRAME_LEN {
+        anyhow::bail!("frame too large: {len}");
+    }
+    let mut payload = vec![0u8; len];
+    reader.read_exact(&mut payload)?;
+    let message = serde_json::from_slice(&payload)?;
+    Ok(Some(message))
+}
+
+pub(crate) fn wait_for_complete_frame(pipe: &File, deadline: Instant) -> io::Result<()> {
+    let mut len_buf = [0_u8; 4];
+
+    loop {
+        let mut bytes_read = 0_u32;
+        let mut total_available = 0_u32;
+        let ok = unsafe {
+            PeekNamedPipe(
+                pipe.as_raw_handle() as _,
+                len_buf.as_mut_ptr().cast(),
+                len_buf.len() as u32,
+                &mut bytes_read,
+                &mut total_available,
+                ptr::null_mut(),
+            )
+        };
+        if ok == 0 {
+            return Err(io::Error::last_os_error());
+        }
+
+        if bytes_read == len_buf.len() as u32 {
+            let frame_len = u32::from_le_bytes(len_buf) as usize;
+            if frame_len > MAX_FRAME_LEN {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidData,
+                    format!("frame too large: {frame_len}"),
+                ));
+            }
+            if total_available as usize >= len_buf.len() + frame_len {
+                return Ok(());
+            }
+        }
+
+        let remaining = deadline.saturating_duration_since(Instant::now());
+        if remaining.is_zero() {
+            return Err(io::Error::new(
+                io::ErrorKind::TimedOut,
+                "timed out waiting for a complete IPC frame",
+            ));
+        }
+        std::thread::sleep(remaining.min(FRAME_POLL_INTERVAL));
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/helper_materialization.rs b/codex-rs/windows-sandbox-rs/src/helper_materialization.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1d219422daa90071c321476b328b3b5cb739ecef
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/helper_materialization.rs
@@ -0,0 +1,432 @@
+//! Resolve sandbox helpers and materialize legacy executables with inherited sandbox ACLs.
+//! An explicit registered-runtime request never falls through to copying or PATH lookup;
+//! the service and startup handshake independently verify the installed image.
+
+mod copy;
+use copy::CopyOutcome;
+use copy::copy_from_source_if_needed;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use std::ffi::OsStr;
+use std::fs;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::UNIX_EPOCH;
+
+use crate::app_package::registered_core_requested;
+use crate::logging::log_note;
+use crate::sandbox_bin_dir;
+use crate::setup::SetupRuntime;
+
+const DEV_BUILD_VERSION_SENTINEL: &str = "0.0.0";
+const COMMAND_RUNNER_EXE: &str = "codex-command-runner.exe";
+pub(crate) const BIN_DIRNAME: &str = "bin";
+pub(crate) const RESOURCES_DIRNAME: &str = "codex-resources";
+
+pub(crate) fn helper_bin_dir(codex_home: &Path) -> PathBuf {
+    sandbox_bin_dir(codex_home)
+}
+
+fn legacy_lookup() -> PathBuf {
+    if let Ok(exe) = std::env::current_exe()
+        && let Some(candidate) = bundled_executable_path_for_exe(&exe, COMMAND_RUNNER_EXE)
+    {
+        return candidate;
+    }
+    PathBuf::from(COMMAND_RUNNER_EXE)
+}
+
+pub(crate) fn resolve_command_runner(codex_home: &Path, log_dir: Option<&Path>) -> Result<PathBuf> {
+    if registered_core_requested() {
+        let exe = std::env::current_exe().context("resolve registered Core helper source")?;
+        let direct_path = exe.with_file_name(COMMAND_RUNNER_EXE);
+        log_note(
+            &format!(
+                "helper launch resolution: using app-contained command-runner path {}",
+                direct_path.display()
+            ),
+            log_dir,
+        );
+        // Missing packaged helpers must fail rather than search PATH or create a copy.
+        return Ok(direct_path);
+    }
+    Ok(match copy_runner_if_needed(codex_home, log_dir) {
+        Ok(path) => {
+            log_note(
+                &format!(
+                    "helper launch resolution: using copied command-runner path {}",
+                    path.display()
+                ),
+                log_dir,
+            );
+            path
+        }
+        Err(err) => {
+            let fallback = legacy_lookup();
+            log_note(
+                &format!(
+                    "helper copy failed for command-runner: {err:#}; falling back to legacy path {}",
+                    fallback.display()
+                ),
+                log_dir,
+            );
+            fallback
+        }
+    })
+}
+
+pub fn resolve_exe_for_launch(source: &Path, codex_home: &Path) -> PathBuf {
+    let runtime = crate::setup::current_setup_runtime();
+    resolve_exe_for_runtime(source, codex_home, runtime)
+}
+
+fn resolve_exe_for_runtime(source: &Path, codex_home: &Path, runtime: SetupRuntime) -> PathBuf {
+    let sandbox_log_dir = crate::sandbox_dir(codex_home);
+    if runtime == SetupRuntime::Registered {
+        log_note(
+            &format!(
+                "helper executable resolution: route=direct source={} selected={}",
+                source.display(),
+                source.display()
+            ),
+            Some(&sandbox_log_dir),
+        );
+        return source.to_path_buf();
+    }
+    let Some(file_name) = source.file_name() else {
+        return source.to_path_buf();
+    };
+    let destination = helper_bin_dir(codex_home).join(file_name);
+    match copy_from_source_if_needed(source, &destination) {
+        Ok(_) => {
+            log_note(
+                &format!(
+                    "helper executable resolution: route=materialized source={} selected={}",
+                    source.display(),
+                    destination.display()
+                ),
+                Some(&sandbox_log_dir),
+            );
+            destination
+        }
+        Err(err) => {
+            log_note(
+                &format!(
+                    "helper copy failed for executable: {err:#}; falling back to legacy path {}",
+                    source.display()
+                ),
+                Some(&sandbox_log_dir),
+            );
+            source.to_path_buf()
+        }
+    }
+}
+
+fn copy_runner_if_needed(codex_home: &Path, log_dir: Option<&Path>) -> Result<PathBuf> {
+    let source = sibling_source_path()?;
+    let suffix = helper_version_suffix(&source)?;
+    let destination = helper_bin_dir(codex_home).join(materialized_file_name(&suffix));
+    log_note(
+        &format!(
+            "helper copy: validating command-runner source={} destination={}",
+            source.display(),
+            destination.display()
+        ),
+        log_dir,
+    );
+    let outcome = copy_from_source_if_needed(&source, &destination)?;
+    let action = match outcome {
+        CopyOutcome::Reused => "reused",
+        CopyOutcome::ReCopied => "recopied",
+    };
+    log_note(
+        &format!(
+            "helper copy: {} command-runner source={} destination={}",
+            action,
+            source.display(),
+            destination.display()
+        ),
+        log_dir,
+    );
+    Ok(destination)
+}
+
+fn sibling_source_path() -> Result<PathBuf> {
+    let exe = std::env::current_exe().context("resolve current executable for helper lookup")?;
+    bundled_executable_path_for_exe(&exe, COMMAND_RUNNER_EXE).ok_or_else(|| {
+        anyhow!(
+            "helper not found next to current executable or under {RESOURCES_DIRNAME}: {}",
+            exe.display()
+        )
+    })
+}
+
+pub(crate) fn bundled_executable_path_for_exe(exe: &Path, file_name: &str) -> Option<PathBuf> {
+    let find = |exe: &Path| {
+        let dir = exe.parent()?;
+        let direct_candidate = dir.join(file_name);
+        if direct_candidate.is_file() {
+            return Some(direct_candidate);
+        }
+
+        if dir.file_name() == Some(OsStr::new(BIN_DIRNAME))
+            && let Some(package_dir) = dir.parent()
+        {
+            let package_resource_candidate = package_dir.join(RESOURCES_DIRNAME).join(file_name);
+            if package_resource_candidate.is_file() {
+                return Some(package_resource_candidate);
+            }
+        }
+
+        let resource_candidate = dir.join(RESOURCES_DIRNAME).join(file_name);
+        resource_candidate.is_file().then_some(resource_candidate)
+    };
+
+    // Installer bin directories can be junctions, so retry beside the real executable once.
+    find(exe).or_else(|| find(&dunce::canonicalize(exe).ok()?))
+}
+
+fn materialized_file_name(suffix: &str) -> String {
+    format!("codex-command-runner-{suffix}.exe")
+}
+
+fn helper_version_suffix(source: &Path) -> Result<String> {
+    let version = env!("CARGO_PKG_VERSION");
+    if version == DEV_BUILD_VERSION_SENTINEL {
+        dev_build_suffix(source)
+    } else {
+        Ok(version.to_string())
+    }
+}
+
+fn dev_build_suffix(source: &Path) -> Result<String> {
+    let metadata = fs::metadata(source)
+        .with_context(|| format!("read helper source metadata {}", source.display()))?;
+    let modified = metadata
+        .modified()
+        .with_context(|| format!("read helper source mtime {}", source.display()))?;
+    let duration = modified
+        .duration_since(UNIX_EPOCH)
+        .with_context(|| format!("convert helper source mtime {}", source.display()))?;
+    Ok(format!("{}-{:x}", metadata.len(), duration.as_secs(),))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::BIN_DIRNAME;
+    use super::CopyOutcome;
+    use super::DEV_BUILD_VERSION_SENTINEL;
+    use super::RESOURCES_DIRNAME;
+    use super::bundled_executable_path_for_exe;
+    use super::copy_from_source_if_needed;
+    use super::dev_build_suffix;
+    use super::helper_bin_dir;
+    use super::helper_version_suffix;
+    use super::materialized_file_name;
+    use super::resolve_exe_for_runtime;
+    use crate::setup::SetupRuntime;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use std::path::Path;
+    use std::path::PathBuf;
+    use tempfile::TempDir;
+
+    #[test]
+    fn helper_bin_dir_is_under_sandbox_bin() {
+        let codex_home = Path::new(r"C:\Users\example\.codex");
+
+        assert_eq!(
+            PathBuf::from(r"C:\Users\example\.codex\.sandbox-bin"),
+            helper_bin_dir(codex_home)
+        );
+    }
+
+    #[test]
+    fn registered_request_does_not_materialize_or_replace_a_missing_source() {
+        let tmp = TempDir::new().expect("tempdir");
+        let executable = tmp.path().join("codex.exe");
+        let home = tmp.path().join("home");
+        for content in [None, Some(b"fixture".as_slice())] {
+            if let Some(content) = content {
+                fs::write(&executable, content).expect("write source");
+            }
+            assert_eq!(
+                resolve_exe_for_runtime(&executable, &home, SetupRuntime::Registered),
+                executable
+            );
+            assert!(!helper_bin_dir(&home).exists());
+        }
+    }
+
+    #[test]
+    fn legacy_request_materializes_the_same_source() {
+        let tmp = TempDir::new().expect("tempdir");
+        let executable = tmp.path().join("codex.exe");
+        let home = tmp.path().join("home");
+        fs::write(&executable, b"fixture").expect("write source");
+        let destination = helper_bin_dir(&home).join("codex.exe");
+        assert_eq!(
+            resolve_exe_for_runtime(&executable, &home, SetupRuntime::Legacy),
+            destination
+        );
+        assert_eq!(fs::read(destination).expect("read copy"), b"fixture");
+    }
+
+    #[test]
+    fn copy_runner_into_shared_bin_dir() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let source_dir = tmp.path().join("sibling-source");
+        fs::create_dir_all(&source_dir).expect("create source dir");
+        let runner_source = source_dir.join("codex-command-runner.exe");
+        fs::write(&runner_source, b"runner").expect("runner");
+        let runner_suffix = helper_version_suffix(&runner_source).expect("runner suffix");
+        let runner_destination =
+            helper_bin_dir(&codex_home).join(materialized_file_name(&runner_suffix));
+
+        let runner_outcome =
+            copy_from_source_if_needed(&runner_source, &runner_destination).expect("runner copy");
+
+        assert_eq!(CopyOutcome::ReCopied, runner_outcome);
+        assert_eq!(
+            b"runner".as_slice(),
+            fs::read(&runner_destination).expect("read runner")
+        );
+    }
+
+    #[test]
+    fn helper_source_lookup_checks_resource_dir() {
+        let tmp = TempDir::new().expect("tempdir");
+        let release_dir = tmp.path().join("release");
+        let resources_dir = release_dir.join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&resources_dir).expect("create resources dir");
+        let exe = release_dir.join("codex.exe");
+        let helper = resources_dir.join("codex-command-runner.exe");
+        fs::write(&exe, b"codex").expect("write exe");
+        fs::write(&helper, b"runner").expect("write helper");
+
+        let resolved =
+            bundled_executable_path_for_exe(&exe, /*file_name*/ "codex-command-runner.exe")
+                .expect("helper path");
+
+        assert_eq!(resolved, helper);
+    }
+
+    #[test]
+    fn helper_source_lookup_checks_package_resource_dir_for_bin_exe() {
+        let tmp = TempDir::new().expect("tempdir");
+        let package_dir = tmp.path().join("package");
+        let bin_dir = package_dir.join(BIN_DIRNAME);
+        let resources_dir = package_dir.join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&bin_dir).expect("create bin dir");
+        fs::create_dir_all(&resources_dir).expect("create resources dir");
+        let exe = bin_dir.join("codex.exe");
+        let helper = resources_dir.join("codex-command-runner.exe");
+        fs::write(&exe, b"codex").expect("write exe");
+        fs::write(&helper, b"runner").expect("write helper");
+
+        let resolved =
+            bundled_executable_path_for_exe(&exe, /*file_name*/ "codex-command-runner.exe")
+                .expect("helper path");
+
+        assert_eq!(resolved, helper);
+    }
+
+    #[test]
+    fn helper_source_lookup_resolves_bin_junctions() {
+        let tmp = TempDir::new().expect("tempdir");
+        let package_dir = tmp.path().join("package");
+        let bin_dir = package_dir.join(BIN_DIRNAME);
+        let resources_dir = package_dir.join(RESOURCES_DIRNAME);
+        let install_dir = tmp.path().join("install");
+        fs::create_dir_all(&bin_dir).expect("create bin dir");
+        fs::create_dir_all(&resources_dir).expect("create resources dir");
+        fs::create_dir_all(&install_dir).expect("create install dir");
+        fs::write(bin_dir.join("codex.exe"), b"codex").expect("write exe");
+        let helper = resources_dir.join("codex-windows-sandbox-setup.exe");
+        fs::write(&helper, b"setup").expect("write helper");
+
+        let junction = install_dir.join(BIN_DIRNAME);
+        let output = std::process::Command::new("cmd")
+            .args(["/c", "mklink", "/J"])
+            .arg(&junction)
+            .arg(&bin_dir)
+            .output()
+            .expect("create bin junction");
+        assert!(output.status.success());
+
+        assert_eq!(
+            bundled_executable_path_for_exe(
+                &junction.join("codex.exe"),
+                /*file_name*/ "codex-windows-sandbox-setup.exe"
+            ),
+            Some(dunce::canonicalize(&helper).expect("canonical helper"))
+        );
+    }
+
+    #[test]
+    fn helper_source_lookup_prefers_package_resource_dir_over_bin_resource_dir() {
+        let tmp = TempDir::new().expect("tempdir");
+        let package_dir = tmp.path().join("package");
+        let bin_dir = package_dir.join(BIN_DIRNAME);
+        let package_resources_dir = package_dir.join(RESOURCES_DIRNAME);
+        let bin_resources_dir = bin_dir.join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&package_resources_dir).expect("create package resources dir");
+        fs::create_dir_all(&bin_resources_dir).expect("create bin resources dir");
+        let exe = bin_dir.join("codex.exe");
+        let package_helper = package_resources_dir.join("codex-command-runner.exe");
+        let bin_helper = bin_resources_dir.join("codex-command-runner.exe");
+        fs::write(&exe, b"codex").expect("write exe");
+        fs::write(&package_helper, b"package runner").expect("write package helper");
+        fs::write(&bin_helper, b"bin runner").expect("write bin helper");
+
+        let resolved =
+            bundled_executable_path_for_exe(&exe, /*file_name*/ "codex-command-runner.exe")
+                .expect("helper path");
+
+        assert_eq!(resolved, package_helper);
+    }
+
+    #[test]
+    fn helper_source_lookup_prefers_direct_sibling_over_resource_dir() {
+        let tmp = TempDir::new().expect("tempdir");
+        let release_dir = tmp.path().join("release");
+        let resources_dir = release_dir.join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&resources_dir).expect("create resources dir");
+        let exe = release_dir.join("codex.exe");
+        let sibling_helper = release_dir.join("codex-command-runner.exe");
+        let resource_helper = resources_dir.join("codex-command-runner.exe");
+        fs::write(&exe, b"codex").expect("write exe");
+        fs::write(&sibling_helper, b"sibling runner").expect("write sibling helper");
+        fs::write(&resource_helper, b"resource runner").expect("write resource helper");
+
+        let resolved =
+            bundled_executable_path_for_exe(&exe, /*file_name*/ "codex-command-runner.exe")
+                .expect("helper path");
+
+        assert_eq!(resolved, sibling_helper);
+    }
+
+    #[test]
+    fn helper_version_suffix_uses_cli_version_or_dev_build_metadata() {
+        let tmp = TempDir::new().expect("tempdir");
+        let source = tmp.path().join("source.exe");
+        fs::write(&source, b"runner-v1").expect("write source");
+        let suffix = helper_version_suffix(&source).expect("suffix");
+
+        if env!("CARGO_PKG_VERSION") == DEV_BUILD_VERSION_SENTINEL {
+            assert_eq!(suffix, dev_build_suffix(&source).expect("dev build suffix"));
+        } else {
+            assert_eq!(suffix, env!("CARGO_PKG_VERSION"));
+        }
+    }
+
+    #[test]
+    fn materialized_file_name_adds_suffix_before_extension() {
+        let file_name = materialized_file_name("test-suffix");
+
+        assert_eq!(file_name, "codex-command-runner-test-suffix.exe");
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/helper_materialization/copy.rs b/codex-rs/windows-sandbox-rs/src/helper_materialization/copy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2658bd350c5f2090826dc56a87c34b2fe47c3ee8
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/helper_materialization/copy.rs
@@ -0,0 +1,120 @@
+//! Copies legacy helpers using destination-inherited ACLs and the existing freshness check.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+use tempfile::NamedTempFile;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum CopyOutcome {
+    Reused,
+    ReCopied,
+}
+
+pub(super) fn copy_from_source_if_needed(source: &Path, destination: &Path) -> Result<CopyOutcome> {
+    if destination_is_fresh(source, destination)? {
+        return Ok(CopyOutcome::Reused);
+    }
+
+    let destination_dir = destination.parent().ok_or_else(|| {
+        anyhow!(
+            "helper destination has no parent: {}",
+            destination.display()
+        )
+    })?;
+    fs::create_dir_all(destination_dir).with_context(|| {
+        format!(
+            "create helper destination directory {}",
+            destination_dir.display()
+        )
+    })?;
+
+    let temp_path = NamedTempFile::new_in(destination_dir)
+        .with_context(|| {
+            format!(
+                "create temporary helper file in {}",
+                destination_dir.display()
+            )
+        })?
+        .into_temp_path();
+    let temp_path_buf = temp_path.to_path_buf();
+
+    let mut source_file = fs::File::open(source)
+        .with_context(|| format!("open helper source for read {}", source.display()))?;
+    let mut temp_file = fs::OpenOptions::new()
+        .write(true)
+        .truncate(true)
+        .open(&temp_path_buf)
+        .with_context(|| format!("open temporary helper file {}", temp_path_buf.display()))?;
+
+    // Write into a temp file created inside `.sandbox-bin` so the copied helper keeps the
+    // destination directory's inherited ACLs instead of reusing the source file's descriptor.
+    std::io::copy(&mut source_file, &mut temp_file).with_context(|| {
+        format!(
+            "copy helper from {} to {}",
+            source.display(),
+            temp_path_buf.display()
+        )
+    })?;
+    temp_file
+        .flush()
+        .with_context(|| format!("flush temporary helper file {}", temp_path_buf.display()))?;
+    drop(temp_file);
+
+    if destination.exists() {
+        fs::remove_file(destination).with_context(|| {
+            format!("remove stale helper destination {}", destination.display())
+        })?;
+    }
+
+    match fs::rename(&temp_path_buf, destination) {
+        Ok(()) => Ok(CopyOutcome::ReCopied),
+        Err(rename_err) => {
+            if destination_is_fresh(source, destination)? {
+                Ok(CopyOutcome::Reused)
+            } else {
+                Err(rename_err).with_context(|| {
+                    format!(
+                        "rename helper temp file {} to {}",
+                        temp_path_buf.display(),
+                        destination.display()
+                    )
+                })
+            }
+        }
+    }
+}
+
+fn destination_is_fresh(source: &Path, destination: &Path) -> Result<bool> {
+    let source_meta = fs::metadata(source)
+        .with_context(|| format!("read helper source metadata {}", source.display()))?;
+    let destination_meta = match fs::metadata(destination) {
+        Ok(meta) => meta,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(false),
+        Err(err) => {
+            return Err(err).with_context(|| {
+                format!("read helper destination metadata {}", destination.display())
+            });
+        }
+    };
+
+    if source_meta.len() != destination_meta.len() {
+        return Ok(false);
+    }
+
+    let source_modified = source_meta
+        .modified()
+        .with_context(|| format!("read helper source mtime {}", source.display()))?;
+    let destination_modified = destination_meta
+        .modified()
+        .with_context(|| format!("read helper destination mtime {}", destination.display()))?;
+
+    Ok(destination_modified >= source_modified)
+}
+
+#[cfg(test)]
+#[path = "copy_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/helper_materialization/copy_tests.rs b/codex-rs/windows-sandbox-rs/src/helper_materialization/copy_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8a71d392a206802843e1b4639017de3871ac924e
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/helper_materialization/copy_tests.rs
@@ -0,0 +1,58 @@
+//! Tests the legacy helper copy and freshness contract.
+
+use super::CopyOutcome;
+use super::copy_from_source_if_needed;
+use super::destination_is_fresh;
+use pretty_assertions::assert_eq;
+use std::fs;
+use tempfile::TempDir;
+
+#[test]
+fn copy_from_source_if_needed_copies_missing_destination() {
+    let tmp = TempDir::new().expect("tempdir");
+    let source = tmp.path().join("source.exe");
+    let destination = tmp.path().join("bin").join("helper.exe");
+
+    fs::write(&source, b"runner-v1").expect("write source");
+
+    let outcome = copy_from_source_if_needed(&source, &destination).expect("copy helper");
+
+    assert_eq!(CopyOutcome::ReCopied, outcome);
+    assert_eq!(
+        b"runner-v1".as_slice(),
+        fs::read(&destination).expect("read destination")
+    );
+}
+
+#[test]
+fn destination_is_fresh_uses_size_and_mtime() {
+    let tmp = TempDir::new().expect("tempdir");
+    let source = tmp.path().join("source.exe");
+    let destination = tmp.path().join("destination.exe");
+
+    fs::write(&destination, b"same-size").expect("write destination");
+    std::thread::sleep(std::time::Duration::from_secs(1));
+    fs::write(&source, b"same-size").expect("write source");
+    assert!(!destination_is_fresh(&source, &destination).expect("stale metadata"));
+
+    fs::write(&destination, b"same-size").expect("rewrite destination");
+    assert!(destination_is_fresh(&source, &destination).expect("fresh metadata"));
+}
+
+#[test]
+fn copy_from_source_if_needed_reuses_fresh_destination() {
+    let tmp = TempDir::new().expect("tempdir");
+    let source = tmp.path().join("source.exe");
+    let destination = tmp.path().join("bin").join("helper.exe");
+
+    fs::write(&source, b"runner-v1").expect("write source");
+    copy_from_source_if_needed(&source, &destination).expect("initial copy");
+
+    let outcome = copy_from_source_if_needed(&source, &destination).expect("revalidate helper");
+
+    assert_eq!(CopyOutcome::Reused, outcome);
+    assert_eq!(
+        b"runner-v1".as_slice(),
+        fs::read(&destination).expect("read destination")
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/hide_users.rs b/codex-rs/windows-sandbox-rs/src/hide_users.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c036a2c4d535ca5e77f60879add3bbc8b3989bfa
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/hide_users.rs
@@ -0,0 +1,198 @@
+use crate::logging::log_note;
+use crate::winutil::format_last_error;
+use crate::winutil::to_wide;
+use anyhow::anyhow;
+use std::ffi::OsStr;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::ERROR_PATH_NOT_FOUND;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_HIDDEN;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_SYSTEM;
+use windows_sys::Win32::Storage::FileSystem::GetFileAttributesW;
+use windows_sys::Win32::Storage::FileSystem::INVALID_FILE_ATTRIBUTES;
+use windows_sys::Win32::Storage::FileSystem::SetFileAttributesW;
+use windows_sys::Win32::System::Registry::HKEY;
+use windows_sys::Win32::System::Registry::HKEY_LOCAL_MACHINE;
+use windows_sys::Win32::System::Registry::KEY_SET_VALUE;
+use windows_sys::Win32::System::Registry::KEY_WRITE;
+use windows_sys::Win32::System::Registry::REG_DWORD;
+use windows_sys::Win32::System::Registry::REG_OPTION_NON_VOLATILE;
+use windows_sys::Win32::System::Registry::RegCloseKey;
+use windows_sys::Win32::System::Registry::RegCreateKeyExW;
+use windows_sys::Win32::System::Registry::RegDeleteValueW;
+use windows_sys::Win32::System::Registry::RegOpenKeyExW;
+use windows_sys::Win32::System::Registry::RegSetValueExW;
+
+const USERLIST_KEY_PATH: &str =
+    r"SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\SpecialAccounts\UserList";
+
+pub fn hide_newly_created_users(usernames: &[String], log_base: &Path) {
+    if usernames.is_empty() {
+        return;
+    }
+    if let Err(err) = hide_users_in_winlogon(usernames, log_base) {
+        log_note(
+            &format!("hide users: failed to update Winlogon UserList: {err}"),
+            Some(log_base),
+        );
+    }
+}
+
+pub(crate) fn unhide_sandbox_users(usernames: &[&str]) -> anyhow::Result<()> {
+    let mut key: HKEY = 0;
+    match unsafe {
+        RegOpenKeyExW(
+            HKEY_LOCAL_MACHINE,
+            to_wide(USERLIST_KEY_PATH).as_ptr(),
+            /*uloptions*/ 0,
+            KEY_SET_VALUE,
+            &mut key,
+        )
+    } {
+        ERROR_FILE_NOT_FOUND | ERROR_PATH_NOT_FOUND => return Ok(()),
+        ERROR_SUCCESS => {}
+        error => return Err(anyhow!("open sandbox hidden-user registry key: {error}")),
+    }
+
+    let mut errors = Vec::new();
+    for username in usernames {
+        let status = unsafe { RegDeleteValueW(key, to_wide(username).as_ptr()) };
+        match status {
+            ERROR_SUCCESS | ERROR_FILE_NOT_FOUND => {}
+            error => errors.push(format!("remove hidden sandbox user {username}: {error}")),
+        }
+    }
+    unsafe {
+        RegCloseKey(key);
+    }
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(anyhow!(errors.join("; ")))
+    }
+}
+
+/// Best-effort: hides the current sandbox user's profile directory once it exists.
+///
+/// Windows only creates profile directories when that user first logs in.
+/// This intentionally runs in the command-runner (as the sandbox user) because
+/// command running is what causes us to log in as a particular sandbox user.
+pub fn hide_current_user_profile_dir(log_base: &Path) {
+    let Some(profile) = std::env::var_os("USERPROFILE") else {
+        return;
+    };
+    let profile_dir = PathBuf::from(profile);
+    if !profile_dir.exists() {
+        return;
+    }
+
+    match hide_directory(&profile_dir) {
+        Ok(true) => {
+            // Log only when we actually change attributes, so this stays one-time per profile dir.
+            log_note(
+                &format!(
+                    "hide users: profile dir hidden for current user ({})",
+                    profile_dir.display()
+                ),
+                Some(log_base),
+            );
+        }
+        Ok(false) => {}
+        Err(err) => {
+            log_note(
+                &format!(
+                    "hide users: failed to hide current user profile dir ({}): {err}",
+                    profile_dir.display()
+                ),
+                Some(log_base),
+            );
+        }
+    }
+}
+
+fn hide_users_in_winlogon(usernames: &[String], log_base: &Path) -> anyhow::Result<()> {
+    let key = create_userlist_key()?;
+    for username in usernames {
+        let name_w = to_wide(OsStr::new(username));
+        let value: u32 = 0;
+        let status = unsafe {
+            RegSetValueExW(
+                key,
+                name_w.as_ptr(),
+                0,
+                REG_DWORD,
+                &value as *const u32 as *const u8,
+                std::mem::size_of_val(&value) as u32,
+            )
+        };
+        if status != 0 {
+            log_note(
+                &format!(
+                    "hide users: failed to set UserList value for {username}: {status} ({error})",
+                    error = format_last_error(status as i32)
+                ),
+                Some(log_base),
+            );
+        }
+    }
+    unsafe {
+        RegCloseKey(key);
+    }
+    Ok(())
+}
+
+fn create_userlist_key() -> anyhow::Result<HKEY> {
+    let key_path = to_wide(USERLIST_KEY_PATH);
+    let mut key: HKEY = 0;
+    let status = unsafe {
+        RegCreateKeyExW(
+            HKEY_LOCAL_MACHINE,
+            key_path.as_ptr(),
+            0,
+            std::ptr::null_mut(),
+            REG_OPTION_NON_VOLATILE,
+            KEY_WRITE,
+            std::ptr::null_mut(),
+            &mut key,
+            std::ptr::null_mut(),
+        )
+    };
+    if status != 0 {
+        return Err(anyhow!(
+            "RegCreateKeyExW failed: {status} ({error})",
+            error = format_last_error(status as i32)
+        ));
+    }
+    Ok(key)
+}
+
+/// Sets HIDDEN|SYSTEM on `path` if needed, returning whether it changed anything.
+fn hide_directory(path: &Path) -> anyhow::Result<bool> {
+    let wide = to_wide(path);
+    let attrs = unsafe { GetFileAttributesW(wide.as_ptr()) };
+    if attrs == INVALID_FILE_ATTRIBUTES {
+        let err = unsafe { GetLastError() } as i32;
+        return Err(anyhow!(
+            "GetFileAttributesW failed for {}: {err} ({error})",
+            path.display(),
+            error = format_last_error(err)
+        ));
+    }
+    let new_attrs = attrs | FILE_ATTRIBUTE_HIDDEN | FILE_ATTRIBUTE_SYSTEM;
+    if new_attrs == attrs {
+        return Ok(false);
+    }
+    let ok = unsafe { SetFileAttributesW(wide.as_ptr(), new_attrs) };
+    if ok == 0 {
+        let err = unsafe { GetLastError() } as i32;
+        return Err(anyhow!(
+            "SetFileAttributesW failed for {}: {err} ({error})",
+            path.display(),
+            error = format_last_error(err)
+        ));
+    }
+    Ok(true)
+}
diff --git a/codex-rs/windows-sandbox-rs/src/identity.rs b/codex-rs/windows-sandbox-rs/src/identity.rs
new file mode 100644
index 0000000000000000000000000000000000000000..14adc5d3ffda60100d548a404293062e9ef4f985
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/identity.rs
@@ -0,0 +1,539 @@
+use crate::SandboxRuntimeAccount;
+use crate::dpapi;
+use crate::logging::debug_log;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::setup::OFFLINE_USERNAME;
+use crate::setup::ONLINE_USERNAME;
+use crate::setup::OfflineProxySettings;
+use crate::setup::SandboxNetworkIdentity;
+use crate::setup::SandboxSetupRequest;
+use crate::setup::SandboxUserRecord;
+use crate::setup::SandboxUsersFile;
+use crate::setup::SetupMarker;
+use crate::setup::gather_read_roots;
+use crate::setup::gather_write_roots_for_permissions;
+use crate::setup::offline_proxy_settings_from_env;
+use crate::setup::run_elevated_setup_with_proxy_settings;
+use crate::setup::run_setup_refresh_with_overrides_and_proxy_settings;
+use crate::setup::sandbox_users_path;
+use crate::setup::setup_marker_path;
+use crate::winutil::local_user_flags;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::ensure;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
+use std::collections::HashMap;
+use std::fs;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_ACCOUNTDISABLE;
+use windows_sys::Win32::Security::LOGON32_LOGON_INTERACTIVE;
+use windows_sys::Win32::Security::LOGON32_PROVIDER_DEFAULT;
+use windows_sys::Win32::Security::LogonUserW;
+
+#[cfg(test)]
+#[path = "identity_integration_tests.rs"]
+mod integration_tests;
+
+#[derive(Debug, Clone)]
+struct SandboxIdentity {
+    username: String,
+    password: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct SandboxCreds {
+    pub username: String,
+    pub password: String,
+}
+
+/// Returns true when the on-disk setup artifacts exist and match the current
+/// setup version.
+///
+/// This is a coarse readiness check; `require_logon_sandbox_creds` performs the
+/// additional runtime validation for offline firewall settings.
+pub fn sandbox_setup_is_complete(codex_home: &Path) -> bool {
+    let marker_ok = matches!(load_marker(codex_home), Ok(Some(marker)) if marker.version_matches());
+    if !marker_ok {
+        return false;
+    }
+    if crate::registered_core_requested()
+        && !crate::app_package::registered_setup_is_ready(codex_home).unwrap_or(false)
+    {
+        return false;
+    }
+    matches!(load_users(codex_home), Ok(Some(users)) if users.version_matches())
+}
+
+/// Returns true when setup artifacts and provisioned network settings match.
+pub fn sandbox_setup_is_complete_with_settings(
+    codex_home: &Path,
+    settings: &crate::WindowsSandboxProvisioningSettings,
+) -> bool {
+    let Ok(Some(mut marker)) = load_marker(codex_home) else {
+        return false;
+    };
+
+    marker.proxy_ports.sort_unstable();
+    let mut proxy_ports = settings.proxy_ports.clone();
+    proxy_ports.sort_unstable();
+    marker.version_matches()
+        && marker.proxy_ports == proxy_ports
+        && marker.allow_local_binding == settings.allow_local_binding
+        && matches!(load_users(codex_home), Ok(Some(users)) if users.version_matches())
+}
+
+fn load_marker(codex_home: &Path) -> Result<Option<SetupMarker>> {
+    let path = setup_marker_path(codex_home);
+    let marker = match fs::read_to_string(&path) {
+        Ok(contents) => match serde_json::from_str::<SetupMarker>(&contents) {
+            Ok(m) => Some(m),
+            Err(err) => {
+                debug_log(
+                    &format!("sandbox setup marker parse failed: {err}"),
+                    Some(codex_home),
+                );
+                None
+            }
+        },
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
+        Err(err) => {
+            debug_log(
+                &format!("sandbox setup marker read failed: {err}"),
+                Some(codex_home),
+            );
+            None
+        }
+    };
+    Ok(marker)
+}
+
+fn load_users(codex_home: &Path) -> Result<Option<SandboxUsersFile>> {
+    let path = sandbox_users_path(codex_home);
+    let file = match fs::read_to_string(&path) {
+        Ok(contents) => contents,
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(err) => {
+            debug_log(
+                &format!("sandbox users read failed: {err}"),
+                Some(codex_home),
+            );
+            return Ok(None);
+        }
+    };
+    match serde_json::from_str::<SandboxUsersFile>(&file) {
+        Ok(users) => Ok(Some(users)),
+        Err(err) => {
+            debug_log(
+                &format!("sandbox users parse failed: {err}"),
+                Some(codex_home),
+            );
+            Ok(None)
+        }
+    }
+}
+
+fn remove_sandbox_users_file(codex_home: &Path, reason: &str) -> Result<()> {
+    let path = sandbox_users_path(codex_home);
+    debug_log(
+        &format!("{reason}; deleting {}", path.display()),
+        Some(codex_home),
+    );
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err).with_context(|| format!("delete {}", path.display())),
+    }
+}
+
+fn decode_password(record: &SandboxUserRecord) -> Result<String> {
+    let blob = BASE64_STANDARD
+        .decode(record.password.as_bytes())
+        .context("base64 decode password")?;
+    let decrypted = dpapi::unprotect(&blob)?;
+    let pwd = String::from_utf8(decrypted).context("sandbox password not utf-8")?;
+    Ok(pwd)
+}
+
+/// Opens a token for one existing managed account without provisioning or changing it.
+/// The caller must keep the authenticated credential directory pinned and verify
+/// the token's recorded SID, group membership, and non-administrator status.
+pub fn logon_existing_sandbox_account(
+    codex_home: &Path,
+    account: SandboxRuntimeAccount,
+) -> Result<OwnedHandle> {
+    // Unlike the ordinary app-side readers, this service recovery path must
+    // never create diagnostic files beneath an owner-controlled directory.
+    let marker: SetupMarker = serde_json::from_slice(
+        &fs::read(setup_marker_path(codex_home)).context("read sandbox setup marker")?,
+    )
+    .context("parse sandbox setup marker")?;
+    ensure!(
+        marker.version_matches(),
+        "sandbox setup marker is missing or incompatible"
+    );
+    let users: SandboxUsersFile = serde_json::from_slice(
+        &fs::read(sandbox_users_path(codex_home)).context("read sandbox accounts")?,
+    )
+    .context("parse sandbox accounts")?;
+    ensure!(users.version_matches(), "sandbox accounts are incompatible");
+    let record = match account {
+        SandboxRuntimeAccount::Offline => users.offline,
+        SandboxRuntimeAccount::Online => users.online,
+    };
+    ensure!(
+        record.username.eq_ignore_ascii_case(account.username()),
+        "sandbox account record does not match the managed account"
+    );
+    let password = crate::to_wide(decode_password(&record)?);
+    let mut token = 0;
+    if unsafe {
+        LogonUserW(
+            crate::to_wide(account.username()).as_ptr(),
+            crate::to_wide(".").as_ptr(),
+            password.as_ptr(),
+            LOGON32_LOGON_INTERACTIVE,
+            LOGON32_PROVIDER_DEFAULT,
+            &mut token,
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("log on existing sandbox account");
+    }
+    Ok(unsafe { OwnedHandle::from_raw_handle(token as _) })
+}
+
+fn select_identity(
+    network_identity: SandboxNetworkIdentity,
+    codex_home: &Path,
+) -> Result<Option<SandboxIdentity>> {
+    let _marker = match load_marker(codex_home)? {
+        Some(m) if m.version_matches() => m,
+        _ => return Ok(None),
+    };
+    let users = match load_users(codex_home)? {
+        Some(u) if u.version_matches() => u,
+        _ => return Ok(None),
+    };
+    let chosen = match network_identity {
+        SandboxNetworkIdentity::Offline => users.offline,
+        SandboxNetworkIdentity::Online => users.online,
+    };
+    let password = decode_password(&chosen)?;
+    Ok(Some(SandboxIdentity {
+        username: chosen.username,
+        password,
+    }))
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn require_logon_sandbox_creds(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    read_roots_override: Option<&[PathBuf]>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<&[PathBuf]>,
+    deny_read_paths_override: &[PathBuf],
+    deny_write_paths_override: &[PathBuf],
+    proxy_enforced: bool,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+) -> Result<SandboxCreds> {
+    let runtime = crate::setup::current_setup_runtime();
+    let needed_read = read_roots_override
+        .map(<[PathBuf]>::to_vec)
+        .unwrap_or_else(|| {
+            gather_read_roots(command_cwd, permissions, env_map, codex_home, runtime)
+        });
+    let needed_write = write_roots_override
+        .map(<[PathBuf]>::to_vec)
+        .unwrap_or_else(|| gather_write_roots_for_permissions(permissions, command_cwd, env_map));
+    // Do not grant the capability token write access to CODEX_HOME/.sandbox; the setup helper
+    // grants the sandbox group access separately through lock_sandbox_dir.
+    let request = SandboxSetupRequest {
+        permissions,
+        command_cwd,
+        env_map,
+        codex_home,
+        proxy_enforced,
+    };
+    let (creds, offline_proxy_settings) = require_sandbox_account(&request, proxy_settings_mode)?;
+    run_setup_refresh_with_overrides_and_proxy_settings(
+        request,
+        crate::setup::SetupRootOverrides {
+            read_roots: Some(needed_read),
+            read_roots_include_platform_defaults,
+            write_roots: Some(needed_write),
+            deny_read_paths: Some(deny_read_paths_override.to_vec()),
+            deny_write_paths: Some(deny_write_paths_override.to_vec()),
+        },
+        &offline_proxy_settings,
+    )?;
+    Ok(creds)
+}
+
+/// Ensures the selected account is ready; launchers must refresh filesystem ACLs separately.
+pub(crate) fn require_sandbox_account(
+    request: &SandboxSetupRequest<'_>,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+) -> Result<(SandboxCreds, OfflineProxySettings)> {
+    require_sandbox_account_with_setup(
+        request,
+        proxy_settings_mode,
+        run_elevated_setup_with_proxy_settings,
+        local_user_flags,
+    )
+}
+
+fn require_sandbox_account_with_setup(
+    request: &SandboxSetupRequest<'_>,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+    run_full_setup: impl FnOnce(SandboxSetupRequest<'_>, &OfflineProxySettings) -> Result<()>,
+    read_local_user_flags: impl Fn(&str) -> Result<Option<u32>>,
+) -> Result<(SandboxCreds, OfflineProxySettings)> {
+    let &SandboxSetupRequest {
+        permissions,
+        command_cwd,
+        env_map,
+        codex_home,
+        proxy_enforced,
+    } = request;
+    let sandbox_dir = crate::setup::sandbox_dir(codex_home);
+    let network_identity = SandboxNetworkIdentity::from_permissions(permissions, proxy_enforced);
+    let marker = load_marker(codex_home)?;
+    let desired_offline_proxy_settings = desired_offline_proxy_settings(
+        marker.as_ref(),
+        proxy_settings_mode,
+        env_map,
+        network_identity,
+    );
+    let mut setup_reason: Option<String> = None;
+
+    let mut identity = match marker {
+        Some(marker) if marker.version_matches() => {
+            if let Some(reason) =
+                marker.request_mismatch_reason(network_identity, &desired_offline_proxy_settings)
+            {
+                setup_reason = Some(reason);
+                None
+            } else {
+                let selected = select_identity(network_identity, codex_home)?;
+                if selected.is_none() {
+                    setup_reason = Some(
+                        "sandbox users missing or incompatible with marker version".to_string(),
+                    );
+                }
+                selected
+            }
+        }
+        _ => {
+            setup_reason = Some("sandbox setup marker missing or incompatible".to_string());
+            None
+        }
+    };
+
+    if identity.is_some() {
+        // Cleanup may also have removed the group, so repair missing or disabled accounts before ACL
+        // refresh can fail, not only after a later logon reports ERROR_ACCOUNT_DISABLED.
+        for username in [OFFLINE_USERNAME, ONLINE_USERNAME] {
+            let needs_repair = match read_local_user_flags(username) {
+                Ok(Some(flags)) => flags & UF_ACCOUNTDISABLE != 0,
+                Ok(None) => true,
+                Err(_) => false,
+            };
+            if needs_repair {
+                setup_reason = Some("sandbox account is missing or disabled".to_string());
+                identity = None;
+                break;
+            }
+        }
+    }
+
+    if identity.is_none() {
+        if let Some(reason) = &setup_reason {
+            crate::logging::log_note(
+                &format!("sandbox setup required: {reason}"),
+                Some(&sandbox_dir),
+            );
+        } else {
+            crate::logging::log_note("sandbox setup required", Some(&sandbox_dir));
+        }
+        run_full_setup(
+            crate::setup::SandboxSetupRequest {
+                permissions,
+                command_cwd,
+                env_map,
+                codex_home,
+                proxy_enforced,
+            },
+            &desired_offline_proxy_settings,
+        )?;
+        identity = select_identity(network_identity, codex_home)?;
+    }
+    let identity = identity.ok_or_else(|| {
+        anyhow!(
+            "Windows sandbox setup is missing or out of date; rerun the sandbox setup with elevation"
+        )
+    })?;
+    Ok((
+        SandboxCreds {
+            username: identity.username,
+            password: identity.password,
+        },
+        desired_offline_proxy_settings,
+    ))
+}
+
+fn desired_offline_proxy_settings(
+    marker: Option<&SetupMarker>,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+    env_map: &HashMap<String, String>,
+    network_identity: SandboxNetworkIdentity,
+) -> crate::setup::OfflineProxySettings {
+    match (marker, proxy_settings_mode) {
+        (Some(marker), crate::WindowsSandboxProxySettingsMode::Preserve)
+            if marker.version_matches() =>
+        {
+            marker.offline_proxy_settings()
+        }
+        _ => offline_proxy_settings_from_env(env_map, network_identity),
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn refresh_logon_sandbox_creds(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    read_roots_override: Option<&[PathBuf]>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<&[PathBuf]>,
+    deny_read_paths_override: &[PathBuf],
+    deny_write_paths_override: &[PathBuf],
+    proxy_enforced: bool,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+) -> Result<SandboxCreds> {
+    remove_sandbox_users_file(codex_home, "sandbox user login failed")?;
+    require_logon_sandbox_creds(
+        permissions,
+        command_cwd,
+        env_map,
+        codex_home,
+        read_roots_override,
+        read_roots_include_platform_defaults,
+        write_roots_override,
+        deny_read_paths_override,
+        deny_write_paths_override,
+        proxy_enforced,
+        proxy_settings_mode,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::desired_offline_proxy_settings;
+    use super::remove_sandbox_users_file;
+    use crate::WindowsSandboxProxySettingsMode;
+    use crate::setup::SandboxNetworkIdentity;
+    use crate::setup::SetupMarker;
+    use crate::setup::sandbox_users_path;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashMap;
+    use std::fs;
+    use tempfile::TempDir;
+
+    #[test]
+    fn remove_sandbox_users_file_deletes_existing_file() {
+        let codex_home = TempDir::new().expect("tempdir");
+        let users_path = sandbox_users_path(codex_home.path());
+        fs::create_dir_all(users_path.parent().expect("sandbox secrets dir"))
+            .expect("create sandbox secrets dir");
+        fs::write(&users_path, "users").expect("write users");
+
+        remove_sandbox_users_file(codex_home.path(), "stale creds").expect("remove users");
+        assert!(!users_path.exists());
+    }
+
+    #[test]
+    fn remove_sandbox_users_file_ignores_missing_file() {
+        let codex_home = TempDir::new().expect("tempdir");
+        let users_path = sandbox_users_path(codex_home.path());
+
+        remove_sandbox_users_file(codex_home.path(), "stale creds").expect("remove users");
+        assert!(!users_path.exists());
+    }
+
+    #[test]
+    fn preserving_proxy_settings_uses_the_existing_marker() {
+        let marker = SetupMarker {
+            version: crate::setup::SETUP_VERSION,
+            offline_username: "offline".to_string(),
+            online_username: "online".to_string(),
+            created_at: None,
+            proxy_ports: vec![7890],
+            allow_local_binding: true,
+        };
+        let env_map = HashMap::from([(
+            "HTTP_PROXY".to_string(),
+            "http://127.0.0.1:8080".to_string(),
+        )]);
+
+        assert_eq!(
+            desired_offline_proxy_settings(
+                Some(&marker),
+                WindowsSandboxProxySettingsMode::Preserve,
+                &env_map,
+                SandboxNetworkIdentity::Offline,
+            ),
+            marker.offline_proxy_settings()
+        );
+        assert_eq!(
+            desired_offline_proxy_settings(
+                Some(&marker),
+                WindowsSandboxProxySettingsMode::Reconcile,
+                &env_map,
+                SandboxNetworkIdentity::Offline,
+            )
+            .proxy_ports,
+            vec![8080]
+        );
+    }
+
+    #[test]
+    fn guardian_preserve_mode_does_not_churn_marker_with_empty_proxy_ports() {
+        let marker = SetupMarker {
+            version: crate::setup::SETUP_VERSION,
+            offline_username: "offline".to_string(),
+            online_username: "online".to_string(),
+            created_at: None,
+            proxy_ports: vec![3128, 8081],
+            allow_local_binding: true,
+        };
+        let env_map = HashMap::new();
+        let reconciled = desired_offline_proxy_settings(
+            Some(&marker),
+            WindowsSandboxProxySettingsMode::Reconcile,
+            &env_map,
+            SandboxNetworkIdentity::Offline,
+        );
+        assert_eq!(reconciled.proxy_ports, Vec::<u16>::new());
+
+        let desired = desired_offline_proxy_settings(
+            Some(&marker),
+            WindowsSandboxProxySettingsMode::Preserve,
+            &env_map,
+            SandboxNetworkIdentity::Offline,
+        );
+        assert_eq!(desired, marker.offline_proxy_settings());
+        assert_eq!(
+            marker.request_mismatch_reason(SandboxNetworkIdentity::Offline, &desired),
+            None
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/identity_integration_tests.rs b/codex-rs/windows-sandbox-rs/src/identity_integration_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..96cc83203f6eb72fc1ab4ef1ce0e2c198e77782d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/identity_integration_tests.rs
@@ -0,0 +1,112 @@
+//! Exercises account preparation with real marker files and DPAPI credentials.
+//! Setup and account lookup callbacks isolate machine state. This does not exercise
+//! the public wrapper, native account queries, payload serialization, singleflight,
+//! or helper launches.
+
+use super::require_sandbox_account_with_setup;
+use crate::WindowsSandboxProxySettingsMode;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::setup::SETUP_VERSION;
+use crate::setup::SandboxSetupRequest;
+use crate::setup::SandboxUserRecord;
+use crate::setup::SandboxUsersFile;
+use crate::setup::SetupMarker;
+use crate::setup::sandbox_users_path;
+use crate::setup::setup_marker_path;
+use anyhow::Result;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use codex_protocol::models::PermissionProfile;
+use pretty_assertions::assert_eq;
+use std::cell::Cell;
+use std::collections::HashMap;
+use std::fs;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_NORMAL_ACCOUNT;
+
+#[test]
+fn credential_setup_reconciles_effective_firewall_policy() -> Result<()> {
+    let permissions = ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+        &PermissionProfile::read_only(),
+    )?;
+    for (stored_binding, desired_binding, ports, expected_full_setups) in [
+        (true, true, "8080", 0),
+        (true, true, "", 0),
+        (true, true, "8080,3129", 0),
+        (false, false, "8080", 1),
+        (false, false, "", 1),
+        (false, true, "3128", 1),
+        (true, false, "3128", 1),
+    ] {
+        let full_setups = Cell::new(/*value*/ 0);
+        let home = tempfile::tempdir()?;
+        let marker = SetupMarker {
+            version: SETUP_VERSION,
+            offline_username: "offline".into(),
+            online_username: "online".into(),
+            created_at: None,
+            proxy_ports: vec![3128],
+            allow_local_binding: stored_binding,
+        };
+        let user = SandboxUserRecord {
+            username: marker.offline_username.clone(),
+            password: BASE64.encode(crate::dpapi::protect(b"test-password")?),
+        };
+        let users = SandboxUsersFile {
+            version: SETUP_VERSION,
+            offline: user.clone(),
+            online: SandboxUserRecord {
+                username: marker.online_username.clone(),
+                ..user
+            },
+        };
+        let marker_bytes = serde_json::to_vec(&marker)?;
+        for (path, bytes) in [
+            (setup_marker_path(home.path()), marker_bytes.clone()),
+            (sandbox_users_path(home.path()), serde_json::to_vec(&users)?),
+        ] {
+            fs::create_dir_all(path.parent().unwrap())?;
+            fs::write(path, bytes)?;
+        }
+        let env = HashMap::from([
+            ("CODEX_WINDOWS_SANDBOX_PROXY_PORTS".into(), ports.into()),
+            (
+                "CODEX_NETWORK_ALLOW_LOCAL_BINDING".into(),
+                u8::from(desired_binding).to_string(),
+            ),
+        ]);
+        let prepare = || {
+            require_sandbox_account_with_setup(
+                &SandboxSetupRequest {
+                    permissions: &permissions,
+                    command_cwd: home.path(),
+                    env_map: &env,
+                    codex_home: home.path(),
+                    proxy_enforced: true,
+                },
+                WindowsSandboxProxySettingsMode::Reconcile,
+                |_, desired| {
+                    full_setups.set(full_setups.get() + 1);
+                    let mut reconciled = marker.clone();
+                    reconciled.proxy_ports = desired.proxy_ports.clone();
+                    reconciled.allow_local_binding = desired.allow_local_binding;
+                    fs::write(
+                        setup_marker_path(home.path()),
+                        serde_json::to_vec(&reconciled)?,
+                    )?;
+                    Ok(())
+                },
+                |_| Ok(Some(UF_NORMAL_ACCOUNT)),
+            )
+        };
+        for _ in 0..2 {
+            let (creds, _) = prepare()?;
+            assert_eq!(
+                (creds.username, creds.password),
+                ("offline".into(), "test-password".into())
+            );
+        }
+        // The second command reuses reconciled settings, including when filtering removed the proxy.
+        assert_eq!(full_setups.get(), expected_full_setups);
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/installation_record.rs b/codex-rs/windows-sandbox-rs/src/installation_record.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3fc2f23ad25b7e427c6e74094f05bb180da7a2cc
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/installation_record.rs
@@ -0,0 +1,101 @@
+//! Persists the authenticated sandbox owner across service restarts and package updates.
+//! The shared store keeps the service's existing key, bounded REG_SZ format, and semantics.
+
+use std::io;
+use std::mem::size_of;
+use std::path::PathBuf;
+use std::ptr;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use serde::Deserialize;
+use serde::Serialize;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::System::Registry as registry;
+
+use crate::runtime_ownership::RuntimeRegistration;
+use crate::winutil::to_wide;
+
+// Package updates can replace the service key, so keep this record outside it.
+pub const INSTALLATION_KEY: &str = r"SOFTWARE\OpenAI\Codex\WindowsSandboxService";
+pub const INSTALLATION_VALUE: &str = "ProvisionedInstallation";
+const MAX_VALUE_UNITS: usize = 4096;
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct DesktopInstallation {
+    pub created_codex_home: bool,
+    pub cache_home: PathBuf,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct InstallationRecord {
+    pub user_sid: String,
+    pub codex_home: PathBuf,
+    pub session_id: u32,
+    #[serde(default)]
+    pub desktop_installation: Option<DesktopInstallation>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub runtime: Option<RuntimeRegistration>,
+}
+
+pub(crate) fn load_from(key: &str) -> Result<Option<InstallationRecord>> {
+    let mut value = [0_u16; MAX_VALUE_UNITS];
+    let mut value_length = std::mem::size_of_val(&value) as u32;
+    let status = unsafe {
+        registry::RegGetValueW(
+            registry::HKEY_LOCAL_MACHINE,
+            to_wide(key).as_ptr(),
+            to_wide(INSTALLATION_VALUE).as_ptr(),
+            registry::RRF_RT_REG_SZ,
+            ptr::null_mut(),
+            value.as_mut_ptr().cast(),
+            &mut value_length,
+        )
+    };
+    match status {
+        foundation::ERROR_FILE_NOT_FOUND | foundation::ERROR_PATH_NOT_FOUND => return Ok(None),
+        foundation::ERROR_SUCCESS => {}
+        status => {
+            return Err(io::Error::from_raw_os_error(status as i32))
+                .context("read protected sandbox installation record");
+        }
+    }
+    ensure!(
+        value_length as usize <= std::mem::size_of_val(&value)
+            && value_length.is_multiple_of(size_of::<u16>() as u32),
+        "sandbox installation record has an invalid length"
+    );
+    let value = value[..value_length as usize / size_of::<u16>()]
+        .strip_suffix(&[0])
+        .context("sandbox installation record is not null-terminated")?;
+    let value = String::from_utf16(value).context("decode sandbox installation record")?;
+    let record = serde_json::from_str(&value).context("parse sandbox installation record")?;
+    Ok(Some(record))
+}
+
+pub(crate) fn save_to(key: &str, record: &InstallationRecord) -> Result<()> {
+    let value = to_wide(
+        serde_json::to_string(record).context("serialize protected sandbox installation record")?,
+    );
+    ensure!(
+        value.len() <= MAX_VALUE_UNITS,
+        "sandbox installation record exceeds its size limit"
+    );
+    let status = unsafe {
+        registry::RegSetKeyValueW(
+            registry::HKEY_LOCAL_MACHINE,
+            to_wide(key).as_ptr(),
+            to_wide(INSTALLATION_VALUE).as_ptr(),
+            registry::REG_SZ,
+            value.as_ptr().cast(),
+            (value.len() * size_of::<u16>()) as u32,
+        )
+    };
+    if status == foundation::ERROR_SUCCESS {
+        Ok(())
+    } else {
+        Err(io::Error::from_raw_os_error(status as i32))
+            .context("persist protected sandbox installation record")
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/lib.rs b/codex-rs/windows-sandbox-rs/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4393e9e1913b26d5f81d3e5e11d2e2abc4523ede
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/lib.rs
@@ -0,0 +1,1058 @@
+// Rust 2024 surfaces this lint across the crate; keep the edition bump separate
+// from the eventual unsafe cleanup.
+#![allow(unsafe_op_in_unsafe_fn)]
+
+#[cfg(any(target_os = "windows", test))]
+mod ssh_config_dependencies;
+
+use std::fmt;
+use std::sync::Arc;
+
+use serde::Deserialize;
+use serde::Serialize;
+
+/// Cancellation hook used by Windows sandbox capture backends.
+#[derive(Clone)]
+pub struct WindowsSandboxCancellationToken {
+    is_cancelled: Arc<dyn Fn() -> bool + Send + Sync>,
+}
+
+impl WindowsSandboxCancellationToken {
+    /// Creates a token backed by a cancellation predicate.
+    pub fn new(is_cancelled: impl Fn() -> bool + Send + Sync + 'static) -> Self {
+        Self {
+            is_cancelled: Arc::new(is_cancelled),
+        }
+    }
+
+    /// Returns whether the caller has requested cancellation.
+    pub fn is_cancelled(&self) -> bool {
+        (self.is_cancelled)()
+    }
+}
+
+impl fmt::Debug for WindowsSandboxCancellationToken {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("WindowsSandboxCancellationToken")
+            .finish_non_exhaustive()
+    }
+}
+
+pub use codex_protocol::config_types::WindowsSandboxProxySettingsMode;
+
+/// Network settings installed by an administrator during managed Windows sandbox setup.
+#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct WindowsSandboxProvisioningSettings {
+    /// Loopback proxy ports permitted for the offline sandbox identity.
+    pub proxy_ports: Vec<u16>,
+    /// Whether the offline sandbox identity may exchange arbitrary loopback traffic.
+    pub allow_local_binding: bool,
+}
+
+#[cfg(target_os = "windows")]
+mod acl;
+#[cfg(target_os = "windows")]
+mod allow;
+#[cfg(target_os = "windows")]
+mod app_package;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use app_package::registered_core_needs_refresh;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use app_package::registered_core_requested;
+#[cfg(target_os = "windows")]
+mod audit;
+#[cfg(target_os = "windows")]
+mod cap;
+#[cfg(target_os = "windows")]
+mod deny_read_acl;
+#[cfg(target_os = "windows")]
+mod deny_read_state;
+#[cfg(target_os = "windows")]
+mod desktop;
+#[cfg(target_os = "windows")]
+mod dpapi;
+#[cfg(target_os = "windows")]
+mod env;
+#[cfg(target_os = "windows")]
+mod file_write;
+#[cfg(target_os = "windows")]
+mod framed_io;
+#[cfg(target_os = "windows")]
+mod helper_materialization;
+#[cfg(target_os = "windows")]
+mod hide_users;
+#[cfg(target_os = "windows")]
+mod identity;
+#[cfg(target_os = "windows")]
+mod installation_record;
+#[cfg(target_os = "windows")]
+mod logging;
+#[cfg(target_os = "windows")]
+mod no_reparse_dir;
+#[cfg(target_os = "windows")]
+mod package_identity;
+#[cfg(target_os = "windows")]
+mod path_normalization;
+#[cfg(target_os = "windows")]
+mod process;
+#[cfg(target_os = "windows")]
+mod provisioning_client;
+#[cfg(target_os = "windows")]
+mod provisioning_protocol;
+#[cfg(target_os = "windows")]
+mod runtime_ownership;
+#[cfg(target_os = "windows")]
+mod service_identity;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::CORE_INSTALLATION_KEY;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::INSTALLATION_KEY;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::INSTALLATION_VALUE;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::RuntimeAccountRegistration;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::RuntimeRegistration;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::load_installation;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::remove_installation;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use runtime_ownership::save_installation;
+#[cfg(target_os = "windows")]
+mod resolved_permissions;
+#[cfg(target_os = "windows")]
+mod token;
+#[cfg(target_os = "windows")]
+mod token_user;
+#[cfg(target_os = "windows")]
+mod wfp;
+#[cfg(target_os = "windows")]
+mod wfp_setup;
+#[cfg(target_os = "windows")]
+mod winutil;
+#[cfg(target_os = "windows")]
+mod workspace_acl;
+
+mod deny_read_resolver;
+#[cfg(target_os = "windows")]
+mod uninstall_windows;
+
+#[cfg(target_os = "windows")]
+mod conpty;
+
+#[cfg(target_os = "windows")]
+mod elevated;
+
+#[cfg(target_os = "windows")]
+mod elevated_impl;
+
+#[cfg(target_os = "windows")]
+mod proc_thread_attr;
+
+#[cfg(target_os = "windows")]
+mod sandbox_utils;
+
+#[cfg(target_os = "windows")]
+mod setup;
+
+#[cfg(target_os = "windows")]
+mod setup_error;
+
+#[cfg(target_os = "windows")]
+mod setup_launch;
+
+#[cfg(target_os = "windows")]
+mod setup_mutex;
+
+#[cfg(target_os = "windows")]
+mod setup_provisioning;
+
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use setup_provisioning::main as setup_helper_main;
+#[cfg(target_os = "windows")]
+pub use setup_provisioning::provision_sandbox_in_process;
+
+#[cfg(target_os = "windows")]
+mod spawn_prep;
+
+#[cfg(target_os = "windows")]
+mod stdio_bridge;
+
+#[cfg(target_os = "windows")]
+mod unified_exec;
+#[cfg(target_os = "windows")]
+mod wrapper;
+
+#[cfg(target_os = "windows")]
+pub(crate) use elevated::ipc_framed;
+
+#[cfg(target_os = "windows")]
+pub(crate) use elevated::runner_client;
+
+#[cfg(target_os = "windows")]
+pub(crate) use elevated::runner_pipe;
+
+#[cfg(target_os = "windows")]
+pub use installation_record::DesktopInstallation;
+#[cfg(target_os = "windows")]
+pub use installation_record::InstallationRecord;
+
+#[cfg(target_os = "windows")]
+pub use acl::add_deny_read_ace;
+#[cfg(target_os = "windows")]
+pub use acl::add_deny_write_ace;
+
+#[cfg(target_os = "windows")]
+pub use acl::allow_null_device;
+#[cfg(target_os = "windows")]
+pub use acl::ensure_allow_mask_aces;
+#[cfg(target_os = "windows")]
+pub use acl::ensure_allow_mask_aces_with_inheritance;
+#[cfg(target_os = "windows")]
+pub use acl::ensure_allow_write_aces;
+#[cfg(target_os = "windows")]
+pub use acl::fetch_dacl_handle;
+#[cfg(target_os = "windows")]
+pub use acl::path_has_standard_user_mutation_allow;
+#[cfg(target_os = "windows")]
+pub use acl::path_has_trusted_system_owner;
+#[cfg(target_os = "windows")]
+pub use acl::path_mask_allows;
+#[cfg(target_os = "windows")]
+pub use acl::path_or_child_file_has_standard_user_mutation_allow;
+#[cfg(target_os = "windows")]
+pub use acl::path_write_aces_need_refresh;
+#[cfg(target_os = "windows")]
+pub use acl::revoke_ace;
+#[cfg(target_os = "windows")]
+pub use audit::apply_world_writable_scan_and_denies_for_permissions;
+#[cfg(target_os = "windows")]
+pub use cap::load_or_create_cap_sids;
+#[cfg(target_os = "windows")]
+pub use cap::workspace_cap_sid_for_cwd;
+#[cfg(target_os = "windows")]
+pub use cap::workspace_write_cap_sid_for_root;
+#[cfg(target_os = "windows")]
+pub use cap::workspace_write_root_contains_path;
+#[cfg(target_os = "windows")]
+pub use cap::workspace_write_root_overlaps_path;
+#[cfg(target_os = "windows")]
+pub use conpty::ConptyInstance;
+#[cfg(target_os = "windows")]
+pub use conpty::spawn_conpty_process_as_user;
+#[cfg(target_os = "windows")]
+pub use deny_read_acl::apply_deny_read_acls;
+#[cfg(target_os = "windows")]
+pub use deny_read_acl::plan_deny_read_acl_paths;
+pub use deny_read_resolver::resolve_windows_deny_read_paths;
+#[cfg(target_os = "windows")]
+pub use deny_read_state::sync_persistent_deny_read_acls;
+#[cfg(target_os = "windows")]
+pub use desktop::LaunchDesktop;
+#[cfg(target_os = "windows")]
+pub use dpapi::protect as dpapi_protect;
+#[cfg(target_os = "windows")]
+pub use dpapi::unprotect as dpapi_unprotect;
+#[cfg(target_os = "windows")]
+pub use elevated_impl::ElevatedSandboxProfileCaptureRequest;
+#[cfg(target_os = "windows")]
+pub use elevated_impl::run_windows_sandbox_capture_for_permission_profile as run_windows_sandbox_capture_for_permission_profile_elevated;
+#[cfg(target_os = "windows")]
+pub use file_write::write_file_atomically;
+#[cfg(target_os = "windows")]
+pub use helper_materialization::resolve_exe_for_launch;
+#[cfg(target_os = "windows")]
+pub use hide_users::hide_current_user_profile_dir;
+#[cfg(target_os = "windows")]
+pub use hide_users::hide_newly_created_users;
+#[cfg(target_os = "windows")]
+pub use identity::logon_existing_sandbox_account;
+#[cfg(target_os = "windows")]
+pub use identity::require_logon_sandbox_creds;
+#[cfg(target_os = "windows")]
+pub use identity::sandbox_setup_is_complete;
+#[cfg(target_os = "windows")]
+pub use identity::sandbox_setup_is_complete_with_settings;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::ErrorPayload;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::ErrorStage;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::ExitPayload;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::FramedMessage;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::IPC_PROTOCOL_VERSION;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::Message;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::OutputPayload;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::OutputStream;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::ResizePayload;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::SpawnReady;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::SpawnRequest;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::decode_bytes;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::encode_bytes;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::read_frame;
+#[cfg(target_os = "windows")]
+pub use ipc_framed::write_frame;
+#[cfg(target_os = "windows")]
+pub use logging::current_log_file_path;
+#[cfg(target_os = "windows")]
+pub use logging::current_log_file_path_for_codex_home;
+#[cfg(target_os = "windows")]
+pub use logging::log_file_path_for_utc_date;
+#[cfg(target_os = "windows")]
+pub use logging::log_note;
+#[cfg(target_os = "windows")]
+pub use logging::log_writer;
+#[cfg(target_os = "windows")]
+pub use logging::setup_log_writer;
+#[cfg(target_os = "windows")]
+pub use no_reparse_dir::DirectoryOpenDisposition;
+#[cfg(target_os = "windows")]
+pub use no_reparse_dir::create_directory_guard;
+#[cfg(target_os = "windows")]
+pub use no_reparse_dir::open_directory_no_reparse;
+#[cfg(target_os = "windows")]
+pub use no_reparse_dir::validate_local_directory_path;
+#[cfg(target_os = "windows")]
+pub use package_identity::process_package_family;
+#[cfg(target_os = "windows")]
+pub use path_normalization::canonicalize_path;
+#[cfg(target_os = "windows")]
+pub use process::ConsoleMode;
+#[cfg(target_os = "windows")]
+pub use process::PipeSpawnHandles;
+#[cfg(target_os = "windows")]
+pub use process::StderrMode;
+#[cfg(target_os = "windows")]
+pub use process::StdinMode;
+#[cfg(target_os = "windows")]
+pub use process::create_process_as_user;
+#[cfg(target_os = "windows")]
+pub use process::read_handle_loop;
+#[cfg(target_os = "windows")]
+pub use process::spawn_process_with_pipes;
+#[cfg(target_os = "windows")]
+pub use provisioning_client::WindowsSandboxProvisioningOutcome;
+#[cfg(target_os = "windows")]
+pub use provisioning_client::provision_windows_sandbox_via_service;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use provisioning_client::refresh_registered_core_via_service;
+#[cfg(target_os = "windows")]
+pub use provisioning_client::register_desktop_installation;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::FramedProvisioningMessage;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::PROVISIONING_PROTOCOL_VERSION;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::ProvisioningMessage;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::SANDBOX_GROUP_CHANGED;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::SANDBOX_PROVISIONING_PIPE_NAME;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::SandboxProvisioningRequest;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::SandboxProvisioningResponse;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::WindowsSandboxProxyListeners;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::read_provisioning_frame;
+#[cfg(target_os = "windows")]
+pub use provisioning_protocol::write_provisioning_frame;
+#[cfg(target_os = "windows")]
+pub use resolved_permissions::ResolvedWindowsSandboxPermissions;
+#[cfg(target_os = "windows")]
+pub use resolved_permissions::WindowsSandboxTokenMode;
+#[cfg(target_os = "windows")]
+pub use resolved_permissions::token_mode_for_permission_profile;
+#[cfg(target_os = "windows")]
+pub use runtime_ownership::APP_CORE_RUNNER_ALIAS;
+#[cfg(target_os = "windows")]
+pub use runtime_ownership::SandboxRuntimeAccount;
+
+#[cfg(target_os = "windows")]
+pub use service_identity::windows_sandbox_service_name;
+#[cfg(target_os = "windows")]
+pub use service_identity::windows_sandbox_service_pipe_name;
+#[cfg(target_os = "windows")]
+pub use setup::OFFLINE_USERNAME;
+#[cfg(target_os = "windows")]
+pub use setup::ONLINE_USERNAME;
+#[cfg(target_os = "windows")]
+pub use setup::SETUP_VERSION;
+#[cfg(target_os = "windows")]
+pub use setup::SandboxSetupRequest;
+#[cfg(target_os = "windows")]
+pub use setup::SetupRootOverrides;
+#[cfg(target_os = "windows")]
+pub use setup::SetupRuntime;
+#[cfg(target_os = "windows")]
+pub use setup::run_elevated_provisioning_setup;
+#[cfg(target_os = "windows")]
+pub use setup::run_elevated_provisioning_setup_with_retained_handles;
+#[cfg(target_os = "windows")]
+pub use setup::run_elevated_setup;
+#[cfg(target_os = "windows")]
+pub use setup::run_setup_refresh;
+#[cfg(target_os = "windows")]
+pub use setup::run_setup_refresh_with_extra_read_roots;
+#[cfg(target_os = "windows")]
+pub use setup::sandbox_bin_dir;
+#[cfg(target_os = "windows")]
+pub use setup::sandbox_dir;
+#[cfg(target_os = "windows")]
+pub use setup::sandbox_secrets_dir;
+#[cfg(target_os = "windows")]
+pub use setup_error::SetupErrorCode;
+#[cfg(target_os = "windows")]
+pub use setup_error::SetupErrorReport;
+#[cfg(target_os = "windows")]
+pub use setup_error::SetupFailure;
+#[cfg(target_os = "windows")]
+pub use setup_error::extract_failure as extract_setup_failure;
+#[cfg(target_os = "windows")]
+pub use setup_error::read_setup_error_report;
+#[cfg(target_os = "windows")]
+pub use setup_error::sanitize_setup_metric_tag_value;
+#[cfg(target_os = "windows")]
+pub use setup_error::setup_error_path;
+#[cfg(target_os = "windows")]
+pub use setup_error::write_setup_error_report;
+#[cfg(target_os = "windows")]
+pub use setup_mutex::acquire_sandbox_setup_lock;
+#[cfg(target_os = "windows")]
+pub use stdio_bridge::forward_sandbox_session_stdio;
+#[cfg(target_os = "windows")]
+#[doc(hidden)]
+pub use token::LocalSid;
+#[cfg(target_os = "windows")]
+pub use token::TokenGroup;
+#[cfg(target_os = "windows")]
+pub use token::convert_string_sid_to_sid;
+#[cfg(target_os = "windows")]
+pub use token::create_readonly_token_with_cap_from;
+#[cfg(target_os = "windows")]
+pub use token::create_readonly_token_with_caps_and_user_from;
+#[cfg(target_os = "windows")]
+pub use token::create_readonly_token_with_caps_from;
+#[cfg(target_os = "windows")]
+pub use token::create_workspace_write_token_with_caps_and_user_from;
+#[cfg(target_os = "windows")]
+pub use token::create_workspace_write_token_with_caps_from;
+#[cfg(target_os = "windows")]
+pub use token::get_current_token_for_restriction;
+#[cfg(target_os = "windows")]
+pub use token::token_groups;
+#[cfg(target_os = "windows")]
+pub use token_user::get_user_sid_bytes;
+#[cfg(target_os = "windows")]
+pub use unified_exec::WindowsSandboxSessionRequest;
+#[cfg(target_os = "windows")]
+pub use unified_exec::spawn_windows_sandbox_session_elevated_for_permission_profile;
+#[cfg(target_os = "windows")]
+pub use unified_exec::spawn_windows_sandbox_session_for_level;
+#[cfg(target_os = "windows")]
+pub use unified_exec::spawn_windows_sandbox_session_legacy;
+#[cfg(target_os = "windows")]
+pub use uninstall_windows::PreparedWindowsSandboxCleanup;
+#[cfg(target_os = "windows")]
+pub use uninstall_windows::clean_up_packaged_windows_sandbox;
+#[cfg(target_os = "windows")]
+pub use uninstall_windows::prepare_packaged_windows_sandbox_cleanup;
+#[cfg(target_os = "windows")]
+pub use uninstall_windows::prepare_packaged_windows_sandbox_cleanup_with_retained_tokens;
+#[cfg(target_os = "windows")]
+pub use wfp::install_wfp_filters_for_account;
+#[cfg(target_os = "windows")]
+pub use wfp_setup::install_wfp_filters;
+#[cfg(target_os = "windows")]
+pub use windows_impl::CaptureResult;
+#[cfg(target_os = "windows")]
+pub use windows_impl::run_windows_sandbox_capture;
+#[cfg(target_os = "windows")]
+pub use windows_impl::run_windows_sandbox_capture_with_filesystem_overrides;
+#[cfg(target_os = "windows")]
+pub use windows_impl::run_windows_sandbox_legacy_preflight;
+#[cfg(target_os = "windows")]
+pub use winutil::SANDBOX_USERS_GROUP;
+#[cfg(target_os = "windows")]
+pub use winutil::account_name_from_sid;
+#[cfg(target_os = "windows")]
+pub use winutil::ensure_sandbox_users_group;
+#[cfg(target_os = "windows")]
+pub use winutil::local_user_flags;
+#[cfg(target_os = "windows")]
+pub use winutil::quote_windows_arg;
+#[cfg(target_os = "windows")]
+pub use winutil::resolve_sid;
+#[cfg(target_os = "windows")]
+pub use winutil::set_local_user_flags;
+#[cfg(target_os = "windows")]
+pub use winutil::string_from_sid_bytes;
+#[cfg(target_os = "windows")]
+pub use winutil::to_wide;
+#[cfg(target_os = "windows")]
+pub use workspace_acl::is_command_cwd_root;
+#[cfg(target_os = "windows")]
+pub use wrapper::CODEX_WINDOWS_SANDBOX_ARG1;
+#[cfg(target_os = "windows")]
+pub use wrapper::create_windows_sandbox_command_args_for_permission_profile;
+#[cfg(target_os = "windows")]
+pub use wrapper::run_windows_sandbox_wrapper_main;
+
+#[cfg(not(target_os = "windows"))]
+pub use stub::CaptureResult;
+#[cfg(not(target_os = "windows"))]
+pub use stub::run_windows_sandbox_capture;
+#[cfg(not(target_os = "windows"))]
+pub use stub::run_windows_sandbox_legacy_preflight;
+
+#[cfg(target_os = "windows")]
+mod windows_impl {
+    use super::WindowsSandboxCancellationToken;
+    use super::logging::log_failure;
+    use super::logging::log_note;
+    use super::logging::log_success;
+    use super::process::ConsoleMode;
+    use super::process::create_process_as_user;
+    use super::sandbox_utils::ensure_codex_home_exists;
+    use super::spawn_prep::LegacyAclSids;
+    use super::spawn_prep::SpawnPrepOptions;
+    use super::spawn_prep::allow_null_device_for_workspace_write;
+    use super::spawn_prep::apply_legacy_session_acl_rules;
+    use super::spawn_prep::legacy_session_capability_roots;
+    use super::spawn_prep::prepare_legacy_session_security;
+    use super::spawn_prep::prepare_legacy_spawn_context;
+    use super::spawn_prep::root_capability_sids;
+    use anyhow::Result;
+    use codex_protocol::models::PermissionProfile;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use std::collections::HashMap;
+    use std::io;
+    use std::path::Path;
+    use std::ptr;
+    use std::sync::Arc;
+    use std::time::Duration;
+    use std::time::Instant;
+    use windows_sys::Win32::Foundation::CloseHandle;
+    use windows_sys::Win32::Foundation::GetLastError;
+    use windows_sys::Win32::Foundation::HANDLE;
+    use windows_sys::Win32::Foundation::HANDLE_FLAG_INHERIT;
+    use windows_sys::Win32::Foundation::SetHandleInformation;
+    use windows_sys::Win32::System::Pipes::CreatePipe;
+    use windows_sys::Win32::System::Threading::GetExitCodeProcess;
+    use windows_sys::Win32::System::Threading::INFINITE;
+    use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+    type PipeHandles = ((HANDLE, HANDLE), (HANDLE, HANDLE), (HANDLE, HANDLE));
+
+    enum WaitOutcome {
+        Exited,
+        TimedOut,
+        Cancelled,
+    }
+
+    fn wait_for_process(
+        process: HANDLE,
+        timeout_ms: Option<u64>,
+        cancellation: Option<&WindowsSandboxCancellationToken>,
+    ) -> WaitOutcome {
+        let Some(cancellation) = cancellation else {
+            let timeout = timeout_ms.map(|ms| ms as u32).unwrap_or(INFINITE);
+            let res = unsafe { WaitForSingleObject(process, timeout) };
+            return if res == 0x0000_0102 {
+                WaitOutcome::TimedOut
+            } else {
+                WaitOutcome::Exited
+            };
+        };
+
+        let deadline = timeout_ms.map(|ms| Instant::now() + Duration::from_millis(ms));
+        loop {
+            if cancellation.is_cancelled() {
+                return WaitOutcome::Cancelled;
+            }
+            let wait_ms = match deadline {
+                Some(deadline) => {
+                    let remaining = deadline.saturating_duration_since(Instant::now());
+                    if remaining.is_zero() {
+                        return WaitOutcome::TimedOut;
+                    }
+                    remaining.min(Duration::from_millis(50)).as_millis() as u32
+                }
+                None => 50,
+            };
+            let res = unsafe { WaitForSingleObject(process, wait_ms) };
+            if res == 0x0000_0102 {
+                continue;
+            }
+            return WaitOutcome::Exited;
+        }
+    }
+
+    unsafe fn setup_stdio_pipes() -> io::Result<PipeHandles> {
+        let mut in_r: HANDLE = 0;
+        let mut in_w: HANDLE = 0;
+        let mut out_r: HANDLE = 0;
+        let mut out_w: HANDLE = 0;
+        let mut err_r: HANDLE = 0;
+        let mut err_w: HANDLE = 0;
+        if CreatePipe(&mut in_r, &mut in_w, ptr::null_mut(), 0) == 0 {
+            return Err(io::Error::from_raw_os_error(GetLastError() as i32));
+        }
+        if CreatePipe(&mut out_r, &mut out_w, ptr::null_mut(), 0) == 0 {
+            return Err(io::Error::from_raw_os_error(GetLastError() as i32));
+        }
+        if CreatePipe(&mut err_r, &mut err_w, ptr::null_mut(), 0) == 0 {
+            return Err(io::Error::from_raw_os_error(GetLastError() as i32));
+        }
+        if SetHandleInformation(in_r, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) == 0 {
+            return Err(io::Error::from_raw_os_error(GetLastError() as i32));
+        }
+        if SetHandleInformation(out_w, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) == 0 {
+            return Err(io::Error::from_raw_os_error(GetLastError() as i32));
+        }
+        if SetHandleInformation(err_w, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) == 0 {
+            return Err(io::Error::from_raw_os_error(GetLastError() as i32));
+        }
+        Ok(((in_r, in_w), (out_r, out_w), (err_r, err_w)))
+    }
+
+    pub struct CaptureResult {
+        pub exit_code: i32,
+        pub stdout: Vec<u8>,
+        pub stderr: Vec<u8>,
+        pub timed_out: bool,
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn run_windows_sandbox_capture(
+        permission_profile: &PermissionProfile,
+        workspace_roots: &[AbsolutePathBuf],
+        codex_home: &Path,
+        command: Vec<String>,
+        cwd: &Path,
+        env_map: HashMap<String, String>,
+        timeout_ms: Option<u64>,
+        cancellation: Option<WindowsSandboxCancellationToken>,
+        use_private_desktop: bool,
+    ) -> Result<CaptureResult> {
+        run_windows_sandbox_capture_with_filesystem_overrides(
+            permission_profile,
+            workspace_roots,
+            codex_home,
+            command,
+            cwd,
+            env_map,
+            timeout_ms,
+            cancellation,
+            &[],
+            &[],
+            use_private_desktop,
+        )
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn run_windows_sandbox_capture_with_filesystem_overrides(
+        permission_profile: &PermissionProfile,
+        workspace_roots: &[AbsolutePathBuf],
+        codex_home: &Path,
+        command: Vec<String>,
+        cwd: &Path,
+        mut env_map: HashMap<String, String>,
+        timeout_ms: Option<u64>,
+        cancellation: Option<WindowsSandboxCancellationToken>,
+        additional_deny_read_paths: &[AbsolutePathBuf],
+        additional_deny_write_paths: &[AbsolutePathBuf],
+        use_private_desktop: bool,
+    ) -> Result<CaptureResult> {
+        let additional_deny_read_paths = additional_deny_read_paths
+            .iter()
+            .map(AbsolutePathBuf::to_path_buf)
+            .collect::<Vec<_>>();
+        let additional_deny_write_paths = additional_deny_write_paths
+            .iter()
+            .map(AbsolutePathBuf::to_path_buf)
+            .collect::<Vec<_>>();
+        let common = prepare_legacy_spawn_context(
+            permission_profile,
+            workspace_roots,
+            codex_home,
+            cwd,
+            &mut env_map,
+            &command,
+            SpawnPrepOptions {
+                inherit_path: false,
+                add_git_safe_directory: false,
+            },
+        )?;
+        let permissions = common.permissions;
+        let current_dir = common.current_dir;
+        let logs_base_dir = common.logs_base_dir.as_deref();
+        let uses_write_capabilities = common.uses_write_capabilities;
+        if !permissions.has_full_disk_read_access() {
+            anyhow::bail!(
+                "Restricted read-only access requires the elevated Windows sandbox backend"
+            );
+        }
+        // WRITE_RESTRICTED tokens consult restricting SIDs only for writes, so this
+        // backend cannot make capability-SID deny-read ACLs authoritative.
+        if !additional_deny_read_paths.is_empty() {
+            anyhow::bail!("deny-read overrides require the elevated Windows sandbox backend");
+        }
+        let capability_roots =
+            legacy_session_capability_roots(&permissions, &current_dir, &env_map, codex_home);
+        let security = prepare_legacy_session_security(
+            uses_write_capabilities,
+            codex_home,
+            cwd,
+            capability_roots,
+        )?;
+        allow_null_device_for_workspace_write(uses_write_capabilities);
+        apply_legacy_session_acl_rules(
+            &permissions,
+            codex_home,
+            &current_dir,
+            &env_map,
+            &additional_deny_read_paths,
+            &additional_deny_write_paths,
+            LegacyAclSids {
+                readonly_sid: security.readonly_sid.as_ref(),
+                readonly_sid_str: security.readonly_sid_str.as_deref(),
+                write_root_sids: &security.write_root_sids,
+            },
+        )?;
+        let (stdin_pair, stdout_pair, stderr_pair) = unsafe { setup_stdio_pipes()? };
+        let ((in_r, in_w), (out_r, out_w), (err_r, err_w)) = (stdin_pair, stdout_pair, stderr_pair);
+        let spawn_res = crate::LaunchDesktop::prepare_legacy(
+            use_private_desktop,
+            &permissions,
+            &current_dir,
+            &env_map,
+            &security,
+            &additional_deny_write_paths,
+            logs_base_dir,
+        )
+        .and_then(|desktop| unsafe {
+            create_process_as_user(
+                security.h_token,
+                &command,
+                cwd,
+                &env_map,
+                logs_base_dir,
+                Some((in_r, out_w, err_w)),
+                ConsoleMode::Inherit,
+                desktop,
+            )
+        });
+        let created = match spawn_res {
+            Ok(v) => v,
+            Err(err) => {
+                unsafe {
+                    CloseHandle(in_r);
+                    CloseHandle(in_w);
+                    CloseHandle(out_r);
+                    CloseHandle(out_w);
+                    CloseHandle(err_r);
+                    CloseHandle(err_w);
+                    CloseHandle(security.h_token);
+                }
+                return Err(err);
+            }
+        };
+        let pi = created.process_info;
+        let job = Arc::clone(&created.job);
+        let _desktop = created;
+
+        unsafe {
+            CloseHandle(in_r);
+            // Close the parent's stdin write end so the child sees EOF immediately.
+            CloseHandle(in_w);
+            CloseHandle(out_w);
+            CloseHandle(err_w);
+        }
+
+        let (tx_out, rx_out) = std::sync::mpsc::channel::<Vec<u8>>();
+        let (tx_err, rx_err) = std::sync::mpsc::channel::<Vec<u8>>();
+        let t_out = std::thread::spawn(move || {
+            let mut buf = Vec::new();
+            let mut tmp = [0u8; 8192];
+            loop {
+                let mut read_bytes: u32 = 0;
+                let ok = unsafe {
+                    windows_sys::Win32::Storage::FileSystem::ReadFile(
+                        out_r,
+                        tmp.as_mut_ptr(),
+                        tmp.len() as u32,
+                        &mut read_bytes,
+                        std::ptr::null_mut(),
+                    )
+                };
+                if ok == 0 || read_bytes == 0 {
+                    break;
+                }
+                buf.extend_from_slice(&tmp[..read_bytes as usize]);
+            }
+            let _ = tx_out.send(buf);
+        });
+        let t_err = std::thread::spawn(move || {
+            let mut buf = Vec::new();
+            let mut tmp = [0u8; 8192];
+            loop {
+                let mut read_bytes: u32 = 0;
+                let ok = unsafe {
+                    windows_sys::Win32::Storage::FileSystem::ReadFile(
+                        err_r,
+                        tmp.as_mut_ptr(),
+                        tmp.len() as u32,
+                        &mut read_bytes,
+                        std::ptr::null_mut(),
+                    )
+                };
+                if ok == 0 || read_bytes == 0 {
+                    break;
+                }
+                buf.extend_from_slice(&tmp[..read_bytes as usize]);
+            }
+            let _ = tx_err.send(buf);
+        });
+
+        let wait_outcome = wait_for_process(pi.hProcess, timeout_ms, cancellation.as_ref());
+        let timed_out = matches!(wait_outcome, WaitOutcome::TimedOut);
+        let cancelled = matches!(wait_outcome, WaitOutcome::Cancelled);
+        let mut exit_code_u32: u32 = 1;
+        if !timed_out && !cancelled {
+            unsafe {
+                GetExitCodeProcess(pi.hProcess, &mut exit_code_u32);
+            }
+        }
+        if timed_out || cancelled {
+            if let Err(job_err) = job.terminate() {
+                log_note(
+                    &format!("capture failed to terminate process tree: {job_err}"),
+                    logs_base_dir,
+                );
+                let root_result = unsafe {
+                    windows_sys::Win32::System::Threading::TerminateProcess(pi.hProcess, 1)
+                };
+                if root_result == 0 {
+                    log_note(
+                        &format!("capture failed to terminate root process: {}", unsafe {
+                            GetLastError()
+                        }),
+                        logs_base_dir,
+                    );
+                }
+            }
+        } else if let Err(err) = job.preserve_descendants() {
+            log_note(
+                &format!("capture failed to preserve descendants after root exit: {err}"),
+                logs_base_dir,
+            );
+        }
+
+        unsafe {
+            if pi.hThread != 0 {
+                CloseHandle(pi.hThread);
+            }
+            if pi.hProcess != 0 {
+                CloseHandle(pi.hProcess);
+            }
+            CloseHandle(security.h_token);
+        }
+        let _ = t_out.join();
+        let _ = t_err.join();
+        let stdout = rx_out.recv().unwrap_or_default();
+        let stderr = rx_err.recv().unwrap_or_default();
+        let exit_code = if timed_out {
+            128 + 64
+        } else {
+            exit_code_u32 as i32
+        };
+
+        if exit_code == 0 {
+            log_success(&command, logs_base_dir);
+        } else {
+            log_failure(&command, &format!("exit code {exit_code}"), logs_base_dir);
+        }
+
+        Ok(CaptureResult {
+            exit_code,
+            stdout,
+            stderr,
+            timed_out,
+        })
+    }
+
+    pub fn run_windows_sandbox_legacy_preflight(
+        permission_profile: &PermissionProfile,
+        workspace_roots: &[AbsolutePathBuf],
+        codex_home: &Path,
+        cwd: &Path,
+        env_map: &HashMap<String, String>,
+    ) -> Result<()> {
+        let Ok(permissions) = super::resolved_permissions::ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        ) else {
+            return Ok(());
+        };
+        if !permissions.uses_write_capabilities_for_cwd(cwd, env_map) {
+            return Ok(());
+        }
+
+        ensure_codex_home_exists(codex_home)?;
+        let current_dir = cwd.to_path_buf();
+        let capability_roots =
+            legacy_session_capability_roots(&permissions, &current_dir, env_map, codex_home);
+        let write_root_sids = root_capability_sids(codex_home, cwd, capability_roots)?;
+        apply_legacy_session_acl_rules(
+            &permissions,
+            codex_home,
+            &current_dir,
+            env_map,
+            &[],
+            &[],
+            LegacyAclSids {
+                readonly_sid: None,
+                readonly_sid_str: None,
+                write_root_sids: &write_root_sids,
+            },
+        )?;
+
+        Ok(())
+    }
+
+    #[cfg(test)]
+    mod tests {
+        use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+        use codex_protocol::models::PermissionProfile;
+        use codex_protocol::permissions::NetworkSandboxPolicy;
+        use std::collections::HashMap;
+        use std::path::Path;
+
+        fn workspace_profile(network_policy: NetworkSandboxPolicy) -> PermissionProfile {
+            PermissionProfile::workspace_write_with(
+                &[],
+                network_policy,
+                /*exclude_tmpdir_env_var*/ false,
+                /*exclude_slash_tmp*/ false,
+            )
+        }
+
+        fn should_apply_network_block(permission_profile: &PermissionProfile) -> bool {
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                permission_profile,
+                &[],
+            )
+            .expect("managed permissions")
+            .should_apply_network_block()
+        }
+
+        #[test]
+        fn applies_network_block_when_access_is_disabled() {
+            assert!(should_apply_network_block(&workspace_profile(
+                NetworkSandboxPolicy::Restricted
+            )));
+        }
+
+        #[test]
+        fn skips_network_block_when_access_is_allowed() {
+            assert!(!should_apply_network_block(&workspace_profile(
+                NetworkSandboxPolicy::Enabled
+            )));
+        }
+
+        #[test]
+        fn applies_network_block_for_read_only() {
+            assert!(should_apply_network_block(&PermissionProfile::read_only()));
+        }
+
+        #[test]
+        fn legacy_preflight_skips_profiles_without_managed_filesystem_permissions() {
+            for permission_profile in [
+                PermissionProfile::Disabled,
+                PermissionProfile::External {
+                    network: NetworkSandboxPolicy::Restricted,
+                },
+            ] {
+                super::run_windows_sandbox_legacy_preflight(
+                    &permission_profile,
+                    &[],
+                    Path::new("."),
+                    Path::new("."),
+                    &HashMap::new(),
+                )
+                .expect("unsupported profiles do not need ACL preflight");
+            }
+        }
+    }
+}
+
+#[cfg(not(target_os = "windows"))]
+mod stub {
+    use super::WindowsSandboxCancellationToken;
+    use anyhow::Result;
+    use anyhow::bail;
+    use codex_protocol::models::PermissionProfile;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use std::collections::HashMap;
+    use std::path::Path;
+
+    #[derive(Debug, Default)]
+    pub struct CaptureResult {
+        pub exit_code: i32,
+        pub stdout: Vec<u8>,
+        pub stderr: Vec<u8>,
+        pub timed_out: bool,
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn run_windows_sandbox_capture(
+        _permission_profile: &PermissionProfile,
+        _workspace_roots: &[AbsolutePathBuf],
+        _codex_home: &Path,
+        _command: Vec<String>,
+        _cwd: &Path,
+        _env_map: HashMap<String, String>,
+        _timeout_ms: Option<u64>,
+        _cancellation: Option<WindowsSandboxCancellationToken>,
+        _use_private_desktop: bool,
+    ) -> Result<CaptureResult> {
+        bail!("Windows sandbox is only available on Windows")
+    }
+
+    pub fn run_windows_sandbox_legacy_preflight(
+        _permission_profile: &PermissionProfile,
+        _workspace_roots: &[AbsolutePathBuf],
+        _codex_home: &Path,
+        _cwd: &Path,
+        _env_map: &HashMap<String, String>,
+    ) -> Result<()> {
+        bail!("Windows sandbox is only available on Windows")
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/logging.rs b/codex-rs/windows-sandbox-rs/src/logging.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8bbd721b8aa9834c407a6c5fefba19f82da31caa
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/logging.rs
@@ -0,0 +1,254 @@
+use anyhow::Context;
+use anyhow::Result;
+use std::fs::File;
+use std::io::Write;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::Mutex;
+use std::sync::OnceLock;
+
+use codex_utils_string::take_bytes_at_char_boundary;
+use tracing_appender::rolling::RollingFileAppender;
+use tracing_appender::rolling::Rotation;
+
+const LOG_COMMAND_PREVIEW_LIMIT: usize = 200;
+pub const LOG_FILE_PREFIX: &str = "sandbox";
+pub const LOG_FILE_SUFFIX: &str = "log";
+pub const MAX_LOG_FILES: usize = 90;
+
+// Service provisioning never appends to a caller-controlled existing log entry.
+// An initialized but empty slot also prevents falling back after an open failure.
+static SETUP_LOG: OnceLock<Mutex<Option<(File, OwnedHandle)>>> = OnceLock::new();
+
+fn exe_label() -> &'static str {
+    static LABEL: OnceLock<String> = OnceLock::new();
+    LABEL.get_or_init(|| {
+        std::env::current_exe()
+            .ok()
+            .and_then(|p| p.file_name().map(|n| n.to_string_lossy().to_string()))
+            .unwrap_or_else(|| "proc".to_string())
+    })
+}
+
+fn preview(command: &[String]) -> String {
+    let joined = command.join(" ");
+    if joined.len() <= LOG_COMMAND_PREVIEW_LIMIT {
+        joined
+    } else {
+        take_bytes_at_char_boundary(&joined, LOG_COMMAND_PREVIEW_LIMIT).to_string()
+    }
+}
+
+pub fn log_file_path_for_utc_date(base_dir: &Path, date: chrono::NaiveDate) -> PathBuf {
+    base_dir.join(format!(
+        "{LOG_FILE_PREFIX}.{}.{}",
+        date.format("%Y-%m-%d"),
+        LOG_FILE_SUFFIX
+    ))
+}
+
+pub fn current_log_file_path(base_dir: &Path) -> PathBuf {
+    log_file_path_for_utc_date(base_dir, chrono::Utc::now().date_naive())
+}
+
+pub fn current_log_file_path_for_codex_home(codex_home: &Path) -> PathBuf {
+    current_log_file_path(&crate::sandbox_dir(codex_home))
+}
+
+pub fn log_writer(base_dir: &Path) -> Option<RollingFileAppender> {
+    if !base_dir.is_dir() {
+        return None;
+    }
+
+    RollingFileAppender::builder()
+        .rotation(Rotation::DAILY)
+        .filename_prefix(LOG_FILE_PREFIX)
+        .filename_suffix(LOG_FILE_SUFFIX)
+        .max_log_files(MAX_LOG_FILES)
+        .build(base_dir)
+        .ok()
+}
+
+/// Opens one fresh log for service provisioning and retains its parent directory.
+/// Subsequent setup diagnostics share this handle instead of reopening a pathname.
+pub fn setup_log_writer(base_dir: &Path) -> Result<File> {
+    let mut log = SETUP_LOG
+        .get_or_init(|| Mutex::new(None))
+        .lock()
+        .map_err(|_| anyhow::anyhow!("setup log lock poisoned"))?;
+    match log.as_ref() {
+        Some((file, _parent)) => file.try_clone().context("clone setup log"),
+        None => {
+            let (file, parent) = crate::file_write::create_temporary_file(base_dir, ".log")?;
+            let writer = file.try_clone().context("clone setup log")?;
+            *log = Some((file, parent));
+            Ok(writer)
+        }
+    }
+}
+
+/// Release setup's retained handles under the setup lock, after its writers finish.
+/// Keep the slot initialized so later diagnostics cannot reopen a caller-controlled path.
+pub(crate) fn release_setup_log() -> Result<()> {
+    if let Some(log) = SETUP_LOG.get() {
+        let mut log = log
+            .lock()
+            .map_err(|_| anyhow::anyhow!("setup log lock poisoned"))?;
+        *log = None;
+    }
+    Ok(())
+}
+
+fn append_line(line: &str, base_dir: Option<&Path>) {
+    if let Some(log) = SETUP_LOG.get() {
+        if let Ok(mut log) = log.lock()
+            && let Some((file, _parent)) = log.as_mut()
+        {
+            let _ = writeln!(file, "{line}");
+        }
+        return;
+    }
+    if let Some(dir) = base_dir
+        && let Some(mut f) = log_writer(dir)
+    {
+        let _ = writeln!(f, "{line}");
+    }
+}
+
+pub fn log_start(command: &[String], base_dir: Option<&Path>) {
+    let p = preview(command);
+    log_note(&format!("START: {p}"), base_dir);
+}
+
+pub fn log_success(command: &[String], base_dir: Option<&Path>) {
+    let p = preview(command);
+    log_note(&format!("SUCCESS: {p}"), base_dir);
+}
+
+pub fn log_failure(command: &[String], detail: &str, base_dir: Option<&Path>) {
+    let p = preview(command);
+    log_note(&format!("FAILURE: {p} ({detail})"), base_dir);
+}
+
+// Debug logging helper. Emits only when SBX_DEBUG=1 to avoid noisy logs.
+pub fn debug_log(msg: &str, base_dir: Option<&Path>) {
+    if std::env::var("SBX_DEBUG").ok().as_deref() == Some("1") {
+        append_line(&format!("DEBUG: {msg}"), base_dir);
+        eprintln!("{msg}");
+    }
+}
+
+// Unconditional note logging to the daily sandbox log.
+pub fn log_note(msg: &str, base_dir: Option<&Path>) {
+    let ts = chrono::Local::now().format("%Y-%m-%d %H:%M:%S%.3f");
+    append_line(&format!("[{ts} {}] {}", exe_label(), msg), base_dir);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn setup_log_releases_handles_without_path_fallback() {
+        const CHILD_ENV: &str = "CODEX_TEST_SETUP_LOG_RELEASE_CHILD";
+        if std::env::var(CHILD_ENV).ok().as_deref() != Some("1") {
+            // SETUP_LOG is process-global; isolate this test from ordinary daily logging.
+            let output = std::process::Command::new(std::env::current_exe().expect("test binary"))
+                .args([
+                    "--exact",
+                    "logging::tests::setup_log_releases_handles_without_path_fallback",
+                    "--nocapture",
+                ])
+                .env(CHILD_ENV, "1")
+                .output()
+                .expect("run isolated setup-log test");
+            assert!(output.status.success(), "isolated test failed: {output:?}");
+            assert!(
+                String::from_utf8_lossy(&output.stdout).contains("setup-log release verified"),
+                "isolated test did not run: {output:?}"
+            );
+            return;
+        }
+
+        let tempdir = tempfile::tempdir().expect("tempdir");
+        let directory = tempdir.path().join(".sandbox");
+        std::fs::create_dir(&directory).expect("create sandbox directory");
+        drop(setup_log_writer(&directory).expect("open retained setup log"));
+        let error =
+            std::fs::remove_dir_all(&directory).expect_err("setup handles prevent deletion");
+        assert_eq!(
+            error.raw_os_error(),
+            Some(windows_sys::Win32::Foundation::ERROR_SHARING_VIOLATION as i32)
+        );
+
+        release_setup_log().expect("release setup log");
+        std::fs::remove_dir_all(&directory).expect("delete sandbox after releasing handles");
+        std::fs::create_dir(&directory).expect("recreate caller-controlled directory");
+        release_setup_log().expect("repeated release is harmless");
+        log_note("must not reopen the directory", Some(&directory));
+        assert!(
+            std::fs::read_dir(&directory)
+                .expect("read directory")
+                .next()
+                .is_none()
+        );
+        println!("setup-log release verified");
+    }
+
+    #[test]
+    fn preview_does_not_panic_on_utf8_boundary() {
+        // Place a 4-byte emoji such that naive (byte-based) truncation would split it.
+        let prefix = "x".repeat(LOG_COMMAND_PREVIEW_LIMIT - 1);
+        let command = vec![format!("{prefix}😀")];
+        let result = std::panic::catch_unwind(|| preview(&command));
+        assert!(result.is_ok());
+        let previewed = result.unwrap();
+        assert!(previewed.len() <= LOG_COMMAND_PREVIEW_LIMIT);
+    }
+
+    #[test]
+    fn log_note_writes_to_daily_rolling_log() {
+        let tempdir = tempfile::tempdir().expect("tempdir");
+
+        log_note("hello daily log", Some(tempdir.path()));
+
+        let entries = std::fs::read_dir(tempdir.path())
+            .expect("read log dir")
+            .collect::<Result<Vec<_>, _>>()
+            .expect("read entries");
+        assert_eq!(entries.len(), 1);
+
+        let log_path = entries[0].path();
+        let filename = log_path
+            .file_name()
+            .and_then(|name| name.to_str())
+            .expect("utf-8 filename");
+        assert!(filename.starts_with("sandbox."));
+        assert!(filename.ends_with(".log"));
+
+        let log = std::fs::read_to_string(log_path).expect("read log");
+        assert!(log.contains("hello daily log"));
+    }
+
+    #[test]
+    fn log_file_path_for_utc_date_matches_rolling_appender_name() {
+        let date = chrono::NaiveDate::from_ymd_opt(2026, 5, 21).expect("valid date");
+
+        assert_eq!(
+            log_file_path_for_utc_date(Path::new("logs"), date),
+            PathBuf::from("logs").join("sandbox.2026-05-21.log")
+        );
+    }
+
+    #[test]
+    fn current_log_file_path_for_codex_home_uses_sandbox_dir() {
+        let codex_home = Path::new("codex-home");
+
+        assert_eq!(
+            current_log_file_path_for_codex_home(codex_home),
+            current_log_file_path(&codex_home.join(".sandbox"))
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/no_reparse_dir.rs b/codex-rs/windows-sandbox-rs/src/no_reparse_dir.rs
new file mode 100644
index 0000000000000000000000000000000000000000..da8cb2de0e1fd7946450d2c4d518676c339fa584
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/no_reparse_dir.rs
@@ -0,0 +1,245 @@
+//! Opens local directories without traversing reparse points. Callers choose
+//! access, sharing, and creation behavior and retain handles for their operation.
+//! Handle-relative guard files keep pinned directories from becoming reparses.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use anyhow::ensure;
+use rand::RngCore;
+use std::ffi::OsStr;
+use std::ffi::c_void;
+use std::mem::size_of;
+use std::mem::size_of_val;
+use std::os::windows::ffi::OsStrExt;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Component;
+use std::path::Path;
+use std::path::Prefix;
+use std::ptr;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Foundation::NTSTATUS;
+use windows_sys::Win32::Foundation::RtlNtStatusToDosError;
+use windows_sys::Win32::Foundation::UNICODE_STRING;
+use windows_sys::Win32::Storage::FileSystem::DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_NORMAL;
+use windows_sys::Win32::Storage::FileSystem::FILE_READ_DATA;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::System::IO::IO_STATUS_BLOCK;
+use windows_sys::Win32::System::IO::IO_STATUS_BLOCK_0;
+use windows_sys::Win32::System::Kernel::OBJ_CASE_INSENSITIVE;
+use windows_sys::Win32::System::Kernel::OBJ_DONT_REPARSE;
+
+const FILE_OPEN: u32 = 1;
+const FILE_CREATE: u32 = 2;
+const FILE_OPEN_IF: u32 = 3;
+const FILE_DIRECTORY_FILE: u32 = 1;
+const FILE_NON_DIRECTORY_FILE: u32 = 0x40;
+const FILE_DELETE_ON_CLOSE: u32 = 0x1000;
+const STATUS_REPARSE_POINT_ENCOUNTERED: NTSTATUS = 0xC000_050B_u32 as i32;
+
+#[repr(C)]
+struct ObjectAttributes {
+    length: u32,
+    root_directory: HANDLE,
+    object_name: *const UNICODE_STRING,
+    attributes: u32,
+    security_descriptor: *const c_void,
+    security_quality_of_service: *const c_void,
+}
+
+#[link(name = "ntdll")]
+unsafe extern "system" {
+    fn NtCreateFile(
+        file_handle: *mut HANDLE,
+        desired_access: u32,
+        object_attributes: *const ObjectAttributes,
+        io_status_block: *mut IO_STATUS_BLOCK,
+        allocation_size: *const i64,
+        file_attributes: u32,
+        share_access: u32,
+        create_disposition: u32,
+        create_options: u32,
+        ea_buffer: *const c_void,
+        ea_length: u32,
+    ) -> NTSTATUS;
+}
+
+/// Whether a no-reparse open may create the final directory.
+#[derive(Clone, Copy, Debug)]
+pub enum DirectoryOpenDisposition {
+    OpenExisting,
+    OpenOrCreate,
+}
+
+/// Validates an absolute local-drive directory path without accessing the filesystem.
+///
+/// Relative components and alternate data streams are not directory targets.
+pub fn validate_local_directory_path(path: &Path) -> Result<()> {
+    ensure!(
+        path.is_absolute(),
+        "directory path must be absolute: {}",
+        path.display()
+    );
+    let mut components = path.components();
+    match components.next() {
+        Some(Component::Prefix(prefix))
+            if matches!(prefix.kind(), Prefix::Disk(_) | Prefix::VerbatimDisk(_)) => {}
+        _ => bail!(
+            "directory path must have a local disk prefix: {}",
+            path.display()
+        ),
+    }
+    for component in components {
+        match component {
+            Component::RootDir => {}
+            Component::Normal(name) if !name.to_string_lossy().contains(':') => {}
+            Component::Normal(_) => bail!("directory path cannot contain alternate data streams"),
+            Component::ParentDir | Component::CurDir | Component::Prefix(_) => {
+                bail!("directory path cannot contain relative or nested prefix components");
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Opens a directory without following a reparse point in any path component.
+/// Parent directories must exist even when creating the final directory.
+///
+/// Retain the handle through handle-based security mutations. To also prevent
+/// renaming or deleting the directory, omit `FILE_SHARE_DELETE` and request
+/// access that participates in sharing checks, such as `FILE_TRAVERSE`.
+pub fn open_directory_no_reparse(
+    path: &Path,
+    desired_access: u32,
+    share_access: u32,
+    disposition: DirectoryOpenDisposition,
+) -> Result<OwnedHandle> {
+    validate_local_directory_path(path)?;
+    let source_offset = if matches!(
+        path.components().next(),
+        Some(Component::Prefix(prefix)) if matches!(prefix.kind(), Prefix::VerbatimDisk(_))
+    ) {
+        4
+    } else {
+        0
+    };
+    // NtCreateFile expects an NT namespace path. Convert only the local-disk
+    // spellings accepted by provisioning, without canonicalizing and following
+    // the reparse points that OBJ_DONT_REPARSE must reject.
+    let source: Vec<u16> = path.as_os_str().encode_wide().collect();
+    let mut nt_path: Vec<u16> = OsStr::new("\\??\\").encode_wide().collect();
+    for unit in source.into_iter().skip(source_offset) {
+        nt_path.push(if unit == b'/' as u16 {
+            b'\\' as u16
+        } else {
+            unit
+        });
+    }
+    nt_path.push(0);
+    open_no_reparse(
+        /*root_directory*/ 0,
+        &mut nt_path,
+        desired_access,
+        share_access,
+        match disposition {
+            DirectoryOpenDisposition::OpenExisting => FILE_OPEN,
+            DirectoryOpenDisposition::OpenOrCreate => FILE_OPEN_IF,
+        },
+        FILE_DIRECTORY_FILE,
+    )
+    .with_context(|| format!("open directory {}", path.display()))
+}
+
+/// Keeps a directory nonempty, preventing in-place reparse conversion while the
+/// returned handle is held. The fresh file cannot be renamed or deleted by other
+/// opens and uses delete-on-close cleanup after the guard and its duplicates close.
+///
+/// Creation is relative to the pinned directory, never to its mutable pathname.
+/// The caller must still validate that pathname after installing the guard and
+/// retain its directory pins alongside the guard throughout privileged work.
+pub fn create_directory_guard(directory: BorrowedHandle<'_>) -> Result<OwnedHandle> {
+    let mut random = [0_u8; 8];
+    rand::rngs::OsRng
+        .try_fill_bytes(&mut random)
+        .context("generate sandbox directory guard name")?;
+    let guard_id = u64::from_le_bytes(random);
+    let name = format!(".codex-provisioning-{guard_id:016x}.guard");
+    let mut name: Vec<u16> = OsStr::new(&name).encode_wide().chain(Some(0)).collect();
+    open_no_reparse(
+        directory.as_raw_handle() as HANDLE,
+        &mut name,
+        FILE_READ_DATA | DELETE,
+        FILE_SHARE_READ | FILE_SHARE_WRITE,
+        FILE_CREATE,
+        FILE_NON_DIRECTORY_FILE | FILE_DELETE_ON_CLOSE,
+    )
+    .context("create sandbox directory guard")
+}
+
+pub(crate) fn open_no_reparse(
+    root_directory: HANDLE,
+    name: &mut [u16],
+    desired_access: u32,
+    share_access: u32,
+    disposition: u32,
+    create_options: u32,
+) -> Result<OwnedHandle> {
+    let name_length = u16::try_from((name.len() - 1) * size_of::<u16>())
+        .context("no-reparse path is too long")?;
+    let maximum_length = u16::try_from(size_of_val(name)).context("no-reparse path is too long")?;
+    let object_name = UNICODE_STRING {
+        Length: name_length,
+        MaximumLength: maximum_length,
+        Buffer: name.as_mut_ptr(),
+    };
+    let object_attributes = ObjectAttributes {
+        length: size_of::<ObjectAttributes>() as u32,
+        root_directory,
+        object_name: &object_name,
+        attributes: OBJ_CASE_INSENSITIVE as u32 | OBJ_DONT_REPARSE as u32,
+        security_descriptor: ptr::null(),
+        security_quality_of_service: ptr::null(),
+    };
+    let mut io_status_block = IO_STATUS_BLOCK {
+        Anonymous: IO_STATUS_BLOCK_0 { Status: 0 },
+        Information: 0,
+    };
+    let mut handle = 0;
+    let status = unsafe {
+        NtCreateFile(
+            &mut handle,
+            desired_access,
+            &object_attributes,
+            &mut io_status_block,
+            ptr::null(),
+            FILE_ATTRIBUTE_NORMAL,
+            share_access,
+            disposition,
+            create_options,
+            ptr::null(),
+            /*ea_length*/ 0,
+        )
+    };
+    if status < 0 {
+        if status == STATUS_REPARSE_POINT_ENCOUNTERED {
+            bail!("path contains a reparse point");
+        }
+        let error = unsafe { RtlNtStatusToDosError(status) };
+        return Err(std::io::Error::from_raw_os_error(error as i32)).context("NtCreateFile");
+    }
+    ensure!(
+        handle != 0 && handle != INVALID_HANDLE_VALUE,
+        "NtCreateFile returned an invalid handle"
+    );
+    Ok(unsafe { OwnedHandle::from_raw_handle(handle as *mut c_void) })
+}
+
+#[cfg(test)]
+#[path = "no_reparse_dir_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/no_reparse_dir_tests.rs b/codex-rs/windows-sandbox-rs/src/no_reparse_dir_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..829552e57758a15232ed3509c63edd9519df4fe4
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/no_reparse_dir_tests.rs
@@ -0,0 +1,120 @@
+use std::fs;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::process::Command;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::Storage::FileSystem::READ_CONTROL;
+use windows_sys::Win32::Storage::FileSystem::WRITE_DAC;
+
+use anyhow::Result;
+
+use super::DirectoryOpenDisposition;
+use super::open_directory_no_reparse;
+use super::validate_local_directory_path;
+
+fn open_for_acl(path: &Path, disposition: DirectoryOpenDisposition) -> Result<OwnedHandle> {
+    open_directory_no_reparse(
+        path,
+        READ_CONTROL | WRITE_DAC,
+        FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+        disposition,
+    )
+}
+
+fn create_directory_junction(target: &Path, alias: &Path) -> Result<()> {
+    let output = Command::new("cmd")
+        .args(["/C", "mklink", "/J"])
+        .arg(alias)
+        .arg(target)
+        .output()?;
+    if !output.status.success() {
+        anyhow::bail!(
+            "mklink /J failed: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout).trim(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+    Ok(())
+}
+
+#[test]
+fn creates_and_opens_plain_directory_leaf() -> Result<()> {
+    let temporary = tempfile::tempdir()?;
+    let directory = temporary.path().join(".sandbox-bin");
+
+    drop(open_for_acl(
+        &directory,
+        DirectoryOpenDisposition::OpenOrCreate,
+    )?);
+    let _handle = open_for_acl(&directory, DirectoryOpenDisposition::OpenExisting)?;
+
+    assert!(directory.is_dir());
+    Ok(())
+}
+
+#[test]
+fn rejects_final_directory_junction() -> Result<()> {
+    let temporary = tempfile::tempdir()?;
+    let target = temporary.path().join("target");
+    let alias = temporary.path().join(".sandbox-bin");
+    fs::create_dir(&target)?;
+    create_directory_junction(&target, &alias)?;
+
+    let _ = open_for_acl(&alias, DirectoryOpenDisposition::OpenOrCreate)
+        .expect_err("final directory junction must be rejected");
+    fs::remove_dir(&alias)?;
+    Ok(())
+}
+
+#[test]
+fn rejects_ancestor_directory_junction() -> Result<()> {
+    let temporary = tempfile::tempdir()?;
+    let target_home = temporary.path().join("target-home");
+    let alias_home = temporary.path().join("linked-home");
+    fs::create_dir(&target_home)?;
+    fs::create_dir(target_home.join(".sandbox-bin"))?;
+    create_directory_junction(&target_home, &alias_home)?;
+
+    let _ = open_for_acl(
+        &alias_home.join(".sandbox-bin"),
+        DirectoryOpenDisposition::OpenOrCreate,
+    )
+    .expect_err("ancestor directory junction must be rejected");
+    fs::remove_dir(&alias_home)?;
+    Ok(())
+}
+
+#[test]
+fn open_existing_does_not_create_missing_directory() -> Result<()> {
+    let temporary = tempfile::tempdir()?;
+    let directory = temporary.path().join("missing");
+    assert!(open_for_acl(&directory, DirectoryOpenDisposition::OpenExisting).is_err());
+    assert!(!directory.exists());
+    Ok(())
+}
+
+#[test]
+fn local_directory_path_accepts_drive_and_verbatim_drive_paths() {
+    assert!(validate_local_directory_path(Path::new(r"C:\Users\alice\.codex")).is_ok());
+    assert!(validate_local_directory_path(Path::new(r"\\?\D:\Codex Data\home")).is_ok());
+}
+
+#[test]
+fn local_directory_path_rejects_relative_network_parent_and_stream_paths() {
+    for path in [
+        r"relative\.codex",
+        r"C:relative\.codex",
+        r"\\server\share\.codex",
+        r"\\?\UNC\server\share\.codex",
+        r"\\.\C:\Users\alice",
+        r"C:\Users\alice\..\other",
+        r"C:\Users\alice\.codex:stream",
+    ] {
+        assert!(
+            validate_local_directory_path(Path::new(path)).is_err(),
+            "unexpectedly accepted {path}"
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/package_identity.rs b/codex-rs/windows-sandbox-rs/src/package_identity.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9ee96797564b9dc172b08dce9c974c795f26f9cb
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/package_identity.rs
@@ -0,0 +1,48 @@
+//! Queries held process package identities without trusting routing hints or environment state.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use std::io;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Storage::Packaging::Appx::GetPackageFamilyName;
+
+/// Reads a process's OS package family. Absence is not authorization.
+///
+/// # Safety
+/// The caller must keep the process handle valid throughout the query.
+pub unsafe fn process_package_family(process: HANDLE) -> Result<Option<String>> {
+    let mut length = 0;
+    let status = unsafe { GetPackageFamilyName(process, &mut length, std::ptr::null_mut()) };
+    if status == foundation::APPMODEL_ERROR_NO_PACKAGE {
+        return Ok(None);
+    }
+    if status != foundation::ERROR_INSUFFICIENT_BUFFER {
+        return Err(io::Error::from_raw_os_error(status as i32))
+            .context("query the process package family");
+    }
+    if length == 0 || length > 256 {
+        bail!("the process package family has an invalid length");
+    }
+
+    let mut buffer = vec![0_u16; length as usize];
+    let status = unsafe { GetPackageFamilyName(process, &mut length, buffer.as_mut_ptr()) };
+    if status != foundation::ERROR_SUCCESS {
+        return Err(io::Error::from_raw_os_error(status as i32))
+            .context("read the process package family");
+    }
+
+    let value = buffer
+        .get(..length as usize)
+        .context("the package-family API returned an invalid length")?;
+    let Some((&0, value)) = value.split_last() else {
+        bail!("the process package family is not null-terminated");
+    };
+    if value.is_empty() || value.contains(&0) {
+        bail!("the process package family is malformed");
+    }
+    Ok(Some(
+        String::from_utf16(value).context("the package family contains invalid UTF-16")?,
+    ))
+}
diff --git a/codex-rs/windows-sandbox-rs/src/path_normalization.rs b/codex-rs/windows-sandbox-rs/src/path_normalization.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1735b745a28dc92b2c78e6f61fd70fa878042352
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/path_normalization.rs
@@ -0,0 +1,31 @@
+use std::path::Path;
+use std::path::PathBuf;
+
+pub fn canonicalize_path(path: &Path) -> PathBuf {
+    dunce::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
+}
+
+pub fn canonical_path_key(path: &Path) -> String {
+    canonicalize_path(path)
+        .to_string_lossy()
+        .replace('\\', "/")
+        .to_ascii_lowercase()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::canonical_path_key;
+    use pretty_assertions::assert_eq;
+    use std::path::Path;
+
+    #[test]
+    fn canonical_path_key_normalizes_case_and_separators() {
+        let windows_style = Path::new(r"C:\Users\Dev\Repo");
+        let slash_style = Path::new("c:/users/dev/repo");
+
+        assert_eq!(
+            canonical_path_key(windows_style),
+            canonical_path_key(slash_style)
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/proc_thread_attr.rs b/codex-rs/windows-sandbox-rs/src/proc_thread_attr.rs
new file mode 100644
index 0000000000000000000000000000000000000000..12c9b3c864c81577af53dacb99655437567bbff2
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/proc_thread_attr.rs
@@ -0,0 +1,142 @@
+use std::ffi::c_void;
+use std::io;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::System::Threading::DeleteProcThreadAttributeList;
+use windows_sys::Win32::System::Threading::InitializeProcThreadAttributeList;
+use windows_sys::Win32::System::Threading::LPPROC_THREAD_ATTRIBUTE_LIST;
+use windows_sys::Win32::System::Threading::PROC_THREAD_ATTRIBUTE_DESKTOP_APP_POLICY;
+use windows_sys::Win32::System::Threading::UpdateProcThreadAttribute;
+use windows_sys::Win32::System::WindowsProgramming::PROCESS_CREATION_DESKTOP_APP_BREAKAWAY_DISABLE_PROCESS_TREE;
+use windows_sys::Win32::System::WindowsProgramming::PROCESS_CREATION_DESKTOP_APP_BREAKAWAY_OVERRIDE;
+
+const PROC_THREAD_ATTRIBUTE_HANDLE_LIST: usize = 0x0002_0002;
+const PROC_THREAD_ATTRIBUTE_JOB_LIST: usize = 0x0002_000D;
+const PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE: usize = 0x0002_0016;
+
+pub struct ProcThreadAttributeList {
+    buffer: Vec<u8>,
+    handle_list: Vec<HANDLE>,
+    job_list: Vec<HANDLE>,
+    desktop_app_policy: Option<Box<u32>>,
+}
+
+impl ProcThreadAttributeList {
+    pub fn new(attr_count: u32) -> io::Result<Self> {
+        let mut size: usize = 0;
+        unsafe {
+            InitializeProcThreadAttributeList(std::ptr::null_mut(), attr_count, 0, &mut size);
+        }
+        if size == 0 {
+            return Err(io::Error::from_raw_os_error(unsafe {
+                GetLastError() as i32
+            }));
+        }
+        let mut buffer = vec![0u8; size];
+        let list = buffer.as_mut_ptr() as LPPROC_THREAD_ATTRIBUTE_LIST;
+        let ok = unsafe { InitializeProcThreadAttributeList(list, attr_count, 0, &mut size) };
+        if ok == 0 {
+            return Err(io::Error::from_raw_os_error(unsafe {
+                GetLastError() as i32
+            }));
+        }
+        Ok(Self {
+            buffer,
+            handle_list: Vec::new(),
+            job_list: Vec::new(),
+            desktop_app_policy: None,
+        })
+    }
+
+    pub fn as_mut_ptr(&mut self) -> LPPROC_THREAD_ATTRIBUTE_LIST {
+        self.buffer.as_mut_ptr() as LPPROC_THREAD_ATTRIBUTE_LIST
+    }
+
+    pub fn set_pseudoconsole(&mut self, hpc: isize) -> io::Result<()> {
+        // SAFETY: `hpc` is the Windows-defined value and size for this attribute.
+        unsafe {
+            self.update(
+                PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE,
+                hpc as *mut c_void,
+                std::mem::size_of::<HANDLE>(),
+            )
+        }
+    }
+
+    pub fn set_handle_list(&mut self, handles: Vec<HANDLE>) -> io::Result<()> {
+        self.handle_list = handles;
+        let value = self.handle_list.as_mut_ptr().cast();
+        let size = std::mem::size_of_val(self.handle_list.as_slice());
+        // SAFETY: `value` points to `self.handle_list`, which remains alive
+        // while the attribute list can reference it, and `size` covers that slice.
+        unsafe { self.update(PROC_THREAD_ATTRIBUTE_HANDLE_LIST, value, size) }
+    }
+
+    pub fn set_job(&mut self, job: HANDLE) -> io::Result<()> {
+        // Sandboxed processes must enter the job atomically. If Windows cannot
+        // honor the job list (for example, because a parent job forbids
+        // nesting), fail the spawn rather than briefly run an uncontained
+        // sandbox process tree.
+        self.job_list = vec![job];
+        let value = self.job_list.as_mut_ptr().cast();
+        let size = std::mem::size_of_val(self.job_list.as_slice());
+        // SAFETY: `value` points to `self.job_list`, which remains alive while
+        // the attribute list can reference it, and `size` covers that slice.
+        unsafe { self.update(PROC_THREAD_ATTRIBUTE_JOB_LIST, value, size) }
+    }
+
+    pub fn preserve_desktop_app_context(&mut self) -> io::Result<()> {
+        // System shells otherwise leave the package environment and cannot launch
+        // children from its protected directory. Keep the initial child and descendants
+        // inside it, using the caller-provided restricted token and job containment.
+        // Compare compatibility outcomes via codex.windows_sandbox.runner_result.
+        // https://learn.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute
+        let policy = self.desktop_app_policy.insert(Box::new(
+            PROCESS_CREATION_DESKTOP_APP_BREAKAWAY_DISABLE_PROCESS_TREE
+                | PROCESS_CREATION_DESKTOP_APP_BREAKAWAY_OVERRIDE,
+        ));
+        let value = std::ptr::from_mut(policy.as_mut()).cast();
+        // SAFETY: the boxed DWORD remains at a stable address through process creation,
+        // even if the attribute list moves. It is released after DeleteProcThreadAttributeList.
+        unsafe {
+            self.update(
+                PROC_THREAD_ATTRIBUTE_DESKTOP_APP_POLICY as usize,
+                value,
+                std::mem::size_of::<u32>(),
+            )
+        }
+    }
+
+    unsafe fn update(
+        &mut self,
+        attribute: usize,
+        value: *mut c_void,
+        size: usize,
+    ) -> io::Result<()> {
+        let ok = unsafe {
+            UpdateProcThreadAttribute(
+                self.as_mut_ptr(),
+                0,
+                attribute,
+                value,
+                size,
+                std::ptr::null_mut(),
+                std::ptr::null_mut(),
+            )
+        };
+        if ok == 0 {
+            return Err(io::Error::from_raw_os_error(unsafe {
+                GetLastError() as i32
+            }));
+        }
+        Ok(())
+    }
+}
+
+impl Drop for ProcThreadAttributeList {
+    fn drop(&mut self) {
+        unsafe {
+            DeleteProcThreadAttributeList(self.as_mut_ptr());
+        }
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/process.rs b/codex-rs/windows-sandbox-rs/src/process.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a6d088ef41fe6228d325a0de52fa7b4f3eb19bba
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/process.rs
@@ -0,0 +1,359 @@
+use crate::desktop::LaunchDesktop;
+use crate::logging;
+use crate::proc_thread_attr::ProcThreadAttributeList;
+use crate::winutil::argv_to_command_line;
+use crate::winutil::format_last_error;
+use crate::winutil::to_wide;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use codex_utils_pty::JobObject;
+use std::collections::HashMap;
+use std::ffi::c_void;
+use std::os::windows::io::AsRawHandle;
+use std::path::Path;
+use std::ptr;
+use std::sync::Arc;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::HANDLE_FLAG_INHERIT;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Foundation::SetHandleInformation;
+use windows_sys::Win32::Storage::FileSystem::ReadFile;
+use windows_sys::Win32::System::Console::GetStdHandle;
+use windows_sys::Win32::System::Console::STD_ERROR_HANDLE;
+use windows_sys::Win32::System::Console::STD_INPUT_HANDLE;
+use windows_sys::Win32::System::Console::STD_OUTPUT_HANDLE;
+use windows_sys::Win32::System::Pipes::CreatePipe;
+use windows_sys::Win32::System::Threading::CREATE_NO_WINDOW;
+use windows_sys::Win32::System::Threading::CREATE_UNICODE_ENVIRONMENT;
+use windows_sys::Win32::System::Threading::CreateProcessAsUserW;
+use windows_sys::Win32::System::Threading::EXTENDED_STARTUPINFO_PRESENT;
+use windows_sys::Win32::System::Threading::PROCESS_INFORMATION;
+use windows_sys::Win32::System::Threading::STARTF_USESTDHANDLES;
+use windows_sys::Win32::System::Threading::STARTUPINFOEXW;
+use windows_sys::Win32::System::Threading::STARTUPINFOW;
+
+pub struct CreatedProcess {
+    pub process_info: PROCESS_INFORMATION,
+    pub startup_info: STARTUPINFOW,
+    pub(crate) job: Arc<JobObject>,
+    _desktop: LaunchDesktop,
+}
+
+/// Controls console creation for pipe-backed child processes.
+pub enum ConsoleMode {
+    Inherit,
+    NoWindow,
+}
+
+pub fn make_env_block(env: &HashMap<String, String>) -> Vec<u16> {
+    let mut items: Vec<(String, String)> =
+        env.iter().map(|(k, v)| (k.clone(), v.clone())).collect();
+    items.sort_by(|a, b| {
+        a.0.to_uppercase()
+            .cmp(&b.0.to_uppercase())
+            .then(a.0.cmp(&b.0))
+    });
+    let mut w: Vec<u16> = Vec::new();
+    for (k, v) in items {
+        let mut s = to_wide(format!("{k}={v}"));
+        s.pop();
+        w.extend_from_slice(&s);
+        w.push(0);
+    }
+    w.push(0);
+    w
+}
+
+unsafe fn ensure_inheritable_stdio(si: &mut STARTUPINFOW) -> Result<()> {
+    for kind in [STD_INPUT_HANDLE, STD_OUTPUT_HANDLE, STD_ERROR_HANDLE] {
+        let h = GetStdHandle(kind);
+        if h == 0 || h == INVALID_HANDLE_VALUE {
+            return Err(anyhow!("GetStdHandle failed: {}", GetLastError()));
+        }
+        if SetHandleInformation(h, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) == 0 {
+            return Err(anyhow!("SetHandleInformation failed: {}", GetLastError()));
+        }
+    }
+    si.dwFlags |= STARTF_USESTDHANDLES;
+    si.hStdInput = GetStdHandle(STD_INPUT_HANDLE);
+    si.hStdOutput = GetStdHandle(STD_OUTPUT_HANDLE);
+    si.hStdError = GetStdHandle(STD_ERROR_HANDLE);
+    Ok(())
+}
+
+/// # Safety
+/// Caller must provide a valid primary token handle (`h_token`) with appropriate access,
+/// and the `argv`, `cwd`, and `env_map` must remain valid for the duration of the call.
+// Low-level CreateProcessAsUserW wrapper mirrors the Windows API shape.
+#[allow(clippy::too_many_arguments)]
+pub unsafe fn create_process_as_user(
+    h_token: HANDLE,
+    argv: &[String],
+    cwd: &Path,
+    env_map: &HashMap<String, String>,
+    logs_base_dir: Option<&Path>,
+    stdio: Option<(HANDLE, HANDLE, HANDLE)>,
+    console_mode: ConsoleMode,
+    desktop: LaunchDesktop,
+) -> Result<CreatedProcess> {
+    let cmdline_str = argv_to_command_line(argv);
+    let mut cmdline: Vec<u16> = to_wide(&cmdline_str);
+    let env_block = make_env_block(env_map);
+    let job = Arc::new(JobObject::create().context("create process job")?);
+    let mut pi: PROCESS_INFORMATION = std::mem::zeroed();
+    let cwd_wide = to_wide(cwd);
+    let env_block_len = env_block.len();
+    let console_flags = match (&stdio, console_mode) {
+        (Some(_), ConsoleMode::NoWindow) => CREATE_NO_WINDOW,
+        (Some(_), ConsoleMode::Inherit)
+        | (None, ConsoleMode::Inherit)
+        | (None, ConsoleMode::NoWindow) => 0,
+    };
+    let preserve_app_context = crate::app_package::current_process_is_registered_core_runner()?;
+    let attr_count = if stdio.is_some() { 2 } else { 1 } + u32::from(preserve_app_context);
+    let mut attrs = ProcThreadAttributeList::new(attr_count)?;
+    attrs.set_job(job.as_raw_handle() as HANDLE)?;
+    if preserve_app_context {
+        attrs.preserve_desktop_app_context()?;
+    }
+
+    let mut si: STARTUPINFOEXW = std::mem::zeroed();
+    si.StartupInfo.cb = std::mem::size_of::<STARTUPINFOEXW>() as u32;
+    // Some processes (e.g., PowerShell) can fail with STATUS_DLL_INIT_FAILED
+    // if lpDesktop is not set when launching with a restricted token.
+    // Point explicitly at the interactive desktop or a private desktop.
+    si.StartupInfo.lpDesktop = desktop.startup_info_desktop();
+    match stdio {
+        Some((stdin_h, stdout_h, stderr_h)) => {
+            si.StartupInfo.dwFlags |= STARTF_USESTDHANDLES;
+            si.StartupInfo.hStdInput = stdin_h;
+            si.StartupInfo.hStdOutput = stdout_h;
+            si.StartupInfo.hStdError = stderr_h;
+            let mut inherited_handles = vec![stdin_h, stdout_h];
+            if !inherited_handles.contains(&stderr_h) {
+                inherited_handles.push(stderr_h);
+            }
+            for &handle in &inherited_handles {
+                if SetHandleInformation(handle, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) == 0 {
+                    return Err(anyhow!(
+                        "SetHandleInformation failed for stdio handle: {}",
+                        GetLastError()
+                    ));
+                }
+            }
+            attrs.set_handle_list(inherited_handles)?;
+        }
+        None => {
+            ensure_inheritable_stdio(&mut si.StartupInfo)?;
+        }
+    }
+    si.lpAttributeList = attrs.as_mut_ptr();
+
+    let creation_flags = CREATE_UNICODE_ENVIRONMENT | EXTENDED_STARTUPINFO_PRESENT | console_flags;
+    let ok = CreateProcessAsUserW(
+        h_token,
+        std::ptr::null(),
+        cmdline.as_mut_ptr(),
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        1,
+        creation_flags,
+        env_block.as_ptr() as *mut c_void,
+        cwd_wide.as_ptr(),
+        &si.StartupInfo,
+        &mut pi,
+    );
+    if ok == 0 {
+        let err = GetLastError() as i32;
+        let msg = format!(
+            "CreateProcessAsUserW failed: {} ({}) | cwd={} | cmd={} | env_u16_len={} | si_flags={} | creation_flags={}",
+            err,
+            format_last_error(err),
+            cwd.display(),
+            cmdline_str,
+            env_block_len,
+            si.StartupInfo.dwFlags,
+            creation_flags,
+        );
+        logging::debug_log(&msg, logs_base_dir);
+        return Err(std::io::Error::from_raw_os_error(err)).context(msg);
+    }
+
+    Ok(CreatedProcess {
+        process_info: pi,
+        startup_info: si.StartupInfo,
+        job,
+        _desktop: desktop,
+    })
+}
+
+/// Controls whether the child's stdin handle is kept open for writing.
+#[allow(dead_code)]
+pub enum StdinMode {
+    Closed,
+    Open,
+}
+
+/// Controls how stderr is wired for a pipe-spawned process.
+#[allow(dead_code)]
+pub enum StderrMode {
+    MergeStdout,
+    Separate,
+}
+
+/// Handles returned by `spawn_process_with_pipes`.
+#[allow(dead_code)]
+pub struct PipeSpawnHandles {
+    pub process: PROCESS_INFORMATION,
+    job: Arc<JobObject>,
+    pub stdin_write: Option<HANDLE>,
+    pub stdout_read: HANDLE,
+    pub stderr_read: Option<HANDLE>,
+    pub(crate) desktop: LaunchDesktop,
+}
+
+impl PipeSpawnHandles {
+    /// Returns the Job Object containing the spawned process.
+    pub fn job(&self) -> Arc<JobObject> {
+        Arc::clone(&self.job)
+    }
+}
+
+/// Spawns a process with anonymous pipes and returns the relevant handles.
+#[allow(clippy::too_many_arguments)]
+pub fn spawn_process_with_pipes(
+    h_token: HANDLE,
+    argv: &[String],
+    cwd: &Path,
+    env_map: &HashMap<String, String>,
+    stdin_mode: StdinMode,
+    stderr_mode: StderrMode,
+    console_mode: ConsoleMode,
+    desktop: LaunchDesktop,
+    logs_base_dir: Option<&Path>,
+) -> Result<PipeSpawnHandles> {
+    let mut in_r: HANDLE = 0;
+    let mut in_w: HANDLE = 0;
+    let mut out_r: HANDLE = 0;
+    let mut out_w: HANDLE = 0;
+    let mut err_r: HANDLE = 0;
+    let mut err_w: HANDLE = 0;
+    unsafe {
+        if CreatePipe(&mut in_r, &mut in_w, ptr::null_mut(), 0) == 0 {
+            return Err(anyhow!("CreatePipe stdin failed: {}", GetLastError()));
+        }
+        if CreatePipe(&mut out_r, &mut out_w, ptr::null_mut(), 0) == 0 {
+            CloseHandle(in_r);
+            CloseHandle(in_w);
+            return Err(anyhow!("CreatePipe stdout failed: {}", GetLastError()));
+        }
+        if matches!(stderr_mode, StderrMode::Separate)
+            && CreatePipe(&mut err_r, &mut err_w, ptr::null_mut(), 0) == 0
+        {
+            CloseHandle(in_r);
+            CloseHandle(in_w);
+            CloseHandle(out_r);
+            CloseHandle(out_w);
+            return Err(anyhow!("CreatePipe stderr failed: {}", GetLastError()));
+        }
+    }
+
+    let stderr_handle = match stderr_mode {
+        StderrMode::MergeStdout => out_w,
+        StderrMode::Separate => err_w,
+    };
+
+    let stdio = Some((in_r, out_w, stderr_handle));
+    let spawn_result = unsafe {
+        create_process_as_user(
+            h_token,
+            argv,
+            cwd,
+            env_map,
+            logs_base_dir,
+            stdio,
+            console_mode,
+            desktop,
+        )
+    };
+    let created = match spawn_result {
+        Ok(v) => v,
+        Err(err) => {
+            unsafe {
+                CloseHandle(in_r);
+                CloseHandle(in_w);
+                CloseHandle(out_r);
+                CloseHandle(out_w);
+                if matches!(stderr_mode, StderrMode::Separate) {
+                    CloseHandle(err_r);
+                    CloseHandle(err_w);
+                }
+            }
+            return Err(err);
+        }
+    };
+    let CreatedProcess {
+        process_info: pi,
+        job,
+        _desktop: desktop,
+        ..
+    } = created;
+
+    unsafe {
+        CloseHandle(in_r);
+        CloseHandle(out_w);
+        if matches!(stderr_mode, StderrMode::Separate) {
+            CloseHandle(err_w);
+        }
+        if matches!(stdin_mode, StdinMode::Closed) {
+            CloseHandle(in_w);
+        }
+    }
+
+    Ok(PipeSpawnHandles {
+        process: pi,
+        job,
+        stdin_write: match stdin_mode {
+            StdinMode::Open => Some(in_w),
+            StdinMode::Closed => None,
+        },
+        stdout_read: out_r,
+        stderr_read: match stderr_mode {
+            StderrMode::Separate => Some(err_r),
+            StderrMode::MergeStdout => None,
+        },
+        desktop,
+    })
+}
+
+/// Reads a HANDLE until EOF and invokes `on_chunk` for each read.
+pub fn read_handle_loop<F>(handle: HANDLE, mut on_chunk: F) -> std::thread::JoinHandle<()>
+where
+    F: FnMut(&[u8]) + Send + 'static,
+{
+    std::thread::spawn(move || {
+        let mut buf = [0u8; 8192];
+        loop {
+            let mut read_bytes: u32 = 0;
+            let ok = unsafe {
+                ReadFile(
+                    handle,
+                    buf.as_mut_ptr(),
+                    buf.len() as u32,
+                    &mut read_bytes,
+                    ptr::null_mut(),
+                )
+            };
+            if ok == 0 || read_bytes == 0 {
+                break;
+            }
+            on_chunk(&buf[..read_bytes as usize]);
+        }
+        unsafe {
+            CloseHandle(handle);
+        }
+    })
+}
diff --git a/codex-rs/windows-sandbox-rs/src/provisioning_client.rs b/codex-rs/windows-sandbox-rs/src/provisioning_client.rs
new file mode 100644
index 0000000000000000000000000000000000000000..de1823aef9c24f04ffe7055b9d424255b2b77587
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/provisioning_client.rs
@@ -0,0 +1,387 @@
+//! Authenticated client for the packaged Windows sandbox provisioning service.
+
+use crate::WindowsSandboxProvisioningSettings;
+use crate::WindowsSandboxProxyListeners;
+use std::collections::HashMap;
+use std::fs::File;
+use std::fs::OpenOptions;
+use std::io;
+use std::mem::size_of;
+use std::os::windows::fs::OpenOptionsExt;
+use std::os::windows::io::AsRawHandle;
+use std::path::Path;
+use std::ptr;
+use std::time::Duration;
+use std::time::Instant;
+
+use anyhow::Context;
+use anyhow::anyhow;
+use anyhow::bail;
+use codex_protocol::models::PermissionProfile;
+use windows_sys::Win32::Foundation::ERROR_BROKEN_PIPE;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::ERROR_NO_DATA;
+use windows_sys::Win32::Foundation::ERROR_PIPE_BUSY;
+use windows_sys::Win32::Foundation::ERROR_PIPE_NOT_CONNECTED;
+use windows_sys::Win32::Foundation::ERROR_SEM_TIMEOUT;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security::SC_HANDLE;
+use windows_sys::Win32::Storage::FileSystem::SECURITY_IMPERSONATION;
+use windows_sys::Win32::Storage::FileSystem::SECURITY_SQOS_PRESENT;
+use windows_sys::Win32::System::Pipes::GetNamedPipeServerProcessId;
+use windows_sys::Win32::System::Pipes::WaitNamedPipeW;
+use windows_sys::Win32::System::Services;
+
+const PROVISIONING_TIMEOUT: Duration = Duration::from_secs(120);
+
+mod group_change;
+mod refresh_retry;
+
+impl WindowsSandboxProvisioningSettings {
+    /// Derives the full firewall settings using the same environment handling as elevated setup.
+    pub fn from_environment(
+        permission_profile: &PermissionProfile,
+        env_map: &HashMap<String, String>,
+    ) -> Self {
+        let network_identity = if permission_profile.network_sandbox_policy().is_enabled() {
+            crate::setup::SandboxNetworkIdentity::Online
+        } else {
+            crate::setup::SandboxNetworkIdentity::Offline
+        };
+        let settings = crate::setup::offline_proxy_settings_from_env(env_map, network_identity);
+        Self {
+            proxy_ports: settings.proxy_ports,
+            allow_local_binding: settings.allow_local_binding,
+        }
+    }
+}
+
+impl WindowsSandboxProxyListeners {
+    /// Identifies known listener protocols without restricting the ports allowed by setup.
+    pub fn from_environment(
+        permission_profile: &PermissionProfile,
+        env_map: &HashMap<String, String>,
+    ) -> Self {
+        if permission_profile.network_sandbox_policy().is_enabled() {
+            return Self::default();
+        }
+        Self::from_proxy_environment(env_map)
+    }
+
+    pub(crate) fn from_proxy_environment(env_map: &HashMap<String, String>) -> Self {
+        let mut listeners = Self::default();
+        for value in crate::setup::PROXY_ENV_KEYS
+            .iter()
+            .filter_map(|key| env_map.get(*key))
+        {
+            let Some((scheme, _)) = value.trim().split_once("://") else {
+                continue;
+            };
+            let Some(port) = crate::setup::loopback_proxy_port_from_url(value) else {
+                continue;
+            };
+            match scheme.to_ascii_lowercase().as_str() {
+                "http" | "https" => listeners.http_ports.push(port),
+                "socks4" | "socks4a" | "socks5" | "socks5h" => {
+                    listeners.socks_ports.push(port);
+                }
+                _ => {}
+            }
+        }
+        listeners.http_ports.sort_unstable();
+        listeners.http_ports.dedup();
+        listeners.socks_ports.sort_unstable();
+        listeners.socks_ports.dedup();
+        listeners
+    }
+}
+
+/// Result of attempting setup through the packaged provisioning service.
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub enum WindowsSandboxProvisioningOutcome {
+    /// The service completed elevated provisioning.
+    Provisioned,
+    /// The service was absent, did not support this caller, or timed out.
+    Unavailable,
+}
+
+enum ProvisioningIntent {
+    Setup,
+    RefreshRegistration,
+}
+
+/// Refreshes only an already-provisioned gated runtime; no helper or setup fallback.
+#[doc(hidden)]
+pub fn refresh_registered_core_via_service(
+    codex_home: &Path,
+    settings: WindowsSandboxProvisioningSettings,
+    listeners: WindowsSandboxProxyListeners,
+) -> anyhow::Result<WindowsSandboxProvisioningOutcome> {
+    anyhow::ensure!(
+        crate::registered_core_requested(),
+        "registered Core is not enabled"
+    );
+    provision(
+        codex_home,
+        settings,
+        listeners,
+        ProvisioningIntent::RefreshRegistration,
+    )
+}
+
+/// Provisions the elevated Windows sandbox through the authenticated packaged service.
+pub fn provision_windows_sandbox_via_service(
+    codex_home: &Path,
+    settings: WindowsSandboxProvisioningSettings,
+    listeners: WindowsSandboxProxyListeners,
+) -> anyhow::Result<WindowsSandboxProvisioningOutcome> {
+    provision(codex_home, settings, listeners, ProvisioningIntent::Setup)
+}
+
+fn provision(
+    codex_home: &Path,
+    settings: WindowsSandboxProvisioningSettings,
+    listeners: WindowsSandboxProxyListeners,
+    intent: ProvisioningIntent,
+) -> anyhow::Result<WindowsSandboxProvisioningOutcome> {
+    let request = crate::FramedProvisioningMessage {
+        version: crate::PROVISIONING_PROTOCOL_VERSION,
+        message: crate::ProvisioningMessage::ProvisionSandboxRequest {
+            payload: crate::SandboxProvisioningRequest {
+                codex_home: codex_home
+                    .to_str()
+                    .context("sandbox provisioning home is not valid UTF-8")?
+                    .to_owned(),
+                registered_core: crate::registered_core_requested(),
+                refresh_only: matches!(intent, ProvisioningIntent::RefreshRegistration),
+                settings,
+                listeners,
+            },
+        },
+    };
+
+    match send_service_request(&request, PROVISIONING_TIMEOUT)? {
+        crate::SandboxProvisioningResponse::Ok => {
+            Ok(WindowsSandboxProvisioningOutcome::Provisioned)
+        }
+        crate::SandboxProvisioningResponse::Unavailable => service_unavailable(),
+        crate::SandboxProvisioningResponse::Error { message } => Err(anyhow!(message)),
+    }
+}
+
+fn service_unavailable() -> anyhow::Result<WindowsSandboxProvisioningOutcome> {
+    if crate::registered_core_requested() {
+        bail!("app runtime provisioning service is unavailable; refusing helper fallback");
+    }
+    Ok(WindowsSandboxProvisioningOutcome::Unavailable)
+}
+
+/// Records desktop uninstall ownership without creating or enabling a sandbox.
+pub fn register_desktop_installation(codex_home: &Path) -> anyhow::Result<()> {
+    let request = crate::FramedProvisioningMessage {
+        version: crate::PROVISIONING_PROTOCOL_VERSION,
+        message: crate::ProvisioningMessage::RegisterInstallationRequest {
+            codex_home: codex_home
+                .to_str()
+                .context("desktop home is not valid UTF-8")?
+                .to_owned(),
+        },
+    };
+    match send_service_request(&request, Duration::from_secs(5))? {
+        crate::SandboxProvisioningResponse::Ok => Ok(()),
+        crate::SandboxProvisioningResponse::Unavailable => {
+            bail!("desktop uninstall registration service is unavailable")
+        }
+        crate::SandboxProvisioningResponse::Error { message } => Err(anyhow!(message)),
+    }
+}
+
+fn send_service_request(
+    request: &crate::FramedProvisioningMessage,
+    timeout: Duration,
+) -> anyhow::Result<crate::SandboxProvisioningResponse> {
+    let deadline = Instant::now() + timeout;
+    let Some(mut pipe) = connect(deadline)? else {
+        return Ok(crate::SandboxProvisioningResponse::Unavailable);
+    };
+    if let crate::ProvisioningMessage::ProvisionSandboxRequest { payload } = &request.message
+        && payload.registered_core
+        && payload.refresh_only
+    {
+        return refresh_retry::send(pipe, request, deadline);
+    }
+    let response = match exchange_request(&mut pipe, request, deadline) {
+        Ok(response) => response,
+        Err(error)
+            if error.downcast_ref::<io::Error>().is_some_and(|error| {
+                matches!(
+                    error.kind(),
+                    io::ErrorKind::UnexpectedEof | io::ErrorKind::TimedOut
+                ) || matches!(
+                    error.raw_os_error(),
+                    Some(code)
+                        if code == ERROR_BROKEN_PIPE as i32
+                            || code == ERROR_NO_DATA as i32
+                            || code == ERROR_PIPE_NOT_CONNECTED as i32
+                )
+            }) =>
+        {
+            return Ok(crate::SandboxProvisioningResponse::Unavailable);
+        }
+        Err(error) => return Err(error),
+    };
+    if matches!(&response, crate::SandboxProvisioningResponse::Error { message }
+        if message == crate::SANDBOX_GROUP_CHANGED)
+    {
+        drop(pipe);
+        return group_change::retry(request, deadline);
+    }
+    Ok(response)
+}
+
+fn exchange_request(
+    pipe: &mut File,
+    request: &crate::FramedProvisioningMessage,
+    deadline: Instant,
+) -> anyhow::Result<crate::SandboxProvisioningResponse> {
+    verify_server(pipe.as_raw_handle() as HANDLE)
+        .context("authenticate provisioning pipe server")?;
+    crate::write_provisioning_frame(&mut *pipe, request)
+        .context("send sandbox provisioning request")?;
+    read_response(pipe, deadline)
+}
+
+fn read_response(
+    pipe: &mut File,
+    deadline: Instant,
+) -> anyhow::Result<crate::SandboxProvisioningResponse> {
+    crate::framed_io::wait_for_complete_frame(pipe, deadline)
+        .context("wait for sandbox provisioning response")?;
+    let response = crate::read_provisioning_frame(pipe)
+        .context("read sandbox provisioning response")?
+        .ok_or_else(|| {
+            io::Error::new(
+                io::ErrorKind::UnexpectedEof,
+                "sandbox provisioning service closed the pipe without a response",
+            )
+        })
+        .context("read sandbox provisioning response")?;
+    if response.version != crate::PROVISIONING_PROTOCOL_VERSION {
+        return Ok(crate::SandboxProvisioningResponse::Unavailable);
+    }
+    let crate::ProvisioningMessage::ProvisionSandboxResponse { payload } = response.message else {
+        bail!("unexpected sandbox provisioning response message");
+    };
+    Ok(payload)
+}
+
+fn connect(deadline: Instant) -> anyhow::Result<Option<File>> {
+    let pipe_name = crate::windows_sandbox_service_pipe_name()?;
+    let open_pipe = || {
+        OpenOptions::new()
+            .read(true)
+            .write(true)
+            .custom_flags(SECURITY_SQOS_PRESENT | SECURITY_IMPERSONATION)
+            .open(&pipe_name)
+    };
+
+    let pipe_name = crate::to_wide(&pipe_name);
+    loop {
+        match open_pipe() {
+            Ok(pipe) => return Ok(Some(pipe)),
+            Err(error) if error.raw_os_error() == Some(ERROR_FILE_NOT_FOUND as i32) => {
+                return Ok(None);
+            }
+            Err(error) if error.raw_os_error() == Some(ERROR_PIPE_BUSY as i32) => {
+                let remaining = deadline.saturating_duration_since(Instant::now());
+                if remaining.is_zero() {
+                    return Ok(None);
+                }
+                let wait_ms = u32::try_from(remaining.as_millis())
+                    .unwrap_or(u32::MAX)
+                    .max(1);
+                if unsafe { WaitNamedPipeW(pipe_name.as_ptr(), wait_ms) } == 0 {
+                    let error = io::Error::last_os_error();
+                    if matches!(
+                        error.raw_os_error(),
+                        Some(code)
+                            if code == ERROR_FILE_NOT_FOUND as i32
+                                || code == ERROR_SEM_TIMEOUT as i32
+                    ) {
+                        return Ok(None);
+                    }
+                    return Err(error).context("wait for sandbox provisioning pipe");
+                }
+            }
+            Err(error) => return Err(error).context("open sandbox provisioning pipe"),
+        }
+    }
+}
+
+fn pipe_server_process_id(pipe: HANDLE) -> anyhow::Result<u32> {
+    let mut pipe_process_id = 0;
+    if unsafe { GetNamedPipeServerProcessId(pipe, &mut pipe_process_id) } == 0 {
+        return Err(io::Error::last_os_error()).context("identify provisioning pipe server");
+    }
+    Ok(pipe_process_id)
+}
+
+fn verify_server(pipe: HANDLE) -> anyhow::Result<u32> {
+    let pipe_process_id = pipe_server_process_id(pipe)?;
+    let status = query_service_status()?;
+    if status.dwCurrentState != Services::SERVICE_RUNNING
+        || status.dwProcessId == 0
+        || status.dwProcessId != pipe_process_id
+    {
+        bail!("the provisioning pipe server does not match the running service");
+    }
+    Ok(pipe_process_id)
+}
+
+fn query_service_status() -> anyhow::Result<Services::SERVICE_STATUS_PROCESS> {
+    let manager =
+        unsafe { Services::OpenSCManagerW(ptr::null(), ptr::null(), Services::SC_MANAGER_CONNECT) };
+    if manager == 0 {
+        return Err(io::Error::last_os_error()).context("open service control manager");
+    }
+    let manager = ServiceHandle(manager);
+
+    let service_name = crate::to_wide(crate::windows_sandbox_service_name()?);
+    let service = unsafe {
+        Services::OpenServiceW(
+            manager.0,
+            service_name.as_ptr(),
+            Services::SERVICE_QUERY_STATUS,
+        )
+    };
+    if service == 0 {
+        return Err(io::Error::last_os_error()).context("open sandbox provisioning service");
+    }
+    let service = ServiceHandle(service);
+
+    let mut status: Services::SERVICE_STATUS_PROCESS = unsafe { std::mem::zeroed() };
+    let mut bytes_needed = 0;
+    if unsafe {
+        Services::QueryServiceStatusEx(
+            service.0,
+            Services::SC_STATUS_PROCESS_INFO,
+            ptr::from_mut(&mut status).cast(),
+            size_of::<Services::SERVICE_STATUS_PROCESS>() as u32,
+            &mut bytes_needed,
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error()).context("query sandbox provisioning service");
+    }
+    Ok(status)
+}
+
+struct ServiceHandle(SC_HANDLE);
+
+impl Drop for ServiceHandle {
+    fn drop(&mut self) {
+        if self.0 != 0 {
+            unsafe { Services::CloseServiceHandle(self.0) };
+        }
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/provisioning_client/group_change.rs b/codex-rs/windows-sandbox-rs/src/provisioning_client/group_change.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6eca7033dc1258b538cfd173bd64787c048ef6bc
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/provisioning_client/group_change.rs
@@ -0,0 +1,25 @@
+//! Retry only the service's authenticated refusal before dispatch.
+//! A lost response may follow a mutation, so the retry's transport errors stay errors.
+
+use std::time::Duration;
+use std::time::Instant;
+
+use crate::FramedProvisioningMessage;
+use crate::SandboxProvisioningResponse;
+
+pub(super) fn retry(
+    request: &FramedProvisioningMessage,
+    deadline: Instant,
+) -> anyhow::Result<SandboxProvisioningResponse> {
+    let mut pipe = loop {
+        if let Some(pipe) = super::connect(deadline)? {
+            break pipe;
+        }
+        anyhow::ensure!(
+            Instant::now() < deadline,
+            "refreshed sandbox service pipe is unavailable"
+        );
+        std::thread::sleep(Duration::from_millis(25));
+    };
+    super::exchange_request(&mut pipe, request, deadline)
+}
diff --git a/codex-rs/windows-sandbox-rs/src/provisioning_client/refresh_retry.rs b/codex-rs/windows-sandbox-rs/src/provisioning_client/refresh_retry.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c4ea23369c98a0b74052d96e0e4be21c4f20a79b
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/provisioning_client/refresh_retry.rs
@@ -0,0 +1,105 @@
+//! Resume gated registration refresh only after an authenticated service restart.
+//! Only response-side pipe disconnections qualify, never failed authentication,
+//! failed request writes, explicit replies, or protocol errors.
+
+use std::fs::File;
+use std::io;
+use std::os::windows::io::AsRawHandle;
+use std::time::Duration;
+use std::time::Instant;
+
+use anyhow::Context;
+use windows_sys::Win32::Foundation::ERROR_BROKEN_PIPE;
+use windows_sys::Win32::Foundation::ERROR_NO_DATA;
+use windows_sys::Win32::Foundation::ERROR_PIPE_NOT_CONNECTED;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::System::Services::SERVICE_START_PENDING;
+
+use crate::FramedProvisioningMessage;
+use crate::SandboxProvisioningResponse;
+
+// Registering the service-bearing package can restart the service once for each
+// of the two managed accounts. Keep both retries inside the original deadline.
+const MAX_SERVICE_RESTARTS: usize = 2;
+const RECONNECT_POLL_INTERVAL: Duration = Duration::from_millis(25);
+
+pub(super) fn send(
+    mut pipe: File,
+    request: &FramedProvisioningMessage,
+    deadline: Instant,
+) -> anyhow::Result<SandboxProvisioningResponse> {
+    let mut restarts_remaining = MAX_SERVICE_RESTARTS;
+    loop {
+        remaining_time(deadline)?;
+        let server_pid = super::verify_server(pipe.as_raw_handle() as HANDLE)
+            .context("authenticate provisioning pipe server")?;
+        crate::write_provisioning_frame(&mut pipe, request)
+            .context("send sandbox provisioning request")?;
+        let response = super::read_response(&mut pipe, deadline);
+        if !take_restart(&response, &mut restarts_remaining, deadline) {
+            return response;
+        }
+        drop(pipe);
+        pipe = connect_after_restart(server_pid, deadline)?;
+    }
+}
+
+fn connect_after_restart(previous_pid: u32, deadline: Instant) -> anyhow::Result<File> {
+    loop {
+        remaining_time(deadline)?;
+        if let Some(pipe) = super::connect(deadline)?
+            && super::pipe_server_process_id(pipe.as_raw_handle() as HANDLE)? != previous_pid
+            // The service creates its listener before reporting RUNNING.
+            && super::query_service_status()?.dwCurrentState != SERVICE_START_PENDING
+        {
+            // The caller authenticates this new PID against the running SCM
+            // service before writing. A same-PID reuse is conservatively refused.
+            return Ok(pipe);
+        }
+        std::thread::sleep(remaining_time(deadline)?.min(RECONNECT_POLL_INTERVAL));
+    }
+}
+
+fn remaining_time(deadline: Instant) -> io::Result<Duration> {
+    let remaining = deadline.saturating_duration_since(Instant::now());
+    if remaining.is_zero() {
+        return Err(io::Error::new(
+            io::ErrorKind::TimedOut,
+            "timed out waiting for restarted sandbox provisioning service",
+        ));
+    }
+    Ok(remaining)
+}
+
+fn take_restart(
+    response: &anyhow::Result<SandboxProvisioningResponse>,
+    restarts_remaining: &mut usize,
+    deadline: Instant,
+) -> bool {
+    let Err(error) = response else {
+        return false;
+    };
+    if *restarts_remaining == 0
+        || Instant::now() >= deadline
+        || !error.downcast_ref::<io::Error>().is_some_and(|error| {
+            matches!(
+                error.kind(),
+                io::ErrorKind::UnexpectedEof | io::ErrorKind::BrokenPipe
+            ) || matches!(
+                error.raw_os_error(),
+                Some(code)
+                    if code == ERROR_BROKEN_PIPE as i32
+                        || code == ERROR_NO_DATA as i32
+                        || code == ERROR_PIPE_NOT_CONNECTED as i32
+            )
+        })
+    {
+        return false;
+    }
+    *restarts_remaining -= 1;
+    true
+}
+
+#[cfg(test)]
+#[path = "refresh_retry_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/provisioning_client/refresh_retry_tests.rs b/codex-rs/windows-sandbox-rs/src/provisioning_client/refresh_retry_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ab553e75df833fcd69cd9ade1e1a1f890646940e
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/provisioning_client/refresh_retry_tests.rs
@@ -0,0 +1,121 @@
+//! Regression coverage for reply classification and the shared restart deadline/budget.
+
+use super::*;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn authentication_failure_cannot_write_or_replay_the_request() -> anyhow::Result<()> {
+    let pipe = tempfile::tempfile()?;
+    let observation = pipe.try_clone()?;
+    let request = FramedProvisioningMessage {
+        version: crate::PROVISIONING_PROTOCOL_VERSION,
+        message: crate::ProvisioningMessage::ProvisionSandboxRequest {
+            payload: crate::SandboxProvisioningRequest {
+                codex_home: r"C:\test-home".to_owned(),
+                registered_core: true,
+                refresh_only: true,
+                settings: crate::WindowsSandboxProvisioningSettings {
+                    proxy_ports: Vec::new(),
+                    allow_local_binding: false,
+                },
+                listeners: crate::WindowsSandboxProxyListeners::default(),
+            },
+        },
+    };
+    let error = send(pipe, &request, Instant::now() + Duration::from_secs(60)).unwrap_err();
+    assert_eq!(error.to_string(), "authenticate provisioning pipe server");
+    assert_eq!(observation.metadata()?.len(), 0);
+    Ok(())
+}
+
+#[test]
+fn permits_two_response_disconnects_but_not_a_third() {
+    let deadline = Instant::now() + Duration::from_secs(60);
+    let response = Err(io::Error::from(io::ErrorKind::UnexpectedEof).into());
+    let mut remaining = MAX_SERVICE_RESTARTS;
+    let decisions = (0..3)
+        .map(|_| take_restart(&response, &mut remaining, deadline))
+        .collect::<Vec<_>>();
+    assert_eq!((decisions, remaining), (vec![true, true, false], 0));
+}
+
+#[test]
+fn accepts_only_response_pipe_disconnect_errors() {
+    let deadline = Instant::now() + Duration::from_secs(60);
+    for error in [
+        io::Error::from(io::ErrorKind::UnexpectedEof),
+        io::Error::from(io::ErrorKind::BrokenPipe),
+        io::Error::from_raw_os_error(ERROR_BROKEN_PIPE as i32),
+        io::Error::from_raw_os_error(ERROR_NO_DATA as i32),
+        io::Error::from_raw_os_error(ERROR_PIPE_NOT_CONNECTED as i32),
+    ] {
+        let response = Err(anyhow::Error::from(error).context("read response"));
+        let mut remaining = MAX_SERVICE_RESTARTS;
+        assert_eq!(
+            (take_restart(&response, &mut remaining, deadline), remaining),
+            (true, 1)
+        );
+    }
+}
+
+#[test]
+fn explicit_replies_never_consume_a_restart() {
+    let deadline = Instant::now() + Duration::from_secs(60);
+    for response in [
+        SandboxProvisioningResponse::Ok,
+        SandboxProvisioningResponse::Unavailable,
+        SandboxProvisioningResponse::Error {
+            message: "refused".to_owned(),
+        },
+        SandboxProvisioningResponse::Error {
+            message: crate::SANDBOX_GROUP_CHANGED.to_owned(),
+        },
+    ] {
+        let mut remaining = MAX_SERVICE_RESTARTS;
+        assert_eq!(
+            (
+                take_restart(&Ok(response), &mut remaining, deadline),
+                remaining
+            ),
+            (false, MAX_SERVICE_RESTARTS)
+        );
+    }
+}
+
+#[test]
+fn timeout_permission_and_protocol_errors_do_not_consume_a_restart() {
+    let deadline = Instant::now() + Duration::from_secs(60);
+    for error in [
+        io::Error::from(io::ErrorKind::TimedOut).into(),
+        io::Error::from(io::ErrorKind::PermissionDenied).into(),
+        io::Error::from(io::ErrorKind::InvalidData).into(),
+        anyhow::anyhow!("unexpected sandbox provisioning response message"),
+        serde_json::from_str::<FramedProvisioningMessage>("not JSON")
+            .unwrap_err()
+            .into(),
+    ] {
+        let mut remaining = MAX_SERVICE_RESTARTS;
+        assert_eq!(
+            (
+                take_restart(&Err(error), &mut remaining, deadline),
+                remaining
+            ),
+            (false, MAX_SERVICE_RESTARTS)
+        );
+    }
+}
+
+#[test]
+fn disconnect_after_original_deadline_is_not_retried() {
+    let deadline = Instant::now();
+    let response = Err(io::Error::from(io::ErrorKind::UnexpectedEof).into());
+    let mut remaining = MAX_SERVICE_RESTARTS;
+    assert_eq!(
+        (take_restart(&response, &mut remaining, deadline), remaining),
+        (false, MAX_SERVICE_RESTARTS)
+    );
+    assert_eq!(
+        remaining_time(deadline).unwrap_err().kind(),
+        io::ErrorKind::TimedOut
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/provisioning_protocol.rs b/codex-rs/windows-sandbox-rs/src/provisioning_protocol.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6a8c978477fc3b644983b9b30e653c39a381da5b
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/provisioning_protocol.rs
@@ -0,0 +1,89 @@
+//! Dedicated protocol exchanged with the Windows sandbox provisioning service.
+
+use crate::WindowsSandboxProvisioningSettings;
+use anyhow::Result;
+use serde::Deserialize;
+use serde::Serialize;
+use std::io::Read;
+use std::io::Write;
+
+/// Protocol version shared by provisioning clients and the Windows service.
+pub const PROVISIONING_PROTOCOL_VERSION: u8 = 1;
+
+/// Named pipe used by the machine-wide Windows sandbox provisioning service.
+pub const SANDBOX_PROVISIONING_PIPE_NAME: &str = r"\\.\pipe\OpenAI.CodexSandbox";
+
+/// Pre-dispatch refusal: the caller may reconnect once to the refreshed pipe.
+pub const SANDBOX_GROUP_CHANGED: &str = "sandbox group changed before authentication";
+
+/// Versioned provisioning-service message carried in a length-prefixed JSON frame.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct FramedProvisioningMessage {
+    pub version: u8,
+    #[serde(flatten)]
+    pub message: ProvisioningMessage,
+}
+
+/// Request and response messages exchanged with the provisioning service.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum ProvisioningMessage {
+    /// Records uninstall ownership without provisioning sandbox resources.
+    RegisterInstallationRequest {
+        codex_home: String,
+    },
+    ProvisionSandboxRequest {
+        payload: SandboxProvisioningRequest,
+    },
+    ProvisionSandboxResponse {
+        payload: SandboxProvisioningResponse,
+    },
+}
+
+/// Sandbox setup parameters sent to the provisioning service.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(deny_unknown_fields)]
+pub struct SandboxProvisioningRequest {
+    pub codex_home: String,
+    /// Routing request; the service independently authenticates its installed caller.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub registered_core: bool,
+    /// Refresh an existing registration without creating or repairing sandbox accounts.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub refresh_only: bool,
+    pub settings: WindowsSandboxProvisioningSettings,
+    pub listeners: WindowsSandboxProxyListeners,
+}
+
+/// Known proxy protocols used for managed-policy validation, separate from firewall settings.
+#[derive(Clone, Debug, Default, Deserialize, Serialize, Eq, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct WindowsSandboxProxyListeners {
+    pub http_ports: Vec<u16>,
+    pub socks_ports: Vec<u16>,
+}
+
+/// Result returned by the sandbox provisioning service.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(tag = "status", rename_all = "snake_case")]
+pub enum SandboxProvisioningResponse {
+    Ok,
+    /// The client should fall back to its elevated setup helper.
+    Unavailable,
+    Error {
+        message: String,
+    },
+}
+
+/// Write a length-prefixed provisioning-service message.
+pub fn write_provisioning_frame<W: Write>(
+    writer: W,
+    message: &FramedProvisioningMessage,
+) -> Result<()> {
+    crate::framed_io::write_frame(writer, message)
+}
+
+/// Read a length-prefixed provisioning-service message, returning `None` on EOF.
+pub fn read_provisioning_frame<R: Read>(reader: R) -> Result<Option<FramedProvisioningMessage>> {
+    crate::framed_io::read_frame(reader)
+}
diff --git a/codex-rs/windows-sandbox-rs/src/resolved_permissions.rs b/codex-rs/windows-sandbox-rs/src/resolved_permissions.rs
new file mode 100644
index 0000000000000000000000000000000000000000..392dd5fc0df6e11dd079144a50afa689985f519a
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/resolved_permissions.rs
@@ -0,0 +1,613 @@
+use anyhow::Result;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::permissions::FileSystemPath;
+use codex_protocol::permissions::FileSystemSandboxEntry;
+use codex_protocol::permissions::FileSystemSandboxKind;
+use codex_protocol::permissions::FileSystemSandboxPolicy;
+use codex_protocol::permissions::FileSystemSpecialPath::Root;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_protocol::permissions::ReadDenyMatcher;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+/// Windows-local view of the runtime permission profile.
+///
+/// Most Windows sandbox code needs resolved runtime permissions plus a few
+/// Windows-specific path conventions, not the user/config-facing
+/// `PermissionProfile` enum itself.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResolvedWindowsSandboxPermissions {
+    file_system: FileSystemSandboxPolicy,
+    network: NetworkSandboxPolicy,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct WindowsWritableRoot {
+    pub(crate) root: PathBuf,
+    pub(crate) read_only_subpaths: Vec<PathBuf>,
+}
+
+/// Restricted-token family needed to enforce a Windows permission profile.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WindowsSandboxTokenMode {
+    ReadOnlyCapability,
+    WritableRootsCapability,
+}
+
+/// Chooses the restricted-token family needed for a managed permission profile.
+pub fn token_mode_for_permission_profile(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    cwd: &Path,
+    env_map: &HashMap<String, String>,
+) -> Result<WindowsSandboxTokenMode> {
+    let permissions =
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        )?;
+    if permissions.file_system.has_full_disk_write_access() {
+        anyhow::bail!(
+            "permission profile requests full-disk filesystem writes, which cannot be enforced by the Windows sandbox"
+        );
+    }
+    if permissions.writable_roots_for_cwd(cwd, env_map).is_empty() {
+        Ok(WindowsSandboxTokenMode::ReadOnlyCapability)
+    } else {
+        Ok(WindowsSandboxTokenMode::WritableRootsCapability)
+    }
+}
+
+impl ResolvedWindowsSandboxPermissions {
+    pub fn try_from_permission_profile(permission_profile: &PermissionProfile) -> Result<Self> {
+        if !matches!(permission_profile, PermissionProfile::Managed { .. }) {
+            anyhow::bail!(
+                "only managed permission profiles can be enforced by the Windows sandbox"
+            );
+        }
+        let (file_system, network) = permission_profile.to_runtime_permissions();
+        if !matches!(file_system.kind, FileSystemSandboxKind::Restricted) {
+            anyhow::bail!(
+                "only restricted managed filesystem permissions can be enforced by the Windows sandbox"
+            );
+        }
+        Ok(Self {
+            file_system,
+            network,
+        })
+    }
+
+    /// Resolves a managed permission profile and binds symbolic `:workspace_roots`
+    /// entries to the workspace roots supplied by the caller.
+    pub fn try_from_permission_profile_for_workspace_roots(
+        permission_profile: &PermissionProfile,
+        workspace_roots: &[AbsolutePathBuf],
+    ) -> Result<Self> {
+        let mut permissions = Self::try_from_permission_profile(permission_profile)?;
+        permissions.file_system = permissions
+            .file_system
+            .materialize_project_roots_with_workspace_roots(workspace_roots);
+        Ok(permissions)
+    }
+
+    pub(crate) fn should_apply_network_block(&self) -> bool {
+        !self.network.is_enabled()
+    }
+
+    pub(crate) fn network_policy(&self) -> NetworkSandboxPolicy {
+        self.network
+    }
+
+    /// Rejects filesystem policies that the elevated Windows sandbox cannot
+    /// enforce safely.
+    pub fn validate_elevated_filesystem_policy(&self, cwd: &Path) -> Result<()> {
+        let root = cwd
+            .ancestors()
+            .last()
+            .ok_or_else(|| anyhow::anyhow!("command cwd has no filesystem root"))?;
+        let root_is_denied = ReadDenyMatcher::try_new_for_local_paths(&self.file_system, cwd)
+            .map_err(anyhow::Error::msg)?
+            .is_some_and(|matcher| matcher.is_local_path_read_denied(root));
+        if !self.file_system.can_read_local_path_with_cwd(root, cwd) || root_is_denied {
+            anyhow::bail!("elevated Windows sandbox requires effective `:root` read access");
+        }
+        Ok(())
+    }
+
+    pub(crate) fn has_full_disk_read_access(&self) -> bool {
+        self.file_system.has_full_disk_read_access()
+    }
+
+    pub(crate) fn has_symbolic_root_read_access(&self, cwd: &Path) -> bool {
+        self.file_system.entries.iter().any(|entry| {
+            matches!(&entry.path, FileSystemPath::Special { value: Root })
+                && entry.access.can_read()
+        }) && cwd
+            .ancestors()
+            .last()
+            .is_some_and(|root| self.file_system.can_read_local_path_with_cwd(root, cwd))
+    }
+
+    pub(crate) fn include_platform_defaults(&self) -> bool {
+        self.file_system.include_platform_defaults()
+    }
+
+    pub(crate) fn readable_roots_for_cwd(&self, cwd: &Path) -> Vec<PathBuf> {
+        self.file_system
+            .get_readable_roots_with_cwd(cwd)
+            .into_iter()
+            .map(AbsolutePathBuf::into_path_buf)
+            .collect()
+    }
+
+    pub(crate) fn uses_write_capabilities_for_cwd(
+        &self,
+        cwd: &Path,
+        env_map: &HashMap<String, String>,
+    ) -> bool {
+        !self.writable_roots_for_cwd(cwd, env_map).is_empty()
+    }
+
+    pub(crate) fn writable_roots_for_cwd(
+        &self,
+        cwd: &Path,
+        env_map: &HashMap<String, String>,
+    ) -> Vec<WindowsWritableRoot> {
+        let mut file_system = self.file_system.clone();
+        file_system
+            .entries
+            .retain(|FileSystemSandboxEntry { path, .. }| {
+                !matches!(
+                    path,
+                    FileSystemPath::Special {
+                        value: codex_protocol::permissions::FileSystemSpecialPath::Tmpdir
+                            | codex_protocol::permissions::FileSystemSpecialPath::SlashTmp,
+                    }
+                )
+            });
+
+        let mut roots = file_system
+            .get_writable_roots_with_cwd(cwd)
+            .into_iter()
+            .map(|root| WindowsWritableRoot {
+                root: root.root.into_path_buf(),
+                read_only_subpaths: root
+                    .read_only_subpaths
+                    .into_iter()
+                    .map(AbsolutePathBuf::into_path_buf)
+                    .collect(),
+            })
+            .collect::<Vec<_>>();
+
+        if self.has_writable_tmpdir_entry() {
+            roots.extend(windows_temp_env_roots(env_map).into_iter().map(|root| {
+                WindowsWritableRoot {
+                    root,
+                    read_only_subpaths: Vec::new(),
+                }
+            }));
+        }
+
+        roots
+    }
+
+    fn has_writable_tmpdir_entry(&self) -> bool {
+        self.file_system
+            .entries
+            .iter()
+            .any(|FileSystemSandboxEntry { path, access, .. }| {
+                matches!(
+                    path,
+                    FileSystemPath::Special {
+                        value: codex_protocol::permissions::FileSystemSpecialPath::Tmpdir,
+                    }
+                ) && access.can_write()
+            })
+    }
+}
+
+fn windows_temp_env_roots(env_map: &HashMap<String, String>) -> Vec<PathBuf> {
+    ["TEMP", "TMP"]
+        .into_iter()
+        .filter_map(|key| {
+            env_map
+                .get(key)
+                .map(|value| PathBuf::from(value.as_str()))
+                .or_else(|| std::env::var_os(key).map(PathBuf::from))
+        })
+        .filter(|path| path.is_absolute())
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use codex_protocol::models::ManagedFileSystemPermissions;
+    use codex_protocol::permissions::FileSystemAccessMode;
+    use codex_protocol::permissions::FileSystemSandboxEntry;
+    use codex_protocol::permissions::FileSystemSpecialPath;
+    use codex_protocol::permissions::project_roots_glob_pattern;
+    use pretty_assertions::assert_eq;
+    use tempfile::TempDir;
+
+    fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf> {
+        vec![AbsolutePathBuf::from_absolute_path(root).expect("absolute workspace root")]
+    }
+
+    fn permission_profile_with_entries(entries: Vec<FileSystemSandboxEntry>) -> PermissionProfile {
+        PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Restricted {
+                entries,
+                glob_scan_max_depth: None,
+            },
+            network: NetworkSandboxPolicy::Restricted,
+        }
+    }
+
+    #[test]
+    fn permission_profile_workspace_write_uses_windows_temp_env_vars() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = tmp.path().join("workspace");
+        let temp_dir = tmp.path().join("temp");
+        std::fs::create_dir_all(&cwd).expect("create cwd");
+        std::fs::create_dir_all(&temp_dir).expect("create temp dir");
+
+        let mut env_map = HashMap::new();
+        env_map.insert("TEMP".to_string(), temp_dir.to_string_lossy().to_string());
+        env_map.insert("TMP".to_string(), temp_dir.to_string_lossy().to_string());
+
+        let permissions = ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+            &PermissionProfile::workspace_write(),
+        )
+        .expect("managed permission profile");
+        let roots = permissions
+            .writable_roots_for_cwd(&cwd, &env_map)
+            .into_iter()
+            .map(|root| root.root)
+            .collect::<std::collections::HashSet<_>>();
+
+        let expected_roots = [
+            temp_dir,
+            dunce::canonicalize(&cwd).expect("canonicalize cwd"),
+        ]
+        .into_iter()
+        .collect::<std::collections::HashSet<_>>();
+
+        assert_eq!(expected_roots, roots);
+    }
+
+    #[test]
+    fn permission_profile_workspace_root_uses_runtime_workspace_roots() {
+        let tmp = TempDir::new().expect("tempdir");
+        let workspace_root = tmp.path().join("workspace");
+        let command_cwd = workspace_root.join("subdir");
+        std::fs::create_dir_all(&command_cwd).expect("create command cwd");
+
+        let permission_profile = PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Restricted {
+                entries: vec![FileSystemSandboxEntry {
+                    path: FileSystemPath::Special {
+                        value: FileSystemSpecialPath::project_roots(/*subpath*/ None),
+                    },
+                    access: FileSystemAccessMode::Write,
+                    missing_path_behavior: None,
+                }],
+                glob_scan_max_depth: None,
+            },
+            network: NetworkSandboxPolicy::Restricted,
+        };
+        let workspace_roots = workspace_roots_for(workspace_root.as_path());
+        let permissions =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                &permission_profile,
+                workspace_roots.as_slice(),
+            )
+            .expect("managed permission profile");
+
+        let roots = permissions
+            .writable_roots_for_cwd(&command_cwd, &HashMap::new())
+            .into_iter()
+            .map(|root| root.root)
+            .collect::<Vec<_>>();
+
+        assert_eq!(
+            roots,
+            vec![dunce::canonicalize(&workspace_root).expect("canonical workspace root")]
+        );
+    }
+
+    #[test]
+    fn permission_profile_workspace_roots_expand_all_runtime_workspace_roots() {
+        let tmp = TempDir::new().expect("tempdir");
+        let first = AbsolutePathBuf::from_absolute_path(tmp.path().join("first"))
+            .expect("absolute first root");
+        let second = AbsolutePathBuf::from_absolute_path(tmp.path().join("second"))
+            .expect("absolute second root");
+        let permission_profile = PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Restricted {
+                entries: vec![
+                    FileSystemSandboxEntry {
+                        path: FileSystemPath::Special {
+                            value: FileSystemSpecialPath::project_roots(/*subpath*/ None),
+                        },
+                        access: FileSystemAccessMode::Write,
+                        missing_path_behavior: None,
+                    },
+                    FileSystemSandboxEntry {
+                        path: FileSystemPath::Special {
+                            value: FileSystemSpecialPath::project_roots(Some(".git".into())),
+                        },
+                        access: FileSystemAccessMode::Deny,
+                        missing_path_behavior: None,
+                    },
+                    FileSystemSandboxEntry {
+                        path: FileSystemPath::GlobPattern {
+                            pattern: project_roots_glob_pattern(Path::new("**/*.env")),
+                        },
+                        access: FileSystemAccessMode::Deny,
+                        missing_path_behavior: None,
+                    },
+                ],
+                glob_scan_max_depth: None,
+            },
+            network: NetworkSandboxPolicy::Restricted,
+        };
+
+        let permissions =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                &permission_profile,
+                &[first.clone(), second.clone()],
+            )
+            .expect("managed permission profile");
+
+        assert_eq!(
+            permissions.file_system,
+            FileSystemSandboxPolicy::restricted(vec![
+                FileSystemSandboxEntry {
+                    path: FileSystemPath::Path {
+                        path: first.clone().into(),
+                    },
+                    access: FileSystemAccessMode::Write,
+                    missing_path_behavior: None,
+                },
+                FileSystemSandboxEntry {
+                    path: FileSystemPath::Path {
+                        path: second.clone().into(),
+                    },
+                    access: FileSystemAccessMode::Write,
+                    missing_path_behavior: None,
+                },
+                FileSystemSandboxEntry {
+                    path: FileSystemPath::Path {
+                        path: first.join(".git").into(),
+                    },
+                    access: FileSystemAccessMode::Deny,
+                    missing_path_behavior: None,
+                },
+                FileSystemSandboxEntry {
+                    path: FileSystemPath::Path {
+                        path: second.join(".git").into(),
+                    },
+                    access: FileSystemAccessMode::Deny,
+                    missing_path_behavior: None,
+                },
+                FileSystemSandboxEntry {
+                    path: FileSystemPath::GlobPattern {
+                        pattern: AbsolutePathBuf::resolve_path_against_base(
+                            "**/*.env",
+                            first.as_path(),
+                        )
+                        .to_string_lossy()
+                        .into_owned(),
+                    },
+                    access: FileSystemAccessMode::Deny,
+                    missing_path_behavior: None,
+                },
+                FileSystemSandboxEntry {
+                    path: FileSystemPath::GlobPattern {
+                        pattern: AbsolutePathBuf::resolve_path_against_base(
+                            "**/*.env",
+                            second.as_path(),
+                        )
+                        .to_string_lossy()
+                        .into_owned(),
+                    },
+                    access: FileSystemAccessMode::Deny,
+                    missing_path_behavior: None,
+                },
+            ])
+        );
+    }
+
+    #[test]
+    fn token_mode_for_profile_without_writable_roots_uses_readonly_capability() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = tmp.path().join("workspace");
+        std::fs::create_dir_all(&cwd).expect("create cwd");
+        let workspace_roots = workspace_roots_for(cwd.as_path());
+
+        let token_mode = token_mode_for_permission_profile(
+            &PermissionProfile::read_only(),
+            workspace_roots.as_slice(),
+            &cwd,
+            &HashMap::new(),
+        )
+        .expect("token mode");
+
+        assert_eq!(WindowsSandboxTokenMode::ReadOnlyCapability, token_mode);
+    }
+
+    #[test]
+    fn token_mode_for_profile_with_writable_roots_uses_write_capabilities() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = tmp.path().join("workspace");
+        std::fs::create_dir_all(&cwd).expect("create cwd");
+        let workspace_roots = workspace_roots_for(cwd.as_path());
+
+        let token_mode = token_mode_for_permission_profile(
+            &PermissionProfile::workspace_write(),
+            workspace_roots.as_slice(),
+            &cwd,
+            &HashMap::new(),
+        )
+        .expect("token mode");
+
+        assert_eq!(WindowsSandboxTokenMode::WritableRootsCapability, token_mode);
+    }
+
+    #[test]
+    fn permission_profile_rejects_disabled_profiles() {
+        let err = ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+            &PermissionProfile::Disabled,
+        )
+        .expect_err("disabled profile should not resolve for sandbox enforcement");
+
+        assert!(
+            err.to_string()
+                .contains("only managed permission profiles can be enforced")
+        );
+    }
+
+    #[test]
+    fn permission_profile_rejects_unrestricted_managed_filesystem() {
+        let permission_profile = PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Unrestricted,
+            network: NetworkSandboxPolicy::Restricted,
+        };
+
+        let err =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile(&permission_profile)
+                .expect_err("unrestricted profile should not resolve for sandbox enforcement");
+
+        assert!(
+            err.to_string()
+                .contains("only restricted managed filesystem permissions can be enforced")
+        );
+    }
+
+    #[test]
+    fn elevated_filesystem_policy_requires_effective_root_read_access() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = tmp.path().join("workspace");
+        let denied_path = tmp.path().join("private");
+        std::fs::create_dir_all(&cwd).expect("create cwd");
+
+        let default_root_denied = ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+            &permission_profile_with_entries(vec![FileSystemSandboxEntry::new(
+                FileSystemPath::Special {
+                    value: FileSystemSpecialPath::project_roots(/*subpath*/ None),
+                },
+                FileSystemAccessMode::Write,
+            )]),
+        )
+        .expect("managed permission profile");
+        let root_read_with_carveout =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+                &permission_profile_with_entries(vec![
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::Special {
+                            value: FileSystemSpecialPath::Root,
+                        },
+                        FileSystemAccessMode::Read,
+                    ),
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::Path {
+                            path: AbsolutePathBuf::from_absolute_path(&denied_path)
+                                .expect("absolute denied path")
+                                .into(),
+                        },
+                        FileSystemAccessMode::Deny,
+                    ),
+                ]),
+            )
+            .expect("managed permission profile");
+        let root = cwd.ancestors().last().expect("filesystem root");
+        let root_read_with_explicit_path =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+                &permission_profile_with_entries(vec![FileSystemSandboxEntry::new(
+                    FileSystemPath::Path {
+                        path: AbsolutePathBuf::from_absolute_path(root)
+                            .expect("absolute root")
+                            .into(),
+                    },
+                    FileSystemAccessMode::Read,
+                )]),
+            )
+            .expect("managed permission profile");
+        let root_read_with_root_deny_glob =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile(
+                &permission_profile_with_entries(vec![
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::Special {
+                            value: FileSystemSpecialPath::Root,
+                        },
+                        FileSystemAccessMode::Read,
+                    ),
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::GlobPattern {
+                            pattern: root.join("**").display().to_string(),
+                        },
+                        FileSystemAccessMode::Deny,
+                    ),
+                ]),
+            )
+            .expect("managed permission profile");
+
+        assert!(
+            default_root_denied
+                .validate_elevated_filesystem_policy(&cwd)
+                .is_err()
+        );
+        assert!(
+            root_read_with_carveout
+                .validate_elevated_filesystem_policy(&cwd)
+                .is_ok()
+        );
+        assert!(
+            root_read_with_explicit_path
+                .validate_elevated_filesystem_policy(&cwd)
+                .is_ok()
+        );
+        assert!(
+            root_read_with_root_deny_glob
+                .validate_elevated_filesystem_policy(&cwd)
+                .is_err()
+        );
+    }
+
+    #[test]
+    fn token_mode_rejects_full_disk_write_entries() {
+        let tmp = TempDir::new().expect("tempdir");
+        let cwd = tmp.path().join("workspace");
+        std::fs::create_dir_all(&cwd).expect("create cwd");
+        let permission_profile = PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Restricted {
+                entries: vec![FileSystemSandboxEntry {
+                    path: FileSystemPath::Special {
+                        value: FileSystemSpecialPath::Root,
+                    },
+                    access: FileSystemAccessMode::Write,
+                    missing_path_behavior: None,
+                }],
+                glob_scan_max_depth: None,
+            },
+            network: NetworkSandboxPolicy::Restricted,
+        };
+        let workspace_roots = workspace_roots_for(cwd.as_path());
+
+        let err = token_mode_for_permission_profile(
+            &permission_profile,
+            workspace_roots.as_slice(),
+            &cwd,
+            &HashMap::new(),
+        )
+        .expect_err("full disk writes should not resolve to a token mode");
+
+        assert!(
+            err.to_string()
+                .contains("full-disk filesystem writes, which cannot be enforced")
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/runtime_ownership.rs b/codex-rs/windows-sandbox-rs/src/runtime_ownership.rs
new file mode 100644
index 0000000000000000000000000000000000000000..eea65af888e01a41d15835ed96d1949f555c1f3d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/runtime_ownership.rs
@@ -0,0 +1,235 @@
+//! Shares the protected installation record with mutating sandbox setup.
+//! Callers must hold the sandbox setup mutex while admitting or changing ownership.
+
+use std::io;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use serde::Deserialize;
+use serde::Serialize;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::System::Registry as registry;
+
+/// Selects legacy helper materialization or verified app-contained Core for setup.
+#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum SetupRuntime {
+    #[default]
+    Legacy,
+    Registered,
+}
+
+impl SetupRuntime {
+    #[expect(
+        clippy::trivially_copy_pass_by_ref,
+        reason = "serde requires a borrowed field"
+    )]
+    pub(crate) fn is_legacy(&self) -> bool {
+        *self == Self::Legacy
+    }
+}
+
+/// Package-scoped execution alias declared for the app's sandbox runner.
+pub const APP_CORE_RUNNER_ALIAS: &str = "codex-core-command-runner.exe";
+
+/// The service may register its package only for these managed sandbox accounts.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SandboxRuntimeAccount {
+    Offline,
+    Online,
+}
+
+impl SandboxRuntimeAccount {
+    pub fn username(self) -> &'static str {
+        match self {
+            Self::Offline => crate::setup::OFFLINE_USERNAME,
+            Self::Online => crate::setup::ONLINE_USERNAME,
+        }
+    }
+}
+
+pub use crate::installation_record::INSTALLATION_KEY;
+pub use crate::installation_record::INSTALLATION_VALUE;
+use crate::installation_record::InstallationRecord;
+use crate::winutil::to_wide;
+
+// Old services overwrite the parent value and delete its key on uninstall.
+// A child key preserves Core state and makes that old whole-key delete fail.
+pub const CORE_INSTALLATION_KEY: &str =
+    r"SOFTWARE\OpenAI\Codex\WindowsSandboxService\RegisteredCore";
+
+/// Written before registration so a service restart cannot lose cleanup ownership.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct RuntimeRegistration {
+    pub package_family: String,
+    pub accounts: Vec<RuntimeAccountRegistration>,
+    /// Owner-authorized AppData roots, recorded before granting metadata access.
+    /// Retain former roots through redirection and package updates until cleanup.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub metadata_roots: Vec<std::path::PathBuf>,
+    /// Committed only after both registrations and metadata grants succeed.
+    #[serde(default)]
+    pub ready_package: Option<String>,
+    /// Fences setup during normal teardown; a restart must not replay it.
+    /// Old non-null phase journals fail to decode rather than lose their fence.
+    #[serde(default, alias = "cleanup")]
+    pub retiring: Option<String>,
+}
+
+impl RuntimeRegistration {
+    pub fn ready_for_package(&self, full_name: &str) -> bool {
+        self.can_resume_registration() && self.ready_package.as_deref() == Some(full_name)
+    }
+
+    /// Complete account ownership allows registration to resume, not runtime execution.
+    /// Callers must still authenticate the owner and verify the live account SIDs/settings.
+    pub fn can_resume_registration(&self) -> bool {
+        self.retiring.is_none()
+            && self.accounts.len() == 2
+            && self.accounts[0].account != self.accounts[1].account
+            && self
+                .accounts
+                .iter()
+                .all(|account| account.alias_path.is_some())
+    }
+}
+
+impl InstallationRecord {
+    pub fn runtime(&self) -> Result<&RuntimeRegistration> {
+        self.runtime
+            .as_ref()
+            .context("registered runtime ownership is missing")
+    }
+
+    pub fn runtime_mut(&mut self) -> Result<&mut RuntimeRegistration> {
+        self.runtime
+            .as_mut()
+            .context("registered runtime ownership is missing")
+    }
+
+    /// Any persisted cleanup has committed to removing this resource generation.
+    pub fn admit_owner(&self, owner: &InstallationRecord, family: &str) -> Result<()> {
+        ensure!(
+            self.user_sid == owner.user_sid
+                && self.codex_home == owner.codex_home
+                && self.runtime()?.package_family.eq_ignore_ascii_case(family),
+            "registered sandbox resources belong to a different owner or package"
+        );
+        ensure!(
+            self.runtime()?.retiring.is_none(),
+            "registered sandbox cleanup must finish before provisioning"
+        );
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub struct RuntimeAccountRegistration {
+    pub account: SandboxRuntimeAccount,
+    pub user_sid: String,
+    /// OS-resolved alias written by the service, never inferred from a user name.
+    #[serde(default)]
+    pub alias_path: Option<std::path::PathBuf>,
+}
+
+/// Capture the requesting process identity before elevation, never USERNAME.
+pub(crate) fn current_setup_user() -> Result<String> {
+    use std::os::windows::io::FromRawHandle;
+    use std::os::windows::io::OwnedHandle;
+    use windows_sys::Win32::Security as security;
+    use windows_sys::Win32::System::Threading as threading;
+    let mut token = 0;
+    if unsafe {
+        threading::OpenProcessToken(
+            threading::GetCurrentProcess(),
+            security::TOKEN_QUERY,
+            &mut token,
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error()).context("query requesting setup identity");
+    }
+    let _token = unsafe { OwnedHandle::from_raw_handle(token as _) };
+    let sid = unsafe { crate::token::get_user_sid_bytes(token)? };
+    unsafe { crate::winutil::account_name_from_sid(sid.as_ptr() as _) }
+        .context("resolve requesting setup identity")
+}
+/// Core owns its complete record; the old parent is only a fallback before/after Core.
+pub fn load_installation() -> Result<Option<InstallationRecord>> {
+    if let Some(record) = crate::installation_record::load_from(CORE_INSTALLATION_KEY)? {
+        ensure!(
+            record.runtime.is_some(),
+            "Core installation record is missing runtime state"
+        );
+        return Ok(Some(record));
+    }
+    crate::installation_record::load_from(INSTALLATION_KEY)
+}
+
+/// Retires only legacy ownership while the caller holds the setup lock.
+/// Registered Core ownership belongs to its post-service-exit finalizer.
+pub fn remove_installation() -> Result<()> {
+    let Some(record) = load_installation()? else {
+        return Ok(());
+    };
+    ensure!(
+        record.runtime.is_none(),
+        "registered Core ownership must be retired after service exit"
+    );
+    let status = unsafe {
+        registry::RegDeleteKeyValueW(
+            registry::HKEY_LOCAL_MACHINE,
+            to_wide(INSTALLATION_KEY).as_ptr(),
+            to_wide(INSTALLATION_VALUE).as_ptr(),
+        )
+    };
+    match status {
+        foundation::ERROR_SUCCESS
+        | foundation::ERROR_FILE_NOT_FOUND
+        | foundation::ERROR_PATH_NOT_FOUND => flush_installation(INSTALLATION_KEY),
+        status => Err(io::Error::from_raw_os_error(status as i32))
+            .context("remove protected legacy sandbox installation record"),
+    }
+}
+
+/// Persists and flushes ownership before an operation may outlive this service.
+/// The caller must hold the sandbox setup mutex across its read/modify/write.
+pub fn save_installation(record: &InstallationRecord) -> Result<()> {
+    let key = if record.runtime.is_some() {
+        CORE_INSTALLATION_KEY
+    } else {
+        INSTALLATION_KEY
+    };
+    crate::installation_record::save_to(key, record)?;
+    flush_installation(key)
+}
+
+fn flush_installation(path: &str) -> Result<()> {
+    let mut key = 0;
+    let status = unsafe {
+        registry::RegOpenKeyExW(
+            registry::HKEY_LOCAL_MACHINE,
+            to_wide(path).as_ptr(),
+            0,
+            registry::KEY_QUERY_VALUE,
+            &mut key,
+        )
+    };
+    if status != foundation::ERROR_SUCCESS {
+        return Err(io::Error::from_raw_os_error(status as i32))
+            .context("open runtime ownership record");
+    }
+    let status = unsafe { registry::RegFlushKey(key) };
+    unsafe { registry::RegCloseKey(key) };
+    if status != foundation::ERROR_SUCCESS {
+        return Err(io::Error::from_raw_os_error(status as i32))
+            .context("flush runtime ownership record");
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "runtime_ownership_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/runtime_ownership_tests.rs b/codex-rs/windows-sandbox-rs/src/runtime_ownership_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9ef77269afad15a4ca2e6d4d1c74f9c7f3d2d2e4
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/runtime_ownership_tests.rs
@@ -0,0 +1,245 @@
+//! Tests owner admission, readiness receipts, and backward-compatible record decoding.
+
+use super::*;
+use crate::DesktopInstallation;
+use pretty_assertions::assert_eq;
+use std::path::PathBuf;
+
+fn record() -> InstallationRecord {
+    InstallationRecord {
+        user_sid: "S-1-5-21-1-2-3-1000".into(),
+        codex_home: PathBuf::from(r"C:\Users\owner\.codex"),
+        session_id: 1,
+        desktop_installation: Some(DesktopInstallation {
+            created_codex_home: true,
+            cache_home: PathBuf::from(r"C:\Users\owner\.cache"),
+        }),
+        runtime: Some(RuntimeRegistration {
+            package_family: "OpenAI.Codex_publisher".into(),
+            metadata_roots: Vec::new(),
+            ready_package: None,
+            accounts: vec![RuntimeAccountRegistration {
+                account: SandboxRuntimeAccount::Offline,
+                user_sid: "S-1-5-21-1-2-3-1001".into(),
+                alias_path: None,
+            }],
+            retiring: None,
+        }),
+    }
+}
+
+fn pending() -> InstallationRecord {
+    let mut record = record();
+    record.runtime_mut().unwrap().retiring = Some("one-cleanup-generation".into());
+    record
+}
+
+const READY_PACKAGE: &str = "OpenAI.Codex_1.0.0.0_arm64__publisher";
+
+fn ready_runtime() -> RuntimeRegistration {
+    let mut runtime = record().runtime.unwrap();
+    runtime.ready_package = Some(READY_PACKAGE.into());
+    runtime.accounts[0].alias_path = Some(PathBuf::from(r"C:\aliases\offline.exe"));
+    runtime.accounts.push(RuntimeAccountRegistration {
+        account: SandboxRuntimeAccount::Online,
+        user_sid: "S-1-5-21-1-2-3-1002".into(),
+        alias_path: Some(PathBuf::from(r"C:\aliases\online.exe")),
+    });
+    runtime
+}
+
+#[test]
+fn readiness_requires_a_receipt_for_the_current_package_version() {
+    let mut runtime = ready_runtime();
+    assert!(runtime.ready_for_package(READY_PACKAGE));
+    assert!(runtime.can_resume_registration());
+    assert!(!runtime.ready_for_package("OpenAI.Codex_2.0.0.0_arm64__publisher"));
+
+    runtime.ready_package = None;
+    assert!(!runtime.ready_for_package(READY_PACKAGE));
+    assert!(runtime.can_resume_registration());
+}
+
+#[test]
+fn readiness_requires_both_distinct_account_receipts() {
+    let mut missing_account = ready_runtime();
+    missing_account.accounts.pop();
+    let mut missing_alias = ready_runtime();
+    missing_alias.accounts[1].alias_path = None;
+    let mut duplicate_role = ready_runtime();
+    duplicate_role.accounts[1].account = SandboxRuntimeAccount::Offline;
+    let mut extra_account = ready_runtime();
+    extra_account
+        .accounts
+        .push(extra_account.accounts[0].clone());
+
+    for runtime in [
+        missing_account,
+        missing_alias,
+        duplicate_role,
+        extra_account,
+    ] {
+        assert!(!runtime.ready_for_package(READY_PACKAGE));
+        assert!(!runtime.can_resume_registration());
+    }
+}
+
+#[test]
+fn readiness_is_revoked_by_the_retirement_fence() {
+    let mut runtime = ready_runtime();
+    runtime.retiring = Some("one-cleanup-generation".into());
+    assert!(!runtime.ready_for_package(READY_PACKAGE));
+    assert!(!runtime.can_resume_registration());
+}
+
+#[test]
+fn admission_accepts_package_family_casing() {
+    for stored in ["OpenAI.Codex_publisher", "openai.codex_PUBLISHER"] {
+        let mut record = record();
+        record.runtime_mut().unwrap().package_family = stored.into();
+        let expected = record.clone();
+        for requested in ["OpenAI.Codex_publisher", "OPENAI.CODEX_PUBLISHER"] {
+            record.admit_owner(&record.clone(), requested).unwrap();
+            assert_eq!(record, expected);
+        }
+    }
+}
+
+#[test]
+fn admission_rejects_other_owner_home_and_family() {
+    let record = record();
+    let expected = record.clone();
+    for (home, sid, family) in [
+        (
+            record.codex_home.as_path(),
+            "S-1-5-21-1-2-3-2000",
+            record.runtime().unwrap().package_family.as_str(),
+        ),
+        (
+            std::path::Path::new(r"C:\Users\owner\other"),
+            record.user_sid.as_str(),
+            record.runtime().unwrap().package_family.as_str(),
+        ),
+        (
+            record.codex_home.as_path(),
+            record.user_sid.as_str(),
+            "OpenAI.CodexBeta_publisher",
+        ),
+        (
+            record.codex_home.as_path(),
+            record.user_sid.as_str(),
+            "OpenAI.Codex_otherpublisher",
+        ),
+    ] {
+        let mut requested = record.clone();
+        requested.codex_home = home.to_path_buf();
+        requested.user_sid = sid.to_owned();
+        assert!(record.admit_owner(&requested, family).is_err());
+        assert_eq!(record, expected);
+    }
+}
+
+#[test]
+fn returned_owner_cannot_cancel_a_persisted_retirement_fence() {
+    let expected = pending();
+    let journal = serde_json::to_string(&expected).unwrap();
+    let restored: InstallationRecord = serde_json::from_str(&journal).unwrap();
+    let returning_owner = record();
+    assert!(
+        restored
+            .admit_owner(
+                &returning_owner,
+                &returning_owner.runtime().unwrap().package_family
+            )
+            .is_err()
+    );
+    assert_eq!(restored, expected);
+}
+
+#[test]
+fn journal_round_trip_retains_desktop_ownership_and_retirement_fence() {
+    for record in [record(), pending()] {
+        let json = serde_json::to_string(&record).unwrap();
+        assert_eq!(
+            serde_json::from_str::<InstallationRecord>(&json).unwrap(),
+            record
+        );
+    }
+}
+
+#[test]
+fn production_record_without_optional_core_or_desktop_fields_still_loads() {
+    let mut expected = record();
+    expected.runtime = None;
+    expected.desktop_installation = None;
+    let json = r#"{"user_sid":"S-1-5-21-1-2-3-1000","codex_home":"C:\\Users\\owner\\.codex","session_id":1}"#;
+    assert_eq!(
+        serde_json::from_str::<InstallationRecord>(json).unwrap(),
+        expected
+    );
+}
+
+#[test]
+fn metadata_root_history_survives_record_round_trip() {
+    let mut expected = record();
+    expected.runtime_mut().unwrap().metadata_roots = vec![
+        PathBuf::from(r"C:\Users\owner\AppData\Roaming"),
+        PathBuf::from(r"D:\Redirected\Roaming"),
+    ];
+    for record in [expected.clone(), {
+        let mut updated = expected;
+        updated.runtime_mut().unwrap().ready_package = Some(READY_PACKAGE.into());
+        updated
+    }] {
+        let json = serde_json::to_string(&record).unwrap();
+        assert_eq!(
+            serde_json::from_str::<InstallationRecord>(&json).unwrap(),
+            record
+        );
+    }
+}
+
+#[test]
+fn older_runtime_receipts_default_to_no_recorded_metadata_roots() {
+    let expected = record();
+    let json = serde_json::to_value(&expected).unwrap();
+    assert!(json["runtime"].get("metadata_roots").is_none());
+    assert_eq!(
+        serde_json::from_value::<InstallationRecord>(json).unwrap(),
+        expected
+    );
+}
+
+#[test]
+fn legacy_null_cleanup_alias_preserves_the_active_record() {
+    let expected = record();
+    let mut json = serde_json::to_value(&expected).unwrap();
+    let runtime = json["runtime"].as_object_mut().unwrap();
+    runtime.remove("retiring");
+    runtime.insert("cleanup".into(), serde_json::Value::Null);
+
+    assert_eq!(
+        serde_json::from_value::<InstallationRecord>(json).unwrap(),
+        expected
+    );
+}
+
+#[test]
+fn legacy_non_null_cleanup_journal_cannot_silently_drop_its_fence() {
+    for stage in ["native_started", "native_complete"] {
+        let mut json = serde_json::to_value(record()).unwrap();
+        let runtime = json["runtime"].as_object_mut().unwrap();
+        runtime.remove("retiring");
+        let accounts = runtime["accounts"].clone();
+        runtime.insert(
+            "cleanup".into(),
+            serde_json::json!({
+                "id": "one-cleanup-generation",
+                "stage": stage,
+                "accounts": accounts,
+            }),
+        );
+
+        assert!(serde_json::from_value::<InstallationRecord>(json).is_err());
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/sandbox_utils.rs b/codex-rs/windows-sandbox-rs/src/sandbox_utils.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1dfd7683021065d8e2899ce589b3f55c8999aebb
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/sandbox_utils.rs
@@ -0,0 +1,119 @@
+//! Shared helper utilities for Windows sandbox setup.
+//!
+//! These helpers centralize small pieces of setup logic used across both legacy and
+//! elevated paths, including unified_exec sessions and capture flows. They cover
+//! codex home directory creation and git safe.directory injection so sandboxed
+//! users can run git inside a repo owned by the primary user.
+
+use anyhow::Result;
+use std::collections::HashMap;
+use std::path::Path;
+
+/// Walk upward from `start` to locate the git worktree root for `safe.directory`.
+fn find_git_worktree_root_for_safe_directory(start: &Path) -> Option<std::path::PathBuf> {
+    let mut cur = dunce::canonicalize(start).ok()?;
+    loop {
+        if cur.join(".git").exists() {
+            return Some(cur);
+        }
+        let parent = cur.parent()?;
+        if parent == cur {
+            return None;
+        }
+        cur = parent.to_path_buf();
+    }
+}
+
+/// Ensure the sandbox codex home directory exists.
+pub fn ensure_codex_home_exists(p: &Path) -> Result<()> {
+    std::fs::create_dir_all(p)?;
+    Ok(())
+}
+
+/// Adds git safe.directory entries for the repository and nested repositories.
+/// git will not otherwise allow the Sandbox user to run git commands on repositories
+/// which are owned by the primary user.
+pub fn inject_git_safe_directory(env_map: &mut HashMap<String, String>, cwd: &Path) {
+    if let Some(git_root) = find_git_worktree_root_for_safe_directory(cwd) {
+        let mut cfg_count: usize = env_map
+            .get("GIT_CONFIG_COUNT")
+            .and_then(|v| v.parse::<usize>().ok())
+            .unwrap_or(0);
+        let git_path = git_root.to_string_lossy().replace("\\\\", "/");
+        let nested_git_path = format!("{git_path}/*");
+        for git_path in [git_path, nested_git_path] {
+            env_map.insert(
+                format!("GIT_CONFIG_KEY_{cfg_count}"),
+                "safe.directory".to_string(),
+            );
+            env_map.insert(format!("GIT_CONFIG_VALUE_{cfg_count}"), git_path);
+            cfg_count += 1;
+        }
+        env_map.insert("GIT_CONFIG_COUNT".to_string(), cfg_count.to_string());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::inject_git_safe_directory;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashMap;
+    use std::fs;
+    use std::path::Path;
+    use tempfile::TempDir;
+
+    fn safe_directory_value(path: &Path) -> String {
+        dunce::canonicalize(path)
+            .expect("canonicalize path")
+            .to_string_lossy()
+            .replace("\\\\", "/")
+    }
+
+    #[test]
+    fn injects_safe_directory_for_git_directory() {
+        let temp = TempDir::new().expect("tempdir");
+        let repo = temp.path().join("repo");
+        let nested = repo.join("nested");
+        fs::create_dir_all(repo.join(".git")).expect("create .git");
+        fs::create_dir_all(&nested).expect("create nested dir");
+
+        let mut env_map = HashMap::new();
+        inject_git_safe_directory(&mut env_map, &nested);
+
+        let git_path = safe_directory_value(&repo);
+        let expected = HashMap::from([
+            ("GIT_CONFIG_COUNT".to_string(), "2".to_string()),
+            ("GIT_CONFIG_KEY_0".to_string(), "safe.directory".to_string()),
+            ("GIT_CONFIG_VALUE_0".to_string(), git_path.clone()),
+            ("GIT_CONFIG_KEY_1".to_string(), "safe.directory".to_string()),
+            ("GIT_CONFIG_VALUE_1".to_string(), format!("{git_path}/*")),
+        ]);
+        assert_eq!(env_map, expected);
+    }
+
+    #[test]
+    fn injects_worktree_root_for_gitfile() {
+        let temp = TempDir::new().expect("tempdir");
+        let repo = temp.path().join("repo");
+        let nested = repo.join("nested");
+        fs::create_dir_all(&nested).expect("create nested dir");
+        fs::write(
+            repo.join(".git"),
+            "gitdir: C:/Users/example/repo/.git/worktrees/codex3\n",
+        )
+        .expect("write .git file");
+
+        let mut env_map = HashMap::new();
+        inject_git_safe_directory(&mut env_map, &nested);
+
+        let git_path = safe_directory_value(&repo);
+        let expected = HashMap::from([
+            ("GIT_CONFIG_COUNT".to_string(), "2".to_string()),
+            ("GIT_CONFIG_KEY_0".to_string(), "safe.directory".to_string()),
+            ("GIT_CONFIG_VALUE_0".to_string(), git_path.clone()),
+            ("GIT_CONFIG_KEY_1".to_string(), "safe.directory".to_string()),
+            ("GIT_CONFIG_VALUE_1".to_string(), format!("{git_path}/*")),
+        ]);
+        assert_eq!(env_map, expected);
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/service_identity.rs b/codex-rs/windows-sandbox-rs/src/service_identity.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ce60848d136456d60ffae13d61c2e9e2573e1dba
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/service_identity.rs
@@ -0,0 +1,67 @@
+//! Keep each packaged channel's service and pipe separate while accounts remain shared.
+//! An unpackaged client may use a routing hint; service admission still verifies OS identity.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+
+use crate::package_identity::process_package_family;
+
+/// SCM name matching the packaged application's manifest. Unpackaged callers keep
+/// the legacy service lookup and may use ordinary elevated setup when it is absent.
+pub fn windows_sandbox_service_name() -> Result<String> {
+    let Some(family) = service_package_family()? else {
+        return Ok("CodexSandboxService".into());
+    };
+    let (name, _) = family.rsplit_once('_').context("invalid package family")?;
+    Ok(format!("CodexSandboxService.{name}"))
+}
+
+/// The full family, including publisher identity, qualifies the authenticated pipe.
+pub fn windows_sandbox_service_pipe_name() -> Result<String> {
+    Ok(match service_package_family()? {
+        Some(family) => format!("{}.{}", crate::SANDBOX_PROVISIONING_PIPE_NAME, family),
+        None => crate::SANDBOX_PROVISIONING_PIPE_NAME.into(),
+    })
+}
+
+pub(crate) fn current_family() -> Result<Option<String>> {
+    unsafe { process_package_family(GetCurrentProcess()) }
+}
+
+fn service_package_family() -> Result<Option<String>> {
+    if let Some(family) = current_family()? {
+        return Ok(Some(family));
+    }
+    let Some(hint) = std::env::var_os("CODEX_WINDOWS_SANDBOX_PACKAGE_FAMILY") else {
+        return Ok(None);
+    };
+    let family = hint
+        .to_str()
+        .context("service package family is not UTF-8")?;
+    validate_service_family_hint(family)?;
+    // Lookup only: SCM/pipe verification and registered-client admission use OS identity.
+    Ok(Some(family.to_owned()))
+}
+
+fn validate_service_family_hint(family: &str) -> Result<()> {
+    let (name, publisher) = family
+        .rsplit_once('_')
+        .context("invalid service package family")?;
+    ensure!(
+        !name.is_empty()
+            && name.len() <= 50
+            && name
+                .bytes()
+                .all(|c| c.is_ascii_alphanumeric() || matches!(c, b'.' | b'-'))
+            && publisher.len() == 13
+            && publisher.bytes().all(|c| c.is_ascii_alphanumeric()),
+        "invalid service package family"
+    );
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "service_identity_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/service_identity_tests.rs b/codex-rs/windows-sandbox-rs/src/service_identity_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..358057ea0a5feceb9472a2022cec7eb771f5399a
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/service_identity_tests.rs
@@ -0,0 +1,26 @@
+use super::validate_service_family_hint;
+
+#[test]
+fn service_routing_accepts_package_families() {
+    for family in [
+        "OpenAI.Codex_3k8sg7r9htsxt",
+        "OpenAI.CodexBeta_jabp31b5fhs74",
+    ] {
+        assert!(validate_service_family_hint(family).is_ok());
+    }
+}
+
+#[test]
+fn service_routing_rejects_paths_and_malformed_families() {
+    for family in [
+        "",
+        "_3k8sg7r9htsxt",
+        "OpenAI.Codex_bad",
+        "OpenAI.Codex_3k8sg7r9htsxt\\child",
+        "..\\OpenAI.Codex_3k8sg7r9htsxt",
+        "OpenAI.Codex_extra_3k8sg7r9htsxt",
+        "OpenAI.Codex\0_3k8sg7r9htsxt",
+    ] {
+        assert!(validate_service_family_hint(family).is_err(), "{family:?}");
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup.rs b/codex-rs/windows-sandbox-rs/src/setup.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ad9ed0dcd334c8beec4355857100c37c9ab8249c
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup.rs
@@ -0,0 +1,2741 @@
+pub use crate::runtime_ownership::SetupRuntime;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::BTreeSet;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::ffi::c_void;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::process::CommandExt;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command;
+use std::process::Stdio;
+use std::sync::Arc;
+use std::sync::Condvar;
+use std::sync::Mutex;
+use std::sync::OnceLock;
+
+use crate::allow::AllowDenyPaths;
+use crate::allow::compute_allow_paths_for_permissions;
+use crate::app_package::registered_core_requested;
+use crate::deny_read_resolver::resolve_windows_deny_read_paths;
+use crate::helper_materialization::bundled_executable_path_for_exe;
+use crate::helper_materialization::helper_bin_dir;
+use crate::identity::sandbox_setup_is_complete;
+use crate::logging::current_log_file_path;
+use crate::logging::log_note;
+use crate::path_normalization::canonical_path_key;
+use crate::path_normalization::canonicalize_path;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::setup_error::SetupErrorCode;
+use crate::setup_error::SetupFailure;
+use crate::setup_error::clear_setup_error_report;
+use crate::setup_error::extract_failure;
+use crate::setup_error::failure;
+use crate::setup_error::read_setup_error_report;
+use crate::ssh_config_dependencies::ssh_config_dependency_paths;
+use anyhow::Result;
+use anyhow::anyhow;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Security::AllocateAndInitializeSid;
+use windows_sys::Win32::Security::CheckTokenMembership;
+use windows_sys::Win32::Security::FreeSid;
+use windows_sys::Win32::Security::SECURITY_NT_AUTHORITY;
+
+pub const SETUP_VERSION: u32 = 5;
+pub const OFFLINE_USERNAME: &str = "CodexSandboxOffline";
+pub const ONLINE_USERNAME: &str = "CodexSandboxOnline";
+const ERROR_CANCELLED: u32 = 1223;
+const SECURITY_BUILTIN_DOMAIN_RID: u32 = 0x0000_0020;
+const DOMAIN_ALIAS_RID_ADMINS: u32 = 0x0000_0220;
+const SETUP_EXE_FILENAME: &str = "codex-windows-sandbox-setup.exe";
+const USERPROFILE_ROOT_EXCLUSIONS: &[&str] = &[
+    ".ssh",
+    ".tsh",
+    ".brev",
+    ".gnupg",
+    ".aws",
+    ".azure",
+    ".kube",
+    ".docker",
+    ".config",
+    ".npm",
+    ".pki",
+    ".terraform.d",
+];
+const WINDOWS_PLATFORM_DEFAULT_READ_ROOTS: &[&str] = &[
+    r"C:\Windows",
+    r"C:\Program Files",
+    r"C:\Program Files (x86)",
+    r"C:\ProgramData",
+];
+
+#[derive(Clone)]
+struct SharedSetupError {
+    code: Option<SetupErrorCode>,
+    message: String,
+}
+
+impl SharedSetupError {
+    fn from_error(error: &anyhow::Error) -> Self {
+        match extract_failure(error) {
+            Some(failure) => Self {
+                code: Some(failure.code),
+                message: failure.message.clone(),
+            },
+            None => Self {
+                code: None,
+                message: format!("{error:#}"),
+            },
+        }
+    }
+
+    fn into_error(self) -> anyhow::Error {
+        match self.code {
+            Some(code) => failure(code, self.message),
+            None => anyhow!(self.message),
+        }
+    }
+}
+
+struct SetupFlight {
+    result: Mutex<Option<Result<(), SharedSetupError>>>,
+    completed: Condvar,
+}
+
+impl SetupFlight {
+    fn pending() -> Self {
+        Self {
+            result: Mutex::new(None),
+            completed: Condvar::new(),
+        }
+    }
+
+    fn complete(&self, result: Result<(), SharedSetupError>) {
+        *self
+            .result
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(result);
+        self.completed.notify_all();
+    }
+
+    fn wait(&self) -> Result<()> {
+        let mut result = self
+            .result
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        while result.is_none() {
+            result = self
+                .completed
+                .wait(result)
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+        }
+        match result.clone() {
+            Some(result) => result.map_err(SharedSetupError::into_error),
+            None => Err(anyhow!("setup flight completed without a result")),
+        }
+    }
+}
+
+static SETUP_FLIGHTS: OnceLock<Mutex<HashMap<String, Arc<SetupFlight>>>> = OnceLock::new();
+
+fn run_setup_singleflight(key: String, run: impl FnOnce() -> Result<()>) -> Result<()> {
+    let flights = SETUP_FLIGHTS.get_or_init(|| Mutex::new(HashMap::new()));
+    let (flight, is_leader) = {
+        let mut flights = flights
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        match flights.get(&key) {
+            Some(flight) => (Arc::clone(flight), false),
+            None => {
+                let flight = Arc::new(SetupFlight::pending());
+                flights.insert(key.clone(), Arc::clone(&flight));
+                (flight, true)
+            }
+        }
+    };
+
+    if !is_leader {
+        return flight.wait();
+    }
+
+    let result = run();
+    let shared_result = match &result {
+        Ok(()) => Ok(()),
+        Err(error) => Err(SharedSetupError::from_error(error)),
+    };
+    flight.complete(shared_result);
+    let mut flights = flights
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
+    if flights
+        .get(&key)
+        .is_some_and(|current| Arc::ptr_eq(current, &flight))
+    {
+        flights.remove(&key);
+    }
+    result
+}
+
+pub fn sandbox_dir(codex_home: &Path) -> PathBuf {
+    codex_home.join(".sandbox")
+}
+
+pub fn sandbox_bin_dir(codex_home: &Path) -> PathBuf {
+    codex_home.join(".sandbox-bin")
+}
+
+pub fn sandbox_secrets_dir(codex_home: &Path) -> PathBuf {
+    codex_home.join(".sandbox-secrets")
+}
+
+pub fn setup_marker_path(codex_home: &Path) -> PathBuf {
+    sandbox_dir(codex_home).join("setup_marker.json")
+}
+
+pub fn sandbox_users_path(codex_home: &Path) -> PathBuf {
+    sandbox_secrets_dir(codex_home).join("sandbox_users.json")
+}
+
+pub struct SandboxSetupRequest<'a> {
+    pub permissions: &'a ResolvedWindowsSandboxPermissions,
+    pub command_cwd: &'a Path,
+    pub env_map: &'a HashMap<String, String>,
+    pub codex_home: &'a Path,
+    pub proxy_enforced: bool,
+}
+
+#[derive(Default)]
+pub struct SetupRootOverrides {
+    pub read_roots: Option<Vec<PathBuf>>,
+    pub read_roots_include_platform_defaults: bool,
+    pub write_roots: Option<Vec<PathBuf>>,
+    pub deny_read_paths: Option<Vec<PathBuf>>,
+    pub deny_write_paths: Option<Vec<PathBuf>>,
+}
+
+pub fn run_setup_refresh(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    proxy_enforced: bool,
+) -> Result<()> {
+    let Ok(permissions) =
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        )
+    else {
+        return Ok(());
+    };
+    permissions.validate_elevated_filesystem_policy(command_cwd)?;
+    let deny_read_paths =
+        setup_refresh_deny_read_paths(permission_profile, workspace_roots, command_cwd)?;
+    run_setup_refresh_inner(
+        SandboxSetupRequest {
+            permissions: &permissions,
+            command_cwd,
+            env_map,
+            codex_home,
+            proxy_enforced,
+        },
+        SetupRootOverrides {
+            deny_read_paths: Some(deny_read_paths),
+            ..SetupRootOverrides::default()
+        },
+        /*offline_proxy_settings_override*/ None,
+        current_setup_runtime(),
+    )
+}
+
+pub(crate) fn run_setup_refresh_with_overrides_and_proxy_settings(
+    request: SandboxSetupRequest<'_>,
+    overrides: SetupRootOverrides,
+    offline_proxy_settings: &OfflineProxySettings,
+) -> Result<()> {
+    run_setup_refresh_inner(
+        request,
+        overrides,
+        Some(offline_proxy_settings),
+        current_setup_runtime(),
+    )
+}
+
+pub fn run_setup_refresh_with_extra_read_roots(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    extra_read_roots: Vec<PathBuf>,
+    proxy_enforced: bool,
+) -> Result<()> {
+    let Ok(permissions) =
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        )
+    else {
+        return Ok(());
+    };
+    permissions.validate_elevated_filesystem_policy(command_cwd)?;
+    let deny_read_paths =
+        setup_refresh_deny_read_paths(permission_profile, workspace_roots, command_cwd)?;
+    let runtime = current_setup_runtime();
+    let mut read_roots = gather_read_roots(command_cwd, &permissions, env_map, codex_home, runtime);
+    read_roots.extend(extra_read_roots);
+    run_setup_refresh_inner(
+        SandboxSetupRequest {
+            permissions: &permissions,
+            command_cwd,
+            env_map,
+            codex_home,
+            proxy_enforced,
+        },
+        SetupRootOverrides {
+            read_roots: Some(read_roots),
+            read_roots_include_platform_defaults: false,
+            write_roots: Some(Vec::new()),
+            deny_read_paths: Some(deny_read_paths),
+            deny_write_paths: None,
+        },
+        /*offline_proxy_settings_override*/ None,
+        runtime,
+    )
+}
+
+fn setup_refresh_deny_read_paths(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    command_cwd: &Path,
+) -> Result<Vec<PathBuf>> {
+    let (mut file_system, _) = permission_profile.to_runtime_permissions();
+    file_system.remove_skip_missing_path_entries();
+    let file_system = file_system.materialize_project_roots_with_workspace_roots(workspace_roots);
+    let command_cwd = AbsolutePathBuf::from_absolute_path(command_cwd)?;
+    resolve_windows_deny_read_paths(&file_system, &command_cwd)
+        .map(|paths| {
+            paths
+                .into_iter()
+                .map(AbsolutePathBuf::into_path_buf)
+                .collect()
+        })
+        .map_err(|err| anyhow!(err))
+}
+
+fn run_setup_refresh_inner(
+    request: SandboxSetupRequest<'_>,
+    overrides: SetupRootOverrides,
+    offline_proxy_settings_override: Option<&OfflineProxySettings>,
+    runtime: SetupRuntime,
+) -> Result<()> {
+    request
+        .permissions
+        .validate_elevated_filesystem_policy(request.command_cwd)?;
+    let (read_roots, write_roots) = build_payload_roots(&request, &overrides, runtime);
+    let deny_read_paths = build_payload_deny_read_paths(overrides.deny_read_paths);
+    let deny_write_paths = build_payload_deny_write_paths(&request, overrides.deny_write_paths);
+    let offline_proxy_settings =
+        offline_proxy_settings_for_request(&request, offline_proxy_settings_override);
+    let payload = ElevationPayload {
+        version: SETUP_VERSION,
+        offline_username: OFFLINE_USERNAME.to_string(),
+        online_username: ONLINE_USERNAME.to_string(),
+        codex_home: request.codex_home.to_path_buf(),
+        command_cwd: request.command_cwd.to_path_buf(),
+        read_roots,
+        write_roots,
+        deny_read_paths,
+        deny_write_paths,
+        proxy_ports: offline_proxy_settings.proxy_ports,
+        allow_local_binding: offline_proxy_settings.allow_local_binding,
+        otel: None,
+        real_user: crate::runtime_ownership::current_setup_user()?,
+        mode: SetupMode::Full,
+        runtime,
+        refresh_only: true,
+    };
+    let json = serde_json::to_vec(&payload)?;
+    let b64 = BASE64_STANDARD.encode(json);
+    run_setup_singleflight(b64.clone(), || {
+        run_setup_refresh_payload(&b64, request.codex_home)
+    })
+}
+
+fn run_setup_refresh_payload(b64: &str, codex_home: &Path) -> Result<()> {
+    let exe = find_setup_exe();
+    let sbx_dir = sandbox_dir(codex_home);
+    let log_path = current_log_file_path(&sbx_dir);
+    let cleared_report = match clear_setup_error_report(codex_home) {
+        Ok(()) => true,
+        Err(err) => {
+            log_note(
+                &format!("setup refresh: failed to clear setup_error.json before launch: {err}"),
+                Some(&sbx_dir),
+            );
+            false
+        }
+    };
+    // Refresh should never request elevation; ensure verb isn't set and we don't trigger UAC.
+    let mut cmd = Command::new(&exe);
+    cmd.arg(b64)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+    let cwd = std::env::current_dir().unwrap_or_else(|_| codex_home.to_path_buf());
+    log_note(
+        &format!(
+            "setup refresh: spawning {} (cwd={}, payload_len={})",
+            exe.display(),
+            cwd.display(),
+            b64.len()
+        ),
+        Some(&sbx_dir),
+    );
+    let status = cmd.status().map_err(|err| {
+        let message = format!(
+            "setup refresh failed to launch helper: helper={}, cwd={}, log={}, error={err}",
+            exe.display(),
+            cwd.display(),
+            log_path.display()
+        );
+        log_note(&format!("setup refresh: {message}"), Some(&sbx_dir));
+        failure(SetupErrorCode::OrchestratorHelperLaunchFailed, message)
+    })?;
+    if !status.success() {
+        log_note(
+            &format!("setup refresh: exited with status {status:?}"),
+            Some(&sbx_dir),
+        );
+        return Err(report_helper_failure(
+            codex_home,
+            cleared_report,
+            status.code(),
+        ));
+    }
+    if let Err(err) = clear_setup_error_report(codex_home) {
+        log_note(
+            &format!("setup refresh: failed to clear setup_error.json after success: {err}"),
+            Some(&sbx_dir),
+        );
+    }
+    Ok(())
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SetupMarker {
+    pub version: u32,
+    pub offline_username: String,
+    pub online_username: String,
+    #[serde(default)]
+    pub created_at: Option<String>,
+    #[serde(default)]
+    pub proxy_ports: Vec<u16>,
+    #[serde(default)]
+    pub allow_local_binding: bool,
+}
+
+impl SetupMarker {
+    pub fn version_matches(&self) -> bool {
+        self.version == SETUP_VERSION
+    }
+
+    pub(crate) fn offline_proxy_settings(&self) -> OfflineProxySettings {
+        OfflineProxySettings {
+            proxy_ports: self.proxy_ports.clone(),
+            allow_local_binding: self.allow_local_binding,
+        }
+    }
+
+    pub(crate) fn request_mismatch_reason(
+        &self,
+        network_identity: SandboxNetworkIdentity,
+        offline_proxy_settings: &OfflineProxySettings,
+    ) -> Option<String> {
+        if !network_identity.uses_offline_identity() {
+            return None;
+        }
+        // Local-binding mode has no port-specific loopback rules, so changing proxy
+        // listeners does not require a firewall update while that mode stays enabled.
+        if self.allow_local_binding == offline_proxy_settings.allow_local_binding
+            && (self.allow_local_binding || self.proxy_ports == offline_proxy_settings.proxy_ports)
+        {
+            return None;
+        }
+        Some(format!(
+            "offline firewall settings changed (stored_ports={:?}, desired_ports={:?}, stored_allow_local_binding={}, desired_allow_local_binding={})",
+            self.proxy_ports,
+            offline_proxy_settings.proxy_ports,
+            self.allow_local_binding,
+            offline_proxy_settings.allow_local_binding
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SandboxUserRecord {
+    pub username: String,
+    /// DPAPI-encrypted password blob, base64 encoded.
+    pub password: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct SandboxUsersFile {
+    pub version: u32,
+    pub offline: SandboxUserRecord,
+    pub online: SandboxUserRecord,
+}
+
+impl SandboxUsersFile {
+    pub fn version_matches(&self) -> bool {
+        self.version == SETUP_VERSION
+    }
+}
+
+fn is_elevated() -> Result<bool> {
+    unsafe {
+        let mut administrators_group: *mut c_void = std::ptr::null_mut();
+        let ok = AllocateAndInitializeSid(
+            &SECURITY_NT_AUTHORITY,
+            2,
+            SECURITY_BUILTIN_DOMAIN_RID,
+            DOMAIN_ALIAS_RID_ADMINS,
+            0,
+            0,
+            0,
+            0,
+            0,
+            0,
+            &mut administrators_group,
+        );
+        if ok == 0 {
+            return Err(anyhow!(
+                "AllocateAndInitializeSid failed: {}",
+                GetLastError()
+            ));
+        }
+        let mut is_member = 0i32;
+        let check = CheckTokenMembership(0, administrators_group, &mut is_member as *mut _);
+        FreeSid(administrators_group as *mut _);
+        if check == 0 {
+            return Err(anyhow!("CheckTokenMembership failed: {}", GetLastError()));
+        }
+        Ok(is_member != 0)
+    }
+}
+
+fn canonical_existing(paths: &[PathBuf]) -> Vec<PathBuf> {
+    paths
+        .iter()
+        .filter_map(|p| {
+            if !p.exists() {
+                return None;
+            }
+            Some(dunce::canonicalize(p).unwrap_or_else(|_| p.clone()))
+        })
+        .collect()
+}
+
+fn profile_read_roots(user_profile: &Path) -> Vec<PathBuf> {
+    let entries = match std::fs::read_dir(user_profile) {
+        Ok(entries) => entries,
+        Err(_) => return vec![user_profile.to_path_buf()],
+    };
+
+    entries
+        .filter_map(Result::ok)
+        .map(|entry| (entry.file_name(), entry.path()))
+        .filter(|(name, _)| {
+            let name = name.to_string_lossy();
+            !USERPROFILE_ROOT_EXCLUSIONS
+                .iter()
+                .any(|excluded| name.eq_ignore_ascii_case(excluded))
+        })
+        .map(|(_, path)| path)
+        .collect()
+}
+
+pub(crate) fn current_setup_runtime() -> SetupRuntime {
+    if registered_core_requested() {
+        SetupRuntime::Registered
+    } else {
+        SetupRuntime::Legacy
+    }
+}
+
+fn gather_helper_read_roots(codex_home: &Path, runtime: SetupRuntime) -> Vec<PathBuf> {
+    if runtime == SetupRuntime::Registered {
+        return Vec::new();
+    }
+    let helper_dir = helper_bin_dir(codex_home);
+    let _ = std::fs::create_dir_all(&helper_dir);
+    vec![helper_dir]
+}
+
+fn gather_full_read_roots_for_permissions(
+    command_cwd: &Path,
+    permissions: &ResolvedWindowsSandboxPermissions,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    runtime: SetupRuntime,
+) -> Vec<PathBuf> {
+    let mut roots = gather_helper_read_roots(codex_home, runtime);
+    roots.extend(
+        WINDOWS_PLATFORM_DEFAULT_READ_ROOTS
+            .iter()
+            .map(PathBuf::from),
+    );
+    if let Ok(up) = std::env::var("USERPROFILE") {
+        roots.extend(profile_read_roots(Path::new(&up)));
+    }
+    roots.push(command_cwd.to_path_buf());
+    roots.extend(
+        permissions
+            .writable_roots_for_cwd(command_cwd, env_map)
+            .into_iter()
+            .map(|root| root.root),
+    );
+    roots.extend(
+        permissions
+            .readable_roots_for_cwd(command_cwd)
+            .into_iter()
+            .filter(|root| root.parent().is_some() || !command_cwd.starts_with(root)),
+    );
+    canonical_existing(&roots)
+}
+
+pub(crate) fn gather_read_roots(
+    command_cwd: &Path,
+    permissions: &ResolvedWindowsSandboxPermissions,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    runtime: SetupRuntime,
+) -> Vec<PathBuf> {
+    if permissions.has_symbolic_root_read_access(command_cwd) {
+        return gather_full_read_roots_for_permissions(
+            command_cwd,
+            permissions,
+            env_map,
+            codex_home,
+            runtime,
+        );
+    }
+
+    let mut roots = gather_helper_read_roots(codex_home, runtime);
+    if permissions.include_platform_defaults() {
+        roots.extend(
+            WINDOWS_PLATFORM_DEFAULT_READ_ROOTS
+                .iter()
+                .map(PathBuf::from),
+        );
+    }
+    roots.extend(permissions.readable_roots_for_cwd(command_cwd));
+    canonical_existing(&roots)
+}
+
+pub(crate) fn gather_write_roots_for_permissions(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+) -> Vec<PathBuf> {
+    let roots = permissions
+        .writable_roots_for_cwd(command_cwd, env_map)
+        .into_iter()
+        .map(|root| root.root)
+        .collect::<Vec<_>>();
+    let mut dedup: HashSet<PathBuf> = HashSet::new();
+    let mut out: Vec<PathBuf> = Vec::new();
+    for r in canonical_existing(&roots) {
+        if dedup.insert(r.clone()) {
+            out.push(r);
+        }
+    }
+    out
+}
+
+pub(crate) fn effective_write_roots_for_setup(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    write_roots_override: Option<&[PathBuf]>,
+) -> Vec<PathBuf> {
+    effective_write_roots_for_permissions(
+        permissions,
+        command_cwd,
+        env_map,
+        codex_home,
+        write_roots_override,
+    )
+}
+
+pub(crate) fn effective_write_roots_for_permissions(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    command_cwd: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+    write_roots_override: Option<&[PathBuf]>,
+) -> Vec<PathBuf> {
+    let write_roots = if let Some(roots) = write_roots_override {
+        canonical_existing(roots)
+    } else {
+        gather_write_roots_for_permissions(permissions, command_cwd, env_map)
+    };
+    let write_roots = expand_user_profile_root(write_roots);
+    let write_roots = filter_user_profile_root(write_roots);
+    let write_roots = filter_user_profile_root_exclusions(write_roots);
+    let write_roots = filter_ssh_config_dependency_roots(write_roots);
+    filter_sensitive_write_roots(write_roots, codex_home)
+}
+
+#[derive(Serialize)]
+struct ElevationPayload {
+    version: u32,
+    offline_username: String,
+    online_username: String,
+    codex_home: PathBuf,
+    command_cwd: PathBuf,
+    read_roots: Vec<PathBuf>,
+    write_roots: Vec<PathBuf>,
+    #[serde(default)]
+    deny_read_paths: Vec<PathBuf>,
+    #[serde(default)]
+    deny_write_paths: Vec<PathBuf>,
+    proxy_ports: Vec<u16>,
+    #[serde(default)]
+    allow_local_binding: bool,
+    otel: Option<codex_otel::StatsigMetricsSettings>,
+    real_user: String,
+    mode: SetupMode,
+    #[serde(default, skip_serializing_if = "SetupRuntime::is_legacy")]
+    runtime: SetupRuntime,
+    #[serde(default)]
+    refresh_only: bool,
+}
+
+#[derive(Clone, Copy, Serialize)]
+#[serde(rename_all = "kebab-case")]
+enum SetupMode {
+    Full,
+    InteractiveProvision,
+    ProvisionOnly,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct OfflineProxySettings {
+    pub proxy_ports: Vec<u16>,
+    pub allow_local_binding: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum SandboxNetworkIdentity {
+    Offline,
+    Online,
+}
+
+impl SandboxNetworkIdentity {
+    pub(crate) fn from_permissions(
+        permissions: &ResolvedWindowsSandboxPermissions,
+        proxy_enforced: bool,
+    ) -> Self {
+        if proxy_enforced || !permissions.network_policy().is_enabled() {
+            Self::Offline
+        } else {
+            Self::Online
+        }
+    }
+
+    pub(crate) fn uses_offline_identity(self) -> bool {
+        matches!(self, Self::Offline)
+    }
+}
+
+pub(crate) const PROXY_ENV_KEYS: &[&str] = &[
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "WS_PROXY",
+    "WSS_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+    "ws_proxy",
+    "wss_proxy",
+];
+const ALLOW_LOCAL_BINDING_ENV_KEY: &str = "CODEX_NETWORK_ALLOW_LOCAL_BINDING";
+// Internal wire format shared with network-proxy/src/proxy.rs. The value is a comma-separated,
+// sorted list of non-zero loopback proxy ports used only when computing the Windows offline
+// sandbox setup marker.
+const WINDOWS_SANDBOX_PROXY_PORTS_ENV_KEY: &str = "CODEX_WINDOWS_SANDBOX_PROXY_PORTS";
+
+pub(crate) fn offline_proxy_settings_from_env(
+    env_map: &HashMap<String, String>,
+    network_identity: SandboxNetworkIdentity,
+) -> OfflineProxySettings {
+    if !network_identity.uses_offline_identity() {
+        return OfflineProxySettings {
+            proxy_ports: vec![],
+            allow_local_binding: false,
+        };
+    }
+    OfflineProxySettings {
+        proxy_ports: proxy_ports_from_env(env_map),
+        allow_local_binding: env_map
+            .get(ALLOW_LOCAL_BINDING_ENV_KEY)
+            .is_some_and(|value| value == "1"),
+    }
+}
+
+fn offline_proxy_settings_for_request(
+    request: &SandboxSetupRequest<'_>,
+    offline_proxy_settings_override: Option<&OfflineProxySettings>,
+) -> OfflineProxySettings {
+    offline_proxy_settings_override.cloned().unwrap_or_else(|| {
+        let network_identity =
+            SandboxNetworkIdentity::from_permissions(request.permissions, request.proxy_enforced);
+        offline_proxy_settings_from_env(request.env_map, network_identity)
+    })
+}
+
+pub(crate) fn proxy_ports_from_env(env_map: &HashMap<String, String>) -> Vec<u16> {
+    let mut ports = BTreeSet::new();
+    for key in PROXY_ENV_KEYS {
+        if let Some(value) = env_map.get(*key)
+            && let Some(port) = loopback_proxy_port_from_url(value)
+        {
+            ports.insert(port);
+        }
+    }
+    if let Some(value) = env_map.get(WINDOWS_SANDBOX_PROXY_PORTS_ENV_KEY) {
+        ports.extend(
+            value
+                .split(',')
+                .filter_map(|port| port.trim().parse::<u16>().ok())
+                .filter(|port| *port != 0),
+        );
+    }
+    ports.into_iter().collect()
+}
+
+pub(crate) fn loopback_proxy_port_from_url(url: &str) -> Option<u16> {
+    let authority = url.trim().split_once("://")?.1.split('/').next()?;
+    let host_port = authority.rsplit_once('@').map_or(authority, |(_, hp)| hp);
+
+    if let Some(host) = host_port.strip_prefix('[') {
+        let (host, rest) = host.split_once(']')?;
+        if host != "::1" {
+            return None;
+        }
+        let port = rest.strip_prefix(':')?.parse::<u16>().ok()?;
+        return (port != 0).then_some(port);
+    }
+
+    let (host, port) = host_port.rsplit_once(':')?;
+    if !(host.eq_ignore_ascii_case("localhost") || host == "127.0.0.1") {
+        return None;
+    }
+    let port = port.parse::<u16>().ok()?;
+    (port != 0).then_some(port)
+}
+
+fn quote_arg(arg: &str) -> String {
+    let needs = arg.is_empty()
+        || arg
+            .chars()
+            .any(|c| matches!(c, ' ' | '\t' | '\n' | '\r' | '"'));
+    if !needs {
+        return arg.to_string();
+    }
+    let mut out = String::from("\"");
+    let mut bs = 0;
+    for ch in arg.chars() {
+        match ch {
+            '\\' => {
+                bs += 1;
+            }
+            '"' => {
+                out.push_str(&"\\".repeat(bs * 2 + 1));
+                out.push('"');
+                bs = 0;
+            }
+            _ => {
+                if bs > 0 {
+                    out.push_str(&"\\".repeat(bs));
+                    bs = 0;
+                }
+                out.push(ch);
+            }
+        }
+    }
+    if bs > 0 {
+        out.push_str(&"\\".repeat(bs * 2));
+    }
+    out.push('"');
+    out
+}
+
+fn find_setup_exe() -> PathBuf {
+    if let Ok(exe) = std::env::current_exe()
+        && let Some(setup_exe) = find_setup_exe_for_current_exe(&exe)
+    {
+        return setup_exe;
+    }
+    PathBuf::from(SETUP_EXE_FILENAME)
+}
+
+fn find_setup_exe_for_current_exe(exe: &Path) -> Option<PathBuf> {
+    bundled_executable_path_for_exe(exe, SETUP_EXE_FILENAME)
+}
+
+fn report_helper_failure(
+    codex_home: &Path,
+    cleared_report: bool,
+    exit_code: Option<i32>,
+) -> anyhow::Error {
+    let exit_detail = format!("setup helper exited with status {exit_code:?}");
+    if !cleared_report {
+        return failure(SetupErrorCode::OrchestratorHelperExitNonzero, exit_detail);
+    }
+    match read_setup_error_report(codex_home) {
+        Ok(Some(report)) => anyhow::Error::new(SetupFailure::from_report(report)),
+        Ok(None) => failure(SetupErrorCode::OrchestratorHelperExitNonzero, exit_detail),
+        Err(err) => failure(
+            SetupErrorCode::OrchestratorHelperReportReadFailed,
+            format!("{exit_detail}; failed to read setup_error.json: {err}"),
+        ),
+    }
+}
+
+fn verify_setup_completed(codex_home: &Path) -> Result<()> {
+    if sandbox_setup_is_complete(codex_home) {
+        Ok(())
+    } else {
+        Err(failure(
+            SetupErrorCode::OrchestratorHelperIncomplete,
+            "setup helper exited successfully before setup completed",
+        ))
+    }
+}
+
+fn run_setup_exe(
+    payload: &ElevationPayload,
+    needs_elevation: bool,
+    codex_home: &Path,
+    retained_handles: &[BorrowedHandle<'_>],
+) -> Result<()> {
+    let payload_json = serde_json::to_string(payload).map_err(|err| {
+        failure(
+            SetupErrorCode::OrchestratorPayloadSerializeFailed,
+            format!("failed to serialize elevation payload: {err}"),
+        )
+    })?;
+    let payload_b64 = BASE64_STANDARD.encode(payload_json.as_bytes());
+    if !retained_handles.is_empty() {
+        // Service requests are serialized and must not join a bare setup flight
+        // whose helper was started without these directory protections.
+        return run_setup_exe_payload(&payload_b64, needs_elevation, codex_home, retained_handles);
+    }
+    run_setup_singleflight(payload_b64.clone(), || {
+        run_setup_exe_payload(&payload_b64, needs_elevation, codex_home, retained_handles)
+    })
+}
+
+fn run_setup_exe_payload(
+    payload_b64: &str,
+    needs_elevation: bool,
+    codex_home: &Path,
+    retained_handles: &[BorrowedHandle<'_>],
+) -> Result<()> {
+    use windows_sys::Win32::System::Threading::GetExitCodeProcess;
+    use windows_sys::Win32::System::Threading::INFINITE;
+    use windows_sys::Win32::System::Threading::WaitForSingleObject;
+    use windows_sys::Win32::UI::Shell::SEE_MASK_NOASYNC;
+    use windows_sys::Win32::UI::Shell::SEE_MASK_NOCLOSEPROCESS;
+    use windows_sys::Win32::UI::Shell::SHELLEXECUTEINFOW;
+    use windows_sys::Win32::UI::Shell::ShellExecuteExW;
+    let exe = find_setup_exe();
+    let cleared_report = match clear_setup_error_report(codex_home) {
+        Ok(()) => true,
+        Err(err) => {
+            log_note(
+                &format!(
+                    "setup orchestrator: failed to clear setup_error.json before launch: {err}"
+                ),
+                Some(&sandbox_dir(codex_home)),
+            );
+            false
+        }
+    };
+
+    if !needs_elevation {
+        let status = if retained_handles.is_empty() {
+            Command::new(&exe)
+                .arg(payload_b64)
+                .creation_flags(0x08000000) // CREATE_NO_WINDOW
+                .stdin(Stdio::null())
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .status()
+        } else {
+            let mut command = Command::new(&exe);
+            command.arg(payload_b64);
+            crate::setup_launch::spawn_with_retained_handles(&mut command, retained_handles)
+                .and_then(|mut child| child.wait())
+        }
+        .map_err(|err| {
+            failure(
+                SetupErrorCode::OrchestratorHelperLaunchFailed,
+                format!("failed to launch setup helper (non-elevated): {err}"),
+            )
+        })?;
+        if !status.success() {
+            return Err(report_helper_failure(
+                codex_home,
+                cleared_report,
+                status.code(),
+            ));
+        }
+        verify_setup_completed(codex_home)?;
+        if let Err(err) = clear_setup_error_report(codex_home) {
+            log_note(
+                &format!(
+                    "setup orchestrator: failed to clear setup_error.json after success: {err}"
+                ),
+                Some(&sandbox_dir(codex_home)),
+            );
+        }
+        return Ok(());
+    }
+
+    let exe_w = crate::winutil::to_wide(&exe);
+    let params = quote_arg(payload_b64);
+    let params_w = crate::winutil::to_wide(params);
+    let verb_w = crate::winutil::to_wide("runas");
+    let mut sei: SHELLEXECUTEINFOW = unsafe { std::mem::zeroed() };
+    sei.cbSize = std::mem::size_of::<SHELLEXECUTEINFOW>() as u32;
+    // Sandbox setup runs on a Tokio worker without a Windows message loop.
+    // ShellExecuteEx requires synchronous activation on such threads.
+    sei.fMask = SEE_MASK_NOCLOSEPROCESS | SEE_MASK_NOASYNC;
+    sei.lpVerb = verb_w.as_ptr();
+    sei.lpFile = exe_w.as_ptr();
+    sei.lpParameters = params_w.as_ptr();
+    // Hide the window for the elevated helper.
+    sei.nShow = 0; // SW_HIDE
+    let ok = unsafe { ShellExecuteExW(&mut sei) };
+    if ok == 0 || sei.hProcess == 0 {
+        let last_error = unsafe { GetLastError() };
+        let code = if last_error == ERROR_CANCELLED {
+            SetupErrorCode::OrchestratorHelperLaunchCanceled
+        } else {
+            SetupErrorCode::OrchestratorHelperLaunchFailed
+        };
+        return Err(failure(
+            code,
+            format!("ShellExecuteExW failed to launch setup helper: {last_error}"),
+        ));
+    }
+    unsafe {
+        WaitForSingleObject(sei.hProcess, INFINITE);
+        let mut code: u32 = 1;
+        GetExitCodeProcess(sei.hProcess, &mut code);
+        CloseHandle(sei.hProcess);
+        if code != 0 {
+            return Err(report_helper_failure(
+                codex_home,
+                cleared_report,
+                Some(code as i32),
+            ));
+        }
+    }
+    verify_setup_completed(codex_home)?;
+    if let Err(err) = clear_setup_error_report(codex_home) {
+        log_note(
+            &format!("setup orchestrator: failed to clear setup_error.json after success: {err}"),
+            Some(&sandbox_dir(codex_home)),
+        );
+    }
+    Ok(())
+}
+
+pub fn run_elevated_setup(request: SandboxSetupRequest<'_>) -> Result<()> {
+    run_elevated_setup_inner(request, /*offline_proxy_settings_override*/ None)
+}
+
+pub(crate) fn run_elevated_setup_with_proxy_settings(
+    request: SandboxSetupRequest<'_>,
+    offline_proxy_settings: &OfflineProxySettings,
+) -> Result<()> {
+    if registered_core_requested() {
+        request
+            .permissions
+            .validate_elevated_filesystem_policy(request.command_cwd)?;
+        // Reconcile the effective command settings through the same authenticated service as setup.
+        // A filtered shell environment may differ from the app's startup environment.
+        let settings = crate::WindowsSandboxProvisioningSettings {
+            proxy_ports: offline_proxy_settings.proxy_ports.clone(),
+            allow_local_binding: offline_proxy_settings.allow_local_binding,
+        };
+        let mut listeners =
+            crate::WindowsSandboxProxyListeners::from_proxy_environment(request.env_map);
+        listeners
+            .http_ports
+            .retain(|port| settings.proxy_ports.contains(port));
+        listeners
+            .socks_ports
+            .retain(|port| settings.proxy_ports.contains(port));
+        let outcome = crate::provisioning_client::provision_windows_sandbox_via_service(
+            request.codex_home,
+            settings,
+            listeners,
+        )?;
+        anyhow::ensure!(
+            outcome == crate::WindowsSandboxProvisioningOutcome::Provisioned,
+            "registered Core reconciliation requires the sandbox service"
+        );
+        return Ok(());
+    }
+    run_elevated_setup_inner(request, Some(offline_proxy_settings))
+}
+
+fn run_elevated_setup_inner(
+    request: SandboxSetupRequest<'_>,
+    offline_proxy_settings_override: Option<&OfflineProxySettings>,
+) -> Result<()> {
+    anyhow::ensure!(
+        !registered_core_requested(),
+        "registered Core requires the sandbox service; retry service setup"
+    );
+    request
+        .permissions
+        .validate_elevated_filesystem_policy(request.command_cwd)?;
+    // Ensure the shared sandbox directory exists before we send it to the elevated helper.
+    let sbx_dir = sandbox_dir(request.codex_home);
+    std::fs::create_dir_all(&sbx_dir).map_err(|err| {
+        failure(
+            SetupErrorCode::OrchestratorSandboxDirCreateFailed,
+            format!("failed to create sandbox dir {}: {err}", sbx_dir.display()),
+        )
+    })?;
+    let payload = elevated_provisioning_payload(
+        &request,
+        offline_proxy_settings_override,
+        crate::runtime_ownership::current_setup_user()?,
+    );
+    let needs_elevation = !is_elevated().map_err(|err| {
+        failure(
+            SetupErrorCode::OrchestratorElevationCheckFailed,
+            format!("failed to determine elevation state: {err}"),
+        )
+    })?;
+    run_setup_exe(&payload, needs_elevation, request.codex_home, &[])
+}
+
+fn elevated_provisioning_payload(
+    request: &SandboxSetupRequest<'_>,
+    offline_proxy_settings_override: Option<&OfflineProxySettings>,
+    real_user: String,
+) -> ElevationPayload {
+    let offline_proxy_settings =
+        offline_proxy_settings_for_request(request, offline_proxy_settings_override);
+    ElevationPayload {
+        version: SETUP_VERSION,
+        offline_username: OFFLINE_USERNAME.to_string(),
+        online_username: ONLINE_USERNAME.to_string(),
+        codex_home: request.codex_home.to_path_buf(),
+        command_cwd: request.codex_home.to_path_buf(),
+        read_roots: Vec::new(),
+        write_roots: Vec::new(),
+        deny_read_paths: Vec::new(),
+        deny_write_paths: Vec::new(),
+        proxy_ports: offline_proxy_settings.proxy_ports,
+        allow_local_binding: offline_proxy_settings.allow_local_binding,
+        real_user,
+        otel: codex_otel::global_statsig_metrics_settings(),
+        mode: SetupMode::InteractiveProvision,
+        runtime: SetupRuntime::Legacy,
+        refresh_only: false,
+    }
+}
+
+pub fn run_elevated_provisioning_setup(
+    codex_home: &Path,
+    real_user: &str,
+    settings: crate::WindowsSandboxProvisioningSettings,
+) -> Result<()> {
+    run_elevated_provisioning_setup_with_retained_handles(
+        codex_home,
+        real_user,
+        settings,
+        current_setup_runtime(),
+        &[],
+    )
+}
+
+/// Runs service provisioning with directory protections retained by the helper
+/// itself, so they survive an unexpected exit of the provisioning service.
+/// The runtime must describe the authenticated client, not the shared service image.
+pub fn run_elevated_provisioning_setup_with_retained_handles(
+    codex_home: &Path,
+    real_user: &str,
+    settings: crate::WindowsSandboxProvisioningSettings,
+    runtime: SetupRuntime,
+    retained_handles: &[BorrowedHandle<'_>],
+) -> Result<()> {
+    if !codex_home.is_absolute()
+        || !matches!(
+            codex_home.components().next(),
+            Some(std::path::Component::Prefix(prefix))
+                if matches!(
+                    prefix.kind(),
+                    std::path::Prefix::Disk(_) | std::path::Prefix::VerbatimDisk(_)
+                )
+        )
+    {
+        return Err(failure(
+            SetupErrorCode::OrchestratorSandboxDirCreateFailed,
+            format!(
+                "sandbox provisioning CODEX_HOME must be an absolute local disk path: {}",
+                codex_home.display()
+            ),
+        ));
+    }
+    let sbx_dir = sandbox_dir(codex_home);
+    std::fs::create_dir_all(&sbx_dir).map_err(|err| {
+        failure(
+            SetupErrorCode::OrchestratorSandboxDirCreateFailed,
+            format!("failed to create sandbox dir {}: {err}", sbx_dir.display()),
+        )
+    })?;
+    if !is_elevated().map_err(|err| {
+        failure(
+            SetupErrorCode::OrchestratorElevationCheckFailed,
+            format!("failed to determine elevation state: {err}"),
+        )
+    })? {
+        return Err(failure(
+            SetupErrorCode::OrchestratorElevationRequired,
+            "sandbox provisioning setup must be run from an elevated process",
+        ));
+    }
+    let payload = ElevationPayload {
+        version: SETUP_VERSION,
+        offline_username: OFFLINE_USERNAME.to_string(),
+        online_username: ONLINE_USERNAME.to_string(),
+        codex_home: codex_home.to_path_buf(),
+        command_cwd: codex_home.to_path_buf(),
+        read_roots: Vec::new(),
+        write_roots: Vec::new(),
+        deny_read_paths: Vec::new(),
+        deny_write_paths: Vec::new(),
+        proxy_ports: settings.proxy_ports,
+        allow_local_binding: settings.allow_local_binding,
+        otel: codex_otel::global_statsig_metrics_settings(),
+        real_user: real_user.to_string(),
+        mode: SetupMode::ProvisionOnly,
+        runtime,
+        refresh_only: false,
+    };
+    run_setup_exe(
+        &payload,
+        /*needs_elevation*/ false,
+        codex_home,
+        retained_handles,
+    )
+}
+
+pub(crate) fn build_payload_roots(
+    request: &SandboxSetupRequest<'_>,
+    overrides: &SetupRootOverrides,
+    runtime: SetupRuntime,
+) -> (Vec<PathBuf>, Vec<PathBuf>) {
+    let write_roots = effective_write_roots_for_setup(
+        request.permissions,
+        request.command_cwd,
+        request.env_map,
+        request.codex_home,
+        overrides.write_roots.as_deref(),
+    );
+    let mut read_roots = if let Some(roots) = overrides.read_roots.as_deref() {
+        // An explicit override is the split policy's complete readable set. Keep only the
+        // helper/platform roots the elevated setup needs; do not re-add legacy cwd/full-read roots.
+        let mut read_roots = gather_helper_read_roots(request.codex_home, runtime);
+        if overrides.read_roots_include_platform_defaults {
+            read_roots.extend(
+                WINDOWS_PLATFORM_DEFAULT_READ_ROOTS
+                    .iter()
+                    .map(PathBuf::from),
+            );
+        }
+        read_roots.extend(roots.iter().cloned());
+        canonical_existing(&read_roots)
+    } else {
+        gather_read_roots(
+            request.command_cwd,
+            request.permissions,
+            request.env_map,
+            request.codex_home,
+            runtime,
+        )
+    };
+    read_roots = expand_user_profile_root(read_roots);
+    read_roots = filter_user_profile_root(read_roots);
+    read_roots = filter_user_profile_root_exclusions(read_roots);
+    read_roots = filter_ssh_config_dependency_roots(read_roots);
+    let write_root_set: HashSet<PathBuf> = write_roots.iter().cloned().collect();
+    let deny_read_keys: Vec<String> = overrides
+        .deny_read_paths
+        .as_deref()
+        .unwrap_or_default()
+        .iter()
+        .map(|path| canonical_path_key(path))
+        .collect();
+    read_roots.retain(|root| {
+        if write_root_set.contains(root) {
+            return false;
+        }
+        if deny_read_keys.is_empty() {
+            return true;
+        }
+        let root_key = canonical_path_key(root);
+        !deny_read_keys
+            .iter()
+            .any(|denied| Path::new(&root_key).starts_with(denied))
+    });
+    (read_roots, write_roots)
+}
+
+pub(crate) fn build_payload_deny_write_paths(
+    request: &SandboxSetupRequest<'_>,
+    explicit_deny_write_paths: Option<Vec<PathBuf>>,
+) -> Vec<PathBuf> {
+    let allow_deny_paths: AllowDenyPaths = compute_allow_paths_for_permissions(
+        request.permissions,
+        request.command_cwd,
+        request.env_map,
+    );
+    let mut deny_write_paths: Vec<PathBuf> = explicit_deny_write_paths
+        .unwrap_or_default()
+        .into_iter()
+        .map(|path| canonicalize_path(&path))
+        .collect();
+    deny_write_paths.extend(allow_deny_paths.deny);
+    deny_write_paths
+}
+
+fn build_payload_deny_read_paths(explicit_deny_read_paths: Option<Vec<PathBuf>>) -> Vec<PathBuf> {
+    // Keep the configured spelling here so the ACL layer can plan both the
+    // lexical path and any existing canonical target for reparse-point aliases.
+    explicit_deny_read_paths.unwrap_or_default()
+}
+
+fn expand_user_profile_root(roots: Vec<PathBuf>) -> Vec<PathBuf> {
+    let Ok(user_profile) = std::env::var("USERPROFILE") else {
+        return roots;
+    };
+    expand_user_profile_root_for(roots, Path::new(&user_profile))
+}
+
+fn expand_user_profile_root_for(roots: Vec<PathBuf>, user_profile: &Path) -> Vec<PathBuf> {
+    let user_profile_key = canonical_path_key(user_profile);
+    let mut expanded = Vec::new();
+    for root in roots {
+        if canonical_path_key(&root) == user_profile_key {
+            expanded.extend(profile_read_roots(user_profile));
+        } else {
+            expanded.push(root);
+        }
+    }
+
+    expanded.sort_by_key(|root| canonical_path_key(root));
+    expanded.dedup_by(|a, b| canonical_path_key(a.as_path()) == canonical_path_key(b.as_path()));
+    expanded
+}
+
+fn filter_user_profile_root(mut roots: Vec<PathBuf>) -> Vec<PathBuf> {
+    let Ok(user_profile) = std::env::var("USERPROFILE") else {
+        return roots;
+    };
+    let user_profile_key = canonical_path_key(Path::new(&user_profile));
+    roots.retain(|root| canonical_path_key(root) != user_profile_key);
+    roots
+}
+
+fn filter_user_profile_root_exclusions(mut roots: Vec<PathBuf>) -> Vec<PathBuf> {
+    let Ok(user_profile) = std::env::var("USERPROFILE") else {
+        return roots;
+    };
+    let user_profile = Path::new(&user_profile);
+    roots.retain(|root| !is_user_profile_root_exclusion(root, user_profile));
+    roots
+}
+
+fn is_user_profile_root_exclusion(root: &Path, user_profile: &Path) -> bool {
+    let root_key = canonical_path_key(root);
+    let profile_key = canonical_path_key(user_profile);
+    let profile_prefix = format!("{}/", profile_key.trim_end_matches('/'));
+    let Some(relative_key) = root_key.strip_prefix(&profile_prefix) else {
+        return false;
+    };
+    let Some(child_name) = relative_key
+        .split('/')
+        .next()
+        .filter(|name| !name.is_empty())
+    else {
+        return false;
+    };
+
+    USERPROFILE_ROOT_EXCLUSIONS
+        .iter()
+        .any(|excluded| child_name.eq_ignore_ascii_case(excluded))
+}
+
+fn filter_ssh_config_dependency_roots(mut roots: Vec<PathBuf>) -> Vec<PathBuf> {
+    let Ok(user_profile) = std::env::var("USERPROFILE") else {
+        return roots;
+    };
+    let user_profile = Path::new(&user_profile);
+    let dependency_paths = ssh_config_dependency_paths(user_profile);
+    roots.retain(|root| !is_ssh_config_dependency_root(root, user_profile, &dependency_paths));
+    roots
+}
+
+fn is_ssh_config_dependency_root(
+    root: &Path,
+    user_profile: &Path,
+    dependency_paths: &[PathBuf],
+) -> bool {
+    let Some(child_name) = user_profile_child_name(root, user_profile) else {
+        return false;
+    };
+
+    dependency_paths.iter().any(|path| {
+        user_profile_child_name(path, user_profile)
+            .is_some_and(|dependency_child| child_name.eq_ignore_ascii_case(&dependency_child))
+    })
+}
+
+fn user_profile_child_name(path: &Path, user_profile: &Path) -> Option<String> {
+    let root_key = canonical_path_key(path);
+    let profile_key = canonical_path_key(user_profile);
+    let profile_prefix = format!("{}/", profile_key.trim_end_matches('/'));
+    let relative_key = root_key.strip_prefix(&profile_prefix)?;
+    relative_key
+        .split('/')
+        .next()
+        .filter(|name| !name.is_empty())
+        .map(str::to_string)
+}
+
+fn filter_sensitive_write_roots(mut roots: Vec<PathBuf>, codex_home: &Path) -> Vec<PathBuf> {
+    // Never grant capability write access to CODEX_HOME or anything under CODEX_HOME/.sandbox,
+    // CODEX_HOME/.sandbox-bin, or CODEX_HOME/.sandbox-secrets. These locations contain sandbox
+    // control/state and helper binaries and must remain tamper-resistant.
+    let codex_home_key = canonical_path_key(codex_home);
+    let sbx_dir_key = canonical_path_key(&sandbox_dir(codex_home));
+    let sbx_dir_prefix = format!("{}/", sbx_dir_key.trim_end_matches('/'));
+    let sbx_bin_dir_key = canonical_path_key(&sandbox_bin_dir(codex_home));
+    let sbx_bin_dir_prefix = format!("{}/", sbx_bin_dir_key.trim_end_matches('/'));
+    let secrets_dir_key = canonical_path_key(&sandbox_secrets_dir(codex_home));
+    let secrets_dir_prefix = format!("{}/", secrets_dir_key.trim_end_matches('/'));
+
+    roots.retain(|root| {
+        let key = canonical_path_key(root);
+        key != codex_home_key
+            && key != sbx_dir_key
+            && !key.starts_with(&sbx_dir_prefix)
+            && key != sbx_bin_dir_key
+            && !key.starts_with(&sbx_bin_dir_prefix)
+            && key != secrets_dir_key
+            && !key.starts_with(&secrets_dir_prefix)
+    });
+    roots
+}
+
+#[cfg(test)]
+mod tests {
+    use super::WINDOWS_PLATFORM_DEFAULT_READ_ROOTS;
+    use super::WINDOWS_SANDBOX_PROXY_PORTS_ENV_KEY;
+    use super::build_payload_roots;
+    use super::find_setup_exe_for_current_exe;
+    use super::gather_full_read_roots_for_permissions;
+    use super::gather_read_roots;
+    use super::loopback_proxy_port_from_url;
+    use super::offline_proxy_settings_from_env;
+    use super::profile_read_roots;
+    use super::proxy_ports_from_env;
+    use super::verify_setup_completed;
+    use crate::WindowsSandboxProvisioningSettings;
+    use crate::WindowsSandboxProxyListeners;
+    use crate::helper_materialization::BIN_DIRNAME;
+    use crate::helper_materialization::RESOURCES_DIRNAME;
+    use crate::helper_materialization::helper_bin_dir;
+    use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+    use crate::setup_error::SetupErrorCode;
+    use crate::setup_error::SetupErrorReport;
+    use crate::setup_error::extract_failure;
+    use crate::setup_error::write_setup_error_report;
+    use codex_protocol::models::ManagedFileSystemPermissions;
+    use codex_protocol::models::PermissionProfile;
+    use codex_protocol::permissions::FileSystemAccessMode;
+    use codex_protocol::permissions::FileSystemPath;
+    use codex_protocol::permissions::FileSystemSandboxEntry;
+    use codex_protocol::permissions::FileSystemSandboxPolicy;
+    use codex_protocol::permissions::FileSystemSpecialPath;
+    use codex_protocol::permissions::NetworkSandboxPolicy;
+    use codex_protocol::permissions::project_roots_glob_pattern;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashMap;
+    use std::collections::HashSet;
+    use std::fs;
+    use std::path::Path;
+    use std::path::PathBuf;
+    use std::sync::Arc;
+    use std::sync::atomic::AtomicUsize;
+    use std::sync::atomic::Ordering;
+    use std::sync::mpsc;
+    use std::thread;
+    use std::time::Duration;
+    use std::time::Instant;
+    use tempfile::TempDir;
+
+    fn canonical_windows_platform_default_roots() -> Vec<PathBuf> {
+        WINDOWS_PLATFORM_DEFAULT_READ_ROOTS
+            .iter()
+            .map(|path| dunce::canonicalize(path).unwrap_or_else(|_| PathBuf::from(path)))
+            .collect()
+    }
+
+    #[test]
+    fn setup_completion_requires_ready_artifacts() {
+        let codex_home = TempDir::new().expect("tempdir");
+        let err = verify_setup_completed(codex_home.path())
+            .expect_err("missing setup artifacts should fail");
+
+        assert_eq!(
+            extract_failure(&err).map(|failure| failure.code),
+            Some(SetupErrorCode::OrchestratorHelperIncomplete)
+        );
+    }
+
+    #[test]
+    fn identical_setup_requests_share_one_in_flight_run() {
+        let key = TempDir::new()
+            .expect("tempdir")
+            .path()
+            .display()
+            .to_string();
+        let runs = Arc::new(AtomicUsize::new(0));
+        let (started_tx, started_rx) = mpsc::channel();
+        let (release_tx, release_rx) = mpsc::channel();
+
+        let leader = {
+            let key = key.clone();
+            let runs = Arc::clone(&runs);
+            thread::spawn(move || {
+                super::run_setup_singleflight(key, || {
+                    runs.fetch_add(1, Ordering::SeqCst);
+                    started_tx.send(()).expect("signal leader started");
+                    release_rx.recv().expect("release leader");
+                    Ok(())
+                })
+            })
+        };
+        started_rx.recv().expect("leader started");
+
+        let waiter = {
+            let key = key.clone();
+            let runs = Arc::clone(&runs);
+            thread::spawn(move || {
+                super::run_setup_singleflight(key, || {
+                    runs.fetch_add(1, Ordering::SeqCst);
+                    Ok(())
+                })
+            })
+        };
+
+        let deadline = Instant::now() + Duration::from_secs(5);
+        loop {
+            let attached = super::SETUP_FLIGHTS
+                .get()
+                .expect("setup flights initialized")
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner)
+                .get(&key)
+                .is_some_and(|flight| Arc::strong_count(flight) >= 3);
+            if attached {
+                break;
+            }
+            assert!(
+                Instant::now() < deadline,
+                "waiter did not join setup flight"
+            );
+            thread::yield_now();
+        }
+
+        release_tx.send(()).expect("release leader");
+        leader
+            .join()
+            .expect("leader thread")
+            .expect("leader result");
+        waiter
+            .join()
+            .expect("waiter thread")
+            .expect("waiter result");
+        assert_eq!(runs.load(Ordering::SeqCst), 1);
+    }
+
+    fn permissions_for(
+        permission_profile: &PermissionProfile,
+        workspace_roots: &[AbsolutePathBuf],
+    ) -> ResolvedWindowsSandboxPermissions {
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        )
+        .expect("managed permission profile")
+    }
+
+    fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf> {
+        vec![AbsolutePathBuf::from_absolute_path(root).expect("absolute workspace root")]
+    }
+
+    fn workspace_write_profile(
+        writable_roots: &[AbsolutePathBuf],
+        exclude_tmpdir_env_var: bool,
+        exclude_slash_tmp: bool,
+    ) -> PermissionProfile {
+        PermissionProfile::workspace_write_with(
+            writable_roots,
+            NetworkSandboxPolicy::Restricted,
+            exclude_tmpdir_env_var,
+            exclude_slash_tmp,
+        )
+    }
+
+    #[test]
+    fn setup_request_prefers_explicit_proxy_settings() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        let permissions = permissions_for(
+            &PermissionProfile::read_only(),
+            workspace_roots_for(&command_cwd).as_slice(),
+        );
+        let env_map = HashMap::from([(
+            "HTTP_PROXY".to_string(),
+            "http://127.0.0.1:8080".to_string(),
+        )]);
+        let explicit = super::OfflineProxySettings {
+            proxy_ports: vec![7890],
+            allow_local_binding: true,
+        };
+        let request = super::SandboxSetupRequest {
+            permissions: &permissions,
+            command_cwd: &command_cwd,
+            env_map: &env_map,
+            codex_home: tmp.path(),
+            proxy_enforced: false,
+        };
+
+        assert_eq!(
+            super::offline_proxy_settings_for_request(&request, Some(&explicit)),
+            explicit
+        );
+    }
+
+    #[test]
+    fn elevated_setup_payload_contains_no_caller_acl_roots() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("caller-workspace");
+        let codex_home = tmp.path().join("codex-home");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        let permissions = permissions_for(
+            &workspace_write_profile(
+                workspace_roots_for(&command_cwd).as_slice(),
+                /*exclude_tmpdir_env_var*/ true,
+                /*exclude_slash_tmp*/ true,
+            ),
+            workspace_roots_for(&command_cwd).as_slice(),
+        );
+        let request = super::SandboxSetupRequest {
+            permissions: &permissions,
+            command_cwd: &command_cwd,
+            env_map: &HashMap::new(),
+            codex_home: &codex_home,
+            proxy_enforced: false,
+        };
+
+        let payload = super::elevated_provisioning_payload(
+            &request,
+            /*offline_proxy_settings_override*/ None,
+            r"DOMAIN\alice".to_string(),
+        );
+
+        assert!(matches!(payload.runtime, super::SetupRuntime::Legacy));
+        assert_eq!(payload.real_user, r"DOMAIN\alice");
+        assert_eq!(payload.command_cwd, codex_home);
+        assert_eq!(payload.read_roots, Vec::<PathBuf>::new());
+        assert_eq!(payload.write_roots, Vec::<PathBuf>::new());
+        assert_eq!(payload.deny_read_paths, Vec::<PathBuf>::new());
+        assert_eq!(payload.deny_write_paths, Vec::<PathBuf>::new());
+        assert!(matches!(
+            payload.mode,
+            super::SetupMode::InteractiveProvision
+        ));
+    }
+
+    #[test]
+    fn report_helper_failure_uses_setup_error_report_when_clear_succeeded() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        write_setup_error_report(
+            codex_home.as_path(),
+            &SetupErrorReport {
+                code: super::SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                message: "firewall policy unavailable".to_string(),
+            },
+        )
+        .expect("write setup error report");
+
+        let err = super::report_helper_failure(
+            codex_home.as_path(),
+            /*cleared_report*/ true,
+            /*exit_code*/ Some(1),
+        );
+
+        let failure = extract_failure(&err).expect("structured setup failure");
+        assert_eq!(
+            &super::SetupFailure::new(
+                super::SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                "firewall policy unavailable",
+            ),
+            failure
+        );
+    }
+
+    #[test]
+    fn report_helper_failure_ignores_setup_error_report_when_clear_failed() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        write_setup_error_report(
+            codex_home.as_path(),
+            &SetupErrorReport {
+                code: super::SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                message: "stale report".to_string(),
+            },
+        )
+        .expect("write setup error report");
+
+        let err = super::report_helper_failure(
+            codex_home.as_path(),
+            /*cleared_report*/ false,
+            /*exit_code*/ Some(1),
+        );
+
+        let failure = extract_failure(&err).expect("structured setup failure");
+        assert_eq!(
+            &super::SetupFailure::new(
+                super::SetupErrorCode::OrchestratorHelperExitNonzero,
+                "setup helper exited with status Some(1)",
+            ),
+            failure
+        );
+    }
+
+    #[test]
+    fn setup_refresh_skips_profiles_without_managed_filesystem_permissions() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let codex_home = tmp.path().join("codex-home");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+
+        for permission_profile in [
+            PermissionProfile::Disabled,
+            PermissionProfile::External {
+                network: NetworkSandboxPolicy::Restricted,
+            },
+        ] {
+            super::run_setup_refresh(
+                &permission_profile,
+                workspace_roots.as_slice(),
+                command_cwd.as_path(),
+                &HashMap::new(),
+                codex_home.as_path(),
+                /*proxy_enforced*/ false,
+            )
+            .expect("unsupported profiles do not need setup refresh");
+
+            super::run_setup_refresh_with_extra_read_roots(
+                &permission_profile,
+                workspace_roots.as_slice(),
+                command_cwd.as_path(),
+                &HashMap::new(),
+                codex_home.as_path(),
+                vec![command_cwd.clone()],
+                /*proxy_enforced*/ false,
+            )
+            .expect("unsupported profiles do not need setup refresh");
+        }
+    }
+
+    #[test]
+    fn setup_refresh_preserves_workspace_scoped_deny_read_paths() {
+        let tmp = TempDir::new().expect("tempdir");
+        let workspace_root = tmp.path().join("workspace");
+        let command_cwd = tmp.path().join("command-cwd");
+        let denied_glob_match = workspace_root.join("app").join("secret.env");
+        fs::create_dir_all(&command_cwd).expect("create command cwd");
+        fs::create_dir_all(denied_glob_match.parent().expect("glob parent"))
+            .expect("create glob parent");
+        fs::write(&denied_glob_match, "secret").expect("write denied glob match");
+        let permission_profile = PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Restricted {
+                entries: vec![
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::Special {
+                            value: FileSystemSpecialPath::Root,
+                        },
+                        FileSystemAccessMode::Read,
+                    ),
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::Special {
+                            value: FileSystemSpecialPath::project_roots(Some(
+                                "private".to_string(),
+                            )),
+                        },
+                        FileSystemAccessMode::Deny,
+                    ),
+                    FileSystemSandboxEntry::new(
+                        FileSystemPath::GlobPattern {
+                            pattern: project_roots_glob_pattern(Path::new("**/*.env")),
+                        },
+                        FileSystemAccessMode::Deny,
+                    ),
+                ],
+                glob_scan_max_depth: None,
+            },
+            network: NetworkSandboxPolicy::Restricted,
+        };
+
+        let deny_read_paths = super::setup_refresh_deny_read_paths(
+            &permission_profile,
+            workspace_roots_for(&workspace_root).as_slice(),
+            &command_cwd,
+        )
+        .expect("resolve refresh deny-read paths");
+
+        assert_eq!(
+            deny_read_paths.into_iter().collect::<HashSet<_>>(),
+            [
+                dunce::canonicalize(&workspace_root)
+                    .expect("canonicalize workspace root")
+                    .join("private"),
+                denied_glob_match,
+            ]
+            .into_iter()
+            .collect()
+        );
+    }
+
+    #[test]
+    fn setup_refresh_rejects_root_globs_before_expansion() {
+        let tmp = TempDir::new().expect("tempdir");
+        let command_cwd = tmp.path().join("workspace");
+        let codex_home = tmp.path().join("codex-home");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        let root = command_cwd.ancestors().last().expect("filesystem root");
+        let mut file_system = FileSystemSandboxPolicy::read_only();
+        file_system.entries.push(FileSystemSandboxEntry::new(
+            FileSystemPath::GlobPattern {
+                pattern: root.join("**").display().to_string(),
+            },
+            FileSystemAccessMode::Deny,
+        ));
+        let permission_profile = PermissionProfile::from_runtime_permissions(
+            &file_system,
+            NetworkSandboxPolicy::Restricted,
+        );
+        let workspace_roots = workspace_roots_for(&command_cwd);
+        let env_map = HashMap::new();
+        let errors = [
+            super::run_setup_refresh(
+                &permission_profile,
+                &workspace_roots,
+                &command_cwd,
+                &env_map,
+                &codex_home,
+                /*proxy_enforced*/ false,
+            )
+            .expect_err("root glob must be rejected before expansion"),
+            super::run_setup_refresh_with_extra_read_roots(
+                &permission_profile,
+                &workspace_roots,
+                &command_cwd,
+                &env_map,
+                &codex_home,
+                Vec::new(),
+                /*proxy_enforced*/ false,
+            )
+            .expect_err("root glob must be rejected before expansion"),
+        ];
+
+        let expected =
+            "elevated Windows sandbox requires effective `:root` read access".to_string();
+        assert_eq!(
+            errors.map(|err| err.to_string()),
+            [expected.clone(), expected]
+        );
+    }
+
+    #[test]
+    fn setup_refresh_rejects_invalid_deny_read_globs() {
+        let tmp = TempDir::new().expect("tempdir");
+        let workspace_root = tmp.path().join("workspace");
+        fs::create_dir_all(&workspace_root).expect("create workspace");
+        let permission_profile = PermissionProfile::Managed {
+            file_system: ManagedFileSystemPermissions::Restricted {
+                entries: vec![FileSystemSandboxEntry::new(
+                    FileSystemPath::GlobPattern {
+                        pattern: project_roots_glob_pattern(Path::new("[z-a]")),
+                    },
+                    FileSystemAccessMode::Deny,
+                )],
+                glob_scan_max_depth: None,
+            },
+            network: NetworkSandboxPolicy::Restricted,
+        };
+
+        let err = super::setup_refresh_deny_read_paths(
+            &permission_profile,
+            workspace_roots_for(&workspace_root).as_slice(),
+            &workspace_root,
+        )
+        .expect_err("invalid deny-read glob");
+
+        assert!(err.to_string().contains("invalid deny-read glob pattern"));
+    }
+
+    #[test]
+    fn loopback_proxy_url_parsing_supports_common_forms() {
+        assert_eq!(
+            loopback_proxy_port_from_url("http://localhost:3128"),
+            Some(3128)
+        );
+        assert_eq!(
+            loopback_proxy_port_from_url("https://127.0.0.1:8080"),
+            Some(8080)
+        );
+        assert_eq!(
+            loopback_proxy_port_from_url("socks5h://user:pass@[::1]:1080"),
+            Some(1080)
+        );
+    }
+
+    #[test]
+    fn setup_exe_lookup_checks_package_resource_dir_for_bin_exe() {
+        let tmp = TempDir::new().expect("tempdir");
+        let package_dir = tmp.path().join("package");
+        let bin_dir = package_dir.join(BIN_DIRNAME);
+        let resources_dir = package_dir.join(RESOURCES_DIRNAME);
+        fs::create_dir_all(&bin_dir).expect("create bin dir");
+        fs::create_dir_all(&resources_dir).expect("create resources dir");
+        let exe = bin_dir.join("codex.exe");
+        let setup_exe = resources_dir.join("codex-windows-sandbox-setup.exe");
+        fs::write(&exe, b"codex").expect("write exe");
+        fs::write(&setup_exe, b"setup").expect("write setup");
+
+        let resolved = find_setup_exe_for_current_exe(&exe).expect("setup exe");
+
+        assert_eq!(resolved, setup_exe);
+    }
+
+    #[test]
+    fn loopback_proxy_url_parsing_rejects_non_loopback_and_zero_port() {
+        assert_eq!(
+            loopback_proxy_port_from_url("http://example.com:3128"),
+            None
+        );
+        assert_eq!(loopback_proxy_port_from_url("http://127.0.0.1:0"), None);
+        assert_eq!(loopback_proxy_port_from_url("localhost:8080"), None);
+    }
+
+    #[test]
+    fn proxy_ports_from_env_dedupes_and_sorts() {
+        let mut env = HashMap::new();
+        env.insert(
+            "HTTP_PROXY".to_string(),
+            "http://127.0.0.1:8080".to_string(),
+        );
+        env.insert(
+            "http_proxy".to_string(),
+            "http://localhost:8080".to_string(),
+        );
+        env.insert("ALL_PROXY".to_string(), "socks5h://[::1]:1081".to_string());
+        env.insert(
+            "HTTPS_PROXY".to_string(),
+            "https://example.com:9999".to_string(),
+        );
+        env.insert(
+            WINDOWS_SANDBOX_PROXY_PORTS_ENV_KEY.to_string(),
+            "8080,43129,0,invalid, 43128,65536".to_string(),
+        );
+
+        assert_eq!(proxy_ports_from_env(&env), vec![1081, 8080, 43128, 43129]);
+        assert_eq!(
+            WindowsSandboxProvisioningSettings::from_environment(
+                &PermissionProfile::workspace_write(),
+                &env,
+            ),
+            WindowsSandboxProvisioningSettings {
+                proxy_ports: vec![1081, 8080, 43128, 43129],
+                allow_local_binding: false,
+            }
+        );
+        assert_eq!(
+            WindowsSandboxProxyListeners::from_environment(
+                &PermissionProfile::workspace_write(),
+                &env,
+            ),
+            WindowsSandboxProxyListeners {
+                http_ports: vec![8080],
+                socks_ports: vec![1081],
+            }
+        );
+    }
+
+    #[test]
+    fn offline_proxy_settings_ignore_proxy_env_when_online_identity_selected() {
+        let mut env = HashMap::new();
+        env.insert(
+            "HTTP_PROXY".to_string(),
+            "http://127.0.0.1:8080".to_string(),
+        );
+        env.insert(
+            "CODEX_NETWORK_ALLOW_LOCAL_BINDING".to_string(),
+            "1".to_string(),
+        );
+
+        assert_eq!(
+            offline_proxy_settings_from_env(&env, super::SandboxNetworkIdentity::Online),
+            super::OfflineProxySettings {
+                proxy_ports: vec![],
+                allow_local_binding: false,
+            }
+        );
+        let permission_profile = PermissionProfile::workspace_write_with(
+            &[],
+            NetworkSandboxPolicy::Enabled,
+            /*exclude_tmpdir_env_var*/ false,
+            /*exclude_slash_tmp*/ false,
+        );
+        assert_eq!(
+            WindowsSandboxProvisioningSettings::from_environment(&permission_profile, &env),
+            WindowsSandboxProvisioningSettings::default()
+        );
+        assert_eq!(
+            WindowsSandboxProxyListeners::from_environment(&permission_profile, &env),
+            WindowsSandboxProxyListeners::default()
+        );
+    }
+
+    #[test]
+    fn offline_proxy_settings_capture_proxy_ports_and_local_binding_for_offline_identity() {
+        let mut env = HashMap::new();
+        env.insert(
+            "HTTP_PROXY".to_string(),
+            "http://127.0.0.1:8080".to_string(),
+        );
+        env.insert(
+            "ALL_PROXY".to_string(),
+            "socks5h://127.0.0.1:1081".to_string(),
+        );
+        env.insert(
+            "CODEX_NETWORK_ALLOW_LOCAL_BINDING".to_string(),
+            "1".to_string(),
+        );
+
+        assert_eq!(
+            WindowsSandboxProvisioningSettings::from_environment(
+                &PermissionProfile::workspace_write(),
+                &env,
+            ),
+            WindowsSandboxProvisioningSettings {
+                proxy_ports: vec![1081, 8080],
+                allow_local_binding: true,
+            }
+        );
+        assert_eq!(
+            WindowsSandboxProxyListeners::from_environment(
+                &PermissionProfile::workspace_write(),
+                &env,
+            ),
+            WindowsSandboxProxyListeners {
+                http_ports: vec![8080],
+                socks_ports: vec![1081],
+            }
+        );
+
+        env.remove("ALL_PROXY");
+        for (all_proxy, socks_ports) in [
+            ("HTTP://localhost:8080", vec![]),
+            ("socks5h://[::1]:8080", vec![8080]),
+        ] {
+            env.insert("all_proxy".to_string(), all_proxy.to_string());
+            assert_eq!(
+                WindowsSandboxProxyListeners::from_environment(
+                    &PermissionProfile::workspace_write(),
+                    &env,
+                ),
+                WindowsSandboxProxyListeners {
+                    http_ports: vec![8080],
+                    socks_ports,
+                }
+            );
+        }
+    }
+
+    #[test]
+    fn provisioning_settings_preserve_all_inherited_proxy_ports() {
+        for (proxy_env, proxy_ports, http_ports, socks_ports) in [
+            (
+                vec![("ALL_PROXY", "socks5h://127.0.0.1:1081")],
+                vec![1081],
+                vec![],
+                vec![1081],
+            ),
+            (
+                vec![
+                    ("HTTP_PROXY", "http://127.0.0.1:8080"),
+                    ("HTTPS_PROXY", "http://127.0.0.1:3128"),
+                ],
+                vec![3128, 8080],
+                vec![3128, 8080],
+                vec![],
+            ),
+            (
+                vec![
+                    ("HTTP_PROXY", "http://127.0.0.1:8080"),
+                    (WINDOWS_SANDBOX_PROXY_PORTS_ENV_KEY, "8080,1081"),
+                ],
+                vec![1081, 8080],
+                vec![8080],
+                vec![],
+            ),
+            (
+                vec![("ALL_PROXY", "ftp://127.0.0.1:3128")],
+                vec![3128],
+                vec![],
+                vec![],
+            ),
+        ] {
+            let env = proxy_env
+                .into_iter()
+                .map(|(key, value)| (key.to_string(), value.to_string()))
+                .collect();
+            assert_eq!(
+                WindowsSandboxProvisioningSettings::from_environment(
+                    &PermissionProfile::workspace_write(),
+                    &env,
+                ),
+                WindowsSandboxProvisioningSettings {
+                    proxy_ports,
+                    allow_local_binding: false,
+                }
+            );
+            assert_eq!(
+                WindowsSandboxProxyListeners::from_environment(
+                    &PermissionProfile::workspace_write(),
+                    &env,
+                ),
+                WindowsSandboxProxyListeners {
+                    http_ports,
+                    socks_ports,
+                }
+            );
+        }
+    }
+
+    #[test]
+    fn setup_marker_request_mismatch_reason_ignores_proxy_drift_for_online_identity() {
+        let marker = super::SetupMarker {
+            version: super::SETUP_VERSION,
+            offline_username: "offline".to_string(),
+            online_username: "online".to_string(),
+            created_at: None,
+            proxy_ports: vec![3128],
+            allow_local_binding: false,
+        };
+        let desired = super::OfflineProxySettings {
+            proxy_ports: vec![1081, 8080],
+            allow_local_binding: true,
+        };
+
+        assert_eq!(
+            marker.request_mismatch_reason(super::SandboxNetworkIdentity::Online, &desired),
+            None
+        );
+    }
+
+    #[test]
+    fn setup_marker_request_mismatch_reason_reports_offline_firewall_drift() {
+        let marker = super::SetupMarker {
+            version: super::SETUP_VERSION,
+            offline_username: "offline".to_string(),
+            online_username: "online".to_string(),
+            created_at: None,
+            proxy_ports: vec![3128],
+            allow_local_binding: false,
+        };
+        let desired = super::OfflineProxySettings {
+            proxy_ports: vec![1081, 8080],
+            allow_local_binding: true,
+        };
+
+        assert_eq!(
+            marker.request_mismatch_reason(super::SandboxNetworkIdentity::Offline, &desired),
+            Some(
+                "offline firewall settings changed (stored_ports=[3128], desired_ports=[1081, 8080], stored_allow_local_binding=false, desired_allow_local_binding=true)"
+                    .to_string()
+            )
+        );
+    }
+
+    #[test]
+    fn profile_read_roots_excludes_configured_top_level_entries() {
+        let tmp = TempDir::new().expect("tempdir");
+        let user_profile = tmp.path();
+        let allowed_dir = user_profile.join("Documents");
+        let allowed_file = user_profile.join("settings.json");
+        let excluded_dir = user_profile.join(".ssh");
+        let excluded_tsh = user_profile.join(".tsh");
+        let excluded_case_variant = user_profile.join(".AWS");
+
+        fs::create_dir_all(&allowed_dir).expect("create allowed dir");
+        fs::write(&allowed_file, "safe").expect("create allowed file");
+        fs::create_dir_all(&excluded_dir).expect("create excluded dir");
+        fs::create_dir_all(&excluded_tsh).expect("create excluded tsh dir");
+        fs::create_dir_all(&excluded_case_variant).expect("create excluded case variant");
+
+        let roots = profile_read_roots(user_profile);
+        let actual: HashSet<PathBuf> = roots.into_iter().collect();
+        let expected: HashSet<PathBuf> = [allowed_dir, allowed_file].into_iter().collect();
+
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn profile_read_roots_falls_back_to_profile_root_when_enumeration_fails() {
+        let tmp = TempDir::new().expect("tempdir");
+        let missing_profile = tmp.path().join("missing-user-profile");
+
+        let roots = profile_read_roots(&missing_profile);
+
+        assert_eq!(vec![missing_profile], roots);
+    }
+
+    #[test]
+    fn is_user_profile_root_exclusion_blocks_configured_children() {
+        let tmp = TempDir::new().expect("tempdir");
+        let user_profile = tmp.path().join("user-profile");
+        let documents = user_profile.join("Documents");
+        let app_data = user_profile.join("AppData");
+        let ssh_child = user_profile.join(".ssh").join("config");
+        let tsh_child = user_profile.join(".tsh").join("keys");
+        let other_root = tmp.path().join("other-root");
+        fs::create_dir_all(&documents).expect("create documents");
+        fs::create_dir_all(&app_data).expect("create app data");
+        fs::create_dir_all(&ssh_child).expect("create ssh child");
+        fs::create_dir_all(&tsh_child).expect("create tsh child");
+        fs::create_dir_all(&other_root).expect("create other root");
+
+        assert!(!super::is_user_profile_root_exclusion(
+            &documents,
+            &user_profile
+        ));
+        assert!(!super::is_user_profile_root_exclusion(
+            &app_data,
+            &user_profile
+        ));
+        assert!(super::is_user_profile_root_exclusion(
+            &ssh_child,
+            &user_profile
+        ));
+        assert!(super::is_user_profile_root_exclusion(
+            &tsh_child,
+            &user_profile
+        ));
+        assert!(!super::is_user_profile_root_exclusion(
+            &other_root,
+            &user_profile
+        ));
+    }
+
+    #[test]
+    fn is_ssh_config_dependency_root_blocks_config_dependencies() {
+        let tmp = TempDir::new().expect("tempdir");
+        let user_profile = tmp.path().join("user-profile");
+        let documents = user_profile.join("Documents");
+        let ssh_dir = user_profile.join(".ssh");
+        let key_dir = user_profile.join(".keys");
+        let include_dir = user_profile.join(".included");
+        let other_root = tmp.path().join("other-root");
+        fs::create_dir_all(&documents).expect("create documents");
+        fs::create_dir_all(&ssh_dir).expect("create .ssh");
+        fs::create_dir_all(&key_dir).expect("create key dir");
+        fs::create_dir_all(&include_dir).expect("create include dir");
+        fs::create_dir_all(&other_root).expect("create other root");
+        fs::write(
+            ssh_dir.join("config"),
+            "IdentityFile ~/.keys/id_ed25519\nInclude ~/.included/config\n",
+        )
+        .expect("write ssh config");
+        fs::write(key_dir.join("id_ed25519"), "").expect("write key");
+        fs::write(include_dir.join("config"), "User git\n").expect("write included config");
+
+        let dependency_paths = super::ssh_config_dependency_paths(&user_profile);
+
+        assert!(!super::is_ssh_config_dependency_root(
+            &documents,
+            &user_profile,
+            &dependency_paths
+        ));
+        assert!(super::is_ssh_config_dependency_root(
+            &key_dir,
+            &user_profile,
+            &dependency_paths
+        ));
+        assert!(super::is_ssh_config_dependency_root(
+            &include_dir.join("config"),
+            &user_profile,
+            &dependency_paths
+        ));
+        assert!(!super::is_ssh_config_dependency_root(
+            &other_root,
+            &user_profile,
+            &dependency_paths
+        ));
+    }
+
+    #[test]
+    fn expand_user_profile_root_for_replaces_profile_root_with_children() {
+        let tmp = TempDir::new().expect("tempdir");
+        let user_profile = tmp.path().join("user-profile");
+        let documents = user_profile.join("Documents");
+        let excluded = user_profile.join(".local");
+        let other_root = tmp.path().join("other-root");
+        fs::create_dir_all(&documents).expect("create documents");
+        fs::create_dir_all(&excluded).expect("create excluded dir");
+        fs::create_dir_all(&other_root).expect("create other root");
+
+        let roots = super::expand_user_profile_root_for(
+            vec![user_profile.clone(), other_root.clone()],
+            &user_profile,
+        );
+        let actual: HashSet<PathBuf> = roots.into_iter().collect();
+        let expected: HashSet<PathBuf> = [documents, excluded, other_root].into_iter().collect();
+
+        assert_eq!(expected, actual);
+    }
+
+    #[test]
+    fn expanded_write_roots_still_drop_protected_codex_home() {
+        let tmp = TempDir::new().expect("tempdir");
+        let user_profile = tmp.path().join("user-profile");
+        let codex_home = user_profile.join("CodexHome");
+        let documents = user_profile.join("Documents");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&documents).expect("create documents");
+
+        let mut roots =
+            super::expand_user_profile_root_for(vec![user_profile.clone()], &user_profile);
+        let user_profile_key = super::canonical_path_key(&user_profile);
+        roots.retain(|root| super::canonical_path_key(root) != user_profile_key);
+        roots.retain(|root| !super::is_user_profile_root_exclusion(root, &user_profile));
+        let roots = super::filter_sensitive_write_roots(roots, &codex_home);
+
+        assert_eq!(vec![documents], roots);
+    }
+
+    #[test]
+    fn gather_read_roots_includes_helper_bin_dir() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let command_cwd = tmp.path().join("workspace");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        let permission_profile = PermissionProfile::read_only();
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+
+        let roots = gather_read_roots(
+            &command_cwd,
+            &permissions,
+            &HashMap::new(),
+            &codex_home,
+            super::SetupRuntime::Legacy,
+        );
+        let expected =
+            dunce::canonicalize(helper_bin_dir(&codex_home)).expect("canonical helper dir");
+
+        assert!(roots.contains(&expected));
+    }
+
+    #[test]
+    fn helper_read_roots_only_create_a_legacy_bin() {
+        let tmp = TempDir::new().expect("tempdir");
+        for runtime in [super::SetupRuntime::Registered, super::SetupRuntime::Legacy] {
+            let home = tmp.path().join(format!("{runtime:?}"));
+            let roots = super::gather_helper_read_roots(&home, runtime);
+            match runtime {
+                super::SetupRuntime::Registered => {
+                    assert_eq!(roots, Vec::<PathBuf>::new());
+                    assert!(!home.exists());
+                }
+                super::SetupRuntime::Legacy => {
+                    assert_eq!(roots, vec![helper_bin_dir(&home)]);
+                    assert!(helper_bin_dir(&home).is_dir());
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn registered_payload_preserves_explicit_bin_read_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let home = tmp.path().join("home");
+        let bin = helper_bin_dir(&home);
+        fs::create_dir_all(&bin).expect("create explicit root");
+        let workspace_roots = workspace_roots_for(tmp.path());
+        let permissions = permissions_for(&PermissionProfile::read_only(), &workspace_roots);
+        let (read_roots, write_roots) = build_payload_roots(
+            &super::SandboxSetupRequest {
+                permissions: &permissions,
+                command_cwd: tmp.path(),
+                env_map: &HashMap::new(),
+                codex_home: &home,
+                proxy_enforced: false,
+            },
+            &super::SetupRootOverrides {
+                read_roots: Some(vec![bin.clone()]),
+                ..super::SetupRootOverrides::default()
+            },
+            super::SetupRuntime::Registered,
+        );
+        assert_eq!(
+            read_roots,
+            vec![dunce::canonicalize(bin).expect("canonical bin")]
+        );
+        assert_eq!(write_roots, Vec::<PathBuf>::new());
+    }
+
+    #[test]
+    fn workspace_write_roots_remain_readable() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let command_cwd = tmp.path().join("workspace");
+        let writable_root = tmp.path().join("extra-write-root");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        fs::create_dir_all(&writable_root).expect("create writable root");
+        let writable_roots = vec![
+            AbsolutePathBuf::from_absolute_path(&writable_root).expect("absolute writable root"),
+        ];
+        let permission_profile = workspace_write_profile(
+            &writable_roots,
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+
+        let roots = gather_read_roots(
+            &command_cwd,
+            &permissions,
+            &HashMap::new(),
+            &codex_home,
+            super::SetupRuntime::Legacy,
+        );
+        let expected_writable =
+            dunce::canonicalize(&writable_root).expect("canonical writable root");
+
+        assert!(roots.contains(&expected_writable));
+    }
+
+    #[test]
+    fn build_payload_roots_preserves_helper_roots_when_read_override_is_provided() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let workspace_root = tmp.path().join("workspace-root");
+        let command_cwd = tmp.path().join("workspace");
+        let readable_root = tmp.path().join("docs");
+        fs::create_dir_all(&workspace_root).expect("create workspace root");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        fs::create_dir_all(&readable_root).expect("create readable root");
+        let permission_profile = PermissionProfile::read_only();
+        let workspace_roots = workspace_roots_for(workspace_root.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+
+        let (read_roots, write_roots) = build_payload_roots(
+            &super::SandboxSetupRequest {
+                permissions: &permissions,
+                command_cwd: &command_cwd,
+                env_map: &HashMap::new(),
+                codex_home: &codex_home,
+                proxy_enforced: false,
+            },
+            &super::SetupRootOverrides {
+                read_roots: Some(vec![readable_root.clone()]),
+                read_roots_include_platform_defaults: true,
+                write_roots: None,
+                deny_read_paths: None,
+                deny_write_paths: None,
+            },
+            super::SetupRuntime::Legacy,
+        );
+        let expected_helper =
+            dunce::canonicalize(helper_bin_dir(&codex_home)).expect("canonical helper dir");
+        let expected_cwd = dunce::canonicalize(&command_cwd).expect("canonical workspace");
+        let expected_readable =
+            dunce::canonicalize(&readable_root).expect("canonical readable root");
+
+        assert_eq!(write_roots, Vec::<PathBuf>::new());
+        assert!(read_roots.contains(&expected_helper));
+        assert!(!read_roots.contains(&expected_cwd));
+        assert!(read_roots.contains(&expected_readable));
+        assert!(
+            canonical_windows_platform_default_roots()
+                .into_iter()
+                .all(|path| read_roots.contains(&path))
+        );
+    }
+
+    #[test]
+    fn build_payload_roots_replaces_full_read_policy_when_read_override_is_provided() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let workspace_root = tmp.path().join("workspace-root");
+        let command_cwd = tmp.path().join("workspace");
+        let readable_root = tmp.path().join("docs");
+        fs::create_dir_all(&workspace_root).expect("create workspace root");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        fs::create_dir_all(&readable_root).expect("create readable root");
+        let permission_profile = PermissionProfile::read_only();
+        let workspace_roots = workspace_roots_for(workspace_root.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+
+        let (read_roots, write_roots) = build_payload_roots(
+            &super::SandboxSetupRequest {
+                permissions: &permissions,
+                command_cwd: &command_cwd,
+                env_map: &HashMap::new(),
+                codex_home: &codex_home,
+                proxy_enforced: false,
+            },
+            &super::SetupRootOverrides {
+                read_roots: Some(vec![readable_root.clone()]),
+                read_roots_include_platform_defaults: false,
+                write_roots: None,
+                deny_read_paths: None,
+                deny_write_paths: None,
+            },
+            super::SetupRuntime::Legacy,
+        );
+        let expected_helper =
+            dunce::canonicalize(helper_bin_dir(&codex_home)).expect("canonical helper dir");
+        let expected_cwd = dunce::canonicalize(&command_cwd).expect("canonical workspace");
+        let expected_readable =
+            dunce::canonicalize(&readable_root).expect("canonical readable root");
+
+        assert_eq!(write_roots, Vec::<PathBuf>::new());
+        assert!(read_roots.contains(&expected_helper));
+        assert!(!read_roots.contains(&expected_cwd));
+        assert!(read_roots.contains(&expected_readable));
+        assert!(
+            canonical_windows_platform_default_roots()
+                .into_iter()
+                .all(|path| !read_roots.contains(&path))
+        );
+    }
+
+    #[test]
+    fn effective_write_roots_match_payload_filtering_for_overrides() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let command_cwd = tmp.path().join("workspace");
+        let extra_root = tmp.path().join("extra-root");
+        let sandbox_root = super::sandbox_dir(&codex_home);
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        fs::create_dir_all(&extra_root).expect("create extra root");
+        fs::create_dir_all(&sandbox_root).expect("create sandbox root");
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+        let override_roots = vec![
+            command_cwd.clone(),
+            extra_root.clone(),
+            codex_home.clone(),
+            sandbox_root.clone(),
+        ];
+        let request = super::SandboxSetupRequest {
+            permissions: &permissions,
+            command_cwd: &command_cwd,
+            env_map: &HashMap::new(),
+            codex_home: &codex_home,
+            proxy_enforced: false,
+        };
+        let overrides = super::SetupRootOverrides {
+            read_roots: None,
+            read_roots_include_platform_defaults: false,
+            write_roots: Some(override_roots.clone()),
+            deny_read_paths: None,
+            deny_write_paths: None,
+        };
+
+        let effective_write_roots = super::effective_write_roots_for_setup(
+            &permissions,
+            &command_cwd,
+            &HashMap::new(),
+            &codex_home,
+            Some(&override_roots),
+        );
+        let (_read_roots, payload_write_roots) =
+            build_payload_roots(&request, &overrides, super::SetupRuntime::Legacy);
+
+        let expected_workspace = dunce::canonicalize(&command_cwd).expect("canonical workspace");
+        let expected_extra = dunce::canonicalize(&extra_root).expect("canonical extra root");
+        let forbidden_codex_home = dunce::canonicalize(&codex_home).expect("canonical codex home");
+        let forbidden_sandbox = dunce::canonicalize(&sandbox_root).expect("canonical sandbox root");
+        assert_eq!(effective_write_roots, payload_write_roots);
+        assert!(effective_write_roots.contains(&expected_workspace));
+        assert!(effective_write_roots.contains(&expected_extra));
+        assert!(!effective_write_roots.contains(&forbidden_codex_home));
+        assert!(!effective_write_roots.contains(&forbidden_sandbox));
+    }
+
+    #[test]
+    fn effective_write_roots_use_runtime_workspace_roots_for_workspace_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let workspace_root = tmp.path().join("workspace");
+        let command_cwd = workspace_root.join("subdir");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&command_cwd).expect("create command cwd");
+
+        let permission_profile = workspace_write_profile(
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(workspace_root.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+
+        let effective_write_roots = super::effective_write_roots_for_setup(
+            &permissions,
+            &command_cwd,
+            &HashMap::new(),
+            &codex_home,
+            /*write_roots_override*/ None,
+        );
+
+        assert_eq!(
+            effective_write_roots,
+            vec![dunce::canonicalize(&workspace_root).expect("canonical workspace root")]
+        );
+    }
+
+    #[test]
+    fn payload_deny_write_paths_merge_explicit_and_protected_children() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let command_cwd = tmp.path().join("workspace");
+        let extra_write_root = tmp.path().join("extra-write-root");
+        let command_git = command_cwd.join(".git");
+        let extra_codex = extra_write_root.join(".codex");
+        let explicit_deny = tmp.path().join("explicit-deny");
+        fs::create_dir_all(&command_git).expect("create command .git");
+        fs::create_dir_all(&extra_codex).expect("create extra .codex");
+        let writable_roots = vec![
+            AbsolutePathBuf::from_absolute_path(&extra_write_root).expect("absolute writable root"),
+        ];
+        let permission_profile = workspace_write_profile(
+            &writable_roots,
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+        let request = super::SandboxSetupRequest {
+            permissions: &permissions,
+            command_cwd: &command_cwd,
+            env_map: &HashMap::new(),
+            codex_home: &codex_home,
+            proxy_enforced: false,
+        };
+
+        let deny_write_paths =
+            super::build_payload_deny_write_paths(&request, Some(vec![explicit_deny.clone()]));
+
+        assert_eq!(
+            [
+                dunce::canonicalize(&command_git).expect("canonical command .git"),
+                dunce::canonicalize(&extra_codex).expect("canonical extra .codex"),
+                explicit_deny,
+            ]
+            .into_iter()
+            .collect::<HashSet<PathBuf>>(),
+            deny_write_paths.into_iter().collect()
+        );
+    }
+
+    #[test]
+    fn full_read_roots_preserve_legacy_platform_defaults() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let command_cwd = tmp.path().join("workspace");
+        fs::create_dir_all(&command_cwd).expect("create workspace");
+        let permission_profile = PermissionProfile::read_only();
+        let workspace_roots = workspace_roots_for(command_cwd.as_path());
+        let permissions = permissions_for(&permission_profile, workspace_roots.as_slice());
+
+        let roots = gather_full_read_roots_for_permissions(
+            &command_cwd,
+            &permissions,
+            &HashMap::new(),
+            &codex_home,
+            super::SetupRuntime::Legacy,
+        );
+
+        assert!(
+            canonical_windows_platform_default_roots()
+                .into_iter()
+                .all(|path| roots.contains(&path))
+        );
+    }
+
+    #[test]
+    fn build_payload_deny_read_paths_preserves_explicit_paths() {
+        let tmp = TempDir::new().expect("tempdir");
+        let existing = tmp.path().join("secret.env");
+        let missing = tmp.path().join("future.env");
+        fs::write(&existing, "secret").expect("write existing");
+
+        assert_eq!(
+            super::build_payload_deny_read_paths(Some(vec![existing.clone(), missing.clone()])),
+            vec![existing, missing]
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_error.rs b/codex-rs/windows-sandbox-rs/src/setup_error.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d9104602bc19af88101fbb5b44f839a1d799c174
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_error.rs
@@ -0,0 +1,289 @@
+use anyhow::Context;
+use anyhow::Result;
+use codex_utils_string::sanitize_metric_tag_value;
+use serde::Deserialize;
+use serde::Serialize;
+use std::fs;
+use std::io::ErrorKind;
+use std::path::Path;
+use std::path::PathBuf;
+
+/// These represent the most common failures for the elevated sandbox setup.
+///
+/// Codes are used as metric tags.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SetupErrorCode {
+    // Orchestrator (run in CLI) failures.
+    /// Failed to create `codex_home/.sandbox` in the orchestrator.
+    OrchestratorSandboxDirCreateFailed,
+    /// Failed to determine whether the current process is elevated.
+    OrchestratorElevationCheckFailed,
+    /// The setup command requires an already elevated process.
+    OrchestratorElevationRequired,
+    /// Failed to serialize the elevation payload before launching the helper.
+    OrchestratorPayloadSerializeFailed,
+    /// Failed to launch the setup helper process (spawn or ShellExecuteExW).
+    OrchestratorHelperLaunchFailed,
+    /// User canceled the UAC prompt while launching the helper.
+    OrchestratorHelperLaunchCanceled,
+    /// Helper exited non-zero and no structured report was available.
+    OrchestratorHelperExitNonzero,
+    /// Helper exited non-zero and reading `setup_error.json` failed.
+    OrchestratorHelperReportReadFailed,
+    /// Helper exited successfully before setup completed.
+    OrchestratorHelperIncomplete,
+    // Helper (elevated process) failures.
+    /// Helper failed while validating or decoding the request payload.
+    HelperRequestArgsFailed,
+    /// Helper failed to create `codex_home/.sandbox`.
+    HelperSandboxDirCreateFailed,
+    /// Helper failed to open or write the setup log.
+    HelperLogFailed,
+    /// Helper failed in the provisioning phase (fallback bucket).
+    HelperUserProvisionFailed,
+    /// Helper failed to create the sandbox users local group.
+    HelperUsersGroupCreateFailed,
+    /// Helper failed to create or update a sandbox user account.
+    HelperUserCreateOrUpdateFailed,
+    /// Helper failed to protect user passwords with DPAPI.
+    HelperDpapiProtectFailed,
+    /// Helper failed to write the sandbox users secrets file.
+    HelperUsersFileWriteFailed,
+    /// Helper failed to write or protect the setup marker file.
+    HelperSetupMarkerWriteFailed,
+    /// Helper failed to resolve a SID or convert it to a PSID.
+    HelperSidResolveFailed,
+    /// Helper failed to load or convert capability SIDs.
+    HelperCapabilitySidFailed,
+    /// Helper failed to initialize COM for firewall configuration.
+    HelperFirewallComInitFailed,
+    /// Helper failed to access firewall policy or rule collections.
+    HelperFirewallPolicyAccessFailed,
+    /// Helper detected that local firewall policy changes will not fully take effect.
+    HelperFirewallPolicyIneffective,
+    /// Helper failed to create, update, or add the firewall rule.
+    HelperFirewallRuleCreateOrAddFailed,
+    /// Helper failed to verify the configured firewall rule scope.
+    HelperFirewallRuleVerifyFailed,
+    /// Helper failed to spawn the read-ACL helper process.
+    HelperReadAclHelperSpawnFailed,
+    /// Helper failed to lock down sandbox directories via ACLs.
+    HelperSandboxLockFailed,
+    /// Helper failed for an unmapped or unexpected reason.
+    HelperUnknownError,
+}
+
+impl SetupErrorCode {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::OrchestratorSandboxDirCreateFailed => "orchestrator_sandbox_dir_create_failed",
+            Self::OrchestratorElevationCheckFailed => "orchestrator_elevation_check_failed",
+            Self::OrchestratorElevationRequired => "orchestrator_elevation_required",
+            Self::OrchestratorPayloadSerializeFailed => "orchestrator_payload_serialize_failed",
+            Self::OrchestratorHelperLaunchFailed => "orchestrator_helper_launch_failed",
+            Self::OrchestratorHelperLaunchCanceled => "orchestrator_helper_launch_canceled",
+            Self::OrchestratorHelperExitNonzero => "orchestrator_helper_exit_nonzero",
+            Self::OrchestratorHelperReportReadFailed => "orchestrator_helper_report_read_failed",
+            Self::OrchestratorHelperIncomplete => "orchestrator_helper_incomplete",
+            Self::HelperRequestArgsFailed => "helper_request_args_failed",
+            Self::HelperSandboxDirCreateFailed => "helper_sandbox_dir_create_failed",
+            Self::HelperLogFailed => "helper_log_failed",
+            Self::HelperUserProvisionFailed => "helper_user_provision_failed",
+            Self::HelperUsersGroupCreateFailed => "helper_users_group_create_failed",
+            Self::HelperUserCreateOrUpdateFailed => "helper_user_create_or_update_failed",
+            Self::HelperDpapiProtectFailed => "helper_dpapi_protect_failed",
+            Self::HelperUsersFileWriteFailed => "helper_users_file_write_failed",
+            Self::HelperSetupMarkerWriteFailed => "helper_setup_marker_write_failed",
+            Self::HelperSidResolveFailed => "helper_sid_resolve_failed",
+            Self::HelperCapabilitySidFailed => "helper_capability_sid_failed",
+            Self::HelperFirewallComInitFailed => "helper_firewall_com_init_failed",
+            Self::HelperFirewallPolicyAccessFailed => "helper_firewall_policy_access_failed",
+            Self::HelperFirewallPolicyIneffective => "helper_firewall_policy_ineffective",
+            Self::HelperFirewallRuleCreateOrAddFailed => {
+                "helper_firewall_rule_create_or_add_failed"
+            }
+            Self::HelperFirewallRuleVerifyFailed => "helper_firewall_rule_verify_failed",
+            Self::HelperReadAclHelperSpawnFailed => "helper_read_acl_helper_spawn_failed",
+            Self::HelperSandboxLockFailed => "helper_sandbox_lock_failed",
+            Self::HelperUnknownError => "helper_unknown_error",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SetupErrorReport {
+    pub code: SetupErrorCode,
+    pub message: String,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub struct SetupFailure {
+    pub code: SetupErrorCode,
+    pub message: String,
+}
+
+impl SetupFailure {
+    pub fn new(code: SetupErrorCode, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+        }
+    }
+
+    pub fn from_report(report: SetupErrorReport) -> Self {
+        Self::new(report.code, report.message)
+    }
+
+    pub fn metric_message(&self) -> String {
+        sanitize_setup_metric_tag_value(&self.message)
+    }
+}
+
+impl std::fmt::Display for SetupFailure {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}: {}", self.code.as_str(), self.message)
+    }
+}
+
+impl std::error::Error for SetupFailure {}
+
+pub fn failure(code: SetupErrorCode, message: impl Into<String>) -> anyhow::Error {
+    anyhow::Error::new(SetupFailure::new(code, message))
+}
+
+pub fn extract_failure(err: &anyhow::Error) -> Option<&SetupFailure> {
+    err.downcast_ref::<SetupFailure>()
+}
+
+pub fn setup_error_path(codex_home: &Path) -> PathBuf {
+    codex_home.join(".sandbox").join("setup_error.json")
+}
+
+pub fn clear_setup_error_report(codex_home: &Path) -> Result<()> {
+    let path = setup_error_path(codex_home);
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err).with_context(|| format!("remove {}", path.display())),
+    }
+}
+
+pub fn write_setup_error_report(codex_home: &Path, report: &SetupErrorReport) -> Result<()> {
+    let sandbox_dir = codex_home.join(".sandbox");
+    fs::create_dir_all(&sandbox_dir)
+        .with_context(|| format!("create sandbox dir {}", sandbox_dir.display()))?;
+    let path = setup_error_path(codex_home);
+    let json = serde_json::to_vec_pretty(report)?;
+    fs::write(&path, json).with_context(|| format!("write {}", path.display()))?;
+    Ok(())
+}
+
+pub fn read_setup_error_report(codex_home: &Path) -> Result<Option<SetupErrorReport>> {
+    let path = setup_error_path(codex_home);
+    let bytes = match fs::read(&path) {
+        Ok(bytes) => bytes,
+        Err(err) if err.kind() == ErrorKind::NotFound => return Ok(None),
+        Err(err) => return Err(err).with_context(|| format!("read {}", path.display())),
+    };
+    let report = serde_json::from_slice::<SetupErrorReport>(&bytes)
+        .with_context(|| format!("parse {}", path.display()))?;
+    Ok(Some(report))
+}
+
+/// Sanitize a setup error message for use as a metric tag.
+pub fn sanitize_setup_metric_tag_value(value: &str) -> String {
+    sanitize_metric_tag_value(redact_home_paths(value).as_str())
+}
+
+fn redact_home_paths(value: &str) -> String {
+    let mut usernames: Vec<String> = Vec::new();
+    if let Ok(username) = std::env::var("USERNAME")
+        && !username.trim().is_empty()
+    {
+        usernames.push(username);
+    }
+    if let Ok(user) = std::env::var("USER")
+        && !user.trim().is_empty()
+        && !usernames.iter().any(|v| v.eq_ignore_ascii_case(&user))
+    {
+        usernames.push(user);
+    }
+
+    redact_username_segments(value, &usernames)
+}
+
+fn redact_username_segments(value: &str, usernames: &[String]) -> String {
+    if usernames.is_empty() {
+        return value.to_string();
+    }
+
+    let mut segments: Vec<String> = Vec::new();
+    let mut separators: Vec<char> = Vec::new();
+    let mut current = String::new();
+
+    for ch in value.chars() {
+        if ch == '\\' || ch == '/' {
+            segments.push(std::mem::take(&mut current));
+            separators.push(ch);
+        } else {
+            current.push(ch);
+        }
+    }
+    segments.push(current);
+
+    for segment in &mut segments {
+        let matches = if cfg!(windows) {
+            usernames
+                .iter()
+                .any(|name| segment.eq_ignore_ascii_case(name))
+        } else {
+            usernames.iter().any(|name| segment == name)
+        };
+        if matches {
+            *segment = "<user>".to_string();
+        }
+    }
+
+    let mut out = String::new();
+    for (idx, segment) in segments.iter().enumerate() {
+        out.push_str(segment);
+        if let Some(sep) = separators.get(idx) {
+            out.push(*sep);
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::redact_username_segments;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn sanitize_tag_value_redacts_username_segments() {
+        let usernames = vec!["Alice".to_string(), "Bob".to_string()];
+        let msg = "failed to write C:\\Users\\Alice\\file.txt; fallback D:\\Profiles\\Bob\\x";
+        let redacted = redact_username_segments(msg, &usernames);
+        assert_eq!(
+            redacted,
+            "failed to write C:\\Users\\<user>\\file.txt; fallback D:\\Profiles\\<user>\\x"
+        );
+    }
+
+    #[test]
+    fn sanitize_tag_value_leaves_unknown_segments() {
+        let usernames = vec!["Alice".to_string()];
+        let msg = "failed to write E:\\data\\file.txt";
+        let redacted = redact_username_segments(msg, &usernames);
+        assert_eq!(redacted, msg);
+    }
+
+    #[test]
+    fn sanitize_tag_value_redacts_multiple_occurrences() {
+        let usernames = vec!["Alice".to_string()];
+        let msg = "C:\\Users\\Alice\\a and C:\\Users\\Alice\\b";
+        let redacted = redact_username_segments(msg, &usernames);
+        assert_eq!(redacted, "C:\\Users\\<user>\\a and C:\\Users\\<user>\\b");
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_launch.rs b/codex-rs/windows-sandbox-rs/src/setup_launch.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a811b6acca3c4c0c27a52edb42f8e84a56d1d287
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_launch.rs
@@ -0,0 +1,75 @@
+//! Starts provisioning helpers only after their retained directory handles are installed.
+//! The child owns its duplicates until exit, independently of the service lifetime.
+
+use std::io;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::process::CommandExt;
+use std::process::Child;
+use std::process::Command;
+use std::process::Stdio;
+use windows_sys::Win32::Foundation::DUPLICATE_SAME_ACCESS;
+use windows_sys::Win32::Foundation::DuplicateHandle;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::NTSTATUS;
+use windows_sys::Win32::Foundation::RtlNtStatusToDosError;
+use windows_sys::Win32::System::Threading::CREATE_NO_WINDOW;
+use windows_sys::Win32::System::Threading::CREATE_SUSPENDED;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+
+#[link(name = "ntdll")]
+unsafe extern "system" {
+    fn NtResumeProcess(process_handle: HANDLE) -> NTSTATUS;
+}
+
+pub(super) fn spawn_with_retained_handles(
+    command: &mut Command,
+    retained_handles: &[BorrowedHandle<'_>],
+) -> io::Result<Child> {
+    let mut child = command
+        .creation_flags(CREATE_NO_WINDOW | CREATE_SUSPENDED)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .spawn()?;
+    let initialized = (|| {
+        for handle in retained_handles {
+            let mut child_handle = 0;
+            if unsafe {
+                DuplicateHandle(
+                    GetCurrentProcess(),
+                    handle.as_raw_handle() as HANDLE,
+                    child.as_raw_handle() as HANDLE,
+                    &mut child_handle,
+                    /*dwdesiredaccess*/ 0,
+                    /*binherithandle*/ 0,
+                    DUPLICATE_SAME_ACCESS,
+                )
+            } == 0
+            {
+                return Err(io::Error::last_os_error());
+            }
+            // This value belongs to the child's handle table. Do not close it here
+            // or make it inheritable by unrelated processes or helper descendants.
+        }
+        let status = unsafe { NtResumeProcess(child.as_raw_handle() as HANDLE) };
+        if status < 0 {
+            return Err(io::Error::from_raw_os_error(
+                unsafe { RtlNtStatusToDosError(status) } as i32,
+            ));
+        }
+        Ok(())
+    })();
+    if let Err(error) = initialized {
+        // A partially initialized helper must never run after its parent drops
+        // the directory protections. Reap it, including any installed duplicates.
+        child.kill()?;
+        child.wait()?;
+        return Err(error);
+    }
+    Ok(child)
+}
+
+#[cfg(test)]
+#[path = "setup_launch_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/setup_launch_tests.rs b/codex-rs/windows-sandbox-rs/src/setup_launch_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..21968f1364df221d314999372ffb099cf11b1766
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_launch_tests.rs
@@ -0,0 +1,136 @@
+//! Exercises retained setup pins using bounded, disposable child processes.
+
+use std::fs;
+use std::io;
+use std::io::Write;
+use std::os::windows::fs::OpenOptionsExt;
+use std::os::windows::io::AsHandle;
+use std::path::PathBuf;
+use std::process::Child;
+use std::process::Command;
+use std::time::Duration;
+use std::time::Instant;
+
+use pretty_assertions::assert_eq;
+use windows_sys::Win32::Storage::FileSystem::DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_BACKUP_SEMANTICS;
+use windows_sys::Win32::Storage::FileSystem::FILE_FLAG_DELETE_ON_CLOSE;
+use windows_sys::Win32::Storage::FileSystem::FILE_READ_DATA;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+
+use super::spawn_with_retained_handles;
+
+const CHILD_TEST: &str = "setup_launch::tests::retained_handles_child";
+const CHILD_DIRECTORY_ENV: &str = "CODEX_TEST_SETUP_LAUNCH_DIRECTORY";
+const CHILD_TIMEOUT: Duration = Duration::from_secs(/*secs*/ 10);
+const POLL_INTERVAL: Duration = Duration::from_millis(/*millis*/ 10);
+
+struct ChildGuard(Child);
+
+impl Drop for ChildGuard {
+    fn drop(&mut self) {
+        let _ = self.0.kill();
+        let _ = self.0.wait();
+    }
+}
+
+#[test]
+fn child_retains_directory_pin_until_exit() -> io::Result<()> {
+    let temporary = tempfile::tempdir()?;
+    let directory = temporary.path().join("pinned");
+    let renamed_directory = temporary.path().join("renamed");
+    fs::create_dir(&directory)?;
+    let pin = fs::OpenOptions::new()
+        .read(true)
+        .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE)
+        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS)
+        .open(&directory)?;
+    let guard_path = directory.join(".guard");
+    let guard = fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .access_mode(FILE_READ_DATA | DELETE)
+        .share_mode(FILE_SHARE_READ | FILE_SHARE_WRITE)
+        .custom_flags(FILE_FLAG_DELETE_ON_CLOSE)
+        .open(&guard_path)?;
+    let mut command = Command::new(std::env::current_exe()?);
+    command
+        .args(["--exact", CHILD_TEST, "--ignored"])
+        .env(CHILD_DIRECTORY_ENV, temporary.path());
+    let mut child = ChildGuard(spawn_with_retained_handles(
+        &mut command,
+        &[pin.as_handle(), guard.as_handle()],
+    )?);
+    drop(pin);
+    drop(guard);
+
+    let started = Instant::now();
+    while !temporary.path().join("ready").exists() {
+        assert_eq!(
+            child.0.try_wait()?,
+            None,
+            "child exited before becoming ready"
+        );
+        assert!(
+            started.elapsed() < CHILD_TIMEOUT,
+            "child did not become ready"
+        );
+        std::thread::sleep(POLL_INTERVAL);
+    }
+    assert!(
+        fs::rename(&directory, &renamed_directory).is_err(),
+        "the child's duplicate must keep the directory pinned after the parent drops its handle"
+    );
+    assert_eq!(child.0.try_wait()?, None);
+    assert!(guard_path.exists(), "the child must retain the guard file");
+
+    fs::write(temporary.path().join("release"), b"")?;
+    let started = Instant::now();
+    let status = loop {
+        if let Some(status) = child.0.try_wait()? {
+            break status;
+        }
+        assert!(started.elapsed() < CHILD_TIMEOUT, "child did not exit");
+        std::thread::sleep(POLL_INTERVAL);
+    };
+    assert!(status.success(), "child failed: {status}");
+    assert!(
+        !guard_path.exists(),
+        "the guard must be deleted on child exit"
+    );
+    fs::rename(&directory, &renamed_directory)?;
+    Ok(())
+}
+
+#[test]
+fn missing_executable_returns_spawn_error_without_closing_retained_handles() -> io::Result<()> {
+    let temporary = tempfile::tempdir()?;
+    let mut retained_file = tempfile::tempfile()?;
+    let mut command = Command::new(temporary.path().join("missing.exe"));
+
+    let error = spawn_with_retained_handles(&mut command, &[retained_file.as_handle()])
+        .expect_err("missing executable must fail to spawn");
+
+    assert_eq!(error.kind(), io::ErrorKind::NotFound);
+    retained_file.write_all(b"the caller still owns its handle")?;
+    Ok(())
+}
+
+#[test]
+#[ignore = "child process for child_retains_directory_pin_until_exit"]
+fn retained_handles_child() -> io::Result<()> {
+    let Some(directory) = std::env::var_os(CHILD_DIRECTORY_ENV).map(PathBuf::from) else {
+        return Ok(());
+    };
+    fs::write(directory.join("ready"), b"")?;
+    let started = Instant::now();
+    while !directory.join("release").exists() {
+        assert!(
+            started.elapsed() < CHILD_TIMEOUT,
+            "parent did not release child"
+        );
+        std::thread::sleep(POLL_INTERVAL);
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_mutex.rs b/codex-rs/windows-sandbox-rs/src/setup_mutex.rs
new file mode 100644
index 0000000000000000000000000000000000000000..dcb8f6f0c17abe650bcae81f04ab0d59d6fa0ea6
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_mutex.rs
@@ -0,0 +1,83 @@
+//! Serializes sandbox account and network changes across setup and uninstall.
+//! The acquiring thread must hold the lock until those changes finish.
+
+use std::io;
+use std::marker::PhantomData;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::ptr::null_mut;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Foundation::WAIT_ABANDONED;
+use windows_sys::Win32::Foundation::WAIT_OBJECT_0;
+use windows_sys::Win32::Foundation::WAIT_TIMEOUT;
+use windows_sys::Win32::Security::Authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW;
+use windows_sys::Win32::Security::SECURITY_ATTRIBUTES;
+use windows_sys::Win32::System::Threading::CreateMutexW;
+use windows_sys::Win32::System::Threading::ReleaseMutex;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+use crate::winutil::to_wide;
+
+/// Holds the machine-wide setup lock on the thread that acquired it.
+#[must_use]
+pub struct SandboxSetupLock {
+    handle: OwnedHandle,
+    _thread_bound: PhantomData<*mut ()>,
+}
+
+impl Drop for SandboxSetupLock {
+    fn drop(&mut self) {
+        unsafe {
+            ReleaseMutex(self.handle.as_raw_handle() as HANDLE);
+        }
+    }
+}
+
+/// Waits up to `timeout_ms` for exclusive access by LocalSystem or an elevated administrator.
+pub fn acquire_sandbox_setup_lock(timeout_ms: u32) -> Result<SandboxSetupLock> {
+    let sddl = to_wide("D:P(A;;GA;;;SY)(A;;GA;;;BA)");
+    let mut descriptor = null_mut();
+    if unsafe {
+        ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            sddl.as_ptr(),
+            /*stringsdrevision*/ 1,
+            &mut descriptor,
+            null_mut(),
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error()).context("create sandbox setup mutex security");
+    }
+    let attributes = SECURITY_ATTRIBUTES {
+        nLength: size_of::<SECURITY_ATTRIBUTES>() as u32,
+        lpSecurityDescriptor: descriptor,
+        bInheritHandle: 0,
+    };
+    let name = to_wide(r"Global\CodexSandboxSetup");
+    let handle = unsafe {
+        CreateMutexW(&attributes, /*binitialowner*/ 0, name.as_ptr())
+    };
+    let result = if handle == 0 {
+        Err(io::Error::last_os_error())
+    } else {
+        Ok(unsafe { OwnedHandle::from_raw_handle(handle as _) })
+    };
+    unsafe { LocalFree(descriptor as HLOCAL) };
+    let handle = result.context("open sandbox setup mutex")?;
+    match unsafe { WaitForSingleObject(handle.as_raw_handle() as HANDLE, timeout_ms) } {
+        // A crashed owner releases the lock; setup still repairs any incomplete account changes.
+        WAIT_OBJECT_0 | WAIT_ABANDONED => Ok(SandboxSetupLock {
+            handle,
+            _thread_bound: PhantomData,
+        }),
+        WAIT_TIMEOUT => bail!("timed out waiting for sandbox setup mutex after {timeout_ms} ms"),
+        _ => Err(io::Error::last_os_error()).context("wait for sandbox setup mutex"),
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6b003f09d67d9ef45c6f19892a7788cc4d72f7ea
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning.rs
@@ -0,0 +1,1468 @@
+//! Privileged sandbox setup shared by the setup helper and the service's ProvisionOnly path.
+//! Full and read-ACL setup remain helper entrypoints; only they may launch a read-ACL child.
+//! Command-line account provisioning cannot enter the service's admitted Core path.
+
+mod firewall;
+mod service;
+pub use service::provision_sandbox_in_process;
+mod read_acl_mutex;
+
+use crate::DirectoryOpenDisposition;
+use crate::SETUP_VERSION;
+use crate::SetupErrorCode;
+use crate::SetupErrorReport;
+use crate::SetupFailure;
+use crate::SetupRuntime;
+use crate::acquire_sandbox_setup_lock;
+use crate::add_deny_write_ace;
+use crate::convert_string_sid_to_sid;
+use crate::ensure_allow_mask_aces_with_inheritance;
+use crate::ensure_allow_write_aces;
+use crate::extract_setup_failure;
+use crate::hide_newly_created_users;
+use crate::install_wfp_filters;
+use crate::local_user_flags;
+use crate::log_note;
+use crate::log_writer;
+use crate::open_directory_no_reparse;
+use crate::path_mask_allows;
+use crate::path_write_aces_need_refresh;
+use crate::resolve_sid;
+use crate::sandbox_bin_dir;
+use crate::sandbox_dir;
+use crate::sandbox_secrets_dir;
+use crate::set_local_user_flags;
+use crate::setup_error_path;
+use crate::setup_log_writer;
+use crate::string_from_sid_bytes;
+use crate::sync_persistent_deny_read_acls;
+use crate::to_wide;
+use crate::workspace_write_cap_sid_for_root;
+use crate::workspace_write_root_overlaps_path;
+use crate::write_file_atomically;
+use crate::write_setup_error_report;
+use anyhow::Context;
+use anyhow::Result;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use codex_otel::StatsigMetricsSettings;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashSet;
+use std::ffi::OsStr;
+use std::ffi::c_void;
+use std::io::Write;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::process::CommandExt;
+use std::path::Path;
+use std::path::PathBuf;
+use std::process::Command;
+use std::process::Stdio;
+use std::sync::mpsc;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_ACCOUNTDISABLE;
+use windows_sys::Win32::Security::ACL;
+use windows_sys::Win32::Security::Authorization::ConvertStringSidToSidW;
+use windows_sys::Win32::Security::Authorization::EXPLICIT_ACCESS_W;
+use windows_sys::Win32::Security::Authorization::GRANT_ACCESS;
+use windows_sys::Win32::Security::Authorization::SE_FILE_OBJECT;
+use windows_sys::Win32::Security::Authorization::SetEntriesInAclW;
+use windows_sys::Win32::Security::Authorization::SetNamedSecurityInfoW;
+use windows_sys::Win32::Security::Authorization::SetSecurityInfo;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_SID;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_W;
+use windows_sys::Win32::Security::CONTAINER_INHERIT_ACE;
+use windows_sys::Win32::Security::DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Security::OBJECT_INHERIT_ACE;
+use windows_sys::Win32::Security::PROTECTED_DACL_SECURITY_INFORMATION;
+use windows_sys::Win32::Storage::FileSystem::DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_EXECUTE;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_WRITE;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_DELETE;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_READ;
+use windows_sys::Win32::Storage::FileSystem::FILE_SHARE_WRITE;
+use windows_sys::Win32::Storage::FileSystem::READ_CONTROL;
+use windows_sys::Win32::Storage::FileSystem::WRITE_DAC;
+use windows_sys::Win32::System::Threading::INFINITE;
+
+const DENY_ACCESS: i32 = 3;
+#[cfg(test)]
+const WRITE_ROOT_ALLOW_MASK: u32 =
+    FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE;
+
+mod sandbox_users;
+mod setup_runtime_bin;
+use read_acl_mutex::acquire_read_acl_mutex;
+use read_acl_mutex::read_acl_mutex_exists;
+use sandbox_users::commit_setup_marker;
+use sandbox_users::prepare_setup_marker;
+use sandbox_users::provision_sandbox_users;
+use sandbox_users::resolve_sandbox_users_group_sid;
+use sandbox_users::sid_bytes_to_psid;
+
+// Legacy omits runtime; readers default its absence to Legacy.
+#[derive(Debug, Clone, Deserialize, Serialize)]
+struct Payload {
+    version: u32,
+    offline_username: String,
+    online_username: String,
+    codex_home: PathBuf,
+    command_cwd: PathBuf,
+    read_roots: Vec<PathBuf>,
+    write_roots: Vec<PathBuf>,
+    #[serde(default)]
+    deny_read_paths: Vec<PathBuf>,
+    #[serde(default)]
+    deny_write_paths: Vec<PathBuf>,
+    proxy_ports: Vec<u16>,
+    #[serde(default)]
+    allow_local_binding: bool,
+    #[serde(default)]
+    otel: Option<StatsigMetricsSettings>,
+    real_user: String,
+    #[serde(default)]
+    mode: SetupMode,
+    #[serde(default, skip_serializing_if = "SetupRuntime::is_legacy")]
+    runtime: SetupRuntime,
+    #[serde(default)]
+    refresh_only: bool,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "kebab-case")]
+enum SetupMode {
+    #[default]
+    Full,
+    InteractiveProvision,
+    ProvisionOnly,
+    ReadAclsOnly,
+}
+
+impl SetupMode {
+    fn provisions_accounts(self, refresh_only: bool) -> bool {
+        match self {
+            Self::ProvisionOnly | Self::InteractiveProvision => true,
+            Self::Full => !refresh_only,
+            Self::ReadAclsOnly => false,
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+enum DaclInheritance {
+    Inherited,
+    Protected,
+}
+
+fn log_line(log: &mut dyn Write, msg: &str) -> Result<()> {
+    let ts = chrono::Utc::now().to_rfc3339();
+    writeln!(log, "[{ts}] {msg}").map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperLogFailed,
+            format!("failed to write setup log line: {err}"),
+        ))
+    })?;
+    Ok(())
+}
+
+fn workspace_write_cap_sids_for_path(
+    codex_home: &Path,
+    command_cwd: &Path,
+    write_roots: &[PathBuf],
+    path: &Path,
+) -> Result<Vec<String>> {
+    let mut sid_strs = Vec::new();
+    for root in write_roots {
+        if workspace_write_root_overlaps_path(root, path) {
+            sid_strs.push(workspace_write_cap_sid_for_root(
+                codex_home,
+                command_cwd,
+                root,
+            )?);
+        }
+    }
+    if sid_strs.is_empty() {
+        if write_roots.is_empty() {
+            sid_strs.push(workspace_write_cap_sid_for_root(
+                codex_home,
+                command_cwd,
+                command_cwd,
+            )?);
+        } else {
+            for root in write_roots {
+                sid_strs.push(workspace_write_cap_sid_for_root(
+                    codex_home,
+                    command_cwd,
+                    root,
+                )?);
+            }
+        }
+    }
+    Ok(sid_strs)
+}
+
+fn spawn_read_acl_helper(payload: &Payload, _log: &mut dyn Write) -> Result<()> {
+    let mut read_payload = payload.clone();
+    read_payload.mode = SetupMode::ReadAclsOnly;
+    read_payload.refresh_only = true;
+    let payload_json = serde_json::to_vec(&read_payload)?;
+    let payload_b64 = BASE64.encode(payload_json);
+    let exe = std::env::current_exe().context("locate setup helper")?;
+    Command::new(&exe)
+        .arg(payload_b64)
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .creation_flags(0x08000000) // CREATE_NO_WINDOW
+        .spawn()
+        .context("spawn read ACL helper")?;
+    Ok(())
+}
+
+struct ReadAclSubjects<'a> {
+    sandbox_group_psid: *mut c_void,
+    rx_psids: &'a [*mut c_void],
+}
+
+fn apply_read_acls(
+    read_roots: &[PathBuf],
+    subjects: &ReadAclSubjects<'_>,
+    log: &mut dyn Write,
+    refresh_errors: &mut Vec<String>,
+    access_mask: u32,
+    access_label: &str,
+    inheritance: u32,
+) -> Result<()> {
+    for root in read_roots {
+        if !root.exists() {
+            log_line(
+                log,
+                &format!("{access_label} root {} missing; skipping", root.display()),
+            )?;
+            continue;
+        }
+        let builtin_has = read_mask_allows_or_log(
+            root,
+            subjects.rx_psids,
+            /*label*/ None,
+            access_mask,
+            access_label,
+            refresh_errors,
+            log,
+        )?;
+        if builtin_has {
+            continue;
+        }
+        let sandbox_has = read_mask_allows_or_log(
+            root,
+            &[subjects.sandbox_group_psid],
+            Some("sandbox_group"),
+            access_mask,
+            access_label,
+            refresh_errors,
+            log,
+        )?;
+        if sandbox_has {
+            continue;
+        }
+        log_line(
+            log,
+            &format!(
+                "granting {access_label} ACE to {} for sandbox users",
+                root.display()
+            ),
+        )?;
+        let result = unsafe {
+            ensure_allow_mask_aces_with_inheritance(
+                root,
+                &[subjects.sandbox_group_psid],
+                access_mask,
+                inheritance,
+            )
+        };
+        if let Err(err) = result {
+            refresh_errors.push(format!(
+                "grant {access_label} ACE failed on {} for sandbox_group: {err}",
+                root.display()
+            ));
+            log_line(
+                log,
+                &format!(
+                    "grant {access_label} ACE failed on {} for sandbox_group: {err}",
+                    root.display()
+                ),
+            )?;
+        }
+    }
+    Ok(())
+}
+
+fn read_mask_allows_or_log(
+    root: &Path,
+    psids: &[*mut c_void],
+    label: Option<&str>,
+    read_mask: u32,
+    access_label: &str,
+    refresh_errors: &mut Vec<String>,
+    log: &mut dyn Write,
+) -> Result<bool> {
+    match path_mask_allows(root, psids, read_mask, /*require_all_bits*/ true) {
+        Ok(has) => Ok(has),
+        Err(e) => {
+            let label_suffix = label
+                .map(|value| format!(" for {value}"))
+                .unwrap_or_default();
+            refresh_errors.push(format!(
+                "{access_label} mask check failed on {}{}: {}",
+                root.display(),
+                label_suffix,
+                e
+            ));
+            log_line(
+                log,
+                &format!(
+                    "{access_label} mask check failed on {}{}: {}; continuing",
+                    root.display(),
+                    label_suffix,
+                    e
+                ),
+            )?;
+            Ok(false)
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn lock_sandbox_dir(
+    dir: &Path,
+    real_user: &str,
+    sandbox_group_sid: &[u8],
+    sandbox_group_access_mode: i32,
+    sandbox_group_mask: u32,
+    real_user_mask: u32,
+    dacl_inheritance: DaclInheritance,
+    setup_mode: SetupMode,
+) -> Result<()> {
+    // ProvisionOnly accepts another user's CODEX_HOME; keep its ACL mutation
+    // bound to a no-reparse handle without changing interactive setup behavior.
+    let directory = match setup_mode {
+        SetupMode::Full | SetupMode::InteractiveProvision | SetupMode::ReadAclsOnly => {
+            std::fs::create_dir_all(dir)?;
+            None
+        }
+        SetupMode::ProvisionOnly => Some(open_directory_no_reparse(
+            dir,
+            // SetSecurityInfo can reject a WRITE_DAC-only directory handle.
+            READ_CONTROL | WRITE_DAC,
+            FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+            DirectoryOpenDisposition::OpenOrCreate,
+        )?),
+    };
+    let system_sid = resolve_sid("SYSTEM")?;
+    let admins_sid = resolve_sid("Administrators")?;
+    let real_sid = resolve_sid(real_user)?;
+    let entries = [
+        (
+            sandbox_group_sid.to_vec(),
+            sandbox_group_mask,
+            sandbox_group_access_mode,
+        ),
+        (
+            system_sid,
+            FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE,
+            GRANT_ACCESS,
+        ),
+        (
+            admins_sid,
+            FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE,
+            GRANT_ACCESS,
+        ),
+        (real_sid, real_user_mask, GRANT_ACCESS),
+    ];
+    unsafe {
+        let mut eas: Vec<EXPLICIT_ACCESS_W> = Vec::new();
+        let mut sids: Vec<*mut c_void> = Vec::new();
+        for (sid_bytes, mask, access_mode) in entries.iter().map(|(s, m, a)| (s, *m, *a)) {
+            let sid_str = string_from_sid_bytes(sid_bytes).map_err(anyhow::Error::msg)?;
+            let sid_w = to_wide(OsStr::new(&sid_str));
+            let mut psid: *mut c_void = std::ptr::null_mut();
+            if ConvertStringSidToSidW(sid_w.as_ptr(), &mut psid) == 0 {
+                return Err(anyhow::anyhow!(
+                    "ConvertStringSidToSidW failed: {}",
+                    GetLastError()
+                ));
+            }
+            sids.push(psid);
+            eas.push(EXPLICIT_ACCESS_W {
+                grfAccessPermissions: mask,
+                grfAccessMode: access_mode,
+                grfInheritance: OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE,
+                Trustee: TRUSTEE_W {
+                    pMultipleTrustee: std::ptr::null_mut(),
+                    MultipleTrusteeOperation: 0,
+                    TrusteeForm: TRUSTEE_IS_SID,
+                    TrusteeType: TRUSTEE_IS_SID,
+                    ptstrName: psid as *mut u16,
+                },
+            });
+        }
+        let mut new_dacl: *mut ACL = std::ptr::null_mut();
+        let set = SetEntriesInAclW(
+            eas.len() as u32,
+            eas.as_ptr(),
+            std::ptr::null_mut(),
+            &mut new_dacl,
+        );
+        if set != 0 {
+            return Err(anyhow::anyhow!(
+                "SetEntriesInAclW sandbox dir failed: {set}",
+            ));
+        }
+        let security_information = match dacl_inheritance {
+            DaclInheritance::Inherited => DACL_SECURITY_INFORMATION,
+            DaclInheritance::Protected => {
+                DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION
+            }
+        };
+        let (res, api) = match directory.as_ref() {
+            Some(directory) => (
+                SetSecurityInfo(
+                    directory.as_raw_handle() as _,
+                    SE_FILE_OBJECT,
+                    security_information,
+                    std::ptr::null_mut(),
+                    std::ptr::null_mut(),
+                    new_dacl,
+                    std::ptr::null_mut(),
+                ),
+                "SetSecurityInfo",
+            ),
+            None => {
+                let path_w = to_wide(dir.as_os_str());
+                (
+                    SetNamedSecurityInfoW(
+                        path_w.as_ptr() as *mut u16,
+                        SE_FILE_OBJECT,
+                        security_information,
+                        std::ptr::null_mut(),
+                        std::ptr::null_mut(),
+                        new_dacl,
+                        std::ptr::null_mut(),
+                    ),
+                    "SetNamedSecurityInfoW",
+                )
+            }
+        };
+        if res != 0 {
+            return Err(anyhow::anyhow!("{api} sandbox dir failed: {res}"));
+        }
+        if !new_dacl.is_null() {
+            LocalFree(new_dacl as HLOCAL);
+        }
+        for sid in sids {
+            if !sid.is_null() {
+                LocalFree(sid as HLOCAL);
+            }
+        }
+    }
+    Ok(())
+}
+
+pub fn main() -> Result<()> {
+    let mut setup_mode = None;
+    let ret = real_main(&mut setup_mode);
+    if let Err(e) = &ret {
+        // Best-effort: log unexpected top-level errors.
+        if let Ok(codex_home) = std::env::var("CODEX_HOME") {
+            let sbx_dir = sandbox_dir(Path::new(&codex_home));
+            let _ = std::fs::create_dir_all(&sbx_dir);
+            // An unparsed payload must not enable writes to an existing log.
+            let mode = setup_mode.unwrap_or(SetupMode::ProvisionOnly);
+            if let Ok(mut f) = open_setup_log(&sbx_dir, mode) {
+                let _ = writeln!(
+                    f,
+                    "[{}] top-level error: {}",
+                    chrono::Utc::now().to_rfc3339(),
+                    e
+                );
+            }
+        }
+    }
+    ret
+}
+
+fn open_setup_log(sbx_dir: &Path, mode: SetupMode) -> Result<Box<dyn Write>> {
+    match mode {
+        SetupMode::ProvisionOnly => Ok(Box::new(setup_log_writer(sbx_dir)?)),
+        SetupMode::Full | SetupMode::InteractiveProvision | SetupMode::ReadAclsOnly => {
+            log_writer(sbx_dir)
+                .map(|log| Box::new(log) as Box<dyn Write>)
+                .context("open daily sandbox log")
+        }
+    }
+}
+
+fn real_main(setup_mode: &mut Option<SetupMode>) -> Result<()> {
+    let mut args = std::env::args().collect::<Vec<_>>();
+    if args.len() != 2 {
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperRequestArgsFailed,
+            "expected payload argument",
+        )));
+    }
+    let payload_b64 = args.remove(1);
+    let payload_json = BASE64.decode(payload_b64).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperRequestArgsFailed,
+            format!("failed to decode payload b64: {err}"),
+        ))
+    })?;
+    let payload: Payload = serde_json::from_slice(&payload_json).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperRequestArgsFailed,
+            format!("failed to parse payload json: {err}"),
+        ))
+    })?;
+    *setup_mode = Some(payload.mode);
+    if payload.version != SETUP_VERSION {
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperRequestArgsFailed,
+            format!(
+                "setup version mismatch: expected {SETUP_VERSION}, got {}",
+                payload.version
+            ),
+        )));
+    }
+    // Only this entry parses command-line JSON. Keep admission locked through
+    // the entire account-provisioning operation, including initial Full setup.
+    // The in-process adapter enters separately after authenticated service admission.
+    let _setup_guard = if payload.mode.provisions_accounts(payload.refresh_only) {
+        let guard = acquire_sandbox_setup_lock(INFINITE)?;
+        anyhow::ensure!(
+            payload.runtime == SetupRuntime::Legacy && !crate::registered_core_requested(),
+            "registered Core requires service-owned provisioning"
+        );
+        anyhow::ensure!(
+            crate::runtime_ownership::load_installation()?
+                .is_none_or(|record| record.runtime.is_none()),
+            "registered Core owns these sandbox accounts; helper provisioning is not permitted"
+        );
+        Some(guard)
+    } else {
+        None
+    };
+    run_payload(&payload)
+}
+
+fn run_payload(payload: &Payload) -> Result<()> {
+    let sbx_dir = sandbox_dir(&payload.codex_home);
+    std::fs::create_dir_all(&sbx_dir).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSandboxDirCreateFailed,
+            format!("failed to create sandbox dir {}: {err}", sbx_dir.display()),
+        ))
+    })?;
+    let mut log = open_setup_log(&sbx_dir, payload.mode).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperLogFailed,
+            format!("open log in {} failed: {err}", sbx_dir.display()),
+        ))
+    })?;
+    let result = run_setup(payload, &mut log, &sbx_dir);
+    if let Err(err) = &result {
+        let _ = log_line(&mut log, &format!("setup error: {err:?}"));
+        log_note(&format!("setup error: {err:?}"), Some(sbx_dir.as_path()));
+        let failure = extract_setup_failure(err)
+            .map(|f| SetupFailure::new(f.code, f.message.clone()))
+            .unwrap_or_else(|| {
+                SetupFailure::new(SetupErrorCode::HelperUnknownError, err.to_string())
+            });
+        let report = SetupErrorReport {
+            code: failure.code,
+            message: failure.message,
+        };
+        let write_report = match payload.mode {
+            SetupMode::ProvisionOnly => serde_json::to_vec_pretty(&report)
+                .map_err(anyhow::Error::from)
+                .and_then(|json| {
+                    write_file_atomically(&setup_error_path(&payload.codex_home), &json)
+                }),
+            SetupMode::Full | SetupMode::InteractiveProvision | SetupMode::ReadAclsOnly => {
+                write_setup_error_report(&payload.codex_home, &report)
+            }
+        };
+        if let Err(write_err) = write_report {
+            let _ = log_line(
+                &mut log,
+                &format!("setup error report write failed: {write_err}"),
+            );
+            log_note(
+                &format!("setup error report write failed: {write_err}"),
+                Some(sbx_dir.as_path()),
+            );
+        }
+    }
+    result
+}
+
+fn run_setup(payload: &Payload, log: &mut dyn Write, sbx_dir: &Path) -> Result<()> {
+    let writes_setup_marker = !payload.refresh_only && payload.mode != SetupMode::ReadAclsOnly;
+    let marker = if writes_setup_marker {
+        Some(prepare_setup_marker(
+            &payload.codex_home,
+            &payload.real_user,
+            payload.mode,
+        )?)
+    } else {
+        None
+    };
+    match payload.mode {
+        SetupMode::ReadAclsOnly => run_read_acl_only(payload, log),
+        SetupMode::InteractiveProvision | SetupMode::ProvisionOnly => {
+            run_provision_only(payload, log, sbx_dir)
+        }
+        SetupMode::Full => run_setup_full(payload, log, sbx_dir),
+    }?;
+    if let Some(marker) = marker {
+        commit_setup_marker(
+            marker,
+            &payload.codex_home,
+            &payload.offline_username,
+            &payload.online_username,
+            &payload.proxy_ports,
+            payload.allow_local_binding,
+        )?;
+    }
+    Ok(())
+}
+
+fn run_read_acl_only(payload: &Payload, log: &mut dyn Write) -> Result<()> {
+    let _read_acl_guard = match acquire_read_acl_mutex()? {
+        Some(guard) => guard,
+        None => {
+            log_line(log, "read ACL helper already running; skipping")?;
+            return Ok(());
+        }
+    };
+    log_line(log, "read-acl-only mode: applying read ACLs")?;
+    let sandbox_group_sid = resolve_sandbox_users_group_sid()?;
+    let sandbox_group_psid = sid_bytes_to_psid(&sandbox_group_sid)?;
+    let mut refresh_errors: Vec<String> = Vec::new();
+    if !payload.read_roots.is_empty() {
+        let users_sid = resolve_sid("Users")?;
+        let users_psid = sid_bytes_to_psid(&users_sid)?;
+        let auth_sid = resolve_sid("Authenticated Users")?;
+        let auth_psid = sid_bytes_to_psid(&auth_sid)?;
+        let everyone_sid = resolve_sid("Everyone")?;
+        let everyone_psid = sid_bytes_to_psid(&everyone_sid)?;
+        let rx_psids = vec![users_psid, auth_psid, everyone_psid];
+        let subjects = ReadAclSubjects {
+            sandbox_group_psid,
+            rx_psids: &rx_psids,
+        };
+        apply_read_acls(
+            &payload.read_roots,
+            &subjects,
+            log,
+            &mut refresh_errors,
+            FILE_GENERIC_READ | FILE_GENERIC_EXECUTE,
+            "read",
+            OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE,
+        )?;
+        unsafe {
+            if !users_psid.is_null() {
+                LocalFree(users_psid as HLOCAL);
+            }
+            if !auth_psid.is_null() {
+                LocalFree(auth_psid as HLOCAL);
+            }
+            if !everyone_psid.is_null() {
+                LocalFree(everyone_psid as HLOCAL);
+            }
+        }
+    }
+    unsafe {
+        if !sandbox_group_psid.is_null() {
+            LocalFree(sandbox_group_psid as HLOCAL);
+        }
+    }
+    if !refresh_errors.is_empty() {
+        log_line(
+            log,
+            &format!("read ACL run completed with errors: {refresh_errors:?}"),
+        )?;
+        if payload.refresh_only {
+            anyhow::bail!("read ACL run had errors");
+        }
+    }
+    log_line(log, "read ACL run completed")?;
+    Ok(())
+}
+
+fn provision_sandbox(payload: &Payload, log: &mut dyn Write, sbx_dir: &Path) -> Result<()> {
+    let _setup_lock = acquire_sandbox_setup_lock(INFINITE)?;
+    let mut repairing_disabled_accounts = false;
+    for username in [&payload.offline_username, &payload.online_username] {
+        if local_user_flags(username)?.is_some_and(|flags| flags & UF_ACCOUNTDISABLE != 0) {
+            repairing_disabled_accounts = true;
+        }
+    }
+    // Interrupted cleanup can leave one account missing and the other disabled. Keep any
+    // replacement disabled too until this repair has restored the network restrictions.
+    let new_user_flags = if repairing_disabled_accounts {
+        UF_ACCOUNTDISABLE
+    } else {
+        0
+    };
+    let provision_result = provision_sandbox_users(
+        &payload.codex_home,
+        &payload.offline_username,
+        &payload.online_username,
+        new_user_flags,
+        log,
+        payload.mode,
+    );
+    if let Err(err) = provision_result {
+        if extract_setup_failure(&err).is_some() {
+            return Err(err);
+        }
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperUserProvisionFailed,
+            format!("provision sandbox users failed: {err}"),
+        )));
+    }
+    let users = vec![
+        payload.offline_username.clone(),
+        payload.online_username.clone(),
+    ];
+    hide_newly_created_users(&users, sbx_dir);
+    let offline_sid = resolve_sid(&payload.offline_username).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSidResolveFailed,
+            format!(
+                "resolve SID for offline user {} failed: {err}",
+                payload.offline_username
+            ),
+        ))
+    })?;
+    let offline_sid_str = string_from_sid_bytes(&offline_sid).map_err(anyhow::Error::msg)?;
+    configure_offline_sandbox_network(payload, &offline_sid_str, log)?;
+    let wfp_result = install_wfp_filters(
+        &payload.codex_home,
+        &payload.offline_username,
+        payload.otel.as_ref(),
+        |message| {
+            let _ = log_line(log, message);
+        },
+    );
+    if repairing_disabled_accounts {
+        // Ordinary setup keeps its best-effort WFP behavior. Recovery must not reopen logons
+        // after cleanup removed protections unless restoring those protections succeeded.
+        wfp_result?;
+        for username in [&payload.offline_username, &payload.online_username] {
+            let flags = local_user_flags(username)?.ok_or_else(|| {
+                anyhow::anyhow!("sandbox user {username} disappeared during repair")
+            })?;
+            set_local_user_flags(username, flags & !UF_ACCOUNTDISABLE)?;
+        }
+    }
+    Ok(())
+}
+
+fn configure_offline_sandbox_network(
+    payload: &Payload,
+    offline_sid_str: &str,
+    log: &mut dyn Write,
+) -> Result<()> {
+    let proxy_allowlist_result = firewall::ensure_offline_proxy_allowlist(
+        offline_sid_str,
+        &payload.proxy_ports,
+        payload.allow_local_binding,
+        log,
+    );
+    if let Err(err) = proxy_allowlist_result {
+        if extract_setup_failure(&err).is_some() {
+            return Err(err);
+        }
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+            format!("ensure offline proxy allowlist failed: {err}"),
+        )));
+    }
+    let firewall_result = firewall::ensure_offline_network_blocks(offline_sid_str, log);
+    if let Err(err) = firewall_result {
+        if extract_setup_failure(&err).is_some() {
+            return Err(err);
+        }
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+            format!("ensure offline network blocks failed: {err}"),
+        )));
+    }
+    Ok(())
+}
+
+fn lock_persistent_sandbox_dirs(payload: &Payload, sandbox_group_sid: &[u8]) -> Result<()> {
+    lock_sandbox_dir(
+        &sandbox_dir(&payload.codex_home),
+        &payload.real_user,
+        sandbox_group_sid,
+        GRANT_ACCESS,
+        FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE,
+        FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE,
+        DaclInheritance::Inherited,
+        payload.mode,
+    )
+    .map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSandboxLockFailed,
+            format!(
+                "lock sandbox dir {} failed: {err}",
+                sandbox_dir(&payload.codex_home).display()
+            ),
+        ))
+    })?;
+    lock_sandbox_dir(
+        &sandbox_secrets_dir(&payload.codex_home),
+        &payload.real_user,
+        sandbox_group_sid,
+        DENY_ACCESS,
+        FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE,
+        FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE,
+        DaclInheritance::Inherited,
+        payload.mode,
+    )
+    .map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSandboxLockFailed,
+            format!(
+                "lock sandbox secrets dir {} failed: {err}",
+                sandbox_secrets_dir(&payload.codex_home).display()
+            ),
+        ))
+    })?;
+    let legacy_users = sandbox_dir(&payload.codex_home).join("sandbox_users.json");
+    if legacy_users.exists() {
+        let _ = std::fs::remove_file(&legacy_users);
+    }
+    Ok(())
+}
+
+fn lock_sandbox_bin_dir(payload: &Payload, sandbox_group_sid: &[u8]) -> Result<()> {
+    if payload.runtime == SetupRuntime::Registered {
+        return Ok(());
+    }
+    // The owner's unelevated refresh must be able to reapply this protected DACL.
+    lock_sandbox_dir(
+        &sandbox_bin_dir(&payload.codex_home),
+        &payload.real_user,
+        sandbox_group_sid,
+        GRANT_ACCESS,
+        FILE_GENERIC_READ | FILE_GENERIC_EXECUTE,
+        FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE | WRITE_DAC,
+        DaclInheritance::Protected,
+        payload.mode,
+    )
+    .map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSandboxLockFailed,
+            format!(
+                "lock sandbox bin dir {} failed: {err}",
+                sandbox_bin_dir(&payload.codex_home).display()
+            ),
+        ))
+    })
+}
+
+fn run_provision_only(payload: &Payload, log: &mut dyn Write, sbx_dir: &Path) -> Result<()> {
+    provision_sandbox(payload, log, sbx_dir)?;
+
+    let sandbox_group_sid = resolve_sandbox_users_group_sid().map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSidResolveFailed,
+            format!("resolve sandbox users group SID failed: {err}"),
+        ))
+    })?;
+
+    lock_sandbox_bin_dir(payload, &sandbox_group_sid)?;
+    lock_persistent_sandbox_dirs(payload, &sandbox_group_sid)?;
+    log_note("setup provisioning binary completed", Some(sbx_dir));
+    Ok(())
+}
+
+fn run_setup_full(payload: &Payload, log: &mut dyn Write, sbx_dir: &Path) -> Result<()> {
+    let refresh_only = payload.refresh_only;
+    if !refresh_only {
+        provision_sandbox(payload, log, sbx_dir)?;
+    }
+
+    let sandbox_group_sid = resolve_sandbox_users_group_sid().map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSidResolveFailed,
+            format!("resolve sandbox users group SID failed: {err}"),
+        ))
+    })?;
+    let sandbox_group_psid = sid_bytes_to_psid(&sandbox_group_sid).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSidResolveFailed,
+            format!("convert sandbox users group SID to PSID failed: {err}"),
+        ))
+    })?;
+    let sandbox_group_sid_str =
+        string_from_sid_bytes(&sandbox_group_sid).map_err(anyhow::Error::msg)?;
+
+    let mut refresh_errors: Vec<String> = Vec::new();
+
+    // Deny-read ACEs must be present before the sandboxed command starts. Apply
+    // them synchronously here instead of delegating them to the background
+    // helper used for read grants.
+    let applied_deny_read_paths = unsafe {
+        sync_persistent_deny_read_acls(
+            &payload.codex_home,
+            &sandbox_group_sid_str,
+            &payload.deny_read_paths,
+            sandbox_group_psid,
+        )
+    }
+    .context("apply deny-read ACLs")?;
+    if !applied_deny_read_paths.is_empty() {
+        log_line(
+            log,
+            &format!("applied {} deny-read ACLs", applied_deny_read_paths.len()),
+        )?;
+    }
+
+    if payload.read_roots.is_empty() {
+        log_line(log, "no read roots to grant; skipping read ACL helper")?;
+    } else {
+        match read_acl_mutex_exists() {
+            Ok(true) => {
+                log_line(log, "read ACL helper already running; skipping spawn")?;
+            }
+            Ok(false) => {
+                spawn_read_acl_helper(payload, log).map_err(|err| {
+                    anyhow::Error::new(SetupFailure::new(
+                        SetupErrorCode::HelperReadAclHelperSpawnFailed,
+                        format!("spawn read ACL helper failed: {err}"),
+                    ))
+                })?;
+            }
+            Err(err) => {
+                log_line(
+                    log,
+                    &format!("read ACL mutex check failed: {err}; spawning anyway"),
+                )?;
+                spawn_read_acl_helper(payload, log).map_err(|spawn_err| {
+                    anyhow::Error::new(SetupFailure::new(
+                        SetupErrorCode::HelperReadAclHelperSpawnFailed,
+                        format!(
+                            "spawn read ACL helper failed after mutex error {err}: {spawn_err}"
+                        ),
+                    ))
+                })?;
+            }
+        }
+    }
+
+    if refresh_only {
+        setup_runtime_bin::ensure_codex_app_runtime_paths_readable(
+            sandbox_group_psid,
+            &mut refresh_errors,
+            log,
+        )?;
+    }
+
+    let mut grant_tasks: Vec<(PathBuf, String)> = Vec::new();
+
+    let mut seen_deny_paths: HashSet<PathBuf> = HashSet::new();
+    let mut seen_write_roots: HashSet<PathBuf> = HashSet::new();
+    for root in &payload.write_roots {
+        if !seen_write_roots.insert(root.clone()) {
+            continue;
+        }
+        if !root.exists() {
+            log_line(
+                log,
+                &format!("write root {} missing; skipping", root.display()),
+            )?;
+            continue;
+        }
+        let root_cap_sid_str =
+            workspace_write_cap_sid_for_root(&payload.codex_home, &payload.command_cwd, root)?;
+        let root_cap_psid = unsafe {
+            convert_string_sid_to_sid(&root_cap_sid_str)
+                .ok_or_else(|| anyhow::anyhow!("convert write root capability SID failed"))?
+        };
+        let need_grant =
+            match path_write_aces_need_refresh(root, &[sandbox_group_psid, root_cap_psid]) {
+                Ok(needs_refresh) => needs_refresh,
+                Err(e) => {
+                    refresh_errors.push(format!(
+                        "write ACE check failed on {}: {}",
+                        root.display(),
+                        e
+                    ));
+                    log_line(
+                        log,
+                        &format!(
+                            "write ACE check failed on {}: {}; continuing",
+                            root.display(),
+                            e
+                        ),
+                    )?;
+                    true
+                }
+            };
+        unsafe {
+            LocalFree(root_cap_psid as HLOCAL);
+        }
+        if need_grant {
+            log_line(
+                log,
+                &format!(
+                    "granting write ACE to {} for sandbox group and capability SID",
+                    root.display()
+                ),
+            )?;
+            grant_tasks.push((root.clone(), root_cap_sid_str));
+        }
+    }
+
+    let (tx, rx) = mpsc::channel::<(PathBuf, Result<bool>)>();
+    std::thread::scope(|scope| {
+        for (root, root_cap_sid_str) in grant_tasks {
+            let sid_strings = vec![sandbox_group_sid_str.clone(), root_cap_sid_str];
+            let tx = tx.clone();
+            scope.spawn(move || {
+                // Convert SID strings to psids locally in this thread.
+                let mut psids: Vec<*mut c_void> = Vec::new();
+                for sid_str in &sid_strings {
+                    if let Some(psid) = unsafe { convert_string_sid_to_sid(sid_str) } {
+                        psids.push(psid);
+                    } else {
+                        let _ = tx.send((root.clone(), Err(anyhow::anyhow!("convert SID failed"))));
+                        return;
+                    }
+                }
+
+                let res = unsafe { ensure_allow_write_aces(&root, &psids) };
+
+                for psid in psids {
+                    unsafe {
+                        LocalFree(psid as HLOCAL);
+                    }
+                }
+                let _ = tx.send((root, res));
+            });
+        }
+        drop(tx);
+        for (root, res) in rx {
+            match res {
+                Ok(_) => {}
+                Err(e) => {
+                    refresh_errors.push(format!("write ACE failed on {}: {}", root.display(), e));
+                    if log_line(
+                        log,
+                        &format!("write ACE grant failed on {}: {}", root.display(), e),
+                    )
+                    .is_err()
+                    {
+                        // ignore log errors inside scoped thread
+                    }
+                }
+            }
+        }
+    });
+
+    for path in &payload.deny_write_paths {
+        if !seen_deny_paths.insert(path.clone()) {
+            continue;
+        }
+
+        // These are deny-write carveouts, not deny-read paths. They may come from explicit
+        // read-only-under-a-writable-root carveouts in the transformed sandbox policy, or from
+        // legacy protected children such as `.git`, `.codex`, and `.agents`.
+        //
+        // Deny ACEs attach to filesystem objects; if an explicit policy carveout does not exist
+        // during setup, the sandbox could otherwise create it later under a writable parent and
+        // bypass the carveout. Materialize missing carveouts as directories so the deny-write ACL
+        // is present before the command starts. Legacy protected children are filtered before
+        // payload creation, so this should not create sentinel directories in a workspace.
+        if !path.exists() {
+            std::fs::create_dir_all(path)
+                .with_context(|| format!("failed to create deny-write path {}", path.display()))?;
+        }
+
+        let deny_sid_strs = workspace_write_cap_sids_for_path(
+            &payload.codex_home,
+            &payload.command_cwd,
+            &payload.write_roots,
+            path,
+        )?;
+        for deny_sid_str in deny_sid_strs {
+            let deny_psid = unsafe {
+                convert_string_sid_to_sid(&deny_sid_str)
+                    .ok_or_else(|| anyhow::anyhow!("convert deny capability SID failed"))?
+            };
+
+            match unsafe { add_deny_write_ace(path, deny_psid) } {
+                Ok(true) => {
+                    log_line(
+                        log,
+                        &format!("applied deny ACE to protect {}", path.display()),
+                    )?;
+                }
+                Ok(false) => {}
+                Err(err) => {
+                    refresh_errors.push(format!("deny ACE failed on {}: {err}", path.display()));
+                    log_line(
+                        log,
+                        &format!("deny ACE failed on {}: {err}", path.display()),
+                    )?;
+                }
+            }
+            unsafe {
+                LocalFree(deny_psid as HLOCAL);
+            }
+        }
+    }
+
+    lock_sandbox_bin_dir(payload, &sandbox_group_sid)?;
+
+    if refresh_only {
+        log_line(
+            log,
+            &format!(
+                "setup refresh: processed {} write roots (read roots delegated); errors={:?}",
+                payload.write_roots.len(),
+                refresh_errors
+            ),
+        )?;
+    }
+    if !refresh_only {
+        lock_persistent_sandbox_dirs(payload, &sandbox_group_sid)?;
+    }
+
+    unsafe {
+        if !sandbox_group_psid.is_null() {
+            LocalFree(sandbox_group_psid as HLOCAL);
+        }
+    }
+    if refresh_only && !refresh_errors.is_empty() {
+        log_line(
+            log,
+            &format!("setup refresh completed with errors: {refresh_errors:?}"),
+        )?;
+        anyhow::bail!("setup refresh had errors");
+    }
+    log_note("setup binary completed", Some(sbx_dir));
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "setup_provisioning/acl_tests.rs"]
+mod acl_tests;
+
+#[cfg(test)]
+#[path = "setup_provisioning/registered_tests.rs"]
+mod registered_tests;
+
+#[cfg(test)]
+mod tests {
+    use super::Payload;
+    use super::SETUP_VERSION;
+    use super::WRITE_ROOT_ALLOW_MASK;
+    use super::convert_string_sid_to_sid;
+    use super::workspace_write_cap_sids_for_path;
+    use crate::ensure_allow_mask_aces;
+    use crate::ensure_allow_write_aces;
+    use crate::load_or_create_cap_sids;
+    use crate::path_mask_allows;
+    use crate::path_write_aces_need_refresh;
+    use crate::workspace_write_cap_sid_for_root;
+    use codex_otel::StatsigMetricsSettings;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+    use std::fs;
+    use windows_sys::Win32::Foundation::HLOCAL;
+    use windows_sys::Win32::Foundation::LocalFree;
+    use windows_sys::Win32::Storage::FileSystem::FILE_DELETE_CHILD;
+
+    pub(super) fn payload_json() -> serde_json::Value {
+        json!({
+            "version": SETUP_VERSION,
+            "offline_username": "CodexSandboxOffline",
+            "online_username": "CodexSandboxOnline",
+            "codex_home": "C:\\codex-home",
+            "command_cwd": "C:\\workspace",
+            "read_roots": [],
+            "write_roots": [],
+            "proxy_ports": [],
+            "real_user": "User",
+        })
+    }
+
+    #[test]
+    fn payload_defaults_otel_absent() {
+        let payload: Payload = serde_json::from_value(payload_json()).expect("payload");
+
+        assert_eq!(payload.otel, None);
+    }
+
+    #[test]
+    fn payload_accepts_provision_only_mode() {
+        let mut payload = payload_json();
+        payload["mode"] = json!("provision-only");
+        let payload: Payload = serde_json::from_value(payload).expect("payload");
+
+        assert_eq!(payload.mode, super::SetupMode::ProvisionOnly);
+    }
+
+    #[test]
+    fn payload_accepts_interactive_provision_mode() {
+        let mut payload = payload_json();
+        payload["mode"] = json!("interactive-provision");
+        let payload: Payload = serde_json::from_value(payload).expect("payload");
+
+        assert_eq!(payload.mode, super::SetupMode::InteractiveProvision);
+    }
+
+    #[test]
+    fn payload_accepts_otel_settings() {
+        let mut payload = payload_json();
+        payload["otel"] = json!({
+            "environment": "prod",
+        });
+        let payload: Payload = serde_json::from_value(payload).expect("payload");
+
+        assert_eq!(
+            payload.otel,
+            Some(StatsigMetricsSettings {
+                environment: "prod".to_string(),
+            })
+        );
+    }
+
+    #[test]
+    fn write_root_refresh_replaces_stale_delete_child_grant() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&workspace).expect("create workspace");
+
+        let sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let psid = unsafe { convert_string_sid_to_sid(&sid).expect("convert workspace sid") };
+        let stale_write_mask = WRITE_ROOT_ALLOW_MASK | FILE_DELETE_CHILD;
+        let seeded = unsafe { ensure_allow_mask_aces(&workspace, &[psid], stale_write_mask) }
+            .expect("seed stale write ACE");
+        let needs_refresh_before =
+            path_write_aces_need_refresh(&workspace, &[psid]).expect("check stale write ACE");
+        let replaced = unsafe { ensure_allow_write_aces(&workspace, &[psid]) }
+            .expect("replace stale write ACE");
+        let needs_refresh_after =
+            path_write_aces_need_refresh(&workspace, &[psid]).expect("check refreshed write ACE");
+        unsafe {
+            LocalFree(psid as HLOCAL);
+        }
+
+        assert_eq!(
+            (seeded, needs_refresh_before, replaced, needs_refresh_after),
+            (true, true, true, false)
+        );
+    }
+
+    #[test]
+    fn write_root_refresh_checks_each_sid() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let other_root = temp.path().join("other-root");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&workspace).expect("create workspace");
+        fs::create_dir_all(&other_root).expect("create other root");
+
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let other_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &other_root)
+            .expect("other root sid");
+        let workspace_psid =
+            unsafe { convert_string_sid_to_sid(&workspace_sid).expect("convert workspace sid") };
+        let other_psid =
+            unsafe { convert_string_sid_to_sid(&other_sid).expect("convert other root sid") };
+
+        let seeded = unsafe { ensure_allow_write_aces(&workspace, &[workspace_psid]) }
+            .expect("seed workspace SID");
+        let needs_refresh_before =
+            path_write_aces_need_refresh(&workspace, &[workspace_psid, other_psid])
+                .expect("check both SIDs");
+        let refreshed =
+            unsafe { ensure_allow_write_aces(&workspace, &[workspace_psid, other_psid]) }
+                .expect("refresh both SIDs");
+        let needs_refresh_after =
+            path_write_aces_need_refresh(&workspace, &[workspace_psid, other_psid])
+                .expect("recheck both SIDs");
+        unsafe {
+            LocalFree(workspace_psid as HLOCAL);
+            LocalFree(other_psid as HLOCAL);
+        }
+
+        assert_eq!(
+            (seeded, needs_refresh_before, refreshed, needs_refresh_after,),
+            (true, true, true, false)
+        );
+    }
+
+    #[test]
+    fn write_root_refresh_ignores_inherited_delete_child_grant() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let parent = temp.path().join("parent");
+        let workspace = parent.join("workspace");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&workspace).expect("create workspace");
+
+        let sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let psid = unsafe { convert_string_sid_to_sid(&sid).expect("convert workspace sid") };
+        let seeded_explicit =
+            unsafe { ensure_allow_mask_aces(&workspace, &[psid], WRITE_ROOT_ALLOW_MASK) }
+                .expect("seed explicit write ACE");
+        let seeded_parent = unsafe {
+            ensure_allow_mask_aces(&parent, &[psid], WRITE_ROOT_ALLOW_MASK | FILE_DELETE_CHILD)
+        }
+        .expect("seed inherited stale write ACE");
+        let has_inherited_delete_child = path_mask_allows(
+            &workspace,
+            &[psid],
+            FILE_DELETE_CHILD,
+            /*require_all_bits*/ false,
+        )
+        .expect("check inherited stale write ACE");
+        let needs_refresh = path_write_aces_need_refresh(&workspace, &[psid])
+            .expect("check inherited stale write ACE");
+        let first_refresh = unsafe { ensure_allow_write_aces(&workspace, &[psid]) }
+            .expect("first inherited write ACE refresh");
+        let second_refresh = unsafe { ensure_allow_write_aces(&workspace, &[psid]) }
+            .expect("second inherited write ACE refresh");
+        unsafe {
+            LocalFree(psid as HLOCAL);
+        }
+
+        assert_eq!(
+            (
+                seeded_explicit,
+                seeded_parent,
+                has_inherited_delete_child,
+                needs_refresh,
+                first_refresh,
+                second_refresh,
+            ),
+            (true, true, true, false, false, false)
+        );
+    }
+
+    #[test]
+    fn deny_path_under_active_root_uses_only_matching_root_sid() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let active_root = temp.path().join("active-root");
+        let stale_root = temp.path().join("stale-root");
+        let deny_path = active_root.join("protected");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&workspace).expect("create workspace");
+        fs::create_dir_all(&active_root).expect("create active root");
+        fs::create_dir_all(&stale_root).expect("create stale root");
+        fs::create_dir_all(&deny_path).expect("create deny path");
+
+        let stale_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &stale_root)
+            .expect("stale sid");
+        let active_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &active_root)
+            .expect("active sid");
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let caps = load_or_create_cap_sids(&codex_home).expect("load caps");
+
+        let deny_sids = workspace_write_cap_sids_for_path(
+            &codex_home,
+            &workspace,
+            &[workspace.clone(), active_root],
+            &deny_path,
+        )
+        .expect("deny sids");
+
+        assert_eq!(deny_sids, vec![active_sid]);
+        assert!(!deny_sids.contains(&workspace_sid));
+        assert!(!deny_sids.contains(&stale_sid));
+        assert!(!deny_sids.contains(&caps.workspace));
+    }
+
+    #[test]
+    fn deny_path_outside_active_roots_falls_back_to_all_active_root_sids() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let active_root = temp.path().join("active-root");
+        let stale_root = temp.path().join("stale-root");
+        let deny_path = temp.path().join("outside-deny");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&workspace).expect("create workspace");
+        fs::create_dir_all(&active_root).expect("create active root");
+        fs::create_dir_all(&stale_root).expect("create stale root");
+        fs::create_dir_all(&deny_path).expect("create deny path");
+
+        let stale_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &stale_root)
+            .expect("stale sid");
+        let active_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &active_root)
+            .expect("active sid");
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let caps = load_or_create_cap_sids(&codex_home).expect("load caps");
+
+        let deny_sids = workspace_write_cap_sids_for_path(
+            &codex_home,
+            &workspace,
+            &[workspace.clone(), active_root],
+            &deny_path,
+        )
+        .expect("deny sids");
+
+        assert_eq!(deny_sids.len(), 2);
+        assert!(deny_sids.contains(&workspace_sid));
+        assert!(deny_sids.contains(&active_sid));
+        assert!(!deny_sids.contains(&stale_sid));
+        assert!(!deny_sids.contains(&caps.workspace));
+    }
+
+    #[test]
+    fn deny_path_includes_nested_active_root_sid() {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let protected_dir = workspace.join(".codex");
+        let nested_root = protected_dir.join("nested-root");
+        fs::create_dir_all(&codex_home).expect("create codex home");
+        fs::create_dir_all(&workspace).expect("create workspace");
+        fs::create_dir_all(&nested_root).expect("create nested root");
+
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let nested_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &nested_root)
+            .expect("nested sid");
+
+        let deny_sids = workspace_write_cap_sids_for_path(
+            &codex_home,
+            &workspace,
+            &[workspace.clone(), nested_root],
+            &protected_dir,
+        )
+        .expect("deny sids");
+
+        assert_eq!(deny_sids, vec![workspace_sid, nested_sid]);
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/acl_tests.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/acl_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..218a0cb2a8962138b06554db0b8f7b3b659f8944
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/acl_tests.rs
@@ -0,0 +1,126 @@
+use super::DELETE;
+use super::DaclInheritance;
+use super::FILE_GENERIC_EXECUTE;
+use super::FILE_GENERIC_READ;
+use super::FILE_GENERIC_WRITE;
+use super::GRANT_ACCESS;
+use super::Payload;
+use super::SETUP_VERSION;
+use super::SetupMode;
+use super::SetupRuntime;
+use super::convert_string_sid_to_sid;
+use super::lock_sandbox_bin_dir;
+use super::lock_sandbox_dir;
+use super::resolve_sid;
+use super::sid_bytes_to_psid;
+use crate::ensure_allow_write_aces;
+use crate::path_mask_allows;
+use crate::workspace_write_cap_sid_for_root;
+use std::fs;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+
+#[test]
+fn provision_only_locks_plain_directory_via_handle() {
+    let temp = tempfile::tempdir().expect("tempdir");
+    let sandbox_bin = temp.path().join(".sandbox-bin");
+    let real_user = std::env::var("USERNAME").unwrap_or_else(|_| "Administrators".to_string());
+    let real_sid = resolve_sid(&real_user).expect("resolve real user SID");
+
+    lock_sandbox_dir(
+        &sandbox_bin,
+        &real_user,
+        &real_sid,
+        GRANT_ACCESS,
+        FILE_GENERIC_READ | FILE_GENERIC_EXECUTE,
+        FILE_GENERIC_READ | FILE_GENERIC_WRITE | FILE_GENERIC_EXECUTE | DELETE,
+        DaclInheritance::Protected,
+        SetupMode::ProvisionOnly,
+    )
+    .expect("lock sandbox bin via no-reparse handle");
+
+    assert!(sandbox_bin.is_dir());
+}
+
+#[test]
+fn lock_sandbox_dir_blocks_inherited_write_for_runner_files() {
+    for setup_mode in [SetupMode::Full, SetupMode::ProvisionOnly] {
+        let temp = tempfile::tempdir().expect("tempdir");
+        let workspace = temp.path().join("workspace");
+        let sandbox_bin = workspace.join(".sandbox-bin");
+        fs::create_dir(&workspace).expect("create workspace");
+
+        let workspace_sid = workspace_write_cap_sid_for_root(temp.path(), temp.path(), temp.path())
+            .expect("workspace SID");
+        let workspace_psid =
+            unsafe { convert_string_sid_to_sid(&workspace_sid).expect("convert workspace SID") };
+        let sandbox_group_sid =
+            resolve_sid("Authenticated Users").expect("resolve sandbox group SID");
+        let sandbox_group_psid =
+            sid_bytes_to_psid(&sandbox_group_sid).expect("convert sandbox group SID");
+        unsafe { ensure_allow_write_aces(&workspace, &[workspace_psid]) }
+            .expect("grant inherited workspace write access");
+
+        fs::create_dir(&sandbox_bin).expect("create sandbox bin");
+        let existing_runner = sandbox_bin.join("existing-runner.exe");
+        fs::write(&existing_runner, b"existing").expect("create existing runner");
+        assert!(
+            path_mask_allows(
+                &existing_runner,
+                &[workspace_psid],
+                FILE_GENERIC_WRITE | DELETE,
+                /*require_all_bits*/ true,
+            )
+            .expect("check inherited runner write and delete access")
+        );
+
+        let real_user = std::env::var("USERNAME").unwrap_or_else(|_| "Administrators".to_string());
+        let payload = Payload {
+            version: SETUP_VERSION,
+            offline_username: String::new(),
+            online_username: String::new(),
+            codex_home: workspace.clone(),
+            command_cwd: workspace.clone(),
+            read_roots: Vec::new(),
+            write_roots: Vec::new(),
+            deny_read_paths: Vec::new(),
+            deny_write_paths: Vec::new(),
+            proxy_ports: Vec::new(),
+            allow_local_binding: false,
+            otel: None,
+            real_user,
+            mode: setup_mode,
+            runtime: SetupRuntime::Legacy,
+            refresh_only: false,
+        };
+        lock_sandbox_bin_dir(&payload, &sandbox_group_sid).expect("lock sandbox bin");
+        let new_runner = sandbox_bin.join("new-runner.exe");
+        fs::write(&new_runner, b"new").expect("create new runner");
+
+        for path in [&sandbox_bin, &existing_runner, &new_runner] {
+            assert!(
+                !path_mask_allows(
+                    path,
+                    &[workspace_psid],
+                    FILE_GENERIC_WRITE | DELETE,
+                    /*require_all_bits*/ false,
+                )
+                .expect("check protected path write and delete access")
+            );
+            assert!(
+                path_mask_allows(
+                    path,
+                    &[sandbox_group_psid],
+                    FILE_GENERIC_READ | FILE_GENERIC_EXECUTE,
+                    /*require_all_bits*/ true,
+                )
+                .expect("check protected path read and execute access")
+            );
+        }
+
+        unsafe {
+            LocalFree(workspace_psid as HLOCAL);
+            LocalFree(sandbox_group_psid as HLOCAL);
+        }
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/firewall.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/firewall.rs
new file mode 100644
index 0000000000000000000000000000000000000000..81f4fa50eb87d7d1bf0560b848b9da17f94fde88
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/firewall.rs
@@ -0,0 +1,643 @@
+use anyhow::Result;
+use std::io::Write;
+
+use windows::Win32::Foundation::RPC_E_CHANGED_MODE;
+use windows::Win32::Foundation::S_OK;
+use windows::Win32::Foundation::VARIANT_TRUE;
+use windows::Win32::NetworkManagement::WindowsFirewall::INetFwPolicy2;
+use windows::Win32::NetworkManagement::WindowsFirewall::INetFwRule3;
+use windows::Win32::NetworkManagement::WindowsFirewall::INetFwRules;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_ACTION_BLOCK;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_IP_PROTOCOL_ANY;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_IP_PROTOCOL_TCP;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_IP_PROTOCOL_UDP;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_MODIFY_STATE;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_MODIFY_STATE_OK;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_PROFILE2_ALL;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_RULE_DIR_IN;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_RULE_DIR_OUT;
+use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_RULE_DIRECTION;
+use windows::Win32::NetworkManagement::WindowsFirewall::NetFwPolicy2;
+use windows::Win32::NetworkManagement::WindowsFirewall::NetFwRule;
+use windows::Win32::System::Com::CLSCTX_INPROC_SERVER;
+use windows::Win32::System::Com::COINIT_APARTMENTTHREADED;
+use windows::Win32::System::Com::CoCreateInstance;
+use windows::Win32::System::Com::CoInitializeEx;
+use windows::Win32::System::Com::CoUninitialize;
+use windows::core::BSTR;
+use windows::core::Interface;
+
+use crate::SetupErrorCode;
+use crate::SetupFailure;
+
+// This is the stable identifier we use to find/update the rule idempotently.
+// It intentionally does not change between installs.
+const OFFLINE_BLOCK_RULE_NAME: &str = "codex_sandbox_offline_block_outbound";
+const OFFLINE_BLOCK_INBOUND_RULE_NAME: &str = "codex_sandbox_offline_block_inbound";
+const OFFLINE_BLOCK_LOOPBACK_TCP_RULE_NAME: &str = "codex_sandbox_offline_block_loopback_tcp";
+const OFFLINE_BLOCK_LOOPBACK_UDP_RULE_NAME: &str = "codex_sandbox_offline_block_loopback_udp";
+
+// Friendly text shown in the firewall UI.
+const OFFLINE_BLOCK_RULE_FRIENDLY: &str = "Codex Sandbox Offline - Block Non-Loopback Outbound";
+const OFFLINE_BLOCK_INBOUND_RULE_FRIENDLY: &str =
+    "Codex Sandbox Offline - Block Non-Loopback Inbound";
+const OFFLINE_BLOCK_LOOPBACK_TCP_RULE_FRIENDLY: &str =
+    "Codex Sandbox Offline - Block Loopback TCP (Except Proxy)";
+const OFFLINE_BLOCK_LOOPBACK_UDP_RULE_FRIENDLY: &str = "Codex Sandbox Offline - Block Loopback UDP";
+const OFFLINE_PROXY_ALLOW_RULE_NAME: &str = "codex_sandbox_offline_allow_loopback_proxy";
+const LOOPBACK_REMOTE_ADDRESSES: &str = "127.0.0.0/8,::/127";
+const NON_LOOPBACK_REMOTE_ADDRESSES: &str = "0.0.0.0-126.255.255.255,128.0.0.0-255.255.255.255,::,::2-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff";
+
+struct BlockRuleSpec<'a> {
+    internal_name: &'a str,
+    friendly_desc: &'a str,
+    direction: NET_FW_RULE_DIRECTION,
+    protocol: i32,
+    local_user_spec: &'a str,
+    offline_sid: &'a str,
+    remote_addresses: Option<&'a str>,
+    remote_ports: Option<&'a str>,
+}
+
+// Firewall COM also supports the service's existing MTA. Balance only our own initialization.
+struct FirewallComApartment {
+    initialized: bool,
+}
+
+impl FirewallComApartment {
+    fn initialize() -> Result<Self> {
+        let hr = unsafe { CoInitializeEx(None, COINIT_APARTMENTTHREADED) };
+        if hr.is_err() && hr != RPC_E_CHANGED_MODE {
+            return Err(anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallComInitFailed,
+                format!("CoInitializeEx failed: {hr:?}"),
+            )));
+        }
+        Ok(Self {
+            initialized: hr.is_ok(),
+        })
+    }
+}
+
+impl Drop for FirewallComApartment {
+    fn drop(&mut self) {
+        if self.initialized {
+            unsafe { CoUninitialize() };
+        }
+    }
+}
+
+pub fn ensure_offline_proxy_allowlist(
+    offline_sid: &str,
+    proxy_ports: &[u16],
+    allow_local_binding: bool,
+    log: &mut dyn Write,
+) -> Result<()> {
+    let local_user_spec = format!("O:LSD:(A;;CC;;;{offline_sid})");
+
+    let _apartment = FirewallComApartment::initialize()?;
+
+    unsafe {
+        (|| -> Result<()> {
+            let policy: INetFwPolicy2 = CoCreateInstance(&NetFwPolicy2, None, CLSCTX_INPROC_SERVER)
+                .map_err(|err| {
+                    anyhow::Error::new(SetupFailure::new(
+                        SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                        format!("CoCreateInstance NetFwPolicy2 failed: {err:?}"),
+                    ))
+                })?;
+            ensure_local_policy_rules_take_effect(&policy)?;
+            let rules = policy.Rules().map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                    format!("INetFwPolicy2::Rules failed: {err:?}"),
+                ))
+            })?;
+
+            if allow_local_binding {
+                // Remove the legacy overlapping allow rule before returning to the local-binding
+                // mode so stale proxy exceptions do not linger.
+                remove_rule_if_present(&rules, OFFLINE_PROXY_ALLOW_RULE_NAME, log)?;
+                remove_rule_if_present(&rules, OFFLINE_BLOCK_LOOPBACK_UDP_RULE_NAME, log)?;
+                remove_rule_if_present(&rules, OFFLINE_BLOCK_LOOPBACK_TCP_RULE_NAME, log)?;
+                return Ok(());
+            }
+
+            ensure_block_rule(
+                &rules,
+                &BlockRuleSpec {
+                    internal_name: OFFLINE_BLOCK_LOOPBACK_UDP_RULE_NAME,
+                    friendly_desc: OFFLINE_BLOCK_LOOPBACK_UDP_RULE_FRIENDLY,
+                    direction: NET_FW_RULE_DIR_OUT,
+                    protocol: NET_FW_IP_PROTOCOL_UDP.0,
+                    local_user_spec: &local_user_spec,
+                    offline_sid,
+                    remote_addresses: Some(LOOPBACK_REMOTE_ADDRESSES),
+                    remote_ports: None,
+                },
+                log,
+            )?;
+
+            // Install a broad TCP loopback block before narrowing it to the allowed proxy port
+            // complement. If the narrowing update fails, the sandbox remains fail-closed.
+            ensure_block_rule(
+                &rules,
+                &BlockRuleSpec {
+                    internal_name: OFFLINE_BLOCK_LOOPBACK_TCP_RULE_NAME,
+                    friendly_desc: OFFLINE_BLOCK_LOOPBACK_TCP_RULE_FRIENDLY,
+                    direction: NET_FW_RULE_DIR_OUT,
+                    protocol: NET_FW_IP_PROTOCOL_TCP.0,
+                    local_user_spec: &local_user_spec,
+                    offline_sid,
+                    remote_addresses: Some(LOOPBACK_REMOTE_ADDRESSES),
+                    remote_ports: None,
+                },
+                log,
+            )?;
+
+            // Remove the legacy overlapping allow rule only after the explicit block rules are in
+            // place so transitions back to proxy-only mode do not fail open.
+            remove_rule_if_present(&rules, OFFLINE_PROXY_ALLOW_RULE_NAME, log)?;
+
+            if let Some(blocked_remote_ports) = blocked_loopback_tcp_remote_ports(proxy_ports) {
+                ensure_block_rule(
+                    &rules,
+                    &BlockRuleSpec {
+                        internal_name: OFFLINE_BLOCK_LOOPBACK_TCP_RULE_NAME,
+                        friendly_desc: OFFLINE_BLOCK_LOOPBACK_TCP_RULE_FRIENDLY,
+                        direction: NET_FW_RULE_DIR_OUT,
+                        protocol: NET_FW_IP_PROTOCOL_TCP.0,
+                        local_user_spec: &local_user_spec,
+                        offline_sid,
+                        remote_addresses: Some(LOOPBACK_REMOTE_ADDRESSES),
+                        remote_ports: Some(&blocked_remote_ports),
+                    },
+                    log,
+                )?;
+            }
+            Ok(())
+        })()
+    }
+}
+
+pub fn ensure_offline_network_blocks(offline_sid: &str, log: &mut dyn Write) -> Result<()> {
+    let local_user_spec = format!("O:LSD:(A;;CC;;;{offline_sid})");
+
+    let _apartment = FirewallComApartment::initialize()?;
+
+    unsafe {
+        (|| -> Result<()> {
+            let policy: INetFwPolicy2 = CoCreateInstance(&NetFwPolicy2, None, CLSCTX_INPROC_SERVER)
+                .map_err(|err| {
+                    anyhow::Error::new(SetupFailure::new(
+                        SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                        format!("CoCreateInstance NetFwPolicy2 failed: {err:?}"),
+                    ))
+                })?;
+            ensure_local_policy_rules_take_effect(&policy)?;
+            let rules = policy.Rules().map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallPolicyAccessFailed,
+                    format!("INetFwPolicy2::Rules failed: {err:?}"),
+                ))
+            })?;
+
+            // Block all outbound IP protocols for this user.
+            ensure_block_rule(
+                &rules,
+                &BlockRuleSpec {
+                    internal_name: OFFLINE_BLOCK_RULE_NAME,
+                    friendly_desc: OFFLINE_BLOCK_RULE_FRIENDLY,
+                    direction: NET_FW_RULE_DIR_OUT,
+                    protocol: NET_FW_IP_PROTOCOL_ANY.0,
+                    local_user_spec: &local_user_spec,
+                    offline_sid,
+                    remote_addresses: Some(NON_LOOPBACK_REMOTE_ADDRESSES),
+                    remote_ports: None,
+                },
+                log,
+            )?;
+            ensure_block_rule(
+                &rules,
+                &BlockRuleSpec {
+                    internal_name: OFFLINE_BLOCK_INBOUND_RULE_NAME,
+                    friendly_desc: OFFLINE_BLOCK_INBOUND_RULE_FRIENDLY,
+                    direction: NET_FW_RULE_DIR_IN,
+                    protocol: NET_FW_IP_PROTOCOL_ANY.0,
+                    local_user_spec: &local_user_spec,
+                    offline_sid,
+                    remote_addresses: Some(NON_LOOPBACK_REMOTE_ADDRESSES),
+                    remote_ports: None,
+                },
+                log,
+            )?;
+            Ok(())
+        })()
+    }
+}
+
+fn remove_rule_if_present(
+    rules: &INetFwRules,
+    internal_name: &str,
+    log: &mut dyn Write,
+) -> Result<()> {
+    let name = BSTR::from(internal_name);
+    if unsafe { rules.Item(&name) }.is_ok() {
+        unsafe { rules.Remove(&name) }.map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("Rules::Remove failed for {internal_name}: {err:?}"),
+            ))
+        })?;
+        log_line(log, &format!("firewall rule removed name={internal_name}"))?;
+    }
+    Ok(())
+}
+
+fn ensure_local_policy_rules_take_effect(policy: &INetFwPolicy2) -> Result<()> {
+    let mut modify_state = NET_FW_MODIFY_STATE::default();
+    let result = unsafe {
+        (Interface::vtable(policy).LocalPolicyModifyState)(
+            Interface::as_raw(policy),
+            &mut modify_state,
+        )
+    };
+    validate_local_policy_modify_result(result, modify_state)
+}
+
+fn validate_local_policy_modify_result(
+    result: windows::core::HRESULT,
+    modify_state: NET_FW_MODIFY_STATE,
+) -> Result<()> {
+    if result.is_err() {
+        // The COM query itself failed, so Windows never gave us a policy answer.
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperFirewallPolicyAccessFailed,
+            format!("INetFwPolicy2::LocalPolicyModifyState failed: {result:?}"),
+        )));
+    }
+
+    if result != S_OK {
+        // S_FALSE means the answer only holds for some active profiles, not all of them.
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperFirewallPolicyIneffective,
+            format!(
+                "local firewall policy modifications do not apply to every current profile: LocalPolicyModifyState result={result:?}"
+            ),
+        )));
+    }
+
+    if modify_state == NET_FW_MODIFY_STATE_OK {
+        return Ok(());
+    }
+
+    // Windows answered uniformly, and that answer says local rule edits are ineffective.
+    Err(anyhow::Error::new(SetupFailure::new(
+        SetupErrorCode::HelperFirewallPolicyIneffective,
+        format!(
+            "local firewall policy modifications will not take effect: LocalPolicyModifyState={modify_state:?}"
+        ),
+    )))
+}
+
+fn ensure_block_rule(
+    rules: &INetFwRules,
+    spec: &BlockRuleSpec<'_>,
+    log: &mut dyn Write,
+) -> Result<()> {
+    let name = BSTR::from(spec.internal_name);
+    let rule: INetFwRule3 = match unsafe { rules.Item(&name) } {
+        Ok(existing) => existing.cast().map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("cast existing firewall rule to INetFwRule3 failed: {err:?}"),
+            ))
+        })?,
+        Err(_) => {
+            let new_rule: INetFwRule3 =
+                unsafe { CoCreateInstance(&NetFwRule, None, CLSCTX_INPROC_SERVER) }.map_err(
+                    |err| {
+                        anyhow::Error::new(SetupFailure::new(
+                            SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                            format!("CoCreateInstance NetFwRule failed: {err:?}"),
+                        ))
+                    },
+                )?;
+            unsafe { new_rule.SetName(&name) }.map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                    format!("SetName failed: {err:?}"),
+                ))
+            })?;
+            // Set all properties before adding the rule so we don't leave half-configured rules.
+            configure_rule(&new_rule, spec)?;
+            unsafe { rules.Add(&new_rule) }.map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                    format!("Rules::Add failed: {err:?}"),
+                ))
+            })?;
+            new_rule
+        }
+    };
+
+    // Always re-apply fields to keep the setup idempotent.
+    configure_rule(&rule, spec)?;
+
+    let remote_addresses_log = spec.remote_addresses.unwrap_or("*");
+    let remote_ports_log = spec.remote_ports.unwrap_or("*");
+
+    log_line(
+        log,
+        &format!(
+            "firewall rule configured name={} protocol={} RemoteAddresses={remote_addresses_log} RemotePorts={remote_ports_log} LocalUserAuthorizedList={}",
+            spec.internal_name, spec.protocol, spec.local_user_spec
+        ),
+    )?;
+    Ok(())
+}
+
+fn configure_rule(rule: &INetFwRule3, spec: &BlockRuleSpec<'_>) -> Result<()> {
+    unsafe {
+        rule.SetDescription(&BSTR::from(spec.friendly_desc))
+            .map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                    format!("SetDescription failed: {err:?}"),
+                ))
+            })?;
+        rule.SetDirection(spec.direction).map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("SetDirection failed: {err:?}"),
+            ))
+        })?;
+        rule.SetAction(NET_FW_ACTION_BLOCK).map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("SetAction failed: {err:?}"),
+            ))
+        })?;
+        rule.SetEnabled(VARIANT_TRUE).map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("SetEnabled failed: {err:?}"),
+            ))
+        })?;
+        rule.SetProfiles(NET_FW_PROFILE2_ALL.0).map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("SetProfiles failed: {err:?}"),
+            ))
+        })?;
+        configure_rule_network_scope(rule, spec)?;
+        rule.SetLocalUserAuthorizedList(&BSTR::from(spec.local_user_spec))
+            .map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                    format!("SetLocalUserAuthorizedList failed: {err:?}"),
+                ))
+            })?;
+    }
+
+    // Read-back verification: ensure we actually wrote the expected SID scope.
+    let actual = unsafe { rule.LocalUserAuthorizedList() }.map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperFirewallRuleVerifyFailed,
+            format!("LocalUserAuthorizedList (read-back) failed: {err:?}"),
+        ))
+    })?;
+    let actual_str = actual.to_string();
+    if !actual_str.contains(spec.offline_sid) {
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperFirewallRuleVerifyFailed,
+            format!(
+                "offline firewall rule user scope mismatch: expected SID {}, got {actual_str}",
+                spec.offline_sid
+            ),
+        )));
+    }
+    Ok(())
+}
+
+fn configure_rule_network_scope(rule: &INetFwRule3, spec: &BlockRuleSpec<'_>) -> Result<()> {
+    unsafe {
+        rule.SetProtocol(spec.protocol).map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                format!("SetProtocol failed: {err:?}"),
+            ))
+        })?;
+        let remote_addresses = spec.remote_addresses.unwrap_or("*");
+        rule.SetRemoteAddresses(&BSTR::from(remote_addresses))
+            .map_err(|err| {
+                anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                    format!("SetRemoteAddresses failed: {err:?}"),
+                ))
+            })?;
+        if let Some(remote_ports) = spec.remote_ports {
+            rule.SetRemotePorts(&BSTR::from(remote_ports))
+                .map_err(|err| {
+                    anyhow::Error::new(SetupFailure::new(
+                        SetupErrorCode::HelperFirewallRuleCreateOrAddFailed,
+                        format!("SetRemotePorts failed: {err:?}"),
+                    ))
+                })?;
+        }
+    }
+
+    Ok(())
+}
+
+fn blocked_loopback_tcp_remote_ports(proxy_ports: &[u16]) -> Option<String> {
+    let mut allowed_ports = proxy_ports
+        .iter()
+        .copied()
+        .filter(|port| *port != 0)
+        .collect::<Vec<_>>();
+    allowed_ports.sort_unstable();
+    allowed_ports.dedup();
+
+    let mut blocked_ranges = Vec::new();
+    let mut start = 1_u32;
+    for port in allowed_ports {
+        let port = u32::from(port);
+        if port < start {
+            continue;
+        }
+        if port > start {
+            blocked_ranges.push(port_range_string(start, port - 1));
+        }
+        start = port + 1;
+    }
+
+    if start <= u32::from(u16::MAX) {
+        blocked_ranges.push(port_range_string(start, u32::from(u16::MAX)));
+    }
+
+    if blocked_ranges.is_empty() {
+        None
+    } else {
+        Some(blocked_ranges.join(","))
+    }
+}
+
+fn port_range_string(start: u32, end: u32) -> String {
+    if start == end {
+        start.to_string()
+    } else {
+        format!("{start}-{end}")
+    }
+}
+
+fn log_line(log: &mut dyn Write, msg: &str) -> Result<()> {
+    let ts = chrono::Utc::now().to_rfc3339();
+    writeln!(log, "[{ts}] {msg}")?;
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "firewall_apartment_tests.rs"]
+mod apartment_tests;
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use windows::Win32::Foundation::S_FALSE;
+    use windows::Win32::NetworkManagement::WindowsFirewall::NET_FW_MODIFY_STATE_GP_OVERRIDE;
+
+    use super::*;
+
+    #[test]
+    fn configured_remote_address_literals_are_accepted_by_firewall_com() {
+        let hr = unsafe { CoInitializeEx(None, COINIT_APARTMENTTHREADED) };
+        assert!(hr.is_ok(), "CoInitializeEx failed: {hr:?}");
+
+        let candidates = [
+            LOOPBACK_REMOTE_ADDRESSES,
+            NON_LOOPBACK_REMOTE_ADDRESSES,
+            "*",
+        ];
+        let results = candidates.map(|remote_addresses| unsafe {
+            let rule: windows::core::Result<INetFwRule3> =
+                CoCreateInstance(&NetFwRule, None, CLSCTX_INPROC_SERVER);
+            rule.and_then(|rule| {
+                rule.SetRemoteAddresses(&BSTR::from(remote_addresses))?;
+                rule.RemoteAddresses()
+            })
+            .map(|stored| stored.to_string())
+        });
+
+        unsafe {
+            CoUninitialize();
+        }
+
+        for (remote_addresses, result) in candidates.into_iter().zip(results) {
+            assert!(
+                result.is_ok(),
+                "firewall rejected RemoteAddresses={remote_addresses:?}: {result:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn production_firewall_rule_network_scopes_are_accepted_by_firewall_com() {
+        let hr = unsafe { CoInitializeEx(None, COINIT_APARTMENTTHREADED) };
+        assert!(hr.is_ok(), "CoInitializeEx failed: {hr:?}");
+
+        let local_user_spec = "O:LSD:(A;;CC;;;S-1-5-18)";
+        let offline_sid = "S-1-5-18";
+        let blocked_remote_ports =
+            blocked_loopback_tcp_remote_ports(&[8080]).expect("proxy-port complement should exist");
+        let specs = [
+            BlockRuleSpec {
+                internal_name: OFFLINE_BLOCK_LOOPBACK_UDP_RULE_NAME,
+                friendly_desc: OFFLINE_BLOCK_LOOPBACK_UDP_RULE_FRIENDLY,
+                direction: NET_FW_RULE_DIR_OUT,
+                protocol: NET_FW_IP_PROTOCOL_UDP.0,
+                local_user_spec,
+                offline_sid,
+                remote_addresses: Some(LOOPBACK_REMOTE_ADDRESSES),
+                remote_ports: None,
+            },
+            BlockRuleSpec {
+                internal_name: OFFLINE_BLOCK_LOOPBACK_TCP_RULE_NAME,
+                friendly_desc: OFFLINE_BLOCK_LOOPBACK_TCP_RULE_FRIENDLY,
+                direction: NET_FW_RULE_DIR_OUT,
+                protocol: NET_FW_IP_PROTOCOL_TCP.0,
+                local_user_spec,
+                offline_sid,
+                remote_addresses: Some(LOOPBACK_REMOTE_ADDRESSES),
+                remote_ports: Some(&blocked_remote_ports),
+            },
+            BlockRuleSpec {
+                internal_name: OFFLINE_BLOCK_RULE_NAME,
+                friendly_desc: OFFLINE_BLOCK_RULE_FRIENDLY,
+                direction: NET_FW_RULE_DIR_OUT,
+                protocol: NET_FW_IP_PROTOCOL_ANY.0,
+                local_user_spec,
+                offline_sid,
+                remote_addresses: Some(NON_LOOPBACK_REMOTE_ADDRESSES),
+                remote_ports: None,
+            },
+        ];
+
+        let results = specs.each_ref().map(|spec| unsafe {
+            let rule: windows::core::Result<INetFwRule3> =
+                CoCreateInstance(&NetFwRule, None, CLSCTX_INPROC_SERVER);
+            match rule {
+                Ok(rule) => configure_rule_network_scope(&rule, spec),
+                Err(err) => Err(err.into()),
+            }
+        });
+
+        unsafe {
+            CoUninitialize();
+        }
+
+        for (spec, result) in specs.into_iter().zip(results) {
+            assert!(
+                result.is_ok(),
+                "firewall rejected network scope for rule={} protocol={} remote_addresses={:?} remote_ports={:?}: {result:?}",
+                spec.internal_name,
+                spec.protocol,
+                spec.remote_addresses,
+                spec.remote_ports
+            );
+        }
+    }
+
+    #[test]
+    fn local_policy_modify_state_accepts_effective_policy() {
+        assert!(validate_local_policy_modify_result(S_OK, NET_FW_MODIFY_STATE_OK).is_ok());
+    }
+
+    #[test]
+    fn local_policy_modify_state_rejects_ineffective_policy() {
+        let err = validate_local_policy_modify_result(S_OK, NET_FW_MODIFY_STATE_GP_OVERRIDE)
+            .expect_err("group-policy override should fail sandbox firewall setup");
+        let failure = err
+            .downcast_ref::<SetupFailure>()
+            .expect("expected setup failure");
+
+        assert_eq!(
+            failure.code,
+            SetupErrorCode::HelperFirewallPolicyIneffective
+        );
+    }
+
+    #[test]
+    fn local_policy_modify_state_rejects_partial_profile_coverage() {
+        let err = validate_local_policy_modify_result(S_FALSE, NET_FW_MODIFY_STATE_OK)
+            .expect_err("partial profile coverage should fail sandbox firewall setup");
+        let failure = err
+            .downcast_ref::<SetupFailure>()
+            .expect("expected setup failure");
+
+        assert_eq!(
+            failure.code,
+            SetupErrorCode::HelperFirewallPolicyIneffective
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/firewall_apartment_tests.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/firewall_apartment_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a08826de808c5dcaf52289a01aa637d2e0eaf0c8
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/firewall_apartment_tests.rs
@@ -0,0 +1,40 @@
+//! Verifies firewall COM access preserves a service thread's existing apartment.
+
+use super::CLSCTX_INPROC_SERVER;
+use super::CoCreateInstance;
+use super::FirewallComApartment;
+use super::INetFwPolicy2;
+use super::NetFwPolicy2;
+use pretty_assertions::assert_eq;
+use windows::Win32::Foundation::RPC_E_CHANGED_MODE;
+use windows::Win32::System::Com::COINIT_APARTMENTTHREADED;
+use windows::Win32::System::Com::COINIT_MULTITHREADED;
+use windows::Win32::System::Com::CoInitializeEx;
+use windows::Win32::System::Com::CoUninitialize;
+
+#[test]
+fn firewall_access_preserves_the_services_existing_mta() {
+    std::thread::spawn(|| {
+        let initialized = unsafe { CoInitializeEx(None, COINIT_MULTITHREADED) };
+        assert!(initialized.is_ok(), "initialize MTA: {initialized:?}");
+
+        // Open the rules collection without adding, changing, or deleting a rule.
+        let result = (|| -> anyhow::Result<()> {
+            let _apartment = FirewallComApartment::initialize()?;
+            let policy: INetFwPolicy2 =
+                unsafe { CoCreateInstance(&NetFwPolicy2, None, CLSCTX_INPROC_SERVER)? };
+            let _rules = unsafe { policy.Rules()? };
+            Ok(())
+        })();
+        let apartment = unsafe { CoInitializeEx(None, COINIT_APARTMENTTHREADED) };
+        unsafe { CoUninitialize() };
+
+        assert_eq!(
+            apartment, RPC_E_CHANGED_MODE,
+            "caller's MTA must remain initialized"
+        );
+        result.expect("read firewall rules from the existing MTA");
+    })
+    .join()
+    .expect("firewall COM test thread");
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/read_acl_mutex.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/read_acl_mutex.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7954826bd442915b5ba6900f960a7c1db9ba3d8f
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/read_acl_mutex.rs
@@ -0,0 +1,61 @@
+use crate::to_wide;
+use anyhow::Result;
+use std::ffi::OsStr;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::ERROR_ALREADY_EXISTS;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::System::Threading::CreateMutexW;
+use windows_sys::Win32::System::Threading::MUTEX_ALL_ACCESS;
+use windows_sys::Win32::System::Threading::OpenMutexW;
+use windows_sys::Win32::System::Threading::ReleaseMutex;
+
+const READ_ACL_MUTEX_NAME: &str = "Local\\CodexSandboxReadAcl";
+
+pub(super) struct ReadAclMutexGuard {
+    handle: HANDLE,
+}
+
+impl Drop for ReadAclMutexGuard {
+    fn drop(&mut self) {
+        unsafe {
+            let _ = ReleaseMutex(self.handle);
+            CloseHandle(self.handle);
+        }
+    }
+}
+
+pub(super) fn read_acl_mutex_exists() -> Result<bool> {
+    let name = to_wide(OsStr::new(READ_ACL_MUTEX_NAME));
+    let handle = unsafe { OpenMutexW(MUTEX_ALL_ACCESS, 0, name.as_ptr()) };
+    if handle == 0 {
+        let err = unsafe { GetLastError() };
+        if err == ERROR_FILE_NOT_FOUND {
+            return Ok(false);
+        }
+        return Err(anyhow::anyhow!("OpenMutexW failed: {err}"));
+    }
+    unsafe {
+        CloseHandle(handle);
+    }
+    Ok(true)
+}
+
+pub(super) fn acquire_read_acl_mutex() -> Result<Option<ReadAclMutexGuard>> {
+    let name = to_wide(OsStr::new(READ_ACL_MUTEX_NAME));
+    let handle = unsafe { CreateMutexW(std::ptr::null_mut(), 1, name.as_ptr()) };
+    if handle == 0 {
+        return Err(anyhow::anyhow!("CreateMutexW failed: {}", unsafe {
+            GetLastError()
+        }));
+    }
+    let err = unsafe { GetLastError() };
+    if err == ERROR_ALREADY_EXISTS {
+        unsafe {
+            CloseHandle(handle);
+        }
+        return Ok(None);
+    }
+    Ok(Some(ReadAclMutexGuard { handle }))
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/registered_tests.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/registered_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e815b60bfde1ddcf58381e65c32d1d936fee8886
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/registered_tests.rs
@@ -0,0 +1,91 @@
+//! Registration-specific setup serialization and legacy-materialization boundaries.
+
+use super::Payload;
+use super::tests::payload_json;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::fs;
+
+#[test]
+fn payload_runtime_wire_normalization_preserves_opt_in() {
+    let mut payload: Payload = serde_json::from_value(payload_json()).unwrap();
+    assert_eq!(payload.runtime, super::SetupRuntime::Legacy);
+    let legacy = serde_json::to_value(&payload).unwrap();
+    assert!(legacy.get("runtime").is_none());
+    let mut explicit = legacy.clone();
+    explicit["runtime"] = serde_json::json!("legacy");
+    let decoded: Payload = serde_json::from_value(explicit).unwrap();
+    assert_eq!(serde_json::to_value(decoded).unwrap(), legacy);
+
+    payload.runtime = super::SetupRuntime::Registered;
+    let mut registered = legacy.clone();
+    registered["runtime"] = serde_json::json!("registered");
+    assert_eq!(serde_json::to_value(&payload).unwrap(), registered);
+    let decoded: Payload = serde_json::from_value(registered.clone()).unwrap();
+    assert_eq!(serde_json::to_value(decoded).unwrap(), registered);
+
+    for invalid in [
+        serde_json::Value::Null,
+        serde_json::json!(true),
+        serde_json::json!("unverified"),
+    ] {
+        let mut malformed = legacy.clone();
+        malformed["runtime"] = invalid;
+        assert!(serde_json::from_value::<Payload>(malformed).is_err());
+    }
+}
+
+#[test]
+fn registered_payload_never_creates_or_locks_legacy_bin() {
+    let tmp = tempfile::tempdir().expect("tempdir");
+    let mut json = payload_json();
+    json["codex_home"] = json!(tmp.path());
+    json["runtime"] = json!("registered");
+    let payload: Payload = serde_json::from_value(json).expect("registered payload");
+    // An empty SID would fail any ACL operation; Registered must not attempt one.
+    super::lock_sandbox_bin_dir(&payload, &[]).expect("no legacy bin work");
+    let bin = super::sandbox_bin_dir(tmp.path());
+    assert!(!bin.exists());
+    fs::create_dir(&bin).expect("existing legacy bin");
+    let sentinel = bin.join("sentinel");
+    fs::write(&sentinel, b"unchanged").expect("existing content");
+    super::lock_sandbox_bin_dir(&payload, &[]).expect("leave existing bin alone");
+    assert_eq!(fs::read(sentinel).expect("read sentinel"), b"unchanged");
+}
+
+#[test]
+fn unverified_payload_cannot_create_legacy_bin() {
+    let tmp = tempfile::tempdir().expect("tempdir");
+    let mut json = payload_json();
+    json["codex_home"] = json!(tmp.path());
+    json["runtime"] = json!("unverified");
+    assert!(serde_json::from_value::<Payload>(json).is_err());
+    assert!(!super::sandbox_bin_dir(tmp.path()).exists());
+}
+
+#[test]
+fn helper_account_gate_covers_actual_provisioning_modes() {
+    for (mode, expected) in [
+        (super::SetupMode::Full, [true, false]),
+        (super::SetupMode::InteractiveProvision, [true, true]),
+        (super::SetupMode::ProvisionOnly, [true, true]),
+        (super::SetupMode::ReadAclsOnly, [false, false]),
+    ] {
+        assert_eq!(
+            [false, true].map(|refresh_only| mode.provisions_accounts(refresh_only)),
+            expected
+        );
+    }
+}
+
+#[test]
+fn parsed_provision_only_cannot_claim_the_private_service_entry() {
+    let mut json = payload_json();
+    json["mode"] = json!("provision-only");
+    json["runtime"] = json!("registered");
+    json["refresh_only"] = json!(true);
+    json["service_admitted"] = json!(true);
+    let payload: Payload = serde_json::from_value(json).expect("payload");
+    assert!(payload.mode.provisions_accounts(payload.refresh_only));
+    assert_ne!(payload.runtime, super::SetupRuntime::Legacy);
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/sandbox_users.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/sandbox_users.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fbc9e1d30a13ddf3ae7991540d68904dae7bdcfc
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/sandbox_users.rs
@@ -0,0 +1,513 @@
+use anyhow::Result;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use rand::RngCore;
+use rand::SeedableRng;
+use rand::rngs::SmallRng;
+use serde::Serialize;
+use std::ffi::OsStr;
+use std::ffi::c_void;
+use std::fs::File;
+use std::io::Write;
+use std::os::windows::io::FromRawHandle;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation::ERROR_INSUFFICIENT_BUFFER;
+use windows_sys::Win32::Foundation::GENERIC_WRITE;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::NetworkManagement::NetManagement::LOCALGROUP_MEMBERS_INFO_3;
+use windows_sys::Win32::NetworkManagement::NetManagement::NERR_Success;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetLocalGroupAddMembers;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetUserAdd;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetUserSetInfo;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_DONT_EXPIRE_PASSWD;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_SCRIPT;
+use windows_sys::Win32::NetworkManagement::NetManagement::USER_INFO_1;
+use windows_sys::Win32::NetworkManagement::NetManagement::USER_INFO_1003;
+use windows_sys::Win32::NetworkManagement::NetManagement::USER_PRIV_USER;
+use windows_sys::Win32::Security::Authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW;
+use windows_sys::Win32::Security::Authorization::ConvertStringSidToSidW;
+use windows_sys::Win32::Security::Authorization::SDDL_REVISION_1;
+use windows_sys::Win32::Security::LookupAccountSidW;
+use windows_sys::Win32::Security::PSECURITY_DESCRIPTOR;
+use windows_sys::Win32::Security::SECURITY_ATTRIBUTES;
+use windows_sys::Win32::Security::SID_NAME_USE;
+use windows_sys::Win32::Storage::FileSystem::CREATE_NEW;
+use windows_sys::Win32::Storage::FileSystem::CreateFileW;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_NORMAL;
+
+use crate::SANDBOX_USERS_GROUP;
+use crate::SETUP_VERSION;
+use crate::SetupErrorCode;
+use crate::SetupFailure;
+use crate::dpapi_protect;
+use crate::ensure_sandbox_users_group;
+use crate::resolve_sid;
+use crate::sandbox_dir;
+use crate::sandbox_secrets_dir;
+use crate::string_from_sid_bytes;
+use crate::to_wide;
+use crate::write_file_atomically;
+
+use super::SetupMode;
+
+const SID_USERS: &str = "S-1-5-32-545";
+
+pub fn resolve_sandbox_users_group_sid() -> Result<Vec<u8>> {
+    resolve_sid(SANDBOX_USERS_GROUP)
+}
+
+pub(super) fn provision_sandbox_users(
+    codex_home: &Path,
+    offline_username: &str,
+    online_username: &str,
+    new_user_flags: u32,
+    log: &mut dyn Write,
+    mode: SetupMode,
+) -> Result<()> {
+    if let Err(err) = ensure_sandbox_users_group() {
+        let message = format!("failed to create local group {SANDBOX_USERS_GROUP}: {err}");
+        super::log_line(log, &message)?;
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperUsersGroupCreateFailed,
+            message,
+        )));
+    }
+    super::log_line(
+        log,
+        &format!("ensuring sandbox users offline={offline_username} online={online_username}"),
+    )?;
+    let offline_password = random_password();
+    let online_password = random_password();
+    ensure_sandbox_user(offline_username, &offline_password, new_user_flags, log)?;
+    ensure_sandbox_user(online_username, &online_password, new_user_flags, log)?;
+    write_secrets(
+        codex_home,
+        offline_username,
+        &offline_password,
+        online_username,
+        &online_password,
+        mode,
+    )?;
+    Ok(())
+}
+
+pub fn ensure_sandbox_user(
+    username: &str,
+    password: &str,
+    new_user_flags: u32,
+    log: &mut dyn Write,
+) -> Result<()> {
+    ensure_local_user(username, password, new_user_flags, log)?;
+    ensure_local_group_member(SANDBOX_USERS_GROUP, username)?;
+    Ok(())
+}
+
+pub fn ensure_local_user(
+    name: &str,
+    password: &str,
+    new_user_flags: u32,
+    log: &mut dyn Write,
+) -> Result<()> {
+    let name_w = to_wide(OsStr::new(name));
+    let pwd_w = to_wide(OsStr::new(password));
+    unsafe {
+        let info = USER_INFO_1 {
+            usri1_name: name_w.as_ptr() as *mut u16,
+            usri1_password: pwd_w.as_ptr() as *mut u16,
+            usri1_password_age: 0,
+            usri1_priv: USER_PRIV_USER,
+            usri1_home_dir: std::ptr::null_mut(),
+            usri1_comment: std::ptr::null_mut(),
+            usri1_flags: UF_SCRIPT | UF_DONT_EXPIRE_PASSWD | new_user_flags,
+            usri1_script_path: std::ptr::null_mut(),
+        };
+        let status = NetUserAdd(
+            std::ptr::null(),
+            1,
+            &info as *const _ as *mut u8,
+            std::ptr::null_mut(),
+        );
+        if status != NERR_Success {
+            // Try update password via level 1003.
+            let pw_info = USER_INFO_1003 {
+                usri1003_password: pwd_w.as_ptr() as *mut u16,
+            };
+            let upd = NetUserSetInfo(
+                std::ptr::null(),
+                name_w.as_ptr(),
+                1003,
+                &pw_info as *const _ as *mut u8,
+                std::ptr::null_mut(),
+            );
+            if upd != NERR_Success {
+                super::log_line(log, &format!("NetUserSetInfo failed for {name} code {upd}"))?;
+                return Err(anyhow::Error::new(SetupFailure::new(
+                    SetupErrorCode::HelperUserCreateOrUpdateFailed,
+                    format!("failed to create/update user {name}, code {status}/{upd}"),
+                )));
+            }
+        }
+
+        // Ensure the principal is a regular local user account.
+        if let Ok(group_name) = lookup_account_name_for_sid(SID_USERS) {
+            let group = to_wide(OsStr::new(&group_name));
+            let member = LOCALGROUP_MEMBERS_INFO_3 {
+                lgrmi3_domainandname: name_w.as_ptr() as *mut u16,
+            };
+            let _ = NetLocalGroupAddMembers(
+                std::ptr::null(),
+                group.as_ptr(),
+                3,
+                &member as *const _ as *mut u8,
+                1,
+            );
+        } else {
+            super::log_line(
+                log,
+                "LookupAccountSidW failed for Users SID; skipping Users group membership",
+            )?;
+        }
+    }
+    Ok(())
+}
+
+pub fn ensure_local_group_member(group_name: &str, member_name: &str) -> Result<()> {
+    // If the member is already in the group, NetLocalGroupAddMembers may
+    // return an error code. We don't care.
+    let group_w = to_wide(OsStr::new(group_name));
+    let member_w = to_wide(OsStr::new(member_name));
+    unsafe {
+        let member = LOCALGROUP_MEMBERS_INFO_3 {
+            lgrmi3_domainandname: member_w.as_ptr() as *mut u16,
+        };
+        let _ = NetLocalGroupAddMembers(
+            std::ptr::null(),
+            group_w.as_ptr(),
+            3,
+            &member as *const _ as *mut u8,
+            1,
+        );
+    }
+    Ok(())
+}
+
+fn lookup_account_name_for_sid(sid_str: &str) -> Result<String> {
+    let sid_w = to_wide(OsStr::new(sid_str));
+    let mut psid: *mut c_void = std::ptr::null_mut();
+    if unsafe { ConvertStringSidToSidW(sid_w.as_ptr(), &mut psid) } == 0 {
+        return Err(anyhow::anyhow!(
+            "ConvertStringSidToSidW failed for {sid_str}: {}",
+            unsafe { GetLastError() }
+        ));
+    }
+    let mut name_len: u32 = 0;
+    let mut domain_len: u32 = 0;
+    let mut use_type: SID_NAME_USE = 0;
+    let ok = unsafe {
+        LookupAccountSidW(
+            std::ptr::null(),
+            psid,
+            std::ptr::null_mut(),
+            &mut name_len,
+            std::ptr::null_mut(),
+            &mut domain_len,
+            &mut use_type,
+        )
+    };
+    if ok == 0 {
+        let err = unsafe { GetLastError() };
+        if err != ERROR_INSUFFICIENT_BUFFER {
+            unsafe {
+                LocalFree(psid as _);
+            }
+            return Err(anyhow::anyhow!(
+                "LookupAccountSidW preflight failed for {sid_str}: {err}"
+            ));
+        }
+    }
+    let mut name_buf: Vec<u16> = vec![0u16; name_len as usize];
+    let mut domain_buf: Vec<u16> = vec![0u16; domain_len as usize];
+    let ok = unsafe {
+        LookupAccountSidW(
+            std::ptr::null(),
+            psid,
+            name_buf.as_mut_ptr(),
+            &mut name_len,
+            domain_buf.as_mut_ptr(),
+            &mut domain_len,
+            &mut use_type,
+        )
+    };
+    unsafe {
+        LocalFree(psid as _);
+    }
+    if ok == 0 {
+        return Err(anyhow::anyhow!(
+            "LookupAccountSidW failed for {sid_str}: {}",
+            unsafe { GetLastError() }
+        ));
+    }
+    let name = String::from_utf16_lossy(&name_buf);
+    Ok(name.trim_end_matches('\0').to_string())
+}
+
+pub fn sid_bytes_to_psid(sid: &[u8]) -> Result<*mut c_void> {
+    let sid_str = string_from_sid_bytes(sid).map_err(anyhow::Error::msg)?;
+    let sid_w = to_wide(OsStr::new(&sid_str));
+    let mut psid: *mut c_void = std::ptr::null_mut();
+    if unsafe { ConvertStringSidToSidW(sid_w.as_ptr(), &mut psid) } == 0 {
+        return Err(anyhow::anyhow!(
+            "ConvertStringSidToSidW failed: {}",
+            unsafe { GetLastError() }
+        ));
+    }
+    Ok(psid)
+}
+
+fn random_password() -> String {
+    const CHARS: &[u8] =
+        b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()-_=+";
+    let mut rng = SmallRng::from_entropy();
+    let mut buf = [0u8; 24];
+    rng.fill_bytes(&mut buf);
+    buf.iter()
+        .map(|b| {
+            let idx = (*b as usize) % CHARS.len();
+            CHARS[idx] as char
+        })
+        .collect()
+}
+
+#[derive(Serialize)]
+struct SandboxUserRecord {
+    username: String,
+    password: String,
+}
+
+#[derive(Serialize)]
+struct SandboxUsersFile {
+    version: u32,
+    offline: SandboxUserRecord,
+    online: SandboxUserRecord,
+}
+
+#[derive(Serialize)]
+struct SetupMarker {
+    version: u32,
+    offline_username: String,
+    online_username: String,
+    created_at: String,
+    proxy_ports: Vec<u16>,
+    allow_local_binding: bool,
+    read_roots: Vec<PathBuf>,
+    write_roots: Vec<PathBuf>,
+}
+
+fn write_secrets(
+    codex_home: &Path,
+    offline_user: &str,
+    offline_pwd: &str,
+    online_user: &str,
+    online_pwd: &str,
+    mode: SetupMode,
+) -> Result<()> {
+    let secrets_dir = sandbox_secrets_dir(codex_home);
+    std::fs::create_dir_all(&secrets_dir).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperUsersFileWriteFailed,
+            format!(
+                "failed to create secrets dir {}: {err}",
+                secrets_dir.display()
+            ),
+        ))
+    })?;
+    let offline_blob = dpapi_protect(offline_pwd.as_bytes()).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperDpapiProtectFailed,
+            format!("dpapi protect failed for offline user: {err}"),
+        ))
+    })?;
+    let online_blob = dpapi_protect(online_pwd.as_bytes()).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperDpapiProtectFailed,
+            format!("dpapi protect failed for online user: {err}"),
+        ))
+    })?;
+    let users = SandboxUsersFile {
+        version: SETUP_VERSION,
+        offline: SandboxUserRecord {
+            username: offline_user.to_string(),
+            password: BASE64.encode(offline_blob),
+        },
+        online: SandboxUserRecord {
+            username: online_user.to_string(),
+            password: BASE64.encode(online_blob),
+        },
+    };
+    let users_path = secrets_dir.join("sandbox_users.json");
+    let users_json = serde_json::to_vec_pretty(&users).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperUsersFileWriteFailed,
+            format!("serialize sandbox users failed: {err}"),
+        ))
+    })?;
+    let write_result = match mode {
+        SetupMode::ProvisionOnly => write_file_atomically(&users_path, &users_json),
+        SetupMode::Full | SetupMode::InteractiveProvision | SetupMode::ReadAclsOnly => {
+            std::fs::write(&users_path, users_json).map_err(anyhow::Error::from)
+        }
+    };
+    write_result.map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperUsersFileWriteFailed,
+            format!(
+                "write sandbox users file {} failed: {err}",
+                users_path.display()
+            ),
+        ))
+    })?;
+    Ok(())
+}
+
+/// Service provisioning retains the marker's exclusive handle; legacy setup reopens it at commit.
+pub(super) enum PreparedSetupMarker {
+    Retained(File),
+    Reopen,
+}
+
+// Create the final marker with its protected ACL. The empty file intentionally fails readiness
+// checks until setup succeeds. Only service provisioning pins it for the entire operation.
+pub(super) fn prepare_setup_marker(
+    codex_home: &Path,
+    real_user: &str,
+    mode: SetupMode,
+) -> Result<PreparedSetupMarker> {
+    let marker_path = sandbox_dir(codex_home).join("setup_marker.json");
+    match std::fs::remove_file(&marker_path) {
+        Ok(()) => {}
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+        Err(err) => {
+            return Err(anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperSetupMarkerWriteFailed,
+                format!(
+                    "remove setup marker file {} failed: {err}",
+                    marker_path.display()
+                ),
+            )));
+        }
+    }
+
+    let real_user_sid = resolve_sid(real_user)
+        .and_then(|sid| string_from_sid_bytes(&sid).map_err(anyhow::Error::msg))
+        .map_err(|err| {
+            anyhow::Error::new(SetupFailure::new(
+                SetupErrorCode::HelperSetupMarkerWriteFailed,
+                format!("resolve real user SID for setup marker failed: {err}"),
+            ))
+        })?;
+    let sddl = to_wide(format!(
+        "D:P(A;;GA;;;SY)(A;;GA;;;BA)(A;;GA;;;{real_user_sid})"
+    ));
+    let mut security_descriptor: PSECURITY_DESCRIPTOR = std::ptr::null_mut();
+    let converted = unsafe {
+        ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            sddl.as_ptr(),
+            SDDL_REVISION_1,
+            &mut security_descriptor,
+            std::ptr::null_mut(),
+        )
+    };
+    if converted == 0 {
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSetupMarkerWriteFailed,
+            format!(
+                "create setup marker security descriptor failed: {}",
+                unsafe { GetLastError() }
+            ),
+        )));
+    }
+
+    let security_attributes = SECURITY_ATTRIBUTES {
+        nLength: std::mem::size_of::<SECURITY_ATTRIBUTES>() as u32,
+        lpSecurityDescriptor: security_descriptor,
+        bInheritHandle: 0,
+    };
+    let marker_path_wide = to_wide(marker_path.as_os_str());
+    let marker_handle = unsafe {
+        CreateFileW(
+            marker_path_wide.as_ptr(),
+            GENERIC_WRITE,
+            /*dwsharemode*/ 0,
+            &security_attributes,
+            CREATE_NEW,
+            FILE_ATTRIBUTE_NORMAL,
+            /*htemplatefile*/ 0,
+        )
+    };
+    let create_error = unsafe { GetLastError() };
+    unsafe {
+        LocalFree(security_descriptor as _);
+    }
+    if marker_handle == INVALID_HANDLE_VALUE {
+        return Err(anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSetupMarkerWriteFailed,
+            format!(
+                "create protected setup marker file {} failed: {}",
+                marker_path.display(),
+                create_error
+            ),
+        )));
+    }
+    let file = unsafe { File::from_raw_handle(marker_handle as *mut c_void) };
+    match mode {
+        SetupMode::ProvisionOnly => Ok(PreparedSetupMarker::Retained(file)),
+        SetupMode::Full | SetupMode::InteractiveProvision | SetupMode::ReadAclsOnly => {
+            drop(file);
+            Ok(PreparedSetupMarker::Reopen)
+        }
+    }
+}
+
+pub(super) fn commit_setup_marker(
+    file: PreparedSetupMarker,
+    codex_home: &Path,
+    offline_user: &str,
+    online_user: &str,
+    proxy_ports: &[u16],
+    allow_local_binding: bool,
+) -> Result<()> {
+    let marker = SetupMarker {
+        version: SETUP_VERSION,
+        offline_username: offline_user.to_string(),
+        online_username: online_user.to_string(),
+        created_at: chrono::Utc::now().to_rfc3339(),
+        proxy_ports: proxy_ports.to_vec(),
+        allow_local_binding,
+        read_roots: Vec::new(),
+        write_roots: Vec::new(),
+    };
+    let marker_path = sandbox_dir(codex_home).join("setup_marker.json");
+    let marker_json = serde_json::to_vec_pretty(&marker).map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSetupMarkerWriteFailed,
+            format!("serialize setup marker failed: {err}"),
+        ))
+    })?;
+    let write_result = match file {
+        PreparedSetupMarker::Retained(mut file) => file.write_all(&marker_json),
+        PreparedSetupMarker::Reopen => std::fs::write(&marker_path, marker_json),
+    };
+    write_result.map_err(|err| {
+        anyhow::Error::new(SetupFailure::new(
+            SetupErrorCode::HelperSetupMarkerWriteFailed,
+            format!(
+                "write setup marker file {} failed: {err}",
+                marker_path.display()
+            ),
+        ))
+    })?;
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/service.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/service.rs
new file mode 100644
index 0000000000000000000000000000000000000000..013c1a4f20acffe93cdf8c6c3ad3e735578ece81
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/service.rs
@@ -0,0 +1,49 @@
+//! Adapts authenticated service provisioning to the existing setup transaction.
+//! The caller owns admission, directory pins, and the setup mutex.
+
+use super::Payload;
+use super::SetupMode;
+use super::run_payload;
+use crate::SETUP_VERSION;
+use crate::SetupRuntime;
+use crate::logging::log_note;
+use crate::sandbox_dir;
+use anyhow::Result;
+use std::path::Path;
+
+/// Runs the existing ProvisionOnly setup transaction without launching a helper process.
+/// The caller authenticates the owner, retains directory protections, and holds the setup mutex
+/// on this thread across registration. Firewall setup preserves the caller's COM apartment.
+pub fn provision_sandbox_in_process(
+    codex_home: &Path,
+    real_user: &str,
+    settings: crate::WindowsSandboxProvisioningSettings,
+    runtime: SetupRuntime,
+) -> Result<()> {
+    let payload = Payload {
+        version: SETUP_VERSION,
+        offline_username: crate::setup::OFFLINE_USERNAME.to_string(),
+        online_username: crate::setup::ONLINE_USERNAME.to_string(),
+        codex_home: codex_home.to_path_buf(),
+        command_cwd: codex_home.to_path_buf(),
+        read_roots: Vec::new(),
+        write_roots: Vec::new(),
+        deny_read_paths: Vec::new(),
+        deny_write_paths: Vec::new(),
+        proxy_ports: settings.proxy_ports,
+        allow_local_binding: settings.allow_local_binding,
+        otel: codex_otel::global_statsig_metrics_settings(),
+        real_user: real_user.to_string(),
+        mode: SetupMode::ProvisionOnly,
+        runtime,
+        refresh_only: false,
+    };
+    run_payload(&payload)?;
+    if let Err(err) = crate::setup_error::clear_setup_error_report(codex_home) {
+        log_note(
+            &format!("setup orchestrator: failed to clear setup_error.json after success: {err}"),
+            Some(&sandbox_dir(codex_home)),
+        );
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/setup_runtime_bin.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/setup_runtime_bin.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f2c16a8705e11014610dd359ce61d1f6ad62df5a
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/setup_runtime_bin.rs
@@ -0,0 +1,117 @@
+use std::ffi::c_void;
+use std::io::Write;
+use std::os::windows::fs::MetadataExt as _;
+use std::path::PathBuf;
+
+use crate::ensure_allow_mask_aces_with_inheritance;
+use crate::path_mask_allows;
+use anyhow::Result;
+use windows_sys::Win32::Security::CONTAINER_INHERIT_ACE;
+use windows_sys::Win32::Security::OBJECT_INHERIT_ACE;
+use windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_REPARSE_POINT;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_EXECUTE;
+use windows_sys::Win32::Storage::FileSystem::FILE_GENERIC_READ;
+
+#[cfg(test)]
+#[path = "setup_runtime_bin_tests.rs"]
+mod tests;
+
+pub(super) fn ensure_codex_app_runtime_paths_readable(
+    sandbox_group_psid: *mut c_void,
+    refresh_errors: &mut Vec<String>,
+    log: &mut dyn Write,
+) -> Result<()> {
+    let read_execute_mask = FILE_GENERIC_READ | FILE_GENERIC_EXECUTE;
+    let runtime_paths = runtime_paths(
+        local_app_data_root(),
+        std::env::var_os("USERPROFILE").map(PathBuf::from),
+    );
+
+    for runtime_path in runtime_paths {
+        if !std::fs::symlink_metadata(&runtime_path).is_ok_and(|metadata| {
+            metadata.is_dir() && (metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT) == 0
+        }) {
+            continue;
+        }
+
+        let has_access = match path_mask_allows(
+            &runtime_path,
+            &[sandbox_group_psid],
+            read_execute_mask,
+            /*require_all_bits*/ true,
+        ) {
+            Ok(has_access) => has_access,
+            Err(err) => {
+                refresh_errors.push(format!(
+                    "runtime read/execute mask check failed on {} for sandbox_group: {err}",
+                    runtime_path.display()
+                ));
+                super::log_line(
+                    log,
+                    &format!(
+                        "runtime read/execute mask check failed on {} for sandbox_group: {err}; continuing",
+                        runtime_path.display()
+                    ),
+                )?;
+                false
+            }
+        };
+        if has_access {
+            continue;
+        }
+
+        super::log_line(
+            log,
+            &format!(
+                "granting read/execute ACE to {} for sandbox users",
+                runtime_path.display()
+            ),
+        )?;
+        let result = unsafe {
+            ensure_allow_mask_aces_with_inheritance(
+                &runtime_path,
+                &[sandbox_group_psid],
+                read_execute_mask,
+                OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE,
+            )
+        };
+        if let Err(err) = result {
+            refresh_errors.push(format!(
+                "grant read/execute ACE failed on {} for sandbox_group: {err}",
+                runtime_path.display()
+            ));
+            super::log_line(
+                log,
+                &format!(
+                    "grant read/execute ACE failed on {} for sandbox_group: {err}",
+                    runtime_path.display()
+                ),
+            )?;
+        }
+    }
+    Ok(())
+}
+
+fn runtime_paths(local_app_data: Option<PathBuf>, user_profile: Option<PathBuf>) -> Vec<PathBuf> {
+    let mut runtime_paths = Vec::new();
+    if let Some(local_app_data) = local_app_data {
+        let codex_root = local_app_data.join("OpenAI").join("Codex");
+        runtime_paths.push(codex_root);
+    }
+    // The managed primary runtime is installed outside the LocalAppData runtime roots.
+    if let Some(user_profile) = user_profile {
+        runtime_paths.push(user_profile.join(".cache").join("codex-runtimes"));
+    }
+
+    runtime_paths
+}
+
+fn local_app_data_root() -> Option<PathBuf> {
+    std::env::var_os("LOCALAPPDATA")
+        .map(PathBuf::from)
+        .or_else(|| {
+            std::env::var_os("USERPROFILE")
+                .map(PathBuf::from)
+                .map(|profile| profile.join("AppData").join("Local"))
+        })
+}
diff --git a/codex-rs/windows-sandbox-rs/src/setup_provisioning/setup_runtime_bin_tests.rs b/codex-rs/windows-sandbox-rs/src/setup_provisioning/setup_runtime_bin_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ad8aa7c3e46fd05403649f7abb5422d513e6a77f
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/setup_provisioning/setup_runtime_bin_tests.rs
@@ -0,0 +1,27 @@
+use super::runtime_paths;
+use pretty_assertions::assert_eq;
+use std::path::PathBuf;
+
+#[test]
+fn runtime_paths_include_desktop_parent_and_primary_runtime_roots() {
+    let local_app_data = PathBuf::from(r"C:\Users\user\AppData\Local");
+    let user_profile = PathBuf::from(r"C:\Users\user");
+
+    assert_eq!(
+        runtime_paths(Some(local_app_data), Some(user_profile)),
+        vec![
+            PathBuf::from(r"C:\Users\user\AppData\Local\OpenAI\Codex"),
+            PathBuf::from(r"C:\Users\user\.cache\codex-runtimes"),
+        ]
+    );
+}
+
+#[test]
+fn primary_runtime_path_does_not_depend_on_local_app_data() {
+    let user_profile = PathBuf::from(r"C:\Users\user");
+
+    assert_eq!(
+        runtime_paths(/*local_app_data*/ None, Some(user_profile)),
+        vec![PathBuf::from(r"C:\Users\user\.cache\codex-runtimes")]
+    );
+}
diff --git a/codex-rs/windows-sandbox-rs/src/spawn_prep.rs b/codex-rs/windows-sandbox-rs/src/spawn_prep.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a19f0eeaac0818b661b0cf4452e21f254a1f8630
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/spawn_prep.rs
@@ -0,0 +1,719 @@
+use crate::acl::add_allow_ace;
+use crate::acl::add_deny_write_ace;
+use crate::acl::allow_null_device;
+use crate::acl::ensure_allow_write_aces;
+use crate::allow::AllowDenyPaths;
+use crate::allow::compute_allow_paths_for_permissions;
+use crate::cap::load_or_create_cap_sids;
+use crate::cap::workspace_write_cap_sid_for_root;
+use crate::cap::workspace_write_root_contains_path;
+use crate::cap::workspace_write_root_overlaps_path;
+use crate::cap::workspace_write_root_specificity;
+use crate::deny_read_state::sync_persistent_deny_read_acls;
+use crate::env::apply_no_network_to_env;
+use crate::env::ensure_non_interactive_pager;
+use crate::env::inherit_path_env;
+use crate::env::normalize_null_device_env;
+use crate::identity::SandboxCreds;
+use crate::identity::require_logon_sandbox_creds;
+use crate::logging::log_start;
+use crate::path_normalization::canonicalize_path;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::sandbox_utils::ensure_codex_home_exists;
+use crate::sandbox_utils::inject_git_safe_directory;
+use crate::setup::effective_write_roots_for_permissions;
+use crate::token::LocalSid;
+use crate::token::create_readonly_token_with_cap;
+use crate::token::create_workspace_write_token_with_caps_from;
+use crate::token::get_current_token_for_restriction;
+use crate::token::get_logon_sid_bytes;
+use crate::workspace_acl::is_command_cwd_root;
+use crate::workspace_acl::protect_workspace_agents_dir;
+use crate::workspace_acl::protect_workspace_codex_dir;
+use anyhow::Context;
+use anyhow::Result;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::collections::HashMap;
+use std::ffi::c_void;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::HANDLE;
+
+pub(crate) struct SpawnContext {
+    pub(crate) permissions: ResolvedWindowsSandboxPermissions,
+    pub(crate) current_dir: PathBuf,
+    pub(crate) logs_base_dir: Option<PathBuf>,
+    pub(crate) uses_write_capabilities: bool,
+}
+
+pub(crate) struct ElevatedSpawnContext {
+    pub(crate) sandbox_base: PathBuf,
+    pub(crate) logs_base_dir: Option<PathBuf>,
+    pub(crate) sandbox_creds: SandboxCreds,
+    pub(crate) cap_sids: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct SpawnPrepOptions {
+    pub(crate) inherit_path: bool,
+    pub(crate) add_git_safe_directory: bool,
+}
+
+pub(crate) struct LegacySessionSecurity {
+    pub(crate) h_token: HANDLE,
+    pub(crate) readonly_sid: Option<LocalSid>,
+    pub(crate) readonly_sid_str: Option<String>,
+    pub(crate) write_root_sids: Vec<RootCapabilitySid>,
+}
+
+pub(crate) struct RootCapabilitySid {
+    pub(crate) root: PathBuf,
+    pub(crate) sid: LocalSid,
+    pub(crate) sid_str: String,
+}
+
+pub(crate) struct LegacyAclSids<'a> {
+    pub(crate) readonly_sid: Option<&'a LocalSid>,
+    pub(crate) readonly_sid_str: Option<&'a str>,
+    pub(crate) write_root_sids: &'a [RootCapabilitySid],
+}
+
+pub(crate) fn prepare_spawn_context_common(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    codex_home: &Path,
+    cwd: &Path,
+    env_map: &mut HashMap<String, String>,
+    command: &[String],
+    options: SpawnPrepOptions,
+) -> Result<SpawnContext> {
+    let permissions =
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        )?;
+
+    normalize_null_device_env(env_map);
+    ensure_non_interactive_pager(env_map);
+    if options.inherit_path {
+        inherit_path_env(env_map);
+    }
+    if options.add_git_safe_directory {
+        inject_git_safe_directory(env_map, cwd);
+    }
+
+    ensure_codex_home_exists(codex_home)?;
+    let sandbox_base = codex_home.join(".sandbox");
+    std::fs::create_dir_all(&sandbox_base)?;
+    let logs_base_dir = Some(sandbox_base);
+    log_start(command, logs_base_dir.as_deref());
+
+    let uses_write_capabilities = permissions.uses_write_capabilities_for_cwd(cwd, env_map);
+
+    Ok(SpawnContext {
+        permissions,
+        current_dir: cwd.to_path_buf(),
+        logs_base_dir,
+        uses_write_capabilities,
+    })
+}
+
+pub(crate) fn prepare_legacy_spawn_context(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    codex_home: &Path,
+    cwd: &Path,
+    env_map: &mut HashMap<String, String>,
+    command: &[String],
+    options: SpawnPrepOptions,
+) -> Result<SpawnContext> {
+    let common = prepare_spawn_context_common(
+        permission_profile,
+        workspace_roots,
+        codex_home,
+        cwd,
+        env_map,
+        command,
+        options,
+    )?;
+    if common.permissions.should_apply_network_block() {
+        apply_no_network_to_env(env_map)?;
+    }
+    Ok(common)
+}
+
+pub(crate) fn prepare_legacy_session_security(
+    uses_write_capabilities: bool,
+    codex_home: &Path,
+    cwd: &Path,
+    capability_roots: impl IntoIterator<Item = PathBuf>,
+) -> Result<LegacySessionSecurity> {
+    let caps = load_or_create_cap_sids(codex_home)?;
+    let (h_token, readonly_sid, readonly_sid_str, write_root_sids) = unsafe {
+        if uses_write_capabilities {
+            let write_root_sids = root_capability_sids(codex_home, cwd, capability_roots)?;
+            if write_root_sids.is_empty() {
+                anyhow::bail!("workspace-write sandbox has no writable root capability SIDs");
+            }
+            let base = get_current_token_for_restriction()?;
+            let cap_ptrs: Vec<*mut c_void> = write_root_sids
+                .iter()
+                .map(|root| root.sid.as_ptr())
+                .collect();
+            let h_token = create_workspace_write_token_with_caps_from(base, cap_ptrs.as_slice());
+            CloseHandle(base);
+            let h_token = h_token?;
+            (h_token, None, None, write_root_sids)
+        } else {
+            let psid = LocalSid::from_string(&caps.readonly)?;
+            let (h_token, _psid) = create_readonly_token_with_cap(psid.as_ptr())?;
+            (h_token, Some(psid), Some(caps.readonly), Vec::new())
+        }
+    };
+
+    Ok(LegacySessionSecurity {
+        h_token,
+        readonly_sid,
+        readonly_sid_str,
+        write_root_sids,
+    })
+}
+
+pub(crate) fn legacy_session_capability_roots(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    current_dir: &Path,
+    env_map: &HashMap<String, String>,
+    codex_home: &Path,
+) -> Vec<PathBuf> {
+    let allow_paths = compute_allow_paths_for_permissions(permissions, current_dir, env_map)
+        .allow
+        .into_iter()
+        .collect::<Vec<_>>();
+    if permissions.uses_write_capabilities_for_cwd(current_dir, env_map) {
+        effective_write_roots_for_permissions(
+            permissions,
+            current_dir,
+            env_map,
+            codex_home,
+            Some(allow_paths.as_slice()),
+        )
+    } else {
+        allow_paths
+    }
+}
+
+pub(crate) fn root_capability_sids(
+    codex_home: &Path,
+    cwd: &Path,
+    allow_paths: impl IntoIterator<Item = PathBuf>,
+) -> Result<Vec<RootCapabilitySid>> {
+    let mut roots: Vec<PathBuf> = allow_paths.into_iter().collect();
+    roots.sort_by_key(|root| canonicalize_path(root.as_path()));
+    roots.dedup_by(|a, b| canonicalize_path(a.as_path()) == canonicalize_path(b.as_path()));
+
+    let mut out = Vec::with_capacity(roots.len());
+    for root in roots {
+        let sid_str = workspace_write_cap_sid_for_root(codex_home, cwd, &root)?;
+        let sid = LocalSid::from_string(&sid_str)?;
+        out.push(RootCapabilitySid { root, sid, sid_str });
+    }
+    Ok(out)
+}
+
+fn matching_root_capability<'a>(
+    path: &Path,
+    root_sids: &'a [RootCapabilitySid],
+) -> Option<&'a RootCapabilitySid> {
+    root_sids
+        .iter()
+        .filter(|root_sid| workspace_write_root_contains_path(&root_sid.root, path))
+        .max_by_key(|root_sid| workspace_write_root_specificity(&root_sid.root))
+}
+
+fn deny_root_capabilities_for_path<'a>(
+    path: &Path,
+    root_sids: &'a [RootCapabilitySid],
+) -> Vec<&'a RootCapabilitySid> {
+    let matching_root_sids = root_sids
+        .iter()
+        .filter(|root_sid| workspace_write_root_overlaps_path(&root_sid.root, path))
+        .collect::<Vec<_>>();
+    if matching_root_sids.is_empty() {
+        root_sids.iter().collect()
+    } else {
+        matching_root_sids
+    }
+}
+
+pub(crate) fn allow_null_device_for_workspace_write(is_workspace_write: bool) {
+    if !is_workspace_write {
+        return;
+    }
+
+    unsafe {
+        if let Ok(base) = get_current_token_for_restriction() {
+            if let Ok(bytes) = get_logon_sid_bytes(base) {
+                let mut tmp = bytes;
+                let psid = tmp.as_mut_ptr() as *mut c_void;
+                allow_null_device(psid);
+            }
+            CloseHandle(base);
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn apply_legacy_session_acl_rules(
+    permissions: &ResolvedWindowsSandboxPermissions,
+    codex_home: &Path,
+    current_dir: &Path,
+    env_map: &HashMap<String, String>,
+    additional_deny_read_paths: &[PathBuf],
+    additional_deny_write_paths: &[PathBuf],
+    acl_sids: LegacyAclSids<'_>,
+) -> Result<()> {
+    let AllowDenyPaths { allow, mut deny } =
+        compute_allow_paths_for_permissions(permissions, current_dir, env_map);
+    unsafe {
+        for path in additional_deny_write_paths {
+            // Explicit carveouts must exist before the command starts so the
+            // sandbox cannot create them under a writable parent first.
+            if !path.exists() {
+                std::fs::create_dir_all(path)
+                    .with_context(|| format!("create deny-write path {}", path.display()))?;
+            }
+            deny.insert(path.clone());
+        }
+        if let Some(readonly_sid) = acl_sids.readonly_sid {
+            for p in &allow {
+                let _ = add_allow_ace(p, readonly_sid.as_ptr());
+            }
+        } else {
+            for p in &allow {
+                let Some(root_sid) = matching_root_capability(p, acl_sids.write_root_sids) else {
+                    continue;
+                };
+                let _ = ensure_allow_write_aces(p, &[root_sid.sid.as_ptr()]);
+            }
+        }
+        for p in &deny {
+            for root_sid in deny_root_capabilities_for_path(p, acl_sids.write_root_sids) {
+                let _ = add_deny_write_ace(p, root_sid.sid.as_ptr());
+            }
+        }
+        if !additional_deny_read_paths.is_empty() {
+            if let Some(readonly_sid) = acl_sids.readonly_sid {
+                let Some(readonly_sid_str) = acl_sids.readonly_sid_str else {
+                    anyhow::bail!("readonly capability SID string missing");
+                };
+                sync_persistent_deny_read_acls(
+                    codex_home,
+                    readonly_sid_str,
+                    additional_deny_read_paths,
+                    readonly_sid.as_ptr(),
+                )?;
+            } else {
+                for root_sid in acl_sids.write_root_sids {
+                    sync_persistent_deny_read_acls(
+                        codex_home,
+                        &root_sid.sid_str,
+                        additional_deny_read_paths,
+                        root_sid.sid.as_ptr(),
+                    )?;
+                }
+            }
+        }
+        for root_sid in acl_sids.write_root_sids {
+            allow_null_device(root_sid.sid.as_ptr());
+        }
+        if let Some(readonly_sid) = acl_sids.readonly_sid {
+            allow_null_device(readonly_sid.as_ptr());
+        }
+        if !acl_sids.write_root_sids.is_empty()
+            && let Some(workspace_sid) =
+                matching_root_capability(current_dir, acl_sids.write_root_sids)
+        {
+            let canonical_cwd = canonicalize_path(current_dir);
+            if is_command_cwd_root(&workspace_sid.root, &canonical_cwd) {
+                let _ = protect_workspace_codex_dir(current_dir, workspace_sid.sid.as_ptr());
+                let _ = protect_workspace_agents_dir(current_dir, workspace_sid.sid.as_ptr());
+            }
+        }
+    }
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn prepare_elevated_spawn_context_for_permissions(
+    permissions: ResolvedWindowsSandboxPermissions,
+    codex_home: &Path,
+    cwd: &Path,
+    env_map: &mut HashMap<String, String>,
+    command: &[String],
+    read_roots_override: Option<&[PathBuf]>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<&[PathBuf]>,
+    deny_read_paths_override: &[PathBuf],
+    deny_write_paths_override: &[PathBuf],
+    proxy_enforced: bool,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+) -> Result<ElevatedSpawnContext> {
+    normalize_null_device_env(env_map);
+    ensure_non_interactive_pager(env_map);
+    inherit_path_env(env_map);
+    inject_git_safe_directory(env_map, cwd);
+
+    // Use a temp-based log dir that the sandbox user can write.
+    let sandbox_base = codex_home.join(".sandbox");
+    ensure_codex_home_exists(&sandbox_base)?;
+    let logs_base_dir = Some(sandbox_base.clone());
+    log_start(command, logs_base_dir.as_deref());
+
+    let uses_write_capabilities = permissions.uses_write_capabilities_for_cwd(cwd, env_map);
+
+    let AllowDenyPaths { allow, deny } =
+        compute_allow_paths_for_permissions(&permissions, cwd, env_map);
+    let write_roots: Vec<PathBuf> = allow.into_iter().collect();
+    let deny_write_paths: Vec<PathBuf> = deny.into_iter().collect();
+    let computed_write_roots_override = if uses_write_capabilities {
+        Some(write_roots.as_slice())
+    } else {
+        None
+    };
+    let write_roots_for_setup = write_roots_override.or(computed_write_roots_override);
+    let effective_write_roots = if uses_write_capabilities {
+        effective_write_roots_for_permissions(
+            &permissions,
+            cwd,
+            env_map,
+            codex_home,
+            write_roots_for_setup,
+        )
+    } else {
+        Vec::new()
+    };
+    let setup_write_roots_override = if uses_write_capabilities {
+        Some(effective_write_roots.as_slice())
+    } else {
+        write_roots_override
+    };
+    let sandbox_creds = require_logon_sandbox_creds(
+        &permissions,
+        cwd,
+        env_map,
+        codex_home,
+        read_roots_override,
+        read_roots_include_platform_defaults,
+        setup_write_roots_override,
+        deny_read_paths_override,
+        if deny_write_paths_override.is_empty() {
+            &deny_write_paths
+        } else {
+            deny_write_paths_override
+        },
+        proxy_enforced,
+        proxy_settings_mode,
+    )?;
+    let caps = load_or_create_cap_sids(codex_home)?;
+    let (psid_to_use, cap_sids) = if uses_write_capabilities {
+        let cap_sids = root_capability_sids(codex_home, cwd, effective_write_roots)?
+            .into_iter()
+            .map(|root_sid| root_sid.sid_str)
+            .collect::<Vec<_>>();
+        if cap_sids.is_empty() {
+            anyhow::bail!("workspace-write sandbox has no writable root capability SIDs");
+        }
+        (LocalSid::from_string(&cap_sids[0])?, cap_sids)
+    } else {
+        (
+            LocalSid::from_string(&caps.readonly)?,
+            vec![caps.readonly.clone()],
+        )
+    };
+
+    unsafe {
+        allow_null_device(psid_to_use.as_ptr());
+    }
+
+    Ok(ElevatedSpawnContext {
+        sandbox_base,
+        logs_base_dir,
+        sandbox_creds,
+        cap_sids,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::SpawnPrepOptions;
+    use super::deny_root_capabilities_for_path;
+    use super::legacy_session_capability_roots;
+    use super::prepare_legacy_spawn_context;
+    use super::prepare_spawn_context_common;
+    use super::root_capability_sids;
+    use crate::cap::load_or_create_cap_sids;
+    use crate::cap::workspace_write_cap_sid_for_root;
+    use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+    use codex_protocol::models::PermissionProfile;
+    use codex_protocol::permissions::NetworkSandboxPolicy;
+    use codex_utils_absolute_path::AbsolutePathBuf;
+    use pretty_assertions::assert_eq;
+    use std::collections::HashMap;
+    use std::path::Path;
+    use tempfile::TempDir;
+
+    fn workspace_profile(
+        network_policy: NetworkSandboxPolicy,
+        writable_roots: &[AbsolutePathBuf],
+        exclude_tmpdir_env_var: bool,
+        exclude_slash_tmp: bool,
+    ) -> PermissionProfile {
+        PermissionProfile::workspace_write_with(
+            writable_roots,
+            network_policy,
+            exclude_tmpdir_env_var,
+            exclude_slash_tmp,
+        )
+    }
+
+    fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf> {
+        vec![AbsolutePathBuf::from_absolute_path(root).expect("absolute workspace root")]
+    }
+
+    fn should_apply_network_block(permission_profile: &PermissionProfile) -> bool {
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            &[],
+        )
+        .expect("managed permission profile")
+        .should_apply_network_block()
+    }
+
+    #[test]
+    fn no_network_env_rewrite_applies_for_workspace_write() {
+        assert!(should_apply_network_block(
+            &PermissionProfile::workspace_write()
+        ));
+    }
+
+    #[test]
+    fn no_network_env_rewrite_skips_when_network_access_is_allowed() {
+        assert!(!should_apply_network_block(&workspace_profile(
+            NetworkSandboxPolicy::Enabled,
+            &[],
+            /*exclude_tmpdir_env_var*/ false,
+            /*exclude_slash_tmp*/ false,
+        )));
+    }
+
+    #[test]
+    fn legacy_spawn_env_applies_offline_network_rewrite() {
+        let codex_home = TempDir::new().expect("tempdir");
+        let cwd = TempDir::new().expect("tempdir");
+        let mut env_map = HashMap::new();
+        let workspace_roots = workspace_roots_for(cwd.path());
+
+        let _context = prepare_legacy_spawn_context(
+            &PermissionProfile::workspace_write(),
+            workspace_roots.as_slice(),
+            codex_home.path(),
+            cwd.path(),
+            &mut env_map,
+            &["cmd.exe".to_string()],
+            SpawnPrepOptions {
+                inherit_path: true,
+                add_git_safe_directory: false,
+            },
+        )
+        .expect("legacy env prep");
+
+        assert_eq!(env_map.get("SBX_NONET_ACTIVE"), Some(&"1".to_string()));
+        assert_eq!(
+            env_map.get("HTTP_PROXY"),
+            Some(&"http://127.0.0.1:9".to_string())
+        );
+    }
+
+    #[test]
+    fn common_spawn_env_keeps_network_env_unchanged() {
+        let codex_home = TempDir::new().expect("tempdir");
+        let cwd = TempDir::new().expect("tempdir");
+        let mut env_map = HashMap::from([(
+            "HTTP_PROXY".to_string(),
+            "http://user.proxy:8080".to_string(),
+        )]);
+        let workspace_roots = workspace_roots_for(cwd.path());
+
+        let context = prepare_spawn_context_common(
+            &PermissionProfile::workspace_write(),
+            workspace_roots.as_slice(),
+            codex_home.path(),
+            cwd.path(),
+            &mut env_map,
+            &["cmd.exe".to_string()],
+            SpawnPrepOptions {
+                inherit_path: true,
+                add_git_safe_directory: true,
+            },
+        )
+        .expect("preserve existing env prep");
+        assert!(context.uses_write_capabilities);
+
+        assert_eq!(env_map.get("SBX_NONET_ACTIVE"), None);
+        assert_eq!(
+            env_map.get("HTTP_PROXY"),
+            Some(&"http://user.proxy:8080".to_string())
+        );
+    }
+
+    #[test]
+    fn legacy_session_capability_roots_use_runtime_workspace_roots_for_workspace_root() {
+        let tmp = TempDir::new().expect("tempdir");
+        let codex_home = tmp.path().join("codex-home");
+        let workspace_root = tmp.path().join("workspace");
+        let command_cwd = workspace_root.join("subdir");
+        std::fs::create_dir_all(&codex_home).expect("create codex home");
+        std::fs::create_dir_all(&command_cwd).expect("create command cwd");
+
+        let permission_profile = workspace_profile(
+            NetworkSandboxPolicy::Restricted,
+            &[],
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(workspace_root.as_path());
+        let permissions =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                &permission_profile,
+                workspace_roots.as_slice(),
+            )
+            .expect("managed permission profile");
+
+        let roots = legacy_session_capability_roots(
+            &permissions,
+            &command_cwd,
+            &HashMap::new(),
+            &codex_home,
+        );
+
+        assert_eq!(
+            roots,
+            vec![dunce::canonicalize(&workspace_root).expect("canonical workspace root")]
+        );
+    }
+
+    #[test]
+    fn root_capability_sids_only_include_active_roots() {
+        let temp = TempDir::new().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let active_root = temp.path().join("active-root");
+        let stale_root = temp.path().join("stale-root");
+        std::fs::create_dir_all(&codex_home).expect("create codex home");
+        std::fs::create_dir_all(&workspace).expect("create workspace");
+        std::fs::create_dir_all(&active_root).expect("create active root");
+        std::fs::create_dir_all(&stale_root).expect("create stale root");
+
+        let stale_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &stale_root)
+            .expect("stale sid");
+        let active_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &active_root)
+            .expect("active sid");
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let caps = load_or_create_cap_sids(&codex_home).expect("load caps");
+
+        let sid_strs = root_capability_sids(
+            &codex_home,
+            &workspace,
+            vec![workspace.clone(), active_root],
+        )
+        .expect("root capabilities")
+        .into_iter()
+        .map(|root_sid| root_sid.sid_str)
+        .collect::<Vec<_>>();
+
+        assert_eq!(sid_strs.len(), 2);
+        assert!(sid_strs.contains(&workspace_sid));
+        assert!(sid_strs.contains(&active_sid));
+        assert!(!sid_strs.contains(&stale_sid));
+        assert!(!sid_strs.contains(&caps.workspace));
+    }
+
+    #[test]
+    fn legacy_deny_path_includes_nested_active_root_sid() {
+        let temp = TempDir::new().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let protected_dir = workspace.join(".codex");
+        let nested_root = protected_dir.join("nested-root");
+        let unrelated_root = temp.path().join("unrelated-root");
+        std::fs::create_dir_all(&codex_home).expect("create codex home");
+        std::fs::create_dir_all(&workspace).expect("create workspace");
+        std::fs::create_dir_all(&nested_root).expect("create nested root");
+        std::fs::create_dir_all(&unrelated_root).expect("create unrelated root");
+
+        let workspace_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &workspace)
+            .expect("workspace sid");
+        let nested_sid = workspace_write_cap_sid_for_root(&codex_home, &workspace, &nested_root)
+            .expect("nested sid");
+        let unrelated_sid =
+            workspace_write_cap_sid_for_root(&codex_home, &workspace, &unrelated_root)
+                .expect("unrelated sid");
+        let root_sids = root_capability_sids(
+            &codex_home,
+            &workspace,
+            vec![workspace.clone(), nested_root, unrelated_root],
+        )
+        .expect("root capabilities");
+
+        let deny_sid_strs = deny_root_capabilities_for_path(&protected_dir, &root_sids)
+            .into_iter()
+            .map(|root_sid| root_sid.sid_str.clone())
+            .collect::<Vec<_>>();
+
+        assert_eq!(deny_sid_strs, vec![workspace_sid, nested_sid]);
+        assert!(!deny_sid_strs.contains(&unrelated_sid));
+    }
+
+    #[test]
+    fn legacy_capability_roots_use_effective_write_roots() {
+        let temp = TempDir::new().expect("tempdir");
+        let codex_home = temp.path().join("codex-home");
+        let workspace = temp.path().join("workspace");
+        let active_root = temp.path().join("active-root");
+        let sandbox_root = codex_home.join(".sandbox");
+        std::fs::create_dir_all(&codex_home).expect("create codex home");
+        std::fs::create_dir_all(&workspace).expect("create workspace");
+        std::fs::create_dir_all(&active_root).expect("create active root");
+        std::fs::create_dir_all(&sandbox_root).expect("create sandbox root");
+
+        let writable_roots = vec![
+            AbsolutePathBuf::try_from(active_root.as_path()).expect("active root"),
+            AbsolutePathBuf::try_from(codex_home.as_path()).expect("codex home"),
+            AbsolutePathBuf::try_from(sandbox_root.as_path()).expect("sandbox root"),
+        ];
+        let permission_profile = workspace_profile(
+            NetworkSandboxPolicy::Restricted,
+            &writable_roots,
+            /*exclude_tmpdir_env_var*/ true,
+            /*exclude_slash_tmp*/ true,
+        );
+        let workspace_roots = workspace_roots_for(workspace.as_path());
+        let permissions =
+            ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+                &permission_profile,
+                workspace_roots.as_slice(),
+            )
+            .expect("managed permission profile");
+
+        let roots =
+            legacy_session_capability_roots(&permissions, &workspace, &HashMap::new(), &codex_home);
+
+        assert!(roots.contains(&dunce::canonicalize(&workspace).expect("workspace")));
+        assert!(roots.contains(&dunce::canonicalize(&active_root).expect("active root")));
+        assert!(!roots.contains(&dunce::canonicalize(&codex_home).expect("codex home")));
+        assert!(!roots.contains(&dunce::canonicalize(&sandbox_root).expect("sandbox root")));
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/ssh_config_dependencies.rs b/codex-rs/windows-sandbox-rs/src/ssh_config_dependencies.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ae6d82d560190e99d84b2f147df7e2f40a656e4b
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/ssh_config_dependencies.rs
@@ -0,0 +1,249 @@
+use std::collections::HashSet;
+use std::path::Path;
+use std::path::PathBuf;
+
+const SSH_PROFILE_PATH_DIRECTIVES: &[&str] = &[
+    "certificatefile",
+    "controlpath",
+    "globalknownhostsfile",
+    "identityagent",
+    "identityfile",
+    "revokedhostkeys",
+    "userknownhostsfile",
+];
+
+pub(crate) fn ssh_config_dependency_paths(user_profile: &Path) -> Vec<PathBuf> {
+    let ssh_dir = user_profile.join(".ssh");
+    let mut paths = vec![ssh_dir.join("config")];
+    visit_config(
+        &ssh_dir.join("config"),
+        user_profile,
+        &ssh_dir,
+        &mut HashSet::new(),
+        &mut paths,
+        /*depth*/ 0,
+    );
+    paths
+}
+
+fn visit_config(
+    path: &Path,
+    user_profile: &Path,
+    ssh_dir: &Path,
+    visited: &mut HashSet<PathBuf>,
+    paths: &mut Vec<PathBuf>,
+    depth: usize,
+) {
+    if depth == 32 {
+        return;
+    }
+    let key = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
+    if !visited.insert(key) {
+        return;
+    }
+
+    let Ok(contents) = std::fs::read_to_string(path) else {
+        return;
+    };
+    for (key, args) in contents.lines().filter_map(directive) {
+        match key.to_ascii_lowercase().as_str() {
+            "include" => {
+                for arg in args {
+                    for include in include_paths(&arg, user_profile, ssh_dir) {
+                        paths.push(include.clone());
+                        visit_config(&include, user_profile, ssh_dir, visited, paths, depth + 1);
+                    }
+                }
+            }
+            key if SSH_PROFILE_PATH_DIRECTIVES.contains(&key) => {
+                for arg in args {
+                    if let Some(path) =
+                        profile_path_arg(&arg, user_profile, /*relative_base*/ None)
+                    {
+                        paths.push(path);
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+fn include_paths(arg: &str, user_profile: &Path, ssh_dir: &Path) -> Vec<PathBuf> {
+    let Some(pattern_path) = profile_path_arg(arg, user_profile, Some(ssh_dir)) else {
+        return Vec::new();
+    };
+    let pattern = pattern_path.to_string_lossy().replace('\\', "/");
+    let Ok(paths) = glob::glob(&pattern) else {
+        return Vec::new();
+    };
+    paths.filter_map(Result::ok).collect()
+}
+
+fn directive(line: &str) -> Option<(String, Vec<String>)> {
+    let mut words = words(line);
+    let first = words.first()?.to_string();
+    if let Some((key, value)) = first.split_once('=')
+        && !key.is_empty()
+    {
+        let mut args = Vec::new();
+        if !value.is_empty() {
+            args.push(value.to_string());
+        }
+        args.extend(words.drain(1..));
+        Some((key.to_string(), args))
+    } else {
+        let key = words.remove(0);
+        if let Some(arg) = words.first_mut()
+            && let Some(value) = arg.strip_prefix('=')
+        {
+            *arg = value.to_string();
+        }
+        words.retain(|arg| !arg.is_empty());
+        Some((key, words))
+    }
+}
+
+fn words(line: &str) -> Vec<String> {
+    let mut out = Vec::new();
+    let mut word = String::new();
+    let mut quote = None;
+    let mut chars = line.chars().peekable();
+
+    while let Some(ch) = chars.next() {
+        match ch {
+            '#' if quote.is_none() => break,
+            '\'' | '"' if quote == Some(ch) => quote = None,
+            '\'' | '"' if quote.is_none() => quote = Some(ch),
+            '\\' => {
+                if let Some(&next) = chars.peek() {
+                    if matches!(next, '\'' | '"' | '\\') || (quote.is_none() && next == ' ') {
+                        if let Some(escaped) = chars.next() {
+                            word.push(escaped);
+                        }
+                    } else {
+                        word.push(ch);
+                    }
+                } else {
+                    word.push(ch);
+                }
+            }
+            ch if ch.is_whitespace() && quote.is_none() => {
+                if !word.is_empty() {
+                    out.push(std::mem::take(&mut word));
+                }
+            }
+            ch => word.push(ch),
+        }
+    }
+    if !word.is_empty() {
+        out.push(word);
+    }
+    out
+}
+
+fn profile_path_arg(
+    arg: &str,
+    user_profile: &Path,
+    relative_base: Option<&Path>,
+) -> Option<PathBuf> {
+    if arg.eq_ignore_ascii_case("none") {
+        return None;
+    }
+    if arg == "~" || arg == "%d" || arg == "${HOME}" {
+        return Some(user_profile.to_path_buf());
+    }
+    if let Some(rest) = arg
+        .strip_prefix("~/")
+        .or_else(|| arg.strip_prefix(r"~\"))
+        .or_else(|| arg.strip_prefix("%d/"))
+        .or_else(|| arg.strip_prefix(r"%d\"))
+        .or_else(|| arg.strip_prefix("${HOME}/"))
+        .or_else(|| arg.strip_prefix(r"${HOME}\"))
+    {
+        return Some(user_profile.join(rest));
+    }
+
+    let path = PathBuf::from(arg);
+    if path.is_absolute() {
+        Some(path)
+    } else {
+        relative_base.map(|base| base.join(path))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ssh_config_dependency_paths;
+    use pretty_assertions::assert_eq;
+    use std::fs;
+    use std::path::PathBuf;
+    use tempfile::TempDir;
+
+    #[test]
+    fn collects_path_directive_profile_entries() {
+        let tmp = TempDir::new().expect("tempdir");
+        let home = tmp.path();
+        fs::create_dir_all(home.join(".ssh")).expect("create .ssh");
+        fs::write(
+            home.join(".ssh/config"),
+            r#"
+Host devbox
+  IdentityFile ~/.keys/id_ed25519
+  IdentityFile '~/.keys/quoted key'
+  CertificateFile = %d/.certs/devbox-cert.pub
+  UserKnownHostsFile ${HOME}/.known_hosts_custom
+  GlobalKnownHostsFile ~/.global_known_hosts
+  ControlPath ~/.control/%h-%p-%r
+  IdentityAgent=%d/.agent/socket
+  RevokedHostKeys ~/.revoked/keys
+"#,
+        )
+        .expect("write config");
+
+        assert_eq!(
+            vec![
+                home.join(".ssh/config"),
+                home.join(".keys/id_ed25519"),
+                home.join(".keys/quoted key"),
+                home.join(".certs/devbox-cert.pub"),
+                home.join(".known_hosts_custom"),
+                home.join(".global_known_hosts"),
+                home.join(".control/%h-%p-%r"),
+                home.join(".agent/socket"),
+                home.join(".revoked/keys"),
+            ],
+            slash_paths(ssh_config_dependency_paths(home))
+        );
+    }
+
+    #[test]
+    fn recursively_collects_include_dependencies() {
+        let tmp = TempDir::new().expect("tempdir");
+        let home = tmp.path();
+        let ssh_dir = home.join(".ssh");
+        fs::create_dir_all(ssh_dir.join("conf.d")).expect("create conf.d");
+        fs::write(ssh_dir.join("config"), "Include conf.d/*.conf\n").expect("write config");
+        fs::write(
+            ssh_dir.join("conf.d/devbox.conf"),
+            "CertificateFile ~/.included/devbox-cert.pub\n",
+        )
+        .expect("write include");
+
+        assert_eq!(
+            vec![
+                home.join(".ssh/config"),
+                ssh_dir.join("conf.d/devbox.conf"),
+                home.join(".included/devbox-cert.pub"),
+            ],
+            slash_paths(ssh_config_dependency_paths(home))
+        );
+    }
+
+    fn slash_paths(paths: Vec<PathBuf>) -> Vec<PathBuf> {
+        paths
+            .into_iter()
+            .map(|path| PathBuf::from(path.to_string_lossy().replace('\\', "/")))
+            .collect()
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/stdio_bridge.rs b/codex-rs/windows-sandbox-rs/src/stdio_bridge.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3ad722ba8db4eae79918aa79f14e102ea8cdb634
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/stdio_bridge.rs
@@ -0,0 +1,126 @@
+use std::io::Read;
+use std::io::Write;
+use std::sync::Arc;
+use std::time::Duration;
+
+use codex_utils_pty::SpawnedProcess;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+
+/// Forwards this process' stdio to a Windows sandbox session and returns the
+/// session exit code.
+pub async fn forward_sandbox_session_stdio(spawned: SpawnedProcess) -> i32 {
+    let session = Arc::new(spawned.session);
+    let tokio_runtime = tokio::runtime::Handle::current();
+    // Give large or slow tail output a better chance to finish draining without
+    // letting rare EOF issues hang the wrapper indefinitely.
+    let output_drain_timeout = Duration::from_secs(5);
+    // A helper thread watches our stdin. When the input source closes it, the
+    // thread tells the main async code so we can also close stdin for the
+    // sandboxed child process.
+    let (stdin_eof_tx, stdin_eof_rx) = oneshot::channel();
+
+    // Start background threads that copy stdin/stdout/stderr. We intentionally
+    // do not keep their JoinHandles; dropping the handle does not stop the
+    // thread, it just means we are not going to wait on it later.
+    drop(spawn_input_forwarder(
+        std::io::stdin(),
+        session.writer_sender(),
+        stdin_eof_tx,
+    ));
+    let (stdout_forwarder, stdout_forwarder_done_rx) =
+        spawn_output_forwarder(tokio_runtime.clone(), spawned.stdout_rx, std::io::stdout());
+    drop(stdout_forwarder);
+    let (stderr_forwarder, stderr_forwarder_done_rx) =
+        spawn_output_forwarder(tokio_runtime.clone(), spawned.stderr_rx, std::io::stderr());
+    drop(stderr_forwarder);
+
+    let stdin_close_task = tokio::spawn({
+        let session = Arc::clone(&session);
+        async move {
+            let _ = stdin_eof_rx.await;
+            session.close_stdin();
+        }
+    });
+
+    let mut exit_rx = spawned.exit_rx;
+    let exit_code = tokio::select! {
+        res = &mut exit_rx => res.unwrap_or(-1),
+        res = tokio::signal::ctrl_c() => {
+            if let Ok(()) = res {
+                session.request_terminate();
+            }
+            exit_rx.await.unwrap_or(-1)
+        }
+    };
+
+    stdin_close_task.abort();
+    let _ = tokio::time::timeout(output_drain_timeout, async {
+        let _ = stdout_forwarder_done_rx.await;
+        let _ = stderr_forwarder_done_rx.await;
+    })
+    .await;
+    exit_code
+}
+
+fn spawn_input_forwarder<R>(
+    mut input: R,
+    writer_tx: mpsc::Sender<Vec<u8>>,
+    stdin_eof_tx: oneshot::Sender<()>,
+) -> std::thread::JoinHandle<()>
+where
+    R: Read + Send + 'static,
+{
+    const STDIN_FORWARD_CHUNK_SIZE: usize = 8 * 1024;
+    std::thread::spawn(move || {
+        let mut buffer = [0_u8; STDIN_FORWARD_CHUNK_SIZE];
+        loop {
+            match input.read(&mut buffer) {
+                Ok(0) => break,
+                Ok(n) => {
+                    if writer_tx.blocking_send(buffer[..n].to_vec()).is_err() {
+                        break;
+                    }
+                }
+                Err(err) if err.kind() == std::io::ErrorKind::Interrupted => continue,
+                Err(err) => {
+                    eprintln!("windows sandbox stdin forwarder failed: {err}");
+                    break;
+                }
+            }
+        }
+        let _ = stdin_eof_tx.send(());
+    })
+}
+
+fn spawn_output_forwarder<W>(
+    tokio_runtime: tokio::runtime::Handle,
+    output_rx: mpsc::Receiver<Vec<u8>>,
+    mut writer: W,
+) -> (std::thread::JoinHandle<()>, oneshot::Receiver<()>)
+where
+    W: Write + Send + 'static,
+{
+    let (done_tx, done_rx) = oneshot::channel();
+    // The sandbox session emits output on Tokio channels, but writing to the
+    // caller's stdio is simplest from a dedicated blocking thread.
+    let handle = std::thread::spawn(move || {
+        let mut output_rx = output_rx;
+        while let Some(chunk) = tokio_runtime.block_on(output_rx.recv()) {
+            if let Err(err) = writer.write_all(&chunk) {
+                eprintln!("windows sandbox output forwarder failed to write: {err}");
+                break;
+            }
+            if let Err(err) = writer.flush() {
+                eprintln!("windows sandbox output forwarder failed to flush: {err}");
+                break;
+            }
+        }
+        let _ = done_tx.send(());
+    });
+    (handle, done_rx)
+}
+
+#[cfg(test)]
+#[path = "stdio_bridge_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/stdio_bridge_tests.rs b/codex-rs/windows-sandbox-rs/src/stdio_bridge_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c13632b84a1e25d906dd46e2570a9f6273774604
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/stdio_bridge_tests.rs
@@ -0,0 +1,63 @@
+use std::sync::Mutex;
+
+use pretty_assertions::assert_eq;
+
+use super::*;
+
+#[tokio::test]
+async fn input_forwarder_sends_chunks_and_reports_eof() -> anyhow::Result<()> {
+    let (writer_tx, mut writer_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(4);
+    let (stdin_closed_tx, stdin_closed_rx) = tokio::sync::oneshot::channel();
+    let input = std::io::Cursor::new(b"first\nsecond\n".to_vec());
+
+    let forwarder = spawn_input_forwarder(input, writer_tx, stdin_closed_tx);
+    let mut received = Vec::new();
+    while let Some(chunk) = writer_rx.recv().await {
+        received.extend_from_slice(&chunk);
+    }
+    stdin_closed_rx.await?;
+    forwarder.join().expect("stdin forwarder should finish");
+
+    assert_eq!(received, b"first\nsecond\n".to_vec());
+    Ok(())
+}
+
+#[tokio::test]
+async fn output_forwarder_writes_all_chunks() -> anyhow::Result<()> {
+    #[derive(Clone, Default)]
+    struct SharedWriter(std::sync::Arc<Mutex<Vec<u8>>>);
+
+    impl std::io::Write for SharedWriter {
+        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+            let mut guard = self
+                .0
+                .lock()
+                .map_err(|_| std::io::Error::other("writer poisoned"))?;
+            guard.extend_from_slice(buf);
+            Ok(buf.len())
+        }
+
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+
+    let runtime = tokio::runtime::Handle::current();
+    let (output_tx, output_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(4);
+    let writer = SharedWriter::default();
+    let sink = std::sync::Arc::clone(&writer.0);
+
+    let (forwarder, done_rx) = spawn_output_forwarder(runtime, output_rx, writer);
+    output_tx.send(b"alpha".to_vec()).await?;
+    output_tx.send(b"beta".to_vec()).await?;
+    drop(output_tx);
+    forwarder.join().expect("output forwarder should finish");
+    done_rx.await?;
+
+    let output = sink
+        .lock()
+        .map_err(|_| anyhow::anyhow!("writer poisoned"))?
+        .clone();
+    assert_eq!(output, b"alphabeta".to_vec());
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/token.rs b/codex-rs/windows-sandbox-rs/src/token.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2fa88012bf016c1c527c2b0621434102e98b59d6
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/token.rs
@@ -0,0 +1,529 @@
+use crate::winutil::to_wide;
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::ensure;
+use std::ffi::c_void;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LUID;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Security::AdjustTokenPrivileges;
+use windows_sys::Win32::Security::Authorization::EXPLICIT_ACCESS_W;
+use windows_sys::Win32::Security::Authorization::GRANT_ACCESS;
+use windows_sys::Win32::Security::Authorization::SetEntriesInAclW;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_SID;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_IS_UNKNOWN;
+use windows_sys::Win32::Security::Authorization::TRUSTEE_W;
+use windows_sys::Win32::Security::CopySid;
+use windows_sys::Win32::Security::CreateRestrictedToken;
+use windows_sys::Win32::Security::CreateWellKnownSid;
+use windows_sys::Win32::Security::GetTokenInformation;
+use windows_sys::Win32::Security::IsValidSid;
+use windows_sys::Win32::Security::LookupPrivilegeValueW;
+use windows_sys::Win32::Security::SetTokenInformation;
+
+use windows_sys::Win32::Security::ACL;
+use windows_sys::Win32::Security::SID_AND_ATTRIBUTES;
+use windows_sys::Win32::Security::TOKEN_ADJUST_DEFAULT;
+use windows_sys::Win32::Security::TOKEN_ADJUST_PRIVILEGES;
+use windows_sys::Win32::Security::TOKEN_ADJUST_SESSIONID;
+use windows_sys::Win32::Security::TOKEN_ASSIGN_PRIMARY;
+use windows_sys::Win32::Security::TOKEN_DUPLICATE;
+use windows_sys::Win32::Security::TOKEN_GROUPS;
+use windows_sys::Win32::Security::TOKEN_PRIVILEGES;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::Security::TokenDefaultDacl;
+use windows_sys::Win32::Security::TokenGroups;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+
+const DISABLE_MAX_PRIVILEGE: u32 = 0x01;
+const LUA_TOKEN: u32 = 0x04;
+const WRITE_RESTRICTED: u32 = 0x08;
+const GENERIC_ALL: u32 = 0x1000_0000;
+const WIN_WORLD_SID: i32 = 1;
+const SE_GROUP_LOGON_ID: u32 = 0xC0000000;
+
+#[repr(C)]
+struct TokenDefaultDaclInfo {
+    default_dacl: *mut ACL,
+}
+
+/// Sets a permissive default DACL so sandboxed processes can create pipes/IPC objects
+/// without hitting ACCESS_DENIED when PowerShell builds pipelines.
+unsafe fn set_default_dacl(h_token: HANDLE, sids: &[*mut c_void]) -> Result<()> {
+    if sids.is_empty() {
+        return Ok(());
+    }
+    let entries: Vec<EXPLICIT_ACCESS_W> = sids
+        .iter()
+        .map(|sid| EXPLICIT_ACCESS_W {
+            grfAccessPermissions: GENERIC_ALL,
+            grfAccessMode: GRANT_ACCESS,
+            grfInheritance: 0,
+            Trustee: TRUSTEE_W {
+                pMultipleTrustee: std::ptr::null_mut(),
+                MultipleTrusteeOperation: 0,
+                TrusteeForm: TRUSTEE_IS_SID,
+                TrusteeType: TRUSTEE_IS_UNKNOWN,
+                ptstrName: *sid as *mut u16,
+            },
+        })
+        .collect();
+    let mut p_new_dacl: *mut ACL = std::ptr::null_mut();
+    let res = SetEntriesInAclW(
+        entries.len() as u32,
+        entries.as_ptr(),
+        std::ptr::null_mut(),
+        &mut p_new_dacl,
+    );
+    if res != ERROR_SUCCESS {
+        return Err(anyhow!("SetEntriesInAclW failed: {res}"));
+    }
+    let mut info = TokenDefaultDaclInfo {
+        default_dacl: p_new_dacl,
+    };
+    let ok = SetTokenInformation(
+        h_token,
+        TokenDefaultDacl,
+        &mut info as *mut _ as *mut c_void,
+        std::mem::size_of::<TokenDefaultDaclInfo>() as u32,
+    );
+    if ok == 0 {
+        let err = GetLastError();
+        if !p_new_dacl.is_null() {
+            LocalFree(p_new_dacl as HLOCAL);
+        }
+        return Err(anyhow!(
+            "SetTokenInformation(TokenDefaultDacl) failed: {err}",
+        ));
+    }
+    if !p_new_dacl.is_null() {
+        LocalFree(p_new_dacl as HLOCAL);
+    }
+    Ok(())
+}
+
+pub unsafe fn world_sid() -> Result<Vec<u8>> {
+    let mut size: u32 = 0;
+    CreateWellKnownSid(
+        WIN_WORLD_SID,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+        &mut size,
+    );
+    let mut buf: Vec<u8> = vec![0u8; size as usize];
+    let ok = CreateWellKnownSid(
+        WIN_WORLD_SID,
+        std::ptr::null_mut(),
+        buf.as_mut_ptr() as *mut c_void,
+        &mut size,
+    );
+    if ok == 0 {
+        return Err(anyhow!("CreateWellKnownSid failed: {}", GetLastError()));
+    }
+    Ok(buf)
+}
+
+/// # Safety
+/// Caller is responsible for freeing the returned SID with `LocalFree`.
+pub unsafe fn convert_string_sid_to_sid(s: &str) -> Option<*mut c_void> {
+    #[link(name = "advapi32")]
+    unsafe extern "system" {
+        fn ConvertStringSidToSidW(StringSid: *const u16, Sid: *mut *mut c_void) -> i32;
+    }
+    let mut psid: *mut c_void = std::ptr::null_mut();
+    let ok = unsafe { ConvertStringSidToSidW(to_wide(s).as_ptr(), &mut psid) };
+    if ok != 0 { Some(psid) } else { None }
+}
+
+/// Owns a SID allocated by `ConvertStringSidToSidW` and releases it with `LocalFree`.
+pub struct LocalSid {
+    psid: *mut c_void,
+}
+
+impl LocalSid {
+    pub fn from_string(sid: &str) -> Result<Self> {
+        let psid = unsafe { convert_string_sid_to_sid(sid) }
+            .ok_or_else(|| anyhow!("invalid SID string: {sid}"))?;
+        Ok(Self { psid })
+    }
+
+    pub fn as_ptr(&self) -> *mut c_void {
+        self.psid
+    }
+}
+
+impl Drop for LocalSid {
+    fn drop(&mut self) {
+        if !self.psid.is_null() {
+            unsafe {
+                LocalFree(self.psid as HLOCAL);
+            }
+        }
+    }
+}
+
+/// # Safety
+/// Caller must close the returned token handle.
+pub unsafe fn get_current_token_for_restriction() -> Result<HANDLE> {
+    let desired = TOKEN_DUPLICATE
+        | TOKEN_QUERY
+        | TOKEN_ASSIGN_PRIMARY
+        | TOKEN_ADJUST_DEFAULT
+        | TOKEN_ADJUST_SESSIONID
+        | TOKEN_ADJUST_PRIVILEGES;
+    let mut h: HANDLE = 0;
+    #[link(name = "advapi32")]
+    unsafe extern "system" {
+        fn OpenProcessToken(
+            ProcessHandle: HANDLE,
+            DesiredAccess: u32,
+            TokenHandle: *mut HANDLE,
+        ) -> i32;
+    }
+    let ok = unsafe { OpenProcessToken(GetCurrentProcess(), desired, &mut h) };
+    if ok == 0 {
+        return Err(anyhow!("OpenProcessToken failed: {}", GetLastError()));
+    }
+    Ok(h)
+}
+
+/// An owned token group, including attributes such as enabled and deny-only.
+#[derive(Debug, PartialEq, Eq)]
+pub struct TokenGroup {
+    pub sid: Vec<u8>,
+    pub attributes: u32,
+}
+
+/// Queries groups without filtering membership or retaining pointers into Windows' buffer.
+///
+/// # Safety
+/// `token` must remain a valid token handle with `TOKEN_QUERY` access during this call.
+pub unsafe fn token_groups(token: HANDLE, max_bytes: u32) -> Result<Vec<TokenGroup>> {
+    let mut needed = 0;
+    GetTokenInformation(token, TokenGroups, std::ptr::null_mut(), 0, &mut needed);
+    ensure!(
+        needed > 0 && needed <= max_bytes,
+        "invalid token group size"
+    );
+    let mut buffer = vec![0u8; needed as usize];
+    if GetTokenInformation(
+        token,
+        TokenGroups,
+        buffer.as_mut_ptr().cast(),
+        needed,
+        &mut needed,
+    ) == 0
+    {
+        return Err(anyhow!(
+            "GetTokenInformation(TokenGroups) failed: {}",
+            GetLastError()
+        ));
+    }
+    ensure!(
+        needed as usize <= buffer.len(),
+        "invalid token group result size"
+    );
+    decode_token_groups(&buffer[..needed as usize])
+}
+
+fn decode_token_groups(buffer: &[u8]) -> Result<Vec<TokenGroup>> {
+    let offset = std::mem::offset_of!(TOKEN_GROUPS, Groups);
+    let stride = std::mem::size_of::<SID_AND_ATTRIBUTES>();
+    ensure!(buffer.len() >= offset, "truncated token group header");
+    let count = unsafe { std::ptr::read_unaligned(buffer.as_ptr().cast::<u32>()) } as usize;
+    ensure!(
+        count <= (buffer.len() - offset) / stride,
+        "truncated token groups"
+    );
+    let mut groups = Vec::with_capacity(count);
+    for index in 0..count {
+        let entry = unsafe {
+            std::ptr::read_unaligned(
+                buffer
+                    .as_ptr()
+                    .add(offset + index * stride)
+                    .cast::<SID_AND_ATTRIBUTES>(),
+            )
+        };
+        // Bound the header and every subauthority before calling a SID API.
+        let sid_offset = (entry.Sid as usize).wrapping_sub(buffer.as_ptr() as usize);
+        ensure!(
+            sid_offset <= buffer.len().saturating_sub(8),
+            "invalid token group SID pointer"
+        );
+        ensure!(buffer[sid_offset] == 1, "invalid token group SID revision");
+        let sid_len = 8 + usize::from(buffer[sid_offset + 1]) * 4;
+        ensure!(
+            sid_len <= 68 && sid_len <= buffer.len() - sid_offset,
+            "invalid token group SID size"
+        );
+        ensure!(
+            unsafe { IsValidSid(entry.Sid) } != 0,
+            "invalid token group SID"
+        );
+        let mut sid = vec![0u8; sid_len];
+        ensure!(
+            unsafe { CopySid(sid_len as u32, sid.as_mut_ptr().cast(), entry.Sid) } != 0,
+            "invalid token group SID"
+        );
+        groups.push(TokenGroup {
+            sid,
+            attributes: entry.Attributes,
+        });
+    }
+    Ok(groups)
+}
+
+pub unsafe fn get_logon_sid_bytes(h_token: HANDLE) -> Result<Vec<u8>> {
+    unsafe fn scan_token_groups_for_logon(h: HANDLE) -> Option<Vec<u8>> {
+        token_groups(h, u32::MAX)
+            .ok()?
+            .into_iter()
+            .find(|group| group.attributes & SE_GROUP_LOGON_ID == SE_GROUP_LOGON_ID)
+            .map(|group| group.sid)
+    }
+
+    if let Some(v) = scan_token_groups_for_logon(h_token) {
+        return Ok(v);
+    }
+
+    #[repr(C)]
+    struct TOKEN_LINKED_TOKEN {
+        linked_token: HANDLE,
+    }
+    const TOKEN_LINKED_TOKEN_CLASS: i32 = 19; // TokenLinkedToken
+    let mut ln_needed: u32 = 0;
+    GetTokenInformation(
+        h_token,
+        TOKEN_LINKED_TOKEN_CLASS,
+        std::ptr::null_mut(),
+        0,
+        &mut ln_needed,
+    );
+    if ln_needed >= std::mem::size_of::<TOKEN_LINKED_TOKEN>() as u32 {
+        let mut ln_buf: Vec<u8> = vec![0u8; ln_needed as usize];
+        let ok = GetTokenInformation(
+            h_token,
+            TOKEN_LINKED_TOKEN_CLASS,
+            ln_buf.as_mut_ptr() as *mut c_void,
+            ln_needed,
+            &mut ln_needed,
+        );
+        if ok != 0 {
+            let lt: TOKEN_LINKED_TOKEN =
+                std::ptr::read_unaligned(ln_buf.as_ptr() as *const TOKEN_LINKED_TOKEN);
+            if lt.linked_token != 0 {
+                let res = scan_token_groups_for_logon(lt.linked_token);
+                CloseHandle(lt.linked_token);
+                if let Some(v) = res {
+                    return Ok(v);
+                }
+            }
+        }
+    }
+
+    Err(anyhow!("Logon SID not present on token"))
+}
+
+pub(crate) use crate::token_user::get_user_sid_bytes;
+
+unsafe fn enable_single_privilege(h_token: HANDLE, name: &str) -> Result<()> {
+    let mut luid = LUID {
+        LowPart: 0,
+        HighPart: 0,
+    };
+    let ok = LookupPrivilegeValueW(std::ptr::null(), to_wide(name).as_ptr(), &mut luid);
+    if ok == 0 {
+        return Err(anyhow!("LookupPrivilegeValueW failed: {}", GetLastError()));
+    }
+    let mut tp: TOKEN_PRIVILEGES = std::mem::zeroed();
+    tp.PrivilegeCount = 1;
+    tp.Privileges[0].Luid = luid;
+    tp.Privileges[0].Attributes = 0x00000002; // SE_PRIVILEGE_ENABLED
+    let ok2 = AdjustTokenPrivileges(
+        h_token,
+        0,
+        &tp,
+        0,
+        std::ptr::null_mut(),
+        std::ptr::null_mut(),
+    );
+    if ok2 == 0 {
+        return Err(anyhow!("AdjustTokenPrivileges failed: {}", GetLastError()));
+    }
+    let err = GetLastError();
+    if err != 0 {
+        return Err(anyhow!("AdjustTokenPrivileges error {err}"));
+    }
+    Ok(())
+}
+
+/// # Safety
+/// Caller must close the returned token handle.
+pub unsafe fn create_readonly_token_with_cap(
+    psid_capability: *mut c_void,
+) -> Result<(HANDLE, *mut c_void)> {
+    let base = get_current_token_for_restriction()?;
+    let res = create_readonly_token_with_cap_from(base, psid_capability);
+    CloseHandle(base);
+    res
+}
+
+/// # Safety
+/// Caller must close the returned token handle; base_token must be a valid primary token.
+/// # Safety
+/// Caller must close the returned token handle; base_token must be a valid primary token.
+pub unsafe fn create_readonly_token_with_cap_from(
+    base_token: HANDLE,
+    psid_capability: *mut c_void,
+) -> Result<(HANDLE, *mut c_void)> {
+    let new_token = create_token_with_caps_from(base_token, &[psid_capability], &[])?;
+    Ok((new_token, psid_capability))
+}
+
+/// Create a restricted token that includes all provided capability SIDs.
+///
+/// # Safety
+/// Caller must close the returned token handle; base_token must be a valid primary token.
+pub unsafe fn create_workspace_write_token_with_caps_from(
+    base_token: HANDLE,
+    psid_capabilities: &[*mut c_void],
+) -> Result<HANDLE> {
+    create_token_with_caps_from(base_token, psid_capabilities, &[])
+}
+
+/// Create a restricted token that includes all provided capability SIDs, the token user SID, and
+/// any additional restricting SIDs.
+///
+/// This is intended for the elevated sandbox backend, where the token user is the dedicated
+/// sandbox account rather than the real signed-in user.
+///
+/// # Safety
+/// Caller must close the returned token handle; base_token must be a valid primary token.
+pub unsafe fn create_workspace_write_token_with_caps_and_user_from(
+    base_token: HANDLE,
+    psid_capabilities: &[*mut c_void],
+    additional_restricting_sids: &[*mut c_void],
+) -> Result<HANDLE> {
+    create_token_with_caps_user_and_additional_restrictions_from(
+        base_token,
+        psid_capabilities,
+        additional_restricting_sids,
+    )
+}
+
+/// Create a restricted token that includes all provided capability SIDs.
+///
+/// # Safety
+/// Caller must close the returned token handle; base_token must be a valid primary token.
+pub unsafe fn create_readonly_token_with_caps_from(
+    base_token: HANDLE,
+    psid_capabilities: &[*mut c_void],
+) -> Result<HANDLE> {
+    create_token_with_caps_from(base_token, psid_capabilities, &[])
+}
+
+/// Create a restricted token that includes all provided capability SIDs, the token user SID, and
+/// any additional restricting SIDs.
+///
+/// This is intended for the elevated sandbox backend, where the token user is the dedicated
+/// sandbox account rather than the real signed-in user.
+///
+/// # Safety
+/// Caller must close the returned token handle; base_token must be a valid primary token.
+pub unsafe fn create_readonly_token_with_caps_and_user_from(
+    base_token: HANDLE,
+    psid_capabilities: &[*mut c_void],
+    additional_restricting_sids: &[*mut c_void],
+) -> Result<HANDLE> {
+    create_token_with_caps_user_and_additional_restrictions_from(
+        base_token,
+        psid_capabilities,
+        additional_restricting_sids,
+    )
+}
+
+unsafe fn create_token_with_caps_user_and_additional_restrictions_from(
+    base_token: HANDLE,
+    psid_capabilities: &[*mut c_void],
+    additional_restricting_sids: &[*mut c_void],
+) -> Result<HANDLE> {
+    let mut user_sid_bytes = get_user_sid_bytes(base_token)?;
+    let psid_user = user_sid_bytes.as_mut_ptr() as *mut c_void;
+    let mut extra_restricting_sids = Vec::with_capacity(additional_restricting_sids.len() + 1);
+    extra_restricting_sids.push(psid_user);
+    extra_restricting_sids.extend_from_slice(additional_restricting_sids);
+    create_token_with_caps_from(base_token, psid_capabilities, &extra_restricting_sids)
+}
+
+unsafe fn create_token_with_caps_from(
+    base_token: HANDLE,
+    psid_capabilities: &[*mut c_void],
+    extra_restricting_sids: &[*mut c_void],
+) -> Result<HANDLE> {
+    if psid_capabilities.is_empty() {
+        return Err(anyhow!("no capability SIDs provided"));
+    }
+    let mut logon_sid_bytes = get_logon_sid_bytes(base_token)?;
+    let psid_logon = logon_sid_bytes.as_mut_ptr() as *mut c_void;
+    let mut everyone = world_sid()?;
+    let psid_everyone = everyone.as_mut_ptr() as *mut c_void;
+
+    // Exact order: Capabilities..., ExtraRestricting..., Logon, Everyone
+    let mut entries: Vec<SID_AND_ATTRIBUTES> =
+        vec![std::mem::zeroed(); psid_capabilities.len() + extra_restricting_sids.len() + 2];
+    for (i, psid) in psid_capabilities.iter().enumerate() {
+        entries[i].Sid = *psid;
+        entries[i].Attributes = 0;
+    }
+    let extras_idx = psid_capabilities.len();
+    for (i, psid) in extra_restricting_sids.iter().enumerate() {
+        entries[extras_idx + i].Sid = *psid;
+        entries[extras_idx + i].Attributes = 0;
+    }
+    let logon_idx = extras_idx + extra_restricting_sids.len();
+    entries[logon_idx].Sid = psid_logon;
+    entries[logon_idx].Attributes = 0;
+    entries[logon_idx + 1].Sid = psid_everyone;
+    entries[logon_idx + 1].Attributes = 0;
+
+    let mut new_token: HANDLE = 0;
+    let flags = DISABLE_MAX_PRIVILEGE | LUA_TOKEN | WRITE_RESTRICTED;
+    let ok = CreateRestrictedToken(
+        base_token,
+        flags,
+        0,
+        std::ptr::null(),
+        0,
+        std::ptr::null(),
+        entries.len() as u32,
+        entries.as_mut_ptr(),
+        &mut new_token,
+    );
+    if ok == 0 {
+        return Err(anyhow!("CreateRestrictedToken failed: {}", GetLastError()));
+    }
+
+    // Additional restricting SIDs are identity markers, not capabilities. Deliberately exclude
+    // them from the default DACL so possessing a route identity cannot grant object access.
+    let mut dacl_sids: Vec<*mut c_void> = Vec::with_capacity(psid_capabilities.len() + 2);
+    dacl_sids.push(psid_logon);
+    dacl_sids.push(psid_everyone);
+    dacl_sids.extend_from_slice(psid_capabilities);
+    set_default_dacl(new_token, &dacl_sids)?;
+
+    enable_single_privilege(new_token, "SeChangeNotifyPrivilege")?;
+    Ok(new_token)
+}
+
+#[cfg(test)]
+#[path = "token_tests.rs"]
+mod tests;
+
+#[cfg(test)]
+#[path = "token_groups_tests.rs"]
+mod token_groups_tests;
diff --git a/codex-rs/windows-sandbox-rs/src/token_groups_tests.rs b/codex-rs/windows-sandbox-rs/src/token_groups_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7a002c0eb9cd5afe16d609cc2966e1c66ca42c9f
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/token_groups_tests.rs
@@ -0,0 +1,118 @@
+//! Exercises owned group decoding and bounded queries without changing token privileges.
+
+use super::*;
+use pretty_assertions::assert_eq;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+
+fn group_buffer(groups: &[TokenGroup]) -> Vec<u8> {
+    let offset = std::mem::offset_of!(TOKEN_GROUPS, Groups);
+    let stride = std::mem::size_of::<SID_AND_ATTRIBUTES>();
+    let mut sid_offset = offset + groups.len() * stride;
+    let mut buffer =
+        vec![0u8; sid_offset + groups.iter().map(|group| group.sid.len()).sum::<usize>()];
+    unsafe { std::ptr::write_unaligned(buffer.as_mut_ptr().cast::<u32>(), groups.len() as u32) };
+    for (index, group) in groups.iter().enumerate() {
+        buffer[sid_offset..sid_offset + group.sid.len()].copy_from_slice(&group.sid);
+        let entry = SID_AND_ATTRIBUTES {
+            Sid: unsafe { buffer.as_mut_ptr().add(sid_offset).cast() },
+            Attributes: group.attributes,
+        };
+        unsafe {
+            std::ptr::write_unaligned(
+                buffer
+                    .as_mut_ptr()
+                    .add(offset + index * stride)
+                    .cast::<SID_AND_ATTRIBUTES>(),
+                entry,
+            )
+        };
+        sid_offset += group.sid.len();
+    }
+    buffer
+}
+
+#[test]
+fn owns_sids_and_preserves_duplicate_order_and_attributes() -> Result<()> {
+    let expected = [0x4, 0x10, SE_GROUP_LOGON_ID]
+        .into_iter()
+        .map(|attributes| TokenGroup {
+            sid: unsafe { world_sid().expect("world SID") },
+            attributes,
+        })
+        .collect::<Vec<_>>();
+    let actual = {
+        let buffer = group_buffer(&expected);
+        decode_token_groups(&buffer)?
+    };
+    assert_eq!(actual, expected);
+    Ok(())
+}
+
+#[test]
+fn rejects_truncated_group_layout() {
+    assert!(decode_token_groups(&[]).is_err());
+    let mut buffer = group_buffer(&[]);
+    assert_eq!(
+        decode_token_groups(&buffer).unwrap(),
+        Vec::<TokenGroup>::new()
+    );
+    unsafe { std::ptr::write_unaligned(buffer.as_mut_ptr().cast::<u32>(), u32::MAX) };
+    assert!(decode_token_groups(&buffer).is_err());
+}
+
+#[test]
+fn rejects_malformed_and_out_of_buffer_sids() {
+    let group = TokenGroup {
+        sid: unsafe { world_sid().expect("world SID") },
+        attributes: 4,
+    };
+    let mut buffer = group_buffer(&[group]);
+    let offset = std::mem::offset_of!(TOKEN_GROUPS, Groups);
+    let entry = unsafe {
+        std::ptr::read_unaligned(buffer.as_ptr().add(offset).cast::<SID_AND_ATTRIBUTES>())
+    };
+    let sid_offset = (entry.Sid as usize) - (buffer.as_ptr() as usize);
+    buffer[sid_offset] = 2;
+    assert!(decode_token_groups(&buffer).is_err());
+    buffer[sid_offset] = 1;
+    buffer[sid_offset + 1] = 15;
+    assert!(decode_token_groups(&buffer).is_err());
+    for sid in [std::ptr::null_mut(), unsafe {
+        buffer.as_mut_ptr().add(buffer.len() - 1).cast()
+    }] {
+        unsafe {
+            std::ptr::write_unaligned(
+                buffer.as_mut_ptr().add(offset).cast::<SID_AND_ATTRIBUTES>(),
+                SID_AND_ATTRIBUTES {
+                    Sid: sid,
+                    Attributes: 4,
+                },
+            )
+        };
+        assert!(decode_token_groups(&buffer).is_err());
+    }
+}
+
+#[test]
+fn queries_current_token_with_a_caller_size_limit() -> Result<()> {
+    let mut raw = 0;
+    ensure!(unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut raw) } != 0);
+    let _token = unsafe { OwnedHandle::from_raw_handle(raw as _) };
+    assert!(
+        unsafe {
+            token_groups(raw, /*max_bytes*/ 0)
+        }
+        .is_err()
+    );
+    let groups = unsafe { token_groups(raw, u32::MAX) }?;
+    assert!(!groups.is_empty());
+    if let Some(logon) = groups
+        .iter()
+        .find(|group| group.attributes & SE_GROUP_LOGON_ID == SE_GROUP_LOGON_ID)
+    {
+        assert_eq!(unsafe { get_logon_sid_bytes(raw) }?, logon.sid);
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/token_tests.rs b/codex-rs/windows-sandbox-rs/src/token_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..63178355b140201332c13f31d99521592dda6dfb
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/token_tests.rs
@@ -0,0 +1,69 @@
+use super::*;
+use windows_sys::Win32::Security::EqualSid;
+use windows_sys::Win32::Security::TokenRestrictedSids;
+
+unsafe fn token_has_restricting_sid(token: HANDLE, expected_sid: *mut c_void) -> Result<bool> {
+    let mut needed = 0;
+    GetTokenInformation(
+        token,
+        TokenRestrictedSids,
+        std::ptr::null_mut(),
+        0,
+        &mut needed,
+    );
+    if needed == 0 {
+        return Err(anyhow!(
+            "GetTokenInformation(TokenRestrictedSids) size query failed: {}",
+            GetLastError()
+        ));
+    }
+
+    let mut buffer = vec![0_u8; needed as usize];
+    if GetTokenInformation(
+        token,
+        TokenRestrictedSids,
+        buffer.as_mut_ptr().cast(),
+        needed,
+        &mut needed,
+    ) == 0
+    {
+        return Err(anyhow!(
+            "GetTokenInformation(TokenRestrictedSids) failed: {}",
+            GetLastError()
+        ));
+    }
+
+    let group_count = std::ptr::read_unaligned(buffer.as_ptr().cast::<u32>()) as usize;
+    let after_count = buffer.as_ptr().add(std::mem::size_of::<u32>()) as usize;
+    let align = std::mem::align_of::<SID_AND_ATTRIBUTES>();
+    let entries_addr = (after_count + (align - 1)) & !(align - 1);
+    let restricting_sids =
+        std::slice::from_raw_parts(entries_addr as *const SID_AND_ATTRIBUTES, group_count);
+    Ok(restricting_sids
+        .iter()
+        .any(|entry| EqualSid(entry.Sid, expected_sid) != 0))
+}
+
+#[test]
+fn elevated_token_includes_network_proxy_restricting_sid() -> Result<()> {
+    let capability_sid = LocalSid::from_string("S-1-5-21-10-20-30-40")?;
+    let network_proxy_sid = LocalSid::from_string("S-1-5-21-50-60-70-80")?;
+    let base_token = unsafe { get_current_token_for_restriction()? };
+    let restricted_token = unsafe {
+        create_readonly_token_with_caps_and_user_from(
+            base_token,
+            &[capability_sid.as_ptr()],
+            &[network_proxy_sid.as_ptr()],
+        )?
+    };
+
+    let has_network_proxy_sid =
+        unsafe { token_has_restricting_sid(restricted_token, network_proxy_sid.as_ptr()) };
+    unsafe {
+        CloseHandle(restricted_token);
+        CloseHandle(base_token);
+    }
+
+    assert!(has_network_proxy_sid?);
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/token_user.rs b/codex-rs/windows-sandbox-rs/src/token_user.rs
new file mode 100644
index 0000000000000000000000000000000000000000..3c8689ddf839d1a76e567ac0104fed56a23ff51d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/token_user.rs
@@ -0,0 +1,74 @@
+//! Copies token user identities with bounded Windows queries and owned SID storage.
+
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::ensure;
+use std::ffi::c_void;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security::GetTokenInformation;
+use windows_sys::Win32::Security::IsValidSid;
+use windows_sys::Win32::Security::TOKEN_USER;
+use windows_sys::Win32::Security::TokenUser;
+
+/// Copies a token's user SID into owned storage after a bounded TokenUser query.
+///
+/// # Safety
+/// The caller must keep a token handle with TOKEN_QUERY access valid during this call.
+pub unsafe fn get_user_sid_bytes(h_token: HANDLE) -> Result<Vec<u8>> {
+    let mut needed: u32 = 0;
+    GetTokenInformation(h_token, TokenUser, std::ptr::null_mut(), 0, &mut needed);
+    ensure!(
+        needed as usize >= std::mem::size_of::<TOKEN_USER>() && needed <= 4096,
+        "invalid TokenUser query size"
+    );
+    let mut user_buf: Vec<u8> = vec![0u8; needed as usize];
+    let ok = GetTokenInformation(
+        h_token,
+        TokenUser,
+        user_buf.as_mut_ptr() as *mut c_void,
+        needed,
+        &mut needed,
+    );
+    if ok == 0 {
+        return Err(anyhow!(
+            "GetTokenInformation(TokenUser) failed: {}",
+            GetLastError()
+        ));
+    }
+    ensure!(
+        needed as usize <= user_buf.len(),
+        "invalid TokenUser result size"
+    );
+    decode_token_user(&user_buf[..needed as usize])
+}
+
+fn decode_token_user(buffer: &[u8]) -> Result<Vec<u8>> {
+    ensure!(
+        buffer.len() >= std::mem::size_of::<TOKEN_USER>(),
+        "truncated TokenUser"
+    );
+    let user = unsafe { std::ptr::read_unaligned(buffer.as_ptr().cast::<TOKEN_USER>()) };
+    copy_token_sid(buffer, user.User.Sid)
+}
+
+fn copy_token_sid(buffer: &[u8], pointer: *mut c_void) -> Result<Vec<u8>> {
+    // Bound the header and every subauthority before calling a SID API.
+    let offset = (pointer as usize).wrapping_sub(buffer.as_ptr() as usize);
+    ensure!(
+        buffer.len() >= 8 && offset <= buffer.len() - 8,
+        "invalid token SID pointer"
+    );
+    ensure!(buffer[offset] == 1, "invalid token SID revision");
+    let length = 8 + usize::from(buffer[offset + 1]) * 4;
+    ensure!(
+        length <= 68 && length <= buffer.len() - offset,
+        "invalid token SID size"
+    );
+    ensure!(unsafe { IsValidSid(pointer) } != 0, "invalid token SID");
+    Ok(buffer[offset..offset + length].to_vec())
+}
+
+#[cfg(test)]
+#[path = "token_user_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/token_user_tests.rs b/codex-rs/windows-sandbox-rs/src/token_user_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..15a7c1e58a2f40ff77dfbf39e598ccf88fd4d386
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/token_user_tests.rs
@@ -0,0 +1,78 @@
+//! Verifies owned token-user SID results and rejects malformed query buffers.
+
+use super::*;
+use crate::token::world_sid;
+use pretty_assertions::assert_eq;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use windows_sys::Win32::Security::SID_AND_ATTRIBUTES;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+
+fn user_buffer(sid: &[u8]) -> Vec<u8> {
+    let offset = std::mem::size_of::<TOKEN_USER>();
+    let mut buffer = vec![0; offset + sid.len()];
+    buffer[offset..].copy_from_slice(sid);
+    unsafe {
+        let user = TOKEN_USER {
+            User: SID_AND_ATTRIBUTES {
+                Sid: buffer.as_mut_ptr().add(offset).cast(),
+                Attributes: 0,
+            },
+        };
+        std::ptr::write_unaligned(buffer.as_mut_ptr().cast::<TOKEN_USER>(), user);
+    }
+    buffer
+}
+
+#[test]
+fn user_sid_is_owned_after_the_query_buffer_is_dropped() -> Result<()> {
+    let expected = unsafe { world_sid() }?;
+    let actual = {
+        let buffer = user_buffer(&expected);
+        decode_token_user(&buffer)?
+    };
+    assert_eq!(actual, expected);
+    Ok(())
+}
+
+#[test]
+fn rejects_truncated_user_and_malformed_sid() -> Result<()> {
+    assert!(decode_token_user(&[]).is_err());
+    let mut buffer = user_buffer(&unsafe { world_sid() }?);
+    let offset = std::mem::size_of::<TOKEN_USER>();
+    buffer[offset] = 2;
+    assert!(decode_token_user(&buffer).is_err());
+    buffer[offset] = 1;
+    buffer[offset + 1] = 15;
+    assert!(decode_token_user(&buffer).is_err());
+    for pointer in [std::ptr::null_mut(), unsafe {
+        buffer.as_mut_ptr().add(buffer.len() - 1).cast()
+    }] {
+        unsafe {
+            std::ptr::write_unaligned(
+                buffer.as_mut_ptr().cast::<TOKEN_USER>(),
+                TOKEN_USER {
+                    User: SID_AND_ATTRIBUTES {
+                        Sid: pointer,
+                        Attributes: 0,
+                    },
+                },
+            );
+        }
+        assert!(decode_token_user(&buffer).is_err());
+    }
+    Ok(())
+}
+
+#[test]
+fn queries_current_user_and_rejects_invalid_token() -> Result<()> {
+    let mut raw = 0;
+    ensure!(unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut raw) } != 0);
+    let _token = unsafe { OwnedHandle::from_raw_handle(raw as _) };
+    let user = unsafe { get_user_sid_bytes(raw) }?;
+    assert!(unsafe { IsValidSid(user.as_ptr() as _) } != 0);
+    assert!(unsafe { get_user_sid_bytes(0) }.is_err());
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated.rs
new file mode 100644
index 0000000000000000000000000000000000000000..24a5494b7141033284b1ede2f3a96450f24a4fdc
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated.rs
@@ -0,0 +1,282 @@
+use super::windows_common::finish_driver_spawn;
+use super::windows_common::make_runner_resizer;
+use super::windows_common::start_runner_pipe_writer;
+use super::windows_common::start_runner_stdin_writer;
+use super::windows_common::start_runner_stdout_reader;
+use crate::desktop::DesktopPolicy;
+use crate::identity::SandboxCreds;
+use crate::identity::refresh_logon_sandbox_creds;
+use crate::ipc_framed::EmptyPayload;
+use crate::ipc_framed::FramedMessage;
+use crate::ipc_framed::IPC_PROTOCOL_VERSION;
+use crate::ipc_framed::Message;
+use crate::ipc_framed::SpawnRequest;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::runner_client::RunnerTransport;
+use crate::runner_client::retry_runner_spawn_once;
+use crate::runner_client::spawn_runner_transport;
+use crate::spawn_prep::prepare_elevated_spawn_context_for_permissions;
+use anyhow::Result;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_pty::ProcessDriver;
+use codex_utils_pty::SpawnedProcess;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+use tokio::sync::broadcast;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+
+struct RunnerTransportRequest {
+    permissions: ResolvedWindowsSandboxPermissions,
+    codex_home: PathBuf,
+    cwd: PathBuf,
+    env_map: HashMap<String, String>,
+    logs_base_dir: Option<PathBuf>,
+    spawn_request: SpawnRequest,
+    read_roots_override: Option<Vec<PathBuf>>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<Vec<PathBuf>>,
+    deny_read_paths_override: Vec<PathBuf>,
+    deny_write_paths_override: Vec<PathBuf>,
+    proxy_enforced: bool,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+}
+
+fn spawn_runner_transport_with_retry<T>(
+    sandbox_creds: SandboxCreds,
+    request: &RunnerTransportRequest,
+    mut spawn: impl FnMut(&Path, &Path, &SandboxCreds, Option<&Path>, SpawnRequest) -> Result<T>,
+    refresh: impl FnOnce(
+        &ResolvedWindowsSandboxPermissions,
+        &Path,
+        &HashMap<String, String>,
+        &Path,
+        Option<&[PathBuf]>,
+        bool,
+        Option<&[PathBuf]>,
+        &[PathBuf],
+        &[PathBuf],
+        bool,
+        crate::WindowsSandboxProxySettingsMode,
+    ) -> Result<SandboxCreds>,
+) -> Result<T> {
+    retry_runner_spawn_once(
+        sandbox_creds,
+        &request.spawn_request.command,
+        |sandbox_creds| {
+            spawn(
+                &request.codex_home,
+                &request.cwd,
+                &sandbox_creds,
+                request.logs_base_dir.as_deref(),
+                request.spawn_request.clone(),
+            )
+        },
+        || {
+            refresh(
+                &request.permissions,
+                &request.cwd,
+                &request.env_map,
+                &request.codex_home,
+                request.read_roots_override.as_deref(),
+                request.read_roots_include_platform_defaults,
+                request.write_roots_override.as_deref(),
+                &request.deny_read_paths_override,
+                &request.deny_write_paths_override,
+                request.proxy_enforced,
+                request.proxy_settings_mode,
+            )
+        },
+    )
+}
+
+async fn spawn_runner_transport_task(
+    sandbox_creds: SandboxCreds,
+    request: RunnerTransportRequest,
+) -> Result<RunnerTransport> {
+    tokio::task::spawn_blocking(move || -> Result<_> {
+        let desktop_policy = (request.spawn_request.use_private_desktop
+            && request.spawn_request.private_desktop_name.is_none())
+        .then(|| {
+            DesktopPolicy::elevated(
+                crate::setup::SandboxSetupRequest {
+                    permissions: &request.permissions,
+                    command_cwd: &request.cwd,
+                    env_map: &request.env_map,
+                    codex_home: &request.codex_home,
+                    proxy_enforced: request.proxy_enforced,
+                },
+                crate::setup::SetupRootOverrides {
+                    read_roots: request.read_roots_override.clone(),
+                    read_roots_include_platform_defaults: request
+                        .read_roots_include_platform_defaults,
+                    write_roots: request.write_roots_override.clone(),
+                    deny_read_paths: Some(request.deny_read_paths_override.clone()),
+                    deny_write_paths: Some(request.deny_write_paths_override.clone()),
+                },
+                &request.spawn_request.cap_sids,
+                request
+                    .spawn_request
+                    .network_proxy_restricting_sid
+                    .as_deref(),
+            )
+        })
+        .transpose()?;
+        spawn_runner_transport_with_retry(
+            sandbox_creds,
+            &request,
+            |codex_home, cwd, sandbox_creds, log_dir, spawn_request| {
+                spawn_runner_transport(
+                    codex_home,
+                    cwd,
+                    sandbox_creds,
+                    log_dir,
+                    spawn_request,
+                    desktop_policy.as_ref(),
+                )
+            },
+            refresh_logon_sandbox_creds,
+        )
+    })
+    .await
+    .map_err(|err| anyhow::anyhow!("runner handshake task failed: {err}"))?
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn spawn_windows_sandbox_session_elevated_for_permission_profile(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    codex_home: &Path,
+    command: Vec<String>,
+    cwd: &Path,
+    mut env_map: HashMap<String, String>,
+    proxy_enforced: bool,
+    network_proxy_restricting_sid: Option<String>,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+    timeout_ms: Option<u64>,
+    read_roots_override: Option<&[PathBuf]>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<&[PathBuf]>,
+    deny_read_paths_override: &[AbsolutePathBuf],
+    deny_write_paths_override: &[AbsolutePathBuf],
+    tty: bool,
+    stdin_open: bool,
+    use_private_desktop: bool,
+    private_desktop_name: Option<String>,
+) -> Result<SpawnedProcess> {
+    let deny_read_paths_override = deny_read_paths_override
+        .iter()
+        .map(AbsolutePathBuf::to_path_buf)
+        .collect::<Vec<_>>();
+    let deny_write_paths_override = deny_write_paths_override
+        .iter()
+        .map(AbsolutePathBuf::to_path_buf)
+        .collect::<Vec<_>>();
+    let permissions =
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            permission_profile,
+            workspace_roots,
+        )?;
+    let elevated = prepare_elevated_spawn_context_for_permissions(
+        permissions.clone(),
+        codex_home,
+        cwd,
+        &mut env_map,
+        &command,
+        read_roots_override,
+        read_roots_include_platform_defaults,
+        write_roots_override,
+        &deny_read_paths_override,
+        &deny_write_paths_override,
+        proxy_enforced,
+        proxy_settings_mode,
+    )?;
+
+    let sandbox_creds = elevated.sandbox_creds;
+    let request = RunnerTransportRequest {
+        permissions,
+        codex_home: codex_home.to_path_buf(),
+        cwd: cwd.to_path_buf(),
+        env_map: env_map.clone(),
+        logs_base_dir: elevated.logs_base_dir,
+        spawn_request: SpawnRequest {
+            command,
+            cwd: cwd.to_path_buf(),
+            env: env_map,
+            permission_profile: permission_profile.clone(),
+            workspace_roots: workspace_roots.to_vec(),
+            codex_home: elevated.sandbox_base,
+            real_codex_home: codex_home.to_path_buf(),
+            cap_sids: elevated.cap_sids,
+            network_proxy_restricting_sid,
+            timeout_ms,
+            tty,
+            stdin_open,
+            use_private_desktop,
+            private_desktop_name,
+        },
+        read_roots_override: read_roots_override.map(<[PathBuf]>::to_vec),
+        read_roots_include_platform_defaults,
+        write_roots_override: write_roots_override.map(<[PathBuf]>::to_vec),
+        deny_read_paths_override,
+        deny_write_paths_override,
+        proxy_enforced,
+        proxy_settings_mode,
+    };
+    let transport = spawn_runner_transport_task(sandbox_creds, request).await?;
+    let (pipe_write, pipe_read) = transport.into_files();
+
+    let (writer_tx, writer_rx) = mpsc::channel::<Vec<u8>>(128);
+    let (stdout_tx, stdout_rx) = broadcast::channel::<Vec<u8>>(256);
+    let stderr_rx = if tty {
+        None
+    } else {
+        Some(broadcast::channel::<Vec<u8>>(256))
+    };
+    let (exit_tx, exit_rx) = oneshot::channel::<i32>();
+
+    let outbound_tx = start_runner_pipe_writer(pipe_write);
+    let writer_handle = start_runner_stdin_writer(writer_rx, outbound_tx.clone(), tty, stdin_open);
+    let terminator = {
+        let outbound_tx = outbound_tx.clone();
+        Some(Box::new(move || {
+            let _ = outbound_tx.send(FramedMessage {
+                version: IPC_PROTOCOL_VERSION,
+                message: Message::Terminate {
+                    payload: EmptyPayload::default(),
+                },
+            });
+        }) as Box<dyn FnMut() + Send + Sync>)
+    };
+
+    start_runner_stdout_reader(
+        pipe_read,
+        stdout_tx,
+        stderr_rx.as_ref().map(|(tx, _rx)| tx.clone()),
+        exit_tx,
+    );
+
+    Ok(finish_driver_spawn(
+        ProcessDriver {
+            writer_tx,
+            stdout_rx,
+            stderr_rx: stderr_rx.map(|(_tx, rx)| rx),
+            exit_rx,
+            terminator,
+            writer_handle: Some(writer_handle),
+            resizer: if tty {
+                Some(make_runner_resizer(outbound_tx))
+            } else {
+                None
+            },
+            tty,
+        },
+        stdin_open,
+    ))
+}
+
+#[cfg(test)]
+#[path = "elevated_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated_tests.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e8025109e025187c10f68e472acab4039d3d281f
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/elevated_tests.rs
@@ -0,0 +1,194 @@
+use super::RunnerTransportRequest;
+use super::spawn_runner_transport_with_retry;
+use crate::WindowsSandboxProxySettingsMode;
+use crate::identity::SandboxCreds;
+use crate::ipc_framed::ErrorPayload;
+use crate::ipc_framed::ErrorStage;
+use crate::ipc_framed::SpawnRequest;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::runner_client::RunnerStartupError;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use serde_json::Value;
+use std::cell::Cell;
+use std::cell::RefCell;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation::ERROR_NO_SUCH_LOGON_SESSION;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct SpawnObservation {
+    codex_home: PathBuf,
+    cwd: PathBuf,
+    username: String,
+    password: String,
+    logs_base_dir: Option<PathBuf>,
+    spawn_request: Value,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct RefreshObservation {
+    permissions: ResolvedWindowsSandboxPermissions,
+    cwd: PathBuf,
+    env_map: HashMap<String, String>,
+    codex_home: PathBuf,
+    read_roots_override: Option<Vec<PathBuf>>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<Vec<PathBuf>>,
+    deny_read_paths_override: Vec<PathBuf>,
+    deny_write_paths_override: Vec<PathBuf>,
+    proxy_enforced: bool,
+    proxy_settings_mode: WindowsSandboxProxySettingsMode,
+}
+
+#[test]
+fn retry_uses_original_unified_exec_request_and_stops_after_second_failure() {
+    let workspace_root = AbsolutePathBuf::from_absolute_path(PathBuf::from(r"C:\workspace"))
+        .expect("absolute workspace root");
+    let permission_profile = PermissionProfile::workspace_write();
+    let permissions =
+        ResolvedWindowsSandboxPermissions::try_from_permission_profile_for_workspace_roots(
+            &permission_profile,
+            std::slice::from_ref(&workspace_root),
+        )
+        .expect("resolved permissions");
+    let env_map = HashMap::from([
+        ("Path".to_string(), r"C:\tools".to_string()),
+        (
+            "HTTPS_PROXY".to_string(),
+            "http://localhost:1234".to_string(),
+        ),
+    ]);
+    let request = RunnerTransportRequest {
+        permissions: permissions.clone(),
+        codex_home: PathBuf::from(r"C:\Users\codex"),
+        cwd: PathBuf::from(r"C:\workspace"),
+        env_map: env_map.clone(),
+        logs_base_dir: Some(PathBuf::from(r"C:\Users\codex\.sandbox")),
+        spawn_request: SpawnRequest {
+            command: vec!["pwsh.exe".to_string(), "-NoProfile".to_string()],
+            cwd: PathBuf::from(r"C:\workspace"),
+            env: env_map.clone(),
+            permission_profile,
+            workspace_roots: vec![workspace_root],
+            codex_home: PathBuf::from(r"C:\Users\codex\.sandbox"),
+            real_codex_home: PathBuf::from(r"C:\Users\codex"),
+            cap_sids: vec!["S-1-15-3-1024-1".to_string()],
+            network_proxy_restricting_sid: Some("S-1-5-21-100-200-300-400".to_string()),
+            timeout_ms: Some(5_000),
+            tty: true,
+            stdin_open: true,
+            use_private_desktop: true,
+            private_desktop_name: None,
+        },
+        read_roots_override: Some(vec![PathBuf::from(r"C:\workspace\read")]),
+        read_roots_include_platform_defaults: true,
+        write_roots_override: Some(vec![PathBuf::from(r"C:\workspace\write")]),
+        deny_read_paths_override: vec![PathBuf::from(r"C:\secrets")],
+        deny_write_paths_override: vec![PathBuf::from(r"C:\workspace\.codex")],
+        proxy_enforced: true,
+        proxy_settings_mode: WindowsSandboxProxySettingsMode::Preserve,
+    };
+    let expected_spawn_request =
+        serde_json::to_value(&request.spawn_request).expect("serialize spawn request");
+    let expected_refresh = RefreshObservation {
+        permissions,
+        cwd: request.cwd.clone(),
+        env_map,
+        codex_home: request.codex_home.clone(),
+        read_roots_override: request.read_roots_override.clone(),
+        read_roots_include_platform_defaults: true,
+        write_roots_override: request.write_roots_override.clone(),
+        deny_read_paths_override: request.deny_read_paths_override.clone(),
+        deny_write_paths_override: request.deny_write_paths_override.clone(),
+        proxy_enforced: true,
+        proxy_settings_mode: WindowsSandboxProxySettingsMode::Preserve,
+    };
+    let spawn_observations = RefCell::new(Vec::new());
+    let refresh_observations = RefCell::new(Vec::new());
+    let spawn_attempts = Cell::new(0);
+
+    let result = spawn_runner_transport_with_retry(
+        SandboxCreds {
+            username: "stale".to_string(),
+            password: "old".to_string(),
+        },
+        &request,
+        |codex_home, cwd, sandbox_creds, logs_base_dir, spawn_request| {
+            spawn_observations.borrow_mut().push(SpawnObservation {
+                codex_home: codex_home.to_path_buf(),
+                cwd: cwd.to_path_buf(),
+                username: sandbox_creds.username.clone(),
+                password: sandbox_creds.password.clone(),
+                logs_base_dir: logs_base_dir.map(Path::to_path_buf),
+                spawn_request: serde_json::to_value(spawn_request)
+                    .expect("serialize spawn request"),
+            });
+            spawn_attempts.set(spawn_attempts.get() + 1);
+            Err::<(), _>(anyhow::Error::new(RunnerStartupError::new(ErrorPayload {
+                message: format!("spawn attempt {} failed", spawn_attempts.get()),
+                stage: ErrorStage::SpawnChild,
+                windows_error_code: Some(ERROR_NO_SUCH_LOGON_SESSION),
+            })))
+        },
+        |permissions,
+         cwd,
+         env_map,
+         codex_home,
+         read_roots_override,
+         read_roots_include_platform_defaults,
+         write_roots_override,
+         deny_read_paths_override,
+         deny_write_paths_override,
+         proxy_enforced,
+         proxy_settings_mode| {
+            refresh_observations.borrow_mut().push(RefreshObservation {
+                permissions: permissions.clone(),
+                cwd: cwd.to_path_buf(),
+                env_map: env_map.clone(),
+                codex_home: codex_home.to_path_buf(),
+                read_roots_override: read_roots_override.map(<[PathBuf]>::to_vec),
+                read_roots_include_platform_defaults,
+                write_roots_override: write_roots_override.map(<[PathBuf]>::to_vec),
+                deny_read_paths_override: deny_read_paths_override.to_vec(),
+                deny_write_paths_override: deny_write_paths_override.to_vec(),
+                proxy_enforced,
+                proxy_settings_mode,
+            });
+            Ok(SandboxCreds {
+                username: "refreshed".to_string(),
+                password: "new".to_string(),
+            })
+        },
+    );
+
+    let err = result.expect_err("second spawn should fail");
+    assert_eq!(
+        "runner failed during SpawnChild: spawn attempt 2 failed (Windows error 1312)",
+        err.to_string()
+    );
+    assert_eq!(
+        vec![
+            SpawnObservation {
+                codex_home: request.codex_home.clone(),
+                cwd: request.cwd.clone(),
+                username: "stale".to_string(),
+                password: "old".to_string(),
+                logs_base_dir: request.logs_base_dir.clone(),
+                spawn_request: expected_spawn_request.clone(),
+            },
+            SpawnObservation {
+                codex_home: request.codex_home.clone(),
+                cwd: request.cwd.clone(),
+                username: "refreshed".to_string(),
+                password: "new".to_string(),
+                logs_base_dir: request.logs_base_dir,
+                spawn_request: expected_spawn_request,
+            },
+        ],
+        *spawn_observations.borrow()
+    );
+    assert_eq!(vec![expected_refresh], *refresh_observations.borrow());
+}
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/backends/legacy.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/legacy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ca13e191062857d0d1d4f6fbcb41d22aba3ba7eb
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/legacy.rs
@@ -0,0 +1,493 @@
+use super::windows_common::finish_driver_spawn;
+use crate::conpty::ConptyInstance;
+use crate::conpty::spawn_conpty_process_as_user;
+use crate::desktop::LaunchDesktop;
+use crate::logging::log_failure;
+use crate::logging::log_note;
+use crate::logging::log_success;
+use crate::process::ConsoleMode;
+use crate::process::StderrMode;
+use crate::process::StdinMode;
+use crate::process::read_handle_loop;
+use crate::process::spawn_process_with_pipes;
+use crate::resolved_permissions::ResolvedWindowsSandboxPermissions;
+use crate::spawn_prep::LegacyAclSids;
+use crate::spawn_prep::LegacySessionSecurity;
+use crate::spawn_prep::SpawnPrepOptions;
+use crate::spawn_prep::allow_null_device_for_workspace_write;
+use crate::spawn_prep::apply_legacy_session_acl_rules;
+use crate::spawn_prep::legacy_session_capability_roots;
+use crate::spawn_prep::prepare_legacy_session_security;
+use crate::spawn_prep::prepare_legacy_spawn_context;
+use anyhow::Result;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_pty::JobObject;
+use codex_utils_pty::ProcessDriver;
+use codex_utils_pty::SpawnedProcess;
+use codex_utils_pty::TerminalSize;
+use codex_utils_pty::WindowsTtyInputNormalizer;
+use std::collections::HashMap;
+use std::path::Path;
+use std::ptr;
+use std::sync::Arc;
+use std::sync::Mutex as StdMutex;
+use tokio::sync::broadcast;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+use windows_sys::Win32::Foundation::CloseHandle;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::INVALID_HANDLE_VALUE;
+use windows_sys::Win32::Storage::FileSystem::WriteFile;
+use windows_sys::Win32::System::Console::COORD;
+use windows_sys::Win32::System::Console::ResizePseudoConsole;
+use windows_sys::Win32::System::Threading::GetExitCodeProcess;
+use windows_sys::Win32::System::Threading::INFINITE;
+use windows_sys::Win32::System::Threading::PROCESS_INFORMATION;
+use windows_sys::Win32::System::Threading::TerminateProcess;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+const WAIT_TIMEOUT: u32 = 0x0000_0102;
+
+struct LegacyProcessHandles {
+    process: PROCESS_INFORMATION,
+    job: Arc<JobObject>,
+    output_join: std::thread::JoinHandle<()>,
+    writer_handle: tokio::task::JoinHandle<()>,
+    hpc: Option<HANDLE>,
+    conpty_owner: Option<ConptyInstance>,
+    token_handle: HANDLE,
+    desktop: Option<LaunchDesktop>,
+}
+
+#[allow(clippy::too_many_arguments)]
+fn spawn_legacy_process(
+    security: &LegacySessionSecurity,
+    permissions: &ResolvedWindowsSandboxPermissions,
+    additional_deny_write_paths: &[std::path::PathBuf],
+    command: &[String],
+    cwd: &Path,
+    env_map: &HashMap<String, String>,
+    use_private_desktop: bool,
+    private_desktop_name: Option<&str>,
+    tty: bool,
+    stdin_open: bool,
+    stdout_tx: broadcast::Sender<Vec<u8>>,
+    stderr_tx: Option<broadcast::Sender<Vec<u8>>>,
+    writer_rx: mpsc::Receiver<Vec<u8>>,
+    logs_base_dir: Option<&Path>,
+) -> Result<LegacyProcessHandles> {
+    let h_token = security.h_token;
+    let launch_desktop = match private_desktop_name {
+        Some(name) => LaunchDesktop::open_private(name)?,
+        None => LaunchDesktop::prepare_legacy(
+            use_private_desktop,
+            permissions,
+            cwd,
+            env_map,
+            security,
+            additional_deny_write_paths,
+            logs_base_dir,
+        )?,
+    };
+    let (pi, job, output_join, writer_handle, hpc, conpty_owner, desktop) = if tty {
+        let (pi, mut conpty) =
+            spawn_conpty_process_as_user(h_token, command, cwd, env_map, launch_desktop)?;
+        let job = conpty
+            .job()
+            .ok_or_else(|| anyhow::anyhow!("spawned ConPTY is missing its process job"))?;
+        let hpc = conpty.raw_handle();
+        let output_join = spawn_output_reader(conpty.take_output_read(), stdout_tx);
+        let writer_handle = spawn_input_writer(
+            Some(conpty.take_input_write()),
+            writer_rx,
+            /*normalize_newlines*/ true,
+        );
+        (pi, job, output_join, writer_handle, hpc, Some(conpty), None)
+    } else {
+        let pipe_handles = spawn_process_with_pipes(
+            h_token,
+            command,
+            cwd,
+            env_map,
+            if stdin_open {
+                StdinMode::Open
+            } else {
+                StdinMode::Closed
+            },
+            StderrMode::Separate,
+            ConsoleMode::Inherit,
+            launch_desktop,
+            logs_base_dir,
+        )?;
+        let stdout_join = spawn_output_reader(pipe_handles.stdout_read, stdout_tx);
+        let Some(stderr_read) = pipe_handles.stderr_read else {
+            anyhow::bail!("separate stderr handle should be present");
+        };
+        let Some(stderr_tx) = stderr_tx else {
+            anyhow::bail!("separate stderr channel should be present");
+        };
+        let stderr_join = spawn_output_reader(stderr_read, stderr_tx);
+        let output_join = std::thread::spawn(move || {
+            let _ = stdout_join.join();
+            let _ = stderr_join.join();
+        });
+        let writer_handle = spawn_input_writer(
+            pipe_handles.stdin_write,
+            writer_rx,
+            /*normalize_newlines*/ false,
+        );
+        (
+            pipe_handles.process,
+            pipe_handles.job(),
+            output_join,
+            writer_handle,
+            None,
+            None,
+            Some(pipe_handles.desktop),
+        )
+    };
+    Ok(LegacyProcessHandles {
+        process: pi,
+        job,
+        output_join,
+        writer_handle,
+        hpc,
+        conpty_owner,
+        token_handle: h_token,
+        desktop,
+    })
+}
+
+fn spawn_output_reader(
+    output_read: HANDLE,
+    output_tx: broadcast::Sender<Vec<u8>>,
+) -> std::thread::JoinHandle<()> {
+    read_handle_loop(output_read, move |chunk| {
+        let _ = output_tx.send(chunk.to_vec());
+    })
+}
+
+fn spawn_input_writer(
+    input_write: Option<HANDLE>,
+    mut writer_rx: mpsc::Receiver<Vec<u8>>,
+    normalize_newlines: bool,
+) -> tokio::task::JoinHandle<()> {
+    tokio::task::spawn_blocking(move || {
+        let mut windows_input = WindowsTtyInputNormalizer::default();
+        while let Some(bytes) = writer_rx.blocking_recv() {
+            let Some(handle) = input_write else {
+                continue;
+            };
+            let bytes = if normalize_newlines {
+                windows_input.normalize(&bytes)
+            } else {
+                bytes
+            };
+            if write_all_handle(handle, &bytes).is_err() {
+                break;
+            }
+        }
+        if let Some(handle) = input_write {
+            unsafe {
+                CloseHandle(handle);
+            }
+        }
+    })
+}
+
+fn terminate_job_or_process(
+    job: &JobObject,
+    process_handle: &Arc<StdMutex<Option<HANDLE>>>,
+    logs_base_dir: Option<&Path>,
+) {
+    if let Err(job_err) = job.terminate() {
+        log_note(
+            &format!("legacy spawn failed to terminate process tree: {job_err}"),
+            logs_base_dir,
+        );
+        if let Ok(guard) = process_handle.lock()
+            && let Some(handle) = guard.as_ref()
+            && unsafe { TerminateProcess(*handle, 1) } == 0
+        {
+            log_note(
+                &format!(
+                    "legacy spawn failed to terminate root process: {}",
+                    unsafe { GetLastError() }
+                ),
+                logs_base_dir,
+            );
+        }
+    }
+}
+
+fn write_all_handle(handle: HANDLE, mut bytes: &[u8]) -> Result<()> {
+    while !bytes.is_empty() {
+        let mut written = 0u32;
+        let ok = unsafe {
+            WriteFile(
+                handle,
+                bytes.as_ptr() as *const _,
+                bytes.len() as u32,
+                &mut written,
+                ptr::null_mut(),
+            )
+        };
+        if ok == 0 {
+            let err = unsafe { GetLastError() } as i32;
+            return Err(anyhow::anyhow!("WriteFile failed: {err}"));
+        }
+        if written == 0 {
+            anyhow::bail!("WriteFile returned success but wrote 0 bytes");
+        }
+        bytes = &bytes[written as usize..];
+    }
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+fn finalize_exit(
+    exit_tx: oneshot::Sender<i32>,
+    process_handle: Arc<StdMutex<Option<HANDLE>>>,
+    thread_handle: HANDLE,
+    output_join: std::thread::JoinHandle<()>,
+    logs_base_dir: Option<&Path>,
+    command: Vec<String>,
+) {
+    let exit_code = {
+        let mut raw_exit = 1u32;
+        if let Ok(guard) = process_handle.lock()
+            && let Some(handle) = guard.as_ref()
+        {
+            unsafe {
+                WaitForSingleObject(*handle, INFINITE);
+                GetExitCodeProcess(*handle, &mut raw_exit);
+            }
+        }
+        raw_exit as i32
+    };
+
+    let _ = output_join.join();
+    let _ = exit_tx.send(exit_code);
+
+    unsafe {
+        if thread_handle != 0 && thread_handle != INVALID_HANDLE_VALUE {
+            CloseHandle(thread_handle);
+        }
+        if let Ok(mut guard) = process_handle.lock()
+            && let Some(handle) = guard.take()
+        {
+            CloseHandle(handle);
+        }
+    }
+
+    if exit_code == 0 {
+        log_success(&command, logs_base_dir);
+    } else {
+        log_failure(&command, &format!("exit code {exit_code}"), logs_base_dir);
+    }
+}
+
+fn resize_conpty_handle(hpc: &Arc<StdMutex<Option<HANDLE>>>, size: TerminalSize) -> Result<()> {
+    let guard = hpc
+        .lock()
+        .map_err(|_| anyhow::anyhow!("failed to lock ConPTY handle"))?;
+    let hpc = guard
+        .as_ref()
+        .copied()
+        .ok_or_else(|| anyhow::anyhow!("process is not attached to a PTY"))?;
+    let result = unsafe {
+        ResizePseudoConsole(
+            hpc,
+            COORD {
+                X: size.cols as i16,
+                Y: size.rows as i16,
+            },
+        )
+    };
+    if result == 0 {
+        Ok(())
+    } else {
+        Err(anyhow::anyhow!(
+            "failed to resize console: HRESULT {result}"
+        ))
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn spawn_windows_sandbox_session_legacy(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    codex_home: &Path,
+    command: Vec<String>,
+    cwd: &Path,
+    mut env_map: HashMap<String, String>,
+    timeout_ms: Option<u64>,
+    additional_deny_read_paths: &[AbsolutePathBuf],
+    additional_deny_write_paths: &[AbsolutePathBuf],
+    tty: bool,
+    stdin_open: bool,
+    use_private_desktop: bool,
+    private_desktop_name: Option<String>,
+) -> Result<SpawnedProcess> {
+    let common = prepare_legacy_spawn_context(
+        permission_profile,
+        workspace_roots,
+        codex_home,
+        cwd,
+        &mut env_map,
+        &command,
+        SpawnPrepOptions {
+            inherit_path: false,
+            add_git_safe_directory: false,
+        },
+    )?;
+    if !common.permissions.has_full_disk_read_access() {
+        anyhow::bail!("Restricted read-only access requires the elevated Windows sandbox backend");
+    }
+    // WRITE_RESTRICTED tokens consult restricting SIDs only for writes, so this
+    // backend cannot make capability-SID deny-read ACLs authoritative.
+    if !additional_deny_read_paths.is_empty() {
+        anyhow::bail!("deny-read overrides require the elevated Windows sandbox backend");
+    }
+    let additional_deny_write_paths = additional_deny_write_paths
+        .iter()
+        .map(AbsolutePathBuf::to_path_buf)
+        .collect::<Vec<_>>();
+    let capability_roots = legacy_session_capability_roots(
+        &common.permissions,
+        &common.current_dir,
+        &env_map,
+        codex_home,
+    );
+    let security = prepare_legacy_session_security(
+        common.uses_write_capabilities,
+        codex_home,
+        cwd,
+        capability_roots,
+    )?;
+    allow_null_device_for_workspace_write(common.uses_write_capabilities);
+
+    apply_legacy_session_acl_rules(
+        &common.permissions,
+        codex_home,
+        &common.current_dir,
+        &env_map,
+        &[],
+        &additional_deny_write_paths,
+        LegacyAclSids {
+            readonly_sid: security.readonly_sid.as_ref(),
+            readonly_sid_str: security.readonly_sid_str.as_deref(),
+            write_root_sids: &security.write_root_sids,
+        },
+    )?;
+
+    let (writer_tx, writer_rx) = mpsc::channel::<Vec<u8>>(128);
+    let (stdout_tx, stdout_rx) = broadcast::channel::<Vec<u8>>(256);
+    let stderr_rx = if tty {
+        None
+    } else {
+        Some(broadcast::channel::<Vec<u8>>(256))
+    };
+    let (exit_tx, exit_rx) = oneshot::channel::<i32>();
+
+    let LegacyProcessHandles {
+        process: pi,
+        job,
+        output_join,
+        writer_handle,
+        hpc,
+        mut conpty_owner,
+        token_handle,
+        desktop,
+    } = match spawn_legacy_process(
+        &security,
+        &common.permissions,
+        &additional_deny_write_paths,
+        &command,
+        cwd,
+        &env_map,
+        use_private_desktop,
+        private_desktop_name.as_deref(),
+        tty,
+        stdin_open,
+        stdout_tx,
+        stderr_rx.as_ref().map(|(tx, _rx)| tx.clone()),
+        writer_rx,
+        common.logs_base_dir.as_deref(),
+    ) {
+        Ok(handles) => handles,
+        Err(err) => {
+            unsafe {
+                CloseHandle(security.h_token);
+            }
+            return Err(err);
+        }
+    };
+    let hpc_handle = hpc.map(|hpc| Arc::new(StdMutex::new(Some(hpc))));
+
+    let process_handle = Arc::new(StdMutex::new(Some(pi.hProcess)));
+    let wait_handle = Arc::clone(&process_handle);
+    let job_for_wait = Arc::clone(&job);
+    let command_for_wait = command.clone();
+    let hpc_for_wait = hpc_handle.clone();
+    let wait_logs_base_dir = common.logs_base_dir.clone();
+    std::thread::spawn(move || {
+        let _desktop = desktop;
+        let timeout = timeout_ms.map(|ms| ms as u32).unwrap_or(INFINITE);
+        let wait_res = unsafe { WaitForSingleObject(pi.hProcess, timeout) };
+        if wait_res == WAIT_TIMEOUT {
+            terminate_job_or_process(&job_for_wait, &wait_handle, wait_logs_base_dir.as_deref());
+        } else if let Err(err) = job_for_wait.preserve_descendants() {
+            log_note(
+                &format!("legacy spawn failed to preserve descendants after root exit: {err}"),
+                wait_logs_base_dir.as_deref(),
+            );
+        }
+        if let Some(hpc) = hpc_for_wait
+            && let Ok(mut guard) = hpc.lock()
+        {
+            let _ = guard.take();
+        }
+        drop(conpty_owner.take());
+        unsafe {
+            if token_handle != 0 && token_handle != INVALID_HANDLE_VALUE {
+                CloseHandle(token_handle);
+            }
+        }
+        finalize_exit(
+            exit_tx,
+            wait_handle,
+            pi.hThread,
+            output_join,
+            wait_logs_base_dir.as_deref(),
+            command_for_wait,
+        );
+    });
+
+    let terminator = {
+        let job = Arc::clone(&job);
+        let process_handle = Arc::clone(&process_handle);
+        let logs_base_dir = common.logs_base_dir;
+        Some(Box::new(move || {
+            terminate_job_or_process(&job, &process_handle, logs_base_dir.as_deref());
+        }) as Box<dyn FnMut() + Send + Sync>)
+    };
+
+    let driver = ProcessDriver {
+        writer_tx,
+        stdout_rx,
+        stderr_rx: stderr_rx.map(|(_tx, rx)| rx),
+        exit_rx,
+        terminator,
+        writer_handle: Some(writer_handle),
+        resizer: hpc_handle.map(|hpc| {
+            Box::new(move |size| resize_conpty_handle(&hpc, size))
+                as Box<dyn FnMut(TerminalSize) -> Result<()> + Send>
+        }),
+        tty,
+    };
+
+    Ok(finish_driver_spawn(driver, stdin_open))
+}
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/backends/mod.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..9d2aaa9070bb269c766b404a3bdeb365fc29955b
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/mod.rs
@@ -0,0 +1,3 @@
+pub(crate) mod elevated;
+pub(crate) mod legacy;
+pub(crate) mod windows_common;
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/backends/windows_common.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/windows_common.rs
new file mode 100644
index 0000000000000000000000000000000000000000..05a87785898cee81d633ad8da294a861fc9e84a0
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/windows_common.rs
@@ -0,0 +1,178 @@
+use crate::ipc_framed::EmptyPayload;
+use crate::ipc_framed::FramedMessage;
+use crate::ipc_framed::IPC_PROTOCOL_VERSION;
+use crate::ipc_framed::Message;
+use crate::ipc_framed::OutputStream;
+use crate::ipc_framed::ResizePayload;
+use crate::ipc_framed::StdinPayload;
+use crate::ipc_framed::decode_bytes;
+use crate::ipc_framed::encode_bytes;
+use anyhow::Result;
+use codex_utils_pty::ProcessDriver;
+use codex_utils_pty::SpawnedProcess;
+use codex_utils_pty::TerminalSize;
+use codex_utils_pty::WindowsTtyInputNormalizer;
+use codex_utils_pty::spawn_from_driver;
+use std::fs::File;
+use tokio::sync::broadcast;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+
+pub(crate) fn finish_driver_spawn(driver: ProcessDriver, stdin_open: bool) -> SpawnedProcess {
+    let spawned = spawn_from_driver(driver);
+    if !stdin_open {
+        spawned.session.close_stdin();
+    }
+    spawned
+}
+
+pub(crate) fn start_runner_pipe_writer(
+    mut pipe_write: File,
+) -> std::sync::mpsc::Sender<FramedMessage> {
+    let (outbound_tx, outbound_rx) = std::sync::mpsc::channel::<FramedMessage>();
+    tokio::task::spawn_blocking(move || {
+        while let Ok(msg) = outbound_rx.recv() {
+            if crate::ipc_framed::write_frame(&mut pipe_write, &msg).is_err() {
+                break;
+            }
+        }
+    });
+    outbound_tx
+}
+
+pub(crate) fn start_runner_stdin_writer(
+    mut writer_rx: mpsc::Receiver<Vec<u8>>,
+    outbound_tx: std::sync::mpsc::Sender<FramedMessage>,
+    normalize_newlines: bool,
+    stdin_open: bool,
+) -> tokio::task::JoinHandle<()> {
+    tokio::task::spawn_blocking(move || {
+        let mut windows_input = WindowsTtyInputNormalizer::default();
+        while let Some(bytes) = writer_rx.blocking_recv() {
+            let bytes = if normalize_newlines {
+                windows_input.normalize(&bytes)
+            } else {
+                bytes
+            };
+            let msg = FramedMessage {
+                version: IPC_PROTOCOL_VERSION,
+                message: Message::Stdin {
+                    payload: StdinPayload {
+                        data_b64: encode_bytes(&bytes),
+                    },
+                },
+            };
+            if outbound_tx.send(msg).is_err() {
+                break;
+            }
+        }
+        if stdin_open {
+            let _ = outbound_tx.send(FramedMessage {
+                version: IPC_PROTOCOL_VERSION,
+                message: Message::CloseStdin {
+                    payload: EmptyPayload::default(),
+                },
+            });
+        }
+    })
+}
+
+pub(crate) fn start_runner_stdout_reader(
+    mut pipe_read: File,
+    stdout_tx: broadcast::Sender<Vec<u8>>,
+    stderr_tx: Option<broadcast::Sender<Vec<u8>>>,
+    exit_tx: oneshot::Sender<i32>,
+) {
+    std::thread::spawn(move || {
+        let exit = loop {
+            let msg = match crate::ipc_framed::read_frame(&mut pipe_read) {
+                Ok(Some(v)) => v,
+                Ok(None) => {
+                    send_runner_error(
+                        "runner pipe closed before exit",
+                        &stdout_tx,
+                        stderr_tx.as_ref(),
+                    );
+                    break None;
+                }
+                Err(err) => {
+                    send_runner_error(
+                        &format!("runner read failed: {err}"),
+                        &stdout_tx,
+                        stderr_tx.as_ref(),
+                    );
+                    break None;
+                }
+            };
+
+            match msg.message {
+                Message::Output { payload } => {
+                    if let Ok(data) = decode_bytes(&payload.data_b64) {
+                        match payload.stream {
+                            OutputStream::Stdout => {
+                                let _ = stdout_tx.send(data);
+                            }
+                            OutputStream::Stderr => {
+                                if let Some(stderr_tx) = stderr_tx.as_ref() {
+                                    let _ = stderr_tx.send(data);
+                                } else {
+                                    let _ = stdout_tx.send(data);
+                                }
+                            }
+                        }
+                    }
+                }
+                Message::Exit { payload } => {
+                    break Some((payload.exit_code, payload.timed_out));
+                }
+                Message::Error { payload } => {
+                    send_runner_error(&payload.message, &stdout_tx, stderr_tx.as_ref());
+                    break None;
+                }
+                Message::SpawnReady { .. }
+                | Message::Stdin { .. }
+                | Message::CloseStdin { .. }
+                | Message::Resize { .. }
+                | Message::SpawnRequest { .. }
+                | Message::Terminate { .. } => {}
+            }
+        };
+        crate::elevated::runner_metrics::record_command(exit);
+        let _ = exit_tx.send(exit.map_or(-1, |(code, _)| code));
+    });
+}
+
+pub(crate) fn make_runner_resizer(
+    outbound_tx: std::sync::mpsc::Sender<FramedMessage>,
+) -> Box<dyn FnMut(TerminalSize) -> Result<()> + Send> {
+    Box::new(move |size: TerminalSize| {
+        outbound_tx
+            .send(FramedMessage {
+                version: IPC_PROTOCOL_VERSION,
+                message: Message::Resize {
+                    payload: ResizePayload {
+                        rows: size.rows,
+                        cols: size.cols,
+                    },
+                },
+            })
+            .map_err(|_| anyhow::anyhow!("runner resize pipe closed"))
+    })
+}
+
+fn send_runner_error(
+    message: &str,
+    stdout_tx: &broadcast::Sender<Vec<u8>>,
+    stderr_tx: Option<&broadcast::Sender<Vec<u8>>>,
+) {
+    let formatted = format!("runner error: {message}\n").into_bytes();
+    if let Some(stderr_tx) = stderr_tx {
+        let _ = stderr_tx.send(formatted);
+    } else {
+        let _ = stdout_tx.send(formatted);
+    }
+}
+
+#[cfg(test)]
+#[path = "windows_common_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/backends/windows_common_tests.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/windows_common_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..1a957e1e52157c968708e8dcb9100440c12face3
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/backends/windows_common_tests.rs
@@ -0,0 +1,34 @@
+//! The result-metric hook must preserve terminal exit codes and pipe-failure behavior.
+
+use super::*;
+use crate::ipc_framed::ExitPayload;
+use crate::ipc_framed::write_frame;
+use pretty_assertions::assert_eq;
+use std::io::Seek;
+
+#[test]
+fn runner_result_reporting_preserves_exit_and_closed_pipe_results() -> Result<()> {
+    for exit_code in [Some(0), Some(23), None] {
+        let mut frames = tempfile::tempfile()?;
+        if let Some(exit_code) = exit_code {
+            write_frame(
+                &mut frames,
+                &FramedMessage {
+                    version: IPC_PROTOCOL_VERSION,
+                    message: Message::Exit {
+                        payload: ExitPayload {
+                            exit_code,
+                            timed_out: false,
+                        },
+                    },
+                },
+            )?;
+        }
+        frames.rewind()?;
+        let (stdout_tx, _stdout_rx) = broadcast::channel(1);
+        let (exit_tx, exit_rx) = oneshot::channel();
+        start_runner_stdout_reader(frames, stdout_tx, /*stderr_tx*/ None, exit_tx);
+        assert_eq!(exit_rx.blocking_recv()?, exit_code.unwrap_or(-1));
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/mod.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/mod.rs
new file mode 100644
index 0000000000000000000000000000000000000000..540baf0c237388d4e82fcadb623deff9d20f2105
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/mod.rs
@@ -0,0 +1,196 @@
+//! Unified exec session spawner for Windows sandboxing.
+//!
+//! This module is the thin orchestration layer for Windows unified-exec sessions.
+//! Backend-specific mechanics live in sibling modules:
+//! - `backends::legacy` adapts the direct restricted-token spawn path into a live session.
+//! - `backends::elevated` adapts the elevated command-runner IPC path into the same session API.
+//! - `backends::windows_common` holds the small shared Windows backend helpers
+//!   used by both.
+
+mod backends;
+
+use anyhow::Result;
+use anyhow::bail;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_pty::SpawnedProcess;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+/// Fully resolved Windows sandbox session launch request.
+///
+/// Callers should parse their own input shape first, then use this request to
+/// share the elevated-vs-legacy backend selection and session launch path.
+// TODO(anp): Reconcile Windows backend and desktop copies with the supplied sandbox
+// context (TurnEnvironment::sandbox_context for turns), preserving this launch snapshot.
+pub struct WindowsSandboxSessionRequest<'a> {
+    pub permission_profile: &'a PermissionProfile,
+    pub workspace_roots: &'a [AbsolutePathBuf],
+    pub codex_home: &'a Path,
+    pub command: Vec<String>,
+    pub cwd: &'a Path,
+    pub env_map: HashMap<String, String>,
+    pub windows_sandbox_level: WindowsSandboxLevel,
+    pub proxy_enforced: bool,
+    pub network_proxy_restricting_sid: Option<String>,
+    pub proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+    pub timeout_ms: Option<u64>,
+    pub read_roots_override: Option<&'a [PathBuf]>,
+    pub read_roots_include_platform_defaults: bool,
+    pub write_roots_override: Option<&'a [PathBuf]>,
+    pub deny_read_paths_override: &'a [AbsolutePathBuf],
+    pub deny_write_paths_override: &'a [AbsolutePathBuf],
+    pub tty: bool,
+    pub stdin_open: bool,
+    pub use_private_desktop: bool,
+}
+
+pub async fn spawn_windows_sandbox_session_for_level(
+    request: WindowsSandboxSessionRequest<'_>,
+) -> Result<SpawnedProcess> {
+    spawn_windows_sandbox_session_with_desktop(request, /*private_desktop_name*/ None).await
+}
+
+pub(crate) async fn spawn_windows_sandbox_session_with_desktop(
+    request: WindowsSandboxSessionRequest<'_>,
+    private_desktop_name: Option<String>,
+) -> Result<SpawnedProcess> {
+    if matches!(request.windows_sandbox_level, WindowsSandboxLevel::Elevated) {
+        backends::elevated::spawn_windows_sandbox_session_elevated_for_permission_profile(
+            request.permission_profile,
+            request.workspace_roots,
+            request.codex_home,
+            request.command,
+            request.cwd,
+            request.env_map,
+            request.proxy_enforced,
+            request.network_proxy_restricting_sid,
+            request.proxy_settings_mode,
+            request.timeout_ms,
+            request.read_roots_override,
+            request.read_roots_include_platform_defaults,
+            request.write_roots_override,
+            request.deny_read_paths_override,
+            request.deny_write_paths_override,
+            request.tty,
+            request.stdin_open,
+            request.use_private_desktop,
+            private_desktop_name,
+        )
+        .await
+    } else {
+        if request.proxy_enforced {
+            bail!("managed networking requires the elevated Windows sandbox backend");
+        }
+        if request.network_proxy_restricting_sid.is_some() {
+            bail!("network proxy restricting SID requires the elevated Windows sandbox backend");
+        }
+        backends::legacy::spawn_windows_sandbox_session_legacy(
+            request.permission_profile,
+            request.workspace_roots,
+            request.codex_home,
+            request.command,
+            request.cwd,
+            request.env_map,
+            request.timeout_ms,
+            request.deny_read_paths_override,
+            request.deny_write_paths_override,
+            request.tty,
+            request.stdin_open,
+            request.use_private_desktop,
+            private_desktop_name,
+        )
+        .await
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub async fn spawn_windows_sandbox_session_legacy(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    codex_home: &Path,
+    command: Vec<String>,
+    cwd: &Path,
+    env_map: HashMap<String, String>,
+    timeout_ms: Option<u64>,
+    additional_deny_read_paths: &[AbsolutePathBuf],
+    additional_deny_write_paths: &[AbsolutePathBuf],
+    tty: bool,
+    stdin_open: bool,
+    use_private_desktop: bool,
+) -> Result<SpawnedProcess> {
+    backends::legacy::spawn_windows_sandbox_session_legacy(
+        permission_profile,
+        workspace_roots,
+        codex_home,
+        command,
+        cwd,
+        env_map,
+        timeout_ms,
+        additional_deny_read_paths,
+        additional_deny_write_paths,
+        tty,
+        stdin_open,
+        use_private_desktop,
+        /*private_desktop_name*/ None,
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub async fn spawn_windows_sandbox_session_elevated_for_permission_profile(
+    permission_profile: &PermissionProfile,
+    workspace_roots: &[AbsolutePathBuf],
+    codex_home: &Path,
+    command: Vec<String>,
+    cwd: &Path,
+    env_map: HashMap<String, String>,
+    proxy_enforced: bool,
+    network_proxy_restricting_sid: Option<String>,
+    timeout_ms: Option<u64>,
+    read_roots_override: Option<&[PathBuf]>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<&[PathBuf]>,
+    deny_read_paths_override: &[AbsolutePathBuf],
+    deny_write_paths_override: &[AbsolutePathBuf],
+    tty: bool,
+    stdin_open: bool,
+    use_private_desktop: bool,
+) -> Result<SpawnedProcess> {
+    backends::elevated::spawn_windows_sandbox_session_elevated_for_permission_profile(
+        permission_profile,
+        workspace_roots,
+        codex_home,
+        command,
+        cwd,
+        env_map,
+        proxy_enforced,
+        network_proxy_restricting_sid,
+        crate::WindowsSandboxProxySettingsMode::Reconcile,
+        timeout_ms,
+        read_roots_override,
+        read_roots_include_platform_defaults,
+        write_roots_override,
+        deny_read_paths_override,
+        deny_write_paths_override,
+        tty,
+        stdin_open,
+        use_private_desktop,
+        /*private_desktop_name*/ None,
+    )
+    .await
+}
+
+#[cfg(test)]
+pub(crate) use backends::windows_common::finish_driver_spawn;
+#[cfg(test)]
+pub(crate) use backends::windows_common::make_runner_resizer;
+#[cfg(test)]
+pub(crate) use backends::windows_common::start_runner_pipe_writer;
+#[cfg(test)]
+pub(crate) use backends::windows_common::start_runner_stdin_writer;
+
+#[cfg(test)]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/unified_exec/tests.rs b/codex-rs/windows-sandbox-rs/src/unified_exec/tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..296b81b0e4177539681a86e4ee7f7f14a243d5a5
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/unified_exec/tests.rs
@@ -0,0 +1,1196 @@
+#![cfg(target_os = "windows")]
+
+use super::WindowsSandboxSessionRequest;
+use super::spawn_windows_sandbox_session_elevated_for_permission_profile;
+use super::spawn_windows_sandbox_session_for_level;
+use super::spawn_windows_sandbox_session_legacy;
+use crate::WindowsSandboxCancellationToken;
+use crate::ipc_framed::Message;
+use crate::ipc_framed::decode_bytes;
+use crate::ipc_framed::read_frame;
+use crate::run_windows_sandbox_capture;
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use codex_utils_pty::ProcessDriver;
+use codex_utils_pty::ProcessSignal;
+use pretty_assertions::assert_eq;
+use std::collections::HashMap;
+use std::fs;
+use std::fs::OpenOptions;
+use std::io::Seek;
+use std::io::SeekFrom;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::MutexGuard;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+use std::time::Instant;
+use tempfile::TempDir;
+use tokio::runtime::Builder;
+use tokio::sync::broadcast;
+use tokio::sync::mpsc;
+use tokio::sync::oneshot;
+use tokio::time::timeout;
+use windows_sys::Win32::Foundation::WAIT_FAILED;
+use windows_sys::Win32::Foundation::WAIT_OBJECT_0;
+use windows_sys::Win32::Foundation::WAIT_TIMEOUT;
+use windows_sys::Win32::System::Threading::OpenProcess;
+use windows_sys::Win32::System::Threading::PROCESS_SYNCHRONIZE;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+static TEST_HOME_COUNTER: AtomicU64 = AtomicU64::new(0);
+static LEGACY_PROCESS_TEST_LOCK: Mutex<()> = Mutex::new(());
+
+fn legacy_process_test_guard() -> MutexGuard<'static, ()> {
+    LEGACY_PROCESS_TEST_LOCK
+        .lock()
+        .expect("legacy Windows sandbox process test lock poisoned")
+}
+
+fn current_thread_runtime() -> tokio::runtime::Runtime {
+    Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .expect("build tokio runtime")
+}
+
+fn pwsh_path() -> Option<PathBuf> {
+    let program_files = std::env::var_os("ProgramFiles")?;
+    let path = PathBuf::from(program_files).join("PowerShell\\7\\pwsh.exe");
+    path.is_file().then_some(path)
+}
+
+fn sandbox_cwd() -> PathBuf {
+    if let Ok(workspace_root) = std::env::var("INSTA_WORKSPACE_ROOT") {
+        return PathBuf::from(workspace_root);
+    }
+
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .expect("repo root")
+        .to_path_buf()
+}
+
+fn sandbox_home(name: &str) -> TempDir {
+    let id = TEST_HOME_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let path = std::env::temp_dir().join(format!("codex-windows-sandbox-{name}-{id}"));
+    let _ = fs::remove_dir_all(&path);
+    fs::create_dir_all(&path).expect("create sandbox home");
+    tempfile::TempDir::new_in(&path).expect("create sandbox home tempdir")
+}
+
+fn sandbox_log(codex_home: &Path) -> String {
+    let log_path = crate::current_log_file_path(&codex_home.join(".sandbox"));
+    fs::read_to_string(&log_path)
+        .unwrap_or_else(|err| format!("failed to read {}: {err}", log_path.display()))
+}
+
+fn workspace_roots_for(root: &Path) -> Vec<AbsolutePathBuf> {
+    vec![AbsolutePathBuf::from_absolute_path(root).expect("absolute workspace root")]
+}
+
+fn powershell_literal(path: &Path) -> String {
+    path.to_string_lossy().replace('\'', "''")
+}
+
+fn start_powershell_child(
+    pwsh: &Path,
+    stdio_dir: &Path,
+    child_command: &str,
+    parent_tail: &str,
+) -> String {
+    let encoded = BASE64.encode(
+        child_command
+            .encode_utf16()
+            .flat_map(u16::to_le_bytes)
+            .collect::<Vec<_>>(),
+    );
+    format!(
+        "Start-Process -WindowStyle Hidden -FilePath '{}' -ArgumentList '-NoProfile','-EncodedCommand','{encoded}' -RedirectStandardOutput '{}' -RedirectStandardError '{}'; {parent_tail}",
+        powershell_literal(pwsh),
+        powershell_literal(&stdio_dir.join("descendant.stdout")),
+        powershell_literal(&stdio_dir.join("descendant.stderr")),
+    )
+}
+
+fn wait_for_path(path: &Path, timeout: Duration) -> bool {
+    let deadline = Instant::now() + timeout;
+    while Instant::now() < deadline {
+        if path.exists() {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+    path.exists()
+}
+
+fn open_process_for_wait(pid: u32) -> std::io::Result<OwnedHandle> {
+    let handle = unsafe { OpenProcess(PROCESS_SYNCHRONIZE, 0, pid) };
+    if handle == 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    Ok(unsafe { OwnedHandle::from_raw_handle(handle as _) })
+}
+
+fn wait_for_process_exit(process: &OwnedHandle, timeout: Duration) -> std::io::Result<()> {
+    let timeout_ms = u32::try_from(timeout.as_millis())
+        .map_err(|_| std::io::Error::other("process wait timeout exceeds u32"))?;
+    let result = unsafe { WaitForSingleObject(process.as_raw_handle() as _, timeout_ms) };
+    match result {
+        WAIT_OBJECT_0 => Ok(()),
+        WAIT_TIMEOUT => Err(std::io::Error::new(
+            std::io::ErrorKind::TimedOut,
+            "timed out waiting for process to exit",
+        )),
+        WAIT_FAILED => Err(std::io::Error::last_os_error()),
+        result => Err(std::io::Error::other(format!(
+            "unexpected process wait result: {result}"
+        ))),
+    }
+}
+
+fn wait_for_frame_count(frames_path: &Path, expected_frames: usize) -> Vec<Message> {
+    let deadline = Instant::now() + Duration::from_secs(2);
+    loop {
+        let mut reader = OpenOptions::new()
+            .read(true)
+            .open(frames_path)
+            .expect("open frame file for read");
+        reader
+            .seek(SeekFrom::Start(0))
+            .expect("seek to start of frame file");
+
+        let mut frames = Vec::new();
+        loop {
+            match read_frame(&mut reader) {
+                Ok(Some(frame)) => frames.push(frame.message),
+                Ok(None) => break,
+                Err(_) => break,
+            }
+        }
+
+        if frames.len() >= expected_frames {
+            return frames;
+        }
+        assert!(
+            Instant::now() < deadline,
+            "timed out waiting for {expected_frames} frames, saw {}",
+            frames.len()
+        );
+        std::thread::sleep(Duration::from_millis(10));
+    }
+}
+
+async fn collect_stdout_and_exit(
+    spawned: codex_utils_pty::SpawnedProcess,
+    codex_home: &Path,
+    timeout_duration: Duration,
+) -> (Vec<u8>, i32) {
+    let codex_utils_pty::SpawnedProcess {
+        session: _session,
+        mut stdout_rx,
+        stderr_rx: _stderr_rx,
+        exit_rx,
+    } = spawned;
+    let stdout_task = tokio::spawn(async move {
+        let mut stdout = Vec::new();
+        while let Some(chunk) = stdout_rx.recv().await {
+            stdout.extend(chunk);
+        }
+        stdout
+    });
+    let exit_code = timeout(timeout_duration, exit_rx)
+        .await
+        .unwrap_or_else(|_| panic!("timed out waiting for exit\n{}", sandbox_log(codex_home)))
+        .unwrap_or(-1);
+    let stdout = timeout(timeout_duration, stdout_task)
+        .await
+        .unwrap_or_else(|_| {
+            panic!(
+                "timed out waiting for stdout task\n{}",
+                sandbox_log(codex_home)
+            )
+        })
+        .expect("stdout task join");
+    (stdout, exit_code)
+}
+
+#[test]
+fn restricted_token_rejects_managed_network_before_spawn() {
+    current_thread_runtime().block_on(async {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("restricted-token-managed-network");
+        let permission_profile = PermissionProfile::workspace_write();
+        let error = spawn_windows_sandbox_session_for_level(WindowsSandboxSessionRequest {
+            permission_profile: &permission_profile,
+            workspace_roots: &[],
+            codex_home: codex_home.path(),
+            command: Vec::new(),
+            cwd: cwd.as_path(),
+            env_map: HashMap::new(),
+            windows_sandbox_level: WindowsSandboxLevel::RestrictedToken,
+            proxy_enforced: true,
+            network_proxy_restricting_sid: None,
+            proxy_settings_mode: crate::WindowsSandboxProxySettingsMode::Preserve,
+            timeout_ms: None,
+            read_roots_override: None,
+            read_roots_include_platform_defaults: false,
+            write_roots_override: None,
+            deny_read_paths_override: &[],
+            deny_write_paths_override: &[],
+            tty: false,
+            stdin_open: false,
+            use_private_desktop: false,
+        })
+        .await
+        .expect_err("managed networking must fail before spawning an unelevated sandbox");
+
+        assert_eq!(
+            error.to_string(),
+            "managed networking requires the elevated Windows sandbox backend"
+        );
+    });
+}
+
+#[test]
+fn legacy_non_tty_cmd_emits_output() {
+    let _guard = legacy_process_test_guard();
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("legacy-non-tty-cmd");
+        println!("cmd codex_home={}", codex_home.path().display());
+        let permission_profile = PermissionProfile::workspace_write();
+        let spawned = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".to_string(),
+                "/c".to_string(),
+                "echo LEGACY-NONTTY-CMD".to_string(),
+            ],
+            cwd.as_path(),
+            HashMap::new(),
+            Some(5_000),
+            &[],
+            &[],
+            /*tty*/ false,
+            /*stdin_open*/ false,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("spawn legacy non-tty cmd session");
+        println!("cmd spawn returned");
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(10)).await;
+        println!("cmd collect returned exit_code={exit_code}");
+        let stdout = String::from_utf8_lossy(&stdout);
+        assert_eq!(exit_code, 0, "stdout={stdout:?}");
+        assert!(stdout.contains("LEGACY-NONTTY-CMD"), "stdout={stdout:?}");
+    });
+}
+
+#[test]
+fn elevated_non_tty_cmd_forwards_env_output_and_exit() {
+    let _guard = legacy_process_test_guard();
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("elevated-non-tty-cmd");
+        let permission_profile = PermissionProfile::workspace_write();
+        let env_map = HashMap::from([(
+            "CODEX_ELEVATED_TEST".to_string(),
+            "ELEVATED-ENV-OK".to_string(),
+        )]);
+        let spawned = spawn_windows_sandbox_session_elevated_for_permission_profile(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".to_string(),
+                "/d".to_string(),
+                "/c".to_string(),
+                "echo %CODEX_ELEVATED_TEST% & exit /b 23".to_string(),
+            ],
+            cwd.as_path(),
+            env_map,
+            /*proxy_enforced*/ false,
+            /*network_proxy_restricting_sid*/ None,
+            Some(5_000),
+            /*read_roots_override*/ None,
+            /*read_roots_include_platform_defaults*/ true,
+            /*write_roots_override*/ None,
+            &[],
+            &[],
+            /*tty*/ false,
+            /*stdin_open*/ false,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("spawn elevated non-tty cmd session");
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(10)).await;
+        let stdout = String::from_utf8_lossy(&stdout);
+        assert_eq!(exit_code, 23, "stdout={stdout:?}");
+        assert!(stdout.contains("ELEVATED-ENV-OK"), "stdout={stdout:?}");
+    });
+}
+
+#[test]
+#[ignore = "requires this test binary in an installed test MSIX, launched with package identity, CODEX_WINDOWS_REGISTERED_CORE=1, and CODEX_HOME provisioned by that package's service in a disposable Windows VM"]
+fn registered_non_tty_cmd_forwards_env_output_and_exit() {
+    assert!(
+        crate::registered_core_requested(),
+        "registered Core opt-in is required"
+    );
+    let codex_home = PathBuf::from(std::env::var_os("CODEX_HOME").expect("fixture CODEX_HOME"));
+    assert!(
+        crate::app_package::registered_setup_is_ready(&codex_home)
+            .expect("validate the installed package and service receipt"),
+        "the test process must have package identity and completed service setup",
+    );
+    let cwd = tempfile::tempdir().expect("isolated command workspace");
+    current_thread_runtime().block_on(async {
+        let mut env_map: HashMap<String, String> = std::env::vars().collect();
+        env_map.insert("CODEX_REGISTERED_TEST".into(), "REGISTERED-ENV-OK".into());
+        let spawned = spawn_windows_sandbox_session_elevated_for_permission_profile(
+            &PermissionProfile::workspace_write(),
+            workspace_roots_for(cwd.path()).as_slice(),
+            &codex_home,
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".into(),
+                "/d".into(),
+                "/c".into(),
+                "echo %CODEX_REGISTERED_TEST%& exit /b 23".into(),
+            ],
+            cwd.path(),
+            env_map,
+            /*proxy_enforced*/ false,
+            /*network_proxy_restricting_sid*/ None,
+            Some(5_000),
+            /*read_roots_override*/ None,
+            /*read_roots_include_platform_defaults*/ true,
+            /*write_roots_override*/ None,
+            &[],
+            &[],
+            /*tty*/ false,
+            /*stdin_open*/ false,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("launch through the service-recorded alias and authenticated pipes");
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, &codex_home, Duration::from_secs(10)).await;
+        assert_eq!(
+            (
+                String::from_utf8(stdout).expect("command output"),
+                exit_code
+            ),
+            ("REGISTERED-ENV-OK\r\n".to_owned(), 23),
+        );
+    });
+}
+
+#[test]
+fn legacy_non_tty_cmd_rejects_deny_read_overrides() {
+    let _guard = legacy_process_test_guard();
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("legacy-non-tty-deny-read");
+        let secret_path =
+            AbsolutePathBuf::from_absolute_path(cwd.join("legacy-non-tty-deny-read-secret.env"))
+                .expect("absolute deny-read fixture path");
+        let permission_profile = PermissionProfile::workspace_write();
+        let err = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".to_string(),
+                "/c".to_string(),
+                "echo deny-read".to_string(),
+            ],
+            cwd.as_path(),
+            HashMap::new(),
+            Some(5_000),
+            std::slice::from_ref(&secret_path),
+            &[],
+            /*tty*/ false,
+            /*stdin_open*/ false,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect_err("legacy deny-read should require the elevated backend");
+        assert!(
+            err.to_string()
+                .contains("deny-read overrides require the elevated Windows sandbox backend"),
+            "unexpected error: {err:#}"
+        );
+    });
+}
+
+#[test]
+fn legacy_non_tty_powershell_interrupt_terminates_process() {
+    let Some(pwsh) = pwsh_path() else {
+        return;
+    };
+    let _guard = legacy_process_test_guard();
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("legacy-non-tty-pwsh");
+        println!("pwsh codex_home={}", codex_home.path().display());
+        let permission_profile = PermissionProfile::workspace_write();
+        let spawned = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                pwsh.display().to_string(),
+                "-NoProfile".to_string(),
+                "-Command".to_string(),
+                "Write-Output LEGACY-NONTTY-DIRECT; [System.Threading.ManualResetEvent]::new($false).WaitOne()".to_string(),
+            ],
+            cwd.as_path(),
+            HashMap::new(),
+            /*timeout_ms*/ None,
+            &[],
+            &[],
+            /*tty*/ false,
+            /*stdin_open*/ false,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("spawn legacy non-tty powershell session");
+        println!("pwsh spawn returned");
+        let codex_utils_pty::SpawnedProcess {
+            session,
+            mut stdout_rx,
+            stderr_rx: _stderr_rx,
+            exit_rx,
+        } = spawned;
+        timeout(Duration::from_secs(5), async {
+            let mut stdout = Vec::new();
+            while let Some(chunk) = stdout_rx.recv().await {
+                stdout.extend(chunk);
+                if String::from_utf8_lossy(&stdout).contains("LEGACY-NONTTY-DIRECT") {
+                    return;
+                }
+            }
+            panic!(
+                "PowerShell exited before emitting its readiness marker\n{}",
+                sandbox_log(codex_home.path())
+            );
+        })
+        .await
+        .unwrap_or_else(|_| {
+            panic!(
+                "timed out waiting for PowerShell readiness marker\n{}",
+                sandbox_log(codex_home.path())
+            )
+        });
+
+        session
+            .signal(ProcessSignal::Interrupt)
+            .expect("interrupt should terminate the restricted-token process job");
+        let exit_code = timeout(Duration::from_secs(5), exit_rx)
+            .await
+            .unwrap_or_else(|_| panic!("timed out waiting for exit\n{}", sandbox_log(codex_home.path())))
+            .expect("interrupted process should report an exit code");
+        assert_eq!(exit_code, 1);
+    });
+}
+
+#[test]
+fn finish_driver_spawn_keeps_stdin_open_when_requested() {
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let (writer_tx, mut writer_rx) = mpsc::channel::<Vec<u8>>(1);
+        let (_stdout_tx, stdout_rx) = broadcast::channel::<Vec<u8>>(1);
+        let (exit_tx, exit_rx) = oneshot::channel::<i32>();
+        drop(exit_tx);
+
+        let spawned = super::finish_driver_spawn(
+            ProcessDriver {
+                writer_tx,
+                stdout_rx,
+                stderr_rx: None,
+                exit_rx,
+                terminator: None,
+                writer_handle: None,
+                resizer: None,
+                tty: false,
+            },
+            /*stdin_open*/ true,
+        );
+
+        spawned
+            .session
+            .writer_sender()
+            .send(b"open".to_vec())
+            .await
+            .expect("stdin should stay open");
+        assert_eq!(writer_rx.recv().await, Some(b"open".to_vec()));
+    });
+}
+
+#[test]
+fn finish_driver_spawn_closes_stdin_when_not_requested() {
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let (writer_tx, _writer_rx) = mpsc::channel::<Vec<u8>>(1);
+        let (_stdout_tx, stdout_rx) = broadcast::channel::<Vec<u8>>(1);
+        let (exit_tx, exit_rx) = oneshot::channel::<i32>();
+        drop(exit_tx);
+
+        let spawned = super::finish_driver_spawn(
+            ProcessDriver {
+                writer_tx,
+                stdout_rx,
+                stderr_rx: None,
+                exit_rx,
+                terminator: None,
+                writer_handle: None,
+                resizer: None,
+                tty: false,
+            },
+            /*stdin_open*/ false,
+        );
+
+        assert!(
+            spawned
+                .session
+                .writer_sender()
+                .send(b"closed".to_vec())
+                .await
+                .is_err(),
+            "stdin should be closed when streaming input is disabled"
+        );
+    });
+}
+
+#[test]
+fn runner_stdin_writer_sends_close_stdin_after_input_eof() {
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let tempdir = TempDir::new().expect("create tempdir");
+        let frames_path = tempdir.path().join("runner-stdin-frames.bin");
+        let file = OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .read(true)
+            .write(true)
+            .open(&frames_path)
+            .expect("create frame file");
+        let outbound_tx = super::start_runner_pipe_writer(file);
+        let (writer_tx, writer_rx) = mpsc::channel::<Vec<u8>>(1);
+        let writer_handle = super::start_runner_stdin_writer(
+            writer_rx,
+            outbound_tx,
+            /*normalize_newlines*/ false,
+            /*stdin_open*/ true,
+        );
+
+        writer_tx
+            .send(b"hello".to_vec())
+            .await
+            .expect("send stdin bytes");
+        drop(writer_tx);
+        writer_handle.await.expect("join stdin writer");
+
+        let frames = wait_for_frame_count(&frames_path, 2);
+
+        match &frames[0] {
+            Message::Stdin { payload } => {
+                let bytes = decode_bytes(&payload.data_b64).expect("decode stdin payload");
+                assert_eq!(bytes, b"hello".to_vec());
+            }
+            other => panic!("expected stdin frame, got {other:?}"),
+        }
+
+        match &frames[1] {
+            Message::CloseStdin { .. } => {}
+            other => panic!("expected close-stdin frame, got {other:?}"),
+        }
+    });
+}
+
+#[test]
+fn runner_resizer_sends_resize_frame() {
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let tempdir = TempDir::new().expect("create tempdir");
+        let frames_path = tempdir.path().join("runner-resize-frames.bin");
+        let file = OpenOptions::new()
+            .create(true)
+            .truncate(true)
+            .read(true)
+            .write(true)
+            .open(&frames_path)
+            .expect("create frame file");
+        let outbound_tx = super::start_runner_pipe_writer(file);
+        let mut resizer = super::make_runner_resizer(outbound_tx);
+
+        resizer(codex_utils_pty::TerminalSize {
+            rows: 45,
+            cols: 132,
+        })
+        .expect("send resize frame");
+
+        let frames = wait_for_frame_count(&frames_path, 1);
+        match &frames[0] {
+            Message::Resize { payload } => {
+                assert_eq!(payload.rows, 45);
+                assert_eq!(payload.cols, 132);
+            }
+            other => panic!("expected resize frame, got {other:?}"),
+        }
+    });
+}
+
+#[test]
+fn legacy_capture_emits_output_and_preserves_descendant_after_normal_exit() {
+    let Some(pwsh) = pwsh_path() else {
+        return;
+    };
+    let _guard = legacy_process_test_guard();
+    let cwd = sandbox_cwd();
+    let codex_home = sandbox_home("legacy-capture-pwsh");
+    println!("capture pwsh codex_home={}", codex_home.path().display());
+    let ready_marker = codex_home.path().join("descendant-started");
+    let release_marker = codex_home.path().join("release-descendant");
+    let survival_marker = codex_home.path().join("descendant-survived");
+    let descendant_command = format!(
+        "$deadline=(Get-Date).AddSeconds(30); Set-Content -LiteralPath '{}' -Value $PID; while (-not (Test-Path -LiteralPath '{}')) {{ if ((Get-Date) -ge $deadline) {{ exit 3 }}; Start-Sleep -Milliseconds 25 }}; Set-Content -LiteralPath '{}' -Value survived",
+        powershell_literal(&ready_marker),
+        powershell_literal(&release_marker),
+        powershell_literal(&survival_marker),
+    );
+    let parent_tail = format!(
+        "while (-not (Test-Path -LiteralPath '{}')) {{ Start-Sleep -Milliseconds 25 }}",
+        powershell_literal(&ready_marker),
+    );
+    let parent_command = format!(
+        "Write-Output LEGACY-CAPTURE-DIRECT; {}",
+        start_powershell_child(&pwsh, codex_home.path(), &descendant_command, &parent_tail,),
+    );
+    let permission_profile = PermissionProfile::workspace_write();
+    let result = run_windows_sandbox_capture(
+        &permission_profile,
+        workspace_roots_for(cwd.as_path()).as_slice(),
+        codex_home.path(),
+        vec![
+            pwsh.display().to_string(),
+            "-NoProfile".to_string(),
+            "-Command".to_string(),
+            parent_command,
+        ],
+        cwd.as_path(),
+        HashMap::new(),
+        Some(10_000),
+        /*cancellation*/ None,
+        /*use_private_desktop*/ true,
+    )
+    .expect("run legacy capture powershell");
+    let descendant_pid = fs::read_to_string(&ready_marker)
+        .expect("read descendant pid")
+        .trim()
+        .parse()
+        .expect("parse descendant pid");
+    let descendant_process = open_process_for_wait(descendant_pid);
+    fs::write(&release_marker, "release").expect("release descendant after root exit");
+    let descendant_process = descendant_process.expect("open descendant after normal capture exit");
+
+    println!("capture pwsh exit_code={}", result.exit_code);
+    println!("capture pwsh timed_out={}", result.timed_out);
+    let stdout = String::from_utf8_lossy(&result.stdout);
+    let stderr = String::from_utf8_lossy(&result.stderr);
+    println!("capture pwsh stderr={stderr:?}");
+    assert_eq!(result.exit_code, 0, "stdout={stdout:?} stderr={stderr:?}");
+    assert!(
+        stdout.contains("LEGACY-CAPTURE-DIRECT"),
+        "stdout={stdout:?}"
+    );
+    assert!(
+        wait_for_path(&survival_marker, Duration::from_secs(10)),
+        "sandbox descendant did not survive normal capture exit"
+    );
+    wait_for_process_exit(&descendant_process, Duration::from_secs(10))
+        .expect("sandbox descendant did not exit after release");
+}
+
+#[test]
+fn legacy_workspace_write_delete_is_limited_to_writable_roots() {
+    let _guard = legacy_process_test_guard();
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        // Keep writable roots out of USERPROFILE exclusions such as AppData.
+        let test_root = TempDir::new_in(sandbox_cwd()).expect("create legacy delete test root");
+        let codex_home = sandbox_home("legacy-delete-writable-roots");
+        let workspace = test_root.path().join("workspace");
+        let temp_root = test_root.path().join("temp");
+        let tmp_root = test_root.path().join("tmp");
+        let outside_root = test_root.path().join("outside");
+        for directory in [&workspace, &temp_root, &tmp_root, &outside_root] {
+            fs::create_dir_all(directory).expect("create legacy delete test directory");
+        }
+        let protected_git_dir = workspace.join(".git");
+        fs::create_dir(&protected_git_dir).expect("create protected .git directory");
+
+        let workspace_file = workspace.join("workspace-delete.txt");
+        let temp_file = temp_root.join("temp-delete.txt");
+        let tmp_file = tmp_root.join("tmp-delete.txt");
+        let outside_file = outside_root.join("outside-delete.txt");
+        fs::write(&workspace_file, "workspace").expect("seed workspace file");
+        fs::write(&temp_file, "temp").expect("seed TEMP file");
+        fs::write(&tmp_file, "tmp").expect("seed TMP file");
+        fs::write(&outside_file, "outside").expect("seed outside file");
+
+        let script = workspace.join("delete-fixtures.cmd");
+        fs::write(
+            &script,
+            concat!(
+                "@echo off\r\n",
+                "del /f /q \"%WORKSPACE_DELETE%\"\r\n",
+                "del /f /q \"%TEMP_DELETE%\"\r\n",
+                "del /f /q \"%TMP_DELETE%\"\r\n",
+                "del /f /q \"%OUTSIDE_DELETE%\"\r\n",
+                "rmdir \"%PROTECTED_GIT_DIR%\"\r\n",
+                "exit /b 0\r\n",
+            ),
+        )
+        .expect("write delete script");
+
+        let env_map = HashMap::from([
+            ("TEMP".to_string(), temp_root.to_string_lossy().into_owned()),
+            ("TMP".to_string(), tmp_root.to_string_lossy().into_owned()),
+            (
+                "WORKSPACE_DELETE".to_string(),
+                workspace_file.to_string_lossy().into_owned(),
+            ),
+            (
+                "TEMP_DELETE".to_string(),
+                temp_file.to_string_lossy().into_owned(),
+            ),
+            (
+                "TMP_DELETE".to_string(),
+                tmp_file.to_string_lossy().into_owned(),
+            ),
+            (
+                "OUTSIDE_DELETE".to_string(),
+                outside_file.to_string_lossy().into_owned(),
+            ),
+            (
+                "PROTECTED_GIT_DIR".to_string(),
+                protected_git_dir.to_string_lossy().into_owned(),
+            ),
+        ]);
+
+        let permission_profile = PermissionProfile::workspace_write();
+        let spawned = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(workspace.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".to_string(),
+                "/d".to_string(),
+                "/c".to_string(),
+                script.display().to_string(),
+            ],
+            workspace.as_path(),
+            env_map,
+            /*timeout_ms*/ Some(5_000),
+            &[],
+            &[],
+            /*tty*/ false,
+            /*stdin_open*/ false,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("spawn legacy delete session");
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(/*secs*/ 10))
+                .await;
+        let stdout = String::from_utf8_lossy(&stdout);
+
+        assert_eq!(
+            (
+                exit_code,
+                workspace_file.exists(),
+                temp_file.exists(),
+                tmp_file.exists(),
+                fs::read_to_string(&outside_file).ok(),
+                protected_git_dir.is_dir(),
+            ),
+            (0, false, false, false, Some("outside".to_string()), true),
+            "stdout={stdout:?}\n{}",
+            sandbox_log(codex_home.path())
+        );
+    });
+}
+
+#[test]
+fn legacy_capture_cancellation_terminates_descendants_without_timeout() {
+    let Some(pwsh) = pwsh_path() else {
+        eprintln!("skipping cancellation regression test: PowerShell 7 is not installed");
+        return;
+    };
+    let _guard = legacy_process_test_guard();
+    let cwd = sandbox_cwd();
+    let codex_home = sandbox_home("legacy-capture-cancel");
+    let descendant_marker = codex_home.path().join("descendant-survived");
+    let ready_marker = codex_home.path().join("descendant-started");
+    let descendant_command = format!(
+        "Set-Content -LiteralPath '{}' -Value $PID; Start-Sleep -Seconds 1; Set-Content -LiteralPath '{}' -Value survived",
+        powershell_literal(&ready_marker),
+        powershell_literal(&descendant_marker),
+    );
+    let parent_command = start_powershell_child(
+        &pwsh,
+        codex_home.path(),
+        &descendant_command,
+        "Start-Sleep -Seconds 30",
+    );
+    let descendant_process = Arc::new(Mutex::new(None));
+    let descendant_process_for_cancellation = Arc::clone(&descendant_process);
+    let cancellation = WindowsSandboxCancellationToken::new(move || {
+        let Ok(pid) = fs::read_to_string(&ready_marker).and_then(|pid| {
+            pid.trim()
+                .parse()
+                .map_err(|err| std::io::Error::other(format!("invalid descendant pid: {err}")))
+        }) else {
+            return false;
+        };
+        let Ok(process) = open_process_for_wait(pid) else {
+            return false;
+        };
+        *descendant_process_for_cancellation
+            .lock()
+            .expect("descendant process lock poisoned") = Some(process);
+        true
+    });
+
+    let started_at = Instant::now();
+    let permission_profile = PermissionProfile::workspace_write();
+    let result = run_windows_sandbox_capture(
+        &permission_profile,
+        workspace_roots_for(cwd.as_path()).as_slice(),
+        codex_home.path(),
+        vec![
+            pwsh.display().to_string(),
+            "-NoProfile".to_string(),
+            "-Command".to_string(),
+            parent_command,
+        ],
+        cwd.as_path(),
+        HashMap::new(),
+        Some(30_000),
+        /*cancellation*/ Some(cancellation),
+        /*use_private_desktop*/ true,
+    )
+    .expect("run legacy capture powershell with cancellation");
+
+    assert!(
+        started_at.elapsed() < Duration::from_secs(10),
+        "cancellation should end capture before the timeout"
+    );
+    assert!(
+        !result.timed_out,
+        "cancellation should not be reported as a timeout"
+    );
+    assert_ne!(result.exit_code, 0);
+    let descendant_process = descendant_process
+        .lock()
+        .expect("descendant process lock poisoned")
+        .take()
+        .expect("cancellation did not capture descendant process");
+    wait_for_process_exit(&descendant_process, Duration::from_secs(10))
+        .expect("sandbox descendant did not exit after cancellation");
+    assert!(
+        !descendant_marker.exists(),
+        "sandbox descendant survived cancellation"
+    );
+}
+
+#[derive(Clone, Copy, Debug)]
+enum LegacyTtyDescendantLifecycle {
+    Terminate,
+    Preserve,
+}
+
+async fn assert_legacy_tty_descendant_lifecycle(
+    pwsh: &Path,
+    lifecycle: LegacyTtyDescendantLifecycle,
+) {
+    let cwd = sandbox_cwd();
+    let codex_home = sandbox_home(match lifecycle {
+        LegacyTtyDescendantLifecycle::Terminate => "legacy-tty-descendant-terminate",
+        LegacyTtyDescendantLifecycle::Preserve => "legacy-tty-descendant-preserve",
+    });
+    let ready_marker = codex_home.path().join("descendant-started");
+    let release_marker = codex_home.path().join("release-descendant");
+    let survival_marker = codex_home.path().join("descendant-survived");
+    let child_tail = match lifecycle {
+        LegacyTtyDescendantLifecycle::Terminate => "Start-Sleep -Seconds 30".to_string(),
+        LegacyTtyDescendantLifecycle::Preserve => format!(
+            "$deadline=(Get-Date).AddSeconds(30); while (-not (Test-Path -LiteralPath '{}')) {{ if ((Get-Date) -ge $deadline) {{ exit 3 }}; Start-Sleep -Milliseconds 25 }}; Set-Content -LiteralPath '{}' -Value survived",
+            powershell_literal(&release_marker),
+            powershell_literal(&survival_marker),
+        ),
+    };
+    let child_command = format!(
+        "Set-Content -LiteralPath '{}' -Value $PID; {child_tail}",
+        powershell_literal(&ready_marker),
+    );
+    let parent_tail = match lifecycle {
+        LegacyTtyDescendantLifecycle::Terminate => "Start-Sleep -Seconds 30".to_string(),
+        LegacyTtyDescendantLifecycle::Preserve => format!(
+            "while (-not (Test-Path -LiteralPath '{}')) {{ Start-Sleep -Milliseconds 25 }}",
+            powershell_literal(&ready_marker),
+        ),
+    };
+    let parent_command =
+        start_powershell_child(pwsh, codex_home.path(), &child_command, &parent_tail);
+    let permission_profile = PermissionProfile::workspace_write();
+    let spawned = spawn_windows_sandbox_session_legacy(
+        &permission_profile,
+        workspace_roots_for(cwd.as_path()).as_slice(),
+        codex_home.path(),
+        vec![
+            pwsh.display().to_string(),
+            "-NoProfile".to_string(),
+            "-Command".to_string(),
+            parent_command,
+        ],
+        cwd.as_path(),
+        HashMap::new(),
+        Some(30_000),
+        &[],
+        &[],
+        /*tty*/ true,
+        /*stdin_open*/ false,
+        /*use_private_desktop*/ true,
+    )
+    .await
+    .expect("spawn legacy sandbox ConPTY lifecycle test");
+    assert!(
+        wait_for_path(&ready_marker, Duration::from_secs(10)),
+        "{lifecycle:?} descendant did not start"
+    );
+    let descendant_pid = fs::read_to_string(&ready_marker)
+        .expect("read descendant pid")
+        .trim()
+        .parse()
+        .expect("parse descendant pid");
+    let descendant_process = open_process_for_wait(descendant_pid);
+
+    if matches!(lifecycle, LegacyTtyDescendantLifecycle::Terminate) {
+        spawned.session.request_terminate();
+    }
+    let (_, exit_code) =
+        collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(15)).await;
+    if matches!(lifecycle, LegacyTtyDescendantLifecycle::Preserve) {
+        fs::write(&release_marker, "release").expect("release preserved descendant");
+    }
+    let descendant_process = descendant_process.expect("open sandbox ConPTY descendant");
+
+    match lifecycle {
+        LegacyTtyDescendantLifecycle::Terminate => assert_ne!(exit_code, 0),
+        LegacyTtyDescendantLifecycle::Preserve => {
+            assert_eq!(exit_code, 0);
+            assert!(
+                wait_for_path(&survival_marker, Duration::from_secs(10)),
+                "sandbox ConPTY descendant did not survive normal exit"
+            );
+        }
+    }
+    wait_for_process_exit(&descendant_process, Duration::from_secs(10))
+        .expect("sandbox ConPTY descendant did not exit");
+}
+
+#[test]
+fn legacy_tty_job_terminates_and_preserves_descendants() {
+    let Some(pwsh) = pwsh_path() else {
+        eprintln!("skipping sandbox ConPTY lifecycle test: PowerShell 7 is not installed");
+        return;
+    };
+    let _guard = legacy_process_test_guard();
+    current_thread_runtime().block_on(async move {
+        assert_legacy_tty_descendant_lifecycle(&pwsh, LegacyTtyDescendantLifecycle::Terminate)
+            .await;
+        assert_legacy_tty_descendant_lifecycle(&pwsh, LegacyTtyDescendantLifecycle::Preserve).await;
+    });
+}
+
+#[test]
+fn legacy_tty_powershell_emits_output_and_accepts_input() {
+    let Some(pwsh) = pwsh_path() else {
+        return;
+    };
+    let _guard = legacy_process_test_guard();
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("legacy-tty-pwsh");
+        println!("tty pwsh codex_home={}", codex_home.path().display());
+        let permission_profile = PermissionProfile::workspace_write();
+        let spawned = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                pwsh.display().to_string(),
+                "-NoLogo".to_string(),
+                "-NoProfile".to_string(),
+                "-NoExit".to_string(),
+                "-Command".to_string(),
+                "$PID; Write-Output ready".to_string(),
+            ],
+            cwd.as_path(),
+            HashMap::new(),
+            Some(10_000),
+            &[],
+            &[],
+            /*tty*/ true,
+            /*stdin_open*/ true,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("spawn legacy tty powershell session");
+        println!("tty pwsh spawn returned");
+
+        let writer = spawned.session.writer_sender();
+        writer
+            .send(b"Write-Output second\n".to_vec())
+            .await
+            .expect("send second command");
+        writer
+            .send(b"exit\n".to_vec())
+            .await
+            .expect("send exit command");
+        spawned.session.close_stdin();
+
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(15)).await;
+        let stdout = String::from_utf8_lossy(&stdout);
+        assert_eq!(exit_code, 0, "stdout={stdout:?}");
+        assert!(stdout.contains("ready"), "stdout={stdout:?}");
+        assert!(stdout.contains("second"), "stdout={stdout:?}");
+    });
+}
+
+#[test]
+#[ignore = "TODO: legacy ConPTY cmd.exe exits with STATUS_DLL_INIT_FAILED in CI"]
+fn legacy_tty_cmd_emits_output_and_accepts_input() {
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("legacy-tty-cmd");
+        println!("tty cmd codex_home={}", codex_home.path().display());
+        let permission_profile = PermissionProfile::workspace_write();
+        let spawned = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".to_string(),
+                "/K".to_string(),
+                "echo ready".to_string(),
+            ],
+            cwd.as_path(),
+            HashMap::new(),
+            Some(10_000),
+            &[],
+            &[],
+            /*tty*/ true,
+            /*stdin_open*/ true,
+            /*use_private_desktop*/ true,
+        )
+        .await
+        .expect("spawn legacy tty cmd session");
+        println!("tty cmd spawn returned");
+
+        let writer = spawned.session.writer_sender();
+        writer
+            .send(b"echo second\n".to_vec())
+            .await
+            .expect("send second command");
+        writer
+            .send(b"exit\n".to_vec())
+            .await
+            .expect("send exit command");
+        spawned.session.close_stdin();
+
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(15)).await;
+        let stdout = String::from_utf8_lossy(&stdout);
+        assert_eq!(exit_code, 0, "stdout={stdout:?}");
+        assert!(stdout.contains("ready"), "stdout={stdout:?}");
+        assert!(stdout.contains("second"), "stdout={stdout:?}");
+    });
+}
+
+#[test]
+#[ignore = "TODO: legacy ConPTY cmd.exe exits with STATUS_DLL_INIT_FAILED in CI"]
+fn legacy_tty_cmd_default_desktop_emits_output_and_accepts_input() {
+    let runtime = current_thread_runtime();
+    runtime.block_on(async move {
+        let cwd = sandbox_cwd();
+        let codex_home = sandbox_home("legacy-tty-cmd-default-desktop");
+        println!(
+            "tty cmd default desktop codex_home={}",
+            codex_home.path().display()
+        );
+        let permission_profile = PermissionProfile::workspace_write();
+        let spawned = spawn_windows_sandbox_session_legacy(
+            &permission_profile,
+            workspace_roots_for(cwd.as_path()).as_slice(),
+            codex_home.path(),
+            vec![
+                "C:\\Windows\\System32\\cmd.exe".to_string(),
+                "/K".to_string(),
+                "echo ready".to_string(),
+            ],
+            cwd.as_path(),
+            HashMap::new(),
+            Some(10_000),
+            &[],
+            &[],
+            /*tty*/ true,
+            /*stdin_open*/ true,
+            /*use_private_desktop*/ false,
+        )
+        .await
+        .expect("spawn legacy tty cmd session");
+        println!("tty cmd default desktop spawn returned");
+
+        let writer = spawned.session.writer_sender();
+        writer
+            .send(b"echo second\n".to_vec())
+            .await
+            .expect("send second command");
+        writer
+            .send(b"exit\n".to_vec())
+            .await
+            .expect("send exit command");
+        spawned.session.close_stdin();
+
+        let (stdout, exit_code) =
+            collect_stdout_and_exit(spawned, codex_home.path(), Duration::from_secs(15)).await;
+        let stdout = String::from_utf8_lossy(&stdout);
+        assert_eq!(exit_code, 0, "stdout={stdout:?}");
+        assert!(stdout.contains("ready"), "stdout={stdout:?}");
+        assert!(stdout.contains("second"), "stdout={stdout:?}");
+    });
+}
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e08b62358dfce3c601ef439f1cb998360aa2a8f5
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows.rs
@@ -0,0 +1,177 @@
+//! Stops sandbox work under the setup lock before removing its resources and protections.
+
+use std::os::windows::io::BorrowedHandle;
+use std::path::Path;
+
+use anyhow::Result;
+use anyhow::anyhow;
+
+use crate::setup::OFFLINE_USERNAME;
+use crate::setup::ONLINE_USERNAME;
+
+mod firewall;
+mod principals;
+mod processes;
+mod retained_logons;
+
+/// Removes sandbox resources created for one authenticated packaged installation.
+/// Keep a supplied home and its ancestors pinned until `clean_up_desktop` starts.
+/// That callback removes user-owned desktop files while the sandbox accounts remain disabled.
+/// `report` must remain usable after the home and its log files have been removed.
+pub fn clean_up_packaged_windows_sandbox(
+    codex_home: Option<&Path>,
+    report: impl Fn(&str),
+    clean_up_desktop: impl FnOnce() -> Result<()>,
+) -> Result<()> {
+    prepare_packaged_windows_sandbox_cleanup()?.finish(codex_home, report, clean_up_desktop)
+}
+
+/// Holds the setup lock after sandbox accounts are disabled, their processes
+/// have exited, and all logon tokens except explicitly retained private cleanup
+/// tokens have been released.
+///
+/// Keep this guard on the thread that acquired the setup lock. Callers must not
+/// re-enable the accounts or create new sandbox logons before `finish`.
+///
+/// Dropping the guard only releases the lock. It does not re-enable accounts,
+/// remove protections, or undo work performed between the two phases.
+#[must_use = "finish cleanup or leave the sandbox accounts disabled with their protections intact"]
+pub struct PreparedWindowsSandboxCleanup {
+    _setup_lock: crate::setup_mutex::SandboxSetupLock,
+    users: principals::DisabledSandboxUsers,
+    _retained_logons: retained_logons::RetainedLogons,
+}
+
+/// Disables sandbox accounts and waits for their processes and logon tokens to exit.
+///
+/// No resources or protections are removed here. On failure, restoration of the
+/// original account flags is attempted before the setup lock is released; any
+/// restoration failure is included in the returned error.
+pub fn prepare_packaged_windows_sandbox_cleanup() -> Result<PreparedWindowsSandboxCleanup> {
+    prepare_packaged_windows_sandbox_cleanup_with_retained_tokens(&[])
+}
+
+/// Retains only the trusted runtime finalizer's login tokens while stopping sandbox work.
+/// These must be fresh, private logins used only by that SYSTEM cleanup process, never
+/// runner tokens or logins shared with sandbox commands. Ordinary processes are still stopped.
+/// The returned guard pins their identities until native cleanup finishes.
+pub fn prepare_packaged_windows_sandbox_cleanup_with_retained_tokens(
+    tokens: &[BorrowedHandle<'_>],
+) -> Result<PreparedWindowsSandboxCleanup> {
+    let setup_lock = crate::setup_mutex::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+    let mut errors = Vec::new();
+    let mut users = principals::DisabledSandboxUsers::default();
+    let mut retained = retained_logons::RetainedLogons::default();
+    if let Err(error) = users.disable().and_then(|()| {
+        retained = retained_logons::RetainedLogons::capture(tokens, &users)?;
+        processes::stop(&users, &retained)
+    }) {
+        errors.push(format!("{error:#}"));
+        // No network protections have been removed, so failed preparation can restore these flags.
+        if let Err(error) = users.restore() {
+            errors.push(format!("{error:#}"));
+        }
+        return Err(anyhow!(errors.join("; ")));
+    }
+
+    Ok(PreparedWindowsSandboxCleanup {
+        _setup_lock: setup_lock,
+        users,
+        _retained_logons: retained,
+    })
+}
+
+impl PreparedWindowsSandboxCleanup {
+    /// Removes resources while retaining the setup lock and disabled accounts.
+    ///
+    /// Keep a supplied home and its ancestors pinned until `clean_up_desktop`
+    /// starts. Independent cleanup steps continue after an error, as in
+    /// `clean_up_packaged_windows_sandbox`. Retrying keeps the original account
+    /// identities; it must not adopt replacement accounts created between attempts.
+    /// `report` records each cleanup outcome without relying on files in the home.
+    pub fn finish(
+        &self,
+        codex_home: Option<&Path>,
+        report: impl Fn(&str),
+        clean_up_desktop: impl FnOnce() -> Result<()>,
+    ) -> Result<()> {
+        self.users.validate_current()?;
+        let mut errors = Vec::new();
+
+        if let Some(codex_home) = codex_home {
+            if let Err(error) = crate::logging::release_setup_log() {
+                errors.push(format!("release setup log: {error:#}"));
+            }
+            for (directory, path) in [
+                (".sandbox", crate::setup::sandbox_dir(codex_home)),
+                (
+                    ".sandbox-secrets",
+                    crate::setup::sandbox_secrets_dir(codex_home),
+                ),
+                (".sandbox-bin", crate::setup::sandbox_bin_dir(codex_home)),
+            ] {
+                match std::fs::remove_dir_all(path) {
+                    Ok(()) => report(&format!("removed {directory}")),
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                        report(&format!("skipping {directory}: not found"));
+                    }
+                    Err(error) => {
+                        let message = format!("remove {directory}: failed, {error}");
+                        report(&message);
+                        errors.push(message);
+                    }
+                }
+            }
+        } else {
+            report("skipping sandbox directories: no pinned home");
+        }
+
+        if let Err(error) = clean_up_desktop() {
+            errors.push(format!("{error:#}"));
+        }
+
+        for (operation, result) in [
+            ("remove WFP filters", crate::wfp::remove_wfp_filters()),
+            ("remove firewall rules", firewall::cleanup_firewall_rules()),
+            (
+                "remove hidden-user entries",
+                crate::hide_users::unhide_sandbox_users(&[OFFLINE_USERNAME, ONLINE_USERNAME]),
+            ),
+        ] {
+            match result {
+                Ok(()) => report(&format!("{operation}: completed")),
+                Err(error) => {
+                    let message = format!("{operation}: failed, {error:#}");
+                    report(&message);
+                    errors.push(message);
+                }
+            }
+        }
+        if let Err(error) = self.users.remove_users(&self._retained_logons, &report) {
+            errors.push(format!("{error:#}"));
+        }
+        // Retry home permission cleanup with the same group; retained runtime users
+        // and their group are removed by the finalizer after their profiles unload.
+        if errors.is_empty()
+            && !self
+                .users
+                .sids()
+                .any(|sid| self._retained_logons.contains_sid(sid))
+        {
+            match principals::remove_sandbox_principal("CodexSandboxUsers") {
+                Ok(()) => report("remove sandbox group: completed"),
+                Err(error) => {
+                    report(&format!("remove sandbox group: failed, {error:#}"));
+                    errors.push(format!("{error:#}"));
+                }
+            }
+        } else {
+            report("retaining sandbox group until cleanup finishes");
+        }
+        if errors.is_empty() {
+            Ok(())
+        } else {
+            Err(anyhow!(errors.join("; ")))
+        }
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows/firewall.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows/firewall.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0e5c98d376047f458f02b8656993d12fc0d527ef
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows/firewall.rs
@@ -0,0 +1,35 @@
+//! Removes known sandbox firewall rules while preserving unrelated rules.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use windows::Win32::NetworkManagement::WindowsFirewall::INetFwPolicy2;
+use windows::Win32::NetworkManagement::WindowsFirewall::NetFwPolicy2;
+use windows::Win32::System::Com::CLSCTX_INPROC_SERVER;
+use windows::Win32::System::Com::CoCreateInstance;
+use windows::core::BSTR;
+
+pub(super) fn cleanup_firewall_rules() -> Result<()> {
+    let policy: INetFwPolicy2 = unsafe {
+        CoCreateInstance(&NetFwPolicy2, /*punkouter*/ None, CLSCTX_INPROC_SERVER)
+            .context("access firewall policy for sandbox uninstall")?
+    };
+    let rules = unsafe { policy.Rules() }.context("access sandbox firewall rules")?;
+    let mut errors = Vec::new();
+    for name in [
+        "codex_sandbox_offline_block_outbound",
+        "codex_sandbox_offline_block_inbound",
+        "codex_sandbox_offline_block_loopback_tcp",
+        "codex_sandbox_offline_block_loopback_udp",
+        "codex_sandbox_offline_allow_loopback_proxy",
+    ] {
+        if let Err(error) = unsafe { rules.Remove(&BSTR::from(name)) } {
+            errors.push(format!("remove sandbox firewall rule {name}: {error}"));
+        }
+    }
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(anyhow!(errors.join("; ")))
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows/principals.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows/principals.rs
new file mode 100644
index 0000000000000000000000000000000000000000..ef79a21980a62529f82e0b6f4105d61289ab910d
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows/principals.rs
@@ -0,0 +1,185 @@
+//! Disables sandbox accounts for cleanup and removes their profiles and principals.
+//! Callers must restore original flags if preparation for cleanup fails.
+
+use std::ptr::null;
+
+use anyhow::Result;
+use anyhow::bail;
+use anyhow::ensure;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::NetworkManagement::NetManagement as network;
+use windows_sys::Win32::System::Registry as registry;
+use windows_sys::Win32::UI::Shell::DeleteProfileW;
+
+use crate::setup::OFFLINE_USERNAME;
+use crate::setup::ONLINE_USERNAME;
+use crate::winutil::local_user_flags;
+use crate::winutil::resolve_sid;
+use crate::winutil::set_local_user_flags;
+use crate::winutil::string_from_sid_bytes;
+use crate::winutil::to_wide;
+
+use super::retained_logons::RetainedLogons;
+
+#[derive(Default)]
+pub(super) struct DisabledSandboxUsers {
+    users: Vec<SandboxUser>,
+}
+
+struct SandboxUser {
+    name: &'static str,
+    original_flags: u32,
+    sid: Vec<u8>,
+}
+
+impl DisabledSandboxUsers {
+    pub(super) fn disable(&mut self) -> Result<()> {
+        for name in [OFFLINE_USERNAME, ONLINE_USERNAME] {
+            let Some(original_flags) = local_user_flags(name)? else {
+                continue;
+            };
+            let sid = resolve_sid(name)?;
+
+            self.users.push(SandboxUser {
+                name,
+                original_flags,
+                sid,
+            });
+            set_local_user_flags(name, original_flags | network::UF_ACCOUNTDISABLE)?;
+        }
+        Ok(())
+    }
+
+    pub(super) fn sids(&self) -> impl Iterator<Item = &[u8]> {
+        self.users.iter().map(|user| user.sid.as_slice())
+    }
+
+    pub(super) fn validate_current(&self) -> Result<()> {
+        for name in [OFFLINE_USERNAME, ONLINE_USERNAME] {
+            let Some(flags) = local_user_flags(name)? else {
+                continue;
+            };
+            let captured = self.users.iter().find(|user| user.name == name);
+            ensure!(
+                captured.is_some_and(|user| resolve_sid(name).is_ok_and(|sid| sid == user.sid))
+                    && flags & network::UF_ACCOUNTDISABLE != 0,
+                "sandbox account changed after being disabled: {name}"
+            );
+        }
+        Ok(())
+    }
+
+    pub(super) fn restore(&self) -> Result<()> {
+        let mut errors = Vec::new();
+        for user in &self.users {
+            if let Err(error) = set_local_user_flags(user.name, user.original_flags)
+                && error
+                    .downcast_ref::<std::io::Error>()
+                    .and_then(std::io::Error::raw_os_error)
+                    != Some(network::NERR_UserNotFound as i32)
+            {
+                errors.push(format!("{error:#}"));
+            }
+        }
+        if !errors.is_empty() {
+            bail!("{}", errors.join("; "));
+        }
+        Ok(())
+    }
+
+    pub(super) fn remove_users(
+        &self,
+        retained: &RetainedLogons,
+        report: impl Fn(&str),
+    ) -> Result<()> {
+        let mut errors = Vec::new();
+        for user in &self.users {
+            if retained.contains_sid(&user.sid) {
+                report(&format!(
+                    "deferring {} profile and account to runtime cleanup",
+                    user.name
+                ));
+                continue;
+            }
+            match user.remove() {
+                Ok(()) => report(&format!("removed {} profile and account", user.name)),
+                Err(error) => {
+                    report(&format!(
+                        "remove {} profile and account: failed, {error:#}",
+                        user.name
+                    ));
+                    errors.push(format!("{error:#}"));
+                }
+            }
+        }
+        ensure!(errors.is_empty(), "{}", errors.join("; "));
+        Ok(())
+    }
+}
+
+impl SandboxUser {
+    fn remove(&self) -> Result<()> {
+        let Self { name, sid, .. } = self;
+        let sid = string_from_sid_bytes(sid).map_err(anyhow::Error::msg)?;
+        let profile_key = to_wide(format!(
+            r"SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\{sid}"
+        ));
+        let mut key = 0;
+        let status = unsafe {
+            registry::RegOpenKeyExW(
+                registry::HKEY_LOCAL_MACHINE,
+                profile_key.as_ptr(),
+                /*uloptions*/ 0,
+                registry::KEY_READ | registry::KEY_WOW64_64KEY,
+                &mut key,
+            )
+        };
+        match status {
+            ERROR_SUCCESS => {
+                unsafe { registry::RegCloseKey(key) };
+                // Keep the account's SID available for retry if its profile is still loaded.
+                if unsafe { DeleteProfileW(to_wide(sid).as_ptr(), null(), null()) } == 0 {
+                    bail!(
+                        "remove sandbox profile for {name}: {}",
+                        std::io::Error::last_os_error()
+                    );
+                }
+            }
+            ERROR_FILE_NOT_FOUND => {}
+            status => bail!("open sandbox profile for {name}: {status}"),
+        }
+        remove_sandbox_principal(name)
+    }
+}
+
+#[cfg(test)]
+impl DisabledSandboxUsers {
+    // In-memory admission fixture only; this does not resolve or change a local account.
+    pub(super) fn for_token_test(sid: Vec<u8>) -> Self {
+        Self {
+            users: vec![SandboxUser {
+                name: OFFLINE_USERNAME,
+                original_flags: network::UF_ACCOUNTDISABLE,
+                sid,
+            }],
+        }
+    }
+}
+
+pub(super) fn remove_sandbox_principal(name: &str) -> Result<()> {
+    let name_wide = to_wide(name);
+    let status = if name == "CodexSandboxUsers" {
+        unsafe { network::NetLocalGroupDel(null(), name_wide.as_ptr()) }
+    } else {
+        unsafe { network::NetUserDel(null(), name_wide.as_ptr()) }
+    };
+    match status {
+        network::NERR_Success | network::NERR_GroupNotFound | network::NERR_UserNotFound => Ok(()),
+        status => bail!("remove local sandbox principal {name}: {status}"),
+    }
+}
+
+#[cfg(test)]
+#[path = "principals_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows/principals_tests.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows/principals_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4e8380d7f5ec9a8051205d8ed0ce2b8a9c19ab95
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows/principals_tests.rs
@@ -0,0 +1,218 @@
+//! Exercises profile deletion and its retry boundary with one disposable local user.
+
+use std::io;
+use std::os::windows::ffi::OsStringExt;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::PathBuf;
+use std::ptr::null;
+use std::ptr::null_mut;
+use std::time::Duration;
+use std::time::Instant;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use pretty_assertions::assert_eq;
+use rand::RngCore;
+use windows_sys::Win32::Foundation::ERROR_ACCESS_DENIED;
+use windows_sys::Win32::Foundation::ERROR_FILE_NOT_FOUND;
+use windows_sys::Win32::Foundation::ERROR_SUCCESS;
+use windows_sys::Win32::Foundation::WAIT_OBJECT_0;
+use windows_sys::Win32::NetworkManagement::NetManagement as network;
+use windows_sys::Win32::System::Registry as registry;
+use windows_sys::Win32::System::Threading as threading;
+
+use super::SandboxUser;
+use crate::winutil::local_user_flags;
+use crate::winutil::resolve_sid;
+use crate::winutil::set_local_user_flags;
+use crate::winutil::string_from_sid_bytes;
+use crate::winutil::to_wide;
+
+struct ProfileFixture {
+    user: SandboxUser,
+    process: Option<OwnedHandle>,
+}
+
+impl ProfileFixture {
+    fn stop(&mut self) -> Result<()> {
+        if let Some(process) = self.process.take() {
+            let handle = process.as_raw_handle() as _;
+            unsafe {
+                threading::TerminateProcess(handle, /*uexitcode*/ 0)
+            };
+            ensure!(
+                unsafe {
+                    threading::WaitForSingleObject(handle, /*dwmilliseconds*/ 10_000)
+                } == WAIT_OBJECT_0,
+                "owned profile fixture did not exit"
+            );
+            drop(process);
+            // User Profile Service unloads the hive after the last owned process exits.
+            let sid = string_from_sid_bytes(&self.user.sid).map_err(anyhow::Error::msg)?;
+            let deadline = Instant::now() + Duration::from_secs(10);
+            loop {
+                let mut key = 0;
+                let status = unsafe {
+                    registry::RegOpenKeyExW(
+                        registry::HKEY_USERS,
+                        to_wide(&sid).as_ptr(),
+                        /*uloptions*/ 0,
+                        registry::KEY_READ,
+                        &mut key,
+                    )
+                };
+                if status == ERROR_FILE_NOT_FOUND {
+                    break;
+                }
+                ensure!(status == ERROR_SUCCESS, "read owned profile hive: {status}");
+                unsafe { registry::RegCloseKey(key) };
+                ensure!(Instant::now() < deadline, "owned profile did not unload");
+                std::thread::sleep(Duration::from_millis(50));
+            }
+        }
+        Ok(())
+    }
+}
+
+impl Drop for ProfileFixture {
+    fn drop(&mut self) {
+        let _ = self.stop();
+        let result = if self.user.sid.is_empty() {
+            super::remove_sandbox_principal(self.user.name)
+        } else {
+            self.user.remove()
+        };
+        if let Err(error) = result {
+            eprintln!("unable to clean up owned profile fixture: {error:#}");
+        }
+    }
+}
+
+#[test]
+fn profile_cleanup_preserves_account_until_profile_can_be_deleted() -> Result<()> {
+    // Production names are static. This one unique name lives for this test process only.
+    let name: &'static str =
+        Box::leak(format!("CodexPrf{:08x}", rand::rngs::OsRng.next_u32()).into_boxed_str());
+    let username = to_wide(name);
+    let password = to_wide(format!("Cdx!a0{:016x}", rand::rngs::OsRng.next_u64()));
+    let user_info = network::USER_INFO_1 {
+        usri1_name: username.as_ptr().cast_mut(),
+        usri1_password: password.as_ptr().cast_mut(),
+        usri1_priv: network::USER_PRIV_USER,
+        usri1_flags: network::UF_NORMAL_ACCOUNT
+            | network::UF_SCRIPT
+            | network::UF_DONT_EXPIRE_PASSWD,
+        ..unsafe { std::mem::zeroed() }
+    };
+    let status = unsafe {
+        network::NetUserAdd(
+            null(),
+            /*level*/ 1,
+            (&raw const user_info).cast(),
+            null_mut(),
+        )
+    };
+    if status == ERROR_ACCESS_DENIED {
+        eprintln!(
+            "skipping native profile cleanup test: creating its disposable user requires elevation"
+        );
+        return Ok(());
+    }
+    ensure!(
+        status == network::NERR_Success,
+        "create owned profile fixture: {status}"
+    );
+    let mut fixture = ProfileFixture {
+        user: SandboxUser {
+            name,
+            original_flags: user_info.usri1_flags,
+            sid: Vec::new(),
+        },
+        process: None,
+    };
+    fixture.user.sid = resolve_sid(name)?;
+    let sid = string_from_sid_bytes(&fixture.user.sid).map_err(anyhow::Error::msg)?;
+    let profile_key = to_wide(format!(
+        r"SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\{sid}"
+    ));
+    let system_root = std::env::var_os("SystemRoot").context("SystemRoot is missing")?;
+    let executable =
+        PathBuf::from(&system_root).join(r"System32\WindowsPowerShell\v1.0\powershell.exe");
+    let executable = to_wide(executable);
+    let mut command =
+        to_wide("powershell.exe -NoProfile -NonInteractive -Command Start-Sleep -Seconds 600");
+    let mut startup: threading::STARTUPINFOW = unsafe { std::mem::zeroed() };
+    startup.cb = std::mem::size_of_val(&startup) as u32;
+    let mut process: threading::PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
+    let created = unsafe {
+        threading::CreateProcessWithLogonW(
+            username.as_ptr(),
+            to_wide(".").as_ptr(),
+            password.as_ptr(),
+            threading::LOGON_WITH_PROFILE,
+            executable.as_ptr(),
+            command.as_mut_ptr(),
+            threading::CREATE_NO_WINDOW,
+            null(),
+            to_wide(&system_root).as_ptr(),
+            &startup,
+            &mut process,
+        )
+    };
+    ensure!(
+        created != 0,
+        "start owned profile fixture: {}",
+        io::Error::last_os_error()
+    );
+    fixture.process = Some(unsafe { OwnedHandle::from_raw_handle(process.hProcess as _) });
+    drop(unsafe { OwnedHandle::from_raw_handle(process.hThread as _) });
+    let mut path = [0u16; 32768];
+    let mut length = std::mem::size_of_val(&path) as u32;
+    let status = unsafe {
+        registry::RegGetValueW(
+            registry::HKEY_LOCAL_MACHINE,
+            profile_key.as_ptr(),
+            to_wide("ProfileImagePath").as_ptr(),
+            registry::RRF_RT_REG_SZ | registry::RRF_RT_REG_EXPAND_SZ,
+            null_mut(),
+            path.as_mut_ptr().cast(),
+            &mut length,
+        )
+    };
+    assert_eq!(status, ERROR_SUCCESS);
+    let path = PathBuf::from(std::ffi::OsString::from_wide(
+        &path[..length as usize / 2 - 1],
+    ));
+    assert!(path.is_dir());
+    set_local_user_flags(name, user_info.usri1_flags | network::UF_ACCOUNTDISABLE)?;
+    assert!(
+        fixture.user.remove().is_err(),
+        "loaded profile must block deletion"
+    );
+    assert_eq!(resolve_sid(name)?, fixture.user.sid);
+    assert!(path.is_dir());
+
+    fixture.stop()?;
+    fixture.user.remove()?;
+    assert_eq!(local_user_flags(name)?, None);
+    assert!(!path.exists());
+    let mut key = 0;
+    let status = unsafe {
+        registry::RegOpenKeyExW(
+            registry::HKEY_LOCAL_MACHINE,
+            profile_key.as_ptr(),
+            /*uloptions*/ 0,
+            registry::KEY_READ,
+            &mut key,
+        )
+    };
+    if status == ERROR_SUCCESS {
+        unsafe { registry::RegCloseKey(key) };
+    }
+    assert_eq!(status, ERROR_FILE_NOT_FOUND);
+    fixture.user.remove()?;
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows/processes.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows/processes.rs
new file mode 100644
index 0000000000000000000000000000000000000000..84752b20303a5d001bc8a30cdb97105525eb5cc1
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows/processes.rs
@@ -0,0 +1,225 @@
+//! Stops sandbox processes and drains logins except exact, pinned cleanup-owned tokens.
+
+use std::ffi::c_void;
+use std::io;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::ptr::null_mut;
+use std::time::Duration;
+use std::time::Instant;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use windows_sys::Win32::Foundation::ERROR_INVALID_PARAMETER;
+use windows_sys::Win32::Foundation::ERROR_NO_SUCH_LOGON_SESSION;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::LUID;
+use windows_sys::Win32::Foundation::STATUS_SUCCESS;
+use windows_sys::Win32::Foundation::WAIT_OBJECT_0;
+use windows_sys::Win32::Foundation::WAIT_TIMEOUT;
+use windows_sys::Win32::Security::Authentication::Identity::LsaEnumerateLogonSessions;
+use windows_sys::Win32::Security::Authentication::Identity::LsaFreeReturnBuffer;
+use windows_sys::Win32::Security::Authentication::Identity::LsaGetLogonSessionData;
+use windows_sys::Win32::Security::Authentication::Identity::LsaNtStatusToWinError;
+use windows_sys::Win32::Security::Authentication::Identity::SECURITY_LOGON_SESSION_DATA;
+use windows_sys::Win32::Security::EqualSid;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::System::RemoteDesktop::WTS_CURRENT_SERVER_HANDLE;
+use windows_sys::Win32::System::RemoteDesktop::WTS_PROCESS_INFOW;
+use windows_sys::Win32::System::RemoteDesktop::WTSEnumerateProcessesW;
+use windows_sys::Win32::System::RemoteDesktop::WTSFreeMemory;
+use windows_sys::Win32::System::Threading::OpenProcess;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+use windows_sys::Win32::System::Threading::PROCESS_QUERY_LIMITED_INFORMATION;
+use windows_sys::Win32::System::Threading::PROCESS_SYNCHRONIZE;
+use windows_sys::Win32::System::Threading::PROCESS_TERMINATE;
+use windows_sys::Win32::System::Threading::TerminateProcess;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+use super::principals::DisabledSandboxUsers;
+use super::retained_logons::RetainedLogons;
+use crate::token::get_user_sid_bytes;
+
+pub(super) fn stop(users: &DisabledSandboxUsers, retained: &RetainedLogons) -> Result<()> {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    loop {
+        let processes = sandbox_processes(users)?;
+        for process in &processes {
+            let handle = process.as_raw_handle() as HANDLE;
+            if unsafe {
+                TerminateProcess(handle, /*uexitcode*/ 1)
+            } == 0
+            {
+                let error = io::Error::last_os_error();
+                if unsafe {
+                    WaitForSingleObject(handle, /*dwmilliseconds*/ 0)
+                } != WAIT_OBJECT_0
+                {
+                    return Err(error).context("stop sandbox process before uninstall");
+                }
+            }
+        }
+        for process in &processes {
+            let remaining = deadline.saturating_duration_since(Instant::now());
+            // The five-second deadline keeps milliseconds within a DWORD.
+            match unsafe {
+                WaitForSingleObject(
+                    process.as_raw_handle() as HANDLE,
+                    remaining.as_millis() as u32,
+                )
+            } {
+                WAIT_OBJECT_0 => {}
+                WAIT_TIMEOUT => bail!("sandbox process did not exit before the uninstall deadline"),
+                _ => {
+                    return Err(io::Error::last_os_error())
+                        .context("wait for sandbox process exit");
+                }
+            }
+        }
+        drop(processes);
+
+        // A token can outlive its process or exist before a runner starts. Account disable does
+        // not revoke it, so check for remaining logins before removing protections. Only
+        // explicitly pinned, private SYSTEM-finalizer tokens may remain; no process is exempt.
+        if !has_sandbox_logon_session(users, retained)? {
+            return Ok(());
+        }
+        if Instant::now() >= deadline {
+            bail!("sandbox processes or logon tokens remain after the uninstall deadline");
+        }
+        // Repeat to catch descendants created during the previous snapshot.
+        std::thread::sleep(
+            Duration::from_millis(50).min(deadline.saturating_duration_since(Instant::now())),
+        );
+    }
+}
+
+fn sandbox_processes(users: &DisabledSandboxUsers) -> Result<Vec<OwnedHandle>> {
+    let mut process_info = null_mut();
+    let mut count = 0;
+    if unsafe {
+        WTSEnumerateProcessesW(
+            WTS_CURRENT_SERVER_HANDLE,
+            /*reserved*/ 0,
+            /*version*/ 1,
+            &mut process_info,
+            &mut count,
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error())
+            .context("enumerate sandbox processes for uninstall");
+    }
+    let process_info = ProcessList(process_info);
+    let mut handles = Vec::new();
+    if count == 0 {
+        return Ok(handles);
+    }
+    for process in unsafe { std::slice::from_raw_parts(process_info.0, count as usize) } {
+        if !is_sandbox_user(users, process.pUserSid) {
+            continue;
+        }
+        let handle = unsafe {
+            OpenProcess(
+                PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_TERMINATE | PROCESS_SYNCHRONIZE,
+                /*binherithandle*/ 0,
+                process.ProcessId,
+            )
+        };
+        if handle == 0 {
+            let error = io::Error::last_os_error();
+            if error.raw_os_error() == Some(ERROR_INVALID_PARAMETER as i32) {
+                continue;
+            }
+            return Err(error).context("open sandbox process for uninstall");
+        }
+        let handle = unsafe { OwnedHandle::from_raw_handle(handle as *mut c_void) };
+        let mut token = 0;
+        if unsafe { OpenProcessToken(handle.as_raw_handle() as HANDLE, TOKEN_QUERY, &mut token) }
+            == 0
+        {
+            let error = io::Error::last_os_error();
+            if unsafe {
+                WaitForSingleObject(handle.as_raw_handle() as HANDLE, /*dwmilliseconds*/ 0)
+            } == WAIT_OBJECT_0
+            {
+                continue;
+            }
+            return Err(error).context("identify sandbox process before uninstall");
+        }
+        let token = unsafe { OwnedHandle::from_raw_handle(token as *mut c_void) };
+        let sid = unsafe { get_user_sid_bytes(token.as_raw_handle() as HANDLE) }?;
+        // A PID can be reused after enumeration. Check the opened process before terminating it.
+        if users.sids().any(|user_sid| user_sid == sid.as_slice()) {
+            handles.push(handle);
+        }
+    }
+    Ok(handles)
+}
+
+fn has_sandbox_logon_session(
+    users: &DisabledSandboxUsers,
+    retained: &RetainedLogons,
+) -> Result<bool> {
+    let mut count = 0;
+    let mut logons = null_mut();
+    let status = unsafe { LsaEnumerateLogonSessions(&mut count, &mut logons) };
+    if status != STATUS_SUCCESS {
+        bail!("enumerate sandbox logon sessions for uninstall: {status:#x}");
+    }
+    let logons = LsaBuffer(logons.cast());
+    if count == 0 {
+        return Ok(false);
+    }
+    for logon in unsafe { std::slice::from_raw_parts(logons.0.cast::<LUID>(), count as usize) } {
+        // LocalSystem uses the reserved logon ID 0:0x3e7 and has no normal logon data.
+        if logon.LowPart == 0x3e7 && logon.HighPart == 0 {
+            continue;
+        }
+        let mut data = null_mut();
+        let status = unsafe { LsaGetLogonSessionData(logon, &mut data) };
+        if status != STATUS_SUCCESS {
+            if unsafe { LsaNtStatusToWinError(status) } == ERROR_NO_SUCH_LOGON_SESSION {
+                continue;
+            }
+            bail!("read sandbox logon session for uninstall: {status:#x}");
+        }
+        // Keep protections when LSA returns no session data.
+        if data.is_null() {
+            return Ok(true);
+        }
+        let data = LsaBuffer(data.cast());
+        let data = unsafe { &*data.0.cast::<SECURITY_LOGON_SESSION_DATA>() };
+        // LSA also lists sessions without a user SID, even before sandbox accounts exist.
+        // Only sessions identified as sandbox users are evidence of remaining sandbox tokens.
+        if is_sandbox_user(users, data.Sid) && !retained.contains(*logon) {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+fn is_sandbox_user(users: &DisabledSandboxUsers, sid: *mut c_void) -> bool {
+    !sid.is_null()
+        && users
+            .sids()
+            .any(|user_sid| unsafe { EqualSid(sid, user_sid.as_ptr() as *mut c_void) } != 0)
+}
+
+struct ProcessList(*mut WTS_PROCESS_INFOW);
+
+impl Drop for ProcessList {
+    fn drop(&mut self) {
+        unsafe { WTSFreeMemory(self.0.cast()) };
+    }
+}
+
+struct LsaBuffer(*mut c_void);
+
+impl Drop for LsaBuffer {
+    fn drop(&mut self) {
+        unsafe { LsaFreeReturnBuffer(self.0) };
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows/retained_logons.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows/retained_logons.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8df1ac694adedcd77c484dee2e90bd7b53480066
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows/retained_logons.rs
@@ -0,0 +1,81 @@
+//! Pins only cleanup-owned login sessions; every other sandbox login still blocks cleanup.
+
+use std::io;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::OwnedHandle;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::LUID;
+use windows_sys::Win32::Security::GetTokenInformation;
+use windows_sys::Win32::Security::TOKEN_STATISTICS;
+use windows_sys::Win32::Security::TokenStatistics;
+
+use super::principals::DisabledSandboxUsers;
+
+#[derive(Default)]
+pub(super) struct RetainedLogons {
+    // Keeping each token open prevents its AuthenticationId from being recycled.
+    _tokens: Vec<OwnedHandle>,
+    ids: Vec<LUID>,
+    sids: Vec<Vec<u8>>,
+}
+
+impl RetainedLogons {
+    pub(super) fn capture(
+        tokens: &[BorrowedHandle<'_>],
+        users: &DisabledSandboxUsers,
+    ) -> Result<Self> {
+        ensure!(tokens.len() <= 2, "too many retained cleanup tokens");
+        let mut retained = Self::default();
+        for token in tokens {
+            let token = token.try_clone_to_owned()?;
+            let handle = token.as_raw_handle() as HANDLE;
+            let sid = unsafe { crate::token::get_user_sid_bytes(handle) }?;
+            ensure!(
+                users.sids().any(|candidate| candidate == sid.as_slice())
+                    && !retained.sids.contains(&sid),
+                "cleanup token does not identify a distinct managed sandbox account"
+            );
+            let mut stats: TOKEN_STATISTICS = unsafe { std::mem::zeroed() };
+            let mut returned = 0;
+            if unsafe {
+                GetTokenInformation(
+                    handle,
+                    TokenStatistics,
+                    (&mut stats as *mut TOKEN_STATISTICS).cast(),
+                    std::mem::size_of::<TOKEN_STATISTICS>() as u32,
+                    &mut returned,
+                )
+            } == 0
+            {
+                return Err(io::Error::last_os_error()).context("identify retained cleanup login");
+            }
+            ensure!(
+                returned as usize == std::mem::size_of::<TOKEN_STATISTICS>(),
+                "unexpected cleanup token statistics length"
+            );
+            retained.sids.push(sid);
+            retained.ids.push(stats.AuthenticationId);
+            retained._tokens.push(token);
+        }
+        Ok(retained)
+    }
+
+    pub(super) fn contains(&self, id: LUID) -> bool {
+        self.ids
+            .iter()
+            .any(|held| held.LowPart == id.LowPart && held.HighPart == id.HighPart)
+    }
+
+    pub(super) fn contains_sid(&self, sid: &[u8]) -> bool {
+        self.sids.iter().any(|held| held == sid)
+    }
+}
+
+#[cfg(test)]
+#[path = "retained_logons_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/uninstall_windows/retained_logons_tests.rs b/codex-rs/windows-sandbox-rs/src/uninstall_windows/retained_logons_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..255c5c5747c73eb4d119b04928ddaa71291ed333
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/uninstall_windows/retained_logons_tests.rs
@@ -0,0 +1,109 @@
+//! Exercises retained-logon admission and ownership using read-only current-process tokens.
+
+use super::super::principals::DisabledSandboxUsers;
+use super::RetainedLogons;
+use crate::token::get_user_sid_bytes;
+use anyhow::Result;
+use anyhow::ensure;
+use pretty_assertions::assert_eq;
+use std::os::windows::io::AsHandle;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::FromRawHandle;
+use std::os::windows::io::OwnedHandle;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::LUID;
+use windows_sys::Win32::Security::TOKEN_QUERY;
+use windows_sys::Win32::System::Threading::GetCurrentProcess;
+use windows_sys::Win32::System::Threading::OpenProcessToken;
+
+fn current_process_token() -> Result<OwnedHandle> {
+    let mut raw = 0;
+    ensure!(
+        unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut raw) } != 0,
+        "open current-process token: {}",
+        std::io::Error::last_os_error()
+    );
+    Ok(unsafe { OwnedHandle::from_raw_handle(raw as _) })
+}
+
+#[test]
+fn matches_only_the_complete_retained_authentication_id() {
+    let retained = RetainedLogons {
+        _tokens: Vec::new(),
+        ids: vec![LUID {
+            LowPart: 17,
+            HighPart: 4,
+        }],
+        sids: Vec::new(),
+    };
+    let observed = [
+        LUID {
+            LowPart: 17,
+            HighPart: 4,
+        },
+        LUID {
+            LowPart: 18,
+            HighPart: 4,
+        },
+        LUID {
+            LowPart: 17,
+            HighPart: 5,
+        },
+        LUID {
+            LowPart: 0,
+            HighPart: 0,
+        },
+    ]
+    .map(|id| retained.contains(id));
+    assert_eq!(observed, [true, false, false, false]);
+    assert!(!RetainedLogons::default().contains(LUID {
+        LowPart: 17,
+        HighPart: 4
+    }));
+}
+
+#[test]
+fn rejects_more_than_two_tokens_before_admission() -> Result<()> {
+    let token = current_process_token()?;
+    let error = RetainedLogons::capture(&[token.as_handle(); 3], &DisabledSandboxUsers::default())
+        .err()
+        .expect("three token inputs must be rejected");
+    assert_eq!(error.to_string(), "too many retained cleanup tokens");
+    Ok(())
+}
+
+#[test]
+fn rejects_a_token_without_a_captured_managed_sid() -> Result<()> {
+    let token = current_process_token()?;
+    assert!(
+        RetainedLogons::capture(&[token.as_handle()], &DisabledSandboxUsers::default()).is_err()
+    );
+    Ok(())
+}
+
+#[test]
+fn rejects_distinct_handles_for_the_same_managed_sid() -> Result<()> {
+    let token = current_process_token()?;
+    let sid = unsafe { get_user_sid_bytes(token.as_raw_handle() as HANDLE) }?;
+    let users = DisabledSandboxUsers::for_token_test(sid);
+    let duplicate = token.as_handle().try_clone_to_owned()?;
+    RetainedLogons::capture(&[token.as_handle()], &users)?;
+    assert!(RetainedLogons::capture(&[token.as_handle(), duplicate.as_handle()], &users).is_err());
+    Ok(())
+}
+
+#[test]
+fn retained_token_remains_queryable_after_the_borrowed_handle_is_closed() -> Result<()> {
+    let (retained, expected_sid) = {
+        let token = current_process_token()?;
+        let sid = unsafe { get_user_sid_bytes(token.as_raw_handle() as HANDLE) }?;
+        let users = DisabledSandboxUsers::for_token_test(sid.clone());
+        (RetainedLogons::capture(&[token.as_handle()], &users)?, sid)
+    };
+    assert_eq!(retained._tokens.len(), 1);
+    let actual_sid = unsafe { get_user_sid_bytes(retained._tokens[0].as_raw_handle() as HANDLE) }?;
+    assert_eq!(actual_sid, expected_sid);
+    assert!(retained.contains_sid(&expected_sid));
+    assert!(!retained.contains_sid(&[]));
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-rs/src/wfp.rs b/codex-rs/windows-sandbox-rs/src/wfp.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d992bcdd931c77050de2b5b4fe04aaf00e247725
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/wfp.rs
@@ -0,0 +1,451 @@
+mod filter_specs;
+
+use crate::to_wide;
+use anyhow::Result;
+use std::ffi::OsStr;
+use std::mem::zeroed;
+use std::ptr::null;
+use std::ptr::null_mut;
+use windows_sys::Win32::Foundation::FWP_E_ALREADY_EXISTS;
+use windows_sys::Win32::Foundation::FWP_E_FILTER_NOT_FOUND;
+use windows_sys::Win32::Foundation::FWP_E_NOT_FOUND;
+use windows_sys::Win32::Foundation::FWP_E_PROVIDER_NOT_FOUND;
+use windows_sys::Win32::Foundation::FWP_E_SUBLAYER_NOT_FOUND;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_ACTION_BLOCK;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_ACTRL_MATCH_FILTER;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_BYTE_BLOB;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_CONDITION_VALUE0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_CONDITION_VALUE0_0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_EMPTY;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_MATCH_EQUAL;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_SECURITY_DESCRIPTOR_TYPE;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_UINT8;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_UINT16;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWP_VALUE0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_ACTION0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_ACTION0_0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_CONDITION_ALE_USER_ID;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_CONDITION_IP_PROTOCOL;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_CONDITION_IP_REMOTE_PORT;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_DISPLAY_DATA0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_FILTER_CONDITION0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_FILTER_FLAG_PERSISTENT;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_FILTER0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_FILTER0_0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_PROVIDER_FLAG_PERSISTENT;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_PROVIDER0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_SESSION0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_SUBLAYER_FLAG_PERSISTENT;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_SUBLAYER0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmEngineClose0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmEngineOpen0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmFilterAdd0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmFilterDeleteByKey0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmProviderAdd0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmProviderDeleteByKey0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmSubLayerAdd0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmSubLayerDeleteByKey0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmTransactionAbort0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmTransactionBegin0;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FwpmTransactionCommit0;
+use windows_sys::Win32::Security::Authorization::BuildExplicitAccessWithNameW;
+use windows_sys::Win32::Security::Authorization::BuildSecurityDescriptorW;
+use windows_sys::Win32::Security::Authorization::EXPLICIT_ACCESS_W;
+use windows_sys::Win32::Security::Authorization::GRANT_ACCESS;
+use windows_sys::Win32::Security::PSECURITY_DESCRIPTOR;
+use windows_sys::Win32::System::Rpc::RPC_C_AUTHN_DEFAULT;
+use windows_sys::Win32::System::Threading::INFINITE;
+use windows_sys::core::GUID;
+
+use filter_specs::ConditionSpec;
+use filter_specs::FILTER_SPECS;
+use filter_specs::FilterSpec;
+
+const SESSION_NAME: &str = "Codex Windows Sandbox WFP";
+const PROVIDER_NAME: &str = "Codex Windows Sandbox WFP";
+const PROVIDER_DESCRIPTION: &str = "Persistent WFP provider for Codex Windows sandbox filters";
+const SUBLAYER_NAME: &str = "Codex Windows Sandbox WFP";
+const SUBLAYER_DESCRIPTION: &str = "Persistent WFP sublayer for Codex Windows sandbox filters";
+
+// WFP identifies persistent providers, sublayers, and filters by stable GUIDs.
+// These values are Codex-owned identities; do not regenerate them unless we
+// intentionally want to orphan old objects and create a new WFP namespace.
+const PROVIDER_KEY: GUID = GUID::from_u128(0x2e31d31c_3948_4753_9117_e5d1a6496f41);
+const SUBLAYER_KEY: GUID = GUID::from_u128(0xe65054fd_4d32_4c7c_95ef_621f0cf6431a);
+
+/// Installs the persistent Codex WFP filters for `account`.
+///
+/// This is intended to run from the already-elevated setup helper. Callers
+/// may continue ordinary setup after an error, but must restore these filters
+/// before re-enabling accounts left disabled by interrupted cleanup.
+pub fn install_wfp_filters_for_account(account: &str) -> Result<usize> {
+    let engine = Engine::open(INFINITE)?;
+    let mut transaction = engine.begin_transaction()?;
+    ensure_provider(engine.handle)?;
+    ensure_sublayer(engine.handle)?;
+
+    let user_condition = UserMatchCondition::for_account(account)?;
+    let mut installed_filter_count = 0;
+    for spec in FILTER_SPECS {
+        delete_filter_if_present(engine.handle, &spec.key)?;
+        add_filter(engine.handle, spec, &user_condition)?;
+        installed_filter_count += 1;
+    }
+
+    transaction.commit()?;
+    Ok(installed_filter_count)
+}
+
+pub(crate) fn remove_wfp_filters() -> Result<()> {
+    // Leave time for other cleanup if a WFP policy writer holds the transaction lock.
+    let engine = Engine::open(/*transaction_wait_timeout_ms*/ 1_000)?;
+    let mut transaction = engine.begin_transaction()?;
+    for spec in FILTER_SPECS {
+        delete_filter_if_present(engine.handle, &spec.key)?;
+    }
+    for (result, operation, missing) in [
+        (
+            unsafe { FwpmSubLayerDeleteByKey0(engine.handle, &SUBLAYER_KEY) },
+            "FwpmSubLayerDeleteByKey0",
+            FWP_E_SUBLAYER_NOT_FOUND as u32,
+        ),
+        (
+            unsafe { FwpmProviderDeleteByKey0(engine.handle, &PROVIDER_KEY) },
+            "FwpmProviderDeleteByKey0",
+            FWP_E_PROVIDER_NOT_FOUND as u32,
+        ),
+    ] {
+        ensure_success_or(result, operation, &[missing, FWP_E_NOT_FOUND as u32])?;
+    }
+    transaction.commit()
+}
+
+/// Owns an open WFP engine handle and closes it on drop.
+struct Engine {
+    handle: HANDLE,
+}
+
+impl Engine {
+    fn open(transaction_wait_timeout_ms: u32) -> Result<Self> {
+        let session_name = to_wide(OsStr::new(SESSION_NAME));
+        let mut session: FWPM_SESSION0 = unsafe { zeroed() };
+        session.displayData = FWPM_DISPLAY_DATA0 {
+            name: session_name.as_ptr() as *mut _,
+            description: null_mut(),
+        };
+        session.txnWaitTimeoutInMSec = transaction_wait_timeout_ms;
+
+        let mut handle = HANDLE::default();
+        let result = unsafe {
+            FwpmEngineOpen0(
+                null(),
+                RPC_C_AUTHN_DEFAULT as u32,
+                null(),
+                &session,
+                &mut handle,
+            )
+        };
+        ensure_success(result, "FwpmEngineOpen0")?;
+        Ok(Self { handle })
+    }
+
+    fn begin_transaction(&self) -> Result<Transaction<'_>> {
+        let result = unsafe { FwpmTransactionBegin0(self.handle, 0) };
+        ensure_success(result, "FwpmTransactionBegin0")?;
+        Ok(Transaction {
+            engine: self,
+            committed: false,
+        })
+    }
+}
+
+impl Drop for Engine {
+    fn drop(&mut self) {
+        unsafe {
+            FwpmEngineClose0(self.handle);
+        }
+    }
+}
+
+/// Aborts an open WFP transaction unless it was explicitly committed.
+struct Transaction<'a> {
+    engine: &'a Engine,
+    committed: bool,
+}
+
+impl Transaction<'_> {
+    fn commit(&mut self) -> Result<()> {
+        let result = unsafe { FwpmTransactionCommit0(self.engine.handle) };
+        ensure_success(result, "FwpmTransactionCommit0")?;
+        self.committed = true;
+        Ok(())
+    }
+}
+
+impl Drop for Transaction<'_> {
+    fn drop(&mut self) {
+        if !self.committed {
+            unsafe {
+                FwpmTransactionAbort0(self.engine.handle);
+            }
+        }
+    }
+}
+
+/// Builds the ALE_USER_ID condition blob that scopes filters to one account.
+struct UserMatchCondition {
+    security_descriptor: PSECURITY_DESCRIPTOR,
+    blob: FWP_BYTE_BLOB,
+}
+
+impl UserMatchCondition {
+    fn for_account(account: &str) -> Result<Self> {
+        let account_w = to_wide(OsStr::new(account));
+        let mut access: EXPLICIT_ACCESS_W = unsafe { zeroed() };
+        unsafe {
+            BuildExplicitAccessWithNameW(
+                &mut access,
+                account_w.as_ptr(),
+                FWP_ACTRL_MATCH_FILTER,
+                GRANT_ACCESS,
+                0,
+            );
+        }
+
+        let mut security_descriptor: PSECURITY_DESCRIPTOR = null_mut();
+        let mut security_descriptor_len = 0;
+        let result = unsafe {
+            BuildSecurityDescriptorW(
+                null(),
+                null(),
+                1,
+                &access,
+                0,
+                null(),
+                null_mut(),
+                &mut security_descriptor_len,
+                &mut security_descriptor,
+            )
+        };
+        ensure_success(result, "BuildSecurityDescriptorW")?;
+
+        Ok(Self {
+            security_descriptor,
+            blob: FWP_BYTE_BLOB {
+                size: security_descriptor_len,
+                data: security_descriptor as *mut u8,
+            },
+        })
+    }
+}
+
+impl Drop for UserMatchCondition {
+    fn drop(&mut self) {
+        if !self.security_descriptor.is_null() {
+            unsafe {
+                LocalFree(self.security_descriptor as HLOCAL);
+            }
+        }
+    }
+}
+
+/// Ensures the persistent Codex WFP provider exists.
+fn ensure_provider(engine: HANDLE) -> Result<()> {
+    let provider_name = to_wide(OsStr::new(PROVIDER_NAME));
+    let provider_description = to_wide(OsStr::new(PROVIDER_DESCRIPTION));
+    let provider = FWPM_PROVIDER0 {
+        providerKey: PROVIDER_KEY,
+        displayData: FWPM_DISPLAY_DATA0 {
+            name: provider_name.as_ptr() as *mut _,
+            description: provider_description.as_ptr() as *mut _,
+        },
+        flags: FWPM_PROVIDER_FLAG_PERSISTENT,
+        providerData: empty_blob(),
+        serviceName: null_mut(),
+    };
+
+    let result = unsafe { FwpmProviderAdd0(engine, &provider, null_mut()) };
+    ensure_success_or(result, "FwpmProviderAdd0", &[FWP_E_ALREADY_EXISTS as u32])
+}
+
+/// Ensures the persistent Codex sublayer exists under the Codex provider.
+fn ensure_sublayer(engine: HANDLE) -> Result<()> {
+    let sublayer_name = to_wide(OsStr::new(SUBLAYER_NAME));
+    let sublayer_description = to_wide(OsStr::new(SUBLAYER_DESCRIPTION));
+    let provider_key = PROVIDER_KEY;
+    let sublayer = FWPM_SUBLAYER0 {
+        subLayerKey: SUBLAYER_KEY,
+        displayData: FWPM_DISPLAY_DATA0 {
+            name: sublayer_name.as_ptr() as *mut _,
+            description: sublayer_description.as_ptr() as *mut _,
+        },
+        flags: FWPM_SUBLAYER_FLAG_PERSISTENT,
+        providerKey: &provider_key as *const _ as *mut _,
+        providerData: empty_blob(),
+        weight: 0x8000,
+    };
+
+    let result = unsafe { FwpmSubLayerAdd0(engine, &sublayer, null_mut()) };
+    ensure_success_or(result, "FwpmSubLayerAdd0", &[FWP_E_ALREADY_EXISTS as u32])
+}
+
+/// Adds one blocking WFP filter from the static filter spec list.
+fn add_filter(
+    engine: HANDLE,
+    spec: &FilterSpec,
+    user_condition: &UserMatchCondition,
+) -> Result<()> {
+    let filter_name = to_wide(OsStr::new(spec.name));
+    let filter_description = to_wide(OsStr::new(spec.description));
+    let mut filter_conditions = build_conditions(spec.conditions, user_condition);
+    let provider_key = PROVIDER_KEY;
+    let filter = FWPM_FILTER0 {
+        filterKey: spec.key,
+        displayData: FWPM_DISPLAY_DATA0 {
+            name: filter_name.as_ptr() as *mut _,
+            description: filter_description.as_ptr() as *mut _,
+        },
+        flags: FWPM_FILTER_FLAG_PERSISTENT,
+        providerKey: &provider_key as *const _ as *mut _,
+        providerData: empty_blob(),
+        layerKey: spec.layer_key,
+        subLayerKey: SUBLAYER_KEY,
+        weight: empty_value(),
+        numFilterConditions: filter_conditions.len() as u32,
+        filterCondition: filter_conditions.as_mut_ptr(),
+        action: FWPM_ACTION0 {
+            r#type: FWP_ACTION_BLOCK,
+            Anonymous: FWPM_ACTION0_0 {
+                filterType: zero_guid(),
+            },
+        },
+        Anonymous: FWPM_FILTER0_0 { rawContext: 0 },
+        reserved: null_mut(),
+        filterId: 0,
+        effectiveWeight: empty_value(),
+    };
+
+    let mut filter_id = 0_u64;
+    let result = unsafe { FwpmFilterAdd0(engine, &filter, null_mut(), &mut filter_id) };
+    ensure_success(result, &format!("FwpmFilterAdd0({})", spec.name))
+}
+
+/// Converts our compact condition specs into WFP filter conditions.
+fn build_conditions(
+    specs: &[ConditionSpec],
+    user_condition: &UserMatchCondition,
+) -> Vec<FWPM_FILTER_CONDITION0> {
+    specs
+        .iter()
+        .map(|spec| match spec {
+            ConditionSpec::User => FWPM_FILTER_CONDITION0 {
+                fieldKey: FWPM_CONDITION_ALE_USER_ID,
+                matchType: FWP_MATCH_EQUAL,
+                conditionValue: FWP_CONDITION_VALUE0 {
+                    r#type: FWP_SECURITY_DESCRIPTOR_TYPE,
+                    Anonymous: FWP_CONDITION_VALUE0_0 {
+                        sd: &user_condition.blob as *const _ as *mut _,
+                    },
+                },
+            },
+            ConditionSpec::Protocol(protocol) => FWPM_FILTER_CONDITION0 {
+                fieldKey: FWPM_CONDITION_IP_PROTOCOL,
+                matchType: FWP_MATCH_EQUAL,
+                conditionValue: FWP_CONDITION_VALUE0 {
+                    r#type: FWP_UINT8,
+                    Anonymous: FWP_CONDITION_VALUE0_0 { uint8: *protocol },
+                },
+            },
+            ConditionSpec::RemotePort(port) => FWPM_FILTER_CONDITION0 {
+                fieldKey: FWPM_CONDITION_IP_REMOTE_PORT,
+                matchType: FWP_MATCH_EQUAL,
+                conditionValue: FWP_CONDITION_VALUE0 {
+                    r#type: FWP_UINT16,
+                    Anonymous: FWP_CONDITION_VALUE0_0 { uint16: *port },
+                },
+            },
+        })
+        .collect()
+}
+
+/// Deletes an old copy of a filter before re-adding it.
+fn delete_filter_if_present(engine: HANDLE, key: &GUID) -> Result<()> {
+    let result = unsafe { FwpmFilterDeleteByKey0(engine, key) };
+    ensure_success_or(
+        result,
+        "FwpmFilterDeleteByKey0",
+        &[FWP_E_FILTER_NOT_FOUND as u32, FWP_E_NOT_FOUND as u32],
+    )
+}
+
+fn ensure_success(result: u32, operation: &str) -> Result<()> {
+    ensure_success_or(result, operation, &[])
+}
+
+fn ensure_success_or(result: u32, operation: &str, allowed: &[u32]) -> Result<()> {
+    if result == 0 || allowed.contains(&result) {
+        Ok(())
+    } else {
+        Err(anyhow::anyhow!(
+            "{operation} failed: {}",
+            format_error_code(result)
+        ))
+    }
+}
+
+fn format_error_code(result: u32) -> String {
+    format!("0x{result:08X}")
+}
+
+fn empty_blob() -> FWP_BYTE_BLOB {
+    FWP_BYTE_BLOB {
+        size: 0,
+        data: null_mut(),
+    }
+}
+
+fn empty_value() -> FWP_VALUE0 {
+    FWP_VALUE0 {
+        r#type: FWP_EMPTY,
+        Anonymous: unsafe { zeroed() },
+    }
+}
+
+fn zero_guid() -> GUID {
+    GUID::from_u128(0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::FILTER_SPECS;
+    use pretty_assertions::assert_eq;
+    use std::collections::BTreeSet;
+
+    #[test]
+    fn filter_keys_are_unique() {
+        let keys = FILTER_SPECS
+            .iter()
+            .map(|spec| {
+                (
+                    spec.key.data1,
+                    spec.key.data2,
+                    spec.key.data3,
+                    spec.key.data4,
+                )
+            })
+            .collect::<BTreeSet<_>>();
+        assert_eq!(keys.len(), FILTER_SPECS.len());
+    }
+
+    #[test]
+    fn filter_names_are_unique() {
+        let names = FILTER_SPECS
+            .iter()
+            .map(|spec| spec.name)
+            .collect::<BTreeSet<_>>();
+        assert_eq!(names.len(), FILTER_SPECS.len());
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/wfp/filter_specs.rs b/codex-rs/windows-sandbox-rs/src/wfp/filter_specs.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d86df4ac1eff0c9cc2cc567817a9cdc8584f78cc
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/wfp/filter_specs.rs
@@ -0,0 +1,124 @@
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_LAYER_ALE_AUTH_CONNECT_V4;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_LAYER_ALE_AUTH_CONNECT_V6;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_V4;
+use windows_sys::Win32::NetworkManagement::WindowsFilteringPlatform::FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_V6;
+use windows_sys::Win32::Networking::WinSock::IPPROTO_ICMP;
+use windows_sys::Win32::Networking::WinSock::IPPROTO_ICMPV6;
+use windows_sys::core::GUID;
+
+#[derive(Clone, Copy)]
+pub(super) enum ConditionSpec {
+    User,
+    Protocol(u8),
+    RemotePort(u16),
+}
+
+#[derive(Clone, Copy)]
+pub(super) struct FilterSpec {
+    pub(super) key: GUID,
+    pub(super) name: &'static str,
+    pub(super) description: &'static str,
+    pub(super) layer_key: GUID,
+    pub(super) conditions: &'static [ConditionSpec],
+}
+
+pub(super) const FILTER_SPECS: &[FilterSpec] = &[
+    FilterSpec {
+        key: GUID::from_u128(0x9f5f3812_79f0_4fe9_9615_4c2c92d2f0ff),
+        name: "codex_wfp_icmp_connect_v4",
+        description: "Block sandbox-account ICMP connect v4",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V4,
+        conditions: &[
+            ConditionSpec::User,
+            ConditionSpec::Protocol(IPPROTO_ICMP as u8),
+        ],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0x87498484_45ab_4510_845e_ece8b791b3bc),
+        name: "codex_wfp_icmp_connect_v6",
+        description: "Block sandbox-account ICMP connect v6",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V6,
+        conditions: &[
+            ConditionSpec::User,
+            ConditionSpec::Protocol(IPPROTO_ICMPV6 as u8),
+        ],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xaf4751de_f874_4a7b_a34d_f0d0f22d1d9b),
+        name: "codex_wfp_icmp_assign_v4",
+        description: "Block sandbox-account ICMP resource assignment v4",
+        layer_key: FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_V4,
+        conditions: &[
+            ConditionSpec::User,
+            ConditionSpec::Protocol(IPPROTO_ICMP as u8),
+        ],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xea10db66_a928_4b2e_a82e_a376a54f93ba),
+        name: "codex_wfp_icmp_assign_v6",
+        description: "Block sandbox-account ICMP resource assignment v6",
+        layer_key: FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_V6,
+        conditions: &[
+            ConditionSpec::User,
+            ConditionSpec::Protocol(IPPROTO_ICMPV6 as u8),
+        ],
+    },
+    // NAME_RESOLUTION_CACHE filters are intentionally omitted because ordinary
+    // static filter shapes returned FWP_E_OUT_OF_BOUNDS during validation.
+    FilterSpec {
+        key: GUID::from_u128(0x83172805_f6be_4ae1_9dc6_6847aef04e7f),
+        name: "codex_wfp_dns_53_v4",
+        description: "Block sandbox-account DNS TCP or UDP port 53 v4",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V4,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(53)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xd23b2efb_1efb_46b2_96f3_b0ccda5690c8),
+        name: "codex_wfp_dns_53_v6",
+        description: "Block sandbox-account DNS TCP or UDP port 53 v6",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V6,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(53)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0x420b026f_9dc9_4aea_88f4_0f2b9feab39a),
+        name: "codex_wfp_dns_853_v4",
+        description: "Block sandbox-account DNS-over-TLS port 853 v4",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V4,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(853)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0x8d917c81_99cc_45e7_84d6_824df860cfb8),
+        name: "codex_wfp_dns_853_v6",
+        description: "Block sandbox-account DNS-over-TLS port 853 v6",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V6,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(853)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xe1d6e0af_ce5f_471b_b2d3_15ca00e966f3),
+        name: "codex_wfp_smb_445_v4",
+        description: "Block sandbox-account SMB port 445 v4",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V4,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(445)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xc2bceca4_66ef_4a0f_ba80_f4f761b8c6f0),
+        name: "codex_wfp_smb_445_v6",
+        description: "Block sandbox-account SMB port 445 v6",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V6,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(445)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xba10c618_84e7_4b83_8f74_36e22b2fa1ff),
+        name: "codex_wfp_smb_139_v4",
+        description: "Block sandbox-account SMB port 139 v4",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V4,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(139)],
+    },
+    FilterSpec {
+        key: GUID::from_u128(0xfe7f22b8_5cf5_4adb_b2aa_71fc0a8f5d44),
+        name: "codex_wfp_smb_139_v6",
+        description: "Block sandbox-account SMB port 139 v6",
+        layer_key: FWPM_LAYER_ALE_AUTH_CONNECT_V6,
+        conditions: &[ConditionSpec::User, ConditionSpec::RemotePort(139)],
+    },
+];
diff --git a/codex-rs/windows-sandbox-rs/src/wfp_setup.rs b/codex-rs/windows-sandbox-rs/src/wfp_setup.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b3d6c4d33925f122661c75dd1843bca861c969ad
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/wfp_setup.rs
@@ -0,0 +1,178 @@
+use crate::install_wfp_filters_for_account;
+use crate::setup_error::sanitize_setup_metric_tag_value;
+use anyhow::Result;
+use codex_otel::OtelExporter;
+use codex_otel::OtelProvider;
+use codex_otel::OtelSettings;
+use codex_otel::StatsigMetricsSettings;
+use std::collections::BTreeMap;
+use std::path::Path;
+
+const WFP_SETUP_SERVICE_NAME: &str = "codex-windows-sandbox-setup";
+const WFP_SETUP_SUCCESS_METRIC: &str = "codex.windows_sandbox.wfp_setup_success";
+const WFP_SETUP_FAILURE_METRIC: &str = "codex.windows_sandbox.wfp_setup_failure";
+
+#[derive(Debug, Clone, Copy)]
+enum WfpSetupMetricOutcome {
+    Success,
+    Failure,
+}
+
+struct WfpSetupMetric {
+    outcome: WfpSetupMetricOutcome,
+    target_account: String,
+    installed_filter_count: usize,
+    error: Option<String>,
+}
+
+fn panic_payload_to_string(panic_payload: Box<dyn std::any::Any + Send>) -> String {
+    match panic_payload.downcast::<String>() {
+        Ok(message) => *message,
+        Err(panic_payload) => match panic_payload.downcast::<&'static str>() {
+            Ok(message) => (*message).to_string(),
+            Err(_) => "unknown panic payload".to_string(),
+        },
+    }
+}
+
+fn build_wfp_metrics_provider(
+    codex_home: &Path,
+    otel: Option<&StatsigMetricsSettings>,
+) -> Result<Option<OtelProvider>> {
+    let Some(otel) = otel else {
+        return Ok(None);
+    };
+    // The setup helper cannot call codex-core's OTEL builder because core
+    // depends on this crate, so the parent process passes only the resolved
+    // Statsig environment in the elevation payload. Other exporters are
+    // intentionally omitted from this helper path.
+    OtelProvider::try_new(&OtelSettings {
+        environment: otel.environment.clone(),
+        service_name: WFP_SETUP_SERVICE_NAME.to_string(),
+        service_version: env!("CARGO_PKG_VERSION").to_string(),
+        codex_home: codex_home.to_path_buf(),
+        exporter: OtelExporter::None,
+        trace_exporter: OtelExporter::None,
+        metrics_exporter: OtelExporter::Statsig,
+        runtime_metrics: false,
+        span_attributes: BTreeMap::new(),
+        tracestate: BTreeMap::new(),
+    })
+    .map_err(|err| anyhow::anyhow!("failed to initialize WFP setup metrics provider: {err}"))
+}
+
+fn emit_wfp_setup_metric(
+    codex_home: &Path,
+    otel: Option<&StatsigMetricsSettings>,
+    metric: &WfpSetupMetric,
+) -> Result<()> {
+    let Some(provider) = build_wfp_metrics_provider(codex_home, otel)? else {
+        return Ok(());
+    };
+    if let Some(metrics) = provider.metrics() {
+        let target_account = sanitize_setup_metric_tag_value(&metric.target_account);
+        match metric.outcome {
+            WfpSetupMetricOutcome::Success => {
+                let installed_filter_count = metric.installed_filter_count.to_string();
+                metrics.counter(
+                    WFP_SETUP_SUCCESS_METRIC,
+                    /*inc*/ 1,
+                    &[
+                        ("target_account", target_account.as_str()),
+                        ("installed_filter_count", installed_filter_count.as_str()),
+                    ],
+                )?;
+            }
+            WfpSetupMetricOutcome::Failure => {
+                let mut tags = vec![("target_account", target_account.as_str())];
+                let error_tag = metric.error.as_deref().map(sanitize_setup_metric_tag_value);
+                if let Some(error) = error_tag.as_deref() {
+                    tags.push(("message", error));
+                }
+                metrics.counter(WFP_SETUP_FAILURE_METRIC, /*inc*/ 1, &tags)?;
+            }
+        }
+    }
+    provider.shutdown();
+    Ok(())
+}
+
+fn emit_wfp_setup_metric_safely<F>(
+    codex_home: &Path,
+    otel: Option<&StatsigMetricsSettings>,
+    offline_username: &str,
+    metric: &WfpSetupMetric,
+    log: &mut F,
+) where
+    F: FnMut(&str),
+{
+    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        emit_wfp_setup_metric(codex_home, otel, metric)
+    }));
+    match result {
+        Ok(Ok(())) => {}
+        Ok(Err(err)) => log(&format!(
+            "failed to emit WFP setup metric for {offline_username}: {err}"
+        )),
+        Err(panic_payload) => {
+            let error = panic_payload_to_string(panic_payload);
+            log(&format!(
+                "WFP setup metric emission panicked for {offline_username}: {error}"
+            ));
+        }
+    }
+}
+
+pub fn install_wfp_filters<F>(
+    codex_home: &Path,
+    offline_username: &str,
+    otel: Option<&StatsigMetricsSettings>,
+    mut log: F,
+) -> Result<()>
+where
+    F: FnMut(&str),
+{
+    let metric = match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        install_wfp_filters_for_account(offline_username)
+    })) {
+        Ok(Ok(installed_filter_count)) => {
+            log(&format!(
+                "WFP setup succeeded for {offline_username} with {installed_filter_count} installed filters"
+            ));
+            WfpSetupMetric {
+                outcome: WfpSetupMetricOutcome::Success,
+                target_account: offline_username.to_string(),
+                installed_filter_count,
+                error: None,
+            }
+        }
+        Ok(Err(err)) => {
+            let error = err.to_string();
+            log(&format!("WFP setup failed for {offline_username}: {error}"));
+            WfpSetupMetric {
+                outcome: WfpSetupMetricOutcome::Failure,
+                target_account: offline_username.to_string(),
+                installed_filter_count: 0,
+                error: Some(error),
+            }
+        }
+        Err(panic_payload) => {
+            let error = panic_payload_to_string(panic_payload);
+            log(&format!(
+                "WFP setup panicked for {offline_username}: {error}"
+            ));
+            WfpSetupMetric {
+                outcome: WfpSetupMetricOutcome::Failure,
+                target_account: offline_username.to_string(),
+                installed_filter_count: 0,
+                error: Some(format!("panic: {error}")),
+            }
+        }
+    };
+
+    emit_wfp_setup_metric_safely(codex_home, otel, offline_username, &metric, &mut log);
+    match metric.error {
+        Some(error) => Err(anyhow::anyhow!(error)),
+        None => Ok(()),
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/winutil.rs b/codex-rs/windows-sandbox-rs/src/winutil.rs
new file mode 100644
index 0000000000000000000000000000000000000000..089936268409c643aead38aeea4bd133875a51ee
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/winutil.rs
@@ -0,0 +1,360 @@
+use anyhow::Context;
+use anyhow::Result;
+use std::ffi::OsStr;
+use std::os::windows::ffi::OsStrExt;
+use windows_sys::Win32::Foundation::ERROR_INSUFFICIENT_BUFFER;
+use windows_sys::Win32::Foundation::GetLastError;
+use windows_sys::Win32::Foundation::HLOCAL;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::NetworkManagement::NetManagement::LOCALGROUP_INFO_1;
+use windows_sys::Win32::NetworkManagement::NetManagement::NERR_Success;
+use windows_sys::Win32::NetworkManagement::NetManagement::NERR_UserNotFound;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetApiBufferFree;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetLocalGroupAdd;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetUserGetInfo;
+use windows_sys::Win32::NetworkManagement::NetManagement::NetUserSetInfo;
+use windows_sys::Win32::NetworkManagement::NetManagement::USER_INFO_1;
+use windows_sys::Win32::NetworkManagement::NetManagement::USER_INFO_1008;
+use windows_sys::Win32::Security::Authorization::ConvertSidToStringSidW;
+use windows_sys::Win32::Security::Authorization::ConvertStringSidToSidW;
+use windows_sys::Win32::Security::CopySid;
+use windows_sys::Win32::Security::GetLengthSid;
+use windows_sys::Win32::Security::LookupAccountNameW;
+use windows_sys::Win32::Security::SID_NAME_USE;
+use windows_sys::Win32::System::Diagnostics::Debug::FORMAT_MESSAGE_ALLOCATE_BUFFER;
+use windows_sys::Win32::System::Diagnostics::Debug::FORMAT_MESSAGE_FROM_SYSTEM;
+use windows_sys::Win32::System::Diagnostics::Debug::FORMAT_MESSAGE_IGNORE_INSERTS;
+use windows_sys::Win32::System::Diagnostics::Debug::FormatMessageW;
+
+pub const SANDBOX_USERS_GROUP: &str = "CodexSandboxUsers";
+const SANDBOX_USERS_GROUP_COMMENT: &str = "Codex sandbox internal group (managed)";
+
+pub fn to_wide<S: AsRef<OsStr>>(s: S) -> Vec<u16> {
+    let mut v: Vec<u16> = s.as_ref().encode_wide().collect();
+    v.push(0);
+    v
+}
+
+/// Resolve a named Windows user without consulting environment variables.
+///
+/// # Safety
+/// `sid` must point to a valid SID for the duration of this call.
+pub unsafe fn account_name_from_sid(sid: *mut std::ffi::c_void) -> Result<String> {
+    use windows_sys::Win32::Security as security;
+    let mut name = [0_u16; 256];
+    let mut domain = [0_u16; 256];
+    let mut name_length = name.len() as u32;
+    let mut domain_length = domain.len() as u32;
+    let mut account_type: security::SID_NAME_USE = 0;
+    if unsafe {
+        security::LookupAccountSidW(
+            std::ptr::null(),
+            sid,
+            name.as_mut_ptr(),
+            &mut name_length,
+            domain.as_mut_ptr(),
+            &mut domain_length,
+            &mut account_type,
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("resolve Windows account name");
+    }
+    anyhow::ensure!(
+        account_type == security::SidTypeUser && domain_length > 0,
+        "SID is not a named Windows user"
+    );
+    let name = String::from_utf16(&name[..name_length as usize])?;
+    let domain = String::from_utf16(&domain[..domain_length as usize])?;
+    Ok(format!("{domain}\\{name}"))
+}
+
+/// Quote a single Windows command-line argument following the rules used by
+/// CommandLineToArgvW/CRT so that spaces, quotes, and backslashes are preserved.
+/// Reference behavior matches Rust std::process::Command on Windows.
+#[cfg(target_os = "windows")]
+pub fn quote_windows_arg(arg: &str) -> String {
+    let needs_quotes = arg.is_empty()
+        || arg
+            .chars()
+            .any(|c| matches!(c, ' ' | '\t' | '\n' | '\r' | '"'));
+    if !needs_quotes {
+        return arg.to_string();
+    }
+
+    let mut quoted = String::with_capacity(arg.len() + 2);
+    quoted.push('"');
+    let mut backslashes = 0;
+    for ch in arg.chars() {
+        match ch {
+            '\\' => {
+                backslashes += 1;
+            }
+            '"' => {
+                quoted.push_str(&"\\".repeat(backslashes * 2 + 1));
+                quoted.push('"');
+                backslashes = 0;
+            }
+            _ => {
+                if backslashes > 0 {
+                    quoted.push_str(&"\\".repeat(backslashes));
+                    backslashes = 0;
+                }
+                quoted.push(ch);
+            }
+        }
+    }
+    if backslashes > 0 {
+        quoted.push_str(&"\\".repeat(backslashes * 2));
+    }
+    quoted.push('"');
+    quoted
+}
+
+/// Build a Windows command line for CreateProcess-style APIs.
+#[cfg(target_os = "windows")]
+pub fn argv_to_command_line(argv: &[String]) -> String {
+    argv.iter()
+        .map(|arg| quote_windows_arg(arg))
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+// Produce a readable description for a Win32 error code.
+pub fn format_last_error(err: i32) -> String {
+    unsafe {
+        let mut buf_ptr: *mut u16 = std::ptr::null_mut();
+        let flags = FORMAT_MESSAGE_ALLOCATE_BUFFER
+            | FORMAT_MESSAGE_FROM_SYSTEM
+            | FORMAT_MESSAGE_IGNORE_INSERTS;
+        let len = FormatMessageW(
+            flags,
+            std::ptr::null(),
+            err as u32,
+            0,
+            // FORMAT_MESSAGE_ALLOCATE_BUFFER expects a pointer to receive the allocated buffer.
+            // Cast &mut *mut u16 to *mut u16 as required by windows-sys.
+            (&mut buf_ptr as *mut *mut u16) as *mut u16,
+            0,
+            std::ptr::null_mut(),
+        );
+        if len == 0 || buf_ptr.is_null() {
+            return format!("Win32 error {err}");
+        }
+        let slice = std::slice::from_raw_parts(buf_ptr, len as usize);
+        let mut s = String::from_utf16_lossy(slice);
+        s = s.trim().to_string();
+        let _ = LocalFree(buf_ptr as HLOCAL);
+        s
+    }
+}
+
+pub fn string_from_sid_bytes(sid: &[u8]) -> Result<String, String> {
+    unsafe {
+        let mut str_ptr: *mut u16 = std::ptr::null_mut();
+        let ok = ConvertSidToStringSidW(sid.as_ptr() as *mut std::ffi::c_void, &mut str_ptr);
+        if ok == 0 || str_ptr.is_null() {
+            return Err(format!(
+                "ConvertSidToStringSidW failed: {}",
+                std::io::Error::last_os_error()
+            ));
+        }
+        let mut len = 0;
+        while *str_ptr.add(len) != 0 {
+            len += 1;
+        }
+        let slice = std::slice::from_raw_parts(str_ptr, len);
+        let out = String::from_utf16_lossy(slice);
+        let _ = LocalFree(str_ptr as HLOCAL);
+        Ok(out)
+    }
+}
+
+const SID_ADMINISTRATORS: &str = "S-1-5-32-544";
+const SID_USERS: &str = "S-1-5-32-545";
+const SID_AUTHENTICATED_USERS: &str = "S-1-5-11";
+const SID_EVERYONE: &str = "S-1-1-0";
+const SID_SYSTEM: &str = "S-1-5-18";
+
+pub fn local_user_flags(name: &str) -> Result<Option<u32>> {
+    let name_wide = to_wide(name);
+    let mut buffer = std::ptr::null_mut();
+    let status = unsafe {
+        NetUserGetInfo(
+            std::ptr::null(),
+            name_wide.as_ptr(),
+            /*level*/ 1,
+            &mut buffer,
+        )
+    };
+    if status == NERR_UserNotFound {
+        return Ok(None);
+    }
+    if status != NERR_Success {
+        return Err(std::io::Error::from_raw_os_error(status as i32))
+            .with_context(|| format!("read local sandbox user {name}"));
+    }
+    let flags = unsafe { (*buffer.cast::<USER_INFO_1>()).usri1_flags };
+    unsafe { NetApiBufferFree(buffer.cast()) };
+    Ok(Some(flags))
+}
+
+pub fn set_local_user_flags(name: &str, flags: u32) -> Result<()> {
+    let name_wide = to_wide(name);
+    let info = USER_INFO_1008 {
+        usri1008_flags: flags,
+    };
+    let status = unsafe {
+        NetUserSetInfo(
+            std::ptr::null(),
+            name_wide.as_ptr(),
+            /*level*/ 1008,
+            (&raw const info).cast(),
+            std::ptr::null_mut(),
+        )
+    };
+    if status != NERR_Success {
+        return Err(std::io::Error::from_raw_os_error(status as i32))
+            .with_context(|| format!("set local sandbox user {name} flags"));
+    }
+    Ok(())
+}
+
+pub fn ensure_sandbox_users_group() -> Result<Vec<u8>> {
+    const ERROR_ALIAS_EXISTS: u32 = 1379;
+    const NERR_GROUP_EXISTS: u32 = 2223;
+
+    let name = to_wide(SANDBOX_USERS_GROUP);
+    let comment = to_wide(SANDBOX_USERS_GROUP_COMMENT);
+    let info = LOCALGROUP_INFO_1 {
+        lgrpi1_name: name.as_ptr() as *mut u16,
+        lgrpi1_comment: comment.as_ptr() as *mut u16,
+    };
+    let mut parameter_error = 0;
+    let status = unsafe {
+        NetLocalGroupAdd(
+            std::ptr::null(),
+            1,
+            (&raw const info).cast(),
+            &raw mut parameter_error,
+        )
+    };
+    if status != NERR_Success && status != ERROR_ALIAS_EXISTS && status != NERR_GROUP_EXISTS {
+        return Err(anyhow::anyhow!(
+            "NetLocalGroupAdd failed for {SANDBOX_USERS_GROUP} code {status} parm_err={parameter_error}"
+        ));
+    }
+
+    resolve_sid(SANDBOX_USERS_GROUP)
+}
+
+pub fn resolve_sid(name: &str) -> Result<Vec<u8>> {
+    if let Some(sid_str) = well_known_sid_str(name) {
+        return sid_bytes_from_string(sid_str);
+    }
+    let name_w = to_wide(OsStr::new(name));
+    let mut sid_buffer = vec![0u8; 68];
+    let mut sid_len: u32 = sid_buffer.len() as u32;
+    let mut domain: Vec<u16> = Vec::new();
+    let mut domain_len: u32 = 0;
+    let mut use_type: SID_NAME_USE = 0;
+    loop {
+        let ok = unsafe {
+            LookupAccountNameW(
+                std::ptr::null(),
+                name_w.as_ptr(),
+                sid_buffer.as_mut_ptr() as *mut std::ffi::c_void,
+                &mut sid_len,
+                domain.as_mut_ptr(),
+                &mut domain_len,
+                &mut use_type,
+            )
+        };
+        if ok != 0 {
+            sid_buffer.truncate(sid_len as usize);
+            return Ok(sid_buffer);
+        }
+        let err = unsafe { GetLastError() };
+        if err == ERROR_INSUFFICIENT_BUFFER {
+            sid_buffer.resize(sid_len as usize, 0);
+            domain.resize(domain_len as usize, 0);
+            continue;
+        }
+        return Err(anyhow::anyhow!(
+            "LookupAccountNameW failed for {name}: {err}"
+        ));
+    }
+}
+
+fn well_known_sid_str(name: &str) -> Option<&'static str> {
+    match name {
+        "Administrators" => Some(SID_ADMINISTRATORS),
+        "Users" => Some(SID_USERS),
+        "Authenticated Users" => Some(SID_AUTHENTICATED_USERS),
+        "Everyone" => Some(SID_EVERYONE),
+        "SYSTEM" => Some(SID_SYSTEM),
+        _ => None,
+    }
+}
+
+pub(crate) fn sid_bytes_from_string(sid_str: &str) -> Result<Vec<u8>> {
+    let sid_w = to_wide(OsStr::new(sid_str));
+    let mut psid: *mut std::ffi::c_void = std::ptr::null_mut();
+    if unsafe { ConvertStringSidToSidW(sid_w.as_ptr(), &mut psid) } == 0 {
+        return Err(anyhow::anyhow!(
+            "ConvertStringSidToSidW failed for {sid_str}: {}",
+            unsafe { GetLastError() }
+        ));
+    }
+    let sid_len = unsafe { GetLengthSid(psid) };
+    if sid_len == 0 {
+        unsafe {
+            LocalFree(psid as _);
+        }
+        return Err(anyhow::anyhow!("GetLengthSid failed for {sid_str}"));
+    }
+    let mut out = vec![0u8; sid_len as usize];
+    let ok = unsafe { CopySid(sid_len, out.as_mut_ptr() as *mut std::ffi::c_void, psid) };
+    unsafe {
+        LocalFree(psid as _);
+    }
+    if ok == 0 {
+        return Err(anyhow::anyhow!("CopySid failed for {sid_str}"));
+    }
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::argv_to_command_line;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn argv_to_command_line_quotes_each_argument_independently() {
+        let argv = vec![
+            "cmd.exe".to_string(),
+            "/c".to_string(),
+            "\"C:\\Program Files\\PowerShell\\7\\pwsh.exe\" -NoProfile -EncodedCommand abc=="
+                .to_string(),
+        ];
+
+        assert_eq!(
+            argv_to_command_line(&argv),
+            "cmd.exe /c \"\\\"C:\\Program Files\\PowerShell\\7\\pwsh.exe\\\" -NoProfile -EncodedCommand abc==\""
+        );
+    }
+
+    #[test]
+    fn argv_to_command_line_quotes_regular_program_args() {
+        let argv = vec![
+            "pwsh.exe".to_string(),
+            "-Command".to_string(),
+            "Write-Output \"hello world\"".to_string(),
+        ];
+
+        assert_eq!(
+            argv_to_command_line(&argv),
+            "pwsh.exe -Command \"Write-Output \\\"hello world\\\"\""
+        );
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/workspace_acl.rs b/codex-rs/windows-sandbox-rs/src/workspace_acl.rs
new file mode 100644
index 0000000000000000000000000000000000000000..7143212b54c088e317ef5acbc729060e68237e68
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/workspace_acl.rs
@@ -0,0 +1,30 @@
+use crate::acl::add_deny_write_ace;
+use crate::path_normalization::canonicalize_path;
+use anyhow::Result;
+use std::ffi::c_void;
+use std::path::Path;
+
+pub fn is_command_cwd_root(root: &Path, canonical_command_cwd: &Path) -> bool {
+    canonicalize_path(root) == canonical_command_cwd
+}
+
+/// # Safety
+/// Caller must ensure `psid` is a valid SID pointer.
+pub unsafe fn protect_workspace_codex_dir(cwd: &Path, psid: *mut c_void) -> Result<bool> {
+    protect_workspace_subdir(cwd, psid, ".codex")
+}
+
+/// # Safety
+/// Caller must ensure `psid` is a valid SID pointer.
+pub unsafe fn protect_workspace_agents_dir(cwd: &Path, psid: *mut c_void) -> Result<bool> {
+    protect_workspace_subdir(cwd, psid, ".agents")
+}
+
+unsafe fn protect_workspace_subdir(cwd: &Path, psid: *mut c_void, subdir: &str) -> Result<bool> {
+    let path = cwd.join(subdir);
+    if path.is_dir() {
+        add_deny_write_ace(&path, psid)
+    } else {
+        Ok(false)
+    }
+}
diff --git a/codex-rs/windows-sandbox-rs/src/wrapper.rs b/codex-rs/windows-sandbox-rs/src/wrapper.rs
new file mode 100644
index 0000000000000000000000000000000000000000..eb410216d806bac331d048545e50c1febfb562e9
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/wrapper.rs
@@ -0,0 +1,482 @@
+//! Internal `codex.exe --run-as-windows-sandbox` wrapper.
+//!
+//! This gives direct-spawn callers an argv-shaped Windows sandbox launcher,
+//! analogous to the macOS seatbelt and Linux sandbox wrapper paths. The wrapper
+//! parses sandbox metadata from argv, launches the requested inner command in a
+//! Windows sandbox session, and forwards stdio to that inner command.
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+use crate::cap::load_or_create_cap_sids;
+use crate::desktop::DesktopPolicy;
+use crate::desktop::LaunchDesktop;
+use crate::desktop::shared_private_desktop_for_user;
+use crate::identity::require_sandbox_account;
+use crate::setup::effective_write_roots_for_permissions;
+use crate::spawn_prep::SpawnPrepOptions;
+use crate::spawn_prep::legacy_session_capability_roots;
+use crate::spawn_prep::prepare_legacy_session_security;
+use crate::spawn_prep::prepare_legacy_spawn_context;
+use crate::spawn_prep::prepare_spawn_context_common;
+use crate::spawn_prep::root_capability_sids;
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::anyhow;
+use anyhow::bail;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::models::PermissionProfile;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use windows_sys::Win32::Foundation::CloseHandle;
+
+pub const CODEX_WINDOWS_SANDBOX_ARG1: &str = "--run-as-windows-sandbox";
+
+const COMMAND_CWD_FLAG: &str = "--command-cwd";
+const CODEX_HOME_FLAG: &str = "--codex-home";
+const DENY_READ_PATHS_JSON_FLAG: &str = "--deny-read-paths-json";
+const DENY_WRITE_PATHS_JSON_FLAG: &str = "--deny-write-paths-json";
+const ENV_JSON_FLAG: &str = "--env-json";
+const NETWORK_PROXY_RESTRICTING_SID_FLAG: &str = "--network-proxy-restricting-sid";
+const PERMISSION_PROFILE_FLAG: &str = "--permission-profile";
+const PRIVATE_DESKTOP_FLAG: &str = "--windows-sandbox-private-desktop";
+const PRIVATE_DESKTOP_NAME_FLAG: &str = "--windows-sandbox-private-desktop-name";
+const PRESERVE_PROXY_SETTINGS_FLAG: &str = "--preserve-proxy-settings";
+const PROXY_ENFORCED_FLAG: &str = "--proxy-enforced";
+const READ_ROOTS_INCLUDE_PLATFORM_DEFAULTS_FLAG: &str = "--read-roots-include-platform-defaults";
+const READ_ROOTS_JSON_FLAG: &str = "--read-roots-json";
+const SANDBOX_LEVEL_FLAG: &str = "--windows-sandbox-level";
+const WRITE_ROOTS_JSON_FLAG: &str = "--write-roots-json";
+const WORKSPACE_ROOT_FLAG: &str = "--workspace-root";
+
+#[allow(clippy::too_many_arguments)]
+pub fn create_windows_sandbox_command_args_for_permission_profile(
+    command: Vec<String>,
+    command_cwd: &AbsolutePathBuf,
+    workspace_roots: &[AbsolutePathBuf],
+    env_map: &HashMap<String, String>,
+    permission_profile: &PermissionProfile,
+    windows_sandbox_level: WindowsSandboxLevel,
+    windows_sandbox_private_desktop: bool,
+    proxy_enforced: bool,
+    network_proxy_restricting_sid: Option<&str>,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+    read_roots_override: Option<&[PathBuf]>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<&[PathBuf]>,
+    deny_read_paths_override: &[AbsolutePathBuf],
+    deny_write_paths_override: &[AbsolutePathBuf],
+    codex_home: &Path,
+) -> Result<Vec<String>> {
+    let permission_profile_json = serde_json::to_string(permission_profile)
+        .unwrap_or_else(|err| panic!("failed to serialize permission profile: {err}"));
+    let env_json = serde_json::to_string(env_map)
+        .unwrap_or_else(|err| panic!("failed to serialize env: {err}"));
+    let mut args = vec![
+        CODEX_WINDOWS_SANDBOX_ARG1.to_string(),
+        CODEX_HOME_FLAG.to_string(),
+        codex_home.to_string_lossy().into_owned(),
+        COMMAND_CWD_FLAG.to_string(),
+        command_cwd.as_path().to_string_lossy().into_owned(),
+        PERMISSION_PROFILE_FLAG.to_string(),
+        permission_profile_json,
+        ENV_JSON_FLAG.to_string(),
+        env_json,
+        SANDBOX_LEVEL_FLAG.to_string(),
+        windows_sandbox_level.to_string(),
+    ];
+    let workspace_roots = if workspace_roots.is_empty() {
+        std::slice::from_ref(command_cwd)
+    } else {
+        workspace_roots
+    };
+    for root in workspace_roots {
+        args.push(WORKSPACE_ROOT_FLAG.to_string());
+        args.push(root.as_path().to_string_lossy().into_owned());
+    }
+    if windows_sandbox_private_desktop {
+        // The caller owns the cache so the desktop survives this short-lived wrapper.
+        let mut desktop_env = env_map.clone();
+        let deny_write_paths = deny_write_paths_override
+            .iter()
+            .map(AbsolutePathBuf::to_path_buf)
+            .collect::<Vec<_>>();
+        let desktop_name = if windows_sandbox_level == WindowsSandboxLevel::Elevated {
+            let common = prepare_spawn_context_common(
+                permission_profile,
+                workspace_roots,
+                codex_home,
+                command_cwd.as_path(),
+                &mut desktop_env,
+                &command,
+                SpawnPrepOptions {
+                    inherit_path: true,
+                    add_git_safe_directory: true,
+                },
+            )?;
+            let request = crate::setup::SandboxSetupRequest {
+                permissions: &common.permissions,
+                command_cwd: command_cwd.as_path(),
+                env_map: &desktop_env,
+                codex_home,
+                proxy_enforced,
+            };
+            // Desktop selection needs the account and capabilities, not the wrapper's ACL refresh.
+            let (sandbox_creds, _) = require_sandbox_account(&request, proxy_settings_mode)?;
+            let caps = load_or_create_cap_sids(codex_home)?;
+            let cap_sids = if common.uses_write_capabilities {
+                root_capability_sids(
+                    codex_home,
+                    command_cwd.as_path(),
+                    effective_write_roots_for_permissions(
+                        &common.permissions,
+                        command_cwd.as_path(),
+                        &desktop_env,
+                        codex_home,
+                        write_roots_override,
+                    ),
+                )?
+                .into_iter()
+                .map(|root| root.sid_str)
+                .collect::<Vec<_>>()
+            } else {
+                vec![caps.readonly]
+            };
+            if cap_sids.is_empty() {
+                bail!("workspace-write sandbox has no writable root capability SIDs");
+            }
+            let policy = DesktopPolicy::elevated(
+                request,
+                crate::setup::SetupRootOverrides {
+                    read_roots: read_roots_override.map(<[PathBuf]>::to_vec),
+                    read_roots_include_platform_defaults,
+                    write_roots: write_roots_override.map(<[PathBuf]>::to_vec),
+                    deny_read_paths: Some(
+                        deny_read_paths_override
+                            .iter()
+                            .map(AbsolutePathBuf::to_path_buf)
+                            .collect(),
+                    ),
+                    deny_write_paths: Some(deny_write_paths),
+                },
+                &cap_sids,
+                network_proxy_restricting_sid,
+            )?;
+            shared_private_desktop_for_user(
+                &sandbox_creds.username,
+                &policy,
+                common.logs_base_dir.as_deref(),
+            )?
+        } else {
+            let common = prepare_legacy_spawn_context(
+                permission_profile,
+                workspace_roots,
+                codex_home,
+                command_cwd.as_path(),
+                &mut desktop_env,
+                &command,
+                SpawnPrepOptions {
+                    inherit_path: false,
+                    add_git_safe_directory: false,
+                },
+            )?;
+            let capability_roots = legacy_session_capability_roots(
+                &common.permissions,
+                &common.current_dir,
+                &desktop_env,
+                codex_home,
+            );
+            let security = prepare_legacy_session_security(
+                common.uses_write_capabilities,
+                codex_home,
+                command_cwd.as_path(),
+                capability_roots,
+            )?;
+            let desktop_name = LaunchDesktop::shared_legacy_name(
+                &common.permissions,
+                &common.current_dir,
+                &desktop_env,
+                &security,
+                &deny_write_paths,
+                common.logs_base_dir.as_deref(),
+            );
+            unsafe {
+                CloseHandle(security.h_token);
+            }
+            desktop_name?
+        };
+        args.push(PRIVATE_DESKTOP_FLAG.to_string());
+        args.push(PRIVATE_DESKTOP_NAME_FLAG.to_string());
+        args.push(desktop_name);
+    }
+    if proxy_enforced {
+        args.push(PROXY_ENFORCED_FLAG.to_string());
+    }
+    if let Some(network_proxy_restricting_sid) = network_proxy_restricting_sid {
+        args.push(NETWORK_PROXY_RESTRICTING_SID_FLAG.to_string());
+        args.push(network_proxy_restricting_sid.to_string());
+    }
+    if proxy_settings_mode == crate::WindowsSandboxProxySettingsMode::Preserve {
+        args.push(PRESERVE_PROXY_SETTINGS_FLAG.to_string());
+    }
+    if let Some(read_roots_override) = read_roots_override {
+        push_json_arg(&mut args, READ_ROOTS_JSON_FLAG, &read_roots_override);
+    }
+    if read_roots_include_platform_defaults {
+        args.push(READ_ROOTS_INCLUDE_PLATFORM_DEFAULTS_FLAG.to_string());
+    }
+    if let Some(write_roots_override) = write_roots_override {
+        push_json_arg(&mut args, WRITE_ROOTS_JSON_FLAG, &write_roots_override);
+    }
+    if !deny_read_paths_override.is_empty() {
+        push_json_arg(
+            &mut args,
+            DENY_READ_PATHS_JSON_FLAG,
+            &deny_read_paths_override,
+        );
+    }
+    if !deny_write_paths_override.is_empty() {
+        push_json_arg(
+            &mut args,
+            DENY_WRITE_PATHS_JSON_FLAG,
+            &deny_write_paths_override,
+        );
+    }
+    args.push("--".to_string());
+    args.extend(command);
+    Ok(args)
+}
+
+fn push_json_arg<T: serde::Serialize>(args: &mut Vec<String>, flag: &str, value: &T) {
+    args.push(flag.to_string());
+    args.push(
+        serde_json::to_string(value)
+            .unwrap_or_else(|err| panic!("failed to serialize {flag}: {err}")),
+    );
+}
+
+pub fn run_windows_sandbox_wrapper_main() -> ! {
+    let args = std::env::args().skip(2).collect::<Vec<_>>();
+    let runtime = match tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+    {
+        Ok(runtime) => runtime,
+        Err(err) => {
+            eprintln!("windows sandbox failed to build runtime: {err}");
+            std::process::exit(1);
+        }
+    };
+    let exit_code = match runtime.block_on(run_windows_sandbox_wrapper_args(args)) {
+        Ok(exit_code) => exit_code,
+        Err(err) => {
+            eprintln!("windows sandbox failed: {err:#}");
+            1
+        }
+    };
+    std::process::exit(exit_code);
+}
+
+async fn run_windows_sandbox_wrapper_args(args: Vec<String>) -> Result<i32> {
+    let request = parse_windows_sandbox_wrapper_args(args)?;
+    run_windows_sandbox_wrapper_request(request).await
+}
+
+struct WindowsSandboxWrapperRequest {
+    codex_home: PathBuf,
+    command_cwd: AbsolutePathBuf,
+    workspace_roots: Vec<AbsolutePathBuf>,
+    env_map: HashMap<String, String>,
+    permission_profile: PermissionProfile,
+    windows_sandbox_level: WindowsSandboxLevel,
+    windows_sandbox_private_desktop: bool,
+    private_desktop_name: Option<String>,
+    proxy_enforced: bool,
+    network_proxy_restricting_sid: Option<String>,
+    proxy_settings_mode: crate::WindowsSandboxProxySettingsMode,
+    read_roots_override: Option<Vec<PathBuf>>,
+    read_roots_include_platform_defaults: bool,
+    write_roots_override: Option<Vec<PathBuf>>,
+    deny_read_paths_override: Vec<AbsolutePathBuf>,
+    deny_write_paths_override: Vec<AbsolutePathBuf>,
+    command: Vec<String>,
+}
+
+async fn run_windows_sandbox_wrapper_request(request: WindowsSandboxWrapperRequest) -> Result<i32> {
+    if request.command.is_empty() {
+        bail!("missing sandboxed command in windows sandbox wrapper request");
+    }
+    let spawned = crate::unified_exec::spawn_windows_sandbox_session_with_desktop(
+        crate::WindowsSandboxSessionRequest {
+            permission_profile: &request.permission_profile,
+            workspace_roots: request.workspace_roots.as_slice(),
+            codex_home: request.codex_home.as_path(),
+            command: request.command,
+            cwd: request.command_cwd.as_path(),
+            env_map: request.env_map,
+            windows_sandbox_level: request.windows_sandbox_level,
+            proxy_enforced: request.proxy_enforced,
+            network_proxy_restricting_sid: request.network_proxy_restricting_sid,
+            proxy_settings_mode: request.proxy_settings_mode,
+            timeout_ms: None,
+            read_roots_override: request.read_roots_override.as_deref(),
+            read_roots_include_platform_defaults: request.read_roots_include_platform_defaults,
+            write_roots_override: request.write_roots_override.as_deref(),
+            deny_read_paths_override: request.deny_read_paths_override.as_slice(),
+            deny_write_paths_override: request.deny_write_paths_override.as_slice(),
+            tty: false,
+            stdin_open: true,
+            use_private_desktop: request.windows_sandbox_private_desktop,
+        },
+        request.private_desktop_name,
+    )
+    .await?;
+
+    Ok(crate::forward_sandbox_session_stdio(spawned).await)
+}
+
+fn parse_windows_sandbox_wrapper_args(args: Vec<String>) -> Result<WindowsSandboxWrapperRequest> {
+    let mut args = args.into_iter();
+    let mut codex_home = None;
+    let mut command_cwd = None;
+    let mut workspace_roots = Vec::new();
+    let mut env_map = None;
+    let mut permission_profile = None;
+    let mut windows_sandbox_level = None;
+    let mut windows_sandbox_private_desktop = false;
+    let mut private_desktop_name = None;
+    let mut proxy_enforced = false;
+    let mut network_proxy_restricting_sid = None;
+    let mut proxy_settings_mode = crate::WindowsSandboxProxySettingsMode::Reconcile;
+    let mut read_roots_override = None;
+    let mut read_roots_include_platform_defaults = false;
+    let mut write_roots_override = None;
+    let mut deny_read_paths_override = Vec::new();
+    let mut deny_write_paths_override = Vec::new();
+    let mut command = None;
+
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            CODEX_HOME_FLAG => codex_home = Some(PathBuf::from(next_flag_value(&mut args, &arg)?)),
+            COMMAND_CWD_FLAG => {
+                command_cwd = Some(absolute_path_arg(next_flag_value(&mut args, &arg)?, &arg)?);
+            }
+            WORKSPACE_ROOT_FLAG => {
+                workspace_roots.push(absolute_path_arg(next_flag_value(&mut args, &arg)?, &arg)?);
+            }
+            ENV_JSON_FLAG => {
+                let value = next_flag_value(&mut args, &arg)?;
+                env_map = Some(serde_json::from_str(&value).context("failed to parse env json")?);
+            }
+            DENY_READ_PATHS_JSON_FLAG => {
+                deny_read_paths_override =
+                    json_flag_value(next_flag_value(&mut args, &arg)?, &arg)?;
+            }
+            DENY_WRITE_PATHS_JSON_FLAG => {
+                deny_write_paths_override =
+                    json_flag_value(next_flag_value(&mut args, &arg)?, &arg)?;
+            }
+            PERMISSION_PROFILE_FLAG => {
+                let value = next_flag_value(&mut args, &arg)?;
+                permission_profile = Some(
+                    serde_json::from_str(&value).context("failed to parse permission profile")?,
+                );
+            }
+            SANDBOX_LEVEL_FLAG => {
+                let value = next_flag_value(&mut args, &arg)?;
+                windows_sandbox_level = Some(parse_windows_sandbox_level(&value)?);
+            }
+            PRIVATE_DESKTOP_FLAG => windows_sandbox_private_desktop = true,
+            PRIVATE_DESKTOP_NAME_FLAG => {
+                private_desktop_name = Some(next_flag_value(&mut args, &arg)?);
+            }
+            PRESERVE_PROXY_SETTINGS_FLAG => {
+                proxy_settings_mode = crate::WindowsSandboxProxySettingsMode::Preserve;
+            }
+            PROXY_ENFORCED_FLAG => proxy_enforced = true,
+            NETWORK_PROXY_RESTRICTING_SID_FLAG => {
+                network_proxy_restricting_sid = Some(next_flag_value(&mut args, &arg)?);
+            }
+            READ_ROOTS_INCLUDE_PLATFORM_DEFAULTS_FLAG => {
+                read_roots_include_platform_defaults = true;
+            }
+            READ_ROOTS_JSON_FLAG => {
+                read_roots_override =
+                    Some(json_flag_value(next_flag_value(&mut args, &arg)?, &arg)?);
+            }
+            WRITE_ROOTS_JSON_FLAG => {
+                write_roots_override =
+                    Some(json_flag_value(next_flag_value(&mut args, &arg)?, &arg)?);
+            }
+            "--" => {
+                command = Some(args.collect::<Vec<_>>());
+                break;
+            }
+            _ => bail!("unexpected windows sandbox wrapper argument: {arg}"),
+        }
+    }
+
+    let codex_home = codex_home.ok_or_else(|| anyhow!("missing required {CODEX_HOME_FLAG}"))?;
+    if !codex_home.is_absolute() {
+        bail!(
+            "{CODEX_HOME_FLAG} must be absolute: {}",
+            codex_home.display()
+        );
+    }
+    let command_cwd = command_cwd.ok_or_else(|| anyhow!("missing required {COMMAND_CWD_FLAG}"))?;
+    if windows_sandbox_private_desktop != private_desktop_name.is_some() {
+        bail!("{PRIVATE_DESKTOP_FLAG} requires {PRIVATE_DESKTOP_NAME_FLAG}");
+    }
+    if workspace_roots.is_empty() {
+        workspace_roots.push(command_cwd.clone());
+    }
+    Ok(WindowsSandboxWrapperRequest {
+        codex_home,
+        command_cwd,
+        workspace_roots,
+        env_map: env_map.ok_or_else(|| anyhow!("missing required {ENV_JSON_FLAG}"))?,
+        permission_profile: permission_profile
+            .ok_or_else(|| anyhow!("missing required {PERMISSION_PROFILE_FLAG}"))?,
+        windows_sandbox_level: windows_sandbox_level
+            .ok_or_else(|| anyhow!("missing required {SANDBOX_LEVEL_FLAG}"))?,
+        windows_sandbox_private_desktop,
+        private_desktop_name,
+        proxy_enforced,
+        network_proxy_restricting_sid,
+        proxy_settings_mode,
+        read_roots_override,
+        read_roots_include_platform_defaults,
+        write_roots_override,
+        deny_read_paths_override,
+        deny_write_paths_override,
+        command: command.ok_or_else(|| anyhow!("missing sandboxed command separator --"))?,
+    })
+}
+
+fn next_flag_value(args: &mut impl Iterator<Item = String>, flag: &str) -> Result<String> {
+    args.next()
+        .ok_or_else(|| anyhow!("missing value for {flag}"))
+}
+
+fn absolute_path_arg(value: String, flag: &str) -> Result<AbsolutePathBuf> {
+    let path = PathBuf::from(value);
+    AbsolutePathBuf::from_absolute_path(path.as_path())
+        .with_context(|| format!("{flag} must be absolute: {}", path.display()))
+}
+
+fn json_flag_value<T: serde::de::DeserializeOwned>(value: String, flag: &str) -> Result<T> {
+    serde_json::from_str(&value).with_context(|| format!("failed to parse {flag}"))
+}
+
+fn parse_windows_sandbox_level(value: &str) -> Result<WindowsSandboxLevel> {
+    match value {
+        "disabled" => Ok(WindowsSandboxLevel::Disabled),
+        "restricted-token" => Ok(WindowsSandboxLevel::RestrictedToken),
+        "elevated" => Ok(WindowsSandboxLevel::Elevated),
+        _ => bail!("invalid windows sandbox level: {value}"),
+    }
+}
+
+#[cfg(test)]
+#[path = "wrapper_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-rs/src/wrapper_tests.rs b/codex-rs/windows-sandbox-rs/src/wrapper_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..b3ba3fa69f6ac8a22ce34ef013c7be2620bdc4ee
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/src/wrapper_tests.rs
@@ -0,0 +1,133 @@
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::models::PermissionProfile;
+use codex_protocol::permissions::NetworkSandboxPolicy;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+
+use super::CODEX_HOME_FLAG;
+use super::CODEX_WINDOWS_SANDBOX_ARG1;
+use super::COMMAND_CWD_FLAG;
+use super::DENY_READ_PATHS_JSON_FLAG;
+use super::DENY_WRITE_PATHS_JSON_FLAG;
+use super::ENV_JSON_FLAG;
+use super::NETWORK_PROXY_RESTRICTING_SID_FLAG;
+use super::PERMISSION_PROFILE_FLAG;
+use super::PRESERVE_PROXY_SETTINGS_FLAG;
+use super::PRIVATE_DESKTOP_FLAG;
+use super::PRIVATE_DESKTOP_NAME_FLAG;
+use super::PROXY_ENFORCED_FLAG;
+use super::READ_ROOTS_INCLUDE_PLATFORM_DEFAULTS_FLAG;
+use super::READ_ROOTS_JSON_FLAG;
+use super::SANDBOX_LEVEL_FLAG;
+use super::WORKSPACE_ROOT_FLAG;
+use super::WRITE_ROOTS_JSON_FLAG;
+use super::create_windows_sandbox_command_args_for_permission_profile;
+use super::parse_windows_sandbox_wrapper_args;
+
+#[test]
+fn windows_wrapper_args_round_trip() {
+    let command_cwd = AbsolutePathBuf::from_absolute_path(Path::new(r"C:\workspace"))
+        .expect("absolute command cwd");
+    let workspace_roots = vec![
+        command_cwd.clone(),
+        AbsolutePathBuf::from_absolute_path(Path::new(r"D:\other-workspace"))
+            .expect("absolute workspace root"),
+    ];
+    let env = HashMap::from([("Path".to_string(), r"C:\Windows\System32".to_string())]);
+    let permission_profile = PermissionProfile::External {
+        network: NetworkSandboxPolicy::Restricted,
+    };
+    let read_roots_override = vec![PathBuf::from(r"C:\read")];
+    let write_roots_override = vec![PathBuf::from(r"C:\write")];
+    let deny_read_paths_override = vec![
+        AbsolutePathBuf::from_absolute_path(Path::new(r"C:\blocked-read"))
+            .expect("absolute deny-read"),
+    ];
+    let deny_write_paths_override = vec![
+        AbsolutePathBuf::from_absolute_path(Path::new(r"C:\blocked-write"))
+            .expect("absolute deny-write"),
+    ];
+
+    let args = create_windows_sandbox_command_args_for_permission_profile(
+        vec![
+            "codex.exe".to_string(),
+            "--codex-run-as-fs-helper".to_string(),
+        ],
+        &command_cwd,
+        workspace_roots.as_slice(),
+        &env,
+        &permission_profile,
+        WindowsSandboxLevel::Elevated,
+        /*windows_sandbox_private_desktop*/ false,
+        /*proxy_enforced*/ true,
+        /*network_proxy_restricting_sid*/ Some("S-1-5-21-100-200-300-400"),
+        crate::WindowsSandboxProxySettingsMode::Preserve,
+        Some(read_roots_override.as_slice()),
+        /*read_roots_include_platform_defaults*/ true,
+        Some(write_roots_override.as_slice()),
+        deny_read_paths_override.as_slice(),
+        deny_write_paths_override.as_slice(),
+        Path::new(r"C:\Users\me\.codex"),
+    )
+    .expect("build wrapper args");
+
+    assert_eq!(args[0], CODEX_WINDOWS_SANDBOX_ARG1);
+    assert!(args.contains(&CODEX_HOME_FLAG.to_string()));
+    assert!(args.contains(&COMMAND_CWD_FLAG.to_string()));
+    assert!(args.contains(&WORKSPACE_ROOT_FLAG.to_string()));
+    assert!(args.contains(&PERMISSION_PROFILE_FLAG.to_string()));
+    assert!(args.contains(&ENV_JSON_FLAG.to_string()));
+    assert!(args.contains(&SANDBOX_LEVEL_FLAG.to_string()));
+    assert!(args.contains(&PROXY_ENFORCED_FLAG.to_string()));
+    assert!(args.contains(&NETWORK_PROXY_RESTRICTING_SID_FLAG.to_string()));
+    assert!(args.contains(&PRESERVE_PROXY_SETTINGS_FLAG.to_string()));
+    assert!(args.contains(&READ_ROOTS_JSON_FLAG.to_string()));
+    assert!(args.contains(&READ_ROOTS_INCLUDE_PLATFORM_DEFAULTS_FLAG.to_string()));
+    assert!(args.contains(&WRITE_ROOTS_JSON_FLAG.to_string()));
+    assert!(args.contains(&DENY_READ_PATHS_JSON_FLAG.to_string()));
+    assert!(args.contains(&DENY_WRITE_PATHS_JSON_FLAG.to_string()));
+
+    let parsed =
+        parse_windows_sandbox_wrapper_args(args[1..].to_vec()).expect("parse wrapper args");
+
+    assert_eq!(
+        parsed.command,
+        vec!["codex.exe", "--codex-run-as-fs-helper"]
+    );
+    assert_eq!(parsed.command_cwd, command_cwd);
+    assert_eq!(parsed.workspace_roots, workspace_roots);
+    assert_eq!(parsed.env_map, env);
+    assert_eq!(parsed.permission_profile, permission_profile);
+    assert_eq!(parsed.windows_sandbox_level, WindowsSandboxLevel::Elevated);
+    assert_eq!(parsed.windows_sandbox_private_desktop, false);
+    assert_eq!(parsed.private_desktop_name, None);
+    assert_eq!(parsed.proxy_enforced, true);
+    assert_eq!(
+        parsed.network_proxy_restricting_sid.as_deref(),
+        Some("S-1-5-21-100-200-300-400")
+    );
+    assert_eq!(
+        parsed.proxy_settings_mode,
+        crate::WindowsSandboxProxySettingsMode::Preserve
+    );
+    assert_eq!(parsed.read_roots_override, Some(read_roots_override));
+    assert_eq!(parsed.read_roots_include_platform_defaults, true);
+    assert_eq!(parsed.write_roots_override, Some(write_roots_override));
+    assert_eq!(parsed.deny_read_paths_override, deny_read_paths_override);
+    assert_eq!(parsed.deny_write_paths_override, deny_write_paths_override);
+
+    let mut private_args = args[1..].to_vec();
+    private_args.insert(/*index*/ 0, PRIVATE_DESKTOP_FLAG.to_string());
+    assert!(parse_windows_sandbox_wrapper_args(private_args.clone()).is_err());
+    let name = "CodexSandboxDesktop-0123456789abcdef";
+    private_args.splice(
+        1..1,
+        [PRIVATE_DESKTOP_NAME_FLAG.to_string(), name.to_string()],
+    );
+    let parsed = parse_windows_sandbox_wrapper_args(private_args).expect("parse named desktop");
+    assert_eq!(parsed.private_desktop_name.as_deref(), Some(name));
+}
diff --git a/codex-rs/windows-sandbox-rs/tests/helper_manifest.rs b/codex-rs/windows-sandbox-rs/tests/helper_manifest.rs
new file mode 100644
index 0000000000000000000000000000000000000000..0428f906aac683584feb18a2236d1acd14c17618
--- /dev/null
+++ b/codex-rs/windows-sandbox-rs/tests/helper_manifest.rs
@@ -0,0 +1,83 @@
+#![cfg(target_os = "windows")]
+
+use anyhow::Context;
+use anyhow::Result;
+use std::io;
+use std::os::windows::ffi::OsStrExt;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation::FreeLibrary;
+use windows_sys::Win32::System::LibraryLoader::FindResourceW;
+use windows_sys::Win32::System::LibraryLoader::LOAD_LIBRARY_AS_DATAFILE;
+use windows_sys::Win32::System::LibraryLoader::LOAD_LIBRARY_AS_IMAGE_RESOURCE;
+use windows_sys::Win32::System::LibraryLoader::LoadLibraryExW;
+use windows_sys::Win32::System::LibraryLoader::LoadResource;
+use windows_sys::Win32::System::LibraryLoader::LockResource;
+use windows_sys::Win32::System::LibraryLoader::SizeofResource;
+use windows_sys::Win32::UI::WindowsAndMessaging::CREATEPROCESS_MANIFEST_RESOURCE_ID;
+use windows_sys::Win32::UI::WindowsAndMessaging::RT_MANIFEST;
+
+/// The setup executable must expose an asInvoker manifest through the Windows resource API.
+#[test]
+fn setup_helper_embeds_as_invoker_manifest() -> Result<()> {
+    let setup_executable = std::env::var_os("CARGO_BIN_EXE_codex-windows-sandbox-setup")
+        .or_else(|| std::env::var_os("CARGO_BIN_EXE_codex_windows_sandbox_setup"))
+        .map(PathBuf::from)
+        .or_else(|| option_env!("CARGO_BIN_EXE_codex-windows-sandbox-setup").map(PathBuf::from))
+        .context("locate the Windows sandbox setup executable")?;
+    std::fs::metadata(&setup_executable)
+        .with_context(|| format!("find setup helper {}", setup_executable.display()))?;
+    let setup_path = setup_executable
+        .as_os_str()
+        .encode_wide()
+        .chain(std::iter::once(0))
+        .collect::<Vec<_>>();
+    let module = unsafe {
+        LoadLibraryExW(
+            setup_path.as_ptr(),
+            /*hfile*/ 0,
+            LOAD_LIBRARY_AS_DATAFILE | LOAD_LIBRARY_AS_IMAGE_RESOURCE,
+        )
+    };
+    if module == 0 {
+        return Err(io::Error::last_os_error())
+            .with_context(|| format!("load setup helper {}", setup_executable.display()));
+    }
+
+    let resource = unsafe {
+        FindResourceW(
+            module,
+            std::ptr::without_provenance(CREATEPROCESS_MANIFEST_RESOURCE_ID as usize),
+            std::ptr::without_provenance(RT_MANIFEST as usize),
+        )
+    };
+    if resource == 0 {
+        return Err(io::Error::last_os_error()).context("find numeric RT_MANIFEST resource ID 1");
+    }
+
+    let resource_size = unsafe { SizeofResource(module, resource) };
+    let loaded_resource = unsafe { LoadResource(module, resource) };
+    if loaded_resource.is_null() {
+        return Err(io::Error::last_os_error()).context("load setup helper manifest resource");
+    }
+    let resource_data = unsafe { LockResource(loaded_resource) };
+    if resource_data.is_null() {
+        return Err(io::Error::last_os_error()).context("read setup helper manifest resource");
+    }
+    let manifest_bytes =
+        unsafe { std::slice::from_raw_parts(resource_data.cast::<u8>(), resource_size as usize) };
+    let manifest = std::str::from_utf8(manifest_bytes).context("decode setup helper manifest")?;
+    assert!(
+        manifest.contains("requestedExecutionLevel level=\"asInvoker\""),
+        "setup helper manifest does not request asInvoker: {manifest}",
+    );
+    assert!(
+        manifest.contains("uiAccess=\"false\""),
+        "setup helper manifest does not disable UI access: {manifest}",
+    );
+
+    if unsafe { FreeLibrary(module) } == 0 {
+        return Err(io::Error::last_os_error()).context("unload setup helper resource module");
+    }
+
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-service/src/installation_record.rs b/codex-rs/windows-sandbox-service/src/installation_record.rs
new file mode 100644
index 0000000000000000000000000000000000000000..10f9e76ecdcb7790978f35327609575af9885978
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/installation_record.rs
@@ -0,0 +1,77 @@
+//! Finds desktop-created directory ownership; storage is shared with sandbox setup.
+
+use std::ffi::OsString;
+use std::io;
+use std::os::windows::ffi::OsStringExt;
+use std::path::Path;
+use std::path::PathBuf;
+use std::ptr;
+
+use anyhow::Context;
+use anyhow::Result;
+pub(crate) use codex_windows_sandbox::CORE_INSTALLATION_KEY;
+pub(crate) use codex_windows_sandbox::DesktopInstallation;
+pub(crate) use codex_windows_sandbox::INSTALLATION_KEY;
+pub(crate) use codex_windows_sandbox::INSTALLATION_VALUE;
+pub(crate) use codex_windows_sandbox::InstallationRecord;
+pub(crate) use codex_windows_sandbox::RuntimeAccountRegistration;
+pub(crate) use codex_windows_sandbox::RuntimeRegistration;
+pub(crate) use codex_windows_sandbox::load_installation as load;
+pub(crate) use codex_windows_sandbox::remove_installation as remove;
+pub(crate) use codex_windows_sandbox::save_installation as save_runtime;
+use codex_windows_sandbox::validate_local_directory_path;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::UI::Shell::GetUserProfileDirectoryW;
+
+const DESKTOP_INSTALLATION_MARKER: &str = ".desktop-created";
+
+// Read this app-owned marker while impersonating the authenticated user. The
+// desktop writes it only when creating the home. Cache cleanup does not need ownership.
+pub(crate) fn read_desktop_installation(
+    home: &Path,
+    user_token: foundation::HANDLE,
+) -> Result<DesktopInstallation> {
+    let mut length = 0;
+    unsafe { GetUserProfileDirectoryW(user_token, ptr::null_mut(), &mut length) };
+    let mut profile = vec![0_u16; length as usize];
+    if unsafe { GetUserProfileDirectoryW(user_token, profile.as_mut_ptr(), &mut length) } == 0 {
+        return Err(io::Error::last_os_error()).context("read sandbox owner's profile directory");
+    }
+    let cache_home =
+        PathBuf::from(OsString::from_wide(&profile[..length as usize - 1])).join(".cache");
+    validate_local_directory_path(&cache_home)?;
+    Ok(DesktopInstallation {
+        created_codex_home: home.join(DESKTOP_INSTALLATION_MARKER).is_file(),
+        cache_home,
+    })
+}
+
+pub(crate) fn load_runtime() -> Result<Option<InstallationRecord>> {
+    Ok(load()?.filter(|record| record.runtime.is_some()))
+}
+
+pub(crate) fn is_current_package_family(record: &InstallationRecord) -> Result<bool> {
+    Ok(record.runtime()?.package_family.eq_ignore_ascii_case(
+        &windows::ApplicationModel::Package::Current()?
+            .Id()?
+            .FamilyName()?
+            .to_string(),
+    ))
+}
+
+pub(crate) fn save(mut record: InstallationRecord) -> Result<InstallationRecord> {
+    let _setup_lock = codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+
+    record.runtime = None;
+    if let Some(current) = load_runtime()? {
+        let family = windows::ApplicationModel::Package::Current()?
+            .Id()?
+            .FamilyName()?;
+        current.admit_owner(&record, &family.to_string())?;
+        // The helper wait may have admitted another account. Preserve fresh Core
+        // state instead of overwriting it with the caller's owner-only snapshot.
+        record.runtime = current.runtime;
+    }
+    save_runtime(&record)?;
+    Ok(record)
+}
diff --git a/codex-rs/windows-sandbox-service/src/ipc.rs b/codex-rs/windows-sandbox-service/src/ipc.rs
new file mode 100644
index 0000000000000000000000000000000000000000..c60c86210757d138b6631e7f5a6ec7f4c27895db
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/ipc.rs
@@ -0,0 +1,368 @@
+//! Authenticated local IPC for the Windows sandbox provisioning service.
+//! Expected service limitations defer provisioning to the client's elevated helper;
+//! authentication and policy rejections remain errors.
+//! Shutdown wakeups are retried until the listener connects or stops.
+
+mod authentication;
+mod home;
+mod listener;
+mod request;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+pub(crate) use authentication::ClientIdentity;
+use authentication::authenticate_client;
+use codex_windows_sandbox::FramedProvisioningMessage;
+use codex_windows_sandbox::PROVISIONING_PROTOCOL_VERSION;
+use codex_windows_sandbox::ProvisioningMessage;
+use codex_windows_sandbox::SandboxProvisioningResponse;
+use codex_windows_sandbox::to_wide;
+use codex_windows_sandbox::write_provisioning_frame;
+pub(crate) use home::OwnedHandle;
+pub(crate) use home::pin_directory;
+pub(crate) use home::pin_existing_ancestors;
+pub(crate) use request::ProvisioningRequest;
+pub(crate) use request::ServiceRequest;
+use request::validate_request;
+use std::mem::size_of;
+use std::ptr;
+use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+use std::time::Instant;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+use windows_sys::Win32::System::Pipes as pipes;
+
+use crate::installation_record::InstallationRecord;
+
+const MAX_REQUEST_BYTES: usize = 4096;
+const MAX_RESPONSE_MESSAGE_BYTES: usize = 512;
+const REQUEST_IDLE_TIMEOUT: Duration = Duration::from_secs(5);
+const PIPE_USER_ACCESS: &str = "0x0012019b";
+
+/// The service cannot complete this request; the interactive setup helper may still work.
+#[derive(Debug)]
+pub(crate) struct ServiceUnavailable(pub(crate) &'static str);
+
+impl std::fmt::Display for ServiceUnavailable {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(self.0)
+    }
+}
+
+impl std::error::Error for ServiceUnavailable {}
+
+#[derive(Debug, Eq, PartialEq)]
+enum PipeConnection {
+    Connected,
+    Disconnected,
+}
+
+pub(crate) fn run(
+    shutdown: Arc<AtomicBool>,
+    on_ready: impl FnOnce() -> Result<()>,
+    on_authenticated_user: impl Fn(
+        InstallationRecord,
+        OwnedHandle,
+        codex_windows_sandbox::SetupRuntime,
+    ) -> Result<InstallationRecord>,
+    on_session_change: impl Fn() -> Result<()>,
+) -> Result<()> {
+    if shutdown.load(Ordering::Acquire) {
+        return Ok(());
+    }
+    let mut listener = listener::ProvisioningListener::open()?;
+    on_ready().context("publish provisioning listener readiness")?;
+
+    // Refresh before blocking even if a direct setup claim's zero-byte wake was lost.
+    while refresh_session(&shutdown, &on_session_change)
+        .context("refresh the recorded sandbox owner")?
+    {
+        let connection = accept_pipe_connection(listener.pipe.0)?;
+        // A session refresh can finish cleanup. Never dispatch an already accepted
+        // connection after it stops the listener, including a disconnected wakeup.
+        if !refresh_session(&shutdown, &on_session_change)
+            .context("restore the signed-in user's uninstall listener")?
+        {
+            break;
+        }
+        if connection == PipeConnection::Disconnected {
+            continue;
+        }
+
+        let authorized_process =
+            match crate::package_identity::authorize_client_process(listener.pipe.0) {
+                Ok(process) => process,
+                Err(_) => {
+                    unsafe { pipes::DisconnectNamedPipe(listener.pipe.0) };
+                    continue;
+                }
+            };
+        let result = handle_request(
+            listener.pipe.0,
+            &authorized_process,
+            &listener.sandbox_sid,
+            &shutdown,
+            &on_authenticated_user,
+        );
+        let response = match result {
+            Ok(response) => response,
+            Err(error) if error.is::<crate::registered_runtime::RegistrationInterrupted>() => {
+                return Err(error);
+            }
+            Err(error) if error.is::<ServiceUnavailable>() => {
+                SandboxProvisioningResponse::Unavailable
+            }
+            Err(error) => {
+                eprintln!("sandbox provisioning request failed: {error}");
+                SandboxProvisioningResponse::Error {
+                    message: response_error_message(&error),
+                }
+            }
+        };
+        let response = FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION,
+            message: ProvisioningMessage::ProvisionSandboxResponse { payload: response },
+        };
+        write_response(&listener.pipe, &response, &shutdown)?;
+        if shutdown.load(Ordering::Acquire) {
+            break;
+        }
+        listener = listener.refresh()?;
+    }
+    Ok(())
+}
+fn refresh_session(
+    shutdown: &AtomicBool,
+    on_session_change: impl FnOnce() -> Result<()>,
+) -> Result<bool> {
+    if shutdown.load(Ordering::Acquire) {
+        return Ok(false);
+    }
+    on_session_change()?;
+    Ok(!shutdown.load(Ordering::Acquire))
+}
+
+/// Sends one frame, then waits briefly for the client to close before disconnecting.
+fn write_response(
+    pipe: &OwnedHandle,
+    response: &FramedProvisioningMessage,
+    shutdown: &AtomicBool,
+) -> Result<()> {
+    let mut frame = Vec::new();
+    write_provisioning_frame(&mut frame, response)
+        .context("serialize sandbox provisioning response")?;
+    let mut written = 0;
+    let sent = unsafe {
+        filesystem::WriteFile(
+            pipe.0,
+            frame.as_ptr(),
+            frame.len() as u32,
+            &mut written,
+            ptr::null_mut(),
+        )
+    };
+    if sent != 0 {
+        let deadline = Instant::now() + Duration::from_secs(1);
+        while !shutdown.load(Ordering::Acquire) && Instant::now() < deadline {
+            if unsafe {
+                pipes::PeekNamedPipe(
+                    pipe.0,
+                    ptr::null_mut(),
+                    0,
+                    ptr::null_mut(),
+                    ptr::null_mut(),
+                    ptr::null_mut(),
+                )
+            } == 0
+            {
+                break;
+            }
+            std::thread::sleep(Duration::from_millis(10));
+        }
+    }
+    Ok(())
+}
+
+fn response_error_message(error: &anyhow::Error) -> String {
+    let mut message = String::new();
+    for character in error.to_string().chars() {
+        let character = if character.is_control() {
+            ' '
+        } else {
+            character
+        };
+        if message.len() + character.len_utf8() > MAX_RESPONSE_MESSAGE_BYTES {
+            break;
+        }
+        message.push(character);
+    }
+    message
+}
+
+fn accept_pipe_connection(pipe: HANDLE) -> Result<PipeConnection> {
+    if unsafe { pipes::ConnectNamedPipe(pipe, ptr::null_mut()) } != 0 {
+        return Ok(PipeConnection::Connected);
+    }
+
+    let error = unsafe { foundation::GetLastError() };
+    match error {
+        foundation::ERROR_PIPE_CONNECTED => Ok(PipeConnection::Connected),
+        foundation::ERROR_NO_DATA | foundation::ERROR_BROKEN_PIPE => {
+            if unsafe { pipes::DisconnectNamedPipe(pipe) } == 0 {
+                let reset_error = std::io::Error::last_os_error();
+                if reset_error.raw_os_error() != Some(foundation::ERROR_PIPE_NOT_CONNECTED as i32) {
+                    return Err(reset_error).context("reset disconnected provisioning client");
+                }
+            }
+            Ok(PipeConnection::Disconnected)
+        }
+        _ => Err(std::io::Error::from_raw_os_error(error as i32))
+            .context("accept provisioning client"),
+    }
+}
+
+pub(crate) fn wake(pipe_name: &str, is_stopped: impl Fn() -> bool) {
+    let pipe_name = to_wide(pipe_name);
+    while !is_stopped() {
+        let handle = unsafe {
+            filesystem::CreateFileW(
+                pipe_name.as_ptr(),
+                foundation::GENERIC_WRITE,
+                /*dwsharemode*/ 0,
+                ptr::null(),
+                filesystem::OPEN_EXISTING,
+                /*dwflagsandattributes*/ 0,
+                /*htemplatefile*/ 0,
+            )
+        };
+        if handle != foundation::INVALID_HANDLE_VALUE {
+            unsafe { foundation::CloseHandle(handle) };
+            return;
+        }
+        // A disconnected instance cannot accept the wakeup until ConnectNamedPipe runs.
+        std::thread::sleep(Duration::from_millis(25));
+    }
+}
+
+fn pipe_security_descriptor(sandbox_sid: &str) -> String {
+    format!("D:P(D;;GA;;;{sandbox_sid})(A;;GA;;;SY)(A;;GA;;;BA)(A;;{PIPE_USER_ACCESS};;;IU)")
+}
+
+fn handle_request(
+    pipe: HANDLE,
+    authorized_process: &crate::package_identity::AuthorizedClientProcess,
+    sandbox_sid: &[u8],
+    shutdown: &AtomicBool,
+    on_authenticated_user: &dyn Fn(
+        InstallationRecord,
+        OwnedHandle,
+        codex_windows_sandbox::SetupRuntime,
+    ) -> Result<InstallationRecord>,
+) -> Result<SandboxProvisioningResponse> {
+    let deadline = Instant::now() + REQUEST_IDLE_TIMEOUT;
+    let mut request = [0_u8; MAX_REQUEST_BYTES];
+    let mut request_length = 0;
+    loop {
+        if shutdown.load(Ordering::Acquire) {
+            bail!("service is stopping");
+        }
+        if Instant::now() >= deadline {
+            bail!("provisioning request timed out");
+        }
+        let mut available = 0;
+        if unsafe {
+            pipes::PeekNamedPipe(
+                pipe,
+                ptr::null_mut(),
+                0,
+                ptr::null_mut(),
+                &mut available,
+                ptr::null_mut(),
+            )
+        } == 0
+        {
+            return Err(std::io::Error::last_os_error()).context("inspect provisioning request");
+        }
+        if available as usize > MAX_REQUEST_BYTES - request_length {
+            bail!("provisioning request exceeds size limit");
+        }
+        if available != 0 {
+            let mut read = 0;
+            if unsafe {
+                filesystem::ReadFile(
+                    pipe,
+                    request[request_length..].as_mut_ptr(),
+                    available,
+                    &mut read,
+                    ptr::null_mut(),
+                )
+            } == 0
+            {
+                return Err(std::io::Error::last_os_error()).context("read provisioning request");
+            }
+            if read == 0 {
+                bail!("provisioning client sent an empty request");
+            }
+            request_length += read as usize;
+            let received = &request[..request_length];
+            if received.len() >= size_of::<u32>() {
+                let payload_length =
+                    u32::from_le_bytes([received[0], received[1], received[2], received[3]])
+                        as usize;
+                if payload_length > MAX_REQUEST_BYTES - size_of::<u32>() {
+                    bail!("provisioning request exceeds size limit");
+                }
+                let frame_length = size_of::<u32>() + payload_length;
+                if request_length > frame_length {
+                    bail!("provisioning requests must contain exactly one IPC frame");
+                }
+                if request_length == frame_length {
+                    break;
+                }
+            }
+            continue;
+        }
+        std::thread::sleep(Duration::from_millis(25));
+    }
+
+    let request = validate_request(&request[..request_length])?;
+    let (identity, policy_result) =
+        authenticate_client(pipe, authorized_process, sandbox_sid, &request)?;
+    if let Err(error) = policy_result {
+        if is_config_parse_error(&error) {
+            return Ok(SandboxProvisioningResponse::Unavailable);
+        }
+        crate::service::log_error(
+            crate::service::EVENT_REQUEST_REJECTED,
+            &format!("Codex sandbox provisioning was rejected by administrator policy: {error}"),
+        );
+        return Err(error)
+            .context("requested sandbox settings violate administrator-controlled machine policy");
+    }
+    crate::provisioning::run(
+        identity,
+        request,
+        sandbox_sid,
+        shutdown,
+        on_authenticated_user,
+    )
+}
+
+fn is_config_parse_error(error: &anyhow::Error) -> bool {
+    error.chain().any(|cause| {
+        cause.is::<toml::de::Error>()
+            || cause
+                .downcast_ref::<std::io::Error>()
+                .and_then(std::io::Error::get_ref)
+                .is_some_and(<dyn std::error::Error + Send + Sync>::is::<toml::de::Error>)
+    })
+}
+
+#[cfg(test)]
+#[path = "ipc_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-service/src/ipc/authentication.rs b/codex-rs/windows-sandbox-service/src/ipc/authentication.rs
new file mode 100644
index 0000000000000000000000000000000000000000..40f56d0294921cd2a32ef5da98b3e4a32e32d621
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/ipc/authentication.rs
@@ -0,0 +1,223 @@
+//! Authenticates provisioning clients and validates impersonated machine policy.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_windows_sandbox::DirectoryOpenDisposition;
+use codex_windows_sandbox::SetupRuntime;
+use codex_windows_sandbox::create_directory_guard;
+use codex_windows_sandbox::string_from_sid_bytes;
+use std::ffi::OsString;
+use std::ffi::c_void;
+use std::mem::size_of;
+use std::os::windows::ffi::OsStringExt;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::IntoRawHandle;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security as security;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+use windows_sys::Win32::System::Pipes as pipes;
+use windows_sys::Win32::System::Threading as threading;
+
+use super::home::OwnedHandle;
+use super::home::prepare_codex_home;
+use super::request::ServiceRequest;
+
+pub(crate) struct ClientIdentity {
+    pub(crate) account: String,
+    pub(crate) codex_home: PathBuf,
+    pub(crate) user_sid: String,
+    pub(crate) session_id: u32,
+    // The requested route, authenticated against the held client's installed image.
+    pub(crate) runtime: SetupRuntime,
+    pub(crate) token: OwnedHandle,
+    pub(crate) desktop_installation: Option<crate::installation_record::DesktopInstallation>,
+    // Pins and guards remain live through registration and the provisioning helper.
+    pub(crate) directory_handles: Vec<OwnedHandle>,
+}
+
+pub(super) fn authenticate_client(
+    pipe: HANDLE,
+    authorized_process: &crate::package_identity::AuthorizedClientProcess,
+    sandbox_sid: &[u8],
+    request: &ServiceRequest,
+) -> Result<(ClientIdentity, Result<()>)> {
+    std::thread::scope(|scope| {
+        scope
+            .spawn(|| {
+                let identity = authenticate_impersonated_client(
+                    pipe,
+                    authorized_process,
+                    sandbox_sid,
+                    request,
+                )?;
+                let policy_result = match request {
+                    // Registration does not provision resources or change sandbox policy.
+                    ServiceRequest::RegisterInstallation { .. } => Ok(()),
+                    ServiceRequest::ProvisionSandbox(request) => {
+                        crate::machine_policy::validate_provisioning_settings(
+                            &identity.codex_home,
+                            &request.settings,
+                            &request.listeners,
+                            identity.token.0,
+                        )
+                    }
+                };
+                Ok((identity, policy_result))
+            })
+            .join()
+            .map_err(|_| anyhow::anyhow!("provisioning client authentication thread panicked"))?
+    })
+}
+
+fn authenticate_impersonated_client(
+    pipe: HANDLE,
+    authorized_process: &crate::package_identity::AuthorizedClientProcess,
+    sandbox_sid: &[u8],
+    request: &ServiceRequest,
+) -> Result<ClientIdentity> {
+    // Pin the group generation through identity capture.
+    // Release this lock before the provisioning worker checks machine policy.
+    let _setup_lock = codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+    anyhow::ensure!(
+        codex_windows_sandbox::resolve_sid(codex_windows_sandbox::SANDBOX_USERS_GROUP)
+            .is_ok_and(|current| current == sandbox_sid),
+        codex_windows_sandbox::SANDBOX_GROUP_CHANGED
+    );
+    if unsafe { pipes::ImpersonateNamedPipeClient(pipe) } == 0 {
+        return Err(std::io::Error::last_os_error()).context("impersonate provisioning client");
+    }
+    let mut raw_token = 0;
+    if unsafe {
+        threading::OpenThreadToken(
+            threading::GetCurrentThread(),
+            security::TOKEN_QUERY | security::TOKEN_IMPERSONATE,
+            1,
+            &mut raw_token,
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("open provisioning client token");
+    }
+    let token = OwnedHandle(raw_token);
+    crate::package_identity::authorize_client(authorized_process, token.0)
+        .context("authorize the packaged Codex provisioning client")?;
+    let mut session = 0_u32;
+    let mut returned = 0_u32;
+    if unsafe {
+        security::GetTokenInformation(
+            token.0,
+            security::TokenSessionId,
+            (&raw mut session).cast(),
+            size_of::<u32>() as u32,
+            &mut returned,
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("read provisioning client session");
+    }
+    if session == 0 {
+        bail!("non-interactive service accounts cannot request provisioning");
+    }
+
+    let mut is_sandbox_member = 0;
+    if unsafe {
+        security::CheckTokenMembership(
+            token.0,
+            sandbox_sid.as_ptr() as *mut c_void,
+            &mut is_sandbox_member,
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("check sandbox group membership");
+    }
+    if is_sandbox_member != 0 {
+        bail!("sandbox accounts cannot request provisioning");
+    }
+
+    let user = unsafe { codex_windows_sandbox::get_user_sid_bytes(token.0) }
+        .context("read provisioning client identity")?;
+    let user_sid = string_from_sid_bytes(&user).map_err(anyhow::Error::msg)?;
+    let account = unsafe { codex_windows_sandbox::account_name_from_sid(user.as_ptr() as _) }
+        .context("resolve provisioning client account")?;
+    let runtime = crate::package_identity::authorize_setup_runtime(authorized_process, request)?;
+    let requested_home = match request {
+        ServiceRequest::RegisterInstallation { codex_home } => codex_home,
+        ServiceRequest::ProvisionSandbox(request) => &request.codex_home,
+    };
+    let (codex_home, handles) = match request {
+        ServiceRequest::ProvisionSandbox(request) => prepare_codex_home(
+            requested_home,
+            runtime,
+            if request.refresh_only {
+                DirectoryOpenDisposition::OpenExisting
+            } else {
+                DirectoryOpenDisposition::OpenOrCreate
+            },
+        )?,
+        ServiceRequest::RegisterInstallation { .. } => {
+            // Registration must not create the sandbox directories or change their ACLs.
+            codex_windows_sandbox::validate_local_directory_path(requested_home)?;
+            let mut handles = Vec::new();
+            super::home::pin_existing_ancestors(requested_home, &mut handles)?;
+            // Uninstall removes sandbox files as SYSTEM; read access cannot grant that authority.
+            let home = super::home::pin_directory(
+                requested_home,
+                filesystem::FILE_ADD_FILE
+                    | filesystem::FILE_ADD_SUBDIRECTORY
+                    | filesystem::WRITE_DAC,
+                DirectoryOpenDisposition::OpenExisting,
+            )?;
+            // Bind the guard to the authorized directory before resolving its pathname.
+            let guard = create_directory_guard(unsafe { BorrowedHandle::borrow_raw(home.0 as _) })?;
+            drop(super::home::pin_directory(
+                requested_home,
+                filesystem::FILE_READ_ATTRIBUTES,
+                DirectoryOpenDisposition::OpenExisting,
+            )?);
+            // Preserve the authorized directory's literal name (including trailing dots).
+            let mut buffer = vec![0_u16; 260];
+            let path = loop {
+                let length = unsafe {
+                    filesystem::GetFinalPathNameByHandleW(
+                        home.0,
+                        buffer.as_mut_ptr(),
+                        buffer.len() as u32,
+                        filesystem::FILE_NAME_NORMALIZED | filesystem::VOLUME_NAME_DOS,
+                    )
+                };
+                if length == 0 {
+                    return Err(std::io::Error::last_os_error())
+                        .context("resolve authorized desktop home");
+                }
+                if (length as usize) < buffer.len() {
+                    break PathBuf::from(OsString::from_wide(&buffer[..length as usize]));
+                }
+                buffer.resize(length as usize, /*value*/ 0);
+            };
+            handles.push(home);
+            handles.push(OwnedHandle(guard.into_raw_handle() as HANDLE));
+            (path, handles)
+        }
+    };
+    let desktop_installation =
+        crate::installation_record::read_desktop_installation(&codex_home, token.0)
+            .inspect_err(|_| {
+                crate::service::log_error(
+                    crate::service::EVENT_SERVICE_FAILED,
+                    "unable to read desktop directory ownership; preserving desktop directories",
+                );
+            })
+            .ok();
+    Ok(ClientIdentity {
+        account,
+        codex_home,
+        user_sid,
+        session_id: session,
+        runtime,
+        token,
+        desktop_installation,
+        directory_handles: handles,
+    })
+}
diff --git a/codex-rs/windows-sandbox-service/src/ipc/home.rs b/codex-rs/windows-sandbox-service/src/ipc/home.rs
new file mode 100644
index 0000000000000000000000000000000000000000..6ddbfd90a13407ee4f253efc46c5041c7524cbd9
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/ipc/home.rs
@@ -0,0 +1,183 @@
+//! Validates and pins local Codex home and sandbox directories, keeping sandbox
+//! leaves nonempty so they cannot become junctions during provisioning.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_windows_sandbox::DirectoryOpenDisposition;
+use codex_windows_sandbox::SetupRuntime;
+use codex_windows_sandbox::create_directory_guard;
+use codex_windows_sandbox::open_directory_no_reparse;
+use codex_windows_sandbox::to_wide;
+use codex_windows_sandbox::validate_local_directory_path;
+use std::os::windows::fs::MetadataExt;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::IntoRawHandle;
+use std::path::Component;
+use std::path::Path;
+use std::path::PathBuf;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+
+use super::ServiceUnavailable;
+
+const DRIVE_FIXED: u32 = 3;
+
+pub(crate) struct OwnedHandle(pub(crate) HANDLE);
+
+impl Drop for OwnedHandle {
+    fn drop(&mut self) {
+        if self.0 != 0 && self.0 != foundation::INVALID_HANDLE_VALUE {
+            unsafe { foundation::CloseHandle(self.0) };
+        }
+    }
+}
+
+pub(super) fn prepare_codex_home(
+    requested: &Path,
+    runtime: SetupRuntime,
+    disposition: DirectoryOpenDisposition,
+) -> Result<(PathBuf, Vec<OwnedHandle>)> {
+    let directory_count = match runtime {
+        SetupRuntime::Registered => 3,
+        SetupRuntime::Legacy => 4,
+    };
+    let mut handles = Vec::new();
+    validate_local_directory_path(requested)?;
+    let requested_root = requested
+        .ancestors()
+        .last()
+        .context("find the root of the requested Codex home")?;
+    if unsafe { filesystem::GetDriveTypeW(to_wide(requested_root.as_os_str()).as_ptr()) }
+        != DRIVE_FIXED
+    {
+        return Err(ServiceUnavailable("Codex home must be located on a fixed local drive").into());
+    }
+    let parent = requested
+        .parent()
+        .context("Codex home must have an existing parent directory")?;
+    pin_existing_ancestors(parent, &mut handles)?;
+    handles.push(pin_directory(
+        requested,
+        filesystem::FILE_READ_ATTRIBUTES,
+        disposition,
+    )?);
+    let home = requested
+        .canonicalize()
+        .with_context(|| format!("canonicalize Codex home {}", requested.display()))?;
+    validate_local_directory_path(&home)?;
+    let root = home
+        .ancestors()
+        .last()
+        .context("find the root of the requested Codex home")?;
+    if unsafe { filesystem::GetDriveTypeW(to_wide(root.as_os_str()).as_ptr()) } != DRIVE_FIXED {
+        return Err(ServiceUnavailable("Codex home must be located on a fixed local drive").into());
+    }
+    if home != requested {
+        pin_existing_ancestors(&home, &mut handles)?;
+    }
+    let sandbox_bin = home.join(".sandbox-bin");
+    for (index, directory) in [
+        home.as_path(),
+        &home.join(".sandbox"),
+        &home.join(".sandbox-secrets"),
+        &sandbox_bin,
+    ]
+    .into_iter()
+    .take(directory_count)
+    .enumerate()
+    {
+        let mut access = filesystem::FILE_READ_ATTRIBUTES
+            | filesystem::FILE_ADD_FILE
+            | filesystem::FILE_ADD_SUBDIRECTORY;
+        if index != 0 {
+            access |= filesystem::WRITE_DAC;
+        }
+        let handle = pin_directory(directory, access, disposition)
+            .map_err(|error| {
+                // Older elevated installs omitted WRITE_DAC; let the interactive helper repair it.
+                if directory == sandbox_bin.as_path()
+                    && error.downcast_ref::<std::io::Error>().is_some_and(|error| {
+                        error.raw_os_error() == Some(foundation::ERROR_ACCESS_DENIED as i32)
+                    })
+                {
+                    error.context(ServiceUnavailable("sandbox binary directory needs elevated repair"))
+                } else {
+                    error
+                }
+            })
+            .with_context(|| {
+            if index == 0 {
+                format!(
+                    "requesting user must be permitted to write Codex home {}",
+                    directory.display()
+                )
+            } else {
+                format!(
+                    "requesting user must be permitted to write and modify sandbox directory ACL {}",
+                    directory.display()
+                )
+            }
+        })?;
+        if index != 0 {
+            // The handle is owned here and remains live until the guard is installed.
+            let directory_handle = unsafe { BorrowedHandle::borrow_raw(handle.0 as _) };
+            let guard = create_directory_guard(directory_handle)?;
+            // Reject conversion before guard creation; after creation the retained
+            // file prevents this directory from becoming empty and being converted.
+            drop(pin_directory(
+                directory,
+                filesystem::FILE_READ_ATTRIBUTES,
+                DirectoryOpenDisposition::OpenExisting,
+            )?);
+            handles.push(OwnedHandle(guard.into_raw_handle() as HANDLE));
+        }
+        handles.push(handle);
+        if index == 0 {
+            continue;
+        }
+        for entry in std::fs::read_dir(directory)? {
+            let entry = entry?;
+            let metadata = entry.path().symlink_metadata()?;
+            if metadata.file_attributes() & filesystem::FILE_ATTRIBUTE_REPARSE_POINT != 0 {
+                bail!("refusing reparse point {}", entry.path().display());
+            }
+        }
+    }
+
+    // Pinned parent handles prevent directory replacement, but existing helper file
+    // opens remain pathname-based; hardlink/leaf-file races need a follow-up redesign.
+    Ok((home, handles))
+}
+
+pub(crate) fn pin_existing_ancestors(path: &Path, handles: &mut Vec<OwnedHandle>) -> Result<()> {
+    let mut current = PathBuf::new();
+    for component in path.components() {
+        current.push(component.as_os_str());
+        if !matches!(component, Component::Prefix(_)) && current.is_absolute() {
+            handles.push(pin_directory(
+                &current,
+                filesystem::FILE_READ_ATTRIBUTES,
+                DirectoryOpenDisposition::OpenExisting,
+            )?);
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn pin_directory(
+    path: &Path,
+    access: u32,
+    disposition: DirectoryOpenDisposition,
+) -> Result<OwnedHandle> {
+    let handle = open_directory_no_reparse(
+        path,
+        // Metadata-only access does not enforce no-delete sharing.
+        access | filesystem::FILE_TRAVERSE,
+        filesystem::FILE_SHARE_READ | filesystem::FILE_SHARE_WRITE,
+        disposition,
+    )
+    .with_context(|| format!("pin {}", path.display()))?;
+    Ok(OwnedHandle(handle.into_raw_handle() as HANDLE))
+}
diff --git a/codex-rs/windows-sandbox-service/src/ipc/listener.rs b/codex-rs/windows-sandbox-service/src/ipc/listener.rs
new file mode 100644
index 0000000000000000000000000000000000000000..de6d3595b4ac47c142f537d89ac5560e418cae07
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/ipc/listener.rs
@@ -0,0 +1,118 @@
+//! Owns a provisioning pipe and the sandbox group generation in its deny rule.
+//! Replaces stale listeners only after a response, closing the old pipe before creating another.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_windows_sandbox::ensure_sandbox_users_group;
+use codex_windows_sandbox::string_from_sid_bytes;
+use codex_windows_sandbox::to_wide;
+use std::mem::size_of;
+use std::ptr;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::Security as security;
+use windows_sys::Win32::Security::Authorization as authorization;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+use windows_sys::Win32::System::Pipes as pipes;
+
+use super::MAX_REQUEST_BYTES;
+use super::OwnedHandle;
+use super::pipe_security_descriptor;
+
+pub(super) struct ProvisioningListener {
+    pub(super) pipe: OwnedHandle,
+    pub(super) sandbox_sid: Vec<u8>,
+    _descriptor: SecurityDescriptor,
+}
+
+impl ProvisioningListener {
+    pub(super) fn open() -> Result<Self> {
+        let pipe_name = codex_windows_sandbox::windows_sandbox_service_pipe_name()?;
+        let _setup_lock =
+            codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+        if crate::installation_record::load()?
+            .and_then(|record| record.runtime)
+            .is_some_and(|runtime| runtime.retiring.is_some())
+        {
+            bail!("interrupted sandbox cleanup requires repair");
+        }
+        let sandbox_sid = ensure_sandbox_users_group()?;
+        let (descriptor, pipe) = create_provisioning_pipe(&pipe_name, &sandbox_sid)?;
+        Ok(Self {
+            pipe,
+            sandbox_sid,
+            _descriptor: descriptor,
+        })
+    }
+
+    pub(super) fn refresh(self) -> Result<Self> {
+        let current_group = {
+            let _setup_lock =
+                codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+            codex_windows_sandbox::resolve_sid(codex_windows_sandbox::SANDBOX_USERS_GROUP)
+        };
+        if current_group.is_ok_and(|current| current == self.sandbox_sid) {
+            unsafe { pipes::DisconnectNamedPipe(self.pipe.0) };
+            return Ok(self);
+        }
+        // A stale deny SID was refused before dispatch. Close this first-instance
+        // pipe before rebuilding its descriptor for the current group generation.
+        drop(self);
+        Self::open()
+    }
+}
+
+struct SecurityDescriptor(security::PSECURITY_DESCRIPTOR);
+
+impl Drop for SecurityDescriptor {
+    fn drop(&mut self) {
+        unsafe { foundation::LocalFree(self.0 as foundation::HLOCAL) };
+    }
+}
+
+/// Preserves the existing listener and descriptor lifetimes.
+fn create_provisioning_pipe(
+    pipe_name: &str,
+    sandbox_sid: &[u8],
+) -> Result<(SecurityDescriptor, OwnedHandle)> {
+    let sid_string = string_from_sid_bytes(sandbox_sid).map_err(anyhow::Error::msg)?;
+    let sddl = pipe_security_descriptor(&sid_string);
+    let mut descriptor: security::PSECURITY_DESCRIPTOR = ptr::null_mut();
+    if unsafe {
+        authorization::ConvertStringSecurityDescriptorToSecurityDescriptorW(
+            to_wide(sddl).as_ptr(),
+            authorization::SDDL_REVISION_1,
+            &mut descriptor,
+            ptr::null_mut(),
+        )
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("create provisioning pipe DACL");
+    }
+    let descriptor = SecurityDescriptor(descriptor);
+    let attributes = security::SECURITY_ATTRIBUTES {
+        nLength: size_of::<security::SECURITY_ATTRIBUTES>() as u32,
+        lpSecurityDescriptor: descriptor.0,
+        bInheritHandle: 0,
+    };
+
+    let pipe = unsafe {
+        pipes::CreateNamedPipeW(
+            to_wide(pipe_name).as_ptr(),
+            filesystem::PIPE_ACCESS_DUPLEX | filesystem::FILE_FLAG_FIRST_PIPE_INSTANCE,
+            pipes::PIPE_TYPE_BYTE
+                | pipes::PIPE_READMODE_BYTE
+                | pipes::PIPE_WAIT
+                | pipes::PIPE_REJECT_REMOTE_CLIENTS,
+            1,
+            1024,
+            MAX_REQUEST_BYTES as u32,
+            0,
+            &attributes,
+        )
+    };
+    if pipe == foundation::INVALID_HANDLE_VALUE {
+        return Err(std::io::Error::last_os_error()).context("create provisioning pipe");
+    }
+    Ok((descriptor, OwnedHandle(pipe)))
+}
diff --git a/codex-rs/windows-sandbox-service/src/ipc/request.rs b/codex-rs/windows-sandbox-service/src/ipc/request.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f084cac3cdb99677a9778c8eb117a9325a91582d
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/ipc/request.rs
@@ -0,0 +1,97 @@
+//! Validates framed provisioning requests and normalizes proxy settings.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_windows_sandbox::PROVISIONING_PROTOCOL_VERSION;
+use codex_windows_sandbox::ProvisioningMessage;
+use codex_windows_sandbox::WindowsSandboxProvisioningSettings;
+use codex_windows_sandbox::WindowsSandboxProxyListeners;
+use codex_windows_sandbox::read_provisioning_frame;
+use std::path::PathBuf;
+
+use super::MAX_REQUEST_BYTES;
+
+#[derive(Debug, Eq, PartialEq)]
+pub(crate) enum ServiceRequest {
+    RegisterInstallation { codex_home: PathBuf },
+    ProvisionSandbox(ProvisioningRequest),
+}
+
+#[derive(Debug, Eq, PartialEq)]
+pub(crate) struct ProvisioningRequest {
+    pub(crate) codex_home: PathBuf,
+    pub(crate) registered_core: bool,
+    pub(crate) refresh_only: bool,
+    pub(crate) listeners: WindowsSandboxProxyListeners,
+    pub(crate) settings: WindowsSandboxProvisioningSettings,
+}
+
+pub(super) fn validate_request(request: &[u8]) -> Result<ServiceRequest> {
+    if request.len() > MAX_REQUEST_BYTES {
+        bail!("provisioning request exceeds size limit");
+    }
+    let mut reader = request;
+    let frame = read_provisioning_frame(&mut reader)
+        .context("invalid framed provisioning request")?
+        .context("provisioning client sent an empty request")?;
+    if !reader.is_empty() {
+        bail!("provisioning requests must contain exactly one IPC frame");
+    }
+
+    if frame.version != PROVISIONING_PROTOCOL_VERSION {
+        bail!(
+            "unsupported provisioning request version: {}",
+            frame.version
+        );
+    }
+    let request = match frame.message {
+        ProvisioningMessage::RegisterInstallationRequest { codex_home } => {
+            validate_home(&codex_home)?;
+            return Ok(ServiceRequest::RegisterInstallation {
+                codex_home: PathBuf::from(codex_home),
+            });
+        }
+        ProvisioningMessage::ProvisionSandboxRequest { payload } => payload,
+        ProvisioningMessage::ProvisionSandboxResponse { .. } => bail!("expected a service request"),
+    };
+    validate_home(&request.codex_home)?;
+    if request.refresh_only && !request.registered_core {
+        bail!("registration refresh requires registered Core");
+    }
+    let mut settings = request.settings;
+    let mut listeners = request.listeners;
+    for ports in [
+        &mut settings.proxy_ports,
+        &mut listeners.http_ports,
+        &mut listeners.socks_ports,
+    ] {
+        if ports.contains(&0) {
+            bail!("provisioning request includes an invalid proxy port");
+        }
+        ports.sort_unstable();
+        ports.dedup();
+    }
+    if listeners
+        .http_ports
+        .iter()
+        .chain(&listeners.socks_ports)
+        .any(|port| !settings.proxy_ports.contains(port))
+    {
+        bail!("provisioning listener is absent from the proxy settings");
+    }
+    Ok(ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+        codex_home: PathBuf::from(request.codex_home),
+        registered_core: request.registered_core,
+        refresh_only: request.refresh_only,
+        listeners,
+        settings,
+    }))
+}
+
+fn validate_home(home: &str) -> Result<()> {
+    if home.is_empty() || home.contains(['\0', '\r', '\n']) {
+        bail!("Codex home is empty or contains an invalid control character");
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-service/src/ipc_tests.rs b/codex-rs/windows-sandbox-service/src/ipc_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..92839d3e17676fc5f3d6bffa5c886c3776ffc87e
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/ipc_tests.rs
@@ -0,0 +1,750 @@
+use super::OwnedHandle;
+use super::PipeConnection;
+use super::ServiceRequest;
+use super::accept_pipe_connection;
+use super::home::prepare_codex_home;
+use super::is_config_parse_error;
+use super::pin_existing_ancestors;
+use super::pipe_security_descriptor;
+use super::refresh_session;
+use super::request::ProvisioningRequest;
+use super::validate_request;
+use super::wake;
+use codex_windows_sandbox::DirectoryOpenDisposition;
+use codex_windows_sandbox::FramedProvisioningMessage;
+use codex_windows_sandbox::PROVISIONING_PROTOCOL_VERSION;
+use codex_windows_sandbox::ProvisioningMessage;
+use codex_windows_sandbox::SandboxProvisioningRequest;
+use codex_windows_sandbox::SandboxProvisioningResponse;
+use codex_windows_sandbox::SetupRuntime;
+use codex_windows_sandbox::WindowsSandboxProvisioningSettings;
+use codex_windows_sandbox::WindowsSandboxProxyListeners;
+use codex_windows_sandbox::read_provisioning_frame;
+use codex_windows_sandbox::to_wide;
+use codex_windows_sandbox::write_provisioning_frame;
+use pretty_assertions::assert_eq;
+use std::path::Path;
+use std::path::PathBuf;
+use std::ptr;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use std::sync::mpsc;
+use std::time::Duration;
+use std::time::Instant;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+use windows_sys::Win32::Storage::Packaging::Appx;
+use windows_sys::Win32::System::Pipes as pipes;
+
+#[test]
+fn session_refresh_observes_cleanup_completion_before_dispatch() {
+    let shutdown = AtomicBool::new(false);
+    assert!(
+        !refresh_session(&shutdown, || {
+            shutdown.store(true, Ordering::Release);
+            Ok(())
+        })
+        .unwrap()
+    );
+}
+
+#[test]
+fn session_refresh_preserves_authoritative_stop() {
+    let shutdown = AtomicBool::new(true);
+    assert!(!refresh_session(&shutdown, || panic!("stopped listener must not refresh")).unwrap());
+    assert!(shutdown.load(Ordering::Acquire));
+}
+
+#[test]
+fn session_refresh_keeps_admission_open_without_cleanup() {
+    let shutdown = AtomicBool::new(false);
+    assert!(refresh_session(&shutdown, || Ok(())).unwrap());
+    assert!(!shutdown.load(Ordering::Acquire));
+}
+
+#[test]
+fn session_refresh_propagates_cleanup_failure() {
+    let shutdown = AtomicBool::new(false);
+    let error = refresh_session(&shutdown, || anyhow::bail!("cleanup failed")).unwrap_err();
+    assert!(error.to_string().contains("cleanup failed"));
+}
+
+#[test]
+fn provisioning_request_rejects_malformed_registered_flag() {
+    for registered_core in [
+        serde_json::json!("true"),
+        serde_json::json!(1),
+        serde_json::json!(null),
+    ] {
+        let bytes = serde_json::to_vec(&serde_json::json!({
+            "version": PROVISIONING_PROTOCOL_VERSION,
+            "type": "provision_sandbox_request",
+            "payload": {
+                "codex_home": "C:\\Users\\owner\\.codex",
+                "registered_core": registered_core,
+                "settings": WindowsSandboxProvisioningSettings::default(),
+                "listeners": WindowsSandboxProxyListeners::default(),
+            },
+        }))
+        .unwrap();
+        let mut frame = (bytes.len() as u32).to_le_bytes().to_vec();
+        frame.extend(bytes);
+        assert!(validate_request(&frame).is_err());
+    }
+}
+
+#[test]
+fn runtime_registration_is_an_explicit_wire_opt_in() {
+    let request = SandboxProvisioningRequest {
+        codex_home: r"C:\Users\owner\.codex".to_string(),
+        registered_core: false,
+        refresh_only: false,
+        settings: WindowsSandboxProvisioningSettings::default(),
+        listeners: WindowsSandboxProxyListeners::default(),
+    };
+    let serialized = serde_json::to_value(&request).unwrap();
+    assert_eq!(
+        serialized,
+        serde_json::json!({
+            "codex_home": request.codex_home,
+            "settings": request.settings,
+            "listeners": request.listeners,
+        }),
+    );
+    let legacy: SandboxProvisioningRequest = serde_json::from_value(serialized).unwrap();
+    assert!(matches!(
+        validate_request(&framed_request(legacy)).unwrap(),
+        ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+            registered_core: false,
+            refresh_only: false,
+            ..
+        })
+    ));
+    let registered = SandboxProvisioningRequest {
+        registered_core: true,
+        refresh_only: false,
+        ..request
+    };
+    assert!(matches!(
+        validate_request(&framed_request(registered)).unwrap(),
+        ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+            registered_core: true,
+            refresh_only: false,
+            ..
+        })
+    ));
+}
+
+#[test]
+fn registration_refresh_is_explicit_and_requires_registered_core() {
+    let mut request = SandboxProvisioningRequest {
+        codex_home: r"C:\Users\owner\.codex".to_string(),
+        registered_core: false,
+        refresh_only: true,
+        settings: WindowsSandboxProvisioningSettings::default(),
+        listeners: WindowsSandboxProxyListeners::default(),
+    };
+    assert!(validate_request(&framed_request(request.clone())).is_err());
+    request.registered_core = true;
+    assert!(matches!(
+        validate_request(&framed_request(request)).unwrap(),
+        ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+            registered_core: true,
+            refresh_only: true,
+            ..
+        })
+    ));
+}
+
+#[test]
+fn runtime_registration_has_no_unpackaged_or_foreground_identity_exemption() {
+    let service = Some("OpenAI.Codex_testpublisher");
+    assert!(crate::package_identity::require_runtime_package_family(service, service).is_ok());
+    for (client, service) in [
+        (None, service),
+        (service, None),
+        (None, None),
+        (Some("OpenAI.CodexBeta_testpublisher"), service),
+        (Some("OpenAI.Codex_otherpublisher"), service),
+    ] {
+        assert!(crate::package_identity::require_runtime_package_family(client, service).is_err());
+    }
+}
+
+fn framed_request(request: SandboxProvisioningRequest) -> Vec<u8> {
+    let mut frame = Vec::new();
+    write_provisioning_frame(
+        &mut frame,
+        &FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION,
+            message: ProvisioningMessage::ProvisionSandboxRequest { payload: request },
+        },
+    )
+    .unwrap();
+    frame
+}
+
+#[test]
+fn unavailable_response_round_trips_through_provisioning_frame() {
+    let mut frame = Vec::new();
+    write_provisioning_frame(
+        &mut frame,
+        &FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION,
+            message: ProvisioningMessage::ProvisionSandboxResponse {
+                payload: SandboxProvisioningResponse::Unavailable,
+            },
+        },
+    )
+    .unwrap();
+
+    assert!(matches!(
+        read_provisioning_frame(frame.as_slice()).unwrap(),
+        Some(FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION,
+            message: ProvisioningMessage::ProvisionSandboxResponse {
+                payload: SandboxProvisioningResponse::Unavailable,
+            },
+        })
+    ));
+}
+
+#[test]
+fn config_parse_errors_are_distinguished_from_policy_and_io_failures() {
+    let schema_error = codex_core::config::deserialize_config_toml_with_base(
+        toml::from_str(r#"model_verbosity = "future-verbosity""#).unwrap(),
+        Path::new(r"C:\CodexTest"),
+    )
+    .unwrap_err();
+    let contents = "[";
+    let parse_error = toml::from_str::<toml::Value>(contents).unwrap_err();
+    let syntax_error = codex_config::io_error_from_config_error(
+        std::io::ErrorKind::InvalidData,
+        codex_config::config_error_from_toml("config.toml", contents, parse_error.clone()),
+        Some(parse_error),
+    );
+    for error in [schema_error, syntax_error] {
+        assert!(is_config_parse_error(
+            &anyhow::Error::new(error).context("load managed configuration"),
+        ));
+    }
+
+    for error in [
+        anyhow::anyhow!("managed policy does not permit the elevated Windows sandbox"),
+        anyhow::Error::new(std::io::Error::from_raw_os_error(
+            foundation::ERROR_ACCESS_DENIED as i32,
+        )),
+        anyhow::Error::new(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "invalid credentials",
+        )),
+    ] {
+        assert!(!is_config_parse_error(
+            &error.context("load managed configuration"),
+        ));
+    }
+}
+
+#[test]
+fn provisioning_request_preserves_home_spaces_and_unicode() {
+    let request = framed_request(SandboxProvisioningRequest {
+        codex_home: "D:\\Codex Homes\\Jos\u{00e9}\\.codex".to_string(),
+        registered_core: false,
+        refresh_only: false,
+        settings: WindowsSandboxProvisioningSettings::default(),
+        listeners: WindowsSandboxProxyListeners::default(),
+    });
+    assert_eq!(
+        validate_request(&request).unwrap(),
+        ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+            codex_home: PathBuf::from("D:\\Codex Homes\\Jos\u{00e9}\\.codex"),
+            registered_core: false,
+            refresh_only: false,
+            listeners: WindowsSandboxProxyListeners::default(),
+            settings: WindowsSandboxProvisioningSettings::default(),
+        })
+    );
+}
+
+#[test]
+fn structured_provisioning_request_carries_normalized_proxy_settings() {
+    for (http_port, socks_port, proxy_ports) in
+        [(8081, 3128, vec![3128, 8081]), (8081, 8081, vec![8081])]
+    {
+        let request = framed_request(SandboxProvisioningRequest {
+            codex_home: "D:\\Codex Homes\\Jos\u{00e9}\\.codex".to_string(),
+            registered_core: false,
+            refresh_only: false,
+            settings: WindowsSandboxProvisioningSettings {
+                proxy_ports: vec![http_port, socks_port, http_port],
+                allow_local_binding: true,
+            },
+            listeners: WindowsSandboxProxyListeners {
+                http_ports: vec![http_port, http_port],
+                socks_ports: vec![socks_port],
+            },
+        });
+        assert_eq!(
+            validate_request(&request).unwrap(),
+            ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+                codex_home: PathBuf::from("D:\\Codex Homes\\Jos\u{00e9}\\.codex"),
+                registered_core: false,
+                refresh_only: false,
+                listeners: WindowsSandboxProxyListeners {
+                    http_ports: vec![http_port],
+                    socks_ports: vec![socks_port],
+                },
+                settings: WindowsSandboxProvisioningSettings {
+                    proxy_ports,
+                    allow_local_binding: true,
+                },
+            }),
+        );
+    }
+}
+
+#[test]
+fn structured_provisioning_request_accepts_independent_and_additional_proxy_ports() {
+    for (http_ports, socks_ports, proxy_ports) in [
+        (vec![3128], vec![], vec![3128]),
+        (vec![], vec![1080], vec![1080]),
+        (vec![3128, 8080], vec![1080], vec![1080, 1082, 3128, 8080]),
+    ] {
+        let settings = WindowsSandboxProvisioningSettings {
+            proxy_ports,
+            allow_local_binding: false,
+        };
+        let listeners = WindowsSandboxProxyListeners {
+            http_ports,
+            socks_ports,
+        };
+        let request = framed_request(SandboxProvisioningRequest {
+            codex_home: r"C:\Users\alice\.codex".to_string(),
+            registered_core: false,
+            refresh_only: false,
+            settings: settings.clone(),
+            listeners: listeners.clone(),
+        });
+        assert_eq!(
+            validate_request(&request).unwrap(),
+            ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+                codex_home: PathBuf::from(r"C:\Users\alice\.codex"),
+                registered_core: false,
+                refresh_only: false,
+                settings,
+                listeners,
+            })
+        );
+    }
+}
+
+#[test]
+fn structured_provisioning_request_accepts_disabled_listeners() {
+    let request = framed_request(SandboxProvisioningRequest {
+        codex_home: r"C:\Users\alice\.codex".to_string(),
+        registered_core: false,
+        refresh_only: false,
+        settings: WindowsSandboxProvisioningSettings::default(),
+        listeners: WindowsSandboxProxyListeners::default(),
+    });
+    assert_eq!(
+        validate_request(&request).unwrap(),
+        ServiceRequest::ProvisionSandbox(ProvisioningRequest {
+            codex_home: PathBuf::from(r"C:\Users\alice\.codex"),
+            registered_core: false,
+            refresh_only: false,
+            listeners: WindowsSandboxProxyListeners::default(),
+            settings: WindowsSandboxProvisioningSettings::default(),
+        })
+    );
+}
+
+#[test]
+fn structured_provisioning_request_requires_exact_version_fields_and_framing() {
+    let valid = SandboxProvisioningRequest {
+        codex_home: r"C:\Users\alice\.codex".to_string(),
+        registered_core: false,
+        refresh_only: false,
+        settings: WindowsSandboxProvisioningSettings::default(),
+        listeners: WindowsSandboxProxyListeners::default(),
+    };
+    let mut invalid_version = Vec::new();
+    write_provisioning_frame(
+        &mut invalid_version,
+        &FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION + 1,
+            message: ProvisioningMessage::ProvisionSandboxRequest {
+                payload: valid.clone(),
+            },
+        },
+    )
+    .unwrap();
+    assert!(validate_request(&invalid_version).is_err());
+
+    let mut unexpected_message = Vec::new();
+    write_provisioning_frame(
+        &mut unexpected_message,
+        &FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION,
+            message: ProvisioningMessage::ProvisionSandboxResponse {
+                payload: SandboxProvisioningResponse::Ok,
+            },
+        },
+    )
+    .unwrap();
+    assert!(validate_request(&unexpected_message).is_err());
+
+    let valid = framed_request(valid);
+    assert!(validate_request(&valid[..valid.len() - 1]).is_err());
+    let mut duplicate = valid.clone();
+    duplicate.extend_from_slice(&valid);
+    assert!(validate_request(&duplicate).is_err());
+}
+
+#[test]
+fn structured_provisioning_request_rejects_invalid_or_inconsistent_ports() {
+    for (proxy_ports, http_ports, socks_ports) in [
+        (vec![0], vec![], vec![]),
+        (vec![3128], vec![0], vec![]),
+        (vec![3128], vec![3128], vec![0]),
+        (vec![3128], vec![3128], vec![8081]),
+    ] {
+        let request = framed_request(SandboxProvisioningRequest {
+            codex_home: r"C:\Users\alice\.codex".to_string(),
+            registered_core: false,
+            refresh_only: false,
+            settings: WindowsSandboxProvisioningSettings {
+                proxy_ports,
+                allow_local_binding: false,
+            },
+            listeners: WindowsSandboxProxyListeners {
+                http_ports,
+                socks_ports,
+            },
+        });
+        assert!(validate_request(&request).is_err());
+    }
+}
+
+#[test]
+fn provisioning_request_rejects_empty_control_characters_and_invalid_utf8() {
+    for home in ["", "C:\\safe\0evil", "C:\\safe\rmore", "C:\\safe\nmore"] {
+        let request = framed_request(SandboxProvisioningRequest {
+            codex_home: home.to_string(),
+            registered_core: false,
+            refresh_only: false,
+            settings: WindowsSandboxProvisioningSettings::default(),
+            listeners: WindowsSandboxProxyListeners::default(),
+        });
+        assert!(validate_request(&request).is_err());
+    }
+
+    let mut invalid_utf8 = framed_request(SandboxProvisioningRequest {
+        codex_home: r"C:\Users\alice\.codex".to_string(),
+        registered_core: false,
+        refresh_only: false,
+        settings: WindowsSandboxProvisioningSettings::default(),
+        listeners: WindowsSandboxProxyListeners::default(),
+    });
+    invalid_utf8[std::mem::size_of::<u32>()] = 0xff;
+    assert!(validate_request(&invalid_utf8).is_err());
+}
+
+#[test]
+fn unpackaged_pipe_clients_are_rejected_before_sending_a_request() {
+    let mut family_length = 0;
+    let package_status =
+        unsafe { Appx::GetCurrentPackageFamilyName(&mut family_length, ptr::null_mut()) };
+    if package_status != foundation::APPMODEL_ERROR_NO_PACKAGE {
+        assert_eq!(package_status, foundation::ERROR_INSUFFICIENT_BUFFER);
+        return;
+    }
+
+    static NEXT_PIPE_INSTANCE: AtomicU64 = AtomicU64::new(0);
+    let name = to_wide(format!(
+        r"\\.\pipe\OpenAI.CodexSandbox.Tests.{}.{}",
+        std::process::id(),
+        NEXT_PIPE_INSTANCE.fetch_add(1, Ordering::Relaxed)
+    ));
+    let server = unsafe {
+        pipes::CreateNamedPipeW(
+            name.as_ptr(),
+            filesystem::PIPE_ACCESS_DUPLEX | filesystem::FILE_FLAG_FIRST_PIPE_INSTANCE,
+            pipes::PIPE_TYPE_BYTE
+                | pipes::PIPE_READMODE_BYTE
+                | pipes::PIPE_WAIT
+                | pipes::PIPE_REJECT_REMOTE_CLIENTS,
+            1,
+            1024,
+            1024,
+            0,
+            ptr::null(),
+        )
+    };
+    assert_ne!(server, foundation::INVALID_HANDLE_VALUE);
+    let server = OwnedHandle(server);
+
+    let client = unsafe {
+        filesystem::CreateFileW(
+            name.as_ptr(),
+            foundation::GENERIC_READ | foundation::GENERIC_WRITE,
+            0,
+            ptr::null(),
+            filesystem::OPEN_EXISTING,
+            0,
+            0,
+        )
+    };
+    assert_ne!(client, foundation::INVALID_HANDLE_VALUE);
+    let _client = OwnedHandle(client);
+
+    let connected = unsafe { pipes::ConnectNamedPipe(server.0, ptr::null_mut()) };
+    assert!(
+        connected != 0 || unsafe { foundation::GetLastError() } == foundation::ERROR_PIPE_CONNECTED
+    );
+
+    let error = match crate::package_identity::authorize_client_process(server.0) {
+        Ok(_) => panic!("an unpackaged client was authorized without sending a request"),
+        Err(error) => error,
+    };
+    assert!(
+        error
+            .to_string()
+            .contains("installed Codex package identity"),
+        "unexpected package authorization failure: {error:#}"
+    );
+}
+
+#[test]
+fn disconnected_pipe_clients_do_not_prevent_subsequent_connections() {
+    let pipe_name = format!(
+        r"\\.\pipe\OpenAI.CodexSandbox.DisconnectTests.{}",
+        std::process::id()
+    );
+    let name = to_wide(&pipe_name);
+    let server = unsafe {
+        pipes::CreateNamedPipeW(
+            name.as_ptr(),
+            filesystem::PIPE_ACCESS_DUPLEX | filesystem::FILE_FLAG_FIRST_PIPE_INSTANCE,
+            pipes::PIPE_TYPE_BYTE
+                | pipes::PIPE_READMODE_BYTE
+                | pipes::PIPE_WAIT
+                | pipes::PIPE_REJECT_REMOTE_CLIENTS,
+            1,
+            1024,
+            1024,
+            0,
+            ptr::null(),
+        )
+    };
+    assert_ne!(server, foundation::INVALID_HANDLE_VALUE);
+    let server = OwnedHandle(server);
+
+    let first_client = unsafe {
+        filesystem::CreateFileW(
+            name.as_ptr(),
+            foundation::GENERIC_READ | foundation::GENERIC_WRITE,
+            0,
+            ptr::null(),
+            filesystem::OPEN_EXISTING,
+            0,
+            0,
+        )
+    };
+    assert_ne!(first_client, foundation::INVALID_HANDLE_VALUE);
+    drop(OwnedHandle(first_client));
+
+    assert_eq!(
+        accept_pipe_connection(server.0).unwrap(),
+        PipeConnection::Disconnected
+    );
+
+    let server_handle = server.0;
+    let listener = std::thread::spawn(move || accept_pipe_connection(server_handle));
+    let available = unsafe { pipes::WaitNamedPipeW(name.as_ptr(), 5_000) };
+    assert_ne!(
+        available,
+        0,
+        "wait for replacement named-pipe listener: {}",
+        std::io::Error::last_os_error()
+    );
+    let next_client = unsafe {
+        filesystem::CreateFileW(
+            name.as_ptr(),
+            foundation::GENERIC_READ | foundation::GENERIC_WRITE,
+            0,
+            ptr::null(),
+            filesystem::OPEN_EXISTING,
+            0,
+            0,
+        )
+    };
+    assert_ne!(
+        next_client,
+        foundation::INVALID_HANDLE_VALUE,
+        "connect replacement named-pipe client: {}",
+        std::io::Error::last_os_error()
+    );
+    let next_client = OwnedHandle(next_client);
+    assert_eq!(
+        listener.join().expect("join named-pipe listener").unwrap(),
+        PipeConnection::Connected
+    );
+
+    drop(next_client);
+    assert_ne!(unsafe { pipes::DisconnectNamedPipe(server.0) }, 0);
+
+    let timeout = Duration::from_secs(5);
+    let deadline = Instant::now() + timeout;
+    let (checks_tx, checks_rx) = mpsc::channel();
+    let waker = std::thread::spawn(move || {
+        wake(&pipe_name, || {
+            let _ = checks_tx.send(());
+            Instant::now() >= deadline
+        });
+    });
+    checks_rx.recv_timeout(timeout).unwrap();
+    // The second check proves a wake failed before the listener started reconnecting.
+    checks_rx.recv_timeout(timeout).unwrap();
+
+    let (accepted_tx, accepted_rx) = mpsc::channel();
+    let listener = std::thread::spawn(move || {
+        let _ = accepted_tx.send(accept_pipe_connection(server.0));
+        drop(server);
+    });
+    let accepted = accepted_rx.recv_timeout(timeout);
+    waker.join().expect("join shutdown waker");
+    // The wake handle may close before ConnectNamedPipe observes the connection.
+    assert!(
+        accepted
+            .expect("shutdown wake should unblock the listener")
+            .is_ok()
+    );
+    listener.join().expect("join shutdown listener");
+}
+
+#[test]
+fn unexpected_pipe_connection_errors_remain_fatal() {
+    let error = accept_pipe_connection(foundation::INVALID_HANDLE_VALUE).unwrap_err();
+
+    assert_eq!(
+        error
+            .downcast_ref::<std::io::Error>()
+            .and_then(std::io::Error::raw_os_error),
+        Some(foundation::ERROR_INVALID_HANDLE as i32)
+    );
+}
+
+#[test]
+fn pin_existing_ancestors_accepts_drive_and_verbatim_drive_roots() {
+    let executable = std::env::current_exe().unwrap().canonicalize().unwrap();
+    let verbatim_root = executable.ancestors().last().unwrap();
+    let ordinary_root = PathBuf::from(
+        verbatim_root
+            .to_str()
+            .unwrap()
+            .strip_prefix(r"\\?\")
+            .unwrap(),
+    );
+
+    for root in [ordinary_root.as_path(), verbatim_root] {
+        let mut handles = Vec::new();
+        pin_existing_ancestors(root, &mut handles).unwrap();
+        assert_eq!(handles.len(), 1);
+    }
+}
+
+#[test]
+fn pipe_descriptor_denies_sandbox_group_before_interactive_users() {
+    let descriptor = pipe_security_descriptor("S-1-5-21-11-12-13-14");
+    let deny = descriptor.find("(D;;GA;;;S-1-5-21-11-12-13-14)").unwrap();
+    let interactive = descriptor.find("(A;;0x0012019b;;;IU)").unwrap();
+    assert!(deny < interactive);
+}
+
+#[test]
+fn registered_home_preparation_does_not_touch_the_legacy_bin() -> anyhow::Result<()> {
+    let root = std::env::temp_dir().join(format!(
+        "codex-service-home-{:?}",
+        windows::core::GUID::new()?
+    ));
+    std::fs::create_dir(&root)?;
+    let result = (|| -> anyhow::Result<()> {
+        let home = root.join(".codex");
+        std::fs::create_dir(&home)?;
+        let bin = home.join(".sandbox-bin");
+        let marker = b"legacy bin is deliberately not a directory";
+        std::fs::write(&bin, marker)?;
+
+        assert!(
+            prepare_codex_home(
+                &home,
+                SetupRuntime::Registered,
+                DirectoryOpenDisposition::OpenExisting,
+            )
+            .is_err()
+        );
+        assert!(!home.join(".sandbox").exists());
+        assert!(!home.join(".sandbox-secrets").exists());
+        let (_, handles) = prepare_codex_home(
+            &home,
+            SetupRuntime::Registered,
+            DirectoryOpenDisposition::OpenOrCreate,
+        )?;
+        assert!(home.join(".sandbox").is_dir());
+        assert!(home.join(".sandbox-secrets").is_dir());
+        assert_eq!(std::fs::read(&bin)?.as_slice(), marker.as_slice());
+        drop(handles);
+
+        // Legacy still validates and pins the copied-bin path.
+        let (_, handles) = prepare_codex_home(
+            &home,
+            SetupRuntime::Registered,
+            DirectoryOpenDisposition::OpenExisting,
+        )?;
+        drop(handles);
+        assert!(
+            prepare_codex_home(
+                &home,
+                SetupRuntime::Legacy,
+                DirectoryOpenDisposition::OpenOrCreate,
+            )
+            .is_err()
+        );
+        assert_eq!(std::fs::read(&bin)?.as_slice(), marker.as_slice());
+        std::fs::remove_file(&bin)?;
+        let (_, handles) = prepare_codex_home(
+            &home,
+            SetupRuntime::Legacy,
+            DirectoryOpenDisposition::OpenOrCreate,
+        )?;
+        assert!(bin.is_dir());
+        drop(handles);
+
+        Ok(())
+    })();
+    std::fs::remove_dir_all(&root)?;
+    result
+}
+
+#[test]
+fn installation_registration_requires_no_sandbox_settings() {
+    let mut frame = Vec::new();
+    write_provisioning_frame(
+        &mut frame,
+        &FramedProvisioningMessage {
+            version: PROVISIONING_PROTOCOL_VERSION,
+            message: ProvisioningMessage::RegisterInstallationRequest {
+                codex_home: r"C:\Users\alice\.codex".to_string(),
+            },
+        },
+    )
+    .unwrap();
+    assert_eq!(
+        validate_request(&frame).unwrap(),
+        ServiceRequest::RegisterInstallation {
+            codex_home: PathBuf::from(r"C:\Users\alice\.codex")
+        },
+    );
+}
diff --git a/codex-rs/windows-sandbox-service/src/lib.rs b/codex-rs/windows-sandbox-service/src/lib.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4924e7acca03bd2ac8a2cb6c42d70911b4333b85
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/lib.rs
@@ -0,0 +1,43 @@
+use anyhow::Result;
+
+#[cfg(windows)]
+mod installation_record;
+#[cfg(windows)]
+mod ipc;
+
+#[cfg(windows)]
+mod machine_policy;
+#[cfg(windows)]
+mod package_identity;
+#[cfg(windows)]
+mod package_lifecycle;
+#[cfg(windows)]
+mod provisioning;
+#[cfg(windows)]
+mod registered_runtime;
+#[cfg(windows)]
+mod service;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum RunMode {
+    Service,
+    #[cfg(debug_assertions)]
+    Foreground,
+}
+
+pub fn run(mode: RunMode) -> Result<()> {
+    #[cfg(windows)]
+    {
+        match mode {
+            RunMode::Service => service::run(),
+            #[cfg(debug_assertions)]
+            RunMode::Foreground => service::run_foreground(),
+        }
+    }
+
+    #[cfg(not(windows))]
+    {
+        let _ = mode;
+        anyhow::bail!("the Codex sandbox service is only available on Windows")
+    }
+}
diff --git a/codex-rs/windows-sandbox-service/src/machine_policy.rs b/codex-rs/windows-sandbox-service/src/machine_policy.rs
new file mode 100644
index 0000000000000000000000000000000000000000..85c43f78ae62ac23dec9436e97f4416cbec8b520
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/machine_policy.rs
@@ -0,0 +1,138 @@
+//! Validates provisioning requests against the standard managed configuration layers.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_cloud_config::cloud_config_bundle_loader_for_storage_without_cache;
+use codex_config::ConfigLoadOptions;
+use codex_config::ConfigRequirementsToml;
+use codex_config::types::WindowsSandboxModeToml;
+use codex_core::config::bootstrap_auth_config;
+use codex_core::config::load_config_toml_with_layer_stack;
+use codex_windows_sandbox::WindowsSandboxProvisioningSettings;
+use codex_windows_sandbox::WindowsSandboxProxyListeners;
+use std::path::Path;
+use std::sync::Arc;
+use tokio::sync::Notify;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security::ImpersonateLoggedOnUser;
+
+pub(crate) fn validate_provisioning_settings(
+    codex_home: &Path,
+    settings: &WindowsSandboxProvisioningSettings,
+    listeners: &WindowsSandboxProxyListeners,
+    impersonation_token: HANDLE,
+) -> Result<()> {
+    let impersonation_failure = Arc::new(Notify::new());
+    let worker_impersonation_failure = Arc::clone(&impersonation_failure);
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .on_thread_start(move || {
+            if unsafe { ImpersonateLoggedOnUser(impersonation_token) } == 0 {
+                let error = std::io::Error::last_os_error();
+                worker_impersonation_failure.notify_one();
+                panic!(
+                    "failed to impersonate provisioning client on configuration runtime thread: {error}"
+                );
+            }
+        })
+        .build()
+        .context("start managed configuration runtime")?;
+    let requirements = runtime.block_on(async {
+        tokio::select! {
+            biased;
+            () = impersonation_failure.notified() => {
+                Err(anyhow::anyhow!("configuration runtime worker failed to impersonate the provisioning client"))
+            },
+            result = async {
+                let mut bootstrap_config = load_config_toml_with_layer_stack(
+                    codex_home,
+                    /*cwd*/ None,
+                    Vec::new(),
+                    ConfigLoadOptions::default(),
+                )
+                .await
+                .context("load bootstrap configuration")?;
+                // Use the default cloud-policy endpoint unless managed requirements override it.
+                bootstrap_config.config_toml.chatgpt_base_url = None;
+                let cloud_config_bundle = cloud_config_bundle_loader_for_storage_without_cache(
+                    bootstrap_auth_config(codex_home, &bootstrap_config)
+                        .context("resolve cloud configuration authentication")?,
+                    /*enable_codex_api_key_env*/ false,
+                )
+                .await
+                .context("initialize cloud configuration authentication")?;
+                let config = load_config_toml_with_layer_stack(
+                    codex_home,
+                    /*cwd*/ None,
+                    Vec::new(),
+                    ConfigLoadOptions {
+                        cloud_config_bundle,
+                        ..Default::default()
+                    },
+                )
+                .await
+                .context("load managed configuration")?;
+
+                Ok::<_, anyhow::Error>(config.config_layer_stack.requirements_toml().clone())
+            } => result,
+        }
+    })?;
+
+    validate_requirements(settings, listeners, &requirements)
+        .context("enforce managed provisioning requirements")
+}
+
+fn validate_requirements(
+    settings: &WindowsSandboxProvisioningSettings,
+    listeners: &WindowsSandboxProxyListeners,
+    requirements: &ConfigRequirementsToml,
+) -> Result<()> {
+    if requirements
+        .windows
+        .as_ref()
+        .and_then(|windows| windows.allowed_sandbox_implementations.as_ref())
+        .is_some_and(|allowed| !allowed.contains(&WindowsSandboxModeToml::Elevated))
+    {
+        bail!("managed policy does not permit the elevated Windows sandbox");
+    }
+
+    let Some(network) = requirements.network.as_ref() else {
+        return Ok(());
+    };
+    if network.enabled == Some(false)
+        && (settings.allow_local_binding || !settings.proxy_ports.is_empty())
+    {
+        bail!("managed policy disables sandbox network access");
+    }
+    if settings.allow_local_binding && network.allow_local_binding == Some(false) {
+        bail!("managed policy does not permit local network binding");
+    }
+    if let Some(required) = network.http_port
+        && let Some(actual) = listeners.http_ports.iter().find(|port| **port != required)
+    {
+        bail!("managed policy does not permit HTTP proxy port {actual}");
+    }
+    if let Some(required) = network.socks_port
+        && let Some(actual) = listeners.socks_ports.iter().find(|port| **port != required)
+    {
+        bail!("managed policy does not permit SOCKS proxy port {actual}");
+    }
+    // Omitting listener identities must not bypass managed port restrictions.
+    if network.http_port.is_some() || network.socks_port.is_some() {
+        for port in &settings.proxy_ports {
+            if !listeners.http_ports.contains(port)
+                && !listeners.socks_ports.contains(port)
+                && network.http_port != Some(*port)
+                && network.socks_port != Some(*port)
+            {
+                bail!("managed policy does not permit unclassified proxy port {port}");
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "machine_policy_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-service/src/machine_policy_tests.rs b/codex-rs/windows-sandbox-service/src/machine_policy_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..17b92359ccb3d4515a29196554e60888816b062f
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/machine_policy_tests.rs
@@ -0,0 +1,277 @@
+use anyhow::Result;
+use codex_config::ConfigRequirementsToml;
+use codex_windows_sandbox::WindowsSandboxProvisioningSettings;
+use codex_windows_sandbox::WindowsSandboxProxyListeners;
+
+fn validate_requirements(
+    settings: &WindowsSandboxProvisioningSettings,
+    listeners: WindowsSandboxProxyListeners,
+    contents: &str,
+) -> Result<()> {
+    let requirements: ConfigRequirementsToml = toml::from_str(contents)?;
+    super::validate_requirements(settings, &listeners, &requirements)
+}
+
+#[test]
+fn runtime_worker_impersonation_failure_rejects_provisioning() {
+    let error = super::validate_provisioning_settings(
+        &std::env::temp_dir(),
+        &WindowsSandboxProvisioningSettings::default(),
+        &WindowsSandboxProxyListeners::default(),
+        /*impersonation_token*/ 0,
+    )
+    .expect_err("runtime workers must not load configuration without impersonating the client");
+
+    assert!(error.to_string().contains("failed to impersonate"));
+}
+
+#[test]
+fn unmanaged_policy_allows_default_and_requested_network_settings() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings::default(),
+        WindowsSandboxProxyListeners::default(),
+        "",
+    )?;
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings {
+            proxy_ports: vec![3128, 8080, 9000],
+            allow_local_binding: true,
+        },
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128],
+            socks_ports: vec![8080],
+        },
+        "allowed_sandbox_modes = [\"workspace-write\"]",
+    )
+}
+
+#[test]
+fn elevated_sandbox_is_allowed_when_included() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings::default(),
+        WindowsSandboxProxyListeners::default(),
+        "[windows]\nallowed_sandbox_implementations = [\"unelevated\", \"elevated\"]",
+    )
+}
+
+#[test]
+fn elevated_sandbox_is_rejected_when_prohibited_or_empty() {
+    for implementations in ["[\"unelevated\"]", "[]"] {
+        let policy = format!("[windows]\nallowed_sandbox_implementations = {implementations}");
+        assert!(
+            validate_requirements(
+                &WindowsSandboxProvisioningSettings::default(),
+                WindowsSandboxProxyListeners::default(),
+                &policy,
+            )
+            .is_err()
+        );
+    }
+}
+
+#[test]
+fn forbidden_local_binding_is_rejected() {
+    let settings = WindowsSandboxProvisioningSettings {
+        proxy_ports: Vec::new(),
+        allow_local_binding: true,
+    };
+    assert!(
+        validate_requirements(
+            &settings,
+            WindowsSandboxProxyListeners::default(),
+            "[experimental_network]\nallow_local_binding = false"
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn disabled_network_rejects_proxy_ports_and_local_binding() -> Result<()> {
+    let policy = "[experimental_network]\nenabled = false";
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings::default(),
+        WindowsSandboxProxyListeners::default(),
+        policy,
+    )?;
+    for settings in [
+        WindowsSandboxProvisioningSettings {
+            proxy_ports: vec![3128],
+            allow_local_binding: false,
+        },
+        WindowsSandboxProvisioningSettings {
+            proxy_ports: Vec::new(),
+            allow_local_binding: true,
+        },
+    ] {
+        assert!(
+            validate_requirements(&settings, WindowsSandboxProxyListeners::default(), policy)
+                .is_err()
+        );
+    }
+    Ok(())
+}
+
+#[test]
+fn enabled_network_allows_unrestricted_proxy_ports() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings {
+            proxy_ports: vec![3128, 8080, 8081, 9000],
+            allow_local_binding: false,
+        },
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128, 8080],
+            socks_ports: vec![8081],
+        },
+        "[experimental_network]\nenabled = true",
+    )
+}
+
+#[test]
+fn disabled_local_binding_is_allowed_when_policy_permits_binding() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings::default(),
+        WindowsSandboxProxyListeners::default(),
+        "[experimental_network]\nallow_local_binding = true",
+    )
+}
+
+#[test]
+fn managed_proxy_ports_allow_only_configured_ports() -> Result<()> {
+    let policy = "[experimental_network]\nhttp_port = 3128\nsocks_port = 1080";
+    let allowed = WindowsSandboxProvisioningSettings {
+        proxy_ports: vec![1080, 3128],
+        allow_local_binding: false,
+    };
+    for listeners in [
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128],
+            socks_ports: vec![1080],
+        },
+        WindowsSandboxProxyListeners::default(),
+    ] {
+        validate_requirements(&allowed, listeners, policy)?;
+    }
+    let prohibited = WindowsSandboxProvisioningSettings {
+        proxy_ports: vec![1080, 3128, 8080],
+        allow_local_binding: false,
+    };
+    for listeners in [
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128, 8080],
+            socks_ports: vec![1080],
+        },
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128],
+            socks_ports: vec![1080],
+        },
+        WindowsSandboxProxyListeners::default(),
+    ] {
+        assert!(validate_requirements(&prohibited, listeners, policy).is_err());
+    }
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings::default(),
+        WindowsSandboxProxyListeners::default(),
+        policy,
+    )
+}
+
+#[test]
+fn managed_http_port_does_not_restrict_the_unmanaged_socks_listener() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings {
+            proxy_ports: vec![3128, 8081],
+            allow_local_binding: false,
+        },
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128],
+            socks_ports: vec![8081],
+        },
+        "[experimental_network]\nhttp_port = 3128",
+    )
+}
+
+#[test]
+fn managed_socks_port_does_not_restrict_the_unmanaged_http_listener() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings {
+            proxy_ports: vec![1080, 3128],
+            allow_local_binding: false,
+        },
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128],
+            socks_ports: vec![1080],
+        },
+        "[experimental_network]\nsocks_port = 1080",
+    )
+}
+
+#[test]
+fn managed_proxy_ports_reject_swapped_listener_roles() {
+    assert!(
+        validate_requirements(
+            &WindowsSandboxProvisioningSettings {
+                proxy_ports: vec![1080, 3128],
+                allow_local_binding: false,
+            },
+            WindowsSandboxProxyListeners {
+                http_ports: vec![1080],
+                socks_ports: vec![3128],
+            },
+            "[experimental_network]\nhttp_port = 3128\nsocks_port = 1080",
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn managed_socks_port_rejects_a_mismatched_socks_listener() {
+    assert!(
+        validate_requirements(
+            &WindowsSandboxProvisioningSettings {
+                proxy_ports: vec![1080, 3128, 8081],
+                allow_local_binding: false,
+            },
+            WindowsSandboxProxyListeners {
+                http_ports: vec![3128],
+                socks_ports: vec![1080, 8081],
+            },
+            "[experimental_network]\nhttp_port = 3128\nsocks_port = 1080",
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn managed_socks_port_does_not_require_a_disabled_socks_listener() -> Result<()> {
+    validate_requirements(
+        &WindowsSandboxProvisioningSettings {
+            proxy_ports: vec![3128],
+            allow_local_binding: false,
+        },
+        WindowsSandboxProxyListeners {
+            http_ports: vec![3128],
+            socks_ports: Vec::new(),
+        },
+        "[experimental_network]\nhttp_port = 3128\nsocks_port = 1080",
+    )
+}
+
+#[test]
+fn malformed_machine_policy_fails_closed() {
+    assert!(
+        validate_requirements(
+            &WindowsSandboxProvisioningSettings::default(),
+            WindowsSandboxProxyListeners::default(),
+            "[experimental_network]\nhttp_port = \"invalid\""
+        )
+        .is_err()
+    );
+    assert!(
+        validate_requirements(
+            &WindowsSandboxProvisioningSettings::default(),
+            WindowsSandboxProxyListeners::default(),
+            "[windows]\nallowed_sandbox_implementations = [\"invalid\"]"
+        )
+        .is_err()
+    );
+}
diff --git a/codex-rs/windows-sandbox-service/src/main.rs b/codex-rs/windows-sandbox-service/src/main.rs
new file mode 100644
index 0000000000000000000000000000000000000000..12f5710fd04b3442739c54da1d4415143964a30e
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/main.rs
@@ -0,0 +1,22 @@
+use anyhow::Result;
+use codex_windows_sandbox_service::RunMode;
+
+fn main() -> Result<()> {
+    codex_windows_sandbox_service::run(parse_mode(std::env::args().skip(1))?)
+}
+
+fn parse_mode(arguments: impl Iterator<Item = String>) -> Result<RunMode> {
+    let arguments = arguments.collect::<Vec<_>>();
+    match arguments.as_slice() {
+        [] => Ok(RunMode::Service),
+        [argument] if argument == "--service" => Ok(RunMode::Service),
+        #[cfg(debug_assertions)]
+        [argument] if argument == "--foreground" => Ok(RunMode::Foreground),
+        [argument] => anyhow::bail!("unrecognized service argument {argument:?}"),
+        _ => anyhow::bail!("expected at most one service argument"),
+    }
+}
+
+#[cfg(test)]
+#[path = "main_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-service/src/main_tests.rs b/codex-rs/windows-sandbox-service/src/main_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d3a1eac3ef7492f5064f96ca10bf3197597e2600
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/main_tests.rs
@@ -0,0 +1,44 @@
+use anyhow::Result;
+
+use super::RunMode;
+use super::parse_mode;
+
+#[test]
+fn defaults_to_service_mode() -> Result<()> {
+    assert_eq!(parse_mode(std::iter::empty())?, RunMode::Service);
+    Ok(())
+}
+
+#[test]
+fn accepts_explicit_service_mode() -> Result<()> {
+    let arguments = [String::from("--service")].into_iter();
+    assert_eq!(parse_mode(arguments)?, RunMode::Service);
+    Ok(())
+}
+
+#[test]
+#[cfg(debug_assertions)]
+fn accepts_foreground_mode() -> Result<()> {
+    let arguments = [String::from("--foreground")].into_iter();
+    assert_eq!(parse_mode(arguments)?, RunMode::Foreground);
+    Ok(())
+}
+
+#[test]
+#[cfg(not(debug_assertions))]
+fn rejects_foreground_mode_in_release_builds() {
+    let arguments = [String::from("--foreground")].into_iter();
+    assert!(parse_mode(arguments).is_err());
+}
+
+#[test]
+fn rejects_unknown_arguments() {
+    let arguments = [String::from("--unknown")].into_iter();
+    assert!(parse_mode(arguments).is_err());
+}
+
+#[test]
+fn rejects_multiple_arguments() {
+    let arguments = [String::from("--service"), String::from("--foreground")].into_iter();
+    assert!(parse_mode(arguments).is_err());
+}
diff --git a/codex-rs/windows-sandbox-service/src/package_identity.rs b/codex-rs/windows-sandbox-service/src/package_identity.rs
new file mode 100644
index 0000000000000000000000000000000000000000..8fc5e949df5cba95ede8ffaf3374c4b831514881
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/package_identity.rs
@@ -0,0 +1,122 @@
+//! Binds provisioning requests to the packaged Codex client and its Windows user.
+
+use std::io;
+#[cfg(debug_assertions)]
+use std::sync::atomic::AtomicBool;
+#[cfg(debug_assertions)]
+use std::sync::atomic::Ordering;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use windows_sys::Win32::Foundation as foundation;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security as security;
+use windows_sys::Win32::System::Pipes;
+use windows_sys::Win32::System::Threading;
+
+mod registered;
+
+pub(crate) use registered::authorize_setup_runtime;
+#[cfg(test)]
+pub(crate) use registered::require_runtime_package_family;
+#[cfg(debug_assertions)]
+static FOREGROUND_MODE: AtomicBool = AtomicBool::new(false);
+
+struct OwnedHandle(HANDLE);
+
+pub(crate) struct AuthorizedClientProcess {
+    handle: OwnedHandle,
+}
+
+impl Drop for OwnedHandle {
+    fn drop(&mut self) {
+        if self.0 != 0 && self.0 != foundation::INVALID_HANDLE_VALUE {
+            unsafe { foundation::CloseHandle(self.0) };
+        }
+    }
+}
+
+#[cfg(debug_assertions)]
+pub(crate) fn enable_foreground_mode() {
+    FOREGROUND_MODE.store(true, Ordering::Release);
+}
+
+pub(crate) fn authorize_client_process(pipe: HANDLE) -> Result<AuthorizedClientProcess> {
+    let mut process_id = 0;
+    if unsafe { Pipes::GetNamedPipeClientProcessId(pipe, &mut process_id) } == 0 || process_id == 0
+    {
+        return Err(io::Error::last_os_error()).context("identify the provisioning client process");
+    }
+
+    let process = unsafe {
+        Threading::OpenProcess(Threading::PROCESS_QUERY_LIMITED_INFORMATION, 0, process_id)
+    };
+    if process == 0 {
+        return Err(io::Error::last_os_error()).context("open the provisioning client process");
+    }
+    let process = OwnedHandle(process);
+
+    let client_family = unsafe { codex_windows_sandbox::process_package_family(process.0) }
+        .context("read provisioning client package identity")?;
+    let service_family =
+        unsafe { codex_windows_sandbox::process_package_family(Threading::GetCurrentProcess()) }
+            .context("read provisioning service package identity")?;
+    match client_family {
+        Some(client_family) => match service_family.as_deref() {
+            Some(service_family) if client_family != service_family => {
+                bail!("provisioning client package does not match the service package")
+            }
+            Some(_) => {}
+            #[cfg(debug_assertions)]
+            None if FOREGROUND_MODE.load(Ordering::Acquire)
+                && is_known_codex_package_family(&client_family) => {}
+            #[cfg(debug_assertions)]
+            None if FOREGROUND_MODE.load(Ordering::Acquire) => {
+                bail!("provisioning client does not belong to a trusted Codex package family")
+            }
+            None => bail!("provisioning service has no package identity"),
+        },
+        None if service_family.is_some() => {}
+        #[cfg(debug_assertions)]
+        None if FOREGROUND_MODE.load(Ordering::Acquire) => {}
+        None => bail!("provisioning clients must run with an installed Codex package identity"),
+    }
+
+    Ok(AuthorizedClientProcess { handle: process })
+}
+
+pub(crate) fn authorize_client(
+    process: &AuthorizedClientProcess,
+    client_token: HANDLE,
+) -> Result<()> {
+    let mut process_token = 0;
+    if unsafe {
+        Threading::OpenProcessToken(process.handle.0, security::TOKEN_QUERY, &mut process_token)
+    } == 0
+    {
+        return Err(io::Error::last_os_error())
+            .context("open the provisioning client process token");
+    }
+    let process_token = OwnedHandle(process_token);
+    let process_user = unsafe { codex_windows_sandbox::get_user_sid_bytes(process_token.0) }
+        .context("read the client process user")?;
+    let impersonated_user = unsafe { codex_windows_sandbox::get_user_sid_bytes(client_token) }
+        .context("read the impersonated client user")?;
+    if process_user != impersonated_user {
+        bail!("provisioning client process does not belong to the impersonated user");
+    }
+
+    Ok(())
+}
+
+#[cfg(debug_assertions)]
+fn is_known_codex_package_family(package_family: &str) -> bool {
+    matches!(
+        package_family,
+        "OpenAI.Codex_3k8sg7r9htsxt"
+            | "OpenAI.CodexAlpha_3k8sg7r9htsxt"
+            | "OpenAI.CodexBeta_3k8sg7r9htsxt"
+            | "OpenAI.CodexNightly_3k8sg7r9htsxt"
+    )
+}
diff --git a/codex-rs/windows-sandbox-service/src/package_identity/registered.rs b/codex-rs/windows-sandbox-service/src/package_identity/registered.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f473bec6ea0fe2e9fe8aa62d5f303d6687c01f98
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/package_identity/registered.rs
@@ -0,0 +1,75 @@
+//! Admits registered Core only from the service's installed package version and
+//! prevents legacy setup from replacing accounts owned by a registered runtime.
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_windows_sandbox::SetupRuntime;
+use windows_sys::Win32::System::Threading;
+
+use super::AuthorizedClientProcess;
+use crate::ipc::ServiceRequest;
+
+pub(crate) fn authorize_setup_runtime(
+    process: &AuthorizedClientProcess,
+    request: &ServiceRequest,
+) -> Result<SetupRuntime> {
+    match request {
+        ServiceRequest::ProvisionSandbox(request) if request.registered_core => {
+            authorize_runtime_client_process(process)?;
+            Ok(SetupRuntime::Registered)
+        }
+        ServiceRequest::ProvisionSandbox(_) => {
+            anyhow::ensure!(
+                crate::installation_record::load_runtime()?.is_none(),
+                "registered Core owns these sandbox accounts; legacy provisioning is not permitted"
+            );
+            Ok(SetupRuntime::Legacy)
+        }
+        ServiceRequest::RegisterInstallation { .. } => Ok(SetupRuntime::Legacy),
+    }
+}
+
+fn authorize_runtime_client_process(process: &AuthorizedClientProcess) -> Result<()> {
+    let client_family = unsafe { codex_windows_sandbox::process_package_family(process.handle.0) }
+        .context("read runtime registration client package family")?;
+    let service_family =
+        unsafe { codex_windows_sandbox::process_package_family(Threading::GetCurrentProcess()) }
+            .context("read runtime registration service package family")?;
+    require_runtime_package_family(client_family.as_deref(), service_family.as_deref())?;
+    let mut image = [0u16; 32768];
+    let mut length = image.len() as u32;
+    if unsafe {
+        Threading::QueryFullProcessImageNameW(process.handle.0, 0, image.as_mut_ptr(), &mut length)
+    } == 0
+    {
+        return Err(std::io::Error::last_os_error()).context("read provisioning client image");
+    }
+    let image = std::path::PathBuf::from(String::from_utf16(&image[..length as usize])?);
+    let image = image.canonicalize()?;
+    let service = std::env::current_exe()?.canonicalize()?;
+    let directory = service.parent().context("service image has no directory")?;
+    anyhow::ensure!(
+        ["codex.exe", "codex-code-mode-host.exe"]
+            .iter()
+            .any(|name| {
+                image
+                    .as_os_str()
+                    .eq_ignore_ascii_case(directory.join(name).as_os_str())
+            }),
+        "registered Core caller is not from this installed service version"
+    );
+    Ok(())
+}
+
+pub(crate) fn require_runtime_package_family(
+    client: Option<&str>,
+    service: Option<&str>,
+) -> Result<()> {
+    match (client, service) {
+        (Some(client), Some(service)) if client == service => Ok(()),
+        _ => bail!(
+            "runtime registration requires a client in the service's installed package family"
+        ),
+    }
+}
diff --git a/codex-rs/windows-sandbox-service/src/package_lifecycle.rs b/codex-rs/windows-sandbox-service/src/package_lifecycle.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f53143c74304f35233e8e7eb064442df6d96c016
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/package_lifecycle.rs
@@ -0,0 +1,302 @@
+//! Restores owner-scoped uninstall notifications and ties file cleanup to pinned directories.
+//! Registered runtime policy stays in its private module; owner tokens and pins stay here.
+
+use std::cell::RefCell;
+use std::io;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::IntoRawHandle;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use codex_windows_sandbox::DirectoryOpenDisposition;
+use codex_windows_sandbox::PreparedWindowsSandboxCleanup;
+use codex_windows_sandbox::create_directory_guard;
+use codex_windows_sandbox::prepare_packaged_windows_sandbox_cleanup;
+use codex_windows_sandbox::string_from_sid_bytes;
+use windows::ApplicationModel::Package;
+use windows::ApplicationModel::PackageCatalog;
+use windows::ApplicationModel::PackageUninstallingEventArgs;
+use windows::Foundation::EventRegistrationToken;
+use windows::Foundation::TypedEventHandler;
+use windows::Win32::System::WinRT::RO_INIT_MULTITHREADED;
+use windows::Win32::System::WinRT::RoInitialize;
+use windows::Win32::System::WinRT::RoUninitialize;
+use windows::core::HSTRING;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security as security;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+use windows_sys::Win32::System::RemoteDesktop::WTS_CURRENT_SERVER_HANDLE;
+use windows_sys::Win32::System::RemoteDesktop::WTSEnumerateSessionsW;
+use windows_sys::Win32::System::RemoteDesktop::WTSFreeMemory;
+use windows_sys::Win32::System::RemoteDesktop::WTSQueryUserToken;
+
+use crate::installation_record::InstallationRecord;
+use crate::ipc::OwnedHandle;
+
+mod cleanup;
+mod registered;
+
+pub(crate) use registered::runtime_owner_removed;
+
+struct UserInstallation {
+    codex_home: Option<PathBuf>,
+    // Ancestors and home remain pinned until owner-scoped cleanup finishes.
+    directory_handles: Vec<OwnedHandle>,
+    directory_guard: Option<OwnedHandle>,
+    record: InstallationRecord,
+    user_token: OwnedHandle,
+    catalog: PackageCatalog,
+    token: EventRegistrationToken,
+}
+
+pub(crate) struct PackageLifecycle {
+    package_name: HSTRING,
+    uninstalling: Arc<AtomicBool>,
+    installation: RefCell<Option<UserInstallation>>,
+}
+
+impl PackageLifecycle {
+    pub(crate) fn new(uninstalling: Arc<AtomicBool>) -> Result<Self> {
+        unsafe { RoInitialize(RO_INIT_MULTITHREADED) }
+            .context("initialize the sandbox service Windows Runtime apartment")?;
+        Ok(Self {
+            package_name: Package::Current()?.Id()?.FullName()?,
+            uninstalling,
+            installation: RefCell::default(),
+        })
+    }
+
+    pub(crate) fn register_authenticated_user(
+        &self,
+        mut record: InstallationRecord,
+        user_token: OwnedHandle,
+    ) -> Result<InstallationRecord> {
+        let mut active = self.installation.borrow_mut();
+        let previous = match active.as_ref() {
+            Some(installation) => Some(installation.record.clone()),
+            None => crate::installation_record::load()?,
+        };
+        if let Some(previous) = previous {
+            // A missing watcher does not retire its owner; other clients can use elevated setup.
+            ensure!(
+                previous.user_sid == record.user_sid && previous.codex_home == record.codex_home,
+                crate::ipc::ServiceUnavailable(
+                    "installation is already registered to a different owner or home"
+                )
+            );
+            record.desktop_installation = previous
+                .desktop_installation
+                .or(record.desktop_installation);
+        }
+        record = crate::installation_record::save(record)?;
+        if let Some(installation) = active.as_mut()
+            && installation.codex_home.is_some()
+        {
+            // A restored watcher must immediately use newly registered desktop ownership.
+            installation.record = record.clone();
+            return Ok(record);
+        }
+
+        let saved_record = record.clone();
+        with_owner_impersonation(user_token.0, || {
+            let mut directory_handles = Vec::new();
+            let mut directory_guard = None;
+            let codex_home = match crate::ipc::pin_existing_ancestors(
+                &record.codex_home,
+                &mut directory_handles,
+            )
+            .and_then(|()| {
+                let home = directory_handles
+                    .last()
+                    .context("pin the registered home")?;
+                let guard =
+                    create_directory_guard(unsafe { BorrowedHandle::borrow_raw(home.0 as _) })?;
+                // Reject a conversion that happened before the handle-relative guard was created.
+                drop(crate::ipc::pin_directory(
+                    &record.codex_home,
+                    filesystem::FILE_READ_ATTRIBUTES,
+                    DirectoryOpenDisposition::OpenExisting,
+                )?);
+                directory_guard = Some(OwnedHandle(guard.into_raw_handle() as HANDLE));
+                Ok(())
+            }) {
+                Ok(()) => Some(record.codex_home.clone()),
+                Err(error) => {
+                    directory_handles.clear();
+                    crate::service::log_error(
+                        crate::service::EVENT_SERVICE_FAILED,
+                        &format!(
+                            "skipping sandbox file cleanup because the home could not be pinned: {error:#}"
+                        ),
+                    );
+                    None
+                }
+            };
+            if let Some(installation) = active.as_mut() {
+                installation.codex_home = codex_home;
+                installation.directory_handles = directory_handles;
+                installation.directory_guard = directory_guard;
+                installation.record = record;
+                return Ok(());
+            }
+            let catalog = PackageCatalog::OpenForCurrentUser().context(
+                crate::ipc::ServiceUnavailable("open the authenticated user's package catalog"),
+            )?;
+            let package_name = self.package_name.clone();
+            let uninstalling = Arc::clone(&self.uninstalling);
+            let owner_sid = record.user_sid.clone();
+            let token = catalog
+                .PackageUninstalling(&TypedEventHandler::<
+                    PackageCatalog,
+                    PackageUninstallingEventArgs,
+                >::new(move |_, event| {
+                    if let Some(event) = event
+                        && event.Package()?.Id()?.FullName()? == package_name
+                    {
+                        registered::on_package_uninstalling(event, &owner_sid, &uninstalling)?;
+                    }
+                    Ok(())
+                }))
+                .context(crate::ipc::ServiceUnavailable(
+                    "subscribe to authenticated package uninstall notifications",
+                ))?;
+            active.replace(UserInstallation {
+                codex_home,
+                directory_handles,
+                directory_guard,
+                record,
+                user_token,
+                catalog,
+                token,
+            });
+            Ok(())
+        })?;
+        Ok(saved_record)
+    }
+
+    pub(crate) fn restore_logged_in_owner(&self, recorded_session_id: u32) -> Result<()> {
+        let Err(error) = self.restore_authenticated_user(recorded_session_id) else {
+            return Ok(());
+        };
+
+        // Session IDs can change while the service is stopped; the owner SID is durable.
+        let mut sessions = std::ptr::null_mut();
+        let mut count = 0;
+        if unsafe {
+            WTSEnumerateSessionsW(
+                WTS_CURRENT_SERVER_HANDLE,
+                /*reserved*/ 0,
+                /*version*/ 1,
+                &mut sessions,
+                &mut count,
+            )
+        } == 0
+        {
+            return Err(io::Error::last_os_error()).context("list current Windows sessions");
+        }
+        let restored = (0..count).any(|index| {
+            let session_id = unsafe { (*sessions.add(index as usize)).SessionId };
+            session_id != recorded_session_id && self.restore_authenticated_user(session_id).is_ok()
+        });
+        unsafe { WTSFreeMemory(sessions.cast()) };
+        if restored { Ok(()) } else { Err(error) }
+    }
+
+    pub(crate) fn restore_authenticated_user(&self, session_id: u32) -> Result<()> {
+        if self.installation.borrow().is_some() {
+            return Ok(());
+        }
+        let Some(record) = crate::installation_record::load()? else {
+            return Ok(());
+        };
+
+        if record.runtime.is_some()
+            && !crate::installation_record::is_current_package_family(&record)?
+        {
+            return Ok(());
+        }
+        let mut raw_token = 0;
+        if unsafe { WTSQueryUserToken(session_id, &mut raw_token) } == 0 {
+            return Err(io::Error::last_os_error()).context("open the logged-in user's token");
+        }
+        let token = crate::ipc::OwnedHandle(raw_token);
+        let user = unsafe { codex_windows_sandbox::get_user_sid_bytes(token.0) }?;
+        let user_sid = string_from_sid_bytes(&user).map_err(anyhow::Error::msg)?;
+        ensure!(
+            user_sid == record.user_sid,
+            "logged-in user does not match the recorded sandbox owner"
+        );
+
+        self.register_authenticated_user(
+            InstallationRecord {
+                session_id,
+                ..record
+            },
+            token,
+        )
+        .map(|_| ())
+    }
+
+    pub(crate) fn clean_up(&self) -> Result<()> {
+        let _setup_lock =
+            codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+        if let Some(record) = crate::installation_record::load_runtime()? {
+            return registered::clean_up(self, record);
+        }
+        // Preserve the legacy path's ownership retirement before native preparation.
+        crate::installation_record::remove()?;
+        self.clean_up_resources(
+            &prepare_packaged_windows_sandbox_cleanup()?,
+            /*runtime*/ None,
+        )
+    }
+
+    fn clean_up_resources(
+        &self,
+        prepared: &PreparedWindowsSandboxCleanup,
+        runtime: Option<&InstallationRecord>,
+    ) -> Result<()> {
+        let mut installation = self.installation.borrow_mut();
+        let installation = installation
+            .as_mut()
+            .context("the authenticated package installation was not recorded")?;
+        cleanup::clean_up(installation, prepared, runtime, &self.uninstalling)
+    }
+}
+
+pub(crate) fn with_owner_impersonation<T>(
+    user_token: HANDLE,
+    operation: impl FnOnce() -> Result<T>,
+) -> Result<T> {
+    if unsafe { security::ImpersonateLoggedOnUser(user_token) } == 0 {
+        return Err(io::Error::last_os_error()).context("impersonate the sandbox owner");
+    }
+    let result = operation();
+    if unsafe { security::RevertToSelf() } == 0 {
+        crate::service::log_error(
+            crate::service::EVENT_SERVICE_FAILED,
+            &format!(
+                "unable to revert sandbox-owner impersonation: {}",
+                io::Error::last_os_error()
+            ),
+        );
+        // Continuing as the user would make later machine cleanup unsafe.
+        std::process::abort();
+    }
+    result
+}
+
+impl Drop for PackageLifecycle {
+    fn drop(&mut self) {
+        if let Some(installation) = self.installation.get_mut().take() {
+            let _ = installation
+                .catalog
+                .RemovePackageUninstalling(installation.token);
+        }
+        unsafe { RoUninitialize() };
+    }
+}
diff --git a/codex-rs/windows-sandbox-service/src/package_lifecycle/cleanup.rs b/codex-rs/windows-sandbox-service/src/package_lifecycle/cleanup.rs
new file mode 100644
index 0000000000000000000000000000000000000000..fa4844efa23b2288c714a701559de0370ba2d5e8
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/package_lifecycle/cleanup.rs
@@ -0,0 +1,184 @@
+//! Removes one authenticated owner's sandbox resources using prepared native cleanup.
+//! Owner impersonation, directory pins, and registration-aware cleanup order are preserved.
+
+use std::io;
+use std::path::Path;
+use std::sync::atomic::AtomicBool;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use codex_windows_sandbox::PreparedWindowsSandboxCleanup;
+use codex_windows_sandbox::resolve_sid;
+use codex_windows_sandbox::revoke_ace;
+
+use super::UserInstallation;
+use super::with_owner_impersonation;
+use crate::installation_record::InstallationRecord;
+use crate::service::EVENT_CLEANUP_DETAIL;
+use crate::service::log_error;
+use crate::service::log_information;
+
+pub(super) fn clean_up(
+    installation: &mut UserInstallation,
+    prepared: &PreparedWindowsSandboxCleanup,
+    runtime: Option<&InstallationRecord>,
+    uninstalling: &AtomicBool,
+) -> Result<()> {
+    crate::service::log_information(
+        crate::service::EVENT_CLEANUP_STARTED,
+        "sandbox uninstall cleanup started",
+    );
+    let codex_home = installation.codex_home.clone();
+    // Remove exact grants from the locked cleanup record before native account deletion.
+    if let Some(record) = runtime {
+        log_cleanup("removing registered runtime metadata");
+        crate::registered_runtime::remove_metadata(installation.user_token.0, record)?;
+    }
+    log_cleanup("removing native sandbox resources");
+    let mut prune_codex_home = false;
+    // Once owner-scoped deletion releases the home, retries must not traverse it as SYSTEM.
+    let sandbox_home = codex_home
+        .as_deref()
+        .filter(|_| installation.directory_guard.is_some());
+    let result = prepared.finish(sandbox_home, log_cleanup, || {
+        if let Some(record) = runtime
+            && !super::registered::owner_allows_cleanup(uninstalling, record)?
+        {
+            // Only the old sandbox resources are repaired on reinstall. Never remove
+            // the reinstalled app's desktop-created home or runtime cache.
+            log_cleanup("skipping desktop directories: owner reinstalled the app");
+            return Ok(());
+        }
+        let Some(desktop) = &installation.record.desktop_installation else {
+            log_cleanup("skipping desktop directories: no desktop installation record");
+            return Ok(());
+        };
+        // The marker is user-writable. It must never authorize deletion as LocalSystem.
+        with_owner_impersonation(installation.user_token.0, || {
+            let mut errors = Vec::new();
+            let mut record_result = |operation: &str, result: io::Result<()>| match result {
+                Ok(()) => log_cleanup(&format!("{operation}: completed")),
+                Err(error) if error.kind() == io::ErrorKind::NotFound => {
+                    log_cleanup(&format!("{operation}: skipped, not found"));
+                }
+                Err(error) => {
+                    let message = format!("{operation}: failed, {error}");
+                    log_error(EVENT_CLEANUP_DETAIL, &message);
+                    errors.push(message);
+                }
+            };
+            if let Some(home) = &codex_home {
+                if desktop.created_codex_home {
+                    // Release the home itself so it can be deleted; keep its ancestors pinned.
+                    if installation.directory_guard.take().is_some() {
+                        installation.directory_handles.pop();
+                    }
+                    record_result(
+                        "remove desktop-created codex home",
+                        std::fs::remove_dir_all(home),
+                    );
+                } else {
+                    prune_codex_home = true;
+                    log_cleanup("skipping recursive codex home removal: existing CLI home");
+                    // Preserve CLI data without leaving inherited permissions for the deleted group.
+                    record_result(
+                        "remove codex home sandbox permissions",
+                        resolve_sid("CodexSandboxUsers")
+                            .and_then(|mut sid| unsafe {
+                                revoke_ace(home, sid.as_mut_ptr().cast())
+                            })
+                            .map_err(io::Error::other),
+                    );
+                }
+            } else {
+                log_cleanup("skipping codex home: no pinned home");
+            }
+            // The cache may have been created after provisioning. Pin it only for cleanup.
+            let mut cache_directory_handles = Vec::new();
+            if desktop.cache_home.is_dir() {
+                match crate::ipc::pin_existing_ancestors(
+                    &desktop.cache_home,
+                    &mut cache_directory_handles,
+                ) {
+                    Ok(()) => {
+                        record_result(
+                            "remove codex runtime cache",
+                            std::fs::remove_dir_all(desktop.cache_home.join("codex-runtimes")),
+                        );
+                        // Release only the cache root; its ancestors must remain pinned.
+                        cache_directory_handles.pop();
+                        remove_empty_directory(&desktop.cache_home, "cache home");
+                    }
+                    Err(error) => {
+                        log_error(
+                            EVENT_CLEANUP_DETAIL,
+                            &format!("skipping runtime cache: could not pin cache home, {error:#}"),
+                        );
+                        errors.push(error.to_string());
+                    }
+                }
+            } else {
+                log_cleanup("skipping cache home: no accessible directory");
+            }
+            ensure!(
+                errors.is_empty(),
+                "remove desktop directories: {}",
+                errors.join("; ")
+            );
+            Ok(())
+        })
+    });
+    result.context("remove packaged Windows sandbox resources")?;
+    if prune_codex_home && let Some(home) = &codex_home {
+        // Keep the home pinned through native retries. Empty-root pruning is best effort
+        // so a failure cannot restart native cleanup through an unpinned home.
+        if let Err(error) = with_owner_impersonation(installation.user_token.0, || {
+            if installation.directory_guard.take().is_some() {
+                installation.directory_handles.pop();
+            }
+            remove_empty_directory(home, "codex home");
+            Ok(())
+        }) {
+            log_error(
+                EVENT_CLEANUP_DETAIL,
+                &format!("remove empty codex home: failed, {error:#}"),
+            );
+        }
+    }
+    crate::service::log_information(
+        if runtime.is_some() {
+            EVENT_CLEANUP_DETAIL
+        } else {
+            crate::service::EVENT_CLEANUP_FINISHED
+        },
+        if runtime.is_some() {
+            "native sandbox cleanup finished; registered runtime cleanup pending"
+        } else {
+            "sandbox uninstall cleanup finished"
+        },
+    );
+    Ok(())
+}
+
+fn remove_empty_directory(path: &Path, target: &str) {
+    match std::fs::remove_dir(path) {
+        Ok(()) => log_cleanup(&format!("removed empty {target}")),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {
+            log_cleanup(&format!("skipping empty {target} removal: not found"));
+        }
+        Err(error) if error.kind() == io::ErrorKind::DirectoryNotEmpty => {
+            log_cleanup(&format!("preserving {target}: directory is not empty"));
+        }
+        Err(error) => {
+            log_error(
+                EVENT_CLEANUP_DETAIL,
+                &format!("remove empty {target}: failed, {error}"),
+            );
+        }
+    }
+}
+
+fn log_cleanup(message: &str) {
+    log_information(EVENT_CLEANUP_DETAIL, message);
+}
diff --git a/codex-rs/windows-sandbox-service/src/package_lifecycle/registered.rs b/codex-rs/windows-sandbox-service/src/package_lifecycle/registered.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4b9d10492b7228665e077890519a12dfcac548d0
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/package_lifecycle/registered.rs
@@ -0,0 +1,149 @@
+//! Registered runtime ownership and uninstall policy for the shared package watcher.
+//! Native cleanup stays inside the caller's setup lock and precedes package removal.
+
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use codex_windows_sandbox::prepare_packaged_windows_sandbox_cleanup_with_retained_tokens;
+use windows::ApplicationModel::Package;
+use windows::ApplicationModel::PackageUninstallingEventArgs;
+use windows::Management::Deployment::PackageManager;
+use windows::core::HSTRING;
+
+use super::PackageLifecycle;
+use crate::installation_record::InstallationRecord;
+
+pub(super) fn on_package_uninstalling(
+    event: &PackageUninstallingEventArgs,
+    owner_sid: &str,
+    uninstalling: &AtomicBool,
+) -> windows::core::Result<()> {
+    let retention = crate::installation_record::load_runtime().and_then(|record| match record {
+        Some(record) if record.user_sid == owner_sid => {
+            crate::registered_runtime::has_retaining_registration(&record).map(Some)
+        }
+        Some(_) => Ok(None),
+        None => Ok(Some(false)),
+    });
+    match retention {
+        Ok(Some(true)) => {
+            // Removing an old version during update must not remove the
+            // managed user's registration. Check the whole family only
+            // after the owner's uninstall has completed.
+            if event.IsComplete()? {
+                crate::service::wake_listener();
+            }
+        }
+        Ok(None) => {}
+        Ok(Some(false)) => {
+            // No actual managed registration keeps this service installed,
+            // even if a failed attempt left intent. Retain SCM-stop cleanup.
+            uninstalling.store(!event.IsComplete()?, Ordering::Release);
+        }
+        Err(error) => crate::service::log_error(
+            crate::service::EVENT_SERVICE_FAILED,
+            &format!("unable to read registered runtime ownership: {error:#}"),
+        ),
+    }
+    Ok(())
+}
+
+/// The shared cleanup entry holds the setup mutex until this function returns.
+pub(super) fn clean_up(lifecycle: &PackageLifecycle, record: InstallationRecord) -> Result<()> {
+    if !crate::installation_record::is_current_package_family(&record)? {
+        return Ok(());
+    }
+    ensure!(
+        record.runtime()?.retiring.is_none(),
+        "interrupted runtime cleanup requires repair"
+    );
+    ensure!(
+        owner_allows_cleanup(&lifecycle.uninstalling, &record)?,
+        "registered runtime owner still has the app installed"
+    );
+    ensure!(
+        lifecycle
+            .installation
+            .borrow()
+            .as_ref()
+            .is_some_and(|installation| {
+                installation.record.user_sid == record.user_sid
+                    && installation.codex_home.as_ref() == Some(&record.codex_home)
+            }),
+        "waiting for the authenticated runtime owner and home before sandbox file cleanup"
+    );
+    let record = crate::registered_runtime::prepare_cleanup(record)?;
+    let removal = {
+        let installation = lifecycle.installation.borrow();
+        let installation = installation
+            .as_ref()
+            .context("authenticated installation is missing")?;
+        crate::registered_runtime::prepare_removal(installation.user_token.0, &record)?
+    };
+    let prepared =
+        prepare_packaged_windows_sandbox_cleanup_with_retained_tokens(&removal.tokens())?;
+    // A reinstall before this boundary cancels without retiring resources.
+    ensure!(
+        owner_allows_cleanup(&lifecycle.uninstalling, &record)?,
+        "owner reinstalled before native cleanup started"
+    );
+    crate::installation_record::save_runtime(&record)?;
+    // Retry only in this live invocation, retaining the outer setup lock.
+    // A stored retirement fence is never proof that native cleanup finished.
+    crate::service::retry_cleanup(|| lifecycle.clean_up_resources(&prepared, Some(&record)))?;
+    removal.commit()
+}
+
+pub(super) fn owner_allows_cleanup(
+    uninstalling: &AtomicBool,
+    record: &InstallationRecord,
+) -> Result<bool> {
+    let packages = PackageManager::new()?.FindPackagesByUserSecurityIdPackageFamilyName(
+        &HSTRING::from(&record.user_sid),
+        &HSTRING::from(&record.runtime()?.package_family),
+    )?;
+    let iterator = packages.First()?;
+    let mut has_current = iterator.HasCurrent()?;
+    if !has_current {
+        return Ok(true);
+    }
+    if !uninstalling.load(Ordering::Acquire)
+        || crate::registered_runtime::has_retaining_registration(record)?
+    {
+        return Ok(false);
+    }
+    // SCM may stop us before this exact package is removed. A successor version
+    // belongs to an update or reinstall and must keep its desktop data.
+    let retiring_package = Package::Current()?.Id()?.FullName()?;
+    while has_current {
+        if iterator.Current()?.Id()?.FullName()? != retiring_package {
+            return Ok(false);
+        }
+        has_current = iterator.MoveNext()?;
+    }
+    Ok(true)
+}
+
+/// The managed registration must not keep the package alive after its owner
+/// uninstalls it, but an update to another version of the family is not uninstall.
+pub(crate) fn runtime_owner_removed() -> Result<bool> {
+    let Some(record) = crate::installation_record::load_runtime()? else {
+        return Ok(false);
+    };
+    Ok(
+        crate::installation_record::is_current_package_family(&record)?
+            && !runtime_owner_has_package(&record)?,
+    )
+}
+
+// Callers have verified that the record belongs to this service's package family.
+pub(super) fn runtime_owner_has_package(record: &InstallationRecord) -> Result<bool> {
+    let packages = PackageManager::new()?.FindPackagesByUserSecurityIdPackageFamilyName(
+        &HSTRING::from(&record.user_sid),
+        &HSTRING::from(&record.runtime()?.package_family),
+    )?;
+    Ok(packages.First()?.HasCurrent()?)
+}
diff --git a/codex-rs/windows-sandbox-service/src/provisioning.rs b/codex-rs/windows-sandbox-service/src/provisioning.rs
new file mode 100644
index 0000000000000000000000000000000000000000..cf91b51cde6c1aaa9280c636b59e416fa091470e
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/provisioning.rs
@@ -0,0 +1,143 @@
+//! Provisions an authenticated client's sandbox through its selected setup path.
+
+mod registered;
+
+use std::os::windows::fs::MetadataExt;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::IntoRawHandle;
+use std::sync::atomic::AtomicBool;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::bail;
+use codex_windows_sandbox::SandboxProvisioningResponse;
+use codex_windows_sandbox::SetupRuntime;
+use codex_windows_sandbox::run_elevated_provisioning_setup_with_retained_handles;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+
+use crate::installation_record::InstallationRecord;
+use crate::ipc::ClientIdentity;
+use crate::ipc::OwnedHandle;
+use crate::ipc::ServiceRequest;
+
+// The lifecycle callback validates ownership and returns the canonical saved record.
+fn register_owner(
+    identity: &ClientIdentity,
+    on_authenticated_user: &dyn Fn(
+        InstallationRecord,
+        OwnedHandle,
+        codex_windows_sandbox::SetupRuntime,
+    ) -> Result<InstallationRecord>,
+) -> Result<InstallationRecord> {
+    let token = unsafe { BorrowedHandle::borrow_raw(identity.token.0 as _) }
+        .try_clone_to_owned()
+        .context("retain authenticated uninstall owner")?;
+    on_authenticated_user(
+        InstallationRecord {
+            codex_home: identity.codex_home.clone(),
+            user_sid: identity.user_sid.clone(),
+            session_id: identity.session_id,
+            desktop_installation: identity.desktop_installation.clone(),
+            runtime: None,
+        },
+        OwnedHandle(token.into_raw_handle() as _),
+        identity.runtime,
+    )
+}
+
+fn setup_is_complete(
+    identity: &ClientIdentity,
+    settings: &codex_windows_sandbox::WindowsSandboxProvisioningSettings,
+) -> Result<bool> {
+    crate::package_lifecycle::with_owner_impersonation(identity.token.0, || {
+        Ok(
+            codex_windows_sandbox::sandbox_setup_is_complete_with_settings(
+                &identity.codex_home,
+                settings,
+            ),
+        )
+    })
+}
+
+pub(crate) fn run(
+    identity: ClientIdentity,
+    request: ServiceRequest,
+    sandbox_sid: &[u8],
+    shutdown: &AtomicBool,
+    on_authenticated_user: &dyn Fn(
+        InstallationRecord,
+        OwnedHandle,
+        codex_windows_sandbox::SetupRuntime,
+    ) -> Result<InstallationRecord>,
+) -> Result<SandboxProvisioningResponse> {
+    let request = match request {
+        ServiceRequest::RegisterInstallation { .. } => {
+            let installation = InstallationRecord {
+                codex_home: identity.codex_home,
+                user_sid: identity.user_sid,
+                session_id: identity.session_id,
+                desktop_installation: identity.desktop_installation,
+                runtime: None,
+            };
+            on_authenticated_user(installation, identity.token, identity.runtime)?;
+            return Ok(SandboxProvisioningResponse::Ok);
+        }
+        ServiceRequest::ProvisionSandbox(request) => request,
+    };
+    if identity.runtime == SetupRuntime::Registered {
+        return registered::run(
+            &identity,
+            request,
+            sandbox_sid,
+            shutdown,
+            on_authenticated_user,
+        );
+    }
+    let settings = request.settings;
+    register_owner(&identity, on_authenticated_user)?;
+    if setup_is_complete(&identity, &settings)? {
+        return Ok(SandboxProvisioningResponse::Ok);
+    }
+    let helper = std::env::current_exe()
+        .context("locate the provisioning service executable")?
+        .with_file_name("codex-windows-sandbox-setup.exe");
+    let helper_metadata = helper
+        .symlink_metadata()
+        .with_context(|| format!("inspect packaged setup helper {}", helper.display()))?;
+    if !helper_metadata.is_file()
+        || helper_metadata.file_attributes() & filesystem::FILE_ATTRIBUTE_REPARSE_POINT != 0
+    {
+        bail!(
+            "refusing invalid packaged setup helper {}",
+            helper.display()
+        );
+    }
+    let retained_handles = identity
+        .directory_handles
+        .iter()
+        // The identity owns these handles through the synchronous helper launch and wait.
+        .map(|handle| unsafe { BorrowedHandle::borrow_raw(handle.0 as _) })
+        .collect::<Vec<_>>();
+    match run_elevated_provisioning_setup_with_retained_handles(
+        &identity.codex_home,
+        &identity.account,
+        settings,
+        identity.runtime,
+        &retained_handles,
+    ) {
+        Ok(()) => {
+            crate::service::log_information(
+                crate::service::EVENT_PROVISIONING_SUCCEEDED,
+                "Codex sandbox provisioning completed successfully.",
+            );
+            Ok(SandboxProvisioningResponse::Ok)
+        }
+        Err(error) => {
+            crate::service::log_error(
+                crate::service::EVENT_PROVISIONING_FAILED,
+                &format!("Codex sandbox provisioning failed: {error}"),
+            );
+            Err(error).context("sandbox provisioning failed")
+        }
+    }
+}
diff --git a/codex-rs/windows-sandbox-service/src/provisioning/registered.rs b/codex-rs/windows-sandbox-service/src/provisioning/registered.rs
new file mode 100644
index 0000000000000000000000000000000000000000..13c53721d10caeb9101c1ae102c1ea43c7901181
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/provisioning/registered.rs
@@ -0,0 +1,127 @@
+//! The registered-Core setup transaction: admit, provision, register, then publish readiness.
+
+use std::sync::atomic::AtomicBool;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use codex_windows_sandbox::SandboxProvisioningResponse;
+
+use crate::ipc::ProvisioningRequest;
+use codex_windows_sandbox::string_from_sid_bytes;
+use windows::ApplicationModel::Package;
+use windows_sys::Win32::NetworkManagement::NetManagement::UF_ACCOUNTDISABLE;
+
+use crate::installation_record::InstallationRecord;
+use crate::installation_record::RuntimeRegistration;
+use crate::ipc::ClientIdentity;
+use crate::ipc::OwnedHandle;
+
+pub(super) fn run(
+    identity: &ClientIdentity,
+    request: ProvisioningRequest,
+    sandbox_sid: &[u8],
+    shutdown: &AtomicBool,
+    on_authenticated_user: &dyn Fn(
+        InstallationRecord,
+        OwnedHandle,
+        codex_windows_sandbox::SetupRuntime,
+    ) -> Result<InstallationRecord>,
+) -> Result<SandboxProvisioningResponse> {
+    // Keep admission, account provisioning and package registration in one transaction.
+    let _setup_lock = codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+    ensure!(
+        codex_windows_sandbox::resolve_sid(codex_windows_sandbox::SANDBOX_USERS_GROUP)
+            .is_ok_and(|current| current == sandbox_sid),
+        codex_windows_sandbox::SANDBOX_GROUP_CHANGED
+    );
+    let settings = request.settings;
+    let mut setup_complete = super::setup_is_complete(identity, &settings)?;
+    if request.refresh_only {
+        // Startup may update registrations, but must never create accounts or repair teardown.
+        // Check under the setup lock, before changing ownership or sandbox accounts.
+        let previous = crate::installation_record::load_runtime()?
+            .context("registration refresh requires completed setup")?;
+        let runtime = previous.runtime()?;
+        // Windows may restart this service during registration, after readiness was
+        // revoked. Resume only the same provisioned accounts; never repair setup.
+        ensure!(
+            previous.user_sid == identity.user_sid
+                && previous.codex_home == identity.codex_home
+                && crate::installation_record::is_current_package_family(&previous)?
+                && runtime.can_resume_registration()
+                && setup_complete,
+            "registration refresh requires unchanged sandbox ownership and settings"
+        );
+        for entry in &runtime.accounts {
+            let account = entry.account.username();
+            ensure!(
+                codex_windows_sandbox::local_user_flags(account)?
+                    .is_some_and(|flags| flags & UF_ACCOUNTDISABLE == 0)
+                    && string_from_sid_bytes(&codex_windows_sandbox::resolve_sid(account)?)
+                        .map_err(anyhow::Error::msg)?
+                        == entry.user_sid,
+                "registration refresh cannot replace a sandbox account"
+            );
+        }
+    }
+    let mut installation = super::register_owner(identity, on_authenticated_user)?;
+    let result = (|| -> Result<()> {
+        let package = Package::Current()?.Id()?;
+        installation.runtime.get_or_insert(RuntimeRegistration {
+            package_family: package.FamilyName()?.to_string(),
+            accounts: Vec::new(),
+            metadata_roots: Vec::new(),
+            ready_package: None,
+            retiring: None,
+        });
+        // Persist the authenticated owner before setup can rotate shared credentials.
+        crate::installation_record::save_runtime(&installation)?;
+        for account in [
+            codex_windows_sandbox::OFFLINE_USERNAME,
+            codex_windows_sandbox::ONLINE_USERNAME,
+        ] {
+            setup_complete &= codex_windows_sandbox::local_user_flags(account)?
+                .is_some_and(|flags| flags & UF_ACCOUNTDISABLE == 0);
+        }
+        if !setup_complete {
+            // Account state can change outside our setup lock; refresh must never repair it.
+            ensure!(
+                !request.refresh_only,
+                "registration refresh cannot repair sandbox setup"
+            );
+            // Setup resolves this name for ACL trustees; it must still name the held token's user.
+            let setup_owner_sid = codex_windows_sandbox::resolve_sid(&identity.account)?;
+            ensure!(
+                string_from_sid_bytes(&setup_owner_sid).map_err(anyhow::Error::msg)?
+                    == identity.user_sid,
+                "sandbox setup account no longer matches the authenticated owner"
+            );
+            codex_windows_sandbox::provision_sandbox_in_process(
+                &identity.codex_home,
+                &identity.account,
+                settings,
+                identity.runtime,
+            )?;
+        }
+        crate::registered_runtime::provision(
+            identity,
+            &mut installation,
+            &package.FullName()?,
+            shutdown,
+        )
+    })();
+    result
+        .inspect_err(|error| {
+            crate::service::log_error(
+                crate::service::EVENT_PROVISIONING_FAILED,
+                &format!("Codex sandbox provisioning failed: {error}"),
+            );
+        })
+        .context("registered sandbox provisioning failed")?;
+    crate::service::log_information(
+        crate::service::EVENT_PROVISIONING_SUCCEEDED,
+        "Codex sandbox provisioning completed successfully.",
+    );
+    Ok(SandboxProvisioningResponse::Ok)
+}
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime.rs b/codex-rs/windows-sandbox-service/src/registered_runtime.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f9fc438d40dcd6e52e98cd2d28e09023d9eb3802
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime.rs
@@ -0,0 +1,328 @@
+//! Owns managed-account registration, AppData metadata access, and deferred removal.
+//! Lifecycle and admission decisions stay with callers. Persist ownership before deployment;
+//! retain profiles until Windows completes, or pending resources until service exit on shutdown.
+
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use codex_windows_sandbox::APP_CORE_RUNNER_ALIAS;
+use codex_windows_sandbox::SandboxRuntimeAccount;
+use codex_windows_sandbox::logon_existing_sandbox_account;
+use codex_windows_sandbox::resolve_sid as lookup_sid;
+use codex_windows_sandbox::sandbox_secrets_dir;
+use codex_windows_sandbox::string_from_sid_bytes;
+use codex_windows_sandbox::to_wide;
+use codex_windows_sandbox::token_groups;
+use windows::Foundation::AsyncStatus;
+use windows::Management::Deployment::DeploymentOptions;
+use windows::Management::Deployment::PackageManager;
+use windows::Win32::Foundation::BOOL;
+use windows::core::HSTRING;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Security as security;
+use windows_sys::Win32::System::SystemServices::SE_GROUP_ENABLED;
+use windows_sys::Win32::UI::Shell::FOLDERID_LocalAppData;
+use windows_sys::Win32::UI::Shell::LoadUserProfileW;
+use windows_sys::Win32::UI::Shell::PROFILEINFOW;
+use windows_sys::Win32::UI::Shell::UnloadUserProfile;
+
+use crate::installation_record::InstallationRecord;
+use crate::installation_record::RuntimeAccountRegistration;
+use crate::ipc::ClientIdentity;
+use crate::package_lifecycle::with_owner_impersonation;
+
+mod known_folder;
+mod metadata;
+mod removal;
+
+pub(crate) use metadata::remove as remove_metadata;
+pub(crate) use removal::prepare as prepare_removal;
+
+/// Must escape request handling: pending resources are retained until this service exits.
+#[derive(Debug)]
+pub(crate) struct RegistrationInterrupted;
+
+impl std::fmt::Display for RegistrationInterrupted {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("runtime setup interrupted; stopping service")
+    }
+}
+
+impl std::error::Error for RegistrationInterrupted {}
+
+struct AccountProfile {
+    user_sid: String,
+    token: OwnedHandle,
+    profile: HANDLE,
+}
+
+impl Drop for AccountProfile {
+    fn drop(&mut self) {
+        let _ = self.unload_profile();
+    }
+}
+
+impl AccountProfile {
+    fn unload_profile(&mut self) -> Result<()> {
+        if self.profile != 0 {
+            let unloaded =
+                unsafe { UnloadUserProfile(self.token.as_raw_handle() as _, self.profile) };
+            BOOL(unloaded)
+                .ok()
+                .context("unload managed runtime account profile")?;
+            self.profile = 0;
+        }
+        Ok(())
+    }
+}
+
+/// The caller holds the setup mutex from owner admission through readiness.
+/// Provision both users together. No runner launch performs package deployment.
+pub(crate) fn provision(
+    identity: &ClientIdentity,
+    record: &mut InstallationRecord,
+    full_name: &HSTRING,
+    shutdown: &AtomicBool,
+) -> Result<()> {
+    let family = record.runtime()?.package_family.clone();
+    validate_record(record)?;
+    let mut profiles = Vec::new();
+    let mut accounts = Vec::new();
+    for account in [
+        SandboxRuntimeAccount::Offline,
+        SandboxRuntimeAccount::Online,
+    ] {
+        let token = with_owner_impersonation(identity.token.0, || {
+            let mut pins = Vec::new();
+            crate::ipc::pin_existing_ancestors(
+                &sandbox_secrets_dir(&identity.codex_home),
+                &mut pins,
+            )?;
+            logon_existing_sandbox_account(&identity.codex_home, account)
+        })?;
+        let expected = record
+            .runtime()?
+            .accounts
+            .iter()
+            .find(|entry| entry.account == account);
+        let profile = load_profile(
+            token,
+            account,
+            expected.map(|entry| entry.user_sid.as_str()),
+        )?;
+        let installed = registered_packages(&profile.user_sid, &family)?;
+        if expected.is_none() {
+            ensure!(
+                installed.is_empty(),
+                "sandbox account has a runtime registration not owned by this service"
+            );
+        }
+        let alias_path = known_folder::path(
+            profile.token.as_raw_handle() as _,
+            &FOLDERID_LocalAppData,
+            /*flags*/ 0,
+        )?
+        .join(r"Microsoft\WindowsApps")
+        .join(&family)
+        .join(APP_CORE_RUNNER_ALIAS);
+        accounts.push(RuntimeAccountRegistration {
+            account,
+            user_sid: profile.user_sid.clone(),
+            alias_path: Some(alias_path),
+        });
+        profiles.push((profile, installed.contains(full_name)));
+    }
+    let receipt_current = record.runtime()?.ready_for_package(&full_name.to_string())
+        && record.runtime()?.accounts == accounts
+        && profiles.iter().all(|(_, installed)| *installed);
+    // Both exact SIDs are durable before either package registration or metadata grant.
+    // An idempotent setup check must not temporarily revoke a valid launch receipt.
+    record.runtime_mut()?.accounts = accounts;
+    if !receipt_current {
+        record.runtime_mut()?.ready_package = None;
+        crate::installation_record::save_runtime(record)?;
+    }
+    for (mut profile, installed) in profiles {
+        if !installed {
+            let operation = with_owner_impersonation(profile.token.as_raw_handle() as _, || {
+                Ok(PackageManager::new()?.RegisterPackageByFullNameAsync(
+                    full_name,
+                    None,
+                    DeploymentOptions::None,
+                )?)
+            })?;
+            // As with provisioning, retain the request's resources until Windows finishes.
+            // A client timeout or an unreadable status cannot safely release the profile.
+            let mut status_error_logged = false;
+            loop {
+                if shutdown.load(Ordering::Acquire) {
+                    // The typed error bypasses all response conversion and cleanup. Keep the
+                    // in-flight operation and its profile alive until this own-process service exits.
+                    std::mem::forget((operation, profile));
+                    return Err(RegistrationInterrupted.into());
+                }
+                match operation.Status() {
+                    Ok(AsyncStatus::Started) => {}
+                    Ok(AsyncStatus::Completed | AsyncStatus::Canceled | AsyncStatus::Error) => {
+                        break;
+                    }
+                    status => {
+                        if !status_error_logged {
+                            crate::service::log_error(
+                                crate::service::EVENT_SERVICE_FAILED,
+                                &format!(
+                                    "runtime registration status unavailable; retaining request: {status:?}"
+                                ),
+                            );
+                            status_error_logged = true;
+                        }
+                    }
+                }
+                std::thread::sleep(Duration::from_millis(50));
+            }
+            operation.GetResults()?.ExtendedErrorCode()?.ok()?;
+            ensure!(
+                registered_packages(&profile.user_sid, &family)?.contains(full_name),
+                "runtime registration completed without the expected package"
+            );
+        }
+        metadata::grant(identity.token.0, &profile.user_sid, record)?;
+        profile.unload_profile()?;
+    }
+    if !receipt_current {
+        record.runtime_mut()?.ready_package = Some(full_name.to_string());
+        crate::installation_record::save_runtime(record)?;
+    }
+    Ok(())
+}
+
+/// Prepare one retirement fence under the caller's setup lock. Removal preparation
+/// then retains exact account logons before the native guard disables those users.
+pub(crate) fn prepare_cleanup(mut record: InstallationRecord) -> Result<InstallationRecord> {
+    validate_record(&record)?;
+    for account in &record.runtime()?.accounts {
+        if codex_windows_sandbox::local_user_flags(account.account.username())?.is_some() {
+            let sid = lookup_sid(account.account.username())?;
+            ensure!(
+                string_from_sid_bytes(&sid).map_err(anyhow::Error::msg)? == account.user_sid,
+                "managed runtime account was replaced before cleanup"
+            );
+        }
+    }
+    ensure!(
+        record.runtime()?.retiring.is_none(),
+        "interrupted runtime cleanup requires repair"
+    );
+    record.runtime_mut()?.ready_package = None;
+    record.runtime_mut()?.retiring = Some(format!("{:?}", windows::core::GUID::new()?));
+    Ok(record)
+}
+
+fn validate_record(record: &InstallationRecord) -> Result<()> {
+    let runtime = record.runtime()?;
+    ensure!(
+        runtime.accounts.len() <= 2,
+        "runtime registration record has too many accounts"
+    );
+    if runtime.accounts.len() == 2 {
+        ensure!(
+            runtime.accounts[0].account != runtime.accounts[1].account,
+            "runtime registration record contains duplicate accounts"
+        );
+    }
+    Ok(())
+}
+
+fn registered_packages(user_sid: &str, family: &str) -> Result<Vec<HSTRING>> {
+    let packages = PackageManager::new()?.FindPackagesByUserSecurityIdPackageFamilyName(
+        &HSTRING::from(user_sid),
+        &HSTRING::from(family),
+    )?;
+    // The Rust Iterator adapter suppresses Current/MoveNext errors. Absence must
+    // be authoritative before releasing cleanup ownership or its package anchor.
+    let iterator = packages.First()?;
+    let mut names = Vec::new();
+    let mut has_current = iterator.HasCurrent()?;
+    while has_current {
+        names.push(iterator.Current()?.Id()?.FullName()?);
+        has_current = iterator.MoveNext()?;
+    }
+    Ok(names)
+}
+
+/// An intent is not an anchor: failed registration may leave no managed package.
+pub(crate) fn has_retaining_registration(record: &InstallationRecord) -> Result<bool> {
+    let runtime = record.runtime()?;
+    for account in &runtime.accounts {
+        if !registered_packages(&account.user_sid, &runtime.package_family)?.is_empty() {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+fn load_profile(
+    token: OwnedHandle,
+    account: SandboxRuntimeAccount,
+    expected_sid: Option<&str>,
+) -> Result<AccountProfile> {
+    let user_sid = validate_target(token.as_raw_handle() as _, account, expected_sid)?;
+    let mut username = to_wide(account.username());
+    let mut profile: PROFILEINFOW = unsafe { std::mem::zeroed() };
+    profile.dwSize = std::mem::size_of::<PROFILEINFOW>() as u32;
+    profile.dwFlags = 1; // PI_NOUI: service operations never prompt interactively.
+    profile.lpUserName = username.as_mut_ptr();
+    unsafe { BOOL(LoadUserProfileW(token.as_raw_handle() as _, &mut profile)).ok() }
+        .context("load managed runtime account profile")?;
+    Ok(AccountProfile {
+        user_sid,
+        token,
+        profile: profile.hProfile,
+    })
+}
+
+fn validate_target(
+    token: HANDLE,
+    account: SandboxRuntimeAccount,
+    expected_sid: Option<&str>,
+) -> Result<String> {
+    let user = unsafe { codex_windows_sandbox::get_user_sid_bytes(token) }?;
+    let user_sid = string_from_sid_bytes(&user).map_err(anyhow::Error::msg)?;
+    ensure!(
+        expected_sid.is_none_or(|expected| expected == user_sid),
+        "managed runtime account SID changed"
+    );
+    ensure!(
+        lookup_sid(account.username())? == user,
+        "managed runtime account was replaced"
+    );
+    let groups = unsafe {
+        token_groups(token, /*max_bytes*/ 65_536)
+    }
+    .context("read runtime account groups")?;
+    ensure!(groups.len() <= 256, "invalid runtime account groups");
+    let sandbox_group = lookup_sid(codex_windows_sandbox::SANDBOX_USERS_GROUP)?;
+    let mut sandbox_member = false;
+    for group in groups {
+        ensure!(
+            string_from_sid_bytes(&group.sid).map_err(anyhow::Error::msg)? != "S-1-5-32-544",
+            "managed runtime account is an administrator"
+        );
+        if unsafe { security::EqualSid(group.sid.as_ptr() as _, sandbox_group.as_ptr() as _) } != 0
+            && group.attributes & SE_GROUP_ENABLED as u32 != 0
+        {
+            sandbox_member = true;
+        }
+    }
+    ensure!(
+        sandbox_member,
+        "runtime account is not in CodexSandboxUsers"
+    );
+    Ok(user_sid)
+}
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime/known_folder.rs b/codex-rs/windows-sandbox-service/src/registered_runtime/known_folder.rs
new file mode 100644
index 0000000000000000000000000000000000000000..e695f635781a6113e59d4eb0c7206d90b3fcbd19
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime/known_folder.rs
@@ -0,0 +1,32 @@
+//! Resolves Known Folders for an explicit token and caller-selected flags.
+//! Preserve Windows UTF-16 paths and free the returned allocation on every result.
+
+use std::ffi::OsString;
+use std::os::windows::ffi::OsStringExt;
+use std::path::PathBuf;
+
+use anyhow::Result;
+use anyhow::ensure;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::System::Com::CoTaskMemFree;
+use windows_sys::Win32::UI::Shell::SHGetKnownFolderPath;
+use windows_sys::core::GUID;
+
+pub(super) fn path(token: HANDLE, folder: &GUID, flags: u32) -> Result<PathBuf> {
+    let mut raw = std::ptr::null_mut();
+    let status = unsafe { SHGetKnownFolderPath(folder, flags, token, &mut raw) };
+    let result = (|| {
+        windows::core::HRESULT(status).ok()?;
+        ensure!(!raw.is_null(), "Known Folder path missing");
+        let mut length = 0;
+        while length < 32768 && unsafe { *raw.add(length) } != 0 {
+            length += 1;
+        }
+        ensure!(length < 32768, "Known Folder path exceeds bound");
+        Ok(PathBuf::from(OsString::from_wide(unsafe {
+            std::slice::from_raw_parts(raw, length)
+        })))
+    })();
+    unsafe { CoTaskMemFree(raw.cast()) };
+    result
+}
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime/metadata.rs b/codex-rs/windows-sandbox-service/src/registered_runtime/metadata.rs
new file mode 100644
index 0000000000000000000000000000000000000000..48cd4e66d06a15196d77f80b569da3dd8b5c96a6
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime/metadata.rs
@@ -0,0 +1,326 @@
+//! Gives registered commands metadata access to the owner's two AppData roots.
+//! No file contents or descendants are granted. Persist the managed account and
+//! each owner-authorized root before granting access, so cleanup includes former roots.
+
+use std::io;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::OwnedHandle;
+use std::path::Path;
+use std::ptr;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use codex_windows_sandbox::DirectoryOpenDisposition;
+use codex_windows_sandbox::LocalSid;
+use codex_windows_sandbox::open_directory_no_reparse;
+use windows::Win32::Foundation::BOOL;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::Foundation::LocalFree;
+use windows_sys::Win32::Foundation::RtlNtStatusToDosError;
+use windows_sys::Win32::Security as security;
+use windows_sys::Win32::Security::Authorization as authorization;
+use windows_sys::Win32::Storage::FileSystem as filesystem;
+use windows_sys::Win32::UI::Shell as shell;
+
+use super::known_folder::path as known_folder;
+use crate::installation_record::InstallationRecord;
+use crate::package_lifecycle::with_owner_impersonation;
+
+const OWNER_FOLDER_FLAGS: u32 =
+    (shell::KF_FLAG_DONT_VERIFY | shell::KF_FLAG_NO_PACKAGE_REDIRECTION) as u32;
+
+#[link(name = "ntdll")]
+unsafe extern "system" {
+    fn NtSetSecurityObject(
+        handle: HANDLE,
+        information: u32,
+        descriptor: *const security::SECURITY_DESCRIPTOR,
+    ) -> i32;
+}
+
+pub(super) fn grant(
+    owner_token: HANDLE,
+    user_sid: &str,
+    record: &mut InstallationRecord,
+) -> Result<()> {
+    ensure!(
+        record
+            .runtime()?
+            .accounts
+            .iter()
+            .any(|account| account.user_sid == user_sid),
+        "AppData metadata access requires a recorded managed account"
+    );
+    let sid = LocalSid::from_string(user_sid)?;
+    for folder in [shell::FOLDERID_LocalAppData, shell::FOLDERID_RoamingAppData] {
+        let path = known_folder(owner_token, &folder, OWNER_FOLDER_FLAGS)?;
+        edit_root_acl(owner_token, &path, |acl| {
+            // The owner-authorized directory and its ancestors are pinned here.
+            // Commit provenance before any ACE mutation, including a partial grant.
+            if !record.runtime()?.metadata_roots.contains(&path) {
+                record.runtime_mut()?.metadata_roots.push(path.clone());
+                crate::installation_record::save_runtime(record)?;
+            }
+            if metadata_ace(acl, &sid)?.is_some() {
+                return Ok(false);
+            }
+            // Packaged Known Folder APIs verify these directory objects even when
+            // APPDATA is inherited. Do not grant listing, contents, or inheritance.
+            insert_metadata_ace(acl, &sid)?;
+            Ok(true)
+        })?;
+    }
+    Ok(())
+}
+
+/// Removes exact grants from all recorded roots before account deletion.
+pub(crate) fn remove(token: HANDLE, record: &InstallationRecord) -> Result<()> {
+    let runtime = record.runtime()?;
+    let accounts = &runtime.accounts;
+    if accounts.is_empty() {
+        return Ok(());
+    }
+    let mut errors = Vec::new();
+    // Every grant records its root before changing permissions, including redirects.
+    for path in &runtime.metadata_roots {
+        let result = edit_root_acl(token, path, |acl| {
+            let mut changed = false;
+            for account in accounts {
+                let sid = LocalSid::from_string(&account.user_sid)?;
+                while let Some(index) = metadata_ace(acl, &sid)? {
+                    unsafe { BOOL(security::DeleteAce(acl.as_mut_ptr().cast(), index)).ok() }
+                        .context("remove AppData metadata ACE")?;
+                    changed = true;
+                }
+            }
+            Ok(changed)
+        });
+        if let Err(error) = result
+            && error
+                .downcast_ref::<io::Error>()
+                .is_none_or(|error| error.kind() != io::ErrorKind::NotFound)
+        {
+            errors.push(format!("{error:#}"));
+        }
+    }
+    ensure!(
+        errors.is_empty(),
+        "AppData metadata cleanup: {}",
+        errors.join("; ")
+    );
+    Ok(())
+}
+
+fn edit_root_acl(
+    token: HANDLE,
+    path: &Path,
+    edit: impl FnOnce(&mut Vec<u32>) -> Result<bool>,
+) -> Result<()> {
+    let (_pins, handle) = with_owner_impersonation(token, || {
+        let mut pins = Vec::new();
+        crate::ipc::pin_existing_ancestors(path, &mut pins)?;
+        let handle = open_directory_no_reparse(
+            path,
+            filesystem::READ_CONTROL
+                | filesystem::WRITE_DAC
+                | filesystem::FILE_READ_ATTRIBUTES
+                | filesystem::FILE_TRAVERSE,
+            filesystem::FILE_SHARE_READ | filesystem::FILE_SHARE_WRITE,
+            DirectoryOpenDisposition::OpenExisting,
+        )?;
+        Ok((pins, handle))
+    })?;
+    let Some((mut acl, control)) = read_acl(&handle)? else {
+        return Ok(()); // A null DACL already allows metadata; never replace it.
+    };
+    if edit(&mut acl)? {
+        write_acl(&handle, &mut acl, control)?;
+    }
+    Ok(())
+}
+
+fn read_acl(handle: &OwnedHandle) -> Result<Option<(Vec<u32>, u16)>> {
+    let mut acl = ptr::null_mut();
+    let mut descriptor = ptr::null_mut();
+    let status = unsafe {
+        authorization::GetSecurityInfo(
+            handle.as_raw_handle() as _,
+            authorization::SE_FILE_OBJECT,
+            security::DACL_SECURITY_INFORMATION,
+            ptr::null_mut(),
+            ptr::null_mut(),
+            &mut acl,
+            ptr::null_mut(),
+            &mut descriptor,
+        )
+    };
+    if status != 0 {
+        return Err(io::Error::from_raw_os_error(status as i32)).context("read AppData DACL");
+    }
+    let result = (|| {
+        if acl.is_null() {
+            return Ok(None);
+        }
+        ensure!(
+            unsafe { security::IsValidAcl(acl) } != 0,
+            "invalid AppData DACL"
+        );
+        let length = unsafe { (*acl).AclSize } as usize;
+        let mut control = 0;
+        let mut revision = 0;
+        let queried = unsafe {
+            security::GetSecurityDescriptorControl(descriptor, &mut control, &mut revision)
+        };
+        BOOL(queried).ok().context("read AppData DACL control")?;
+        let mut buffer = vec![0u32; length.div_ceil(4)];
+        unsafe {
+            ptr::copy_nonoverlapping(acl.cast::<u8>(), buffer.as_mut_ptr().cast(), length);
+        }
+        Ok(Some((buffer, control)))
+    })();
+    unsafe { LocalFree(descriptor as _) };
+    result
+}
+
+fn metadata_ace(acl: &mut [u32], sid: &LocalSid) -> Result<Option<u32>> {
+    let acl = acl.as_mut_ptr().cast::<security::ACL>();
+    for index in 0..u32::from(unsafe { (*acl).AceCount }) {
+        let mut raw = ptr::null_mut();
+        unsafe { BOOL(security::GetAce(acl, index, &mut raw)).ok() }.context("read AppData ACE")?;
+        let offset = raw as usize - acl as usize;
+        ensure!(
+            offset + std::mem::size_of::<security::ACE_HEADER>()
+                <= usize::from(unsafe { (*acl).AclSize }),
+            "AppData ACE header exceeds ACL"
+        );
+        let header = unsafe { &*raw.cast::<security::ACE_HEADER>() };
+        ensure!(
+            offset + usize::from(header.AceSize) <= usize::from(unsafe { (*acl).AclSize }),
+            "AppData ACE exceeds ACL"
+        );
+        if header.AceType == 0 && header.AceFlags == 0 {
+            ensure!(header.AceSize >= 16, "AppData allow ACE is truncated");
+            let ace = unsafe { &*raw.cast::<security::ACCESS_ALLOWED_ACE>() };
+            let sid_pointer = ptr::addr_of!(ace.SidStart) as *mut std::ffi::c_void;
+            let subauthorities = unsafe { *sid_pointer.cast::<u8>().add(1) } as usize;
+            ensure!(
+                subauthorities <= 15 && 16 + subauthorities * 4 <= usize::from(header.AceSize),
+                "AppData allow ACE SID is truncated"
+            );
+            ensure!(
+                unsafe { security::IsValidSid(sid_pointer) } != 0,
+                "AppData allow ACE SID is invalid"
+            );
+            if ace.Mask == filesystem::FILE_READ_ATTRIBUTES
+                && unsafe { security::EqualSid(sid_pointer, sid.as_ptr()) } != 0
+            {
+                return Ok(Some(index));
+            }
+        }
+    }
+    Ok(None)
+}
+
+fn insert_metadata_ace(acl: &mut Vec<u32>, sid: &LocalSid) -> Result<()> {
+    let capacity = usize::from(unsafe { (*acl.as_ptr().cast::<security::ACL>()).AclSize })
+        + 8
+        + unsafe { security::GetLengthSid(sid.as_ptr()) } as usize;
+    ensure!(capacity <= u16::MAX as usize, "AppData DACL is full");
+    acl.resize(capacity.div_ceil(4), 0);
+    unsafe { (*acl.as_mut_ptr().cast::<security::ACL>()).AclSize = capacity as u16 };
+    let mut single = [0u32; 32];
+    let single_acl = single.as_mut_ptr().cast();
+    unsafe {
+        BOOL(security::InitializeAcl(
+            single_acl,
+            std::mem::size_of_val(&single) as u32,
+            security::ACL_REVISION_DS,
+        ))
+        .ok()
+        .context("initialize AppData metadata ACE")?;
+        BOOL(security::AddAccessAllowedAceEx(
+            single_acl,
+            security::ACL_REVISION_DS,
+            0,
+            filesystem::FILE_READ_ATTRIBUTES,
+            sid.as_ptr(),
+        ))
+        .ok()
+        .context("construct AppData metadata ACE")?;
+    }
+    let mut added = ptr::null_mut();
+    unsafe { BOOL(security::GetAce(single_acl, 0, &mut added)).ok() }
+        .context("read new AppData metadata ACE")?;
+    let acl = acl.as_mut_ptr().cast::<security::ACL>();
+    let mut position = u32::from(unsafe { (*acl).AceCount });
+    for index in 0..position {
+        let mut raw = ptr::null_mut();
+        unsafe { BOOL(security::GetAce(acl, index, &mut raw)).ok() }
+            .context("read AppData ACE order")?;
+        if unsafe { (*raw.cast::<security::ACE_HEADER>()).AceFlags } & security::INHERITED_ACE as u8
+            != 0
+        {
+            position = index;
+            break;
+        }
+    }
+    unsafe {
+        BOOL(security::AddAce(
+            acl,
+            security::ACL_REVISION_DS,
+            position,
+            added,
+            u32::from((*added.cast::<security::ACE_HEADER>()).AceSize),
+        ))
+        .ok()
+    }
+    .context("insert AppData metadata ACE")?;
+    Ok(())
+}
+
+fn write_acl(handle: &OwnedHandle, acl: &mut [u32], control: u16) -> Result<()> {
+    let mut descriptor: security::SECURITY_DESCRIPTOR = unsafe { std::mem::zeroed() };
+    let preserved = security::SE_DACL_PROTECTED | security::SE_DACL_AUTO_INHERITED;
+    let raw_descriptor = (&mut descriptor as *mut security::SECURITY_DESCRIPTOR).cast();
+    unsafe {
+        BOOL(security::InitializeSecurityDescriptor(raw_descriptor, 1))
+            .ok()
+            .context("initialize AppData security descriptor")?;
+        BOOL(security::SetSecurityDescriptorDacl(
+            raw_descriptor,
+            1,
+            acl.as_mut_ptr().cast(),
+            i32::from(control & security::SE_DACL_DEFAULTED != 0),
+        ))
+        .ok()
+        .context("set AppData DACL")?;
+        BOOL(security::SetSecurityDescriptorControl(
+            raw_descriptor,
+            preserved,
+            control & preserved,
+        ))
+        .ok()
+        .context("preserve AppData DACL control")?;
+    }
+    // SetSecurityInfo recursively reapplies existing inheritable ACEs. The native
+    // object setter changes only this retained, owner-authorized directory handle.
+    let status = unsafe {
+        NtSetSecurityObject(
+            handle.as_raw_handle() as _,
+            security::DACL_SECURITY_INFORMATION,
+            &descriptor,
+        )
+    };
+    if status < 0 {
+        return Err(io::Error::from_raw_os_error(
+            unsafe { RtlNtStatusToDosError(status) } as i32,
+        ))
+        .context("write AppData metadata DACL");
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "metadata_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime/metadata_tests.rs b/codex-rs/windows-sandbox-service/src/registered_runtime/metadata_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..72199f12752ca8bbc455c8a744f4b7b80abf48d7
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime/metadata_tests.rs
@@ -0,0 +1,97 @@
+//! Tests that metadata ACE edits preserve unrelated, inherited, and broader permissions.
+
+use super::*;
+
+fn ace_bytes(acl: &mut [u32]) -> Vec<Vec<u8>> {
+    let acl = acl.as_mut_ptr().cast::<security::ACL>();
+    (0..u32::from(unsafe { (*acl).AceCount }))
+        .map(|index| {
+            let mut raw = ptr::null_mut();
+            assert_ne!(unsafe { security::GetAce(acl, index, &mut raw) }, 0);
+            let length = unsafe { (*raw.cast::<security::ACE_HEADER>()).AceSize } as usize;
+            unsafe { std::slice::from_raw_parts(raw.cast::<u8>(), length) }.to_vec()
+        })
+        .collect()
+}
+
+fn existing_acl(sid: &LocalSid) -> Vec<u32> {
+    let mut acl = vec![0u32; 256];
+    let raw = acl.as_mut_ptr().cast();
+    assert_ne!(
+        unsafe { security::InitializeAcl(raw, 1024, security::ACL_REVISION_DS) },
+        0
+    );
+    assert_ne!(
+        unsafe {
+            security::AddAccessDeniedAceEx(
+                raw,
+                security::ACL_REVISION_DS,
+                0,
+                filesystem::FILE_WRITE_DATA,
+                sid.as_ptr(),
+            )
+        },
+        0
+    );
+    assert_ne!(
+        unsafe {
+            security::AddAccessAllowedAceEx(
+                raw,
+                security::ACL_REVISION_DS,
+                0,
+                filesystem::FILE_READ_DATA | filesystem::FILE_READ_ATTRIBUTES,
+                sid.as_ptr(),
+            )
+        },
+        0
+    );
+    assert_ne!(
+        unsafe {
+            security::AddAccessAllowedAceEx(
+                raw,
+                security::ACL_REVISION_DS,
+                security::INHERITED_ACE,
+                filesystem::FILE_READ_ATTRIBUTES,
+                sid.as_ptr(),
+            )
+        },
+        0
+    );
+    acl
+}
+
+#[test]
+fn metadata_grant_and_cleanup_preserve_broader_and_inherited_aces() -> Result<()> {
+    let sid = LocalSid::from_string("S-1-5-21-1-2-3-1001")?;
+    let mut acl = existing_acl(&sid);
+    let before = ace_bytes(&mut acl);
+    assert_eq!(metadata_ace(&mut acl, &sid)?, None);
+    insert_metadata_ace(&mut acl, &sid)?;
+    assert_eq!(metadata_ace(&mut acl, &sid)?, Some(2));
+    assert_ne!(unsafe { security::IsValidAcl(acl.as_mut_ptr().cast()) }, 0);
+    assert_ne!(
+        unsafe { security::DeleteAce(acl.as_mut_ptr().cast(), 2) },
+        0
+    );
+    assert_eq!(ace_bytes(&mut acl), before);
+    Ok(())
+}
+
+#[test]
+fn metadata_cleanup_handles_duplicates_without_touching_another_principal() -> Result<()> {
+    let sid = LocalSid::from_string("S-1-5-21-1-2-3-1001")?;
+    let other = LocalSid::from_string("S-1-5-21-1-2-3-1002")?;
+    let mut acl = existing_acl(&sid);
+    let before = ace_bytes(&mut acl);
+    insert_metadata_ace(&mut acl, &sid)?;
+    assert_eq!(metadata_ace(&mut acl, &other)?, None);
+    insert_metadata_ace(&mut acl, &sid)?;
+    while let Some(index) = metadata_ace(&mut acl, &sid)? {
+        assert_ne!(
+            unsafe { security::DeleteAce(acl.as_mut_ptr().cast(), index) },
+            0
+        );
+    }
+    assert_eq!(ace_bytes(&mut acl), before);
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime/removal.ps1 b/codex-rs/windows-sandbox-service/src/registered_runtime/removal.ps1
new file mode 100644
index 0000000000000000000000000000000000000000..17ff74f57eb5bd690a23d530cc2f0619f73b61c0
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime/removal.ps1
@@ -0,0 +1,191 @@
+$ErrorActionPreference = 'Stop'
+$PSModuleAutoLoadingPreference = 'None'
+Import-Module -Name ($PSHOME + '\Modules\Microsoft.PowerShell.Utility\Microsoft.PowerShell.Utility.psd1') -ErrorAction Stop
+Import-Module -Name ($PSHOME + '\Modules\Appx\Appx.psd1') -ErrorAction Stop
+Import-Module -Name ($PSHOME + '\Modules\Microsoft.PowerShell.Management\Microsoft.PowerShell.Management.psd1') -ErrorAction Stop
+if ([Security.Principal.WindowsIdentity]::GetCurrent().User.Value -ne 'S-1-5-18') { throw 'SYSTEM required' }
+# Rust sends UTF-8 regardless of the machine's console code page. Keep one reader
+# for the complete protocol so read-ahead cannot consume COMMIT or its EOF fence.
+$protocolInput = [IO.StreamReader]::new([Console]::OpenStandardInput(), [Text.UTF8Encoding]::new($false, $true), $false)
+$planJson = $protocolInput.ReadLine()
+if (!$planJson) { return }
+$plan = Microsoft.PowerShell.Utility\ConvertFrom-Json -InputObject $planJson
+if ([string]::IsNullOrEmpty($plan.record.runtime.retiring)) { throw 'Retirement generation required' }
+if (@($plan.targets).Count -gt 2) { throw 'Too many cleanup tokens' }
+Add-Type -TypeDefinition @"
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+public static class CleanupNative {
+ [StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)] public struct Profile { public int size,flags; public string user,path,def,server,policy; public IntPtr handle; }
+ [StructLayout(LayoutKind.Sequential)] public struct Luid { public uint lo; public int hi; }
+ [StructLayout(LayoutKind.Sequential)] public struct Priv { public uint count; public Luid luid; public uint attributes; }
+ [DllImport("userenv.dll",CharSet=CharSet.Unicode,SetLastError=true)] public static extern bool LoadUserProfile(IntPtr t,ref Profile p);
+ [DllImport("userenv.dll",SetLastError=true)] public static extern bool UnloadUserProfile(IntPtr t,IntPtr p);
+ [DllImport("userenv.dll",CharSet=CharSet.Unicode,SetLastError=true)] public static extern bool DeleteProfile(string sid,string path,string computer);
+ [StructLayout(LayoutKind.Sequential)] struct User23 { public IntPtr name,fullName,comment; public uint flags; public IntPtr sid; }
+ [DllImport("netapi32.dll",CharSet=CharSet.Unicode)] static extern int NetUserGetInfo(string server,string user,int level,out IntPtr info);
+ [DllImport("netapi32.dll",CharSet=CharSet.Unicode)] static extern int NetUserDel(string server,string user);
+ [DllImport("netapi32.dll")] static extern int NetApiBufferFree(IntPtr info);
+ [DllImport("netapi32.dll",CharSet=CharSet.Unicode)] public static extern int NetLocalGroupDel(string server,string group);
+ [DllImport("advapi32.dll",CharSet=CharSet.Unicode)] static extern IntPtr RegisterEventSource(string server,string source);
+ [DllImport("advapi32.dll",CharSet=CharSet.Unicode)] static extern bool ReportEvent(IntPtr h,ushort type,ushort category,uint id,IntPtr sid,ushort count,uint size,string[] messages,IntPtr data);
+ [DllImport("advapi32.dll")] static extern bool DeregisterEventSource(IntPtr h);
+ public static void Log(string source,ushort type,uint id,string message) { IntPtr h=RegisterEventSource(null,source); if(h==IntPtr.Zero)return; try { ReportEvent(h,type,0,id,IntPtr.Zero,1,0,new[]{message.Substring(0,Math.Min(message.Length,4096))},IntPtr.Zero); } finally { DeregisterEventSource(h); } }
+ public static void DeleteUser(string user,string sid) { IntPtr p; int status=NetUserGetInfo(null,user,23,out p); if(status==2221)return; if(status!=0)throw new Win32Exception(status); try { User23 info=(User23)Marshal.PtrToStructure(p,typeof(User23)); if(new System.Security.Principal.SecurityIdentifier(info.sid).Value!=sid || (info.flags&2)==0)throw new InvalidOperationException("Sandbox account changed or was re-enabled"); } finally { NetApiBufferFree(p); } status=NetUserDel(null,user); if(status!=0 && status!=2221)throw new Win32Exception(status); }
+ [DllImport("advapi32.dll",SetLastError=true)] public static extern bool ImpersonateLoggedOnUser(IntPtr t);
+ [DllImport("advapi32.dll",SetLastError=true)] public static extern bool RevertToSelf();
+ [DllImport("kernel32.dll")] public static extern bool CloseHandle(IntPtr h);
+ [DllImport("kernel32.dll")] public static extern IntPtr GetCurrentProcess();
+ [DllImport("advapi32.dll",SetLastError=true)] static extern bool OpenProcessToken(IntPtr p,uint a,out IntPtr t);
+ [DllImport("advapi32.dll",CharSet=CharSet.Unicode,SetLastError=true)] static extern bool LookupPrivilegeValue(string s,string n,out Luid l);
+ [DllImport("advapi32.dll",SetLastError=true)] static extern bool AdjustTokenPrivileges(IntPtr t,bool d,ref Priv p,int len,IntPtr old,IntPtr ret);
+ public static void Enable(string n) { IntPtr t; Luid l; if(!OpenProcessToken(GetCurrentProcess(),0x28,out t))throw new Win32Exception(); try { if(!LookupPrivilegeValue(null,n,out l))throw new Win32Exception(); Priv p=new Priv{count=1,luid=l,attributes=2}; if(!AdjustTokenPrivileges(t,false,ref p,0,IntPtr.Zero,IntPtr.Zero))throw new Win32Exception(); int e=Marshal.GetLastWin32Error(); if(e!=0)throw new Win32Exception(e); } finally { CloseHandle(t); } }
+ public static void Revert() { if(!RevertToSelf())Environment.FailFast("Cleanup impersonation revert failed"); }
+}
+"@
+Add-Type -AssemblyName System.Runtime.WindowsRuntime
+$null = [Windows.Management.Deployment.PackageManager,Windows.Management.Deployment,ContentType=WindowsRuntime]
+$null = [Windows.Management.Deployment.DeploymentResult,Windows.Management.Deployment,ContentType=WindowsRuntime]
+$null = [Windows.Management.Deployment.DeploymentProgress,Windows.Management.Deployment,ContentType=WindowsRuntime]
+$asTask = [System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object { $_.Name -eq 'AsTask' -and $_.IsGenericMethod -and $_.GetGenericArguments().Count -eq 2 -and $_.GetParameters().Count -eq 1 } | Select-Object -First 1
+$await = $asTask.MakeGenericMethod([Windows.Management.Deployment.DeploymentResult],[Windows.Management.Deployment.DeploymentProgress])
+$profiles = @()
+$removedRegistrations = @{}
+try {
+    [CleanupNative]::Enable('SeBackupPrivilege')
+    [CleanupNative]::Enable('SeRestorePrivilege')
+    foreach ($target in $plan.targets) {
+        $token = [IntPtr][long]$target.handle
+        $identity = [Security.Principal.WindowsIdentity]::new($token)
+        try { if ($identity.User.Value -cne $target.sid) { throw 'Cleanup token SID mismatch' } }
+        finally { $identity.Dispose() }
+        $profile = New-Object CleanupNative+Profile
+        $profile.size = [Runtime.InteropServices.Marshal]::SizeOf($profile)
+        $profile.flags = 1
+        $profile.user = $target.username
+        if (![CleanupNative]::LoadUserProfile($token, [ref]$profile)) { throw [ComponentModel.Win32Exception]::new([Runtime.InteropServices.Marshal]::GetLastWin32Error()) }
+        $profiles += @{ token = $token; profile = $profile; sid = $target.sid }
+    }
+    [Console]::Out.WriteLine('READY')
+    # EOF without a successful native-cleanup commit only unloads profiles.
+    if ($protocolInput.ReadLine() -cne 'COMMIT') { return }
+    # Even after COMMIT, removal must wait until the service releases its own package.
+    if ($protocolInput.ReadToEnd().Length -ne 0) { return }
+    $finished = $false
+    while (!$finished) {
+        $mutex = $null; $locked = $false; $key = $null; $legacy = $null
+        try {
+            $security = [Security.AccessControl.MutexSecurity]::new()
+            $security.SetSecurityDescriptorSddlForm('D:P(A;;GA;;;SY)(A;;GA;;;BA)')
+            $created = $false
+            $mutex = [Threading.Mutex]::new($false, 'Global\CodexSandboxSetup', [ref]$created, $security)
+            try { $locked = $mutex.WaitOne(30000) }
+            catch [Threading.AbandonedMutexException] { $locked = $true }
+            if (!$locked) { throw 'Sandbox setup is still active' }
+            $key = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey($plan.key, $true)
+            if (!$key) { return }
+            $record = Microsoft.PowerShell.Utility\ConvertFrom-Json -InputObject ([string]$key.GetValue($plan.value))
+            if ($record.runtime.retiring -ne $plan.record.runtime.retiring -or
+                $record.user_sid -ne $plan.record.user_sid -or
+                $record.codex_home -ne $plan.record.codex_home -or
+                $record.runtime.package_family -ne $plan.record.runtime.package_family) { return }
+            foreach ($entry in $profiles) {
+                if ($removedRegistrations.ContainsKey($entry.sid)) { continue }
+                foreach ($package in @(Appx\Get-AppxPackage -User $entry.sid -ErrorAction Stop)) {
+                    if ($package.PackageFamilyName -ne $record.runtime.package_family) { continue }
+                    if (![CleanupNative]::ImpersonateLoggedOnUser($entry.token)) { throw 'Cleanup impersonation failed' }
+                    try {
+                        if ([Security.Principal.WindowsIdentity]::GetCurrent().User.Value -cne $entry.sid) { throw 'Cleanup identity changed' }
+                        # Construct and submit synchronously under the retained user, not SYSTEM.
+                        $manager = [Windows.Management.Deployment.PackageManager]::new()
+                        $operation = $manager.RemovePackageAsync($package.PackageFullName)
+                    } finally { [CleanupNative]::Revert() }
+                    # Failure to obtain a waiter is not proof the operation stopped.
+                    $task = $null
+                    while (!$task) {
+                        try { $task = $await.Invoke($null, @($operation)) }
+                        catch { Microsoft.PowerShell.Utility\Start-Sleep -Seconds 1 }
+                    }
+                    while (!$task.IsCompleted) { Microsoft.PowerShell.Utility\Start-Sleep -Milliseconds 50 }
+                    $result = $task.GetAwaiter().GetResult()
+                    if ($result.ExtendedErrorCode -and $result.ExtendedErrorCode.HResult -ne 0) { throw $result.ErrorText }
+                }
+            }
+            foreach ($account in $plan.record.runtime.accounts) {
+                if ($removedRegistrations.ContainsKey($account.user_sid)) { continue }
+                foreach ($package in @(Appx\Get-AppxPackage -User $account.user_sid -ErrorAction Stop)) {
+                    if ($package.PackageFamilyName -eq $record.runtime.package_family) { throw 'Runtime registration remains' }
+                }
+                $removedRegistrations[$account.user_sid] = $true
+            }
+            foreach ($account in $plan.record.runtime.accounts) {
+                $sid = $account.user_sid
+                foreach ($entry in $profiles) {
+                    if ($entry.sid -ne $sid -or $entry.profile.handle -eq [IntPtr]::Zero) { continue }
+                    if (![CleanupNative]::UnloadUserProfile($entry.token, $entry.profile.handle)) { throw [ComponentModel.Win32Exception]::new([Runtime.InteropServices.Marshal]::GetLastWin32Error()) }
+                    $entry.profile.handle = [IntPtr]::Zero
+                }
+                $profileKey = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey("SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList\$sid")
+                if ($profileKey) {
+                    $profileKey.Dispose()
+                    # PowerShell converts $null to an empty string; DeleteProfile requires native NULL.
+                    if (![CleanupNative]::DeleteProfile($sid, [NullString]::Value, [NullString]::Value)) { throw [ComponentModel.Win32Exception]::new([Runtime.InteropServices.Marshal]::GetLastWin32Error()) }
+                }
+                [CleanupNative]::DeleteUser(('CodexSandbox' + $account.account), $sid)
+                [CleanupNative]::Log($plan.service_name, 4, 3004, "Removed $($account.account) sandbox profile and account")
+            }
+            $groupSid = $null
+            try { if ($plan.group_sid) { $groupSid = ([Security.Principal.NTAccount]::new('CodexSandboxUsers')).Translate([Security.Principal.SecurityIdentifier]).Value } }
+            catch [Security.Principal.IdentityNotMappedException] { }
+            if ($groupSid) {
+                if ($groupSid -cne $plan.group_sid) { throw 'Sandbox group was replaced' }
+                $status = [CleanupNative]::NetLocalGroupDel($null, 'CodexSandboxUsers')
+                if ($status -ne 0 -and $status -ne 2220) { throw [ComponentModel.Win32Exception]::new($status) }
+            }
+            $legacy = [Microsoft.Win32.Registry]::LocalMachine.OpenSubKey($plan.legacy_key, $true)
+            if (!$legacy) { throw 'Installation parent is missing' }
+            $legacyJson = $legacy.GetValue($plan.value)
+            if ($legacyJson) {
+                $owner = Microsoft.PowerShell.Utility\ConvertFrom-Json -InputObject ([string]$legacyJson)
+                if ($owner.user_sid -eq $plan.record.user_sid -and $owner.codex_home -eq $plan.record.codex_home) { $legacy.DeleteValue($plan.value, $false) }
+            }
+            $key.Dispose(); $key = $null
+            $legacy.Flush()
+            [Microsoft.Win32.Registry]::LocalMachine.DeleteSubKey($plan.key, $false)
+            if ($legacy.SubKeyCount -eq 0 -and $legacy.ValueCount -eq 0) {
+                $legacy.Dispose(); $legacy = $null
+                [Microsoft.Win32.Registry]::LocalMachine.DeleteSubKey($plan.legacy_key, $false)
+            }
+            $finished = $true
+            [CleanupNative]::Log($plan.service_name, 4, 3003, 'Sandbox uninstall cleanup finished, including registered runtimes, profiles, and accounts')
+        } catch { [CleanupNative]::Log($plan.service_name, 1, 3004, "Runtime cleanup deferred: $_") }
+        finally {
+            if ($key) { $key.Dispose() }
+            if ($legacy) { $legacy.Dispose() }
+            if ($locked) { $mutex.ReleaseMutex() }
+            if ($mutex) { $mutex.Dispose() }
+        }
+        if (!$finished) { Microsoft.PowerShell.Utility\Start-Sleep -Seconds 30 }
+    }
+} finally {
+    foreach ($entry in $profiles) {
+        if ($entry.profile.handle -eq [IntPtr]::Zero) { continue }
+        while (![CleanupNative]::UnloadUserProfile($entry.token, $entry.profile.handle)) {
+            Microsoft.PowerShell.Utility\Start-Sleep -Seconds 1
+        }
+    }
+    foreach ($target in $plan.targets) { $null = [CleanupNative]::CloseHandle([IntPtr][long]$target.handle) }
+}
+# A reinstall may have tried to start the service while the retirement fence blocked it.
+while ($true) {
+    try {
+        foreach ($package in @(Appx\Get-AppxPackage -User $plan.record.user_sid -ErrorAction Stop)) {
+            if ($package.PackageFamilyName -eq $plan.record.runtime.package_family) {
+                Microsoft.PowerShell.Management\Start-Service -Name $plan.service_name -ErrorAction Stop
+                break
+            }
+        }
+        break
+    } catch { Microsoft.PowerShell.Utility\Start-Sleep -Seconds 30 }
+}
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime/removal.rs b/codex-rs/windows-sandbox-service/src/registered_runtime/removal.rs
new file mode 100644
index 0000000000000000000000000000000000000000..54de22bb250221d3fbda15a84c64b454621204ca
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime/removal.rs
@@ -0,0 +1,221 @@
+//! Prepare exact managed logons before native cleanup; authorize removal only after success.
+//! The child owns loaded profiles and waits for both COMMIT and service-process EOF.
+
+use std::io::Read;
+use std::io::Write;
+use std::os::windows::fs::MetadataExt;
+use std::os::windows::io::AsHandle;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::io::BorrowedHandle;
+use std::os::windows::io::OwnedHandle;
+use std::os::windows::process::CommandExt;
+use std::path::PathBuf;
+use std::process::Child;
+use std::process::Command;
+use std::process::Stdio;
+use std::time::Duration;
+use std::time::Instant;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use windows_sys::Win32::Foundation::DUPLICATE_SAME_ACCESS;
+use windows_sys::Win32::Foundation::DuplicateHandle;
+use windows_sys::Win32::Foundation::HANDLE;
+use windows_sys::Win32::System::Pipes::PeekNamedPipe;
+use windows_sys::Win32::System::SystemInformation::GetSystemDirectoryW;
+use windows_sys::Win32::System::Threading as threading;
+
+use crate::installation_record::InstallationRecord;
+use crate::package_lifecycle::with_owner_impersonation;
+
+pub(crate) struct PreparedRemoval {
+    child: Child,
+    tokens: Vec<OwnedHandle>,
+}
+
+impl PreparedRemoval {
+    pub(crate) fn tokens(&self) -> Vec<BorrowedHandle<'_>> {
+        self.tokens.iter().map(AsHandle::as_handle).collect()
+    }
+
+    /// Called only after the native cleanup guard has successfully finished.
+    pub(crate) fn commit(mut self) -> Result<()> {
+        self.child
+            .stdin
+            .as_mut()
+            .context("cleanup input closed")?
+            .write_all(b"COMMIT\n")
+            .context("commit Windows package cleanup")?;
+        // The only pipe writer remains open until this own-process service exits.
+        // Dropping an uncommitted preparation instead sends EOF, which only aborts.
+        std::mem::forget(self.child);
+        Ok(())
+    }
+}
+
+// The cleanup entry checked the service family; prepare_cleanup validated this record
+// under the same setup lock. Fresh logons below still require exact account-SID checks.
+pub(crate) fn prepare(owner_token: HANDLE, record: &InstallationRecord) -> Result<PreparedRemoval> {
+    ensure!(
+        record.runtime()?.retiring.is_some(),
+        "runtime is not retiring"
+    );
+    let mut tokens = Vec::new();
+    let mut targets = Vec::new();
+    for account in &record.runtime()?.accounts {
+        if codex_windows_sandbox::local_user_flags(account.account.username())?.is_none() {
+            ensure!(
+                super::registered_packages(&account.user_sid, &record.runtime()?.package_family)?
+                    .is_empty(),
+                "runtime account is missing while its package remains registered"
+            );
+            continue;
+        }
+        let token = with_owner_impersonation(owner_token, || {
+            let mut pins = Vec::new();
+            crate::ipc::pin_existing_ancestors(
+                &codex_windows_sandbox::sandbox_secrets_dir(&record.codex_home),
+                &mut pins,
+            )?;
+            codex_windows_sandbox::logon_existing_sandbox_account(
+                &record.codex_home,
+                account.account,
+            )
+        })?;
+        super::validate_target(
+            token.as_raw_handle() as _,
+            account.account,
+            Some(&account.user_sid),
+        )?;
+        targets.push(serde_json::json!({
+            "username": account.account.username(),
+            "sid": account.user_sid,
+        }));
+        tokens.push(token);
+    }
+    let group_sid = if tokens.is_empty() {
+        None
+    } else {
+        Some(
+            codex_windows_sandbox::string_from_sid_bytes(&codex_windows_sandbox::resolve_sid(
+                codex_windows_sandbox::SANDBOX_USERS_GROUP,
+            )?)
+            .map_err(anyhow::Error::msg)?,
+        )
+    };
+    let mut system = [0u16; 32768];
+    let length = unsafe { GetSystemDirectoryW(system.as_mut_ptr(), system.len() as u32) } as usize;
+    ensure!(
+        length > 0 && length < system.len(),
+        "Windows system directory is unavailable"
+    );
+    let system = PathBuf::from(String::from_utf16(&system[..length])?);
+    let executable = system.join(r"WindowsPowerShell\v1.0\powershell.exe");
+    let metadata = executable
+        .symlink_metadata()
+        .context("inspect Windows PowerShell")?;
+    ensure!(
+        metadata.is_file()
+            && metadata.file_attributes()
+                & windows_sys::Win32::Storage::FileSystem::FILE_ATTRIBUTE_REPARSE_POINT
+                == 0,
+        "invalid Windows PowerShell executable"
+    );
+    let script = include_str!("removal.ps1");
+    ensure!(
+        executable.as_os_str().len() + script.len() * 2 + 64 < 32767,
+        "cleanup command exceeds the Windows command-line limit"
+    );
+    let mut child = Command::new(executable)
+        .args([
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            script,
+        ])
+        .current_dir(system)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::null())
+        .creation_flags(threading::CREATE_NO_WINDOW)
+        .spawn()
+        .context("start Windows package cleanup")?;
+    // Do not relax process handle inheritance. Only these validated token handles
+    // are duplicated into the exact child process, with inheritance disabled.
+    for (target, token) in targets.iter_mut().zip(&tokens) {
+        let mut remote = 0;
+        let duplicated = unsafe {
+            DuplicateHandle(
+                threading::GetCurrentProcess(),
+                token.as_raw_handle() as _,
+                child.as_raw_handle() as _,
+                &mut remote,
+                /*dwdesiredaccess*/ 0,
+                /*binherithandle*/ 0,
+                DUPLICATE_SAME_ACCESS,
+            )
+        };
+        ensure!(
+            duplicated != 0,
+            "duplicate managed cleanup token: {}",
+            std::io::Error::last_os_error()
+        );
+        target["handle"] = serde_json::json!(remote as usize);
+    }
+    let plan = serde_json::json!({
+        "key": crate::installation_record::CORE_INSTALLATION_KEY,
+        "legacy_key": crate::installation_record::INSTALLATION_KEY,
+        "value": crate::installation_record::INSTALLATION_VALUE,
+        "record": record,
+        "targets": targets,
+        "service_name": codex_windows_sandbox::windows_sandbox_service_name()?,
+        "group_sid": group_sid,
+    });
+    let input = child.stdin.as_mut().context("capture cleanup input")?;
+    serde_json::to_writer(&mut *input, &plan)?;
+    input.write_all(b"\n")?;
+    let output = child.stdout.as_mut().context("capture cleanup readiness")?;
+    let deadline = Instant::now() + Duration::from_secs(30);
+    let mut ready = Vec::new();
+    while !ready.ends_with(b"\n") {
+        ensure!(
+            Instant::now() < deadline,
+            "timed out preparing Windows package cleanup"
+        );
+        let mut available = 0;
+        let result = unsafe {
+            PeekNamedPipe(
+                output.as_raw_handle() as _,
+                std::ptr::null_mut(),
+                /*nbuffersize*/ 0,
+                std::ptr::null_mut(),
+                &mut available,
+                std::ptr::null_mut(),
+            )
+        };
+        ensure!(
+            result != 0,
+            "cleanup exited before readiness: {}",
+            std::io::Error::last_os_error()
+        );
+        if available == 0 {
+            std::thread::sleep(Duration::from_millis(20));
+            continue;
+        }
+        let mut byte = [0];
+        output.read_exact(&mut byte)?;
+        ready.push(byte[0]);
+        ensure!(ready.len() <= 16, "invalid cleanup readiness response");
+    }
+    ensure!(
+        ready == b"READY\r\n" || ready == b"READY\n",
+        "cleanup profiles were not prepared"
+    );
+    Ok(PreparedRemoval { child, tokens })
+}
+
+#[cfg(test)]
+#[path = "removal_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-service/src/registered_runtime/removal_tests.rs b/codex-rs/windows-sandbox-service/src/registered_runtime/removal_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..10cbef4479841831f0f938588ef846145d522c86
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/registered_runtime/removal_tests.rs
@@ -0,0 +1,153 @@
+//! Exercise the actual finalizer authorization barrier without account or package mutations.
+
+use std::io::BufRead;
+use std::io::BufReader;
+use std::io::Write;
+use std::os::windows::io::AsRawHandle;
+use std::os::windows::process::CommandExt;
+use std::path::PathBuf;
+use std::process::Command;
+use std::process::Stdio;
+
+use anyhow::Context;
+use anyhow::Result;
+use anyhow::ensure;
+use pretty_assertions::assert_eq;
+use windows_sys::Win32::Foundation::WAIT_OBJECT_0;
+use windows_sys::Win32::Foundation::WAIT_TIMEOUT;
+use windows_sys::Win32::System::SystemInformation::GetSystemDirectoryW;
+use windows_sys::Win32::System::Threading::CREATE_NO_WINDOW;
+use windows_sys::Win32::System::Threading::WaitForSingleObject;
+
+#[test]
+fn finalizer_script_parses_and_native_bindings_compile() -> Result<()> {
+    let executable =
+        PathBuf::from(std::env::var_os("SystemRoot").context("SystemRoot is missing")?)
+            .join(r"System32\WindowsPowerShell\v1.0\powershell.exe");
+    let script = include_str!("removal.ps1");
+    let native_start = script
+        .find("Add-Type -TypeDefinition @\"")
+        .context("find native bindings")?;
+    let native_end = native_start
+        + script[native_start..]
+            .find("\n\"@")
+            .context("find binding boundary")?
+        + 3;
+    let validation = format!(
+        "$ErrorActionPreference = 'Stop'; $tokens = $null; $errors = $null;\n\
+         $null = [Management.Automation.Language.Parser]::ParseInput([Console]::In.ReadToEnd(), [ref]$tokens, [ref]$errors);\n\
+         if ($errors.Count) {{ throw ($errors | Out-String) }}\n{}",
+        &script[native_start..native_end],
+    );
+    let mut child = Command::new(executable)
+        .args([
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            &validation,
+        ])
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .creation_flags(CREATE_NO_WINDOW)
+        .spawn()?;
+    child
+        .stdin
+        .take()
+        .context("capture parser input")?
+        .write_all(script.as_bytes())?;
+    let output = child.wait_with_output()?;
+    ensure!(
+        output.status.success(),
+        "finalizer validation failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    Ok(())
+}
+
+#[test]
+fn finalizer_preserves_utf8_plan_and_requires_commit_and_stdin_eof() -> Result<()> {
+    let mut system = [0u16; 32768];
+    let length = unsafe { GetSystemDirectoryW(system.as_mut_ptr(), system.len() as u32) } as usize;
+    ensure!(
+        length > 0 && length < system.len(),
+        "Windows system directory is unavailable"
+    );
+    let executable = PathBuf::from(String::from_utf16(&system[..length])?)
+        .join(r"WindowsPowerShell\v1.0\powershell.exe");
+    // Run the production decoder and protocol in isolation, never the cleanup body.
+    let script = include_str!("removal.ps1");
+    let input_anchor = "throw 'SYSTEM required' }";
+    let input_start = script.find(input_anchor).context("find input setup")? + input_anchor.len();
+    let input_end = script
+        .find("if ([string]::IsNullOrEmpty")
+        .context("find plan validation")?;
+    let input_setup = &script[input_start..input_end];
+    let start = script
+        .find("    # EOF without a successful native-cleanup commit")
+        .context("find commit barrier")?;
+    let end = script[start..]
+        .find("    $finished = $false")
+        .context("find cleanup boundary")?
+        + start;
+    let home = r"C:\Users\Zoë-東京\.codex";
+    let script = format!(
+        "$ErrorActionPreference = 'Stop';
+         [Console]::InputEncoding = [Text.Encoding]::GetEncoding(437);
+         {input_setup}
+         if ($plan.record.codex_home -cne '{home}') {{ throw 'UTF-8 plan was corrupted' }}
+         [Console]::Out.WriteLine('waiting');\n{}\n[Console]::Out.WriteLine('released')",
+        &script[start..end]
+    );
+    let mut plan = serde_json::to_vec(&serde_json::json!({ "record": { "codex_home": home } }))?;
+    plan.push(b'\n');
+    for (input, expected) in [
+        ("", ""),
+        ("ABORT\n", ""),
+        ("COMMIT\n", "released"),
+        ("COMMIT\ntrailing", ""),
+    ] {
+        let mut child = Command::new(&executable)
+            .args([
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                &script,
+            ])
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .creation_flags(CREATE_NO_WINDOW)
+            .spawn()?;
+        // Batch the plan and command so decoder read-ahead also exercises the shared reader.
+        let mut request = plan.clone();
+        request.extend_from_slice(input.as_bytes());
+        child
+            .stdin
+            .as_mut()
+            .context("capture barrier input")?
+            .write_all(&request)?;
+        let mut output = BufReader::new(child.stdout.take().context("capture barrier output")?);
+        let mut line = String::new();
+        output.read_line(&mut line)?;
+        assert_eq!(line.trim_end(), "waiting");
+        if input.is_empty() || input.starts_with("COMMIT\n") {
+            let before_eof = unsafe {
+                WaitForSingleObject(child.as_raw_handle() as _, /*dwmilliseconds*/ 500)
+            };
+            assert_eq!(before_eof, WAIT_TIMEOUT);
+        }
+        drop(child.stdin.take());
+        let after_eof = unsafe {
+            WaitForSingleObject(child.as_raw_handle() as _, /*dwmilliseconds*/ 10_000)
+        };
+        assert_eq!(after_eof, WAIT_OBJECT_0);
+        line.clear();
+        output.read_line(&mut line)?;
+        assert_eq!(line.trim_end(), expected);
+        ensure!(child.wait()?.success(), "barrier subprocess failed");
+    }
+    Ok(())
+}
diff --git a/codex-rs/windows-sandbox-service/src/service.rs b/codex-rs/windows-sandbox-service/src/service.rs
new file mode 100644
index 0000000000000000000000000000000000000000..a650e316892eb9a2a0909ab8793f7456b6c1035e
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/service.rs
@@ -0,0 +1,319 @@
+//! Owns Windows SCM registration, service state, and sandbox provisioning event logs.
+
+use std::ffi::c_void;
+use std::io;
+use std::ptr;
+use std::sync::Arc;
+use std::sync::OnceLock;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::AtomicU32;
+use std::sync::atomic::Ordering;
+
+use anyhow::Context;
+use anyhow::Result;
+use windows_sys::Win32::Foundation::ERROR_CALL_NOT_IMPLEMENTED;
+use windows_sys::Win32::Foundation::ERROR_SERVICE_SPECIFIC_ERROR;
+use windows_sys::Win32::Foundation::NO_ERROR;
+use windows_sys::Win32::System::EventLog::DeregisterEventSource;
+use windows_sys::Win32::System::EventLog::EVENTLOG_ERROR_TYPE;
+use windows_sys::Win32::System::EventLog::EVENTLOG_INFORMATION_TYPE;
+use windows_sys::Win32::System::EventLog::RegisterEventSourceW;
+use windows_sys::Win32::System::EventLog::ReportEventW;
+use windows_sys::Win32::System::Services::RegisterServiceCtrlHandlerExW;
+use windows_sys::Win32::System::Services::SERVICE_ACCEPT_SESSIONCHANGE;
+use windows_sys::Win32::System::Services::SERVICE_ACCEPT_SHUTDOWN;
+use windows_sys::Win32::System::Services::SERVICE_ACCEPT_STOP;
+use windows_sys::Win32::System::Services::SERVICE_CONTROL_INTERROGATE;
+use windows_sys::Win32::System::Services::SERVICE_CONTROL_SESSIONCHANGE;
+use windows_sys::Win32::System::Services::SERVICE_CONTROL_SHUTDOWN;
+use windows_sys::Win32::System::Services::SERVICE_CONTROL_STOP;
+use windows_sys::Win32::System::Services::SERVICE_RUNNING;
+use windows_sys::Win32::System::Services::SERVICE_START_PENDING;
+use windows_sys::Win32::System::Services::SERVICE_STATUS;
+use windows_sys::Win32::System::Services::SERVICE_STATUS_HANDLE;
+use windows_sys::Win32::System::Services::SERVICE_STOP_PENDING;
+use windows_sys::Win32::System::Services::SERVICE_STOPPED;
+use windows_sys::Win32::System::Services::SERVICE_TABLE_ENTRYW;
+use windows_sys::Win32::System::Services::SERVICE_WIN32_OWN_PROCESS;
+use windows_sys::Win32::System::Services::SetServiceStatus;
+use windows_sys::Win32::System::Services::StartServiceCtrlDispatcherW;
+
+mod runtime_lifecycle;
+
+pub(crate) use runtime_lifecycle::retry_cleanup;
+
+const EVENT_SERVICE_STARTED: u32 = 1000;
+const EVENT_SERVICE_STOP_REQUESTED: u32 = 1001;
+const EVENT_SERVICE_STOPPED: u32 = 1002;
+pub(crate) const EVENT_SERVICE_FAILED: u32 = 1003;
+pub(crate) const EVENT_PROVISIONING_SUCCEEDED: u32 = 2000;
+pub(crate) const EVENT_PROVISIONING_FAILED: u32 = 2001;
+pub(crate) const EVENT_REQUEST_REJECTED: u32 = 2002;
+pub(crate) const EVENT_CLEANUP_STARTED: u32 = 3002;
+pub(crate) const EVENT_CLEANUP_FINISHED: u32 = 3003;
+pub(crate) const EVENT_CLEANUP_DETAIL: u32 = 3004;
+const MAX_EVENT_MESSAGE_UNITS: usize = 1024;
+
+static SERVICE_STATE: OnceLock<ServiceState> = OnceLock::new();
+
+struct ServiceState {
+    service_name: String,
+    pipe_name: String,
+    shutdown: Arc<AtomicBool>,
+    uninstalling: Arc<AtomicBool>,
+    status_handle: OnceLock<SERVICE_STATUS_HANDLE>,
+    current_status: AtomicU32,
+    stop_requested: AtomicBool,
+}
+
+pub(crate) fn run() -> Result<()> {
+    let service_name = codex_windows_sandbox::windows_sandbox_service_name()?;
+    let state = ServiceState {
+        service_name: service_name.clone(),
+        pipe_name: codex_windows_sandbox::windows_sandbox_service_pipe_name()?,
+        shutdown: Arc::new(AtomicBool::new(false)),
+        uninstalling: Arc::new(AtomicBool::new(false)),
+        status_handle: OnceLock::new(),
+        current_status: AtomicU32::new(SERVICE_START_PENDING),
+        stop_requested: AtomicBool::new(false),
+    };
+    SERVICE_STATE
+        .set(state)
+        .map_err(|_| anyhow::anyhow!("the service dispatcher was already initialized"))?;
+
+    let mut service_name = service_name
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect::<Vec<_>>();
+    let service_table = [
+        SERVICE_TABLE_ENTRYW {
+            lpServiceName: service_name.as_mut_ptr(),
+            lpServiceProc: Some(service_main),
+        },
+        SERVICE_TABLE_ENTRYW {
+            lpServiceName: ptr::null_mut(),
+            lpServiceProc: None,
+        },
+    ];
+
+    // The table and its service-name buffer remain alive until the dispatcher returns.
+    let dispatched = unsafe { StartServiceCtrlDispatcherW(service_table.as_ptr()) };
+    if dispatched == 0 {
+        return Err(io::Error::last_os_error()).context("start the Windows service dispatcher");
+    }
+
+    Ok(())
+}
+
+#[cfg(debug_assertions)]
+pub(crate) fn run_foreground() -> Result<()> {
+    crate::package_identity::enable_foreground_mode();
+    crate::ipc::run(
+        Arc::new(AtomicBool::new(false)),
+        || {
+            eprintln!(
+                "{} listening on {}",
+                codex_windows_sandbox::windows_sandbox_service_name()?,
+                codex_windows_sandbox::windows_sandbox_service_pipe_name()?
+            );
+            Ok(())
+        },
+        runtime_lifecycle::foreground_owner,
+        || Ok(()),
+    )
+}
+
+unsafe extern "system" fn service_main(_argument_count: u32, _arguments: *mut *mut u16) {
+    let Some(state) = SERVICE_STATE.get() else {
+        return;
+    };
+
+    if let Err(error) = service_main_inner(state) {
+        log_error(
+            EVENT_SERVICE_FAILED,
+            &format!("The Codex sandbox service encountered a fatal error: {error:#}"),
+        );
+        eprintln!("{} failed: {error:#}", state.service_name);
+        if state.status_handle.get().is_some() {
+            let _ = state.report_status(SERVICE_STOPPED, ERROR_SERVICE_SPECIFIC_ERROR);
+        }
+    }
+}
+
+fn service_main_inner(state: &ServiceState) -> Result<()> {
+    let service_name = state
+        .service_name
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect::<Vec<_>>();
+
+    // The service controller only reads the name during registration.
+    let status_handle = unsafe {
+        RegisterServiceCtrlHandlerExW(
+            service_name.as_ptr(),
+            Some(service_control_handler),
+            ptr::null(),
+        )
+    };
+    if status_handle == 0 {
+        return Err(io::Error::last_os_error()).context("register the service control handler");
+    }
+    state
+        .status_handle
+        .set(status_handle)
+        .map_err(|_| anyhow::anyhow!("the service status handle was already registered"))?;
+
+    state.report_status(SERVICE_START_PENDING, NO_ERROR)?;
+    let package_lifecycle =
+        crate::package_lifecycle::PackageLifecycle::new(Arc::clone(&state.uninstalling))?;
+    runtime_lifecycle::run(state, &package_lifecycle)?;
+    log_information(
+        EVENT_SERVICE_STOPPED,
+        "The Codex sandbox service has stopped.",
+    );
+    state.report_status(SERVICE_STOPPED, NO_ERROR)
+}
+
+unsafe extern "system" fn service_control_handler(
+    control: u32,
+    _event_type: u32,
+    _event_data: *mut c_void,
+    _context: *mut c_void,
+) -> u32 {
+    let Some(state) = SERVICE_STATE.get() else {
+        return ERROR_CALL_NOT_IMPLEMENTED;
+    };
+
+    match control {
+        SERVICE_CONTROL_STOP | SERVICE_CONTROL_SHUTDOWN => {
+            if control == SERVICE_CONTROL_STOP {
+                state.stop_requested.store(true, Ordering::Release);
+            }
+            if !state.shutdown.swap(true, Ordering::AcqRel) {
+                if let Err(error) = state.report_status(SERVICE_STOP_PENDING, NO_ERROR) {
+                    eprintln!("unable to report service shutdown: {error:#}");
+                }
+                log_information(
+                    EVENT_SERVICE_STOP_REQUESTED,
+                    "The Codex sandbox service was asked to stop.",
+                );
+                wake_listener();
+            }
+            NO_ERROR
+        }
+        SERVICE_CONTROL_INTERROGATE => {
+            let current_status = state.current_status.load(Ordering::Acquire);
+            if let Err(error) = state.report_status(current_status, NO_ERROR) {
+                log_error(
+                    EVENT_SERVICE_FAILED,
+                    "The Codex sandbox service could not report its current status.",
+                );
+                eprintln!("unable to report the current service status: {error:#}");
+            }
+            NO_ERROR
+        }
+        SERVICE_CONTROL_SESSIONCHANGE => {
+            wake_listener();
+            NO_ERROR
+        }
+        _ => ERROR_CALL_NOT_IMPLEMENTED,
+    }
+}
+
+pub(crate) fn wake_listener() {
+    if let Some(state) = SERVICE_STATE.get() {
+        std::thread::spawn(move || {
+            crate::ipc::wake(&state.pipe_name, || {
+                state.current_status.load(Ordering::Acquire) == SERVICE_STOPPED
+            });
+        });
+    }
+}
+
+pub(crate) fn log_information(event_id: u32, message: &str) {
+    log_event(EVENTLOG_INFORMATION_TYPE, event_id, message);
+}
+
+pub(crate) fn log_error(event_id: u32, message: &str) {
+    log_event(EVENTLOG_ERROR_TYPE, event_id, message);
+}
+
+fn log_event(event_type: u16, event_id: u32, message: &str) {
+    let source = SERVICE_STATE
+        .get()
+        .map_or("CodexSandboxService", |state| state.service_name.as_str())
+        .encode_utf16()
+        .chain(std::iter::once(0))
+        .collect::<Vec<_>>();
+    let event_log = unsafe { RegisterEventSourceW(ptr::null(), source.as_ptr()) };
+    if event_log == 0 {
+        eprintln!("unable to open the Windows event log: {message}");
+        return;
+    }
+
+    let mut message_units = Vec::with_capacity(MAX_EVENT_MESSAGE_UNITS + 1);
+    for character in message.chars() {
+        let character = if character.is_control() {
+            ' '
+        } else {
+            character
+        };
+        let mut buffer = [0_u16; 2];
+        let encoded = character.encode_utf16(&mut buffer);
+        if message_units.len() + encoded.len() > MAX_EVENT_MESSAGE_UNITS {
+            break;
+        }
+        message_units.extend_from_slice(encoded);
+    }
+    message_units.push(0);
+    let strings = [message_units.as_ptr()];
+    let reported = unsafe {
+        ReportEventW(
+            event_log,
+            event_type,
+            0,
+            event_id,
+            ptr::null_mut(),
+            1,
+            0,
+            strings.as_ptr(),
+            ptr::null(),
+        )
+    };
+    if reported == 0 {
+        eprintln!("unable to write a Windows event-log entry (event {event_id})");
+    }
+    unsafe { DeregisterEventSource(event_log) };
+}
+
+impl ServiceState {
+    fn report_status(&self, current_status: u32, win32_exit_code: u32) -> Result<()> {
+        let status_handle = *self
+            .status_handle
+            .get()
+            .context("the service status handle was not registered")?;
+        let is_pending = matches!(current_status, SERVICE_START_PENDING | SERVICE_STOP_PENDING);
+        let status = SERVICE_STATUS {
+            dwServiceType: SERVICE_WIN32_OWN_PROCESS,
+            dwCurrentState: current_status,
+            dwControlsAccepted: if current_status == SERVICE_RUNNING {
+                SERVICE_ACCEPT_STOP | SERVICE_ACCEPT_SHUTDOWN | SERVICE_ACCEPT_SESSIONCHANGE
+            } else {
+                0
+            },
+            dwWin32ExitCode: win32_exit_code,
+            dwServiceSpecificExitCode: u32::from(win32_exit_code == ERROR_SERVICE_SPECIFIC_ERROR),
+            dwCheckPoint: u32::from(is_pending),
+            dwWaitHint: if is_pending { 10_000 } else { 0 },
+        };
+
+        self.current_status.store(current_status, Ordering::Release);
+        // The SCM synchronously copies the status structure during this call.
+        let updated = unsafe { SetServiceStatus(status_handle, &status) };
+        if updated == 0 {
+            return Err(io::Error::last_os_error()).context("update the Windows service status");
+        }
+
+        Ok(())
+    }
+}
diff --git a/codex-rs/windows-sandbox-service/src/service/runtime_lifecycle.rs b/codex-rs/windows-sandbox-service/src/service/runtime_lifecycle.rs
new file mode 100644
index 0000000000000000000000000000000000000000..f6f3341c1987cd20a96b9b30bde42e1d8789a3c0
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/service/runtime_lifecycle.rs
@@ -0,0 +1,162 @@
+//! Runs owner-aware cleanup in the live provisioning broker before further admission.
+//! Shutdown means SCM stop until cleanup finishes; retirement fences are never replayed.
+
+use std::cell::Cell;
+use std::sync::Arc;
+use std::sync::atomic::Ordering;
+
+use anyhow::Context;
+use anyhow::Result;
+use windows_sys::Win32::Foundation::NO_ERROR;
+use windows_sys::Win32::System::Services::SERVICE_RUNNING;
+use windows_sys::Win32::System::Services::SERVICE_STOP_PENDING;
+
+use super::EVENT_SERVICE_FAILED;
+use super::EVENT_SERVICE_STARTED;
+use super::SERVICE_STATE;
+use super::ServiceState;
+use super::log_error;
+use super::log_information;
+use crate::package_lifecycle::PackageLifecycle;
+
+/// Foreground debugging has no persistent watcher, but must retain the same admission rules.
+#[cfg(debug_assertions)]
+pub(super) fn foreground_owner(
+    mut record: crate::installation_record::InstallationRecord,
+    _token: crate::ipc::OwnedHandle,
+    runtime: codex_windows_sandbox::SetupRuntime,
+) -> Result<crate::installation_record::InstallationRecord> {
+    let _lock = codex_windows_sandbox::acquire_sandbox_setup_lock(/*timeout_ms*/ 5_000)?;
+    if let Some(previous) = crate::installation_record::load()? {
+        let same_owner =
+            previous.user_sid == record.user_sid && previous.codex_home == record.codex_home;
+        if previous.runtime.is_some() {
+            let family = windows::ApplicationModel::Package::Current()?
+                .Id()?
+                .FamilyName()?;
+            previous.admit_owner(&record, &family.to_string())?;
+            record.runtime = previous.runtime;
+        } else if runtime == codex_windows_sandbox::SetupRuntime::Registered {
+            anyhow::ensure!(
+                same_owner,
+                "shared sandbox resources belong to a different owner"
+            );
+        }
+        if same_owner {
+            record.desktop_installation = previous
+                .desktop_installation
+                .or(record.desktop_installation);
+        }
+    }
+    Ok(record)
+}
+
+pub(super) fn run(state: &ServiceState, package_lifecycle: &PackageLifecycle) -> Result<()> {
+    let cleaned = Cell::new(false);
+    let restore_owner = || {
+        let restored = crate::installation_record::load().and_then(|record| {
+            record.map_or(Ok(()), |record| {
+                package_lifecycle.restore_logged_in_owner(record.session_id)
+            })
+        });
+        if let Err(error) = restored {
+            log_error(
+                EVENT_SERVICE_FAILED,
+                &format!("unable to restore package uninstall listener: {error:#}"),
+            );
+        }
+    };
+    crate::ipc::run(
+        Arc::clone(&state.shutdown),
+        || {
+            restore_owner();
+            state.report_status(SERVICE_RUNNING, NO_ERROR)?;
+            log_information(
+                EVENT_SERVICE_STARTED,
+                "The Codex sandbox service is running.",
+            );
+            Ok(())
+        },
+        |installation, user_token, _runtime| {
+            package_lifecycle.register_authenticated_user(installation, user_token)
+        },
+        || loop {
+            restore_owner();
+            if !crate::package_lifecycle::runtime_owner_removed()? {
+                return Ok(());
+            }
+            let Err(error) = package_lifecycle.clean_up() else {
+                cleaned.set(true);
+                state.shutdown.store(true, Ordering::Release);
+                return state.report_status(SERVICE_STOP_PENDING, NO_ERROR);
+            };
+            if crate::installation_record::load_runtime()?.is_none_or(|record| {
+                record
+                    .runtime
+                    .is_some_and(|runtime| runtime.retiring.is_some())
+            }) {
+                return Err(error);
+            }
+            log_error(
+                EVENT_SERVICE_FAILED,
+                &format!("sandbox cleanup deferred: {error:#}"),
+            );
+            // Keep the pipe available during pre-fence backoff. A reinstall
+            // resumes admission on the next owner check; SCM stops are never reset.
+            if !wait_for_cleanup_retry(state) {
+                return Err(error);
+            }
+        },
+    )
+    .context("run the sandbox provisioning broker")?;
+    if !cleaned.get()
+        && state.stop_requested.load(Ordering::Acquire)
+        && (state.uninstalling.load(Ordering::Acquire)
+            || crate::package_lifecycle::runtime_owner_removed()?)
+    {
+        package_lifecycle.clean_up()?;
+    }
+    Ok(())
+}
+
+/// Retries the current teardown step, never a phase recovered from stored intent.
+pub(crate) fn retry_cleanup(mut operation: impl FnMut() -> Result<()>) -> Result<()> {
+    let mut stop_failures = 0;
+    loop {
+        let Err(error) = operation() else {
+            return Ok(());
+        };
+        let Some(state) = SERVICE_STATE.get() else {
+            return Err(error);
+        };
+        log_error(
+            EVENT_SERVICE_FAILED,
+            &format!("sandbox cleanup deferred: {error:#}"),
+        );
+        if state.stop_requested.load(Ordering::Acquire) {
+            // SCM stop initiates uninstall cleanup rather than cancelling it.
+            // Four one-second retry waits fit within the 10-second SCM wait hint.
+            stop_failures += 1;
+            if stop_failures == 5 {
+                return Err(error);
+            }
+            std::thread::sleep(std::time::Duration::from_secs(1));
+        } else if !wait_for_cleanup_retry(state) && !state.stop_requested.load(Ordering::Acquire) {
+            return Err(error);
+        }
+    }
+}
+
+fn wait_for_cleanup_retry(state: &ServiceState) -> bool {
+    for _ in 0..30 {
+        if state.shutdown.load(Ordering::Acquire) {
+            return false;
+        }
+        std::thread::sleep(std::time::Duration::from_secs(1));
+    }
+    !state.shutdown.load(Ordering::Acquire)
+}
+
+#[cfg(test)]
+#[path = "runtime_lifecycle_tests.rs"]
+mod tests;
diff --git a/codex-rs/windows-sandbox-service/src/service/runtime_lifecycle_tests.rs b/codex-rs/windows-sandbox-service/src/service/runtime_lifecycle_tests.rs
new file mode 100644
index 0000000000000000000000000000000000000000..4b283e53d65b989bb2d9fcd63bd5085d02f696ce
--- /dev/null
+++ b/codex-rs/windows-sandbox-service/src/service/runtime_lifecycle_tests.rs
@@ -0,0 +1,79 @@
+//! Verifies teardown retries distinguish SCM stop from system shutdown.
+
+use super::retry_cleanup;
+use crate::service::SERVICE_STATE;
+use crate::service::ServiceState;
+use crate::service::service_control_handler;
+use anyhow::Context;
+use anyhow::Result;
+use pretty_assertions::assert_eq;
+use std::io;
+use std::ptr;
+use std::sync::Arc;
+use std::sync::OnceLock;
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::AtomicU32;
+use std::sync::atomic::Ordering;
+use windows_sys::Win32::Foundation::ERROR_SHARING_VIOLATION;
+use windows_sys::Win32::Foundation::NO_ERROR;
+use windows_sys::Win32::System::Services::SERVICE_CONTROL_SHUTDOWN;
+use windows_sys::Win32::System::Services::SERVICE_CONTROL_STOP;
+use windows_sys::Win32::System::Services::SERVICE_STOPPED;
+
+#[test]
+fn cleanup_retries_after_scm_stop_but_not_system_shutdown() -> Result<()> {
+    // One test owns the process-global state. The pre-set shutdown flag keeps
+    // the real control handler from calling SCM or spawning a pipe wake thread.
+    assert!(
+        SERVICE_STATE
+            .set(ServiceState {
+                service_name: "CodexSandboxServiceTests".into(),
+                pipe_name: r"\\.\pipe\CodexSandboxServiceTests".into(),
+                shutdown: Arc::new(AtomicBool::new(true)),
+                uninstalling: Arc::new(AtomicBool::new(false)),
+                status_handle: OnceLock::new(),
+                current_status: AtomicU32::new(SERVICE_STOPPED),
+                stop_requested: AtomicBool::new(false),
+            })
+            .is_ok()
+    );
+    let state = SERVICE_STATE.get().context("service state is missing")?;
+    for (control, failures, expected_attempts, expected_success) in [
+        (SERVICE_CONTROL_SHUTDOWN, 1, 1, false),
+        (SERVICE_CONTROL_STOP, 1, 2, true),
+        (SERVICE_CONTROL_STOP, usize::MAX, 5, false),
+    ] {
+        assert_eq!(
+            unsafe {
+                service_control_handler(
+                    control,
+                    /*_event_type*/ 0,
+                    ptr::null_mut(),
+                    ptr::null_mut(),
+                )
+            },
+            NO_ERROR
+        );
+        let mut attempts = 0;
+        let result = retry_cleanup(|| {
+            attempts += 1;
+            if attempts <= failures {
+                return Err(io::Error::from_raw_os_error(ERROR_SHARING_VIOLATION as i32).into());
+            }
+            Ok(())
+        });
+        assert_eq!(result.is_ok(), expected_success);
+        assert_eq!(attempts, expected_attempts);
+        assert!(state.shutdown.load(Ordering::Acquire));
+        if let Err(error) = result {
+            assert_eq!(
+                error
+                    .downcast_ref::<io::Error>()
+                    .context("cleanup did not preserve the I/O error")?
+                    .raw_os_error(),
+                Some(ERROR_SHARING_VIOLATION as i32)
+            );
+        }
+    }
+    Ok(())
+}