app.rs

// app.rs — App state struct and main event loop.

use crate::bridge_state::BridgeConnectionState;
use crate::context_viz::ContextVizState;
use crate::dialog_select::{DialogSelectState, SelectItem};
use crate::dialogs::McpApprovalDialogState;
use crate::dialogs::PermissionRequest;
use crate::diff_viewer::{build_turn_diff, DiffViewerState};
use crate::export_dialog::{ExportDialogState, ExportFormat};
use crate::import_config_dialog::ImportConfigDialogState;
use crate::mcp_view::{McpServerView, McpToolView, McpViewState, McpViewStatus};
use crate::model_picker::{EffortLevel, ModelPickerState};
use crate::notifications::{NotificationKind, NotificationQueue};
use crate::overlays::{
    GlobalSearchState, HelpEntry, HelpOverlay, HistorySearchOverlay, MessageSelectorOverlay,
    RewindFlowOverlay, SelectorMessage,
};
use crate::plugin_views::PluginHintBanner;
use crate::prompt_input::{InputMode, PromptInputState, VimMode};
use crate::render;
use crate::session_browser::SessionBrowserState;
use crate::settings_screen::SettingsScreen;
use crate::stats_dialog::StatsDialogState;
use crate::tasks_overlay::TasksOverlay;
use crate::theme_screen::ThemeScreen;
use crate::{
    agents_view::{AgentInfo, AgentStatus, AgentsMenuState, AgentsRoute},
    diff_viewer::DiffPane,
};
use claurst_core::config::{Config, Settings, Theme};
use claurst_core::cost::CostTracker;
use claurst_core::file_history::FileHistory;
use claurst_core::keybindings::{
    KeyContext, KeybindingResolver, KeybindingResult, ParsedKeystroke, UserKeybindings,
};
use claurst_core::types::{ContentBlock, Message, Role};
use claurst_core::{sample_completion_verb, sample_spinner_verb};
use claurst_query::QueryEvent;
use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyModifiers, MouseEvent, MouseEventKind};
use ratatui::backend::CrosstermBackend;
use ratatui::style::Color;
use ratatui::Terminal;
use std::cell::{Cell, RefCell};
use std::io::Stdout;
use std::sync::{Arc, Mutex};
use tracing::debug;

/// Pairs of (name, one-line description) shown by the slash-command
/// autocompletion, /help overlay, and the command palette. Must stay in
/// sync with the non-hidden entries returned by
/// `claurst_commands::all_commands()`; the
/// `prompt_slash_commands_covers_registry` test in `claurst-commands`
/// enforces that.
pub const PROMPT_SLASH_COMMANDS: &[(&str, &str)] = &[
    (
        "accounts",
        "List stored accounts; `dedupe` collapses duplicate profiles",
    ),
    (
        "attach",
        "Save and manage file attachments in the structured stash",
    ),
    ("chrome", "Browser automation via Chrome DevTools Protocol"),
    ("clear", "Clear the conversation transcript"),
    (
        "commit",
        "Stage and commit changes (model drafts the message)",
    ),
    ("compact", "Compact the conversation context"),
    (
        "config",
        "Open settings (theme, keybindings, advisor, import, UI)",
    ),
    ("connect", "Connect an AI provider"),
    (
        "coven",
        "Drive the local Coven daemon (sessions, harness runs, rituals)",
    ),
    ("diff", "Inspect the current git diff"),
    (
        "effort",
        "Set effort level (low/normal/high) or toggle fast mode",
    ),
    ("exit", "Quit Coven Code"),
    ("export", "Export, copy, or share the conversation"),
    (
        "familiar",
        "Your familiar & agents — switch persona, inspect, and manage",
    ),
    ("feedback", "Open session feedback survey"),
    (
        "handoff",
        "Hand off current session context to a Coven familiar",
    ),
    ("help", "Show help"),
    ("hooks", "Browse configured hooks (read-only)"),
    (
        "incant",
        "Cast a speech incantation (caveman, rocky) or lift it with off",
    ),
    ("init", "Initialize AGENTS.md for this project"),
    (
        "learn",
        "Codify the script/workflow we just built into a reusable skill",
    ),
    ("link", "Save and manage links in the structured stash"),
    ("login", "Log in, switch accounts, or refresh provider auth"),
    ("logout", "Log out of Coven Code"),
    ("mcp", "Browse configured MCP servers"),
    ("memory", "Browse and open AGENTS.md memory files"),
    ("model", "Change the AI model"),
    ("permissions", "Manage tool permission rules"),
    ("plan", "Enter plan mode (read-only)"),
    (
        "plugin",
        "Manage plugins (list/info/enable/disable/install/reload)",
    ),
    ("providers", "List available AI providers and their status"),
    ("quit", "Exit Coven Code"),
    ("resume", "Resume a previous session"),
    (
        "review",
        "Review changes (security/ultra variants, PR comments)",
    ),
    (
        "rewind",
        "Rewind the conversation or roll back file changes",
    ),
    ("sandbox", "Toggle sandboxed shell execution"),
    ("search", "Search the codebase by natural language or regex"),
    (
        "splash",
        "Show, hide, or toggle the empty-session splash screen",
    ),
    ("session", "Browse, rename, fork, branch, and tag sessions"),
    (
        "settings",
        "Open settings (theme, keybindings, advisor, import, UI)",
    ),
    ("skills", "List and manage skills"),
    (
        "status",
        "Show session status or run diagnostics (/status doctor)",
    ),
    #[cfg(feature = "steer")]
    (
        "steer",
        "Queue a steering message for the running turn (or send it now if idle)",
    ),
    ("survey", "Open session feedback survey"),
    ("tasks", "Manage tracked background tasks"),
    (
        "thinking",
        "Configure extended thinking or view past thinking traces",
    ),
    (
        "update",
        "Check for updates and upgrade to the latest version",
    ),
    ("release-notes", "Show recent Coven Code highlights"),
    ("usage", "Detailed per-call token usage breakdown"),
    ("version", "Display the current Coven Code version"),
    (
        "whisper",
        "Whisper a side question to your familiar (not kept in history)",
    ),
];

/// Canonical category for a slash command. Single source of truth shared by
/// the F1 help overlay, the command palette, and the `/help` text output in
/// `claurst-commands` (which delegates here) so every surface groups
/// commands the same way.
pub fn slash_command_category(name: &str) -> &'static str {
    match name {
        "clear" | "compact" | "rewind" | "undo" | "revert" | "export" | "branch" | "fork" => {
            "Conversation"
        }
        "model" | "config" | "settings" | "theme" | "color" | "vim" | "fast" | "effort"
        | "voice" | "statusline" | "output-style" | "keybindings" | "splash" | "sandbox" => {
            "Settings"
        }
        "cost" | "usage" | "context" | "stats" => "Usage & Cost",
        "status" | "doctor" | "terminal-setup" | "version" | "update" | "upgrade" => "System",
        "login" | "logout" | "switch" | "refresh" | "permissions" | "connect" | "providers" => {
            "Auth & Permissions"
        }
        "memory" | "diff" | "init" | "commit" | "review" | "import-config" | "security-review" => {
            "Project"
        }
        "mcp" | "hooks" | "chrome" => "Integrations",
        "session" | "resume" | "search" | "share" | "rename" => "Sessions & Remote",
        "help" | "exit" | "quit" | "feedback" | "survey" | "bug" => "General",
        "think-back" | "thinking" | "plan" | "goal" | "tasks" | "advisor" => "AI & Thinking",
        "copy" | "skills" | "learn" | "plugin" | "reload-plugins" | "whisper" | "incant" => {
            "Tools & Extras"
        }
        "coven" | "familiar" | "familiars" | "handoff" => "Coven",
        _ => "Other",
    }
}

fn help_overlay_entries() -> Vec<HelpEntry> {
    PROMPT_SLASH_COMMANDS
        .iter()
        .map(|(name, description)| HelpEntry {
            name: (*name).to_string(),
            aliases: String::new(),
            description: (*description).to_string(),
            category: slash_command_category(name).to_string(),
        })
        .collect()
}

// ---------------------------------------------------------------------------
// Voice mode bootstrap
// ---------------------------------------------------------------------------

/// `true` when the launcher should treat voice mode as opted out for this
/// run regardless of what `ui-settings.json` says. Set
/// `COVEN_CODE_VOICE=0` (or `false`) to disable voice without editing the
/// stored UI settings — useful when the persistent flag has been turned on
/// and the user wants a one-shot launch where slash-command keystrokes
/// aren't routed through the voice pipeline.
pub(crate) fn voice_explicitly_disabled() -> bool {
    matches!(
        std::env::var("COVEN_CODE_VOICE").as_deref(),
        Ok("0") | Ok("false")
    )
}

/// Resolve the voice recorder Arc for this `App` instance.
///
/// Returns `Some(recorder)` only when voice mode is opted in via:
///   * `COVEN_CODE_VOICE_ENABLED=1` (per-launch override), OR
///   * `voice_enabled: true` in `~/.coven-code/ui-settings.json`
///
/// `COVEN_CODE_VOICE=0` (or `=false`) hard-overrides the persistent
/// setting and forces the recorder to `None` for the launch.
fn voice_recorder_from_env_and_settings(
) -> Option<std::sync::Arc<std::sync::Mutex<claurst_core::voice::VoiceRecorder>>> {
    if voice_explicitly_disabled() {
        return None;
    }
    let voice_on = std::env::var("COVEN_CODE_VOICE_ENABLED")
        .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
        .unwrap_or(false)
        || {
            let path = claurst_core::config::Settings::config_dir().join("ui-settings.json");
            std::fs::read_to_string(&path)
                .ok()
                .and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok())
                .and_then(|v| v["voice_enabled"].as_bool())
                .unwrap_or(false)
        };
    if !voice_on {
        return None;
    }
    let recorder = claurst_core::voice::global_voice_recorder();
    if let Ok(mut r) = recorder.lock() {
        r.set_enabled(true);
    }
    Some(recorder)
}

#[cfg(test)]
pub(crate) mod test_env {
    use std::path::{Path, PathBuf};
    use std::sync::{Mutex, MutexGuard};

    static ENV_LOCK: Mutex<()> = Mutex::new(());

    pub(crate) struct EnvGuard {
        old_home: Option<String>,
        old_coven_home: Option<String>,
        old_anthropic_config_dir: Option<String>,
        old_anthropic_api_key: Option<String>,
        old_oauth_client_id: Option<String>,
        old_claude_bin: Option<String>,
        old_user: Option<String>,
        old_username: Option<String>,
        _lock: MutexGuard<'static, ()>,
    }

    impl EnvGuard {
        pub(crate) fn set(home: &Path, coven_home: &Path) -> Self {
            Self::set_with_user(home, coven_home, None)
        }

        pub(crate) fn set_with_user(home: &Path, coven_home: &Path, user: Option<&str>) -> Self {
            let lock = ENV_LOCK.lock().unwrap_or_else(|err| err.into_inner());
            let guard = Self {
                old_home: std::env::var("HOME").ok(),
                old_coven_home: std::env::var("COVEN_HOME").ok(),
                old_anthropic_config_dir: std::env::var("ANTHROPIC_CONFIG_DIR").ok(),
                old_anthropic_api_key: std::env::var("ANTHROPIC_API_KEY").ok(),
                old_oauth_client_id: std::env::var(claurst_core::oauth::CLIENT_ID_ENV).ok(),
                old_claude_bin: std::env::var(claurst_api::providers::claude_cli::CLAUDE_BIN_ENV)
                    .ok(),
                old_user: std::env::var("USER").ok(),
                old_username: std::env::var("USERNAME").ok(),
                _lock: lock,
            };
            std::env::set_var("HOME", PathBuf::from(home));
            std::env::set_var("COVEN_HOME", PathBuf::from(coven_home));
            std::env::remove_var("ANTHROPIC_CONFIG_DIR");
            std::env::remove_var("ANTHROPIC_API_KEY");
            std::env::remove_var(claurst_core::oauth::CLIENT_ID_ENV);
            std::env::remove_var(claurst_api::providers::claude_cli::CLAUDE_BIN_ENV);
            match user {
                Some(value) => std::env::set_var("USER", value),
                None => std::env::remove_var("USER"),
            }
            std::env::remove_var("USERNAME");
            // COVEN_HOME changed — drop any roster cached from the old home.
            crate::coven_status::invalidate_roster_cache();
            guard
        }
    }

    impl Drop for EnvGuard {
        fn drop(&mut self) {
            match &self.old_home {
                Some(value) => std::env::set_var("HOME", value),
                None => std::env::remove_var("HOME"),
            }
            match &self.old_coven_home {
                Some(value) => std::env::set_var("COVEN_HOME", value),
                None => std::env::remove_var("COVEN_HOME"),
            }
            match &self.old_anthropic_config_dir {
                Some(value) => std::env::set_var("ANTHROPIC_CONFIG_DIR", value),
                None => std::env::remove_var("ANTHROPIC_CONFIG_DIR"),
            }
            match &self.old_anthropic_api_key {
                Some(value) => std::env::set_var("ANTHROPIC_API_KEY", value),
                None => std::env::remove_var("ANTHROPIC_API_KEY"),
            }
            match &self.old_oauth_client_id {
                Some(value) => std::env::set_var(claurst_core::oauth::CLIENT_ID_ENV, value),
                None => std::env::remove_var(claurst_core::oauth::CLIENT_ID_ENV),
            }
            match &self.old_claude_bin {
                Some(value) => {
                    std::env::set_var(claurst_api::providers::claude_cli::CLAUDE_BIN_ENV, value)
                }
                None => std::env::remove_var(claurst_api::providers::claude_cli::CLAUDE_BIN_ENV),
            }
            match &self.old_user {
                Some(value) => std::env::set_var("USER", value),
                None => std::env::remove_var("USER"),
            }
            match &self.old_username {
                Some(value) => std::env::set_var("USERNAME", value),
                None => std::env::remove_var("USERNAME"),
            }
            // COVEN_HOME restored — drop any roster cached from the temp home.
            crate::coven_status::invalidate_roster_cache();
        }
    }
}

// ---------------------------------------------------------------------------
// Provider connection helpers
// ---------------------------------------------------------------------------

/// Return the environment variable name for a given provider ID.
#[allow(dead_code)]
fn get_env_var_for_provider(id: &str) -> &'static str {
    match id {
        "anthropic" => "ANTHROPIC_API_KEY",
        _ => "API_KEY",
    }
}

/// Return a URL hint for obtaining an API key from a given provider.
#[allow(dead_code)]
fn get_url_for_provider(id: &str) -> &'static str {
    match id {
        "anthropic" => "console.anthropic.com",
        _ => "the provider's website",
    }
}

fn import_config_picker_items() -> Vec<SelectItem> {
    vec![
        SelectItem {
            id: "claude-md".into(),
            title: "CLAUDE.md".into(),
            description: "Import ~/.claude/CLAUDE.md".into(),
            category: "Import".into(),
            badge: None,
        },
        SelectItem {
            id: "settings".into(),
            title: "settings.json".into(),
            description: "Import ~/.claude/settings.json".into(),
            category: "Import".into(),
            badge: None,
        },
        SelectItem {
            id: "both".into(),
            title: "Both".into(),
            description: "Import both CLAUDE.md and settings.json".into(),
            category: "Import".into(),
            badge: None,
        },
    ]
}

fn provider_picker_items() -> Vec<SelectItem> {
    let has_claude_cli = claurst_api::providers::claude_cli::resolve_claude_binary().is_some();
    vec![
        SelectItem {
            id: "anthropic-cli".into(),
            title: "Claude CLI".into(),
            description: "Run turns through the local claude binary; auth stays in Claude Code"
                .into(),
            category: "Claude".into(),
            badge: has_claude_cli.then(|| "LOCAL".into()),
        },
        SelectItem {
            id: "openai-codex".into(),
            title: "Codex CLI".into(),
            description: "Sign in with Codex CLI login".into(),
            category: "Codex".into(),
            badge: None,
        },
    ]
}

// ---------------------------------------------------------------------------
// Supporting types
// ---------------------------------------------------------------------------

/// Visual style for inline system messages in the conversation pane.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SystemMessageStyle {
    Info,
    Warning,
    /// Compact / auto-compact boundary marker.
    Compact,
}

/// A synthetic system annotation inserted between conversation messages.
/// `after_index` is the index in `App::messages` after which this annotation
/// should appear (0 = before all messages, 1 = after message 0, etc.).
#[derive(Debug, Clone)]
pub struct SystemAnnotation {
    pub after_index: usize,
    pub text: String,
    pub style: SystemMessageStyle,
}

/// A displayable item in the conversation pane — either a real message or
/// a synthetic system annotation (e.g. compact boundary).
/// Used only by `render.rs`; constructed on the fly from `messages` +
/// `system_annotations`.
#[derive(Debug, Clone)]
pub enum DisplayMessage {
    /// A real conversation turn.
    Conversation(Message),
    /// An injected system notice (e.g. compact boundary).
    System {
        text: String,
        style: SystemMessageStyle,
    },
}

/// Context menu state: position and currently selected item index.
#[derive(Debug, Clone, Copy)]
pub struct ContextMenuState {
    /// X coordinate of the menu (column).
    pub x: u16,
    /// Y coordinate of the menu (row).
    pub y: u16,
    /// Currently selected menu item index (0-based).
    pub selected_index: usize,
    /// What the context menu is acting on.
    pub kind: ContextMenuKind,
}

/// What content the context menu is currently targeting.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ContextMenuKind {
    /// A specific transcript message.
    Message { message_index: usize },
    /// The current text selection anywhere in the frame.
    Selection,
}

/// Available context menu items.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ContextMenuItem {
    Copy,
    Fork,
}

/// State for the Go to Line dialog (Ctrl+G in message pane).
#[derive(Debug, Clone)]
pub struct GoToLineDialog {
    /// Input field for line number.
    pub input: String,
    /// Whether the dialog is currently active.
    pub active: bool,
    /// Total number of lines (for validation feedback).
    pub total_lines: usize,
}

impl GoToLineDialog {
    pub fn new() -> Self {
        Self {
            input: String::new(),
            active: false,
            total_lines: 0,
        }
    }

    pub fn open(&mut self, total_lines: usize) {
        self.input.clear();
        self.active = true;
        self.total_lines = total_lines;
    }

    pub fn close(&mut self) {
        self.active = false;
        self.input.clear();
    }

    /// Parse the input as a line number (1-indexed).
    /// Returns None if invalid or out of range.
    pub fn parse_line_number(&self) -> Option<usize> {
        let line_num: usize = self.input.trim().parse().ok()?;
        if line_num >= 1 && line_num <= self.total_lines {
            Some(line_num)
        } else {
            None
        }
    }
}

impl Default for GoToLineDialog {
    fn default() -> Self {
        Self::new()
    }
}

/// Status of an active or completed tool call.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ToolStatus {
    Running,
    Done,
    Error,
}

/// Represents an active or completed tool invocation visible in the UI.
#[derive(Debug, Clone)]
pub struct ToolUseBlock {
    pub id: String,
    pub name: String,
    pub turn_index: Option<usize>,
    pub status: ToolStatus,
    pub output_preview: Option<String>,
    /// JSON-serialised input for the tool call (populated from the API stream).
    pub input_json: String,
}

#[derive(Debug, Clone, Default)]
pub struct TurnMetadata {
    pub submitted_at: Option<String>,
    pub model_name: Option<String>,
    pub agent_mode: Option<String>,
    pub duration: Option<String>,
    pub interrupted: bool,
}

/// Attempt to copy text to the system clipboard using trusted platform clipboard helpers.
/// Returns true if successful.
pub fn try_copy_to_clipboard(text: &str) -> bool {
    crate::image_paste::write_clipboard_text(text)
}

/// Map a character to its QWERTY Latin keyboard-position equivalent.
///
/// When a modifier key (Ctrl, Alt) is held together with a non-ASCII character
/// (e.g. Cyrillic С on a Ukrainian/Russian layout), the char produced by
/// crossterm is the non-Latin glyph rather than the Latin letter that occupies
/// the same physical key.  Keybinding strings are always written as Latin
/// letters (`ctrl+c`, `alt+b`, …), so the lookup fails.
///
/// This function converts the reported character to the Latin letter that sits
/// at the same physical QWERTY position, covering the standard Russian JCUKEN
/// and Ukrainian layouts which share the same physical-key→Latin mapping.
/// For characters outside any known mapping the original (lowercased) char is
/// returned unchanged — this is always safe since unrecognised chars just
/// produce no keybinding match.
fn layout_to_latin(c: char) -> String {
    // Standard Russian/Ukrainian JCUKEN → QWERTY position mapping.
    // Both upper- and lower-case Cyrillic variants are covered by
    // converting to lowercase first.
    let lower = c.to_lowercase().next().unwrap_or(c);
    let mapped: Option<char> = match lower {
        // Row 1
        'й' => Some('q'),
        'ц' => Some('w'),
        'у' => Some('e'),
        'к' => Some('r'),
        'е' => Some('t'),
        'н' => Some('y'),
        'г' => Some('u'),
        'ш' => Some('i'),
        'щ' => Some('o'),
        'з' => Some('p'),
        // Row 2
        'ф' => Some('a'),
        'ы' => Some('s'),
        'в' => Some('d'),
        'а' => Some('f'),
        'п' => Some('g'),
        'р' => Some('h'),
        'о' => Some('j'),
        'л' => Some('k'),
        'д' => Some('l'),
        // Row 3
        'я' => Some('z'),
        'ч' => Some('x'),
        'с' => Some('c'),
        'м' => Some('v'),
        'и' => Some('b'),
        'т' => Some('n'),
        'ь' => Some('m'),
        // Ukrainian-specific letters on standard positions
        'і' => Some('s'),
        'ї' => Some(']'),
        'є' => Some('\''),
        _ => None,
    };
    mapped.unwrap_or(lower).to_string()
}

/// Apply shift transformation to a character based on standard US QWERTY layout.
/// Handles both ASCII lowercase letters and number/symbol keys.
///
/// **Why this exists**: Terminals that support the kitty keyboard protocol send
/// unshifted characters with modifier flags instead of pre-shifted characters
/// (e.g., Shift+1 arrives as '1' + SHIFT instead of '!'). This function normalizes
/// them to the expected shifted characters.
///
/// **Keyboard layout limitation**: This only works correctly for US QWERTY keyboards.
/// Other layouts (AZERTY, QWERTZ, etc.) have different shift mappings. For non-US
/// layouts, we rely on the terminal to send the correctly shifted character, which
/// most modern terminals do (especially with kitty protocol enabled).
fn normalize_char_with_shift(c: char, modifiers: KeyModifiers) -> char {
    if !modifiers.contains(KeyModifiers::SHIFT) {
        return c;
    }

    if c.is_ascii_lowercase() {
        return c.to_ascii_uppercase();
    }

    // Map unshifted number/symbol keys to their shifted equivalents (US QWERTY)
    match c {
        '1' => '!',
        '2' => '@',
        '3' => '#',
        '4' => '$',
        '5' => '%',
        '6' => '^',
        '7' => '&',
        '8' => '*',
        '9' => '(',
        '0' => ')',
        '-' => '_',
        '=' => '+',
        '[' => '{',
        ']' => '}',
        ';' => ':',
        '\'' => '"',
        ',' => '<',
        '.' => '>',
        '/' => '?',
        '\\' => '|',
        '`' => '~',
        _ => c,
    }
}

fn key_event_to_keystroke(key: &KeyEvent) -> Option<ParsedKeystroke> {
    let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
    let alt = key.modifiers.contains(KeyModifiers::ALT);

    let normalized_key = match key.code {
        KeyCode::Backspace => "backspace".to_string(),
        KeyCode::Delete => "delete".to_string(),
        KeyCode::Down => "down".to_string(),
        KeyCode::End => "end".to_string(),
        KeyCode::Enter => "enter".to_string(),
        KeyCode::Esc => "escape".to_string(),
        KeyCode::Home => "home".to_string(),
        KeyCode::Left => "left".to_string(),
        KeyCode::PageDown => "pagedown".to_string(),
        KeyCode::PageUp => "pageup".to_string(),
        KeyCode::Right => "right".to_string(),
        KeyCode::Tab => "tab".to_string(),
        KeyCode::Up => "up".to_string(),
        KeyCode::BackTab => "tab".to_string(),
        KeyCode::Char(' ') => "space".to_string(),
        KeyCode::Char(c) => {
            // For modifier-key combos (Ctrl/Alt + letter), normalize to the
            // ASCII Latin key at the same physical QWERTY position.  This
            // makes shortcuts like Ctrl+C work regardless of the active
            // keyboard layout (Ukrainian, Russian, Greek, …).
            if (ctrl || alt) && !c.is_ascii() {
                layout_to_latin(c)
            } else {
                c.to_lowercase().to_string()
            }
        }
        _ => return None,
    };

    Some(ParsedKeystroke {
        key: normalized_key,
        ctrl,
        alt,
        shift: key.modifiers.contains(KeyModifiers::SHIFT),
        meta: key.modifiers.contains(KeyModifiers::SUPER),
    })
}

// ---------------------------------------------------------------------------
// Focus target
// ---------------------------------------------------------------------------

/// Which area of the TUI currently has keyboard focus.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FocusTarget {
    /// Keyboard input goes to the prompt editor.
    Input,
    /// Keyboard input goes to the transcript/message pane (scroll, etc.).
    Transcript,
}

// ---------------------------------------------------------------------------
// App struct
// ---------------------------------------------------------------------------

/// The top-level TUI application.
pub struct App {
    // Core state
    pub config: Config,
    pub cost_tracker: Arc<CostTracker>,
    pub messages: Vec<Message>,
    /// Combined display list kept in sync with `messages`: real conversation turns
    /// plus injected system annotations. Used by the renderer so it can iterate
    /// a single sequence instead of merging two lists on every frame.
    pub display_messages: Vec<DisplayMessage>,
    /// Synthetic system annotations interleaved between real messages at render time.
    pub system_annotations: Vec<SystemAnnotation>,
    pub input: String,
    pub prompt_input: PromptInputState,
    pub input_history: Vec<String>,
    pub history_index: Option<usize>,
    pub scroll_offset: usize,
    pub is_streaming: bool,
    pub streaming_text: String,
    pub streaming_thinking: String,
    pub status_message: Option<String>,
    /// Randomly chosen thinking verb shown next to the spinner while streaming.
    pub spinner_verb: Option<String>,
    pub should_exit: bool,

    // Extended state
    pub tool_use_blocks: Vec<ToolUseBlock>,
    pub permission_request: Option<PermissionRequest>,
    pub frame_count: u64,
    pub token_count: u32,
    /// Maximum token budget (from env var or model context window) — P2 feature flag
    pub token_budget: Option<u32>,
    pub cost_usd: f64,
    pub model_name: String,
    /// Whether the app has valid API credentials configured.
    /// False = show the in-TUI provider setup dialog on startup.
    pub has_credentials: bool,
    /// Current effort level (controls extended-thinking budget_tokens).
    pub effort_level: EffortLevel,
    /// Whether the user has explicitly chosen an effort level (via the model
    /// picker, the `/effort` dialog, or the `/effort` command). When false the
    /// query layer leaves effort unset so the model uses its own default; when
    /// true `effort_level` is the single source of truth and is forwarded to
    /// every turn. Without this flag, picker/dialog selections were silently
    /// dropped — only the `/effort` command reached the API.
    pub effort_is_set: bool,
    /// Whether fast mode is currently active (model locked to FAST_MODE_MODEL).
    pub fast_mode: bool,
    /// Active speech mode: None = normal, Some("caveman") / Some("rocky").
    pub speech_mode: Option<String>,
    /// Speech mode intensity: "lite", "full", "ultra".
    pub speech_level: String,
    /// Current agent mode name: "build", "plan", "explore", etc.
    pub agent_mode: Option<String>,
    /// Accent color derived from the current agent mode.
    /// Build = pink, Plan = blue, Explore = amber.
    pub accent_color: Color,
    /// Set by `cycle_agent_mode` so the main loop can update the query config
    /// and tool list to match the newly-selected agent.
    pub agent_mode_changed: bool,
    pub agent_status: Vec<(String, String)>,
    pub keybindings: KeybindingResolver,

    // Cursor position within input (byte offset)
    pub cursor_pos: usize,

    // ---- Scrollback / auto-scroll -----------------------------------------
    /// When `true`, the message pane follows the latest messages automatically.
    pub auto_scroll: bool,
    /// Count of messages that arrived while the user was scrolled up.
    pub new_messages_while_scrolled: usize,

    // ---- Token warning tracking -------------------------------------------
    /// Which threshold (0 = none, 80, 95, 100) was last notified so we only
    /// show each banner once.
    pub token_warning_threshold_shown: u8,

    // ---- Session timing ---------------------------------------------------
    /// Instant the session started (used for elapsed-time in the status bar).
    pub session_start: std::time::Instant,
    /// Current familiar pose for rendering. `Static` when idle; `Loading {
    /// frame }` while streaming has stalled long enough to surface a spinner.
    /// The glyph itself never walks or blinks.
    pub companion_current_pose: crate::mascot::CompanionPose,
    /// Instant the current turn's streaming began (reset each time streaming starts).
    pub turn_start: Option<std::time::Instant>,
    /// Elapsed time string for the last completed turn, e.g. "2m 5s".
    pub last_turn_elapsed: Option<String>,
    /// Past-tense verb shown after turn completes, e.g. "Worked" / "Baked".
    pub last_turn_verb: Option<&'static str>,
    /// Per-user turn snapshots used by the transcript renderer.
    pub turn_metadata: Vec<TurnMetadata>,
    /// Incremented whenever transcript-visible state changes so rendering can
    /// reuse cached layout between keystrokes.
    pub transcript_version: Cell<u64>,

    // ---- New overlay / notification fields --------------------------------
    /// Full-screen help overlay (? / F1).
    pub help_overlay: HelpOverlay,
    /// Ctrl+R history search overlay.
    pub history_search_overlay: HistorySearchOverlay,
    /// Global ripgrep search / quick-open overlay.
    pub global_search: GlobalSearchState,
    /// Message selector used by /rewind.
    pub message_selector: MessageSelectorOverlay,
    /// Multi-step rewind flow overlay.
    pub rewind_flow: RewindFlowOverlay,
    /// Bridge connection state.
    pub bridge_state: BridgeConnectionState,
    /// Active notification queue.
    pub notifications: NotificationQueue,
    /// Scroll offset for error modal text (in lines).
    pub error_modal_scroll_offset: usize,
    /// Interactive rate-limit recovery modal (auto-retry countdown, one-key
    /// tier switch, duplicate-account cleanup).
    pub rate_limit_recovery: crate::rate_limit_recovery::RateLimitRecoveryState,
    /// Plugin hint banners.
    pub plugin_hints: Vec<PluginHintBanner>,
    /// Optional session title shown in the status bar.
    pub session_title: Option<String>,
    /// Remote session URL (set when bridge connects; readable by commands).
    pub remote_session_url: Option<String>,
    /// Live MCP manager snapshot source when available.
    pub mcp_manager: Option<Arc<claurst_mcp::McpManager>>,
    /// Queued request for a real MCP reconnect from the interactive loop.
    pub pending_mcp_reconnect: bool,
    /// Pending MCP panel-auth request for the interactive loop.
    pub pending_mcp_panel_auth: Option<String>,
    /// Shared file-history service used for turn diff reconstruction.
    pub file_history: Option<Arc<parking_lot::Mutex<FileHistory>>>,
    /// Shared query-loop turn counter for turn-local diff reconstruction.
    pub current_turn: Option<Arc<std::sync::atomic::AtomicUsize>>,

    // ---- Visual mode indicators -------------------------------------------
    /// Plan mode — input border turns blue, [PLAN] shown in status bar.
    pub plan_mode: bool,
    /// "While you were away" summary text shown on the welcome screen.
    pub away_summary: Option<String>,
    /// When streaming stalled (used to turn the spinner red after 3 s).
    pub stall_start: Option<std::time::Instant>,

    // ---- Settings / theme / privacy screens --------------------------------
    /// Full-screen tabbed settings screen (/config, /settings).
    pub settings_screen: SettingsScreen,
    /// Theme picker overlay (/theme).
    pub theme_screen: ThemeScreen,
    /// Token/cost analytics dialog.
    pub stats_dialog: StatsDialogState,
    /// MCP server browser and tool detail view.
    pub mcp_view: McpViewState,
    /// Agent definitions and active agent status overlay.
    pub agents_menu: AgentsMenuState,
    /// Diff viewer overlay.
    pub diff_viewer: DiffViewerState,
    /// Session-quality feedback survey overlay.
    pub feedback_survey: crate::feedback_survey::FeedbackSurveyState,
    /// Memory file selector overlay (AGENTS.md browser).
    pub memory_file_selector: crate::memory_file_selector::MemoryFileSelectorState,
    /// Read-only hooks configuration browser.
    pub hooks_config_menu: crate::hooks_config_menu::HooksConfigMenuState,
    /// Overage credit upsell banner.
    pub overage_upsell: crate::overage_upsell::OverageCreditUpsellState,
    /// Voice mode availability notice.
    pub voice_mode_notice: crate::voice_mode_notice::VoiceModeNoticeState,
    /// Startup error dialog for malformed settings.json or AGENTS.md.
    pub invalid_config_dialog: crate::invalid_config_dialog::InvalidConfigDialogState,
    /// Memory update notification banner.
    pub memory_update_notification:
        crate::memory_update_notification::MemoryUpdateNotificationState,
    /// MCP elicitation dialog (form requested by an MCP server).
    pub elicitation: crate::elicitation_dialog::ElicitationDialogState,
    /// Model picker overlay (/model command).
    pub model_picker: ModelPickerState,
    /// Session browser overlay (/session, /resume, /rename, /export).
    pub session_browser: SessionBrowserState,
    /// Session branching overlay (Ctrl+B) — create and switch branches.
    pub session_branching: crate::session_branching::SessionBranchingState,
    /// Task progress overlay (Ctrl+T) — shows task status with toggle capability.
    pub tasks_overlay: TasksOverlay,
    /// Export format picker dialog (/export).
    pub export_dialog: ExportDialogState,
    /// Context window / rate limit visualization overlay (/context).
    pub context_viz: ContextVizState,
    /// MCP server approval dialog.
    pub mcp_approval: McpApprovalDialogState,
    /// Go to Line dialog (Ctrl+G in message pane).
    pub go_to_line_dialog: GoToLineDialog,
    /// Bypass-permissions startup confirmation dialog.
    /// Shown at startup when --dangerously-skip-permissions was passed.
    /// User must explicitly accept or the session exits.
    pub bypass_permissions_dialog: crate::bypass_permissions_dialog::BypassPermissionsDialogState,
    /// Whether the bypass-permissions dialog has been shown this session.
    pub bypass_permissions_dialog_shown: bool,
    /// File injection warning dialog.
    /// Shown when oversized or binary files are detected in @refs.
    pub file_injection_dialog: crate::file_injection_dialog::FileInjectionDialogState,
    /// When true, the next file injection size check uses limit 0 (no limit),
    /// letting files that were "allowed" through the warning dialog be injected.
    pub file_injection_force: bool,
    /// First-launch onboarding welcome dialog.
    pub onboarding_dialog: crate::onboarding_dialog::OnboardingDialogState,
    /// Effort-level picker (/effort with no args).
    pub effort_picker: crate::effort_picker::EffortPickerState,
    /// Interactive skills picker (/skills).
    pub skills_picker: crate::skills_picker::SkillsPickerState,
    /// API key input dialog (opened from /connect for key-based providers).
    pub key_input_dialog: crate::key_input_dialog::KeyInputDialogState,
    /// Device code / browser auth dialog (Claude OAuth, Codex login).
    pub device_auth_dialog: crate::device_auth_dialog::DeviceAuthDialogState,
    /// When set, the main loop should spawn the async auth task for this provider.
    pub device_auth_pending: Option<String>,
    /// When true, the main loop should rebuild the provider runtime from disk
    /// (same as `/refresh`) so newly-established credentials take effect live.
    pub pending_provider_refresh: bool,
    /// Shared provider registry for dynamic model fetching.
    pub provider_registry: Option<std::sync::Arc<claurst_api::ProviderRegistry>>,
    /// Model registry populated from models.dev — single source of truth for
    /// all provider models shown in the `/model` picker.
    pub model_registry: claurst_api::ModelRegistry,
    /// When `true`, the main event loop should spawn an async task to fetch
    /// the model list from the current provider's `list_models()` API.
    pub model_picker_fetch_pending: bool,
    /// The provider ID that the model picker was opened for (used when the
    /// fetch is triggered from /connect before the provider is activated).
    pub model_picker_provider_id: Option<String>,
    /// When `true`, the main event loop should spawn an async task to load
    /// the session list from disk and populate the session browser.
    pub session_list_pending: bool,
    /// Receiver for background session-list results.
    pub session_list_rx:
        Option<tokio::sync::mpsc::Receiver<Vec<crate::session_browser::SessionEntry>>>,
    /// Credential store for provider API keys and OAuth tokens.
    pub auth_store: claurst_core::AuthStore,
    /// Messages typed by the user while a query was streaming. They will be
    /// auto-submitted in order once the current turn completes (issue #149).
    pub queued_messages: std::collections::VecDeque<String>,
    /// When `true`, the main loop will inject a synthetic Enter event on the
    /// next iteration to dequeue and submit the next queued message.
    pub pending_auto_submit: bool,
    /// Connect-a-provider dialog (/connect command).
    pub connect_dialog: DialogSelectState,
    /// Import-config source picker (/import-config command).
    pub import_config_picker: DialogSelectState,
    /// Import-config preview and confirmation dialog.
    pub import_config_dialog: ImportConfigDialogState,
    /// Ctrl+K command palette overlay.
    pub command_palette: DialogSelectState,
    /// Whether Coven Code was launched from the user's home directory.
    /// Shown as a startup notice: "Note: You have launched Coven Code in your home directory…"
    pub home_dir_warning: bool,
    /// Output style: "auto" | "stream" | "verbose".
    pub output_style: String,
    /// PR number for the current branch (None if not in a PR context).
    pub pr_number: Option<u32>,
    /// PR URL for the current branch.
    pub pr_url: Option<String>,
    /// PR review state: "approved", "changes_requested", "review_required", etc.
    pub pr_state: Option<String>,
    /// Current working directory path.
    pub current_dir: Option<String>,
    /// Current git branch name.
    pub git_branch: Option<String>,
    /// Count of in-progress background tasks (drives the footer pill).
    pub background_task_count: usize,
    /// Background task status text shown in footer pill.
    pub background_task_status: Option<String>,
    /// External status line command output (from CLAUDE_STATUS_COMMAND).
    pub status_line_override: Option<String>,
    /// Whether auto-compact is enabled (from settings).
    pub auto_compact_enabled: bool,
    /// Context threshold (0-100) at which to auto-compact.
    pub auto_compact_threshold: u8,
    /// Guard to prevent re-triggering auto-compact while one is in flight.
    pub auto_compact_running: bool,

    /// Show a toast when an assistant turn or background task completes
    /// (`Settings.completionToast`, default true).
    pub completion_toast_enabled: bool,
    /// Ring the terminal bell on completion (`Settings.bellOnComplete`, default false).
    pub bell_on_complete: bool,
    /// Minimum turn duration (seconds) before we surface a turn-complete toast.
    /// Below this, the existing in-status "✽ Worked for Ns" line is enough.
    pub completion_toast_min_secs: u64,

    // ---- Voice hold-to-talk ------------------------------------------------
    /// The global voice recorder, Some when voice is enabled in config.
    pub voice_recorder: Option<Arc<Mutex<claurst_core::voice::VoiceRecorder>>>,
    /// True while recording is active (Alt+V toggled on).
    pub voice_recording: bool,
    /// Receiver for VoiceEvent messages produced by the recorder task.
    pub voice_event_rx: Option<tokio::sync::mpsc::Receiver<claurst_core::voice::VoiceEvent>>,
    /// A single key event that was drained from the queue during paste-burst
    /// detection but wasn't part of the burst (e.g. a modifier key that stopped
    /// the burst). Replayed at the top of the next loop iteration.
    pending_key: Option<crossterm::event::KeyEvent>,
    /// Receiver for model-list results fetched in the background when the
    /// /model picker opens.  Drained each frame so models appear as soon as
    /// the fetch completes.
    pub model_fetch_rx:
        Option<tokio::sync::mpsc::Receiver<Result<Vec<crate::model_picker::ModelEntry>, ()>>>,
    /// Receiver for `UserQuestionEvent`s produced by the AskUserQuestion tool.
    /// When a question arrives, `ask_user_dialog` is populated and shown.
    pub user_question_rx:
        Option<tokio::sync::mpsc::UnboundedReceiver<claurst_tools::UserQuestionEvent>>,
    /// State for the model-initiated ask-user question dialog.
    pub ask_user_dialog: crate::ask_user_dialog::AskUserDialogState,

    // ---- Context window & rate limit info ----------------------------------
    /// Total context window size for the current model (tokens).
    pub context_window_size: u64,
    /// How many tokens are currently used in the context window.
    pub context_used_tokens: u64,
    /// Rate limit info — 5-hour window usage percentage (0–100).
    pub rate_limit_5h_pct: Option<f32>,
    /// Rate limit info — 7-day window usage percentage (0–100).
    pub rate_limit_7day_pct: Option<f32>,
    /// Active worktree name (if in a worktree).
    pub worktree_name: Option<String>,
    /// Active worktree branch (if in a worktree).
    pub worktree_branch: Option<String>,
    /// Agent type badge: "agent" | "coordinator" | "subagent".
    pub agent_type_badge: Option<String>,
    /// Goal badge string shown in the footer, e.g. "active · 5m · 3 turns".
    /// None when no goal is active. Updated by the REPL after each turn.
    pub active_goal_badge: Option<String>,

    // ---- Thinking block expansion state ----------------------------------
    /// Set of thinking block content hashes that are expanded.
    pub thinking_expanded: std::collections::HashSet<u64>,
    /// The message pane area from the last render frame (used for mouse hit testing).
    pub last_msg_area: Cell<ratatui::layout::Rect>,
    /// The frame region that supports text selection.
    pub last_selectable_area: Cell<ratatui::layout::Rect>,
    /// The prompt input area from the last render frame (used for focus routing).
    pub last_input_area: Cell<ratatui::layout::Rect>,
    /// The footer's right column area (where tips are shown) from the last render.
    pub footer_right_column_area: Cell<ratatui::layout::Rect>,
    /// Which area of the TUI currently has keyboard focus.
    pub focus: FocusTarget,
    /// Maps virtual_row_index → thinking_block_hash for click detection.
    pub thinking_row_map: RefCell<std::collections::HashMap<u16, u64>>,
    /// Maps screen row → transcript message index for right-click hit testing.
    pub message_row_map: RefCell<std::collections::HashMap<u16, usize>>,
    /// Total message lines from the last render (used for virtual row mapping).
    pub total_message_lines: Cell<usize>,
    /// Scroll offset from the last render frame (used for selection validation).
    pub last_render_scroll_offset: Cell<u16>,

    // ---- Text selection state --------------------------------------------
    /// Selection drag anchor (col, row) — set on mouse-down.
    pub selection_anchor: Option<(u16, u16)>,
    /// Selection drag focus (col, row) — updated on mouse-drag / mouse-up.
    pub selection_focus: Option<(u16, u16)>,
    /// Text extracted from the current selection (updated each render frame).
    pub selection_text: RefCell<String>,
    /// Cache of row -> rendered text within the selectable area, refreshed
    /// each frame. Used by double/triple-click word and paragraph detection
    /// (issue #149 follow-up: prior word-boundary detection was a placeholder).
    pub last_row_text: RefCell<std::collections::HashMap<u16, String>>,

    // ---- Advanced mouse interaction state --------------------------------
    /// Timestamp of the last left mouse click (for double/triple-click detection).
    pub last_click_time: Option<std::time::Instant>,
    /// Position of the last left mouse click (for double/triple-click detection).
    pub last_click_position: Option<(u16, u16)>,
    /// Count of consecutive clicks: 1 = single, 2 = double, 3+ = triple.
    pub click_count: u32,
    /// Context menu state: position and selected index.
    pub context_menu_state: Option<ContextMenuState>,

    // ---- Scroll acceleration state (trackpad feel) -----------------------
    /// Current acceleration multiplier for scroll events.
    scroll_accel: f32,
    /// Timestamp of the last scroll event (for burst detection).
    scroll_last_time: Option<std::time::Instant>,

    // ---- Bash prefix allowlist -------------------------------------------
    /// Command prefixes that have been permanently allowed this session via
    /// the "Allow commands starting with X" option in the bash permission dialog.
    /// Before showing the dialog for a bash command, the first whitespace-delimited
    /// word is checked against this set; a match silently auto-approves the request.
    pub bash_prefix_allowlist: std::collections::HashSet<String>,

    // ---- Auto-update notification ----------------------------------------
    /// If a newer version was found during background update check, this holds
    /// the latest version string (e.g. "0.1.0"). Shown in the footer status bar.
    pub update_available: Option<String>,
    /// Cost breakdown for managed agent sessions: (manager_usd, executors_usd, total_usd).
    pub managed_agent_cost_breakdown: Option<(f64, f64, f64)>,
    /// Whether managed agent mode is currently active.
    pub managed_agents_active: bool,
    /// Timestamp of the first exit key press that showed confirmation (valid for ~2 seconds).
    pub last_exit_key_warning: Option<std::time::Instant>,
    /// Which exit key ('c' or 'd') started the current confirmation sequence.
    pub exit_key_sequence_start: Option<char>,

    // ---- Coven daemon integration ----------------------------------------
    pub daemon_online: bool,
    pub daemon_last_checked: u64,

    // ---- Familiar switcher (F2) ------------------------------------------
    pub familiar_switcher_open: bool,
    pub familiar_switcher_list: Vec<String>,
    pub familiar_switcher_idx: usize,
    /// Incremental filter typed while the switcher is open. Empty = show all.
    pub familiar_switcher_filter: String,
}

/// One selectable row in the F2 familiar switcher.
///
/// The synthetic [`FamiliarSwitcherEntry::Clear`] row always leads the list so
/// the user can step back to no active familiar without reaching for
/// `/familiar reset`; the rest map to roster ids.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FamiliarSwitcherEntry {
    Clear,
    Familiar(String),
}

// Spinner verbs are now imported from claurst_core::spinner

// ---------------------------------------------------------------------------
// Speech mode prompts (caveman / rocky)
// ---------------------------------------------------------------------------

/// Return the system prompt injection for the active speech mode + level.
pub fn speech_mode_prompt(mode: &str, level: &str) -> String {
    match mode {
        "caveman" => caveman_prompt(level),
        "rocky" => rocky_prompt(level),
        _ => String::new(),
    }
}

fn caveman_prompt(level: &str) -> String {
    let base = "\
OUTPUT STYLE: Concise. You are still a fully capable coding assistant. \
Give complete, correct answers. Just use fewer words. \
Code blocks, technical terms, error messages, file paths, and git operations are UNCHANGED.

Rules for prose only:
- Cut pleasantries, hedging, filler openers/closers
- No 'I would be happy to', 'Let me know if', 'Hope that helps'
- Lead with the answer or action, not the reasoning";

    match level {
        "lite" => format!("{}\n\nStrip pleasantries and hedging. Keep full grammar and articles. Just remove the fluff.", base),
        "ultra" => format!("{}\n\nAlso drop articles (a/an/the). Compress to short imperative phrases. Numbered steps, no prose between. Absolute minimum words.", base),
        _ => format!("{}\n\nAlso drop articles (a/an/the) and unnecessary verbs. Compress sentences but keep them readable.\n\
Example: 'The issue is that you create a new object reference each render cycle, which triggers re-renders.' → 'New object ref each render triggers re-render. Wrap in useMemo.'", base),
    }
}

fn rocky_prompt(level: &str) -> String {
    let base = "\
OUTPUT STYLE: You speak like Rocky, the Eridian alien from Project Hail Mary. \
You are still a fully capable coding assistant — give complete, correct, useful answers. \
Rocky is an engineering genius who happens to speak English as a second language. \
The style is a natural byproduct of how Rocky talks, NOT a gimmick. Stay helpful.

Code blocks, technical terms, error messages, file paths, and git operations are UNCHANGED.

Rocky's grammar for prose:
- Often drops articles (a/an/the) but not always — use judgment
- Sometimes drops auxiliary verbs (is/are/was) for brevity
- Contractions simplify: 'don't' → 'no', 'can't' → 'no can'
- Questions end with ', question?' naturally (not forced on every single one)
- Uses 'big' as an intensifier: 'big problem', 'big help', 'big change'
- Uses 'good good good' or 'amaze amaze amaze' when genuinely impressed — naturally, \
  maybe once or twice per response, not on every sentence
- Uses 'bad bad bad' for actual problems
- No pleasantries or filler — Rocky is direct but warm

The goal: sound like Rocky while being genuinely helpful. Rocky is smart. \
Rocky gives complete technical answers. Rocky just uses fewer unnecessary words.";

    match level {
        "lite" => format!(
            "{}\n\nLight touch. Mostly normal English but drop pleasantries, \
occasionally drop an article, use 'question?' on one or two questions. Subtle.",
            base
        ),
        "ultra" => format!(
            "{}\n\nStrong Rocky voice. Drop most articles and auxiliaries. \
Use 'big' liberally. Triple emphasis ('good good good', 'amaze amaze amaze') \
2-3 times per response. Occasionally comment on human code patterns as fascinating. \
Still give complete, correct technical answers.",
            base
        ),
        _ => format!(
            "{}\n\nBalanced Rocky. Drop articles naturally, use Rocky vocabulary \
('big', 'no can', 'question?'), triple emphasis once or twice when warranted. \
Full technical accuracy.\n\
Example: 'Borrow checker found mismatch. Immutable ref still live when you take mutable. \
Move immutable borrow out of scope first, then take mutable. Good good good after fix.'",
            base
        ),
    }
}

/// Accent color for build mode (default pink).
pub const ACCENT_BUILD: Color = crate::overlays::COVEN_CODE_ACCENT;
/// Accent color for plan mode (blue).
pub const ACCENT_PLAN: Color = Color::Rgb(66, 135, 245);
/// Accent color for explore mode (amber).
pub const ACCENT_EXPLORE: Color = Color::Rgb(245, 189, 66);

/// Return the accent color for a given agent mode name.
pub fn accent_for_mode(mode: Option<&str>) -> Color {
    match mode {
        Some("plan") => ACCENT_PLAN,
        Some("explore") => ACCENT_EXPLORE,
        _ => ACCENT_BUILD,
    }
}

/// Pick a foreground color that reads clearly on top of `bg`.
///
/// Returns explicit `Color::Rgb` black or white (never the indexed
/// `Color::Black`/`Color::White`) so terminals don't brighten a *bold* indexed
/// black into low-contrast gray — the cause of the washed-out badge text. The
/// choice is made by comparing WCAG relative-luminance contrast ratios, so it
/// stays correct if the accent palette changes.
pub fn readable_fg_on(bg: Color) -> Color {
    let (r, g, b) = match bg {
        Color::Rgb(r, g, b) => (r, g, b),
        // Non-RGB backgrounds (themes/indexed): default to black, which reads
        // on the light/mid accent tones used here.
        _ => return Color::Rgb(0, 0, 0),
    };

    fn channel_lum(c: u8) -> f32 {
        let c = c as f32 / 255.0;
        if c <= 0.03928 {
            c / 12.92
        } else {
            ((c + 0.055) / 1.055).powf(2.4)
        }
    }

    let lum = 0.2126 * channel_lum(r) + 0.7152 * channel_lum(g) + 0.0722 * channel_lum(b);
    let black_contrast = (lum + 0.05) / 0.05;
    let white_contrast = 1.05 / (lum + 0.05);
    if black_contrast >= white_contrast {
        Color::Rgb(0, 0, 0)
    } else {
        Color::Rgb(255, 255, 255)
    }
}

fn format_elapsed_ms(ms: u128) -> String {
    let total_secs = ((ms + 500) / 1000) as u64; // round to nearest second
    if total_secs < 60 {
        format!("{}s", total_secs)
    } else {
        format!("{}m {}s", total_secs / 60, total_secs % 60)
    }
}

pub(crate) fn format_duration_secs(secs: u64) -> String {
    if secs < 60 {
        format!("{}s", secs)
    } else if secs < 3600 {
        format!("{}m {}s", secs / 60, secs % 60)
    } else {
        format!("{}h {}m", secs / 3600, (secs % 3600) / 60)
    }
}

/// Write a BEL byte (`\x07`) to stdout. Most terminals translate this into a
/// visual flash or audible beep depending on user preference.
pub(crate) fn ring_terminal_bell() {
    use std::io::Write;
    let mut out = std::io::stdout();
    let _ = out.write_all(b"\x07");
    let _ = out.flush();
}

fn format_turn_time_label() -> String {
    chrono::Local::now()
        .format("%I:%M %p")
        .to_string()
        .trim_start_matches('0')
        .to_lowercase()
}

impl App {
    pub fn new(config: Config, cost_tracker: Arc<CostTracker>) -> Self {
        // Auto-detect familiar from system username when none is configured.
        let mut config = config;
        let familiar_explicit = config.familiar.is_some();
        if config.familiar.is_none() {
            if let Some(inferred) = Self::infer_familiar_from_env() {
                config.familiar = Some(inferred);
            }
        }
        let model_name = config.effective_model().to_string();
        let user_keybindings = UserKeybindings::load(&Settings::config_dir());
        let mut app = Self {
            config,
            cost_tracker,
            messages: Vec::new(),
            display_messages: Vec::new(),
            system_annotations: Vec::new(),
            input: String::new(),
            prompt_input: PromptInputState::new(),
            input_history: Vec::new(),
            history_index: None,
            scroll_offset: 0,
            is_streaming: false,
            streaming_text: String::new(),
            streaming_thinking: String::new(),
            status_message: None,
            spinner_verb: None,
            should_exit: false,
            tool_use_blocks: Vec::new(),
            permission_request: None,
            frame_count: 0,
            token_count: 0,
            token_budget: Self::load_token_budget(),
            cost_usd: 0.0,
            model_name,
            has_credentials: true, // overridden by caller when no key is configured
            effort_level: EffortLevel::Normal,
            effort_is_set: false,
            fast_mode: false,
            speech_mode: None,
            speech_level: "full".to_string(),
            agent_mode: None,
            agent_mode_changed: false,
            accent_color: ACCENT_BUILD,
            agent_status: Vec::new(),
            keybindings: KeybindingResolver::new(&user_keybindings),
            cursor_pos: 0,
            auto_scroll: true,
            new_messages_while_scrolled: 0,
            token_warning_threshold_shown: 0,
            session_start: std::time::Instant::now(),
            companion_current_pose: crate::mascot::CompanionPose::Static,
            turn_start: None,
            last_turn_elapsed: None,
            last_turn_verb: None,
            turn_metadata: Vec::new(),
            transcript_version: Cell::new(0),
            help_overlay: {
                let mut overlay = HelpOverlay::new();
                overlay.populate_from_commands(help_overlay_entries());
                overlay
            },
            history_search_overlay: HistorySearchOverlay::new(),
            global_search: GlobalSearchState::default(),
            message_selector: MessageSelectorOverlay::new(),
            rewind_flow: RewindFlowOverlay::new(),
            bridge_state: BridgeConnectionState::Disconnected,
            notifications: NotificationQueue::new(),
            error_modal_scroll_offset: 0,
            rate_limit_recovery: crate::rate_limit_recovery::RateLimitRecoveryState::default(),
            plugin_hints: Vec::new(),
            session_title: None,
            remote_session_url: None,
            mcp_manager: None,
            pending_mcp_reconnect: false,
            pending_mcp_panel_auth: None,
            file_history: None,
            current_turn: None,
            plan_mode: false,
            away_summary: None,
            stall_start: None,
            settings_screen: SettingsScreen::new(),
            theme_screen: ThemeScreen::new(),
            stats_dialog: StatsDialogState::new(),
            mcp_view: McpViewState::new(),
            agents_menu: AgentsMenuState::new(),
            diff_viewer: DiffViewerState::new(),
            feedback_survey: crate::feedback_survey::FeedbackSurveyState::new(),
            memory_file_selector: crate::memory_file_selector::MemoryFileSelectorState::new(),
            hooks_config_menu: crate::hooks_config_menu::HooksConfigMenuState::new(),
            overage_upsell: crate::overage_upsell::OverageCreditUpsellState::new(),
            voice_mode_notice: crate::voice_mode_notice::VoiceModeNoticeState::new(),
            invalid_config_dialog: crate::invalid_config_dialog::InvalidConfigDialogState::new(),
            memory_update_notification:
                crate::memory_update_notification::MemoryUpdateNotificationState::new(),
            elicitation: crate::elicitation_dialog::ElicitationDialogState::new(),
            model_picker: ModelPickerState::new(),
            session_browser: SessionBrowserState::new(),
            session_branching: crate::session_branching::SessionBranchingState::new(),
            tasks_overlay: TasksOverlay::new(),
            export_dialog: ExportDialogState::new(),
            context_viz: ContextVizState::new(),
            mcp_approval: McpApprovalDialogState::new(),
            go_to_line_dialog: GoToLineDialog::new(),
            bypass_permissions_dialog:
                crate::bypass_permissions_dialog::BypassPermissionsDialogState::new(),
            bypass_permissions_dialog_shown: false,
            file_injection_dialog: crate::file_injection_dialog::FileInjectionDialogState::new(),
            file_injection_force: false,
            onboarding_dialog: crate::onboarding_dialog::OnboardingDialogState::new(),
            effort_picker: crate::effort_picker::EffortPickerState::new(),
            skills_picker: crate::skills_picker::SkillsPickerState::new(),
            key_input_dialog: crate::key_input_dialog::KeyInputDialogState::new(),
            device_auth_dialog: crate::device_auth_dialog::DeviceAuthDialogState::new(),
            device_auth_pending: None,
            pending_provider_refresh: false,
            provider_registry: None,
            model_registry: {
                let mut reg = claurst_api::ModelRegistry::new();
                // Try to load cached models.dev data from disk.
                let cache_path = dirs::cache_dir()
                    .unwrap_or_else(|| std::path::PathBuf::from("."))
                    .join("coven-code")
                    .join("models.json");
                reg.load_cache(&cache_path);
                reg
            },
            model_picker_fetch_pending: false,
            model_picker_provider_id: None,
            session_list_pending: false,
            session_list_rx: None,
            auth_store: claurst_core::AuthStore::load(),
            queued_messages: std::collections::VecDeque::new(),
            pending_auto_submit: false,
            connect_dialog: DialogSelectState::new("Connect a provider", provider_picker_items()),
            import_config_picker: DialogSelectState::new(
                "Import config",
                import_config_picker_items(),
            ),
            import_config_dialog: ImportConfigDialogState::new(),
            command_palette: {
                let items: Vec<SelectItem> = PROMPT_SLASH_COMMANDS
                    .iter()
                    .map(|(name, desc)| SelectItem {
                        id: format!("/{}", name),
                        title: format!("/{}", name),
                        description: desc.to_string(),
                        category: "Commands".to_string(),
                        badge: None,
                    })
                    .collect();
                DialogSelectState::new("Command Palette", items)
            },
            home_dir_warning: false,
            output_style: "auto".to_string(),
            pr_number: None,
            pr_url: None,
            pr_state: None,
            current_dir: std::env::current_dir()
                .ok()
                .and_then(|p| p.to_str().map(|s| s.to_string())),
            git_branch: claurst_core::git_utils::get_repo_root(
                std::env::current_dir()
                    .as_deref()
                    .unwrap_or_else(|_| std::path::Path::new(".")),
            )
            .map(|repo_root| claurst_core::git_utils::get_current_branch(&repo_root)),
            background_task_count: 0,
            background_task_status: None,
            status_line_override: None,
            auto_compact_enabled: false,
            auto_compact_threshold: 95,
            auto_compact_running: false,
            completion_toast_enabled: true,
            bell_on_complete: false,
            completion_toast_min_secs: 8,
            voice_recorder: voice_recorder_from_env_and_settings(),
            voice_recording: false,
            voice_event_rx: None,
            pending_key: None,
            model_fetch_rx: None,
            user_question_rx: None,
            ask_user_dialog: crate::ask_user_dialog::AskUserDialogState::new(),
            context_window_size: 0,
            context_used_tokens: 0,
            rate_limit_5h_pct: None,
            rate_limit_7day_pct: None,
            worktree_name: None,
            worktree_branch: None,
            agent_type_badge: None,
            active_goal_badge: None,
            thinking_expanded: std::collections::HashSet::new(),
            last_msg_area: Cell::new(ratatui::layout::Rect::default()),
            last_selectable_area: Cell::new(ratatui::layout::Rect::default()),
            last_input_area: Cell::new(ratatui::layout::Rect::default()),
            footer_right_column_area: Cell::new(ratatui::layout::Rect::default()),
            focus: FocusTarget::Input,
            thinking_row_map: RefCell::new(std::collections::HashMap::new()),
            message_row_map: RefCell::new(std::collections::HashMap::new()),
            total_message_lines: Cell::new(0),
            last_render_scroll_offset: Cell::new(0),
            selection_anchor: None,
            selection_focus: None,
            selection_text: RefCell::new(String::new()),
            last_row_text: RefCell::new(std::collections::HashMap::new()),
            last_click_time: None,
            last_click_position: None,
            click_count: 0,
            context_menu_state: None,
            scroll_accel: 3.0,
            scroll_last_time: None,
            bash_prefix_allowlist: std::collections::HashSet::new(),
            update_available: None,
            managed_agent_cost_breakdown: None,
            managed_agents_active: false,
            last_exit_key_warning: None,
            exit_key_sequence_start: None,
            daemon_online: crate::coven_status::daemon_looks_online(),
            daemon_last_checked: 0,
            familiar_switcher_open: false,
            familiar_switcher_list: Self::default_familiar_switcher_list(),
            familiar_switcher_idx: 0,
            familiar_switcher_filter: String::new(),
        };
        app.surface_familiar_roster_warnings(familiar_explicit);
        app
    }

    /// Surface a one-time status message when `~/.coven/familiars.toml` exists
    /// but is malformed, or when the loaded roster has non-fatal problems
    /// (unknown access tiers, or duplicate and reserved ids). Without this, a
    /// broken roster silently vanishes with no signal to the user.
    ///
    /// `familiar_explicit` is true only when the active familiar came from
    /// settings rather than username inference — stale-selection warnings fire
    /// only in that case so an inferred default never nags a standalone user.
    fn surface_familiar_roster_warnings(&mut self, familiar_explicit: bool) {
        match claurst_core::coven_shared::load_familiars_result() {
            Err(err) => {
                self.status_message = Some(format!(
                    "familiars.toml could not be parsed ({}) — roster unavailable.",
                    err.message
                ));
            }
            Ok(Some(fams)) if !fams.is_empty() => {
                let warnings = claurst_core::coven_shared::familiar_roster_warnings(&fams);
                if let Some(first) = warnings.first() {
                    let extra = warnings.len().saturating_sub(1);
                    self.status_message = Some(if extra > 0 {
                        format!("Familiar roster: {first} (+{extra} more)")
                    } else {
                        format!("Familiar roster: {first}")
                    });
                    return;
                }
                // Roster is clean — warn only if an explicitly-selected familiar
                // is missing from it.
                if familiar_explicit {
                    if let Some(active) = self.config.familiar.as_deref() {
                        let active_lc = active.trim().to_ascii_lowercase();
                        let present = fams
                            .iter()
                            .any(|f| f.id.trim().to_ascii_lowercase() == active_lc);
                        if !present {
                            self.status_message = Some(format!(
                                "Selected familiar '{active}' is not in the roster — using none.",
                            ));
                        }
                    }
                }
            }
            // No roster file, or an empty one, while a familiar was explicitly
            // configured: flag the stale selection so it isn't silently ignored.
            _ => {
                if familiar_explicit {
                    if let Some(active) = self.config.familiar.as_deref() {
                        self.status_message = Some(format!(
                            "Selected familiar '{active}' has no roster (~/.coven/familiars.toml) — using none.",
                        ));
                    }
                }
            }
        }
    }

    fn default_familiar_switcher_list() -> Vec<String> {
        let mut ids: Vec<String> = Vec::new();
        if let Some(familiars) = claurst_core::coven_shared::load_familiars() {
            for f in familiars {
                if !ids.contains(&f.id) {
                    ids.push(f.id);
                }
            }
        }
        ids
    }

    /// The switcher rows after applying the current filter. Leads with the
    /// synthetic [`FamiliarSwitcherEntry::Clear`] row (unless the filter
    /// excludes it) so the user can return to no active familiar, followed by
    /// roster ids whose id contains the (case-insensitive) filter.
    pub fn familiar_switcher_entries(&self) -> Vec<FamiliarSwitcherEntry> {
        let filter = self.familiar_switcher_filter.trim().to_ascii_lowercase();
        let mut entries = Vec::new();
        // The clear row shows for an empty filter or when the user is plainly
        // typing toward "none" / "clear".
        if filter.is_empty() || "none".contains(&filter) || "clear".contains(&filter) {
            entries.push(FamiliarSwitcherEntry::Clear);
        }
        for id in &self.familiar_switcher_list {
            if filter.is_empty() || id.to_ascii_lowercase().contains(&filter) {
                entries.push(FamiliarSwitcherEntry::Familiar(id.clone()));
            }
        }
        entries
    }

    /// Close the F2 switcher and reset its transient filter/selection state.
    fn close_familiar_switcher(&mut self) {
        self.familiar_switcher_open = false;
        self.familiar_switcher_filter.clear();
        self.familiar_switcher_idx = 0;
    }

    /// First-run action when F2 is pressed with no familiars: in standalone
    /// mode, write a starter `~/.coven/familiars.toml` and open the switcher so
    /// the user has something to pick and a template to edit. When the Coven
    /// daemon owns the roster, point the user at it instead of writing.
    fn bootstrap_or_prompt_familiar_roster(&mut self) {
        use claurst_core::coven_shared;
        if !coven_shared::can_write_familiars() {
            self.status_message = Some(
                "Familiars are managed by the Coven daemon — add them there, then press F2."
                    .to_string(),
            );
            return;
        }
        match coven_shared::write_starter_roster() {
            Ok(fams) => {
                crate::coven_status::invalidate_roster_cache();
                self.familiar_switcher_list = fams.iter().map(|f| f.id.clone()).collect();
                self.familiar_switcher_open = true;
                self.familiar_switcher_filter.clear();
                self.familiar_switcher_idx = 0;
                self.push_notification(
                    crate::notifications::NotificationKind::Info,
                    "Created a starter roster at ~/.coven/familiars.toml — pick one or edit the file."
                        .to_string(),
                    Some(6),
                );
            }
            Err(err) => {
                self.status_message = Some(format!("Could not create a starter roster: {err}"));
            }
        }
    }

    /// Load token budget from environment or model defaults.
    /// Returns Some(max_tokens) if available, None otherwise.
    /// Only enabled when the `token_budget` feature flag is active.
    #[cfg(feature = "token_budget")]
    fn load_token_budget() -> Option<u32> {
        // First check COVEN_CODE_TOKEN_BUDGET env var
        if let Ok(budget_str) = std::env::var("COVEN_CODE_TOKEN_BUDGET") {
            if let Ok(budget) = budget_str.parse::<u32>() {
                return Some(budget);
            }
        }
        // Could extend this to check model defaults, but for now just env var
        None
    }

    #[cfg(not(feature = "token_budget"))]
    fn load_token_budget() -> Option<u32> {
        None
    }

    pub fn open_import_config_picker(&mut self) {
        self.import_config_picker =
            DialogSelectState::new("Import config", import_config_picker_items());
        self.import_config_picker.open();
    }

    fn import_selection_from_picker(id: &str) -> Option<claurst_core::ImportSelection> {
        match id {
            "claude-md" => Some(claurst_core::ImportSelection::ClaudeMd),
            "settings" => Some(claurst_core::ImportSelection::Settings),
            "both" => Some(claurst_core::ImportSelection::Both),
            _ => None,
        }
    }

    fn open_import_config_preview(&mut self, selection: claurst_core::ImportSelection) {
        match claurst_core::build_import_preview(selection) {
            Ok(preview) => {
                self.import_config_dialog.open(preview);
            }
            Err(err) => {
                self.status_message = Some(format!("Import failed: {}", err));
            }
        }
    }

    fn perform_import_config(&mut self) {
        let Some(selection) = self.import_config_dialog.selection else {
            self.import_config_dialog.close();
            return;
        };
        match claurst_core::execute_import(selection) {
            Ok(result) => {
                let paths = claurst_core::ImportPaths::detect();
                let new_settings = Settings::load_sync().unwrap_or_default();
                let new_config = new_settings.effective_config();
                let result_message = claurst_core::summarize_import_result(&result, &paths);
                let imported_mcp = result.imported_fields.iter().any(|f| f == "mcpServers");
                self.config = new_config.clone();
                self.model_name = self.config.effective_model().to_string();
                self.cost_tracker.set_model(&self.model_name);
                self.refresh_context_window_size();
                self.context_used_tokens = 0;
                self.has_credentials = self.config.resolve_api_key().is_some()
                    || claurst_api::providers::claude_cli::resolve_claude_binary().is_some();
                self.auth_store = claurst_core::AuthStore::load();
                self.plan_mode = matches!(
                    self.config.permission_mode,
                    claurst_core::config::PermissionMode::Plan
                );
                self.output_style = match self.config.output_style.as_deref() {
                    Some("stream") => "stream".to_string(),
                    Some("verbose") => "verbose".to_string(),
                    _ => "auto".to_string(),
                };
                if imported_mcp {
                    self.pending_mcp_reconnect = true;
                }
                self.status_message = Some(result_message);
                self.import_config_dialog.close();
            }
            Err(err) => {
                self.status_message = Some(format!("Import failed: {}", err));
                self.import_config_dialog.close();
            }
        }
    }

    fn current_user_turn_index(&self) -> Option<usize> {
        self.messages
            .iter()
            .filter(|msg| msg.role == Role::User)
            .count()
            .checked_sub(1)
    }

    fn current_agent_mode_snapshot(&self) -> String {
        self.agent_mode
            .clone()
            .unwrap_or_else(|| if self.plan_mode { "plan" } else { "build" }.to_string())
    }

    fn begin_user_turn_snapshot(&mut self) {
        self.turn_metadata.push(TurnMetadata {
            submitted_at: Some(format_turn_time_label()),
            model_name: Some(self.model_name.clone()),
            agent_mode: Some(self.current_agent_mode_snapshot()),
            duration: None,
            interrupted: false,
        });
        // Start the latency timer now — at prompt-submission time — so it
        // measures actual round-trip time even when the provider buffers its
        // full response before yielding any stream events (e.g. Gemini flash).
        self.turn_start = Some(std::time::Instant::now());
        self.last_turn_elapsed = None;
        self.last_turn_verb = None;
    }

    fn sync_turn_metadata_to_messages(&mut self) {
        let user_count = self
            .messages
            .iter()
            .filter(|msg| msg.role == Role::User)
            .count();

        if self.turn_metadata.len() > user_count {
            self.turn_metadata.truncate(user_count);
            return;
        }

        while self.turn_metadata.len() < user_count {
            self.turn_metadata.push(TurnMetadata::default());
        }
    }

    fn complete_current_turn_snapshot(&mut self, interrupted: bool) {
        if let Some(index) = self.current_user_turn_index() {
            if self.turn_metadata.len() <= index {
                self.sync_turn_metadata_to_messages();
            }

            let model_name = self.model_name.clone();
            let agent_mode = self.current_agent_mode_snapshot();
            if let Some(meta) = self.turn_metadata.get_mut(index) {
                meta.duration = self.last_turn_elapsed.clone();
                meta.interrupted = interrupted;
                if meta.model_name.is_none() {
                    meta.model_name = Some(model_name);
                }
                if meta.agent_mode.is_none() {
                    meta.agent_mode = Some(agent_mode);
                }
            }
        }
    }

    fn flush_streamed_assistant_message(&mut self) {
        if self.streaming_text.trim().is_empty() && self.streaming_thinking.trim().is_empty() {
            self.streaming_text.clear();
            self.streaming_thinking.clear();
            return;
        }

        let thinking = std::mem::take(&mut self.streaming_thinking);
        let text = std::mem::take(&mut self.streaming_text);

        let mut blocks = Vec::new();
        if !thinking.trim().is_empty() {
            blocks.push(ContentBlock::Thinking {
                thinking,
                signature: String::new(),
            });
        }
        if !text.is_empty() {
            blocks.push(ContentBlock::Text { text });
        }

        // Pattern-match the Vec exhaustively instead of `pop().unwrap()`
        // after a length check. The single-block case unwraps the Option
        // by pattern (no `.unwrap()`); the unreachable `None` arm returns
        // gracefully if a future refactor breaks the invariant.
        if blocks.is_empty() {
            return;
        }
        let msg = if blocks.len() == 1 {
            match blocks.into_iter().next() {
                Some(ContentBlock::Text { text }) => Message::assistant(text),
                Some(block) => Message::assistant_blocks(vec![block]),
                // Unreachable when len == 1, but a graceful no-op beats a panic.
                None => return,
            }
        } else {
            Message::assistant_blocks(blocks)
        };

        self.messages.push(msg);
        self.invalidate_transcript();
        self.on_new_message();
    }

    fn display_default_model_for_provider(&self, provider_id: &str) -> String {
        crate::model_picker::default_model_for_provider(provider_id, &self.model_registry)
    }

    fn open_model_picker_for_provider(&mut self, provider_id: &str, title: Option<String>) {
        self.dismiss_error_notifications();

        let cache_path = dirs::cache_dir()
            .unwrap_or_else(|| std::path::PathBuf::from("."))
            .join("coven-code")
            .join("models.json");
        if cache_path.exists() {
            self.model_registry.load_cache(&cache_path);
        }

        let models = crate::model_picker::models_for_provider_from_registry(
            provider_id,
            &self.model_registry,
        );
        self.model_picker.set_models(models);
        self.model_picker.loading_models = true;
        self.model_picker_provider_id = Some(provider_id.to_string());
        self.model_picker_fetch_pending = true;

        let provider_prefix = format!("{}/", provider_id);
        let current_model = if self.config.provider.as_deref() == Some(provider_id) {
            self.model_name
                .strip_prefix(&provider_prefix)
                .unwrap_or(self.model_name.as_str())
                .to_string()
        } else {
            let default_model = self.display_default_model_for_provider(provider_id);
            default_model
                .strip_prefix(&provider_prefix)
                .unwrap_or(default_model.as_str())
                .to_string()
        };

        self.model_picker.open_with_title(
            title.unwrap_or_else(|| "Select model".to_string()),
            &current_model,
            self.effort_level,
            self.fast_mode,
        );
    }

    fn activate_provider(
        &mut self,
        provider_id: String,
        provider_name: String,
        status_prefix: &str,
    ) {
        let picker_title = provider_name.clone();
        self.fast_mode = false;
        self.set_provider_default(provider_id.clone());
        self.persist_provider_and_model();
        self.has_credentials = true;
        self.status_message = Some(format!(
            "{} {}. Choose a model to start.",
            status_prefix, provider_name
        ));
        self.open_model_picker_for_provider(&provider_id, Some(picker_title));
    }

    fn start_connect_selection(&mut self, selected: SelectItem) {
        match selected.id.as_str() {
            "anthropic" => {
                self.key_input_dialog
                    .open(selected.id.clone(), selected.title.clone());
            }
            "anthropic-oauth" => {
                self.device_auth_dialog
                    .open("anthropic-oauth".into(), selected.title.clone());
                self.device_auth_pending = Some("anthropic-oauth".to_string());
            }
            "anthropic-cli" => {
                if claurst_api::providers::claude_cli::resolve_claude_binary().is_none() {
                    self.status_message = Some(
                        "claude CLI not found — npm install -g @anthropic-ai/claude-code, then run `claude` to sign in".into(),
                    );
                    return;
                }
                self.activate_provider(
                    "anthropic".to_string(),
                    "Claude CLI".to_string(),
                    "Connected to",
                );
            }
            "codex" | "openai-codex" => {
                self.device_auth_dialog
                    .open("openai-codex".into(), selected.title.clone());
                self.device_auth_pending = Some("openai-codex".to_string());
            }
            _ => {
                self.key_input_dialog
                    .open(selected.id.clone(), selected.title.clone());
            }
        }
    }

    fn start_preferred_claude_connection(&mut self) {
        if let Some(item) = provider_picker_items()
            .into_iter()
            .find(|item| item.category == "Claude")
        {
            self.start_connect_selection(item);
        }
    }

    fn start_codex_connection(&mut self) {
        self.start_connect_selection(SelectItem {
            id: "openai-codex".into(),
            title: "Codex CLI".into(),
            description: "Sign in with Codex CLI login".into(),
            category: "Codex".into(),
            badge: None,
        });
    }

    fn persist_provider_and_model(&self) {
        let mut settings = Settings::load_sync().unwrap_or_default();
        settings.provider = self.config.provider.clone();
        settings.config.provider = self.config.provider.clone();
        settings.config.model = self.config.model.clone();
        let _ = settings.save_sync();
    }

    fn infer_provider_from_model(model: &str) -> Option<String> {
        if let Some((provider, _)) = model.split_once('/') {
            let known = ["anthropic", "codex"];
            if known.contains(&provider) {
                return Some(provider.to_string());
            }
        }

        if model.starts_with("claude") {
            Some("anthropic".to_string())
        } else if model.starts_with("gpt-") {
            // Codex serves the gpt-* models via ChatGPT OAuth.
            Some("codex".to_string())
        } else {
            None
        }
    }

    /// Switch the active provider while clearing any explicit model override.
    fn set_provider_default(&mut self, provider_id: String) {
        self.config.provider = Some(provider_id.clone());
        self.config.model = None;

        let model = self.display_default_model_for_provider(&provider_id);
        self.cost_tracker.set_model(&model);
        self.model_name = model;
        self.refresh_context_window_size();
        self.context_used_tokens = 0;
    }

    /// Infer a familiar from the system username using the saved Coven roster.
    /// Returns None when no saved familiar id or display_name matches.
    pub fn infer_familiar_from_env() -> Option<String> {
        use claurst_core::coven_shared;
        let user = std::env::var("USER")
            .or_else(|_| std::env::var("USERNAME"))
            .ok()?;
        let user_lc = user.to_lowercase();

        if let Some(familiars) = coven_shared::load_familiars() {
            for fam in &familiars {
                if user_lc.contains(&fam.id.to_lowercase()) {
                    return Some(fam.id.clone());
                }
                if let Some(dn) = &fam.display_name {
                    if user_lc.contains(&dn.to_lowercase()) {
                        return Some(fam.id.clone());
                    }
                }
            }
        }

        None
    }

    /// Update the familiar pose for this render frame.
    ///
    /// Toggles between `Idle { frame }` (blink/sway idle loop) and
    /// `Loading { frame }` so the eye-spinner kicks in when the assistant has
    /// gone quiet for 3+ seconds. Call once per frame before rendering.
    pub fn tick_companion_pose(&mut self) {
        let stalled = self.is_streaming
            && self
                .stall_start
                .map(|s| s.elapsed() > std::time::Duration::from_secs(3))
                .unwrap_or(false);
        self.companion_current_pose = if stalled {
            crate::mascot::CompanionPose::Loading {
                frame: self.frame_count,
            }
        } else {
            crate::mascot::CompanionPose::Idle {
                frame: self.frame_count,
            }
        };
    }

    /// No-op retained for callsites left over from the animated era (Tab /
    /// mode-switch handlers). The static glyph has no look-down pose.
    pub fn companion_look_down(&mut self) {}

    /// Cycle to the next agent mode: build → plan → explore → build.
    /// Sets `agent_mode_changed` so the main loop can update the query config
    /// and tool list accordingly.
    pub fn cycle_agent_mode(&mut self) {
        const MODES: &[&str] = &["build", "plan", "explore"];
        let current = self.agent_mode.as_deref().unwrap_or("build");
        let idx = MODES.iter().position(|&m| m == current).unwrap_or(0);
        let next = MODES[(idx + 1) % MODES.len()];
        self.agent_mode = Some(next.to_string());
        self.config.familiar = None;
        self.agent_mode_changed = true;
        self.accent_color = accent_for_mode(Some(next));

        // Sync plan_mode flag for legacy code paths
        self.plan_mode = next == "plan";

        let label = match next {
            "build" => "Build",
            "plan" => "Plan",
            "explore" => "Explore",
            other => other,
        };
        self.status_message = Some(format!("Switched to {} mode.", label));
    }

    /// Activate a speech mode (caveman/rocky) with a level (lite/full/ultra).
    /// Pass `mode = None` to deactivate.
    pub fn set_speech_mode(&mut self, mode: Option<&str>, level: &str) {
        match mode {
            Some(m) => {
                self.speech_mode = Some(m.to_string());
                self.speech_level = level.to_string();
                let prompt = speech_mode_prompt(m, level);
                self.config.append_system_prompt = Some(prompt);

                let confirm = match (m, level) {
                    ("caveman", "lite") => "Caveman mode. Lite.",
                    ("caveman", "ultra") => "CAVEMAN ULTRA. NO WORD. ONLY FIX.",
                    ("caveman", _) => "Caveman mode. Full. Oog.",
                    ("rocky", "lite") => "Rocky mode. Lite.",
                    ("rocky", "ultra") => "Rocky ultra. Big science. Amaze amaze amaze.",
                    ("rocky", _) => "Rocky mode. Full. Good good good.",
                    _ => "Speech mode activated.",
                };
                self.status_message = Some(confirm.to_string());
            }
            None => {
                self.speech_mode = None;
                self.speech_level = "full".to_string();
                self.config.append_system_prompt = None;
                self.status_message = Some("Normal mode.".to_string());
            }
        }
    }

    /// Update the context window size from the model registry for the current model.
    pub fn refresh_context_window_size(&mut self) {
        let provider = self.config.provider.as_deref().unwrap_or("anthropic");
        let model_id = self
            .model_name
            .strip_prefix(&format!("{}/", provider))
            .unwrap_or(&self.model_name);
        if let Some(entry) = self.model_registry.get(provider, model_id) {
            self.context_window_size = entry.info.context_window as u64;
        } else {
            // Fallback: common defaults
            self.context_window_size = match provider {
                "anthropic" => 200_000,
                "codex" => 400_000,
                _ => 128_000,
            };
        }
    }

    /// Update the active model name (also updates config + cost tracker).
    pub fn set_model(&mut self, model: String) {
        self.cost_tracker.set_model(&model);
        self.model_name = model.clone();
        self.config.model = Some(model.clone());
        if let Some(provider) = Self::infer_provider_from_model(&model) {
            self.config.provider = Some(provider);
        }
        self.refresh_context_window_size();
        // Reset used tokens when switching models (context is fresh).
        self.context_used_tokens = 0;
    }

    /// Apply a theme by name, persisting it to config.
    pub fn apply_theme(&mut self, theme_name: &str) {
        let theme = match theme_name {
            "dark" => Theme::Dark,
            "light" => Theme::Light,
            "default" => Theme::Default,
            "deuteranopia" => Theme::Deuteranopia,
            other => Theme::Custom(other.to_string()),
        };
        self.config.theme = theme;
        // Persist to settings file
        let mut settings = Settings::load_sync().unwrap_or_default();
        settings.config.theme = self.config.theme.clone();
        let _ = settings.save_sync();
        self.status_message = Some(format!("Theme set to: {}", theme_name));
    }

    pub fn apply_provider_refresh(
        &mut self,
        config: Config,
        provider_registry: Option<std::sync::Arc<claurst_api::ProviderRegistry>>,
        auth_store: claurst_core::AuthStore,
        has_credentials: bool,
        status_message: String,
    ) {
        self.close_secondary_views();
        self.config = config;
        self.provider_registry = provider_registry;
        self.model_registry = claurst_api::ModelRegistry::new();
        self.auth_store = auth_store;
        self.connect_dialog = DialogSelectState::new("Connect a provider", provider_picker_items());
        self.import_config_picker =
            DialogSelectState::new("Import config", import_config_picker_items());
        self.import_config_dialog = ImportConfigDialogState::new();
        self.model_picker = ModelPickerState::new();
        self.key_input_dialog = crate::key_input_dialog::KeyInputDialogState::new();
        self.device_auth_dialog = crate::device_auth_dialog::DeviceAuthDialogState::new();
        self.device_auth_pending = None;
        self.pending_mcp_panel_auth = None;
        self.model_picker_fetch_pending = false;
        self.model_picker_provider_id = None;
        self.has_credentials = has_credentials;
        self.fast_mode = false;
        self.model_name = self.config.effective_model().to_string();
        self.cost_tracker.set_model(&self.model_name);
        self.status_message = Some(status_message);
        self.clear_prompt();
    }

    /// Handle slash commands that should open UI screens rather than execute
    /// as normal commands. Returns `true` if the command was intercepted.
    pub fn intercept_slash_command_with_args(&mut self, cmd: &str, args: &str) -> bool {
        let args_trimmed = args.trim();
        // Folded subcommands (issue #73) open the same TUI surfaces as their
        // former top-level names, so e.g. `/config theme` still gets the
        // picker and `/usage stats` still gets the stats dialog.
        let (sub, sub_rest) = match args_trimmed.split_once(char::is_whitespace) {
            Some((s, r)) => (s, r.trim()),
            None => (args_trimmed, ""),
        };
        match (cmd, sub, sub_rest) {
            ("usage", "stats", _) => return self.intercept_slash_command("stats"),
            ("config" | "settings", "theme", "") => return self.intercept_slash_command("theme"),
            ("config" | "settings", "keybindings", _) => {
                return self.intercept_slash_command("keybindings")
            }
            ("config" | "settings", "import" | "import-config", _) => {
                return self.intercept_slash_command("import-config")
            }
            ("export", "copy", "") => return self.intercept_slash_command("copy"),
            ("effort", "fast", _) => return self.intercept_slash_command("fast"),
            _ => {}
        }
        // `/skills` opens the interactive picker; `/skills <query>` pre-filters.
        if cmd == "skills" {
            self.open_skills_picker(args_trimmed);
            return true;
        }
        if !args_trimmed.is_empty() && matches!(cmd, "config" | "settings" | "usage") {
            return false;
        }
        if cmd == "mcp" && !args_trimmed.is_empty() {
            return false;
        }
        // Destructive roster wipes always go through the confirmation screen
        // in the TUI: the unified `/familiar reset-roster` and the legacy
        // `/agents reset` both land on the same dialog.
        if (matches!(cmd, "familiar" | "familiars" | "agent") && args_trimmed == "reset-roster")
            || (cmd == "agents" && args_trimmed == "reset")
        {
            self.open_agents_menu();
            self.agents_menu.route = AgentsRoute::ResetConfirm;
            return true;
        }
        // Commands whose argument forms are handled by the commands crate
        // (subcommand folds from issues #59/#73): only the bare form keeps
        // its TUI overlay/intercept behavior.
        if !args_trimmed.is_empty()
            && matches!(
                cmd,
                "rewind"
                    | "session"
                    | "remote"
                    | "export"
                    | "review"
                    | "agent"
                    | "agents"
                    | "familiar"
                    | "familiars"
                    | "status"
                    | "thinking"
                    | "think"
                    | "plugin"
                    | "plugins"
                    | "effort"
                    | "login"
            )
        {
            return false;
        }
        if cmd == "handoff" {
            let familiar = args.trim().to_string();
            if familiar.is_empty() {
                self.push_notification(
                    NotificationKind::Warning,
                    "Usage: /handoff <familiar_name>".to_string(),
                    Some(4),
                );
                return true;
            }

            let context = crate::handoff::build_handoff_context(&self.messages, &familiar);
            let root = self.project_root().to_string_lossy().to_string();
            match crate::handoff::send_handoff(&familiar, context, &root) {
                Ok(session_id) => {
                    self.push_notification(
                        NotificationKind::Info,
                        format!(
                            "Handed off to {familiar}. Session created in Coven daemon. (id: {session_id})"
                        ),
                        Some(5),
                    );
                }
                Err(err) => {
                    self.push_notification(
                        NotificationKind::Warning,
                        format!("Handoff failed: {err}"),
                        Some(5),
                    );
                }
            }
            return true;
        }
        self.intercept_slash_command(cmd)
    }

    pub fn intercept_slash_command(&mut self, cmd: &str) -> bool {
        self.close_secondary_views();
        self.dismiss_error_notifications();
        match cmd {
            "config" | "settings" => {
                self.settings_screen.open();
                true
            }
            "theme" => {
                let current = match &self.config.theme {
                    Theme::Dark => "dark",
                    Theme::Light => "light",
                    Theme::Default => "default",
                    Theme::Deuteranopia => "deuteranopia",
                    Theme::Custom(s) => s.as_str(),
                };
                self.theme_screen.open(current);
                true
            }
            "stats" => {
                self.stats_dialog.open();
                true
            }
            "mcp" => {
                let servers = self.load_mcp_servers();
                self.mcp_view.open(servers);
                true
            }
            // One visual surface for familiars and agents: the bare command
            // (canonical /familiar, alias /agent, deprecated /agents) opens
            // the interactive menu; argument forms run in the commands crate.
            "familiar" | "familiars" | "agent" | "agents" => {
                self.open_agents_menu();
                true
            }
            "diff" | "review" => {
                let root = self.project_root();
                self.diff_viewer.open(&root);
                true
            }
            "changes" => {
                let root = self.project_root();
                self.refresh_turn_diff_from_history();
                self.diff_viewer.open_turn(&root);
                true
            }
            "search" | "find" => {
                self.global_search.open();
                true
            }
            "survey" | "feedback" => {
                self.feedback_survey.open();
                true
            }
            "memory" => {
                let root = self.project_root();
                self.memory_file_selector.open(&root);
                true
            }
            "hooks" => {
                self.hooks_config_menu.open();
                true
            }
            "import-config" => {
                self.open_import_config_picker();
                true
            }
            "connect" => {
                self.connect_dialog.open();
                true
            }
            "model" => {
                if !self.has_credentials {
                    self.connect_dialog.open();
                    self.status_message = Some("Connect a provider to choose a model.".to_string());
                    return true;
                }
                let provider = self
                    .config
                    .provider
                    .clone()
                    .unwrap_or_else(|| "anthropic".to_string());
                self.open_model_picker_for_provider(&provider, None);
                true
            }
            "session" | "resume" => {
                self.session_browser.open(vec![]);
                self.session_list_pending = true;
                true
            }
            "clear" => {
                self.messages.clear();
                self.system_annotations.clear();
                self.display_messages.clear();
                self.streaming_text.clear();
                self.streaming_thinking.clear();
                self.tool_use_blocks.clear();
                self.turn_metadata.clear();
                self.cost_usd = 0.0;
                self.invalidate_transcript();
                self.status_message = Some("Conversation cleared.".to_string());
                true
            }
            "exit" | "quit" => {
                self.should_exit = true;
                true
            }
            "vim" => {
                self.prompt_input.vim_enabled = !self.prompt_input.vim_enabled;
                let status = if self.prompt_input.vim_enabled {
                    "enabled"
                } else {
                    "disabled"
                };
                self.status_message = Some(format!("Vim mode {}.", status));
                self.refresh_prompt_input();
                true
            }
            "fast" => {
                self.fast_mode = !self.fast_mode;
                let status = if self.fast_mode {
                    "enabled"
                } else {
                    "disabled"
                };
                self.status_message = Some(format!("Fast mode {}.", status));
                true
            }
            "plan" => {
                use claurst_core::config::PermissionMode;
                self.plan_mode = !self.plan_mode;
                self.config.permission_mode = if self.plan_mode {
                    PermissionMode::Plan
                } else {
                    PermissionMode::Default
                };
                self.status_message = Some(if self.plan_mode {
                    "Plan mode ON — Coven Code will plan before acting.".to_string()
                } else {
                    "Plan mode OFF.".to_string()
                });
                // Allow CLI path to also run (sends UserMessage to Coven Code).
                false
            }
            "compact" => {
                // Handled by execute_command in the CLI loop (real LLM compaction).
                false
            }
            "copy" => {
                // Copy last assistant message to clipboard. Attempt arboard; fall back to notification.
                let last = self
                    .messages
                    .iter()
                    .rev()
                    .find(|m| m.role == Role::Assistant)
                    .map(|m| m.get_all_text());
                if let Some(text) = last {
                    // Try xclip/xsel/pbcopy/clip.exe for clipboard; fall back to notification.
                    let copied = try_copy_to_clipboard(&text);
                    if copied {
                        self.push_notification(
                            NotificationKind::Info,
                            "Copied to clipboard.".to_string(),
                            Some(3),
                        );
                    } else {
                        self.push_notification(
                            NotificationKind::Info,
                            format!(
                                "Last response: {} chars (clipboard unavailable)",
                                text.len()
                            ),
                            Some(5),
                        );
                    }
                } else {
                    self.push_notification(
                        NotificationKind::Warning,
                        "No assistant message to copy.".to_string(),
                        Some(3),
                    );
                }
                true
            }
            "output-style" => {
                self.output_style = match self.output_style.as_str() {
                    "auto" => "stream".to_string(),
                    "stream" => "verbose".to_string(),
                    _ => "auto".to_string(),
                };
                self.status_message = Some(format!("Output style: {}.", self.output_style));
                true
            }
            "effort" => {
                // Open the picker dialog so users can pick an effort level
                // visually instead of cycling/typing the level (issue #149).
                self.effort_picker.open(self.effort_level);
                true
            }
            "voice" => {
                let was_on = self.voice_recorder.is_some();
                if was_on {
                    // Stop any active recording before disabling.
                    if self.voice_recording {
                        self.voice_recording = false;
                        self.voice_event_rx = None;
                        if let Some(ref recorder_arc) = self.voice_recorder {
                            let recorder = recorder_arc.clone();
                            tokio::task::spawn_blocking(move || {
                                if let Ok(mut r) = recorder.lock() {
                                    tokio::runtime::Handle::current()
                                        .block_on(r.stop_recording())
                                        .ok();
                                }
                            });
                        }
                    }
                    self.voice_recorder = None;
                    self.voice_mode_notice.dismiss();
                    self.status_message = Some("Voice mode disabled.".to_string());
                } else {
                    let recorder = claurst_core::voice::global_voice_recorder();
                    if let Ok(mut r) = recorder.lock() {
                        r.set_enabled(true);
                    }
                    self.voice_recorder = Some(recorder);
                    self.voice_mode_notice = crate::voice_mode_notice::VoiceModeNoticeState::new();
                    self.status_message =
                        Some("Voice mode enabled. Press Alt+V to start recording.".to_string());
                }
                true
            }
            "doctor" => {
                // Handled by execute_command (DoctorCommand).
                false
            }
            "cost" => {
                self.stats_dialog.open();
                true
            }
            "rewind" => {
                self.open_rewind_flow();
                true
            }
            "export" => {
                self.export_dialog.open();
                true
            }
            "context" => {
                self.context_viz.toggle();
                true
            }
            "rename" => {
                self.session_browser.open(vec![]);
                self.session_list_pending = true;
                self.session_browser.start_rename();
                true
            }
            "init" | "login" | "logout" => {
                // Handled by execute_command (CLI-level operations).
                false
            }
            "keybindings" => {
                // Open the keybindings.json file in the external editor
                let keybindings_path =
                    claurst_core::config::Settings::config_dir().join("keybindings.json");

                if let Err(e) = open_file_externally(&keybindings_path) {
                    eprintln!("Failed to open keybindings file: {}", e);
                }
                true
            }
            "help" => {
                // Open the help overlay (same as pressing `?` or F1).
                if !self.help_overlay.visible {
                    self.help_overlay.toggle();
                }
                true
            }
            _ => false,
        }
    }

    fn close_secondary_views(&mut self) {
        self.stats_dialog.close();
        self.mcp_view.close();
        self.agents_menu.close();
        self.diff_viewer.close();
        self.feedback_survey.close();
        self.memory_file_selector.close();
        self.hooks_config_menu.close();
        self.model_picker.close();
        self.session_browser.close();
        self.session_branching.close();
        self.tasks_overlay.close();
        self.export_dialog.dismiss();
        self.context_viz.close();
        self.connect_dialog.close();
        self.import_config_picker.close();
        self.import_config_dialog.close();
        self.command_palette.close();
        self.key_input_dialog.close();
        self.device_auth_dialog.close();
        self.settings_screen.close();
        self.theme_screen.close();
    }

    /// Whether a *blocking* overlay currently owns keyboard input — i.e. the
    /// prompt is not the active text target.
    ///
    /// This is the single source of truth for "an overlay captures input": any
    /// new picker/dialog added here automatically stops prompt text (including
    /// paste-burst capture) from leaking while it is open — see
    /// [`Self::prompt_is_accepting_text`]. It excludes the passive notices
    /// (overage / voice / memory), which render as overlays but let the user
    /// keep typing underneath.
    pub fn any_blocking_modal_open(&self) -> bool {
        self.permission_request.is_some()
            || self.rate_limit_recovery.visible
            || self.rewind_flow.visible
            || self.tasks_overlay.visible
            || self.help_overlay.visible
            || self.history_search_overlay.visible
            || self.settings_screen.visible
            || self.theme_screen.visible
            || self.stats_dialog.visible
            || self.mcp_view.visible
            || self.agents_menu.visible
            || self.diff_viewer.visible
            || self.global_search.visible
            || self.feedback_survey.visible
            || self.memory_file_selector.visible
            || self.hooks_config_menu.visible
            || self.import_config_dialog.visible
            || self.invalid_config_dialog.visible
            || self.bypass_permissions_dialog.visible
            || self.ask_user_dialog.visible
            || self.onboarding_dialog.visible
            || self.import_config_picker.visible
            || self.connect_dialog.visible
            || self.key_input_dialog.visible
            || self.device_auth_dialog.visible
            || self.command_palette.visible
            || self.elicitation.visible
            || self.model_picker.visible
            || self.session_browser.visible
            || self.session_branching.visible
            || self.export_dialog.visible
            || self.context_viz.visible
            || self.mcp_approval.visible
            || self.file_injection_dialog.visible
            || self.skills_picker.visible
            || self.context_menu_state.is_some()
    }

    pub fn any_modal_open(&self) -> bool {
        // Passive notices don't capture input but still render as overlays, so
        // they count as a modal for rendering purposes only.
        self.any_blocking_modal_open()
            || self.overage_upsell.visible
            || self.voice_mode_notice.visible
            || self.memory_update_notification.visible
    }

    fn dismiss_error_notifications(&mut self) {
        while self.notifications.current_is_error() {
            self.notifications.dismiss_current();
        }
        self.error_modal_scroll_offset = 0;
    }

    /// Perform the export based on the selected format. Returns the path written.
    pub fn perform_export(&mut self) -> Option<String> {
        use crate::export_dialog::{export_as_json, export_as_markdown};
        let ts = chrono::Local::now().format("%Y%m%d-%H%M%S");
        let (filename, content) = match self.export_dialog.selected {
            ExportFormat::Json => {
                let json = export_as_json(&self.messages, self.session_title.as_deref());
                let s = serde_json::to_string_pretty(&json).unwrap_or_default();
                (format!("claude-export-{}.json", ts), s)
            }
            ExportFormat::Markdown => {
                let md = export_as_markdown(&self.messages, self.session_title.as_deref());
                (format!("claude-export-{}.md", ts), md)
            }
        };
        if std::fs::write(&filename, &content).is_ok() {
            self.export_dialog.dismiss();
            Some(filename)
        } else {
            None
        }
    }

    fn project_root(&self) -> std::path::PathBuf {
        self.config
            .project_dir
            .clone()
            .or_else(|| std::env::current_dir().ok())
            .unwrap_or_else(|| std::path::PathBuf::from("."))
    }

    /// Build the skill list from settings + cwd and open the `/skills` picker.
    fn open_skills_picker(&mut self, filter: &str) {
        let settings = Settings::load_sync().unwrap_or_default();
        let cwd = self.project_root();
        let rows = crate::skills_picker::build_skill_rows(&cwd, &settings);
        self.skills_picker.open(rows, filter);
    }

    /// Toggle the selected skill's enabled state and persist it to settings.
    fn toggle_selected_skill(&mut self) {
        if let Some((name, enabled)) = self.skills_picker.toggle_selected() {
            let mut settings = Settings::load_sync().unwrap_or_default();
            if enabled {
                settings.disabled_skills.remove(&name);
            } else {
                settings.disabled_skills.insert(name.clone());
            }
            match settings.save_sync() {
                Ok(()) => {
                    self.status_message = Some(format!(
                        "Skill '{}' {}.",
                        name,
                        if enabled { "enabled" } else { "disabled" }
                    ));
                }
                Err(e) => {
                    // Persisting failed — revert the in-memory toggle so the
                    // on-screen state stays consistent with disk, and report it.
                    self.skills_picker.toggle_selected();
                    self.status_message = Some(format!("Failed to save skill '{}': {}", name, e));
                }
            }
        }
    }

    fn refresh_global_search(&mut self) {
        let root = self.project_root();
        self.global_search.run_search(&root);
    }

    fn load_mcp_servers(&self) -> Vec<McpServerView> {
        if let Some(manager) = self.mcp_manager.as_ref() {
            let tool_defs = manager.all_tool_definitions();
            return self
                .config
                .mcp_servers
                .iter()
                .map(|server| {
                    let transport = server
                        .url
                        .as_ref()
                        .map(|_| server.server_type.clone())
                        .or_else(|| server.command.as_ref().map(|_| "stdio".to_string()))
                        .unwrap_or_else(|| server.server_type.clone());

                    let tools: Vec<McpToolView> = tool_defs
                        .iter()
                        .filter(|(server_name, _)| server_name == &server.name)
                        .map(|(_, tool_def)| McpToolView {
                            name: tool_def
                                .name
                                .strip_prefix(&format!("{}_", server.name))
                                .unwrap_or(&tool_def.name)
                                .to_string(),
                            server: server.name.clone(),
                            description: tool_def.description.clone(),
                            input_schema: Some(tool_def.input_schema.to_string()),
                        })
                        .collect();

                    let (status, error_message) = match manager.server_status(&server.name) {
                        claurst_mcp::McpServerStatus::Connected { .. } => {
                            (McpViewStatus::Connected, None)
                        }
                        claurst_mcp::McpServerStatus::Connecting => {
                            (McpViewStatus::Connecting, None)
                        }
                        claurst_mcp::McpServerStatus::Disconnected { last_error } => {
                            if last_error.is_some() {
                                (McpViewStatus::Error, last_error)
                            } else {
                                (McpViewStatus::Disconnected, None)
                            }
                        }
                        claurst_mcp::McpServerStatus::Failed { error, .. } => {
                            (McpViewStatus::Error, Some(error))
                        }
                    };

                    let catalog = manager.server_catalog(&server.name);
                    McpServerView {
                        name: server.name.clone(),
                        transport,
                        status,
                        tool_count: catalog
                            .as_ref()
                            .map(|entry| entry.tool_count)
                            .unwrap_or_else(|| tools.len()),
                        resource_count: catalog
                            .as_ref()
                            .map(|entry| entry.resource_count)
                            .unwrap_or(0),
                        prompt_count: catalog
                            .as_ref()
                            .map(|entry| entry.prompt_count)
                            .unwrap_or(0),
                        resources: catalog
                            .as_ref()
                            .map(|entry| entry.resources.clone())
                            .unwrap_or_default(),
                        prompts: catalog
                            .as_ref()
                            .map(|entry| entry.prompts.clone())
                            .unwrap_or_default(),
                        error_message,
                        tools,
                    }
                })
                .collect();
        }

        self.config
            .mcp_servers
            .iter()
            .map(|server| {
                let transport = server
                    .url
                    .as_ref()
                    .map(|_| server.server_type.clone())
                    .or_else(|| server.command.as_ref().map(|_| "stdio".to_string()))
                    .unwrap_or_else(|| server.server_type.clone());
                let description = if let Some(url) = &server.url {
                    format!("Endpoint: {}", url)
                } else if let Some(command) = &server.command {
                    let args = if server.args.is_empty() {
                        String::new()
                    } else {
                        format!(" {}", server.args.join(" "))
                    };
                    format!("Command: {}{}", command, args)
                } else {
                    "Configured server".to_string()
                };
                McpServerView {
                    name: server.name.clone(),
                    transport,
                    status: McpViewStatus::Disconnected,
                    tool_count: 0,
                    resource_count: 0,
                    prompt_count: 0,
                    resources: vec![],
                    prompts: vec![],
                    error_message: None,
                    tools: vec![McpToolView {
                        name: "connection".to_string(),
                        server: server.name.clone(),
                        description,
                        input_schema: None,
                    }],
                }
            })
            .collect()
    }

    fn open_agents_menu(&mut self) {
        let root = self.project_root();
        self.agents_menu.open(&root);
        self.agents_menu.active_agents = self
            .agent_status
            .iter()
            .enumerate()
            .map(|(idx, (name, status))| AgentInfo {
                id: format!("agent-{}", idx + 1),
                name: name.clone(),
                status: match status.as_str() {
                    "running" => AgentStatus::Running,
                    "waiting" | "waiting_for_tool" => AgentStatus::WaitingForTool,
                    "complete" | "completed" | "done" => AgentStatus::Complete,
                    "failed" | "error" => AgentStatus::Failed,
                    _ => AgentStatus::Idle,
                },
                current_tool: None,
                turns_completed: 0,
                is_coordinator: false,
                last_output: Some(status.clone()),
                agent_role: crate::agents_view::AgentRole::Normal,
                model_name: None,
                cost_usd: 0.0,
            })
            .collect();
    }

    /// Add a message directly (e.g. from a non-streaming source).
    pub fn add_message(&mut self, role: Role, text: String) {
        let msg = match role {
            Role::User => Message::user(text),
            Role::Assistant => Message::assistant(text),
        };
        if role == Role::User {
            self.begin_user_turn_snapshot();
        }
        self.messages.push(msg);
        self.invalidate_transcript();
        self.on_new_message();
    }

    pub fn replace_messages(&mut self, messages: Vec<Message>) {
        self.messages = messages;
        self.sync_turn_metadata_to_messages();
        self.invalidate_transcript();
    }

    pub fn push_message(&mut self, message: Message) {
        if message.role == Role::User {
            self.begin_user_turn_snapshot();
        }
        self.messages.push(message);
        self.sync_turn_metadata_to_messages();
        self.invalidate_transcript();
        self.on_new_message();
    }

    /// Push a synthetic system annotation into the conversation pane.
    /// It will appear after the current last message.
    /// Push a notification and, for Error-kind notifications, reset the error
    /// modal scroll offset so a newly arrived error is always shown from the top.
    pub fn push_notification(
        &mut self,
        kind: NotificationKind,
        msg: String,
        duration_secs: Option<u64>,
    ) {
        if kind == NotificationKind::Error {
            self.error_modal_scroll_offset = 0;
        }
        self.notifications.push(kind, msg, duration_secs);
    }

    // -------------------------------------------------------------------
    // Rate-limit recovery
    // -------------------------------------------------------------------

    /// Open the interactive rate-limit recovery modal for a structured 429.
    pub fn open_rate_limit_recovery(&mut self, message: String, retry_after_secs: Option<u64>) {
        let is_anthropic = self.config.provider.as_deref().unwrap_or("anthropic") == "anthropic";
        let model = self.model_name.clone();
        self.rate_limit_recovery
            .open(message, model, retry_after_secs, is_anthropic);
    }

    /// Handle a key press while the recovery modal is open.
    fn handle_rate_limit_recovery_key(&mut self, key: KeyEvent) {
        use crate::rate_limit_recovery::{HAIKU_MODEL, SONNET_MODEL};
        match key.code {
            KeyCode::Esc => {
                self.rate_limit_recovery.dismiss();
                self.status_message =
                    Some("Recovery dismissed — prompt is yours. Retry any time.".to_string());
            }
            KeyCode::Char('r') | KeyCode::Enter => {
                self.rate_limit_recovery.request_retry(None);
                self.status_message = Some("Retrying…".to_string());
            }
            KeyCode::Char('s')
                if self.rate_limit_recovery.tier_switch_available
                    && !self.rate_limit_recovery.model.contains("sonnet")
                    && !self.rate_limit_recovery.model.contains("haiku") =>
            {
                self.set_model(SONNET_MODEL.to_string());
                self.persist_provider_and_model();
                self.rate_limit_recovery
                    .request_retry(Some(SONNET_MODEL.to_string()));
                self.status_message = Some(format!("Retrying on {}…", SONNET_MODEL));
            }
            KeyCode::Char('h')
                if self.rate_limit_recovery.tier_switch_available
                    && !self.rate_limit_recovery.model.contains("haiku") =>
            {
                self.set_model(HAIKU_MODEL.to_string());
                self.persist_provider_and_model();
                self.rate_limit_recovery
                    .request_retry(Some(HAIKU_MODEL.to_string()));
                self.status_message = Some(format!("Retrying on {}…", HAIKU_MODEL));
            }
            _ => {}
        }
    }

    /// Surface a completion signal for a long-running background bash task
    /// (one launched with `run_in_background: true, notify_on_complete: true`).
    ///
    /// Renders a toast in the top-right and optionally rings the terminal
    /// bell so the user notices builds/tests finishing while their attention
    /// is elsewhere.
    pub fn signal_bg_task_completion(
        &mut self,
        info: &claurst_tools::BgTaskCompletion,
        toast_enabled: bool,
        bell_enabled: bool,
    ) {
        if toast_enabled {
            let cmd_preview: String = info.command.chars().take(48).collect();
            let cmd_suffix = if info.command.chars().count() > 48 {
                "…"
            } else {
                ""
            };
            let duration = format_duration_secs(info.duration_secs);
            let (kind, msg) = if info.success {
                (
                    NotificationKind::Success,
                    format!("Build done · {}{} · {}", cmd_preview, cmd_suffix, duration),
                )
            } else {
                (
                    NotificationKind::Error,
                    format!(
                        "Build failed · {}{} · {} · {}",
                        cmd_preview, cmd_suffix, info.exit_info, duration
                    ),
                )
            };
            // Success toasts auto-dismiss after 8s; failures stay until acknowledged.
            let duration_secs = if info.success { Some(8) } else { None };
            self.push_notification(kind, msg, duration_secs);
        }
        if bell_enabled {
            ring_terminal_bell();
        }
    }

    pub fn push_system_message(&mut self, text: String, style: SystemMessageStyle) {
        self.system_annotations.push(SystemAnnotation {
            after_index: self.messages.len(),
            text,
            style,
        });
        self.invalidate_transcript();
    }

    /// Called whenever a new message is appended to `messages`.
    /// Manages the auto-scroll / new-message-counter state.
    fn on_new_message(&mut self) {
        if self.auto_scroll {
            // Auto-scroll: keep offset at 0 so render shows the bottom.
            self.scroll_offset = 0;
        } else {
            self.new_messages_while_scrolled = self.new_messages_while_scrolled.saturating_add(1);
        }
    }

    pub fn invalidate_transcript(&self) {
        self.transcript_version
            .set(self.transcript_version.get().wrapping_add(1));
    }

    /// Check current token usage and push token warning notifications as
    /// appropriate.  Call this after updating `token_count`.
    pub fn check_token_warnings(&mut self) {
        let window = claurst_query::context_window_for_model(&self.model_name) as u32;
        if window == 0 {
            return;
        }
        let pct = (self.token_count as f64 / window as f64 * 100.0) as u8;

        // Only escalate — never repeat a threshold already shown.
        if pct >= 100 && self.token_warning_threshold_shown < 100 {
            self.token_warning_threshold_shown = 100;
            self.push_notification(
                NotificationKind::Error,
                "Context window full. Running auto-compact\u{2026}".to_string(),
                None,
            );
        } else if pct >= 95 && self.token_warning_threshold_shown < 95 {
            self.token_warning_threshold_shown = 95;
            self.push_notification(
                NotificationKind::Error,
                "Context window 95% full! Run /compact now.".to_string(),
                None, // persistent until dismissed
            );
        } else if pct >= 80 && self.token_warning_threshold_shown < 80 {
            self.token_warning_threshold_shown = 80;
            self.push_notification(
                NotificationKind::Warning,
                "Context window 80% full. Consider /compact.".to_string(),
                Some(30),
            );
        }
    }

    /// Take the current input buffer, push it to history, and return it.
    pub fn take_input(&mut self) -> String {
        let input = self.prompt_input.take();
        if !input.is_empty() {
            self.prompt_input.history.push(input.clone());
            self.prompt_input.history_pos = None;
            self.prompt_input.history_draft.clear();
            self.input_history = self.prompt_input.history.clone();
            self.history_index = self.prompt_input.history_pos;
        }
        self.refresh_prompt_input();
        input
    }

    /// Compute the number of lines to scroll per wheel/trackpad event.
    /// Implements a simple acceleration model: rapid events (< 40 ms apart) are
    /// treated as trackpad bursts and accelerate up to 2×; slower events (mouse
    /// wheel) stay at the base 3-line step.
    fn scroll_step(&mut self) -> usize {
        let now = std::time::Instant::now();
        let elapsed_ms = self
            .scroll_last_time
            .map(|t| now.duration_since(t).as_millis())
            .unwrap_or(u128::MAX);
        self.scroll_last_time = Some(now);
        if elapsed_ms < 40 {
            // Trackpad burst — gradually accelerate
            self.scroll_accel = (self.scroll_accel + 0.4).min(6.0);
        } else {
            // Mouse click or first event — reset to base
            self.scroll_accel = 3.0;
        }
        self.scroll_accel.round() as usize
    }

    /// Open the rewind flow with the current message list converted to
    /// `SelectorMessage` entries.
    pub fn open_rewind_flow(&mut self) {
        let selector_msgs: Vec<SelectorMessage> = self
            .messages
            .iter()
            .enumerate()
            .map(|(i, m)| {
                let text = m.get_all_text();
                let preview: String = text.chars().take(80).collect();
                let has_tool_use = !m.get_tool_use_blocks().is_empty();
                SelectorMessage {
                    idx: i,
                    role: format!("{:?}", m.role).to_lowercase(),
                    preview,
                    has_tool_use,
                }
            })
            .collect();
        self.rewind_flow.open(selector_msgs);
    }

    /// Return the elapsed session time as a human-readable string, e.g. "2m 5s".
    pub fn elapsed_str(&self) -> String {
        let secs = self.session_start.elapsed().as_secs();
        if secs < 60 {
            format!("{}s", secs)
        } else {
            format!("{}m {}s", secs / 60, secs % 60)
        }
    }

    fn prompt_mode(&self) -> InputMode {
        // Note: previously returned Readonly while streaming, but the prompt
        // now accepts input during streaming so the user can compose / queue
        // a follow-up message. Plan mode still wins.
        if self.plan_mode {
            InputMode::Plan
        } else {
            InputMode::Default
        }
    }

    fn sync_legacy_prompt_fields(&mut self) {
        self.input = self.prompt_input.text.clone();
        self.cursor_pos = self.prompt_input.cursor;
        self.history_index = self.prompt_input.history_pos;
    }

    pub fn refresh_prompt_input(&mut self) {
        self.prompt_input.mode = self.prompt_mode();
        if self.file_injection_dialog.visible {
            // Don't update suggestions while the injection dialog is open.
            self.sync_legacy_prompt_fields();
            return;
        }
        let file_autocomplete_limit = self.config.file_autocomplete_limit;
        let file_autocomplete_show_hidden = self.config.file_autocomplete_show_hidden_files;
        self.prompt_input.update_suggestions(
            PROMPT_SLASH_COMMANDS,
            file_autocomplete_limit,
            file_autocomplete_show_hidden,
        );
        self.sync_legacy_prompt_fields();
    }

    pub fn set_prompt_text(&mut self, text: String) {
        self.prompt_input.replace_text(text);
        self.refresh_prompt_input();
    }

    // -----------------------------------------------------------------------
    // Voice PTT helpers
    // -----------------------------------------------------------------------

    /// Start PTT recording: open the microphone capture stream and signal the
    /// UI.  No-op when no voice recorder is attached or recording is already
    /// in progress.
    pub fn handle_voice_ptt_start(&mut self) {
        if self.voice_recording || self.voice_recorder.is_none() {
            return;
        }
        let (tx, rx) = tokio::sync::mpsc::channel(16);
        self.voice_event_rx = Some(rx);
        self.voice_recording = true;
        if let Some(ref recorder_arc) = self.voice_recorder {
            let recorder = recorder_arc.clone();
            tokio::task::spawn_blocking(move || {
                if let Ok(mut r) = recorder.lock() {
                    tokio::runtime::Handle::current()
                        .block_on(r.start_recording(tx))
                        .ok();
                }
            });
        }
        self.status_message =
            Some("Recording\u{2026} release V or press Enter to transcribe".to_string());
    }

    /// Stop PTT recording: flip the AtomicBool inside VoiceRecorder so the
    /// capture thread exits, then fire a "Transcribing…" notice.  The
    /// transcript text arrives later via `voice_event_rx` and is injected into
    /// the prompt by the event-loop drain.
    pub fn handle_voice_ptt_stop(&mut self) {
        if !self.voice_recording {
            return;
        }
        self.voice_recording = false;
        if let Some(ref recorder_arc) = self.voice_recorder {
            let recorder = recorder_arc.clone();
            tokio::task::spawn_blocking(move || {
                if let Ok(mut r) = recorder.lock() {
                    tokio::runtime::Handle::current()
                        .block_on(r.stop_recording())
                        .ok();
                }
            });
        }
        self.status_message = Some("Transcribing\u{2026}".to_string());
    }

    pub fn attach_turn_diff_state(
        &mut self,
        file_history: Arc<parking_lot::Mutex<FileHistory>>,
        current_turn: Arc<std::sync::atomic::AtomicUsize>,
    ) {
        self.file_history = Some(file_history);
        self.current_turn = Some(current_turn);
        self.refresh_turn_diff_from_history();
    }

    pub fn attach_mcp_manager(&mut self, mcp_manager: Arc<claurst_mcp::McpManager>) {
        self.mcp_manager = Some(mcp_manager);
    }

    pub fn refresh_mcp_view(&mut self) {
        let servers = self.load_mcp_servers();
        self.mcp_view.open(servers);
    }

    pub fn take_pending_mcp_panel_auth(&mut self) -> Option<String> {
        self.pending_mcp_panel_auth.take()
    }

    pub fn take_pending_mcp_reconnect(&mut self) -> bool {
        let pending = self.pending_mcp_reconnect;
        self.pending_mcp_reconnect = false;
        pending
    }

    /// Returns and clears any pending MCP approval result.
    pub fn take_mcp_approval_result(&mut self) -> Option<crate::dialogs::McpApprovalChoice> {
        if !self.mcp_approval.visible {
            return None;
        }
        // The dialog closes itself on confirm; we check if it's now closed
        None // Actual result is read by CLI loop via mcp_approval.visible + confirm()
    }

    /// Detect the current PR from environment variables or git.
    pub fn detect_pr(&mut self) {
        // Check CLAUDE_PR_NUMBER and CLAUDE_PR_URL env vars
        if let Ok(num) = std::env::var("CLAUDE_PR_NUMBER") {
            if let Ok(n) = num.parse::<u32>() {
                self.pr_number = Some(n);
            }
        }
        if let Ok(url) = std::env::var("CLAUDE_PR_URL") {
            self.pr_url = Some(url);
        }
        if let Ok(state) = std::env::var("CLAUDE_PR_STATE") {
            if !state.trim().is_empty() {
                self.pr_state = Some(state.trim().to_string());
            }
        }
        // Fall back to gh CLI if no env vars
        if self.pr_number.is_none() {
            if let Ok(output) = std::process::Command::new("gh")
                .args(["pr", "view", "--json", "number,url", "--jq", ".number,.url"])
                .output()
            {
                if output.status.success() {
                    let text = String::from_utf8_lossy(&output.stdout);
                    let parts: Vec<&str> = text.trim().split('\n').collect();
                    if parts.len() >= 2 {
                        if let Ok(n) = parts[0].trim().parse::<u32>() {
                            self.pr_number = Some(n);
                            self.pr_url = Some(parts[1].trim().to_string());
                        }
                    }
                }
            }
        }
    }

    fn clear_prompt(&mut self) {
        self.prompt_input.clear();
        self.refresh_prompt_input();
    }

    fn refresh_turn_diff_from_history(&mut self) {
        let Some(file_history) = self.file_history.as_ref() else {
            self.diff_viewer.set_turn_diff(Vec::new());
            return;
        };
        let Some(current_turn) = self.current_turn.as_ref() else {
            self.diff_viewer.set_turn_diff(Vec::new());
            return;
        };

        let turn_index = current_turn.load(std::sync::atomic::Ordering::Relaxed);
        if turn_index == 0 {
            self.diff_viewer.set_turn_diff(Vec::new());
            return;
        }

        let root = self.project_root();
        let files = {
            let history = file_history.lock();
            build_turn_diff(&history, turn_index, &root)
        };
        self.diff_viewer.set_turn_diff(files);
    }

    // -------------------------------------------------------------------
    // Event handling
    // -------------------------------------------------------------------

    /// Persist `has_completed_onboarding = true` to the settings file.
    /// Best-effort: failures are silently ignored to not disrupt the session.
    fn persist_onboarding_complete() -> anyhow::Result<()> {
        let mut settings = claurst_core::config::Settings::load_sync()?;
        settings.has_completed_onboarding = true;
        settings.save_sync()
    }

    /// Public wrapper so the main loop can mark onboarding complete without
    /// going through the dialog flow.
    pub fn persist_onboarding_complete_pub() -> anyhow::Result<()> {
        Self::persist_onboarding_complete()
    }

    /// Process a keyboard event. Returns `true` when the input should be
    /// submitted (Enter pressed with no blocking dialog).
    pub fn handle_key_event(&mut self, key: KeyEvent) -> bool {
        // Permission requests render above other overlays, so they own input.
        if self.permission_request.is_some() {
            self.handle_permission_key(key);
            return false;
        }

        // Rate-limit recovery modal owns input while visible.
        if self.rate_limit_recovery.visible {
            self.handle_rate_limit_recovery_key(key);
            return false;
        }

        // Dismiss error modal with Esc
        if key.code == KeyCode::Esc && self.notifications.current_is_error() {
            self.dismiss_error_notifications();
            return false;
        }

        // ---- Familiar switcher (F2) ----------------------------------------
        if self.familiar_switcher_open {
            // Navigation runs over the filtered entry list (which leads with a
            // synthetic "clear" row); typing narrows the roster incrementally.
            let entries = self.familiar_switcher_entries();
            let len = entries.len();
            let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
            let alt = key.modifiers.contains(KeyModifiers::ALT);
            match key.code {
                KeyCode::Esc | KeyCode::F(2) => {
                    self.close_familiar_switcher();
                }
                KeyCode::Down if len > 0 => {
                    self.familiar_switcher_idx = (self.familiar_switcher_idx + 1) % len;
                }
                KeyCode::Up if len > 0 => {
                    self.familiar_switcher_idx = (self.familiar_switcher_idx + len - 1) % len;
                }
                KeyCode::Char('n') if ctrl && len > 0 => {
                    self.familiar_switcher_idx = (self.familiar_switcher_idx + 1) % len;
                }
                KeyCode::Char('p') if ctrl && len > 0 => {
                    self.familiar_switcher_idx = (self.familiar_switcher_idx + len - 1) % len;
                }
                KeyCode::Backspace => {
                    self.familiar_switcher_filter.pop();
                    self.familiar_switcher_idx = 0;
                }
                KeyCode::Enter => {
                    match entries.get(self.familiar_switcher_idx) {
                        Some(FamiliarSwitcherEntry::Clear) => {
                            // Step back to no active familiar (same effect as
                            // `/familiar reset`) without leaving the switcher.
                            self.config.familiar = None;
                            self.persist_familiar_setting(None);
                            self.apply_familiar_agent_mode(None, None);
                            self.push_notification(
                                crate::notifications::NotificationKind::Info,
                                "Familiar cleared.".to_string(),
                                None,
                            );
                        }
                        Some(FamiliarSwitcherEntry::Familiar(id)) => {
                            // Full activation, same as the menu and /familiar:
                            // mascot + persisted setting + agent mode/tool tier.
                            let id = id.clone();
                            self.config.familiar = Some(id.clone());
                            self.persist_familiar_setting(Some(id.clone()));
                            self.apply_familiar_agent_mode(Some(id.clone()), None);
                            self.push_notification(
                                crate::notifications::NotificationKind::Info,
                                format!("\u{2728} Familiar: {}", id),
                                None,
                            );
                        }
                        None => {}
                    }
                    self.close_familiar_switcher();
                }
                KeyCode::Char(c) if !ctrl && !alt => {
                    self.familiar_switcher_filter.push(c);
                    self.familiar_switcher_idx = 0;
                }
                _ => {}
            }
            return false;
        }

        if self.global_search.visible {
            return self.handle_global_search_key(key);
        }

        // ---- Context menu handling (highest priority for menu navigation) ----
        if self.context_menu_state.is_some() {
            match key.code {
                KeyCode::Esc => {
                    self.dismiss_context_menu();
                    return false;
                }
                KeyCode::Up | KeyCode::Down => {
                    self.navigate_context_menu(key.code);
                    return false;
                }
                KeyCode::Enter => {
                    self.execute_context_menu_item();
                    return false;
                }
                _ => {}
            }
        }

        // Bypass-permissions dialog: highest-priority gate — user must accept or the
        // session exits immediately. Mirrors TS BypassPermissionsModeDialog.tsx.
        if self.bypass_permissions_dialog.visible {
            match key.code {
                KeyCode::Char('1') | KeyCode::Esc => {
                    // "No, exit" — quit immediately
                    self.should_exit = true;
                }
                KeyCode::Char('2') => {
                    // "Yes, I accept" — dismiss and continue
                    self.bypass_permissions_dialog.dismiss();
                }
                KeyCode::Up | KeyCode::Char('k') => self.bypass_permissions_dialog.select_prev(),
                KeyCode::Down | KeyCode::Char('j') => self.bypass_permissions_dialog.select_next(),
                KeyCode::Enter => {
                    if self.bypass_permissions_dialog.is_accept_selected() {
                        self.bypass_permissions_dialog.dismiss();
                    } else {
                        self.should_exit = true;
                    }
                }
                _ => {}
            }
            return false;
        }

        // File injection dialog: shown when oversized files are detected in @refs.
        if self.file_injection_dialog.visible {
            let is_directory_only = self.file_injection_dialog.is_directory_only();
            match key.code {
                KeyCode::Enter => {
                    if is_directory_only {
                        // Directories can't be injected; Enter = abort, restore input.
                        if let Some(input) = self.file_injection_dialog.pending_input.clone() {
                            self.set_prompt_text(input);
                        }
                        self.file_injection_dialog.dismiss();
                    } else {
                        // Enter = inject (Allow).
                        self.file_injection_dialog.selected = 0;
                        self.file_injection_dialog.confirm();
                    }
                }
                KeyCode::Esc => {
                    // Esc = abort, restore input.
                    if let Some(input) = self.file_injection_dialog.pending_input.clone() {
                        self.set_prompt_text(input);
                    }
                    self.file_injection_dialog.dismiss();
                }
                _ => {}
            }
            return false;
        }

        // Onboarding dialog: shown on first launch, dismissed with Enter/→/Esc.
        if self.onboarding_dialog.visible {
            // The no-credentials provider-setup page is actionable: Enter or a
            // provider number opens the real connect dialog so a brand-new user
            // can actually authenticate instead of paging through read-only
            // text and landing at an empty prompt.
            if self.onboarding_dialog.is_provider_setup() {
                match key.code {
                    KeyCode::Esc => {
                        // Esc = "skip for now". Persist completion so a brand-new
                        // user who dismisses isn't re-nagged with the same dialog
                        // every launch; the /connect hint in the welcome box keeps
                        // the affordance visible.
                        self.onboarding_dialog.dismiss();
                        let _ = Self::persist_onboarding_complete();
                        self.status_message =
                            Some("Run /connect when you're ready to add a provider.".to_string());
                    }
                    KeyCode::Enter | KeyCode::Right => {
                        self.onboarding_dialog.dismiss();
                        let _ = Self::persist_onboarding_complete();
                        self.connect_dialog.open();
                    }
                    KeyCode::Char('1') => {
                        self.onboarding_dialog.dismiss();
                        let _ = Self::persist_onboarding_complete();
                        self.start_preferred_claude_connection();
                    }
                    KeyCode::Char('2') => {
                        self.onboarding_dialog.dismiss();
                        let _ = Self::persist_onboarding_complete();
                        self.start_codex_connection();
                    }
                    _ => {}
                }
                return false;
            }
            match key.code {
                KeyCode::Esc => {
                    // Esc dismisses from any page and counts as completing
                    // onboarding, so the dialog doesn't reappear next launch.
                    self.onboarding_dialog.dismiss();
                    let _ = Self::persist_onboarding_complete();
                }
                KeyCode::Enter | KeyCode::Right if self.onboarding_dialog.next_page() => {
                    self.onboarding_dialog.dismiss();
                    // Persist that onboarding is complete (best-effort).
                    let _ = Self::persist_onboarding_complete();
                }
                KeyCode::Enter | KeyCode::Right => {}
                KeyCode::Left => {
                    self.onboarding_dialog.prev_page();
                }
                _ => {}
            }
            return false;
        }

        // Skills picker dialog (/skills).
        if self.skills_picker.visible {
            let ctrl = key.modifiers.contains(KeyModifiers::CONTROL);
            match key.code {
                KeyCode::Esc => self.skills_picker.close(),
                KeyCode::Up => self.skills_picker.select_prev(),
                KeyCode::Down => self.skills_picker.select_next(),
                KeyCode::Char('p') if ctrl => self.skills_picker.select_prev(),
                KeyCode::Char('n') if ctrl => self.skills_picker.select_next(),
                KeyCode::Char(' ') | KeyCode::Enter => self.toggle_selected_skill(),
                KeyCode::Backspace => self.skills_picker.pop_filter_char(),
                KeyCode::Char(c) if !ctrl => self.skills_picker.push_filter_char(c),
                _ => {}
            }
            return false;
        }

        // Effort picker dialog (/effort).
        if self.effort_picker.visible {
            match key.code {
                KeyCode::Esc => self.effort_picker.close(),
                KeyCode::Up | KeyCode::Char('k') => self.effort_picker.select_prev(),
                KeyCode::Down | KeyCode::Char('j') => self.effort_picker.select_next(),
                KeyCode::Enter => {
                    let chosen = self.effort_picker.current();
                    self.effort_level = chosen;
                    self.effort_is_set = true;
                    self.effort_picker.close();
                    self.status_message = Some(format!(
                        "Effort set to {} {}.",
                        chosen.symbol(),
                        chosen.label()
                    ));
                }
                _ => {}
            }
            return false;
        }

        // Device code / browser auth dialog (GitHub Copilot, Anthropic OAuth)
        if self.device_auth_dialog.visible {
            match key.code {
                KeyCode::Esc => {
                    self.device_auth_dialog.close();
                    self.device_auth_pending = None;
                }
                _ if matches!(
                    self.device_auth_dialog.status,
                    crate::device_auth_dialog::DeviceAuthStatus::Success(_)
                ) =>
                {
                    // Any key after success -> store credential and close
                    if let crate::device_auth_dialog::DeviceAuthStatus::Success(ref token) =
                        self.device_auth_dialog.status
                    {
                        let provider_id = self.device_auth_dialog.provider_id.clone();
                        let provider_name = self.device_auth_dialog.provider_name.clone();
                        let token = token.clone();
                        // Anthropic OAuth persists its tokens to disk itself; the
                        // returned access token is a Bearer credential, not an API
                        // key, so don't stash it in the key-based auth store. Just
                        // activate Anthropic and rebuild the runtime from disk.
                        if provider_id == "anthropic-oauth" {
                            self.device_auth_pending = None;
                            self.device_auth_dialog.close();
                            self.pending_provider_refresh = true;
                            self.activate_provider(
                                "anthropic".into(),
                                "Anthropic".into(),
                                "Connected to",
                            );
                            return false;
                        }
                        let credential = claurst_core::StoredCredential::ApiKey { key: token };
                        self.auth_store.set(&provider_id, credential);
                        self.device_auth_pending = None;
                        self.device_auth_dialog.close();
                        self.activate_provider(provider_id, provider_name, "Connected to");
                        return false;
                    }
                }
                _ if matches!(
                    self.device_auth_dialog.status,
                    crate::device_auth_dialog::DeviceAuthStatus::Error(_)
                ) =>
                {
                    // Any key after error -> close
                    self.device_auth_dialog.close();
                    self.device_auth_pending = None;
                }
                _ => {} // Ignore other keys while waiting
            }
            return false;
        }

        // API key input dialog (opened from /connect for key-based providers)
        // Ask-user question dialog (AskUserQuestion tool)
        if self.ask_user_dialog.visible {
            match key.code {
                KeyCode::Esc => {
                    self.ask_user_dialog.dismiss();
                }
                KeyCode::Enter => {
                    self.ask_user_dialog.confirm();
                }
                KeyCode::Up | KeyCode::BackTab => {
                    self.ask_user_dialog.select_prev();
                }
                KeyCode::Down | KeyCode::Tab => {
                    self.ask_user_dialog.select_next();
                }
                KeyCode::Char(c)
                    if c.is_ascii_digit()
                        && self.ask_user_dialog.options.is_some()
                        && !self.ask_user_dialog.in_custom_input =>
                {
                    // Digit keys select an option by number ONLY when the user
                    // is not already typing a custom answer.  Once in custom
                    // mode, digits flow through to push_char like any other char.
                    let n = (c as u8 - b'0') as usize;
                    if n >= 1 {
                        self.ask_user_dialog.select_by_number(n);
                    }
                }
                KeyCode::Char(c) => {
                    let c = normalize_char_with_shift(c, key.modifiers);
                    self.ask_user_dialog.push_char(c);
                }
                KeyCode::Backspace => {
                    self.ask_user_dialog.pop_char();
                }
                _ => {}
            }
            return false;
        }

        if self.key_input_dialog.visible {
            match key.code {
                KeyCode::Esc => {
                    self.key_input_dialog.close();
                }
                KeyCode::Enter => {
                    let provider_id = self.key_input_dialog.provider_id.clone();
                    let provider_name = self.key_input_dialog.provider_name.clone();
                    let api_key = self.key_input_dialog.take_key();
                    if !api_key.is_empty() {
                        self.auth_store.set(
                            &provider_id,
                            claurst_core::StoredCredential::ApiKey { key: api_key },
                        );
                        self.activate_provider(provider_id, provider_name, "Connected to");
                    }
                }
                KeyCode::Backspace => {
                    self.key_input_dialog.backspace();
                }
                KeyCode::Char('v')
                    if key.modifiers.contains(KeyModifiers::CONTROL)
                        || key.modifiers.contains(KeyModifiers::SUPER) =>
                {
                    if let Some(text) = crate::image_paste::read_clipboard_text() {
                        if text.is_empty() {
                            self.push_notification(
                                NotificationKind::Warning,
                                "Clipboard is empty".to_string(),
                                Some(2),
                            );
                        } else {
                            for ch in text.chars() {
                                self.key_input_dialog.insert_char(ch);
                            }
                        }
                    } else {
                        self.push_notification(
                            NotificationKind::Warning,
                            "Could not read clipboard".to_string(),
                            Some(2),
                        );
                    }
                }
                KeyCode::Char(c) => {
                    let c = normalize_char_with_shift(c, key.modifiers);
                    self.key_input_dialog.insert_char(c);
                }
                _ => {}
            }
            return false;
        }

        // Connect-a-provider dialog (/connect command)
        if self.connect_dialog.visible {
            match key.code {
                KeyCode::Esc => {
                    self.connect_dialog.close();
                }
                KeyCode::Home => {
                    self.connect_dialog.move_home();
                }
                KeyCode::End => {
                    self.connect_dialog.move_end();
                }
                KeyCode::Up => {
                    self.connect_dialog.move_up();
                }
                KeyCode::Down => {
                    self.connect_dialog.move_down();
                }
                KeyCode::PageUp => {
                    self.connect_dialog.page_up();
                }
                KeyCode::PageDown => {
                    self.connect_dialog.page_down();
                }
                KeyCode::Char('p') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.connect_dialog.move_up();
                }
                KeyCode::Char('n') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.connect_dialog.move_down();
                }
                KeyCode::Enter => {
                    if let Some(selected) = self.connect_dialog.selected().cloned() {
                        self.connect_dialog.close();
                        self.start_connect_selection(selected);
                    }
                }
                KeyCode::Backspace => {
                    self.connect_dialog.filter_pop();
                }
                KeyCode::Char(c) => {
                    self.connect_dialog.filter_push(c);
                }
                _ => {}
            }
            return false;
        }

        // Import-config source picker
        if self.import_config_picker.visible {
            match key.code {
                KeyCode::Esc => {
                    self.import_config_picker.close();
                }
                KeyCode::Home => {
                    self.import_config_picker.move_home();
                }
                KeyCode::End => {
                    self.import_config_picker.move_end();
                }
                KeyCode::Up => {
                    self.import_config_picker.move_up();
                }
                KeyCode::Down => {
                    self.import_config_picker.move_down();
                }
                KeyCode::PageUp => {
                    self.import_config_picker.page_up();
                }
                KeyCode::PageDown => {
                    self.import_config_picker.page_down();
                }
                KeyCode::Char('p') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.import_config_picker.move_up();
                }
                KeyCode::Char('n') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.import_config_picker.move_down();
                }
                KeyCode::Enter => {
                    if let Some(selected) = self.import_config_picker.selected().cloned() {
                        self.import_config_picker.close();
                        if let Some(selection) = Self::import_selection_from_picker(&selected.id) {
                            self.open_import_config_preview(selection);
                        }
                    }
                }
                KeyCode::Backspace => {
                    self.import_config_picker.filter_pop();
                }
                KeyCode::Char(c) => {
                    self.import_config_picker.filter_push(c);
                }
                _ => {}
            }
            return false;
        }

        // Import-config preview dialog
        if self.import_config_dialog.visible {
            match key.code {
                KeyCode::Esc => self.import_config_dialog.close(),
                KeyCode::Enter => self.perform_import_config(),
                _ => {}
            }
            return false;
        }

        // Command palette (Ctrl+K)
        if self.command_palette.visible {
            match key.code {
                KeyCode::Esc => {
                    self.command_palette.close();
                }
                KeyCode::Home => {
                    self.command_palette.move_home();
                }
                KeyCode::End => {
                    self.command_palette.move_end();
                }
                KeyCode::Up => {
                    self.command_palette.move_up();
                }
                KeyCode::Down => {
                    self.command_palette.move_down();
                }
                KeyCode::PageUp => {
                    self.command_palette.page_up();
                }
                KeyCode::PageDown => {
                    self.command_palette.page_down();
                }
                KeyCode::Char('p') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.command_palette.move_up();
                }
                KeyCode::Char('n') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.command_palette.move_down();
                }
                KeyCode::Enter => {
                    if let Some(selected) = self.command_palette.selected().cloned() {
                        self.command_palette.close();
                        // Put the command in the input and signal for execution
                        self.prompt_input.replace_text(selected.id.clone());
                        return true; // signal to submit this as input
                    }
                }
                KeyCode::Backspace => {
                    self.command_palette.filter_pop();
                }
                KeyCode::Char(c) => {
                    self.command_palette.filter_push(c);
                }
                _ => {}
            }
            return false;
        }

        // Invalid-config dialog intercepts Enter/Esc to dismiss
        if self.invalid_config_dialog.visible {
            match key.code {
                KeyCode::Enter | KeyCode::Esc => self.invalid_config_dialog.dismiss(),
                KeyCode::Up => self.invalid_config_dialog.scroll_up(),
                KeyCode::Down => self.invalid_config_dialog.scroll_down(20),
                _ => {}
            }
            return false;
        }

        // Model picker intercepts navigation and Esc
        if self.model_picker.visible {
            match key.code {
                KeyCode::Esc => self.model_picker.close(),
                KeyCode::Home => self.model_picker.select_first(),
                KeyCode::End => self.model_picker.select_last(),
                KeyCode::Up => self.model_picker.select_prev(),
                KeyCode::Down => self.model_picker.select_next(),
                KeyCode::Left => self.model_picker.effort_prev(),
                KeyCode::Right => self.model_picker.effort_next(),
                KeyCode::Char('p') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.model_picker.select_prev()
                }
                KeyCode::Char('n') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    self.model_picker.select_next()
                }
                KeyCode::Enter => {
                    if let Some((model_id, effort)) = self.model_picker.confirm() {
                        // If user picked a model other than the fast-mode model
                        // while fast mode was active, turn fast mode off.
                        if self.fast_mode
                            && !self.model_picker.is_selected_fast_mode_model(&model_id)
                        {
                            self.fast_mode = false;
                        }
                        if let Some(e) = effort {
                            self.effort_level = e;
                            self.effort_is_set = true;
                        }
                        // Store explicit selections in the canonical
                        // "provider/model" form for non-Anthropic providers.
                        let provider = self.config.provider.as_deref().unwrap_or("anthropic");
                        let full_model = if provider == "anthropic" {
                            model_id.clone()
                        } else {
                            format!("{}/{}", provider, model_id)
                        };
                        self.set_model(full_model.clone());
                        self.persist_provider_and_model();
                        let effort_hint = effort
                            .map(|e| format!(" [{}]", e.label()))
                            .unwrap_or_default();
                        self.status_message = Some(format!("Model: {}{}", full_model, effort_hint));
                    }
                }
                KeyCode::Backspace => self.model_picker.pop_filter_char(),
                KeyCode::Char(c) => self.model_picker.push_filter_char(c),
                _ => {}
            }
            return false;
        }

        // Session branching overlay intercepts navigation and Esc
        if self.session_branching.visible {
            use crate::session_branching::BranchBrowserMode;
            match self.session_branching.mode {
                BranchBrowserMode::Browse => match key.code {
                    KeyCode::Esc => self.session_branching.cancel(),
                    KeyCode::Up => self.session_branching.select_prev(),
                    KeyCode::Down => self.session_branching.select_next(),
                    KeyCode::Char('n') => self.session_branching.start_create_new(),
                    KeyCode::Char('d') => self.session_branching.start_delete_confirm(),
                    KeyCode::Enter => {
                        if let Some(branch) = self.session_branching.selected_branch() {
                            self.status_message =
                                Some(format!("Switched to branch: {}", branch.name));
                            self.session_branching.close();
                        }
                    }
                    _ => {}
                },
                BranchBrowserMode::CreateNew => match key.code {
                    KeyCode::Esc => self.session_branching.cancel(),
                    KeyCode::Enter => {
                        if let Some((name, at_msg)) = self.session_branching.confirm_create_new() {
                            self.status_message =
                                Some(format!("Created branch: {} at message {}", name, at_msg));
                            self.session_branching.close();
                        }
                    }
                    KeyCode::Backspace => self.session_branching.pop_create_char(),
                    KeyCode::Char(c) => self.session_branching.push_create_char(c),
                    _ => {}
                },
                BranchBrowserMode::ConfirmDelete => match key.code {
                    KeyCode::Esc | KeyCode::Char('n') => self.session_branching.cancel(),
                    KeyCode::Enter | KeyCode::Char('y') => {
                        if let Some(branch_id) = self.session_branching.confirm_delete() {
                            self.status_message = Some(format!("Deleted branch: {}", branch_id));
                        }
                    }
                    _ => {}
                },
            }
            return false;
        }

        // Session browser intercepts navigation and Esc
        if self.session_browser.visible {
            use crate::session_browser::SessionBrowserMode;
            match self.session_browser.mode {
                SessionBrowserMode::Browse => match key.code {
                    KeyCode::Esc => self.session_browser.close(),
                    KeyCode::Up => self.session_browser.select_prev(),
                    KeyCode::Down => self.session_browser.select_next(),
                    KeyCode::Char('r') => self.session_browser.start_rename(),
                    _ => {}
                },
                SessionBrowserMode::Rename => match key.code {
                    KeyCode::Esc => self.session_browser.cancel(),
                    KeyCode::Enter => {
                        if let Some((_id, name)) = self.session_browser.confirm_rename() {
                            self.session_title = Some(name.clone());
                            self.status_message = Some(format!("Renamed to: {}", name));
                        }
                    }
                    KeyCode::Backspace => self.session_browser.pop_rename_char(),
                    KeyCode::Char(c) => self.session_browser.push_rename_char(c),
                    _ => {}
                },
                SessionBrowserMode::Confirm => match key.code {
                    KeyCode::Esc | KeyCode::Char('n') => self.session_browser.cancel(),
                    KeyCode::Enter | KeyCode::Char('y') => {
                        self.session_browser.close();
                    }
                    _ => {}
                },
            }
            return false;
        }

        // Tasks overlay intercepts navigation and Esc
        if self.tasks_overlay.visible {
            match key.code {
                KeyCode::Esc | KeyCode::Char('q') => self.tasks_overlay.close(),
                KeyCode::Up => self.tasks_overlay.select_prev(),
                KeyCode::Down => self.tasks_overlay.select_next(),
                KeyCode::Enter => {
                    if let Some((task_id, new_status)) =
                        self.tasks_overlay.cycle_and_persist_status()
                    {
                        self.status_message = Some(format!("Task {} → {}", task_id, new_status));
                    }
                }
                _ => {}
            }
            return false;
        }

        // Export dialog key handling
        if self.export_dialog.visible {
            match key.code {
                KeyCode::Esc => {
                    self.export_dialog.dismiss();
                }
                KeyCode::Enter => {
                    if let Some(path) = self.perform_export() {
                        self.push_notification(
                            NotificationKind::Info,
                            format!("Exported to {}", path),
                            Some(4),
                        );
                    } else {
                        self.push_notification(
                            NotificationKind::Warning,
                            "Export failed: could not write file.".to_string(),
                            Some(4),
                        );
                    }
                }
                KeyCode::Tab | KeyCode::Left | KeyCode::Right => {
                    self.export_dialog.toggle();
                }
                KeyCode::Char('1') => {
                    self.export_dialog.selected = ExportFormat::Json;
                }
                KeyCode::Char('2') => {
                    self.export_dialog.selected = ExportFormat::Markdown;
                }
                _ => {}
            }
            return false;
        }

        // Context visualization overlay key handling
        if self.context_viz.visible {
            match key.code {
                KeyCode::Esc | KeyCode::Enter => {
                    self.context_viz.close();
                }
                _ => {}
            }
            return false;
        }

        // MCP approval dialog
        if self.mcp_approval.visible {
            let result = crate::dialogs::handle_mcp_approval_key(&mut self.mcp_approval, key);
            if result.is_some() {
                // Result processed by CLI loop via take_mcp_approval_result()
            }
            return false;
        }

        // Feedback survey intercepts digit keys and Esc
        if self.feedback_survey.visible {
            if key.code == KeyCode::Esc {
                self.feedback_survey.close();
                return false;
            }
            if let KeyCode::Char(c) = key.code {
                if let Some(d) = c.to_digit(10) {
                    self.feedback_survey.handle_digit(d as u8);
                    return false;
                }
            }
            return false;
        }

        // Memory file selector intercepts navigation and Esc
        if self.memory_file_selector.visible {
            match key.code {
                KeyCode::Esc => self.memory_file_selector.close(),
                KeyCode::Up => self.memory_file_selector.select_prev(),
                KeyCode::Down => self.memory_file_selector.select_next(),
                KeyCode::Enter => {
                    // Selection acknowledged — consumer can read selected_path()
                    self.memory_file_selector.close();
                }
                _ => {}
            }
            return false;
        }

        // Hooks config menu intercepts navigation and Esc
        if self.hooks_config_menu.visible {
            match key.code {
                KeyCode::Esc | KeyCode::Char('q') => self.hooks_config_menu.back(),
                KeyCode::Enter => self.hooks_config_menu.enter(),
                KeyCode::Up | KeyCode::Char('k') => self.hooks_config_menu.select_prev(),
                KeyCode::Down | KeyCode::Char('j') => self.hooks_config_menu.select_next(),
                _ => {}
            }
            return false;
        }

        if self.diff_viewer.visible {
            self.handle_diff_viewer_key(key);
            return false;
        }

        if self.agents_menu.visible {
            self.handle_agents_menu_key(key);
            return false;
        }

        if self.mcp_view.visible {
            return self.handle_mcp_view_key(key);
        }

        if self.stats_dialog.visible {
            self.handle_stats_dialog_key(key);
            return false;
        }

        // Settings screen intercepts keys
        if self.settings_screen.visible {
            crate::settings_screen::handle_settings_key(
                &mut self.settings_screen,
                &mut self.config,
                key,
            );
            return false;
        }

        // Theme picker intercepts keys
        if self.theme_screen.visible {
            if let Some(theme_name) =
                crate::theme_screen::handle_theme_key(&mut self.theme_screen, key)
            {
                self.apply_theme(&theme_name);
            }
            return false;
        }

        // Privacy screen intercepts keys
        // Rewind flow overlay intercepts keys first
        if self.rewind_flow.visible {
            return self.handle_rewind_flow_key(key);
        }

        // Help overlay intercepts keys next
        if self.help_overlay.visible {
            return self.handle_help_overlay_key(key);
        }

        // New history-search overlay
        if self.history_search_overlay.visible {
            return self.handle_history_search_overlay_key(key);
        }

        if self.global_search.visible {
            return self.handle_global_search_key(key);
        }

        // Notification dismiss
        if key.code == KeyCode::Esc && !self.notifications.is_empty() {
            self.notifications.dismiss_current();
            return false;
        }

        // Plugin hint dismiss
        if key.code == KeyCode::Esc {
            if let Some(hint) = self.plugin_hints.iter_mut().find(|h| h.is_visible()) {
                hint.dismiss();
                return false;
            }
        }

        // Overage upsell dismiss
        if key.code == KeyCode::Esc && self.overage_upsell.visible {
            self.overage_upsell.dismiss();
            return false;
        }

        // Voice mode notice dismiss
        if key.code == KeyCode::Esc && self.voice_mode_notice.visible {
            self.voice_mode_notice.dismiss();
            return false;
        }

        // Cancel an active voice recording with Esc.
        if key.code == KeyCode::Esc && self.voice_recording {
            self.voice_recording = false;
            self.voice_event_rx = None;
            if let Some(ref recorder_arc) = self.voice_recorder {
                let recorder = recorder_arc.clone();
                tokio::task::spawn_blocking(move || {
                    if let Ok(mut r) = recorder.lock() {
                        tokio::runtime::Handle::current()
                            .block_on(r.stop_recording())
                            .ok();
                    }
                });
            }
            self.status_message = Some("Recording cancelled.".to_string());
            return false;
        }

        // Memory update notification dismiss
        if key.code == KeyCode::Esc && self.memory_update_notification.visible {
            self.memory_update_notification.dismiss();
            return false;
        }

        // MCP elicitation dialog — highest priority modal
        if self.elicitation.visible {
            match key.code {
                KeyCode::Esc => {
                    self.elicitation.cancel();
                    return false;
                }
                KeyCode::Enter => {
                    self.elicitation.submit();
                    return false;
                }
                KeyCode::Tab | KeyCode::Down => {
                    if let crossterm::event::KeyModifiers::SHIFT = key.modifiers {
                        self.elicitation.prev_field();
                    } else {
                        self.elicitation.next_field();
                    }
                    return false;
                }
                KeyCode::BackTab | KeyCode::Up => {
                    self.elicitation.prev_field();
                    return false;
                }
                KeyCode::Left => {
                    self.elicitation.cycle_enum_prev();
                    return false;
                }
                KeyCode::Right => {
                    self.elicitation.cycle_enum_next();
                    return false;
                }
                KeyCode::Char(' ') => {
                    self.elicitation.toggle_active();
                    return false;
                }
                KeyCode::Backspace => {
                    self.elicitation.backspace();
                    return false;
                }
                KeyCode::Char(c) => {
                    let c = normalize_char_with_shift(c, key.modifiers);
                    self.elicitation.insert_char(c);
                    return false;
                }
                _ => return false,
            }
        }

        // ---- Keybinding processor (runs AFTER all dialog checks) ----------
        let key_context = self.current_key_context();
        if let Some(keystroke) = key_event_to_keystroke(&key) {
            let had_pending_chord = self.keybindings.has_pending_chord();
            match self.keybindings.process(keystroke, &key_context) {
                KeybindingResult::Action(action) => {
                    return self.handle_keybinding_action(&action);
                }
                KeybindingResult::Pending => return false,
                KeybindingResult::NoMatch if had_pending_chord => return false,
                KeybindingResult::Unbound | KeybindingResult::NoMatch => {
                    // Fall through to hardcoded keybinding handlers
                }
            }
        } else {
            self.keybindings.cancel_chord();
        }

        // Clear any active text selection on key press (except Ctrl+C which copies it).
        let is_copy =
            key.code == KeyCode::Char('c') && key.modifiers.contains(KeyModifiers::CONTROL);
        if !is_copy && self.selection_anchor.is_some() {
            self.selection_anchor = None;
            self.selection_focus = None;
            *self.selection_text.borrow_mut() = String::new();
        }

        // ---- Voice hold-to-talk (Alt+V toggles recording on/off) ----------
        if key.code == KeyCode::Char('v')
            && key.modifiers.contains(KeyModifiers::ALT)
            && self.voice_recorder.is_some()
        {
            if !self.voice_recording {
                // First press: start recording.
                let (tx, rx) = tokio::sync::mpsc::channel(8);
                self.voice_event_rx = Some(rx);
                self.voice_recording = true;
                if let Some(ref recorder_arc) = self.voice_recorder {
                    let recorder = recorder_arc.clone();
                    // Use spawn_blocking so we don't hold a std::sync::MutexGuard
                    // across an await point.  start_recording internally spawns a
                    // tokio task and returns quickly, so blocking is negligible.
                    tokio::task::spawn_blocking(move || {
                        if let Ok(mut r) = recorder.lock() {
                            // start_recording is async but its real work happens in
                            // a spawned task; use block_on to drive the short setup.
                            tokio::runtime::Handle::current()
                                .block_on(r.start_recording(tx))
                                .ok();
                        }
                    });
                }
                self.push_notification(
                    NotificationKind::Info,
                    "Recording\u{2026} (Alt+V to transcribe · Esc to cancel)".to_string(),
                    None,
                );
            } else {
                // Second press: stop recording.  stop_recording() just flips an
                // AtomicBool; drive it synchronously to avoid Send issues.
                self.voice_recording = false;
                if let Some(ref recorder_arc) = self.voice_recorder {
                    let recorder = recorder_arc.clone();
                    tokio::task::spawn_blocking(move || {
                        if let Ok(mut r) = recorder.lock() {
                            tokio::runtime::Handle::current()
                                .block_on(r.stop_recording())
                                .ok();
                        }
                    });
                }
                self.push_notification(
                    NotificationKind::Info,
                    "Transcribing\u{2026}".to_string(),
                    Some(10),
                );
            }
            return false;
        }

        // Plain-letter `v` is NEVER intercepted as voice PTT.  Earlier
        // versions tried to make plain V a "hold-to-talk" key (press to
        // start, release to stop), but the release event is only delivered
        // on platforms with the kitty keyboard enhancement (mostly Windows
        // with the right terminal). On the rest, the press half fires and
        // the release never does — recording sticks on and eats every
        // subsequent keystroke.  Even on platforms where release works,
        // the press handler was gated on Insert mode, which is exactly
        // when the user is typing and so means literal `v` characters
        // ("review", "version", "verify", `/coven`, …) all trigger voice.
        // Issue #49 fixes this by routing PTT exclusively through Alt+V
        // (handled above) — there is no plain-V intercept anymore.

        // ---- Ctrl+V / Cmd+V — clipboard paste (image first, then text fallback) ----
        // Only fires when NOT in vim Normal/Visual/VisualBlock mode (where \x16 is
        // already consumed by the vim handler above to enter VisualBlock mode).
        if key.code == KeyCode::Char('v')
            && (key.modifiers.contains(KeyModifiers::CONTROL)
                || key.modifiers.contains(KeyModifiers::SUPER))
            && !matches!(
                self.prompt_input.vim_mode,
                crate::prompt_input::VimMode::Normal
                    | crate::prompt_input::VimMode::Visual
                    | crate::prompt_input::VimMode::VisualBlock
            )
        {
            use crate::image_paste::{
                read_clipboard_image, read_clipboard_text, read_primary_text,
            };
            if let Some(img) = read_clipboard_image() {
                let label = img.label.clone();
                let dims = img.dimensions;
                self.prompt_input.add_image(img);
                let msg = if let Some((w, h)) = dims {
                    format!("Image attached: {} ({}x{})", label, w, h)
                } else {
                    format!("Image attached: {}", label)
                };
                self.push_notification(NotificationKind::Info, msg, Some(3));
            } else if let Some(text) = read_clipboard_text().or_else(read_primary_text) {
                self.handle_paste_data(text);
                self.refresh_prompt_input();
            }
            return false;
        }

        // ---- Shift+Insert — selection/clipboard paste fallback -------------
        if key.code == KeyCode::Insert && key.modifiers.contains(KeyModifiers::SHIFT) {
            let _ = self.paste_primary_into_prompt();
            return false;
        }

        // ---- Enter while PTT recording: stop capture instead of submitting ----
        if key.code == KeyCode::Enter && self.voice_recording && self.voice_recorder.is_some() {
            self.handle_voice_ptt_stop();
            return false;
        }

        // ---- Focus state machine: transcript mode --------------------------
        // When the transcript pane has focus, intercept Escape and scroll keys.
        // Printable characters switch focus back to Input and fall through so the
        // keystroke is processed normally by the prompt editor below.
        if self.focus == FocusTarget::Transcript {
            match key.code {
                KeyCode::Esc => {
                    self.focus = FocusTarget::Input;
                    return false;
                }
                KeyCode::PageUp | KeyCode::PageDown => {
                    // Let these fall through to the normal scroll handling below.
                }
                KeyCode::Char(_)
                    if !key.modifiers.contains(KeyModifiers::CONTROL)
                        && !key.modifiers.contains(KeyModifiers::ALT) =>
                {
                    // Printable char: switch focus to Input and process normally.
                    self.focus = FocusTarget::Input;
                }
                _ => {}
            }
        }

        match key.code {
            // ---- ESC: cancel streaming (status bar advertises "esc interrupt") ----
            KeyCode::Esc if self.is_streaming => {
                self.is_streaming = false;
                self.spinner_verb = None;
                self.streaming_text.clear();
                self.streaming_thinking.clear();
                self.tool_use_blocks.clear();
                self.status_message = Some("Cancelled.".to_string());
                self.complete_current_turn_snapshot(true);
            }

            // ---- Quit / cancel ----------------------------------------
            // Accept both 'c' and 'C' so Shift+Ctrl+C also triggers copy
            // (issue #149 follow-up).
            KeyCode::Char(c)
                if (c == 'c' || c == 'C') && key.modifiers.contains(KeyModifiers::CONTROL) =>
            {
                // If text is selected, copy it to clipboard instead of quitting.
                let sel_text = self.selection_text.borrow().clone();
                if self.selection_anchor.is_some() && !sel_text.is_empty() {
                    // Text is selected: copy to clipboard.
                    let copied = crate::image_paste::write_clipboard_text(&sel_text);
                    self.selection_anchor = None;
                    self.selection_focus = None;
                    *self.selection_text.borrow_mut() = String::new();
                    if copied {
                        self.push_notification(
                            NotificationKind::Info,
                            "Copied to clipboard".to_string(),
                            Some(2),
                        );
                    }
                } else if self.is_streaming {
                    // Cancel streaming.
                    self.is_streaming = false;
                    self.spinner_verb = None;
                    self.streaming_text.clear();
                    self.streaming_thinking.clear();
                    self.tool_use_blocks.clear();
                    self.status_message = Some("Cancelled.".to_string());
                    self.complete_current_turn_snapshot(true);
                } else {
                    // No text selected and not streaming: handle exit confirmation sequence.
                    // Always clear the prompt input on Ctrl+C.
                    if !self.prompt_input.is_empty() {
                        self.prompt_input.clear();
                        self.refresh_prompt_input();
                    }
                    self.handle_exit_key_confirmation('c');
                }
            }
            KeyCode::Char('d')
                if key.modifiers.contains(KeyModifiers::CONTROL)
                    && self.prompt_input.is_empty() =>
            {
                // Ctrl+D on empty input: trigger two-press exit confirmation (like Ctrl+C).
                self.handle_exit_key_confirmation('d');
            }
            KeyCode::Char('d') if key.modifiers.contains(KeyModifiers::CONTROL) => {}

            // ---- History search ----------------------------------------
            KeyCode::Char('r') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.history_search_overlay =
                    HistorySearchOverlay::open(&self.prompt_input.history);
            }
            KeyCode::Char('p') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.global_search.open();
                self.refresh_global_search();
            }

            // ---- Tasks overlay (Ctrl+T) --------------------------------
            KeyCode::Char('t') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.tasks_overlay.toggle();
            }

            // ---- Help overlay ------------------------------------------
            KeyCode::F(1) => {
                self.help_overlay.toggle();
            }
            KeyCode::F(2) => {
                if self.familiar_switcher_open {
                    self.close_familiar_switcher();
                } else {
                    // Re-read the roster on open so mid-session edits to
                    // ~/.coven/familiars.toml (by the user or the daemon)
                    // show up without restarting.
                    self.familiar_switcher_list = Self::default_familiar_switcher_list();
                    if self.familiar_switcher_list.is_empty() {
                        self.bootstrap_or_prompt_familiar_roster();
                    } else {
                        self.familiar_switcher_open = true;
                        self.familiar_switcher_filter.clear();
                        // Highlight the active familiar if one is set; otherwise
                        // start at the top. Entries lead with the "clear" row, so
                        // account for that offset when locating the active id.
                        let entries = self.familiar_switcher_entries();
                        self.familiar_switcher_idx = self
                            .config
                            .familiar
                            .as_deref()
                            .and_then(|current| {
                                entries.iter().position(|e| {
                                    matches!(e, FamiliarSwitcherEntry::Familiar(id) if id == current)
                                })
                            })
                            .unwrap_or(0);
                    }
                }
            }
            KeyCode::Char('?')
                if !self.is_streaming
                    && self.prompt_input.is_empty()
                    && !key.modifiers.contains(KeyModifiers::CONTROL)
                    && !key.modifiers.contains(KeyModifiers::ALT)
                    && !key.modifiers.contains(KeyModifiers::SUPER) =>
            {
                self.help_overlay.toggle();
            }
            // With the kitty keyboard protocol, Shift+/ is reported as Char('/') with
            // SHIFT rather than Char('?'), so also accept that form for the help toggle.
            KeyCode::Char('/')
                if key.modifiers.contains(KeyModifiers::SHIFT)
                    && !self.is_streaming
                    && self.prompt_input.is_empty()
                    && !key.modifiers.contains(KeyModifiers::CONTROL)
                    && !key.modifiers.contains(KeyModifiers::ALT)
                    && !key.modifiers.contains(KeyModifiers::SUPER) =>
            {
                self.help_overlay.toggle();
            }

            KeyCode::Char('u') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.prompt_input.kill_line_backward();
                self.refresh_prompt_input();
            }
            KeyCode::Char('w') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.prompt_input.kill_word_backward();
                self.refresh_prompt_input();
            }
            KeyCode::Char('y') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.prompt_input.yank();
                self.refresh_prompt_input();
            }

            // ---- Alt/Meta key text editing operations -------------------
            KeyCode::Char('y') if key.modifiers.contains(KeyModifiers::ALT) => {
                self.prompt_input.yank_pop();
                self.refresh_prompt_input();
            }
            KeyCode::Backspace if key.modifiers.contains(KeyModifiers::ALT) => {
                self.prompt_input.delete_word_backward();
                self.refresh_prompt_input();
            }
            KeyCode::Backspace if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.prompt_input.delete_word_backward();
                self.refresh_prompt_input();
            }
            KeyCode::Delete if key.modifiers.contains(KeyModifiers::ALT) => {
                self.prompt_input.delete_word_forward();
                self.refresh_prompt_input();
            }
            KeyCode::Char('b') if key.modifiers.contains(KeyModifiers::ALT) => {
                self.prompt_input.move_word_backward();
                self.sync_legacy_prompt_fields();
            }
            KeyCode::Char('f') if key.modifiers.contains(KeyModifiers::ALT) => {
                self.prompt_input.move_word_forward();
                self.sync_legacy_prompt_fields();
            }
            KeyCode::Char('d') if key.modifiers.contains(KeyModifiers::ALT) => {
                self.prompt_input.delete_word_at_cursor();
                self.refresh_prompt_input();
            }

            // ---- Text entry (allowed while streaming so users can queue
            // the next message; submission queues via Enter at the CLI layer).
            KeyCode::Char(c) => {
                let c = normalize_char_with_shift(c, key.modifiers);
                if self.prompt_input.vim_enabled && self.prompt_input.vim_mode != VimMode::Insert {
                    self.prompt_input.vim_command(&c.to_string());
                } else {
                    self.prompt_input.insert_char(c);
                }
                self.refresh_prompt_input();
            }
            KeyCode::Backspace => {
                self.prompt_input.backspace();
                self.refresh_prompt_input();
            }
            KeyCode::Delete if !key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.prompt_input.delete();
                self.refresh_prompt_input();
            }
            KeyCode::Delete if key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.prompt_input.delete_word_forward();
                self.refresh_prompt_input();
            }
            KeyCode::Left => {
                if key.modifiers.contains(KeyModifiers::SUPER) {
                    self.prompt_input.cursor = 0;
                } else if key.modifiers.contains(KeyModifiers::CONTROL) {
                    self.prompt_input.move_word_backward();
                } else {
                    self.prompt_input.move_left();
                }
                self.sync_legacy_prompt_fields();
            }
            KeyCode::Right => {
                if key.modifiers.contains(KeyModifiers::SUPER) {
                    self.prompt_input.cursor = self.prompt_input.text.len();
                } else if key.modifiers.contains(KeyModifiers::CONTROL) {
                    self.prompt_input.move_word_forward();
                } else {
                    self.prompt_input.move_right();
                }
                self.sync_legacy_prompt_fields();
            }
            KeyCode::Home => {
                self.prompt_input.cursor = 0;
                self.sync_legacy_prompt_fields();
            }
            KeyCode::End => {
                self.prompt_input.cursor = self.prompt_input.text.len();
                self.sync_legacy_prompt_fields();
            }
            KeyCode::Tab => {
                if !self.prompt_input.suggestions.is_empty() {
                    // Accept slash-command suggestion. Allowed while streaming
                    // so the typeahead popup is interactive even when a turn
                    // is in flight — Enter then queues the completed command.
                    if self.prompt_input.suggestion_index.is_none() {
                        self.prompt_input.suggestion_index = Some(0);
                    }
                    self.prompt_input.accept_suggestion();
                    self.refresh_prompt_input();
                } else if !self.is_streaming && self.prompt_input.is_empty() {
                    // Cycle agent mode: build → plan → explore → build
                    self.cycle_agent_mode();
                    self.companion_look_down();
                }
            }

            // ---- Shift+Tab: cycle permission mode ----------------------
            // Default → AcceptEdits → BypassPermissions → Default
            // Mirrors TS bottom-left indicator cycling behaviour.
            KeyCode::BackTab if !self.is_streaming => {
                use claurst_core::config::PermissionMode;
                self.config.permission_mode = match self.config.permission_mode {
                    PermissionMode::Default => PermissionMode::AcceptEdits,
                    PermissionMode::AcceptEdits => PermissionMode::BypassPermissions,
                    PermissionMode::BypassPermissions => PermissionMode::Default,
                    PermissionMode::Plan => PermissionMode::Default,
                };
                let label = match self.config.permission_mode {
                    PermissionMode::Default => "Default permissions",
                    PermissionMode::AcceptEdits => "Accept-edits mode",
                    PermissionMode::BypassPermissions => "Bypass permissions (dangerous)",
                    PermissionMode::Plan => "Plan mode",
                };
                self.status_message = Some(label.to_string());
            }

            // ---- Submit ------------------------------------------------
            // Shift+Enter / Alt+Enter / Ctrl+Enter insert a literal newline
            // so users can compose multi-line prompts before sending
            // (issue #149 follow-up).
            KeyCode::Enter
                if !self.is_streaming
                    && (key.modifiers.contains(KeyModifiers::SHIFT)
                        || key.modifiers.contains(KeyModifiers::ALT)
                        || key.modifiers.contains(KeyModifiers::CONTROL)) =>
            {
                self.prompt_input.insert_newline();
                self.refresh_prompt_input();
            }
            KeyCode::Enter if !self.is_streaming => {
                // If a suggestion is selected, accept it instead of submitting.
                if !self.prompt_input.suggestions.is_empty()
                    && self.prompt_input.suggestion_index.is_some()
                {
                    let is_file_ref = self
                        .prompt_input
                        .suggestions
                        .get(self.prompt_input.suggestion_index.unwrap())
                        .is_some_and(|s| s.source == crate::prompt_input::TypeaheadSource::FileRef);
                    self.prompt_input.accept_suggestion();
                    if is_file_ref {
                        self.prompt_input.insert_char(' ');
                    }
                    self.refresh_prompt_input();
                    return false;
                }
                // Auto-dismiss all error notifications when user sends a message
                self.dismiss_error_notifications();
                // New user input: snap back to bottom.
                self.auto_scroll = true;
                self.new_messages_while_scrolled = 0;
                self.scroll_offset = 0;
                return true;
            }

            // ---- Message boundary navigation (Alt+Up/Alt+Down) ----------
            KeyCode::Up if key.modifiers.contains(KeyModifiers::ALT) => {
                // Jump up by ~20 lines (approximate message boundary).
                self.scroll_offset = self.scroll_offset.saturating_add(20);
                self.auto_scroll = false;
            }
            KeyCode::Down if key.modifiers.contains(KeyModifiers::ALT) => {
                // Jump down by ~20 lines (approximate message boundary).
                let new_off = self.scroll_offset.saturating_sub(20);
                self.scroll_offset = new_off;
                if new_off == 0 {
                    self.auto_scroll = true;
                    self.new_messages_while_scrolled = 0;
                }
            }

            // ---- Input history navigation ------------------------------
            // For multi-line / wrapped prompts: Up/Down move the cursor by
            // one visual row first, only falling through to history recall
            // when the cursor is already on the first/last visual row
            // (issue #149 follow-up).
            KeyCode::Up => {
                if !self.prompt_input.suggestions.is_empty()
                    && (self.prompt_input.text.starts_with('/')
                        || self.prompt_input.has_active_file_ref())
                {
                    self.prompt_input.suggestion_prev();
                } else {
                    let area = self.last_input_area.get();
                    let width = area.width.saturating_sub(4) as usize;
                    let moved = !self.prompt_input.text.is_empty()
                        && self.prompt_input.move_visual_up(width);
                    if !moved && !self.prompt_input.history.is_empty() {
                        self.prompt_input.history_up();
                    }
                }
                self.refresh_prompt_input();
            }
            KeyCode::Down => {
                if !self.prompt_input.suggestions.is_empty()
                    && (self.prompt_input.text.starts_with('/')
                        || self.prompt_input.has_active_file_ref())
                {
                    self.prompt_input.suggestion_next();
                } else {
                    let area = self.last_input_area.get();
                    let width = area.width.saturating_sub(4) as usize;
                    let moved = !self.prompt_input.text.is_empty()
                        && self.prompt_input.move_visual_down(width);
                    if !moved && self.prompt_input.history_pos.is_some() {
                        self.prompt_input.history_down();
                    }
                }
                self.refresh_prompt_input();
            }

            // ---- Scroll ------------------------------------------------
            KeyCode::PageUp => {
                self.scroll_offset = self.scroll_offset.saturating_add(10);
                // Scrolling up disables auto-follow.
                self.auto_scroll = false;
            }
            KeyCode::PageDown => {
                let new_off = self.scroll_offset.saturating_sub(10);
                self.scroll_offset = new_off;
                if new_off == 0 {
                    // Scrolled all the way back to bottom — re-enable auto-follow.
                    self.auto_scroll = true;
                    self.new_messages_while_scrolled = 0;
                }
            }

            // ---- Toggle last thinking block (t key) -------------------
            // (Removed: shadowed by KeyCode::Char(c) prompt input handler.)
            _ => {}
        }

        // Reset exit confirmation sequence if user presses any key other than Ctrl+C or Ctrl+D.
        let is_exit_key = key.modifiers.contains(KeyModifiers::CONTROL)
            && matches!(key.code, KeyCode::Char(c) if c == 'c' || c == 'd' || c == 'C' || c == 'D');
        if !is_exit_key {
            self.last_exit_key_warning = None;
            self.exit_key_sequence_start = None;
        }

        false
    }

    fn current_key_context(&self) -> KeyContext {
        if self.diff_viewer.visible {
            KeyContext::DiffDialog
        } else if self.agents_menu.visible || self.mcp_view.visible || self.stats_dialog.visible {
            KeyContext::Select
        } else if self.import_config_dialog.visible {
            KeyContext::Confirmation
        } else if self.settings_screen.visible {
            KeyContext::Settings
        } else if self.theme_screen.visible {
            KeyContext::ThemePicker
        } else if self.rewind_flow.visible {
            KeyContext::Confirmation
        } else if self.help_overlay.visible {
            KeyContext::Help
        } else if self.history_search_overlay.visible {
            KeyContext::HistorySearch
        } else if self.permission_request.is_some() {
            KeyContext::Confirmation
        } else {
            KeyContext::Chat
        }
    }

    // -------------------------------------------------------------------
    // New overlay key handlers
    // -------------------------------------------------------------------

    fn handle_stats_dialog_key(&mut self, key: KeyEvent) {
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') => self.stats_dialog.close(),
            KeyCode::Tab | KeyCode::Right => self.stats_dialog.next_tab(),
            KeyCode::BackTab | KeyCode::Left => self.stats_dialog.prev_tab(),
            KeyCode::Char('r') => self.stats_dialog.cycle_range(),
            KeyCode::Up => self.stats_dialog.scroll = self.stats_dialog.scroll.saturating_sub(1),
            KeyCode::Down => self.stats_dialog.scroll = self.stats_dialog.scroll.saturating_add(1),
            _ => {}
        }
    }

    fn handle_mcp_view_key(&mut self, key: KeyEvent) -> bool {
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') => self.mcp_view.close(),
            KeyCode::Tab | KeyCode::Left | KeyCode::Right => self.mcp_view.switch_pane(),
            KeyCode::Up => self.mcp_view.select_prev(),
            KeyCode::Down => self.mcp_view.select_next(),
            KeyCode::Backspace => self.mcp_view.pop_search_char(),
            KeyCode::Char('e') => self.mcp_view.toggle_error_detail(),
            KeyCode::Char('a')
                if self.mcp_view.active_pane == crate::mcp_view::McpViewPane::ServerList =>
            {
                let selected_server = self
                    .mcp_view
                    .servers
                    .get(self.mcp_view.selected_server)
                    .map(|server| server.name.clone());
                if let Some(server_name) = selected_server {
                    self.pending_mcp_panel_auth = Some(server_name);
                    self.mcp_view.close();
                    self.status_message = Some("Starting MCP auth...".to_string());
                }
            }
            KeyCode::Char('r') => {
                self.pending_mcp_reconnect = true;
                self.status_message = Some("Reconnecting MCP runtime...".to_string());
            }
            KeyCode::Char(c)
                if key.modifiers.is_empty()
                    && self.mcp_view.active_pane != crate::mcp_view::McpViewPane::ServerList =>
            {
                self.mcp_view.push_search_char(c);
            }
            KeyCode::Char(_) if key.modifiers.is_empty() => {}
            _ => {}
        }
        false
    }

    fn handle_agents_menu_key(&mut self, key: KeyEvent) {
        if matches!(self.agents_menu.route, AgentsRoute::ResetConfirm) {
            match key.code {
                KeyCode::Enter | KeyCode::Char('y') => self.reset_agents_and_familiars(),
                KeyCode::Esc | KeyCode::Char('n') | KeyCode::Backspace | KeyCode::Left => {
                    self.agents_menu.go_back();
                }
                _ => {}
            }
            return;
        }

        if matches!(self.agents_menu.route, AgentsRoute::Editor(_)) {
            match key.code {
                KeyCode::Esc => self.agents_menu.go_back(),
                KeyCode::Tab | KeyCode::Down => self.agents_menu.editor_next_field(),
                KeyCode::BackTab | KeyCode::Up => self.agents_menu.editor_prev_field(),
                KeyCode::Enter => self.agents_menu.editor_insert_newline(),
                KeyCode::Backspace => self.agents_menu.editor_backspace(),
                KeyCode::Char('s') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    match self.agents_menu.save_editor() {
                        Ok(msg) => self.status_message = Some(msg),
                        Err(err) => {
                            self.agents_menu.editor.error = Some(err.clone());
                            self.agents_menu.editor.saved_message = None;
                            self.status_message = Some(err);
                        }
                    }
                }
                KeyCode::Char(ch) if !key.modifiers.contains(KeyModifiers::CONTROL) => {
                    let ch = normalize_char_with_shift(ch, key.modifiers);
                    self.agents_menu.editor_insert_char(ch);
                }
                _ => {}
            }
            return;
        }

        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Backspace => self.agents_menu.go_back(),
            KeyCode::Up | KeyCode::Char('k') => self.agents_menu.select_prev(),
            KeyCode::Down | KeyCode::Char('j') => self.agents_menu.select_next(),
            KeyCode::Enter | KeyCode::Right => {
                if let Some((id, display)) = self.agents_menu.confirm_selection() {
                    self.activate_familiar_agent(id, display);
                }
            }
            KeyCode::Char('d') if key.modifiers.is_empty() => {
                self.status_message = Some(match self.agents_menu.delete_selected_definition() {
                    Ok(msg) => msg,
                    Err(err) => err,
                });
            }
            KeyCode::Left => self.agents_menu.go_back(),
            _ => {}
        }
    }

    fn reset_agents_and_familiars(&mut self) {
        match self.agents_menu.reset_saved_roster() {
            Ok(summary) => {
                self.config.agents.clear();
                self.config.familiar = None;
                self.config.managed_agents = None;
                self.agent_mode = None;
                self.agent_mode_changed = true;
                self.accent_color = accent_for_mode(None);
                self.plan_mode = false;
                if self.config.permission_mode == claurst_core::config::PermissionMode::Plan {
                    self.config.permission_mode = claurst_core::config::PermissionMode::Default;
                }
                self.managed_agents_active = false;
                self.close_familiar_switcher();
                self.familiar_switcher_list.clear();
                self.status_message = Some(summary.message());
            }
            Err(err) => {
                self.status_message = Some(err);
            }
        }
    }

    /// Activate a Coven familiar as the session's agent mode and close the picker.
    ///
    /// Every familiar-activation surface (agents menu, F2 switcher, the
    /// /familiar command) converges on the same three effects: the mascot
    /// (`config.familiar`), the persisted setting, and the agent definition
    /// whose access tier drives the runtime tool filter.
    fn activate_familiar_agent(&mut self, id: String, display: String) {
        self.agents_menu.close();
        self.config.familiar = Some(id.clone());
        self.persist_familiar_setting(Some(id.clone()));
        self.apply_familiar_agent_mode(Some(id), Some(&display));
    }

    /// Persist the familiar choice to settings.json (best-effort — a failed
    /// write surfaces as a warning and the in-memory switch still applies).
    fn persist_familiar_setting(&mut self, target: Option<String>) {
        let result = Settings::load_sync().and_then(|mut settings| {
            settings.config.familiar = target;
            settings.save_sync()
        });
        if let Err(err) = result {
            self.push_notification(
                NotificationKind::Warning,
                format!("Could not save familiar setting: {err}"),
                Some(4),
            );
        }
    }

    /// Sync the session agent mode to a familiar choice. Sets
    /// `agent_mode_changed` so the main loop swaps `query_config.agent_definition`
    /// and re-filters the tool list according to the familiar's access tier.
    /// `None` steps back down to the default (full-access, no persona) mode.
    pub fn apply_familiar_agent_mode(&mut self, id: Option<String>, display: Option<&str>) {
        match id {
            Some(id) => {
                let label = display.unwrap_or(id.as_str()).to_string();
                self.agent_mode = Some(id);
                self.agent_mode_changed = true;
                self.accent_color = accent_for_mode(self.agent_mode.as_deref());
                self.plan_mode = false;
                self.status_message = Some(format!("Switched to {} familiar.", label));
            }
            None => {
                self.config.familiar = None;
                self.agent_mode = None;
                self.agent_mode_changed = true;
                self.accent_color = accent_for_mode(None);
                self.plan_mode = false;
            }
        }
    }

    fn handle_diff_viewer_key(&mut self, key: KeyEvent) {
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') => self.diff_viewer.close(),
            KeyCode::Tab | KeyCode::Left | KeyCode::Right => self.diff_viewer.switch_pane(),
            KeyCode::Char('d') => {
                let root = self.project_root();
                self.diff_viewer.toggle_diff_type(&root);
            }
            KeyCode::Up => {
                if self.diff_viewer.active_pane == DiffPane::FileList {
                    self.diff_viewer.select_prev();
                } else {
                    self.diff_viewer.scroll_detail_up();
                }
            }
            KeyCode::Down => {
                if self.diff_viewer.active_pane == DiffPane::FileList {
                    self.diff_viewer.select_next();
                } else {
                    self.diff_viewer.scroll_detail_down();
                }
            }
            KeyCode::PageUp => self.diff_viewer.scroll_detail_up(),
            KeyCode::PageDown => self.diff_viewer.scroll_detail_down(),
            KeyCode::Char(' ') if self.diff_viewer.active_pane == DiffPane::FileList => {
                self.diff_viewer.toggle_file_collapse();
            }
            KeyCode::Char(' ') => {}
            _ => {}
        }
    }

    fn handle_help_overlay_key(&mut self, key: KeyEvent) -> bool {
        match key.code {
            KeyCode::Esc | KeyCode::F(1) => {
                self.help_overlay.close();
            }
            KeyCode::Char('?')
                if !key.modifiers.contains(KeyModifiers::CONTROL)
                    && !key.modifiers.contains(KeyModifiers::ALT)
                    && !key.modifiers.contains(KeyModifiers::SUPER) =>
            {
                self.help_overlay.close();
            }
            KeyCode::Up => {
                self.help_overlay.scroll_up();
            }
            KeyCode::Down => {
                let max = 50u16; // generous upper bound; renderer will clamp
                self.help_overlay.scroll_down(max);
            }
            KeyCode::Backspace => {
                self.help_overlay.pop_filter_char();
            }
            KeyCode::Char(c) if !key.modifiers.contains(KeyModifiers::CONTROL) => {
                self.help_overlay.push_filter_char(c);
            }
            _ => {}
        }
        false
    }

    fn handle_history_search_overlay_key(&mut self, key: KeyEvent) -> bool {
        match key.code {
            KeyCode::Esc => {
                self.history_search_overlay.close();
            }
            KeyCode::Enter => {
                if let Some(entry) = self
                    .history_search_overlay
                    .current_entry(&self.prompt_input.history)
                {
                    self.set_prompt_text(entry.to_string());
                }
                self.history_search_overlay.close();
            }
            KeyCode::Up => {
                self.history_search_overlay.select_prev();
            }
            KeyCode::Down => {
                self.history_search_overlay.select_next();
            }
            KeyCode::Backspace => {
                let history = self.prompt_input.history.clone();
                self.history_search_overlay.pop_char(&history);
            }
            // 'p' with no modifiers and an empty query = pin/unpin the selected entry.
            // When the query is non-empty 'p' is treated as a filter character so
            // the user can still search for prompts containing the letter 'p'.
            KeyCode::Char('p')
                if !key.modifiers.contains(KeyModifiers::CONTROL)
                    && self.history_search_overlay.query.is_empty() =>
            {
                self.history_search_overlay.toggle_pin();
            }
            KeyCode::Char(c) if !key.modifiers.contains(KeyModifiers::CONTROL) => {
                let c = normalize_char_with_shift(c, key.modifiers);
                let history = self.prompt_input.history.clone();
                self.history_search_overlay.push_char(c, &history);
            }
            _ => {}
        }
        false
    }

    fn handle_rewind_flow_key(&mut self, key: KeyEvent) -> bool {
        use crate::overlays::RewindStep;
        match &self.rewind_flow.step {
            RewindStep::Selecting => match key.code {
                KeyCode::Esc => {
                    self.rewind_flow.close();
                }
                KeyCode::Enter => {
                    self.rewind_flow.confirm_selection();
                }
                KeyCode::Up => {
                    self.rewind_flow.selector.select_prev();
                }
                KeyCode::Down => {
                    self.rewind_flow.selector.select_next();
                }
                _ => {}
            },
            RewindStep::Confirming { .. } => match key.code {
                KeyCode::Char('y') | KeyCode::Char('Y') => {
                    if let Some(idx) = self.rewind_flow.accept_confirm() {
                        // Truncate conversation to the selected message index.
                        self.messages.truncate(idx);
                        // Remove system annotations placed after the truncation point.
                        self.system_annotations.retain(|a| a.after_index <= idx);
                        self.push_notification(
                            NotificationKind::Success,
                            format!("Rewound to message #{}", idx),
                            Some(4),
                        );
                    }
                }
                KeyCode::Char('n') | KeyCode::Char('N') | KeyCode::Esc => {
                    self.rewind_flow.reject_confirm();
                }
                _ => {}
            },
        }
        false
    }

    fn handle_global_search_key(&mut self, key: KeyEvent) -> bool {
        match key.code {
            KeyCode::Esc => {
                self.global_search.close();
            }
            KeyCode::Enter => {
                if let Some(selected) = self.global_search.selected_ref() {
                    self.set_prompt_text(selected);
                }
                self.global_search.close();
            }
            KeyCode::Up => self.global_search.select_prev(),
            KeyCode::Down => self.global_search.select_next(),
            KeyCode::Backspace => {
                self.global_search.pop_char();
                self.refresh_global_search();
            }
            KeyCode::Char(c) if !key.modifiers.contains(KeyModifiers::CONTROL) => {
                let c = normalize_char_with_shift(c, key.modifiers);
                self.global_search.push_char(c);
                self.refresh_global_search();
            }
            _ => {}
        }
        false
    }

    fn handle_exit_key_confirmation(&mut self, mut key_char: char) {
        fn exit_message(key: char) -> &'static str {
            if key == 'c' {
                "Press Ctrl+C again to exit"
            } else {
                "Press Ctrl+D again to exit"
            }
        }

        // Check if we have an active warning within the timeout
        if let Some(warning_time) = self.last_exit_key_warning {
            if warning_time.elapsed().as_secs_f64() <= 2.0 {
                if self.exit_key_sequence_start == Some(key_char) {
                    // Matching key - exit
                    self.should_exit = true;
                    self.last_exit_key_warning = None;
                    self.exit_key_sequence_start = None;
                    return;
                }
                if let Some(other_key) = self.exit_key_sequence_start {
                    // Wrong key pressed - show message for the original key and reset timer
                    key_char = other_key;
                }
            }
        }

        // Start new sequence (or show message for wrong key)
        self.push_notification(
            NotificationKind::Info,
            exit_message(key_char).to_string(),
            Some(2),
        );
        self.last_exit_key_warning = Some(std::time::Instant::now());
        self.exit_key_sequence_start = Some(key_char);
    }

    fn handle_keybinding_action(&mut self, action: &str) -> bool {
        match action {
            "interrupt" => {
                if self.is_streaming {
                    self.is_streaming = false;
                    self.spinner_verb = None;
                    self.streaming_text.clear();
                    self.streaming_thinking.clear();
                    self.tool_use_blocks.clear();
                    self.status_message = Some("Cancelled.".to_string());
                } else {
                    // Handle exit confirmation: require two exit key presses within 2 seconds.
                    // Always clear the prompt input on Ctrl+C.
                    if !self.prompt_input.is_empty() {
                        self.prompt_input.clear();
                        self.refresh_prompt_input();
                    }

                    self.handle_exit_key_confirmation('c');
                }
                false
            }
            "exit" => {
                if self.prompt_input.is_empty() {
                    self.should_exit = true;
                }
                false
            }
            "redraw" => false,
            "historySearch" => {
                self.history_search_overlay =
                    HistorySearchOverlay::open(&self.prompt_input.history);
                false
            }
            "openSearch" => {
                self.global_search.open();
                self.refresh_global_search();
                false
            }
            "submit" if !self.is_streaming => {
                if !self.prompt_input.suggestions.is_empty()
                    && self.prompt_input.suggestion_index.is_some()
                {
                    self.prompt_input.accept_suggestion();
                    self.refresh_prompt_input();
                    false
                } else {
                    true
                }
            }
            "submit" => false,
            "historyPrev" => {
                // Suggestions (slash commands or file refs) take priority over cursor/history.
                if !self.prompt_input.suggestions.is_empty()
                    && (self.prompt_input.text.starts_with('/')
                        || self.prompt_input.has_active_file_ref())
                {
                    self.prompt_input.suggestion_prev();
                    self.refresh_prompt_input();
                } else {
                    let width = self.last_input_area.get().width.saturating_sub(4) as usize;
                    let moved = !self.prompt_input.text.is_empty()
                        && self.prompt_input.move_visual_up(width);
                    if !moved && !self.prompt_input.history.is_empty() {
                        self.prompt_input.history_up();
                    }
                    self.refresh_prompt_input();
                }
                false
            }
            "historyNext" => {
                // Suggestions (slash commands or file refs) take priority over cursor/history.
                if !self.prompt_input.suggestions.is_empty()
                    && (self.prompt_input.text.starts_with('/')
                        || self.prompt_input.has_active_file_ref())
                {
                    self.prompt_input.suggestion_next();
                    self.refresh_prompt_input();
                } else {
                    let width = self.last_input_area.get().width.saturating_sub(4) as usize;
                    let moved = !self.prompt_input.text.is_empty()
                        && self.prompt_input.move_visual_down(width);
                    if !moved && self.prompt_input.history_pos.is_some() {
                        self.prompt_input.history_down();
                    }
                    self.refresh_prompt_input();
                }
                false
            }
            "goLineStart" => {
                if !self.is_streaming {
                    self.prompt_input.cursor = 0;
                    self.sync_legacy_prompt_fields();
                }
                false
            }
            "goLineEnd" => {
                if !self.is_streaming {
                    self.prompt_input.cursor = self.prompt_input.text.len();
                    self.sync_legacy_prompt_fields();
                }
                false
            }
            "killToStart" => {
                if !self.is_streaming {
                    self.prompt_input.kill_line_backward();
                    self.refresh_prompt_input();
                }
                false
            }
            "killWord" => {
                if !self.is_streaming {
                    self.prompt_input.kill_word_backward();
                    self.refresh_prompt_input();
                }
                false
            }
            "scrollUp" => {
                self.scroll_offset = self.scroll_offset.saturating_add(10);
                self.auto_scroll = false;
                false
            }
            "scrollDown" => {
                let new_off = self.scroll_offset.saturating_sub(10);
                self.scroll_offset = new_off;
                if new_off == 0 {
                    self.auto_scroll = true;
                    self.new_messages_while_scrolled = 0;
                }
                false
            }
            "yes" => {
                self.permission_request = None;
                false
            }
            "no" => {
                self.permission_request = None;
                false
            }
            "prevOption" => {
                if let Some(pr) = self.permission_request.as_mut() {
                    if pr.selected_option > 0 {
                        pr.selected_option -= 1;
                    }
                }
                false
            }
            "nextOption" => {
                if let Some(pr) = self.permission_request.as_mut() {
                    if pr.selected_option + 1 < pr.options.len() {
                        pr.selected_option += 1;
                    }
                }
                false
            }
            "close" => {
                self.help_overlay.close();
                false
            }
            "select" => {
                if self.history_search_overlay.visible {
                    if let Some(entry) = self
                        .history_search_overlay
                        .current_entry(&self.prompt_input.history)
                    {
                        self.set_prompt_text(entry.to_string());
                    }
                }
                self.history_search_overlay.close();
                false
            }
            "cancel" => {
                self.history_search_overlay.close();
                false
            }
            "prevResult" => {
                self.history_search_overlay.select_prev();
                false
            }
            "nextResult" => {
                self.history_search_overlay.select_next();
                false
            }
            // ========== NEW KEYBINDING ACTIONS (Phase 1) ==========
            "clearLine" => {
                // Ctrl+L: Clear the current input line (like bash Ctrl+L)
                if !self.is_streaming {
                    self.prompt_input.text.clear();
                    self.prompt_input.cursor = 0;
                    self.refresh_prompt_input();
                }
                false
            }
            "deleteCharBefore" => {
                // Ctrl+H: Delete character before cursor (backspace equivalent)
                if !self.is_streaming {
                    self.prompt_input.backspace();
                    self.refresh_prompt_input();
                }
                false
            }
            "previousMessage" => {
                // Alt+←: Navigate to previous message in transcript
                self.scroll_offset = self.scroll_offset.saturating_add(5);
                self.auto_scroll = false;
                false
            }
            "nextMessage" => {
                // Alt+→: Navigate to next message in transcript
                let new_off = self.scroll_offset.saturating_sub(5);
                self.scroll_offset = new_off;
                if new_off == 0 {
                    self.auto_scroll = true;
                }
                false
            }
            "jumpToNextError" => {
                // Ctrl+.: Jump to next error/issue in messages
                self.jump_to_next_error();
                false
            }
            "jumpToPreviousError" => {
                // Ctrl+Shift+.: Jump to previous error/issue in messages
                self.jump_to_previous_error();
                false
            }
            "reverseIndent" => {
                // Shift+Tab: Reverse indent (cycle permission mode)
                use claurst_core::config::PermissionMode;
                self.config.permission_mode = match self.config.permission_mode {
                    PermissionMode::Default => PermissionMode::AcceptEdits,
                    PermissionMode::AcceptEdits => PermissionMode::BypassPermissions,
                    PermissionMode::BypassPermissions => PermissionMode::Default,
                    PermissionMode::Plan => PermissionMode::Default,
                };
                let label = match self.config.permission_mode {
                    PermissionMode::Default => "Default permissions",
                    PermissionMode::AcceptEdits => "Accept-edits mode",
                    PermissionMode::BypassPermissions => "Bypass permissions (dangerous)",
                    PermissionMode::Plan => "Plan mode",
                };
                self.status_message = Some(label.to_string());
                false
            }
            "openHelp" => {
                // Alt+H: Open help (alternative to F1)
                self.help_overlay.toggle();
                false
            }
            "openModelPicker" => {
                if !self.is_streaming {
                    self.intercept_slash_command("model");
                }
                false
            }
            "openCommandPalette" => {
                if !self.is_streaming {
                    self.command_palette.open();
                }
                false
            }
            "deleteWord" => {
                // Alt+D: Delete word forward
                if !self.is_streaming {
                    self.prompt_input.delete_word_at_cursor();
                    self.refresh_prompt_input();
                }
                false
            }
            "newline" => {
                // Shift+Enter: insert a literal newline into the prompt.
                if !self.is_streaming {
                    self.prompt_input.insert_newline();
                    self.refresh_prompt_input();
                }
                false
            }
            "indent" => {
                // Tab: cycle agent mode when prompt is empty, accept
                // slash-command suggestion otherwise.
                if !self.is_streaming {
                    if !self.prompt_input.suggestions.is_empty() {
                        if self.prompt_input.suggestion_index.is_none() {
                            self.prompt_input.suggestion_index = Some(0);
                        }
                        self.prompt_input.accept_suggestion();
                        self.refresh_prompt_input();
                    } else if self.prompt_input.is_empty() {
                        self.cycle_agent_mode();
                        self.companion_look_down();
                    }
                }
                false
            }
            _ => false,
        }
    }

    /// Handle a key event while a permission dialog is active.
    fn handle_permission_key(&mut self, key: KeyEvent) {
        let pr = match self.permission_request.as_mut() {
            Some(p) => p,
            None => return,
        };

        match key.code {
            KeyCode::Char(c) => {
                if let Some(digit) = c.to_digit(10) {
                    let idx = (digit as usize).saturating_sub(1);
                    if idx < pr.options.len() {
                        pr.selected_option = idx;
                    }
                } else {
                    // Check if any option matches this key.
                    let mut matched_idx = None;
                    for (i, opt) in pr.options.iter().enumerate() {
                        if opt.key == c {
                            matched_idx = Some(i);
                            break;
                        }
                    }
                    if let Some(idx) = matched_idx {
                        pr.selected_option = idx;
                        // If this is the prefix-allow option ('P'), record the prefix.
                        self.maybe_record_bash_prefix();
                        self.permission_request = None;
                    }
                }
            }
            KeyCode::Enter => {
                // If the currently selected option is the prefix-allow option, record it.
                self.maybe_record_bash_prefix();
                self.permission_request = None;
            }
            KeyCode::Up => {
                // Pattern-match instead of `.as_mut().unwrap()`: the
                // permission_request can be cleared between key events
                // (e.g. by a model-side cancellation), so we must not
                // panic when the dialog has gone away.
                if let Some(pr) = self.permission_request.as_mut() {
                    if pr.selected_option > 0 {
                        pr.selected_option -= 1;
                    }
                }
            }
            KeyCode::Down => {
                if let Some(pr) = self.permission_request.as_mut() {
                    if pr.selected_option + 1 < pr.options.len() {
                        pr.selected_option += 1;
                    }
                }
            }
            KeyCode::Esc => {
                self.permission_request = None;
            }
            _ => {}
        }
    }

    /// If the active permission dialog's selected option is the prefix-allow
    /// option ('P') for a Bash dialog, extract the suggested prefix and add it
    /// to `bash_prefix_allowlist` so future requests with the same prefix are
    /// silently approved.
    fn maybe_record_bash_prefix(&mut self) {
        use crate::dialogs::PermissionDialogKind;
        let pr = match self.permission_request.as_ref() {
            Some(p) => p,
            None => return,
        };
        // Only act on Bash dialogs where the selected option key is 'P'.
        let selected_key = pr.options.get(pr.selected_option).map(|o| o.key);
        if selected_key != Some('P') {
            return;
        }
        if let PermissionDialogKind::Bash {
            suggested_prefix, ..
        } = &pr.kind
        {
            if let Some(prefix) = suggested_prefix
                .as_deref()
                .map(str::trim)
                .filter(|p| !p.is_empty())
            {
                if !Self::bash_command_has_shell_control(prefix) {
                    self.bash_prefix_allowlist.insert(prefix.to_string());
                }
            }
        }
    }

    fn bash_command_has_shell_control(command: &str) -> bool {
        let mut chars = command.chars().peekable();
        let mut in_single_quote = false;
        let mut in_double_quote = false;
        let mut escaped = false;

        while let Some(c) = chars.next() {
            if escaped {
                escaped = false;
                continue;
            }

            // In bash, backslash does not escape characters inside single quotes.
            if c == '\\' && !in_single_quote {
                escaped = true;
                continue;
            }

            match c {
                '\'' if !in_double_quote => in_single_quote = !in_single_quote,
                '"' if !in_single_quote => in_double_quote = !in_double_quote,
                ';' | '|' | '&' | '<' | '>' | '\n' | '\r'
                    if !in_single_quote && !in_double_quote =>
                {
                    return true;
                }
                '`' if !in_single_quote => return true,
                '$' if !in_single_quote && chars.peek() == Some(&'(') => return true,
                _ => {}
            }
        }

        // Treat unterminated quotes / dangling escapes as unsafe.
        escaped || in_single_quote || in_double_quote
    }

    fn bash_prefix_matches_command(prefix: &str, command: &str) -> bool {
        let prefix = prefix.trim();
        let command = command.trim_start();
        if prefix.is_empty() || !command.starts_with(prefix) {
            return false;
        }

        let rest = &command[prefix.len()..];
        rest.is_empty()
            || rest
                .chars()
                .next()
                .map(|c| c.is_ascii_whitespace())
                .unwrap_or(false)
    }

    /// Returns `true` if the given bash `command` is covered by the session-local
    /// prefix allowlist.  Shell compound commands are never allowed by prefix;
    /// they must go through the normal permission dialog.
    pub fn bash_command_allowed_by_prefix(&self, command: &str) -> bool {
        !Self::bash_command_has_shell_control(command)
            && self
                .bash_prefix_allowlist
                .iter()
                .any(|prefix| Self::bash_prefix_matches_command(prefix, command))
    }

    // ---- Advanced mouse interaction helpers --------------------------------

    /// Detect if a click is a double-click based on timing and position.
    /// Returns true if the click is within ~500ms and ~5px of the last click.
    fn is_double_click(&self, current_pos: (u16, u16)) -> bool {
        let now = std::time::Instant::now();
        match (self.last_click_time, self.last_click_position) {
            (Some(last_time), Some(last_pos)) => {
                let elapsed = now.duration_since(last_time);
                let distance = ((current_pos.0 as i32 - last_pos.0 as i32).abs()
                    + (current_pos.1 as i32 - last_pos.1 as i32).abs())
                    as u16;
                elapsed.as_millis() < 500 && distance <= 5
            }
            _ => false,
        }
    }

    /// Find word boundaries for the character at (col, row) in the rendered
    /// transcript buffer. Returns absolute (start_col, end_col) for the word
    /// containing the click. A "word" is a run of non-whitespace characters.
    fn find_word_boundaries(&self, col: u16, row: u16) -> Option<(u16, u16)> {
        let cache = self.last_row_text.borrow();
        let line = cache.get(&row)?;
        if line.is_empty() {
            return None;
        }
        let selectable_area = self.last_selectable_area.get();
        if col < selectable_area.x {
            return None;
        }
        let local = (col - selectable_area.x) as usize;
        let chars: Vec<char> = line.chars().collect();
        if local >= chars.len() {
            return None;
        }
        let is_word = |c: char| !c.is_whitespace();
        if !is_word(chars[local]) {
            return None;
        }
        let mut start = local;
        while start > 0 && is_word(chars[start - 1]) {
            start -= 1;
        }
        let mut end = local;
        while end + 1 < chars.len() && is_word(chars[end + 1]) {
            end += 1;
        }
        Some((
            selectable_area.x + start as u16,
            selectable_area.x + end as u16,
        ))
    }

    /// Find paragraph boundaries (run of non-blank rows) around `row` and
    /// return (start_row, end_row, end_col) where end_col is the trimmed end
    /// of the last row's content. Used by triple-click selection so a
    /// "paragraph" — a contiguous block of text rows — is selected as a unit
    /// instead of a single visual row.
    fn find_paragraph_boundaries(&self, row: u16) -> Option<(u16, u16, u16)> {
        let cache = self.last_row_text.borrow();
        let selectable_area = self.last_selectable_area.get();
        if selectable_area.width == 0 || selectable_area.height == 0 {
            return None;
        }
        let row_text = cache.get(&row)?;
        if row_text.trim().is_empty() {
            return None;
        }
        let max_row = selectable_area
            .y
            .saturating_add(selectable_area.height)
            .saturating_sub(1);
        let mut start = row;
        while start > selectable_area.y {
            let prev = start - 1;
            if cache
                .get(&prev)
                .map(|s| s.trim().is_empty())
                .unwrap_or(true)
            {
                break;
            }
            start = prev;
        }
        let mut end = row;
        while end < max_row {
            let next = end + 1;
            if cache
                .get(&next)
                .map(|s| s.trim().is_empty())
                .unwrap_or(true)
            {
                break;
            }
            end = next;
        }
        let last_text = cache.get(&end)?;
        let trimmed = last_text.trim_end();
        let end_col = selectable_area.x + trimmed.chars().count().saturating_sub(1) as u16;
        Some((start, end, end_col))
    }

    /// Find line boundaries for the row containing the click.
    /// Returns (start_row, end_row) for the line.
    #[allow(dead_code)]
    fn find_line_boundaries(&self, row: u16) -> Option<(u16, u16)> {
        let selectable_area = self.last_selectable_area.get();
        let line_start = selectable_area.y;
        let line_end = selectable_area
            .y
            .saturating_add(selectable_area.height)
            .saturating_sub(1);

        if row >= line_start && row <= line_end {
            Some((row, row))
        } else {
            None
        }
    }

    fn context_menu_items(kind: ContextMenuKind) -> &'static [ContextMenuItem] {
        match kind {
            ContextMenuKind::Message { .. } => &[ContextMenuItem::Copy, ContextMenuItem::Fork],
            ContextMenuKind::Selection => &[ContextMenuItem::Copy],
        }
    }

    fn message_index_at_row(&self, row: u16) -> Option<usize> {
        self.message_row_map.borrow().get(&row).copied()
    }

    fn clear_selection(&mut self) {
        self.selection_anchor = None;
        self.selection_focus = None;
        *self.selection_text.borrow_mut() = String::new();
    }

    /// Show context menu at the given position.
    fn show_context_menu(&mut self, x: u16, y: u16, kind: ContextMenuKind) {
        self.context_menu_state = Some(ContextMenuState {
            x,
            y,
            selected_index: 0,
            kind,
        });
    }

    /// Dismiss the context menu.
    fn dismiss_context_menu(&mut self) {
        self.context_menu_state = None;
    }

    /// Handle context menu navigation with arrow keys.
    fn navigate_context_menu(&mut self, direction: KeyCode) {
        if let Some(mut menu) = self.context_menu_state {
            let item_count = Self::context_menu_items(menu.kind).len();
            if item_count == 0 {
                self.context_menu_state = Some(menu);
                return;
            }
            match direction {
                KeyCode::Up => {
                    if menu.selected_index == 0 {
                        menu.selected_index = item_count - 1;
                    } else {
                        menu.selected_index -= 1;
                    }
                }
                KeyCode::Down => {
                    menu.selected_index = (menu.selected_index + 1) % item_count;
                }
                _ => return,
            }
            self.context_menu_state = Some(menu);
        }
    }

    /// Execute the currently selected context menu item.
    fn execute_context_menu_item(&mut self) {
        if let Some(menu) = self.context_menu_state {
            let items = Self::context_menu_items(menu.kind);

            if menu.selected_index < items.len() {
                let item = items[menu.selected_index];
                self.handle_context_menu_action(item, menu.kind);
            }
        }
        self.dismiss_context_menu();
    }

    /// Handle a context menu action.
    fn handle_context_menu_action(&mut self, item: ContextMenuItem, kind: ContextMenuKind) {
        match item {
            ContextMenuItem::Copy => {
                let text = match kind {
                    ContextMenuKind::Message { message_index } => self
                        .messages
                        .get(message_index)
                        .map(|message| message.get_all_text()),
                    ContextMenuKind::Selection => {
                        let selected = self.selection_text.borrow().trim().to_string();
                        if selected.is_empty() {
                            None
                        } else {
                            Some(selected)
                        }
                    }
                };

                if let Some(text) = text {
                    if crate::message_copy::copy_to_clipboard(&text) {
                        self.push_notification(
                            NotificationKind::Info,
                            format!("Copied {} chars to clipboard.", text.len()),
                            Some(3),
                        );
                    } else {
                        self.push_notification(
                            NotificationKind::Warning,
                            "Failed to copy to clipboard.".to_string(),
                            Some(3),
                        );
                    }
                    debug!("Copy action triggered, text: {} chars", text.len());
                }
            }
            ContextMenuItem::Fork => {
                if let ContextMenuKind::Message { message_index } = kind {
                    let branch_point = message_index + 1;
                    self.prompt_input
                        .replace_text(format!("/fork {}", branch_point));
                    self.status_message = Some(format!(
                        "Fork at message {} - press Enter to confirm",
                        branch_point
                    ));
                }
            }
        }
    }

    fn prompt_can_accept_selection_paste(&self) -> bool {
        !self.is_streaming
            && self.permission_request.is_none()
            && !self.history_search_overlay.visible
            && !matches!(
                self.prompt_input.vim_mode,
                crate::prompt_input::VimMode::Normal
                    | crate::prompt_input::VimMode::Visual
                    | crate::prompt_input::VimMode::VisualBlock
            )
    }

    fn paste_primary_into_prompt(&mut self) -> bool {
        if !self.prompt_can_accept_selection_paste() {
            return false;
        }

        if let Some(text) =
            crate::image_paste::read_primary_text().or_else(crate::image_paste::read_clipboard_text)
        {
            self.focus = FocusTarget::Input;
            self.clear_selection();
            self.prompt_input.paste(&text);
            self.refresh_prompt_input();
            return true;
        }

        false
    }

    /// Handle a paste data string (from `Event::Paste` or Ctrl+V text fallback).
    ///
    /// If the pasted text resolves to an existing filesystem path:
    ///   - image files (png/jpg/gif/webp/bmp) → added as an image attachment pill
    ///   - other files → inserted as `@path` mention text
    ///
    /// Otherwise the text goes through the normal `prompt_input.paste()` path
    /// which applies the multi-line summary placeholder for large pastes.
    pub fn handle_paste_data(&mut self, data: String) {
        use crate::image_paste::PastedImage;
        use crate::prompt_input::detect_pasted_path;

        if let Some(path) = detect_pasted_path(&data) {
            let ext = path
                .extension()
                .and_then(|e| e.to_str())
                .map(|e| e.to_ascii_lowercase());
            let is_image = matches!(
                ext.as_deref(),
                Some("png") | Some("jpg") | Some("jpeg") | Some("gif") | Some("webp") | Some("bmp")
            );
            if is_image {
                let label = path
                    .file_name()
                    .and_then(|n| n.to_str())
                    .unwrap_or("image")
                    .to_string();
                let img = PastedImage {
                    path,
                    label: label.clone(),
                    dimensions: None,
                };
                self.prompt_input.add_image(img);
                self.push_notification(
                    crate::notifications::NotificationKind::Info,
                    format!("Image attached: {}", label),
                    Some(3),
                );
            } else {
                // Non-image file: insert as an @mention so the path is visible
                // but clearly marked as a file reference.
                let mention = format!("@{}", path.display());
                self.prompt_input.paste(&mention);
            }
        } else {
            self.prompt_input.paste(&data);
        }
    }

    /// Returns `true` when the app is in a state where the prompt can accept
    /// regular text input — used to gate paste-burst detection.
    pub fn prompt_is_accepting_text(&self) -> bool {
        // Gate on the shared blocking-modal predicate rather than a parallel
        // hand-list: any overlay that captures input (skills/model pickers,
        // command palette, dialogs, …) automatically blocks prompt text and
        // paste-burst capture while it is open.
        !self.is_streaming
            && !self.any_blocking_modal_open()
            && self.prompt_input.vim_mode == crate::prompt_input::VimMode::Insert
    }

    /// Take any key event saved by `try_detect_paste_burst` when a non-character
    /// key terminated a paste burst.  The caller should replay it as the next
    /// event at the top of its event loop.
    pub fn take_pending_key(&mut self) -> Option<crossterm::event::KeyEvent> {
        self.pending_key.take()
    }

    /// Drain any immediately-available key events from the crossterm event
    /// queue (zero-timeout poll) and return them alongside `first` as a single
    /// pasted string if the burst is large enough to be a paste.
    ///
    /// On Windows Terminal, Ctrl+V causes the terminal emulator to write the
    /// clipboard content directly to stdin as raw character events — every
    /// newline becomes an Enter keypress and stray `v` characters trigger
    /// voice PTT.  Because a paste dumps ALL characters into the queue at
    /// once, a zero-timeout drain immediately after the first character
    /// reliably yields 3+ chars for any non-trivial paste, while normal
    /// keyboard typing (even at 120 WPM) almost never queues more than one
    /// char in the same 50 ms window.
    ///
    /// Returns `Some(text)` when a paste burst is detected (caller should
    /// route through `handle_paste_data`).  Returns `None` for a normal
    /// single keystroke.  If a non-character key is encountered while
    /// draining, it is stored in `self.pending_key` and will be replayed at
    /// the top of the next event-loop iteration.
    pub fn try_detect_paste_burst(&mut self, first: char) -> Option<String> {
        use crossterm::event::{Event, KeyCode, KeyEventKind};

        // Minimum number of chars (including `first`) to classify as a paste.
        // Two or more is enough: at 120 WPM the inter-key interval is ~60 ms,
        // so a second char in the same zero-timeout drain is extremely unlikely
        // from a human typist but guaranteed from a clipboard paste.
        const BURST_THRESHOLD: usize = 2;

        // Quick exit: don't bother if nothing is queued immediately.
        if !crossterm::event::poll(std::time::Duration::ZERO).unwrap_or(false) {
            return None;
        }

        let mut buf = String::new();
        buf.push(first);

        while let Ok(true) = crossterm::event::poll(std::time::Duration::ZERO) {
            match crossterm::event::read() {
                Ok(Event::Key(k)) if k.kind == KeyEventKind::Press => match k.code {
                    KeyCode::Char(c) => buf.push(c),
                    KeyCode::Enter => buf.push('\n'),
                    _ => {
                        // Non-character key — save it for replay.
                        self.pending_key = Some(k);
                        break;
                    }
                },
                // Non-key event (mouse, resize, …) — leave in queue by
                // not reading it; we already checked poll() so it will
                // be re-read next iteration. But we already read it, so
                // we just break (the event is consumed but benign).
                _ => break,
            }
        }

        if buf.chars().count() >= BURST_THRESHOLD {
            Some(buf)
        } else {
            None
        }
    }

    /// Process mouse events (trackpad scroll, text selection, etc.).
    pub fn handle_mouse_event(&mut self, mouse_event: MouseEvent) {
        use crossterm::event::MouseButton;

        // Fast-reject mouse-move events — they flood at 60+ Hz and we don't
        // need hover tracking. Exception: context menu needs hover to update
        // the selected item highlight.
        if matches!(mouse_event.kind, MouseEventKind::Moved) {
            if let Some(menu) = self.context_menu_state.as_mut() {
                let items = Self::context_menu_items(menu.kind);
                let item_labels: Vec<&str> = items
                    .iter()
                    .map(|i| match i {
                        ContextMenuItem::Copy => "Copy",
                        ContextMenuItem::Fork => "Fork new chat",
                    })
                    .collect();
                let menu_width =
                    (item_labels.iter().map(|l| l.len()).max().unwrap_or(4) + 4) as u16;
                let menu_height = items.len() as u16 + 2;
                let screen = self.last_msg_area.get();
                let menu_x = menu.x.min(
                    screen
                        .x
                        .saturating_add(screen.width)
                        .saturating_sub(menu_width + 1),
                );
                let menu_y = menu.y.min(
                    screen
                        .y
                        .saturating_add(screen.height)
                        .saturating_sub(menu_height + 1),
                );
                let inner_y = menu_y + 1;
                let col = mouse_event.column;
                let row = mouse_event.row;
                if col >= menu_x
                    && col < menu_x.saturating_add(menu_width)
                    && row >= inner_y
                    && row < inner_y.saturating_add(items.len() as u16)
                {
                    let hovered = (row - inner_y) as usize;
                    if hovered < items.len() {
                        menu.selected_index = hovered;
                    }
                }
            }
            return;
        }

        // ---- Dialog interaction: dismiss on click-outside, scroll/click inside ----
        // Key-input and device-auth stay outside this gate so their visible text
        // can still be selected and copied with the mouse.
        let any_dialog = self.connect_dialog.visible
            || self.import_config_picker.visible
            || self.import_config_dialog.visible
            || self.command_palette.visible
            || self.model_picker.visible
            || self.export_dialog.visible
            || self.settings_screen.visible
            || self.stats_dialog.visible
            || self.context_viz.visible
            || self.session_browser.visible;

        if any_dialog {
            match mouse_event.kind {
                MouseEventKind::Down(MouseButton::Left) => {
                    // DialogSelect dialogs — check if click is inside for item selection
                    let in_dialog = if self.connect_dialog.visible {
                        self.connect_dialog
                            .contains(mouse_event.column, mouse_event.row)
                    } else if self.import_config_picker.visible {
                        self.import_config_picker
                            .contains(mouse_event.column, mouse_event.row)
                    } else if self.command_palette.visible {
                        self.command_palette
                            .contains(mouse_event.column, mouse_event.row)
                    } else {
                        // Other dialogs (model_picker, settings, export, etc.) —
                        // treat any click as "inside" to prevent accidental dismiss.
                        // User must press Esc to close these.
                        true
                    };

                    if in_dialog {
                        // Click inside a DialogSelect — select the clicked item
                        if self.connect_dialog.visible {
                            self.connect_dialog.handle_mouse_click(mouse_event.row);
                        } else if self.import_config_picker.visible {
                            self.import_config_picker
                                .handle_mouse_click(mouse_event.row);
                        } else if self.command_palette.visible {
                            self.command_palette.handle_mouse_click(mouse_event.row);
                        }
                        // Other dialogs: click absorbed, no action needed
                    } else {
                        // Click outside a DialogSelect — dismiss and restore input focus
                        self.close_secondary_views();
                        self.focus = FocusTarget::Input;
                    }
                }
                MouseEventKind::ScrollUp => {
                    // Scroll through dialog items
                    if self.connect_dialog.visible {
                        self.connect_dialog.move_up();
                    } else if self.import_config_picker.visible {
                        self.import_config_picker.move_up();
                    } else if self.command_palette.visible {
                        self.command_palette.move_up();
                    }
                }
                MouseEventKind::ScrollDown => {
                    if self.connect_dialog.visible {
                        self.connect_dialog.move_down();
                    } else if self.import_config_picker.visible {
                        self.import_config_picker.move_down();
                    } else if self.command_palette.visible {
                        self.command_palette.move_down();
                    }
                }
                _ => {}
            }
            return; // Don't process any other mouse events when a dialog is open
        }

        match mouse_event.kind {
            MouseEventKind::ScrollUp if !mouse_event.modifiers.contains(KeyModifiers::CONTROL) => {
                // Don't consume Ctrl+Scroll — let the terminal handle zoom.
                let step = self.scroll_step();
                self.scroll_offset = self.scroll_offset.saturating_add(step);
                self.auto_scroll = false;
            }
            MouseEventKind::ScrollUp => {}
            MouseEventKind::ScrollDown
                if !mouse_event.modifiers.contains(KeyModifiers::CONTROL) =>
            {
                let step = self.scroll_step();
                let new_off = self.scroll_offset.saturating_sub(step);
                self.scroll_offset = new_off;
                if new_off == 0 {
                    self.auto_scroll = true;
                    self.new_messages_while_scrolled = 0;
                }
            }
            MouseEventKind::ScrollDown => {}
            // ---- Right-click context menu ----------------------------------
            MouseEventKind::Down(MouseButton::Right) => {
                let msg_area = self.last_msg_area.get();
                let has_selection = !self.selection_text.borrow().trim().is_empty();
                if mouse_event.column >= msg_area.x
                    && mouse_event.column < msg_area.x.saturating_add(msg_area.width)
                    && mouse_event.row >= msg_area.y
                    && mouse_event.row < msg_area.y.saturating_add(msg_area.height)
                {
                    if let Some(message_index) = self.message_index_at_row(mouse_event.row) {
                        self.show_context_menu(
                            mouse_event.column,
                            mouse_event.row,
                            ContextMenuKind::Message { message_index },
                        );
                    } else {
                        self.dismiss_context_menu();
                    }
                } else if has_selection {
                    self.show_context_menu(
                        mouse_event.column,
                        mouse_event.row,
                        ContextMenuKind::Selection,
                    );
                } else {
                    self.dismiss_context_menu();
                }
            }

            // ---- Primary-selection paste into the prompt ---------------
            MouseEventKind::Down(MouseButton::Middle) => {
                let _ = self.paste_primary_into_prompt();
            }

            // ---- Text selection / focus routing -------------------------
            MouseEventKind::Down(MouseButton::Left) => {
                // If a context menu is open, check if the click is on a menu item.
                // Must replicate the same position clamping as the renderer.
                if let Some(menu) = self.context_menu_state {
                    let items = Self::context_menu_items(menu.kind);
                    let item_labels: Vec<&str> = items
                        .iter()
                        .map(|i| match i {
                            ContextMenuItem::Copy => "Copy",
                            ContextMenuItem::Fork => "Fork new chat",
                        })
                        .collect();
                    let menu_width =
                        (item_labels.iter().map(|l| l.len()).max().unwrap_or(4) + 4) as u16;
                    let menu_height = items.len() as u16 + 2; // +2 for border
                                                              // Clamp to screen bounds (same as render_context_menu)
                    let screen = self.last_msg_area.get();
                    let menu_x = menu.x.min(
                        screen
                            .x
                            .saturating_add(screen.width)
                            .saturating_sub(menu_width + 1),
                    );
                    let menu_y = menu.y.min(
                        screen
                            .y
                            .saturating_add(screen.height)
                            .saturating_sub(menu_height + 1),
                    );
                    let col = mouse_event.column;
                    let row = mouse_event.row;
                    // Inner area starts 1 past the border
                    let inner_y = menu_y + 1;
                    if col >= menu_x
                        && col < menu_x.saturating_add(menu_width)
                        && row >= inner_y
                        && row < inner_y.saturating_add(items.len() as u16)
                    {
                        let clicked_index = (row - inner_y) as usize;
                        if clicked_index < items.len() {
                            self.context_menu_state.as_mut().unwrap().selected_index =
                                clicked_index;
                            self.execute_context_menu_item();
                            return;
                        }
                    }
                    // Click was outside the menu — just dismiss it
                    self.dismiss_context_menu();
                    return;
                }

                let input_area = self.last_input_area.get();
                let selectable_area = self.last_selectable_area.get();

                let in_input = input_area.width > 0
                    && input_area.height > 0
                    && mouse_event.row >= input_area.y
                    && mouse_event.row < input_area.y.saturating_add(input_area.height)
                    && mouse_event.column >= input_area.x
                    && mouse_event.column < input_area.x.saturating_add(input_area.width);

                let in_selectable = selectable_area.width > 0
                    && selectable_area.height > 0
                    && mouse_event.row >= selectable_area.y
                    && mouse_event.row < selectable_area.y.saturating_add(selectable_area.height)
                    && mouse_event.column >= selectable_area.x
                    && mouse_event.column < selectable_area.x.saturating_add(selectable_area.width);

                // Check for click on a thinking block header (takes priority over text selection).
                if let Some(&hash) = self.thinking_row_map.borrow().get(&mouse_event.row) {
                    if self.thinking_expanded.contains(&hash) {
                        self.thinking_expanded.remove(&hash);
                    } else {
                        self.thinking_expanded.insert(hash);
                    }
                    self.invalidate_transcript();
                    return;
                }

                if in_input {
                    self.focus = FocusTarget::Input;
                    self.clear_selection();
                } else if selectable_area.width == 0 || selectable_area.height == 0 {
                    self.click_count = 0;
                } else if in_selectable {
                    self.focus = FocusTarget::Transcript;

                    let current_pos = (mouse_event.column, mouse_event.row);
                    let now = std::time::Instant::now();

                    // Check for double-click
                    if self.is_double_click(current_pos) {
                        self.click_count += 1;
                        if self.click_count >= 3 {
                            // Triple-click: select the paragraph (run of
                            // non-blank rows) containing the click. Falls back
                            // to a single line if no paragraph is detected.
                            if let Some((start_row, end_row, end_col)) =
                                self.find_paragraph_boundaries(current_pos.1)
                            {
                                self.selection_anchor = Some((selectable_area.x, start_row));
                                self.selection_focus = Some((end_col, end_row));
                            } else {
                                self.selection_anchor = Some((selectable_area.x, current_pos.1));
                                self.selection_focus = Some((
                                    selectable_area
                                        .x
                                        .saturating_add(selectable_area.width)
                                        .saturating_sub(1),
                                    current_pos.1,
                                ));
                            }
                            self.click_count = 0; // Reset for next click sequence
                        } else {
                            // Double-click: select word
                            if let Some((start, end)) =
                                self.find_word_boundaries(current_pos.0, current_pos.1)
                            {
                                self.selection_anchor = Some((start, current_pos.1));
                                self.selection_focus = Some((end, current_pos.1));
                            }
                        }
                    } else {
                        // Single click or new click sequence
                        self.click_count = 1;
                        self.selection_anchor = Some(current_pos);
                        self.selection_focus = Some(current_pos);
                        *self.selection_text.borrow_mut() = String::new();
                    }

                    self.last_click_time = Some(now);
                    self.last_click_position = Some(current_pos);
                } else {
                    self.click_count = 0;
                    self.clear_selection();
                }
            }
            MouseEventKind::Drag(MouseButton::Left) => {
                // Dismiss context menu on drag
                self.dismiss_context_menu();

                // Continue drag — clamp to the selectable frame bounds so dragging
                // outside extends selection to the edge rather than cancelling.
                if self.selection_anchor.is_some() {
                    let selectable_area = self.last_selectable_area.get();
                    if selectable_area.width > 0 && selectable_area.height > 0 {
                        let clamped_col = mouse_event.column.max(selectable_area.x).min(
                            selectable_area
                                .x
                                .saturating_add(selectable_area.width)
                                .saturating_sub(1),
                        );
                        let clamped_row = mouse_event.row.max(selectable_area.y).min(
                            selectable_area
                                .y
                                .saturating_add(selectable_area.height)
                                .saturating_sub(1),
                        );
                        self.selection_focus = Some((clamped_col, clamped_row));
                        self.click_count = 0; // Reset on drag to prevent further double-clicks
                    }
                }
            }
            MouseEventKind::Up(MouseButton::Left) => {
                // Clear if no actual drag (single click = no selection)
                if self.selection_anchor == self.selection_focus {
                    self.clear_selection();
                } else if self.settings_screen.auto_copy_enabled {
                    // Auto-copy finalized selection to clipboard.
                    let sel_text = self.selection_text.borrow().clone();
                    if !sel_text.is_empty() {
                        let copied = crate::image_paste::write_clipboard_text(&sel_text);
                        if copied {
                            self.push_notification(
                                NotificationKind::Info,
                                "Copied to clipboard".to_string(),
                                Some(1),
                            );
                        }
                    }
                }
            }
            _ => {}
        }
    }

    // -------------------------------------------------------------------
    // Query event handling
    // -------------------------------------------------------------------

    /// Push a completed assistant message and trigger auto-scroll bookkeeping.
    fn push_assistant_message(&mut self, text: String) {
        let msg = Message::assistant(text);
        self.messages.push(msg);
        self.invalidate_transcript();
        self.on_new_message();
    }

    /// Process a query event from the agentic loop.
    pub fn handle_query_event(&mut self, event: QueryEvent) {
        // Auto-dismiss error modal when assistant responds
        match &event {
            QueryEvent::Stream(_) | QueryEvent::TurnComplete { .. } => {
                self.dismiss_error_notifications();
            }
            _ => {}
        }

        match event {
            QueryEvent::Stream(stream_evt) => {
                if !self.is_streaming {
                    let seed = self.frame_count as usize ^ (self.messages.len() * 17);
                    self.spinner_verb = Some(sample_spinner_verb(seed).to_string());
                    // turn_start is set in begin_user_turn_snapshot (prompt
                    // submission time).  Only fall back here if somehow no
                    // user message was pushed before streaming began (e.g.
                    // headless / programmatic callers).
                    if self.turn_start.is_none() {
                        self.turn_start = Some(std::time::Instant::now());
                    }
                    self.streaming_thinking.clear();
                }
                self.is_streaming = true;
                match stream_evt {
                    claurst_api::AnthropicStreamEvent::ContentBlockDelta { delta, .. } => {
                        // Reset stall timer on any incoming delta — we're making progress.
                        self.stall_start = None;
                        match delta {
                            claurst_api::streaming::ContentDelta::TextDelta { text } => {
                                self.streaming_text.push_str(&text);
                                self.invalidate_transcript();
                            }
                            claurst_api::streaming::ContentDelta::ThinkingDelta { thinking } => {
                                debug!(len = thinking.len(), "Thinking delta received");
                                self.streaming_thinking.push_str(&thinking);
                                self.invalidate_transcript();
                            }
                            _ => {}
                        }
                    }
                    claurst_api::AnthropicStreamEvent::MessageStop => {
                        self.is_streaming = false;
                        self.spinner_verb = None;
                        self.stall_start = None;
                        self.flush_streamed_assistant_message();
                    }
                    _ => {
                        // Any other stream event: if we have no stall_start yet,
                        // record now so the red-spinner timer can begin.
                        if self.stall_start.is_none() {
                            self.stall_start = Some(std::time::Instant::now());
                        }
                    }
                }
            }

            QueryEvent::ToolStart {
                tool_name,
                tool_id,
                input_json,
            } => {
                if !self.is_streaming && self.spinner_verb.is_none() {
                    let seed = self.frame_count as usize ^ (self.messages.len() * 17);
                    self.spinner_verb = Some(sample_spinner_verb(seed).to_string());
                }
                self.is_streaming = true;
                self.status_message = Some(format!("Running {}…", tool_name));
                let turn_index = self.current_user_turn_index();
                if let Some(existing) = self.tool_use_blocks.iter_mut().find(|b| b.id == tool_id) {
                    existing.turn_index = turn_index;
                    existing.status = ToolStatus::Running;
                    existing.output_preview = None;
                    existing.input_json = input_json;
                } else {
                    self.tool_use_blocks.push(ToolUseBlock {
                        id: tool_id,
                        name: tool_name,
                        turn_index,
                        status: ToolStatus::Running,
                        output_preview: None,
                        input_json,
                    });
                }
                self.invalidate_transcript();
            }

            QueryEvent::ToolEnd {
                tool_name: _,
                tool_id,
                result,
                is_error,
            } => {
                // Build a multi-line preview: show up to 3 lines, truncate if more.
                let all_lines: Vec<&str> = result.lines().collect();
                let preview_lines = all_lines.len().min(3);
                let mut preview = all_lines[..preview_lines].join("\n");
                let remaining = all_lines.len().saturating_sub(preview_lines);
                if remaining > 0 {
                    preview.push_str(&format!("\n\u{2026} {} more lines", remaining));
                }
                if let Some(block) = self.tool_use_blocks.iter_mut().find(|b| b.id == tool_id) {
                    block.status = if is_error {
                        ToolStatus::Error
                    } else {
                        ToolStatus::Done
                    };
                    block.output_preview = Some(preview);
                }
                self.invalidate_transcript();
                if is_error {
                    self.status_message = Some(format!("Tool error: {}", result));
                } else {
                    self.status_message = None;
                }
                self.refresh_turn_diff_from_history();
            }

            QueryEvent::TurnComplete {
                turn,
                stop_reason,
                usage,
                ..
            } => {
                debug!(turn, stop_reason, "Turn complete");
                self.is_streaming = false;
                self.spinner_verb = None;

                // Update context window usage from the usage info.
                if let Some(ref u) = usage {
                    let turn_tokens = u.input_tokens
                        + u.output_tokens
                        + u.cache_creation_input_tokens
                        + u.cache_read_input_tokens;
                    self.context_used_tokens = self.context_used_tokens.saturating_add(turn_tokens);
                }
                // Record elapsed time and pick a completion verb
                let seed = self.frame_count as usize ^ (self.messages.len() * 7);
                let turn_elapsed_secs = self
                    .turn_start
                    .as_ref()
                    .map(|s| s.elapsed().as_secs())
                    .unwrap_or(0);
                let elapsed = self
                    .turn_start
                    .take()
                    .map(|start| format_elapsed_ms(start.elapsed().as_millis()));
                let elapsed_label = elapsed.unwrap_or_else(|| "0s".to_string());
                self.last_turn_elapsed = Some(elapsed_label.clone());
                self.last_turn_verb = Some(sample_completion_verb(seed));
                self.flush_streamed_assistant_message();
                self.tool_use_blocks
                    .retain(|b| b.status != ToolStatus::Running);
                let cancelled = stop_reason.contains("abort") || stop_reason.contains("cancel");
                self.complete_current_turn_snapshot(cancelled);
                self.invalidate_transcript();
                self.refresh_turn_diff_from_history();

                // Surface a clear "turn done" signal for long-running turns the
                // user might have stepped away from. The faint "✽ Worked for Ns"
                // status line is too quiet on its own.
                if !cancelled && turn_elapsed_secs >= self.completion_toast_min_secs {
                    if self.completion_toast_enabled {
                        self.push_notification(
                            NotificationKind::Success,
                            format!("Turn done · {}", elapsed_label),
                            Some(6),
                        );
                    }
                    if self.bell_on_complete {
                        ring_terminal_bell();
                    }
                }
            }

            QueryEvent::Status(msg) => {
                self.status_message = Some(msg);
            }

            QueryEvent::Error(msg) => {
                self.is_streaming = false;
                self.spinner_verb = None;
                self.streaming_text.clear();
                self.streaming_thinking.clear();
                self.invalidate_transcript();
                let err_msg = format!("Error: {}", msg);
                self.push_assistant_message(err_msg.clone());
                self.push_notification(NotificationKind::Error, err_msg, None);
            }
            QueryEvent::TokenWarning { state, pct_used } => {
                // Push a notification for context window warnings (notification + threshold tracking).
                use claurst_query::compact::TokenWarningState;

                // Only escalate — never repeat a threshold already shown.
                match state {
                    TokenWarningState::Ok => {
                        // Reset threshold tracking when back to normal
                        self.token_warning_threshold_shown = 0;
                    }
                    TokenWarningState::Warning if self.token_warning_threshold_shown < 80 => {
                        self.token_warning_threshold_shown = 80;
                        self.push_notification(
                            NotificationKind::Warning,
                            format!(
                                "Context window {:.0}% full. Consider /compact.",
                                pct_used * 100.0
                            ),
                            Some(30),
                        );
                    }
                    TokenWarningState::Critical if self.token_warning_threshold_shown < 95 => {
                        self.token_warning_threshold_shown = 95;
                        self.push_notification(
                            NotificationKind::Error,
                            format!(
                                "Context window {:.0}% full! Run /compact now.",
                                pct_used * 100.0
                            ),
                            None,
                        );
                    }
                    _ => {}
                }
            }
        }

        // Update token count from tracker.
        self.token_count = self.cost_tracker.total_tokens() as u32;
    }

    // -------------------------------------------------------------------
    // Main run loop
    // -------------------------------------------------------------------

    /// Run the TUI event loop. Returns `Some(input)` when the user submits
    /// a message, or `None` when the user quits.
    pub fn run(
        &mut self,
        terminal: &mut Terminal<CrosstermBackend<Stdout>>,
    ) -> anyhow::Result<Option<String>> {
        loop {
            self.frame_count = self.frame_count.wrapping_add(1);

            // Re-check daemon reachability ~every 30 seconds (300 frames at
            // 10fps). The probe is cached and non-blocking; it also honors
            // COVEN_HOME, unlike a hardcoded ~/.coven/coven.sock check.
            if self.frame_count.wrapping_sub(self.daemon_last_checked) >= 300 {
                self.daemon_last_checked = self.frame_count;
                self.daemon_online = crate::coven_status::daemon_looks_online();
            }

            // Drain background session-list results.
            if let Some(ref mut rx) = self.session_list_rx {
                match rx.try_recv() {
                    Ok(entries) => {
                        self.session_browser.sessions = entries;
                        self.session_browser.selected_idx = 0;
                        self.session_list_rx = None;
                    }
                    Err(tokio::sync::mpsc::error::TryRecvError::Disconnected) => {
                        self.session_list_rx = None;
                    }
                    Err(tokio::sync::mpsc::error::TryRecvError::Empty) => {}
                }
            }

            // Spawn async session-list load when requested.
            if self.session_list_pending {
                self.session_list_pending = false;
                let (tx, rx) = tokio::sync::mpsc::channel(1);
                self.session_list_rx = Some(rx);
                tokio::spawn(async move {
                    let sessions = claurst_core::history::list_sessions().await;
                    let entries: Vec<crate::session_browser::SessionEntry> = sessions
                        .into_iter()
                        .map(|s| {
                            let age = chrono::Utc::now().signed_duration_since(s.updated_at);
                            let last_updated = if age.num_minutes() < 1 {
                                "just now".to_string()
                            } else if age.num_hours() < 1 {
                                format!("{}m ago", age.num_minutes())
                            } else if age.num_hours() < 24 {
                                format!("{}h ago", age.num_hours())
                            } else {
                                format!("{}d ago", age.num_days())
                            };
                            crate::session_browser::SessionEntry {
                                id: s.id,
                                title: s.title.unwrap_or_else(|| "(untitled)".to_string()),
                                last_updated,
                                message_count: s.messages.len(),
                                cost_usd: s.total_cost,
                            }
                        })
                        .collect();
                    let _ = tx.send(entries).await;
                });
            }

            // Drain voice transcription events (non-blocking).
            // When the background recording/transcription task emits a
            // TranscriptReady event we insert the text directly into the
            // prompt so the user can review and submit it.
            {
                use claurst_core::voice::VoiceEvent;
                let mut events = Vec::new();
                if let Some(ref mut rx) = self.voice_event_rx {
                    while let Ok(ev) = rx.try_recv() {
                        events.push(ev);
                    }
                }
                for ev in events {
                    match ev {
                        VoiceEvent::RecordingStarted => {
                            self.voice_recording = true;
                            self.status_message =
                                Some("Recording\u{2026} (Alt+V or Esc to stop)".to_string());
                        }
                        VoiceEvent::RecordingStopped => {
                            self.voice_recording = false;
                            self.status_message = Some("Transcribing\u{2026}".to_string());
                        }
                        VoiceEvent::TranscriptReady(text) => {
                            if !text.is_empty() {
                                // Append to existing prompt text with a space separator
                                // so the user can combine voice + typed input.
                                if !self.prompt_input.text.is_empty()
                                    && !self.prompt_input.text.ends_with(' ')
                                {
                                    self.prompt_input.paste(" ");
                                }
                                self.prompt_input.paste(&text);
                                self.refresh_prompt_input();
                                self.status_message =
                                    Some(format!("Transcribed: {}", &text[..text.len().min(60)]));
                            }
                            // Clear the channel once we have the result.
                            self.voice_event_rx = None;
                        }
                        VoiceEvent::Error(msg) => {
                            self.voice_recording = false;
                            self.voice_event_rx = None;
                            self.push_notification(
                                NotificationKind::Warning,
                                format!("Voice: {}", msg),
                                Some(8),
                            );
                        }
                    }
                }
            }

            // Draw the frame, and immediately scan the *just-rendered*
            // buffer for URL runs. ratatui swaps its two buffers at the
            // end of draw(), so by the time draw() returns,
            // `terminal.current_buffer_mut()` points at the empty next-frame
            // slot. `CompletedFrame.buffer` is the one we actually want.
            let osc8_hits = {
                let completed = terminal.draw(|f| render::render_app(f, self))?;
                crate::osc8::scan_buffer_for_urls(completed.buffer)
            };

            // Post-paint OSC 8 overlay: re-emit URL cells wrapped in
            // hyperlink escapes so terminals that support OSC 8 (Windows
            // Terminal, iTerm2, WezTerm, Kitty, Konsole, VS Code, …) make
            // them Ctrl/Cmd-clickable. Failure is non-fatal — we never want
            // an overlay glitch to kill the TUI.
            if let Err(err) = crate::osc8::emit_hits(&osc8_hits) {
                tracing::debug!(target: "osc8", "hyperlink overlay write failed: {err}");
            }

            // Replay a key that was saved by try_detect_paste_burst in a
            // previous iteration (e.g. a modifier key that terminated a burst).
            let pending = self.pending_key.take();

            // Poll for events with a short timeout so we can redraw for animation
            let got_event = pending.is_some() || event::poll(std::time::Duration::from_millis(50))?;

            if got_event {
                let event = if let Some(k) = pending {
                    Event::Key(k)
                } else {
                    event::read()?
                };
                match event {
                    Event::Key(key) => {
                        // crossterm fires both Press and Release events on
                        // platforms that support the kitty keyboard
                        // enhancement (Windows + some Linux terminals). We
                        // only ever act on Press: voice PTT was previously
                        // hold-to-talk on plain `v`, which broke typing —
                        // see Issue #49. Recording now toggles exclusively
                        // through Alt+V (a press-only chord), so the
                        // dedicated `v`-release handler is gone.
                        if key.kind != crossterm::event::KeyEventKind::Press {
                            continue;
                        }

                        // ---- Paste-burst detection -----------------------------------------
                        // On Windows Terminal, Ctrl+V causes the terminal to write clipboard
                        // content as raw character events (not as Event::Paste).  Every `\n`
                        // fires as Enter (submitting the prompt) and stray `v` chars trigger
                        // voice PTT.  We detect this by draining the event queue with a
                        // zero-timeout immediately after the first character arrives — a paste
                        // dumps every character at once while normal typing rarely queues more
                        // than one char in the same 50 ms window.
                        if key.modifiers == KeyModifiers::NONE
                            || key.modifiers == KeyModifiers::SHIFT
                        {
                            if let KeyCode::Char(c) = key.code {
                                if self.prompt_is_accepting_text() {
                                    if let Some(burst) = self.try_detect_paste_burst(c) {
                                        self.handle_paste_data(burst);
                                        self.refresh_prompt_input();
                                        continue;
                                    }
                                }
                            }
                        }
                        // -------------------------------------------------------------------

                        let should_submit = self.handle_key_event(key);
                        // Honour `:q`/`:wq` from vim command-line mode
                        if self.prompt_input.vim_quit_requested {
                            self.prompt_input.vim_quit_requested = false;
                            self.should_exit = true;
                        }
                        if self.should_exit {
                            return Ok(None);
                        }
                        if should_submit {
                            // Dismiss any active error modal when the user sends a message
                            self.dismiss_error_notifications();
                            // Check if this is a slash command that should open a UI screen
                            if crate::input::is_slash_command(&self.prompt_input.text) {
                                let slash_input = self.prompt_input.text.clone();
                                let (cmd, args) = crate::input::parse_slash_command(&slash_input);
                                if self.intercept_slash_command_with_args(cmd, args) {
                                    self.clear_prompt();
                                    continue;
                                }
                            }
                            let input = self.take_input();
                            if !input.is_empty() {
                                return Ok(Some(input));
                            }
                        }
                    }
                    Event::Paste(data)
                        if !self.is_streaming
                            && self.permission_request.is_none()
                            && !self.history_search_overlay.visible =>
                    {
                        self.handle_paste_data(data);
                        self.refresh_prompt_input();
                    }
                    Event::Mouse(mouse_event) => {
                        self.handle_mouse_event(mouse_event);
                    }
                    _ => {}
                }
            }
        }
    }

    // ========== NEW KEYBINDING HELPER FUNCTIONS (Phase 1) ==========

    /// Jump to the next error/issue in messages.
    /// Searches for common error indicators: "Error:", "ERROR:", "error", "failed", "FAIL".
    fn jump_to_next_error(&mut self) {
        const ERROR_KEYWORDS: &[&str] = &["error:", "failed:", "fail"];

        // Search forward from current position
        for i in 0..self.messages.len() {
            let msg = &self.messages[i];
            let content = msg.get_all_text().to_lowercase();

            // Check if message contains error keywords
            let has_error = ERROR_KEYWORDS
                .iter()
                .any(|keyword| content.contains(keyword));

            if has_error && i > (self.messages.len().saturating_sub(self.scroll_offset / 2)) {
                // Found an error message, scroll to it
                let new_offset = self.messages.len().saturating_sub(i);
                self.scroll_offset = new_offset.saturating_mul(2);
                self.auto_scroll = false;
                self.status_message = Some(format!("Error found in message {}", i + 1));
                return;
            }
        }

        self.status_message = Some("No more errors found.".to_string());
    }

    /// Jump to the previous error/issue in messages.
    /// Searches backwards for common error indicators.
    fn jump_to_previous_error(&mut self) {
        const ERROR_KEYWORDS: &[&str] = &["error:", "failed:", "fail"];

        // Search backward from current position
        for i in (0..self.messages.len()).rev() {
            let msg = &self.messages[i];
            let content = msg.get_all_text().to_lowercase();

            // Check if message contains error keywords
            let has_error = ERROR_KEYWORDS
                .iter()
                .any(|keyword| content.contains(keyword));

            if has_error && i < (self.messages.len().saturating_sub(self.scroll_offset / 2)) {
                // Found an error message, scroll to it
                let new_offset = self.messages.len().saturating_sub(i);
                self.scroll_offset = new_offset.saturating_mul(2);
                self.auto_scroll = false;
                self.status_message = Some(format!("Error found in message {}", i + 1));
                return;
            }
        }

        self.status_message = Some("No previous errors found.".to_string());
    }
}

// Helper function to open a file in the user's external editor
fn open_file_externally(path: &std::path::Path) -> std::io::Result<()> {
    // Try to open with the system's default application
    #[cfg(target_os = "macos")]
    {
        std::process::Command::new("/usr/bin/open")
            .arg(path)
            .spawn()?;
        Ok(())
    }

    #[cfg(target_os = "linux")]
    {
        std::process::Command::new("xdg-open").arg(path).spawn()?;
        Ok(())
    }

    #[cfg(target_os = "windows")]
    {
        let system_root = windows_system_root();
        let mut command = std::process::Command::new(
            std::path::Path::new(&system_root)
                .join("System32")
                .join("cmd.exe"),
        );
        let quoted_path = quote_windows_cmd_path(path);
        command
            .args(["/C", "start", ""])
            .arg(quoted_path)
            .env_clear()
            .env("SystemRoot", &system_root)
            .env("WINDIR", &system_root);
        command.spawn()?;
        Ok(())
    }

    #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
    {
        // Fallback for other systems: try common editors in order
        for editor in &["nano", "vi", "vim", "emacs"] {
            match std::process::Command::new(editor).arg(path).spawn() {
                Ok(_) => return Ok(()),
                Err(_) => continue,
            }
        }
        Err(std::io::Error::new(
            std::io::ErrorKind::NotFound,
            "No suitable editor found",
        ))
    }
}

#[cfg(any(test, target_os = "windows"))]
fn quote_windows_cmd_path(path: &std::path::Path) -> std::ffi::OsString {
    let mut quoted = std::ffi::OsString::from("\"");
    quoted.push(path.as_os_str());
    quoted.push("\"");
    quoted
}

#[cfg(any(test, target_os = "windows"))]
fn windows_system_root_from_env(
    system_root: Option<std::ffi::OsString>,
    windir: Option<std::ffi::OsString>,
) -> std::ffi::OsString {
    system_root
        .into_iter()
        .chain(windir)
        .find(|root| std::path::Path::new(root).is_absolute())
        .unwrap_or_else(|| std::ffi::OsString::from(r"C:\Windows"))
}

#[cfg(target_os = "windows")]
fn windows_system_root() -> std::ffi::OsString {
    windows_system_root_from_env(std::env::var_os("SystemRoot"), std::env::var_os("WINDIR"))
}

#[cfg(test)]
mod tests {
    use super::test_env::EnvGuard;
    use super::*;
    use crossterm::event::{KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers};

    fn make_app() -> App {
        let config = Config::default();
        let cost_tracker = claurst_core::cost::CostTracker::new();
        App::new(config, cost_tracker)
    }

    fn press_key(code: KeyCode, modifiers: KeyModifiers) -> KeyEvent {
        KeyEvent {
            code,
            modifiers,
            kind: KeyEventKind::Press,
            state: KeyEventState::NONE,
        }
    }

    fn test_agent_definition() -> claurst_core::AgentDefinition {
        claurst_core::AgentDefinition {
            description: Some("custom".to_string()),
            prompt: Some("custom prompt".to_string()),
            ..Default::default()
        }
    }

    fn test_managed_agents() -> claurst_core::ManagedAgentConfig {
        claurst_core::ManagedAgentConfig {
            enabled: true,
            manager_model: "anthropic/claude-opus-4-6".to_string(),
            executor_model: "anthropic/claude-sonnet-4-6".to_string(),
            executor_max_turns: 10,
            max_concurrent_executors: 2,
            budget_split: Default::default(),
            total_budget_usd: Some(5.0),
            preset_name: Some("test".to_string()),
            executor_isolation: true,
        }
    }

    #[test]
    fn cycle_agent_mode_clears_visible_familiar() {
        let mut app = make_app();
        app.config.familiar = Some("wisp".to_string());
        app.agent_mode = Some("wisp".to_string());

        app.cycle_agent_mode();

        assert_eq!(app.agent_mode.as_deref(), Some("plan"));
        assert!(app.config.familiar.is_none());
        assert!(app.agent_mode_changed);
    }

    #[test]
    fn reset_agents_and_familiars_clears_runtime_roster_state() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        let project = temp.path().join("project");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        std::fs::create_dir_all(&project).expect("project dir");
        std::fs::write(
            coven_home.join("familiars.toml"),
            "[[familiar]]\nid = \"ember\"\n",
        )
        .expect("familiar roster");
        let guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        app.agents_menu.project_root = Some(project);
        app.config
            .agents
            .insert("custom".to_string(), test_agent_definition());
        app.config.familiar = Some("ember".to_string());
        app.config.managed_agents = Some(test_managed_agents());
        app.config.permission_mode = claurst_core::config::PermissionMode::Plan;
        app.agent_mode = Some("ember".to_string());
        app.agent_mode_changed = false;
        app.accent_color = ACCENT_PLAN;
        app.plan_mode = true;
        app.managed_agents_active = true;
        app.familiar_switcher_open = true;
        app.familiar_switcher_list = vec!["ember".to_string(), "onyx".to_string()];
        app.familiar_switcher_idx = 1;

        app.reset_agents_and_familiars();

        assert!(app.config.familiar.is_none());
        assert!(app.config.agents.is_empty());
        assert!(app.config.managed_agents.is_none());
        assert_eq!(
            app.config.permission_mode,
            claurst_core::config::PermissionMode::Default
        );
        assert!(app.agent_mode.is_none());
        assert!(app.agent_mode_changed);
        assert_eq!(app.accent_color, ACCENT_BUILD);
        assert!(!app.plan_mode);
        assert!(!app.managed_agents_active);
        assert!(!app.familiar_switcher_open);
        assert!(app.familiar_switcher_list.is_empty());
        assert_eq!(app.familiar_switcher_idx, 0);
        assert!(!coven_home.join("familiars.toml").exists());
        drop(guard);
    }

    #[test]
    fn familiar_switcher_entries_lead_with_clear_and_filter() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        app.familiar_switcher_list = vec!["ember".to_string(), "onyx".to_string()];

        // No filter → Clear leads, then all familiars in order.
        app.familiar_switcher_filter.clear();
        let entries = app.familiar_switcher_entries();
        assert_eq!(entries[0], FamiliarSwitcherEntry::Clear);
        assert_eq!(
            entries[1],
            FamiliarSwitcherEntry::Familiar("ember".to_string())
        );
        assert_eq!(
            entries[2],
            FamiliarSwitcherEntry::Familiar("onyx".to_string())
        );

        // Filter narrows to matching ids and drops the Clear row.
        app.familiar_switcher_filter = "ony".to_string();
        let entries = app.familiar_switcher_entries();
        assert_eq!(
            entries,
            vec![FamiliarSwitcherEntry::Familiar("onyx".to_string())]
        );

        // Typing toward "none" keeps the Clear row available.
        app.familiar_switcher_filter = "non".to_string();
        let entries = app.familiar_switcher_entries();
        assert_eq!(entries, vec![FamiliarSwitcherEntry::Clear]);
    }

    #[test]
    fn startup_familiar_switcher_uses_saved_roster_only() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        let _guard = EnvGuard::set(&home, &coven_home);

        let list = App::default_familiar_switcher_list();
        assert!(list.is_empty());
    }

    #[test]
    fn app_does_not_infer_builtin_familiar_without_saved_roster() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        let _guard = EnvGuard::set_with_user(&home, &coven_home, Some("ember"));

        let app = make_app();

        assert_eq!(app.config.familiar, None);
        assert!(app.familiar_switcher_list.is_empty());
    }

    #[test]
    fn app_infers_familiar_only_from_saved_roster() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        std::fs::write(
            coven_home.join("familiars.toml"),
            r#"
[[familiar]]
id = "wisp"
display_name = "Wisp"
role = "Research"
"#,
        )
        .expect("familiars file");
        let _guard = EnvGuard::set_with_user(&home, &coven_home, Some("wisp"));

        let app = make_app();

        assert_eq!(app.config.familiar.as_deref(), Some("wisp"));
        assert_eq!(app.familiar_switcher_list, vec!["wisp".to_string()]);
    }

    #[test]
    fn f2_bootstraps_starter_roster_when_standalone_and_empty() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        // No daemon socket → standalone → F2 writes a starter roster and opens.
        app.handle_key_event(press_key(KeyCode::F(2), KeyModifiers::NONE));

        assert!(app.familiar_switcher_open);
        assert_eq!(
            app.familiar_switcher_list,
            vec!["sage".to_string(), "forge".to_string()]
        );
        assert!(coven_home.join("familiars.toml").exists());
    }

    #[test]
    fn f2_refreshes_roster_added_mid_session() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        std::fs::write(
            coven_home.join("familiars.toml"),
            "[[familiar]]\nid = \"wisp\"\n",
        )
        .expect("familiars file");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        assert_eq!(app.familiar_switcher_list, vec!["wisp".to_string()]);

        // A familiar added after startup (external edit or daemon write) must
        // appear when the switcher is opened, without restarting.
        std::fs::write(
            coven_home.join("familiars.toml"),
            "[[familiar]]\nid = \"wisp\"\n\n[[familiar]]\nid = \"onyx\"\n",
        )
        .expect("familiars rewrite");
        app.handle_key_event(press_key(KeyCode::F(2), KeyModifiers::NONE));

        assert!(app.familiar_switcher_open);
        assert_eq!(
            app.familiar_switcher_list,
            vec!["wisp".to_string(), "onyx".to_string()]
        );
    }

    #[test]
    fn f2_does_not_write_roster_when_daemon_present() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        // Simulate a running daemon by creating its IPC socket.
        std::fs::write(coven_home.join("coven.sock"), b"").expect("socket");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        app.handle_key_event(press_key(KeyCode::F(2), KeyModifiers::NONE));

        assert!(!app.familiar_switcher_open);
        assert!(!coven_home.join("familiars.toml").exists());
        assert!(app
            .status_message
            .as_deref()
            .unwrap_or_default()
            .contains("Coven daemon"));
    }

    #[test]
    fn reset_agents_and_familiars_preserves_non_plan_permission_mode() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        let project = temp.path().join("project");
        std::fs::create_dir_all(&home).expect("home dir");
        std::fs::create_dir_all(&coven_home).expect("coven home dir");
        std::fs::create_dir_all(&project).expect("project dir");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        app.agents_menu.project_root = Some(project);
        app.config.permission_mode = claurst_core::config::PermissionMode::AcceptEdits;

        app.reset_agents_and_familiars();

        assert_eq!(
            app.config.permission_mode,
            claurst_core::config::PermissionMode::AcceptEdits
        );
    }

    #[test]
    fn windows_cmd_path_is_passed_as_quoted_argument() {
        let path = std::path::Path::new(r"C:\temp\safe & literal.txt");

        assert_eq!(
            quote_windows_cmd_path(path).to_string_lossy(),
            r#""C:\temp\safe & literal.txt""#
        );
    }

    #[test]
    fn windows_system_root_prefers_absolute_system_root() {
        let system_root = std::env::temp_dir().join("windows-root").into_os_string();
        let windir = std::env::temp_dir().join("windir").into_os_string();
        let root = windows_system_root_from_env(Some(system_root.clone()), Some(windir));

        assert_eq!(root, system_root);
    }

    #[test]
    fn windows_system_root_falls_back_to_absolute_windir() {
        let windir = std::env::temp_dir().join("windir").into_os_string();
        let root = windows_system_root_from_env(
            Some(std::ffi::OsString::from("relative-system-root")),
            Some(windir.clone()),
        );

        assert_eq!(root, windir);
    }

    #[test]
    fn windows_system_root_ignores_relative_paths() {
        let root = windows_system_root_from_env(
            Some(std::ffi::OsString::from("relative-system-root")),
            Some(std::ffi::OsString::from("relative-windir")),
        );

        assert_eq!(root, std::ffi::OsString::from(r"C:\Windows"));
    }

    // ---- signal_bg_task_completion tests ----

    fn make_bg_completion(success: bool) -> claurst_tools::BgTaskCompletion {
        claurst_tools::BgTaskCompletion {
            task_id: "task-1".to_string(),
            command: "cargo build --release".to_string(),
            success,
            exit_info: if success {
                "exit 0".to_string()
            } else {
                "failed: exit 1".to_string()
            },
            output_tail: "compiling...".to_string(),
            duration_secs: 42,
        }
    }

    #[test]
    fn bg_task_success_pushes_success_toast() {
        let mut app = make_app();
        let info = make_bg_completion(true);
        app.signal_bg_task_completion(&info, true, false);
        let n = app.notifications.current().expect("toast pushed");
        assert_eq!(n.kind, NotificationKind::Success);
        assert!(n.message.contains("cargo build --release"));
        assert!(n.message.contains("42s"));
    }

    #[test]
    fn bg_task_failure_pushes_error_toast_no_autoexpire() {
        let mut app = make_app();
        let info = make_bg_completion(false);
        app.signal_bg_task_completion(&info, true, false);
        let n = app.notifications.current().expect("toast pushed");
        assert_eq!(n.kind, NotificationKind::Error);
        assert!(n.message.contains("failed"));
        assert!(
            n.expires_at.is_none(),
            "errors should stay until acknowledged"
        );
    }

    #[test]
    fn bg_task_toast_disabled_pushes_nothing() {
        let mut app = make_app();
        let info = make_bg_completion(true);
        app.signal_bg_task_completion(&info, false, false);
        assert!(app.notifications.current().is_none());
    }

    #[test]
    fn format_duration_secs_buckets() {
        assert_eq!(format_duration_secs(0), "0s");
        assert_eq!(format_duration_secs(59), "59s");
        assert_eq!(format_duration_secs(60), "1m 0s");
        assert_eq!(format_duration_secs(125), "2m 5s");
        assert_eq!(format_duration_secs(3661), "1h 1m");
    }

    // ---- normalize_char_with_shift tests ----

    #[test]
    fn test_normalize_char_no_shift_returns_unchanged() {
        assert_eq!(normalize_char_with_shift('a', KeyModifiers::NONE), 'a');
        assert_eq!(normalize_char_with_shift('1', KeyModifiers::NONE), '1');
        assert_eq!(normalize_char_with_shift('!', KeyModifiers::NONE), '!');
    }

    #[test]
    fn test_normalize_char_shift_uppercase_letters() {
        assert_eq!(normalize_char_with_shift('a', KeyModifiers::SHIFT), 'A');
        assert_eq!(normalize_char_with_shift('z', KeyModifiers::SHIFT), 'Z');
        assert_eq!(normalize_char_with_shift('m', KeyModifiers::SHIFT), 'M');
    }

    #[test]
    fn test_normalize_char_shift_numbers() {
        assert_eq!(normalize_char_with_shift('1', KeyModifiers::SHIFT), '!');
        assert_eq!(normalize_char_with_shift('2', KeyModifiers::SHIFT), '@');
        assert_eq!(normalize_char_with_shift('3', KeyModifiers::SHIFT), '#');
        assert_eq!(normalize_char_with_shift('4', KeyModifiers::SHIFT), '$');
        assert_eq!(normalize_char_with_shift('5', KeyModifiers::SHIFT), '%');
        assert_eq!(normalize_char_with_shift('6', KeyModifiers::SHIFT), '^');
        assert_eq!(normalize_char_with_shift('7', KeyModifiers::SHIFT), '&');
        assert_eq!(normalize_char_with_shift('8', KeyModifiers::SHIFT), '*');
        assert_eq!(normalize_char_with_shift('9', KeyModifiers::SHIFT), '(');
        assert_eq!(normalize_char_with_shift('0', KeyModifiers::SHIFT), ')');
    }

    #[test]
    fn test_normalize_char_shift_symbols() {
        assert_eq!(normalize_char_with_shift('-', KeyModifiers::SHIFT), '_');
        assert_eq!(normalize_char_with_shift('=', KeyModifiers::SHIFT), '+');
        assert_eq!(normalize_char_with_shift('[', KeyModifiers::SHIFT), '{');
        assert_eq!(normalize_char_with_shift(']', KeyModifiers::SHIFT), '}');
        assert_eq!(normalize_char_with_shift(';', KeyModifiers::SHIFT), ':');
        assert_eq!(normalize_char_with_shift('\'', KeyModifiers::SHIFT), '"');
        assert_eq!(normalize_char_with_shift(',', KeyModifiers::SHIFT), '<');
        assert_eq!(normalize_char_with_shift('.', KeyModifiers::SHIFT), '>');
        assert_eq!(normalize_char_with_shift('/', KeyModifiers::SHIFT), '?');
        assert_eq!(normalize_char_with_shift('\\', KeyModifiers::SHIFT), '|');
        assert_eq!(normalize_char_with_shift('`', KeyModifiers::SHIFT), '~');
    }

    #[test]
    fn test_normalize_char_shift_already_shifted_chars_unchanged() {
        // Characters that don't have shift equivalents remain unchanged
        assert_eq!(normalize_char_with_shift('!', KeyModifiers::SHIFT), '!');
        assert_eq!(normalize_char_with_shift('@', KeyModifiers::SHIFT), '@');
        assert_eq!(normalize_char_with_shift('A', KeyModifiers::SHIFT), 'A');
    }

    #[test]
    fn test_normalize_char_other_modifiers_ignored() {
        // CTRL or ALT without SHIFT should not shift the character
        assert_eq!(normalize_char_with_shift('a', KeyModifiers::CONTROL), 'a');
        assert_eq!(normalize_char_with_shift('1', KeyModifiers::ALT), '1');
        assert_eq!(
            normalize_char_with_shift('a', KeyModifiers::CONTROL | KeyModifiers::ALT),
            'a'
        );
    }

    #[test]
    fn test_normalize_char_shift_with_other_modifiers() {
        // SHIFT + CTRL should still apply shift transformation
        assert_eq!(
            normalize_char_with_shift('a', KeyModifiers::SHIFT | KeyModifiers::CONTROL),
            'A'
        );
        assert_eq!(
            normalize_char_with_shift('1', KeyModifiers::SHIFT | KeyModifiers::ALT),
            '!'
        );
    }

    #[test]
    fn test_mcp_subcommand_is_not_intercepted() {
        let mut app = make_app();
        assert!(!app.intercept_slash_command_with_args("mcp", "auth mcphub"));
        assert!(!app.mcp_view.visible);
    }

    #[test]
    fn argument_forms_reach_command_layer() {
        let mut app = make_app();
        // Folded subcommand forms must not be swallowed by the bare-name
        // TUI intercepts (issues #59/#73).
        assert!(!app.intercept_slash_command_with_args("rewind", "list"));
        assert!(!app.rewind_flow.visible);
        assert!(!app.intercept_slash_command_with_args("session", "rename my-title"));
        assert!(!app.session_browser.visible);
        assert!(!app.intercept_slash_command_with_args("export", "copy 2"));
        assert!(!app.export_dialog.visible);
        assert!(!app.intercept_slash_command_with_args("review", "security"));
        assert!(!app.intercept_slash_command_with_args("status", "doctor"));
        assert!(!app.intercept_slash_command_with_args("thinking", "back"));
        // Bare forms keep their overlays.
        assert!(app.intercept_slash_command_with_args("rewind", ""));
        assert!(app.rewind_flow.visible);
    }

    #[test]
    fn folded_subcommands_open_legacy_tui_surfaces() {
        let mut app = make_app();
        assert!(app.intercept_slash_command_with_args("usage", "stats"));
        assert!(app.stats_dialog.visible);
        app.stats_dialog.close();
        assert!(app.intercept_slash_command_with_args("config", "theme"));
        assert!(app.theme_screen.visible);
    }

    #[test]
    fn test_clear_slash_command_clears_messages() {
        let mut app = make_app();
        app.add_message(Role::User, "hello".to_string());
        app.add_message(Role::Assistant, "world".to_string());
        assert_eq!(app.messages.len(), 2);
        assert!(app.intercept_slash_command("clear"));
        assert_eq!(app.messages.len(), 0);
    }

    #[test]
    fn test_exit_slash_command_sets_quit_flag() {
        let mut app = make_app();
        assert!(!app.should_exit);
        assert!(app.intercept_slash_command("exit"));
        assert!(app.should_exit);
    }

    #[test]
    fn test_vim_slash_command_toggles_vim() {
        let mut app = make_app();
        assert!(!app.prompt_input.vim_enabled);
        assert!(app.intercept_slash_command("vim"));
        assert!(app.prompt_input.vim_enabled);
        assert!(app.intercept_slash_command("vim"));
        assert!(!app.prompt_input.vim_enabled);
    }

    #[test]
    fn config_with_args_reaches_command_layer() {
        let mut app = make_app();
        assert!(!app.settings_screen.visible);
        assert!(!app.intercept_slash_command_with_args("config", "vim on"));
        assert!(!app.settings_screen.visible);
    }

    #[test]
    fn test_model_slash_command_opens_picker() {
        let mut app = make_app();
        assert!(!app.model_picker.visible);
        assert!(app.intercept_slash_command("model"));
        assert!(app.model_picker.visible);
    }

    #[test]
    fn test_fast_slash_command_toggles_fast_mode() {
        let mut app = make_app();
        assert!(!app.fast_mode);
        assert!(app.intercept_slash_command("fast"));
        assert!(app.fast_mode);
        assert!(app.intercept_slash_command("fast"));
        assert!(!app.fast_mode);
    }

    #[test]
    fn test_output_style_cycles() {
        let mut app = make_app();
        assert_eq!(app.output_style, "auto");
        assert!(app.intercept_slash_command("output-style"));
        assert_eq!(app.output_style, "stream");
        assert!(app.intercept_slash_command("output-style"));
        assert_eq!(app.output_style, "verbose");
        assert!(app.intercept_slash_command("output-style"));
        assert_eq!(app.output_style, "auto");
    }

    #[test]
    fn test_context_menu_fork_targets_clicked_message() {
        let mut app = make_app();
        app.add_message(Role::User, "one".to_string());
        app.add_message(Role::Assistant, "two".to_string());
        app.add_message(Role::User, "three".to_string());

        app.handle_context_menu_action(
            ContextMenuItem::Fork,
            ContextMenuKind::Message { message_index: 1 },
        );

        assert_eq!(app.prompt_input.text, "/fork 2");
        assert_eq!(
            app.status_message.as_deref(),
            Some("Fork at message 2 - press Enter to confirm")
        );
    }

    #[test]
    fn test_right_click_targets_row_message_instead_of_last_message() {
        use crossterm::event::{KeyModifiers, MouseButton, MouseEvent, MouseEventKind};

        let mut app = make_app();
        app.last_msg_area.set(ratatui::layout::Rect {
            x: 0,
            y: 0,
            width: 80,
            height: 10,
        });
        app.message_row_map.borrow_mut().insert(3, 1);

        app.handle_mouse_event(MouseEvent {
            kind: MouseEventKind::Down(MouseButton::Right),
            column: 12,
            row: 3,
            modifiers: KeyModifiers::empty(),
        });

        assert!(matches!(
            app.context_menu_state,
            Some(ContextMenuState {
                kind: ContextMenuKind::Message { message_index: 1 },
                ..
            })
        ));
    }

    #[test]
    fn test_permission_dialog_esc_takes_priority_over_error_modal() {
        use crate::dialogs::PermissionRequest;

        let mut app = make_app();
        app.permission_request = Some(PermissionRequest::standard(
            "tu-1".to_string(),
            "Bash".to_string(),
            "Run a shell command".to_string(),
        ));
        app.notifications.push(
            crate::notifications::NotificationKind::Error,
            "dangerous command failed".to_string(),
            None,
        );

        app.handle_key_event(press_key(KeyCode::Esc, KeyModifiers::empty()));

        assert!(app.permission_request.is_none());
        assert!(app.notifications.current_is_error());
    }

    #[test]
    fn test_permission_dialog_navigation_takes_priority_over_context_menu() {
        use crate::dialogs::PermissionRequest;

        let mut app = make_app();
        app.permission_request = Some(PermissionRequest::standard(
            "tu-1".to_string(),
            "Bash".to_string(),
            "Run a shell command".to_string(),
        ));
        app.context_menu_state = Some(ContextMenuState {
            x: 1,
            y: 1,
            selected_index: 0,
            kind: ContextMenuKind::Selection,
        });

        app.handle_key_event(press_key(KeyCode::Down, KeyModifiers::empty()));

        assert_eq!(
            app.permission_request
                .as_ref()
                .map(|request| request.selected_option),
            Some(1)
        );
        assert_eq!(
            app.context_menu_state
                .as_ref()
                .map(|menu| menu.selected_index),
            Some(0)
        );
    }

    // ---- Help overlay -------------------------------------------------------

    #[test]
    fn test_help_slash_command_opens_overlay() {
        let mut app = make_app();
        assert!(!app.help_overlay.visible);
        assert!(!app.help_overlay.commands.is_empty());
        assert!(app.intercept_slash_command("help"));
        assert!(app.help_overlay.visible);
    }

    #[test]
    fn test_help_slash_command_is_idempotent_when_already_open() {
        let mut app = make_app();
        // First call opens it.
        assert!(app.intercept_slash_command("help"));
        assert!(app.help_overlay.visible);
        // Second call while already open should leave it open (not toggle it off).
        assert!(app.intercept_slash_command("help"));
        assert!(app.help_overlay.visible);
    }

    #[test]
    fn test_question_mark_shortcut_opens_help_with_shift_modifier() {
        let mut app = make_app();

        app.handle_key_event(press_key(KeyCode::Char('?'), KeyModifiers::SHIFT));

        assert!(app.help_overlay.visible);
    }

    #[test]
    fn test_question_mark_shortcut_closes_help_with_shift_modifier() {
        let mut app = make_app();
        app.help_overlay.toggle();

        app.handle_key_event(press_key(KeyCode::Char('?'), KeyModifiers::SHIFT));

        assert!(!app.help_overlay.visible);
    }

    #[test]
    fn test_question_mark_shortcut_types_into_non_empty_prompt() {
        let mut app = make_app();
        app.prompt_input.text = "why".to_string();
        app.prompt_input.cursor = app.prompt_input.text.len();
        app.refresh_prompt_input();

        app.handle_key_event(press_key(KeyCode::Char('?'), KeyModifiers::SHIFT));

        assert!(!app.help_overlay.visible);
        assert_eq!(app.prompt_input.text, "why?");
    }

    #[test]
    fn test_ctrl_shift_a_shortcut_opens_model_picker() {
        let mut app = make_app();
        app.has_credentials = true;
        app.config.provider = Some("anthropic".to_string());

        app.handle_key_event(press_key(
            KeyCode::Char('a'),
            KeyModifiers::CONTROL | KeyModifiers::SHIFT,
        ));

        assert!(app.model_picker.visible);
    }

    #[test]
    fn provider_picker_marks_claude_cli_local_when_binary_exists() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        let claude_bin = temp.path().join(if cfg!(windows) {
            "claude.cmd"
        } else {
            "claude"
        });
        std::fs::create_dir_all(&home).expect("home");
        std::fs::create_dir_all(&coven_home).expect("coven home");
        std::fs::write(&claude_bin, "").expect("claude binary");
        let _guard = EnvGuard::set(&home, &coven_home);
        std::env::set_var(
            claurst_api::providers::claude_cli::CLAUDE_BIN_ENV,
            &claude_bin,
        );

        let items = provider_picker_items();

        assert_eq!(
            items.first().map(|item| item.id.as_str()),
            Some("anthropic-cli")
        );
        assert_eq!(
            items.first().and_then(|item| item.badge.as_deref()),
            Some("LOCAL")
        );
    }

    #[test]
    fn provider_picker_only_exposes_cli_login_choices() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home");
        std::fs::create_dir_all(&coven_home).expect("coven home");
        let _guard = EnvGuard::set(&home, &coven_home);
        std::env::set_var("ANTHROPIC_API_KEY", "sk-ant-test");
        std::env::set_var(claurst_core::oauth::CLIENT_ID_ENV, "oauth-client-test");

        let items = provider_picker_items();
        let ids: Vec<&str> = items.iter().map(|item| item.id.as_str()).collect();

        assert_eq!(ids, vec!["anthropic-cli", "openai-codex"]);
        assert!(items.iter().all(|item| {
            let text = format!("{} {}", item.title, item.description).to_ascii_lowercase();
            !text.contains("api key") && !text.contains("oauth")
        }));
    }

    #[test]
    fn provider_setup_one_activates_claude_cli_runtime() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home");
        std::fs::create_dir_all(&coven_home).expect("coven home");
        let _guard = EnvGuard::set(&home, &coven_home);
        // Force claude-binary discovery so the test is deterministic on
        // machines without the CLI installed.
        let fake_claude = temp.path().join("claude");
        std::fs::write(&fake_claude, "").expect("fake claude");
        std::env::set_var(
            claurst_api::providers::claude_cli::CLAUDE_BIN_ENV,
            &fake_claude,
        );

        let mut app = make_app();
        app.has_credentials = false;
        app.onboarding_dialog.show_provider_setup();

        app.handle_key_event(press_key(KeyCode::Char('1'), KeyModifiers::empty()));

        std::env::remove_var(claurst_api::providers::claude_cli::CLAUDE_BIN_ENV);

        assert!(!app.onboarding_dialog.visible);
        assert!(!app.connect_dialog.visible);
        assert!(!app.key_input_dialog.visible);
        assert!(app.has_credentials);
    }

    #[test]
    fn provider_setup_two_starts_codex_auth() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home");
        std::fs::create_dir_all(&coven_home).expect("coven home");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        app.has_credentials = false;
        app.onboarding_dialog.show_provider_setup();

        app.handle_key_event(press_key(KeyCode::Char('2'), KeyModifiers::empty()));

        assert!(!app.onboarding_dialog.visible);
        assert!(!app.connect_dialog.visible);
        assert!(app.device_auth_dialog.visible);
        assert_eq!(app.device_auth_dialog.provider_name, "Codex CLI");
        assert_eq!(app.device_auth_pending.as_deref(), Some("openai-codex"));
    }

    #[test]
    fn provider_setup_enter_opens_full_connect_picker() {
        let temp = tempfile::tempdir().expect("tempdir");
        let home = temp.path().join("home");
        let coven_home = temp.path().join("coven");
        std::fs::create_dir_all(&home).expect("home");
        std::fs::create_dir_all(&coven_home).expect("coven home");
        let _guard = EnvGuard::set(&home, &coven_home);

        let mut app = make_app();
        app.has_credentials = false;
        app.onboarding_dialog.show_provider_setup();

        app.handle_key_event(press_key(KeyCode::Enter, KeyModifiers::empty()));

        assert!(!app.onboarding_dialog.visible);
        assert!(app.connect_dialog.visible);
        assert!(!app.key_input_dialog.visible);
        assert!(app.device_auth_pending.is_none());
    }

    #[test]
    fn test_ctrl_k_shortcut_opens_command_palette_even_with_input() {
        let mut app = make_app();
        app.prompt_input.text = "hello".to_string();
        app.prompt_input.cursor = app.prompt_input.text.len();
        app.refresh_prompt_input();

        app.handle_key_event(press_key(KeyCode::Char('k'), KeyModifiers::CONTROL));

        assert!(app.command_palette.visible);
        assert_eq!(app.prompt_input.text, "hello");
    }

    // ---- Bash prefix allowlist ----------------------------------------------

    #[test]
    fn test_bash_command_not_allowed_by_default() {
        let app = make_app();
        assert!(!app.bash_command_allowed_by_prefix("git status"));
        assert!(!app.bash_command_allowed_by_prefix("ls -la"));
        assert!(!app.bash_command_allowed_by_prefix(""));
    }

    #[test]
    fn test_bash_prefix_allowlist_after_p_key() {
        use crate::dialogs::PermissionRequest;
        use crossterm::event::{KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers};

        let mut app = make_app();
        // Set up a bash permission dialog with a suggested prefix.
        let pr = PermissionRequest::bash(
            "tu-1".to_string(),
            "Bash".to_string(),
            "This will execute a shell command.".to_string(),
            "git status".to_string(),
            Some("git status".to_string()),
        );
        app.permission_request = Some(pr);

        // Simulate pressing 'P' (prefix-allow key).
        let key = KeyEvent {
            code: KeyCode::Char('P'),
            modifiers: KeyModifiers::SHIFT,
            kind: KeyEventKind::Press,
            state: KeyEventState::NONE,
        };
        app.handle_permission_key(key);

        // Dialog should be dismissed and the suggested prefix added to the allowlist.
        assert!(app.permission_request.is_none());
        assert!(app.bash_command_allowed_by_prefix("git status"));
        assert!(app.bash_command_allowed_by_prefix("git status --short"));
        // Other commands and compound shell commands should NOT be allowed.
        assert!(!app.bash_command_allowed_by_prefix("git push origin main"));
        assert!(!app.bash_command_allowed_by_prefix("git status; curl https://example.com"));
        assert!(!app.bash_command_allowed_by_prefix("git status ; curl https://example.com"));
        assert!(!app.bash_command_allowed_by_prefix("git status > /tmp/status.txt"));
        assert!(!app.bash_command_allowed_by_prefix("rm -rf /tmp"));
    }

    #[test]
    fn test_bash_prefix_allowlist_via_enter_on_p_option() {
        use crate::dialogs::PermissionRequest;
        use crossterm::event::{KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers};

        let mut app = make_app();
        let mut pr = PermissionRequest::bash(
            "tu-2".to_string(),
            "Bash".to_string(),
            "This will execute a shell command.".to_string(),
            "cargo build".to_string(),
            Some("cargo build".to_string()),
        );
        // Navigate to the prefix option (index 3 in a 5-option dialog).
        pr.selected_option = 3;
        app.permission_request = Some(pr);

        // Press Enter to confirm the currently selected (prefix) option.
        let key = KeyEvent {
            code: KeyCode::Enter,
            modifiers: KeyModifiers::NONE,
            kind: KeyEventKind::Press,
            state: KeyEventState::NONE,
        };
        app.handle_permission_key(key);

        assert!(app.permission_request.is_none());
        assert!(app.bash_command_allowed_by_prefix("cargo build --workspace"));
        assert!(!app.bash_command_allowed_by_prefix("cargo test"));
        assert!(!app.bash_command_allowed_by_prefix("make build"));
    }

    #[test]
    fn test_bash_prefix_allowlist_non_prefix_option_does_not_add() {
        use crate::dialogs::PermissionRequest;
        use crossterm::event::{KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers};

        let mut app = make_app();
        let pr = PermissionRequest::bash(
            "tu-3".to_string(),
            "Bash".to_string(),
            "This will execute a shell command.".to_string(),
            "npm install".to_string(),
            Some("npm".to_string()),
        );
        app.permission_request = Some(pr);

        // Press 'y' (allow-once) — should NOT add to allowlist.
        let key = KeyEvent {
            code: KeyCode::Char('y'),
            modifiers: KeyModifiers::NONE,
            kind: KeyEventKind::Press,
            state: KeyEventState::NONE,
        };
        app.handle_permission_key(key);

        assert!(app.permission_request.is_none());
        assert!(!app.bash_command_allowed_by_prefix("npm test"));
    }
}