feat(tui): add /title terminal title configuration (#12334)

## Problem

When multiple Codex sessions are open at once, terminal tabs and windows
are hard to distinguish from each other. The existing status line only
helps once the TUI is already focused, so it does not solve the "which
tab is this?" problem.

This PR adds a first-class `/title` command so the terminal window or
tab title can carry a short, configurable summary of the current
session.

## Screenshot

<img width="849" height="320" alt="image"
src="https://github.com/user-attachments/assets/8b112927-7890-45ed-bb1e-adf2f584663d"
/>

## Mental model

`/statusline` and `/title` are separate status surfaces with different
constraints. The status line is an in-app footer that can be denser and
more detailed. The terminal title is external terminal metadata, so it
needs short, stable segments that still make multiple sessions easy to
tell apart.

The `/title` configuration is an ordered list of compact items. By
default it renders `spinner,project`, so active sessions show
lightweight progress first while idle sessions still stay easy to
disambiguate. Each configured item is omitted when its value is not
currently available rather than forcing a placeholder.

## Non-goals

This does not merge `/title` into `/statusline`, and it does not add an
arbitrary free-form title string. The feature is intentionally limited
to a small set of structured items so the title stays short and
reviewable.

This also does not attempt to restore whatever title the terminal or
shell had before Codex started. When Codex clears the title, it clears
the title Codex last wrote.

## Tradeoffs

A separate `/title` command adds some conceptual overlap with
`/statusline`, but it keeps title-specific constraints explicit instead
of forcing the status line model to cover two different surfaces.

Title refresh can happen frequently, so the implementation now shares
parsing and git-branch orchestration between the status line and title
paths, and caches the derived project-root name by cwd. That keeps the
hot path cheap without introducing background polling.

## Architecture

The TUI gets a new `/title` slash command and a dedicated picker UI for
selecting and ordering terminal-title items. The chosen ids are
persisted in `tui.terminal_title`, with `spinner` and `project` as the
default when the config is unset. `status` remains available as a
separate text item, so configurations like `spinner,status` render
compact progress like `⠋ Working`.

`ChatWidget` now refreshes both status surfaces through a shared
`refresh_status_surfaces()` path. That shared path parses configured
items once, warns on invalid ids once, synchronizes shared cached state
such as git-branch lookup, then renders the footer status line and
terminal title from the same snapshot.

Low-level OSC title writes live in `codex-rs/tui/src/terminal_title.rs`,
which owns the terminal write path and last-mile sanitization before
emitting OSC 0.

## Security

Terminal-title text is treated as untrusted display content before Codex
emits it. The write path strips control characters, removes invisible
and bidi formatting characters that can make the title visually
misleading, normalizes whitespace, and caps the emitted length.

References used while implementing this:

- [xterm control
sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)
- [WezTerm escape sequences](https://wezterm.org/escape-sequences.html)
- [CWE-150: Improper Neutralization of Escape, Meta, or Control
Sequences](https://cwe.mitre.org/data/definitions/150.html)
- [CERT VU#999008 (Trojan Source)](https://kb.cert.org/vuls/id/999008)
- [Trojan Source disclosure site](https://trojansource.codes/)
- [Unicode Bidirectional Algorithm (UAX
#9)](https://www.unicode.org/reports/tr9/)
- [Unicode Security Considerations (UTR
#36)](https://www.unicode.org/reports/tr36/)

## Observability

Unknown configured title item ids are warned about once instead of
repeatedly spamming the transcript. Live preview applies immediately
while the `/title` picker is open, and cancel rolls the in-memory title
selection back to the pre-picker value.

If terminal title writes fail, the TUI emits debug logs around set and
clear attempts. The rendered status label intentionally collapses richer
internal states into compact title text such as `Starting...`, `Ready`,
`Thinking...`, `Working...`, `Waiting...`, and `Undoing...` when
`status` is configured.

## Tests

Ran:

- `just fmt`
- `cargo test -p codex-tui`

At the moment, the red Windows `rust-ci` failures are due to existing
`codex-core` `apply_patch_cli` stack-overflow tests that also reproduce
on `main`. The `/title`-specific `codex-tui` suite is green.

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

@@ -0,0 +1,660 @@
+//! Status-line and terminal-title rendering helpers for `ChatWidget`.
+//!
+//! Keeping this logic in a focused submodule makes the additive title/status
+//! behavior easier to review without paging through the rest of `chatwidget.rs`.
+
+use super::*;
+
+pub(super) const DEFAULT_TERMINAL_TITLE_ITEMS: [&str; 2] = ["spinner", "project"];
+pub(super) const TERMINAL_TITLE_SPINNER_FRAMES: [&str; 10] =
+    ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+pub(super) const TERMINAL_TITLE_SPINNER_INTERVAL: Duration = Duration::from_millis(100);
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+/// Compact runtime states that can be rendered into the terminal title.
+///
+/// This is intentionally smaller than the full status-header vocabulary. The
+/// title needs short, stable labels, so callers map richer lifecycle events
+/// onto one of these buckets before rendering.
+pub(super) enum TerminalTitleStatusKind {
+    Working,
+    WaitingForBackgroundTerminal,
+    Undoing,
+    #[default]
+    Thinking,
+}
+
+#[derive(Debug)]
+/// Parsed status-surface configuration for one refresh pass.
+///
+/// The status line and terminal title share some expensive or stateful inputs
+/// (notably git branch lookup and invalid-item warnings). This snapshot lets one
+/// refresh pass compute those shared concerns once, then render both surfaces
+/// from the same selection set.
+struct StatusSurfaceSelections {
+    status_line_items: Vec<StatusLineItem>,
+    invalid_status_line_items: Vec<String>,
+    terminal_title_items: Vec<TerminalTitleItem>,
+    invalid_terminal_title_items: Vec<String>,
+}
+
+impl StatusSurfaceSelections {
+    fn uses_git_branch(&self) -> bool {
+        self.status_line_items.contains(&StatusLineItem::GitBranch)
+            || self
+                .terminal_title_items
+                .contains(&TerminalTitleItem::GitBranch)
+    }
+}
+
+#[derive(Clone, Debug)]
+/// Cached project-root display name keyed by the cwd used for the last lookup.
+///
+/// Terminal-title refreshes can happen very frequently, so the title path avoids
+/// repeatedly walking up the filesystem to rediscover the same project root name
+/// while the working directory is unchanged.
+pub(super) struct CachedProjectRootName {
+    pub(super) cwd: PathBuf,
+    pub(super) root_name: Option<String>,
+}
+
+impl ChatWidget {
+    fn status_surface_selections(&self) -> StatusSurfaceSelections {
+        let (status_line_items, invalid_status_line_items) = self.status_line_items_with_invalids();
+        let (terminal_title_items, invalid_terminal_title_items) =
+            self.terminal_title_items_with_invalids();
+        StatusSurfaceSelections {
+            status_line_items,
+            invalid_status_line_items,
+            terminal_title_items,
+            invalid_terminal_title_items,
+        }
+    }
+
+    fn warn_invalid_status_line_items_once(&mut self, invalid_items: &[String]) {
+        if self.thread_id.is_some()
+            && !invalid_items.is_empty()
+            && self
+                .status_line_invalid_items_warned
+                .compare_exchange(false, true, Ordering::Relaxed, Ordering::Relaxed)
+                .is_ok()
+        {
+            let label = if invalid_items.len() == 1 {
+                "item"
+            } else {
+                "items"
+            };
+            let message = format!(
+                "Ignored invalid status line {label}: {}.",
+                proper_join(invalid_items)
+            );
+            self.on_warning(message);
+        }
+    }
+
+    fn warn_invalid_terminal_title_items_once(&mut self, invalid_items: &[String]) {
+        if self.thread_id.is_some()
+            && !invalid_items.is_empty()
+            && self
+                .terminal_title_invalid_items_warned
+                .compare_exchange(false, true, Ordering::Relaxed, Ordering::Relaxed)
+                .is_ok()
+        {
+            let label = if invalid_items.len() == 1 {
+                "item"
+            } else {
+                "items"
+            };
+            let message = format!(
+                "Ignored invalid terminal title {label}: {}.",
+                proper_join(invalid_items)
+            );
+            self.on_warning(message);
+        }
+    }
+
+    fn sync_status_surface_shared_state(&mut self, selections: &StatusSurfaceSelections) {
+        if !selections.uses_git_branch() {
+            self.status_line_branch = None;
+            self.status_line_branch_pending = false;
+            self.status_line_branch_lookup_complete = false;
+            return;
+        }
+
+        let cwd = self.status_line_cwd().to_path_buf();
+        self.sync_status_line_branch_state(&cwd);
+        if !self.status_line_branch_lookup_complete {
+            self.request_status_line_branch(cwd);
+        }
+    }
+
+    fn refresh_status_line_from_selections(&mut self, selections: &StatusSurfaceSelections) {
+        let enabled = !selections.status_line_items.is_empty();
+        self.bottom_pane.set_status_line_enabled(enabled);
+        if !enabled {
+            self.set_status_line(/*status_line*/ None);
+            return;
+        }
+
+        let mut parts = Vec::new();
+        for item in &selections.status_line_items {
+            if let Some(value) = self.status_line_value_for_item(item) {
+                parts.push(value);
+            }
+        }
+
+        let line = if parts.is_empty() {
+            None
+        } else {
+            Some(Line::from(parts.join(" · ")))
+        };
+        self.set_status_line(line);
+    }
+
+    /// Clears the terminal title Codex most recently wrote, if any.
+    ///
+    /// This does not attempt to restore the shell or terminal's previous title;
+    /// it only clears the managed title and updates the cache after a successful
+    /// OSC write.
+    pub(crate) fn clear_managed_terminal_title(&mut self) -> std::io::Result<()> {
+        if self.last_terminal_title.is_some() {
+            clear_terminal_title()?;
+            self.last_terminal_title = None;
+        }
+
+        Ok(())
+    }
+
+    /// Renders and applies the terminal title for one parsed selection snapshot.
+    ///
+    /// Empty selections clear the managed title. Non-empty selections render the
+    /// current values in configured order, skip unavailable segments, and cache
+    /// the last successfully written title so redundant OSC writes are avoided.
+    /// When the `spinner` item is present in an animated running state, this also
+    /// schedules the next frame so the spinner keeps advancing.
+    fn refresh_terminal_title_from_selections(&mut self, selections: &StatusSurfaceSelections) {
+        if selections.terminal_title_items.is_empty() {
+            if let Err(err) = self.clear_managed_terminal_title() {
+                tracing::debug!(error = %err, "failed to clear terminal title");
+            }
+            return;
+        }
+
+        let now = Instant::now();
+        let mut previous = None;
+        let title = selections
+            .terminal_title_items
+            .iter()
+            .copied()
+            .filter_map(|item| {
+                self.terminal_title_value_for_item(item, now)
+                    .map(|value| (item, value))
+            })
+            .fold(String::new(), |mut title, (item, value)| {
+                title.push_str(item.separator_from_previous(previous));
+                title.push_str(&value);
+                previous = Some(item);
+                title
+            });
+        let title = (!title.is_empty()).then_some(title);
+        let should_animate_spinner =
+            self.should_animate_terminal_title_spinner_with_selections(selections);
+        if self.last_terminal_title == title {
+            if should_animate_spinner {
+                self.frame_requester
+                    .schedule_frame_in(TERMINAL_TITLE_SPINNER_INTERVAL);
+            }
+            return;
+        }
+        match title {
+            Some(title) => match set_terminal_title(&title) {
+                Ok(SetTerminalTitleResult::Applied) => {
+                    self.last_terminal_title = Some(title);
+                }
+                Ok(SetTerminalTitleResult::NoVisibleContent) => {
+                    if let Err(err) = self.clear_managed_terminal_title() {
+                        tracing::debug!(error = %err, "failed to clear terminal title");
+                    }
+                }
+                Err(err) => {
+                    tracing::debug!(error = %err, "failed to set terminal title");
+                }
+            },
+            None => {
+                if let Err(err) = self.clear_managed_terminal_title() {
+                    tracing::debug!(error = %err, "failed to clear terminal title");
+                }
+            }
+        }
+
+        if should_animate_spinner {
+            self.frame_requester
+                .schedule_frame_in(TERMINAL_TITLE_SPINNER_INTERVAL);
+        }
+    }
+
+    /// Recomputes both status surfaces from one shared config snapshot.
+    ///
+    /// This is the common refresh entrypoint for the footer status line and the
+    /// terminal title. It parses both configurations once, emits invalid-item
+    /// warnings once, synchronizes shared cached state (such as git-branch
+    /// lookup), then renders each surface from that shared snapshot.
+    pub(crate) fn refresh_status_surfaces(&mut self) {
+        let selections = self.status_surface_selections();
+        self.warn_invalid_status_line_items_once(&selections.invalid_status_line_items);
+        self.warn_invalid_terminal_title_items_once(&selections.invalid_terminal_title_items);
+        self.sync_status_surface_shared_state(&selections);
+        self.refresh_status_line_from_selections(&selections);
+        self.refresh_terminal_title_from_selections(&selections);
+    }
+
+    /// Recomputes and emits the terminal title from config and runtime state.
+    pub(crate) fn refresh_terminal_title(&mut self) {
+        let selections = self.status_surface_selections();
+        self.warn_invalid_terminal_title_items_once(&selections.invalid_terminal_title_items);
+        self.sync_status_surface_shared_state(&selections);
+        self.refresh_terminal_title_from_selections(&selections);
+    }
+
+    pub(super) fn request_status_line_branch_refresh(&mut self) {
+        let selections = self.status_surface_selections();
+        if !selections.uses_git_branch() {
+            return;
+        }
+        let cwd = self.status_line_cwd().to_path_buf();
+        self.sync_status_line_branch_state(&cwd);
+        self.request_status_line_branch(cwd);
+    }
+
+    /// Parses configured status-line ids into known items and collects unknown ids.
+    ///
+    /// Unknown ids are deduplicated in insertion order for warning messages.
+    fn status_line_items_with_invalids(&self) -> (Vec<StatusLineItem>, Vec<String>) {
+        let mut invalid = Vec::new();
+        let mut invalid_seen = HashSet::new();
+        let mut items = Vec::new();
+        for id in self.configured_status_line_items() {
+            match id.parse::<StatusLineItem>() {
+                Ok(item) => items.push(item),
+                Err(_) => {
+                    if invalid_seen.insert(id.clone()) {
+                        invalid.push(format!(r#""{id}""#));
+                    }
+                }
+            }
+        }
+        (items, invalid)
+    }
+
+    pub(super) fn configured_status_line_items(&self) -> Vec<String> {
+        self.config.tui_status_line.clone().unwrap_or_else(|| {
+            DEFAULT_STATUS_LINE_ITEMS
+                .iter()
+                .map(ToString::to_string)
+                .collect()
+        })
+    }
+
+    /// Parses configured terminal-title ids into known items and collects unknown ids.
+    ///
+    /// Unknown ids are deduplicated in insertion order for warning messages.
+    fn terminal_title_items_with_invalids(&self) -> (Vec<TerminalTitleItem>, Vec<String>) {
+        let mut invalid = Vec::new();
+        let mut invalid_seen = HashSet::new();
+        let mut items = Vec::new();
+        for id in self.configured_terminal_title_items() {
+            match id.parse::<TerminalTitleItem>() {
+                Ok(item) => items.push(item),
+                Err(_) => {
+                    if invalid_seen.insert(id.clone()) {
+                        invalid.push(format!(r#""{id}""#));
+                    }
+                }
+            }
+        }
+        (items, invalid)
+    }
+
+    /// Returns the configured terminal-title ids, or the default ordering when unset.
+    pub(super) fn configured_terminal_title_items(&self) -> Vec<String> {
+        self.config.tui_terminal_title.clone().unwrap_or_else(|| {
+            DEFAULT_TERMINAL_TITLE_ITEMS
+                .iter()
+                .map(ToString::to_string)
+                .collect()
+        })
+    }
+
+    fn status_line_cwd(&self) -> &Path {
+        self.current_cwd.as_ref().unwrap_or(&self.config.cwd)
+    }
+
+    /// Resolves the project root associated with `cwd`.
+    ///
+    /// Git repository root wins when available. Otherwise we fall back to the
+    /// nearest project config layer so non-git projects can still surface a
+    /// stable project label.
+    fn status_line_project_root_for_cwd(&self, cwd: &Path) -> Option<PathBuf> {
+        if let Some(repo_root) = get_git_repo_root(cwd) {
+            return Some(repo_root);
+        }
+
+        self.config
+            .config_layer_stack
+            .get_layers(
+                ConfigLayerStackOrdering::LowestPrecedenceFirst,
+                /*include_disabled*/ true,
+            )
+            .iter()
+            .find_map(|layer| match &layer.name {
+                ConfigLayerSource::Project { dot_codex_folder } => {
+                    dot_codex_folder.as_path().parent().map(Path::to_path_buf)
+                }
+                _ => None,
+            })
+    }
+
+    fn status_line_project_root_name_for_cwd(&self, cwd: &Path) -> Option<String> {
+        self.status_line_project_root_for_cwd(cwd).map(|root| {
+            root.file_name()
+                .map(|name| name.to_string_lossy().to_string())
+                .unwrap_or_else(|| format_directory_display(&root, /*max_width*/ None))
+        })
+    }
+
+    /// Returns a cached project-root display name for the active cwd.
+    fn status_line_project_root_name(&mut self) -> Option<String> {
+        let cwd = self.status_line_cwd().to_path_buf();
+        if let Some(cache) = &self.status_line_project_root_name_cache
+            && cache.cwd == cwd
+        {
+            return cache.root_name.clone();
+        }
+
+        let root_name = self.status_line_project_root_name_for_cwd(&cwd);
+        self.status_line_project_root_name_cache = Some(CachedProjectRootName {
+            cwd,
+            root_name: root_name.clone(),
+        });
+        root_name
+    }
+
+    /// Produces the terminal-title `project` value.
+    ///
+    /// This prefers the cached project-root name and falls back to the current
+    /// directory name when no project root can be inferred.
+    fn terminal_title_project_name(&mut self) -> Option<String> {
+        let project = self.status_line_project_root_name().or_else(|| {
+            let cwd = self.status_line_cwd();
+            Some(
+                cwd.file_name()
+                    .map(|name| name.to_string_lossy().to_string())
+                    .unwrap_or_else(|| format_directory_display(cwd, /*max_width*/ None)),
+            )
+        })?;
+        Some(Self::truncate_terminal_title_part(
+            project, /*max_chars*/ 24,
+        ))
+    }
+
+    /// Resets git-branch cache state when the status-line cwd changes.
+    ///
+    /// The branch cache is keyed by cwd because branch lookup is performed relative to that path.
+    /// Keeping stale branch values across cwd changes would surface incorrect repository context.
+    fn sync_status_line_branch_state(&mut self, cwd: &Path) {
+        if self
+            .status_line_branch_cwd
+            .as_ref()
+            .is_some_and(|path| path == cwd)
+        {
+            return;
+        }
+        self.status_line_branch_cwd = Some(cwd.to_path_buf());
+        self.status_line_branch = None;
+        self.status_line_branch_pending = false;
+        self.status_line_branch_lookup_complete = false;
+    }
+
+    /// Starts an async git-branch lookup unless one is already running.
+    ///
+    /// The resulting `StatusLineBranchUpdated` event carries the lookup cwd so callers can reject
+    /// stale completions after directory changes.
+    fn request_status_line_branch(&mut self, cwd: PathBuf) {
+        if self.status_line_branch_pending {
+            return;
+        }
+        self.status_line_branch_pending = true;
+        let tx = self.app_event_tx.clone();
+        tokio::spawn(async move {
+            let branch = current_branch_name(&cwd).await;
+            tx.send(AppEvent::StatusLineBranchUpdated { cwd, branch });
+        });
+    }
+
+    /// Resolves a display string for one configured status-line item.
+    ///
+    /// Returning `None` means "omit this item for now", not "configuration error". Callers rely on
+    /// this to keep partially available status lines readable while waiting for session, token, or
+    /// git metadata.
+    pub(super) fn status_line_value_for_item(&mut self, item: &StatusLineItem) -> Option<String> {
+        match item {
+            StatusLineItem::ModelName => Some(self.model_display_name().to_string()),
+            StatusLineItem::ModelWithReasoning => {
+                let label =
+                    Self::status_line_reasoning_effort_label(self.effective_reasoning_effort());
+                let fast_label = if self
+                    .should_show_fast_status(self.current_model(), self.config.service_tier)
+                {
+                    " fast"
+                } else {
+                    ""
+                };
+                Some(format!("{} {label}{fast_label}", self.model_display_name()))
+            }
+            StatusLineItem::CurrentDir => {
+                Some(format_directory_display(
+                    self.status_line_cwd(),
+                    /*max_width*/ None,
+                ))
+            }
+            StatusLineItem::ProjectRoot => self.status_line_project_root_name(),
+            StatusLineItem::GitBranch => self.status_line_branch.clone(),
+            StatusLineItem::UsedTokens => {
+                let usage = self.status_line_total_usage();
+                let total = usage.tokens_in_context_window();
+                if total <= 0 {
+                    None
+                } else {
+                    Some(format!("{} used", format_tokens_compact(total)))
+                }
+            }
+            StatusLineItem::ContextRemaining => self
+                .status_line_context_remaining_percent()
+                .map(|remaining| format!("{remaining}% left")),
+            StatusLineItem::ContextUsed => self
+                .status_line_context_used_percent()
+                .map(|used| format!("{used}% used")),
+            StatusLineItem::FiveHourLimit => {
+                let window = self
+                    .rate_limit_snapshots_by_limit_id
+                    .get("codex")
+                    .and_then(|s| s.primary.as_ref());
+                let label = window
+                    .and_then(|window| window.window_minutes)
+                    .map(get_limits_duration)
+                    .unwrap_or_else(|| "5h".to_string());
+                self.status_line_limit_display(window, &label)
+            }
+            StatusLineItem::WeeklyLimit => {
+                let window = self
+                    .rate_limit_snapshots_by_limit_id
+                    .get("codex")
+                    .and_then(|s| s.secondary.as_ref());
+                let label = window
+                    .and_then(|window| window.window_minutes)
+                    .map(get_limits_duration)
+                    .unwrap_or_else(|| "weekly".to_string());
+                self.status_line_limit_display(window, &label)
+            }
+            StatusLineItem::CodexVersion => Some(CODEX_CLI_VERSION.to_string()),
+            StatusLineItem::ContextWindowSize => self
+                .status_line_context_window_size()
+                .map(|cws| format!("{} window", format_tokens_compact(cws))),
+            StatusLineItem::TotalInputTokens => Some(format!(
+                "{} in",
+                format_tokens_compact(self.status_line_total_usage().input_tokens)
+            )),
+            StatusLineItem::TotalOutputTokens => Some(format!(
+                "{} out",
+                format_tokens_compact(self.status_line_total_usage().output_tokens)
+            )),
+            StatusLineItem::SessionId => self.thread_id.map(|id| id.to_string()),
+            StatusLineItem::FastMode => Some(
+                if matches!(self.config.service_tier, Some(ServiceTier::Fast)) {
+                    "Fast on".to_string()
+                } else {
+                    "Fast off".to_string()
+                },
+            ),
+        }
+    }
+
+    /// Resolves one configured terminal-title item into a displayable segment.
+    ///
+    /// Returning `None` means "omit this segment for now" so callers can keep
+    /// the configured order while hiding values that are not yet available.
+    fn terminal_title_value_for_item(
+        &mut self,
+        item: TerminalTitleItem,
+        now: Instant,
+    ) -> Option<String> {
+        match item {
+            TerminalTitleItem::AppName => Some("codex".to_string()),
+            TerminalTitleItem::Project => self.terminal_title_project_name(),
+            TerminalTitleItem::Spinner => self.terminal_title_spinner_text_at(now),
+            TerminalTitleItem::Status => Some(self.terminal_title_status_text()),
+            TerminalTitleItem::Thread => self.thread_name.as_ref().and_then(|name| {
+                let trimmed = name.trim();
+                if trimmed.is_empty() {
+                    None
+                } else {
+                    Some(Self::truncate_terminal_title_part(
+                        trimmed.to_string(),
+                        /*max_chars*/ 48,
+                    ))
+                }
+            }),
+            TerminalTitleItem::GitBranch => self.status_line_branch.as_ref().map(|branch| {
+                Self::truncate_terminal_title_part(branch.clone(), /*max_chars*/ 32)
+            }),
+            TerminalTitleItem::Model => Some(Self::truncate_terminal_title_part(
+                self.model_display_name().to_string(),
+                /*max_chars*/ 32,
+            )),
+            TerminalTitleItem::TaskProgress => self.terminal_title_task_progress(),
+        }
+    }
+
+    /// Computes the compact runtime status label used by the terminal title.
+    ///
+    /// Startup takes precedence over normal task states, and idle state renders
+    /// as `Ready` regardless of the last active status bucket.
+    pub(super) fn terminal_title_status_text(&self) -> String {
+        if self.mcp_startup_status.is_some() {
+            return "Starting".to_string();
+        }
+
+        match self.terminal_title_status_kind {
+            TerminalTitleStatusKind::Working if !self.bottom_pane.is_task_running() => {
+                "Ready".to_string()
+            }
+            TerminalTitleStatusKind::WaitingForBackgroundTerminal
+                if !self.bottom_pane.is_task_running() =>
+            {
+                "Ready".to_string()
+            }
+            TerminalTitleStatusKind::Thinking if !self.bottom_pane.is_task_running() => {
+                "Ready".to_string()
+            }
+            TerminalTitleStatusKind::Working => "Working".to_string(),
+            TerminalTitleStatusKind::WaitingForBackgroundTerminal => "Waiting".to_string(),
+            TerminalTitleStatusKind::Undoing => "Undoing".to_string(),
+            TerminalTitleStatusKind::Thinking => "Thinking".to_string(),
+        }
+    }
+
+    pub(super) fn terminal_title_spinner_text_at(&self, now: Instant) -> Option<String> {
+        if !self.config.animations {
+            return None;
+        }
+
+        if !self.terminal_title_has_active_progress() {
+            return None;
+        }
+
+        Some(self.terminal_title_spinner_frame_at(now).to_string())
+    }
+
+    fn terminal_title_spinner_frame_at(&self, now: Instant) -> &'static str {
+        let elapsed = now.saturating_duration_since(self.terminal_title_animation_origin);
+        let frame_index =
+            (elapsed.as_millis() / TERMINAL_TITLE_SPINNER_INTERVAL.as_millis()) as usize;
+        TERMINAL_TITLE_SPINNER_FRAMES[frame_index % TERMINAL_TITLE_SPINNER_FRAMES.len()]
+    }
+
+    fn terminal_title_uses_spinner(&self) -> bool {
+        self.config
+            .tui_terminal_title
+            .as_ref()
+            .is_none_or(|items| items.iter().any(|item| item == "spinner"))
+    }
+
+    fn terminal_title_has_active_progress(&self) -> bool {
+        self.mcp_startup_status.is_some()
+            || self.bottom_pane.is_task_running()
+            || self.terminal_title_status_kind == TerminalTitleStatusKind::Undoing
+    }
+
+    pub(super) fn should_animate_terminal_title_spinner(&self) -> bool {
+        self.config.animations
+            && self.terminal_title_uses_spinner()
+            && self.terminal_title_has_active_progress()
+    }
+
+    fn should_animate_terminal_title_spinner_with_selections(
+        &self,
+        selections: &StatusSurfaceSelections,
+    ) -> bool {
+        self.config.animations
+            && selections
+                .terminal_title_items
+                .contains(&TerminalTitleItem::Spinner)
+            && self.terminal_title_has_active_progress()
+    }
+
+    /// Formats the last `update_plan` progress snapshot for terminal-title display.
+    pub(super) fn terminal_title_task_progress(&self) -> Option<String> {
+        let (completed, total) = self.last_plan_progress?;
+        if total == 0 {
+            return None;
+        }
+        Some(format!("Tasks {completed}/{total}"))
+    }
+
+    /// Truncates a title segment by grapheme cluster and appends `...` when needed.
+    pub(super) fn truncate_terminal_title_part(value: String, max_chars: usize) -> String {
+        if max_chars == 0 {
+            return String::new();
+        }
+
+        let mut graphemes = value.graphemes(true);
+        let head: String = graphemes.by_ref().take(max_chars).collect();
+        if graphemes.next().is_none() || max_chars <= 3 {
+            return head;
+        }
+
+        let mut truncated = head.graphemes(true).take(max_chars - 3).collect::<String>();
+        truncated.push_str("...");
+        truncated
+    }
+}

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

@@ -1777,6 +1777,7 @@ async fn helpers_are_available_and_do_not_panic() {
         model: Some(resolved_model),
         startup_tooltip_override: None,
         status_line_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        terminal_title_invalid_items_warned: Arc::new(AtomicBool::new(false)),
         session_telemetry,
     };
     let mut w = ChatWidget::new(init, thread_manager);
@@ -1896,6 +1897,7 @@ async fn make_chatwidget_manual(
         reasoning_buffer: String::new(),
         full_reasoning_buffer: String::new(),
         current_status: StatusIndicatorState::working(),
+        terminal_title_status_kind: TerminalTitleStatusKind::Working,
         retry_status_header: None,
         pending_status_indicator_restore: false,
         suppress_queue_autosend: false,
@@ -1919,6 +1921,7 @@ async fn make_chatwidget_manual(
         had_work_activity: false,
         saw_plan_update_this_turn: false,
         saw_plan_item_this_turn: false,
+        last_plan_progress: None,
         plan_delta_buffer: String::new(),
         plan_item_active: false,
         last_separator_elapsed_secs: None,
@@ -1930,6 +1933,11 @@ async fn make_chatwidget_manual(
         current_cwd: None,
         session_network_proxy: None,
         status_line_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        terminal_title_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        last_terminal_title: None,
+        terminal_title_setup_original_items: None,
+        terminal_title_animation_origin: Instant::now(),
+        status_line_project_root_name_cache: None,
         status_line_branch: None,
         status_line_branch_cwd: None,
         status_line_branch_pending: false,
@@ -5716,6 +5724,7 @@ async fn collaboration_modes_defaults_to_code_on_startup() {
         model: Some(resolved_model.clone()),
         startup_tooltip_override: None,
         status_line_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        terminal_title_invalid_items_warned: Arc::new(AtomicBool::new(false)),
         session_telemetry,
     };
 
@@ -5766,6 +5775,7 @@ async fn experimental_mode_plan_is_ignored_on_startup() {
         model: Some(resolved_model.clone()),
         startup_tooltip_override: None,
         status_line_invalid_items_warned: Arc::new(AtomicBool::new(false)),
+        terminal_title_invalid_items_warned: Arc::new(AtomicBool::new(false)),
         session_telemetry,
     };
 
@@ -6322,6 +6332,50 @@ async fn undo_started_hides_interrupt_hint() {
     );
 }
 
+#[tokio::test]
+async fn undo_completed_clears_terminal_title_undo_state() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = true;
+    chat.config.tui_terminal_title = Some(vec!["spinner".to_string(), "status".to_string()]);
+    chat.terminal_title_animation_origin = Instant::now() + Duration::from_secs(1);
+
+    chat.handle_codex_event(Event {
+        id: "turn-undo".to_string(),
+        msg: EventMsg::UndoStarted(UndoStartedEvent { message: None }),
+    });
+
+    assert_eq!(chat.last_terminal_title, Some("⠋ Undoing".to_string()));
+
+    chat.handle_codex_event(Event {
+        id: "turn-undo".to_string(),
+        msg: EventMsg::UndoCompleted(UndoCompletedEvent {
+            success: true,
+            message: None,
+        }),
+    });
+
+    assert_eq!(chat.last_terminal_title, Some("Ready".to_string()));
+}
+
+#[tokio::test]
+async fn undo_started_refreshes_default_spinner_project_title() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = true;
+    chat.refresh_terminal_title();
+    let project = chat
+        .last_terminal_title
+        .clone()
+        .expect("default title should include a project name");
+    chat.terminal_title_animation_origin = Instant::now() + Duration::from_secs(1);
+
+    chat.handle_codex_event(Event {
+        id: "turn-undo".to_string(),
+        msg: EventMsg::UndoStarted(UndoStartedEvent { message: None }),
+    });
+
+    assert_eq!(chat.last_terminal_title, Some(format!("⠋ {project}")));
+}
+
 /// The commit picker shows only commit subjects (no timestamps).
 #[tokio::test]
 async fn review_commit_picker_shows_subjects_without_timestamps() {
@@ -10505,16 +10559,20 @@ async fn status_line_invalid_items_warn_once() {
     ]);
     chat.thread_id = Some(ThreadId::new());
 
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
     let cells = drain_insert_history(&mut rx);
     assert_eq!(cells.len(), 1, "expected one warning history cell");
     let rendered = lines_to_single_string(&cells[0]);
     assert!(
-        rendered.contains("bogus_item"),
+        rendered.contains(r#""bogus_item""#),
         "warning cell missing invalid item content: {rendered}"
     );
+    assert!(
+        !rendered.contains(r#"\"bogus_item\""#),
+        "warning cell should render plain quotes, not escaped quotes: {rendered}"
+    );
 
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
     let cells = drain_insert_history(&mut rx);
     assert!(
         cells.is_empty(),
@@ -10522,6 +10580,257 @@ async fn status_line_invalid_items_warn_once() {
     );
 }
 
+#[tokio::test]
+async fn terminal_title_invalid_items_warn_once() {
+    let (mut chat, mut rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.tui_terminal_title = Some(vec![
+        "status".to_string(),
+        "bogus_item".to_string(),
+        "bogus_item".to_string(),
+    ]);
+    chat.thread_id = Some(ThreadId::new());
+
+    chat.refresh_status_surfaces();
+    let cells = drain_insert_history(&mut rx);
+    assert_eq!(cells.len(), 1, "expected one warning history cell");
+    let rendered = lines_to_single_string(&cells[0]);
+    assert!(
+        rendered.contains(r#""bogus_item""#),
+        "warning cell missing invalid item content: {rendered}"
+    );
+    assert!(
+        !rendered.contains(r#"\"bogus_item\""#),
+        "warning cell should render plain quotes, not escaped quotes: {rendered}"
+    );
+
+    chat.refresh_status_surfaces();
+    let cells = drain_insert_history(&mut rx);
+    assert!(
+        cells.is_empty(),
+        "expected invalid terminal title warning to emit only once"
+    );
+}
+
+#[tokio::test]
+async fn terminal_title_setup_cancel_reverts_live_preview() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    let original = chat.config.tui_terminal_title.clone();
+
+    chat.open_terminal_title_setup();
+    chat.preview_terminal_title(vec![TerminalTitleItem::Thread, TerminalTitleItem::Status]);
+
+    assert_eq!(
+        chat.config.tui_terminal_title,
+        Some(vec!["thread".to_string(), "status".to_string()])
+    );
+    assert_eq!(
+        chat.terminal_title_setup_original_items,
+        Some(original.clone())
+    );
+
+    chat.cancel_terminal_title_setup();
+
+    assert_eq!(chat.config.tui_terminal_title, original);
+    assert_eq!(chat.terminal_title_setup_original_items, None);
+}
+
+#[tokio::test]
+async fn terminal_title_status_uses_waiting_label_for_background_terminal_when_animations_disabled()
+{
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = false;
+    chat.on_task_started();
+    terminal_interaction(&mut chat, "call-1", "proc-1", "");
+
+    assert_eq!(chat.terminal_title_status_text(), "Waiting");
+}
+
+#[tokio::test]
+async fn terminal_title_status_uses_plain_labels_for_transient_states_when_animations_disabled() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = false;
+
+    chat.mcp_startup_status = Some(std::collections::HashMap::new());
+    assert_eq!(chat.terminal_title_status_text(), "Starting");
+
+    chat.mcp_startup_status = None;
+    chat.on_task_started();
+    assert_eq!(chat.terminal_title_status_text(), "Working");
+
+    chat.handle_codex_event(Event {
+        id: "undo-1".to_string(),
+        msg: EventMsg::UndoStarted(UndoStartedEvent {
+            message: Some("Undoing changes".to_string()),
+        }),
+    });
+    assert_eq!(chat.terminal_title_status_text(), "Undoing");
+
+    chat.on_agent_reasoning_delta("**Planning**\nmore".to_string());
+    assert_eq!(chat.terminal_title_status_text(), "Thinking");
+}
+
+#[tokio::test]
+async fn default_terminal_title_items_are_spinner_then_project() {
+    let (chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+
+    assert_eq!(
+        chat.configured_terminal_title_items(),
+        vec!["spinner".to_string(), "project".to_string()]
+    );
+}
+
+#[tokio::test]
+async fn terminal_title_can_render_app_name_item() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.tui_terminal_title = Some(vec!["app-name".to_string()]);
+
+    chat.refresh_terminal_title();
+
+    assert_eq!(chat.last_terminal_title, Some("codex".to_string()));
+}
+
+#[tokio::test]
+async fn default_terminal_title_refreshes_when_spinner_state_changes() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = true;
+
+    chat.config.tui_terminal_title = None;
+    let cwd = chat
+        .current_cwd
+        .clone()
+        .unwrap_or_else(|| chat.config.cwd.clone());
+    let project = get_git_repo_root(&cwd)
+        .map(|root| {
+            root.file_name()
+                .map(|name| name.to_string_lossy().to_string())
+                .unwrap_or_else(|| format_directory_display(&root, None))
+        })
+        .or_else(|| {
+            chat.config
+                .config_layer_stack
+                .get_layers(ConfigLayerStackOrdering::LowestPrecedenceFirst, true)
+                .iter()
+                .find_map(|layer| match &layer.name {
+                    ConfigLayerSource::Project { dot_codex_folder } => {
+                        dot_codex_folder.as_path().parent().map(|path| {
+                            path.file_name()
+                                .map(|name| name.to_string_lossy().to_string())
+                                .unwrap_or_else(|| format_directory_display(path, None))
+                        })
+                    }
+                    _ => None,
+                })
+        })
+        .unwrap_or_else(|| {
+            cwd.file_name()
+                .map(|name| name.to_string_lossy().to_string())
+                .unwrap_or_else(|| format_directory_display(&cwd, None))
+        });
+    chat.last_terminal_title = Some(project.clone());
+    chat.bottom_pane.set_task_running(true);
+    chat.terminal_title_status_kind = TerminalTitleStatusKind::Thinking;
+    chat.terminal_title_animation_origin = Instant::now() + Duration::from_secs(1);
+
+    chat.refresh_terminal_title();
+
+    assert_eq!(chat.last_terminal_title, Some(format!("⠋ {project}")));
+}
+
+#[tokio::test]
+async fn terminal_title_spinner_item_renders_when_animations_enabled() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.bottom_pane.set_task_running(true);
+    chat.terminal_title_status_kind = TerminalTitleStatusKind::Working;
+    chat.terminal_title_animation_origin = Instant::now();
+
+    assert_eq!(
+        chat.terminal_title_spinner_text_at(chat.terminal_title_animation_origin),
+        Some("⠋".to_string())
+    );
+    assert_eq!(
+        chat.terminal_title_spinner_text_at(
+            chat.terminal_title_animation_origin + TERMINAL_TITLE_SPINNER_INTERVAL,
+        ),
+        Some("⠙".to_string())
+    );
+}
+
+#[tokio::test]
+async fn terminal_title_uses_spaces_around_spinner_item() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = true;
+    chat.config.tui_terminal_title = Some(vec![
+        "project".to_string(),
+        "spinner".to_string(),
+        "status".to_string(),
+        "thread".to_string(),
+    ]);
+    chat.thread_name = Some("Investigate flaky test".to_string());
+    chat.bottom_pane.set_task_running(true);
+    chat.terminal_title_status_kind = TerminalTitleStatusKind::Working;
+    chat.terminal_title_animation_origin = Instant::now() + Duration::from_secs(1);
+
+    chat.refresh_terminal_title();
+
+    let title = chat
+        .last_terminal_title
+        .clone()
+        .expect("expected terminal title");
+    assert!(title.contains(" ⠋ Working | "));
+    assert!(!title.contains("| ⠋"));
+    assert!(!title.contains("⠋ |"));
+}
+
+#[tokio::test]
+async fn terminal_title_shows_spinner_and_undoing_without_task_running() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.animations = true;
+    chat.config.tui_terminal_title = Some(vec!["spinner".to_string(), "status".to_string()]);
+    chat.terminal_title_status_kind = TerminalTitleStatusKind::Undoing;
+    chat.terminal_title_animation_origin = Instant::now() + Duration::from_secs(1);
+
+    assert!(!chat.bottom_pane.is_task_running());
+
+    chat.refresh_terminal_title();
+
+    assert_eq!(chat.last_terminal_title, Some("⠋ Undoing".to_string()));
+}
+
+#[tokio::test]
+async fn terminal_title_reschedules_spinner_when_title_text_is_unchanged() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    let (frame_requester, mut frame_schedule_rx) = FrameRequester::test_observable();
+    chat.frame_requester = frame_requester;
+    chat.config.animations = true;
+    chat.config.tui_terminal_title = Some(vec!["spinner".to_string()]);
+    chat.bottom_pane.set_task_running(true);
+    chat.terminal_title_status_kind = TerminalTitleStatusKind::Working;
+    chat.terminal_title_animation_origin = Instant::now() + Duration::from_secs(1);
+    chat.last_terminal_title = Some("⠋".to_string());
+
+    chat.refresh_terminal_title();
+
+    assert!(frame_schedule_rx.try_recv().is_ok());
+}
+
+#[tokio::test]
+async fn on_task_started_resets_terminal_title_task_progress() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.last_plan_progress = Some((2, 5));
+
+    chat.on_task_started();
+
+    assert_eq!(chat.last_plan_progress, None);
+    assert_eq!(chat.terminal_title_task_progress(), None);
+}
+
+#[test]
+fn terminal_title_part_truncation_preserves_grapheme_clusters() {
+    let value = "ab👩‍💻cdefg".to_string();
+    let truncated = ChatWidget::truncate_terminal_title_part(value, 7);
+    assert_eq!(truncated, "ab👩‍💻c...");
+}
+
 #[tokio::test]
 async fn status_line_branch_state_resets_when_git_branch_disabled() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
@@ -10530,7 +10839,7 @@ async fn status_line_branch_state_resets_when_git_branch_disabled() {
     chat.status_line_branch_lookup_complete = true;
     chat.config.tui_status_line = Some(vec!["model_name".to_string()]);
 
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
 
     assert_eq!(chat.status_line_branch, None);
     assert!(!chat.status_line_branch_pending);
@@ -10555,6 +10864,25 @@ async fn status_line_branch_refreshes_after_turn_complete() {
     assert!(chat.status_line_branch_pending);
 }
 
+#[tokio::test]
+async fn status_line_branch_refreshes_after_turn_complete_when_terminal_title_uses_git_branch() {
+    let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
+    chat.config.tui_status_line = Some(Vec::new());
+    chat.config.tui_terminal_title = Some(vec!["git-branch".to_string()]);
+    chat.status_line_branch_lookup_complete = true;
+    chat.status_line_branch_pending = false;
+
+    chat.handle_codex_event(Event {
+        id: "turn-1".into(),
+        msg: EventMsg::TurnComplete(TurnCompleteEvent {
+            turn_id: "turn-1".to_string(),
+            last_agent_message: None,
+        }),
+    });
+
+    assert!(chat.status_line_branch_pending);
+}
+
 #[tokio::test]
 async fn status_line_branch_refreshes_after_interrupt() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
@@ -10578,11 +10906,11 @@ async fn status_line_fast_mode_renders_on_and_off() {
     let (mut chat, _rx, _op_rx) = make_chatwidget_manual(None).await;
     chat.config.tui_status_line = Some(vec!["fast-mode".to_string()]);
 
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
     assert_eq!(status_line_text(&chat), Some("Fast off".to_string()));
 
     chat.set_service_tier(Some(ServiceTier::Fast));
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
     assert_eq!(status_line_text(&chat), Some("Fast on".to_string()));
 }
 
@@ -10595,7 +10923,7 @@ async fn status_line_fast_mode_footer_snapshot() {
     chat.show_welcome_banner = false;
     chat.config.tui_status_line = Some(vec!["fast-mode".to_string()]);
     chat.set_service_tier(Some(ServiceTier::Fast));
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
 
     let width = 80;
     let height = chat.desired_height(width);
@@ -10618,7 +10946,7 @@ async fn status_line_model_with_reasoning_includes_fast_for_gpt54_only() {
     chat.set_reasoning_effort(Some(ReasoningEffortConfig::XHigh));
     chat.set_service_tier(Some(ServiceTier::Fast));
     set_chatgpt_auth(&mut chat);
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
 
     assert_eq!(
         status_line_text(&chat),
@@ -10626,7 +10954,7 @@ async fn status_line_model_with_reasoning_includes_fast_for_gpt54_only() {
     );
 
     chat.set_model("gpt-5.3-codex");
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
 
     assert_eq!(
         status_line_text(&chat),
@@ -10650,7 +10978,7 @@ async fn status_line_model_with_reasoning_fast_footer_snapshot() {
     chat.set_reasoning_effort(Some(ReasoningEffortConfig::XHigh));
     chat.set_service_tier(Some(ServiceTier::Fast));
     set_chatgpt_auth(&mut chat);
-    chat.refresh_status_line();
+    chat.refresh_status_surfaces();
 
     let width = 80;
     let height = chat.desired_height(width);