zeph_tui/app/

events.rs

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

use std::time::Instant;

use tokio::sync::mpsc;

use crate::event::{AgentEvent, AppEvent};

use super::{App, ChatMessage, ConfirmState, ElicitationState, MessageRole, debug};

impl App {
    /// Dispatch a top-level [`AppEvent`] to the appropriate handler.
    ///
    /// Called once per event in the main [`crate::run_tui`] loop.
    pub fn handle_event(&mut self, event: AppEvent) {
        match event {
            AppEvent::Key(key) => self.handle_key(key),
            AppEvent::Tick => {
                self.throbber_state.calc_next();
                self.wave_tick = self.wave_tick.saturating_add(1);
                self.tick_delights();
            }
            AppEvent::Resize(_, _) => {
                self.sessions.current_mut().render_cache.clear();
            }
            AppEvent::Agent(agent_event) => self.handle_agent_event(agent_event),
            // Routed through `reduce` (S1, spec 084) rather than calling `handle_paste`
            // directly: this is behaviour-identical (the `InsertText` reducer arm just
            // calls `handle_paste`) but gives paste the mention-picker resync for free —
            // without it, pasting before the `@` shifts the buffer while `at_char_index`
            // stays fixed, which can invert `MentionPickerAccept`'s replacement range.
            AppEvent::Paste(text) => {
                let effects =
                    crate::app::reducer::reduce(self, crate::app::action::Action::InsertText(text));
                crate::app::reducer::run_effects(self, effects);
            }
            AppEvent::Mouse(m) => self.handle_mouse(m),
        }
    }

    /// Await the next [`AgentEvent`] from the agent channel.
    ///
    /// Returns `None` when all senders have been dropped (agent exited).
    /// Called from the `select!` block in [`crate::run_tui`].
    pub fn poll_agent_event(&mut self) -> impl Future<Output = Option<AgentEvent>> + use<'_> {
        self.agent_event_rx.recv()
    }

    /// Non-blocking poll for a pending [`AgentEvent`].
    ///
    /// Used to drain the channel after a first event has been received,
    /// coalescing multiple events into a single render frame.
    ///
    /// # Errors
    ///
    /// Returns `TryRecvError::Empty` if no events are pending, or
    /// `TryRecvError::Disconnected` if the sender has been dropped.
    pub fn try_recv_agent_event(&mut self) -> Result<AgentEvent, mpsc::error::TryRecvError> {
        self.agent_event_rx.try_recv()
    }

    /// Handle an [`AgentEvent`] and update widget state accordingly.
    ///
    /// This is the main state-transition function for agent-driven updates:
    /// appending streaming chunks, recording tool events, displaying confirm
    /// dialogs, and wiring late-bound channels (cancel signal, metrics).
    #[allow(clippy::too_many_lines)] // large match over all agent event variants
    pub fn handle_agent_event(&mut self, event: AgentEvent) {
        match event {
            AgentEvent::Chunk(text) => {
                self.sessions.current_mut().status_label = None;
                // New token chunk — refresh stall clock.
                self.last_progress_at = Instant::now();
                if let Some(last) = self.sessions.current_mut().messages.last_mut()
                    && last.role == MessageRole::Assistant
                    && last.streaming
                {
                    last.content.push_str(&text);
                } else {
                    self.sessions
                        .current_mut()
                        .messages
                        .push(ChatMessage::new(MessageRole::Assistant, text).streaming());
                    self.trim_messages();
                }
                // Micro-delight: update streaming rate estimate with current completion tokens.
                let completion_tokens = self.metrics.completion_tokens;
                self.stream_rate.on_token_chunk(completion_tokens);
                // No explicit cache invalidation needed: the cache key includes
                // content_hash, so new chunk content causes a natural cache miss.
                self.auto_scroll();
            }
            AgentEvent::FullMessage(text) => {
                self.sessions.current_mut().status_label = None;
                if !text.starts_with("[tool output") {
                    self.sessions
                        .current_mut()
                        .messages
                        .push(ChatMessage::new(MessageRole::Assistant, text));
                    self.trim_messages();
                }
                self.auto_scroll();
            }
            AgentEvent::Flush => {
                if let Some(last) = self.sessions.current_mut().messages.last_mut()
                    && last.streaming
                {
                    last.streaming = false;
                    let last_idx = self.sessions.current().messages.len().saturating_sub(1);
                    self.sessions
                        .current_mut()
                        .render_cache
                        .invalidate(last_idx);
                }
            }
            AgentEvent::Typing => {
                self.pending_count = self.pending_count.saturating_sub(1);
                self.sessions.current_mut().status_label = Some("thinking...".to_owned());
                // Turn begins — initialize the stall clock so the first frame is Swell, not Stalled.
                self.last_progress_at = Instant::now();
                // Micro-delight: reset streaming rate tracker for this new turn.
                self.stream_rate.on_turn_start();
            }
            AgentEvent::Status(text) => {
                self.sessions.current_mut().status_label =
                    if text.is_empty() { None } else { Some(text) };
                // Non-empty status update counts as progress (supervisor activity, tool dispatch…).
                if self.sessions.current().status_label.is_some() {
                    self.last_progress_at = Instant::now();
                }
                self.auto_scroll();
            }
            AgentEvent::ToolStart {
                tool_name,
                command,
                tool_call_id,
                is_mcp,
            } => {
                self.sessions.current_mut().status_label = None;
                self.sessions.current_mut().messages.push(
                    ChatMessage::new(MessageRole::Tool, format!("$ {command}\n"))
                        .streaming()
                        .with_tool(tool_name)
                        .with_tool_call_id(tool_call_id)
                        .with_is_mcp(is_mcp),
                );
                self.trim_messages();
                self.auto_scroll();
            }
            AgentEvent::ToolOutputChunk {
                chunk,
                tool_call_id,
                ..
            } => {
                self.last_progress_at = Instant::now();
                let pos = if tool_call_id.is_empty() {
                    // Shell tool chunks arrive without a tool_call_id; fall back to the last
                    // streaming Tool message (there is at most one active at a time).
                    self.sessions
                        .current()
                        .messages
                        .iter()
                        .rposition(|m| m.role == MessageRole::Tool && m.streaming)
                } else {
                    let found =
                        self.sessions.current().messages.iter().rposition(|m| {
                            m.tool_call_id.as_deref() == Some(tool_call_id.as_str())
                        });
                    if found.is_none() {
                        tracing::warn!(
                            %tool_call_id,
                            "ToolOutputChunk: no message with matching tool_call_id — dropping chunk"
                        );
                    }
                    found
                };
                if let Some(pos) = pos {
                    self.sessions.current_mut().messages[pos]
                        .content
                        .push_str(&chunk);
                    self.sessions.current_mut().render_cache.invalidate(pos);
                }
                self.auto_scroll();
            }
            AgentEvent::ToolOutput {
                tool_name,
                output,
                diff,
                filter_stats,
                kept_lines,
                success,
                tool_call_id,
                ..
            } => {
                self.handle_tool_output_event(
                    tool_name,
                    output,
                    diff,
                    filter_stats,
                    kept_lines,
                    success,
                    tool_call_id,
                );
            }
            AgentEvent::ConfirmRequest {
                prompt,
                response_tx,
            } => {
                self.confirm_state = Some(ConfirmState {
                    prompt,
                    response_tx: Some(response_tx),
                });
            }
            AgentEvent::ElicitationRequest {
                request,
                response_tx,
            } => {
                let dialog = crate::widgets::elicitation::ElicitationDialogState::new(request);
                self.elicitation_state = Some(ElicitationState {
                    dialog,
                    response_tx: Some(response_tx),
                });
            }
            AgentEvent::QueueCount(count) => {
                self.queued_count = count;
                self.pending_count = count;
            }
            AgentEvent::DiffReady { diff, tool_call_id } => {
                self.handle_diff_ready(diff, &tool_call_id);
            }
            AgentEvent::CommandResult { output, .. } => {
                self.command_palette = None;
                self.sessions
                    .current_mut()
                    .messages
                    .push(ChatMessage::new(MessageRole::System, output));
                self.trim_messages();
                self.auto_scroll();
            }
            AgentEvent::SetCancelSignal(signal) => {
                self.set_cancel_signal(signal);
            }
            AgentEvent::SetMetricsRx(rx) => {
                self.set_metrics_rx(rx);
            }
            AgentEvent::SetTaskSupervisor(supervisor) => {
                self.set_task_supervisor(supervisor);
            }
            AgentEvent::ForegroundSubagentStarted { id, name } => {
                self.sessions.current_mut().status_label =
                    Some(format!("Sub-agent '{name}' running..."));
                // Status change counts as progress so the wave animates (never reads Stalled).
                self.last_progress_at = Instant::now();
                self.set_view_target(super::AgentViewTarget::SubAgent { id, name });
            }
            AgentEvent::ForegroundSubagentCompleted { id, name, success } => {
                // Only switch back to Main if we are still viewing this subagent.
                // If the user manually navigated away, respect that choice.
                if self.sessions.current().view_target.subagent_id() == Some(id.as_str()) {
                    self.set_view_target(super::AgentViewTarget::Main);
                }
                let label = if success {
                    format!("Sub-agent '{name}' completed")
                } else {
                    format!("Sub-agent '{name}' failed")
                };
                self.sessions.current_mut().status_label = Some(label.clone());
                // Status change counts as progress so the wave animates (never reads Stalled).
                self.last_progress_at = Instant::now();
                self.sessions
                    .current_mut()
                    .messages
                    .push(ChatMessage::new(MessageRole::System, label));
                self.trim_messages();
                self.auto_scroll();
            }
            AgentEvent::BackgroundSubagentCompleted { id, name, success } => {
                // Only act if the user is currently viewing this subagent's transcript —
                // background completions not being viewed are already surfaced via the
                // Channel::send notice pushed to Main chat (notify_completed_subagents), so
                // acting unconditionally here would double-notify every background subagent.
                if self.sessions.current().view_target.subagent_id() == Some(id.as_str()) {
                    let label = if success {
                        format!("Sub-agent '{name}' completed")
                    } else {
                        format!("Sub-agent '{name}' failed")
                    };
                    self.set_view_target(super::AgentViewTarget::Main);
                    self.sessions.current_mut().status_label = Some(label.clone());
                    // Status change counts as progress so the wave animates (never reads Stalled).
                    self.last_progress_at = Instant::now();
                    self.sessions
                        .current_mut()
                        .messages
                        .push(ChatMessage::new(MessageRole::System, label));
                    self.trim_messages();
                    self.auto_scroll();
                }
            }
            AgentEvent::ContextEstimate(tokens) => {
                self.context_token_estimate = tokens;
            }
            AgentEvent::FleetSnapshot(snapshot) => {
                self.fleet_snapshot = snapshot;
            }
            AgentEvent::DurableSnapshot(snapshot) => {
                self.durable_snapshot = snapshot;
            }
            AgentEvent::ResumeBanner(text) => {
                self.resume_banner = Some(text);
            }
            AgentEvent::HistoryBackfill(entries) => {
                self.backfill_history_display_only(&entries);
            }
            AgentEvent::SkillCatalog(items) => {
                self.skill_catalog = Some(items);
                if self.mention_picker.is_some() {
                    let query = crate::app::reducer::mention_picker_query(self);
                    let skills = self.skill_catalog.clone();
                    if let Some(picker) = self.mention_picker.as_mut() {
                        picker.catalog.skills = skills;
                        picker.refilter(&query);
                    }
                }
            }
        }
    }

    fn handle_diff_ready(&mut self, diff: zeph_core::DiffData, tool_call_id: &str) {
        if let Some(msg) = self
            .sessions
            .current_mut()
            .messages
            .iter_mut()
            .rev()
            .find(|m| {
                m.role == MessageRole::Tool && m.tool_call_id.as_deref() == Some(tool_call_id)
            })
        {
            msg.diff_data = Some(diff);
        }
    }

    #[allow(clippy::too_many_arguments)]
    fn handle_tool_output_event(
        &mut self,
        tool_name: zeph_common::ToolName,
        output: String,
        diff: Option<zeph_core::DiffData>,
        filter_stats: Option<String>,
        kept_lines: Option<Vec<usize>>,
        success: bool,
        tool_call_id: String,
    ) {
        debug!(
            %tool_name,
            has_diff = diff.is_some(),
            has_filter_stats = filter_stats.is_some(),
            output_len = output.len(),
            "TUI ToolOutput event received"
        );
        // Try id-based lookup first; fall back to streaming-flag lookup for
        // cases where ToolStart was not emitted (legacy path, empty tool_call_id).
        let pos = if tool_call_id.is_empty() {
            self.sessions
                .current()
                .messages
                .iter()
                .rposition(|m| m.role == MessageRole::Tool && m.streaming)
        } else {
            let found = self
                .sessions
                .current()
                .messages
                .iter()
                .rposition(|m| {
                    m.role == MessageRole::Tool
                        && m.streaming
                        && m.tool_call_id.as_deref() == Some(tool_call_id.as_str())
                })
                .or_else(|| {
                    self.sessions
                        .current()
                        .messages
                        .iter()
                        .rposition(|m| m.role == MessageRole::Tool && m.streaming)
                });
            if found.is_none() {
                tracing::warn!(
                    tool_call_id = %tool_call_id,
                    "ToolOutput: no streaming Tool message found — skipping finalization"
                );
            }
            found
        };

        if let Some(pos) = pos {
            // Finalize existing streaming tool message (shell or native path with ToolStart).
            // Replace content after the header line ("$ cmd\n") with the canonical body_display
            // from ToolOutputEvent. Streaming chunks (Path B) may already occupy that space;
            // appending would duplicate the output. Truncating to the header and re-writing
            // body_display produces exactly one copy regardless of whether chunks arrived.
            debug!("finalizing existing streaming Tool message");
            let header_end = self.sessions.current_mut().messages[pos]
                .content
                .find('\n')
                .map_or(0, |i| i + 1);
            self.sessions.current_mut().messages[pos]
                .content
                .truncate(header_end);
            self.sessions.current_mut().messages[pos]
                .content
                .push_str(&output);
            self.sessions.current_mut().messages[pos].streaming = false;
            self.sessions.current_mut().messages[pos].diff_data = diff;
            self.sessions.current_mut().messages[pos].filter_stats = filter_stats;
            self.sessions.current_mut().messages[pos].kept_lines = kept_lines;
            self.sessions.current_mut().messages[pos].success = Some(success);
            self.sessions.current_mut().render_cache.invalidate(pos);
        } else if diff.is_some() || filter_stats.is_some() || kept_lines.is_some() {
            // No prior ToolStart: create the message now (legacy fallback).
            debug!("creating new Tool message with diff (no prior ToolStart)");
            let mut msg = ChatMessage::new(MessageRole::Tool, output)
                .with_tool(tool_name)
                .with_tool_call_id(tool_call_id);
            msg.diff_data = diff;
            msg.filter_stats = filter_stats;
            msg.kept_lines = kept_lines;
            msg.success = Some(success);
            self.sessions.current_mut().messages.push(msg);
            self.trim_messages();
        } else if let Some(msg) = self
            .sessions
            .current_mut()
            .messages
            .iter_mut()
            .rev()
            .find(|m| m.role == MessageRole::Tool)
        {
            msg.filter_stats = filter_stats;
        }
        self.auto_scroll();
        self.maybe_flash_completed_group();
    }

    /// If the most recently completed tool message belongs to a fully-resolved group,
    /// trigger a completion flash for that group (#5104).
    ///
    /// Groups are defined as a contiguous run of [`MessageRole::Tool`] messages in the
    /// transcript. We scan backward from the last Tool message to find the group's
    /// `start_idx`, then verify that every message in the run is no longer streaming.
    fn maybe_flash_completed_group(&mut self) {
        if self.motion == zeph_config::Motion::Off || !self.delights.completion_flash {
            return;
        }

        let messages = &self.sessions.current().messages;

        // Find the last Tool message index.
        let Some(last_tool_pos) = messages.iter().rposition(|m| m.role == MessageRole::Tool) else {
            return;
        };

        // Walk backward to find the start of the contiguous Tool run.
        let mut start_idx = last_tool_pos;
        while start_idx > 0 && messages[start_idx - 1].role == MessageRole::Tool {
            start_idx -= 1;
        }

        // Check that every message in this run is finalized (not streaming).
        let all_done = messages[start_idx..=last_tool_pos]
            .iter()
            .all(|m| !m.streaming && m.success.is_some());
        if !all_done {
            return;
        }

        // Avoid re-flashing a group that already flashed this tick cycle.
        if self.sessions.current().flashed_groups.contains(&start_idx) {
            return;
        }

        let group_size = last_tool_pos - start_idx + 1;
        let now = self.anim_tick();
        self.sessions.current_mut().flashed_groups.insert(start_idx);
        self.sessions.current_mut().flash.insert(start_idx, now);

        // Show a transient success toast when the toasts delight is also enabled.
        if self.delights.toasts {
            let text = if group_size == 1 {
                "Tool done".to_owned()
            } else {
                format!("{group_size} tools done")
            };
            self.push_toast(text, crate::delights::ToastKind::Success);
        }
    }

    #[must_use]
    pub fn confirm_state(&self) -> Option<&ConfirmState> {
        self.confirm_state.as_ref()
    }
}

#[cfg(test)]
mod tests {
    use tokio::sync::mpsc;

    use crate::app::{AgentViewTarget, App};
    use crate::event::AgentEvent;
    use crate::types::{ChatMessage, MessageRole};
    use zeph_core::DiffData;

    fn make_app() -> App {
        let (user_tx, agent_rx) = {
            let (utx, _urx) = mpsc::channel(8);
            let (_atx, arx) = mpsc::channel(8);
            (utx, arx)
        };
        let mut app = App::new(user_tx, agent_rx);
        app.sessions.current_mut().messages.clear();
        app
    }

    /// Push a streaming Tool message with a specific `tool_call_id` directly onto the session.
    fn push_tool_msg(app: &mut App, id: &str) {
        let msg = ChatMessage::new(MessageRole::Tool, format!("$ cmd_{id}\n"))
            .streaming()
            .with_tool_call_id(id.to_owned());
        app.sessions.current_mut().messages.push(msg);
    }

    fn tool_msg(id: &str) -> ChatMessage {
        ChatMessage::new(MessageRole::Tool, "$ cmd\n".to_owned())
            .with_tool("bash".into())
            .with_tool_call_id(id.to_owned())
    }

    fn diff() -> DiffData {
        DiffData {
            file_path: "a.rs".into(),
            old_content: "old".into(),
            new_content: "new".into(),
        }
    }

    #[test]
    fn tool_output_chunk_routes_by_id_out_of_order() {
        let mut app = make_app();
        push_tool_msg(&mut app, "a");
        push_tool_msg(&mut app, "b");
        push_tool_msg(&mut app, "c");

        // Deliver chunks out of order: c, a, b, a, c
        for (id, chunk) in [
            ("c", "c1"),
            ("a", "a1"),
            ("b", "b1"),
            ("a", "a2"),
            ("c", "c2"),
        ] {
            app.handle_agent_event(AgentEvent::ToolOutputChunk {
                tool_name: "bash".into(),
                command: String::new(),
                chunk: chunk.to_owned(),
                tool_call_id: id.to_owned(),
            });
        }

        let msgs = app.messages();
        assert_eq!(msgs.len(), 3);
        // Message order: a=0, b=1, c=2
        assert_eq!(msgs[0].content, "$ cmd_a\na1a2");
        assert_eq!(msgs[1].content, "$ cmd_b\nb1");
        assert_eq!(msgs[2].content, "$ cmd_c\nc1c2");
    }

    #[test]
    fn tool_output_chunk_with_unknown_id_is_dropped() {
        let mut app = make_app();
        push_tool_msg(&mut app, "known");

        // Chunk for an id that has no matching message — must be silently dropped.
        app.handle_agent_event(AgentEvent::ToolOutputChunk {
            tool_name: "bash".into(),
            command: String::new(),
            chunk: "should-not-appear".to_owned(),
            tool_call_id: "unknown-xyz".to_owned(),
        });

        // The known message must be unchanged.
        assert_eq!(app.messages().len(), 1);
        assert_eq!(app.messages()[0].content, "$ cmd_known\n");
    }

    #[test]
    fn tool_output_finalizes_correct_message_by_id() {
        let mut app = make_app();
        push_tool_msg(&mut app, "t1");
        push_tool_msg(&mut app, "t2");

        // Finalize t1 with ToolOutput.
        app.handle_agent_event(AgentEvent::ToolOutput {
            tool_name: "bash".into(),
            command: "$ cmd_t1\n".into(),
            output: "final-output-t1".to_owned(),
            success: true,
            diff: None,
            filter_stats: None,
            kept_lines: None,
            tool_call_id: "t1".to_owned(),
        });

        let msgs = app.messages();
        assert_eq!(msgs.len(), 2);
        // t1 must be finalized (not streaming) with the canonical output.
        assert!(!msgs[0].streaming);
        assert!(msgs[0].content.contains("final-output-t1"));
        // t2 must still be streaming and unchanged.
        assert!(msgs[1].streaming);
        assert_eq!(msgs[1].content, "$ cmd_t2\n");
    }

    #[test]
    fn diff_ready_attaches_to_matching_id() {
        let mut app = make_app();
        app.sessions.current_mut().messages.push(tool_msg("call-1"));
        app.sessions.current_mut().messages.push(tool_msg("call-2"));

        app.handle_agent_event(AgentEvent::DiffReady {
            diff: diff(),
            tool_call_id: "call-2".into(),
        });

        assert!(app.sessions.current().messages[0].diff_data.is_none());
        assert!(app.sessions.current().messages[1].diff_data.is_some());
    }

    #[test]
    fn diff_ready_mismatched_id_does_not_attach() {
        let mut app = make_app();
        app.sessions.current_mut().messages.push(tool_msg("call-1"));

        app.handle_agent_event(AgentEvent::DiffReady {
            diff: diff(),
            tool_call_id: "call-99".into(),
        });

        assert!(app.sessions.current().messages[0].diff_data.is_none());
    }

    #[test]
    fn diff_ready_empty_id_does_not_attach() {
        let mut app = make_app();
        app.sessions.current_mut().messages.push(tool_msg("call-1"));

        app.handle_agent_event(AgentEvent::DiffReady {
            diff: diff(),
            tool_call_id: String::new(),
        });

        assert!(app.sessions.current().messages[0].diff_data.is_none());
    }

    #[test]
    fn diff_ready_two_concurrent_attach_to_correct_messages() {
        let mut app = make_app();
        app.sessions.current_mut().messages.push(tool_msg("call-A"));
        app.sessions.current_mut().messages.push(tool_msg("call-B"));
        app.sessions.current_mut().messages.push(tool_msg("call-C"));

        let diff_a = DiffData {
            file_path: "a.rs".into(),
            old_content: "old_a".into(),
            new_content: "new_a".into(),
        };
        let diff_b = DiffData {
            file_path: "b.rs".into(),
            old_content: "old_b".into(),
            new_content: "new_b".into(),
        };

        // Deliver out of order: B first, then A
        app.handle_agent_event(AgentEvent::DiffReady {
            diff: diff_b,
            tool_call_id: "call-B".into(),
        });
        app.handle_agent_event(AgentEvent::DiffReady {
            diff: diff_a,
            tool_call_id: "call-A".into(),
        });

        let msgs = &app.sessions.current().messages;
        assert_eq!(
            msgs[0].diff_data.as_ref().map(|d| d.file_path.as_str()),
            Some("a.rs"),
            "call-A diff must attach to message 0"
        );
        assert_eq!(
            msgs[1].diff_data.as_ref().map(|d| d.file_path.as_str()),
            Some("b.rs"),
            "call-B diff must attach to message 1"
        );
        assert!(
            msgs[2].diff_data.is_none(),
            "call-C must remain without diff"
        );
    }

    #[test]
    fn foreground_subagent_started_switches_view_to_subagent() {
        let mut app = make_app();
        assert!(app.sessions.current().view_target.is_main());

        app.handle_agent_event(AgentEvent::ForegroundSubagentStarted {
            id: "sa-001".into(),
            name: "planner".into(),
        });

        assert_eq!(
            app.sessions.current().view_target.subagent_id(),
            Some("sa-001"),
            "view must switch to the started subagent"
        );
        assert_eq!(
            app.sessions.current().status_label.as_deref(),
            Some("Sub-agent 'planner' running...")
        );
    }

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

        app.handle_agent_event(AgentEvent::ForegroundSubagentStarted {
            id: "sa-002".into(),
            name: "coder".into(),
        });
        assert_eq!(
            app.sessions.current().view_target.subagent_id(),
            Some("sa-002")
        );

        app.handle_agent_event(AgentEvent::ForegroundSubagentCompleted {
            id: "sa-002".into(),
            name: "coder".into(),
            success: true,
        });

        assert!(
            app.sessions.current().view_target.is_main(),
            "view must return to Main after completion"
        );
        assert_eq!(
            app.sessions.current().status_label.as_deref(),
            Some("Sub-agent 'coder' completed")
        );
        let system_msg = app
            .sessions
            .current()
            .messages
            .iter()
            .find(|m| m.role == MessageRole::System);
        assert!(
            system_msg.is_some(),
            "completion system message must be pushed"
        );
    }

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

        app.handle_agent_event(AgentEvent::ForegroundSubagentStarted {
            id: "sa-003".into(),
            name: "researcher".into(),
        });

        // Simulate user manually navigating away to a different subagent.
        app.set_view_target(AgentViewTarget::SubAgent {
            id: "sa-other".into(),
            name: "other".into(),
        });

        app.handle_agent_event(AgentEvent::ForegroundSubagentCompleted {
            id: "sa-003".into(),
            name: "researcher".into(),
            success: false,
        });

        // View must NOT switch to Main because user is viewing a different subagent.
        assert_eq!(
            app.sessions.current().view_target.subagent_id(),
            Some("sa-other"),
            "user's manual navigation must be preserved"
        );
    }

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

        app.handle_agent_event(AgentEvent::ForegroundSubagentStarted {
            id: "sa-004".into(),
            name: "builder".into(),
        });
        app.handle_agent_event(AgentEvent::ForegroundSubagentCompleted {
            id: "sa-004".into(),
            name: "builder".into(),
            success: false,
        });

        assert_eq!(
            app.sessions.current().status_label.as_deref(),
            Some("Sub-agent 'builder' failed")
        );
    }

    // Fast-completing subagents cause a Started then immediately Completed event.
    // This results in a brief flash before returning to Main, which is acceptable.
    #[test]
    fn foreground_subagent_fast_complete_ends_on_main() {
        let mut app = make_app();

        app.handle_agent_event(AgentEvent::ForegroundSubagentStarted {
            id: "sa-fast".into(),
            name: "quick".into(),
        });
        app.handle_agent_event(AgentEvent::ForegroundSubagentCompleted {
            id: "sa-fast".into(),
            name: "quick".into(),
            success: true,
        });

        assert!(app.sessions.current().view_target.is_main());
    }

    // ── #6570 background subagent completion while manually viewed via sidebar ─────────

    #[test]
    fn background_subagent_completed_switches_back_when_viewing_subagent() {
        // Reproduces the stuck-transcript bug: a background subagent (`/agent bg`) is
        // manually opened via the sidebar's Enter action (set_view_target, not the
        // ForegroundSubagentStarted event), then finishes. Before #6570, nothing ever told
        // the TUI the viewed subagent had reached a terminal state — maybe_reload_transcript
        // relies on `metrics.sub_agents`, which the manager empties synchronously at
        // completion (SubAgentManager::collect), so the transcript pane was left frozen
        // forever with no completion notice or reset to Main.
        let mut app = make_app();
        app.set_view_target(AgentViewTarget::SubAgent {
            id: "sa-bg-1".into(),
            name: "researcher".into(),
        });
        assert_eq!(
            app.sessions.current().view_target.subagent_id(),
            Some("sa-bg-1")
        );

        app.handle_agent_event(AgentEvent::BackgroundSubagentCompleted {
            id: "sa-bg-1".into(),
            name: "researcher".into(),
            success: true,
        });

        assert!(
            app.sessions.current().view_target.is_main(),
            "view must return to Main once the manually-viewed background subagent completes"
        );
        assert_eq!(
            app.sessions.current().status_label.as_deref(),
            Some("Sub-agent 'researcher' completed")
        );
        let system_msg = app
            .sessions
            .current()
            .messages
            .iter()
            .find(|m| m.role == MessageRole::System);
        assert!(
            system_msg.is_some(),
            "a terminal completion marker must be pushed into the chat"
        );
    }

    #[test]
    fn background_subagent_completed_shows_failed_label_when_viewing_subagent() {
        let mut app = make_app();
        app.set_view_target(AgentViewTarget::SubAgent {
            id: "sa-bg-2".into(),
            name: "worker".into(),
        });

        app.handle_agent_event(AgentEvent::BackgroundSubagentCompleted {
            id: "sa-bg-2".into(),
            name: "worker".into(),
            success: false,
        });

        assert!(app.sessions.current().view_target.is_main());
        assert_eq!(
            app.sessions.current().status_label.as_deref(),
            Some("Sub-agent 'worker' failed")
        );
    }

    #[test]
    fn background_subagent_completed_ignored_when_not_viewing_that_subagent() {
        // A background subagent completing while the user is looking at Main (or a
        // different subagent) must not interrupt the current view — its plain-text
        // completion notice is already delivered to Main chat separately via
        // `Channel::send` in `notify_completed_subagents`; this event must be a no-op here.
        let mut app = make_app();
        assert!(app.sessions.current().view_target.is_main());
        let messages_before = app.sessions.current().messages.len();

        app.handle_agent_event(AgentEvent::BackgroundSubagentCompleted {
            id: "sa-bg-elsewhere".into(),
            name: "other".into(),
            success: true,
        });

        assert!(app.sessions.current().view_target.is_main());
        assert_eq!(
            app.sessions.current().messages.len(),
            messages_before,
            "no message should be pushed for a background subagent that isn't being viewed"
        );
        assert_eq!(app.sessions.current().status_label, None);
    }

    #[test]
    fn background_subagent_completed_respects_different_subagent_being_viewed() {
        let mut app = make_app();
        app.set_view_target(AgentViewTarget::SubAgent {
            id: "sa-other".into(),
            name: "other".into(),
        });

        app.handle_agent_event(AgentEvent::BackgroundSubagentCompleted {
            id: "sa-bg-3".into(),
            name: "worker".into(),
            success: true,
        });

        assert_eq!(
            app.sessions.current().view_target.subagent_id(),
            Some("sa-other"),
            "viewing a different subagent must not be disturbed by an unrelated completion"
        );
    }

    #[test]
    fn context_estimate_updates_cached_value() {
        let mut app = make_app();
        assert_eq!(
            app.context_token_estimate(),
            0,
            "initial estimate must be 0"
        );

        app.handle_agent_event(AgentEvent::ContextEstimate(14_200));
        assert_eq!(app.context_token_estimate(), 14_200);

        app.handle_agent_event(AgentEvent::ContextEstimate(512));
        assert_eq!(
            app.context_token_estimate(),
            512,
            "estimate must update on each event"
        );
    }
}