Assume that we trust codex for worktrees spawned from a repo that we already trust codex with

https://github.com/user-attachments/assets/dc7bf820-eeec-4b78-aba9-231e1337921c

README.md

@@ -383,6 +383,13 @@ base_url = "http://my-ollama.example.com:11434/v1"
 
 ### Platform sandboxing details
 
+By default, Codex CLI runs code and shell commands inside a restricted sandbox to protect your system.  
+
+> [!IMPORTANT]
+> Not all tool calls are sandboxed. Specifically, **trusted Model Context Protocol (MCP) tool calls** are executed outside of the sandbox.  
+> This is intentional: MCP tools are explicitly configured and trusted by you, and they often need to connect to **external applications or services** (e.g. issue trackers, databases, messaging systems).  
+> Running them outside the sandbox allows Codex to integrate with these external systems without being blocked by sandbox restrictions.
+
 The mechanism Codex uses to implement the sandbox policy depends on your OS:
 
 - **macOS 12+** uses **Apple Seatbelt** and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` that was specified.

codex-rs/core/src/codex.rs

@@ -94,6 +94,7 @@ use crate::protocol::PatchApplyEndEvent;
 use crate::protocol::ReviewDecision;
 use crate::protocol::SandboxPolicy;
 use crate::protocol::SessionConfiguredEvent;
+use crate::protocol::StreamErrorEvent;
 use crate::protocol::Submission;
 use crate::protocol::TaskCompleteEvent;
 use crate::protocol::TurnDiffEvent;
@@ -508,10 +509,10 @@ impl Session {
             conversation_items.push(Prompt::format_user_instructions_message(user_instructions));
         }
         conversation_items.push(ResponseItem::from(EnvironmentContext::new(
-            turn_context.cwd.to_path_buf(),
-            turn_context.approval_policy,
-            turn_context.sandbox_policy.clone(),
-            sess.user_shell.clone(),
+            Some(turn_context.cwd.clone()),
+            Some(turn_context.approval_policy),
+            Some(turn_context.sandbox_policy.clone()),
+            Some(sess.user_shell.clone()),
         )));
         sess.record_conversation_items(&conversation_items).await;
 
@@ -815,6 +816,16 @@ impl Session {
         let _ = self.tx_event.send(event).await;
     }
 
+    async fn notify_stream_error(&self, sub_id: &str, message: impl Into<String>) {
+        let event = Event {
+            id: sub_id.to_string(),
+            msg: EventMsg::StreamError(StreamErrorEvent {
+                message: message.into(),
+            }),
+        };
+        let _ = self.tx_event.send(event).await;
+    }
+
     /// Build the full turn input by concatenating the current conversation
     /// history with additional items for this turn.
     pub fn turn_input_with_history(&self, extra: Vec<ResponseItem>) -> Vec<ResponseItem> {
@@ -1068,10 +1079,11 @@ async fn submission_loop(
                 turn_context = Arc::new(new_turn_context);
                 if cwd.is_some() || approval_policy.is_some() || sandbox_policy.is_some() {
                     sess.record_conversation_items(&[ResponseItem::from(EnvironmentContext::new(
-                        new_cwd,
-                        new_approval_policy,
-                        new_sandbox_policy,
-                        sess.user_shell.clone(),
+                        cwd,
+                        approval_policy,
+                        sandbox_policy,
+                        // Shell is not configurable from turn to turn
+                        None,
                     ))])
                     .await;
                 }
@@ -1522,7 +1534,7 @@ async fn run_turn(
                     // Surface retry information to any UI/front‑end so the
                     // user understands what is happening instead of staring
                     // at a seemingly frozen screen.
-                    sess.notify_background_event(
+                    sess.notify_stream_error(
                         &sub_id,
                         format!(
                             "stream error: {e}; retrying {retries}/{max_retries} in {delay:?}…"
@@ -1757,7 +1769,7 @@ async fn run_compact_task(
                 if retries < max_retries {
                     retries += 1;
                     let delay = backoff(retries);
-                    sess.notify_background_event(
+                    sess.notify_stream_error(
                         &sub_id,
                         format!(
                             "stream error: {e}; retrying {retries}/{max_retries} in {delay:?}…"

codex-rs/core/src/config.rs

@@ -261,7 +261,8 @@ pub fn set_project_trusted(codex_home: &Path, project_path: &Path) -> anyhow::Re
 
     // Mark the project as trusted. toml_edit is very good at handling
     // missing properties
-    let project_key = project_path.to_string_lossy().to_string();
+    let normalized = crate::util::normalized_trust_project_root(project_path);
+    let project_key = normalized.to_string_lossy().to_string();
     doc["projects"][project_key.as_str()]["trust_level"] = toml_edit::value("trusted");
 
     // ensure codex_home exists
@@ -454,8 +455,13 @@ impl ConfigToml {
     pub fn is_cwd_trusted(&self, resolved_cwd: &Path) -> bool {
         let projects = self.projects.clone().unwrap_or_default();
 
+        // Prefer a normalized project key that points to the main git repo root when applicable.
+        let normalized_root = crate::util::normalized_trust_project_root(resolved_cwd);
+        let normalized_key = normalized_root.to_string_lossy().to_string();
+
         projects
-            .get(&resolved_cwd.to_string_lossy().to_string())
+            .get(&normalized_key)
+            .or_else(|| projects.get(&resolved_cwd.to_string_lossy().to_string()))
             .map(|p| p.trust_level.clone().unwrap_or("".to_string()) == "trusted")
             .unwrap_or(false)
     }

codex-rs/core/src/environment_context.rs

@@ -8,11 +8,10 @@ use crate::protocol::AskForApproval;
 use crate::protocol::SandboxPolicy;
 use crate::shell::Shell;
 use codex_protocol::config_types::SandboxMode;
-use std::fmt::Display;
 use std::path::PathBuf;
 
 /// wraps environment context message in a tag for the model to parse more easily.
-pub(crate) const ENVIRONMENT_CONTEXT_START: &str = "<environment_context>\n";
+pub(crate) const ENVIRONMENT_CONTEXT_START: &str = "<environment_context>";
 pub(crate) const ENVIRONMENT_CONTEXT_END: &str = "</environment_context>";
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, DeriveDisplay)]
@@ -25,58 +24,87 @@ pub enum NetworkAccess {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename = "environment_context", rename_all = "snake_case")]
 pub(crate) struct EnvironmentContext {
-    pub cwd: PathBuf,
-    pub approval_policy: AskForApproval,
-    pub sandbox_mode: SandboxMode,
-    pub network_access: NetworkAccess,
-    pub shell: Shell,
+    pub cwd: Option<PathBuf>,
+    pub approval_policy: Option<AskForApproval>,
+    pub sandbox_mode: Option<SandboxMode>,
+    pub network_access: Option<NetworkAccess>,
+    pub shell: Option<Shell>,
 }
 
 impl EnvironmentContext {
     pub fn new(
-        cwd: PathBuf,
-        approval_policy: AskForApproval,
-        sandbox_policy: SandboxPolicy,
-        shell: Shell,
+        cwd: Option<PathBuf>,
+        approval_policy: Option<AskForApproval>,
+        sandbox_policy: Option<SandboxPolicy>,
+        shell: Option<Shell>,
     ) -> Self {
         Self {
             cwd,
             approval_policy,
             sandbox_mode: match sandbox_policy {
-                SandboxPolicy::DangerFullAccess => SandboxMode::DangerFullAccess,
-                SandboxPolicy::ReadOnly => SandboxMode::ReadOnly,
-                SandboxPolicy::WorkspaceWrite { .. } => SandboxMode::WorkspaceWrite,
+                Some(SandboxPolicy::DangerFullAccess) => Some(SandboxMode::DangerFullAccess),
+                Some(SandboxPolicy::ReadOnly) => Some(SandboxMode::ReadOnly),
+                Some(SandboxPolicy::WorkspaceWrite { .. }) => Some(SandboxMode::WorkspaceWrite),
+                None => None,
             },
             network_access: match sandbox_policy {
-                SandboxPolicy::DangerFullAccess => NetworkAccess::Enabled,
-                SandboxPolicy::ReadOnly => NetworkAccess::Restricted,
-                SandboxPolicy::WorkspaceWrite { network_access, .. } => {
+                Some(SandboxPolicy::DangerFullAccess) => Some(NetworkAccess::Enabled),
+                Some(SandboxPolicy::ReadOnly) => Some(NetworkAccess::Restricted),
+                Some(SandboxPolicy::WorkspaceWrite { network_access, .. }) => {
                     if network_access {
-                        NetworkAccess::Enabled
+                        Some(NetworkAccess::Enabled)
                     } else {
-                        NetworkAccess::Restricted
+                        Some(NetworkAccess::Restricted)
                     }
                 }
+                None => None,
             },
             shell,
         }
     }
 }
 
-impl Display for EnvironmentContext {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        writeln!(
-            f,
-            "Current working directory: {}",
-            self.cwd.to_string_lossy()
-        )?;
-        writeln!(f, "Approval policy: {}", self.approval_policy)?;
-        writeln!(f, "Sandbox mode: {}", self.sandbox_mode)?;
-        writeln!(f, "Network access: {}", self.network_access)?;
-        if let Some(shell_name) = self.shell.name() {
-            writeln!(f, "Shell: {shell_name}")?;
+impl EnvironmentContext {
+    /// Serializes the environment context to XML. Libraries like `quick-xml`
+    /// require custom macros to handle Enums with newtypes, so we just do it
+    /// manually, to keep things simple. Output looks like:
+    ///
+    /// ```xml
+    /// <environment_context>
+    ///   <cwd>...</cwd>
+    ///   <approval_policy>...</approval_policy>
+    ///   <sandbox_mode>...</sandbox_mode>
+    ///   <network_access>...</network_access>
+    ///   <shell>...</shell>
+    /// </environment_context>
+    /// ```
+    pub fn serialize_to_xml(self) -> String {
+        let mut lines = vec![ENVIRONMENT_CONTEXT_START.to_string()];
+        if let Some(cwd) = self.cwd {
+            lines.push(format!("  <cwd>{}</cwd>", cwd.to_string_lossy()));
         }
-        Ok(())
+        if let Some(approval_policy) = self.approval_policy {
+            lines.push(format!(
+                "  <approval_policy>{}</approval_policy>",
+                approval_policy
+            ));
+        }
+        if let Some(sandbox_mode) = self.sandbox_mode {
+            lines.push(format!("  <sandbox_mode>{}</sandbox_mode>", sandbox_mode));
+        }
+        if let Some(network_access) = self.network_access {
+            lines.push(format!(
+                "  <network_access>{}</network_access>",
+                network_access
+            ));
+        }
+        if let Some(shell) = self.shell
+            && let Some(shell_name) = shell.name()
+        {
+            lines.push(format!("  <shell>{}</shell>", shell_name));
+        }
+        lines.push(ENVIRONMENT_CONTEXT_END.to_string());
+        lines.join("\n")
     }
 }
 
@@ -86,7 +114,7 @@ impl From<EnvironmentContext> for ResponseItem {
             id: None,
             role: "user".to_string(),
             content: vec![ContentItem::InputText {
-                text: format!("{ENVIRONMENT_CONTEXT_START}{ec}{ENVIRONMENT_CONTEXT_END}"),
+                text: ec.serialize_to_xml(),
             }],
         }
     }

codex-rs/core/src/lib.rs

@@ -43,7 +43,7 @@ mod models;
 mod openai_model_info;
 mod openai_tools;
 pub mod plan_tool;
-mod project_doc;
+pub mod project_doc;
 mod rollout;
 pub(crate) mod safety;
 pub mod seatbelt;

codex-rs/core/src/project_doc.rs

@@ -1,18 +1,19 @@
 //! Project-level documentation discovery.
 //!
-//! Project-level documentation can be stored in a file named `AGENTS.md`.
-//! Currently, we include only the contents of the first file found as follows:
+//! Project-level documentation can be stored in files named `AGENTS.md`.
+//! We include the concatenation of all files found along the path from the
+//! repository root to the current working directory as follows:
 //!
-//! 1.  Look for the doc file in the current working directory (as determined
-//!     by the `Config`).
-//! 2.  If not found, walk *upwards* until the Git repository root is reached
-//!     (detected by the presence of a `.git` directory/file), or failing that,
-//!     the filesystem root.
-//! 3.  If the Git root is encountered, look for the doc file there. If it
-//!     exists, the search stops – we do **not** walk past the Git root.
+//! 1.  Determine the Git repository root by walking upwards from the current
+//!     working directory until a `.git` directory or file is found. If no Git
+//!     root is found, only the current working directory is considered.
+//! 2.  Collect every `AGENTS.md` found from the repository root down to the
+//!     current working directory (inclusive) and concatenate their contents in
+//!     that order.
+//! 3.  We do **not** walk past the Git root.
 
 use crate::config::Config;
-use std::path::Path;
+use std::path::PathBuf;
 use tokio::io::AsyncReadExt;
 use tracing::error;
 
@@ -26,7 +27,7 @@ const PROJECT_DOC_SEPARATOR: &str = "\n\n--- project-doc ---\n\n";
 /// Combines `Config::instructions` and `AGENTS.md` (if present) into a single
 /// string of instructions.
 pub(crate) async fn get_user_instructions(config: &Config) -> Option<String> {
-    match find_project_doc(config).await {
+    match read_project_docs(config).await {
         Ok(Some(project_doc)) => match &config.user_instructions {
             Some(original_instructions) => Some(format!(
                 "{original_instructions}{PROJECT_DOC_SEPARATOR}{project_doc}"
@@ -41,95 +42,135 @@ pub(crate) async fn get_user_instructions(config: &Config) -> Option<String> {
     }
 }
 
-/// Attempt to locate and load the project documentation. Currently, the search
-/// starts from `Config::cwd`, but if we may want to consider other directories
-/// in the future, e.g., additional writable directories in the `SandboxPolicy`.
+/// Attempt to locate and load the project documentation.
 ///
-/// On success returns `Ok(Some(contents))`. If no documentation file is found
-/// the function returns `Ok(None)`. Unexpected I/O failures bubble up as
-/// `Err` so callers can decide how to handle them.
-async fn find_project_doc(config: &Config) -> std::io::Result<Option<String>> {
-    let max_bytes = config.project_doc_max_bytes;
+/// On success returns `Ok(Some(contents))` where `contents` is the
+/// concatenation of all discovered docs. If no documentation file is found the
+/// function returns `Ok(None)`. Unexpected I/O failures bubble up as `Err` so
+/// callers can decide how to handle them.
+pub async fn read_project_docs(config: &Config) -> std::io::Result<Option<String>> {
+    let max_total = config.project_doc_max_bytes;
 
-    // Attempt to load from the working directory first.
-    if let Some(doc) = load_first_candidate(&config.cwd, CANDIDATE_FILENAMES, max_bytes).await? {
-        return Ok(Some(doc));
+    if max_total == 0 {
+        return Ok(None);
     }
 
-    // Walk up towards the filesystem root, stopping once we encounter the Git
-    // repository root. The presence of **either** a `.git` *file* or
-    // *directory* counts.
-    let mut dir = config.cwd.clone();
+    let paths = discover_project_doc_paths(config)?;
+    if paths.is_empty() {
+        return Ok(None);
+    }
 
-    // Canonicalize the path so that we do not end up in an infinite loop when
-    // `cwd` contains `..` components.
+    let mut remaining: u64 = max_total as u64;
+    let mut parts: Vec<String> = Vec::new();
+
+    for p in paths {
+        if remaining == 0 {
+            break;
+        }
+
+        let file = match tokio::fs::File::open(&p).await {
+            Ok(f) => f,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
+            Err(e) => return Err(e),
+        };
+
+        let size = file.metadata().await?.len();
+        let mut reader = tokio::io::BufReader::new(file).take(remaining);
+        let mut data: Vec<u8> = Vec::new();
+        reader.read_to_end(&mut data).await?;
+
+        if size > remaining {
+            tracing::warn!(
+                "Project doc `{}` exceeds remaining budget ({} bytes) - truncating.",
+                p.display(),
+                remaining,
+            );
+        }
+
+        let text = String::from_utf8_lossy(&data).to_string();
+        if !text.trim().is_empty() {
+            parts.push(text);
+            remaining = remaining.saturating_sub(data.len() as u64);
+        }
+    }
+
+    if parts.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(parts.join("\n\n")))
+    }
+}
+
+/// Discover the list of AGENTS.md files using the same search rules as
+/// `read_project_docs`, but return the file paths instead of concatenated
+/// contents. The list is ordered from repository root to the current working
+/// directory (inclusive). Symlinks are allowed. When `project_doc_max_bytes`
+/// is zero, returns an empty list.
+pub fn discover_project_doc_paths(config: &Config) -> std::io::Result<Vec<PathBuf>> {
+    let mut dir = config.cwd.clone();
     if let Ok(canon) = dir.canonicalize() {
         dir = canon;
     }
 
-    while let Some(parent) = dir.parent() {
-        // `.git` can be a *file* (for worktrees or submodules) or a *dir*.
-        let git_marker = dir.join(".git");
-        let git_exists = match tokio::fs::metadata(&git_marker).await {
+    // Build chain from cwd upwards and detect git root.
+    let mut chain: Vec<PathBuf> = vec![dir.clone()];
+    let mut git_root: Option<PathBuf> = None;
+    let mut cursor = dir.clone();
+    while let Some(parent) = cursor.parent() {
+        let git_marker = cursor.join(".git");
+        let git_exists = match std::fs::metadata(&git_marker) {
             Ok(_) => true,
             Err(e) if e.kind() == std::io::ErrorKind::NotFound => false,
             Err(e) => return Err(e),
         };
 
         if git_exists {
-            // We are at the repo root – attempt one final load.
-            if let Some(doc) = load_first_candidate(&dir, CANDIDATE_FILENAMES, max_bytes).await? {
-                return Ok(Some(doc));
-            }
+            git_root = Some(cursor.clone());
             break;
         }
 
-        dir = parent.to_path_buf();
+        chain.push(parent.to_path_buf());
+        cursor = parent.to_path_buf();
     }
 
-    Ok(None)
-}
-
-/// Attempt to load the first candidate file found in `dir`. Returns the file
-/// contents (truncated if it exceeds `max_bytes`) when successful.
-async fn load_first_candidate(
-    dir: &Path,
-    names: &[&str],
-    max_bytes: usize,
-) -> std::io::Result<Option<String>> {
-    for name in names {
-        let candidate = dir.join(name);
-
-        let file = match tokio::fs::File::open(&candidate).await {
-            Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
-            Err(e) => return Err(e),
-            Ok(f) => f,
-        };
-
-        let size = file.metadata().await?.len();
-
-        let reader = tokio::io::BufReader::new(file);
-        let mut data = Vec::with_capacity(std::cmp::min(size as usize, max_bytes));
-        let mut limited = reader.take(max_bytes as u64);
-        limited.read_to_end(&mut data).await?;
-
-        if size as usize > max_bytes {
-            tracing::warn!(
-                "Project doc `{}` exceeds {max_bytes} bytes - truncating.",
-                candidate.display(),
-            );
+    let search_dirs: Vec<PathBuf> = if let Some(root) = git_root {
+        let mut dirs: Vec<PathBuf> = Vec::new();
+        let mut saw_root = false;
+        for p in chain.iter().rev() {
+            if !saw_root {
+                if p == &root {
+                    saw_root = true;
+                } else {
+                    continue;
+                }
+            }
+            dirs.push(p.clone());
         }
+        dirs
+    } else {
+        vec![config.cwd.clone()]
+    };
 
-        let contents = String::from_utf8_lossy(&data).to_string();
-        if contents.trim().is_empty() {
-            // Empty file – treat as not found.
-            continue;
+    let mut found: Vec<PathBuf> = Vec::new();
+    for d in search_dirs {
+        for name in CANDIDATE_FILENAMES {
+            let candidate = d.join(name);
+            match std::fs::symlink_metadata(&candidate) {
+                Ok(md) => {
+                    let ft = md.file_type();
+                    // Allow regular files and symlinks; opening will later fail for dangling links.
+                    if ft.is_file() || ft.is_symlink() {
+                        found.push(candidate);
+                        break;
+                    }
+                }
+                Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
+                Err(e) => return Err(e),
+            }
         }
-
-        return Ok(Some(contents));
     }
 
-    Ok(None)
+    Ok(found)
 }
 
 #[cfg(test)]
@@ -278,4 +319,32 @@ mod tests {
 
         assert_eq!(res, Some(INSTRUCTIONS.to_string()));
     }
+
+    /// When both the repository root and the working directory contain
+    /// AGENTS.md files, their contents are concatenated from root to cwd.
+    #[tokio::test]
+    async fn concatenates_root_and_cwd_docs() {
+        let repo = tempfile::tempdir().expect("tempdir");
+
+        // Simulate a git repository.
+        std::fs::write(
+            repo.path().join(".git"),
+            "gitdir: /path/to/actual/git/dir\n",
+        )
+        .unwrap();
+
+        // Repo root doc.
+        fs::write(repo.path().join("AGENTS.md"), "root doc").unwrap();
+
+        // Nested working directory with its own doc.
+        let nested = repo.path().join("workspace/crate_a");
+        std::fs::create_dir_all(&nested).unwrap();
+        fs::write(nested.join("AGENTS.md"), "crate doc").unwrap();
+
+        let mut cfg = make_config(&repo, 4096, None);
+        cfg.cwd = nested;
+
+        let res = get_user_instructions(&cfg).await.expect("doc expected");
+        assert_eq!(res, "root doc\n\ncrate doc");
+    }
 }

codex-rs/core/src/util.rs

@@ -1,4 +1,6 @@
+use std::fs;
 use std::path::Path;
+use std::path::PathBuf;
 use std::time::Duration;
 
 use rand::Rng;
@@ -42,3 +44,87 @@ pub fn is_inside_git_repo(base_dir: &Path) -> bool {
 
     false
 }
+
+/// Try to resolve the main git repository root for `base_dir`.
+///
+/// - For a normal repo (where `.git` is a directory), returns the directory
+///   that contains the `.git` directory.
+/// - For a worktree (where `.git` is a file with a `gitdir:` pointer), reads
+///   the referenced git directory and, if present, its `commondir` file to
+///   locate the common `.git` directory of the main repository. Returns the
+///   parent of that common directory.
+/// - Returns `None` when no enclosing repo is found.
+pub fn git_main_repo_root(base_dir: &Path) -> Option<PathBuf> {
+    // Walk up from base_dir to find the first ancestor containing a `.git` entry.
+    let mut dir = base_dir.to_path_buf();
+    loop {
+        let dot_git = dir.join(".git");
+        if dot_git.is_dir() {
+            // Standard repository. The repo root is the directory containing `.git`.
+            return Some(dir);
+        } else if dot_git.is_file() {
+            // Worktree case: `.git` is a file like: `gitdir: /path/to/worktrees/<name>`
+            if let Ok(contents) = fs::read_to_string(&dot_git) {
+                // Extract the path after `gitdir:` and trim whitespace.
+                let gitdir_prefix = "gitdir:";
+                let line = contents
+                    .lines()
+                    .find(|l| l.trim_start().starts_with(gitdir_prefix));
+                if let Some(line) = line {
+                    let path_part = line.split_once(':').map(|(_, r)| r.trim());
+                    if let Some(gitdir_str) = path_part {
+                        // Resolve relative paths against the directory containing `.git` (the worktree root).
+                        let gitdir_path = Path::new(gitdir_str);
+                        let gitdir_abs = if gitdir_path.is_absolute() {
+                            gitdir_path.to_path_buf()
+                        } else {
+                            dir.join(gitdir_path)
+                        };
+
+                        // In worktrees, the per-worktree gitdir typically contains a `commondir`
+                        // file that points (possibly relatively) to the common `.git` directory.
+                        let commondir_path = gitdir_abs.join("commondir");
+                        if let Ok(common_dir_rel) = fs::read_to_string(&commondir_path) {
+                            let common_dir_rel = common_dir_rel.trim();
+                            let common_dir_path = Path::new(common_dir_rel);
+                            let common_dir_abs = if common_dir_path.is_absolute() {
+                                common_dir_path.to_path_buf()
+                            } else {
+                                gitdir_abs.join(common_dir_path)
+                            };
+                            // The main repo root is the parent of the common `.git` directory.
+                            if let Some(parent) = common_dir_abs.parent() {
+                                return Some(parent.to_path_buf());
+                            }
+                        } else {
+                            // Fallback: if no commondir file, use the parent of `gitdir_abs` if it looks like a `.git` dir.
+                            if let Some(parent) = gitdir_abs.parent() {
+                                return Some(parent.to_path_buf());
+                            }
+                        }
+                    }
+                }
+            }
+            // If parsing fails, continue the walk upwards in case of nested repos (rare).
+        }
+
+        if !dir.pop() {
+            break;
+        }
+    }
+
+    None
+}
+
+/// Normalize a path for trust configuration lookups.
+///
+/// If inside a git repo, returns the main repository root; otherwise returns the
+// canonicalized `base_dir` (or `base_dir` if canonicalization fails).
+pub fn normalized_trust_project_root(base_dir: &Path) -> PathBuf {
+    if let Some(repo_root) = git_main_repo_root(base_dir) {
+        return repo_root.canonicalize().unwrap_or(repo_root);
+    }
+    base_dir
+        .canonicalize()
+        .unwrap_or_else(|_| base_dir.to_path_buf())
+}

codex-rs/core/tests/prompt_caching.rs

@@ -89,10 +89,15 @@ async fn prefixes_context_and_instructions_once_and_consistently_across_requests
     let shell = default_user_shell().await;
 
     let expected_env_text = format!(
-        "<environment_context>\nCurrent working directory: {}\nApproval policy: on-request\nSandbox mode: read-only\nNetwork access: restricted\n{}</environment_context>",
+        r#"<environment_context>
+  <cwd>{}</cwd>
+  <approval_policy>on-request</approval_policy>
+  <sandbox_mode>read-only</sandbox_mode>
+  <network_access>restricted</network_access>
+{}</environment_context>"#,
         cwd.path().to_string_lossy(),
         match shell.name() {
-            Some(name) => format!("Shell: {name}\n"),
+            Some(name) => format!("  <shell>{}</shell>\n", name),
             None => String::new(),
         }
     );
@@ -190,12 +195,10 @@ async fn overrides_turn_context_but_keeps_cached_prefix_and_key_constant() {
         .unwrap();
     wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
 
-    // Change everything about the turn context.
-    let new_cwd = TempDir::new().unwrap();
     let writable = TempDir::new().unwrap();
     codex
         .submit(Op::OverrideTurnContext {
-            cwd: Some(new_cwd.path().to_path_buf()),
+            cwd: None,
             approval_policy: Some(AskForApproval::Never),
             sandbox_policy: Some(SandboxPolicy::WorkspaceWrite {
                 writable_roots: vec![writable.path().to_path_buf()],
@@ -227,7 +230,6 @@ async fn overrides_turn_context_but_keeps_cached_prefix_and_key_constant() {
 
     let body1 = requests[0].body_json::<serde_json::Value>().unwrap();
     let body2 = requests[1].body_json::<serde_json::Value>().unwrap();
-
     // prompt_cache_key should remain constant across overrides
     assert_eq!(
         body1["prompt_cache_key"], body2["prompt_cache_key"],
@@ -243,16 +245,13 @@ async fn overrides_turn_context_but_keeps_cached_prefix_and_key_constant() {
         "content": [ { "type": "input_text", "text": "hello 2" } ]
     });
     // After overriding the turn context, the environment context should be emitted again
-    // reflecting the new cwd, approval policy and sandbox settings.
-    let shell = default_user_shell().await;
-    let expected_env_text_2 = format!(
-        "<environment_context>\nCurrent working directory: {}\nApproval policy: never\nSandbox mode: workspace-write\nNetwork access: enabled\n{}</environment_context>",
-        new_cwd.path().to_string_lossy(),
-        match shell.name() {
-            Some(name) => format!("Shell: {name}\n"),
-            None => String::new(),
-        }
-    );
+    // reflecting the new approval policy and sandbox settings. Omit cwd because it did
+    // not change.
+    let expected_env_text_2 = r#"<environment_context>
+  <approval_policy>never</approval_policy>
+  <sandbox_mode>workspace-write</sandbox_mode>
+  <network_access>enabled</network_access>
+</environment_context>"#;
     let expected_env_msg_2 = serde_json::json!({
         "type": "message",
         "id": serde_json::Value::Null,

codex-rs/exec/src/event_processor_with_human_output.rs

@@ -20,6 +20,7 @@ use codex_core::protocol::McpToolCallEndEvent;
 use codex_core::protocol::PatchApplyBeginEvent;
 use codex_core::protocol::PatchApplyEndEvent;
 use codex_core::protocol::SessionConfiguredEvent;
+use codex_core::protocol::StreamErrorEvent;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::protocol::TurnAbortReason;
 use codex_core::protocol::TurnDiffEvent;
@@ -174,6 +175,9 @@ impl EventProcessor for EventProcessorWithHumanOutput {
             EventMsg::BackgroundEvent(BackgroundEventEvent { message }) => {
                 ts_println!(self, "{}", message.style(self.dimmed));
             }
+            EventMsg::StreamError(StreamErrorEvent { message }) => {
+                ts_println!(self, "{}", message.style(self.dimmed));
+            }
             EventMsg::TaskStarted => {
                 // Ignore.
             }

codex-rs/mcp-server/src/codex_tool_runner.rs

@@ -268,6 +268,7 @@ async fn run_codex_tool_session_inner(
                     | EventMsg::ExecCommandOutputDelta(_)
                     | EventMsg::ExecCommandEnd(_)
                     | EventMsg::BackgroundEvent(_)
+                    | EventMsg::StreamError(_)
                     | EventMsg::PatchApplyBegin(_)
                     | EventMsg::PatchApplyEnd(_)
                     | EventMsg::TurnDiff(_)

codex-rs/protocol/src/parse_command.rs

@@ -2,6 +2,7 @@ use serde::Deserialize;
 use serde::Serialize;
 
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
 pub enum ParsedCommand {
     Read {
         cmd: String,

codex-rs/protocol/src/protocol.rs

@@ -446,6 +446,10 @@ pub enum EventMsg {
 
     BackgroundEvent(BackgroundEventEvent),
 
+    /// Notification that a model stream experienced an error or disconnect
+    /// and the system is handling it (e.g., retrying with backoff).
+    StreamError(StreamErrorEvent),
+
     /// Notification that the agent is about to apply a code patch. Mirrors
     /// `ExecCommandBegin` so front‑ends can show progress indicators.
     PatchApplyBegin(PatchApplyBeginEvent),
@@ -721,6 +725,11 @@ pub struct BackgroundEventEvent {
     pub message: String,
 }
 
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct StreamErrorEvent {
+    pub message: String,
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct PatchApplyBeginEvent {
     /// Identifier so this can be paired with the PatchApplyEnd event.

codex-rs/tui/src/app.rs

@@ -2,21 +2,21 @@ use crate::app_event::AppEvent;
 use crate::app_event_sender::AppEventSender;
 use crate::chatwidget::ChatWidget;
 use crate::file_search::FileSearchManager;
-use crate::get_git_diff::get_git_diff;
-use crate::slash_command::SlashCommand;
-use crate::transcript_app::run_transcript_app;
+use crate::transcript_app::TranscriptApp;
 use crate::tui;
 use crate::tui::TuiEvent;
 use codex_core::ConversationManager;
 use codex_core::config::Config;
-use codex_core::protocol::Event;
-use codex_core::protocol::Op;
 use codex_core::protocol::TokenUsage;
 use color_eyre::eyre::Result;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyEventKind;
+use crossterm::execute;
+use crossterm::terminal::EnterAlternateScreen;
+use crossterm::terminal::LeaveAlternateScreen;
 use crossterm::terminal::supports_keyboard_enhancement;
+use ratatui::layout::Rect;
 use ratatui::text::Line;
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -39,6 +39,11 @@ pub(crate) struct App {
 
     transcript_lines: Vec<Line<'static>>,
 
+    // Transcript overlay state
+    transcript_overlay: Option<TranscriptApp>,
+    deferred_history_lines: Vec<Line<'static>>,
+    transcript_saved_viewport: Option<Rect>,
+
     enhanced_keys_supported: bool,
 
     /// Controls the animation thread that sends CommitTick events.
@@ -80,6 +85,9 @@ impl App {
             file_search,
             enhanced_keys_supported,
             transcript_lines: Vec::new(),
+            transcript_overlay: None,
+            deferred_history_lines: Vec::new(),
+            transcript_saved_viewport: None,
             commit_anim_running: Arc::new(AtomicBool::new(false)),
         };
 
@@ -105,34 +113,55 @@ impl App {
         tui: &mut tui::Tui,
         event: TuiEvent,
     ) -> Result<bool> {
-        match event {
-            TuiEvent::Key(key_event) => {
-                self.handle_key_event(tui, key_event).await;
+        if let Some(overlay) = &mut self.transcript_overlay {
+            overlay.handle_event(tui, event)?;
+            if overlay.is_done {
+                // Exit alternate screen and restore viewport.
+                let _ = execute!(tui.terminal.backend_mut(), LeaveAlternateScreen);
+                if let Some(saved) = self.transcript_saved_viewport.take() {
+                    tui.terminal.set_viewport_area(saved);
+                }
+                if !self.deferred_history_lines.is_empty() {
+                    let lines = std::mem::take(&mut self.deferred_history_lines);
+                    tui.insert_history_lines(lines);
+                }
+                self.transcript_overlay = None;
             }
-            TuiEvent::Paste(pasted) => {
-                // Many terminals convert newlines to \r when pasting (e.g., iTerm2),
-                // but tui-textarea expects \n. Normalize CR to LF.
-                // [tui-textarea]: https://github.com/rhysd/tui-textarea/blob/4d18622eeac13b309e0ff6a55a46ac6706da68cf/src/textarea.rs#L782-L783
-                // [iTerm2]: https://github.com/gnachman/iTerm2/blob/5d0c0d9f68523cbd0494dad5422998964a2ecd8d/sources/iTermPasteHelper.m#L206-L216
-                let pasted = pasted.replace("\r", "\n");
-                self.chat_widget.handle_paste(pasted);
-            }
-            TuiEvent::Draw => {
-                tui.draw(
-                    self.chat_widget.desired_height(tui.terminal.size()?.width),
-                    |frame| {
-                        frame.render_widget_ref(&self.chat_widget, frame.area());
-                        if let Some((x, y)) = self.chat_widget.cursor_pos(frame.area()) {
-                            frame.set_cursor_position((x, y));
-                        }
-                    },
-                )?;
-            }
-            #[cfg(unix)]
-            TuiEvent::ResumeFromSuspend => {
-                let cursor_pos = tui.terminal.get_cursor_position()?;
-                tui.terminal
-                    .set_viewport_area(ratatui::layout::Rect::new(0, cursor_pos.y, 0, 0));
+            tui.frame_requester().schedule_frame();
+        } else {
+            match event {
+                TuiEvent::Key(key_event) => {
+                    self.handle_key_event(tui, key_event).await;
+                }
+                TuiEvent::Paste(pasted) => {
+                    // Many terminals convert newlines to \r when pasting (e.g., iTerm2),
+                    // but tui-textarea expects \n. Normalize CR to LF.
+                    // [tui-textarea]: https://github.com/rhysd/tui-textarea/blob/4d18622eeac13b309e0ff6a55a46ac6706da68cf/src/textarea.rs#L782-L783
+                    // [iTerm2]: https://github.com/gnachman/iTerm2/blob/5d0c0d9f68523cbd0494dad5422998964a2ecd8d/sources/iTermPasteHelper.m#L206-L216
+                    let pasted = pasted.replace("\r", "\n");
+                    self.chat_widget.handle_paste(pasted);
+                }
+                TuiEvent::Draw => {
+                    tui.draw(
+                        self.chat_widget.desired_height(tui.terminal.size()?.width),
+                        |frame| {
+                            frame.render_widget_ref(&self.chat_widget, frame.area());
+                            if let Some((x, y)) = self.chat_widget.cursor_pos(frame.area()) {
+                                frame.set_cursor_position((x, y));
+                            }
+                        },
+                    )?;
+                }
+                #[cfg(unix)]
+                TuiEvent::ResumeFromSuspend => {
+                    let cursor_pos = tui.terminal.get_cursor_position()?;
+                    tui.terminal.set_viewport_area(ratatui::layout::Rect::new(
+                        0,
+                        cursor_pos.y,
+                        0,
+                        0,
+                    ));
+                }
             }
         }
         Ok(true)
@@ -140,15 +169,43 @@ impl App {
 
     fn handle_event(&mut self, tui: &mut tui::Tui, event: AppEvent) -> Result<bool> {
         match event {
+            AppEvent::NewSession => {
+                self.chat_widget = ChatWidget::new(
+                    self.config.clone(),
+                    self.server.clone(),
+                    tui.frame_requester(),
+                    self.app_event_tx.clone(),
+                    None,
+                    Vec::new(),
+                    self.enhanced_keys_supported,
+                );
+                tui.frame_requester().schedule_frame();
+            }
             AppEvent::InsertHistoryLines(lines) => {
+                if let Some(overlay) = &mut self.transcript_overlay {
+                    overlay.insert_lines(lines.clone());
+                    tui.frame_requester().schedule_frame();
+                }
                 self.transcript_lines.extend(lines.clone());
-                tui.insert_history_lines(lines);
+                if self.transcript_overlay.is_some() {
+                    self.deferred_history_lines.extend(lines);
+                } else {
+                    tui.insert_history_lines(lines);
+                }
             }
             AppEvent::InsertHistoryCell(cell) => {
+                if let Some(overlay) = &mut self.transcript_overlay {
+                    overlay.insert_lines(cell.transcript_lines());
+                    tui.frame_requester().schedule_frame();
+                }
                 self.transcript_lines.extend(cell.transcript_lines());
                 let display = cell.display_lines();
                 if !display.is_empty() {
-                    tui.insert_history_lines(display);
+                    if self.transcript_overlay.is_some() {
+                        self.deferred_history_lines.extend(display);
+                    } else {
+                        tui.insert_history_lines(display);
+                    }
                 }
             }
             AppEvent::StartCommitAnimation => {
@@ -183,111 +240,6 @@ impl App {
             AppEvent::DiffResult(text) => {
                 self.chat_widget.add_diff_output(text);
             }
-            AppEvent::DispatchCommand(command) => match command {
-                SlashCommand::New => {
-                    // User accepted – switch to chat view.
-                    let new_widget = ChatWidget::new(
-                        self.config.clone(),
-                        self.server.clone(),
-                        tui.frame_requester(),
-                        self.app_event_tx.clone(),
-                        None,
-                        Vec::new(),
-                        self.enhanced_keys_supported,
-                    );
-                    self.chat_widget = new_widget;
-                    tui.frame_requester().schedule_frame();
-                }
-                SlashCommand::Init => {
-                    // Guard: do not run if a task is active.
-                    const INIT_PROMPT: &str = include_str!("../prompt_for_init_command.md");
-                    self.chat_widget
-                        .submit_text_message(INIT_PROMPT.to_string());
-                }
-                SlashCommand::Compact => {
-                    self.chat_widget.clear_token_usage();
-                    self.app_event_tx.send(AppEvent::CodexOp(Op::Compact));
-                }
-                SlashCommand::Model => {
-                    self.chat_widget.open_model_popup();
-                }
-                SlashCommand::Approvals => {
-                    self.chat_widget.open_approvals_popup();
-                }
-                SlashCommand::Quit => {
-                    return Ok(false);
-                }
-                SlashCommand::Logout => {
-                    if let Err(e) = codex_login::logout(&self.config.codex_home) {
-                        tracing::error!("failed to logout: {e}");
-                    }
-                    return Ok(false);
-                }
-                SlashCommand::Diff => {
-                    self.chat_widget.add_diff_in_progress();
-                    let tx = self.app_event_tx.clone();
-                    tokio::spawn(async move {
-                        let text = match get_git_diff().await {
-                            Ok((is_git_repo, diff_text)) => {
-                                if is_git_repo {
-                                    diff_text
-                                } else {
-                                    "`/diff` — _not inside a git repository_".to_string()
-                                }
-                            }
-                            Err(e) => format!("Failed to compute diff: {e}"),
-                        };
-                        tx.send(AppEvent::DiffResult(text));
-                    });
-                }
-                SlashCommand::Mention => {
-                    self.chat_widget.insert_str("@");
-                }
-                SlashCommand::Status => {
-                    self.chat_widget.add_status_output();
-                }
-                SlashCommand::Mcp => {
-                    self.chat_widget.add_mcp_output();
-                }
-                #[cfg(debug_assertions)]
-                SlashCommand::TestApproval => {
-                    use codex_core::protocol::EventMsg;
-                    use std::collections::HashMap;
-
-                    use codex_core::protocol::ApplyPatchApprovalRequestEvent;
-                    use codex_core::protocol::FileChange;
-
-                    self.app_event_tx.send(AppEvent::CodexEvent(Event {
-                        id: "1".to_string(),
-                        // msg: EventMsg::ExecApprovalRequest(ExecApprovalRequestEvent {
-                        //     call_id: "1".to_string(),
-                        //     command: vec!["git".into(), "apply".into()],
-                        //     cwd: self.config.cwd.clone(),
-                        //     reason: Some("test".to_string()),
-                        // }),
-                        msg: EventMsg::ApplyPatchApprovalRequest(ApplyPatchApprovalRequestEvent {
-                            call_id: "1".to_string(),
-                            changes: HashMap::from([
-                                (
-                                    PathBuf::from("/tmp/test.txt"),
-                                    FileChange::Add {
-                                        content: "test".to_string(),
-                                    },
-                                ),
-                                (
-                                    PathBuf::from("/tmp/test2.txt"),
-                                    FileChange::Update {
-                                        unified_diff: "+test\n-test2".to_string(),
-                                        move_path: None,
-                                    },
-                                ),
-                            ]),
-                            reason: None,
-                            grant_root: Some(PathBuf::from("/tmp")),
-                        }),
-                    }));
-                }
-            },
             AppEvent::StartFileSearch(query) => {
                 if !query.is_empty() {
                     self.file_search.on_user_query(query);
@@ -340,7 +292,17 @@ impl App {
                 kind: KeyEventKind::Press,
                 ..
             } => {
-                run_transcript_app(tui, self.transcript_lines.clone()).await;
+                // Enter alternate screen and set viewport to full size.
+                let _ = execute!(tui.terminal.backend_mut(), EnterAlternateScreen);
+                if let Ok(size) = tui.terminal.size() {
+                    self.transcript_saved_viewport = Some(tui.terminal.viewport_area);
+                    tui.terminal
+                        .set_viewport_area(Rect::new(0, 0, size.width, size.height));
+                    let _ = tui.terminal.clear();
+                }
+
+                self.transcript_overlay = Some(TranscriptApp::new(self.transcript_lines.clone()));
+                tui.frame_requester().schedule_frame();
             }
             KeyEvent {
                 kind: KeyEventKind::Press | KeyEventKind::Repeat,

codex-rs/tui/src/app_event.rs

@@ -4,7 +4,6 @@ use ratatui::text::Line;
 
 use crate::history_cell::HistoryCell;
 
-use crate::slash_command::SlashCommand;
 use codex_core::protocol::AskForApproval;
 use codex_core::protocol::SandboxPolicy;
 use codex_core::protocol_config_types::ReasoningEffort;
@@ -14,6 +13,9 @@ use codex_core::protocol_config_types::ReasoningEffort;
 pub(crate) enum AppEvent {
     CodexEvent(Event),
 
+    /// Start a new session.
+    NewSession,
+
     /// Request to exit the application gracefully.
     ExitRequest,
 
@@ -21,10 +23,6 @@ pub(crate) enum AppEvent {
     /// bubbling channels through layers of widgets.
     CodexOp(codex_core::protocol::Op),
 
-    /// Dispatch a recognized slash command from the UI (composer) to the app
-    /// layer so it can be handled centrally.
-    DispatchCommand(SlashCommand),
-
     /// Kick off an asynchronous file search for the given query (text after
     /// the `@`). Previous searches may be cancelled by the app layer so there
     /// is at most one in-flight search.

codex-rs/tui/src/bottom_pane/chat_composer.rs

@@ -23,6 +23,7 @@ use ratatui::widgets::WidgetRef;
 use super::chat_composer_history::ChatComposerHistory;
 use super::command_popup::CommandPopup;
 use super::file_search_popup::FileSearchPopup;
+use crate::slash_command::SlashCommand;
 
 use crate::app_event::AppEvent;
 use crate::app_event_sender::AppEventSender;
@@ -38,6 +39,7 @@ const LARGE_PASTE_CHAR_THRESHOLD: usize = 1000;
 /// Result returned when the user interacts with the text area.
 pub enum InputResult {
     Submitted(String),
+    Command(SlashCommand),
     None,
 }
 
@@ -289,15 +291,15 @@ impl ChatComposer {
                 ..
             } => {
                 if let Some(cmd) = popup.selected_command() {
-                    // Send command to the app layer.
-                    self.app_event_tx.send(AppEvent::DispatchCommand(*cmd));
-
                     // Clear textarea so no residual text remains.
                     self.textarea.set_text("");
 
+                    let result = (InputResult::Command(*cmd), true);
+
                     // Hide popup since the command has been dispatched.
                     self.active_popup = ActivePopup::None;
-                    return (InputResult::None, true);
+
+                    return result;
                 }
                 // Fallback to default newline handling if no command selected.
                 self.handle_key_event_without_popup(key_event)
@@ -1039,9 +1041,8 @@ mod tests {
         use crossterm::event::KeyCode;
         use crossterm::event::KeyEvent;
         use crossterm::event::KeyModifiers;
-        use tokio::sync::mpsc::error::TryRecvError;
 
-        let (tx, mut rx) = unbounded_channel::<AppEvent>();
+        let (tx, _rx) = unbounded_channel::<AppEvent>();
         let sender = AppEventSender::new(tx);
         let mut composer =
             ChatComposer::new(true, sender, false, "Ask Codex to do anything".to_string());
@@ -1057,25 +1058,18 @@ mod tests {
         let (result, _needs_redraw) =
             composer.handle_key_event(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE));
 
-        // When a slash command is dispatched, the composer should not submit
-        // literal text and should clear its textarea.
+        // When a slash command is dispatched, the composer should return a
+        // Command result (not submit literal text) and clear its textarea.
         match result {
-            InputResult::None => {}
+            InputResult::Command(cmd) => {
+                assert_eq!(cmd.command(), "init");
+            }
             InputResult::Submitted(text) => {
                 panic!("expected command dispatch, but composer submitted literal text: {text}")
             }
+            InputResult::None => panic!("expected Command result for '/init'"),
         }
         assert!(composer.textarea.is_empty(), "composer should be cleared");
-
-        // Verify a DispatchCommand event for the "init" command was sent.
-        match rx.try_recv() {
-            Ok(AppEvent::DispatchCommand(cmd)) => {
-                assert_eq!(cmd.command(), "init");
-            }
-            Ok(_other) => panic!("unexpected app event"),
-            Err(TryRecvError::Empty) => panic!("expected a DispatchCommand event for '/init'"),
-            Err(TryRecvError::Disconnected) => panic!("app event channel disconnected"),
-        }
     }
 
     #[test]
@@ -1105,9 +1099,8 @@ mod tests {
         use crossterm::event::KeyCode;
         use crossterm::event::KeyEvent;
         use crossterm::event::KeyModifiers;
-        use tokio::sync::mpsc::error::TryRecvError;
 
-        let (tx, mut rx) = unbounded_channel::<AppEvent>();
+        let (tx, _rx) = unbounded_channel::<AppEvent>();
         let sender = AppEventSender::new(tx);
         let mut composer =
             ChatComposer::new(true, sender, false, "Ask Codex to do anything".to_string());
@@ -1120,24 +1113,16 @@ mod tests {
             composer.handle_key_event(KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE));
 
         match result {
-            InputResult::None => {}
+            InputResult::Command(cmd) => {
+                assert_eq!(cmd.command(), "mention");
+            }
             InputResult::Submitted(text) => {
                 panic!("expected command dispatch, but composer submitted literal text: {text}")
             }
+            InputResult::None => panic!("expected Command result for '/mention'"),
         }
         assert!(composer.textarea.is_empty(), "composer should be cleared");
-
-        match rx.try_recv() {
-            Ok(AppEvent::DispatchCommand(cmd)) => {
-                assert_eq!(cmd.command(), "mention");
-                composer.insert_str("@");
-            }
-            Ok(_other) => panic!("unexpected app event"),
-            Err(TryRecvError::Empty) => panic!("expected a DispatchCommand event for '/mention'"),
-            Err(TryRecvError::Disconnected) => {
-                panic!("app event channel disconnected")
-            }
-        }
+        composer.insert_str("@");
         assert_eq!(composer.textarea.text(), "@");
     }
 

codex-rs/tui/src/chatwidget.rs

@@ -23,6 +23,7 @@ use codex_core::protocol::McpToolCallBeginEvent;
 use codex_core::protocol::McpToolCallEndEvent;
 use codex_core::protocol::Op;
 use codex_core::protocol::PatchApplyBeginEvent;
+use codex_core::protocol::StreamErrorEvent;
 use codex_core::protocol::TaskCompleteEvent;
 use codex_core::protocol::TokenUsage;
 use codex_core::protocol::TurnDiffEvent;
@@ -47,11 +48,13 @@ use crate::bottom_pane::CancellationEvent;
 use crate::bottom_pane::InputResult;
 use crate::bottom_pane::SelectionAction;
 use crate::bottom_pane::SelectionItem;
+use crate::get_git_diff::get_git_diff;
 use crate::history_cell;
 use crate::history_cell::CommandOutput;
 use crate::history_cell::ExecCell;
 use crate::history_cell::HistoryCell;
 use crate::history_cell::PatchEventType;
+use crate::slash_command::SlashCommand;
 use crate::tui::FrameRequester;
 // streaming internals are provided by crate::streaming and crate::markdown_stream
 use crate::user_approval_widget::ApprovalRequest;
@@ -327,6 +330,12 @@ impl ChatWidget {
     fn on_background_event(&mut self, message: String) {
         debug!("BackgroundEvent: {message}");
     }
+
+    fn on_stream_error(&mut self, message: String) {
+        // Show stream errors in the transcript so users see retry/backoff info.
+        self.add_to_history(history_cell::new_stream_error_event(message));
+        self.mark_needs_redraw();
+    }
     /// Periodic tick to commit at most one queued line to history with a small delay,
     /// animating the output.
     pub(crate) fn on_commit_tick(&mut self) {
@@ -576,10 +585,109 @@ impl ChatWidget {
             InputResult::Submitted(text) => {
                 self.submit_user_message(text.into());
             }
+            InputResult::Command(cmd) => {
+                self.dispatch_command(cmd);
+            }
             InputResult::None => {}
         }
     }
 
+    fn dispatch_command(&mut self, cmd: SlashCommand) {
+        match cmd {
+            SlashCommand::New => {
+                self.app_event_tx.send(AppEvent::NewSession);
+            }
+            SlashCommand::Init => {
+                // Guard: do not run if a task is active.
+                const INIT_PROMPT: &str = include_str!("../prompt_for_init_command.md");
+                self.submit_text_message(INIT_PROMPT.to_string());
+            }
+            SlashCommand::Compact => {
+                self.clear_token_usage();
+                self.app_event_tx.send(AppEvent::CodexOp(Op::Compact));
+            }
+            SlashCommand::Model => {
+                self.open_model_popup();
+            }
+            SlashCommand::Approvals => {
+                self.open_approvals_popup();
+            }
+            SlashCommand::Quit => {
+                self.app_event_tx.send(AppEvent::ExitRequest);
+            }
+            SlashCommand::Logout => {
+                if let Err(e) = codex_login::logout(&self.config.codex_home) {
+                    tracing::error!("failed to logout: {e}");
+                }
+                self.app_event_tx.send(AppEvent::ExitRequest);
+            }
+            SlashCommand::Diff => {
+                self.add_diff_in_progress();
+                let tx = self.app_event_tx.clone();
+                tokio::spawn(async move {
+                    let text = match get_git_diff().await {
+                        Ok((is_git_repo, diff_text)) => {
+                            if is_git_repo {
+                                diff_text
+                            } else {
+                                "`/diff` — _not inside a git repository_".to_string()
+                            }
+                        }
+                        Err(e) => format!("Failed to compute diff: {e}"),
+                    };
+                    tx.send(AppEvent::DiffResult(text));
+                });
+            }
+            SlashCommand::Mention => {
+                self.insert_str("@");
+            }
+            SlashCommand::Status => {
+                self.add_status_output();
+            }
+            SlashCommand::Mcp => {
+                self.add_mcp_output();
+            }
+            #[cfg(debug_assertions)]
+            SlashCommand::TestApproval => {
+                use codex_core::protocol::EventMsg;
+                use std::collections::HashMap;
+
+                use codex_core::protocol::ApplyPatchApprovalRequestEvent;
+                use codex_core::protocol::FileChange;
+
+                self.app_event_tx.send(AppEvent::CodexEvent(Event {
+                    id: "1".to_string(),
+                    // msg: EventMsg::ExecApprovalRequest(ExecApprovalRequestEvent {
+                    //     call_id: "1".to_string(),
+                    //     command: vec!["git".into(), "apply".into()],
+                    //     cwd: self.config.cwd.clone(),
+                    //     reason: Some("test".to_string()),
+                    // }),
+                    msg: EventMsg::ApplyPatchApprovalRequest(ApplyPatchApprovalRequestEvent {
+                        call_id: "1".to_string(),
+                        changes: HashMap::from([
+                            (
+                                PathBuf::from("/tmp/test.txt"),
+                                FileChange::Add {
+                                    content: "test".to_string(),
+                                },
+                            ),
+                            (
+                                PathBuf::from("/tmp/test2.txt"),
+                                FileChange::Update {
+                                    unified_diff: "+test\n-test2".to_string(),
+                                    move_path: None,
+                                },
+                            ),
+                        ]),
+                        reason: None,
+                        grant_root: Some(PathBuf::from("/tmp")),
+                    }),
+                }));
+            }
+        }
+    }
+
     pub(crate) fn handle_paste(&mut self, text: String) {
         self.bottom_pane.handle_paste(text);
     }
@@ -690,6 +798,7 @@ impl ChatWidget {
             EventMsg::BackgroundEvent(BackgroundEventEvent { message }) => {
                 self.on_background_event(message)
             }
+            EventMsg::StreamError(StreamErrorEvent { message }) => self.on_stream_error(message),
         }
         // Coalesce redraws: issue at most one after handling the event
         if self.needs_redraw {

codex-rs/tui/src/chatwidget/tests.rs

@@ -19,6 +19,7 @@ use codex_core::protocol::ExecCommandEndEvent;
 use codex_core::protocol::FileChange;
 use codex_core::protocol::PatchApplyBeginEvent;
 use codex_core::protocol::PatchApplyEndEvent;
+use codex_core::protocol::StreamErrorEvent;
 use codex_core::protocol::TaskCompleteEvent;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
@@ -823,6 +824,25 @@ fn plan_update_renders_history_cell() {
     assert!(blob.contains("Write tests"));
 }
 
+#[test]
+fn stream_error_is_rendered_to_history() {
+    let (mut chat, mut rx, _op_rx) = make_chatwidget_manual();
+    let msg = "stream error: stream disconnected before completion: idle timeout waiting for SSE; retrying 1/5 in 211ms…";
+    chat.handle_codex_event(Event {
+        id: "sub-1".into(),
+        msg: EventMsg::StreamError(StreamErrorEvent {
+            message: msg.to_string(),
+        }),
+    });
+
+    let cells = drain_insert_history(&mut rx);
+    assert!(!cells.is_empty(), "expected a history cell for StreamError");
+    let blob = lines_to_single_string(cells.last().unwrap());
+    assert!(blob.contains("⚠ "));
+    assert!(blob.contains("stream error:"));
+    assert!(blob.contains("idle timeout waiting for SSE"));
+}
+
 #[test]
 fn headers_emitted_on_stream_begin_for_answer_and_not_for_reasoning() {
     let (mut chat, mut rx, _op_rx) = make_chatwidget_manual();

codex-rs/tui/src/diff_render.rs

@@ -212,7 +212,18 @@ fn render_patch_details(changes: &HashMap<PathBuf, FileChange>) -> Vec<RtLine<'s
                 move_path: _,
             } => {
                 if let Ok(patch) = diffy::Patch::from_str(unified_diff) {
+                    let mut is_first_hunk = true;
                     for h in patch.hunks() {
+                        // Render a simple separator between non-contiguous hunks
+                        // instead of diff-style @@ headers.
+                        if !is_first_hunk {
+                            out.push(RtLine::from(vec![
+                                RtSpan::raw("    "),
+                                RtSpan::styled("⋮", style_dim()),
+                            ]));
+                        }
+                        is_first_hunk = false;
+
                         let mut old_ln = h.old_range().start();
                         let mut new_ln = h.new_range().start();
                         for l in h.lines() {
@@ -276,8 +287,7 @@ fn push_wrapped_diff_line(
     // ("+"/"-" for inserts/deletes, or a space for context lines) so alignment
     // stays consistent across all diff lines.
     let gap_after_ln = SPACES_AFTER_LINE_NUMBER.saturating_sub(ln_str.len());
-    let first_prefix_cols = indent.len() + ln_str.len() + gap_after_ln;
-    let cont_prefix_cols = indent.len() + ln_str.len() + gap_after_ln;
+    let prefix_cols = indent.len() + ln_str.len() + gap_after_ln;
 
     let mut first = true;
     let (sign_opt, line_style) = match kind {
@@ -286,16 +296,14 @@ fn push_wrapped_diff_line(
         DiffLineType::Context => (None, None),
     };
     let mut lines: Vec<RtLine<'static>> = Vec::new();
-    while !remaining_text.is_empty() {
-        let prefix_cols = if first {
-            first_prefix_cols
-        } else {
-            cont_prefix_cols
-        };
+
+    loop {
         // Fit the content for the current terminal row:
         // compute how many columns are available after the prefix, then split
         // at a UTF-8 character boundary so this row's chunk fits exactly.
-        let available_content_cols = term_cols.saturating_sub(prefix_cols).max(1);
+        let available_content_cols = term_cols
+            .saturating_sub(if first { prefix_cols + 1 } else { prefix_cols })
+            .max(1);
         let split_at_byte_index = remaining_text
             .char_indices()
             .nth(available_content_cols)
@@ -341,6 +349,9 @@ fn push_wrapped_diff_line(
             }
             lines.push(line);
         }
+        if remaining_text.is_empty() {
+            break;
+        }
     }
     lines
 }
@@ -430,4 +441,72 @@ mod tests {
         // Render into a small terminal to capture the visual layout
         snapshot_lines("wrap_behavior_insert", lines, DEFAULT_WRAP_COLS + 10, 8);
     }
+
+    #[test]
+    fn ui_snapshot_single_line_replacement_counts() {
+        // Reproduce: one deleted line replaced by one inserted line, no extra context
+        let original = "# Codex CLI (Rust Implementation)\n";
+        let modified = "# Codex CLI (Rust Implementation) banana\n";
+        let patch = diffy::create_patch(original, modified).to_string();
+
+        let mut changes: HashMap<PathBuf, FileChange> = HashMap::new();
+        changes.insert(
+            PathBuf::from("README.md"),
+            FileChange::Update {
+                unified_diff: patch,
+                move_path: None,
+            },
+        );
+
+        let lines =
+            create_diff_summary("proposed patch", &changes, PatchEventType::ApprovalRequest);
+
+        snapshot_lines("single_line_replacement_counts", lines, 80, 8);
+    }
+
+    #[test]
+    fn ui_snapshot_blank_context_line() {
+        // Ensure a hunk that includes a blank context line at the beginning is rendered visibly
+        let original = "\nY\n";
+        let modified = "\nY changed\n";
+        let patch = diffy::create_patch(original, modified).to_string();
+
+        let mut changes: HashMap<PathBuf, FileChange> = HashMap::new();
+        changes.insert(
+            PathBuf::from("example.txt"),
+            FileChange::Update {
+                unified_diff: patch,
+                move_path: None,
+            },
+        );
+
+        let lines =
+            create_diff_summary("proposed patch", &changes, PatchEventType::ApprovalRequest);
+
+        snapshot_lines("blank_context_line", lines, 80, 10);
+    }
+
+    #[test]
+    fn ui_snapshot_vertical_ellipsis_between_hunks() {
+        // Create a patch with two separate hunks to ensure we render the vertical ellipsis (⋮)
+        let original =
+            "line 1\nline 2\nline 3\nline 4\nline 5\nline 6\nline 7\nline 8\nline 9\nline 10\n";
+        let modified = "line 1\nline two changed\nline 3\nline 4\nline 5\nline 6\nline 7\nline 8\nline nine changed\nline 10\n";
+        let patch = diffy::create_patch(original, modified).to_string();
+
+        let mut changes: HashMap<PathBuf, FileChange> = HashMap::new();
+        changes.insert(
+            PathBuf::from("example.txt"),
+            FileChange::Update {
+                unified_diff: patch,
+                move_path: None,
+            },
+        );
+
+        let lines =
+            create_diff_summary("proposed patch", &changes, PatchEventType::ApprovalRequest);
+
+        // Height is large enough to show both hunks and the separator
+        snapshot_lines("vertical_ellipsis_between_hunks", lines, 80, 16);
+    }
 }

codex-rs/tui/src/history_cell.rs

@@ -12,6 +12,7 @@ use codex_core::config::Config;
 use codex_core::plan_tool::PlanItemArg;
 use codex_core::plan_tool::StepStatus;
 use codex_core::plan_tool::UpdatePlanArgs;
+use codex_core::project_doc::discover_project_doc_paths;
 use codex_core::protocol::FileChange;
 use codex_core::protocol::McpInvocation;
 use codex_core::protocol::SandboxPolicy;
@@ -561,6 +562,54 @@ pub(crate) fn new_status_output(
         sandbox_name.into(),
     ]));
 
+    // AGENTS.md files discovered via core's project_doc logic
+    let agents_list = {
+        match discover_project_doc_paths(config) {
+            Ok(paths) => {
+                let mut rels: Vec<String> = Vec::new();
+                for p in paths {
+                    let display = if let Some(parent) = p.parent() {
+                        if parent == config.cwd {
+                            "AGENTS.md".to_string()
+                        } else {
+                            let mut cur = config.cwd.as_path();
+                            let mut ups = 0usize;
+                            let mut reached = false;
+                            while let Some(c) = cur.parent() {
+                                if cur == parent {
+                                    reached = true;
+                                    break;
+                                }
+                                cur = c;
+                                ups += 1;
+                            }
+                            if reached {
+                                format!("{}AGENTS.md", "../".repeat(ups))
+                            } else if let Ok(stripped) = p.strip_prefix(&config.cwd) {
+                                stripped.display().to_string()
+                            } else {
+                                p.display().to_string()
+                            }
+                        }
+                    } else {
+                        p.display().to_string()
+                    };
+                    rels.push(display);
+                }
+                rels
+            }
+            Err(_) => Vec::new(),
+        }
+    };
+    if agents_list.is_empty() {
+        lines.push(Line::from("  • AGENTS files: (none)"));
+    } else {
+        lines.push(Line::from(vec![
+            "  • AGENTS files: ".into(),
+            agents_list.join(", ").into(),
+        ]));
+    }
+
     lines.push(Line::from(""));
 
     // 👤 Account (only if ChatGPT tokens exist), shown under the first block
@@ -751,6 +800,12 @@ pub(crate) fn new_error_event(message: String) -> PlainHistoryCell {
     PlainHistoryCell { lines }
 }
 
+pub(crate) fn new_stream_error_event(message: String) -> PlainHistoryCell {
+    let lines: Vec<Line<'static>> =
+        vec![vec!["⚠ ".magenta().bold(), message.dim()].into(), "".into()];
+    PlainHistoryCell { lines }
+}
+
 /// Render a user‑friendly plan update styled like a checkbox todo list.
 pub(crate) fn new_plan_update(update: UpdatePlanArgs) -> PlainHistoryCell {
     let UpdatePlanArgs { explanation, plan } = update;

codex-rs/tui/src/session_log.rs

@@ -132,13 +132,11 @@ pub(crate) fn log_inbound_app_event(event: &AppEvent) {
         AppEvent::CodexEvent(ev) => {
             write_record("to_tui", "codex_event", ev);
         }
-
-        AppEvent::DispatchCommand(cmd) => {
+        AppEvent::NewSession => {
             let value = json!({
                 "ts": now_ts(),
                 "dir": "to_tui",
-                "kind": "slash_command",
-                "command": format!("{:?}", cmd),
+                "kind": "new_session",
             });
             LOGGER.write_json_line(value);
         }

codex-rs/tui/src/shimmer.rs

@@ -63,9 +63,11 @@ pub(crate) fn shimmer_spans(text: &str) -> Vec<Span<'static>> {
 }
 
 fn color_for_level(level: u8) -> Style {
-    if level < 144 {
+    // Tune thresholds so the edges of the shimmer band appear dim
+    // in fallback mode (no true color support).
+    if level < 160 {
         Style::default().add_modifier(Modifier::DIM)
-    } else if level < 208 {
+    } else if level < 224 {
         Style::default()
     } else {
         Style::default().add_modifier(Modifier::BOLD)

codex-rs/tui/src/snapshots/codex_tui__diff_render__tests__blank_context_line.snap

@@ -0,0 +1,14 @@
+---
+source: tui/src/diff_render.rs
+expression: terminal.backend()
+---
+"proposed patch to 1 file (+1 -1)                                                "
+"  └ example.txt                                                                 "
+"    1                                                                           "
+"    2     -Y                                                                    "
+"    2     +Y changed                                                            "
+"                                                                                "
+"                                                                                "
+"                                                                                "
+"                                                                                "
+"                                                                                "

codex-rs/tui/src/snapshots/codex_tui__diff_render__tests__single_line_replacement_counts.snap

@@ -0,0 +1,12 @@
+---
+source: tui/src/diff_render.rs
+expression: terminal.backend()
+---
+"proposed patch to 1 file (+1 -1)                                                "
+"  └ README.md                                                                   "
+"    1     -# Codex CLI (Rust Implementation)                                    "
+"    1     +# Codex CLI (Rust Implementation) banana                             "
+"                                                                                "
+"                                                                                "
+"                                                                                "
+"                                                                                "

codex-rs/tui/src/snapshots/codex_tui__diff_render__tests__update_details_with_rename.snap

@@ -1,6 +1,5 @@
 ---
 source: tui/src/diff_render.rs
-assertion_line: 380
 expression: terminal.backend()
 ---
 "proposed patch to 1 file (+1 -1)                                                "

codex-rs/tui/src/snapshots/codex_tui__diff_render__tests__vertical_ellipsis_between_hunks.snap

@@ -0,0 +1,20 @@
+---
+source: tui/src/diff_render.rs
+expression: terminal.backend()
+---
+"proposed patch to 1 file (+2 -2)                                                "
+"  └ example.txt                                                                 "
+"    1      line 1                                                               "
+"    2     -line 2                                                               "
+"    2     +line two changed                                                     "
+"    3      line 3                                                               "
+"    4      line 4                                                               "
+"    5      line 5                                                               "
+"    ⋮                                                                           "
+"    6      line 6                                                               "
+"    7      line 7                                                               "
+"    8      line 8                                                               "
+"    9     -line 9                                                               "
+"    9     +line nine changed                                                    "
+"    10     line 10                                                              "
+"                                                                                "

codex-rs/tui/src/snapshots/codex_tui__diff_render__tests__wrap_behavior_insert.snap

@@ -1,10 +1,9 @@
 ---
 source: tui/src/diff_render.rs
-assertion_line: 380
 expression: terminal.backend()
 ---
-"    1     +this is a very long line that should wrap across multiple terminal col         "
-"           umns and continue                                                              "
+"    1     +this is a very long line that should wrap across multiple terminal co          "
+"           lumns and continue                                                             "
 "                                                                                          "
 "                                                                                          "
 "                                                                                          "

codex-rs/tui/src/transcript_app.rs

@@ -1,11 +1,11 @@
+use std::io::Result;
+
 use crate::insert_history;
 use crate::tui;
+use crate::tui::TuiEvent;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
 use crossterm::event::KeyEventKind;
-use crossterm::execute;
-use crossterm::terminal::EnterAlternateScreen;
-use crossterm::terminal::LeaveAlternateScreen;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
 use ratatui::style::Color;
@@ -16,52 +16,6 @@ use ratatui::text::Line;
 use ratatui::text::Span;
 use ratatui::widgets::Paragraph;
 use ratatui::widgets::WidgetRef;
-use tokio::select;
-
-pub async fn run_transcript_app(tui: &mut tui::Tui, transcript_lines: Vec<Line<'static>>) {
-    use tokio_stream::StreamExt;
-    let _ = execute!(tui.terminal.backend_mut(), EnterAlternateScreen);
-    #[allow(clippy::unwrap_used)]
-    let size = tui.terminal.size().unwrap();
-    let old_viewport_area = tui.terminal.viewport_area;
-    tui.terminal
-        .set_viewport_area(Rect::new(0, 0, size.width, size.height));
-    let _ = tui.terminal.clear();
-
-    let tui_events = tui.event_stream();
-    tokio::pin!(tui_events);
-
-    tui.frame_requester().schedule_frame();
-
-    let mut app = TranscriptApp {
-        transcript_lines,
-        scroll_offset: usize::MAX,
-        is_done: false,
-    };
-
-    while !app.is_done {
-        select! {
-            Some(event) = tui_events.next() => {
-                match event {
-                    crate::tui::TuiEvent::Key(key_event) => {
-                        app.handle_key_event(tui, key_event);
-                        tui.frame_requester().schedule_frame();
-                    }
-                    crate::tui::TuiEvent::Draw => {
-                        let _ = tui.draw(u16::MAX, |frame| {
-                            app.render(frame.area(), frame.buffer);
-                        });
-                    }
-                    _ => {}
-                }
-            }
-        }
-    }
-
-    let _ = execute!(tui.terminal.backend_mut(), LeaveAlternateScreen);
-
-    tui.terminal.set_viewport_area(old_viewport_area);
-}
 
 pub(crate) struct TranscriptApp {
     pub(crate) transcript_lines: Vec<Line<'static>>,
@@ -70,7 +24,32 @@ pub(crate) struct TranscriptApp {
 }
 
 impl TranscriptApp {
-    pub(crate) fn handle_key_event(&mut self, tui: &mut tui::Tui, key_event: KeyEvent) {
+    pub(crate) fn new(transcript_lines: Vec<Line<'static>>) -> Self {
+        Self {
+            transcript_lines,
+            scroll_offset: 0,
+            is_done: false,
+        }
+    }
+
+    pub(crate) fn handle_event(&mut self, tui: &mut tui::Tui, event: TuiEvent) -> Result<()> {
+        match event {
+            TuiEvent::Key(key_event) => self.handle_key_event(tui, key_event),
+            TuiEvent::Draw => {
+                tui.draw(u16::MAX, |frame| {
+                    self.render(frame.area(), frame.buffer);
+                })?;
+            }
+            _ => {}
+        }
+        Ok(())
+    }
+
+    pub(crate) fn insert_lines(&mut self, lines: Vec<Line<'static>>) {
+        self.transcript_lines.extend(lines);
+    }
+
+    fn handle_key_event(&mut self, tui: &mut tui::Tui, key_event: KeyEvent) {
         match key_event {
             KeyEvent {
                 code: KeyCode::Char('q'),
@@ -147,7 +126,7 @@ impl TranscriptApp {
         area
     }
 
-    pub(crate) fn render(&mut self, area: Rect, buf: &mut Buffer) {
+    fn render(&mut self, area: Rect, buf: &mut Buffer) {
         Span::from("/ ".repeat(area.width as usize / 2))
             .dim()
             .render_ref(area, buf);

codex-rs/tui/src/tui.rs

@@ -6,6 +6,7 @@ use std::time::Duration;
 use std::time::Instant;
 
 use crossterm::SynchronizedUpdate;
+use crossterm::cursor;
 use crossterm::cursor::MoveTo;
 use crossterm::event::DisableBracketedPaste;
 use crossterm::event::EnableBracketedPaste;
@@ -15,8 +16,7 @@ use crossterm::event::KeyEventKind;
 use crossterm::event::KeyboardEnhancementFlags;
 use crossterm::event::PopKeyboardEnhancementFlags;
 use crossterm::event::PushKeyboardEnhancementFlags;
-use crossterm::terminal::Clear;
-use crossterm::terminal::ClearType;
+use crossterm::terminal::ScrollUp;
 use ratatui::backend::Backend;
 use ratatui::backend::CrosstermBackend;
 use ratatui::crossterm::execute;
@@ -71,8 +71,14 @@ pub fn init() -> Result<Terminal> {
 
     set_panic_hook();
 
-    // Clear screen and move cursor to top-left before drawing UI
-    execute!(stdout(), Clear(ClearType::All), MoveTo(0, 0))?;
+    // Instead of clearing the screen (which can drop scrollback in some terminals),
+    // scroll existing lines up until the cursor reaches the top, then start at (0, 0).
+    if let Ok((_x, y)) = cursor::position()
+        && y > 0
+    {
+        execute!(stdout(), ScrollUp(y))?;
+    }
+    execute!(stdout(), MoveTo(0, 0))?;
 
     let backend = CrosstermBackend::new(stdout());
     let tui = CustomTerminal::with_options(backend)?;