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.
2026-04-30 19:32:04 +03:00 · 2026-03-19 19:26:36 +00:00
parent fe287ac467
commit 60cd0cf75e
17 changed files with 1867 additions and 294 deletions
--- a/codex-rs/tui/src/terminal_title.rs
+++ b/codex-rs/tui/src/terminal_title.rs
@@ -0,0 +1,205 @@
+//! Terminal-title output helpers for the TUI.
+//!
+//! This module owns the low-level OSC title write path and the sanitization
+//! that happens immediately before we emit it. It is intentionally narrow:
+//! callers decide when the title should change and whether an empty title means
+//! "leave the old title alone" or "clear the title Codex last wrote".
+//! This module does not attempt to read or restore the terminal's previous
+//! title because that is not portable across terminals.
+//!
+//! Sanitization is necessary because title content is assembled from untrusted
+//! text sources such as model output, thread names, project paths, and config.
+//! Before we place that text inside an OSC sequence, we strip:
+//! - control characters that could terminate or reshape the escape sequence
+//! - bidi/invisible formatting codepoints that can visually reorder or hide
+//!   text (the same family of issues discussed in Trojan Source writeups)
+//! - redundant whitespace that would make titles noisy or hard to scan
+
+use std::fmt;
+use std::io;
+use std::io::IsTerminal;
+use std::io::stdout;
+
+use crossterm::Command;
+use ratatui::crossterm::execute;
+
+const MAX_TERMINAL_TITLE_CHARS: usize = 240;
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub(crate) enum SetTerminalTitleResult {
+    /// A sanitized title was written, or stdout is not a terminal so no write was needed.
+    Applied,
+    /// Sanitization removed every visible character, so no title was emitted.
+    ///
+    /// This is distinct from clearing the title. Callers decide whether an
+    /// empty post-sanitization value should result in no-op behavior, clearing
+    /// the title Codex manages, or some other fallback.
+    NoVisibleContent,
+}
+
+/// Writes a sanitized OSC window-title sequence to stdout.
+///
+/// The input is treated as untrusted display text: control characters,
+/// invisible formatting characters, and redundant whitespace are removed before
+/// the title is emitted. If sanitization removes all visible content, the
+/// function returns [`SetTerminalTitleResult::NoVisibleContent`] instead of
+/// clearing the title because clearing and restoring are policy decisions for
+/// higher-level callers. Mechanically, sanitization collapses whitespace runs
+/// to single spaces, drops disallowed codepoints, and bounds the result to
+/// [`MAX_TERMINAL_TITLE_CHARS`] visible characters before writing OSC 0.
+pub(crate) fn set_terminal_title(title: &str) -> io::Result<SetTerminalTitleResult> {
+    if !stdout().is_terminal() {
+        return Ok(SetTerminalTitleResult::Applied);
+    }
+
+    let title = sanitize_terminal_title(title);
+    if title.is_empty() {
+        return Ok(SetTerminalTitleResult::NoVisibleContent);
+    }
+
+    execute!(stdout(), SetWindowTitle(title))?;
+    Ok(SetTerminalTitleResult::Applied)
+}
+
+/// Clears the current terminal title by writing an empty OSC title payload.
+///
+/// This clears the visible title; it does not restore whatever title the shell
+/// or a previous program may have set before Codex started managing the title.
+pub(crate) fn clear_terminal_title() -> io::Result<()> {
+    if !stdout().is_terminal() {
+        return Ok(());
+    }
+
+    execute!(stdout(), SetWindowTitle(String::new()))
+}
+
+#[derive(Debug, Clone)]
+struct SetWindowTitle(String);
+
+impl Command for SetWindowTitle {
+    fn write_ansi(&self, f: &mut impl fmt::Write) -> fmt::Result {
+        // xterm/ctlseqs documents OSC 0/2 title sequences with ST (ESC \) termination.
+        // Most terminals also accept BEL for compatibility, but ST is the canonical form.
+        write!(f, "\x1b]0;{}\x1b\\", self.0)
+    }
+
+    #[cfg(windows)]
+    fn execute_winapi(&self) -> io::Result<()> {
+        Err(std::io::Error::other(
+            "tried to execute SetWindowTitle using WinAPI; use ANSI instead",
+        ))
+    }
+
+    #[cfg(windows)]
+    fn is_ansi_code_supported(&self) -> bool {
+        true
+    }
+}
+
+/// Normalizes untrusted title text into a single bounded display line.
+///
+/// This removes terminal control characters, strips invisible/bidi formatting
+/// characters, collapses any whitespace run into a single ASCII space, and
+/// truncates after [`MAX_TERMINAL_TITLE_CHARS`] emitted characters.
+fn sanitize_terminal_title(title: &str) -> String {
+    let mut sanitized = String::new();
+    let mut chars_written = 0;
+    let mut pending_space = false;
+
+    for ch in title.chars() {
+        if ch.is_whitespace() {
+            pending_space = !sanitized.is_empty();
+            continue;
+        }
+
+        if is_disallowed_terminal_title_char(ch) {
+            continue;
+        }
+
+        if pending_space && chars_written < MAX_TERMINAL_TITLE_CHARS {
+            sanitized.push(' ');
+            chars_written += 1;
+            pending_space = false;
+        }
+
+        if chars_written >= MAX_TERMINAL_TITLE_CHARS {
+            break;
+        }
+
+        sanitized.push(ch);
+        chars_written += 1;
+    }
+
+    sanitized
+}
+
+/// Returns whether `ch` should be dropped from terminal-title output.
+///
+/// This includes both plain control characters and a curated set of invisible
+/// formatting codepoints. The bidi entries here cover the Trojan-Source-style
+/// text-reordering controls that can make a title render misleadingly relative
+/// to its underlying byte sequence.
+fn is_disallowed_terminal_title_char(ch: char) -> bool {
+    if ch.is_control() {
+        return true;
+    }
+
+    // Strip Trojan-Source-related bidi controls plus common non-rendering
+    // formatting characters so title text cannot smuggle terminal control
+    // semantics or visually misleading content.
+    matches!(
+        ch,
+        '\u{00AD}'
+            | '\u{034F}'
+            | '\u{061C}'
+            | '\u{180E}'
+            | '\u{200B}'..='\u{200F}'
+            | '\u{202A}'..='\u{202E}'
+            | '\u{2060}'..='\u{206F}'
+            | '\u{FE00}'..='\u{FE0F}'
+            | '\u{FEFF}'
+            | '\u{FFF9}'..='\u{FFFB}'
+            | '\u{1BCA0}'..='\u{1BCA3}'
+            | '\u{E0100}'..='\u{E01EF}'
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::MAX_TERMINAL_TITLE_CHARS;
+    use super::SetWindowTitle;
+    use super::sanitize_terminal_title;
+    use crossterm::Command;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn sanitizes_terminal_title() {
+        let sanitized =
+            sanitize_terminal_title("  Project\t|\nWorking\x1b\x07\u{009D}\u{009C} |  Thread  ");
+        assert_eq!(sanitized, "Project | Working | Thread");
+    }
+
+    #[test]
+    fn strips_invisible_format_chars_from_terminal_title() {
+        let sanitized = sanitize_terminal_title(
+            "Pro\u{202E}j\u{2066}e\u{200F}c\u{061C}t\u{200B} \u{FEFF}T\u{2060}itle",
+        );
+        assert_eq!(sanitized, "Project Title");
+    }
+
+    #[test]
+    fn truncates_terminal_title() {
+        let input = "a".repeat(MAX_TERMINAL_TITLE_CHARS + 10);
+        let sanitized = sanitize_terminal_title(&input);
+        assert_eq!(sanitized.len(), MAX_TERMINAL_TITLE_CHARS);
+    }
+
+    #[test]
+    fn writes_osc_title_with_string_terminator() {
+        let mut out = String::new();
+        SetWindowTitle("hello".to_string())
+            .write_ansi(&mut out)
+            .expect("encode terminal title");
+        assert_eq!(out, "\x1b]0;hello\x1b\\");
+    }
+}