Skip to content

armgit / agtx

Public Imported from GitHub
0

🏄🏼‍♂️ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.

618 KB
Raw Blame
use anyhow::Result;
use crossterm::{
    event::{DisableBracketedPaste, EnableBracketedPaste, Event, KeyCode, KeyEventKind},
    execute,
    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
};
use ratatui::{prelude::*, widgets::*};
use std::cell::Cell;
use std::collections::{HashMap, HashSet, VecDeque};
use std::io::{self, Stdout};
use std::path::{Path, PathBuf};
use std::sync::{
    atomic::{AtomicBool, Ordering},
    mpsc, Arc, Condvar, Mutex,
};
use std::time::Instant;

use crate::agent::hook_status::{self, HookState};
use crate::agent::{self, AgentOperations};
use crate::config::{GlobalConfig, MergedConfig, ProjectConfig, ThemeConfig, WorkflowPlugin};
use crate::core::input::{
    composer_holds, delivery_needle, pane_shows, submit_message, COMPOSER_TAIL_LINES,
    SUBMIT_ATTEMPTS, SUBMIT_CONFIRM_POLLS,
};
use crate::db::{Database, PhaseStatus, Task, TaskStatus, TransitionRequest};
use crate::git::{
    self, GitOperations, GitProviderOperations, PullRequestState, RealGitHubOps, RealGitOps,
};
use crate::skills;
use crate::tmux::{
    self, pane_tail, InputConfig, InputError, PaneInput, PaneInputSink, RealTmuxOps,
    TmuxOperations,
};
use crate::AppMode;

use super::board::BoardState;
use super::config_editor::{ConfigEditor, EditorAction, FieldKind};
use super::help;
use super::shell_popup::{self, ShellPopup};
use super::text_input::TextInput;
use super::theme::TuiStyles;
use super::wizard::{PickOption, WizardState, WizardStep};

/// Helper to convert hex color string to ratatui Color
fn hex_to_color(hex: &str) -> Color {
    ThemeConfig::parse_hex(hex)
        .map(|(r, g, b)| Color::Rgb(r, g, b))
        .unwrap_or(Color::White)
}

/// Build footer help text based on current UI state
fn build_footer_text(
    wizard_step: Option<WizardStep>,
    sidebar_focused: bool,
    selected_column: usize,
    has_cyclic_plugin: bool,
    fullscreen_on_enter: bool,
) -> String {
    // Only the column-specific actions plus the two universal ones; the `?`
    // overlay carries the full list. One line has to survive a narrow terminal,
    // and a truncated footer silently hides whatever comes last.
    match wizard_step {
        None => {
            if sidebar_focused {
                "[j/k] navigate  [Enter] board  ·  [e] hide  [?] help  [q] quit".to_string()
            } else {
                let fullscreen = if fullscreen_on_enter {
                    ""
                } else {
                    "  [C-f] fullscreen"
                };
                match selected_column {
                    0 => "[o] new  [Enter] edit  [d] diff  ·  [m] plan  [M] run  [R] research  ·  [?] help  [q] quit".to_string(),
                    1 => format!("[o] new  [Enter] open{fullscreen}  [d] diff  ·  [m] run  ·  [?] help  [q] quit"),
                    2 => format!("[o] new  [Enter] open{fullscreen}  [d] diff  ·  [r] back  [m] move  ·  [?] help  [q] quit"),
                    3 if has_cyclic_plugin => format!(
                        "[o] new  [Enter] open{fullscreen}  ·  [r] resume  [p] next phase  [m] done  ·  [?] help  [q] quit"
                    ),
                    3 => format!("[o] new  [Enter] open{fullscreen}  [d] diff  ·  [r] back  [m] move  ·  [?] help  [q] quit"),
                    _ => "[o] new  [Enter] open  [x] delete  ·  [?] help  [q] quit".to_string(),
                }
            }
        }
        // Every step advertises how to leave it in both directions. `Esc` is
        // the back key now, and only cancels from the first step — which is
        // why the first step says "cancel" and the others say "back".
        Some(WizardStep::Title) => {
            " Enter task title...  [Enter] next  [C-s] save  [Esc] cancel ".to_string()
        }
        Some(WizardStep::Agent) | Some(WizardStep::Plugin) => {
            " [j/k] select  [/] filter  [Enter] next  [S-Tab] back  [C-s] save  [Esc] cancel "
                .to_string()
        }
        Some(WizardStep::Prompt) => {
            " [#] files  [/] skills  [!] tasks  ·  [\\+Enter] newline  [S-Tab] back  [Enter] save  [Esc] cancel "
                .to_string()
        }
    }
}

/// Turn the existing contextual help string into modern keycap/value spans.
/// Keeping `build_footer_text` as the source preserves its tested behavior.
fn styled_footer(text: &str, styles: TuiStyles) -> Line<'static> {
    let mut spans = Vec::new();
    let mut rest = text.trim();
    while let Some(open) = rest.find('[') {
        if open > 0 {
            spans.push(Span::styled(rest[..open].to_string(), styles.muted()));
        }
        let Some(close) = rest[open..].find(']') else {
            spans.push(Span::styled(rest[open..].to_string(), styles.muted()));
            rest = "";
            break;
        };
        let end = open + close + 1;
        spans.push(Span::styled(rest[open..end].to_string(), styles.keycap()));
        rest = &rest[end..];
    }
    if !rest.is_empty() {
        spans.push(Span::styled(rest.to_string(), styles.muted()));
    }
    Line::from(spans)
}

fn visible_column_range(selected: usize, width: u16) -> std::ops::Range<usize> {
    let visible = if width >= 140 {
        5
    } else if width >= 96 {
        3
    } else {
        2
    };
    let start = selected
        .saturating_sub(visible / 2)
        .min(5usize.saturating_sub(visible));
    start..start + visible
}

/// Terminal cells are typically about twice as tall as they are wide, so a
/// card needs roughly half as many rows as columns to look visually square.
/// Bounds keep narrow cards usable and very wide cards from dominating the board.
fn card_height_for_width(card_width: u16) -> u16 {
    (card_width / 2).clamp(6, 12)
}

fn board_scrollbar_metrics(
    total_items: usize,
    visible_items: usize,
    scroll_offset: usize,
    track_height: usize,
) -> Option<(usize, usize)> {
    if track_height == 0 || total_items <= visible_items || visible_items == 0 {
        return None;
    }

    let min_thumb_height = track_height.min(2);
    let thumb_height = (visible_items * track_height / total_items)
        .max(min_thumb_height)
        .min(track_height);
    let max_thumb_pos = track_height.saturating_sub(thumb_height);
    let max_scroll_offset = total_items.saturating_sub(visible_items);
    let thumb_pos = scroll_offset.min(max_scroll_offset) * max_thumb_pos / max_scroll_offset;

    Some((thumb_pos, thumb_height))
}

type Terminal = ratatui::Terminal<AppBackend>;

/// Backend abstraction: real CrosstermBackend in production, TestBackend in tests.
enum AppBackend {
    Crossterm(CrosstermBackend<Stdout>),
    #[cfg(feature = "test-mocks")]
    Test(ratatui::backend::TestBackend),
}

impl ratatui::backend::Backend for AppBackend {
    type Error = io::Error;

    fn draw<'a, I>(&mut self, content: I) -> io::Result<()>
    where
        I: Iterator<Item = (u16, u16, &'a ratatui::buffer::Cell)>,
    {
        match self {
            Self::Crossterm(b) => b.draw(content),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .draw(content)
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn hide_cursor(&mut self) -> io::Result<()> {
        match self {
            Self::Crossterm(b) => b.hide_cursor(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .hide_cursor()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn show_cursor(&mut self) -> io::Result<()> {
        match self {
            Self::Crossterm(b) => b.show_cursor(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .show_cursor()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn get_cursor_position(&mut self) -> io::Result<ratatui::layout::Position> {
        match self {
            Self::Crossterm(b) => b.get_cursor_position(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .get_cursor_position()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn set_cursor_position<P: Into<ratatui::layout::Position>>(
        &mut self,
        position: P,
    ) -> io::Result<()> {
        match self {
            Self::Crossterm(b) => b.set_cursor_position(position),
            // TestBackend's set_cursor_position is also generic, so just forward
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .set_cursor_position(position)
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn clear(&mut self) -> io::Result<()> {
        match self {
            Self::Crossterm(b) => b.clear(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .clear()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn clear_region(&mut self, clear_type: ratatui::backend::ClearType) -> io::Result<()> {
        match self {
            Self::Crossterm(b) => b.clear_region(clear_type),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .clear_region(clear_type)
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn size(&self) -> io::Result<ratatui::layout::Size> {
        match self {
            Self::Crossterm(b) => b.size(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .size()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn window_size(&mut self) -> io::Result<ratatui::backend::WindowSize> {
        match self {
            Self::Crossterm(b) => b.window_size(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .window_size()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }

    fn flush(&mut self) -> io::Result<()> {
        match self {
            Self::Crossterm(b) => b.flush(),
            #[cfg(feature = "test-mocks")]
            Self::Test(b) => b
                .flush()
                .map_err(|e| io::Error::new(io::ErrorKind::Other, e)),
        }
    }
}

/// Shell popup dimensions - used for both rendering and tmux window sizing
/// Horizontal breathing room inside the task wizard, in cells per side.
///
/// Without it a wrapped prompt line starts hard against the left border and
/// every line ends hard against the right one. The literals below therefore
/// carry no leading spaces of their own — the padding is the only indent, so
/// wrapped continuation rows line up with the row they came from.
const WIZARD_PADDING: u16 = 2;

/// Longest task title the wizard accepts.
///
/// Not a database limit — the board draws a title on one card line, and a title
/// long enough to be truncated everywhere it appears is not a useful name.
const MAX_TASK_TITLE_CHARS: usize = 120;

const SHELL_POPUP_WIDTH: u16 = 128; // Total width including borders
const SHELL_POPUP_CONTENT_WIDTH: u16 = 126; // Content width (SHELL_POPUP_WIDTH - 2 for borders)
const SHELL_POPUP_HEIGHT_PERCENT: u16 = 75; // Percentage of terminal height

/// Application state (separate from terminal for borrow checker)
struct AppState {
    mode: AppMode,
    flags: crate::FeatureFlags,
    should_quit: bool,
    board: BoardState,
    /// The task creation / edit wizard, open or not. `Some` *is* the input
    /// mode: there is no second flag that could disagree with it.
    wizard: Option<WizardState>,
    /// The config editor, open or not. See `tui::config_editor`.
    config_editor: Option<ConfigEditor>,
    /// The `?` overlay's scroll offset, when it is open. See `tui::help`.
    help_scroll: Option<usize>,
    /// The furthest the overlay can actually scroll, recorded by the renderer
    /// because only it knows how many rows fit.
    ///
    /// Without it the handler clamps to the *table* length instead, so `C-g`
    /// parks the offset far past the last screenful and the next `C-u` moves
    /// nothing — which reads exactly like a broken scroll.
    help_max_scroll: Cell<usize>,
    /// The agent the open wizard's plugin list was filtered by, so a change on
    /// the agent step can rebuild it and nothing else has to.
    plugins_filtered_for: Option<String>,
    db: Option<Database>,
    #[allow(dead_code)]
    global_db: Database,
    config: MergedConfig,
    project_path: Option<PathBuf>,
    project_name: String,
    tmux_project_name: String,
    available_agents: Vec<agent::Agent>,
    // Tmux operations (injectable for testing)
    tmux_ops: Arc<dyn TmuxOperations>,
    // Popup keystrokes go here, never straight to tmux: enqueueing is the only
    // thing the input thread is allowed to do with a key. See `tmux::input`.
    input_sink: Arc<dyn PaneInputSink>,
    // Git operations (injectable for testing)
    git_ops: Arc<dyn git::GitOperations>,
    // Git provider operations (injectable for testing)
    git_provider_ops: Arc<dyn GitProviderOperations>,
    // Agent registry (injectable for testing)
    agent_registry: Arc<dyn agent::AgentRegistry>,
    // Sidebar
    sidebar_visible: bool,
    sidebar_focused: bool,
    projects: Vec<ProjectInfo>,
    selected_project: usize,
    // Dashboard state
    show_project_list: bool,
    // Task shell popup
    shell_popup: Option<ShellPopup>,
    // File search dropdown
    file_search: Option<FileSearchState>,
    // Skill search dropdown
    skill_search: Option<SkillSearchState>,
    // Task reference search dropdown
    task_ref_search: Option<TaskRefSearchState>,
    // Task search popup
    task_search: Option<TaskSearchState>,
    // PR creation confirmation popup
    pr_confirm_popup: Option<PrConfirmPopup>,
    // Moving Review back to Running
    review_to_running_task_id: Option<String>,
    // Git diff popup
    diff_popup: Option<DiffPopup>,
    // Channel for receiving PR description generation results
    pr_generation_rx: Option<mpsc::Receiver<(String, String)>>,
    // PR creation status popup
    pr_status_popup: Option<PrStatusPopup>,
    // Channel for receiving PR creation results
    pr_creation_rx: Option<mpsc::Receiver<Result<(i32, String), String>>>,
    // Confirmation popup for moving to Done with open PR
    done_confirm_popup: Option<DoneConfirmPopup>,
    // Confirmation popup for moving task when phase is incomplete
    move_confirm_popup: Option<MoveConfirmPopup>,
    // Flag to skip move confirmation (set after user confirms popup)
    skip_move_confirm: bool,
    // Confirmation popup for deleting a task
    delete_confirm_popup: Option<DeleteConfirmPopup>,
    // Confirmation popup for asking if user wants to create PR when moving to Review
    review_confirm_popup: Option<ReviewConfirmPopup>,
    // Trust-on-first-use confirmation popup
    trust_confirm_popup: Option<TrustConfirmPopup>,
    // Channel for receiving background worktree setup results
    setup_rx: Option<mpsc::Receiver<SetupResult>>,
    // Phase detection
    phase_status_cache: HashMap<String, (PhaseStatus, Instant)>,
    /// Paces the MCP transition-queue read, which is a SQLite query.
    last_transition_poll: Instant,
    /// Raised by the control connection when tmux reports a window closing.
    window_events: Arc<AtomicBool>,
    // Idle detection: (content_hash, last_change_time) per task
    pane_content_hashes: HashMap<String, (u64, Instant)>,
    /// Why a task is Blocked, as reported by its agent's hook payload.
    blocked_reasons: HashMap<String, String>,
    /// Tasks whose agent is parked on a trust / permission prompt agtx declined to
    /// answer. Kept apart from `blocked_reasons` because the orchestrator must
    /// treat these differently: a nudge would be typed straight into the dialog.
    trust_blocked: HashSet<String>,
    // Guard: task IDs for which merge-conflict check has already been performed
    merge_conflict_checked: HashSet<String>,
    // Guard: task IDs for which stuck-task notification has been fired (reset on phase advance)
    stuck_task_notified: HashSet<String>,
    // When each task first became Idle (for stuck-task detection)
    stuck_task_idle_since: HashMap<String, Instant>,
    cached_plugin: Option<Option<WorkflowPlugin>>,
    // Transient warning message shown in footer (auto-clears after a few seconds)
    warning_message: Option<(String, Instant)>,
    // Plugin selection popup
    plugin_select_popup: Option<PluginSelectPopup>,
    // Orchestrator agent tmux target (e.g. "project:orchestrator")
    orchestrator_session: Option<String>,
    // Set to true once the orchestrator agent is ready and has received the skill command.
    // Gates notification delivery so we don't send into a pane that's still initializing.
    orchestrator_ready: Arc<AtomicBool>,
    // Orchestrator idle detection for push notifications
    orchestrator_last_content: String,
    orchestrator_stable_since: Option<Instant>,
    orchestrator_last_check: Instant,
    // Background session refresh channel (non-blocking phase status polling)
    session_refresh_rx: Option<mpsc::Receiver<SessionRefreshResult>>,
    // Release check: spawned once at startup, consumed non-blocking like the
    // session refresh above. `None` in the receiver means "no newer release" —
    // every failure (offline, no curl, rate limit) arrives that way too, so a
    // missing notice is the only symptom a broken check can have.
    update_rx: Option<mpsc::Receiver<Option<crate::update::UpdateInfo>>>,
    update_available: Option<crate::update::UpdateInfo>,
    // Update popup ([u]) and the background install it can start
    update_popup: Option<UpdatePopup>,
    update_install_rx: Option<mpsc::Receiver<Result<String, String>>>,
    // Cache of dependency satisfaction per task ID (refreshed with tasks)
    deps_satisfied_cache: HashMap<String, bool>,
    // Full-screen dependency-graph overlay (Shift+D)
    dep_graph_popup: Option<DepGraphPopup>,
    /// The `W` overlay: serve the board to a phone, and manage paired devices.
    mobile_popup: Option<crate::tui::serve_control::MobilePopup>,
    /// The child `agtx serve`, if one is running.
    ///
    /// Held here and **not on the popup**, because the popup is a view that is
    /// dropped whenever the overlay closes — and dropping a `ServeSession`
    /// kills the child. Someone opens `W`, scans, closes it, and carries on
    /// using the board; the server has to survive that.
    serve_session: Option<crate::tui::serve_control::ServeSession>,
    // Tasks awaiting serialized worktree setup, with what each was asked to do.
    // Worktree setup runs one-at-a-time via `setup_rx`; this queue is drained as
    // each setup completes. Fed by the dependency view's batch move and by MCP
    // transition requests, which is why the intent travels with the id: those
    // two disagree about where a Backlog task should land.
    setup_queue: VecDeque<QueuedSetup>,
    instance_id: String,
}

/// Where a queued Backlog task should go once a setup slot frees up.
///
/// The dependency overlay and the MCP queue want different things from the same
/// mechanism: the overlay moves whatever the user marked and lets each task's
/// plugin decide between research and planning, while an MCP request names one
/// transition and must not be answered with a different one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SetupIntent {
    /// Research if the task's plugin defines a research command, else planning.
    PluginDefault,
    Research,
    Planning,
    Running,
}

/// A task waiting for the single worktree-setup slot.
#[derive(Debug, Clone)]
struct QueuedSetup {
    task_id: String,
    intent: SetupIntent,
    /// The MCP transition request this came from, if any. It stays claimed and
    /// unprocessed — so `get_transition_status` reports `pending` — until the
    /// drain either starts the setup or gives up on it. Marking it completed at
    /// enqueue time would tell a caller the task had moved while it was still
    /// sitting in a queue.
    request_id: Option<String>,
}

/// What `execute_transition_request` did with a request.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TransitionOutcome {
    /// Handled now; the caller marks it processed.
    Applied,
    /// Waiting for the setup slot. The drain owns marking it from here.
    Queued,
}

/// State for the dependency-graph overlay.
struct DepGraphPopup {
    graph: crate::tui::dep_graph::DepGraph,
    /// Cursor index into `graph.nodes`.
    selected: usize,
    /// Task IDs marked for batch-move (only unblocked nodes are markable).
    marked: HashSet<String>,
    /// Horizontal scroll offset, in levels (columns), for wide graphs. Owned and
    /// corrected by the draw pass each frame so the selected node stays on
    /// screen; the key handler only moves `selected` and lets render re-clamp.
    scroll_levels: Cell<usize>,
    /// Number of level-columns that fit on screen, recorded by the last draw.
    /// Used only for the footer hint. Starts at 1, corrected on first render.
    visible_levels: Cell<usize>,
}

/// State for confirming move to Done
#[derive(Debug, Clone)]
struct DoneConfirmPopup {
    task_id: String,
    pr_number: i32,
    pr_state: DoneConfirmPrState,
}

#[derive(Debug, Clone)]
enum DoneConfirmPrState {
    Open,
    Merged,
    Closed,
    UncommittedChanges,
    Unknown,
}

/// State for confirming move when phase is incomplete (agent still working)
#[derive(Debug, Clone)]
struct MoveConfirmPopup {
    task_id: String,
    from_status: TaskStatus,
    to_status: TaskStatus,
}

/// Result from background worktree setup (research, planning, move-to-running)
struct SetupResult {
    task_id: String,
    session_name: String,
    worktree_path: String,
    branch_name: String,
    new_status: Option<TaskStatus>,
    agent: String,
    plugin: Option<String>,
    error: Option<String>,
}

/// Pre-fetched info about a referenced task for worktree setup (avoids DB access in thread).
#[derive(Debug, Clone)]
struct ReferencedTaskInfo {
    slug: String,
    branch_name: Option<String>,
    worktree_path: Option<String>,
}

/// The card / notification text for a task parked on a security prompt.
///
/// Names the agent and the action, because the fix is not something agtx can do:
/// the user answers in the agent's own pane, or trusts the project once and every
/// later worktree inherits it.
fn trust_blocked_reason(agent: &str, dialog: &str) -> String {
    format!(
        "{agent} is waiting on a trust prompt (\"{dialog}\") — answer it in the pane, \
         or run {agent} once in the project root and confirm there"
    )
}

/// Per-task result from the background session refresh thread.
struct SessionTaskStatus {
    task_id: String,
    phase_status: PhaseStatus,
    /// Content hash from tmux capture (for idle detection on main thread).
    content_hash: Option<u64>,
    /// Task status (needed for merge-conflict check on main thread).
    status: TaskStatus,
    /// Worktree path (needed for merge-conflict check).
    worktree_path: Option<String>,
    /// Tmux session name (needed for merge-conflict check).
    session_name: Option<String>,
    /// Agent name (needed for merge-conflict skill dispatch).
    agent: String,
    /// Whether this task was already Ready before this refresh cycle.
    was_ready: bool,
    /// The agent's own report of its state, when it writes one.
    hook_status: Option<hook_status::AgentHookStatus>,
    /// Set when the pane is showing a trust / permission prompt that agtx is
    /// deliberately not answering (`auto_trust = false`). The task is waiting on a
    /// person, not on the agent, so it reads as `Blocked` rather than `Working`.
    awaiting_trust: Option<String>,
}

/// Results sent back from the background session refresh thread.
struct SessionRefreshResult {
    statuses: Vec<SessionTaskStatus>,
}

/// State for PR creation status popup (loading/success/error)
#[derive(Debug, Clone)]
struct PrStatusPopup {
    status: PrCreationStatus,
    pr_url: Option<String>,
    error_message: Option<String>,
}

#[derive(Debug, Clone, PartialEq)]
enum PrCreationStatus {
    Creating,
    Pushing, // Pushing to existing PR
    Success,
    Error,
}

/// State for git diff popup
#[derive(Debug, Clone)]
struct DiffPopup {
    task_title: String,
    diff_content: String,
    scroll_offset: usize,
}

/// State for task search popup
#[derive(Debug, Clone)]
struct TaskSearchState {
    query: String,
    matches: Vec<(String, String, TaskStatus)>, // (id, title, status)
    selected: usize,
}

/// State for PR creation confirmation popup
#[derive(Debug, Clone)]
struct PrConfirmPopup {
    task_id: String,
    pr_title: String,
    pr_body: String,
    editing_title: bool, // true = editing title, false = editing body
    generating: bool,    // true while agent is generating description
}

/// Info about a project for the sidebar
#[derive(Debug, Clone)]
struct ProjectInfo {
    name: String,
    path: String,
}

/// State for file search dropdown
#[derive(Debug, Clone)]
struct FileSearchState {
    pattern: String,
    matches: Vec<String>,
    selected: usize,
    start_pos: usize,   // Position in the input buffer where trigger was typed
    trigger_char: char, // The character that triggered the search (# or @)
}

/// A discovered skill command from an agent's native directory
#[derive(Debug, Clone)]
struct SkillEntry {
    command: String,     // agent-native: "/agtx:plan" or "$agtx-plan"
    description: String, // from frontmatter or file stem
}

/// State for skill search dropdown (triggered by `/`)
#[derive(Debug, Clone)]
struct SkillSearchState {
    pattern: String,
    matches: Vec<SkillEntry>,
    all_skills: Vec<SkillEntry>, // cached full list for re-filtering
    selected: usize,
    start_pos: usize, // cursor position where `/` was typed
}

/// State for task reference search dropdown (triggered by `!`)
#[derive(Debug, Clone)]
struct TaskRefSearchState {
    pattern: String,
    matches: Vec<(String, String, TaskStatus)>, // (id, title, status)
    selected: usize,
    start_pos: usize, // cursor position where `!` was typed
}

/// The list behaviour shared by the three prompt dropdowns.
///
/// All of them are a match list with a cursor, and all of them are driven by
/// the same four keys — the only thing that differs is what a match *is*.
trait SearchList {
    fn match_count(&self) -> usize;
    fn selected_index(&mut self) -> &mut usize;

    fn select_prev(&mut self) {
        let selected = self.selected_index();
        *selected = selected.saturating_sub(1);
    }

    fn select_next(&mut self) {
        let last = self.match_count().saturating_sub(1);
        let selected = self.selected_index();
        if *selected < last {
            *selected += 1;
        }
    }
}

impl SearchList for FileSearchState {
    fn match_count(&self) -> usize {
        self.matches.len()
    }
    fn selected_index(&mut self) -> &mut usize {
        &mut self.selected
    }
}

impl SearchList for SkillSearchState {
    fn match_count(&self) -> usize {
        self.matches.len()
    }
    fn selected_index(&mut self) -> &mut usize {
        &mut self.selected
    }
}

impl SearchList for TaskRefSearchState {
    fn match_count(&self) -> usize {
        self.matches.len()
    }
    fn selected_index(&mut self) -> &mut usize {
        &mut self.selected
    }
}

/// State for delete confirmation popup
#[derive(Debug, Clone)]
struct DeleteConfirmPopup {
    task_id: String,
    task_title: String,
}

/// State for trust-on-first-use confirmation popup
#[derive(Debug, Clone)]
struct TrustConfirmPopup {
    project_path: std::path::PathBuf,
    /// The suppressed fields, verbatim.
    ///
    /// `App::new` strips these before anything can run them, so the popup
    /// re-reads the file to show them: consenting to a script you cannot see is
    /// not consent. Each entry is (field name, value).
    dangerous: Vec<(&'static str, String)>,
}

/// State for asking if user wants to create PR when moving to Review
#[derive(Debug, Clone)]
struct ReviewConfirmPopup {
    task_id: String,
    task_title: String,
}

/// State for plugin selection popup
#[derive(Debug, Clone)]
struct PluginSelectPopup {
    selected: usize,
    options: Vec<PickOption>,
}

/// The `[u]` popup: what is available, and one key to install it.
#[derive(Debug, Clone)]
struct UpdatePopup {
    info: crate::update::UpdateInfo,
    /// The last line `install_release` reported, or the final outcome. The
    /// install runs on a background thread; this is the only thing the draw
    /// path reads.
    status: Option<String>,
    installing: bool,
}

impl AppState {
    /// Which wizard step is open, if any. The one place anything outside the
    /// wizard asks about input mode.
    fn wizard_step(&self) -> Option<WizardStep> {
        self.wizard.as_ref().map(|w| w.step())
    }
}

pub struct App {
    terminal: Terminal,
    state: AppState,
}

impl App {
    pub fn new(mode: AppMode, flags: crate::FeatureFlags) -> Result<Self> {
        Self::with_ops(
            mode,
            flags,
            Arc::new(RealTmuxOps),
            Arc::new(RealGitOps),
            Arc::new(RealGitHubOps),
            Arc::new(agent::RealAgentRegistry::new("claude")),
        )
    }

    pub fn with_ops(
        mode: AppMode,
        flags: crate::FeatureFlags,
        tmux_ops: Arc<dyn TmuxOperations>,
        git_ops: Arc<dyn GitOperations>,
        git_provider_ops: Arc<dyn GitProviderOperations>,
        agent_registry: Arc<dyn agent::AgentRegistry>,
    ) -> Result<Self> {
        // Setup terminal
        enable_raw_mode()?;
        let mut stdout = io::stdout();
        execute!(stdout, EnterAlternateScreen, EnableBracketedPaste)?;
        // No Kitty-keyboard-protocol push here, deliberately. It was added so
        // `Shift+Enter` could be told apart from `Enter` — both are a bare CR
        // otherwise — but `supports_keyboard_enhancement()` **blocks for up to
        // two seconds** on any terminal that does not answer the query, which
        // is a real cost on every launch for a chord that then still did not
        // arrive through tmux. `\`+Enter and `C-j` need no negotiation.
        let backend = CrosstermBackend::new(stdout);
        let terminal = ratatui::Terminal::new(AppBackend::Crossterm(backend))?;

        // Load configs
        let global_config = GlobalConfig::load().unwrap_or_default();
        let global_db = Database::open_global()?;

        // Detect available agents
        let available_agents = agent::detect_available_agents();

        // Setup based on mode
        let (db, project_path, project_name, tmux_project_name, project_config, trust_warning) =
            match &mode {
                AppMode::Dashboard => (
                    None,
                    None,
                    "Dashboard".to_string(),
                    tmux::safe_session_name("Dashboard"),
                    ProjectConfig::default(),
                    None,
                ),
                AppMode::Project(path) => {
                    let canonical = path.canonicalize().unwrap_or_else(|_| path.clone());
                    let name = canonical
                        .file_name()
                        .and_then(|n| n.to_str())
                        .unwrap_or("unknown")
                        .to_string();
                    let tmux_name = tmux::safe_session_name(&name);
                    let mut project_config = ProjectConfig::load(&canonical).unwrap_or_default();
                    let db = Database::open_project(&canonical)?;

                    // Trust-on-first-use: suppress dangerous config fields from untrusted projects
                    let trust_store = crate::config::TrustStore::load().unwrap_or_default();
                    let trust_warning = if !trust_store.is_trusted(&canonical) {
                        if project_config.init_script.is_some()
                            || project_config.copy_files.is_some()
                            || project_config.cleanup_script.is_some()
                        {
                            tracing::warn!(
                                project = %canonical.display(),
                                "Untrusted project config — init_script, cleanup_script, and copy_files suppressed"
                            );
                            project_config.init_script = None;
                            project_config.cleanup_script = None;
                            project_config.copy_files = None;
                            Some("Untrusted project config: init_script, cleanup_script, and copy_files disabled. Run `agtx trust` to enable.".to_string())
                        } else {
                            None
                        }
                    } else {
                        None
                    };

                    // Register project in global database
                    let project = crate::db::Project::new(&name, canonical.to_string_lossy());
                    global_db.upsert_project(&project)?;

                    // Ensure tmux session exists for this project
                    ensure_project_tmux_session(&tmux_name, &canonical, tmux_ops.as_ref());

                    (
                        Some(db),
                        Some(canonical),
                        name,
                        tmux_name,
                        project_config,
                        trust_warning,
                    )
                }
            };

        let config = MergedConfig::merge(&global_config, &project_config);

        // One broker for the process. Popup keys are enqueued onto it, so the
        // input thread never waits for a tmux subprocess. Whether the broker
        // then writes through a control connection or one process per key is a
        // runtime decision it makes for itself: this only says not to try the
        // control connection at all.
        let mut input_config = InputConfig::new(tmux::AGENT_SERVER, &tmux_project_name);
        input_config.control_mode = control_mode_enabled();
        // tmux reports a window closing on this same connection, even with
        // `no-output`. That is how an exited agent becomes an `Exited` card
        // promptly instead of on the status refresh's next tick.
        let window_events = Arc::new(AtomicBool::new(false));
        input_config.window_events = Some(Arc::clone(&window_events));
        let input_sink = tmux::input::spawn(input_config, Arc::clone(&tmux_ops));

        // If the project is untrusted, also suppress plugin init_scripts
        // by forcing no_init_scripts in the flags
        let mut flags = flags;
        if trust_warning.is_some() {
            flags.no_init_scripts = true;
        }

        let mut app = Self {
            terminal,
            state: AppState {
                mode,
                flags,
                should_quit: false,
                board: BoardState::new(),
                wizard: None,
                config_editor: None,
                help_scroll: None,
                help_max_scroll: Cell::new(0),
                plugins_filtered_for: None,
                db,
                global_db,
                config,
                project_path,
                project_name: project_name.clone(),
                tmux_project_name: tmux_project_name.clone(),
                available_agents,
                tmux_ops,
                input_sink,
                git_ops,
                git_provider_ops,
                agent_registry,
                sidebar_visible: true,
                sidebar_focused: false,
                projects: vec![],
                selected_project: 0,
                show_project_list: false,
                shell_popup: None,
                file_search: None,
                skill_search: None,
                task_ref_search: None,
                task_search: None,
                pr_confirm_popup: None,
                review_to_running_task_id: None,
                diff_popup: None,
                pr_generation_rx: None,
                pr_status_popup: None,
                pr_creation_rx: None,
                setup_rx: None,
                done_confirm_popup: None,
                move_confirm_popup: None,
                skip_move_confirm: false,
                delete_confirm_popup: None,
                review_confirm_popup: None,
                trust_confirm_popup: None,
                phase_status_cache: HashMap::new(),
                last_transition_poll: Instant::now(),
                window_events,
                pane_content_hashes: HashMap::new(),
                blocked_reasons: HashMap::new(),
                trust_blocked: HashSet::new(),
                merge_conflict_checked: HashSet::new(),
                stuck_task_notified: HashSet::new(),
                stuck_task_idle_since: HashMap::new(),
                cached_plugin: None,
                warning_message: None,
                plugin_select_popup: None,
                orchestrator_session: None,
                orchestrator_ready: Arc::new(AtomicBool::new(false)),
                orchestrator_last_content: String::new(),
                orchestrator_stable_since: None,
                orchestrator_last_check: Instant::now(),
                session_refresh_rx: None,
                update_rx: None,
                update_available: None,
                update_popup: None,
                update_install_rx: None,
                deps_satisfied_cache: HashMap::new(),
                dep_graph_popup: None,
                mobile_popup: None,
                serve_session: None,
                setup_queue: VecDeque::new(),
                instance_id: uuid::Uuid::new_v4().to_string(),
            },
        };

        // Load and cache workflow plugin
        app.state.cached_plugin = Some(load_plugin_if_configured(
            &app.state.config,
            app.state.project_path.as_deref(),
        ));

        // Load tasks if in project mode
        app.refresh_tasks()?;
        // Load projects from global database
        app.refresh_projects()?;

        // Re-deploy agent configs for worktrees set up by a different agtx binary.
        if let Some(ref project_path) = app.state.project_path {
            let candidates: Vec<(String, Option<String>, Vec<String>)> = app
                .state
                .board
                .tasks
                .iter()
                .filter(|t| t.status != TaskStatus::Done)
                .filter_map(|t| {
                    t.worktree_path.clone().map(|wt| {
                        (wt, t.plugin.clone(), collect_phase_agents(&app.state.config, t))
                    })
                })
                .collect();
            if !candidates.is_empty() {
                refresh_stale_worktree_configs(
                    candidates,
                    project_path.clone(),
                    app.state.config.agent_hooks,
                );
            }
        }

        // Recover tasks whose tmux windows were lost (server restart, manual kill, etc.)
        {
            let tasks_to_recover: Vec<_> = app
                .state
                .board
                .tasks
                .iter()
                .filter(|t| {
                    matches!(
                        t.status,
                        TaskStatus::Planning | TaskStatus::Running | TaskStatus::Review
                    ) && t.session_name.is_some()
                        && t.worktree_path.is_some()
                })
                .filter(|t| {
                    let sn = t.session_name.as_ref().unwrap();
                    !app.state.tmux_ops.window_exists(sn).unwrap_or(true)
                })
                .cloned()
                .collect();

            for task in &tasks_to_recover {
                let agent_ops = app.state.agent_registry.get(&task.agent);
                let _ = recover_task_session(
                    task,
                    &app.state.tmux_project_name,
                    app.state.project_path.as_deref().unwrap_or(Path::new(".")),
                    app.state.tmux_ops.as_ref(),
                    agent_ops.as_ref(),
                );
            }
        }

        if let Some(orch_target) = detect_existing_orchestrator(
            app.state.flags.experimental,
            app.state.tmux_ops.as_ref(),
            &app.state.tmux_project_name,
            app.state.db.as_ref(),
            &app.state.board.tasks,
            app.state.project_path.as_deref(),
        ) {
            app.state.orchestrator_session = Some(orch_target.clone());
            let tmux_ops = Arc::clone(&app.state.tmux_ops);
            let ready_flag = Arc::clone(&app.state.orchestrator_ready);
            let auto_trust = app.state.config.auto_trust;
            std::thread::spawn(move || {
                if wait_for_agent_ready(&tmux_ops, &orch_target, Some("claude"), auto_trust)
                    .is_some()
                {
                    ready_flag.store(true, Ordering::Release);
                }
            });
        }

        // Release check, on a background thread so a slow or hung network never
        // delays the first frame. Deliberately not in `new_for_test`: the test
        // suite must not make network calls.
        if crate::update::check::checks_enabled(app.state.config.update_check) {
            let (tx, rx) = mpsc::channel();
            app.state.update_rx = Some(rx);
            std::thread::spawn(move || {
                let _ = tx.send(crate::update::check_for_update().unwrap_or(None));
            });
        }

        app.open_first_run_editor();

        // Display trust confirmation popup if project config was suppressed
        if trust_warning.is_some() {
            if let Some(ref path) = app.state.project_path {
                // Re-read from disk: the merged config has already had these
                // stripped, which is the whole reason the popup exists.
                let on_disk = ProjectConfig::load(path).unwrap_or_default();
                app.state.trust_confirm_popup = Some(TrustConfirmPopup {
                    project_path: path.clone(),
                    dangerous: dangerous_fields(&on_disk),
                });
            }
        }

        Ok(app)
    }

    /// Create an App instance for testing with in-memory databases and TestBackend.
    /// No real terminal, no real filesystem databases, no agent detection.
    #[cfg(feature = "test-mocks")]
    pub fn new_for_test(
        project_path: Option<PathBuf>,
        tmux_ops: Arc<dyn TmuxOperations>,
        git_ops: Arc<dyn GitOperations>,
        git_provider_ops: Arc<dyn GitProviderOperations>,
        agent_registry: Arc<dyn agent::AgentRegistry>,
    ) -> Result<Self> {
        Self::new_for_test_with_flags(
            project_path,
            tmux_ops,
            git_ops,
            git_provider_ops,
            agent_registry,
            crate::FeatureFlags::default(),
        )
    }

    #[cfg(feature = "test-mocks")]
    pub fn new_for_test_with_flags(
        project_path: Option<PathBuf>,
        tmux_ops: Arc<dyn TmuxOperations>,
        git_ops: Arc<dyn GitOperations>,
        git_provider_ops: Arc<dyn GitProviderOperations>,
        agent_registry: Arc<dyn agent::AgentRegistry>,
        flags: crate::FeatureFlags,
    ) -> Result<Self> {
        let backend = ratatui::backend::TestBackend::new(80, 24);
        let terminal = ratatui::Terminal::new(AppBackend::Test(backend))?;

        let global_db = Database::open_in_memory_global()?;
        let (db, mode, project_name, tmux_project_name) = if let Some(ref path) = project_path {
            let name = path
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or("test-project")
                .to_string();
            let db = Database::open_in_memory_project()?;
            (
                Some(db),
                AppMode::Project(path.clone()),
                name.clone(),
                tmux::safe_session_name(&name),
            )
        } else {
            (
                None,
                AppMode::Dashboard,
                "Dashboard".to_string(),
                tmux::safe_session_name("Dashboard"),
            )
        };

        let config = MergedConfig::merge(&GlobalConfig::default(), &ProjectConfig::default());

        let mut app = Self {
            terminal,
            state: AppState {
                mode,
                flags,
                should_quit: false,
                board: BoardState::new(),
                wizard: None,
                config_editor: None,
                help_scroll: None,
                help_max_scroll: Cell::new(0),
                plugins_filtered_for: None,
                db,
                global_db,
                config,
                project_path,
                project_name,
                tmux_project_name,
                available_agents: vec![],
                tmux_ops,
                // Tests assert what the UI *enqueued*; a broker thread would add
                // timing to something that is a pure translation.
                input_sink: Arc::new(crate::tmux::RecordingSink::new()),
                git_ops,
                git_provider_ops,
                agent_registry,
                sidebar_visible: false,
                sidebar_focused: false,
                projects: vec![],
                selected_project: 0,
                show_project_list: false,
                shell_popup: None,
                file_search: None,
                skill_search: None,
                task_ref_search: None,
                task_search: None,
                pr_confirm_popup: None,
                review_to_running_task_id: None,
                diff_popup: None,
                pr_generation_rx: None,
                pr_status_popup: None,
                pr_creation_rx: None,
                setup_rx: None,
                done_confirm_popup: None,
                move_confirm_popup: None,
                skip_move_confirm: false,
                delete_confirm_popup: None,
                review_confirm_popup: None,
                trust_confirm_popup: None,
                phase_status_cache: HashMap::new(),
                last_transition_poll: Instant::now(),
                window_events: Arc::new(AtomicBool::new(false)),
                pane_content_hashes: HashMap::new(),
                blocked_reasons: HashMap::new(),
                trust_blocked: HashSet::new(),
                merge_conflict_checked: HashSet::new(),
                stuck_task_notified: HashSet::new(),
                stuck_task_idle_since: HashMap::new(),
                cached_plugin: None,
                warning_message: None,
                plugin_select_popup: None,
                orchestrator_session: None,
                orchestrator_ready: Arc::new(AtomicBool::new(false)),
                orchestrator_last_content: String::new(),
                orchestrator_stable_since: None,
                orchestrator_last_check: Instant::now(),
                session_refresh_rx: None,
                update_rx: None,
                update_available: None,
                update_popup: None,
                update_install_rx: None,
                deps_satisfied_cache: HashMap::new(),
                dep_graph_popup: None,
                mobile_popup: None,
                serve_session: None,
                setup_queue: VecDeque::new(),
                instance_id: uuid::Uuid::new_v4().to_string(),
            },
        };
        // The same call the real constructor makes, so a test exercises the
        // first-run path rather than a copy of it.
        app.open_first_run_editor();
        Ok(app)
    }

    /// Swap in a recording sink so a test can assert what the UI enqueued.
    #[cfg(feature = "test-mocks")]
    pub fn set_input_sink(&mut self, sink: Arc<dyn PaneInputSink>) {
        self.state.input_sink = sink;
    }

    /// The event loop.
    ///
    /// It **blocks** on a channel that two threads feed — terminal input and
    /// pane captures — and draws only when something actually changed. The
    /// previous shape polled: `event::poll(interval)` woke the loop on a timer
    /// whether or not anything had happened, and every wake-up redrew the whole
    /// screen and re-parsed the pane capture through `parse_ansi_to_lines`. That
    /// made the poll interval a three-way trade between echo latency, DB
    /// polling rate and idle CPU, so tuning it for the first made the other two
    /// expensive.
    ///
    /// Splitting them makes each one answer to what it is actually for:
    ///
    /// - **latency** is the pane watcher's cadence, and it wakes the loop only
    ///   when the pane it captured differs from the last one it sent;
    /// - **housekeeping** — the DB queue, the session refresh, the spinner — runs
    ///   on its own tick, no faster than it needs to and independent of how fast
    ///   the user types;
    /// - **drawing** happens when state changed, so an idle board with an idle
    ///   popup costs one backstop frame a second.
    pub async fn run(&mut self) -> Result<()> {
        let (tx, rx) = mpsc::channel::<Wake>();
        spawn_terminal_reader(tx.clone());
        let watch = Arc::new(PaneWatch::default());
        spawn_pane_watcher(
            Arc::clone(&watch),
            tx,
            Arc::clone(&self.state.input_sink),
            Arc::clone(&self.state.tmux_ops),
        );

        // The first frame has nothing to be a change from.
        let mut dirty = true;
        let mut last_draw = Instant::now();
        let mut last_housekeeping = Instant::now() - HOUSEKEEPING_TICK;

        while !self.state.should_quit {
            // A missed `dirty` would leave a stale screen until the next
            // keystroke, which is a far worse failure than a wasted frame — so
            // the loop repaints once a second regardless. A backstop, not the
            // mechanism: one frame a second is nothing, and if it is ever what
            // makes the UI look right, something above it is wrong.
            if dirty || last_draw.elapsed() >= REDRAW_BACKSTOP {
                self.draw()?;
                dirty = false;
                last_draw = Instant::now();
            }

            // Point the watcher at whatever popup is open now. Done here rather
            // than at the three sites that open one and the several that close
            // one: this cannot be forgotten by a new call site.
            let (watch_target, watch_depth) = match self.state.shell_popup.as_ref() {
                Some(popup) => (
                    Some(popup.window_name.as_str()),
                    popup_capture_depth(popup.scroll_offset),
                ),
                None => (None, SHELL_POPUP_TAIL_LINES),
            };
            watch.follow(watch_target, watch_depth);

            match rx.recv_timeout(HOUSEKEEPING_TICK) {
                Ok(wake) => {
                    // Typing is the case the fast cadence exists for, so a key
                    // ends the watcher's wait rather than landing in the middle
                    // of a backed-off one.
                    if matches!(wake, Wake::Input(_)) {
                        watch.poke();
                    }
                    dirty |= self.handle_wake(wake)?;
                    // Drain what is already queued: a burst of keystrokes, or a
                    // key and the capture it caused, are one redraw, not four.
                    loop {
                        match rx.try_recv() {
                            Ok(wake) => dirty |= self.handle_wake(wake)?,
                            Err(mpsc::TryRecvError::Empty) => break,
                            Err(mpsc::TryRecvError::Disconnected) => {
                                self.state.should_quit = true;
                                break;
                            }
                        }
                    }
                }
                Err(mpsc::RecvTimeoutError::Timeout) => {}
                // Both feeder threads are gone; without terminal input there is
                // no way left to quit.
                Err(mpsc::RecvTimeoutError::Disconnected) => self.state.should_quit = true,
            }

            dirty |= self.pump_background_results()?;

            if last_housekeeping.elapsed() >= HOUSEKEEPING_TICK {
                last_housekeeping = Instant::now();
                dirty |= self.run_housekeeping();
            }
        }

        watch.stop();
        Ok(())
    }

    /// Apply one wake-up. Returns whether the screen needs redrawing.
    fn handle_wake(&mut self, wake: Wake) -> Result<bool> {
        match wake {
            Wake::Input(Event::Key(key)) if key.kind == KeyEventKind::Press => {
                self.handle_key(key)?;
                Ok(true)
            }
            Wake::Input(Event::Paste(text)) => {
                self.handle_paste(text)?;
                Ok(true)
            }
            Wake::Input(Event::Resize(..)) => Ok(true),
            Wake::Input(_) => Ok(false),
            Wake::Pane {
                window,
                content,
                lines,
                metrics,
                cursor_line,
            } => {
                let Some(popup) = self.state.shell_popup.as_mut() else {
                    return Ok(false);
                };
                // A capture for a popup that has since closed or switched panes
                // is not this popup's content.
                if popup.window_name != window {
                    return Ok(false);
                }
                // The watcher already suppresses unchanged captures; this also
                // covers the first one after a popup seeded its own content
                // synchronously at open time.
                if popup.cached_content == content && popup.metrics == metrics {
                    return Ok(false);
                }
                popup.set_content(content, lines, cursor_line);
                popup.metrics = metrics;
                Ok(true)
            }
        }
    }

    /// Collect anything the background threads have finished. Returns whether
    /// any of it changed what is on screen.
    fn pump_background_results(&mut self) -> Result<bool> {
        let mut changed = false;

        // Check for PR generation completion
        if let Some(ref rx) = self.state.pr_generation_rx {
            if let Ok((pr_title, pr_body)) = rx.try_recv() {
                if let Some(ref mut popup) = self.state.pr_confirm_popup {
                    popup.pr_title = pr_title;
                    popup.pr_body = pr_body;
                    popup.generating = false;
                }
                self.state.pr_generation_rx = None;
                changed = true;
            }
        }

        // Check for PR creation completion
        if let Some(ref rx) = self.state.pr_creation_rx {
            if let Ok(result) = rx.try_recv() {
                match result {
                    Ok((_, pr_url)) => {
                        self.state.pr_status_popup = Some(PrStatusPopup {
                            status: PrCreationStatus::Success,
                            pr_url: Some(pr_url),
                            error_message: None,
                        });
                    }
                    Err(err) => {
                        self.state.pr_status_popup = Some(PrStatusPopup {
                            status: PrCreationStatus::Error,
                            pr_url: None,
                            error_message: Some(err),
                        });
                    }
                }
                self.state.pr_creation_rx = None;
                self.refresh_tasks()?;
                changed = true;
            }
        }

        // Check for worktree setup completion
        if let Some(ref rx) = self.state.setup_rx {
            if let Ok(result) = rx.try_recv() {
                self.state.setup_rx = None;
                if let Some(err) = result.error {
                    self.state.warning_message = Some((err, Instant::now()));
                } else {
                    // Update task with worktree info from background setup
                    if let Some(db) = &self.state.db {
                        if let Ok(Some(mut task)) = db.get_task(&result.task_id) {
                            task.session_name = Some(result.session_name);
                            task.worktree_path = Some(result.worktree_path);
                            task.branch_name = Some(result.branch_name);
                            task.agent = result.agent;
                            task.plugin = result.plugin;
                            if let Some(status) = result.new_status {
                                task.status = status;
                            }
                            task.updated_at = chrono::Utc::now();
                            let _ = db.update_task(&task);
                        }
                    }
                    self.refresh_tasks()?;
                }
                // This setup finished; start the next queued batch task (if any).
                self.try_start_next_queued_setup()?;
                changed = true;
            }
        }

        // Apply results from background session refresh (non-blocking)
        if let Some(ref rx) = self.state.session_refresh_rx {
            match rx.try_recv() {
                Ok(result) => {
                    self.state.session_refresh_rx = None;
                    self.apply_session_refresh(result);
                    changed = true;
                }
                Err(mpsc::TryRecvError::Disconnected) => {
                    // Thread panicked or dropped sender — clear to allow future spawns
                    self.state.session_refresh_rx = None;
                }
                Err(mpsc::TryRecvError::Empty) => {}
            }
        }

        // Release check result (arrives once, then the channel is dropped)
        if let Some(ref rx) = self.state.update_rx {
            match rx.try_recv() {
                Ok(info) => {
                    self.state.update_rx = None;
                    self.state.update_available = info;
                    changed = true;
                }
                Err(mpsc::TryRecvError::Disconnected) => {
                    self.state.update_rx = None;
                }
                Err(mpsc::TryRecvError::Empty) => {}
            }
        }

        // Result of an install started from the update popup
        if let Some(ref rx) = self.state.update_install_rx {
            match rx.try_recv() {
                Ok(result) => {
                    self.state.update_install_rx = None;
                    if let Some(popup) = self.state.update_popup.as_mut() {
                        popup.installing = false;
                        popup.status = Some(match result {
                            Ok(msg) => msg,
                            Err(e) => format!("failed: {e}"),
                        });
                    }
                    changed = true;
                }
                Err(mpsc::TryRecvError::Disconnected) => {
                    self.state.update_install_rx = None;
                    if let Some(popup) = self.state.update_popup.as_mut() {
                        popup.installing = false;
                        popup.status = Some("failed: the update thread stopped".to_string());
                    }
                    changed = true;
                }
                Err(mpsc::TryRecvError::Empty) => {}
            }
        }

        Ok(changed)
    }

    /// Periodic work, on its own tick rather than once per wake-up.
    ///
    /// Running these per loop iteration would tie their rate to how fast the
    /// user happens to be typing — `process_transition_requests` queries SQLite.
    /// Returns whether anything on screen moved.
    fn run_housekeeping(&mut self) -> bool {
        let mut changed = false;
        let now = Instant::now();

        // Process MCP transition requests from the command queue, on their own
        // interval: this is a SQLite query, and housekeeping's tick is faster
        // than a queued transition needs.
        if now.duration_since(self.state.last_transition_poll) >= TRANSITION_POLL_INTERVAL {
            self.state.last_transition_poll = now;
            if let Err(e) = self.process_transition_requests() {
                tracing::warn!(error = %e, "failed to process transition requests");
            }
            // Notice a served board whose child has died — a taken port, or a
            // tunnel the provider refused. Without this the overlay keeps
            // showing a QR for a server that is gone, which is the worst of
            // both: it looks fine and nothing works.
            if self.state.serve_session.is_some() {
                if let Some(popup) = self.state.mobile_popup.as_mut() {
                    if popup.poll_session(&mut self.state.serve_session) {
                        changed = true;
                    }
                } else if self
                    .state
                    .serve_session
                    .as_mut()
                    .and_then(|s| s.check())
                    .is_some()
                {
                    // Overlay closed, so there is nowhere to show a message —
                    // but the dead session must still be dropped, or `s` would
                    // report "stopped serving" for something already gone.
                    self.state.serve_session = None;
                }
            }

            // Beat on the same tick, because it answers a question about
            // exactly this loop: something out of process can enqueue a
            // transition whenever, but only a running TUI drains the queue.
            if let Some(path) = &self.state.project_path {
                let _ = self
                    .state
                    .global_db
                    .beat_tui_heartbeat(&path.to_string_lossy());
            }
        }

        // tmux said a window closed. The refresh is what turns that into an
        // `Exited` card, and its per-task cache would otherwise hold the old
        // status for up to `PHASE_STATUS_CACHE_TTL` — so age the cache out and
        // let the refresh below run now.
        if self.state.window_events.swap(false, Ordering::Relaxed) {
            self.expire_phase_status_cache();
        }

        // Spawn background refresh if not already running and cache expired.
        self.maybe_spawn_session_refresh();

        // Nothing on the board animates any more: every indicator is static, so
        // an idle board asks for no frame at all between real changes.

        // Deliver queued notifications to orchestrator when idle
        self.deliver_orchestrator_notifications();

        // Clear expired warning messages
        if let Some((_, created)) = &self.state.warning_message {
            if created.elapsed() >= WARNING_MESSAGE_TTL {
                self.state.warning_message = None;
                changed = true;
            }
        }

        changed
    }

    /// Make every cached phase status look stale, so the next refresh re-checks
    /// every task rather than waiting out its per-task TTL.
    ///
    /// The timestamps are aged rather than the entries dropped: the previous
    /// status is what decides `was_ready`, and losing it would suppress the
    /// "newly ready" notification for a task that had just finished.
    fn expire_phase_status_cache(&mut self) {
        let Some(stale) = Instant::now().checked_sub(PHASE_STATUS_CACHE_TTL) else {
            return;
        };
        for (_, ts) in self.state.phase_status_cache.values_mut() {
            *ts = stale;
        }
    }

    pub fn draw(&mut self) -> Result<()> {
        let state = &self.state;
        self.terminal.draw(|frame| {
            let area = frame.area();

            match &state.mode {
                AppMode::Dashboard => Self::draw_dashboard(state, frame, area),
                AppMode::Project(_) => Self::draw_board(state, frame, area),
            }
        })?;

        Ok(())
    }

    fn draw_board(state: &AppState, frame: &mut Frame, area: Rect) {
        // Main layout with optional sidebar
        let main_chunks = if state.sidebar_visible {
            Layout::default()
                .direction(Direction::Horizontal)
                .constraints([
                    Constraint::Length(25), // Sidebar
                    Constraint::Min(0),     // Main content
                ])
                .split(area)
        } else {
            // No sidebar - use full area
            Layout::default()
                .direction(Direction::Horizontal)
                .constraints([Constraint::Min(0)])
                .split(area)
        };

        // Draw sidebar if visible
        if state.sidebar_visible {
            Self::draw_sidebar(state, frame, main_chunks[0]);
        }

        let content_area = if state.sidebar_visible {
            main_chunks[1]
        } else {
            main_chunks[0]
        };

        let styles = TuiStyles::from_theme(&state.config.theme);

        // Main layout: compact application bar, board, contextual command bar.
        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([
                Constraint::Length(2), // Header + divider
                Constraint::Min(0),    // Board
                Constraint::Length(2), // Divider + footer
            ])
            .split(content_area);

        // Header
        let plugin_label = state.config.workflow_plugin.as_deref().unwrap_or("agtx");
        let left = Span::styled(
            format!("  {}", state.project_name),
            Style::default().fg(styles.text).bold(),
        );
        let mut right_spans: Vec<Span> = Vec::new();
        if state.flags.experimental {
            let orch_active = state.orchestrator_session.is_some();
            if orch_active {
                right_spans.push(Span::styled("● ", Style::default().fg(Color::Green)));
                right_spans.push(Span::styled(
                    "orchestrator ",
                    Style::default().fg(Color::Green),
                ));
            }
            right_spans.push(Span::styled(
                "[O] ",
                Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
            ));
        }
        if let Some(ref update) = state.update_available {
            // color_selected, not a warning color: this is an affordance, not a
            // fault. `[u]` is the discovery point — the footer is already dense
            // enough that another hint there would be lost.
            right_spans.push(Span::styled(
                format!("⬆ {} ", update.latest),
                Style::default().fg(hex_to_color(&state.config.theme.color_selected)),
            ));
            right_spans.push(Span::styled(
                "[u] ",
                Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
            ));
        }
        right_spans.extend([
            Span::styled(
                format!("{} ", plugin_label),
                Style::default().fg(hex_to_color(&state.config.theme.color_accent)),
            ),
            Span::styled(
                "[P] ",
                Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
            ),
        ]);
        let left_len = state.project_name.chars().count() + 2;
        // Character count, not byte count: the update notice's "⬆" is 3 bytes
        // and one column, and a byte-based width would over-pad the header.
        let right_len: usize = right_spans.iter().map(|s| s.content.chars().count()).sum();
        let padding = (chunks[0].width as usize).saturating_sub(left_len + right_len + 2);
        let mut spans = vec![left, Span::raw(" ".repeat(padding))];
        spans.extend(right_spans);
        frame.render_widget(
            Paragraph::new(Line::from(spans)),
            Rect {
                height: 1,
                ..chunks[0]
            },
        );
        frame.render_widget(
            Paragraph::new("─".repeat(chunks[0].width as usize)).style(styles.muted()),
            Rect {
                y: chunks[0].y + 1,
                height: 1,
                ..chunks[0]
            },
        );

        // Keep cards usable on narrow terminals by showing a window around the
        // selected column. Navigation still spans all five workflow columns.
        let visible_range = visible_column_range(state.board.selected_column, chunks[1].width);
        let mut constraints = Vec::new();
        for slot in 0..visible_range.len() {
            if slot > 0 {
                constraints.push(Constraint::Length(1));
            }
            constraints.push(Constraint::Ratio(1, visible_range.len() as u32));
        }
        let board_areas = Layout::horizontal(constraints).split(chunks[1]);

        let statuses = TaskStatus::columns();
        for (slot, i) in visible_range.enumerate() {
            let status = &statuses[i];
            let column_area = board_areas[slot * 2];
            let tasks: Vec<&Task> = state
                .board
                .tasks
                .iter()
                .filter(|t| t.status == *status)
                .collect();

            let is_selected_column = state.board.selected_column == i;

            let title_style = if is_selected_column {
                Style::default().fg(styles.selected).bold()
            } else {
                Style::default().fg(styles.column_header).bold()
            };

            let header_area = Rect {
                height: 2,
                ..column_area
            };
            let count = Span::styled(format!("  {}", tasks.len()), styles.muted());
            frame.render_widget(
                Paragraph::new(Line::from(vec![
                    Span::styled(
                        format!(" {}", status.display_name().to_uppercase()),
                        title_style,
                    ),
                    count,
                ])),
                Rect {
                    height: 1,
                    ..header_area
                },
            );
            let rule_color = if is_selected_column {
                styles.selected
            } else {
                styles.dimmed
            };
            frame.render_widget(
                Paragraph::new("─".repeat(header_area.width as usize))
                    .style(Style::default().fg(rule_color)),
                Rect {
                    y: header_area.y + 1,
                    height: 1,
                    ..header_area
                },
            );

            let inner_area = Rect {
                y: column_area.y + 2,
                height: column_area.height.saturating_sub(2),
                ..column_area
            };
            let card_height = card_height_for_width(inner_area.width);
            let max_visible_cards = (inner_area.height / card_height).max(1) as usize;

            // Calculate scroll offset to keep selected task visible
            let scroll_offset = if is_selected_column && tasks.len() > max_visible_cards {
                let selected = state.board.selected_row;
                if selected >= max_visible_cards {
                    selected - max_visible_cards + 1
                } else {
                    0
                }
            } else {
                0
            };

            // Check if we need a scrollbar
            let needs_scrollbar = tasks.len() > max_visible_cards;
            // Render task cards with scroll offset
            let visible_tasks: Vec<_> = tasks
                .iter()
                .skip(scroll_offset)
                .take(max_visible_cards)
                .collect();
            for (j, task) in visible_tasks.iter().enumerate() {
                let actual_index = scroll_offset + j;
                let is_selected = is_selected_column && state.board.selected_row == actual_index;

                let card_area = Rect {
                    x: inner_area.x,
                    y: inner_area.y + (j as u16 * card_height),
                    width: if needs_scrollbar {
                        inner_area.width.saturating_sub(1)
                    } else {
                        inner_area.width
                    },
                    height: card_height
                        .min(inner_area.height.saturating_sub(j as u16 * card_height)),
                };

                if card_area.height < 3 {
                    break;
                }

                let deps_blocked = state
                    .deps_satisfied_cache
                    .get(&task.id)
                    .map_or(false, |satisfied| !satisfied);
                Self::draw_task_card(
                    frame,
                    task,
                    card_area,
                    is_selected,
                    &state.config.theme,
                    state.phase_status_cache.get(&task.id),
                    deps_blocked,
                );
            }

            if tasks.is_empty() {
                let empty = if is_selected_column {
                    "  No tasks · [o] new"
                } else {
                    "  No tasks"
                };
                frame.render_widget(Paragraph::new(empty).style(styles.muted()), inner_area);
            }

            // Draw scrollbar if needed
            if needs_scrollbar {
                let scrollbar_area = Rect {
                    x: inner_area.x + inner_area.width - 1,
                    y: inner_area.y,
                    width: 1,
                    height: inner_area.height,
                };

                let scrollbar_height = inner_area.height as usize;
                if let Some((thumb_pos, thumb_height)) = board_scrollbar_metrics(
                    tasks.len(),
                    max_visible_cards,
                    scroll_offset,
                    scrollbar_height,
                ) {
                    for y in 0..scrollbar_height {
                        let is_thumb = y >= thumb_pos && y < thumb_pos + thumb_height;
                        let (glyph, style) = if is_thumb {
                            ("┃", Style::default().fg(styles.selected).bold())
                        } else {
                            ("│", styles.muted())
                        };
                        frame.render_widget(
                            Paragraph::new(glyph).style(style),
                            Rect {
                                x: scrollbar_area.x,
                                y: scrollbar_area.y + y as u16,
                                width: 1,
                                height: 1,
                            },
                        );
                    }
                }
            }
        }

        // Footer with help (or transient warning)
        let has_cyclic_plugin = state
            .board
            .selected_task()
            .and_then(|t| t.plugin.as_ref())
            .and_then(|name| WorkflowPlugin::load(name, state.project_path.as_deref()).ok())
            .map_or(false, |p| p.cyclic);
        let (footer_text, footer_style) = if let Some((ref msg, created)) = state.warning_message {
            if created.elapsed() < std::time::Duration::from_secs(5) {
                (msg.clone(), Style::default().fg(Color::Yellow))
            } else {
                (
                    build_footer_text(
                        state.wizard_step(),
                        state.sidebar_focused,
                        state.board.selected_column,
                        has_cyclic_plugin,
                        state.config.fullscreen_on_enter,
                    ),
                    Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
                )
            }
        } else {
            (
                build_footer_text(
                    state.wizard_step(),
                    state.sidebar_focused,
                    state.board.selected_column,
                    has_cyclic_plugin,
                    state.config.fullscreen_on_enter,
                ),
                Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
            )
        };

        frame.render_widget(
            Paragraph::new("─".repeat(chunks[2].width as usize)).style(styles.muted()),
            Rect {
                height: 1,
                ..chunks[2]
            },
        );
        let footer_line = if footer_style.fg == Some(Color::Yellow) {
            Line::from(Span::styled(
                format!("  {}", footer_text.trim()),
                footer_style,
            ))
        } else {
            styled_footer(&footer_text, styles)
        };
        frame.render_widget(
            Paragraph::new(footer_line).alignment(Alignment::Center),
            Rect {
                y: chunks[2].y + 1,
                height: 1,
                ..chunks[2]
            },
        );

        // The task wizard overlay
        if let Some(ref wizard) = state.wizard {
            let input_area = centered_rect(60, 60, area);
            draw_wizard(state, wizard, frame, input_area);

            // Search dropdowns (only in InputDescription mode)
            if wizard.step() == WizardStep::Prompt {
                // File search dropdown
                if let Some(ref search) = state.file_search {
                    if !search.matches.is_empty() {
                        let dropdown_height = (search.matches.len() as u16 + 2).min(12);
                        let dropdown_area = Rect {
                            x: input_area.x + 2,
                            y: input_area.y + input_area.height,
                            width: input_area.width.saturating_sub(4),
                            height: dropdown_height,
                        };
                        let dropdown_area = if dropdown_area.y + dropdown_area.height > area.height
                        {
                            Rect {
                                y: input_area.y.saturating_sub(dropdown_height),
                                ..dropdown_area
                            }
                        } else {
                            dropdown_area
                        };

                        frame.render_widget(Clear, dropdown_area);
                        let file_selected_color = hex_to_color(&state.config.theme.color_selected);
                        let items: Vec<ListItem> = search
                            .matches
                            .iter()
                            .enumerate()
                            .map(|(i, path)| {
                                let style = if i == search.selected {
                                    Style::default().bg(file_selected_color).fg(Color::Black)
                                } else {
                                    Style::default().fg(Color::White)
                                };
                                ListItem::new(format!(" {} ", path)).style(style)
                            })
                            .collect();
                        let list = List::new(items).block(
                            Block::default()
                                .title(" Files [↑↓] select [Tab/Enter] insert [Esc] cancel ")
                                .borders(Borders::ALL)
                                .border_style(Style::default().fg(Color::Cyan)),
                        );
                        frame.render_widget(list, dropdown_area);
                    }
                }

                // Skill search dropdown
                if let Some(ref search) = state.skill_search {
                    if !search.matches.is_empty() {
                        let dropdown_height = (search.matches.len() as u16 + 2).min(12);
                        let dropdown_area = Rect {
                            x: input_area.x + 2,
                            y: input_area.y + input_area.height,
                            width: input_area.width.saturating_sub(4),
                            height: dropdown_height,
                        };
                        let dropdown_area = if dropdown_area.y + dropdown_area.height > area.height
                        {
                            Rect {
                                y: input_area.y.saturating_sub(dropdown_height),
                                ..dropdown_area
                            }
                        } else {
                            dropdown_area
                        };

                        frame.render_widget(Clear, dropdown_area);
                        let skill_sel_color = hex_to_color(&state.config.theme.color_selected);
                        let accent = hex_to_color(&state.config.theme.color_accent);
                        let dim = hex_to_color(&state.config.theme.color_dimmed);
                        let items: Vec<ListItem> = search
                            .matches
                            .iter()
                            .enumerate()
                            .map(|(i, entry)| {
                                let (style, cmd_style, dsc_style) = if i == search.selected {
                                    let s = Style::default().bg(skill_sel_color).fg(Color::Black);
                                    (s, s, s)
                                } else {
                                    (
                                        Style::default(),
                                        Style::default().fg(accent),
                                        Style::default().fg(dim),
                                    )
                                };
                                let cmd_padded = format!(" {:<24}", entry.command);
                                ListItem::new(Line::from(vec![
                                    Span::styled(cmd_padded, cmd_style),
                                    Span::styled(&entry.description, dsc_style),
                                ]))
                                .style(style)
                            })
                            .collect();
                        let list = List::new(items).block(
                            Block::default()
                                .title(" Skills [↑↓] select [Tab/Enter] insert [Esc] cancel ")
                                .borders(Borders::ALL)
                                .border_style(Style::default().fg(Color::Cyan)),
                        );
                        frame.render_widget(list, dropdown_area);
                    }
                }

                // Task reference search dropdown
                if let Some(ref search) = state.task_ref_search {
                    if !search.matches.is_empty() {
                        let dropdown_height = (search.matches.len() as u16 + 2).min(12);
                        let dropdown_area = Rect {
                            x: input_area.x + 2,
                            y: input_area.y + input_area.height,
                            width: input_area.width.saturating_sub(4),
                            height: dropdown_height,
                        };
                        let dropdown_area = if dropdown_area.y + dropdown_area.height > area.height
                        {
                            Rect {
                                y: input_area.y.saturating_sub(dropdown_height),
                                ..dropdown_area
                            }
                        } else {
                            dropdown_area
                        };

                        frame.render_widget(Clear, dropdown_area);
                        let task_sel_color = hex_to_color(&state.config.theme.color_selected);
                        let accent = hex_to_color(&state.config.theme.color_accent);
                        let dim = hex_to_color(&state.config.theme.color_dimmed);
                        let items: Vec<ListItem> = search
                            .matches
                            .iter()
                            .enumerate()
                            .map(|(i, (_, title, status))| {
                                let (style, title_style, status_style) = if i == search.selected {
                                    let s = Style::default().bg(task_sel_color).fg(Color::Black);
                                    (s, s, s)
                                } else {
                                    (
                                        Style::default(),
                                        Style::default().fg(accent),
                                        Style::default().fg(dim),
                                    )
                                };
                                let status_badge = format!("  [{}]", status.as_str());
                                ListItem::new(Line::from(vec![
                                    Span::styled(format!(" {}", title), title_style),
                                    Span::styled(status_badge, status_style),
                                ]))
                                .style(style)
                            })
                            .collect();
                        let list = List::new(items).block(
                            Block::default()
                                .title(" Tasks [↑↓] select [Tab/Enter] insert [Esc] cancel ")
                                .borders(Borders::ALL)
                                .border_style(Style::default().fg(Color::Cyan)),
                        );
                        frame.render_widget(list, dropdown_area);
                    }
                }
            }
        }

        // Shell popup overlay
        if let Some(popup) = &state.shell_popup {
            Self::draw_shell_popup(popup, frame, area, &state.config.theme);
        }

        // Task search popup
        if let Some(ref search) = state.task_search {
            let popup_area = centered_rect(50, 50, area);
            frame.render_widget(Clear, popup_area);

            let popup_chunks = Layout::default()
                .direction(Direction::Vertical)
                .constraints([
                    Constraint::Length(3), // Search input
                    Constraint::Min(0),    // Results
                ])
                .split(popup_area);

            let selected_color = hex_to_color(&state.config.theme.color_selected);

            // Search input
            let input = Paragraph::new(format!(" 🔍 {}█", search.query))
                .style(Style::default().fg(selected_color))
                .block(
                    Block::default()
                        .title(" Search Tasks ")
                        .borders(Borders::ALL)
                        .border_style(Style::default().fg(selected_color)),
                );
            frame.render_widget(input, popup_chunks[0]);

            // Results list
            let items: Vec<ListItem> = search
                .matches
                .iter()
                .enumerate()
                .map(|(i, (_, title, status))| {
                    let is_selected = i == search.selected;
                    let style = if is_selected {
                        Style::default().bg(selected_color).fg(Color::Black)
                    } else {
                        Style::default().fg(Color::White)
                    };

                    let status_icon = match status {
                        TaskStatus::Backlog => "📋",
                        TaskStatus::Planning => "📝",
                        TaskStatus::Running => "⚡",
                        TaskStatus::Review => "👀",
                        TaskStatus::Done => "✅",
                    };

                    ListItem::new(format!(" {} {} ", status_icon, title)).style(style)
                })
                .collect();

            let list = List::new(items).block(
                Block::default()
                    .title(" [↑↓] select [Enter] jump [Esc] cancel ")
                    .borders(Borders::ALL)
                    .border_style(
                        Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
                    ),
            );
            frame.render_widget(list, popup_chunks[1]);
        }

        // PR confirmation popup
        if let Some(ref popup) = state.pr_confirm_popup {
            let popup_area = centered_rect(60, 60, area);
            frame.render_widget(Clear, popup_area);

            // Show loading state while generating
            if popup.generating {
                let main_block = Block::default()
                    .title(" Create Pull Request ")
                    .borders(Borders::ALL)
                    .border_style(
                        Style::default().fg(hex_to_color(&state.config.theme.color_selected)),
                    );
                frame.render_widget(main_block, popup_area);

                // Spinner animation based on frame count
                let spinner_chars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
                let spinner_idx = (std::time::SystemTime::now()
                    .duration_since(std::time::UNIX_EPOCH)
                    .unwrap_or_default()
                    .as_millis()
                    / 100) as usize
                    % spinner_chars.len();
                let spinner = spinner_chars[spinner_idx];

                let agent_name = state.config.default_agent.clone();
                let loading_text = format!(
                    "{} Generating PR description with {}...",
                    spinner, agent_name
                );
                let loading = Paragraph::new(loading_text)
                    .style(Style::default().fg(Color::Cyan))
                    .alignment(ratatui::layout::Alignment::Center);

                // Center vertically within the popup
                let inner = popup_area.inner(ratatui::layout::Margin {
                    horizontal: 2,
                    vertical: popup_area.height.saturating_sub(3) / 2,
                });
                frame.render_widget(loading, inner);
            } else {
                let popup_chunks = Layout::default()
                    .direction(Direction::Vertical)
                    .constraints([
                        Constraint::Length(3), // Title input
                        Constraint::Min(0),    // Body input
                        Constraint::Length(1), // Help line
                    ])
                    .margin(1)
                    .split(popup_area);

                // Main border
                let main_block = Block::default()
                    .title(" Create Pull Request ")
                    .borders(Borders::ALL)
                    .border_style(
                        Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)),
                    );
                frame.render_widget(main_block, popup_area);

                // Title input
                let title_style = if popup.editing_title {
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected))
                } else {
                    Style::default().fg(Color::White)
                };
                let title_border = if popup.editing_title {
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected))
                } else {
                    Style::default().fg(hex_to_color(&state.config.theme.color_dimmed))
                };
                let title_cursor = if popup.editing_title { "█" } else { "" };
                let title_input = Paragraph::new(format!("{}{}", popup.pr_title, title_cursor))
                    .style(title_style)
                    .block(
                        Block::default()
                            .title(" Title ")
                            .borders(Borders::ALL)
                            .border_style(title_border),
                    );
                frame.render_widget(title_input, popup_chunks[0]);

                // Body input
                let body_style = if !popup.editing_title {
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected))
                } else {
                    Style::default().fg(Color::White)
                };
                let body_border = if !popup.editing_title {
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected))
                } else {
                    Style::default().fg(hex_to_color(&state.config.theme.color_dimmed))
                };
                let body_cursor = if !popup.editing_title { "█" } else { "" };
                let body_input = Paragraph::new(format!("{}{}", popup.pr_body, body_cursor))
                    .style(body_style)
                    .wrap(Wrap { trim: false })
                    .block(
                        Block::default()
                            .title(" Description ")
                            .borders(Borders::ALL)
                            .border_style(body_border),
                    );
                frame.render_widget(body_input, popup_chunks[1]);

                // Help line
                let help = Paragraph::new(" [Tab] switch field  [Ctrl+s] create PR  [Esc] cancel ")
                    .style(Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)));
                frame.render_widget(help, popup_chunks[2]);
            }
        }

        // PR creation status popup (loading/success/error)
        if let Some(ref popup) = state.pr_status_popup {
            let popup_area = centered_rect(50, 20, area);
            frame.render_widget(Clear, popup_area);

            let (title, border_color) = match popup.status {
                PrCreationStatus::Creating => (
                    " Creating Pull Request ",
                    hex_to_color(&state.config.theme.color_selected),
                ),
                PrCreationStatus::Pushing => (
                    " Pushing Changes ",
                    hex_to_color(&state.config.theme.color_selected),
                ),
                PrCreationStatus::Success => (" Pull Request Created ", Color::Green),
                PrCreationStatus::Error => (" Error Creating PR ", Color::Red),
            };

            let main_block = Block::default()
                .title(title)
                .borders(Borders::ALL)
                .border_style(Style::default().fg(border_color));
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 2,
            });

            match popup.status {
                PrCreationStatus::Creating => {
                    let spinner_chars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
                    let spinner_idx = (std::time::SystemTime::now()
                        .duration_since(std::time::UNIX_EPOCH)
                        .unwrap_or_default()
                        .as_millis()
                        / 100) as usize
                        % spinner_chars.len();
                    let spinner = spinner_chars[spinner_idx];

                    let text = format!("{} Pushing branch and creating PR...", spinner);
                    let content = Paragraph::new(text)
                        .style(Style::default().fg(Color::Cyan))
                        .alignment(ratatui::layout::Alignment::Center);
                    frame.render_widget(content, inner);
                }
                PrCreationStatus::Pushing => {
                    let spinner_chars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
                    let spinner_idx = (std::time::SystemTime::now()
                        .duration_since(std::time::UNIX_EPOCH)
                        .unwrap_or_default()
                        .as_millis()
                        / 100) as usize
                        % spinner_chars.len();
                    let spinner = spinner_chars[spinner_idx];

                    let text = format!("{} PR exists. Pushing changes...", spinner);
                    let content = Paragraph::new(text)
                        .style(Style::default().fg(Color::Cyan))
                        .alignment(ratatui::layout::Alignment::Center);
                    frame.render_widget(content, inner);
                }
                PrCreationStatus::Success => {
                    let url = popup.pr_url.as_deref().unwrap_or("unknown");
                    // Check if this was a push to existing PR or new PR creation
                    let message = if url.starts_with("http") {
                        format!("Success!\n\n{}\n\n[Enter] to close", url)
                    } else {
                        format!("{}\n\n[Enter] to close", url)
                    };
                    let content = Paragraph::new(message)
                        .style(Style::default().fg(Color::Green))
                        .alignment(ratatui::layout::Alignment::Center);
                    frame.render_widget(content, inner);
                }
                PrCreationStatus::Error => {
                    let err = popup.error_message.as_deref().unwrap_or("Unknown error");
                    let text = format!("Failed to create PR:\n\n{}\n\n[Enter] to close", err);
                    let content = Paragraph::new(text)
                        .style(Style::default().fg(Color::Red))
                        .alignment(ratatui::layout::Alignment::Center)
                        .wrap(Wrap { trim: false });
                    frame.render_widget(content, inner);
                }
            }
        }

        // Done confirmation popup
        if let Some(ref popup) = state.done_confirm_popup {
            let popup_area = centered_rect(50, 25, area);
            frame.render_widget(Clear, popup_area);

            let main_block = Block::default()
                .title(" Move to Done? ")
                .borders(Borders::ALL)
                .border_style(
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected)),
                );
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 2,
            });
            let text = match popup.pr_state {
                DoneConfirmPrState::Open => format!(
                    "PR #{} is still open.\n\nAre you sure you want to move this task to Done?\n\nWorktree will be deleted, tmux coding session killed.\nBranch kept locally.\n\n[y] Yes, move to Done    [n/Esc] Cancel",
                    popup.pr_number
                ),
                DoneConfirmPrState::Merged => format!(
                    "PR #{} was merged.\n\nWorktree will be deleted, tmux coding session killed.\nBranch kept locally.\n\n[y] Yes, move to Done    [n/Esc] Cancel",
                    popup.pr_number
                ),
                DoneConfirmPrState::Closed => format!(
                    "PR #{} was closed.\n\nWorktree will be deleted, tmux coding session killed.\nBranch kept locally.\n\n[y] Yes, move to Done    [n/Esc] Cancel",
                    popup.pr_number
                ),
                DoneConfirmPrState::Unknown => format!(
                    "PR #{} state unknown.\n\nAre you sure you want to move this task to Done?\n\nWorktree will be deleted, tmux coding session killed.\nBranch kept locally.\n\n[y] Yes, move to Done    [n/Esc] Cancel",
                    popup.pr_number
                ),
                DoneConfirmPrState::UncommittedChanges => String::from(
                    "There are uncommitted changes in the worktree.\n\nAre you sure you want to move this task to Done?\n\nUncommitted changes will be lost.\nWorktree will be deleted, tmux coding session killed.\nBranch kept locally.\n\n[y] Yes, move to Done    [n/Esc] Cancel"
                ),
            };
            let content = Paragraph::new(text)
                .style(Style::default().fg(Color::White))
                .alignment(ratatui::layout::Alignment::Center)
                .wrap(Wrap { trim: false });
            frame.render_widget(content, inner);
        }

        // Move confirmation popup (phase incomplete)
        if let Some(ref popup) = state.move_confirm_popup {
            let popup_area = centered_rect(50, 20, area);
            frame.render_widget(Clear, popup_area);

            let phase_name = match popup.from_status {
                TaskStatus::Planning => "Planning",
                TaskStatus::Running => "Running",
                TaskStatus::Review => "Review",
                _ => "Current",
            };
            let main_block = Block::default()
                .title(format!(" {} Phase Incomplete ", phase_name))
                .borders(Borders::ALL)
                .border_style(
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected)),
                );
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 2,
            });
            let text = format!(
                "The agent is still working and the {} artifact\nhas not been created yet.\n\nAre you sure you want to move this task forward?\n\n[y] Yes, move    [n/Esc] Cancel",
                phase_name.to_lowercase()
            );
            let content = Paragraph::new(text)
                .style(Style::default().fg(Color::White))
                .alignment(ratatui::layout::Alignment::Center)
                .wrap(Wrap { trim: false });
            frame.render_widget(content, inner);
        }

        // Delete confirmation popup
        if let Some(ref popup) = state.delete_confirm_popup {
            let popup_area = centered_rect(50, 25, area);
            frame.render_widget(Clear, popup_area);

            let main_block = Block::default()
                .title(" Delete Task? ")
                .borders(Borders::ALL)
                .border_style(Style::default().fg(Color::Red));
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 2,
            });
            let text = format!(
                "Are you sure you want to delete:\n\n\"{}\"\n\nThis will also remove the worktree and tmux session.\n\n[y] Yes, delete    [n/Esc] Cancel",
                popup.task_title
            );
            let content = Paragraph::new(text)
                .style(Style::default().fg(Color::White))
                .alignment(ratatui::layout::Alignment::Center)
                .wrap(Wrap { trim: false });
            frame.render_widget(content, inner);
        }

        // Review confirmation popup (ask if user wants to create PR)
        if let Some(ref popup) = state.review_confirm_popup {
            let popup_area = centered_rect(50, 25, area);
            frame.render_widget(Clear, popup_area);

            let main_block = Block::default()
                .title(" Move to Review ")
                .borders(Borders::ALL)
                .border_style(
                    Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)),
                );
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 2,
            });
            let text = format!(
                "Moving task to Review:\n\n\"{}\"\n\nDo you want to create a Pull Request?\n\n[y] Yes, create PR    [n] No, just move    [Esc] Cancel",
                popup.task_title
            );
            let content = Paragraph::new(text)
                .style(Style::default().fg(Color::White))
                .alignment(ratatui::layout::Alignment::Center)
                .wrap(Wrap { trim: false });
            frame.render_widget(content, inner);
        }

        // Trust confirmation popup
        if let Some(ref popup) = state.trust_confirm_popup {
            // Sized to the content. At a fixed 30% height the answer line fell
            // off the bottom as soon as a project declared two fields — a
            // consent dialog that hides how to answer it.
            let path = popup.project_path.display().to_string();
            let widest = popup
                .dangerous
                .iter()
                .map(|(f, v)| f.len() + v.chars().count() + 5)
                .chain(std::iter::once(path.chars().count()))
                .max()
                .unwrap_or(60)
                .max(52);
            let width = (widest as u16 + 6).min(area.width.saturating_sub(4));
            // path + intro + blank + heading + fields + blank + answer, then
            // borders and the vertical margin.
            let rows = 4 + popup.dangerous.len().max(1) as u16 + 2;
            let height = (rows + 4).min(area.height.saturating_sub(2));
            let popup_area = Rect {
                x: area.x + area.width.saturating_sub(width) / 2,
                y: area.y + area.height.saturating_sub(height) / 2,
                width,
                height,
            };
            frame.render_widget(Clear, popup_area);

            let main_block = Block::default()
                .title(" Untrusted Project Config ")
                .borders(Borders::ALL)
                .border_style(Style::default().fg(Color::Yellow));
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 1,
            });
            // Left-aligned, and showing the actual values: this is a consent
            // dialog, and a centred summary of "dangerous fields" tells the
            // user nothing about what would run.
            let mut lines: Vec<Line<'static>> = vec![
                Line::from(Span::styled(
                    format!("{}", popup.project_path.display()),
                    Style::default().fg(Color::White).bold(),
                )),
                Line::from(Span::styled(
                    "ships an .agtx/config.toml agtx has not seen before.".to_string(),
                    Style::default().fg(Color::White),
                )),
                Line::from(String::new()),
            ];
            if popup.dangerous.is_empty() {
                lines.push(Line::from(Span::styled(
                    "It declares no scripts or file copies.".to_string(),
                    Style::default().fg(Color::White),
                )));
            } else {
                lines.push(Line::from(Span::styled(
                    "Trusting it lets agtx run:".to_string(),
                    Style::default().fg(Color::White),
                )));
                for (field, value) in &popup.dangerous {
                    lines.push(Line::from(vec![
                        Span::styled(
                            format!("  {field} = "),
                            Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
                        ),
                        Span::styled(value.clone(), Style::default().fg(Color::Yellow)),
                    ]));
                }
            }
            lines.push(Line::from(String::new()));
            lines.push(Line::from(Span::styled(
                "[y] trust and enable    [n] leave disabled".to_string(),
                Style::default().fg(hex_to_color(&state.config.theme.color_selected)),
            )));

            let content = Paragraph::new(Text::from(lines))
                .style(Style::default().fg(Color::White))
                .wrap(Wrap { trim: false });
            frame.render_widget(content, inner);
        }

        // Update popup ([u])
        if let Some(ref popup) = state.update_popup {
            let popup_area = centered_rect(60, 30, area);
            frame.render_widget(Clear, popup_area);

            let main_block = Block::default()
                .title(" Update Available ")
                .borders(Borders::ALL)
                .border_style(
                    Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)),
                );
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 1,
            });

            let selected = hex_to_color(&state.config.theme.color_selected);
            let dimmed = hex_to_color(&state.config.theme.color_dimmed);
            let mut lines: Vec<Line> = vec![
                Line::from(""),
                Line::from(vec![
                    Span::styled("  current ", Style::default().fg(dimmed)),
                    Span::styled(popup.info.current.to_string(), Style::default()),
                    Span::styled("  →  latest ", Style::default().fg(dimmed)),
                    Span::styled(
                        popup.info.latest.to_string(),
                        Style::default().fg(selected).add_modifier(Modifier::BOLD),
                    ),
                ]),
            ];
            if !popup.info.html_url.is_empty() {
                lines.push(Line::from(""));
                lines.push(Line::from(Span::styled(
                    format!("  {}", popup.info.html_url),
                    Style::default().fg(dimmed),
                )));
            }
            lines.push(Line::from(""));
            match (&popup.status, popup.installing) {
                (Some(status), _) => lines.push(Line::from(Span::styled(
                    format!("  {}", status),
                    Style::default().fg(selected),
                ))),
                (None, true) => lines.push(Line::from(Span::styled(
                    "  installing…",
                    Style::default().fg(selected),
                ))),
                (None, false) => lines.push(Line::from(Span::styled(
                    "  [Enter] install    [Esc] close",
                    Style::default().fg(dimmed),
                ))),
            }
            let content = Paragraph::new(lines).wrap(Wrap { trim: false });
            frame.render_widget(content, inner);
        }

        // Plugin selection popup
        if let Some(ref popup) = state.plugin_select_popup {
            let popup_area = centered_rect(50, 40, area);
            frame.render_widget(Clear, popup_area);

            let main_block = Block::default()
                .title(" Select Workflow Plugin ")
                .borders(Borders::ALL)
                .border_style(
                    Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)),
                );
            frame.render_widget(main_block, popup_area);

            let inner = popup_area.inner(ratatui::layout::Margin {
                horizontal: 2,
                vertical: 1,
            });
            let mut lines: Vec<Line> = Vec::new();

            for (i, opt) in popup.options.iter().enumerate() {
                let is_selected = i == popup.selected;
                let marker = if is_selected { "> " } else { "  " };
                let check = if opt.active { " ✓" } else { "" };

                let name_style = if is_selected {
                    Style::default()
                        .fg(hex_to_color(&state.config.theme.color_selected))
                        .add_modifier(Modifier::BOLD)
                } else {
                    Style::default().fg(hex_to_color(&state.config.theme.color_text))
                };

                lines.push(Line::from(vec![
                    Span::styled(marker, name_style),
                    Span::styled(&opt.label, name_style),
                    Span::styled(check, Style::default().fg(Color::Green)),
                ]));

                let desc_style =
                    Style::default().fg(hex_to_color(&state.config.theme.color_description));
                lines.push(Line::from(Span::styled(
                    format!("  {}", opt.description),
                    desc_style,
                )));
                lines.push(Line::from(""));
            }

            lines.push(Line::from(Span::styled(
                "  [Enter] select  [Esc] cancel",
                Style::default().fg(hex_to_color(&state.config.theme.color_dimmed)),
            )));

            let content = Paragraph::new(lines);
            frame.render_widget(content, inner);
        }

        // The `?` overlay
        if let Some(scroll) = state.help_scroll {
            draw_help(state, scroll, frame, area);
        }

        // The config editor
        if let Some(ref editor) = state.config_editor {
            draw_config_editor(state, editor, frame, area);
        }

        // Git diff popup
        if let Some(ref popup) = state.diff_popup {
            let popup_area = centered_rect(80, 80, area);
            frame.render_widget(Clear, popup_area);

            let popup_chunks = Layout::default()
                .direction(Direction::Vertical)
                .constraints([
                    Constraint::Length(1), // Title bar
                    Constraint::Min(0),    // Diff content
                    Constraint::Length(1), // Footer
                ])
                .split(popup_area);

            // Title bar
            let title = format!(" Diff: {} ", popup.task_title);
            let title_bar = Paragraph::new(title).style(
                Style::default()
                    .fg(Color::Black)
                    .bg(hex_to_color(&state.config.theme.color_popup_header)),
            );
            frame.render_widget(title_bar, popup_chunks[0]);

            // Diff content with syntax highlighting
            let lines: Vec<Line> = popup
                .diff_content
                .lines()
                .skip(popup.scroll_offset)
                .take(popup_chunks[1].height.saturating_sub(2) as usize)
                .map(|line| {
                    let style = if line.starts_with('+') && !line.starts_with("+++") {
                        Style::default().fg(Color::Green)
                    } else if line.starts_with('-') && !line.starts_with("---") {
                        Style::default().fg(Color::Red)
                    } else if line.starts_with("@@") {
                        Style::default().fg(Color::Cyan)
                    } else if line.starts_with("diff ") || line.starts_with("index ") {
                        Style::default().fg(hex_to_color(&state.config.theme.color_selected))
                    } else {
                        Style::default().fg(Color::White)
                    };
                    Line::from(Span::styled(line, style))
                })
                .collect();

            let diff_content =
                Paragraph::new(lines).block(Block::default().borders(Borders::ALL).border_style(
                    Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)),
                ));
            frame.render_widget(diff_content, popup_chunks[1]);

            // Footer with scroll info
            let total_lines = popup.diff_content.lines().count();
            let footer_text = format!(
                " [j/k] scroll  [d/u] page  [g/G] top/bottom  [q/Esc] close  ({}/{}) ",
                popup.scroll_offset + 1,
                total_lines
            );
            let footer = Paragraph::new(footer_text).style(
                Style::default()
                    .fg(Color::Black)
                    .bg(hex_to_color(&state.config.theme.color_dimmed)),
            );
            frame.render_widget(footer, popup_chunks[2]);
        }

        // Dependency-graph overlay
        if let Some(ref popup) = state.dep_graph_popup {
            Self::draw_dependency_graph(popup, frame, area, &state.config.theme);
        }

        // Mobile overlay
        if let Some(ref popup) = state.mobile_popup {
            Self::draw_mobile_popup(
                popup,
                state.serve_session.as_ref(),
                frame,
                area,
                &state.config.theme,
            );
        }
    }

    /// Render the dependency-graph overlay: topological columns of task cards,
    /// with unblocked Backlog tasks in green and marked tasks reversed.
    fn draw_dependency_graph(
        popup: &DepGraphPopup,
        frame: &mut Frame,
        area: Rect,
        theme: &ThemeConfig,
    ) {
        let popup_area = centered_rect(90, 90, area);
        frame.render_widget(Clear, popup_area);

        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([
                Constraint::Length(1), // Title bar
                Constraint::Min(0),    // Columns
                Constraint::Length(1), // Footer
            ])
            .split(popup_area);

        // Title bar.
        let unblocked_count = popup.graph.nodes.iter().filter(|n| n.unblocked).count();
        let title = format!(
            " Dependency Graph — {} tasks, {} unblocked ",
            popup.graph.nodes.len(),
            unblocked_count
        );
        let title_bar = Paragraph::new(title).style(
            Style::default()
                .fg(Color::Black)
                .bg(hex_to_color(&theme.color_popup_header)),
        );
        frame.render_widget(title_bar, chunks[0]);

        let body = chunks[1];
        let level_count = popup.graph.level_count();
        if level_count == 0 {
            let empty = Paragraph::new("No tasks").block(
                Block::default()
                    .borders(Borders::ALL)
                    .border_style(Style::default().fg(hex_to_color(&theme.color_popup_border))),
            );
            frame.render_widget(empty, body);
        } else {
            // Fit as many columns as possible at a fixed minimum width, starting
            // from the horizontal scroll offset.
            const COL_WIDTH: u16 = 26;
            let max_visible = (body.width / COL_WIDTH).max(1) as usize;
            // Record the viewport width so the key handler can keep the cursor in
            // view when scrolling horizontally.
            popup.visible_levels.set(max_visible);
            // Honor the stored offset, but always keep the selected node's level
            // on screen — covers the initial open (cursor may start in a far
            // level) and every navigation (the key handler just moves the cursor
            // and lets this clamp re-scroll).
            let sel_level = popup.graph.nodes.get(popup.selected).map_or(0, |n| n.level);
            let start = clamp_scroll_to_selected(
                popup.scroll_levels.get(),
                sel_level,
                max_visible,
                level_count,
            );
            // Persist the corrected offset so the footer hint stays in sync.
            popup.scroll_levels.set(start);
            let visible_cols = max_visible.min(level_count - start);
            let end = (start + visible_cols).min(level_count);

            let col_constraints: Vec<Constraint> = (start..end)
                .map(|_| Constraint::Ratio(1, (end - start) as u32))
                .collect();
            let col_areas = Layout::default()
                .direction(Direction::Horizontal)
                .constraints(col_constraints)
                .split(body);

            for (slot, level) in (start..end).enumerate() {
                let col_area = col_areas[slot];
                Self::draw_dep_level_column(popup, frame, col_area, level, theme);
            }
        }

        // Footer.
        let scroll_hint = if level_count > 0 {
            let scroll = popup.scroll_levels.get();
            let first = scroll + 1;
            let last = (scroll + popup.visible_levels.get()).min(level_count);
            format!(" cols {first}-{last}/{level_count} ")
        } else {
            String::new()
        };
        let footer_text = format!(
            " [hjkl] move  [Space] mark  [a] all unblocked  [c] clear  [Enter] move {} →research  [q] close {}",
            popup.marked.len(),
            scroll_hint
        );
        let footer = Paragraph::new(footer_text).style(
            Style::default()
                .fg(Color::Black)
                .bg(hex_to_color(&theme.color_dimmed)),
        );
        frame.render_widget(footer, chunks[2]);
    }

    /// Render a single topological column (level) of the dependency graph.
    fn draw_dep_level_column(
        popup: &DepGraphPopup,
        frame: &mut Frame,
        area: Rect,
        level: usize,
        theme: &ThemeConfig,
    ) {
        let Some(indices) = popup.graph.levels.get(level) else {
            return;
        };

        // Column header.
        let header = Paragraph::new(format!("Level {level}"))
            .style(
                Style::default()
                    .fg(hex_to_color(&theme.color_column_header))
                    .bold(),
            )
            .alignment(Alignment::Center);
        let header_area = Rect { height: 1, ..area };
        frame.render_widget(header, header_area);

        // Each card is 4 rows tall (border + title + status + hint).
        const CARD_HEIGHT: u16 = 4;
        let mut y = area.y + 1;
        for &idx in indices {
            if y + CARD_HEIGHT > area.y + area.height {
                break;
            }
            let Some(node) = popup.graph.nodes.get(idx) else {
                continue;
            };
            let card_area = Rect {
                x: area.x,
                y,
                width: area.width,
                height: CARD_HEIGHT,
            };
            let is_cursor = idx == popup.selected;
            let is_marked = popup.marked.contains(&node.task_id);

            // Choose the node color by status / unblocked state.
            let base_color = if node.unblocked {
                Color::Green
            } else if matches!(node.status, TaskStatus::Done) {
                hex_to_color(&theme.color_dimmed)
            } else if matches!(node.status, TaskStatus::Backlog) {
                // Blocked Backlog (deps not satisfied).
                hex_to_color(&theme.color_dimmed)
            } else {
                hex_to_color(&theme.color_normal)
            };

            let border_style = if is_cursor {
                Style::default().fg(hex_to_color(&theme.color_selected))
            } else {
                Style::default().fg(base_color)
            };
            let border_type = if is_cursor {
                BorderType::Thick
            } else {
                BorderType::Plain
            };

            let block = Block::default()
                .borders(Borders::ALL)
                .border_style(border_style)
                .border_type(border_type);
            let inner = block.inner(card_area);
            frame.render_widget(block, card_area);

            // Marker glyph: ✓ done, ⊘ blocked Backlog, ● unblocked, else space.
            let marker = if node.unblocked {
                "\u{25cf} " // ●
            } else if matches!(node.status, TaskStatus::Done) {
                "\u{2713} " // ✓
            } else if matches!(node.status, TaskStatus::Backlog) {
                "\u{2298} " // ⊘ blocked
            } else {
                "  "
            };

            let mut title_style = Style::default().fg(base_color);
            if is_marked {
                title_style = title_style.add_modifier(Modifier::REVERSED).bold();
            } else if is_cursor {
                title_style = title_style.bold();
            }

            // Title line (marker + truncated title).
            let title_text = truncate_str(&node.title, inner.width.saturating_sub(2) as usize);
            let title_line = Line::from(vec![
                Span::styled(marker, title_style),
                Span::styled(title_text, title_style),
            ]);
            // Status line.
            let status_line = Line::from(Span::styled(
                format!("[{}]", node.status.as_str()),
                Style::default().fg(hex_to_color(&theme.color_description)),
            ));
            // Dependency hint line.
            let hint = if node.dep_titles.is_empty() {
                String::new()
            } else {
                let joined = node.dep_titles.join(", ");
                format!(
                    "\u{2190} {}",
                    truncate_str(&joined, inner.width.saturating_sub(2) as usize)
                )
            };
            let hint_line = Line::from(Span::styled(
                hint,
                Style::default().fg(hex_to_color(&theme.color_dimmed)),
            ));

            let para = Paragraph::new(vec![title_line, status_line, hint_line]);
            frame.render_widget(para, inner);

            y += CARD_HEIGHT;
        }
    }

    fn draw_shell_popup(popup: &ShellPopup, frame: &mut Frame, area: Rect, theme: &ThemeConfig) {
        let popup_area = if popup.fullscreen {
            area
        } else {
            centered_rect_fixed_width(SHELL_POPUP_WIDTH, SHELL_POPUP_HEIGHT_PERCENT, area)
        };

        // Parse ANSI escape sequences for colors
        // Parsed by the watcher, and borrowed rather than cloned: only the rows
        // that fit on screen are copied, not the whole cached pane.
        let styled_lines = popup.cached_lines.as_slice();

        // Build colors from theme
        let colors = shell_popup::ShellPopupColors {
            border: hex_to_color(&theme.color_popup_border),
            header_fg: Color::Black,
            header_bg: hex_to_color(&theme.color_popup_header),
            footer_fg: Color::Black,
            footer_bg: hex_to_color(&theme.color_dimmed),
            escalation_fg: Color::Black,
            escalation_bg: Color::Yellow,
        };

        shell_popup::render_shell_popup(popup, frame, popup_area, styled_lines, &colors);
    }

    fn draw_task_card(
        frame: &mut Frame,
        task: &Task,
        area: Rect,
        is_selected: bool,
        theme: &ThemeConfig,
        phase_status: Option<&(PhaseStatus, Instant)>,
        deps_blocked: bool,
    ) {
        let styles = TuiStyles::from_theme(theme);
        let border_style = if is_selected {
            Style::default().fg(styles.selected)
        } else {
            Style::default().fg(styles.dimmed)
        };

        let title_style = if is_selected {
            Style::default()
                .fg(hex_to_color(&theme.color_selected))
                .bold()
        } else {
            Style::default().fg(hex_to_color(&theme.color_text)).bold()
        };

        // Truncate title to fit (char-safe for UTF-8)
        let max_title_len = area.width.saturating_sub(4) as usize;
        let title: String = if task.title.chars().count() > max_title_len {
            let truncated: String = task
                .title
                .chars()
                .take(max_title_len.saturating_sub(3))
                .collect();
            format!("{}...", truncated)
        } else {
            task.title.clone()
        };

        let card_block = Block::default()
            .borders(Borders::ALL)
            .border_style(border_style)
            .border_type(if is_selected {
                BorderType::Rounded
            } else {
                BorderType::Plain
            });
        let block_inner = card_block.inner(area);
        frame.render_widget(card_block, area);
        let inner = Rect {
            x: block_inner.x.saturating_add(1),
            width: block_inner.width.saturating_sub(2),
            ..block_inner
        };

        // Title line with optional phase indicator
        let show_indicator = matches!(
            task.status,
            TaskStatus::Planning | TaskStatus::Running | TaskStatus::Review
        ) || (task.status == TaskStatus::Backlog
            && task.session_name.is_some());

        if show_indicator {
            let indicator = match phase_status {
                Some((PhaseStatus::Ready, _)) => {
                    Span::styled("\u{2713} ", Style::default().fg(Color::Green))
                }
                // Static, not a spinner. An animated frame is a redraw of the
                // whole board, and on an otherwise idle board it was the *only*
                // thing forcing one — ten a second, forever, to rotate a glyph.
                // The card already says a task is running; the motion added
                // nothing that the icon does not.
                Some((PhaseStatus::Working, _)) => {
                    Span::styled("\u{25b6} ", Style::default().fg(Color::Yellow))
                }
                Some((PhaseStatus::Blocked, _)) => Span::styled(
                    "? ",
                    Style::default()
                        .fg(hex_to_color(&theme.color_accent))
                        .bold(),
                ),
                Some((PhaseStatus::Idle, _)) => Span::styled(
                    "\u{23f8} ",
                    Style::default().fg(hex_to_color(&theme.color_dimmed)),
                ),
                Some((PhaseStatus::Exited, _)) => {
                    Span::styled("\u{2717} ", Style::default().fg(Color::Red))
                }
                None => Span::raw(""),
            };
            // Escalation warning indicator
            let warn_span = if task.escalation_note.is_some() {
                Span::styled(
                    "\u{26a0} ",
                    Style::default()
                        .fg(hex_to_color(&theme.color_accent))
                        .bold(),
                )
            } else {
                Span::raw("")
            };
            let title_spans =
                Line::from(vec![indicator, warn_span, Span::styled(title, title_style)]);
            let title_line = Paragraph::new(title_spans);
            let title_area = Rect {
                x: inner.x,
                y: inner.y,
                width: inner.width,
                height: 1,
            };
            frame.render_widget(title_line, title_area);
        } else if deps_blocked {
            let lock_span = Span::styled(
                "\u{2298} ",
                Style::default().fg(hex_to_color(&theme.color_dimmed)),
            );
            let title_spans = Line::from(vec![lock_span, Span::styled(title, title_style)]);
            let title_line = Paragraph::new(title_spans);
            let title_area = Rect {
                x: inner.x,
                y: inner.y,
                width: inner.width,
                height: 1,
            };
            frame.render_widget(title_line, title_area);
        } else {
            let title_line = Paragraph::new(title).style(title_style);
            let title_area = Rect {
                x: inner.x,
                y: inner.y,
                width: inner.width,
                height: 1,
            };
            frame.render_widget(title_line, title_area);
        }

        // Footer line with a compact phase label and agent badge.
        let show_agent = task.status != TaskStatus::Backlog || task.session_name.is_some();
        let footer_height = if show_agent && inner.height > 2 {
            1u16
        } else {
            0u16
        };

        // Preview area (below title) - always show description
        if inner.height > 1 + footer_height {
            let preview_area = Rect {
                x: inner.x,
                y: inner.y + 1,
                width: inner.width,
                height: inner.height.saturating_sub(1 + footer_height),
            };

            // Show description or placeholder
            let preview_text = task.description.as_deref().unwrap_or("");

            // Truncate description to fit preview area
            let max_chars = (preview_area.width as usize) * (preview_area.height as usize);
            let truncated: String = if preview_text.chars().count() > max_chars {
                format!(
                    "{}...",
                    preview_text
                        .chars()
                        .take(max_chars.saturating_sub(3))
                        .collect::<String>()
                )
            } else {
                preview_text.to_string()
            };

            let preview = Paragraph::new(truncated)
                .style(Style::default().fg(styles.description))
                .wrap(Wrap { trim: true });
            frame.render_widget(preview, preview_area);
        }

        // Agent footer
        if footer_height > 0 {
            let footer_area = Rect {
                x: inner.x,
                y: inner.y + inner.height.saturating_sub(1),
                width: inner.width,
                height: 1,
            };
            // Pure white stays `Color::White` rather than becoming truecolor: it
            // is an ANSI palette entry, which a themed terminal renders as its
            // own white. Rgb(255,255,255) would override the user's theme.
            let to_color = |(r, g, b): (u8, u8, u8)| {
                if (r, g, b) == (255, 255, 255) {
                    Color::White
                } else {
                    Color::Rgb(r, g, b)
                }
            };
            let agent_style = match agent::spec(task.agent.as_str()) {
                Some(spec) => {
                    let style = Style::default().fg(to_color(spec.label_fg));
                    match spec.label_bg {
                        Some(bg) => style.bg(to_color(bg)),
                        None => style,
                    }
                }
                None => Style::default().fg(Color::White),
            };
            let phase_label = phase_status.map(|(status, _)| match status {
                PhaseStatus::Ready => "✓ Ready",
                PhaseStatus::Working => "● Working",
                PhaseStatus::Blocked => "? Blocked",
                PhaseStatus::Idle => "Ⅱ Idle",
                PhaseStatus::Exited => "× Exited",
            });
            let mut spans = Vec::new();
            if let Some(label) = phase_label {
                spans.push(Span::styled(label, styles.muted()));
            }
            let used: usize = spans.iter().map(|span| span.width()).sum();
            let agent = format!(" {} ", task.agent);
            let gap = (footer_area.width as usize).saturating_sub(used + agent.chars().count());
            spans.push(Span::raw(" ".repeat(gap)));
            spans.push(Span::styled(agent, agent_style));
            frame.render_widget(Paragraph::new(Line::from(spans)), footer_area);
        }
    }

    fn draw_sidebar(state: &AppState, frame: &mut Frame, area: Rect) {
        let styles = TuiStyles::from_theme(&state.config.theme);
        // Show projects from database
        let current_path = state
            .project_path
            .as_ref()
            .map(|p| p.to_string_lossy().to_string());

        let items: Vec<ListItem> = state
            .projects
            .iter()
            .enumerate()
            .map(|(i, project)| {
                let is_selected = i == state.selected_project && state.sidebar_focused;
                let is_current = current_path.as_ref() == Some(&project.path);

                let style = if is_selected {
                    Style::default()
                        .bg(hex_to_color(&state.config.theme.color_selected))
                        .fg(Color::Black)
                } else if is_current {
                    Style::default().fg(hex_to_color(&state.config.theme.color_selected))
                } else {
                    Style::default().fg(hex_to_color(&state.config.theme.color_text))
                };

                let marker = if is_current { "▌" } else { " " };
                ListItem::new(format!("{} {}", marker, project.name)).style(style)
            })
            .collect();

        let title_style = if state.sidebar_focused {
            Style::default().fg(styles.selected).bold()
        } else {
            Style::default().fg(styles.column_header).bold()
        };
        frame.render_widget(
            Paragraph::new(Line::from(vec![
                Span::styled(" PROJECTS", title_style),
                Span::styled(format!("  {}", state.projects.len()), styles.muted()),
            ])),
            Rect { height: 1, ..area },
        );
        frame.render_widget(
            Paragraph::new("─".repeat(area.width.saturating_sub(1) as usize)).style(styles.muted()),
            Rect {
                y: area.y + 1,
                height: 1,
                ..area
            },
        );
        frame.render_widget(
            List::new(items),
            Rect {
                x: area.x + 1,
                y: area.y + 3,
                width: area.width.saturating_sub(2),
                height: area.height.saturating_sub(3),
            },
        );
        frame.render_widget(
            Block::default()
                .borders(Borders::RIGHT)
                .border_style(styles.muted()),
            area,
        );
    }

    fn draw_dashboard(state: &AppState, frame: &mut Frame, area: Rect) {
        let dimmed_color = hex_to_color(&state.config.theme.color_dimmed);
        let selected_color = hex_to_color(&state.config.theme.color_selected);

        let chunks = Layout::default()
            .direction(Direction::Vertical)
            .constraints([
                Constraint::Length(10), // Logo + subtitle
                Constraint::Min(0),     // Project list or options
                Constraint::Length(3),  // Footer
            ])
            .split(area);

        // ASCII art logo — hardcoded gold to match docs/banner.svg
        let logo_color = Color::Rgb(234, 212, 154); // #ead49a
        let logo = vec![
            Line::from(""),
            Line::from(Span::styled(
                " █████╗  ██████╗████████╗██╗  ██╗",
                Style::default().fg(logo_color).bold(),
            )),
            Line::from(Span::styled(
                "██╔══██╗██╔════╝╚══██╔══╝╚██╗██╔╝",
                Style::default().fg(logo_color).bold(),
            )),
            Line::from(Span::styled(
                "███████║██║  ███╗  ██║    ╚███╔╝ ",
                Style::default().fg(logo_color).bold(),
            )),
            Line::from(Span::styled(
                "██╔══██║██║   ██║  ██║    ██╔██╗ ",
                Style::default().fg(logo_color).bold(),
            )),
            Line::from(Span::styled(
                "██║  ██║╚██████╔╝  ██║   ██╔╝ ██╗",
                Style::default().fg(logo_color).bold(),
            )),
            Line::from(Span::styled(
                "╚═╝  ╚═╝ ╚═════╝   ╚═╝   ╚═╝  ╚═╝",
                Style::default().fg(logo_color).bold(),
            )),
            Line::from(""),
            Line::from(Span::styled(
                "Autonomous multi-session spec-driven AI coding orchestration in the terminal",
                Style::default().fg(dimmed_color),
            )),
        ];
        // A user in dashboard mode is between projects, which is the best
        // moment there is to be told. The logo block has exactly one spare row.
        let mut logo = logo;
        if let Some(ref update) = state.update_available {
            logo.push(Line::from(vec![
                Span::styled(
                    format!("⬆ agtx {} available ", update.latest),
                    Style::default().fg(selected_color),
                ),
                Span::styled("[u]", Style::default().fg(dimmed_color)),
            ]));
        }
        let logo_widget = Paragraph::new(logo).alignment(Alignment::Center);
        frame.render_widget(logo_widget, chunks[0]);

        // Project list or options
        if state.show_project_list && !state.projects.is_empty() {
            let items: Vec<ListItem> = state
                .projects
                .iter()
                .enumerate()
                .map(|(i, project)| {
                    let is_selected = i == state.selected_project;
                    let style = if is_selected {
                        Style::default().bg(dimmed_color).fg(Color::White)
                    } else {
                        Style::default()
                    };
                    ListItem::new(format!("  {}", project.name)).style(style)
                })
                .collect();

            let list = List::new(items).block(
                Block::default()
                    .title(" Projects [j/k] navigate [Enter] open [Esc] back ")
                    .borders(Borders::ALL)
                    .border_style(Style::default().fg(selected_color)),
            );
            frame.render_widget(list, chunks[1]);
        } else {
            let options = Paragraph::new(
                "\n  [p] Open existing project\n  [n] Create new project in current directory\n",
            )
            .block(
                Block::default()
                    .title(" Options ")
                    .borders(Borders::ALL)
                    .border_style(Style::default().fg(dimmed_color)),
            );
            frame.render_widget(options, chunks[1]);
        }

        // Footer
        let footer_text = if state.update_available.is_some() {
            " [p] projects  [n] new project  [u] update  [q] quit "
        } else {
            " [p] projects  [n] new project  [q] quit "
        };
        let footer = Paragraph::new(footer_text)
            .style(Style::default().fg(dimmed_color))
            .block(Block::default().borders(Borders::ALL));
        frame.render_widget(footer, chunks[2]);
    }

    pub fn handle_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        // Handle PR status popup if open (loading/success/error)
        if let Some(ref popup) = self.state.pr_status_popup {
            // Only allow closing if not in Creating/Pushing state
            if popup.status != PrCreationStatus::Creating
                && popup.status != PrCreationStatus::Pushing
            {
                if matches!(key.code, KeyCode::Enter | KeyCode::Esc) {
                    self.state.pr_status_popup = None;
                }
            }
            return Ok(());
        }

        // Handle Move confirmation popup if open (phase incomplete)
        if self.state.move_confirm_popup.is_some() {
            return self.handle_move_confirm_key(key);
        }

        // Handle Done confirmation popup if open
        if self.state.done_confirm_popup.is_some() {
            return self.handle_done_confirm_key(key);
        }

        // Handle Delete confirmation popup if open
        if self.state.delete_confirm_popup.is_some() {
            return self.handle_delete_confirm_key(key);
        }

        // Handle Review confirmation popup if open
        if self.state.review_confirm_popup.is_some() {
            return self.handle_review_confirm_key(key);
        }

        // Handle update popup if open
        if self.state.update_popup.is_some() {
            return self.handle_update_popup_key(key);
        }

        // Handle trust confirmation popup if open
        if self.state.trust_confirm_popup.is_some() {
            return self.handle_trust_confirm_key(key);
        }

        // Handle diff popup if open
        if self.state.diff_popup.is_some() {
            return self.handle_diff_popup_key(key);
        }

        // Handle dependency-graph overlay if open
        if self.state.dep_graph_popup.is_some() {
            return self.handle_dep_graph_key(key);
        }

        // Handle the mobile overlay if open
        if self.state.mobile_popup.is_some() {
            return self.handle_mobile_key(key);
        }

        // Handle PR confirmation popup if open
        if self.state.pr_confirm_popup.is_some() {
            return self.handle_pr_confirm_key(key);
        }

        // Handle plugin selection popup if open
        if self.state.plugin_select_popup.is_some() {
            return self.handle_plugin_select_key(key);
        }

        // Handle the config editor if open
        if self.state.config_editor.is_some() {
            return self.handle_config_editor_key(key);
        }

        // Handle the help overlay if open
        if self.state.help_scroll.is_some() {
            return self.handle_help_key(key);
        }

        // Handle task search popup if open
        if self.state.task_search.is_some() {
            return self.handle_task_search_key(key);
        }

        // Handle shell popup if open
        if self.state.shell_popup.is_some() {
            return self.handle_shell_popup_key(key);
        }

        // Handle based on mode (Dashboard vs Project)
        match &self.state.mode {
            AppMode::Dashboard => self.handle_dashboard_key(key.code),
            AppMode::Project(_) if self.state.wizard.is_some() => self.handle_wizard_key(key),
            AppMode::Project(_) => {
                // Ctrl+f = open the selected task in the in-app fullscreen view.
                if key.code == KeyCode::Char('f')
                    && key
                        .modifiers
                        .contains(crossterm::event::KeyModifiers::CONTROL)
                {
                    self.open_selected_task_fullscreen()?;
                    return Ok(());
                }
                self.handle_normal_key(key.code)
            }
        }
    }

    fn handle_done_confirm_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        if let Some(popup) = self.state.done_confirm_popup.clone() {
            match key.code {
                KeyCode::Char('y') | KeyCode::Char('Y') => {
                    // Confirmed - force move to Done
                    self.state.done_confirm_popup = None;
                    self.force_move_to_done(&popup.task_id)?;
                }
                KeyCode::Char('n') | KeyCode::Char('N') | KeyCode::Esc => {
                    // Cancelled
                    self.state.done_confirm_popup = None;
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn handle_move_confirm_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        if self.state.move_confirm_popup.is_some() {
            match key.code {
                KeyCode::Char('y') | KeyCode::Char('Y') => {
                    self.state.move_confirm_popup = None;
                    self.state.skip_move_confirm = true;
                    self.move_task_right()?;
                    self.state.skip_move_confirm = false;
                }
                KeyCode::Char('n') | KeyCode::Char('N') | KeyCode::Esc => {
                    self.state.move_confirm_popup = None;
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn handle_delete_confirm_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        if let Some(popup) = self.state.delete_confirm_popup.clone() {
            match key.code {
                KeyCode::Char('y') | KeyCode::Char('Y') => {
                    // Confirmed - delete the task
                    self.state.delete_confirm_popup = None;
                    self.perform_delete_task(&popup.task_id)?;
                }
                KeyCode::Char('n') | KeyCode::Char('N') | KeyCode::Esc => {
                    // Cancelled
                    self.state.delete_confirm_popup = None;
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn handle_review_confirm_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        if let Some(popup) = self.state.review_confirm_popup.clone() {
            match key.code {
                KeyCode::Char('y') | KeyCode::Char('Y') => {
                    // Yes - create PR and move to review
                    self.state.review_confirm_popup = None;
                    self.move_running_to_review_with_pr(&popup.task_id)?;
                }
                KeyCode::Char('n') | KeyCode::Char('N') => {
                    // No - just move to review without PR
                    self.state.review_confirm_popup = None;
                    self.move_running_to_review_without_pr(&popup.task_id)?;
                }
                KeyCode::Esc => {
                    // Cancelled - don't move
                    self.state.review_confirm_popup = None;
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn open_update_popup(&mut self) {
        if let Some(info) = self.state.update_available.clone() {
            self.state.update_popup = Some(UpdatePopup {
                info,
                status: None,
                installing: false,
            });
        }
    }

    /// `[u]` popup: Enter installs, Esc closes.
    ///
    /// The install runs on a background thread — it downloads and verifies a
    /// tarball, which must not block the event loop — and reports through
    /// `update_install_rx` like every other background operation here.
    fn handle_update_popup_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let Some(popup) = self.state.update_popup.as_mut() else {
            return Ok(());
        };
        // Ignore everything while the swap is in flight: a second Enter would
        // start a competing download into the same staging directory.
        if popup.installing {
            return Ok(());
        }
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') => {
                self.state.update_popup = None;
            }
            KeyCode::Enter => {
                // Already finished (success or failure) — Enter closes.
                if popup.status.is_some() {
                    self.state.update_popup = None;
                    return Ok(());
                }
                let tag = popup.info.tag.clone();
                let latest = popup.info.latest.to_string();
                popup.installing = true;
                let (tx, rx) = mpsc::channel();
                self.state.update_install_rx = Some(rx);
                std::thread::spawn(move || {
                    let result = crate::update::install::install_release(&tag, &mut |_| {})
                        .map(|_| {
                            // The running process still holds the old inode;
                            // tmux sessions and their agents are untouched.
                            format!("agtx {latest} installed — restart agtx to apply")
                        })
                        .map_err(|e| e.to_string());
                    let _ = tx.send(result);
                });
            }
            _ => {}
        }
        Ok(())
    }

    /// Answer the trust prompt.
    ///
    /// This decides whether shell commands the user has not read are allowed to
    /// run, so it takes a deliberate `y`. Accepting any key would let typing
    /// ahead after launch, or reaching for an unrelated shortcut, grant it.
    fn handle_trust_confirm_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        match key.code {
            KeyCode::Char('y') | KeyCode::Char('Y') => {}
            KeyCode::Char('n') | KeyCode::Char('N') | KeyCode::Esc | KeyCode::Char('q') => {
                self.state.trust_confirm_popup = None;
                self.state.warning_message = Some((
                    "Left untrusted. init_script, cleanup_script and copy_files stay disabled."
                        .to_string(),
                    Instant::now(),
                ));
                return Ok(());
            }
            // Anything else leaves the question on screen rather than guessing.
            _ => return Ok(()),
        }

        if let Some(popup) = self.state.trust_confirm_popup.clone() {
            self.state.trust_confirm_popup = None;
            // Trust the project: save hash to trust store
            let mut store = crate::config::TrustStore::load().unwrap_or_default();
            if let Err(e) = store.trust_project(&popup.project_path) {
                self.state.warning_message =
                    Some((format!("Failed to trust project: {}", e), Instant::now()));
                return Ok(());
            }
            // Re-enable scripts by reloading project config and re-merging
            let project_config =
                crate::config::ProjectConfig::load(&popup.project_path).unwrap_or_default();
            let global_config = crate::config::GlobalConfig::load().unwrap_or_default();
            self.state.config = crate::config::MergedConfig::merge(&global_config, &project_config);
            self.state.flags.no_init_scripts = false;
            self.state.warning_message = Some((
                "Project trusted. init_script, cleanup_script, and copy_files are now active."
                    .to_string(),
                Instant::now(),
            ));
        }
        Ok(())
    }

    /// Keys while the `?` overlay is up. It is a reference, so it only scrolls
    /// and closes.
    fn handle_help_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let Some(scroll) = self.state.help_scroll else {
            return Ok(());
        };
        // The renderer clamps to what actually fits; this only has to keep the
        // offset inside the table.
        // Clamp to what the last frame could actually show, not to the table
        // length: an offset past the final screenful looks like a dead key.
        let last = self.state.help_max_scroll.get();
        let clamp = |row: i64| -> usize { row.clamp(0, last as i64) as usize };

        // The same chords the task pane scrolls with, from the same table.
        if let Some(action) = scroll_action_for(key) {
            self.state.help_scroll = Some(match action {
                PopupScroll::Up(lines) => clamp(scroll as i64 - lines as i64),
                PopupScroll::Down(lines) => clamp(scroll as i64 + lines as i64),
                PopupScroll::Bottom => last,
            });
            return Ok(());
        }

        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('?') => {
                self.state.help_scroll = None;
            }
            KeyCode::Char('j') | KeyCode::Down => {
                self.state.help_scroll = Some(clamp(scroll as i64 + 1));
            }
            KeyCode::Char('k') | KeyCode::Up => {
                self.state.help_scroll = Some(clamp(scroll as i64 - 1));
            }
            KeyCode::Home => self.state.help_scroll = Some(0),
            KeyCode::End => self.state.help_scroll = Some(last),
            _ => {}
        }
        Ok(())
    }

    /// Open the config editor on the configs as they are on disk.
    ///
    /// Loaded fresh rather than reconstructed from `state.config`: that is a
    /// *merged* view, and writing it back would bake every global default into
    /// the project file as an explicit override.
    fn open_config_editor(&mut self) {
        let global = GlobalConfig::load().unwrap_or_default();
        let project = self
            .state
            .project_path
            .as_ref()
            .map(|path| ProjectConfig::load(path).unwrap_or_default());

        let agents: Vec<String> = agent::known_agents().into_iter().map(|a| a.name).collect();

        let mut plugins: Vec<String> = skills::BUNDLED_PLUGINS
            .iter()
            .map(|(name, _, _)| name.to_string())
            .collect();
        for custom in skills::discover_custom_plugins(self.state.project_path.as_deref()) {
            if !plugins.contains(&custom.name) {
                plugins.push(custom.name);
            }
        }

        self.state.config_editor = Some(ConfigEditor::open(global, project, &agents, &plugins));
    }

    fn handle_config_editor_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let Some(editor) = self.state.config_editor.as_mut() else {
            return Ok(());
        };
        let action = editor.handle_key(key);
        // Preview the theme as it is edited. Theme is global-only, so the
        // merged config's copy can simply be replaced — no merge to redo, and
        // every draw call already reads it. `reload_config` on close is what
        // puts back an unsaved experiment.
        let previewed = editor.global.theme.clone();
        self.state.config.theme = previewed;

        match action {
            EditorAction::None => Ok(()),
            EditorAction::Close => {
                self.state.config_editor = None;
                // Drop any previewed theme that was never saved.
                self.reload_config();
                Ok(())
            }
            EditorAction::Save => self.save_config_editor(),
        }
    }

    /// Write both configs, restore the project's trust, and re-merge.
    fn save_config_editor(&mut self) -> Result<()> {
        let Some(editor) = self.state.config_editor.as_mut() else {
            return Ok(());
        };
        let global = editor.global.clone();
        let project = editor.project.clone();

        if let Err(e) = global.save() {
            editor.status = Some(format!("Could not save global config: {e}"));
            return Ok(());
        }

        if let (Some(project), Some(path)) = (project, self.state.project_path.clone()) {
            // Trust is a hash of this file, so read it before the write. See
            // `TrustStore::retrust_after_agtx_write` — the user authored these
            // changes in agtx's own UI, which is the consent the hash protects.
            let was_trusted = crate::config::TrustStore::load()
                .map(|store| store.is_trusted(&path))
                .unwrap_or(false);
            if let Err(e) = project.save(&path) {
                if let Some(editor) = self.state.config_editor.as_mut() {
                    editor.status = Some(format!("Could not save project config: {e}"));
                }
                return Ok(());
            }
            if let Err(e) = crate::config::TrustStore::retrust_after_agtx_write(&path, was_trusted)
            {
                self.state.warning_message = Some((
                    format!("Config saved, but re-trusting the project failed: {e}"),
                    Instant::now(),
                ));
            }
        }

        self.reload_config();
        if let Some(editor) = self.state.config_editor.as_mut() {
            editor.mark_saved("Saved. Worktree settings apply to new tasks.");
        }
        Ok(())
    }

    /// Re-read both configs from disk and rebuild everything derived from them.
    fn reload_config(&mut self) {
        let global = GlobalConfig::load().unwrap_or_default();
        let project = self
            .state
            .project_path
            .as_ref()
            .map(|path| ProjectConfig::load(path).unwrap_or_default())
            .unwrap_or_default();
        self.state.config = MergedConfig::merge(&global, &project);
        self.state.cached_plugin = Some(load_plugin_if_configured(
            &self.state.config,
            self.state.project_path.as_deref(),
        ));
    }

    fn open_plugin_select_popup(&mut self) {
        let current = self
            .state
            .config
            .workflow_plugin
            .as_deref()
            .unwrap_or("agtx");
        let mut options = vec![PickOption {
            name: "agtx".to_string(),
            label: "agtx".to_string(),
            description: "Built-in workflow with skills and prompts".to_string(),
            active: current == "agtx",
        }];
        for (name, desc, _content) in skills::BUNDLED_PLUGINS {
            if *name == "agtx" {
                continue;
            }
            options.push(PickOption {
                name: name.to_string(),
                label: name.to_string(),
                description: desc.to_string(),
                active: current == *name,
            });
        }
        let agent_name = &self.state.config.default_agent;
        for custom in skills::discover_custom_plugins(self.state.project_path.as_deref()) {
            if !custom.plugin.supports_agent(agent_name) {
                continue;
            }
            options.push(PickOption {
                name: custom.name.clone(),
                label: custom.name.clone(),
                description: custom.description,
                active: current == custom.name,
            });
        }
        let selected = options.iter().position(|o| o.active).unwrap_or(0);
        self.state.plugin_select_popup = Some(PluginSelectPopup { selected, options });
    }

    fn handle_plugin_select_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        if let Some(ref mut popup) = self.state.plugin_select_popup {
            match key.code {
                KeyCode::Char('j') | KeyCode::Down => {
                    if popup.selected < popup.options.len().saturating_sub(1) {
                        popup.selected += 1;
                    }
                }
                KeyCode::Char('k') | KeyCode::Up => {
                    if popup.selected > 0 {
                        popup.selected -= 1;
                    }
                }
                KeyCode::Enter => {
                    let name = popup.options[popup.selected].name.clone();
                    self.state.plugin_select_popup = None;
                    self.install_plugin(&name)?;
                }
                KeyCode::Esc => {
                    self.state.plugin_select_popup = None;
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn install_plugin(&mut self, plugin_name: &str) -> Result<()> {
        let Some(project_path) = self.state.project_path.clone() else {
            return Ok(());
        };

        // Read trust *before* the write: saving the config changes its hash,
        // which is what trust is. See `TrustStore::retrust_after_agtx_write`.
        let was_trusted = crate::config::TrustStore::load()
            .map(|store| store.is_trusted(&project_path))
            .unwrap_or(false);

        // Load current project config
        let mut project_config = ProjectConfig::load(&project_path).unwrap_or_default();

        if plugin_name.is_empty() || plugin_name == "agtx" {
            // agtx is the default — clear explicit setting
            project_config.workflow_plugin = None;
        } else {
            // Find bundled plugin content and write it
            if let Some((_name, _desc, content)) = skills::BUNDLED_PLUGINS
                .iter()
                .find(|(n, _, _)| *n == plugin_name)
            {
                let plugin_dir = project_path.join(".agtx").join("plugins").join(plugin_name);
                let _ = std::fs::create_dir_all(&plugin_dir);
                let _ = std::fs::write(plugin_dir.join("plugin.toml"), content);
            }
            project_config.workflow_plugin = Some(plugin_name.to_string());
        }

        // Save project config
        project_config.save(&project_path)?;

        // The save just invalidated the trust hash. Restore the prior decision
        // so picking a plugin does not untrust the project behind the user's
        // back; a project that was already untrusted stays that way.
        if let Err(e) =
            crate::config::TrustStore::retrust_after_agtx_write(&project_path, was_trusted)
        {
            self.state.warning_message = Some((
                format!("Plugin set, but re-trusting the project failed: {}", e),
                Instant::now(),
            ));
        }

        // Refresh merged config and cached plugin
        let global_config = GlobalConfig::load().unwrap_or_default();
        self.state.config = MergedConfig::merge(&global_config, &project_config);
        self.state.cached_plugin = Some(load_plugin_if_configured(
            &self.state.config,
            Some(&project_path),
        ));

        Ok(())
    }

    fn force_move_to_done(&mut self, task_id: &str) -> Result<()> {
        if let (Some(db), Some(project_path)) = (&self.state.db, self.state.project_path.clone()) {
            if let Some(mut task) = db.get_task(task_id)? {
                let session_name = task.session_name.clone();
                let worktree_path = task.worktree_path.clone();
                let branch_name = task.branch_name.clone();
                let agent = task.agent.clone();

                // Update task status immediately
                task.session_name = None;
                task.worktree_path = None;
                task.status = TaskStatus::Done;
                task.updated_at = chrono::Utc::now();
                db.update_task(&task)?;

                // Same clearing the other transitions do. Without it the card
                // keeps whatever the last refresh saw — a Done task showing
                // "Working" — because nothing refreshes Done to correct it.
                self.state.stuck_task_notified.remove(&task.id);
                self.state.stuck_task_idle_since.remove(&task.id);
                self.state.phase_status_cache.remove(&task.id);

                self.refresh_tasks()?;

                // Cleanup in background (archive, kill tmux, remove worktree)
                let tmux_ops = Arc::clone(&self.state.tmux_ops);
                let git_ops = Arc::clone(&self.state.git_ops);
                let task_id = task.id.clone();
                let cleanup_script = if self.state.flags.no_init_scripts {
                    None
                } else {
                    self.state.config.cleanup_script.clone()
                };
                std::thread::spawn(move || {
                    cleanup_task_resources(
                        &task_id,
                        &agent,
                        &branch_name,
                        &session_name,
                        &worktree_path,
                        cleanup_script.as_deref(),
                        &project_path,
                        tmux_ops.as_ref(),
                        git_ops.as_ref(),
                    );
                });
            }
        }
        Ok(())
    }

    fn move_running_to_review_with_pr(&mut self, task_id: &str) -> Result<()> {
        if let Some(db) = &self.state.db {
            if let Some(task) = db.get_task(task_id)? {
                let task_title = task.title.clone();
                let worktree_path = task.worktree_path.clone();

                // Show popup immediately with loading state
                self.state.pr_confirm_popup = Some(PrConfirmPopup {
                    task_id: task_id.to_string(),
                    pr_title: task_title.clone(),
                    pr_body: String::new(),
                    editing_title: true,
                    generating: true,
                });

                // Spawn background thread to generate PR description
                let (tx, rx) = mpsc::channel();
                self.state.pr_generation_rx = Some(rx);

                let title_for_thread = task_title.clone();
                let worktree_for_thread = worktree_path.clone();
                let git_ops = Arc::clone(&self.state.git_ops);
                let agent_ops = self
                    .state
                    .agent_registry
                    .get(&self.state.config.default_agent);
                std::thread::spawn(move || {
                    let (pr_title, pr_body) = generate_pr_description(
                        &title_for_thread,
                        worktree_for_thread.as_deref(),
                        None,
                        git_ops.as_ref(),
                        agent_ops.as_ref(),
                    );
                    let _ = tx.send((pr_title, pr_body));
                });
            }
        }
        Ok(())
    }

    fn move_running_to_review_without_pr(&mut self, task_id: &str) -> Result<()> {
        if let Some(db) = &self.state.db {
            if let Some(mut task) = db.get_task(task_id)? {
                task.status = TaskStatus::Review;
                task.updated_at = chrono::Utc::now();
                db.update_task(&task)?;
                self.refresh_tasks()?;
            }
        }
        Ok(())
    }

    fn handle_pr_confirm_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        use crossterm::event::KeyModifiers;

        if let Some(ref mut popup) = self.state.pr_confirm_popup {
            match key.code {
                KeyCode::Esc => {
                    self.state.pr_confirm_popup = None;
                }
                KeyCode::Tab => {
                    // Switch between title and body editing
                    popup.editing_title = !popup.editing_title;
                }
                KeyCode::Char('s') if key.modifiers.contains(KeyModifiers::CONTROL) => {
                    if !popup.generating {
                        // Ctrl+s: Submit and create PR
                        let task_id = popup.task_id.clone();
                        let pr_title = popup.pr_title.clone();
                        let pr_body = popup.pr_body.clone();
                        self.state.pr_confirm_popup = None;
                        self.create_pr_and_move_to_review_with_content(
                            &task_id, &pr_title, &pr_body,
                        )?;
                    }
                }
                KeyCode::Enter => {
                    if popup.editing_title && !popup.generating {
                        // Enter in title: move to body editing
                        popup.editing_title = false;
                    } else if !popup.generating {
                        // Enter in body: add newline
                        popup.pr_body.push('\n');
                    }
                }
                KeyCode::Backspace => {
                    if popup.editing_title {
                        popup.pr_title.pop();
                    } else {
                        popup.pr_body.pop();
                    }
                }
                KeyCode::Char(c) => {
                    if popup.editing_title {
                        popup.pr_title.push(c);
                    } else {
                        popup.pr_body.push(c);
                    }
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn create_pr_and_move_to_review_with_content(
        &mut self,
        task_id: &str,
        pr_title: &str,
        pr_body: &str,
    ) -> Result<()> {
        if let (Some(db), Some(project_path)) = (&self.state.db, self.state.project_path.clone()) {
            if let Some(mut task) = db.get_task(task_id)? {
                // Keep tmux window open - session_name stays set for resume

                // Show loading popup
                self.state.pr_status_popup = Some(PrStatusPopup {
                    status: PrCreationStatus::Creating,
                    pr_url: None,
                    error_message: None,
                });

                // Clone data for background thread
                let task_clone = task.clone();
                let project_path_clone = project_path.clone();
                let pr_title_clone = pr_title.to_string();
                let pr_body_clone = pr_body.to_string();
                let git_ops = Arc::clone(&self.state.git_ops);
                let git_provider_ops = Arc::clone(&self.state.git_provider_ops);
                let agent_ops = self
                    .state
                    .agent_registry
                    .get(&self.state.config.default_agent);

                // Create channel for result
                let (tx, rx) = mpsc::channel();
                self.state.pr_creation_rx = Some(rx);

                // Spawn background thread to create PR
                std::thread::spawn(move || {
                    let result = create_pr_with_content(
                        &task_clone,
                        &project_path_clone,
                        &pr_title_clone,
                        &pr_body_clone,
                        git_ops.as_ref(),
                        git_provider_ops.as_ref(),
                        agent_ops.as_ref(),
                    );
                    match result {
                        Ok((pr_number, pr_url)) => {
                            // Update task in database from background thread
                            // Keep session_name so popup can still be opened in Review
                            if let Ok(db) = crate::db::Database::open_project(&project_path_clone) {
                                let mut updated_task = task_clone;
                                updated_task.pr_number = Some(pr_number);
                                updated_task.pr_url = Some(pr_url.clone());
                                updated_task.status = TaskStatus::Review;
                                updated_task.updated_at = chrono::Utc::now();
                                let _ = db.update_task(&updated_task);
                            }
                            let _ = tx.send(Ok((pr_number, pr_url)));
                        }
                        Err(e) => {
                            let _ = tx.send(Err(e.to_string()));
                        }
                    }
                });
            }
        }
        Ok(())
    }

    fn handle_task_search_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        use crossterm::event::KeyModifiers;

        let should_close = match key.code {
            KeyCode::Esc => {
                self.state.task_search = None;
                true
            }
            KeyCode::Enter => {
                // Jump to selected task and open it
                if let Some(ref search) = self.state.task_search {
                    if let Some((task_id, _, status)) = search.matches.get(search.selected).cloned()
                    {
                        // Find column index for this status
                        let col_idx = TaskStatus::columns()
                            .iter()
                            .position(|s| *s == status)
                            .unwrap_or(0);
                        self.state.board.selected_column = col_idx;

                        // Find row index for this task
                        let tasks_in_col: Vec<_> = self
                            .state
                            .board
                            .tasks
                            .iter()
                            .filter(|t| t.status == status)
                            .collect();
                        if let Some(row_idx) = tasks_in_col.iter().position(|t| t.id == task_id) {
                            self.state.board.selected_row = row_idx;
                        }
                    }
                }
                self.state.task_search = None;
                // Open the selected task (same as pressing Enter on a task)
                self.open_selected_task()?;
                true
            }
            KeyCode::Up | KeyCode::BackTab => {
                if let Some(ref mut search) = self.state.task_search {
                    if search.selected > 0 {
                        search.selected -= 1;
                    }
                }
                false
            }
            KeyCode::Down | KeyCode::Tab => {
                if let Some(ref mut search) = self.state.task_search {
                    if search.selected < search.matches.len().saturating_sub(1) {
                        search.selected += 1;
                    }
                }
                false
            }
            KeyCode::Char('k') | KeyCode::Char('p')
                if key.modifiers.contains(KeyModifiers::CONTROL) =>
            {
                if let Some(ref mut search) = self.state.task_search {
                    if search.selected > 0 {
                        search.selected -= 1;
                    }
                }
                false
            }
            KeyCode::Char('j') | KeyCode::Char('n')
                if key.modifiers.contains(KeyModifiers::CONTROL) =>
            {
                if let Some(ref mut search) = self.state.task_search {
                    if search.selected < search.matches.len().saturating_sub(1) {
                        search.selected += 1;
                    }
                }
                false
            }
            KeyCode::Backspace => {
                if let Some(ref mut search) = self.state.task_search {
                    search.query.pop();
                }
                let query = self
                    .state
                    .task_search
                    .as_ref()
                    .map(|s| s.query.clone())
                    .unwrap_or_default();
                let matches = self.get_all_task_matches(&query);
                if let Some(ref mut search) = self.state.task_search {
                    search.matches = matches;
                    search.selected = 0;
                }
                false
            }
            KeyCode::Char(c) => {
                if let Some(ref mut search) = self.state.task_search {
                    search.query.push(c);
                }
                let query = self
                    .state
                    .task_search
                    .as_ref()
                    .map(|s| s.query.clone())
                    .unwrap_or_default();
                let matches = self.get_all_task_matches(&query);
                if let Some(ref mut search) = self.state.task_search {
                    search.matches = matches;
                    search.selected = 0;
                }
                false
            }
            _ => false,
        };

        if should_close {
            self.state.task_search = None;
        }

        Ok(())
    }

    fn get_all_task_matches(&self, query: &str) -> Vec<(String, String, TaskStatus)> {
        let query_lower = query.to_lowercase();

        let mut matches: Vec<(String, String, TaskStatus, i32)> = self
            .state
            .board
            .tasks
            .iter()
            .filter_map(|task| {
                let title_lower = task.title.to_lowercase();
                let score = if query.is_empty() {
                    1
                } else {
                    fuzzy_score(&title_lower, &query_lower)
                };

                if score > 0 {
                    Some((task.id.clone(), task.title.clone(), task.status, score))
                } else {
                    None
                }
            })
            .collect();

        // Sort by score (higher is better)
        matches.sort_by(|a, b| b.3.cmp(&a.3));

        matches
            .into_iter()
            .take(10)
            .map(|(id, title, status, _)| (id, title, status))
            .collect()
    }

    fn handle_shell_popup_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        use crossterm::event::KeyModifiers;

        if let Some(ref mut popup) = self.state.shell_popup {
            let window_name = popup.window_name.clone();
            let has_ctrl = key.modifiers.contains(KeyModifiers::CONTROL);

            // Dismiss escalation note on any key press (before forwarding)
            if popup.escalation_note.is_some() {
                let task_id = popup.task_id.clone();
                popup.escalation_note = None;
                if let Some(id) = task_id {
                    if let Some(db) = &self.state.db {
                        if let Ok(Some(mut task)) = db.get_task(&id) {
                            task.escalation_note = None;
                            task.updated_at = chrono::Utc::now();
                            let _ = db.update_task(&task);
                        }
                    }
                    // Update the in-memory task list too
                    if let Some(t) = self.state.board.tasks.iter_mut().find(|t| t.id == id) {
                        t.escalation_note = None;
                    }
                }
                // Return early so the keypress only dismisses the banner, not forwarded
                return Ok(());
            }

            let scroll_action = scroll_action_for(key);
            if let Some(action) = scroll_action {
                handle_popup_scroll(
                    popup,
                    self.state.input_sink.as_ref(),
                    &mut self.state.warning_message,
                    &window_name,
                    action,
                );
                return Ok(());
            }

            match key.code {
                // Ctrl+q = close popup
                KeyCode::Char('q') if has_ctrl => {
                    // Anything still batched belongs to *this* pane. Deliver it
                    // before the popup — and with it the target — can change,
                    // and before agtx's own next write to this pane (a phase
                    // advance is one keystroke away on the board).
                    flush_pane_input_sync(
                        self.state.input_sink.as_ref(),
                        &mut self.state.warning_message,
                    );
                    self.state.shell_popup = None;
                }
                // Ctrl+f toggles between centered and fullscreen in-app views.
                KeyCode::Char('f') if has_ctrl => {
                    // The resize is a plain tmux subprocess on a different
                    // socket; queued text must reach the pane at the size it was
                    // typed at, so this waits rather than just enqueueing.
                    flush_pane_input_sync(
                        self.state.input_sink.as_ref(),
                        &mut self.state.warning_message,
                    );
                    popup.fullscreen = !popup.fullscreen;
                    let (pane_width, pane_height) = if popup.fullscreen {
                        crossterm::terminal::size()
                            .map(|(width, height)| {
                                (width.saturating_sub(2), height.saturating_sub(4))
                            })
                            .unwrap_or((SHELL_POPUP_CONTENT_WIDTH, 20))
                    } else {
                        let height = crossterm::terminal::size()
                            .map(|(_, height)| {
                                (height as u32 * SHELL_POPUP_HEIGHT_PERCENT as u32 / 100) as u16
                            })
                            .unwrap_or(24);
                        (SHELL_POPUP_CONTENT_WIDTH, height.saturating_sub(4))
                    };
                    let _ =
                        self.state
                            .tmux_ops
                            .resize_window(&window_name, pane_width, pane_height);
                    popup.last_pane_size = Some((pane_width, pane_height));
                    return Ok(());
                }
                _ => {
                    // Forward all other keys to tmux window (including Esc)
                    if let Some(input) = popup_key_input(&window_name, key) {
                        forward_pane_input(
                            self.state.input_sink.as_ref(),
                            &mut self.state.warning_message,
                            input,
                        );
                    }
                }
            }
        }
        Ok(())
    }

    fn handle_paste(&mut self, text: String) -> Result<()> {
        // Shell popup open: forward paste to the tmux pane with proper bracketed
        // paste sequences. It goes through the broker like every other request,
        // so it cannot overtake characters typed just before it.
        if let Some(ref popup) = self.state.shell_popup {
            let window_name = popup.window_name.clone();
            forward_pane_input(
                self.state.input_sink.as_ref(),
                &mut self.state.warning_message,
                PaneInput::Paste {
                    target: window_name,
                    text,
                },
            );
            return Ok(());
        }

        // Prompt step open: insert pasted text at the caret.
        if self.state.wizard_step() == Some(WizardStep::Prompt) {
            let prompt = self.prompt_mut();
            let cursor = prompt.cursor;
            prompt.buffer.insert_str(cursor, &text);
            prompt.cursor += text.len();
        }

        Ok(())
    }

    fn handle_diff_popup_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        if let Some(ref mut popup) = self.state.diff_popup {
            match key.code {
                KeyCode::Esc | KeyCode::Char('q') => {
                    self.state.diff_popup = None;
                }
                KeyCode::Char('j') | KeyCode::Down => {
                    popup.scroll_offset = popup.scroll_offset.saturating_add(1);
                }
                KeyCode::Char('k') | KeyCode::Up => {
                    popup.scroll_offset = popup.scroll_offset.saturating_sub(1);
                }
                KeyCode::Char('d') | KeyCode::PageDown => {
                    popup.scroll_offset = popup.scroll_offset.saturating_add(20);
                }
                KeyCode::Char('u') | KeyCode::PageUp => {
                    popup.scroll_offset = popup.scroll_offset.saturating_sub(20);
                }
                KeyCode::Char('g') => {
                    popup.scroll_offset = 0;
                }
                KeyCode::Char('G') => {
                    // Go to end
                    let line_count = popup.diff_content.lines().count();
                    popup.scroll_offset = line_count.saturating_sub(10);
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn handle_dashboard_key(&mut self, key: KeyCode) -> Result<()> {
        if self.state.show_project_list {
            match key {
                KeyCode::Char('q') => self.state.should_quit = true,
                KeyCode::Char('j') | KeyCode::Down => {
                    if self.state.selected_project < self.state.projects.len().saturating_sub(1) {
                        self.state.selected_project += 1;
                    }
                }
                KeyCode::Char('k') | KeyCode::Up => {
                    if self.state.selected_project > 0 {
                        self.state.selected_project -= 1;
                    }
                }
                KeyCode::Enter => {
                    if let Some(project) = self
                        .state
                        .projects
                        .get(self.state.selected_project)
                        .cloned()
                    {
                        self.switch_to_project(&project)?;
                        self.state.mode = AppMode::Project(PathBuf::from(&project.path));
                        self.state.sidebar_visible = false;
                    }
                }
                KeyCode::Esc => {
                    self.state.show_project_list = false;
                }
                _ => {}
            }
        } else {
            match key {
                KeyCode::Char('q') => self.state.should_quit = true,
                KeyCode::Char('p') => {
                    self.state.show_project_list = true;
                }
                KeyCode::Char('u') if self.state.update_available.is_some() => {
                    self.open_update_popup();
                }
                KeyCode::Char('n') => {
                    let current_dir = std::env::current_dir()?;
                    if crate::git::is_git_repo(&current_dir) {
                        let canonical = current_dir.canonicalize().unwrap_or(current_dir);
                        let name = canonical
                            .file_name()
                            .and_then(|n| n.to_str())
                            .unwrap_or("unknown")
                            .to_string();
                        let project = ProjectInfo {
                            name: name.clone(),
                            path: canonical.to_string_lossy().to_string(),
                        };
                        self.switch_to_project(&project)?;
                        self.state.mode = AppMode::Project(canonical);
                        self.state.sidebar_visible = false;
                    }
                }
                _ => {}
            }
        }
        Ok(())
    }

    fn handle_normal_key(&mut self, key: KeyCode) -> Result<()> {
        // Handle sidebar navigation if focused
        if self.state.sidebar_focused && self.state.sidebar_visible {
            match key {
                KeyCode::Char('q') => self.state.should_quit = true,
                KeyCode::Char('e') => {
                    // Toggle sidebar visibility
                    self.state.sidebar_visible = false;
                    self.state.sidebar_focused = false;
                }
                KeyCode::Char('l') | KeyCode::Right | KeyCode::Esc => {
                    // Move focus back to board
                    self.state.sidebar_focused = false;
                }
                KeyCode::Char('j') | KeyCode::Down => {
                    if self.state.selected_project < self.state.projects.len().saturating_sub(1) {
                        self.state.selected_project += 1;
                        // Switch to project immediately on cursor move
                        if let Some(project) = self
                            .state
                            .projects
                            .get(self.state.selected_project)
                            .cloned()
                        {
                            self.switch_to_project_keep_sidebar(&project)?;
                        }
                    }
                }
                KeyCode::Char('k') | KeyCode::Up => {
                    if self.state.selected_project > 0 {
                        self.state.selected_project -= 1;
                        // Switch to project immediately on cursor move
                        if let Some(project) = self
                            .state
                            .projects
                            .get(self.state.selected_project)
                            .cloned()
                        {
                            self.switch_to_project_keep_sidebar(&project)?;
                        }
                    }
                }
                KeyCode::Enter => {
                    // Enter focuses the board (sidebar stays visible)
                    self.state.sidebar_focused = false;
                }
                _ => {}
            }
            return Ok(());
        }

        // Handle board navigation
        match key {
            KeyCode::Char('q') => self.state.should_quit = true,
            KeyCode::Char('e') => {
                // Toggle sidebar visibility
                self.state.sidebar_visible = !self.state.sidebar_visible;
                if self.state.sidebar_visible {
                    self.refresh_projects()?;
                }
            }
            KeyCode::Char('h') | KeyCode::Left => {
                // Move to sidebar only if visible AND in first column (Backlog)
                if self.state.sidebar_visible && self.state.board.selected_column == 0 {
                    self.state.sidebar_focused = true;
                    self.refresh_projects()?;
                } else {
                    self.state.board.move_left();
                }
            }
            KeyCode::Char('l') | KeyCode::Right => self.state.board.move_right(),
            KeyCode::Char('j') | KeyCode::Down => self.state.board.move_down(),
            KeyCode::Char('k') | KeyCode::Up => self.state.board.move_up(),
            KeyCode::Char('o') => {
                // New task
                self.state.wizard = Some(WizardState::creating());
                self.seed_wizard_lists();
            }
            KeyCode::Enter => {
                if let Some(task) = self.state.board.selected_task() {
                    if task.status == TaskStatus::Backlog && task.session_name.is_some() {
                        // Backlog task with active research session
                        if self.state.config.fullscreen_on_enter {
                            self.open_selected_task_fullscreen()?;
                        } else {
                            self.open_selected_task()?;
                        }
                    } else if task.status == TaskStatus::Backlog {
                        // Edit task
                        self.state.wizard =
                            Some(WizardState::editing(task.id.clone(), task.title.clone()));
                        self.seed_wizard_lists();
                    } else if task.session_name.is_some() {
                        // Open shell popup or fullscreen
                        if self.state.config.fullscreen_on_enter {
                            self.open_selected_task_fullscreen()?;
                        } else {
                            self.open_selected_task()?;
                        }
                    }
                }
            }
            KeyCode::Char('x') => self.delete_selected_task()?,
            KeyCode::Char('d') => self.show_task_diff()?,
            KeyCode::Char('D') => self.show_dependency_graph()?,
            KeyCode::Char('W') => {
                // `W` and not `R`/`r`: those are start-research and resume.
                self.state.mobile_popup = Some(crate::tui::serve_control::MobilePopup::new());
            }
            KeyCode::Char('m') => self.move_task_right()?,
            KeyCode::Char('M') => self.move_backlog_to_running()?,
            KeyCode::Char('R') => {
                if let Some(task) = self.state.board.selected_task() {
                    if task.status == TaskStatus::Backlog && task.session_name.is_none() {
                        let task_id = task.id.clone();
                        self.start_research(&task_id)?;
                    }
                }
            }
            KeyCode::Char('r') => {
                if let Some(task) = self.state.board.selected_task() {
                    let task_id = task.id.clone();
                    match task.status {
                        // Move Review task back to Running (for PR changes)
                        TaskStatus::Review => self.move_review_to_running(&task_id)?,
                        // Move Running task back to Planning
                        TaskStatus::Running => self.move_running_to_planning(&task_id)?,
                        _ => {}
                    }
                }
            }
            KeyCode::Char('p') => {
                // Cyclic: Review → Planning (next phase) — only when plugin is cyclic
                if let Some(task) = self.state.board.selected_task() {
                    if task.status == TaskStatus::Review {
                        let plugin = self.load_task_plugin(&task);
                        if plugin.as_ref().map_or(false, |p| p.cyclic) {
                            let task_id = task.id.clone();
                            self.move_review_to_planning(&task_id)?;
                        }
                    }
                }
            }
            KeyCode::Char('/') => {
                // Open task search
                self.state.task_search = Some(TaskSearchState {
                    query: String::new(),
                    matches: self.get_all_task_matches(""),
                    selected: 0,
                });
            }
            KeyCode::Char('P') => {
                // Open plugin selection popup
                self.open_plugin_select_popup();
            }
            KeyCode::Char(',') => self.open_config_editor(),
            KeyCode::Char('?') => self.state.help_scroll = Some(0),
            KeyCode::Char('u') if self.state.update_available.is_some() => {
                self.open_update_popup();
            }
            KeyCode::Char('O') if self.state.flags.experimental => {
                // Toggle orchestrator agent (experimental)
                self.toggle_orchestrator()?;
            }
            _ => {}
        }
        Ok(())
    }

    /// The wizard's state. Only reachable while it is open, which the key
    /// dispatch guarantees before routing anything here.
    fn wizard_mut(&mut self) -> &mut WizardState {
        self.state
            .wizard
            .as_mut()
            .expect("wizard handlers only run while the wizard is open")
    }

    /// Every key the wizard sees, whichever step it is on.
    ///
    /// The navigation keys are handled first and identically on all three
    /// steps — that is the whole point of one handler. Only what is left over
    /// is dispatched to the step.
    fn handle_wizard_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let ctrl = key
            .modifiers
            .contains(crossterm::event::KeyModifiers::CONTROL);

        // A dropdown on the prompt step owns its keys entirely, including Esc
        // and Enter — closing the picker must not also step the wizard back.
        if self.wizard_mut().step() == WizardStep::Prompt
            && (self.handle_task_ref_search_key(key)
                || self.handle_skill_search_key(key)
                || self.handle_file_search_key(key))
        {
            return Ok(());
        }

        // Any keystroke means the user is acting on the complaint, so it goes.
        self.wizard_mut().validation = None;

        // An open filter owns Esc the way a prompt dropdown does: closing the
        // filter must not take the wizard with it.
        if key.code == KeyCode::Esc {
            if let Some(list) = self.wizard_mut().current_list_mut() {
                if list.is_filtering() {
                    list.stop_filter();
                    list.settle();
                    return Ok(());
                }
            }
        }

        match key.code {
            // Save from anywhere, so a correction made on step one does not
            // require walking forward through the rest of the flow again.
            KeyCode::Char('s') if ctrl => {
                self.try_save_wizard()?;
                return Ok(());
            }
            // Esc leaves the wizard outright, from any step. Stepping back is
            // Shift+Tab / Ctrl+B below — one key that always means "get me out
            // of here" beats one whose effect depends on where you are.
            KeyCode::Esc => {
                self.cancel_wizard();
                return Ok(());
            }
            // Legacy terminals send BackTab; the Kitty protocol sends Tab with
            // SHIFT. Both mean the same thing.
            KeyCode::BackTab => {
                self.wizard_mut().back();
                return Ok(());
            }
            KeyCode::Tab
                if key
                    .modifiers
                    .contains(crossterm::event::KeyModifiers::SHIFT) =>
            {
                self.wizard_mut().back();
                return Ok(());
            }
            KeyCode::Char('b') if ctrl => {
                self.wizard_mut().back();
                return Ok(());
            }
            _ => {}
        }

        match self.wizard_mut().step() {
            WizardStep::Title => self.handle_title_input(key),
            WizardStep::Agent | WizardStep::Plugin => self.handle_list_step_key(key),
            WizardStep::Prompt => self.handle_prompt_input(key),
        }
    }

    fn handle_title_input(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        match key.code {
            KeyCode::Enter => self.advance_wizard()?,
            // Motion, deletion and ordinary characters are the same in every
            // text field; only the keys above mean something particular here.
            _ => {
                self.wizard_mut().title.handle_edit_key(key);
            }
        }
        Ok(())
    }

    /// Keys on the agent and plugin steps. Both are pick-one-from-a-list, so
    /// they share a handler.
    ///
    /// `/` starts a filter, and while one is open ordinary characters go to it
    /// — which is why navigation there is arrows and `C-n`/`C-p` rather than
    /// `j`/`k`. Without the filter open, `j`/`k` navigate as usual.
    fn handle_list_step_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let ctrl = key
            .modifiers
            .contains(crossterm::event::KeyModifiers::CONTROL);
        if key.code == KeyCode::Enter {
            return self.advance_wizard();
        }
        let Some(list) = self.wizard_mut().current_list_mut() else {
            return Ok(());
        };

        if list.is_filtering() {
            match key.code {
                KeyCode::Down => list.select_next(),
                KeyCode::Up => list.select_prev(),
                KeyCode::Char('n') if ctrl => list.select_next(),
                KeyCode::Char('p') if ctrl => list.select_prev(),
                KeyCode::Tab => list.cycle(),
                _ => {
                    let filter = list.filter.as_mut().expect("filtering");
                    if filter.handle_edit_key(key) {
                        // Backspacing the filter away is how you leave it, so
                        // the whole list comes back rather than the step
                        // staying in a mode with nothing typed.
                        if filter.is_empty() && key.code == KeyCode::Backspace {
                            list.stop_filter();
                        }
                        list.settle();
                    }
                }
            }
            return Ok(());
        }

        match key.code {
            KeyCode::Char('/') => list.start_filter(),
            KeyCode::Char('j') | KeyCode::Down => list.select_next(),
            KeyCode::Char('k') | KeyCode::Up => list.select_prev(),
            KeyCode::Char('n') if ctrl => list.select_next(),
            KeyCode::Char('p') if ctrl => list.select_prev(),
            KeyCode::Tab => list.cycle(),
            _ => {}
        }
        Ok(())
    }

    /// Move to the next step, seeding it if this is the first time through, or
    /// save when there is no next step.
    fn advance_wizard(&mut self) -> Result<()> {
        if self.wizard_mut().step() == WizardStep::Title {
            // Nothing downstream can proceed without a title, so refuse here
            // rather than letting the user reach the last step and be told.
            if let Some(problem) = self.title_problem() {
                self.wizard_mut().validation = Some(problem);
                return Ok(());
            }
        }
        // The plugin list is filtered by the agent the task will run on, so a
        // change on the agent step has to rebuild it — otherwise the user is
        // offered plugins their agent does not support.
        if self.wizard_mut().step() == WizardStep::Agent {
            self.reseed_plugins_for_agent();
        }
        if !self.wizard_mut().advance() {
            return self.try_save_wizard();
        }
        if self.wizard_mut().step() == WizardStep::Prompt {
            self.seed_prompt_step();
        }
        Ok(())
    }

    /// Save if the wizard has what it needs, and say why not if it does not.
    ///
    /// A silent refusal reads as a broken key rather than a rejected input, so
    /// every path out of here either saves or explains itself.
    /// What is wrong with the title, if anything.
    ///
    /// One function so `Enter` on the title step and `Ctrl+S` from anywhere
    /// refuse for the same reasons and say the same thing.
    fn title_problem(&self) -> Option<String> {
        let wizard = self.state.wizard.as_ref()?;
        let title = wizard.title.as_str().trim();
        if title.is_empty() {
            return Some("A title is required.".to_string());
        }
        if title.chars().count() > MAX_TASK_TITLE_CHARS {
            return Some(format!(
                "Title is {} characters; the limit is {MAX_TASK_TITLE_CHARS}.",
                title.chars().count()
            ));
        }
        // A duplicate is legal but almost never intended, and the board shows
        // titles alone — two identical cards are indistinguishable.
        let editing = wizard.editing_task_id.as_deref();
        let clash = self
            .state
            .board
            .tasks
            .iter()
            .any(|t| Some(t.id.as_str()) != editing && t.title.trim() == title);
        if clash {
            return Some(format!("Another task is already called \"{title}\"."));
        }
        None
    }

    fn try_save_wizard(&mut self) -> Result<()> {
        // The plugin list is filtered by the agent; saving from the agent step
        // itself would otherwise store a plugin that agent does not support.
        self.reseed_plugins_for_agent();
        if let Some(problem) = self.title_problem() {
            let wizard = self.wizard_mut();
            // Send the user where the problem is, not where the key was pressed.
            // `back` clears the message on the way, so it is set afterwards.
            while wizard.step() != WizardStep::Title && wizard.back() {}
            wizard.validation = Some(problem);
            return Ok(());
        }
        self.save_task()?;
        self.cancel_wizard();
        Ok(())
    }

    /// The wizard's prompt field.
    ///
    /// The dropdown handlers below only run while the prompt step is open, so a
    /// missing wizard there is a routing bug rather than a state to handle.
    fn prompt_mut(&mut self) -> &mut TextInput {
        &mut self
            .state
            .wizard
            .as_mut()
            .expect("prompt handlers only run while the wizard is open")
            .prompt
    }

    /// Splice `replacement` over the trigger character and the pattern typed
    /// after it, keeping whatever follows.
    ///
    /// All three dropdowns commit and cancel this way; only the text differs.
    /// The caret lands at the end of the inserted text rather than the end of
    /// the line, which is what lets the user keep typing mid-sentence.
    fn splice_search_region(&mut self, start: usize, pattern_len: usize, replacement: &str) {
        let prompt = self.prompt_mut();
        // +1 for the trigger character itself.
        let end = (start + 1 + pattern_len).min(prompt.buffer.len());
        let start = start.min(prompt.buffer.len());
        let suffix = prompt.buffer[end..].to_string();
        prompt.buffer.truncate(start);
        prompt.buffer.push_str(replacement);
        prompt.cursor = prompt.buffer.len();
        prompt.buffer.push_str(&suffix);
    }

    /// Keys belonging to the `!` task-reference dropdown. `false` when it is
    /// not open, so the caller falls through to the ordinary prompt handling.
    ///
    /// The dropdown state is **taken out** for the duration: every arm needs it
    /// alongside the wizard's prompt field, and several also call back into
    /// `self` to refresh the match list, which a held borrow would not allow.
    fn handle_task_ref_search_key(&mut self, key: crossterm::event::KeyEvent) -> bool {
        let Some(mut search) = self.state.task_ref_search.take() else {
            return false;
        };
        let ctrl = key
            .modifiers
            .contains(crossterm::event::KeyModifiers::CONTROL);
        let alt = key.modifiers.contains(crossterm::event::KeyModifiers::ALT);
        let mut keep_open = true;
        let mut refresh = false;

        match key.code {
            KeyCode::Esc => {
                self.splice_search_region(search.start_pos, search.pattern.len(), "");
                keep_open = false;
            }
            KeyCode::Enter | KeyCode::Tab => {
                if let Some((task_id, title, _status)) =
                    search.matches.get(search.selected).cloned()
                {
                    let ref_text = format!("![{}]", title);
                    self.splice_search_region(search.start_pos, search.pattern.len(), &ref_text);
                    let wizard = self.wizard_mut();
                    wizard.highlighted_references.insert(ref_text);
                    wizard.referenced_task_ids.insert(task_id);
                }
                keep_open = false;
            }
            KeyCode::Up => search.select_prev(),
            KeyCode::Down => search.select_next(),
            KeyCode::Char('k') | KeyCode::Char('p') if ctrl => search.select_prev(),
            KeyCode::Char('j') | KeyCode::Char('n') if ctrl => search.select_next(),
            KeyCode::Backspace => {
                if search.pattern.is_empty() {
                    // Nothing typed yet: backspace removes the `!` and closes.
                    self.prompt_mut().backspace();
                    keep_open = false;
                } else {
                    search.pattern.pop();
                    self.prompt_mut().backspace();
                    refresh = true;
                }
            }
            // A chord the picker did not claim is not text: `Ctrl+X` must not
            // reach the pattern, and `Ctrl+J` means newline once the picker is
            // closed.
            KeyCode::Char(c) if !ctrl && !alt => {
                search.pattern.push(c);
                self.prompt_mut().insert_char(c);
                refresh = true;
            }
            _ => {}
        }

        if keep_open {
            if refresh {
                search.matches = self.get_all_task_matches(&search.pattern);
                search.selected = 0;
            }
            self.state.task_ref_search = Some(search);
        }
        true
    }

    /// Keys belonging to the `/` skill dropdown. See
    /// `handle_task_ref_search_key` for why the state is taken out.
    fn handle_skill_search_key(&mut self, key: crossterm::event::KeyEvent) -> bool {
        let Some(mut search) = self.state.skill_search.take() else {
            return false;
        };
        let ctrl = key
            .modifiers
            .contains(crossterm::event::KeyModifiers::CONTROL);
        let alt = key.modifiers.contains(crossterm::event::KeyModifiers::ALT);
        let mut keep_open = true;
        let mut refresh = false;

        match key.code {
            KeyCode::Esc => {
                self.splice_search_region(search.start_pos, search.pattern.len(), "");
                keep_open = false;
            }
            KeyCode::Enter | KeyCode::Tab => {
                if let Some(entry) = search.matches.get(search.selected).cloned() {
                    self.splice_search_region(
                        search.start_pos,
                        search.pattern.len(),
                        &entry.command,
                    );
                    self.wizard_mut()
                        .highlighted_references
                        .insert(entry.command);
                }
                keep_open = false;
            }
            KeyCode::Up => search.select_prev(),
            KeyCode::Down => search.select_next(),
            KeyCode::Char('k') | KeyCode::Char('p') if ctrl => search.select_prev(),
            KeyCode::Char('j') | KeyCode::Char('n') if ctrl => search.select_next(),
            KeyCode::Backspace => {
                if search.pattern.is_empty() {
                    self.prompt_mut().backspace();
                    keep_open = false;
                } else {
                    search.pattern.pop();
                    self.prompt_mut().backspace();
                    refresh = true;
                }
            }
            KeyCode::Char(c) if !ctrl && !alt => {
                search.pattern.push(c);
                self.prompt_mut().insert_char(c);
                refresh = true;
            }
            _ => {}
        }

        if keep_open {
            self.state.skill_search = Some(search);
            if refresh {
                self.update_skill_search_matches();
            }
        }
        true
    }

    /// Keys belonging to the `#` / `@` file dropdown. See
    /// `handle_task_ref_search_key` for why the state is taken out.
    fn handle_file_search_key(&mut self, key: crossterm::event::KeyEvent) -> bool {
        let Some(mut search) = self.state.file_search.take() else {
            return false;
        };
        let ctrl = key
            .modifiers
            .contains(crossterm::event::KeyModifiers::CONTROL);
        let alt = key.modifiers.contains(crossterm::event::KeyModifiers::ALT);
        let mut keep_open = true;
        let mut refresh = false;

        match key.code {
            // Unlike the other two, Esc leaves the typed text in place — the
            // `#` was a real character the user may have meant.
            KeyCode::Esc => keep_open = false,
            KeyCode::Enter | KeyCode::Tab => {
                if let Some(selected_file) = search.matches.get(search.selected).cloned() {
                    self.splice_search_region(
                        search.start_pos,
                        search.pattern.len(),
                        &selected_file,
                    );
                    self.wizard_mut()
                        .highlighted_references
                        .insert(selected_file);
                }
                keep_open = false;
            }
            KeyCode::Up => search.select_prev(),
            KeyCode::Down => search.select_next(),
            KeyCode::Char('k') | KeyCode::Char('p') if ctrl => search.select_prev(),
            KeyCode::Char('j') | KeyCode::Char('n') if ctrl => search.select_next(),
            KeyCode::Backspace => {
                if search.pattern.is_empty() {
                    self.prompt_mut().backspace();
                    keep_open = false;
                } else {
                    search.pattern.pop();
                    self.prompt_mut().backspace();
                    refresh = true;
                }
            }
            KeyCode::Char(c) if !ctrl && !alt => {
                search.pattern.push(c);
                self.prompt_mut().insert_char(c);
                refresh = true;
            }
            _ => {}
        }

        if keep_open {
            self.state.file_search = Some(search);
            if refresh {
                self.update_file_search_matches();
            }
        }
        true
    }

    /// Keys on the wizard's prompt step, once no dropdown has claimed them.
    fn handle_prompt_input(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        match key.code {
            // Two chords that need no negotiation from the terminal, beside
            // the `\`+Enter escape below:
            //
            // - `Ctrl+J` always works: in raw mode crossterm parses 0x0A as
            //   Ctrl+J rather than as Enter.
            // - `Alt+Enter` arrives as ESC then CR on most terminals, though
            //   macOS Terminal and iTerm2 only send it once Option is
            //   configured as Meta.
            //
            // `Shift+Enter` is deliberately absent: a terminal sends a bare CR
            // for both it and Enter unless the Kitty keyboard protocol is
            // negotiated, so the binding would fire almost never and read as
            // "save" the rest of the time. See `with_ops`.
            KeyCode::Char('j')
                if key
                    .modifiers
                    .contains(crossterm::event::KeyModifiers::CONTROL) =>
            {
                self.prompt_mut().insert_char('\n');
            }
            KeyCode::Enter if key.modifiers.contains(crossterm::event::KeyModifiers::ALT) => {
                self.prompt_mut().insert_char('\n');
            }
            KeyCode::Enter => {
                // A trailing backslash is the line-continuation escape.
                if self.prompt_mut().buffer.ends_with('\\') {
                    let prompt = self.prompt_mut();
                    prompt.buffer.pop();
                    prompt.buffer.push('\n');
                    prompt.cursor = prompt.buffer.len();
                } else {
                    self.try_save_wizard()?;
                }
            }
            KeyCode::Char('#') | KeyCode::Char('@') => {
                let trigger = if let KeyCode::Char(c) = key.code {
                    c
                } else {
                    '#'
                };
                let start_pos = self.prompt_mut().cursor;
                self.prompt_mut().insert_char(trigger);
                self.state.file_search = Some(FileSearchState {
                    pattern: String::new(),
                    matches: vec![],
                    selected: 0,
                    start_pos,
                    trigger_char: trigger,
                });
                self.update_file_search_matches();
            }
            KeyCode::Char('/') if self.prompt_at_word_start() => {
                let start_pos = self.prompt_mut().cursor;
                self.prompt_mut().insert_char('/');

                // In the syntax of the agent the task will run on, which the
                // wizard's agent step may have changed.
                let skill_agent = self
                    .state
                    .wizard
                    .as_ref()
                    .and_then(|w| w.agent_name())
                    .unwrap_or(self.state.config.default_agent.as_str())
                    .to_string();

                // Start with bundled skills (always available, no filesystem needed)
                let mut seen = std::collections::HashSet::new();
                let mut all_skills: Vec<SkillEntry> =
                    skills::enumerate_available_skills(&skill_agent)
                        .into_iter()
                        .map(|(command, description)| {
                            seen.insert(command.clone());
                            SkillEntry {
                                command,
                                description,
                            }
                        })
                        .collect();

                // Merge filesystem-discovered skills (project root), dedup by command
                if let Some(ref project_path) = self.state.project_path {
                    for (command, description) in
                        skills::scan_agent_skills(&skill_agent, project_path)
                    {
                        if seen.insert(command.clone()) {
                            all_skills.push(SkillEntry {
                                command,
                                description,
                            });
                        }
                    }
                }

                self.state.skill_search = Some(SkillSearchState {
                    pattern: String::new(),
                    matches: all_skills.clone(),
                    all_skills,
                    selected: 0,
                    start_pos,
                });
            }
            KeyCode::Char('!') if self.prompt_at_word_start() => {
                let start_pos = self.prompt_mut().cursor;
                self.prompt_mut().insert_char('!');

                let matches = self.get_all_task_matches("");
                self.state.task_ref_search = Some(TaskRefSearchState {
                    pattern: String::new(),
                    matches,
                    selected: 0,
                    start_pos,
                });
            }
            // Everything the trigger guards above declined — including a `/`
            // mid-word, which must arrive as ordinary text — plus all motion
            // and deletion. See `tui::text_input`.
            _ => {
                self.prompt_mut().handle_edit_key(key);
            }
        }
        Ok(())
    }

    /// Whether the caret sits where `/` and `!` open their pickers: at the very
    /// start, or just after a space or newline. Mid-word they are ordinary
    /// characters — a path like `src/main.rs` must not open the skill list.
    fn prompt_at_word_start(&self) -> bool {
        let Some(wizard) = self.state.wizard.as_ref() else {
            return false;
        };
        let cursor = wizard.prompt.cursor;
        if cursor == 0 {
            return true;
        }
        matches!(
            wizard.prompt.buffer.as_bytes().get(cursor - 1),
            Some(&b'\n') | Some(&b' ')
        )
    }

    fn update_file_search_matches(&mut self) {
        if let (Some(ref mut search), Some(ref project_path)) =
            (&mut self.state.file_search, &self.state.project_path)
        {
            let pattern = &search.pattern;
            search.matches =
                fuzzy_find_files(project_path, pattern, 10, self.state.git_ops.as_ref());
            search.selected = 0;
        }
    }

    fn update_skill_search_matches(&mut self) {
        if let Some(ref mut search) = self.state.skill_search {
            let pattern = search.pattern.to_lowercase();
            if pattern.is_empty() {
                search.matches = search.all_skills.clone();
            } else {
                let mut scored: Vec<_> = search
                    .all_skills
                    .iter()
                    .filter_map(|entry| {
                        let cmd_score = fuzzy_score(&entry.command.to_lowercase(), &pattern);
                        let desc_score = fuzzy_score(&entry.description.to_lowercase(), &pattern);
                        let score = std::cmp::max(cmd_score, desc_score);
                        if score > 0 {
                            Some((entry.clone(), score))
                        } else {
                            None
                        }
                    })
                    .collect();
                scored.sort_by(|a, b| b.1.cmp(&a.1));
                search.matches = scored.into_iter().take(10).map(|(e, _)| e).collect();
            }
            search.selected = 0;
        }
    }

    fn save_task(&mut self) -> Result<()> {
        let Some(wizard) = self.state.wizard.as_ref() else {
            return Ok(());
        };
        let Some(db) = self.state.db.as_ref() else {
            return Ok(());
        };
        // The agent step's pick when it offered one, else the configured
        // default. Stored as `Task::base_agent`, which every later phase
        // without its own `[agents]` entry resolves to.
        let agent = wizard
            .agent_name()
            .map(str::to_string)
            .unwrap_or_else(|| self.state.config.default_agent.clone());
        let plugin = wizard.plugin_name().map(str::to_string);
        let refs = if wizard.referenced_task_ids.is_empty() {
            None
        } else {
            Some(
                wizard
                    .referenced_task_ids
                    .iter()
                    .cloned()
                    .collect::<Vec<_>>()
                    .join(","),
            )
        };
        // `can_save` has already rejected a blank title, so trimming here only
        // strips the padding a real one may have picked up.
        let title = wizard.title.as_str().trim().to_string();
        let description = if wizard.prompt.is_empty() {
            None
        } else {
            Some(wizard.prompt.buffer.clone())
        };

        match wizard.editing_task_id.clone() {
            Some(task_id) => {
                if let Some(mut task) = db.get_task(&task_id)? {
                    task.title = title;
                    task.description = description;
                    task.base_agent = Some(agent.clone());
                    // A research window keeps running the agent it was launched
                    // with; `agent` must keep naming it, so the next phase sees the
                    // difference and switches.
                    if task.session_name.is_none() {
                        task.agent = agent;
                    }
                    task.plugin = plugin;
                    task.referenced_tasks = refs;
                    task.updated_at = chrono::Utc::now();
                    db.update_task(&task)?;
                }
            }
            None => {
                let project_id = self.state.project_name.clone();
                let mut task = Task::new(&title, agent, project_id);
                task.description = description;
                task.plugin = plugin;
                task.referenced_tasks = refs;
                // Task starts in Backlog without tmux window.
                // No orchestrator notification — it only manages Planning/Running.
                db.create_task(&task)?;
            }
        }
        self.refresh_tasks()
    }

    /// On a first launch, ask which agent to use in the editor that owns that
    /// question rather than in a menu of its own.
    ///
    /// A no-op on every other launch, so the caller does not have to check.
    fn open_first_run_editor(&mut self) {
        if !self.state.flags.first_run {
            return;
        }
        self.open_config_editor();
        if let Some(editor) = self.state.config_editor.as_mut() {
            editor.focus(super::config_editor::FieldId::DefaultAgent);
            // Kept shorter than the footer, which is what sets the box width.
            editor.status = Some("Welcome — pick your default agent.".to_string());
        }
    }

    /// Fill both list steps as soon as the wizard opens.
    ///
    /// Done here rather than on the first `Enter` so the breadcrumb shows the
    /// real flow from the first frame — otherwise it reads "Title › Prompt"
    /// and then grows two steps once you commit to a title.
    fn seed_wizard_lists(&mut self) {
        self.seed_agent_step();
        self.seed_plugin_step();
    }

    /// Rebuild the plugin list when the agent it was filtered by has changed.
    ///
    /// Keeps the user's pick when that plugin survives the new filter, because
    /// switching agent is not a decision about the plugin.
    fn reseed_plugins_for_agent(&mut self) {
        let agent = self.wizard_mut().agent_name().map(str::to_string);
        if agent.as_deref() == self.state.plugins_filtered_for.as_deref() {
            return;
        }
        let previous = self
            .wizard_mut()
            .plugin
            .selected_option()
            .map(|o| o.name.clone());
        self.wizard_mut().plugin = super::wizard::ListPick::default();
        self.seed_plugin_step();
        if let Some(name) = previous {
            let wizard = self.wizard_mut();
            if let Some(index) = wizard.plugin.options.iter().position(|o| o.name == name) {
                wizard.plugin.selected = index;
            }
        }
    }

    /// Build the agent list and decide whether the step is worth showing.
    ///
    /// The choice is per task: `Task::agent` is a database field, and before
    /// this the only way to run one task on a different agent was to edit the
    /// config, start it, and edit back.
    fn seed_agent_step(&mut self) {
        if !self.wizard_mut().agent.take_seed() {
            return;
        }
        let default_agent = self.state.config.default_agent.clone();
        // Editing opens on whatever the task already runs on, which need not be
        // the project default.
        let current = self
            .wizard_mut()
            .editing_task_id
            .clone()
            .and_then(|id| {
                self.state
                    .db
                    .as_ref()
                    .and_then(|db| db.get_task(&id).ok().flatten())
            })
            .map(|t| t.base_agent.unwrap_or(t.agent))
            .unwrap_or_else(|| default_agent.clone());

        let options: Vec<PickOption> = self
            .state
            .available_agents
            .iter()
            .map(|agent| {
                PickOption::new(
                    &agent.name,
                    &agent.name,
                    &agent.description,
                    agent.name == current,
                )
            })
            .collect();

        let selected = options.iter().position(|o| o.active).unwrap_or(0);
        let offer_step = options.len() > 1;
        let wizard = self.wizard_mut();
        wizard.agent.options = options;
        wizard.agent.selected = selected;
        wizard.set_optional_step(WizardStep::Agent, offer_step);
    }

    /// Build the plugin list and decide whether the step is worth showing.
    ///
    /// Runs once per wizard: re-entering the title step and advancing again
    /// must not rebuild the list, or the user's pick resets to the project
    /// default they just chose against.
    fn seed_plugin_step(&mut self) {
        if !self.wizard_mut().plugin.take_seed() {
            return;
        }
        // With no detected agents there is no compatibility to filter on and
        // nothing meaningful to choose between.
        if self.state.available_agents.is_empty() {
            self.wizard_mut()
                .set_optional_step(WizardStep::Plugin, false);
            return;
        }

        let editing = self.wizard_mut().editing_task_id.clone();
        let current = match editing {
            Some(task_id) => self
                .state
                .db
                .as_ref()
                .and_then(|db| db.get_task(&task_id).ok().flatten())
                .and_then(|t| t.plugin.clone())
                .or_else(|| self.state.config.workflow_plugin.clone())
                .unwrap_or_else(|| "agtx".to_string()),
            None => self
                .state
                .config
                .workflow_plugin
                .as_deref()
                .unwrap_or("agtx")
                .to_string(),
        };

        // Filtered against the agent the *task* will run on, which the agent
        // step may just have changed — a plugin that does not support it should
        // not be offered.
        let selected_agent_name = self
            .wizard_mut()
            .agent_name()
            .map(str::to_string)
            .unwrap_or_else(|| self.state.config.default_agent.clone());

        let mut options = vec![PickOption::new(
            "agtx",
            "agtx",
            "Built-in workflow with skills and prompts",
            current == "agtx",
        )];
        for (name, desc, content) in skills::BUNDLED_PLUGINS {
            if *name == "agtx" {
                continue;
            }
            // Filter by agent compatibility
            if let Ok(plugin) = toml::from_str::<WorkflowPlugin>(content) {
                if !plugin.supports_agent(&selected_agent_name) {
                    continue;
                }
            }
            options.push(PickOption::new(name, name, desc, current == *name));
        }
        for custom in skills::discover_custom_plugins(self.state.project_path.as_deref()) {
            if !custom.plugin.supports_agent(&selected_agent_name) {
                continue;
            }
            let active = current == custom.name;
            options.push(PickOption::new(
                &custom.name,
                &custom.name,
                &custom.description,
                active,
            ));
        }
        let selected = options.iter().position(|o| o.active).unwrap_or(0);
        let offer_step = options.len() > 1;
        self.state.plugins_filtered_for = Some(selected_agent_name);
        let wizard = self.wizard_mut();
        wizard.plugin.options = options;
        wizard.plugin.selected = selected;
        wizard.set_optional_step(WizardStep::Plugin, offer_step);
    }

    /// Load an edited task's existing prompt and references.
    ///
    /// Runs once per wizard, for the same reason as `seed_plugin_step` and with
    /// worse consequences: reloading from the database on the way forward would
    /// throw away every edit made before the user stepped back.
    fn seed_prompt_step(&mut self) {
        if !self.wizard_mut().take_prompt_seed() {
            return;
        }
        let Some(task_id) = self.wizard_mut().editing_task_id.clone() else {
            return;
        };
        let existing = self
            .state
            .db
            .as_ref()
            .and_then(|db| db.get_task(&task_id).ok().flatten());
        let wizard = self.wizard_mut();
        match existing {
            Some(task) => {
                wizard.prompt.set_text(task.description.unwrap_or_default());
                wizard.referenced_task_ids = task
                    .referenced_tasks
                    .as_deref()
                    .map(|s| {
                        s.split(',')
                            .filter(|id| !id.is_empty())
                            .map(String::from)
                            .collect()
                    })
                    .unwrap_or_default();
            }
            None => wizard.prompt.clear(),
        }
    }

    /// Close the wizard, discarding it. Any open dropdown goes with it, and so
    /// does the note of which agent its plugin list was filtered by.
    fn cancel_wizard(&mut self) {
        self.state.wizard = None;
        self.state.plugins_filtered_for = None;
        self.state.task_ref_search = None;
        self.state.skill_search = None;
        self.state.file_search = None;
    }

    fn delete_selected_task(&mut self) -> Result<()> {
        if let Some(task) = self.state.board.selected_task().cloned() {
            // Show confirmation popup
            self.state.delete_confirm_popup = Some(DeleteConfirmPopup {
                task_id: task.id.clone(),
                task_title: task.title.clone(),
            });
        }
        Ok(())
    }

    fn perform_delete_task(&mut self, task_id: &str) -> Result<()> {
        if let (Some(db), Some(project_path)) = (&self.state.db, &self.state.project_path) {
            if let Some(task) = db.get_task(task_id)? {
                let cleanup_script = if self.state.flags.no_init_scripts {
                    None
                } else {
                    self.state.config.cleanup_script.clone()
                };
                // Drop the task from the board first, then clean up behind it.
                // The recursive worktree delete is the whole of the freeze this
                // used to cause, and nothing below needs the card to still exist.
                db.delete_task(&task.id)?;

                self.state.stuck_task_notified.remove(&task.id);
                self.state.stuck_task_idle_since.remove(&task.id);
                self.state.phase_status_cache.remove(&task.id);
                self.state.pane_content_hashes.remove(&task.id);

                let tmux_ops = Arc::clone(&self.state.tmux_ops);
                let git_ops = Arc::clone(&self.state.git_ops);
                let project_path = project_path.clone();
                std::thread::spawn(move || {
                    delete_task_resources(
                        &task,
                        cleanup_script.as_deref(),
                        &project_path,
                        tmux_ops.as_ref(),
                        git_ops.as_ref(),
                    );
                });

                self.refresh_tasks()?;
            }
        }
        Ok(())
    }

    fn show_task_diff(&mut self) -> Result<()> {
        if let Some(task) = self.state.board.selected_task() {
            let diff_content = if let Some(worktree_path) = &task.worktree_path {
                let mut exclude_prefixes: Vec<&str> = crate::git::AGENT_CONFIG_DIRS.to_vec();
                let plugin = self.load_task_plugin(task);
                let plugin_dirs: Vec<String> =
                    plugin.map_or_else(Vec::new, |p| p.copy_dirs.clone());
                let plugin_dir_refs: Vec<&str> = plugin_dirs.iter().map(|s| s.as_str()).collect();
                exclude_prefixes.extend(plugin_dir_refs);
                collect_task_diff(
                    worktree_path,
                    self.state.git_ops.as_ref(),
                    &exclude_prefixes,
                )
            } else {
                "(task has no worktree yet)".to_string()
            };

            self.state.diff_popup = Some(DiffPopup {
                task_title: task.title.clone(),
                diff_content,
                scroll_offset: 0,
            });
        }
        Ok(())
    }

    fn move_task_right(&mut self) -> Result<()> {
        let (mut task, project_path) = match (
            self.state.board.selected_task().cloned(),
            self.state.project_path.clone(),
        ) {
            (Some(t), Some(p)) => (t, p),
            _ => return Ok(()),
        };

        let current_status = task.status;
        let next_status = match current_status {
            TaskStatus::Backlog => Some(TaskStatus::Planning),
            TaskStatus::Planning => Some(TaskStatus::Running),
            TaskStatus::Running => Some(TaskStatus::Review),
            TaskStatus::Review => Some(TaskStatus::Done),
            TaskStatus::Done => None,
        };

        if let Some(new_status) = next_status {
            // Block moving out of Backlog when dependencies are not satisfied
            if current_status == TaskStatus::Backlog {
                if let Some(db) = &self.state.db {
                    if !db.deps_satisfied(&task) {
                        self.state.warning_message = Some((
                            "Dependencies not in Review/Done — cannot start task".to_string(),
                            Instant::now(),
                        ));
                        return Ok(());
                    }
                }
            }

            if self.check_phase_incomplete(&task, current_status, new_status) {
                return Ok(());
            }

            let handled = match (current_status, new_status) {
                (TaskStatus::Backlog, TaskStatus::Planning) => {
                    self.transition_to_planning(&mut task, &project_path)?
                }
                (TaskStatus::Planning, TaskStatus::Running) => {
                    self.transition_to_running(&mut task)?
                }
                (TaskStatus::Running, TaskStatus::Review) => {
                    self.transition_to_review(&mut task, &project_path)?
                }
                (TaskStatus::Review, TaskStatus::Done) => {
                    self.transition_to_done(&mut task, &project_path)?
                }
                _ => false,
            };

            if !handled {
                task.status = new_status;
                task.updated_at = chrono::Utc::now();

                // Clear context from previous phase on transition
                task.escalation_note = None;

                if let Some(db) = &self.state.db {
                    db.update_task(&task)?;
                }

                // Clear stale phase context
                self.state.stuck_task_notified.remove(&task.id);
                self.state.stuck_task_idle_since.remove(&task.id);
                self.state.phase_status_cache.remove(&task.id);
            }
        }
        self.refresh_tasks()?;
        Ok(())
    }

    /// Check if the current phase is incomplete (artifact missing + agent still running).
    /// Returns true if a confirmation popup was shown and the caller should return early.
    fn check_phase_incomplete(
        &mut self,
        task: &Task,
        current_status: TaskStatus,
        new_status: TaskStatus,
    ) -> bool {
        if self.state.skip_move_confirm {
            return false;
        }
        if !matches!(
            current_status,
            TaskStatus::Planning | TaskStatus::Running | TaskStatus::Review
        ) {
            return false;
        }
        let plugin = self.load_task_plugin(task);
        let Some(ref wt_path) = task.worktree_path else {
            return false;
        };
        if phase_artifact_fresh(wt_path, current_status, &plugin, task.cycle, task.phase_entered_at) {
            return false;
        }
        let agent_running = task.session_name.as_ref().map_or(false, |target| {
            self.state.tmux_ops.window_exists(target).unwrap_or(false)
                && is_agent_active(&*self.state.tmux_ops, target, Some(task.agent.as_str()))
        });
        if agent_running {
            self.state.move_confirm_popup = Some(MoveConfirmPopup {
                task_id: task.id.clone(),
                from_status: current_status,
                to_status: new_status,
            });
            return true;
        }
        false
    }

    /// Backlog → Planning: create worktree and tmux window, or reuse existing research session.
    /// Returns Ok(true) if handled separately (setup spawned, warning shown), Ok(false) to continue with db update.
    fn transition_to_planning(&mut self, task: &mut Task, project_path: &Path) -> Result<bool> {
        if task.plugin.is_none() {
            task.plugin = self.state.config.workflow_plugin.clone();
        }
        let plugin = self.load_task_plugin(task);

        // Block if planning phase doesn't accept {task} and no prior phase artifact exists
        if plugin
            .as_ref()
            .map_or(false, |p| !p.phase_accepts_task("planning"))
        {
            let has_research = task
                .worktree_path
                .as_ref()
                .map_or(false, |wt| research_artifact_exists(wt, &task.id, &plugin));
            if !has_research {
                self.state.warning_message = Some((
                    format!("Research phase required first — press R to start research"),
                    std::time::Instant::now(),
                ));
                return Ok(true);
            }
        }

        let (planning_agent, agent_switch) =
            needs_agent_switch(&self.state.config, task, "planning");

        let has_live_session = task_has_live_session(&task, self.state.tmux_ops.as_ref());
        if has_live_session {
            // Reuse existing session from research
            let target = task.session_name.clone().unwrap();
            let task_content = task.content_text();
            let planning_phase = determine_phase_variant(
                "planning",
                task.worktree_path.as_deref(),
                &task.id,
                &plugin,
                task.cycle,
            );
            let skill_cmd = resolve_skill_command(
                &plugin,
                planning_phase,
                &planning_agent,
                &task_content,
                task.cycle,
                &task.id,
                true,
            );
            // Non-collapsed twin for the argv path (see `spawn_send_to_agent`).
            let skill_cmd_launch = resolve_skill_command(
                &plugin,
                planning_phase,
                &planning_agent,
                &task_content,
                task.cycle,
                &task.id,
                false,
            );
            let prompt =
                resolve_prompt(&plugin, planning_phase, &task_content, &task.id, task.cycle);
            let prompt_trigger = resolve_prompt_trigger(&plugin, planning_phase);
            let auto_dismiss = plugin
                .as_ref()
                .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
            spawn_send_to_agent(
                Arc::clone(&self.state.tmux_ops),
                Arc::clone(&self.state.agent_registry),
                task.id.clone(),
                self.state.config.agent_hooks,
                self.state.config.auto_trust,
                target,
                task.agent.clone(),
                planning_agent.clone(),
                agent_switch,
                skill_cmd,
                skill_cmd_launch,
                prompt,
                prompt_trigger,
                task_content,
                auto_dismiss,
                task.worktree_path.clone(),
                project_path.to_path_buf(),
                plugin,
            );
            task.agent = planning_agent;
            return Ok(false);
        }

        if self.state.setup_rx.is_some() {
            return Ok(true);
        }

        // Create worktree + tmux window from scratch (non-blocking)
        let task_content = task.content_text();
        let prompt = resolve_prompt(&plugin, "planning", &task_content, &task.id, task.cycle);
        let skill_cmd = resolve_skill_command(
            &plugin,
            "planning",
            &planning_agent,
            &task_content,
            task.cycle,
            &task.id,
            true,
        );
        // The launch lane hands the command to the process in argv, so it keeps the
        // task's own line structure. Only the send-after-ready fallback below needs
        // the flattened form. See `resolve_skill_command`.
        let skill_cmd_launch = resolve_skill_command(
            &plugin,
            "planning",
            &planning_agent,
            &task_content,
            task.cycle,
            &task.id,
            false,
        );
        let prompt_trigger = resolve_prompt_trigger(&plugin, "planning");
        let all_agents = collect_phase_agents(&self.state.config, task);
        let project_name = self.state.project_name.clone();
        let tmux_project_name = self.state.tmux_project_name.clone();
        let base_branch = task
            .base_branch
            .clone()
            .unwrap_or_else(|| self.state.config.base_branch.clone());
        let worktree_dir = self.state.config.worktree_dir.clone();
        let branch_prefix = self.state.config.branch_prefix.clone();
        let copy_files = self.state.config.copy_files.clone();
        let init_script = if self.state.flags.no_init_scripts {
            None
        } else {
            self.state.config.init_script.clone()
        };
        let skip_init_scripts = self.state.flags.no_init_scripts;
        let skip_worktree = self.state.config.skip_worktree;
        let agent_hooks = self.state.config.agent_hooks;
        let tmux_ops = Arc::clone(&self.state.tmux_ops);
        let git_ops = Arc::clone(&self.state.git_ops);
        let agent_ops = self.state.agent_registry.get(&planning_agent);
        let task_id = task.id.clone();
        let task_title = task.title.clone();
        let plugin_name = task.plugin.clone();
        let planning_agent_clone = planning_agent.clone();
        let auto_dismiss = plugin
            .as_ref()
            .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
        let project_path = project_path.to_path_buf();

        // Pre-fetch referenced task info (DB isn't Send, so fetch before spawning thread)
        let referenced_tasks: Vec<ReferencedTaskInfo> = task
            .referenced_tasks
            .as_deref()
            .map(|refs_str| {
                refs_str
                    .split(',')
                    .filter(|s| !s.is_empty())
                    .filter_map(|ref_id| {
                        self.state
                            .db
                            .as_ref()
                            .and_then(|db| db.get_task(ref_id).ok().flatten())
                            .map(|ref_task| ReferencedTaskInfo {
                                slug: generate_task_slug(&ref_task.id, &ref_task.title),
                                branch_name: ref_task.branch_name.clone(),
                                worktree_path: ref_task.worktree_path.clone(),
                            })
                    })
                    .collect()
            })
            .unwrap_or_default();

        let (tx, rx) = mpsc::channel();
        self.state.setup_rx = Some(rx);

        let auto_trust = self.state.config.auto_trust;
        std::thread::spawn(move || {
            let mut tmp_task = Task::new(&task_title, &planning_agent_clone, &project_name);
            tmp_task.id = task_id.clone();
            tmp_task.plugin = plugin_name.clone();

            let result = setup_task_worktree(
                &mut tmp_task,
                &project_path,
                &tmux_project_name,
                &prompt,
                &base_branch,
                &worktree_dir,
                &branch_prefix,
                copy_files,
                init_script,
                &plugin,
                &planning_agent_clone,
                &all_agents,
                tmux_ops.as_ref(),
                git_ops.as_ref(),
                agent_ops.as_ref(),
                &referenced_tasks,
                skip_init_scripts,
                skip_worktree,
                agent_hooks,
                skill_cmd_launch.as_deref(),
            );

            match result {
                Ok((target, launched_with_prompt)) => {
                    let _ = tx.send(SetupResult {
                        task_id: task_id.clone(),
                        session_name: tmp_task.session_name.unwrap_or_default(),
                        worktree_path: tmp_task.worktree_path.unwrap_or_default(),
                        branch_name: tmp_task.branch_name.unwrap_or_default(),
                        new_status: Some(TaskStatus::Planning),
                        agent: planning_agent_clone.clone(),
                        plugin: plugin_name,
                        error: None,
                    });
                    // Skip the whole send-after-ready dance when the agent was
                    // launched with the opening message already in argv.
                    if launched_with_prompt {
                        // nothing to send
                    } else if let Some(target) = wait_for_agent_ready(
                        &tmux_ops,
                        &target,
                        Some(&planning_agent_clone),
                        auto_trust,
                    ) {
                        send_skill_and_prompt(
                            &tmux_ops,
                            &target,
                            &skill_cmd,
                            &prompt,
                            &prompt_trigger,
                            &task_content,
                            &planning_agent_clone,
                            &auto_dismiss,
                            false,
                        );
                    }
                }
                Err(e) => {
                    let _ = tx.send(SetupResult {
                        task_id,
                        session_name: String::new(),
                        worktree_path: String::new(),
                        branch_name: String::new(),
                        new_status: None,
                        agent: planning_agent_clone,
                        plugin: plugin_name,
                        error: Some(format!("Planning setup failed: {}", e)),
                    });
                }
            }
        });

        Ok(true)
    }

    /// Planning → Running: send execution skill/prompt to agent.
    /// Always returns Ok(false) to continue with db update.
    fn transition_to_running(&mut self, task: &mut Task) -> Result<bool> {
        if let Some(session_name) = &task.session_name {
            let plugin = self.load_task_plugin(task);
            let (running_agent, agent_switch) =
                needs_agent_switch(&self.state.config, task, "running");
            let task_content = task.content_text();
            let run_phase = determine_phase_variant(
                "running",
                task.worktree_path.as_deref(),
                &task.id,
                &plugin,
                task.cycle,
            );
            let skill_cmd = resolve_skill_command(
                &plugin,
                run_phase,
                &running_agent,
                &task_content,
                task.cycle,
                &task.id,
                true,
            );
            // Non-collapsed twin for the argv path (see `spawn_send_to_agent`).
            let skill_cmd_launch = resolve_skill_command(
                &plugin,
                run_phase,
                &running_agent,
                &task_content,
                task.cycle,
                &task.id,
                false,
            );
            let prompt = resolve_prompt(&plugin, run_phase, &task_content, &task.id, task.cycle);
            let prompt_trigger = resolve_prompt_trigger(&plugin, run_phase);
            let auto_dismiss = plugin
                .as_ref()
                .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
            spawn_send_to_agent(
                Arc::clone(&self.state.tmux_ops),
                Arc::clone(&self.state.agent_registry),
                task.id.clone(),
                self.state.config.agent_hooks,
                self.state.config.auto_trust,
                session_name.clone(),
                task.agent.clone(),
                running_agent.clone(),
                agent_switch,
                skill_cmd,
                skill_cmd_launch,
                prompt,
                prompt_trigger,
                task_content,
                auto_dismiss,
                task.worktree_path.clone(),
                self.state.project_path.clone().unwrap_or_default(),
                plugin,
            );
            task.agent = running_agent;
        }
        Ok(false)
    }

    /// Running → Review: send review skill/prompt, then handle PR state.
    /// Returns Ok(true) always (PR push or review confirm popup shown).
    fn transition_to_review(&mut self, task: &mut Task, project_path: &Path) -> Result<bool> {
        let (review_agent, agent_switch) = needs_agent_switch(&self.state.config, task, "review");
        if let Some(session_name) = &task.session_name {
            let plugin = self.load_task_plugin(task);
            let task_content = task.content_text();
            let skill_cmd = resolve_skill_command(
                &plugin,
                "review",
                &review_agent,
                &task_content,
                task.cycle,
                &task.id,
                true,
            );
            // Non-collapsed twin for the argv path (see `spawn_send_to_agent`).
            let skill_cmd_launch = resolve_skill_command(
                &plugin,
                "review",
                &review_agent,
                &task_content,
                task.cycle,
                &task.id,
                false,
            );
            let prompt = resolve_prompt(&plugin, "review", &task_content, &task.id, task.cycle);
            let prompt_trigger = resolve_prompt_trigger(&plugin, "review");
            let auto_dismiss = plugin
                .as_ref()
                .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
            spawn_send_to_agent(
                Arc::clone(&self.state.tmux_ops),
                Arc::clone(&self.state.agent_registry),
                task.id.clone(),
                self.state.config.agent_hooks,
                self.state.config.auto_trust,
                session_name.clone(),
                task.agent.clone(),
                review_agent.clone(),
                agent_switch,
                skill_cmd,
                skill_cmd_launch,
                prompt,
                prompt_trigger,
                task_content,
                auto_dismiss,
                task.worktree_path.clone(),
                project_path.to_path_buf(),
                plugin,
            );
        }
        task.agent = review_agent.clone();

        // PR already exists (task was resumed from Review) — push new changes
        if task.pr_number.is_some() {
            self.state.pr_status_popup = Some(PrStatusPopup {
                status: PrCreationStatus::Pushing,
                pr_url: None,
                error_message: None,
            });

            let task_clone = task.clone();
            let project_path_clone = project_path.to_path_buf();
            let git_ops = Arc::clone(&self.state.git_ops);
            let agent_ops = self.state.agent_registry.get(&review_agent);

            let (tx, rx) = mpsc::channel();
            self.state.pr_creation_rx = Some(rx);

            std::thread::spawn(move || {
                let result =
                    push_changes_to_existing_pr(&task_clone, git_ops.as_ref(), agent_ops.as_ref());
                match result {
                    Ok(pr_url) => {
                        if let Ok(db) = crate::db::Database::open_project(&project_path_clone) {
                            let mut updated_task = task_clone;
                            updated_task.status = TaskStatus::Review;
                            updated_task.updated_at = chrono::Utc::now();
                            let _ = db.update_task(&updated_task);
                        }
                        let _ = tx.send(Ok((0, pr_url)));
                    }
                    Err(e) => {
                        let _ = tx.send(Err(e.to_string()));
                    }
                }
            });

            return Ok(true);
        }

        // No PR yet — show confirmation popup
        self.state.review_confirm_popup = Some(ReviewConfirmPopup {
            task_id: task.id.clone(),
            task_title: task.title.clone(),
        });
        Ok(true)
    }

    /// Review → Done: check PR state, uncommitted changes, or clean up.
    /// Returns Ok(true) if a confirmation popup was shown, Ok(false) to continue with db update.
    fn transition_to_done(&mut self, task: &mut Task, project_path: &Path) -> Result<bool> {
        if let Some(pr_number) = task.pr_number {
            let pr_state = self
                .state
                .git_provider_ops
                .get_pr_state(project_path, pr_number)?;
            let confirm_state = match pr_state {
                PullRequestState::Merged => DoneConfirmPrState::Merged,
                PullRequestState::Closed => DoneConfirmPrState::Closed,
                PullRequestState::Open => DoneConfirmPrState::Open,
                PullRequestState::Unknown => DoneConfirmPrState::Unknown,
            };
            self.state.done_confirm_popup = Some(DoneConfirmPopup {
                task_id: task.id.clone(),
                pr_number,
                pr_state: confirm_state,
            });
            return Ok(true);
        }

        // No PR — check for uncommitted changes
        let has_uncommitted = task
            .worktree_path
            .as_ref()
            .map_or(false, |wt| self.state.git_ops.has_changes(Path::new(wt)));
        if has_uncommitted {
            self.state.done_confirm_popup = Some(DoneConfirmPopup {
                task_id: task.id.clone(),
                pr_number: 0,
                pr_state: DoneConfirmPrState::UncommittedChanges,
            });
            return Ok(true);
        }

        // Clean — spawn background cleanup
        let session_name = task.session_name.clone();
        let worktree_path = task.worktree_path.clone();
        let branch_name = task.branch_name.clone();
        let agent = task.agent.clone();
        task.session_name = None;
        task.worktree_path = None;

        let tmux_ops = Arc::clone(&self.state.tmux_ops);
        let git_ops = Arc::clone(&self.state.git_ops);
        let task_id_clone = task.id.clone();
        let project_path_clone = project_path.to_path_buf();
        let cleanup_script = if self.state.flags.no_init_scripts {
            None
        } else {
            self.state.config.cleanup_script.clone()
        };
        std::thread::spawn(move || {
            cleanup_task_resources(
                &task_id_clone,
                &agent,
                &branch_name,
                &session_name,
                &worktree_path,
                cleanup_script.as_deref(),
                &project_path_clone,
                tmux_ops.as_ref(),
                git_ops.as_ref(),
            );
        });
        Ok(false)
    }

    /// Start a research session for a Backlog task (creates worktree, reused in planning)
    fn start_research(&mut self, task_id: &str) -> Result<()> {
        // Don't start if a setup is already in progress
        if self.state.setup_rx.is_some() {
            return Ok(());
        }

        let mut task = {
            let Some(db) = &self.state.db else {
                return Ok(());
            };
            let Some(task) = db.get_task(task_id)? else {
                return Ok(());
            };
            // Block research when dependencies are not satisfied
            if task.status == TaskStatus::Backlog && !db.deps_satisfied(&task) {
                self.state.warning_message = Some((
                    "Dependencies not in Review/Done — cannot start task".to_string(),
                    Instant::now(),
                ));
                return Ok(());
            }
            task
        };
        let Some(project_path) = self.state.project_path.clone() else {
            return Ok(());
        };

        // Stamp plugin on task for research (only if not already set at task creation)
        if task.plugin.is_none() {
            task.plugin = self.state.config.workflow_plugin.clone();
        }
        let plugin_name = task.plugin.clone();
        let plugin = self.load_task_plugin(&task);

        // Block if plugin has no research command (e.g. OpenSpec uses planning as first phase)
        let has_research_cmd = plugin.as_ref().map_or(false, |p| {
            p.commands.research.is_some() || p.commands.preresearch.is_some()
        });
        if !has_research_cmd {
            self.state.warning_message = Some((
                "This plugin has no research phase — move to Planning instead".to_string(),
                std::time::Instant::now(),
            ));
            return Ok(());
        }

        let agent_name = phase_agent(&self.state.config, &task, "research").to_string();

        let task_content = task.content_text();

        let all_agents = collect_phase_agents(&self.state.config, &task);
        let project_name = self.state.project_name.clone();
        let tmux_project_name = self.state.tmux_project_name.clone();
        let base_branch = task
            .base_branch
            .clone()
            .unwrap_or_else(|| self.state.config.base_branch.clone());
        let worktree_dir = self.state.config.worktree_dir.clone();
        let branch_prefix = self.state.config.branch_prefix.clone();
        let copy_files = self.state.config.copy_files.clone();
        let init_script = if self.state.flags.no_init_scripts {
            None
        } else {
            self.state.config.init_script.clone()
        };
        let skip_init_scripts = self.state.flags.no_init_scripts;
        let skip_worktree = self.state.config.skip_worktree;
        let agent_hooks = self.state.config.agent_hooks;

        let tmux_ops = Arc::clone(&self.state.tmux_ops);
        let git_ops = Arc::clone(&self.state.git_ops);
        let agent_ops = self.state.agent_registry.get(&agent_name);

        let task_id = task.id.clone();
        let task_title = task.title.clone();
        let task_cycle = task.cycle;
        let auto_dismiss = plugin
            .as_ref()
            .map_or_else(Vec::new, |p| p.auto_dismiss.clone());

        let (tx, rx) = mpsc::channel();
        self.state.setup_rx = Some(rx);

        let auto_trust = self.state.config.auto_trust;
        std::thread::spawn(move || {
            // Create a temporary task to pass to setup_task_worktree
            let mut tmp_task = Task::new(&task_title, &agent_name, &project_name);
            tmp_task.id = task_id.clone();
            tmp_task.plugin = plugin_name.clone();

            // setup_task_worktree creates the worktree and copies files (including preresearch artifacts if they exist at root)
            // We pass an empty prompt here — the actual prompt is resolved after worktree creation
            let result = setup_task_worktree(
                &mut tmp_task,
                &project_path,
                &tmux_project_name,
                "",
                &base_branch,
                &worktree_dir,
                &branch_prefix,
                copy_files,
                init_script,
                &plugin,
                &agent_name,
                &all_agents,
                tmux_ops.as_ref(),
                git_ops.as_ref(),
                agent_ops.as_ref(),
                &[],
                skip_init_scripts,
                skip_worktree,
                agent_hooks,
                // Research keeps the send-after-ready path for now: its skill is
                // resolved later in the thread, and the launch lane is planning-only.
                None,
            );

            match result {
                Ok((target, launched_with_prompt)) => {
                    let worktree_path = tmp_task.worktree_path.clone().unwrap_or_default();

                    // Determine preresearch vs research by checking if preresearch artifacts
                    // exist in the worktree (they would have been copied from project root via copy_files)
                    let use_preresearch = plugin.as_ref().map_or(false, |p| {
                        p.commands.preresearch.is_some()
                            && !p.artifacts.preresearch.is_empty()
                            && !p
                                .artifacts
                                .preresearch
                                .iter()
                                .all(|a| Path::new(&worktree_path).join(a).exists())
                    });
                    let research_phase = if use_preresearch {
                        "preresearch"
                    } else {
                        "research"
                    };

                    let prompt = resolve_prompt(
                        &plugin,
                        research_phase,
                        &task_content,
                        &task_id,
                        task_cycle,
                    );
                    let skill_cmd = resolve_skill_command(
                        &plugin,
                        research_phase,
                        &agent_name,
                        &task_content,
                        task_cycle,
                        &task_id,
                        true,
                    );
                    let prompt_trigger = resolve_prompt_trigger(&plugin, research_phase);

                    let _ = tx.send(SetupResult {
                        task_id: task_id.clone(),
                        session_name: tmp_task.session_name.unwrap_or_default(),
                        worktree_path,
                        branch_name: tmp_task.branch_name.unwrap_or_default(),
                        new_status: None, // stays in Backlog
                        agent: agent_name.clone(),
                        plugin: plugin_name,
                        error: None,
                    });

                    // Wait for agent ready and send skill+prompt
                    // Skip the whole send-after-ready dance when the agent was
                    // launched with the opening message already in argv.
                    if launched_with_prompt {
                        // nothing to send
                    } else if let Some(target) =
                        wait_for_agent_ready(&tmux_ops, &target, Some(&agent_name), auto_trust)
                    {
                        send_skill_and_prompt(
                            &tmux_ops,
                            &target,
                            &skill_cmd,
                            &prompt,
                            &prompt_trigger,
                            &task_content,
                            &agent_name,
                            &auto_dismiss,
                            false,
                        );
                    }
                }
                Err(e) => {
                    let _ = tx.send(SetupResult {
                        task_id,
                        session_name: String::new(),
                        worktree_path: String::new(),
                        branch_name: String::new(),
                        new_status: None,
                        agent: agent_name,
                        plugin: plugin_name,
                        error: Some(format!("Research setup failed: {}", e)),
                    });
                }
            }
        });

        Ok(())
    }

    /// Build and open the dependency-graph overlay for the current project's tasks.
    fn show_dependency_graph(&mut self) -> Result<()> {
        let Some(db) = self.state.db.as_ref() else {
            return Ok(());
        };
        let tasks = db.get_all_tasks().unwrap_or_default();
        if tasks.is_empty() {
            self.state.warning_message = Some((
                "No tasks to show in the dependency view".to_string(),
                Instant::now(),
            ));
            return Ok(());
        }
        let graph = crate::tui::dep_graph::build_dep_graph(&tasks, |t| db.deps_satisfied(t));
        // Start the cursor on the first unblocked node if there is one.
        let selected = graph.nodes.iter().position(|n| n.unblocked).unwrap_or(0);
        self.state.dep_graph_popup = Some(DepGraphPopup {
            graph,
            selected,
            marked: HashSet::new(),
            scroll_levels: Cell::new(0),
            visible_levels: Cell::new(1),
        });
        Ok(())
    }

    /// Key handling for the dependency-graph overlay.
    /// Keys for the `W` overlay.
    ///
    /// Closing it does **not** stop the server: someone opens this, scans, and
    /// closes it while carrying on with the board. Only `s` and quitting stop
    /// serving.
    fn handle_mobile_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let Some(popup) = self.state.mobile_popup.as_mut() else {
            return Ok(());
        };
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') | KeyCode::Char('W') => {
                self.state.mobile_popup = None;
            }
            // Each key is a whole action, not a mode plus a trigger.
            KeyCode::Char('s') => popup.serve(
                &mut self.state.serve_session,
                crate::tui::serve_control::DEFAULT_PORT,
                crate::tui::serve_control::Reach::Lan,
            ),
            KeyCode::Char('t') => popup.serve(
                &mut self.state.serve_session,
                crate::tui::serve_control::DEFAULT_PORT,
                crate::tui::serve_control::Reach::Tailnet,
            ),
            KeyCode::Char('x') => popup.revoke_selected(),
            KeyCode::Char('j') | KeyCode::Down => popup.move_selection(1),
            KeyCode::Char('k') | KeyCode::Up => popup.move_selection(-1),
            KeyCode::Char('r') => {
                popup.reload_devices();
                popup.message = Some("Reloaded.".to_string());
            }
            // Swallow everything else rather than letting it reach the board
            // behind the overlay.
            _ => {}
        }
        Ok(())
    }

    /// The `W` overlay: a QR to scan, and the devices already paired.
    fn draw_mobile_popup(
        popup: &crate::tui::serve_control::MobilePopup,
        session: Option<&crate::tui::serve_control::ServeSession>,
        frame: &mut Frame,
        area: Rect,
        theme: &crate::config::ThemeConfig,
    ) {
        use ratatui::widgets::Clear;

        let accent = hex_to_color(&theme.color_accent);
        let dim = hex_to_color(&theme.color_dimmed);
        let text = hex_to_color(&theme.color_text);
        let selected = hex_to_color(&theme.color_selected);

        let qr = session.and_then(|s| crate::tui::serve_control::qr_grid(&s.url));
        // The QR is the widest thing here and it must not wrap — a wrapped QR
        // is unscannable and reads as corruption rather than as a layout bug.
        // Two module rows per text row, so the height is half the width.
        let qr_width = qr.as_ref().map_or(0, |(w, _)| *w);
        let qr_height = qr_width.div_ceil(2);

        let serving = session.is_some();

        let mut lines: Vec<Line> = Vec::new();

        match (session, &qr) {
            (Some(session), Some((total, dark))) => {
                lines.extend(qr_lines(*total, dark));
                lines.push(Line::from(""));
                lines.push(Line::from(Span::styled(
                    session.url.clone(),
                    Style::default().fg(accent),
                )));
                lines.push(Line::from(Span::styled(
                    "Scan it. The code is single-use; paired devices need nothing.",
                    Style::default().fg(dim),
                )));
                // Say the reach out loud. A QR invites the assumption that it
                // works from anywhere, and a private address does not — the
                // failure is a phone on mobile data timing out against an
                // unroutable host, which looks like a broken pairing rather
                // than a network that was never going to carry it.
                lines.push(Line::from(Span::styled(
                    if session.is_lan_only() {
                        "Works on this wifi only — a private address is unroutable from mobile data."
                    } else {
                        "Reachable from outside this network."
                    },
                    Style::default().fg(selected),
                )));
            }
            (Some(session), None) => {
                lines.push(Line::from(Span::styled(
                    session.url.clone(),
                    Style::default().fg(accent),
                )));
            }
            (None, _) => {
                // Both options, each stating what it gives. The alternative —
                // one key setting a mode another key acts on — means neither
                // label can say what pressing it will do.
                lines.push(Line::from(Span::styled(
                    "Not serving.",
                    Style::default().fg(dim),
                )));
                lines.push(Line::from(""));
                for (key, reach) in [
                    ("s", crate::tui::serve_control::Reach::Lan),
                    ("t", crate::tui::serve_control::Reach::Tailnet),
                ] {
                    let blocked = reach.unavailable();
                    lines.push(Line::from(vec![
                        Span::styled(
                            format!("  {key}  "),
                            Style::default()
                                .fg(if blocked.is_some() { dim } else { selected })
                                .add_modifier(Modifier::BOLD),
                        ),
                        Span::styled(
                            format!("{:<15}", reach.label()),
                            Style::default().fg(if blocked.is_some() { dim } else { text }),
                        ),
                        Span::styled(reach.describe(), Style::default().fg(dim)),
                    ]));
                    if let Some(why) = blocked {
                        lines.push(Line::from(Span::styled(
                            format!("     unavailable: {why}"),
                            Style::default().fg(hex_to_color(&theme.color_description)),
                        )));
                    }
                }
                lines.push(Line::from(""));
                lines.push(Line::from(Span::styled(
                    "A paired device can type into your agents.",
                    Style::default().fg(dim),
                )));
            }
        }

        lines.push(Line::from(""));
        lines.push(Line::from(Span::styled(
            format!("Paired devices ({})", popup.devices.len()),
            Style::default().fg(text).add_modifier(Modifier::BOLD),
        )));

        if popup.devices.is_empty() {
            lines.push(Line::from(Span::styled(
                "  none yet",
                Style::default().fg(dim),
            )));
        } else {
            for (i, device) in popup.devices.iter().enumerate() {
                let marker = if i == popup.selected { "▸ " } else { "  " };
                let seen = device
                    .last_seen
                    .map(|t| t.format("%Y-%m-%d %H:%M").to_string())
                    .unwrap_or_else(|| "never".to_string());
                lines.push(Line::from(vec![
                    Span::styled(
                        format!("{marker}{}", device.label),
                        Style::default().fg(if i == popup.selected { selected } else { text }),
                    ),
                    Span::styled(format!("  last seen {seen}"), Style::default().fg(dim)),
                ]));
            }
        }

        if let Some(ref message) = popup.message {
            lines.push(Line::from(""));
            lines.push(Line::from(Span::styled(
                message.clone(),
                Style::default().fg(selected),
            )));
        }

        lines.push(Line::from(""));
        lines.push(Line::from(Span::styled(
            // Trimmed to fit the box, like the board's own footer: `r` still
            // reloads, it just lives in HELP rather than here. A footer that
            // runs off the edge advertises a key by half its name.
            if serving {
                "[s] stop  [x] revoke  [j/k] move  [Esc] close, keeps serving"
            } else {
                "[s] wifi  [t] tailnet  [x] revoke  [j/k] move  [Esc] close"
            },
            Style::default().fg(dim),
        )));

        // Sized from the longest line it will actually draw. `Paragraph` is
        // left unwrapped on purpose — wrapping would break the QR's rows into
        // nonsense — so anything wider than the box is silently truncated.
        //
        // Measuring the QR alone is not enough, and the shortfall is not
        // cosmetic: the pairing URL is longer than the QR is wide, and a code
        // missing its last characters is not a shorter code but an invalid
        // one. Clicking that link fails to pair and then reports "This device
        // is not authorised", which reads as a pairing bug rather than a
        // layout one.
        let content_width = lines.iter().map(|l| l.width()).max().unwrap_or(0) as u16;
        let width = (qr_width as u16 + 6)
            .max(content_width + 4)
            .max(MOBILE_POPUP_MIN_WIDTH)
            .min(area.width.saturating_sub(2));
        let body_height = qr_height as u16 + popup.devices.len().max(1) as u16 + 10;
        let height = body_height.min(area.height.saturating_sub(2));
        let rect = centered_rect_fixed_width(width, 100, area);
        let rect = Rect {
            x: rect.x,
            y: area.y + (area.height.saturating_sub(height)) / 2,
            width: rect.width.min(width),
            height,
        };

        frame.render_widget(Clear, rect);

        let block = Block::default()
            .borders(Borders::ALL)
            .border_style(Style::default().fg(hex_to_color(&theme.color_popup_border)))
            .title(Span::styled(
                if serving {
                    " Mobile — serving "
                } else {
                    " Mobile "
                },
                Style::default()
                    .fg(hex_to_color(&theme.color_popup_header))
                    .add_modifier(Modifier::BOLD),
            ));
        let inner = block.inner(rect);
        frame.render_widget(block, rect);

        frame.render_widget(Paragraph::new(lines), inner);
    }

    fn handle_dep_graph_key(&mut self, key: crossterm::event::KeyEvent) -> Result<()> {
        let Some(popup) = self.state.dep_graph_popup.as_mut() else {
            return Ok(());
        };
        match key.code {
            KeyCode::Esc | KeyCode::Char('q') => {
                self.state.dep_graph_popup = None;
            }
            KeyCode::Char('j') | KeyCode::Down => {
                Self::dep_graph_move_vertical(popup, 1);
            }
            KeyCode::Char('k') | KeyCode::Up => {
                Self::dep_graph_move_vertical(popup, -1);
            }
            KeyCode::Char('l') | KeyCode::Right => {
                Self::dep_graph_move_horizontal(popup, 1);
            }
            KeyCode::Char('h') | KeyCode::Left => {
                Self::dep_graph_move_horizontal(popup, -1);
            }
            KeyCode::Char(' ') => {
                // Toggle mark on the selected node, only if it is unblocked.
                if let Some(node) = popup.graph.nodes.get(popup.selected) {
                    if node.unblocked {
                        let id = node.task_id.clone();
                        if !popup.marked.remove(&id) {
                            popup.marked.insert(id);
                        }
                    }
                }
            }
            KeyCode::Char('a') => {
                // Mark all unblocked nodes.
                for id in popup.graph.unblocked_ids() {
                    popup.marked.insert(id);
                }
            }
            KeyCode::Char('c') => {
                popup.marked.clear();
            }
            KeyCode::Enter => {
                // Collect targets: marked nodes, or the selected node if nothing
                // is marked and it is unblocked.
                let mut targets: Vec<String> = popup
                    .graph
                    .nodes
                    .iter()
                    .filter(|n| n.unblocked && popup.marked.contains(&n.task_id))
                    .map(|n| n.task_id.clone())
                    .collect();
                if targets.is_empty() {
                    if let Some(node) = popup.graph.nodes.get(popup.selected) {
                        if node.unblocked {
                            targets.push(node.task_id.clone());
                        }
                    }
                }
                if targets.is_empty() {
                    self.state.warning_message = Some((
                        "No unblocked tasks selected — press Space to mark one".to_string(),
                        Instant::now(),
                    ));
                    return Ok(());
                }
                self.state.dep_graph_popup = None;
                self.batch_move_unblocked(targets)?;
            }
            _ => {}
        }
        Ok(())
    }

    /// Move the cursor up/down within the current level (column).
    fn dep_graph_move_vertical(popup: &mut DepGraphPopup, delta: i32) {
        let Some(node) = popup.graph.nodes.get(popup.selected) else {
            return;
        };
        let level = node.level;
        let Some(col) = popup.graph.levels.get(level) else {
            return;
        };
        let pos = col.iter().position(|&i| i == popup.selected).unwrap_or(0);
        let new_pos = (pos as i32 + delta).clamp(0, col.len() as i32 - 1) as usize;
        if let Some(&idx) = col.get(new_pos) {
            popup.selected = idx;
        }
    }

    /// Move the cursor left/right across levels, keeping a similar row position.
    fn dep_graph_move_horizontal(popup: &mut DepGraphPopup, delta: i32) {
        let Some(node) = popup.graph.nodes.get(popup.selected) else {
            return;
        };
        let level = node.level;
        let cur_pos = popup
            .graph
            .levels
            .get(level)
            .and_then(|col| col.iter().position(|&i| i == popup.selected))
            .unwrap_or(0);
        let new_level = (level as i32 + delta).clamp(0, popup.graph.level_count() as i32 - 1);
        if new_level < 0 {
            return;
        }
        let new_level = new_level as usize;
        if let Some(col) = popup.graph.levels.get(new_level) {
            if !col.is_empty() {
                let new_pos = cur_pos.min(col.len() - 1);
                popup.selected = col[new_pos];
            }
        }
        // Scrolling is handled by the draw pass, which re-clamps `scroll_levels`
        // each frame to keep the selected node on screen.
    }

    /// Enqueue unblocked tasks for serialized worktree setup, then kick off the first.
    fn batch_move_unblocked(&mut self, task_ids: Vec<String>) -> Result<()> {
        for id in task_ids {
            self.enqueue_setup(&id, SetupIntent::PluginDefault, None);
        }
        self.try_start_next_queued_setup()
    }

    /// Queue a Backlog task for the setup slot, unless it is already waiting.
    ///
    /// Deduplicated on the task rather than on the pair: a task queued twice
    /// with different intents is a caller changing its mind, and running the
    /// first one and then the second would set the worktree up twice. The
    /// duplicate's request is resolved rather than dropped, so a caller polling
    /// it is not left waiting on a row nothing will ever touch.
    fn enqueue_setup(&mut self, task_id: &str, intent: SetupIntent, request_id: Option<String>) {
        if self.state.setup_queue.iter().any(|q| q.task_id == task_id) {
            if let (Some(db), Some(rid)) = (&self.state.db, request_id) {
                let _ = db.mark_transition_processed(
                    &rid,
                    Some("Task is already queued for worktree setup"),
                );
            }
            return;
        }
        self.state.setup_queue.push_back(QueuedSetup {
            task_id: task_id.to_string(),
            intent,
            request_id,
        });
    }

    /// If no worktree setup is currently running, start the next queued batch task.
    /// Routes each task to research when its plugin supports it, else to planning.
    fn try_start_next_queued_setup(&mut self) -> Result<()> {
        // A setup is in progress — it will call back here when it completes.
        if self.state.setup_rx.is_some() {
            return Ok(());
        }
        while let Some(QueuedSetup {
            task_id,
            intent,
            request_id,
        }) = self.state.setup_queue.pop_front()
        {
            // Re-validate: the task may have changed status or deps since queuing.
            // A queued request outlives the state it was accepted against, so
            // each way of failing here has to resolve the request — dropping it
            // silently leaves a caller polling `pending` forever.
            let Some(db) = self.state.db.as_ref() else {
                self.resolve_queued_request(&request_id, Some("No project database"));
                continue;
            };
            let Some(task) = db.get_task(&task_id).ok().flatten() else {
                self.resolve_queued_request(&request_id, Some("Task no longer exists"));
                continue;
            };
            if task.status != TaskStatus::Backlog {
                self.resolve_queued_request(
                    &request_id,
                    Some(&format!(
                        "Task left Backlog while queued (now: {})",
                        task.status.as_str()
                    )),
                );
                continue;
            }
            if !db.deps_satisfied(&task) {
                self.resolve_queued_request(
                    &request_id,
                    Some("Cannot advance task: dependencies not in Review/Done"),
                );
                continue;
            }

            let intent = match intent {
                // Prefer research if the plugin defines a research/preresearch command.
                SetupIntent::PluginDefault => {
                    let plugin = self.load_task_plugin(&task);
                    let has_research_cmd = plugin.as_ref().map_or(false, |p| {
                        p.commands.research.is_some() || p.commands.preresearch.is_some()
                    });
                    if has_research_cmd {
                        SetupIntent::Research
                    } else {
                        SetupIntent::Planning
                    }
                }
                explicit => explicit,
            };

            // A failure here belongs to this request, not to the drain: taking
            // `?` would abandon everything queued behind it and leave every one
            // of their requests pending.
            let started = match intent {
                SetupIntent::Research => self.start_research(&task_id),
                SetupIntent::Planning => self.start_planning_from_backlog(&task_id),
                SetupIntent::Running => self.move_backlog_to_running_by_id(&task_id),
                SetupIntent::PluginDefault => unreachable!("resolved above"),
            };
            match started {
                Ok(()) => self.resolve_queued_request(&request_id, None),
                Err(e) => self.resolve_queued_request(&request_id, Some(&e.to_string())),
            }

            // start_research / start_planning_from_backlog set setup_rx when they
            // spawn a background setup. If so, stop draining — the completion
            // handler will resume the queue. If not (no-op), keep draining.
            if self.state.setup_rx.is_some() {
                break;
            }
        }
        self.refresh_tasks()?;
        Ok(())
    }

    /// Queue a Backlog task's setup and try to start it now.
    ///
    /// Every Backlog transition from MCP comes through here, whether or not the
    /// setup slot is free, so the queue is the single ordering authority and no
    /// transition is rejected for arriving while the slot is busy. A rejection
    /// there would be invisible: `move_task` has already answered `queued`, and
    /// nothing would retry the task.
    fn queue_backlog_setup(
        &mut self,
        req: &TransitionRequest,
        intent: SetupIntent,
    ) -> Result<TransitionOutcome> {
        self.enqueue_setup(&req.task_id, intent, Some(req.id.clone()));
        self.try_start_next_queued_setup()?;
        Ok(TransitionOutcome::Queued)
    }

    /// Mark a queued request's transition row processed, if it came from one.
    ///
    /// `TransitionOutcome::Queued` defers the marking to here, so this is the
    /// only place a setup queued from MCP stops reporting `pending`.
    fn resolve_queued_request(&self, request_id: &Option<String>, error: Option<&str>) {
        if let (Some(db), Some(rid)) = (&self.state.db, request_id) {
            let _ = db.mark_transition_processed(rid, error);
        }
    }

    /// Move a Backlog task into Planning (the planning fallback for plugins with
    /// no research phase). Mirrors `move_task_right`'s Backlog→Planning branch.
    fn start_planning_from_backlog(&mut self, task_id: &str) -> Result<()> {
        if self.state.setup_rx.is_some() {
            return Ok(());
        }
        let (mut task, project_path) = match (
            self.state
                .db
                .as_ref()
                .and_then(|db| db.get_task(task_id).ok().flatten()),
            self.state.project_path.clone(),
        ) {
            (Some(t), Some(p)) => (t, p),
            _ => return Ok(()),
        };
        if task.status != TaskStatus::Backlog {
            return Ok(());
        }
        let handled = self.transition_to_planning(&mut task, &project_path)?;
        if !handled {
            task.status = TaskStatus::Planning;
            task.updated_at = chrono::Utc::now();
            task.escalation_note = None;
            if let Some(db) = &self.state.db {
                db.update_task(&task)?;
            }
            self.state.stuck_task_notified.remove(&task.id);
            self.state.stuck_task_idle_since.remove(&task.id);
            self.state.phase_status_cache.remove(&task.id);
        }
        Ok(())
    }

    /// Move task directly from Backlog to Running (skip Planning)
    fn move_backlog_to_running(&mut self) -> Result<()> {
        let task_id = match self.state.board.selected_task() {
            Some(t) if t.status == TaskStatus::Backlog => t.id.clone(),
            _ => return Ok(()),
        };
        self.move_backlog_to_running_by_id(&task_id)
    }

    fn move_backlog_to_running_by_id(&mut self, task_id: &str) -> Result<()> {
        // Don't start if a setup is already in progress
        if self.state.setup_rx.is_some() {
            anyhow::bail!("Another task setup is already in progress, try again shortly");
        }

        let (mut task, project_path) = match (
            self.state
                .db
                .as_ref()
                .and_then(|db| db.get_task(task_id).ok().flatten()),
            self.state.project_path.clone(),
        ) {
            (Some(t), Some(p)) => (t, p),
            _ => return Ok(()),
        };

        if task.status != TaskStatus::Backlog {
            anyhow::bail!(
                "Task must be in Backlog to move to Running (current: {})",
                task.status.as_str()
            );
        }

        // Block when dependencies are not satisfied
        if let Some(db) = &self.state.db {
            if !db.deps_satisfied(&task) {
                self.state.warning_message = Some((
                    "Dependencies not in Review/Done — cannot start task".to_string(),
                    Instant::now(),
                ));
                return Ok(());
            }
        }

        // Stamp plugin on task before checking research requirement
        if task.plugin.is_none() {
            task.plugin = self.state.config.workflow_plugin.clone();
        }

        // Block if running phase doesn't accept {task} and no prior phase artifact exists
        let plugin_check = self.load_task_plugin(&task);
        if plugin_check
            .as_ref()
            .map_or(false, |p| !p.phase_accepts_task("running"))
        {
            let has_prior = task.worktree_path.as_ref().map_or(false, |wt| {
                research_artifact_exists(wt, &task.id, &plugin_check)
                    || phase_artifact_exists(wt, TaskStatus::Planning, &plugin_check, task.cycle)
            });
            if !has_prior {
                self.state.warning_message = Some((
                    format!("Research or planning phase required first"),
                    std::time::Instant::now(),
                ));
                return Ok(());
            }
        }

        // Build prompt - skip planning, go straight to implementation
        let task_content = task.content_text();

        let plugin_name = task.plugin.clone();
        let plugin = self.load_task_plugin(&task);
        let running_agent = phase_agent(&self.state.config, &task, "running").to_string();
        let all_agents = collect_phase_agents(&self.state.config, &task);
        let prompt = resolve_prompt(&plugin, "running", &task_content, &task.id, task.cycle);
        let skill_cmd = resolve_skill_command(
            &plugin,
            "running",
            &running_agent,
            &task_content,
            task.cycle,
            &task.id,
            true,
        );
        // Verbatim variant for the launch lane — see the planning path above.
        let skill_cmd_launch = resolve_skill_command(
            &plugin,
            "running",
            &running_agent,
            &task_content,
            task.cycle,
            &task.id,
            false,
        );
        let prompt_trigger = resolve_prompt_trigger(&plugin, "running");
        let auto_dismiss = plugin
            .as_ref()
            .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
        let clear_context_on_advance = plugin
            .as_ref()
            .map_or(false, |p| p.clear_context_on_advance);

        // If a live session already exists (e.g. from a prior research/planning phase),
        // reuse it instead of creating a duplicate tmux window.
        let has_live_session = task_has_live_session(&task, self.state.tmux_ops.as_ref());
        if has_live_session {
            let target = task.session_name.clone().unwrap();
            let (agent_switch_agent, agent_switch) =
                needs_agent_switch(&self.state.config, &task, "running");
            spawn_send_to_agent(
                Arc::clone(&self.state.tmux_ops),
                Arc::clone(&self.state.agent_registry),
                task.id.clone(),
                self.state.config.agent_hooks,
                self.state.config.auto_trust,
                target,
                task.agent.clone(),
                agent_switch_agent.clone(),
                agent_switch,
                skill_cmd,
                skill_cmd_launch,
                prompt,
                prompt_trigger,
                task_content,
                auto_dismiss,
                task.worktree_path.clone(),
                project_path.clone(),
                plugin,
            );
            task.agent = agent_switch_agent;
            task.status = TaskStatus::Running;
            task.updated_at = chrono::Utc::now();
            if let Some(db) = &self.state.db {
                db.update_task(&task)?;
            }
            self.refresh_tasks()?;
            return Ok(());
        }

        let project_name = self.state.project_name.clone();
        let tmux_project_name = self.state.tmux_project_name.clone();
        let base_branch = task
            .base_branch
            .clone()
            .unwrap_or_else(|| self.state.config.base_branch.clone());
        let worktree_dir = self.state.config.worktree_dir.clone();
        let branch_prefix = self.state.config.branch_prefix.clone();
        let copy_files = self.state.config.copy_files.clone();
        let init_script = if self.state.flags.no_init_scripts {
            None
        } else {
            self.state.config.init_script.clone()
        };
        let skip_init_scripts = self.state.flags.no_init_scripts;
        let skip_worktree = self.state.config.skip_worktree;
        let agent_hooks = self.state.config.agent_hooks;
        let tmux_ops = Arc::clone(&self.state.tmux_ops);
        let git_ops = Arc::clone(&self.state.git_ops);
        let agent_ops = self.state.agent_registry.get(&running_agent);
        let task_id = task.id.clone();
        let task_title = task.title.clone();
        let running_agent_clone = running_agent.clone();

        let (tx, rx) = mpsc::channel();
        self.state.setup_rx = Some(rx);

        let auto_trust = self.state.config.auto_trust;
        std::thread::spawn(move || {
            let mut tmp_task = Task::new(&task_title, &running_agent_clone, &project_name);
            tmp_task.id = task_id.clone();
            tmp_task.plugin = plugin_name.clone();

            let result = setup_task_worktree(
                &mut tmp_task,
                &project_path,
                &tmux_project_name,
                &prompt,
                &base_branch,
                &worktree_dir,
                &branch_prefix,
                copy_files,
                init_script,
                &plugin,
                &running_agent_clone,
                &all_agents,
                tmux_ops.as_ref(),
                git_ops.as_ref(),
                agent_ops.as_ref(),
                &[],
                skip_init_scripts,
                skip_worktree,
                agent_hooks,
                skill_cmd_launch.as_deref(),
            );

            match result {
                Ok((target, launched_with_prompt)) => {
                    let _ = tx.send(SetupResult {
                        task_id: task_id.clone(),
                        session_name: tmp_task.session_name.unwrap_or_default(),
                        worktree_path: tmp_task.worktree_path.unwrap_or_default(),
                        branch_name: tmp_task.branch_name.unwrap_or_default(),
                        new_status: Some(TaskStatus::Running),
                        agent: running_agent_clone.clone(),
                        plugin: plugin_name,
                        error: None,
                    });

                    // Skip the whole send-after-ready dance when the agent was
                    // launched with the opening message already in argv.
                    if launched_with_prompt {
                        // nothing to send
                    } else if let Some(target) = wait_for_agent_ready(
                        &tmux_ops,
                        &target,
                        Some(&running_agent_clone),
                        auto_trust,
                    ) {
                        send_skill_and_prompt(
                            &tmux_ops,
                            &target,
                            &skill_cmd,
                            &prompt,
                            &prompt_trigger,
                            &task_content,
                            &running_agent_clone,
                            &auto_dismiss,
                            clear_context_on_advance,
                        );
                    }
                }
                Err(e) => {
                    let _ = tx.send(SetupResult {
                        task_id,
                        session_name: String::new(),
                        worktree_path: String::new(),
                        branch_name: String::new(),
                        new_status: None,
                        agent: running_agent_clone,
                        plugin: plugin_name,
                        error: Some(format!("Running setup failed: {}", e)),
                    });
                }
            }
        });

        Ok(())
    }

    /// Move task from Review back to Running (only allowed transition backwards)
    /// The tmux window should still be open from when it was in Running state
    fn move_review_to_running(&mut self, task_id: &str) -> Result<()> {
        if let (Some(db), Some(_project_path)) = (&self.state.db, &self.state.project_path) {
            if let Some(mut task) = db.get_task(task_id)? {
                if task.status != TaskStatus::Review {
                    return Ok(());
                }

                mark_reviewed_point(&task);

                // Switch agent if running phase uses a different agent than review
                let (running_agent, agent_switch) =
                    needs_agent_switch(&self.state.config, &task, "running");
                if agent_switch {
                    if let Some(session_name) = &task.session_name {
                        let session_clone = session_name.clone();
                        let hook_task_id = task.id.clone();
                        let tmux_ops = Arc::clone(&self.state.tmux_ops);
                        let agent_registry = Arc::clone(&self.state.agent_registry);
                        let running_agent_clone = running_agent.clone();
                        let current_agent_clone = task.agent.clone();
                        let wt_path = task.worktree_path.clone();
                        std::thread::spawn(move || {
                            let agent_ops = agent_registry.get(&running_agent_clone);
                            ensure_window_or_recover(
                                tmux_ops.as_ref(),
                                &session_clone,
                                agent_ops.as_ref(),
                                wt_path.as_deref(),
                                &hook_task_id,
                            );
                            let new_cmd = agent_ops.build_interactive_command("");
                            switch_agent_in_tmux(
                                tmux_ops.as_ref(),
                                &session_clone,
                                &current_agent_clone,
                                &new_cmd,
                            );
                        });
                    }
                }

                task.agent = running_agent;
                task.status = TaskStatus::Running;
                task.updated_at = chrono::Utc::now();
                db.update_task(&task)?;
                self.refresh_tasks()?;
            }
        }
        Ok(())
    }

    fn move_review_to_planning(&mut self, task_id: &str) -> Result<()> {
        if let (Some(db), Some(_project_path)) = (&self.state.db, &self.state.project_path) {
            if let Some(mut task) = db.get_task(task_id)? {
                if task.status != TaskStatus::Review {
                    return Ok(());
                }

                // Increment cycle counter for the next phase
                task.cycle += 1;

                // Switch agent if planning phase uses a different agent than review
                let (planning_agent, agent_switch) =
                    needs_agent_switch(&self.state.config, &task, "planning");
                let plugin = self.load_task_plugin(&task);

                // Resolve skill command and prompt for the new planning phase
                let task_content = task
                    .description
                    .as_deref()
                    .unwrap_or(&task.title)
                    .to_string();
                let skill_cmd = resolve_skill_command(
                    &plugin,
                    "planning",
                    &planning_agent,
                    &task_content,
                    task.cycle,
                    &task.id,
                    true,
                );
                // An agent switch launches a new process, so it can take the message
                // in argv — and that path keeps the task's own line structure.
                // Only the send-after-ready fallback needs the flattened form.
                let skill_cmd_launch = resolve_skill_command(
                    &plugin,
                    "planning",
                    &planning_agent,
                    &task_content,
                    task.cycle,
                    &task.id,
                    false,
                );
                let prompt =
                    resolve_prompt(&plugin, "planning", &task_content, &task.id, task.cycle);
                let prompt_trigger = resolve_prompt_trigger(&plugin, "planning");

                if let Some(session_name) = &task.session_name {
                    let session_clone = session_name.clone();
                    let hook_task_id = task.id.clone();
                    let tmux_ops = Arc::clone(&self.state.tmux_ops);
                    let agent_registry = Arc::clone(&self.state.agent_registry);
                    let planning_agent_clone = planning_agent.clone();
                    let current_agent_clone = task.agent.clone();
                    let task_content_clone = task_content.clone();
                    let skill_cmd_launch = skill_cmd_launch.clone();
                    let auto_dismiss = plugin
                        .as_ref()
                        .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
                    let wt_path = task.worktree_path.clone();
                    let auto_trust = self.state.config.auto_trust;
                    std::thread::spawn(move || {
                        let agent_ops = agent_registry.get(&planning_agent_clone);
                        // Recover window if it was lost
                        ensure_window_or_recover(
                            tmux_ops.as_ref(),
                            &session_clone,
                            agent_ops.as_ref(),
                            wt_path.as_deref(),
                            &hook_task_id,
                        );
                        // An agent switch starts a *new process*, so it takes the
                        // opening message in argv exactly like a first launch —
                        // same act, just into an existing window. A same-agent
                        // advance cannot: that process is already running.
                        let mut delivered_at_launch = false;
                        if agent_switch {
                            let launch_text =
                                compose_launch_text(skill_cmd_launch.as_deref(), &prompt);
                            delivered_at_launch = agent::spec::can_launch_with_prompt(
                                agent_ops.prompt_injection(),
                                &launch_text,
                            );
                            let new_cmd =
                                agent_ops.build_interactive_command(if delivered_at_launch {
                                    &launch_text
                                } else {
                                    ""
                                });
                            switch_agent_in_tmux(
                                tmux_ops.as_ref(),
                                &session_clone,
                                &current_agent_clone,
                                &new_cmd,
                            );
                            if !delivered_at_launch {
                                // The *new* agent is what has to become ready.
                                let _ = wait_for_agent_ready(
                                    &tmux_ops,
                                    &session_clone,
                                    Some(&planning_agent_clone),
                                    auto_trust,
                                );
                            }
                        }
                        if !delivered_at_launch {
                            send_skill_and_prompt(
                                &tmux_ops,
                                &session_clone,
                                &skill_cmd,
                                &prompt,
                                &prompt_trigger,
                                &task_content_clone,
                                &planning_agent_clone,
                                &auto_dismiss,
                                false,
                            );
                        }
                    });
                }

                task.agent = planning_agent;
                task.status = TaskStatus::Planning;
                task.updated_at = chrono::Utc::now();
                db.update_task(&task)?;
                self.refresh_tasks()?;
            }
        }
        Ok(())
    }

    fn move_running_to_planning(&mut self, task_id: &str) -> Result<()> {
        if let (Some(db), Some(_project_path)) = (&self.state.db, &self.state.project_path) {
            if let Some(mut task) = db.get_task(task_id)? {
                if task.status != TaskStatus::Running {
                    return Ok(());
                }

                // Switch agent if planning phase uses a different agent than running
                let (planning_agent, agent_switch) =
                    needs_agent_switch(&self.state.config, &task, "planning");
                if agent_switch {
                    if let Some(session_name) = &task.session_name {
                        let session_clone = session_name.clone();
                        let hook_task_id = task.id.clone();
                        let tmux_ops = Arc::clone(&self.state.tmux_ops);
                        let agent_registry = Arc::clone(&self.state.agent_registry);
                        let planning_agent_clone = planning_agent.clone();
                        let current_agent_clone = task.agent.clone();
                        let wt_path = task.worktree_path.clone();
                        std::thread::spawn(move || {
                            let agent_ops = agent_registry.get(&planning_agent_clone);
                            ensure_window_or_recover(
                                tmux_ops.as_ref(),
                                &session_clone,
                                agent_ops.as_ref(),
                                wt_path.as_deref(),
                                &hook_task_id,
                            );
                            let new_cmd = agent_ops.build_interactive_command("");
                            switch_agent_in_tmux(
                                tmux_ops.as_ref(),
                                &session_clone,
                                &current_agent_clone,
                                &new_cmd,
                            );
                        });
                    }
                }

                task.agent = planning_agent;
                task.status = TaskStatus::Planning;
                task.updated_at = chrono::Utc::now();
                db.update_task(&task)?;
                self.refresh_tasks()?;
            }
        }
        Ok(())
    }

    // === MCP Transition Request Processing ===

    /// Poll the transition_requests table for unprocessed requests and execute them.
    fn process_transition_requests(&mut self) -> Result<()> {
        let instance_id = self.state.instance_id.clone();

        // Recover anything a previous TUI claimed and never finished, before
        // reading the queue, so a reclaimed request is drained in this same
        // pass. Done here rather than only at startup: a TUI that dies mid-run
        // strands its queue, and the recovery should not wait for whenever
        // someone next launches agtx.
        if let Some(db) = self.state.db.as_ref() {
            match db.reclaim_stale_transition_requests(&instance_id, RECLAIM_CLAIMS_AFTER) {
                Ok(n) if n > 0 => {
                    tracing::info!(count = n, "Reclaimed transition requests from a dead instance")
                }
                Ok(_) => {}
                Err(e) => tracing::warn!(error = %e, "Failed to reclaim transition requests"),
            }
        }

        // `self.state.db` is re-borrowed per use site to avoid holding it across `&mut self`.
        let pending = match self.state.db.as_ref() {
            Some(db) => db.get_pending_transition_requests()?,
            None => return Ok(()),
        };
        if pending.is_empty() {
            return Ok(());
        }
        let instance_id = self.state.instance_id.clone();

        for req in pending {
            let claimed = self
                .state
                .db
                .as_ref()
                .map(|db| db.claim_transition_request(&req.id, &instance_id))
                .and_then(Result::ok)
                .unwrap_or(false);
            if !claimed {
                continue;
            }

            let result = self.execute_transition_request(&req);
            if let Some(db) = &self.state.db {
                let _ = match &result {
                    // A queued setup stays claimed and unprocessed; the drain
                    // marks it when the slot frees up and it actually starts.
                    Ok(TransitionOutcome::Queued) => Ok(()),
                    Ok(TransitionOutcome::Applied) => db.mark_transition_processed(&req.id, None),
                    Err(e) => db.mark_transition_processed(&req.id, Some(&e.to_string())),
                };
            }
            self.refresh_tasks()?;
        }

        // Periodically clean up old processed requests
        if let Some(db) = &self.state.db {
            let _ = db.cleanup_old_transition_requests();
        }

        Ok(())
    }

    fn execute_transition_request(
        &mut self,
        req: &TransitionRequest,
    ) -> Result<TransitionOutcome> {
        tracing::info!(
            task_id = %req.task_id,
            action = %req.action,
            "Processing transition request"
        );

        let Some(db) = &self.state.db else {
            anyhow::bail!("No project database");
        };
        let Some(project_path) = self.state.project_path.clone() else {
            anyhow::bail!("No project path");
        };

        let mut task = db
            .get_task(&req.task_id)?
            .ok_or_else(|| anyhow::anyhow!("Task not found: {}", req.task_id))?;

        // Recheck when the queue is drained: an agent may have written more
        // work since the phone rendered the card or submitted the request.
        //
        // **Every** action that can reach Done must be listed here, because
        // reaching Done deletes the worktree and `has_changes` reads
        // `git status --porcelain`, which counts *untracked* files. An agent
        // that wrote its work and never ran `git commit` has all of it here and
        // nowhere else, so a route to Done missing from this list merges an
        // empty branch and then deletes the work — a silent data-loss bug, not a
        // missing check. `move_forward` is listed so a stale request cannot be a
        // way around it.
        if task.status == TaskStatus::Review
            && matches!(
                req.action.as_str(),
                "move_to_done" | "move_to_done_and_merge" | "move_forward"
            )
            && task
                .worktree_path
                .as_ref()
                .is_some_and(|wt| self.state.git_ops.has_changes(Path::new(wt)))
        {
            anyhow::bail!("Uncommitted changes prevent moving this task to Done. Commit or resolve them first.");
        }

        // Block forward transitions when dependencies are not satisfied
        let is_forward = matches!(
            req.action.as_str(),
            "move_forward" | "move_to_planning" | "move_to_running" | "research"
        );
        if is_forward && task.status == TaskStatus::Backlog && !db.deps_satisfied(&task) {
            anyhow::bail!("Cannot advance task: dependencies not in Review/Done");
        }

        match req.action.as_str() {
            "research" => {
                if task.status != TaskStatus::Backlog {
                    anyhow::bail!(
                        "Task must be in Backlog to start research (current: {})",
                        task.status.as_str()
                    );
                }
                if task.session_name.is_some() {
                    anyhow::bail!(
                        "Task already has an active session (research may already be running)"
                    );
                }
                return self.queue_backlog_setup(req, SetupIntent::Research);
            }
            "move_forward" => {
                if task.status == TaskStatus::Backlog {
                    return self.queue_backlog_setup(req, SetupIntent::Planning);
                }
                self.execute_forward_transition(&mut task, &project_path)?;
            }
            "move_to_planning" => {
                if task.status != TaskStatus::Backlog {
                    anyhow::bail!(
                        "Task must be in Backlog to move to Planning (current: {})",
                        task.status.as_str()
                    );
                }
                return self.queue_backlog_setup(req, SetupIntent::Planning);
            }
            "move_to_running" => {
                if task.status != TaskStatus::Planning && task.status != TaskStatus::Backlog {
                    anyhow::bail!(
                        "Task must be in Backlog or Planning to move to Running (current: {})",
                        task.status.as_str()
                    );
                }
                if task.status == TaskStatus::Backlog {
                    return self.queue_backlog_setup(req, SetupIntent::Running);
                }
                self.execute_forward_transition(&mut task, &project_path)?;
            }
            "move_to_review" => {
                if task.status != TaskStatus::Running {
                    anyhow::bail!(
                        "Task must be in Running to move to Review (current: {})",
                        task.status.as_str()
                    );
                }
                self.mcp_transition_to_review(&mut task)?;
            }
            "move_to_done" => {
                if task.status != TaskStatus::Review {
                    anyhow::bail!(
                        "Task must be in Review to move to Done (current: {})",
                        task.status.as_str()
                    );
                }
                self.force_move_to_done(&task.id)?;
            }
            "move_to_done_and_merge" => {
                if task.status != TaskStatus::Review {
                    // Names the action asked for, and — for the state this
                    // actually gets asked from — what to do about it. A resume
                    // puts a task back in Running, and trying to merge straight
                    // afterwards is the common way a caller lands here.
                    let fix = if task.status == TaskStatus::Running {
                        " Move it forward to Review first."
                    } else {
                        ""
                    };
                    anyhow::bail!(
                        "Task must be in Review to merge and move to Done (current: {}).{}",
                        task.status.as_str(),
                        fix
                    );
                }
                self.merge_then_done(&task, &project_path)?;
            }
            "resume" => {
                if task.status != TaskStatus::Review {
                    anyhow::bail!(
                        "Task must be in Review to resume (current: {})",
                        task.status.as_str()
                    );
                }
                self.move_review_to_running(&req.task_id)?;
            }
            "escalate_to_user" => {
                if !matches!(task.status, TaskStatus::Planning | TaskStatus::Running) {
                    anyhow::bail!(
                        "escalate_to_user is only valid for Planning or Running tasks (current: {})",
                        task.status.as_str()
                    );
                }
                task.escalation_note = req
                    .reason
                    .clone()
                    .or_else(|| Some("Needs attention".to_string()));
                task.updated_at = chrono::Utc::now();
                if let Some(db) = &self.state.db {
                    db.update_task(&task)?;
                }
                self.refresh_tasks()?;
            }
            other => {
                anyhow::bail!("Unknown action: {}", other);
            }
        }

        Ok(TransitionOutcome::Applied)
    }

    /// Execute a forward transition (next column), mirroring move_task_right logic.
    fn execute_forward_transition(&mut self, task: &mut Task, project_path: &Path) -> Result<()> {
        let next_status = match task.status {
            TaskStatus::Backlog => TaskStatus::Planning,
            TaskStatus::Planning => TaskStatus::Running,
            TaskStatus::Running => TaskStatus::Review,
            TaskStatus::Review => TaskStatus::Done,
            TaskStatus::Done => anyhow::bail!("Task is already Done"),
        };

        // Skip the phase-incomplete confirmation for MCP requests
        let handled = match (task.status, next_status) {
            (TaskStatus::Backlog, TaskStatus::Planning) => {
                self.transition_to_planning(task, project_path)?
            }
            (TaskStatus::Planning, TaskStatus::Running) => self.transition_to_running(task)?,
            (TaskStatus::Running, TaskStatus::Review) => {
                self.mcp_transition_to_review(task)?;
                return Ok(());
            }
            (TaskStatus::Review, TaskStatus::Done) => {
                self.force_move_to_done(&task.id)?;
                return Ok(());
            }
            _ => false,
        };

        if !handled {
            task.status = next_status;
            task.updated_at = chrono::Utc::now();
            if let Some(db) = &self.state.db {
                db.update_task(task)?;
            }
        }

        Ok(())
    }

    /// Merge a Review task's branch into its base, then move it to Done.
    ///
    /// The two halves are one action because doing them separately loses the
    /// only chance to keep the worktree: Done removes it, and a conflict is
    /// resolved by the task's own agent, in that worktree, against the branch it
    /// has been working on. So a conflict leaves the task exactly where it was —
    /// in Review, with its session alive — and hands the work to the agent that
    /// is already there.
    ///
    /// Merging is synchronous, unlike the cleanup that follows it. Done is
    /// reversible in the sense that matters (the branch survives); a merge
    /// commit in the user's checkout is not, so its outcome has to be known
    /// before the task's status is changed to match.
    fn merge_then_done(&mut self, task: &Task, project_path: &Path) -> Result<()> {
        let Some(branch) = task.branch_name.clone() else {
            anyhow::bail!("Task has no branch to merge");
        };
        let base = match task.base_branch.as_deref() {
            Some(b) if !b.trim().is_empty() => b.trim().to_string(),
            _ => crate::git::detect_main_branch(project_path)?,
        };

        let message = format!("Merge task '{}' ({})", task.title, branch);
        match crate::git::merge_task_branch(project_path, &base, &branch, &message)? {
            crate::git::MergeOutcome::Merged => {
                tracing::info!(task_id = %task.id, %branch, %base, "Merged task branch");
                self.force_move_to_done(&task.id)
            }
            crate::git::MergeOutcome::NothingToMerge => {
                anyhow::bail!(
                    "Branch '{branch}' has no commits — nothing to merge into '{base}', \
                     and the task stays in Review. If the agent wrote files, they are \
                     uncommitted in the worktree and would be destroyed by Done: tell it \
                     to commit, then retry."
                );
            }
            crate::git::MergeOutcome::Conflicts(files) => {
                self.send_to_conflict_resolution(task, &base, &files)?;
                let shown: Vec<&str> = files.iter().take(5).map(String::as_str).collect();
                let more = files.len().saturating_sub(shown.len());
                anyhow::bail!(
                    "Branch '{}' conflicts with '{}' in {} file(s): {}{}. \
                     Task stays in Review; its agent was asked to resolve them. \
                     Retry once it reports done.",
                    branch,
                    base,
                    files.len(),
                    shown.join(", "),
                    if more > 0 {
                        format!(" (+{more} more)")
                    } else {
                        String::new()
                    }
                );
            }
            crate::git::MergeOutcome::Refused(why) => {
                anyhow::bail!(
                    "Cannot merge '{branch}' into '{base}': {why}. \
                     Nothing was changed."
                );
            }
        }
    }

    /// Hand a conflicting Review task to its own agent, and mark the card.
    ///
    /// The escalation note is set whether or not the agent could be reached: a
    /// conflict the caller cannot resolve is exactly what the user needs to see
    /// on the board, and a task whose session has already exited is the case
    /// where that matters most.
    fn send_to_conflict_resolution(
        &mut self,
        task: &Task,
        base: &str,
        files: &[String],
    ) -> Result<()> {
        if let Some(db) = &self.state.db {
            if let Some(mut t) = db.get_task(&task.id)? {
                t.escalation_note = Some(format!(
                    "Merge conflicts with {base} in {} file(s)",
                    files.len()
                ));
                t.updated_at = chrono::Utc::now();
                db.update_task(&t)?;
            }
        }

        if let Some(session) = task.session_name.clone() {
            if self.state.tmux_ops.window_exists(&session).unwrap_or(false) {
                let skill_cmd =
                    skills::transform_plugin_command("/agtx:merge-conflicts", &task.agent);
                let prompt = format!(
                    "The feature branch has merge conflicts with {base} in: {}. \
                     Please resolve them now.",
                    files.join(", ")
                );
                let tmux_ops = Arc::clone(&self.state.tmux_ops);
                let agent_name = task.agent.clone();
                std::thread::spawn(move || {
                    send_skill_and_prompt(
                        &tmux_ops,
                        &session,
                        &skill_cmd,
                        &prompt,
                        &None,
                        "",
                        &agent_name,
                        &[],
                        false,
                    );
                });
            }
        }
        self.refresh_tasks()
    }

    /// MCP version of transition_to_review: sends review prompt but skips PR popup.
    fn mcp_transition_to_review(&mut self, task: &mut Task) -> Result<()> {
        let (review_agent, agent_switch) = needs_agent_switch(&self.state.config, task, "review");
        if let Some(session_name) = &task.session_name {
            let plugin = self.load_task_plugin(task);
            let task_content = task.content_text();
            let skill_cmd = resolve_skill_command(
                &plugin,
                "review",
                &review_agent,
                &task_content,
                task.cycle,
                &task.id,
                true,
            );
            // Non-collapsed twin for the argv path (see `spawn_send_to_agent`).
            let skill_cmd_launch = resolve_skill_command(
                &plugin,
                "review",
                &review_agent,
                &task_content,
                task.cycle,
                &task.id,
                false,
            );
            let prompt = resolve_prompt(&plugin, "review", &task_content, &task.id, task.cycle);
            let prompt_trigger = resolve_prompt_trigger(&plugin, "review");
            let auto_dismiss = plugin
                .as_ref()
                .map_or_else(Vec::new, |p| p.auto_dismiss.clone());
            spawn_send_to_agent(
                Arc::clone(&self.state.tmux_ops),
                Arc::clone(&self.state.agent_registry),
                task.id.clone(),
                self.state.config.agent_hooks,
                self.state.config.auto_trust,
                session_name.clone(),
                task.agent.clone(),
                review_agent.clone(),
                agent_switch,
                skill_cmd,
                skill_cmd_launch,
                prompt,
                prompt_trigger,
                task_content,
                auto_dismiss,
                task.worktree_path.clone(),
                self.state.project_path.clone().unwrap_or_default(),
                plugin,
            );
        }
        task.agent = review_agent;
        task.status = TaskStatus::Review;
        task.updated_at = chrono::Utc::now();
        if let Some(db) = &self.state.db {
            db.update_task(task)?;
        }
        Ok(())
    }

    /// Toggle orchestrator agent: spawn if not running, view if running.
    fn toggle_orchestrator(&mut self) -> Result<()> {
        let project_path = match &self.state.project_path {
            Some(p) => p.clone(),
            None => {
                self.state.warning_message = Some((
                    "Orchestrator requires a project (not dashboard mode)".to_string(),
                    Instant::now(),
                ));
                return Ok(());
            }
        };

        let tmux_project_name = self.state.tmux_project_name.clone();
        let window_name = "orchestrator";
        let orch_target = format!("{}:{}", tmux_project_name, window_name);

        // If orchestrator is running, open the popup to view it
        if is_orchestrator_live(self.state.tmux_ops.as_ref(), &orch_target) {
            let first_time = self.state.orchestrator_session.as_deref() != Some(&orch_target);
            self.state.orchestrator_session = Some(orch_target.clone());

            if first_time {
                // Cross-instance reattach: verify ready, replay phase events (deduped).
                self.state
                    .orchestrator_ready
                    .store(false, Ordering::Release);
                if let Some(ref db) = self.state.db {
                    run_orchestrator_catchup(
                        db,
                        &self.state.board.tasks,
                        self.state.project_path.as_deref(),
                    );
                }
                let tmux_ops = Arc::clone(&self.state.tmux_ops);
                let ready_flag = Arc::clone(&self.state.orchestrator_ready);
                let target = orch_target.clone();
                let auto_trust = self.state.config.auto_trust;
                std::thread::spawn(move || {
                    if wait_for_agent_ready(&tmux_ops, &target, Some("claude"), auto_trust)
                        .is_some()
                    {
                        ready_flag.store(true, Ordering::Release);
                    }
                });
            }

            let mut popup = ShellPopup::new("Orchestrator".to_string(), orch_target.clone());
            if let Ok((_term_width, term_height)) = crossterm::terminal::size() {
                let pane_width = SHELL_POPUP_CONTENT_WIDTH;
                let popup_height =
                    (term_height as u32 * SHELL_POPUP_HEIGHT_PERCENT as u32 / 100) as u16;
                let pane_height = popup_height.saturating_sub(4);
                let _ = self
                    .state
                    .tmux_ops
                    .resize_window(&orch_target, pane_width, pane_height);
                popup.last_pane_size = Some((pane_width, pane_height));
                std::thread::sleep(std::time::Duration::from_millis(200));
            }
            let (content, metrics, cursor_line) =
                capture_tmux_pane_snapshot(&orch_target, 500, self.state.tmux_ops.as_ref());
            let lines = parse_ansi_to_lines(&content);
            popup.set_content(content, lines, cursor_line);
            popup.metrics = metrics;
            let _ = self.state.input_sink.flush();
            self.state.shell_popup = Some(popup);
            return Ok(());
        }

        if !kill_windows_by_name(self.state.tmux_ops.as_ref(), &orch_target) {
            self.state.warning_message = Some((
                format!(
                    "Could not clear lingering `{}` window; try `tmux -L agtx kill-window -t {}`",
                    orch_target, orch_target,
                ),
                Instant::now(),
            ));
            return Ok(());
        }
        self.state.orchestrator_session = None;
        self.state
            .orchestrator_ready
            .store(false, Ordering::Release);

        // Spawn new orchestrator
        let default_agent = self.state.config.default_agent.clone();
        let agent = self.state.agent_registry.get(&default_agent);
        let project_path_str = project_path.to_string_lossy().to_string();

        // Build MCP registration JSON for the agtx server
        let agtx_bin = std::env::current_exe()
            .unwrap_or_else(|_| PathBuf::from("agtx"))
            .to_string_lossy()
            .to_string();
        let mcp_json = serde_json::json!({
            "type": "stdio",
            "command": agtx_bin,
            "args": ["mcp-serve", &project_path_str]
        });
        // Escaped for the single-quoted word it becomes inside the orchestrator
        // command (`add-json … '<json>'`). Only reachable when the project path
        // contains an apostrophe. The *outer* `sh -c` layer is handled by
        // `single_quote` in create_window — pre-escaping for it here would
        // double-escape and break the command.
        let mcp_json_str = mcp_json.to_string().replace('\'', "'\"'\"'");

        let agent_cmd = agent.build_orchestrator_command(&mcp_json_str, &agtx_bin);

        // Ensure project tmux session exists
        ensure_project_tmux_session(
            &tmux_project_name,
            &project_path,
            self.state.tmux_ops.as_ref(),
        );

        // Create orchestrator tmux window in the project root (no worktree)
        self.state.tmux_ops.create_window(
            &tmux_project_name,
            window_name,
            &project_path_str,
            Some(agent_cmd),
            false,
            // The orchestrator is not a task, so it reports no hook status.
            &[],
        )?;

        self.state.orchestrator_session = Some(orch_target.clone());
        self.state
            .orchestrator_ready
            .store(false, Ordering::Release);

        // Open the popup immediately so the user can see the orchestrator starting
        let mut popup = ShellPopup::new("Orchestrator".to_string(), orch_target.clone());
        if let Ok((_term_width, term_height)) = crossterm::terminal::size() {
            let pane_width = SHELL_POPUP_CONTENT_WIDTH;
            let popup_height =
                (term_height as u32 * SHELL_POPUP_HEIGHT_PERCENT as u32 / 100) as u16;
            let pane_height = popup_height.saturating_sub(4);
            let _ = self
                .state
                .tmux_ops
                .resize_window(&orch_target, pane_width, pane_height);
            popup.last_pane_size = Some((pane_width, pane_height));
        }
        let (content, metrics, cursor_line) =
            capture_tmux_pane_snapshot(&orch_target, 500, self.state.tmux_ops.as_ref());
        let lines = parse_ansi_to_lines(&content);
        popup.set_content(content, lines, cursor_line);
        popup.metrics = metrics;
        let _ = self.state.input_sink.flush();
        self.state.shell_popup = Some(popup);

        // Deploy orchestrate skill to project root so the agent can discover it
        deploy_skill(
            &project_path,
            "agtx-orchestrate",
            skills::ORCHESTRATE_SKILL,
            &default_agent,
        );

        if let Some(ref db) = self.state.db {
            run_orchestrator_catchup(
                db,
                &self.state.board.tasks,
                self.state.project_path.as_deref(),
            );
        }

        // Send the /agtx:orchestrate command once the agent is ready
        let skill_cmd = skills::transform_plugin_command("/agtx:orchestrate", &default_agent)
            .unwrap_or_else(|| "/agtx:orchestrate".to_string());
        let tmux_ops = Arc::clone(&self.state.tmux_ops);
        let ready_flag = Arc::clone(&self.state.orchestrator_ready);
        let target = orch_target;
        let auto_trust = self.state.config.auto_trust;
        std::thread::spawn(move || {
            if let Some(ready_target) =
                wait_for_agent_ready(&tmux_ops, &target, Some(&default_agent), auto_trust)
            {
                let _ = tmux_ops.send_keys(&ready_target, &skill_cmd);
                ready_flag.store(true, Ordering::Release);
            }
        });

        Ok(())
    }

    fn open_selected_task(&mut self) -> Result<()> {
        if let Some(task) = self.state.board.selected_task() {
            if let Some(window_name) = &task.session_name.clone() {
                // If the tmux window is gone, try to recover it before opening
                if !self
                    .state
                    .tmux_ops
                    .window_exists(window_name)
                    .unwrap_or(true)
                {
                    let agent_ops = self.state.agent_registry.get(&task.agent);
                    let project_path = self.state.project_path.as_deref().unwrap_or(Path::new("."));
                    let _ = recover_task_session(
                        task,
                        &self.state.tmux_project_name,
                        project_path,
                        self.state.tmux_ops.as_ref(),
                        agent_ops.as_ref(),
                    );
                    // Clear stale phase status so it gets re-evaluated
                    self.state.phase_status_cache.remove(&task.id);
                    self.state.pane_content_hashes.remove(&task.id);
                }

                let task_id = task.id.clone();
                let escalation_note = task.escalation_note.clone();
                // Qualified, like the orchestrator popup's target: a bare window
                // name resolves inside whichever session the caller is bound to,
                // which is not necessarily this project's. See `pane_target`.
                let target = pane_target(&self.state.tmux_project_name, window_name);
                let mut popup = ShellPopup::new(task.title.clone(), target.clone());
                popup.task_id = Some(task_id);
                popup.escalation_note = escalation_note;

                // Resize tmux window to match popup dimensions (uses same constants as draw_shell_popup)
                if let Ok((_term_width, term_height)) = crossterm::terminal::size() {
                    let pane_width = SHELL_POPUP_CONTENT_WIDTH;
                    let popup_height =
                        (term_height as u32 * SHELL_POPUP_HEIGHT_PERCENT as u32 / 100) as u16;
                    let pane_height = popup_height.saturating_sub(4); // -4 for borders + header/footer

                    let _ = self
                        .state
                        .tmux_ops
                        .resize_window(&target, pane_width, pane_height);
                    popup.last_pane_size = Some((pane_width, pane_height));
                    // Give TUI apps (OpenCode, Gemini Ink) time to re-render after resize
                    std::thread::sleep(std::time::Duration::from_millis(200));
                }

                // Capture initial content *and* the pane metrics, so the first
                // keypress already knows whether this pane has tmux scrollback.
                // Leaving them to the first refresh left a window in which
                // `has_scrollback()` fell back to its `true` default and the
                // scroll keys moved a buffer that could not move.
                let (content, metrics, cursor_line) =
                    capture_tmux_pane_snapshot(&target, 500, self.state.tmux_ops.as_ref());
                let lines = parse_ansi_to_lines(&content);
                popup.set_content(content, lines, cursor_line);
                popup.metrics = metrics;

                // A popup opening changes the target; nothing queued for the
                // previous one may follow it here.
                let _ = self.state.input_sink.flush();
                self.state.shell_popup = Some(popup);
            }
        }
        Ok(())
    }

    fn open_selected_task_fullscreen(&mut self) -> Result<()> {
        self.open_selected_task()?;
        if let Some(popup) = self.state.shell_popup.as_mut() {
            popup.fullscreen = true;
            if let Ok((width, height)) = crossterm::terminal::size() {
                let pane_size = (width.saturating_sub(2), height.saturating_sub(4));
                let _ =
                    self.state
                        .tmux_ops
                        .resize_window(&popup.window_name, pane_size.0, pane_size.1);
                popup.last_pane_size = Some(pane_size);
            }
        }
        Ok(())
    }

    /// Load the plugin that a specific task was created with.
    /// Falls back to bundled agtx plugin for tasks with no explicit plugin.
    fn load_task_plugin(&self, task: &Task) -> Option<WorkflowPlugin> {
        load_task_plugin(
            task,
            self.state.project_path.as_deref(),
            &self.state.config.default_agent,
        )
    }

    pub fn refresh_tasks(&mut self) -> Result<()> {
        if let Some(db) = &self.state.db {
            self.state.board.tasks = db.get_all_tasks()?;
            // Refresh dependency satisfaction cache for backlog tasks with references
            self.state.deps_satisfied_cache.clear();
            for task in &self.state.board.tasks {
                if task.referenced_tasks.is_some() {
                    self.state
                        .deps_satisfied_cache
                        .insert(task.id.clone(), db.deps_satisfied(task));
                }
            }
        }
        Ok(())
    }

    fn refresh_projects(&mut self) -> Result<()> {
        // Load projects from global database
        let db_projects = self.state.global_db.get_all_projects()?;

        self.state.projects = db_projects
            .into_iter()
            .map(|p| ProjectInfo {
                name: p.name,
                path: p.path,
            })
            .collect();

        // Sort alphabetically by name (case-insensitive)
        self.state
            .projects
            .sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase()));

        // Find current project in list and select it
        if let Some(project_path) = &self.state.project_path {
            let current_path = project_path.to_string_lossy();
            if let Some(pos) = self
                .state
                .projects
                .iter()
                .position(|p| p.path == current_path)
            {
                self.state.selected_project = pos;
            }
        }

        Ok(())
    }

    /// Push queued notifications to the orchestrator's tmux pane, but only when idle.
    /// Runs every 2s. Idle = pane content unchanged for ≥3s.
    fn deliver_orchestrator_notifications(&mut self) {
        // Only check every 2 seconds
        if self.state.orchestrator_last_check.elapsed() < std::time::Duration::from_secs(2) {
            return;
        }
        self.state.orchestrator_last_check = Instant::now();

        let orch_target = match &self.state.orchestrator_session {
            Some(t) => t.clone(),
            None => return,
        };

        // Don't deliver until the agent is ready and has received the skill command
        if !self.state.orchestrator_ready.load(Ordering::Acquire) {
            return;
        }

        // Check window still exists
        if !is_orchestrator_live(self.state.tmux_ops.as_ref(), &orch_target) {
            self.state.orchestrator_session = None;
            self.state
                .orchestrator_ready
                .store(false, Ordering::Release);
            return;
        }

        // Capture current pane content (bottom portion for comparison)
        let current_content = self
            .state
            .tmux_ops
            .capture_pane(&orch_target)
            .unwrap_or_default();

        let result = check_orchestrator_idle(
            &current_content,
            &self.state.orchestrator_last_content,
            self.state.orchestrator_stable_since,
        );

        match result {
            OrchestratorIdleResult::Idle => {
                // Fall through to deliver notifications
            }
            OrchestratorIdleResult::Busy => {
                self.state.orchestrator_last_content = current_content;
                self.state.orchestrator_stable_since = Some(Instant::now());
                return;
            }
            OrchestratorIdleResult::Waiting => {
                if self.state.orchestrator_stable_since.is_none() {
                    self.state.orchestrator_stable_since = Some(Instant::now());
                }
                return;
            }
        }

        // Orchestrator is idle — deliver pending notifications
        let db = match &self.state.db {
            Some(db) => db,
            None => return,
        };

        let notifications = match db.consume_notifications() {
            Ok(n) if !n.is_empty() => n,
            _ => return,
        };

        let messages: Vec<String> = notifications.iter().map(|n| n.message.clone()).collect();
        let combined = format!("[agtx] {}", messages.join(" | "));
        let _ = self.state.tmux_ops.send_keys(&orch_target, &combined);

        // Reset idle tracking since we just sent input
        self.state.orchestrator_last_content.clear();
        self.state.orchestrator_stable_since = None;
    }

    /// Spawn a background thread to check phase statuses if no refresh is already running
    /// and the cache has expired for at least one task.
    fn maybe_spawn_session_refresh(&mut self) {
        // Don't spawn if a refresh is already in flight
        if self.state.session_refresh_rx.is_some() {
            return;
        }

        let now = Instant::now();
        const CACHE_TTL: std::time::Duration = PHASE_STATUS_CACHE_TTL;

        // Collect tasks that need checking (cache expired or never checked)
        let tasks_to_check: Vec<_> = self
            .state
            .board
            .tasks
            .iter()
            .filter(|t| has_live_phase_status(t))
            .filter(|t| {
                self.state
                    .phase_status_cache
                    .get(&t.id)
                    .map_or(true, |(_, ts)| now.duration_since(*ts) >= CACHE_TTL)
            })
            .map(|t| {
                // was_ready: true if previously Ready OR not in cache yet (first poll after startup).
                // This avoids false "newly ready" notifications for tasks that were already done before restart.
                let was_ready = self
                    .state
                    .phase_status_cache
                    .get(&t.id)
                    .map_or(true, |(prev, _)| *prev == PhaseStatus::Ready);
                (
                    t.id.clone(),
                    t.status,
                    t.worktree_path.clone(),
                    t.plugin.clone(),
                    t.session_name.clone(),
                    t.cycle,
                    was_ready,
                    t.agent.clone(),
                    t.phase_entered_at,
                )
            })
            .collect();

        if tasks_to_check.is_empty() {
            return;
        }

        let project_path = self.state.project_path.clone();
        let tmux_ops = Arc::clone(&self.state.tmux_ops);
        let input_sink = Arc::clone(&self.state.input_sink);
        let auto_trust = self.state.config.auto_trust;

        let (tx, rx) = mpsc::channel();
        self.state.session_refresh_rx = Some(rx);

        std::thread::spawn(move || {
            // Every window on the server, once, rather than a `list-windows`
            // process per task. `window_exists` is a membership test, and asking
            // tmux N times for the same answer was the largest remaining
            // per-task subprocess cost on the board.
            let live_windows = live_window_targets(tmux_ops.as_ref());

            let mut plugin_cache: HashMap<Option<String>, Option<WorkflowPlugin>> = HashMap::new();
            let mut statuses = Vec::new();
            let now_secs = chrono::Utc::now().timestamp();

            for (
                task_id,
                status,
                worktree_path,
                task_plugin,
                session_name,
                cycle,
                was_ready,
                agent,
                phase_entered_at,
            ) in tasks_to_check
            {
                let plugin =
                    plugin_cache
                        .entry(task_plugin.clone())
                        .or_insert_with(|| match &task_plugin {
                            Some(name) => WorkflowPlugin::load(name, project_path.as_deref())
                                .ok()
                                .or_else(|| skills::load_bundled_plugin(name)),
                            None => skills::load_bundled_plugin("agtx"),
                        });

                let phase_status = if status == TaskStatus::Backlog {
                    // Preresearch copy-back
                    if let (Some(ref wt), Some(ref pp)) = (&worktree_path, &project_path) {
                        if let Some(ref p) = plugin {
                            if let Some(entries) = p.copy_back.get("preresearch") {
                                let all_at_root = !entries.is_empty()
                                    && entries.iter().all(|e| pp.join(e).exists());
                                if !all_at_root && !p.artifacts.preresearch.is_empty() {
                                    let any_artifact = p.artifacts.preresearch.iter().all(|a| {
                                        let path = Path::new(wt).join(a);
                                        if a.contains('*') {
                                            glob_path_exists(&path.to_string_lossy())
                                        } else {
                                            path.exists()
                                        }
                                    });
                                    if any_artifact {
                                        copy_back_to_project(Path::new(wt), pp, entries);
                                    }
                                }
                            }
                        }
                    }

                    let found = worktree_path
                        .as_ref()
                        .map_or(false, |wt| research_artifact_exists(wt, &task_id, plugin));
                    if found {
                        PhaseStatus::Ready
                    } else {
                        PhaseStatus::Working
                    }
                } else if let Some(ref wt) = worktree_path {
                    if phase_artifact_fresh(wt, status, plugin, cycle, phase_entered_at) {
                        PhaseStatus::Ready
                    } else {
                        PhaseStatus::Working
                    }
                } else {
                    PhaseStatus::Working
                };

                // An artifact is written mid-turn; `Ready` waits for the turn to end
                // (`gate_ready_on_turn`). Decided here, before the copy-back below
                // acts on `Ready`, and the record is read once and reused for the
                // `Working` path further down.
                let window_alive = !window_is_gone(session_name.as_deref(), live_windows.as_ref());
                let hook_record = if window_alive
                    && matches!(phase_status, PhaseStatus::Working | PhaseStatus::Ready)
                {
                    worktree_path
                        .as_ref()
                        .and_then(|wt| hook_status::read_status(Path::new(wt), &task_id, now_secs))
                } else {
                    None
                };
                let phase_status =
                    gate_ready_on_turn(phase_status, hook_record.as_ref().map(|h| h.state));

                // Copy-back on Working → Ready transition
                if phase_status == PhaseStatus::Ready && !was_ready {
                    if let (Some(ref wt), Some(ref pp)) = (&worktree_path, &project_path) {
                        let phase_name = if status == TaskStatus::Backlog {
                            "research"
                        } else {
                            status.as_str()
                        };
                        if let Some(ref p) = plugin {
                            if let Some(entries) = p.copy_back.get(phase_name) {
                                copy_back_to_project(Path::new(wt), pp, entries);
                            }
                        }
                    }
                }

                // Check if tmux window still exists — if not, mark as Exited
                // (unless phase artifact was found, in which case it completed before the crash)
                //
                // Answered from one listing taken for the whole pass, rather
                // than a `list-windows` process per task on a 2-second timer.
                let window_gone = window_is_gone(session_name.as_deref(), live_windows.as_ref());
                let phase_status = if window_gone && phase_status == PhaseStatus::Working {
                    PhaseStatus::Exited
                } else {
                    phase_status
                };

                // The agent's own report of what it is doing, when it writes one.
                // Authoritative over the pane heuristic below.
                let hook_status = if phase_status == PhaseStatus::Working && !window_gone {
                    hook_record
                } else {
                    None
                };

                // Interactive prompts that block an agent are answered here as well
                // as during startup, because `wait_for_agent_ready` gives up after
                // ~60s and a slow agent can render its first-launch dialog later
                // than that — observed in an emulated swebench container, where
                // Claude showed the bypass warning well after the readiness window
                // had closed and nothing was left watching for it.
                // Only a *fresh `Working`* report proves the pane is dialog-free: the
                // agent is mid-turn, so it is past whatever gated its startup.
                // Only a *fresh* `Working` skips it. `read_status` ages out a
                // stale `Working`, but a `waiting`/`ended` record never expires
                // (`hook_status.rs:102`), so letting one suppress the capture
                // would hide a dialog rendered after a relaunch — which is
                // exactly the resume path.
                let hook_says_working = matches!(
                    hook_status.as_ref().map(|h| h.state),
                    Some(hook_status::HookState::Working)
                );
                let mut awaiting_trust: Option<String> = None;
                // One capture for this pass, shared by the dialog scan below and
                // the content hash further down. They ask different questions of
                // the same bytes, and reading the pane twice was a second `tmux`
                // process per task for every agent that reports no hook status —
                // which is the case the hash exists for in the first place.
                // `hook_says_working` implies a hook status exists, so this one
                // condition is exactly the union of the two below.
                let pane_text: Option<String> =
                    if phase_status == PhaseStatus::Working && !window_gone && !hook_says_working {
                        session_name.as_ref().and_then(|sn| {
                            capture_pane_text(sn, input_sink.as_ref(), tmux_ops.as_ref())
                        })
                    } else {
                        None
                    };
                if phase_status == PhaseStatus::Working && !window_gone && !hook_says_working {
                    if let Some(sn) = session_name.as_ref() {
                        if let Some(content) = pane_text.as_deref() {
                            // Detected whether or not it is answered: with
                            // `auto_trust` off this is what turns the card
                            // `Blocked`, so the user knows a decision is theirs to
                            // make rather than watching a task sit at "working".
                            if !auto_trust {
                                awaiting_trust = visible_security_dialog(Some(&agent), content)
                                    .map(str::to_string);
                            }
                            // A fresh state each poll: the attempt cap guards a
                            // single startup burst, whereas here the 2s cadence
                            // between polls is itself the pacing.
                            let mut st = LaunchDialogState::default();
                            dismiss_launch_dialog(
                                &tmux_ops,
                                sn,
                                Some(&agent),
                                content,
                                &mut st,
                                auto_trust,
                            );

                            // Mid-session approval prompts (Codex's "allow this
                            // MCP server to run tool") — a workaround for an
                            // interactive prompt, not part of status detection.
                            // Matched against this agent's own dialogs only: the
                            // refresh loop knows what runs in the pane, unlike
                            // `wait_for_agent_ready`.
                            answer_session_dialogs(&tmux_ops, sn, &agent, content);
                        }
                    }
                }

                // Pane hash is the fallback for agents that report nothing.
                // Skipping it when a hook status exists also drops one
                // `capture-pane` subprocess per task per refresh.
                let content_hash = if phase_status == PhaseStatus::Working
                    && !window_gone
                    && hook_status.is_none()
                {
                    pane_text.as_ref().map(|content| {
                        use std::hash::{Hash, Hasher};
                        let mut hasher = std::collections::hash_map::DefaultHasher::new();
                        content.hash(&mut hasher);
                        hasher.finish()
                    })
                } else {
                    None
                };

                statuses.push(SessionTaskStatus {
                    task_id,
                    phase_status,
                    content_hash,
                    hook_status,
                    awaiting_trust,
                    status,
                    worktree_path,
                    session_name,
                    agent,
                    was_ready,
                });
            }

            let _ = tx.send(SessionRefreshResult { statuses });
        });
    }

    /// Whether `task_runtime` is worth writing right now.
    ///
    /// The table exists so a *reader outside this process* can see phase status
    /// it cannot recompute. With no such reader the write is pure cost — and it
    /// is not a small one in aggregate: a transaction every couple of seconds,
    /// for the life of every agtx session, forever, on the chance a phone might
    /// one day connect.
    ///
    /// So publishing starts when someone actually asks for a board and stops
    /// when they stop. Two kinds of reader mark `board_watch`: the web server,
    /// on a board request — the `W` overlay's own child counts too, since
    /// starting it is an explicit request for mobile — and the MCP server, on
    /// `list_tasks` / `get_task`.
    ///
    /// The MCP reader is why this is not gated on the `serve` feature. A
    /// default build has no web server, but it always has `agtx mcp-serve`, and
    /// an orchestrator or oneshot session polling phase status is exactly the
    /// out-of-process reader this table is for. Compiling the call out would
    /// leave every such client reading a table nothing ever writes.
    ///
    /// The window is generous because the board no longer polls: someone can
    /// read it for minutes without issuing a request, and going quiet mid-read
    /// would freeze their phase icons rather than save anything worth having.
    fn should_publish_runtime(&self) -> bool {
        const WATCH_WINDOW: i64 = 10 * 60;

        #[cfg(feature = "serve")]
        if self.state.serve_session.is_some() {
            return true;
        }
        let Some(path) = &self.state.project_path else {
            return false;
        };
        self.state
            .global_db
            .board_watched_recently(
                &path.to_string_lossy(),
                chrono::Duration::seconds(WATCH_WINDOW),
            )
            .unwrap_or(false)
    }

    /// Apply results from the background session refresh thread.
    fn apply_session_refresh(&mut self, result: SessionRefreshResult) {
        let now = Instant::now();
        let mut runtime_rows: Vec<crate::db::TaskRuntime> = Vec::new();

        for task_status in result.statuses {
            // The refresh ran on a thread, so the task may have moved on since
            // it was selected. A Done task has no window, no worktree and no
            // agent, so every PhaseStatus is meaningless for it — and nothing
            // refreshes Done, so a value written here would sit on the card
            // forever. That is how a task moved to Done kept reading "Working".
            //
            // Only a task that is *on the board and no longer live* is dropped.
            // Absent means deleted or not yet reloaded, which are not the same
            // thing, and treating them as stale would discard good results
            // whenever this lands between a DB write and `refresh_tasks`.
            if self
                .state
                .board
                .tasks
                .iter()
                .any(|t| t.id == task_status.task_id && !has_live_phase_status(t))
            {
                self.state.phase_status_cache.remove(&task_status.task_id);
                continue;
            }

            // The pass snapshotted tasks before it ran, so a transition that
            // landed meanwhile leaves this verdict describing the *previous*
            // phase — Running's `execute.md` would read as `review:ready`.
            // Dropped rather than applied; the next pass, two seconds on,
            // computes it against the right phase.
            if self
                .state
                .board
                .tasks
                .iter()
                .any(|t| t.id == task_status.task_id && t.status != task_status.status)
            {
                continue;
            }

            let mut phase = task_status.phase_status;

            // A trust prompt outranks every liveness signal below it. The agent is
            // alive and idle by any pane or hook measure, but it is waiting on a
            // person — showing that as `Working` or `Idle` is what left users
            // watching a task that would never move.
            if let Some(ref dialog) = task_status.awaiting_trust {
                if phase == PhaseStatus::Working || phase == PhaseStatus::Idle {
                    phase = PhaseStatus::Blocked;
                    self.state.pane_content_hashes.remove(&task_status.task_id);
                    self.state.trust_blocked.insert(task_status.task_id.clone());
                    self.state.blocked_reasons.insert(
                        task_status.task_id.clone(),
                        trust_blocked_reason(&task_status.agent, dialog),
                    );
                }
            } else {
                self.state.trust_blocked.remove(&task_status.task_id);
            }

            if phase == PhaseStatus::Working {
                match task_status.hook_status.as_ref().map(|h| h.state) {
                    // The agent told us what it is doing — believe it, and drop
                    // the pane history so a later fallback starts clean.
                    Some(HookState::Working) => {
                        self.state.pane_content_hashes.remove(&task_status.task_id);
                    }
                    Some(HookState::Blocked) => {
                        phase = PhaseStatus::Blocked;
                        self.state.pane_content_hashes.remove(&task_status.task_id);
                    }
                    // Turn ended with no artifact yet: what Idle has always meant.
                    Some(HookState::Waiting) => {
                        phase = PhaseStatus::Idle;
                        self.state.pane_content_hashes.remove(&task_status.task_id);
                    }
                    Some(HookState::Ended) => {
                        phase = PhaseStatus::Exited;
                        self.state.pane_content_hashes.remove(&task_status.task_id);
                    }
                    // No hook report: unchanged 15s pane-hash heuristic.
                    None => {
                        if let Some(hash) = task_status.content_hash {
                            let entry = self
                                .state
                                .pane_content_hashes
                                .entry(task_status.task_id.clone())
                                .or_insert((hash, now));
                            if entry.0 != hash {
                                *entry = (hash, now);
                            } else if now.duration_since(entry.1)
                                >= std::time::Duration::from_secs(15)
                            {
                                phase = PhaseStatus::Idle;
                            }
                        }
                    }
                }
            } else if phase == PhaseStatus::Ready {
                self.state.pane_content_hashes.remove(&task_status.task_id);
            } else if phase == PhaseStatus::Exited {
                self.state.pane_content_hashes.remove(&task_status.task_id);
            }

            // Keep the reason text alongside the status so the card and the
            // orchestrator notification can name what the agent is waiting for.
            match (phase, task_status.hook_status.as_ref()) {
                // A trust block already wrote its own reason, and no agent hook
                // knows about it — the agent has not started reporting yet.
                _ if task_status.awaiting_trust.is_some() => {}
                (PhaseStatus::Blocked, Some(h)) => {
                    if let Some(msg) = h.message.clone() {
                        self.state
                            .blocked_reasons
                            .insert(task_status.task_id.clone(), msg);
                    }
                }
                _ => {
                    self.state.blocked_reasons.remove(&task_status.task_id);
                }
            }

            let newly_ready = phase == PhaseStatus::Ready && !task_status.was_ready;
            self.state
                .phase_status_cache
                .insert(task_status.task_id.clone(), (phase, now));

            // Collect the resolved status for readers in other processes, to be
            // published as one transaction below. This is the only writer:
            // `phase` is final here, after every override above, and recomputing
            // it elsewhere would mean duplicating the artifact-check and
            // pane-hash pipeline against the same panes.
            let pane = self.state.pane_content_hashes.get(&task_status.task_id);
            runtime_rows.push(crate::db::TaskRuntime {
                task_id: task_status.task_id.clone(),
                phase_status: phase,
                status: Some(task_status.status),
                pane_hash: pane.map(|(h, _)| h.to_string()),
                // `Instant` has no epoch, so the stored wall-clock time is
                // derived from how long ago the change was.
                pane_changed_at: pane.map(|(_, at)| {
                    chrono::Utc::now()
                        - chrono::Duration::from_std(now.duration_since(*at))
                            .unwrap_or_else(|_| chrono::Duration::zero())
                }),
                updated_at: chrono::Utc::now(),
            });

            // Notify orchestrator when a phase completes (newly Ready)
            if newly_ready {
                if self.state.orchestrator_session.is_some() {
                    if let Some(db) = &self.state.db {
                        let task_title = self
                            .state
                            .board
                            .tasks
                            .iter()
                            .find(|t| t.id == task_status.task_id)
                            .map(|t| t.title.as_str())
                            .unwrap_or("unknown");
                        let phase_name = if task_status.status == TaskStatus::Backlog {
                            "research"
                        } else {
                            task_status.status.as_str()
                        };
                        let short_id = if task_status.task_id.len() >= 8 {
                            &task_status.task_id[..8]
                        } else {
                            &task_status.task_id
                        };
                        let notif = crate::db::Notification::for_task(
                            crate::db::NotificationKind::PhaseCompleted,
                            &task_status.task_id,
                            format!(
                                "Task \"{}\" ({}) completed phase: {}",
                                task_title, short_id, phase_name
                            ),
                        );
                        let _ = db.create_notification(&notif);
                    }
                }
            }

            // Auto merge-conflict check for Review tasks
            if task_status.status == TaskStatus::Review
                && !self
                    .state
                    .merge_conflict_checked
                    .contains(&task_status.task_id)
            {
                let should_check = match phase {
                    PhaseStatus::Ready => newly_ready,
                    PhaseStatus::Idle => self
                        .state
                        .pane_content_hashes
                        .get(&task_status.task_id)
                        .map_or(false, |(_, last_change)| {
                            now.duration_since(*last_change) >= std::time::Duration::from_secs(30)
                        }),
                    _ => false,
                };

                if should_check {
                    if let (Some(ref wt), Some(ref sn)) =
                        (&task_status.worktree_path, &task_status.session_name)
                    {
                        if self.state.tmux_ops.window_exists(sn).unwrap_or(false) {
                            self.state
                                .merge_conflict_checked
                                .insert(task_status.task_id.clone());

                            let git_ops = Arc::clone(&self.state.git_ops);
                            let tmux_ops = Arc::clone(&self.state.tmux_ops);
                            let wt = wt.clone();
                            let sn = sn.clone();
                            let agent_name = task_status.agent.clone();

                            std::thread::spawn(move || {
                                match git_ops.fetch_and_check_conflicts(Path::new(&wt)) {
                                    Ok(true) => {
                                        let skill_cmd = skills::transform_plugin_command(
                                            "/agtx:merge-conflicts",
                                            &agent_name,
                                        );
                                        send_skill_and_prompt(
                                            &tmux_ops,
                                            &sn,
                                            &skill_cmd,
                                            "The feature branch has merge conflicts with the default branch. Please resolve them now.",
                                            &None,
                                            "",
                                            &agent_name,
                                            &[],
                                            false,
                                        );
                                    }
                                    Ok(false) | Err(_) => {}
                                }
                            });
                        }
                    }
                }
            }

            // Stuck-task notification: fire once when Planning/Running task has been Idle for 1+ min
            // Void plugin tasks are fully user-managed — no stuck notifications
            let task_plugin = self
                .state
                .board
                .tasks
                .iter()
                .find(|t| t.id == task_status.task_id)
                .and_then(|t| t.plugin.as_deref());
            // A task parked on a trust prompt is deliberately excluded. The
            // orchestrator's remedies are `send_to_task` (a nudge) and
            // `escalate_to_user`, and the nudge would be typed **into the dialog** —
            // the exact corruption `LAUNCH_DIALOGS` scoping exists to prevent. It is
            // also not a task the orchestrator can unstick: only the user can answer.
            // The `Blocked` badge and its reason already say so on the board.
            let trust_blocked = self.state.trust_blocked.contains(&task_status.task_id);
            if matches!(
                task_status.status,
                TaskStatus::Planning | TaskStatus::Running
            ) && matches!(phase, PhaseStatus::Idle | PhaseStatus::Blocked)
                && !trust_blocked
                && self.state.orchestrator_session.is_some()
                && should_send_stuck_notification(task_plugin)
            {
                let stuck_key = format!("{}:{}", task_status.task_id, task_status.status.as_str());
                if !self.state.stuck_task_notified.contains(&stuck_key) {
                    // Blocked is agent-reported: the agent has *said* it is
                    // waiting on a human, so there is nothing to wait out. Idle is
                    // still a guess from pane output, so it keeps its 1m settle.
                    let blocked = phase == PhaseStatus::Blocked;
                    let idle_since = self
                        .state
                        .stuck_task_idle_since
                        .entry(task_status.task_id.clone())
                        .or_insert(now);

                    if blocked
                        || now.duration_since(*idle_since) >= std::time::Duration::from_secs(60)
                    {
                        self.state.stuck_task_notified.insert(stuck_key);

                        if let Some(db) = &self.state.db {
                            let task_title = self
                                .state
                                .board
                                .tasks
                                .iter()
                                .find(|t| t.id == task_status.task_id)
                                .map(|t| t.title.as_str())
                                .unwrap_or("unknown");
                            let short_id = if task_status.task_id.len() >= 8 {
                                &task_status.task_id[..8]
                            } else {
                                &task_status.task_id
                            };
                            let reason = self.state.blocked_reasons.get(&task_status.task_id);
                            let message = match (blocked, reason) {
                                (true, Some(r)) => format!(
                                    "Task \"{}\" ({}) is blocked in phase {} waiting for: {}",
                                    task_title,
                                    short_id,
                                    task_status.status.as_str(),
                                    r
                                ),
                                (true, None) => format!(
                                    "Task \"{}\" ({}) is blocked in phase {} waiting for user input",
                                    task_title,
                                    short_id,
                                    task_status.status.as_str()
                                ),
                                _ => format!(
                                    "Task \"{}\" ({}) has been idle for 1m in phase: {}",
                                    task_title,
                                    short_id,
                                    task_status.status.as_str()
                                ),
                            };
                            let notif = crate::db::Notification::for_task(
                                crate::db::NotificationKind::TaskStuck,
                                &task_status.task_id,
                                message,
                            );
                            let _ = db.create_notification(&notif);
                        }
                    }
                }
            } else if !matches!(phase, PhaseStatus::Idle | PhaseStatus::Blocked) {
                // Task is working again — reset the idle-since timer
                self.state
                    .stuck_task_idle_since
                    .remove(&task_status.task_id);
            }
        }

        // One commit for the whole pass, and only when something is reading.
        // Pruning rides along inside it — see `publish_task_runtime`; it is done
        // there rather than at the delete sites because MCP deletes tasks from
        // another process entirely.
        if self.should_publish_runtime() {
            if let Some(db) = &self.state.db {
                if let Err(e) = db.publish_task_runtime(&runtime_rows) {
                    tracing::warn!(error = %e, "failed to publish task runtime");
                }
            }
        }
    }

    fn switch_to_project(&mut self, project: &ProjectInfo) -> Result<()> {
        self.switch_to_project_keep_sidebar(project)?;
        // Unfocus sidebar
        self.state.sidebar_focused = false;
        Ok(())
    }

    fn switch_to_project_keep_sidebar(&mut self, project: &ProjectInfo) -> Result<()> {
        let project_path = PathBuf::from(&project.path);

        // Check if project path exists
        if !project_path.exists() {
            // Skip non-existent projects silently
            return Ok(());
        }

        // Update current project
        self.state.project_name = project.name.clone();
        self.state.tmux_project_name = tmux::safe_session_name(&project.name);
        self.state.project_path = Some(project_path.clone());

        // Open project database (create if needed)
        match Database::open_project(&project_path) {
            Ok(db) => self.state.db = Some(db),
            Err(_) => {
                // If we can't open the db, skip this project
                return Ok(());
            }
        }

        // Update last_opened in global db
        let proj = crate::db::Project::new(&project.name, &project.path);
        let _ = self.state.global_db.upsert_project(&proj);

        // Ensure tmux session exists
        ensure_project_tmux_session(
            &self.state.tmux_project_name,
            &project_path,
            self.state.tmux_ops.as_ref(),
        );
        // The control client attaches to a session, and the old project's may be
        // killed later. Delivery does not depend on which one it is — commands
        // carry their own target — but the next *connect* does.
        self.state
            .input_sink
            .set_session(&self.state.tmux_project_name);

        // Clear per-task caches from previous project
        self.state.merge_conflict_checked.clear();
        self.state.stuck_task_notified.clear();
        self.state.stuck_task_idle_since.clear();

        // Reload config for the new project so per-phase agent overrides are respected
        let global_config = GlobalConfig::load().unwrap_or_default();
        let project_config = ProjectConfig::load(&project_path).unwrap_or_default();
        self.state.config = MergedConfig::merge(&global_config, &project_config);
        self.state.cached_plugin = Some(load_plugin_if_configured(
            &self.state.config,
            Some(&project_path),
        ));

        // Reload tasks for new project
        self.refresh_tasks()?;

        Ok(())
    }
}

impl Drop for App {
    fn drop(&mut self) {
        // Stop a server started from the overlay. tmux windows deliberately
        // outlive agtx; a child server must not, or it holds its port with
        // nothing on screen owning it. Quitting is the only thing that stops
        // it — closing the overlay does not.
        self.state.serve_session = None;

        // Deliver what is still queued and stop the broker before the process
        // goes away — the last characters typed into a pane were typed on
        // purpose. Bounded by the queue depth, so quitting stays instant.
        self.state.input_sink.shutdown();
        match self.terminal.backend_mut() {
            AppBackend::Crossterm(backend) => {
                let _ = disable_raw_mode();
                let _ = execute!(backend, LeaveAlternateScreen, DisableBracketedPaste);
            }
            #[cfg(feature = "test-mocks")]
            AppBackend::Test(_) => {}
        }
    }
}

/// Ensure tmux session exists for a project
// =============================================================================
// Orchestrator idle detection (extracted for testability)
// =============================================================================

/// Result of checking whether the orchestrator is idle and ready for notifications.
#[derive(Debug, PartialEq)]
enum OrchestratorIdleResult {
    /// Agent is idle — safe to deliver notifications.
    Idle,
    /// Content changed and no idle signal — agent is actively working.
    Busy,
    /// Content unchanged but not stable long enough — keep waiting.
    Waiting,
}

/// Idle detection duration for the stability fallback (no `[agtx:idle]` signal).
const ORCHESTRATOR_IDLE_FALLBACK_SECS: u64 = 15;

/// Pure idle-detection logic for the orchestrator pane.
///
/// Checks two conditions (first match wins):
/// 1. **Explicit signal**: pane content contains `[agtx:idle]` → `Idle`
/// 2. **Stability fallback**: pane unchanged for ≥15s → `Idle`
///
/// Returns `Busy` when content changed without the idle signal,
/// `Waiting` when content is unchanged but the timer hasn't elapsed.
fn check_orchestrator_idle(
    current_content: &str,
    last_content: &str,
    stable_since: Option<Instant>,
) -> OrchestratorIdleResult {
    let has_idle_signal = current_content.contains("[agtx:idle]");
    let content_changed = current_content != last_content;

    if content_changed {
        if has_idle_signal {
            OrchestratorIdleResult::Idle
        } else {
            OrchestratorIdleResult::Busy
        }
    } else {
        // Content unchanged — check stability timer
        match stable_since {
            Some(t)
                if t.elapsed()
                    >= std::time::Duration::from_secs(ORCHESTRATOR_IDLE_FALLBACK_SECS) =>
            {
                OrchestratorIdleResult::Idle
            }
            _ => OrchestratorIdleResult::Waiting,
        }
    }
}

/// Returns true if the task already has a tmux window that is currently alive.
/// Used to decide whether to reuse an existing session instead of creating a new one.
fn task_has_live_session(task: &Task, tmux_ops: &dyn TmuxOperations) -> bool {
    task.session_name
        .as_ref()
        .map_or(false, |s| tmux_ops.window_exists(s).unwrap_or(false))
}

fn ensure_project_tmux_session(
    project_name: &str,
    project_path: &Path,
    tmux_ops: &dyn TmuxOperations,
) {
    if !tmux_ops.has_session(project_name) {
        let _ = tmux_ops.create_session(project_name, &project_path.to_string_lossy());
    }
}

/// Recover a task's tmux session by creating a new window with the agent's resume command.
/// Used when the tmux window has been lost (server restart, manual kill, etc.)
/// but the task's worktree and agent session data still exist on disk.
/// Returns the tmux target string on success.
fn recover_task_session(
    task: &Task,
    project_name: &str,
    project_path: &Path,
    tmux_ops: &dyn TmuxOperations,
    agent_ops: &dyn AgentOperations,
) -> Result<String> {
    let worktree_path = task
        .worktree_path
        .as_ref()
        .ok_or_else(|| anyhow::anyhow!("Task has no worktree path"))?;

    if !Path::new(worktree_path).exists() {
        anyhow::bail!("Worktree no longer exists: {}", worktree_path);
    }

    let target = task
        .session_name
        .as_ref()
        .ok_or_else(|| anyhow::anyhow!("Task has no session name"))?;
    let (session, window) = target
        .split_once(':')
        .ok_or_else(|| anyhow::anyhow!("Invalid session name format: {}", target))?;

    ensure_project_tmux_session(project_name, project_path, tmux_ops);

    let resume_cmd = agent_ops.build_resume_command();

    tmux_ops.create_window(
        session,
        window,
        worktree_path,
        Some(resume_cmd),
        true,
        &agtx_task_env(&task.id, worktree_path),
    )?;

    Ok(target.clone())
}

/// Copy files/dirs from worktree back to project root.
/// Used by plugins with `[copy_back]` to sync artifacts after phase completion.
fn copy_back_to_project(worktree: &Path, project_root: &Path, entries: &[String]) {
    for entry in entries {
        let src = worktree.join(entry);
        let dst = project_root.join(entry);
        if !src.exists() {
            continue;
        }
        if src.is_dir() {
            let _ = crate::git::copy_dir_recursive(&src, &dst);
        } else {
            // Ensure parent directory exists for nested file paths
            if let Some(parent) = dst.parent() {
                let _ = std::fs::create_dir_all(parent);
            }
            let _ = std::fs::copy(&src, &dst);
        }
    }
}

/// Whether a task can have a meaningful phase status right now.
///
/// Both halves of the refresh contract read this: `maybe_spawn_session_refresh`
/// to decide what to poll, and `apply_session_refresh` to decide what to keep.
/// They must agree — the refresh runs on a thread, so a task can leave a
/// refreshable status between being selected and its result coming back, and
/// nothing polls Done to correct a value written after the fact.
fn has_live_phase_status(task: &Task) -> bool {
    let refreshable = matches!(
        task.status,
        TaskStatus::Planning | TaskStatus::Running | TaskStatus::Review
    ) || (task.status == TaskStatus::Backlog && task.session_name.is_some());
    refreshable && (task.worktree_path.is_some() || task.session_name.is_some())
}

/// Generate a URL-safe slug from task ID and title
fn generate_task_slug(task_id: &str, title: &str) -> String {
    let title_slug: String = title
        .chars()
        .map(|c| {
            if c.is_alphanumeric() || c == '-' || c == '_' {
                c
            } else {
                '-'
            }
        })
        .take(30)
        .collect();
    let title_slug = title_slug.trim_matches('-').to_string();

    // Add task ID prefix to ensure uniqueness
    let id_prefix: String = task_id.chars().take(8).collect();
    format!("{}-{}", id_prefix, title_slug)
}

fn run_cleanup_script_for_worktree(cleanup_script: Option<&str>, worktree_path: &Path) {
    let Some(script) = cleanup_script else {
        return;
    };
    let script = script.trim();
    if script.is_empty() {
        return;
    }

    tracing::info!(
        script = script,
        worktree = %worktree_path.display(),
        "Executing cleanup_script"
    );

    match git::run_worktree_script(script, worktree_path, &[]) {
        Err(e) => eprintln!("cleanup_script failed to run: {}", e),
        Ok(output) => {
            if !output.status.success() {
                eprintln!(
                    "cleanup_script exited with {}: {}",
                    output.status,
                    output.stderr.trim()
                );
            }
        }
    }
}

/// Background-safe cleanup: archive artifacts, kill tmux window, run cleanup script, remove worktree.
/// Takes owned/cloned values so it can run in a spawned thread.
fn cleanup_task_resources(
    task_id: &str,
    agent: &str,
    branch_name: &Option<String>,
    session_name: &Option<String>,
    worktree_path: &Option<String>,
    cleanup_script: Option<&str>,
    project_path: &Path,
    tmux_ops: &dyn TmuxOperations,
    git_ops: &dyn GitOperations,
) {
    // Drop this worktree from the agent's trust store, before it is removed —
    // `forget` resolves the path, which needs the directory to still exist.
    //
    // Only stores agtx seeds are pruned; a record agtx did not write is not
    // agtx's to delete. Without this the lists grow one dead entry per task
    // forever: the machine this was written on had 19 in antigravity's, 27 in
    // codex's and ~20 in claude's, nearly all pointing at directories that were
    // long gone.
    if let (Some(worktree), Some(home)) = (worktree_path, agent_trust_home()) {
        let _ = agent::trust::forget(agent, Path::new(worktree), &home);
    }

    // Archive artifacts before removing worktree
    if let Some(worktree) = worktree_path {
        let artifacts_dir = Path::new(worktree).join(".agtx");
        if artifacts_dir.exists() {
            let slug = branch_name
                .as_deref()
                .and_then(|b| b.rsplit_once('/').map(|(_, s)| s))
                .unwrap_or(task_id);
            let archive_dir = project_path.join(".agtx").join("archive").join(slug);
            if let Ok(()) = std::fs::create_dir_all(&archive_dir) {
                if let Ok(entries) = std::fs::read_dir(&artifacts_dir) {
                    for entry in entries.flatten() {
                        let path = entry.path();
                        if path.is_file() && path.extension().map_or(false, |ext| ext == "md") {
                            let _ = std::fs::copy(&path, archive_dir.join(entry.file_name()));
                        }
                    }
                }
            }
        }
    }

    if let Some(session_name) = session_name {
        // Reap the pane's descendants *before* the window dies. `kill-window`
        // signals the pane's own process group, which misses anything the agent
        // backgrounded into a group of its own — a dev server, a watcher, a
        // `python3 -m http.server`. Those survive, get reparented to init, and
        // keep holding their ports long after the task is Done and its worktree
        // is gone.
        //
        // Order matters and is the whole reason this is not simply a `pkill`
        // afterwards: once the window is killed the parent links are gone and
        // the survivors can no longer be attributed to this task at all.
        reap_task_processes(task_id, session_name, tmux_ops);
        let _ = tmux_ops.kill_window(session_name);
    }
    if let Some(worktree) = worktree_path {
        run_cleanup_script_for_worktree(cleanup_script, Path::new(worktree));
        if let Err(e) = git_ops.remove_worktree(project_path, worktree) {
            tracing::warn!(worktree = %worktree, error = %e, "Failed to remove worktree");
        }
    }
}

/// The paths agtx writes into a worktree, as git exclude patterns.
///
/// Must track the writers in `write_skills_to_worktree`, `write_mcp_config` and
/// `write_hook_config`. Deliberately specific rather than whole dotdirs: a
/// project may keep its own `.claude/` or `.cursor/` content, and only the
/// entries agtx creates are agtx's to hide.
const AGTX_WRITTEN_PATHS: &[&str] = &[
    ".agtx/",
    ".mcp.json",
    ".claude/settings.local.json",
    ".claude/commands/agtx/",
    ".gemini/settings.json",
    ".gemini/commands/agtx/",
    ".codex/config.toml",
    ".codex/skills/agtx-*/",
    ".cursor/mcp.json",
    ".cursor/hooks.json",
    ".cursor/skills/agtx-*/",
    ".grok/config.toml",
    ".grok/hooks/agtx.json",
    ".grok/skills/agtx-*/",
    ".agents/mcp_config.json",
    ".agents/hooks.json",
    ".agents/skills/agtx-*/",
    ".opencode/command/agtx-*.md",
    ".github/agents/agtx/",
    ".pi/mcp.json",
    ".pi/skills/agtx-*/",
];

/// Marks agtx's block in `info/exclude` so it is written once and is obvious to
/// anyone who finds it.
const AGTX_EXCLUDE_MARKER: &str = "# agtx: files agtx writes into worktrees";

/// Hide agtx's own bookkeeping from git, so it does not read as the agent's
/// uncommitted work.
///
/// Without this, `.agtx/` and the per-agent config agtx deploys show as
/// untracked in every worktree — and `has_changes`, which the Done guard reads
/// from `git status --porcelain`, counts untracked files. agtx's own writes
/// would trip agtx's own guard on a project's first task, before any
/// `.gitignore` exists, and a guard that cries wolf first and means it second
/// stops being believed.
///
/// **There is exactly one place this can go.** Measured against git 2.55.0: a
/// per-worktree `.git/worktrees/<name>/info/exclude` is *ignored*; only
/// `$GIT_COMMON_DIR/info/exclude` takes effect, and it applies to the main
/// checkout as well as every worktree.
///
/// Sharing it with the user's own checkout is safe because **exclude patterns
/// only affect untracked files** — also measured: a tracked `.mcp.json` still
/// reports its modification with `.mcp.json` excluded. So a
/// project that deliberately tracks any of these keeps tracking it, and nothing
/// a user committed can be hidden. What this changes is only whether files agtx
/// created show up as noise.
fn exclude_agtx_files_from_git(worktree: &Path) {
    let Ok(out) = std::process::Command::new("git")
        .current_dir(worktree)
        .args(["rev-parse", "--git-common-dir"])
        .output()
    else {
        return;
    };
    if !out.status.success() {
        return;
    }
    let common = String::from_utf8_lossy(&out.stdout).trim().to_string();
    if common.is_empty() {
        return;
    }
    // `--git-common-dir` answers relative to the worktree unless it is absolute.
    let common = {
        let p = Path::new(&common);
        if p.is_absolute() {
            p.to_path_buf()
        } else {
            worktree.join(p)
        }
    };

    let exclude = common.join("info").join("exclude");
    let existing = std::fs::read_to_string(&exclude).unwrap_or_default();
    if existing.contains(AGTX_EXCLUDE_MARKER) {
        return;
    }

    let mut out = existing;
    if !out.is_empty() && !out.ends_with('\n') {
        out.push('\n');
    }
    out.push_str(&format!(
        "\n{AGTX_EXCLUDE_MARKER}\n\
         # Only untracked files are affected; anything this project tracks is untouched.\n\
         # Delete this block to see them in `git status` again.\n"
    ));
    for pattern in AGTX_WRITTEN_PATHS {
        out.push_str(pattern);
        out.push('\n');
    }

    if let Some(dir) = exclude.parent() {
        if std::fs::create_dir_all(dir).is_err() {
            return;
        }
    }
    if let Err(e) = std::fs::write(&exclude, out) {
        tracing::warn!(path = %exclude.display(), error = %e, "Failed to write git exclude");
    }
}

/// Record where review got to, so the next one can read only what came after.
///
/// Written when a task leaves Review for Running — the resume path — because
/// that commit is exactly "what the last review already looked at". The next
/// review reads the file and diffs from there instead of re-reading the whole
/// branch, which it would otherwise do every cycle: `clear_context_on_advance`
/// means the review agent starts with no memory of its own previous pass.
///
/// A file in the worktree rather than a column on the task, because the only
/// reader is the review skill and it is already reading `.agtx/`. Nothing
/// queries this, so a schema change would buy nothing, and it is removed with
/// the worktree it describes.
///
/// **This is a commit, so it describes committed work only** — a phase that
/// leaves changes uncommitted is not represented here. That is why the skill
/// pairs `<marker>..HEAD` with `git status --short`: between them they cover
/// what was committed since the marker *and* whatever is still uncommitted now.
/// The two can overlap — work that was uncommitted when the marker was written
/// and committed afterwards falls into both — so such a change is reviewed
/// twice. Erring that way is deliberate: the failure mode is a redundant read,
/// never a skipped one.
///
/// The second half is `git status --short` and not `git diff HEAD` because
/// **`git diff` does not show untracked files at all**. A brand-new file from
/// the running phase is absent from the range diff (not committed) and absent
/// from the working-tree diff (not tracked), so the obvious pairing reviews it
/// in neither. `the_marker_never_covers_uncommitted_work` pins that.
///
/// Best-effort: a task with no worktree, or a repository that cannot be read,
/// simply leaves no marker and the next review falls back to the full diff —
/// which is the correct answer when the reviewed point is unknown.
fn mark_reviewed_point(task: &Task) {
    let Some(worktree) = task.worktree_path.as_deref() else {
        return;
    };
    let worktree = Path::new(worktree);
    let Ok(sha) = crate::git::head_sha(worktree) else {
        return;
    };
    let dir = worktree.join(".agtx");
    if std::fs::create_dir_all(&dir).is_err() {
        return;
    }
    if let Err(e) = std::fs::write(dir.join(REVIEWED_AT_FILE), format!("{sha}\n")) {
        tracing::warn!(task_id = %task.id, error = %e, "Failed to record the reviewed point");
    }
}

/// Terminate everything a task started, before its window and worktree go.
///
/// Two ways of finding them, because neither alone is enough:
///
/// - **By environment.** `create_window` sets `AGTX_TASK_ID` on the tmux window,
///   and a child inherits the environment at spawn and never loses it. This is
///   what catches a *daemonized* process: one reparented to init as soon as it
///   was backgrounded still carries the task id. Attribution is exact, and
///   enumerating costs ~0.1s.
/// - **By descent from the pane.** The backstop for anything that never received
///   the environment.
///
/// Walking the pane's descendants alone is not enough: a process reparented to
/// init *before* cleanup runs is no longer in the tree, so ordering the walk
/// ahead of `kill-window` — necessary, since the links vanish with the window —
/// still misses exactly the case that matters.
///
/// The alternatives were measured and rejected. A cwd scan
/// (`lsof -u <uid> -d cwd`) takes ~12s, and `lsof +D <worktree>` walks the tree
/// — 26s on a large checkout — while matching nothing once the directory is
/// gone. Session id is not readable per-process from `ps` on macOS.
///
/// Children are signalled before parents so a supervisor cannot restart one on
/// the way down. Best-effort by design: a process that has already exited is
/// skipped rather than treated as a failure. Cleanup runs on a background thread
/// after the task is already Done, and there is nothing useful to abort.
fn reap_task_processes(task_id: &str, target: &str, tmux_ops: &dyn TmuxOperations) {
    let mut victims = processes_for_task(task_id);
    for pid in pane_descendants(target, tmux_ops) {
        if !victims.contains(&pid) {
            victims.push(pid);
        }
    }
    // Never signal agtx itself. It carries no `AGTX_TASK_ID` and is not
    // descended from the pane, so this cannot currently match — it is here
    // because the cost of being wrong is killing the board mid-cleanup.
    let me = std::process::id();
    victims.retain(|pid| *pid != me);

    if victims.is_empty() {
        return;
    }
    tracing::info!(
        task_id = %task_id,
        target = %target,
        count = victims.len(),
        "Terminating processes started by a task"
    );
    signal_all(&victims, "TERM");
    std::thread::sleep(std::time::Duration::from_millis(300));
    signal_all(&victims, "KILL");
}

/// Every process carrying this task's `AGTX_TASK_ID`, however it was reparented.
///
/// Reads `/proc/<pid>/environ` where it exists and falls back to `ps -Eww`,
/// which is what macOS offers. The two cannot share one command: Linux's `ps -E`
/// means something else entirely.
fn processes_for_task(task_id: &str) -> Vec<u32> {
    let needle = format!("{}={}", hook_status::ENV_TASK_ID, task_id);

    if Path::new("/proc").is_dir() {
        let mut found = Vec::new();
        if let Ok(entries) = std::fs::read_dir("/proc") {
            for entry in entries.flatten() {
                let Some(pid) = entry
                    .file_name()
                    .to_str()
                    .and_then(|n| n.parse::<u32>().ok())
                else {
                    continue;
                };
                // NUL-separated; a lossy read is fine, the needle is ASCII.
                if let Ok(env) = std::fs::read(entry.path().join("environ")) {
                    if String::from_utf8_lossy(&env)
                        .split('\0')
                        .any(|v| v == needle)
                    {
                        found.push(pid);
                    }
                }
            }
        }
        return found;
    }

    // `-A` is load-bearing: without a process selector `ps` lists only the
    // processes attached to the caller's own terminal, so a daemonized orphan —
    // the entire reason this function exists — never appears. Verified against a
    // real survivor: no selector found nothing, `-A` found it.
    let Ok(out) = std::process::Command::new("ps")
        .args(["-AEww", "-o", "pid=,command="])
        .output()
    else {
        return Vec::new();
    };
    pids_matching_env(&String::from_utf8_lossy(&out.stdout), &needle)
}

/// Pick the pids out of `ps -Eww -o pid=,command=` output whose line carries
/// `needle`.
///
/// Split out because the surrounding call cannot be tested reliably: whether
/// `ps` exposes another process's environment depends on the platform and on
/// how the caller itself was launched. The parsing is what can regress, and a
/// mis-parse here signals the wrong pids to kill.
fn pids_matching_env(ps_output: &str, needle: &str) -> Vec<u32> {
    ps_output
        .lines()
        .filter(|line| line.contains(needle))
        .filter_map(|line| line.split_whitespace().next()?.parse().ok())
        .collect()
}

/// Every process descended from a task pane, deepest first.
fn pane_descendants(target: &str, tmux_ops: &dyn TmuxOperations) -> Vec<u32> {
    let Some(root) = tmux_ops.pane_pid(target) else {
        return Vec::new();
    };
    // pid 0 and pid 1 are the roots of the whole process tree — on macOS pid 0
    // is the ancestor of launchd, so `descendants_of(0)` returns *every process
    // on the machine*. A pane can never legitimately be either, so a value this
    // low means tmux answered with something that is not a pane pid, and the
    // only safe response is to reap nothing.
    if root <= 1 {
        tracing::warn!(target = %target, pane_pid = root, "Refusing to reap from a root pid");
        return Vec::new();
    }
    descendants_of(root)
}

/// Send one signal to every pid, children before parents.
///
/// Shelling out to `kill` rather than taking a `libc` dependency for two
/// signals: this file already reaches git and tmux the same way, and it keeps
/// the whole path free of `unsafe`.
fn signal_all(pids: &[u32], signal: &str) {
    if pids.is_empty() {
        return;
    }
    let mut cmd = std::process::Command::new("kill");
    cmd.arg(format!("-{signal}"));
    for pid in pids.iter().rev() {
        cmd.arg(pid.to_string());
    }
    // Non-zero here means "already gone", which is the desired end state.
    let _ = cmd.output();
}

/// Every descendant of `root`, parents before children.
///
/// Built from one `ps` snapshot rather than by walking `/proc`, which does not
/// exist on macOS. `root` itself is excluded — `kill-window` owns the pane.
fn descendants_of(root: u32) -> Vec<u32> {
    let Ok(out) = std::process::Command::new("ps")
        .args(["-Ao", "pid=,ppid="])
        .output()
    else {
        return Vec::new();
    };
    let text = String::from_utf8_lossy(&out.stdout);

    let mut children: HashMap<u32, Vec<u32>> = HashMap::new();
    for line in text.lines() {
        let mut it = line.split_whitespace();
        if let (Some(Ok(pid)), Some(Ok(ppid))) = (
            it.next().map(str::parse::<u32>),
            it.next().map(str::parse::<u32>),
        ) {
            children.entry(ppid).or_default().push(pid);
        }
    }

    let mut found = Vec::new();
    let mut queue = std::collections::VecDeque::from([root]);
    while let Some(pid) = queue.pop_front() {
        for &child in children.get(&pid).map(Vec::as_slice).unwrap_or(&[]) {
            // A cycle is impossible in a real process tree, but the snapshot is
            // read from text and a malformed row must not spin forever.
            if child != root && !found.contains(&child) {
                found.push(child);
                queue.push_back(child);
            }
        }
    }
    found
}

/// Set up a worktree and tmux window for a task.
/// Creates worktree, initializes it (copy files + init script), creates tmux window with agent.
/// Updates task fields (session_name, worktree_path, branch_name) in place.
/// Returns the tmux target string on success.
///
/// `prompt` is used only for agents without native skill invocation (fallback).
/// For agents with skill support, the agent starts with no prompt and the skill command
/// is sent later via send_keys (see the acceptance thread in move_task_right).
fn setup_task_worktree(
    task: &mut Task,
    project_path: &Path,
    tmux_project_name: &str,
    prompt: &str,
    base_branch: &str,
    worktree_dir: &str,
    branch_prefix: &str,
    copy_files: Option<String>,
    init_script: Option<String>,
    plugin: &Option<WorkflowPlugin>,
    agent_name: &str,
    all_phase_agents: &[String],
    tmux_ops: &dyn TmuxOperations,
    git_ops: &dyn GitOperations,
    agent_ops: &dyn AgentOperations,
    referenced_tasks: &[ReferencedTaskInfo],
    skip_init_scripts: bool,
    skip_worktree: bool,
    agent_hooks: bool,
    skill_cmd: Option<&str>,
) -> Result<(String, bool)> {
    let unique_slug = generate_task_slug(&task.id, &task.title);
    let window_name = format!("task-{}", unique_slug);
    let target = format!("{}:{}", tmux_project_name, window_name);

    // When skip_worktree is set, use the project root directly instead of creating a git worktree.
    // Useful for isolated environments (e.g. Docker) where the repo is already the working copy.
    let worktree_path_str = if skip_worktree {
        project_path.to_string_lossy().to_string()
    } else {
        // Create git worktree from the configured base branch
        match git_ops.create_worktree(
            project_path,
            &unique_slug,
            base_branch,
            worktree_dir,
            branch_prefix,
        ) {
            Ok(path) => path,
            Err(e) => {
                eprintln!("Failed to create worktree: {}", e);
                project_path
                    .join(worktree_dir)
                    .join(&unique_slug)
                    .to_string_lossy()
                    .to_string()
            }
        }
    };

    // Initialize worktree: copy files and run init script
    // Merge plugin-level copy_files with project-level copy_files
    let worktree_path = Path::new(&worktree_path_str);
    let copy_dirs = plugin
        .as_ref()
        .map_or_else(Vec::new, |p| p.copy_dirs.clone());
    let merged_copy_files = {
        let mut parts: Vec<String> = Vec::new();
        if let Some(ref cf) = copy_files {
            if !cf.trim().is_empty() {
                parts.push(cf.clone());
            }
        }
        if let Some(ref p) = plugin {
            if !p.copy_files.is_empty() {
                parts.push(p.copy_files.join(","));
            }
        }
        if parts.is_empty() {
            None
        } else {
            Some(parts.join(","))
        }
    };
    let init_warnings = git_ops.initialize_worktree(
        project_path,
        worktree_path,
        merged_copy_files,
        init_script,
        copy_dirs,
    );
    // Warnings from copy_files are expected (e.g. files don't exist yet on first run)
    let _ = &init_warnings;

    // Write skills to worktree .agtx/skills/ and agent-native discovery paths
    // Deploy for all unique agents configured across phases
    let agent_refs: Vec<&str> = all_phase_agents.iter().map(|s| s.as_str()).collect();
    write_skills_to_worktree(
        &worktree_path_str,
        project_path,
        plugin,
        &agent_refs,
        agent_hooks,
    );

    // Copy referenced task artifacts into .agtx/references/
    if !referenced_tasks.is_empty() {
        let refs_dir = worktree_path.join(".agtx").join("references");
        for ref_info in referenced_tasks {
            // 1. Git diff of referenced task's branch
            if let Some(ref branch) = ref_info.branch_name {
                if let Ok(output) = std::process::Command::new("git")
                    .args(["diff", &format!("main..{}", branch)])
                    .current_dir(project_path)
                    .output()
                {
                    if output.status.success() && !output.stdout.is_empty() {
                        let _ = std::fs::create_dir_all(&refs_dir);
                        let diff_path = refs_dir.join(format!("{}.diff", ref_info.slug));
                        let _ = std::fs::write(&diff_path, &output.stdout);
                    }
                }
            }
            // 2. Copy artifact files from referenced task's worktree (if it still exists)
            if let Some(ref wt) = ref_info.worktree_path {
                let wt_path = Path::new(wt);
                if wt_path.exists() {
                    let dest = refs_dir.join(&ref_info.slug);
                    let _ = std::fs::create_dir_all(&dest);
                    // Copy common artifact locations
                    for pattern in &[".agtx/skills", ".planning"] {
                        let src = wt_path.join(pattern);
                        if src.exists() {
                            let target_dir = dest.join(pattern);
                            let _ = crate::git::copy_dir_recursive(&src, &target_dir);
                        }
                    }
                }
            }
        }
    }

    // Run plugin init_script (in addition to project init_script)
    // Supports {agent} placeholder for agent-specific initialization
    if !skip_init_scripts {
        if let Some(ref p) = plugin {
            if let Some(ref script) = p.init_script {
                let script = script.replace("{agent}", agent_name);
                tracing::info!(
                    script = %script,
                    agent = agent_name,
                    worktree = %worktree_path_str,
                    "Executing plugin init_script"
                );
                let output = std::process::Command::new("sh")
                    .arg("-c")
                    .arg(&script)
                    .current_dir(&worktree_path_str)
                    .output();
                match output {
                    Ok(o) if !o.status.success() => {
                        let stderr = String::from_utf8_lossy(&o.stderr);
                        anyhow::bail!(
                            "Plugin init_script failed (exit {}): {}\n{}",
                            o.status.code().unwrap_or(-1),
                            script,
                            stderr.trim()
                        );
                    }
                    Err(e) => {
                        anyhow::bail!("Plugin init_script failed to run: {}\n{}", script, e);
                    }
                    _ => {}
                }
            }
        }
    }

    // Hand the opening message to the agent process when it can take one. That
    // removes the send-after-ready race entirely for the first message: there is
    // no window in which a keystroke can be dropped, and nothing to poll for.
    // Agents without a verified launch form — or a task too large for argv —
    // fall back to the historical path (launch bare, wait for readiness, type).
    let launch_text = compose_launch_text(skill_cmd, prompt);
    let launched_with_prompt =
        agent::spec::can_launch_with_prompt(agent_ops.prompt_injection(), &launch_text);
    let agent_cmd = if launched_with_prompt {
        agent_ops.build_interactive_command(&launch_text)
    } else {
        let has_skill_support = resolve_skill_command(
            plugin, "planning", agent_name, "", task.cycle, &task.id, true,
        )
        .is_some();
        if has_skill_support {
            agent_ops.build_interactive_command("")
        } else {
            agent_ops.build_interactive_command(prompt)
        }
    };

    // Ensure project tmux session exists
    ensure_project_tmux_session(tmux_project_name, project_path, tmux_ops);

    tracing::info!(
        task_id = %task.id,
        agent = agent_name,
        worktree = %worktree_path_str,
        "Agent session spawned"
    );

    tmux_ops.create_window(
        tmux_project_name,
        &window_name,
        &worktree_path_str,
        Some(agent_cmd),
        true,
        &agtx_task_env(&task.id, &worktree_path_str),
    )?;

    task.session_name = Some(target.clone());
    task.worktree_path = Some(worktree_path_str);
    task.branch_name = Some(format!("{}/{}", branch_prefix, unique_slug));

    Ok((target, launched_with_prompt))
}

/// Delete task resources: kill tmux window, run cleanup script, remove worktree, delete branch
fn delete_task_resources(
    task: &Task,
    cleanup_script: Option<&str>,
    project_path: &Path,
    tmux_ops: &dyn TmuxOperations,
    git_ops: &dyn GitOperations,
) {
    // Same prune as the Done path: a deleted task's worktree is just as gone.
    if let (Some(worktree), Some(home)) = (&task.worktree_path, agent_trust_home()) {
        let _ = agent::trust::forget(&task.agent, Path::new(worktree), &home);
    }

    // Kill tmux window if exists
    if let Some(ref session_name) = task.session_name {
        let _ = tmux_ops.kill_window(session_name);
    }

    // Removing the worktree does not depend on there being a branch. Nesting the
    // two leaked the checkout for every task that had a worktree and no branch —
    // a setup that failed after `create_worktree`, or a worktree created for a
    // research session that never reached Planning.
    if let Some(ref worktree) = task.worktree_path {
        run_cleanup_script_for_worktree(cleanup_script, Path::new(worktree));
        if let Err(e) = git_ops.remove_worktree(project_path, worktree) {
            tracing::warn!(worktree = %worktree, error = %e, "Failed to remove worktree");
        }

        // Deleting the branch stays paired with having had a worktree, and is not
        // hoisted out with the removal above. A task with a branch but no worktree
        // is one that reached Done, where the workflow keeps the branch on
        // purpose — and `delete_branch` is `git branch -D`, so hoisting it would
        // silently force-delete work the user was told was preserved.
        if let Some(ref branch_name) = task.branch_name {
            let _ = git_ops.delete_branch(project_path, branch_name);
        }
    }
}

/// Collect git diff content from a worktree
/// Returns formatted diff sections (unstaged, staged, untracked)
fn collect_task_diff(
    worktree_path: &str,
    git_ops: &dyn GitOperations,
    exclude_prefixes: &[&str],
) -> String {
    let worktree = Path::new(worktree_path);
    let mut sections = Vec::new();

    // Unstaged changes (modified tracked files)
    let unstaged = git_ops.diff(worktree);
    if !unstaged.trim().is_empty() {
        sections.push(format!("=== Unstaged Changes ===\n\n{}", unstaged));
    }

    // Staged changes
    let staged = git_ops.diff_cached(worktree);
    if !staged.trim().is_empty() {
        sections.push(format!("=== Staged Changes ===\n\n{}", staged));
    }

    // Untracked files - show as diff (new file content)
    let untracked = git_ops.list_untracked_files(worktree);
    if !untracked.trim().is_empty() {
        let mut untracked_section = String::from("=== Untracked Files ===\n");
        for file in untracked.lines() {
            let file = file.trim();
            if file.is_empty() {
                continue;
            }
            // Skip files in copied directories (agent configs, plugin dirs)
            if exclude_prefixes
                .iter()
                .any(|prefix| file.starts_with(&format!("{}/", prefix.trim_end_matches('/'))))
            {
                continue;
            }
            // Show diff for untracked file (as if adding new file)
            let file_diff = git_ops.diff_untracked_file(worktree, file);
            if !file_diff.trim().is_empty() {
                untracked_section.push_str(&format!("\n{}", file_diff));
            } else {
                // Fallback: just show file name
                untracked_section.push_str(&format!("\n+++ new file: {}\n", file));
            }
        }
        sections.push(untracked_section);
    }

    if sections.is_empty() {
        format!("(no changes)\n\nWorktree: {}", worktree_path)
    } else {
        sections.join("\n\n")
    }
}

/// Helper function to create a centered rect
/// Clamp a horizontal scroll offset (in level-columns) so the selected level is
/// visible within a viewport `visible` columns wide. Returns the new offset.
///
/// - If the selection is left of the window, scroll left to it.
/// - If it is at/past the right edge, scroll right so it sits on the last
///   visible column.
/// - The offset never exceeds what keeps the last column flush with the right
///   edge (no blank trailing space when the graph is wider than the viewport).
fn clamp_scroll_to_selected(
    scroll: usize,
    sel_level: usize,
    visible: usize,
    level_count: usize,
) -> usize {
    let visible = visible.max(1);
    let mut start = scroll.min(level_count.saturating_sub(1));
    if sel_level < start {
        start = sel_level;
    } else if sel_level >= start + visible {
        start = sel_level + 1 - visible;
    }
    // Don't scroll past the point where the final column is at the right edge.
    let max_start = level_count.saturating_sub(visible);
    start.min(max_start)
}

/// Truncate a string to at most `max` characters, appending an ellipsis when
/// it was shortened. Operates on chars so it is UTF-8 safe.
fn truncate_str(s: &str, max: usize) -> String {
    if max == 0 {
        return String::new();
    }
    let char_count = s.chars().count();
    if char_count <= max {
        return s.to_string();
    }
    if max == 1 {
        return "\u{2026}".to_string();
    }
    let taken: String = s.chars().take(max - 1).collect();
    format!("{taken}\u{2026}")
}

fn centered_rect(percent_x: u16, percent_y: u16, r: Rect) -> Rect {
    let popup_layout = Layout::default()
        .direction(Direction::Vertical)
        .constraints([
            Constraint::Percentage((100 - percent_y) / 2),
            Constraint::Percentage(percent_y),
            Constraint::Percentage((100 - percent_y) / 2),
        ])
        .split(r);

    Layout::default()
        .direction(Direction::Horizontal)
        .constraints([
            Constraint::Percentage((100 - percent_x) / 2),
            Constraint::Percentage(percent_x),
            Constraint::Percentage((100 - percent_x) / 2),
        ])
        .split(popup_layout[1])[1]
}

/// Create a centered popup with fixed width and percentage height
fn centered_rect_fixed_width(fixed_width: u16, percent_y: u16, r: Rect) -> Rect {
    // Cap width to terminal width minus some margin
    let width = fixed_width.min(r.width.saturating_sub(4));

    let popup_layout = Layout::default()
        .direction(Direction::Vertical)
        .constraints([
            Constraint::Percentage((100 - percent_y) / 2),
            Constraint::Percentage(percent_y),
            Constraint::Percentage((100 - percent_y) / 2),
        ])
        .split(r);

    // Calculate horizontal centering
    let horizontal_margin = r.width.saturating_sub(width) / 2;

    Rect {
        x: r.x + horizontal_margin,
        y: popup_layout[1].y,
        width,
        height: popup_layout[1].height,
    }
}

/// Capture a pane's content with history (ANSI escape sequences included) and
/// the metrics describing it, in one pass.
fn capture_tmux_pane_snapshot(
    window_name: &str,
    history_lines: i32,
    tmux_ops: &dyn TmuxOperations,
) -> PaneCapture {
    let content = tmux_ops.capture_pane_with_history(window_name, history_lines);

    // Get the cursor position and pane height to know where the "real" content ends
    // Lines below the cursor are unused pane buffer space
    let metrics = tmux_ops.pane_metrics(window_name);

    trim_pane_snapshot(crate::tmux::PaneSnapshot { content, metrics })
}

/// A trimmed pane capture: what the popup draws, plus where the cursor is in it.
///
/// The cursor's row travels with the content because trimming is what makes it
/// underivable later — see [`ShellPopup::cursor_line`].
type PaneCapture = (Vec<u8>, Option<crate::tmux::PaneMetrics>, Option<usize>);

/// Cut the unused pane buffer below the cursor off a capture.
///
/// Shared by both capture paths so they cannot disagree about what the popup is
/// shown — the whole point of the control-mode path is to be indistinguishable
/// from the subprocess one apart from its cost.
fn trim_pane_snapshot(snapshot: crate::tmux::PaneSnapshot) -> PaneCapture {
    let trim_info = snapshot.metrics.map(|m| m.trim_bounds());
    let (content, cursor_line) = shell_popup::trim_content_to_cursor(snapshot.content, trim_info);
    (content, snapshot.metrics, cursor_line)
}

/// Capture a pane for the popup: over the input broker's control connection when
/// there is one, otherwise the two `tmux` processes this has always cost.
///
/// The broker is asked first because it already holds a live `tmux -C` client
/// for keystrokes, and reusing it avoids the process startup that dominated the
/// delay between typing into a task pane and seeing the character appear. It
/// also flushes buffered keystrokes ahead of the capture, so a frame can never
/// be missing text the user has already typed.
fn capture_pane_for_popup(
    window_name: &str,
    history_lines: i32,
    input_sink: &dyn PaneInputSink,
    tmux_ops: &dyn TmuxOperations,
) -> PaneCapture {
    match input_sink.capture(window_name, crate::tmux::CaptureSpec::popup(history_lines)) {
        Some(snapshot) => trim_pane_snapshot(snapshot),
        None => capture_tmux_pane_snapshot(window_name, history_lines, tmux_ops),
    }
}

/// Windows that currently exist, as a set of `session:window` targets, or `None`
/// when tmux could not be asked.
///
/// The `Option` is the whole point and must not be flattened to an empty set.
/// The per-task check this replaces failed *safe* —
/// `!window_exists(sn).unwrap_or(true)` leaves a task alone when the check
/// errors — whereas an empty set reads as "every window is gone" and would mark
/// every running task `Exited` on one transient tmux hiccup. That is a visible,
/// wrong status change on the whole board, so a failed listing must mean
/// "unknown", not "none".
fn live_window_targets(tmux_ops: &dyn TmuxOperations) -> Option<std::collections::HashSet<String>> {
    tmux_ops
        .list_window_targets()
        .ok()
        .map(|targets| targets.into_iter().collect())
}

/// Has this task's tmux window gone away?
///
/// Split out because its **failure direction** is the whole subtlety: `None` for
/// the listing means tmux could not be asked, and must read as "leave the task
/// alone", never as "every window is gone". Getting that backwards marks a whole
/// board `Exited` on one transient tmux hiccup.
fn window_is_gone(session: Option<&str>, live: Option<&std::collections::HashSet<String>>) -> bool {
    match (session, live) {
        (Some(sn), Some(live)) => !live.contains(sn),
        _ => false,
    }
}

/// Read a pane as **plain text**, over the input connection when there is one.
///
/// The status refresh's counterpart to [`capture_pane_for_popup`]: no escapes,
/// no scrollback, no geometry — byte-identical to
/// [`TmuxOperations::capture_pane`], which is what the dialog matcher and the
/// content hash have always been fed.
///
/// Worth routing because this is the last per-task subprocess left on the status
/// refresh's timer: the fallback is a `tmux` process *per task*, and it scales
/// with the size of the board.
fn capture_pane_text(
    target: &str,
    input_sink: &dyn PaneInputSink,
    tmux_ops: &dyn TmuxOperations,
) -> Option<String> {
    if let Some(snapshot) = input_sink.capture(target, crate::tmux::CaptureSpec::text()) {
        return Some(String::from_utf8_lossy(&snapshot.content).into_owned());
    }
    tmux_ops.capture_pane(target).ok()
}

/// Generate PR title and description using the configured agent
pub(crate) fn generate_pr_description(
    task_title: &str,
    worktree_path: Option<&str>,
    _branch_name: Option<&str>,
    git_ops: &dyn GitOperations,
    agent_ops: &dyn AgentOperations,
) -> (String, String) {
    // Default values
    let default_title = task_title.to_string();
    let mut default_body = String::new();

    // Try to get git diff for context
    if let Some(worktree) = worktree_path {
        let worktree_path = Path::new(worktree);
        // Get diff from main
        let diff_stat = git_ops.diff_stat_from_main(worktree_path);

        if !diff_stat.is_empty() {
            default_body.push_str("## Changes\n```\n");
            default_body.push_str(&diff_stat);
            default_body.push_str("```\n");
        }

        // Try to use the agent to generate a better description
        let prompt = format!(
            "Generate a concise PR description for these changes. Task: '{}'. Output only the description, no markdown code blocks around it. Keep it brief (2-3 sentences max).",
            task_title
        );

        if let Ok(generated) = agent_ops.generate_text(worktree_path, &prompt) {
            if !generated.is_empty() {
                default_body = format!("{}\n\n{}", generated, default_body);
            }
        }
    }

    (default_title, default_body)
}

/// Create a PR with provided title and body, return (pr_number, pr_url)
fn create_pr_with_content(
    task: &Task,
    project_path: &Path,
    pr_title: &str,
    pr_body: &str,
    git_ops: &dyn GitOperations,
    git_provider_ops: &dyn GitProviderOperations,
    agent_ops: &dyn AgentOperations,
) -> Result<(i32, String)> {
    let worktree = task.worktree_path.as_deref().unwrap_or(".");
    let worktree_path = Path::new(worktree);

    // Stage all changes
    git_ops.add_all(worktree_path)?;

    // Check if there are changes to commit
    let has_changes = git_ops.has_changes(worktree_path);

    // Commit if there are staged changes
    if has_changes {
        let commit_msg = format!(
            "{}\n\nCo-Authored-By: {}",
            pr_title,
            agent_ops.co_author_string()
        );
        git_ops.commit(worktree_path, &commit_msg)?;
    }

    // Push the branch
    if let Some(branch) = &task.branch_name {
        git_ops.push(worktree_path, branch, true)?;
    }

    // Create PR (use base_branch for stacked PRs)
    git_provider_ops.create_pr(
        project_path,
        pr_title,
        pr_body,
        task.branch_name.as_deref().unwrap_or(""),
        task.base_branch.clone(),
    )
}

/// Push changes to an existing PR (commit and push only, no PR creation)
fn push_changes_to_existing_pr(
    task: &Task,
    git_ops: &dyn GitOperations,
    agent_ops: &dyn AgentOperations,
) -> Result<String> {
    let worktree = task.worktree_path.as_deref().unwrap_or(".");
    let worktree_path = Path::new(worktree);

    // Stage all changes
    git_ops.add_all(worktree_path)?;

    // Check if there are changes to commit
    let has_changes = git_ops.has_changes(worktree_path);

    // Commit if there are staged changes
    if has_changes {
        let commit_msg = format!(
            "Address review comments\n\nCo-Authored-By: {}",
            agent_ops.co_author_string()
        );
        git_ops.commit(worktree_path, &commit_msg)?;
    }

    // Push the branch
    if let Some(branch) = &task.branch_name {
        git_ops.push(worktree_path, branch, false)?;
    }

    // Return the existing PR URL
    Ok(task
        .pr_url
        .clone()
        .unwrap_or_else(|| "Changes pushed to existing PR".to_string()))
}

/// Translate a popup keystroke into a request for the pane input broker.
///
/// The split between [`PaneInput::Text`] and [`PaneInput::Key`] is the whole
/// point of the type: text goes out with `send-keys -l`, which suppresses tmux's
/// key-name lookup, and a key goes out without it, which is what makes `Enter`
/// an Enter.
///
/// An unmodified character is therefore **text**, not a key: `send-keys -t x
/// ";"` never reaches the pane, because a standalone semicolon is how tmux
/// separates commands and it is parsed as one. The same lookup is why a batched
/// run of characters cannot be sent as a key.
fn popup_key_input(target: &str, key: crossterm::event::KeyEvent) -> Option<PaneInput> {
    use crossterm::event::KeyModifiers;
    let has_alt = key.modifiers.contains(KeyModifiers::ALT);
    let has_ctrl = key.modifiers.contains(KeyModifiers::CONTROL);

    // Shift is already reflected in the character crossterm reports, so it is
    // not a modifier prefix here — `C-A` and `C-a` are different keys to tmux,
    // but `A` alone is just the character.
    if let KeyCode::Char(c) = key.code {
        if !has_ctrl && !has_alt {
            return Some(PaneInput::Text {
                target: target.to_string(),
                text: c.to_string(),
            });
        }
    }

    let base = match key.code {
        KeyCode::Char(c) => c.to_string(),
        KeyCode::Enter => "Enter".to_string(),
        KeyCode::Esc => "Escape".to_string(),
        KeyCode::Backspace => "BSpace".to_string(),
        KeyCode::Tab => "Tab".to_string(),
        KeyCode::Up => "Up".to_string(),
        KeyCode::Down => "Down".to_string(),
        KeyCode::Left => "Left".to_string(),
        KeyCode::Right => "Right".to_string(),
        KeyCode::Home => "Home".to_string(),
        KeyCode::End => "End".to_string(),
        KeyCode::PageUp => "PageUp".to_string(),
        KeyCode::PageDown => "PageDown".to_string(),
        KeyCode::Delete => "DC".to_string(),
        KeyCode::Insert => "IC".to_string(),
        KeyCode::F(n) => format!("F{}", n),
        _ => return None,
    };

    let key_str = match (has_ctrl, has_alt) {
        (true, true) => format!("C-M-{}", base),
        (true, false) => format!("C-{}", base),
        (false, true) => format!("M-{}", base),
        (false, false) => base,
    };

    Some(PaneInput::Key {
        target: target.to_string(),
        key: key_str,
    })
}

/// Hand one request to the broker, surfacing the two ways that can fail.
///
/// Takes the sink and the warning slot rather than `&mut App` on purpose: it is
/// called with the popup mutably borrowed, and these are disjoint fields.
///
/// A full queue is **not** retried synchronously. Sending it now would put this
/// key ahead of everything already queued, and a keystroke arriving out of order
/// is worse than one that visibly did not arrive — so the queued prefix is kept
/// and the user is told.
fn forward_pane_input(
    sink: &dyn PaneInputSink,
    warning: &mut Option<(String, Instant)>,
    input: PaneInput,
) {
    match sink.send(input) {
        Ok(()) => {}
        Err(InputError::QueueFull) => {
            tracing::warn!("pane input queue full; keystroke dropped");
            *warning = Some((
                "Input is backing up; a keystroke was dropped rather than sent out of order."
                    .to_string(),
                Instant::now(),
            ));
        }
        Err(InputError::Disconnected) => {
            tracing::error!("pane input broker stopped");
            *warning = Some((
                "Pane input is not running; restart agtx to type into task panes.".to_string(),
                Instant::now(),
            ));
        }
        // `send` is an enqueue and cannot time out. The arm exists because the
        // variant shares an error type with `flush_sync`, which can.
        Err(InputError::Timeout) => {
            tracing::debug!("pane input enqueue reported a timeout");
        }
    }
}

/// Deliver everything queued and wait for tmux to have executed it.
///
/// Used before agtx does a synchronous tmux operation of its own on this thread:
/// that travels a different socket, so without the wait it can overtake keys the
/// user typed a moment earlier. The wait is bounded — see `FLUSH_SYNC_TIMEOUT` —
/// and reaching the bound means the ordering was not achieved, which is worth a
/// word to the user rather than a silent shrug.
fn flush_pane_input_sync(sink: &dyn PaneInputSink, warning: &mut Option<(String, Instant)>) {
    match sink.flush_sync() {
        Ok(()) => {}
        Err(InputError::Timeout) => {
            tracing::warn!("pane input did not drain before a synchronous tmux operation");
            *warning = Some((
                "tmux is slow to accept input — your last keystrokes may arrive late.".to_string(),
                Instant::now(),
            ));
        }
        Err(e) => tracing::debug!(error = %e, "acknowledged flush failed"),
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum PopupScroll {
    Up(i32),
    Down(i32),
    Bottom,
}

/// The scroll chords, in one place.
///
/// Every scrollable surface in agtx reads them from here — the task pane and
/// the `?` overlay — so a user who learns `C-d` once does not find it inert
/// somewhere else, and the two cannot drift apart.
fn scroll_action_for(key: crossterm::event::KeyEvent) -> Option<PopupScroll> {
    let ctrl = key
        .modifiers
        .contains(crossterm::event::KeyModifiers::CONTROL);
    match key.code {
        KeyCode::Char('p') | KeyCode::Up if ctrl => Some(PopupScroll::Up(5)),
        KeyCode::Char('n') | KeyCode::Down if ctrl => Some(PopupScroll::Down(5)),
        KeyCode::Char('u') if ctrl => Some(PopupScroll::Up(20)),
        KeyCode::PageUp => Some(PopupScroll::Up(20)),
        KeyCode::Char('d') if ctrl => Some(PopupScroll::Down(20)),
        KeyCode::PageDown => Some(PopupScroll::Down(20)),
        KeyCode::Char('g') if ctrl => Some(PopupScroll::Bottom),
        _ => None,
    }
}

/// Apply one logical popup scroll action to whichever component owns history.
///
/// A pane in the alternate screen keeps no tmux scrollback (`history_size == 0`),
/// so the session's history is the agent's, not ours. Rather than move a
/// one-screen buffer by zero lines and print a line number to match, agtx sends
/// the agent a key that scrolls *its* view.
///
/// **Never `Up`/`Down`.** Measured against Claude
/// Code 2.1.251: in its detailed transcript view (`ctrl+o`) all four scroll, but
/// in the main view `Up` recalls a previous prompt **into the composer** —
/// overwriting whatever the user had typed — while `PageUp` is inert. A scroll
/// key that silently rewrites the user's half-typed message is worse than one
/// that does nothing, so `C-n/p` use the safe Page Down/Up translation.
///
/// The chord is **translated, never passed through**, for the same reason:
/// forwarding a raw `C-d` would be an EOF that can end the session, and `C-u`
/// would kill the line in the composer.
fn handle_popup_scroll(
    popup: &mut ShellPopup,
    sink: &dyn PaneInputSink,
    warning: &mut Option<(String, Instant)>,
    target: &str,
    action: PopupScroll,
) {
    if popup.has_scrollback() {
        match action {
            PopupScroll::Up(lines) => popup.scroll_up(lines),
            PopupScroll::Down(lines) => popup.scroll_down(lines),
            PopupScroll::Bottom => popup.scroll_to_bottom(),
        }
        return;
    }

    let key = match action {
        PopupScroll::Up(_) => "PageUp",
        PopupScroll::Down(_) => "PageDown",
        PopupScroll::Bottom => "End",
    };
    forward_pane_input(
        sink,
        warning,
        PaneInput::Key {
            target: target.to_string(),
            key: key.to_string(),
        },
    );
}

/// Address a window the way every tmux command in agtx should: `session:window`.
///
/// A **bare** window name is resolved inside whichever session the issuing
/// client is bound to — the attached session for a control client, the
/// most-recently-used one for a subprocess. Neither is reliably this project's
/// after a project switch, and `orchestrator` is a window name every project
/// session has, so a bare target could deliver a keystroke to the wrong
/// project's agent. Qualifying makes the target absolute.
fn pane_target(session: &str, window: &str) -> String {
    if window.contains(':') {
        // Already qualified — the orchestrator builds its target this way.
        return window.to_string();
    }
    format!("{session}:{window}")
}

/// Is the persistent control-mode backend on for this run?
///
/// On unless `AGTX_TMUX_CONTROL` says otherwise. There is no config field: a
/// failed or lost connection already falls back to the subprocess backend on its
/// own, so the only thing a persisted setting could add is a second, staler copy
/// of that decision. The variable stays as a one-run escape hatch, so a bug
/// report can be bisected across the two lanes without editing anything.
fn control_mode_enabled() -> bool {
    control_mode_from_env(std::env::var("AGTX_TMUX_CONTROL").ok().as_deref())
}

/// The policy half, split from the read so it can be tested without touching
/// the process environment. `setenv` is not thread-safe against a concurrent
/// `getenv`, and `cargo test` runs hundreds of tests in parallel threads — a
/// test that mutates a global to check a `match` is a race for no reason.
fn control_mode_from_env(value: Option<&str>) -> bool {
    !matches!(value, Some("0") | Some("false") | Some("no"))
}

/// How fresh the popup's view of its pane is while the **user is typing**.
///
/// It means two different things depending on how the watcher is being driven:
/// under push it is a *rate limit* — the ceiling on how often a paint may cause
/// a capture — and on the poll fallback it is the sampling period itself.
///
/// Either way it is the term a keystroke's echo latency is made of, which is
/// only true because a capture over the control connection is cheap where two
/// `tmux` processes were not. Its cost is paid on the far side — a capture makes
/// the tmux server format the whole pane — so this is not free to lower. [`PANE_OUTPUT_MIN_INTERVAL`] is the same ceiling for the agent's own
/// output, where nobody is waiting on a single frame.
const SHELL_REFRESH_INTERVAL: std::time::Duration = std::time::Duration::from_millis(10);

/// Scrollback lines a popup capture asks for **when the user has scrolled up**.
///
/// A pane in the alternate screen — where full-screen agent UIs live — has none,
/// and returns just the visible rows regardless of this.
const SHELL_POPUP_CAPTURE_LINES: i32 = 500;

/// Scrollback lines to ask for while the popup sits **at the bottom**.
///
/// Only the visible rows are rendered there, so the rest is fetched, formatted
/// by the tmux server, compared and parsed for nothing. Not zero, because the
/// first `C-u` needs somewhere to scroll to: 100 lines is ~3 pages, and by the
/// time the user scrolls past that the deeper capture has arrived.
///
/// Worth nothing for the agents that matter today — they take the alternate
/// screen, where `history_size` is 0 and every depth returns the same bytes. It
/// is for a pane that *does* accumulate history, where the deeper capture is
/// many times the size of the screen being rendered.
const SHELL_POPUP_TAIL_LINES: i32 = 100;

/// How deep the watcher should capture, given where the popup is scrolled.
fn popup_capture_depth(scroll_offset: i32) -> i32 {
    if scroll_offset < 0 {
        SHELL_POPUP_CAPTURE_LINES
    } else {
        SHELL_POPUP_TAIL_LINES
    }
}

/// What the **poll fallback** slows to once a pane has stopped changing.
///
/// Only reached when push is unavailable ([`attach_pane_push`]); with an output
/// watch attached, a still pane produces no captures at all and this never
/// applies. Once a pane has been unchanged for [`PANE_IDLE_ROUNDS`] nobody is
/// waiting on a millisecond, and this much staleness is invisible. A keystroke
/// pokes the watcher back
/// to [`SHELL_REFRESH_INTERVAL`] before the character is even delivered, so the
/// first character after a pause is as prompt as the tenth.
const PANE_IDLE_INTERVAL: std::time::Duration = std::time::Duration::from_millis(50);

/// How long the watcher waits for a paint that never comes.
///
/// Under push this replaces the poll interval entirely, so it is a **safety
/// net**, not a cadence: `%output` says bytes reached the pty, not that the
/// rendered pane differs, and the converse happens too — a repaint with no new
/// bytes still changes what `capture-pane` returns. A missed signal is otherwise
/// invisible, because the popup simply stops updating. Same reasoning as
/// [`REDRAW_BACKSTOP`], and if it is ever what makes the popup look right,
/// something above it is wrong.
const PANE_PUSH_BACKSTOP: std::time::Duration = std::time::Duration::from_millis(500);

/// Slowest a capture may be driven by the **agent painting**, as opposed to by
/// the user typing.
///
/// The two deserve different answers. Nobody reads text scrolling past frame by
/// frame, but everybody notices their own keystroke arriving late — so the
/// agent's output is sampled at a readable rate while typing keeps
/// [`SHELL_REFRESH_INTERVAL`].
///
/// Not a micro-optimisation: one shared ceiling makes a pane painting flat out
/// cost more than polling would. Every frame is a `capture-pane`, and a capture
/// makes the tmux server format the whole pane.
const PANE_OUTPUT_MIN_INTERVAL: std::time::Duration = std::time::Duration::from_millis(50);

/// How long after a keystroke captures stay on the fast cadence.
///
/// A keystroke's echo does not arrive with the keystroke: the key reaches the
/// pane almost immediately, the agent repaints a little later, and *that* is
/// what the watcher sees — as a paint, indistinguishable from the agent's own
/// output.
/// Rate-limiting paints to [`PANE_OUTPUT_MIN_INTERVAL`] without this window would
/// therefore delay the echo of every character by that much, which is the one
/// thing this whole lane exists to avoid.
const PANE_TYPING_WINDOW: std::time::Duration = std::time::Duration::from_millis(250);

/// How long to wait before trying to attach an output watch again.
///
/// Attaching costs two `tmux` processes (the pane id, then the client), and the
/// attempt sits in a loop that runs every [`SHELL_REFRESH_INTERVAL`]. A popup
/// left open on a window that has since closed would otherwise spawn a hundred
/// processes a second — the exact cost this whole change removes, reintroduced
/// through the failure path.
const PANE_PUSH_RETRY: std::time::Duration = std::time::Duration::from_secs(2);

/// Unchanged captures before the poll fallback backs off.
///
/// Counted in rounds, so the wall-clock settling time is this times
/// [`SHELL_REFRESH_INTERVAL`] — change one and the other moves with it. It only
/// has to outlast the gap between two keystrokes.
const PANE_IDLE_ROUNDS: u32 = 40;

/// How often periodic work runs: the MCP transition queue, the session refresh,
/// the spinner, expiring warnings.
///
/// What matters is that it is *decoupled* from input, so none of it speeds up
/// because the user is typing. Anything wanting a slower rate keeps its own
/// interval — see [`TRANSITION_POLL_INTERVAL`].
const HOUSEKEEPING_TICK: std::time::Duration = std::time::Duration::from_millis(100);

/// How long the screen may go unpainted while nothing reports a change.
const REDRAW_BACKSTOP: std::time::Duration = std::time::Duration::from_secs(1);

/// How often the MCP transition queue is read.
///
/// A SQLite query, so it does not belong on the housekeeping tick — ten times a
/// second, forever, whether or not anything is connected. A queued transition is
/// not latency-critical: it is a request to move a task between columns, and the
/// phase status it acts on is itself refreshed on a 2-second cache.
const TRANSITION_POLL_INTERVAL: std::time::Duration = std::time::Duration::from_secs(2);

/// How long a claimed-but-unfinished transition request must sit before another
/// instance may take it over.
///
/// The window has to clear the longest legitimate wait for the serialized setup
/// slot — a queued task waits out every setup ahead of it — while still
/// recovering promptly from a TUI that died holding a queue. Five minutes is
/// well past a normal setup and well inside the hour after which
/// `cleanup_old_transition_requests` deletes the row unexecuted.
const RECLAIM_CLAIMS_AFTER: chrono::Duration = chrono::Duration::minutes(5);

/// Where the last review's end point is recorded, inside a task's `.agtx/`.
/// Read by the review skill; see [`mark_reviewed_point`].
const REVIEWED_AT_FILE: &str = "reviewed-at";

/// How long a phase status is trusted before the refresh looks again.
const PHASE_STATUS_CACHE_TTL: std::time::Duration = std::time::Duration::from_secs(2);

/// How long a warning banner stays up.
const WARNING_MESSAGE_TTL: std::time::Duration = std::time::Duration::from_secs(5);

/// Why the event loop woke up.
///
/// Terminal input and pane content arrive on separate threads and are merged
/// into one channel, so the loop can block on both at once instead of polling
/// each on a timer.
enum Wake {
    Input(Event),
    Pane {
        window: String,
        content: Vec<u8>,
        /// Parsed on the watcher thread — see `ShellPopup::cached_lines`.
        lines: Vec<Line<'static>>,
        metrics: Option<crate::tmux::PaneMetrics>,
        /// Where the cursor is in `content` — see `ShellPopup::cursor_line`.
        cursor_line: Option<usize>,
    },
}

/// Which pane the watcher should be capturing, if any.
///
/// A condvar rather than a channel because the watcher spends most of its life
/// waiting on exactly one of two things — a target to appear, or its next
/// capture — and both are this same wait. With no popup open it blocks
/// indefinitely and costs nothing.
#[derive(Default)]
struct PaneWatch {
    inner: Mutex<PaneWatchState>,
    cv: Condvar,
}

#[derive(Default)]
struct PaneWatchState {
    target: Option<String>,
    /// tmux pane id of `target` (`%7`), matched against `%output` notifications.
    /// `None` means push is unavailable for this pane and the timer runs.
    pane_id: Option<String>,
    /// Scrollback depth to capture — see [`popup_capture_depth`].
    history_lines: i32,
    /// Bumped to make the watcher capture now, at the fast cadence.
    poke: u64,
    /// Bumped by the output watch every time *this* pane paints.
    signal: u64,
    stopped: bool,
}

impl PaneWatch {
    /// Point the watcher at `target` (or nothing). Cheap enough to call every
    /// iteration, which is the point: no popup call site has to remember to.
    fn follow(&self, target: Option<&str>, history_lines: i32) {
        let Ok(mut state) = self.inner.lock() else {
            return;
        };
        if state.target.as_deref() == target {
            if state.history_lines != history_lines {
                // The user scrolled: re-capture at the new depth now, rather
                // than leaving them looking at a buffer with nothing above it.
                state.history_lines = history_lines;
                state.poke = state.poke.wrapping_add(1);
                drop(state);
                self.cv.notify_all();
            }
            return;
        }
        state.history_lines = history_lines;
        state.target = target.map(str::to_string);
        // The id belongs to the old pane; the watcher resolves the new one.
        state.pane_id = None;
        state.poke = state.poke.wrapping_add(1);
        drop(state);
        self.cv.notify_all();
    }

    /// Record that `pane_id` painted. Called from the output-watch reader
    /// thread, for **every** pane in the session, so it filters before waking.
    fn mark_output(&self, pane_id: &str) {
        let Ok(mut state) = self.inner.lock() else {
            return;
        };
        if state.pane_id.as_deref() != Some(pane_id) {
            return;
        }
        state.signal = state.signal.wrapping_add(1);
        drop(state);
        self.cv.notify_all();
    }

    /// Wait for a poke, a paint, a target change or `wait` to elapse, and report
    /// whether a **poke** was what ended it. `None` means stop.
    ///
    /// A method, not an inline block, because the lock must not outlive the
    /// wait: the watcher takes it again immediately afterwards for the rate
    /// limit, and `Mutex` is not reentrant. Inline, the arm that does not hand
    /// its guard to `wait_timeout` kept the guard alive for the rest of the
    /// iteration and the watcher deadlocked against itself — holding the very
    /// lock the UI thread calls [`follow`](Self::follow) on every iteration, so
    /// the whole TUI froze. Here the guard cannot escape the call.
    fn wait_for_change(
        &self,
        poke: u64,
        signal: u64,
        wait: std::time::Duration,
    ) -> Option<WaitOutcome> {
        let Ok(state) = self.inner.lock() else {
            return None;
        };
        if state.stopped {
            return None;
        }
        if state.poke != poke || state.signal != signal {
            // Something landed while the capture was in flight; no reason to wait.
            return Some(WaitOutcome {
                poked: state.poke != poke,
                skipped: true,
            });
        }
        let Ok((state, _)) = self.cv.wait_timeout(state, wait) else {
            return None;
        };
        if state.stopped {
            return None;
        }
        Some(WaitOutcome {
            poked: state.poke != poke,
            skipped: false,
        })
    }

    /// Hold off for `wait`, unless a poke arrives first. `None` means stop.
    ///
    /// Same reasoning as [`wait_for_change`](Self::wait_for_change): the guard
    /// stays inside the call. A plain sleep would be simpler and wrong — it would
    /// hold the ceiling meant for the agent's paints against the user's own echo.
    ///
    /// **It has to resume the wait**, which a single `wait_timeout` does not: the
    /// condvar is shared with [`mark_output`](Self::mark_output), so a paint
    /// notifies it, and returning there releases the ceiling to the very thing
    /// it is a ceiling *on*. A pane painting flat out then drives one capture per
    /// notification — exactly what [`PANE_OUTPUT_MIN_INTERVAL`] exists to stop —
    /// and no wait longer than the gap between two paints is ever served.
    fn wait_out_rate_limit(&self, wait: std::time::Duration) -> Option<bool> {
        let deadline = Instant::now() + wait;
        let Ok(mut state) = self.inner.lock() else {
            return None;
        };
        let before = state.poke;
        loop {
            if state.stopped {
                return None;
            }
            if state.poke != before {
                return Some(true);
            }
            // `None` once the deadline is behind us: the ceiling has been served.
            let Some(remaining) = deadline.checked_duration_since(Instant::now()) else {
                return Some(false);
            };
            let Ok((next, _)) = self.cv.wait_timeout(state, remaining) else {
                return None;
            };
            state = next;
        }
    }

    fn set_pane_id(&self, pane_id: Option<String>) {
        if let Ok(mut state) = self.inner.lock() {
            state.pane_id = pane_id;
        }
    }

    /// Capture now and go back to the fast cadence: the user just typed.
    fn poke(&self) {
        if let Ok(mut state) = self.inner.lock() {
            state.poke = state.poke.wrapping_add(1);
        }
        self.cv.notify_all();
    }

    fn stop(&self) {
        if let Ok(mut state) = self.inner.lock() {
            state.stopped = true;
        }
        self.cv.notify_all();
    }

    fn target(&self) -> Option<String> {
        self.inner.lock().ok().and_then(|s| s.target.clone())
    }

    /// Pokes issued so far. The watcher compares it across its wait to notice a
    /// poke that arrived *while* it was capturing; tests read it to assert that
    /// following the same target twice is not one.
    fn poke_count(&self) -> u64 {
        self.inner.lock().map(|s| s.poke).unwrap_or(0)
    }

    /// Paint signals accepted so far. Tests read it to assert the filtering.
    #[cfg(test)]
    fn signal_count(&self) -> u64 {
        self.inner.lock().map(|s| s.signal).unwrap_or(0)
    }
}

/// How a [`PaneWatch::wait_for_change`] ended.
struct WaitOutcome {
    /// The user typed. Puts the watcher back on the fast cadence.
    poked: bool,
    /// There was no wait at all: a poke or a paint had already landed while the
    /// capture was in flight, so the pane is known to be moving.
    skipped: bool,
}

/// Is this capture different from the last one the watcher sent?
///
/// Geometry counts as much as content: a cursor that moved without the text
/// changing still has to be repainted, and a capture whose target has changed is
/// not this pane's content at all.
fn pane_capture_changed(
    last: &Option<(String, Vec<u8>, Option<crate::tmux::PaneMetrics>)>,
    target: &str,
    content: &[u8],
    metrics: &Option<crate::tmux::PaneMetrics>,
) -> bool {
    match last {
        Some((window, seen, seen_metrics)) => {
            window != target || seen != content || seen_metrics != metrics
        }
        None => true,
    }
}

/// Still rounds to carry into the next wait.
///
/// A poke resets the count, and that is not bookkeeping — it is the half of the
/// back-off that makes it safe. The capture a poke triggers runs *before* the
/// keystroke that caused it has reached the pane and been echoed, so it sees
/// nothing new; without the reset the watcher would then wait out another idle
/// interval and the character would appear a whole one late.
fn pane_watch_rounds_after_wait(unchanged_rounds: u32, poked: bool) -> u32 {
    if poked {
        0
    } else {
        unchanged_rounds
    }
}

/// How long to wait before the next capture, given how long the pane has been
/// still. See [`PANE_IDLE_INTERVAL`] for why this has two speeds.
fn pane_watch_interval(unchanged_rounds: u32) -> std::time::Duration {
    if unchanged_rounds >= PANE_IDLE_ROUNDS {
        PANE_IDLE_INTERVAL
    } else {
        SHELL_REFRESH_INTERVAL
    }
}

/// Read terminal events on their own thread.
///
/// `event::read()` blocks, which is exactly what is wanted now: the loop learns
/// about a keystroke when there is one instead of asking every few milliseconds.
fn spawn_terminal_reader(tx: mpsc::Sender<Wake>) {
    let _ = std::thread::Builder::new()
        .name("agtx-terminal-input".to_string())
        .spawn(move || loop {
            match crossterm::event::read() {
                Ok(event) => {
                    if tx.send(Wake::Input(event)).is_err() {
                        break;
                    }
                }
                // The terminal is gone; the loop's channel will disconnect and
                // it will quit on its own.
                Err(e) => {
                    tracing::debug!(error = %e, "terminal input reader stopped");
                    break;
                }
            }
        });
}

/// Capture the open popup's pane, and wake the loop **only when it changed**.
///
/// Comparing here rather than in the loop is what makes an idle popup free: an
/// agent that is painting nothing produces no wake-ups at all, so no frame is
/// drawn and no capture is re-parsed.
///
/// **How it learns the pane painted** has two modes, and the second is not a
/// degraded copy of the first — it is the whole design when control mode is off:
///
/// - **push**, when an [`OutputWatch`](crate::tmux::OutputWatch) is attached:
///   the thread sleeps until tmux says *this* pane produced output. Typing at
///   human speed changes the pane 5–8 times a second where the timer sampled it
///   100 times, so most of those captures found nothing new; push removes
///   exactly that waste.
/// - **poll**, otherwise: the historical timer, fast while the pane changes and
///   backing off once it settles.
///
/// Under push, `SHELL_REFRESH_INTERVAL` stops being a poll period and becomes a
/// **rate limit**. The signal removes the floor — no capture when nothing
/// happened — while the interval keeps the ceiling, because a pane painting flat
/// out notifies far faster than it is worth capturing.
fn spawn_pane_watcher(
    watch: Arc<PaneWatch>,
    tx: mpsc::Sender<Wake>,
    input_sink: Arc<dyn PaneInputSink>,
    tmux_ops: Arc<dyn TmuxOperations>,
) {
    let _ = std::thread::Builder::new()
        .name("agtx-pane-watch".to_string())
        .spawn(move || {
            let mut last: Option<(String, Vec<u8>, Option<crate::tmux::PaneMetrics>)> = None;
            let mut unchanged: u32 = 0;
            let mut push: Option<PanePush> = None;
            let mut push_retry_at: Option<Instant> = None;
            let mut watched_target = String::new();
            // When the user last typed, which decides how fast paints are
            // sampled — see `PANE_TYPING_WINDOW`.
            let mut last_keystroke: Option<Instant> = None;
            loop {
                // With no popup open, release the output watch so tmux mirrors
                // nothing for a session nobody is looking at.
                //
                // Outside the lock, never under it: dropping the watch closes a
                // tmux client and reaps the child, and the UI thread calls
                // `follow()` on this same mutex every iteration — so holding it
                // here stalls the whole TUI until that client exits.
                if watch
                    .inner
                    .lock()
                    .map(|state| state.target.is_none())
                    .unwrap_or(true)
                {
                    push = None;
                }
                // Then wait for something to watch. No popup open is the common
                // case, and costs one blocked thread and nothing else.
                let (target, poke, signal, history_lines) = {
                    let Ok(mut state) = watch.inner.lock() else {
                        return;
                    };
                    while state.target.is_none() && !state.stopped {
                        let Ok(next) = watch.cv.wait(state) else {
                            return;
                        };
                        state = next;
                    }
                    if state.stopped {
                        return;
                    }
                    (
                        state.target.clone(),
                        state.poke,
                        state.signal,
                        state.history_lines,
                    )
                };
                let Some(target) = target else { continue };

                if target != watched_target {
                    // A new pane deserves an immediate attempt rather than
                    // whatever backoff the previous one had accumulated.
                    push_retry_at = None;
                    watched_target = target.clone();
                }
                push =
                    attach_pane_push(push, &target, &watch, tmux_ops.as_ref(), &mut push_retry_at);

                let captured_at = Instant::now();
                let (content, metrics, cursor_line) = capture_pane_for_popup(
                    &target,
                    history_lines,
                    input_sink.as_ref(),
                    tmux_ops.as_ref(),
                );
                if pane_capture_changed(&last, &target, &content, &metrics) {
                    unchanged = 0;
                    last = Some((target.clone(), content.clone(), metrics));
                    // Parsed here, off the thread that handles keystrokes, and
                    // once per *change* rather than once per frame.
                    let lines = parse_ansi_to_lines(&content);
                    if tx
                        .send(Wake::Pane {
                            window: target,
                            content,
                            lines,
                            metrics,
                            cursor_line,
                        })
                        .is_err()
                    {
                        return;
                    }
                } else {
                    unchanged = unchanged.saturating_add(1);
                }

                let pushing = push.is_some();
                // Under push there is nothing to poll for: the next capture is
                // caused by the pane painting, and this is only the net for a
                // signal that never came.
                let wait = if pushing {
                    PANE_PUSH_BACKSTOP
                } else {
                    pane_watch_interval(unchanged)
                };
                // A poke, a paint, or a target change ends the wait early, so
                // backing off never costs the first keystroke after a pause.
                //
                // A poke also puts the watcher back on the fast cadence, and
                // that half is not optional: the capture a poke triggers runs
                // *before* the key it announced has reached the pane and been
                // echoed, so it sees no change. Without the reset the next wait
                // would be the slow one again and the echo would arrive a whole
                // idle interval late — the back-off charging exactly what it
                // was built not to.
                let Some(outcome) = watch.wait_for_change(poke, signal, wait) else {
                    return;
                };
                if outcome.skipped {
                    // The pane is moving; do not let a back-off accumulate.
                    unchanged = 0;
                }
                let poked = outcome.poked;
                if poked {
                    last_keystroke = Some(Instant::now());
                }
                unchanged = pane_watch_rounds_after_wait(unchanged, poked);

                // The rate limit, under push only — polling already paces itself.
                //
                // Waited on the condvar rather than slept, so a keystroke still
                // gets through: a plain sleep here would hold the ceiling meant
                // for the *agent's* paints against the user's own echo, adding up
                // to `PANE_OUTPUT_MIN_INTERVAL` to the first character typed
                // after a pause.
                if let Some(remaining) = push_rate_limit_wait(
                    pushing,
                    captured_at.elapsed(),
                    last_keystroke.map(|at| at.elapsed()),
                ) {
                    let Some(poked_during_limit) = watch.wait_out_rate_limit(remaining) else {
                        return;
                    };
                    if poked_during_limit {
                        last_keystroke = Some(Instant::now());
                    }
                }
            }
        });
}

/// How long to hold off the next capture, given how long ago the last one
/// started. `None` means capture now.
///
/// Only meaningful under push: it turns `SHELL_REFRESH_INTERVAL` from "how often
/// to look" into "no more often than this", which is what stops a pane painting
/// flat out from driving one capture per notification.
fn push_rate_limit_wait(
    pushing: bool,
    since_last_capture: std::time::Duration,
    since_last_keystroke: Option<std::time::Duration>,
) -> Option<std::time::Duration> {
    if !pushing {
        return None;
    }
    let floor = match since_last_keystroke {
        // The user is typing: their own echo is what is being waited on.
        Some(since) if since < PANE_TYPING_WINDOW => SHELL_REFRESH_INTERVAL,
        // Nobody is waiting on a single frame of the agent's output.
        _ => PANE_OUTPUT_MIN_INTERVAL,
    };
    if since_last_capture >= floor {
        return None;
    }
    Some(floor - since_last_capture)
}

/// The output-watch connection for the pane currently being followed.
struct PanePush {
    /// Session the watch is attached to. `%output` never crosses sessions, so a
    /// popup in another session needs a different client.
    session: String,
    watch: crate::tmux::OutputWatch,
}

/// Keep the output watch pointed at `target`'s session, reconnecting when the
/// popup moves and giving up — to the timer — when tmux will not cooperate.
///
/// `None` is a supported state, not a failure: `AGTX_TMUX_CONTROL=0`, a tmux
/// that refuses the attach, and a pane whose id cannot be read all land here and
/// get the poll path instead.
fn attach_pane_push(
    current: Option<PanePush>,
    target: &str,
    watch: &Arc<PaneWatch>,
    tmux_ops: &dyn TmuxOperations,
    retry_at: &mut Option<Instant>,
) -> Option<PanePush> {
    if !control_mode_enabled() || !output_push_enabled() {
        return None;
    }
    let session = pane_push_session(target);
    if let Some(push) = current {
        if push.session == session && push.watch.alive() {
            return Some(push);
        }
        // Dropping it closes the client, so nothing stays mirrored for a session
        // nobody is looking at.
        // Also outside any lock, for the same reason: this runs on the watcher
        // thread with nothing held, and closing the client can take a moment.
        drop(push);
        // A watch that died is retried like a first attempt, not immediately.
        *retry_at = Some(Instant::now() + PANE_PUSH_RETRY);
        return None;
    }
    // Both steps below spawn a `tmux` process, and this runs once per watcher
    // iteration. Without a backoff, a popup left open on a window that has since
    // closed would spawn them continuously — far worse than the polling this
    // replaces.
    if let Some(at) = retry_at {
        if Instant::now() < *at {
            return None;
        }
    }
    *retry_at = Some(Instant::now() + PANE_PUSH_RETRY);
    // The id is what every `%output` line is matched against; without it the
    // watch could only say "some pane in this session painted", which is not a
    // signal — it would fire on every other task's output.
    let pane_id = tmux_ops.pane_id(target)?;
    watch.set_pane_id(Some(pane_id));

    let signal_watch = Arc::clone(watch);
    match crate::tmux::OutputWatch::connect(crate::tmux::AGENT_SERVER, &session, move |id| {
        signal_watch.mark_output(id);
    }) {
        Ok(client) => {
            tracing::debug!(session, "pane output watch attached");
            *retry_at = None;
            Some(PanePush {
                session,
                watch: client,
            })
        }
        Err(e) => {
            tracing::debug!(error = %e, "pane output watch unavailable; polling instead");
            watch.set_pane_id(None);
            None
        }
    }
}

/// Is `%output` push on for this run?
///
/// On unless `AGTX_TMUX_PUSH` says otherwise, and there is no config field for
/// the same reason [`control_mode_enabled`] has none: an attach that fails falls
/// back to polling on its own, so a persisted setting could only hold a staler
/// copy of a decision made at runtime. The escape hatch exists because a bug
/// report needs to bisect the two capture lanes — push against poll — the way
/// `AGTX_TMUX_CONTROL` bisects the two input lanes.
fn output_push_enabled() -> bool {
    control_mode_from_env(std::env::var("AGTX_TMUX_PUSH").ok().as_deref())
}

/// The session half of a `session:window` target — the only thing `%output` is
/// scoped to, so it is what decides whether an existing watch can be reused.
fn pane_push_session(target: &str) -> String {
    target
        .split_once(':')
        .map(|(session, _)| session)
        .unwrap_or(target)
        .to_string()
}

/// Parse ANSI escape sequences to ratatui Lines with colors
fn parse_ansi_to_lines(bytes: &[u8]) -> Vec<Line<'static>> {
    let text = String::from_utf8_lossy(bytes);
    let mut lines: Vec<Line<'static>> = Vec::new();
    let mut current_style = Style::default();

    for line_str in text.lines() {
        let mut spans: Vec<Span<'static>> = Vec::new();
        let mut current_text = String::new();
        let mut chars = line_str.chars().peekable();

        while let Some(c) = chars.next() {
            if c == '\x1b' {
                // Start of escape sequence
                if !current_text.is_empty() {
                    spans.push(Span::styled(current_text.clone(), current_style));
                    current_text.clear();
                }

                // Parse escape sequence
                if chars.peek() == Some(&'[') {
                    chars.next(); // consume '['
                    let mut seq = String::new();
                    while let Some(&ch) = chars.peek() {
                        if ch.is_ascii_digit() || ch == ';' {
                            seq.push(chars.next().unwrap());
                        } else {
                            break;
                        }
                    }
                    // Get the final character
                    if let Some(final_char) = chars.next() {
                        if final_char == 'm' {
                            // SGR sequence - parse color codes
                            current_style = parse_sgr(&seq, current_style);
                        }
                    }
                }
            } else {
                current_text.push(c);
            }
        }

        if !current_text.is_empty() {
            spans.push(Span::styled(current_text, current_style));
        }

        if spans.is_empty() {
            lines.push(Line::from(""));
        } else {
            lines.push(Line::from(spans));
        }
    }

    lines
}

/// Parse SGR (Select Graphic Rendition) codes
fn parse_sgr(seq: &str, mut style: Style) -> Style {
    if seq.is_empty() {
        return Style::default();
    }

    let codes: Vec<u8> = seq.split(';').filter_map(|s| s.parse().ok()).collect();

    let mut i = 0;
    while i < codes.len() {
        match codes[i] {
            0 => style = Style::default(),
            1 => style = style.bold(),
            2 => style = style.dim(),
            3 => style = style.italic(),
            4 => style = style.underlined(),
            7 => style = style.reversed(),
            // Foreground colors
            30 => style = style.fg(Color::Black),
            31 => style = style.fg(Color::Red),
            32 => style = style.fg(Color::Green),
            33 => style = style.fg(Color::Yellow),
            34 => style = style.fg(Color::Blue),
            35 => style = style.fg(Color::Magenta),
            36 => style = style.fg(Color::Cyan),
            37 => style = style.fg(Color::Gray),
            39 => style = style.fg(Color::Reset),
            90 => style = style.fg(Color::DarkGray),
            91 => style = style.fg(Color::LightRed),
            92 => style = style.fg(Color::LightYellow),
            93 => style = style.fg(Color::LightYellow),
            94 => style = style.fg(Color::LightBlue),
            95 => style = style.fg(Color::LightMagenta),
            96 => style = style.fg(Color::LightCyan),
            97 => style = style.fg(Color::White),
            // Background colors
            40 => style = style.bg(Color::Black),
            41 => style = style.bg(Color::Red),
            42 => style = style.bg(Color::Green),
            43 => style = style.bg(Color::Yellow),
            44 => style = style.bg(Color::Blue),
            45 => style = style.bg(Color::Magenta),
            46 => style = style.bg(Color::Cyan),
            47 => style = style.bg(Color::Gray),
            49 => style = style.bg(Color::Reset),
            100 => style = style.bg(Color::DarkGray),
            101 => style = style.bg(Color::LightRed),
            102 => style = style.bg(Color::LightYellow),
            103 => style = style.bg(Color::LightYellow),
            104 => style = style.bg(Color::LightBlue),
            105 => style = style.bg(Color::LightMagenta),
            106 => style = style.bg(Color::LightCyan),
            107 => style = style.bg(Color::White),
            // 256-color mode: 38;5;n or 48;5;n
            38 if i + 2 < codes.len() && codes[i + 1] == 5 => {
                style = style.fg(Color::Indexed(codes[i + 2]));
                i += 2;
            }
            48 if i + 2 < codes.len() && codes[i + 1] == 5 => {
                style = style.bg(Color::Indexed(codes[i + 2]));
                i += 2;
            }
            // RGB mode: 38;2;r;g;b or 48;2;r;g;b
            38 if i + 4 < codes.len() && codes[i + 1] == 2 => {
                style = style.fg(Color::Rgb(codes[i + 2], codes[i + 3], codes[i + 4]));
                i += 4;
            }
            48 if i + 4 < codes.len() && codes[i + 1] == 2 => {
                style = style.bg(Color::Rgb(codes[i + 2], codes[i + 3], codes[i + 4]));
                i += 4;
            }
            _ => {}
        }
        i += 1;
    }

    style
}

/// Display width of a single character, matching what the renderer draws.
fn char_display_width(ch: char) -> usize {
    ratatui::text::Span::raw(ch.to_string()).width()
}

/// Map a byte offset in `text` to the (col, row) of the terminal cell it
/// will render on, using the same char-by-char wrap rule as `wrap_spans`.
///
/// - `prefix_width` is the display width preceding `text` on the first visual
///   row (e.g. the `"  Prompt: "` label). It is consumed only on row 0; after
///   any wrap or `'\n'`, the next visual row starts at column 0.
/// - `wrap_width` is the inner width of the block (border-subtracted). A
///   width of 0 short-circuits to (prefix_width, 0).
/// - `'\n'` in `text` is treated as a hard line break.
///
/// This function and `wrap_spans` MUST stay in lock-step: any change to the
/// wrap rule has to land in both, otherwise the cursor drifts off what was
/// actually drawn. Both use lazy wrap (wrap only when the next char would
/// overflow), so a cursor at end-of-row sits at col=wrap_width on that row
/// — which is still inside the inner area (wrap_width = area.width - 2).
fn wrapped_cursor_pos(
    text: &str,
    cursor_byte: usize,
    prefix_width: usize,
    wrap_width: usize,
) -> (usize, usize) {
    let cursor_byte = cursor_byte.min(text.len());
    let mut col = prefix_width;
    let mut row = 0usize;
    if wrap_width == 0 {
        return (col, row);
    }
    let mut byte = 0usize;
    for ch in text.chars() {
        if byte >= cursor_byte {
            break;
        }
        if ch == '\n' {
            row += 1;
            col = 0;
        } else {
            let w = char_display_width(ch);
            if col + w > wrap_width {
                row += 1;
                col = 0;
            }
            col += w;
        }
        byte += ch.len_utf8();
    }
    (col, row)
}

/// Pre-wrap a sequence of styled spans into visual `Line`s by display width.
///
/// Char-by-char lazy wrap (no word-boundary detection). This makes our layout
/// authoritative: each produced `Line` has display width ≤ `wrap_width`, so
/// `Paragraph::wrap(Wrap { trim: false })` leaves it untouched and the cursor
/// position computed by `wrapped_cursor_pos` lines up exactly with what was
/// drawn — no two-source-of-truth between renderer and cursor.
///
/// Span styles are preserved across wrap points by splitting the span text
/// at the wrap boundary and re-emitting both halves with the same style.
/// `'\n'` inside span content is NOT handled here — callers split on `'\n'`
/// before calling so each invocation wraps a single logical line.
fn wrap_spans(spans: Vec<Span<'static>>, wrap_width: usize) -> Vec<Line<'static>> {
    if wrap_width == 0 || spans.is_empty() {
        return vec![Line::from(spans)];
    }
    let mut visual: Vec<Vec<Span<'static>>> = vec![Vec::new()];
    let mut col = 0usize;
    for span in spans {
        let style = span.style;
        let mut chunk = String::new();
        for ch in span.content.chars() {
            let w = char_display_width(ch);
            if col + w > wrap_width {
                if !chunk.is_empty() {
                    visual
                        .last_mut()
                        .unwrap()
                        .push(Span::styled(std::mem::take(&mut chunk), style));
                }
                visual.push(Vec::new());
                col = 0;
            }
            chunk.push(ch);
            col += w;
        }
        if !chunk.is_empty() {
            visual.last_mut().unwrap().push(Span::styled(chunk, style));
        }
    }
    visual.into_iter().map(Line::from).collect()
}

/// Build styled Text with highlighted file paths
fn build_highlighted_text<'a>(
    text: &str,
    file_paths: &HashSet<String>,
    text_color: Color,
    highlight_color: Color,
) -> Text<'a> {
    let normal_style = Style::default().fg(text_color);
    let highlight_style = Style::default().fg(highlight_color).bold();

    let lines: Vec<Line> = text
        .split('\n')
        .map(|line| {
            let mut spans: Vec<Span> = Vec::new();
            let mut remaining = line;

            while !remaining.is_empty() {
                // Find the earliest file path match in the remaining text
                let mut earliest: Option<(usize, &str)> = None;
                for path in file_paths {
                    if let Some(pos) = remaining.find(path.as_str()) {
                        if earliest.is_none() || pos < earliest.unwrap().0 {
                            earliest = Some((pos, path.as_str()));
                        }
                    }
                }

                if let Some((pos, path)) = earliest {
                    if pos > 0 {
                        spans.push(Span::styled(remaining[..pos].to_string(), normal_style));
                    }
                    spans.push(Span::styled(path.to_string(), highlight_style));
                    remaining = &remaining[pos + path.len()..];
                } else {
                    spans.push(Span::styled(remaining.to_string(), normal_style));
                    break;
                }
            }

            Line::from(spans)
        })
        .collect();

    Text::from(lines)
}

/// Fuzzy find files in a directory (respects .gitignore)
fn fuzzy_find_files(
    project_path: &Path,
    pattern: &str,
    max_results: usize,
    git_ops: &dyn GitOperations,
) -> Vec<String> {
    // Use git ls-files to get tracked files (respects .gitignore)
    let files = git_ops.list_files(project_path);

    if files.is_empty() {
        return vec![];
    }

    if pattern.is_empty() {
        // Show first N files when pattern is empty
        return files.into_iter().take(max_results).collect();
    }

    let pattern_lower = pattern.to_lowercase();
    let mut matches: Vec<(String, i32)> = files
        .into_iter()
        .filter_map(|path| {
            let path_lower = path.to_lowercase();

            // Simple fuzzy matching: check if all pattern chars appear in order
            let score = fuzzy_score(&path_lower, &pattern_lower);
            if score > 0 {
                Some((path, score))
            } else {
                None
            }
        })
        .collect();

    // Sort by score (higher is better)
    matches.sort_by(|a, b| b.1.cmp(&a.1));

    matches
        .into_iter()
        .take(max_results)
        .map(|(path, _)| path)
        .collect()
}

/// Calculate fuzzy match score (higher is better, 0 means no match)
fn fuzzy_score(haystack: &str, needle: &str) -> i32 {
    if needle.is_empty() {
        return 1;
    }

    let mut score = 0;
    let mut needle_chars = needle.chars().peekable();
    let mut prev_matched = false;
    let mut prev_was_separator = true;

    for c in haystack.chars() {
        let is_separator = c == '/' || c == '_' || c == '-' || c == '.';

        if let Some(&nc) = needle_chars.peek() {
            if c == nc {
                needle_chars.next();
                score += 1;

                // Bonus for matching after separator (start of word)
                if prev_was_separator {
                    score += 5;
                }
                // Bonus for consecutive matches
                if prev_matched {
                    score += 3;
                }
                prev_matched = true;
            } else {
                prev_matched = false;
            }
        }

        prev_was_separator = is_separator;
    }

    // Only return score if all needle chars were found
    if needle_chars.peek().is_none() {
        score
    } else {
        0
    }
}

/// Resolve the task prompt for a given phase transition, using plugin prompt template.
/// Substitutes {task}, {task_id}, and {phase} placeholders. Returns empty if no template is configured.
fn resolve_prompt(
    plugin: &Option<WorkflowPlugin>,
    phase: &str,
    task_content: &str,
    task_id: &str,
    cycle: i32,
) -> String {
    let template = match phase {
        "preresearch" | "research" => plugin
            .as_ref()
            .and_then(|p| p.prompts.research.as_deref())
            .unwrap_or(""),
        "planning" => plugin
            .as_ref()
            .and_then(|p| p.prompts.planning.as_deref())
            .unwrap_or(""),
        "planning_with_research" => plugin
            .as_ref()
            .and_then(|p| p.prompts.planning_with_research.as_deref())
            .unwrap_or(""),
        "running" => plugin
            .as_ref()
            .and_then(|p| p.prompts.running.as_deref())
            .unwrap_or(""),
        "running_with_research_or_planning" => plugin
            .as_ref()
            .and_then(|p| p.prompts.running_with_research_or_planning.as_deref())
            .unwrap_or(""),
        "review" => plugin
            .as_ref()
            .and_then(|p| p.prompts.review.as_deref())
            .unwrap_or(""),
        _ => return task_content.to_string(),
    };

    if template.is_empty() {
        return String::new();
    }

    template
        .replace("{task}", task_content)
        .replace("{task_id}", task_id)
        .replace("{phase}", &cycle.to_string())
}

/// Resolve the skill command to send via send_keys for a given phase.
/// Returns the plugin command transformed for the target agent, or None if no command is configured.
/// `collapse` controls how `{task}` is substituted.
///
/// `true` flattens the task to a single line, which the **typed** send path
/// needs: it delivers the command with `send_keys`, where an embedded newline is
/// a real Enter and would submit the message half-written.
///
/// `false` substitutes it verbatim. The **launch lane** passes the command in
/// argv, where newlines are just bytes, so a task keeps the paragraphs and lists
/// its author wrote — `spec-kit`'s `/speckit.specify {task}` and `openspec`'s
/// `/opsx:propose {task}` are the two bundled plugins this affects.
#[allow(clippy::too_many_arguments)]
fn resolve_skill_command(
    plugin: &Option<WorkflowPlugin>,
    phase: &str,
    agent_name: &str,
    task_content: &str,
    cycle: i32,
    task_id: &str,
    collapse: bool,
) -> Option<String> {
    let p = plugin.as_ref()?;

    // Commands are stored in canonical form (Claude/Gemini syntax) and transformed per agent
    // Commands may contain {task} and {phase} placeholders
    let cmd = match phase {
        "preresearch" => p
            .commands
            .preresearch
            .as_deref()
            .or(p.commands.research.as_deref()),
        "research" => p.commands.research.as_deref(),
        "planning" | "planning_with_research" => p.commands.planning.as_deref(),
        "running" | "running_with_research_or_planning" => p.commands.running.as_deref(),
        "review" => p.commands.review.as_deref(),
        _ => None,
    }?;

    if cmd.is_empty() {
        // Explicit empty command means "no command" (e.g., void plugin)
        return None;
    }

    // When a prior phase was done, strip {task} — agent already has context
    let expanded =
        if phase == "planning_with_research" || phase == "running_with_research_or_planning" {
            cmd.replace("{task}", "").trim().to_string()
        } else {
            let task_text = if collapse {
                task_content
                    .lines()
                    .map(|l| l.trim())
                    .filter(|l| !l.is_empty())
                    .collect::<Vec<_>>()
                    .join(" ")
            } else {
                task_content.to_string()
            };
            cmd.replace("{task}", &task_text)
        };
    let expanded = expanded.replace("{phase}", &cycle.to_string());
    let expanded = expanded.replace("{task_id}", task_id);
    skills::transform_plugin_command(&expanded, agent_name)
}

/// Spawn a background thread that optionally switches agent, waits for readiness,
/// then sends a skill command and prompt to the tmux pane.
#[allow(clippy::too_many_arguments)]
fn spawn_send_to_agent(
    tmux_ops: Arc<dyn TmuxOperations>,
    agent_registry: Arc<dyn agent::AgentRegistry>,
    task_id: String,
    agent_hooks: bool,
    auto_trust: bool,
    target: String,
    current_agent: String,
    target_agent: String,
    needs_switch: bool,
    skill_cmd: Option<String>,
    // The same command resolved **without** collapsing `{task}`, for the argv
    // path. An agent switch starts a new process, so it takes the message in argv
    // and keeps the task's line structure; only the typed fallback needs the
    // flattened `skill_cmd`. See `resolve_skill_command`.
    skill_cmd_launch: Option<String>,
    prompt: String,
    prompt_trigger: Option<String>,
    task_content: String,
    auto_dismiss: Vec<crate::config::AutoDismiss>,
    worktree_path: Option<String>,
    project_path: std::path::PathBuf,
    plugin: Option<WorkflowPlugin>,
) {
    std::thread::spawn(move || {
        // If the tmux window is gone, recover it with the agent's resume command
        {
            let agent_ops = agent_registry.get(&target_agent);
            ensure_window_or_recover(
                tmux_ops.as_ref(),
                &target,
                agent_ops.as_ref(),
                worktree_path.as_deref(),
                &task_id,
            );
        }

        let mut delivered_at_launch = false;
        if needs_switch {
            // Deploy skills for the incoming agent only if its native skill directory
            // doesn't exist yet. This handles the case where a worktree was created
            // with a different agent (e.g. Claude for planning) and a new agent
            // (e.g. OpenCode for review) is switched in later.
            if let Some(ref wt_path) = worktree_path {
                let already_deployed = skills::agent_native_skill_dir(&target_agent)
                    .map(|(base, namespace)| {
                        let dir = if namespace.is_empty() {
                            Path::new(wt_path).join(base)
                        } else {
                            Path::new(wt_path).join(base).join(namespace)
                        };
                        dir.exists()
                    })
                    .unwrap_or(true); // no native path for this agent — nothing to deploy
                if !already_deployed {
                    write_skills_to_worktree(
                        wt_path,
                        &project_path,
                        &plugin,
                        &[&target_agent],
                        agent_hooks,
                    );
                }
            }
            let agent_ops = agent_registry.get(&target_agent);
            // A switch starts a *new process*, so the opening message goes in argv
            // exactly as it does on a first launch — same act, just into an
            // existing window. A same-agent advance below cannot: that process is
            // already running, so there is no argv to fill.
            let launch_text = compose_launch_text(skill_cmd_launch.as_deref(), &prompt);
            delivered_at_launch =
                agent::spec::can_launch_with_prompt(agent_ops.prompt_injection(), &launch_text);
            let new_cmd = agent_ops.build_interactive_command(if delivered_at_launch {
                &launch_text
            } else {
                ""
            });
            switch_agent_in_tmux(tmux_ops.as_ref(), &target, &current_agent, &new_cmd);
            if !delivered_at_launch {
                // The *new* agent is what has to become ready.
                let _ = wait_for_agent_ready(&tmux_ops, &target, Some(&target_agent), auto_trust);
            }
        }
        if !delivered_at_launch {
            let clear_context = plugin
                .as_ref()
                .map(|p| p.clear_context_on_advance)
                .unwrap_or(false);
            send_skill_and_prompt(
                &tmux_ops,
                &target,
                &skill_cmd,
                &prompt,
                &prompt_trigger,
                &task_content,
                &target_agent,
                &auto_dismiss,
                clear_context,
            );
        }
    });
}

/// Attempts and per-attempt budget for [`deliver_message`].
///
/// Worst case is `DELIVERY_ATTEMPTS × (settle + confirm)` = 3 × (10s + 2s) = 36s,
/// because the settle runs *inside* the attempt loop — and the OpenCodePicker
/// path calls this twice, so ~72s. That only happens when the pane never goes
/// quiet and nothing ever lands, i.e. a session that is already broken; every
/// call site is a background thread, so it delays that task's send and nothing
/// else.
const DELIVERY_ATTEMPTS: u32 = 3;
const DELIVERY_CONFIRM_POLLS: u32 = 10; // x 200ms = 2s

/// Pane-settle budget before each attempt: 1s of quiet, given up on after 10s.
const SETTLE_STABLE_POLLS: u32 = 5;
const SETTLE_MAX_POLLS: u32 = 50;

/// Wait for the pane to stop changing, up to [`SETTLE_MAX_POLLS`].
///
/// Returns whether it settled; callers proceed either way, since a pane that
/// never settles (a spinner, a clock) must not block the send forever.
fn wait_for_pane_settled(tmux_ops: &Arc<dyn TmuxOperations>, target: &str) -> bool {
    let mut last = String::new();
    let mut stable = 0u32;
    for _ in 0..SETTLE_MAX_POLLS {
        std::thread::sleep(std::time::Duration::from_millis(200));
        let now = tmux_ops.capture_pane(target).unwrap_or_default();
        if now == last {
            stable += 1;
            if stable >= SETTLE_STABLE_POLLS {
                return true;
            }
        } else {
            stable = 0;
            last = now;
        }
    }
    false
}

/// Put `text` into the agent's composer, resending while nothing lands.
///
/// An agent TUI that has not attached its stdin reader yet silently discards
/// what it is sent, and bracketed paste does not help: the discard happens in
/// the application, not in the pty. `wait_for_agent_ready` narrows that window
/// but cannot close it — it has no signal for an agent that reports its npm
/// wrapper in `pane_current_command` and declares no readiness indicator, so it
/// falls through to a timeout and sends into whatever is there.
///
/// Landing is judged by **the pane changing**, not by finding the text in it: a
/// composer wraps, re-indents and box-draws what it echoes, so any needle longer
/// than a few characters is unreliable. Conversely a resend only happens while
/// the pane is unchanged — the same rule [`dismiss_launch_dialog`] uses, and for
/// the same reason: a redraw means the first one landed, and resending would
/// double the message.
///
/// Returns whether the message was seen to land. Callers submit either way,
/// because a false negative (a pane that happened not to redraw) must not
/// swallow the task.
fn deliver_message(
    tmux_ops: &Arc<dyn TmuxOperations>,
    target: &str,
    text: &str,
    paste: bool,
) -> bool {
    let needle = delivery_needle(text);
    for attempt in 0..DELIVERY_ATTEMPTS {
        // Settle first, for two reasons. A composer that is still rendering the
        // previous turn may not take the message at all — a phase advance fires
        // as soon as the artifact appears, which can be while the agent is still
        // writing its closing lines. And a pane that is changing on its own makes
        // change-detection meaningless, because the change it sees would be the
        // agent's output rather than the echo of what was sent.
        let settled = wait_for_pane_settled(tmux_ops, target);

        // Clear the composer before a *resend* only. A resend happens because
        // nothing was seen to land, but "seen" is not "did not" — if the first
        // send did land and merely rendered late, appending a second copy gives
        // the agent the message twice, concatenated. Ctrl+U is best-effort: an
        // agent that does not map it to kill-line is no worse off than before
        // this guard, and the first send is never preceded by one, so a fresh
        // composer is never touched.
        if attempt > 0 {
            let _ = tmux_ops.send_key(target, "C-u");
            std::thread::sleep(std::time::Duration::from_millis(150));
        }

        let before = tmux_ops.capture_pane(target).unwrap_or_default();
        let _ = if paste {
            tmux_ops.paste_text(target, text)
        } else {
            tmux_ops.send_text(target, text)
        };
        for _ in 0..DELIVERY_CONFIRM_POLLS {
            std::thread::sleep(std::time::Duration::from_millis(200));
            let Ok(now) = tmux_ops.capture_pane(target) else {
                continue;
            };
            // On a pane that went quiet, any change is the echo. On one that
            // never did, a change proves nothing — it is the agent still
            // writing — so the text itself has to be found. Without that
            // distinction a busy pane confirms on its first poll every time,
            // which is precisely the case the settle step exists for.
            let landed = match (settled, needle.as_deref()) {
                (true, _) => now != before,
                (false, Some(n)) => pane_shows(&now, n),
                (false, None) => now != before,
            };
            if landed {
                return true;
            }
        }
    }
    false
}

/// Send skill command and prompt to the agent via tmux.
/// When there is no prompt_trigger, combines skill command + prompt into a single message
/// (separated by a newline). When a prompt_trigger is set, sends them as two separate messages
/// with the prompt sent only after the trigger text appears in the pane.
fn send_skill_and_prompt(
    tmux_ops: &Arc<dyn TmuxOperations>,
    target: &str,
    skill_cmd: &Option<String>,
    prompt: &str,
    prompt_trigger: &Option<String>,
    task_content: &str,
    agent_name: &str,
    auto_dismiss: &[crate::config::AutoDismiss],
    clear_context: bool,
) {
    // How this agent's composer takes a message. Read once: it decides both the
    // clear-context send below and the skill+prompt send after it.
    let strategy =
        agent::spec(agent_name).map_or(agent::SendStrategy::Generic, |s| s.send_strategy);

    // Opt-in context clear on phase advance. Agents with no known clear command
    // (`clear_context_command: None`, tbd per issue #46) fall through to a normal
    // send unchanged.
    let clear_cmd = agent::spec(agent_name).and_then(|s| s.clear_context_command);
    if let (true, Some(cmd)) = (clear_context, clear_cmd) {
        // An Ink-class composer (`SendStrategy::Combined`) drops a combined
        // text+Enter `send-keys`: the Enter fires before the TUI has rendered the
        // input, so the command is left parked. That is worse than not clearing —
        // the skill+prompt below is then pasted *onto the end* of the parked text
        // and the whole thing submits as one message, so the phase command never
        // resolves. Deliver it the way a message is delivered and confirm it left
        // the composer. Verified against pi 0.84.3, which is why pi is `Combined`.
        if strategy == agent::SendStrategy::Combined {
            deliver_message(tmux_ops, target, cmd, true);
            submit_message(tmux_ops, target, cmd);
        } else {
            let _ = tmux_ops.send_keys(target, cmd);
        }
        // Wait for the agent to clear its buffer and return to idle prompt.
        // Pattern mirrors the stability-poll loops used elsewhere in this
        // function: poll until pane content stabilises (no changes for ~1s),
        // capped at ~5s total.
        let mut last_content = String::new();
        let mut stable_ticks = 0u32;
        for _ in 0..25 {
            std::thread::sleep(std::time::Duration::from_millis(200));
            if let Ok(content) = tmux_ops.capture_pane(target) {
                if content != last_content {
                    last_content = content;
                    stable_ticks = 0;
                } else {
                    stable_ticks += 1;
                    if stable_ticks >= 5 {
                        break;
                    }
                }
            }
        }
    }

    // OpenCode command picker handles args differently: when a command has arguments
    // (e.g. `/agtx-plan abc123`), typing the full string and pressing Enter causes the
    // picker to confirm/insert only the command name — stripping the args. Commands
    // without args (e.g. `/agtx-review`) work fine with a single Enter confirm + submit.
    //
    // Fix: send just the command name, wait for picker, Enter to confirm (inserts cmd),
    // then send the args (picker dismissed, input now has just the command), then Enter.
    if strategy == agent::SendStrategy::OpenCodePicker {
        // Build the full message: skill command (if any) + prompt (if any)
        let full_text = if let Some(cmd) = skill_cmd {
            if !prompt.is_empty() {
                format!("{}\n\n{}", cmd, prompt)
            } else {
                cmd.clone()
            }
        } else if !prompt.is_empty() {
            prompt.to_string()
        } else {
            let oneline = task_content
                .lines()
                .map(|l| l.trim())
                .filter(|l| !l.is_empty())
                .collect::<Vec<_>>()
                .join(" ");
            oneline
        };

        if !full_text.is_empty() {
            // Check if the first token looks like a slash command (starts with /)
            let first_line = full_text.lines().next().unwrap_or(&full_text);
            if let Some(space_pos) = first_line.find(' ') {
                let cmd_name = &first_line[..space_pos];
                let cmd_args = &first_line[space_pos..]; // includes leading space
                let rest = &full_text[first_line.len()..]; // rest of the message after first line

                if cmd_name.starts_with('/') {
                    // Send just the command name to trigger the picker. Typed,
                    // not pasted — the picker opens on typing — so this is the
                    // step most exposed to a TUI that is not reading stdin yet,
                    // and losing it loses the whole message: the Enter below then
                    // confirms nothing and the args are typed into an empty
                    // composer. `deliver_message` resends while the pane is
                    // unchanged.
                    deliver_message(tmux_ops, target, cmd_name, false);
                    std::thread::sleep(std::time::Duration::from_millis(200));
                    // Enter confirms/inserts the command from picker
                    let _ = tmux_ops.send_key(target, "Enter");
                    std::thread::sleep(std::time::Duration::from_millis(200));
                    // Now send the args + any remaining prompt text
                    let remaining = format!("{}{}", cmd_args, rest);
                    deliver_message(tmux_ops, target, &remaining, false);
                    std::thread::sleep(std::time::Duration::from_millis(200));
                    let _ = tmux_ops.send_key(target, "Enter");
                    return;
                }
            }

            // No args (or no slash command): one send, confirmed, then Enter.
            deliver_message(tmux_ops, target, &full_text, false);
            std::thread::sleep(std::time::Duration::from_millis(200));
            // Enter to confirm picker (if any), then second Enter to submit
            let _ = tmux_ops.send_key(target, "Enter");
            std::thread::sleep(std::time::Duration::from_millis(400));
            let _ = tmux_ops.send_key(target, "Enter");
        }
        return;
    }

    // Gemini, Codex, cursor & antigravity: always combine skill+prompt into a
    // single message.
    // Gemini: sending separately causes it to execute the skill and queue the
    //   prompt, which gets lost or arrives too late.
    // Codex: skill mentions ($skill-name) are inline references that must be
    //   part of a message — sending just "$skill" standalone does nothing.
    // Antigravity: descends from the Gemini CLI lineage (settings live under
    //   ~/.gemini/), so it is treated as Ink-class and gets the same
    //   wait-for-echo send. Not yet confirmed against a live session.
    if strategy == agent::SendStrategy::Combined {
        let text_to_send = if let Some(cmd) = skill_cmd {
            if !prompt.is_empty() {
                Some(format!("{}\n\n{}", cmd, prompt))
            } else {
                Some(cmd.clone())
            }
        } else if !prompt.is_empty() {
            Some(prompt.to_string())
        } else {
            let oneline = task_content
                .lines()
                .map(|l| l.trim())
                .filter(|l| !l.is_empty())
                .collect::<Vec<_>>()
                .join(" ");
            if !oneline.is_empty() {
                Some(oneline)
            } else {
                None
            }
        };

        if let Some(text) = text_to_send {
            // Bracketed paste rather than typed keystrokes. Two reasons, both of
            // which the echo-poll this replaces was only working around:
            //
            // 1. It is atomic. `send-keys` streams characters into a TUI that may
            //    not have attached its stdin reader yet, which forces a poll of
            //    `capture_pane` for up to 4s to see the text render before daring
            //    to press Enter. A paste arrives as one write wrapped in
            //    \x1b[200~ … \x1b[201~, so there is no window to lose keystrokes
            //    in and nothing to poll for.
            // 2. It keeps newlines as newlines. A skill command and its prompt are
            //    joined by "\n\n", and `send-keys` delivers those as real Enter
            //    presses — an Ink composer submits on the first one and the rest of
            //    the message arrives as a second, truncated turn. Inside a bracketed
            //    paste they are literal text.
            //
            // Atomic is not the same as delivered, though: an agent that has
            // not attached its stdin reader discards the paste whole, which is
            // how every antigravity task reached its composer empty. So the
            // paste goes through `deliver_message`, which resends while the pane
            // is unchanged, and only then is it submitted.
            deliver_message(tmux_ops, target, &text, true);
            std::thread::sleep(std::time::Duration::from_millis(150));
            // How many Enters this takes is not fixed. A message with a prompt
            // after the command submits on the first; a bare command opens the
            // command picker on the paste and needs a second. `submit_message`
            // decides by watching the composer rather than counting keypresses.
            submit_message(tmux_ops, target, &text);
        }
        return;
    }

    match (skill_cmd, prompt_trigger) {
        // Skill + prompt trigger: must send separately, wait for trigger between them
        (Some(cmd), Some(trigger)) => {
            let _ = tmux_ops.send_keys(target, cmd);
            if !prompt.is_empty() {
                if wait_for_prompt_trigger(tmux_ops, target, trigger, auto_dismiss) {
                    std::thread::sleep(std::time::Duration::from_millis(500));
                    let _ = tmux_ops.send_keys(target, prompt);
                }
            }
        }
        // Skill + prompt, no trigger: send separately, wait for agent to finish processing
        (Some(cmd), None) => {
            let _ = tmux_ops.send_keys(target, cmd);

            // Verify the command was received: check that pane content changes within
            // ~3s (agent picked it up). If nothing changed, the agent wasn't ready yet —
            // wait 1s and resend once.
            let baseline = tmux_ops.capture_pane(target).unwrap_or_default();
            let mut received = false;
            for _ in 0..15 {
                // up to 3s
                std::thread::sleep(std::time::Duration::from_millis(200));
                if let Ok(content) = tmux_ops.capture_pane(target) {
                    if content != baseline {
                        received = true;
                        break;
                    }
                }
            }
            if !received {
                std::thread::sleep(std::time::Duration::from_secs(1));
                let _ = tmux_ops.send_keys(target, cmd);
            }
            if !prompt.is_empty() {
                // Wait for agent to process the skill command and become idle again.
                // Requires at least 1 content change (agent started processing) before
                // counting stability, to avoid false-positive when the command hasn't
                // been picked up yet.
                let mut last_content = String::new();
                let mut stable_ticks = 0u32;
                let mut change_count = 0u32;
                for _ in 0..75 {
                    // 15s max
                    std::thread::sleep(std::time::Duration::from_millis(200));
                    if let Ok(content) = tmux_ops.capture_pane(target) {
                        if content != last_content {
                            change_count += 1;
                            stable_ticks = 0;
                            last_content = content;
                        } else if change_count >= 1 {
                            stable_ticks += 1;
                            if stable_ticks >= 10 {
                                // 2s of no changes after agent responded
                                break;
                            }
                        }
                    }
                }
                let _ = tmux_ops.send_keys(target, prompt);
            }
        }
        // No skill command, just prompt
        (None, _) => {
            if !prompt.is_empty() {
                let _ = tmux_ops.send_keys(target, prompt);
            } else {
                // No command and no prompt (e.g. void plugin): prefill task in input
                let oneline = task_content
                    .lines()
                    .map(|l| l.trim())
                    .filter(|l| !l.is_empty())
                    .collect::<Vec<_>>()
                    .join(" ");
                if !oneline.is_empty() {
                    // Task-derived text: must not go through key-name lookup.
                    let _ = tmux_ops.send_text(target, &oneline);
                }
            }
        }
    }
}

/// Resolve the prompt trigger text for a given phase.
/// When set, the system polls the tmux pane for this text before sending the prompt.
fn resolve_prompt_trigger(plugin: &Option<WorkflowPlugin>, phase: &str) -> Option<String> {
    plugin
        .as_ref()
        .and_then(|p| match phase {
            "preresearch" | "research" => p.prompt_triggers.research.clone(),
            "planning" | "planning_with_research" => p.prompt_triggers.planning.clone(),
            "running" | "running_with_research_or_planning" => p.prompt_triggers.running.clone(),
            "review" => p.prompt_triggers.review.clone(),
            _ => None,
        })
        .filter(|s| !s.is_empty())
}

/// Wait for a specific text to appear in a tmux pane, then return.
/// Returns true if the trigger was found, false if timed out.
/// Auto-dismiss rules are checked while waiting: when all detect patterns match
/// and the pane is stable for ~2s, the response keystrokes are sent automatically.
fn wait_for_prompt_trigger(
    tmux_ops: &Arc<dyn TmuxOperations>,
    target: &str,
    trigger: &str,
    auto_dismiss: &[crate::config::AutoDismiss],
) -> bool {
    let mut last_content = String::new();
    let mut stable_ticks = 0u32;

    for _ in 0..600 {
        // ~5 minutes (600 * 500ms)
        std::thread::sleep(std::time::Duration::from_millis(500));
        if let Ok(content) = tmux_ops.capture_pane(target) {
            if content == last_content {
                stable_ticks += 1;
            } else {
                stable_ticks = 0;
                last_content = content.clone();
            }

            // Auto-dismiss interactive prompts that block the trigger.
            // Requires stability (2s) to ensure the UI is ready for input.
            if stable_ticks >= 4 {
                for rule in auto_dismiss {
                    if rule.detect.iter().all(|p| content.contains(p.as_str())) {
                        tracing::info!(
                            target = target,
                            patterns = ?rule.detect,
                            response = %rule.response,
                            "Auto-dismiss rule triggered"
                        );
                        for key in rule.response.split('\n') {
                            let _ = tmux_ops.send_key(target, key);
                            std::thread::sleep(std::time::Duration::from_millis(100));
                        }
                        stable_ticks = 0;
                        last_content.clear();
                        break;
                    }
                }
                if last_content.is_empty() {
                    continue;
                }
            }

            // Trigger as soon as the text is present in the pane.
            if content.contains(trigger) {
                return true;
            }
        }
    }
    false
}

/// Returns true if a stuck-task notification should be sent for this task.
/// Void plugin tasks are fully user-managed and never produce stuck notifications.
fn should_send_stuck_notification(plugin_name: Option<&str>) -> bool {
    plugin_name != Some("void")
}

/// Check if the phase artifact exists for a task in its worktree.
/// Tries both zero-padded (e.g. "01") and non-padded (e.g. "1") {phase} substitution.
fn phase_artifact_exists(
    worktree_path: &str,
    status: TaskStatus,
    plugin: &Option<WorkflowPlugin>,
    cycle: i32,
) -> bool {
    let rel_template = plugin.as_ref().and_then(|p| match status {
        TaskStatus::Planning => p.artifacts.planning.as_deref(),
        TaskStatus::Running => p.artifacts.running.as_deref(),
        TaskStatus::Review => p.artifacts.review.as_deref(),
        _ => None,
    });

    let Some(rel_template) = rel_template else {
        return false;
    };
    artifact_path_exists(worktree_path, rel_template, cycle)
}

/// Check if the research artifact exists for a task.
/// Tries both zero-padded (e.g. "01") and non-padded (e.g. "1") {phase} substitution.
fn research_artifact_exists(
    worktree_path: &str,
    task_id: &str,
    plugin: &Option<WorkflowPlugin>,
) -> bool {
    let Some(template) = plugin
        .as_ref()
        .and_then(|p| p.artifacts.research.as_deref())
    else {
        return false;
    };
    let rel_template = template.replace("{task_id}", task_id);
    // Research is always cycle 1
    artifact_path_exists(worktree_path, &rel_template, 1)
}

/// Determine the phase variant name based on whether prior-phase artifacts exist.
/// Returns the base phase name or a `_with_*` variant.
fn determine_phase_variant(
    phase: &str,
    worktree_path: Option<&str>,
    task_id: &str,
    plugin: &Option<WorkflowPlugin>,
    cycle: i32,
) -> &'static str {
    match phase {
        "planning" => {
            let has_research =
                worktree_path.map_or(false, |wt| research_artifact_exists(wt, task_id, plugin));
            if has_research {
                "planning_with_research"
            } else {
                "planning"
            }
        }
        "running" => {
            let has_prior = worktree_path.map_or(false, |wt| {
                research_artifact_exists(wt, task_id, plugin)
                    || phase_artifact_exists(wt, TaskStatus::Planning, plugin, cycle)
            });
            if has_prior {
                "running_with_research_or_planning"
            } else {
                "running"
            }
        }
        _ => {
            // Phases without variants leak the &str — use a known static
            match phase {
                "review" => "review",
                "research" => "research",
                _ => "running",
            }
        }
    }
}

/// Whether the current phase's artifact was written *during* this phase.
///
/// Existence alone is what `phase_artifact_exists` answers, and it is the wrong
/// question after a resume: the previous cycle's `execute.md` is still on disk,
/// so a task sent back to Running would read `ready` the moment it arrived,
/// before doing any work. The artifact counts only if its mtime is at or after `entered_at`.
///
/// `phase_artifact_exists` stays for its other callers, which ask whether a
/// *prior* phase ever produced its artifact — a gating question, where any plan
/// on disk is the right answer.
///
/// Two fallbacks, both to the existence check: `entered_at` is `None` for a
/// task stored before the column existed, and a glob template names a set of
/// files rather than one, so it has no single mtime to compare.
fn phase_artifact_fresh(
    worktree_path: &str,
    status: TaskStatus,
    plugin: &Option<WorkflowPlugin>,
    cycle: i32,
    entered_at: Option<chrono::DateTime<chrono::Utc>>,
) -> bool {
    let Some(entered_at) = entered_at else {
        return phase_artifact_exists(worktree_path, status, plugin, cycle);
    };
    let rel_template = plugin.as_ref().and_then(|p| match status {
        TaskStatus::Planning => p.artifacts.planning.as_deref(),
        TaskStatus::Running => p.artifacts.running.as_deref(),
        TaskStatus::Review => p.artifacts.review.as_deref(),
        _ => None,
    });
    let Some(rel_template) = rel_template else {
        return false;
    };
    if rel_template.contains('*') {
        return artifact_path_exists(worktree_path, rel_template, cycle);
    }
    let entered_at = std::time::SystemTime::from(entered_at);
    [format!("{:02}", cycle), cycle.to_string()].iter().any(|phase_str| {
        let full = Path::new(worktree_path).join(rel_template.replace("{phase}", phase_str));
        std::fs::metadata(&full)
            .and_then(|m| m.modified())
            .is_ok_and(|mtime| mtime >= entered_at)
    })
}

/// `Ready` only once the agent's turn is over.
///
/// An agent writes its phase artifact mid-turn and keeps going — measured, a
/// reviewer wrote `review.md`, then ran `git status` and printed a summary — so
/// a fresh artifact under a live `working` report is not done yet, and a caller
/// acting on it would resume an agent that has not stopped. `blocked` likewise: the
/// artifact exists but the agent is now waiting on a person.
///
/// No timestamp comparison, deliberately. The status file holds only the latest
/// event, and writing the artifact is itself a tool call whose `PreToolUse` sets
/// `working` before the file exists, so a current `waiting`/`ended` can only have
/// come after the write. Comparing times would be worse than redundant: hook
/// `ts` is whole seconds against a sub-second mtime, and a `Stop` in the same
/// second as the write would read as older and hold the task at `working`.
///
/// It cannot hold a task forever. A turn that ends reports `waiting`; an agent
/// that exits leaves `ended` or a window that is gone; one that falls silent
/// leaves a `working` record `read_status` stops trusting after
/// `HOOK_STALE_SECS`, and `None` falls back to the artifact alone.
fn gate_ready_on_turn(phase: PhaseStatus, hook: Option<hook_status::HookState>) -> PhaseStatus {
    match (phase, hook) {
        (
            PhaseStatus::Ready,
            Some(hook_status::HookState::Working | hook_status::HookState::Blocked),
        ) => PhaseStatus::Working,
        (phase, _) => phase,
    }
}

/// Check if an artifact path exists, trying both zero-padded and non-padded {phase} substitution.
fn artifact_path_exists(worktree_path: &str, rel_template: &str, cycle: i32) -> bool {
    // Try zero-padded first (e.g. "01"), then non-padded (e.g. "1")
    for phase_str in [format!("{:02}", cycle), cycle.to_string()] {
        let rel_path = rel_template.replace("{phase}", &phase_str);
        let full_path = Path::new(worktree_path).join(&rel_path);

        if rel_path.contains('*') {
            if glob_path_exists(&full_path.to_string_lossy()) {
                return true;
            }
        } else if full_path.exists() {
            return true;
        }
    }
    false
}

/// Simple glob matching for paths with `*` wildcards.
/// Supports directory-level wildcards (e.g. "/path/*/plan.md")
/// and file-level wildcards (e.g. "/path/*-PLAN.md").
fn glob_path_exists(pattern: &str) -> bool {
    let Some(star_pos) = pattern.find('*') else {
        return Path::new(pattern).exists();
    };

    // Split at the wildcard: parent_dir / * / remainder
    let parent = &pattern[..star_pos];
    let remainder = &pattern[star_pos + 1..];
    let parent = parent.trim_end_matches('/');

    let Ok(entries) = std::fs::read_dir(parent) else {
        return false;
    };

    // File-level wildcard: * is in the last path component (e.g. "*-CONTEXT.md")
    let is_file_wildcard = !remainder.starts_with('/');

    for entry in entries.flatten() {
        let path = entry.path();
        if is_file_wildcard {
            // Match against filenames: e.g. "*-CONTEXT.md" matches "01-CONTEXT.md"
            if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
                if name.ends_with(remainder) {
                    return true;
                }
            }
        } else if path.is_dir() {
            let candidate = format!("{}{}", path.display(), remainder);
            if remainder.contains('*') {
                if glob_path_exists(&candidate) {
                    return true;
                }
            } else if Path::new(&candidate).exists() {
                return true;
            }
        }
    }
    false
}

/// The agent `task` runs in `phase`: the phase's own `[agents]` entry, else the
/// task's own agent (`Task::base_agent`), else the configured default.
///
/// The task's agent stands exactly where `default_agent` would, so a per-phase
/// override still wins, and a phase without one returns to the task's pick —
/// not to the global default, and not to whichever override ran last, which is
/// what `Task::agent` holds by then.
fn phase_agent<'a>(config: &'a MergedConfig, task: &'a Task, phase: &str) -> &'a str {
    config
        .explicit_agent_for_phase(phase)
        .or(task.base_agent.as_deref().filter(|a| !a.is_empty()))
        .unwrap_or(&config.default_agent)
}

/// Determine the target agent for a phase and whether a switch is needed.
/// Returns (target_agent_name, needs_switch). See `phase_agent` for the target.
fn needs_agent_switch(config: &MergedConfig, task: &Task, phase: &str) -> (String, bool) {
    let target = phase_agent(config, task, phase);
    // Empty task.agent means agent not yet assigned (SetupResult pending) — no switch needed
    let switch = !task.agent.is_empty() && task.agent != target;
    (target.to_string(), switch)
}

/// Every agent `task` can run on: the one in its window now, plus each phase's.
/// Used to deploy skills for all of them at worktree setup, since a later phase
/// switch finds the worktree already written.
fn collect_phase_agents(config: &MergedConfig, task: &Task) -> Vec<String> {
    let mut agents: Vec<String> = Vec::new();
    if !task.agent.is_empty() {
        agents.push(task.agent.clone());
    }
    for phase in &["research", "planning", "running", "review"] {
        let agent = phase_agent(config, task, phase).to_string();
        if !agents.contains(&agent) {
            agents.push(agent);
        }
    }
    agents
}

/// Known agent binary names as they appear in `pane_current_command`.
/// Used by `is_pane_at_shell` to detect when an agent process is running.
/// Does NOT include `node` — Node/Ink agents (Gemini, Cursor, OpenCode, Codex) are
/// detected via `AGENT_ACTIVE_INDICATORS` instead, so Check 2 in `wait_for_agent_ready`
/// can fire for them rather than Check 1 firing too early.
/// Note: on systems where agents are installed via asdf/nvm, all agents run as `node`
/// and Check 1 never fires — AGENT_ACTIVE_INDICATORS is the only reliable signal there.
static AGENT_COMMANDS: std::sync::LazyLock<Vec<&'static str>> = std::sync::LazyLock::new(|| {
    agent::AGENT_SPECS
        .iter()
        .flat_map(|s| s.process_names.iter().copied())
        // Not agent binaries: a pane running a Python entry point (the swebench
        // harness) must not read as "back at the shell".
        .chain(["python3", "python"])
        .collect()
});

/// Strings in pane content that indicate an agent TUI is active and ready.
/// Used by `is_agent_active` to detect agents like Gemini, Cursor and Grok that
/// run inside bash/node and don't change `pane_current_command` to their own name.
/// (Grok is a native binary, but the npm package launches it through a wrapper,
/// so the pane still reports `bash`.)
/// Also used by `wait_for_agent_ready` (Check 2) to detect readiness for these agents.
/// Flattened across all agents deliberately: matching is done against any pane
/// regardless of which agent runs there. Attributing each string to its agent
/// would be strictly more correct — "Ask anything" matching in a Claude pane is a
/// false positive today — but that *changes behaviour*, so it belongs in its own
/// change with its own test rather than riding inside a refactor that is meant to
/// preserve it.
static AGENT_ACTIVE_INDICATORS: std::sync::LazyLock<Vec<&'static str>> =
    std::sync::LazyLock::new(|| {
        agent::AGENT_SPECS
            .iter()
            .flat_map(|s| s.active_indicators.iter().copied())
            .collect()
    });

/// Check if the pane is running a shell (i.e. the agent has exited).
/// Returns true when `pane_current_command` reports a shell (bash, zsh, sh, fish)
/// rather than an agent process.
fn is_pane_at_shell(tmux_ops: &dyn TmuxOperations, target: &str) -> bool {
    if let Some(cmd) = tmux_ops.pane_current_command(target) {
        // Compared whole, not by substring. `pane_current_command` reports the
        // command *name*, so equality is what the field means — and a substring
        // test lets short names swallow unrelated processes: `pi` matches `pip`,
        // `pipx`, `pipenv` and `pinentry`, and `agent` (cursor) matches anything
        // ending in it. Every one of those would read as "an agent is running"
        // for *every* task, since this list is flattened across all agents.
        let cmd = cmd.trim();
        !AGENT_COMMANDS.iter().any(|a| cmd == *a)
    } else {
        false
    }
}

/// Orchestrator is live iff its tmux window exists (no pane-command peeking).
fn is_orchestrator_live(tmux_ops: &dyn TmuxOperations, target: &str) -> bool {
    tmux_ops.window_exists(target).unwrap_or(false)
}

/// Startup reattach: returns the target if a window survives, replaying catch-up.
fn detect_existing_orchestrator(
    experimental: bool,
    tmux_ops: &dyn TmuxOperations,
    tmux_project_name: &str,
    db: Option<&Database>,
    tasks: &[Task],
    project_path: Option<&Path>,
) -> Option<String> {
    if !experimental {
        return None;
    }
    let target = format!("{}:orchestrator", tmux_project_name);
    if !tmux_ops.window_exists(&target).unwrap_or(false) {
        return None;
    }
    if let Some(db) = db {
        run_orchestrator_catchup(db, tasks, project_path);
    }
    Some(target)
}

/// Kill all windows matching `target` (tmux allows duplicates); false if the 16-iter cap is hit.
fn kill_windows_by_name(tmux_ops: &dyn TmuxOperations, target: &str) -> bool {
    for _ in 0..16 {
        if !tmux_ops.window_exists(target).unwrap_or(false) {
            return true;
        }
        let _ = tmux_ops.kill_window(target);
    }
    !tmux_ops.window_exists(target).unwrap_or(false)
}

/// Replay "completed phase" notifications for tasks whose artifact is on disk.
fn run_orchestrator_catchup(db: &Database, tasks: &[Task], project_path: Option<&Path>) {
    let existing: HashSet<String> = db
        .peek_notifications()
        .unwrap_or_default()
        .into_iter()
        .map(|n| n.message)
        .collect();

    for task in tasks {
        if !matches!(task.status, TaskStatus::Planning | TaskStatus::Running) {
            continue;
        }
        let plugin = match &task.plugin {
            Some(name) => WorkflowPlugin::load(name, project_path).ok(),
            None => skills::load_bundled_plugin("agtx"),
        };
        let Some(ref wt) = task.worktree_path else {
            continue;
        };
        if !phase_artifact_fresh(wt, task.status, &plugin, task.cycle, task.phase_entered_at) {
            continue;
        }
        let short_id = if task.id.len() >= 8 {
            &task.id[..8]
        } else {
            &task.id
        };
        let message = format!(
            "Task \"{}\" ({}) completed phase: {}",
            task.title,
            short_id,
            task.status.as_str()
        );
        if existing.contains(&message) {
            continue;
        }
        let _ = db.create_notification(&crate::db::Notification::for_task(
            crate::db::NotificationKind::PhaseCompleted,
            &task.id,
            message,
        ));
    }
}

/// Check if an agent is actively running in the pane.
/// Uses both `pane_current_command` (works for Claude, Codex, Copilot) and
/// pane content indicators (works for Gemini which runs inside bash).
fn is_agent_active(tmux_ops: &dyn TmuxOperations, target: &str, agent_name: Option<&str>) -> bool {
    // Check 1: agent process visible in pane_current_command
    if !is_pane_at_shell(tmux_ops, target) {
        return true;
    }
    // Check 2: check the bottom of the visible pane for agent UI indicators.
    // Only the last few lines are checked to avoid false positives from
    // indicator strings appearing in conversation output higher up.
    if let Ok(content) = tmux_ops.capture_pane(target) {
        let tail_text = pane_tail(&content, PANE_TAIL_LINES);
        if active_indicators_for(agent_name)
            .iter()
            .any(|s| tail_text.contains(s))
        {
            return true;
        }
    }
    false
}

/// If the tmux window for `target` is gone, recreate it with the agent's resume command.
/// Used before `switch_agent_in_tmux` and `send_skill_and_prompt` to handle dead windows.
fn ensure_window_or_recover(
    tmux_ops: &dyn TmuxOperations,
    target: &str,
    agent_ops: &dyn AgentOperations,
    worktree_path: Option<&str>,
    task_id: &str,
) {
    if !tmux_ops.window_exists(target).unwrap_or(true) {
        let Some(wt_path) = worktree_path else { return };
        if !Path::new(wt_path).exists() {
            return;
        }
        let Some((session, window)) = target.split_once(':') else {
            return;
        };
        if !tmux_ops.has_session(session) {
            let _ = tmux_ops.create_session(session, wt_path);
        }
        let resume_cmd = agent_ops.build_resume_command();
        let _ = tmux_ops.create_window(
            session,
            window,
            wt_path,
            Some(resume_cmd),
            true,
            &agtx_task_env(task_id, wt_path),
        );
    }
}

/// Gracefully switch the agent running in a tmux window.
/// Terminates the current agent, waits for the shell prompt,
/// then starts the new agent.
///
/// The exit command comes from `AgentSpec::exit_command`; `None` (codex, cursor)
/// means Ctrl+C is the only way out, and Ctrl+C + Ctrl+D is the last resort when
/// the command does not take. How it is *delivered* is decided by
/// `AgentSpec::send_strategy` — see the comment on the send below.
///
/// Detection uses `tmux display -p #{pane_current_command}` which reports
/// the actual process name (e.g. "claude", "node", "bash"), avoiding
/// false positives from parsing pane text content.
fn switch_agent_in_tmux(
    tmux_ops: &dyn TmuxOperations,
    target: &str,
    current_agent: &str,
    new_agent_cmd: &str,
) {
    // 1. Send the graceful exit command for the current agent.
    // `None` means Ctrl+C is the only way out (codex, cursor). An agent agtx does
    // not know keeps the historical default of /exit.
    let exit_cmd = agent::spec(current_agent).map_or(Some("/exit"), |s| s.exit_command);

    if let Some(cmd) = exit_cmd {
        // An Ink-class composer (`SendStrategy::Combined`) loses a combined
        // text+Enter `send-keys`: Enter fires before the TUI has rendered the
        // input, and the exit command is lost. Send the text, wait for it to
        // echo, then Enter — the same pattern as `send_skill_and_prompt`. Found
        // with gemini; pi's spec records the identical measurement, and
        // antigravity is the same class of TUI. Without this the graceful path is
        // dead code for those agents: the command sits unsent, the 3s poll times
        // out, and every switch away from them kills the agent with Ctrl+C
        // mid-turn — after which the unsent text lands in the bare shell.
        let split_enter = agent::spec(current_agent)
            .is_some_and(|s| s.send_strategy == agent::SendStrategy::Combined);
        if split_enter {
            let _ = tmux_ops.send_text(target, cmd);
            for _ in 0..20 {
                std::thread::sleep(std::time::Duration::from_millis(200));
                if let Ok(content) = tmux_ops.capture_pane(target) {
                    if content.contains(cmd) {
                        break;
                    }
                }
            }
            std::thread::sleep(std::time::Duration::from_millis(200));
            let _ = tmux_ops.send_key(target, "Enter");
        } else {
            let _ = tmux_ops.send_keys(target, cmd);
        }
    } else {
        let _ = tmux_ops.send_key(target, "C-c");
    }

    // 2. Poll for agent exit. If the agent was busy, the exit command
    //    may have been queued — so we wait up to 3s for it to take effect.
    //    Uses is_agent_active (checks both pane_current_command AND pane content)
    //    so that Node/Ink agents like Gemini (which always show "bash" as the
    //    process name) are correctly detected as still running.
    let mut found_shell = false;
    for _ in 0..30 {
        // 3s
        std::thread::sleep(std::time::Duration::from_millis(100));
        if !is_agent_active(tmux_ops, target, Some(current_agent)) {
            found_shell = true;
            break;
        }
    }

    // 3. If still running, the agent was likely busy. Ctrl+C to cancel, then retry exit.
    if !found_shell {
        let _ = tmux_ops.send_key(target, "C-c");
        std::thread::sleep(std::time::Duration::from_millis(1000));

        if let Some(cmd) = exit_cmd {
            if current_agent == "gemini" {
                let _ = tmux_ops.send_text(target, cmd);
                for _ in 0..20 {
                    std::thread::sleep(std::time::Duration::from_millis(200));
                    if let Ok(content) = tmux_ops.capture_pane(target) {
                        if content.contains(cmd) {
                            break;
                        }
                    }
                }
                std::thread::sleep(std::time::Duration::from_millis(200));
                let _ = tmux_ops.send_key(target, "Enter");
            } else {
                let _ = tmux_ops.send_keys(target, cmd);
            }
        }

        // Wait for agent exit after retry
        for _ in 0..50 {
            // 5s
            std::thread::sleep(std::time::Duration::from_millis(100));
            if !is_agent_active(tmux_ops, target, Some(current_agent)) {
                found_shell = true;
                break;
            }
        }
    }

    // 4. Last resort: Ctrl+D to force exit
    if !found_shell {
        let _ = tmux_ops.send_key(target, "C-d");
        for _ in 0..20 {
            // 2s
            std::thread::sleep(std::time::Duration::from_millis(100));
            if !is_agent_active(tmux_ops, target, Some(current_agent)) {
                break;
            }
        }
    }

    // 4. Let the shell fully initialize before sending the new agent command
    std::thread::sleep(std::time::Duration::from_millis(2000));

    // 5. Start the new agent
    // Wrap with env -u to clear Claude Code's nesting-detection vars — the
    // persistent shell inherited them at window creation time, so they must
    // be stripped explicitly here (unlike create_window which uses env -u
    // on the initial command only).
    let cmd = format!(
        "env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT {}",
        new_agent_cmd
    );
    // **One layer of quoting here, not two.** `create_window` nests its command
    // inside `sh -c '…'` (`wrap_launch_command`), so a prompt going that way is
    // quoted twice. This path types a command line into the window's
    // *already-running* interactive shell, which parses it once — the quoting
    // `compose_command` already applied is exactly right, and adding
    // `single_quote` again would deliver visible backslashes into the composer.
    if cmd.contains('\n') {
        // A launch-injected prompt keeps its paragraphs, and typing a newline at a
        // shell prompt submits the line. Bracketed paste puts the whole thing in
        // the line editor as literal text, so one Enter runs it intact. If the
        // shell has bracketed paste off this degrades to the typed behaviour —
        // never worse than `send_keys`, which is why the no-newline path is left
        // exactly as it was.
        let _ = tmux_ops.paste_text(target, &cmd);
        std::thread::sleep(std::time::Duration::from_millis(300));
        let _ = tmux_ops.send_key(target, "Enter");
    } else {
        let _ = tmux_ops.send_keys(target, &cmd);
    }

    // 6. Wait for the new agent process to actually start (pane_current_command != shell).
    //    Without this, wait_for_agent_ready may see stale ">" from old pane content
    //    and return before the new agent has even launched.
    //    Includes `node` here so Gemini/Cursor (Node/Ink TUIs) are detected immediately.
    for _ in 0..10 {
        // 10s max
        std::thread::sleep(std::time::Duration::from_secs(1));
        if let Some(cmd) = tmux_ops.pane_current_command(target) {
            let process_started =
                AGENT_COMMANDS.iter().any(|a| cmd.contains(a)) || cmd.contains("node");
            if process_started {
                break;
            }
        }
    }
}

/// Wait for an agent in a tmux pane to be ready for input.
/// Handles the bypass warning prompt (sends acceptance) during the wait.
/// Always returns Some — the prompt is always sent (better late than never).
/// Number of consecutive stable polls (1s each) before considering the agent ready.
/// 3s of no pane content changes = agent has finished loading its TUI.
const CONTENT_STABLE_THRESHOLD: u32 = 3;

/// Known first-launch dialogs that block an agent before it accepts any input,
/// paired with the keystroke that answers them.
///
/// A worktree is a brand-new directory every time, and for agents whose trust is
/// per-directory and not inherited (antigravity, cursor) these fire on most task
/// starts — the normal case, not an edge case. Claude is the exception: it
/// honours a trusted ancestor, so with the default in-project `worktree_dir` its
/// trust arm only fires where the worktree has no trusted parent (containers,
/// an out-of-project `worktree_dir`, the smoke runner). See the per-agent notes
/// on `AgentSpec::dialogs`.
/// Every agent's `Launch`-scope dialog, flattened.
///
/// Flat because `wait_for_agent_ready` is handed only a tmux target and does not
/// know which agent runs there. Attributing these at match time is strictly more
/// correct but *changes behaviour*, so it gets its own change. `Session`-scope
/// dialogs are excluded: they are matched against their own agent only, by the
/// refresh loop.
static LAUNCH_DIALOGS: std::sync::LazyLock<Vec<&'static agent::AgentDialog>> =
    std::sync::LazyLock::new(|| {
        agent::AGENT_SPECS
            .iter()
            .flat_map(|s| s.dialogs.iter())
            .filter(|d| d.scope == agent::DialogScope::Launch)
            .collect()
    });

/// The launch dialogs to match in a pane running `agent_name`.
///
/// Attributed when the agent is known, so one agent's prompt is never answered in
/// another's pane — answering sends a menu digit, and a stray "2" typed into a
/// live composer is a real corruption. Falls back to every agent's dialogs for an
/// agent agtx has no spec for, which is the historical behaviour and better than
/// leaving such a pane blocked forever.
fn launch_dialogs_for(agent_name: Option<&str>) -> Vec<&'static agent::AgentDialog> {
    match agent_name.and_then(agent::spec) {
        Some(spec) => spec
            .dialogs
            .iter()
            .filter(|d| d.scope == agent::DialogScope::Launch)
            .collect(),
        None => LAUNCH_DIALOGS.clone(),
    }
}

/// The readiness indicators to look for in a pane running `agent_name`.
///
/// Same reasoning: "Ask anything" in a Claude pane would otherwise read as
/// OpenCode being ready. Unknown agents keep the flat list.
fn active_indicators_for(agent_name: Option<&str>) -> Vec<&'static str> {
    match agent_name.and_then(agent::spec) {
        // `scoped_indicators` are added only here, where the pane's agent is
        // known. They are deliberately absent from AGENT_ACTIVE_INDICATORS: pi's
        // `%/` occurs in ordinary output, so in the flat list it would report an
        // exited claude or codex as still running.
        Some(spec) => spec
            .active_indicators
            .iter()
            .chain(spec.scoped_indicators.iter())
            .copied()
            .collect(),
        None => AGENT_ACTIVE_INDICATORS.clone(),
    }
}

/// The indicators distinctive enough to match anywhere in a pane.
///
/// The counterpart of [`scoped_indicators_for`]: the split exists because the two
/// halves need different match windows. Only [`is_agent_active`] uses the merged
/// list, and it looks at the tail either way.
fn flat_indicators_for(agent_name: Option<&str>) -> Vec<&'static str> {
    match agent_name.and_then(agent::spec) {
        Some(spec) => spec.active_indicators.to_vec(),
        None => AGENT_ACTIVE_INDICATORS.clone(),
    }
}

/// Indicators that are only meaningful at the *bottom* of the pane.
///
/// pi's `%/` is one field of its footer and also occurs in ordinary output
/// (`Coverage: 85%/90%`), so matching it against a whole capture — scrollback
/// included — finds an earlier turn's text rather than a live footer. On the
/// agent-switch path that scrollback belongs to the *previous* agent, so a stale
/// percentage would end the readiness wait before the new agent had execed.
fn scoped_indicators_for(agent_name: Option<&str>) -> &'static [&'static str] {
    agent_name
        .and_then(agent::spec)
        .map_or(&[][..], |spec| spec.scoped_indicators)
}

/// How many lines from the bottom of a capture count as "live now".
const PANE_TAIL_LINES: usize = 5;

/// Per-launch state for [`dismiss_launch_dialog`].
#[derive(Default)]
struct LaunchDialogState {
    /// Answers sent per dialog, and a hash of the pane at the last attempt.
    /// Indexed by position in [`LAUNCH_DIALOGS`], so it grows with the table
    /// rather than needing a hand-maintained size.
    attempts: Vec<(u8, u64)>,
}

/// An agent TUI that has not yet started reading stdin drops the keystrokes, so
/// a single attempt is not enough on a slow machine.
///
/// Sized to span the whole readiness budget (30 polls in step 1 + 30 in the
/// settle loop, one per second), because that is how long the agent has to
/// become ready. An earlier value of 5 exhausted itself in the first five
/// seconds of an emulated swebench container — every answer was dropped, and
/// Claude sat on the bypass warning for the rest of the run. The cap is only a
/// backstop against a pattern that matches something which is not a dialog;
/// the real guard is that a retry requires an unchanged pane.
const LAUNCH_DIALOG_MAX_ATTEMPTS: u8 = 60;

fn hash_of(content: &str) -> u64 {
    use std::hash::{Hash, Hasher};
    let mut h = std::collections::hash_map::DefaultHasher::new();
    content.hash(&mut h);
    h.finish()
}

/// Answer any `Session`-scope dialog this agent shows, visible in `content`.
///
/// Unlike the launch dialogs these are matched **only** against their own agent,
/// because the caller knows which agent occupies the pane and these prompts can
/// appear at any point in a session rather than once at startup.
fn answer_session_dialogs(
    tmux_ops: &Arc<dyn TmuxOperations>,
    target: &str,
    agent_name: &str,
    content: &str,
) {
    let Some(spec) = agent::spec(agent_name) else {
        return;
    };
    for dialog in spec
        .dialogs
        .iter()
        .filter(|d| d.scope == agent::DialogScope::Session)
    {
        if dialog.matches(content) {
            for key in dialog.answer {
                let _ = tmux_ops.send_key(target, key);
                std::thread::sleep(std::time::Duration::from_millis(100));
            }
        }
    }
}

/// Answer any known first-launch dialog visible in `content`.
///
/// Retries only while **nothing has changed** since the last attempt: an
/// unchanged pane means the keystrokes were dropped, whereas any redraw means
/// they landed and resending would type a stray "2" into the agent's live
/// composer. Capped at [`LAUNCH_DIALOG_MAX_ATTEMPTS`] so a pattern that matches
/// something which is not really a dialog cannot hammer the pane forever.
///
/// Returns true when an answer was sent.
/// The security-decision dialog visible in `content`, if any.
///
/// Detection is deliberately separate from answering: with `auto_trust` off agtx
/// still needs to *know* a trust prompt is up — that is what turns the task card
/// `Blocked` — it just does not answer it.
fn visible_security_dialog(agent_name: Option<&str>, content: &str) -> Option<&'static str> {
    launch_dialogs_for(agent_name)
        .into_iter()
        .find(|d| d.security && d.matches(content))
        .and_then(|d| d.patterns.first().copied())
}

fn dismiss_launch_dialog(
    tmux_ops: &Arc<dyn TmuxOperations>,
    target: &str,
    agent_name: Option<&str>,
    content: &str,
    state: &mut LaunchDialogState,
    auto_trust: bool,
) -> bool {
    let dialogs = launch_dialogs_for(agent_name);
    let content_hash = hash_of(content);
    if state.attempts.len() < dialogs.len() {
        state.attempts.resize(dialogs.len(), (0, 0));
    }
    for (i, dialog) in dialogs.iter().enumerate() {
        if !dialog.matches(content) {
            continue;
        }
        // Vouching for a directory, or accepting unattended tool execution, is the
        // user's call. Left alone the agent simply waits, and the task shows
        // `Blocked` with the reason — nothing is lost, because a prompt handed to
        // the process in argv is queued behind the dialog rather than eaten by it.
        if dialog.security && !auto_trust {
            continue;
        }
        let (attempts, last_hash) = state.attempts[i];
        if attempts >= LAUNCH_DIALOG_MAX_ATTEMPTS {
            continue;
        }
        // The pane redrew since the last answer — it landed; the lingering text
        // is just the previous frame. Do not send into a live composer.
        if attempts > 0 && last_hash != content_hash {
            continue;
        }
        for key in dialog.answer {
            let _ = tmux_ops.send_key(target, key);
            std::thread::sleep(std::time::Duration::from_millis(200));
        }
        state.attempts[i] = (attempts + 1, content_hash);
        return true;
    }
    false
}

fn wait_for_agent_ready(
    tmux_ops: &Arc<dyn TmuxOperations>,
    target: &str,
    agent_name: Option<&str>,
    auto_trust: bool,
) -> Option<String> {
    // Step 1: detect the ready signal (up to 30s).
    // Three detection methods, whichever fires first:
    //   1. Agent process detected via pane_current_command (Claude, Codex, Copilot)
    //   2. Known ready indicator in pane content (Gemini's "Type your message")
    //   3. Content stabilization: pane unchanged for 3s after >=3 changes (universal fallback)
    let mut last_content = String::new();
    let mut stable_ticks: u32 = 0;
    let mut change_count: u32 = 0;
    // Shared with the settle loop below so attempt counts carry across both.
    let mut dialog_state = LaunchDialogState::default();

    for _ in 0..30 {
        // 30s (30 * 1s)
        std::thread::sleep(std::time::Duration::from_secs(1));

        // A blocking dialog is checked BEFORE anything that can break out of
        // this loop. A native-binary agent (claude, grok) changes
        // `pane_current_command` to its own name the moment it execs, before it
        // has rendered anything — so Check 1 wins that race and would leave the
        // dialog standing, with the task prompt then typed into the menu.
        let content = tmux_ops.capture_pane(target).ok();
        if let Some(ref c) = content {
            if !auto_trust && visible_security_dialog(agent_name, c).is_some() {
                // Parked awaiting a human. Returning `None` is what stops the
                // caller typing the task into a menu that ignores text — the
                // failure this whole path exists to prevent. Agents on the argv
                // lane never reach here: their prompt is already queued in the
                // process and runs the moment the user answers.
                return None;
            }
            if dismiss_launch_dialog(
                tmux_ops,
                target,
                agent_name,
                c,
                &mut dialog_state,
                auto_trust,
            ) {
                // Keep looping rather than breaking: the answer may have been
                // dropped by a TUI that was not reading stdin yet, and the
                // readiness checks below would otherwise run against a pane
                // that is still showing the dialog.
                last_content = String::new();
                stable_ticks = 0;
                change_count = 0;
                continue;
            }
        }

        // Check 1: agent process detected via pane_current_command
        if !is_pane_at_shell(tmux_ops.as_ref(), target) {
            break;
        }

        // Check 2 & 3: pane content checks
        if let Some(content) = content {
            // Check 2: known ready indicator in pane content. Flat indicators
            // are distinctive enough to match anywhere; `scoped_indicators` are
            // not, so they get the same tail window `is_agent_active` uses —
            // otherwise the previous agent's scrollback answers for the new one.
            let scoped_hit = {
                let tail = pane_tail(&content, PANE_TAIL_LINES);
                scoped_indicators_for(agent_name)
                    .iter()
                    .any(|s| tail.contains(s))
            };
            if scoped_hit
                || flat_indicators_for(agent_name)
                    .iter()
                    .any(|s| content.contains(s))
            {
                break;
            }

            // Check 3: content stabilization (unchanged for 3s)
            // Only count after content has changed multiple times (>=3), so we
            // don't false-positive on shell init output (e.g. asdf notice prints
            // once, then shell pauses while loading profiles/launching agent).
            if content != last_content {
                change_count += 1;
                stable_ticks = 0;
                last_content = content;
            } else if change_count >= 3 {
                stable_ticks += 1;
                if stable_ticks >= CONTENT_STABLE_THRESHOLD {
                    return Some(target.to_string());
                }
            }
        }
    }

    // Step 2: ready signal detected — wait for pane content to stop changing (up to 30s).
    // Needed for Node/Ink agents (Gemini, Cursor) where the process starts before the
    // TUI has finished rendering. Avoids sending the prompt into a half-drawn screen.
    let mut last_content = String::new();
    let mut stable_ticks: u32 = 0;
    for _ in 0..30 {
        // 30s hard timeout
        std::thread::sleep(std::time::Duration::from_secs(1));
        if let Ok(content) = tmux_ops.capture_pane(target) {
            // The dialog can render *after* the process is detectable, so it must
            // be watched for here too — this is the case that actually bit in a
            // swebench container: claude exec'd, Check 1 broke out of step 1, and
            // the warning appeared only once we were already in this loop.
            if !auto_trust && visible_security_dialog(agent_name, &content).is_some() {
                return None;
            }
            if dismiss_launch_dialog(
                tmux_ops,
                target,
                agent_name,
                &content,
                &mut dialog_state,
                auto_trust,
            ) {
                last_content = String::new();
                stable_ticks = 0;
                continue;
            }
            if content != last_content {
                stable_ticks = 0;
                last_content = content;
            } else {
                stable_ticks += 1;
                if stable_ticks >= CONTENT_STABLE_THRESHOLD {
                    break;
                }
            }
        }
    }

    // Fixed 2s grace period after stability is detected. There is a small window
    // where the agent's prompt indicator is visible but the input buffer is not
    // yet accepting keystrokes (e.g. Claude finishing async tool registration).
    std::thread::sleep(std::time::Duration::from_secs(2));

    Some(target.to_string())
}

/// Load the workflow plugin for a task, checking agent compatibility.
/// Tries disk first (project-local → global), then falls back to bundled plugins.
fn load_task_plugin(
    task: &Task,
    project_path: Option<&Path>,
    default_agent: &str,
) -> Option<WorkflowPlugin> {
    let plugin = match &task.plugin {
        Some(name) => WorkflowPlugin::load(name, project_path)
            .ok()
            .or_else(|| skills::load_bundled_plugin(name)),
        None => skills::load_bundled_plugin("agtx"),
    };
    if let Some(ref p) = plugin {
        if !p.supports_agent(default_agent) {
            return None;
        }
    }
    plugin
}

/// Load workflow plugin if configured
fn load_plugin_if_configured(
    config: &MergedConfig,
    project_path: Option<&Path>,
) -> Option<WorkflowPlugin> {
    // For bundled plugins, always write the latest version to disk so updates ship with new releases
    if let (Some(name), Some(pp)) = (config.workflow_plugin.as_ref(), project_path) {
        if let Some((_name, _desc, content)) = skills::BUNDLED_PLUGINS
            .iter()
            .find(|(n, _, _)| *n == name.as_str())
        {
            let plugin_dir = pp.join(".agtx").join("plugins").join(name.as_str());
            let _ = std::fs::create_dir_all(&plugin_dir);
            let _ = std::fs::write(plugin_dir.join("plugin.toml"), content);
        }
    }
    config
        .workflow_plugin
        .as_ref()
        .and_then(|name| WorkflowPlugin::load(name, project_path).ok())
        .or_else(|| skills::load_bundled_plugin("agtx"))
}

/// Home directory for agent-global config that agtx writes as a trust
/// side-effect — today only Codex's `~/.codex/config.toml`.
///
/// `AGTX_AGENT_HOME` overrides `$HOME` so tests can exercise that write without
/// appending temp-dir trust entries to the real user's config, which is
/// otherwise exactly what running the suite does.
fn agent_trust_home() -> Option<PathBuf> {
    if let Ok(dir) = std::env::var("AGTX_AGENT_HOME") {
        if !dir.is_empty() {
            return Some(PathBuf::from(dir));
        }
    }
    std::env::var("HOME").ok().map(PathBuf::from)
}

/// Write skill files to a worktree's .agtx/skills/ directory and agent-native discovery paths.
/// `agent_names` determines which native paths to use (e.g. `.claude/commands/agtx/` for Claude).
/// When multiple agents are configured for different phases, skills are deployed for all of them.
/// The `agtx hook` invocation registered for one agent.
///
/// Task-agnostic: the hook reads AGTX_TASK_ID / AGTX_WORKTREE from the window
/// env. Baking the task id in breaks `skip_worktree`, where every task shares one
/// config file.
fn hook_command(agtx_bin: &str, agent: &str) -> String {
    format!("{} hook --env {}", agtx_bin, agent)
}

/// Build the `hooks` block for a worktree's `.claude/settings.local.json`.
///
/// Event names verified against claude 2.1.247. Unregistered names are ignored,
/// so listing one an older build does not know is harmless.
#[cfg(test)]
fn claude_hook_settings(agtx_bin: &str) -> serde_json::Value {
    claude_shaped_hooks(agtx_bin, "claude", agent::HookConfigKind::ClaudeSettings)
}

/// The `{Event: [{matcher, hooks: [{type, command}]}]}` shape, which four of the
/// six agents share. Where the object goes and what the events are called still
/// differ — that is `write_hook_config` and [`hook_events`].
fn claude_shaped_hooks(
    agtx_bin: &str,
    agent_name: &str,
    kind: agent::HookConfigKind,
) -> serde_json::Value {
    let base = hook_command(agtx_bin, agent_name);
    let argv_event = agent::spec(agent_name)
        .is_some_and(|s| s.hook_event_source == agent::HookEventSource::Argv);
    let mut out = serde_json::Map::new();
    for (event, matcher) in hook_status::hook_events(kind) {
        let command = if argv_event {
            format!("{} --event {}", base, event)
        } else {
            base.clone()
        };
        let mut group = serde_json::json!({
            "hooks": [{ "type": "command", "command": command }]
        });
        if let (Some(m), Some(obj)) = (matcher, group.as_object_mut()) {
            obj.insert("matcher".to_string(), serde_json::json!(m));
        }
        out.insert((*event).to_string(), serde_json::Value::Array(vec![group]));
    }
    serde_json::Value::Object(out)
}

/// Re-deploy agent configs for worktrees that were set up by a different agtx
/// binary.
///
/// The hook command and every MCP config embed an absolute path from
/// `current_exe()`. After `cargo install`, a Homebrew upgrade, or a `cargo clean`
/// following a debug-build session, those paths dangle: hooks stop reporting (the
/// board silently falls back to the pane heuristic) and the task's MCP server
/// stops resolving. Neither failure is visible.
///
/// Runs on a background thread at startup and rewrites only worktrees whose
/// marker disagrees with the running binary.
fn refresh_stale_worktree_configs(
    stale_candidates: Vec<(String, Option<String>, Vec<String>)>,
    project_path: PathBuf,
    agent_hooks: bool,
) {
    let Ok(current_bin) = std::env::current_exe() else {
        return;
    };
    let current_bin = current_bin.to_string_lossy().to_string();

    std::thread::spawn(move || {
        let mut plugin_cache: HashMap<Option<String>, Option<WorkflowPlugin>> = HashMap::new();

        for (worktree, plugin_name, agent_names) in stale_candidates {
            let wt = Path::new(&worktree);
            if !wt.exists() {
                continue;
            }
            // A missing marker means the worktree predates the marker itself, so
            // its paths cannot be verified — redeploy to be sure.
            if read_deploy_marker(wt).as_deref() == Some(current_bin.as_str()) {
                continue;
            }
            let plugin = plugin_cache
                .entry(plugin_name.clone())
                .or_insert_with(|| match &plugin_name {
                    Some(name) => WorkflowPlugin::load(name, Some(project_path.as_path()))
                        .ok()
                        .or_else(|| skills::load_bundled_plugin(name)),
                    None => skills::load_bundled_plugin("agtx"),
                })
                .clone();

            tracing::info!(
                worktree = %worktree,
                "Re-deploying agent configs: worktree was set up by a different agtx binary"
            );
            let refs: Vec<&str> = agent_names.iter().map(|s| s.as_str()).collect();
            write_skills_to_worktree(&worktree, &project_path, &plugin, &refs, agent_hooks);
        }
    });
}

/// True when a hook command is one agtx wrote, regardless of where the binary
/// lived at the time. See `merge_claude_hooks`.
fn is_agtx_hook_command(command: &str) -> bool {
    command.contains(" hook --env")
}

/// Records which agtx binary deployed a worktree's agent configs.
///
/// The absolute path from `current_exe()` is baked into the hook command and
/// every MCP config, so moving or reinstalling agtx silently breaks both for
/// worktrees deployed earlier. This marker makes the mismatch detectable in O(1)
/// per task instead of parsing seven different config formats.
const DEPLOY_MARKER: &str = ".agtx/deployed-by";

fn read_deploy_marker(worktree: &Path) -> Option<String> {
    std::fs::read_to_string(worktree.join(DEPLOY_MARKER))
        .ok()
        .map(|s| s.trim().to_string())
}

/// Compose the opening message handed to an agent at launch: the phase skill
/// command followed by the task prompt.
///
/// Same text `send_skill_and_prompt` builds for the combined-send agents, but
/// given to the process instead of typed at it.
fn compose_launch_text(skill_cmd: Option<&str>, prompt: &str) -> String {
    match (skill_cmd, prompt.trim().is_empty()) {
        (Some(cmd), false) => format!("{}\n\n{}", cmd, prompt),
        (Some(cmd), true) => cmd.to_string(),
        (None, false) => prompt.to_string(),
        (None, true) => String::new(),
    }
}

/// Environment identifying which task a tmux window belongs to.
///
/// Set on the window (tmux `-e`) so the agent — and any hook it spawns —
/// inherits it. Agent hooks are registered once with a task-agnostic command and
/// read these to know what they are reporting about, which is what lets several
/// tasks share one `.claude/settings.local.json` under `skip_worktree`.
fn agtx_task_env(task_id: &str, worktree: &str) -> Vec<(String, String)> {
    vec![
        ("AGTX_TASK_ID".to_string(), task_id.to_string()),
        ("AGTX_WORKTREE".to_string(), worktree.to_string()),
    ]
}

/// Merge agtx's hook entries into an existing `hooks` object, preserving the
/// user's own entries on the same events.
///
/// agtx's previous entries (identified by the agtx binary path in the command)
/// are dropped first, so re-running against an existing worktree replaces them
/// rather than accumulating duplicates that would fire the hook N times per event.
fn merge_claude_hooks(
    settings: &mut serde_json::Map<String, serde_json::Value>,
    ours: serde_json::Value,
) {
    let mut hooks = settings
        .get("hooks")
        .and_then(|h| h.as_object())
        .cloned()
        .unwrap_or_default();
    merge_hook_events(&mut hooks, ours);
    // Pruning to nothing removes the key rather than leaving `"hooks": {}`, so a
    // worktree with hooks turned off is byte-identical to one that never had them.
    if hooks.is_empty() {
        settings.remove("hooks");
    } else {
        settings.insert("hooks".to_string(), serde_json::Value::Object(hooks));
    }
}

/// True when a handler entry is one agtx wrote, in either shape agents accept:
/// the Claude wrapper `{hooks: [{command}]}` or cursor's flat `{command}`.
///
/// Matched on the invocation, not the binary path — the path changes when agtx is
/// moved or reinstalled, and a prefix match would then stop recognising our own
/// entries, leaving the stale one behind and appending a duplicate.
fn is_agtx_hook_entry(def: &serde_json::Value) -> bool {
    if def["command"].as_str().is_some_and(is_agtx_hook_command) {
        return true;
    }
    def["hooks"].as_array().is_some_and(|hooks| {
        hooks
            .iter()
            .any(|h| h["command"].as_str().is_some_and(is_agtx_hook_command))
    })
}

/// Replace agtx's handlers under each event in `ours`, leaving the user's own
/// entries on those events untouched and every other event alone.
///
/// An event whose `ours` value is an empty array is *pruned*: agtx's handlers are
/// stripped and nothing replaces them, and the key is dropped entirely when
/// nothing else was registered under it. That is what turning `agent_hooks` off
/// uses to unregister from a worktree that already has hooks deployed.
fn merge_hook_events(
    existing: &mut serde_json::Map<String, serde_json::Value>,
    ours: serde_json::Value,
) {
    let Some(ours) = ours.as_object() else {
        return;
    };
    for (event, our_defs) in ours {
        let mut defs: Vec<serde_json::Value> = existing
            .get(event)
            .and_then(|d| d.as_array())
            .map(|a| {
                a.iter()
                    .filter(|d| !is_agtx_hook_entry(d))
                    .cloned()
                    .collect()
            })
            .unwrap_or_default();
        if let Some(arr) = our_defs.as_array() {
            defs.extend(arr.iter().cloned());
        }
        if defs.is_empty() {
            existing.remove(event);
        } else {
            existing.insert(event.clone(), serde_json::Value::Array(defs));
        }
    }
}

fn write_skills_to_worktree(
    worktree_path: &str,
    project_path: &Path,
    plugin: &Option<WorkflowPlugin>,
    agent_names: &[&str],
    agent_hooks: bool,
) {
    // Before anything else agtx writes here, so the files below are invisible to
    // git the moment they appear.
    exclude_agtx_files_from_git(Path::new(worktree_path));

    // Replay the project's existing trust onto this worktree, for the one agent
    // that needs it. Antigravity matches trusted paths **exactly** — no ancestor
    // inheritance at any depth — so a user who already trusted the project would
    // otherwise face a fresh prompt for every task.
    //
    // This is the right call site for both paths: worktree creation *and* an agent
    // switch land here, and with a multi-agent config the switched-in agent sees
    // the worktree for the first time at switch time, not at creation.
    //
    // It never grants trust that does not already exist — `seed_from_project` is a
    // no-op unless the project root is in the agent's own store. See
    // `agent::trust`.
    if let Some(home) = agent_trust_home() {
        for agent_name in agent_names {
            if !agent::trust::needs_seeding(agent_name) {
                continue;
            }
            let _ = agent::trust::seed_from_project(
                agent_name,
                project_path,
                Path::new(worktree_path),
                &home,
            );
        }
    }

    let agtx_dir = Path::new(worktree_path).join(".agtx");
    let _ = std::fs::create_dir_all(&agtx_dir);

    // Write canonical .agtx/skills/ directory
    let skills_dir = agtx_dir.join("skills");
    if let Some(ref p) = plugin {
        // Copy skills from plugin directory, falling back to built-in defaults
        if let Some(plugin_dir) = WorkflowPlugin::plugin_dir(&p.name, Some(project_path)) {
            for (skill_name, default_content) in skills::BUILTIN_SKILLS {
                let src = plugin_dir.join(skill_name).join("SKILL.md");
                let dst_dir = skills_dir.join(skill_name);
                let _ = std::fs::create_dir_all(&dst_dir);
                if src.exists() {
                    let _ = std::fs::copy(&src, dst_dir.join("SKILL.md"));
                } else {
                    let _ = std::fs::write(dst_dir.join("SKILL.md"), default_content);
                }
            }
        } else {
            // Plugin dir not found, write defaults
            for (skill_name, skill_content) in skills::BUILTIN_SKILLS {
                let skill_dir = skills_dir.join(skill_name);
                let _ = std::fs::create_dir_all(&skill_dir);
                let _ = std::fs::write(skill_dir.join("SKILL.md"), skill_content);
            }
        }
    } else {
        // Write built-in default skills
        for (skill_name, skill_content) in skills::BUILTIN_SKILLS {
            let skill_dir = skills_dir.join(skill_name);
            let _ = std::fs::create_dir_all(&skill_dir);
            let _ = std::fs::write(skill_dir.join("SKILL.md"), skill_content);
        }
    }

    // Write project-scoped MCP server config for each configured agent.
    // Use the project root path (not the worktree path) so the MCP server opens
    // the correct project DB where tasks are stored.
    let agtx_bin = std::env::current_exe()
        .unwrap_or_else(|_| std::path::PathBuf::from("agtx"))
        .to_string_lossy()
        .to_string();
    let project_path_str = project_path.to_string_lossy().to_string();
    // Marker for the startup drift check; see DEPLOY_MARKER.
    let _ = std::fs::write(Path::new(worktree_path).join(DEPLOY_MARKER), &agtx_bin);
    for agent_name in agent_names {
        if let Some(spec) = agent::spec(agent_name) {
            write_mcp_config(spec, worktree_path, &project_path_str, &agtx_bin);
            // After the MCP writer, never before: two agents keep their hooks in
            // the same file as their MCP config, and both writers
            // read-modify-write it. Called even when hooks are off, so a worktree
            // deployed with them on gets them removed rather than left firing.
            write_hook_config(spec, worktree_path, &agtx_bin, agent_hooks);
        }
    }

    // Write to agent-native discovery paths (e.g. .claude/commands/agtx/)
    // Deploy for all configured agents so skills are available across phase transitions
    for agent_name in agent_names {
        let Some(spec) = agent::spec(agent_name) else {
            continue;
        };
        if let Some((base_dir, namespace)) = spec.skill_dir {
            let native_dir = if namespace.is_empty() {
                Path::new(worktree_path).join(base_dir)
            } else {
                Path::new(worktree_path).join(base_dir).join(namespace)
            };
            let _ = std::fs::create_dir_all(&native_dir);

            for (skill_dir_name, default_content) in skills::BUILTIN_SKILLS {
                let content =
                    resolve_skill_content(plugin, skill_dir_name, project_path, default_content);
                write_skill_file(spec, skill_dir_name, &content, &native_dir);
            }
        }
    }
}

/// Write one agent's lifecycle-hook config into its worktree.
///
/// Selected by [`HookConfigKind`](agent::HookConfigKind); `None` means the agent
/// reports nothing and the pane-hash heuristic runs unchanged.
///
/// Every path here is inside the worktree — all six agents accept a project-local
/// hook config, so agtx never writes into `~/.codex`, `~/.gemini` or `~/.cursor`
/// and removing the worktree removes the registration.
///
/// The writers whose file is shared with an MCP config, or may be committed,
/// merge; the rest own their file and are written outright.
fn write_hook_config(spec: &agent::AgentSpec, worktree_path: &str, agtx_bin: &str, enabled: bool) {
    let Some(kind) = spec.hook_config else {
        return;
    };
    let wt = Path::new(worktree_path);
    // When hooks are off this is an *empty* set of handlers under the same event
    // names, which `merge_hook_events` reads as "strip agtx's and add nothing".
    // Skipping the call instead would leave a worktree deployed while hooks were
    // on firing `agtx hook` forever after they were turned off.
    let ours = if enabled {
        claude_shaped_hooks(agtx_bin, spec.name, kind)
    } else {
        empty_hook_events(kind)
    };

    match kind {
        // Shares `.claude/settings.local.json` with the MCP preflight keys
        // `write_mcp_config` just wrote.
        agent::HookConfigKind::ClaudeSettings => {
            merge_hooks_into_json_settings(&wt.join(".claude").join("settings.local.json"), ours);
        }
        // Same shape; `.gemini/settings.json` also carries `mcpServers` and
        // `trust: true`.
        agent::HookConfigKind::GeminiSettings => {
            merge_hooks_into_json_settings(&wt.join(".gemini").join("settings.json"), ours);
        }
        // `.codex/hooks.json` is auto-discovered — no pointer in
        // `.codex/config.toml`, whose `hooks` key is a table, not a path;
        // assigning a string to it makes codex reject the entire config with
        // "invalid type: string, expected struct HooksToml" and lose its MCP
        // server with it. The events sit under a `hooks` object beside an
        // optional `description`. codex-cli 0.144.5.
        agent::HookConfigKind::CodexHooksJson => {
            let dir = wt.join(".codex");
            let _ = std::fs::create_dir_all(&dir);
            let path = dir.join("hooks.json");
            let mut root = read_json_object(&path);
            let mut hooks = root
                .get("hooks")
                .and_then(|v| v.as_object().cloned())
                .unwrap_or_default();
            merge_hook_events(&mut hooks, ours);
            if hooks.is_empty() {
                root.remove("hooks");
            } else {
                root.entry("description".to_string())
                    .or_insert_with(|| serde_json::json!("agtx phase status"));
                root.insert("hooks".to_string(), serde_json::Value::Object(hooks));
            }
            write_json(&path, &serde_json::Value::Object(root));
        }
        // `{version, hooks: {event: [{command}]}}`. The one agent that does not
        // take the Claude-shaped `{hooks: [{type, command}]}` wrapper — its
        // handlers are a flat list of `{command}`, and written the other way the
        // file parses, loads, and fires nothing. cursor-agent 2026.08.25.
        agent::HookConfigKind::CursorHooksJson => {
            let command = hook_command(agtx_bin, spec.name);
            let mut ours = serde_json::Map::new();
            for (event, _) in hook_status::hook_events(kind) {
                let defs = if enabled {
                    serde_json::json!([{ "command": command }])
                } else {
                    serde_json::json!([])
                };
                ours.insert((*event).to_string(), defs);
            }
            // Merges, like every other writer whose file the project may ship. A
            // worktree is a full checkout, so a repo that tracks
            // `.cursor/hooks.json` has it here — and clobbering it would both
            // destroy the user's hooks and leave a modified tracked file on the
            // task branch for the agent to commit. `.cursor` is not in
            // AGENT_CONFIG_DIRS either, so the diff view would not hide it.
            let dir = wt.join(".cursor");
            let _ = std::fs::create_dir_all(&dir);
            let path = dir.join("hooks.json");
            let mut root = read_json_object(&path);
            let mut hooks = root
                .get("hooks")
                .and_then(|v| v.as_object().cloned())
                .unwrap_or_default();
            merge_hook_events(&mut hooks, serde_json::Value::Object(ours));
            if hooks.is_empty() {
                root.remove("hooks");
            } else {
                root.insert("version".to_string(), serde_json::json!(1));
                root.insert("hooks".to_string(), serde_json::Value::Object(hooks));
            }
            write_json(&path, &serde_json::Value::Object(root));
        }
        // Grok scans the directory, so agtx owns one file in it and never merges.
        agent::HookConfigKind::GrokHooksJson => {
            let dir = wt.join(".grok").join("hooks");
            let _ = std::fs::create_dir_all(&dir);
            write_json(
                &dir.join("agtx.json"),
                &serde_json::json!({ "hooks": ours }),
            );
        }
        // Keyed by hook *name* first, event second; every handler carries its own
        // `--event` because the payload has no event name. `.agents/` is
        // vendor-neutral and may be committed, so this merges.
        agent::HookConfigKind::AntigravityHooksJson => {
            let dir = wt.join(".agents");
            let _ = std::fs::create_dir_all(&dir);
            let path = dir.join("hooks.json");
            let mut root = read_json_object(&path);
            // Keyed by hook name, so agtx owns one key and pruning is a removal
            // rather than a per-event filter.
            if enabled {
                root.insert(
                    AGTX_HOOK_NAME.to_string(),
                    antigravity_hook_spec(agtx_bin, spec, kind),
                );
            } else {
                root.remove(AGTX_HOOK_NAME);
            }
            write_json(&path, &serde_json::Value::Object(root));
        }
    }
}

/// The same event keys with no handlers, which `merge_hook_events` prunes.
fn empty_hook_events(kind: agent::HookConfigKind) -> serde_json::Value {
    let mut out = serde_json::Map::new();
    for (event, _) in hook_status::hook_events(kind) {
        out.insert((*event).to_string(), serde_json::json!([]));
    }
    serde_json::Value::Object(out)
}

/// The name agtx registers its hooks under, where the format is keyed by name.
const AGTX_HOOK_NAME: &str = "agtx";

/// Antigravity's per-event handlers, each carrying its own `--event`.
///
/// Its two event shapes are not interchangeable: tool events are grouped under a
/// `matcher`, the rest are a flat list of handlers, and the wrong shape is
/// silently ignored.
fn antigravity_hook_spec(
    agtx_bin: &str,
    spec: &agent::AgentSpec,
    kind: agent::HookConfigKind,
) -> serde_json::Value {
    let handler = |event: &str| {
        let base = hook_command(agtx_bin, spec.name);
        // `--event` only where the agent's payload carries no event name. Read
        // from the spec rather than assumed, so an agent that later needs the
        // same treatment gets it by setting one field.
        let command = match spec.hook_event_source {
            agent::HookEventSource::Argv => format!("{} --event {}", base, event),
            agent::HookEventSource::Payload => base,
        };
        serde_json::json!({ "type": "command", "command": command })
    };
    let mut out = serde_json::Map::new();
    for (event, matcher) in hook_status::hook_events(kind) {
        let entry = match matcher {
            Some(m) => serde_json::json!([{ "matcher": m, "hooks": [handler(event)] }]),
            None => serde_json::json!([handler(event)]),
        };
        out.insert((*event).to_string(), entry);
    }
    serde_json::Value::Object(out)
}

/// Read a JSON file as an object, or an empty one if it is missing or not an
/// object. Never an error: a config the user can fix is not a reason to refuse to
/// set up their worktree.
fn read_json_object(path: &Path) -> serde_json::Map<String, serde_json::Value> {
    std::fs::read_to_string(path)
        .ok()
        .and_then(|raw| serde_json::from_str::<serde_json::Value>(&raw).ok())
        .and_then(|v| v.as_object().cloned())
        .unwrap_or_default()
}

fn write_json(path: &Path, value: &serde_json::Value) {
    let _ = std::fs::write(
        path,
        serde_json::to_string_pretty(value).unwrap_or_default(),
    );
}

/// Merge agtx's hooks into a settings file it shares with other keys.
fn merge_hooks_into_json_settings(path: &Path, ours: serde_json::Value) {
    if let Some(parent) = path.parent() {
        let _ = std::fs::create_dir_all(parent);
    }
    let mut settings = read_json_object(path);
    merge_claude_hooks(&mut settings, ours);
    write_json(path, &serde_json::Value::Object(settings));
}

/// Insert agtx's entry into a `mcpServers` JSON file without disturbing the rest.
///
/// Shared by the two `…Merge` JSON kinds (antigravity, pi), which differ only in
/// directory and filename: their file is vendor-neutral or written back by the
/// agent's own tooling, so the project's other servers — and any sibling
/// top-level keys — have to survive. A missing or unparseable file starts from an
/// empty object rather than failing, on the same best-effort footing as the rest
/// of worktree setup.
fn merge_mcp_servers_json(dir: &Path, filename: &str, agtx_bin: &str, project_path_str: &str) {
    let _ = std::fs::create_dir_all(dir);
    let path = dir.join(filename);
    let mut root = std::fs::read_to_string(&path)
        .ok()
        .and_then(|s| serde_json::from_str::<serde_json::Value>(&s).ok())
        .filter(|v| v.is_object())
        .unwrap_or_else(|| serde_json::json!({}));
    if !root["mcpServers"].is_object() {
        root["mcpServers"] = serde_json::json!({});
    }
    root["mcpServers"]["agtx"] = serde_json::json!({
        "command": agtx_bin,
        "args": ["mcp-serve", project_path_str]
    });
    let _ = std::fs::write(
        &path,
        serde_json::to_string_pretty(&root).unwrap_or_default(),
    );
}

/// Write the project-scoped MCP server config for one agent into its worktree.
///
/// Selected by [`McpConfigKind`](agent::McpConfigKind) rather than agent name.
/// The variants are genuinely seven, not one parameterised writer: the formats
/// differ (JSON vs TOML, `mcpServers` vs `mcp_servers` vs `mcp`), two must
/// **merge** rather than overwrite because their file may already be tracked in
/// the repo, and two carry a side-effect beyond the config file itself — so the
/// `…Merge` names mark where clobbering a user's file is the failure mode.
///
/// `project_path_str` is the *project root*, not the worktree, so the server
/// opens the project DB where tasks actually live.
fn write_mcp_config(
    spec: &agent::AgentSpec,
    worktree_path: &str,
    project_path_str: &str,
    agtx_bin: &str,
) {
    let Some(kind) = spec.mcp_config else {
        return;
    };
    match kind {
        agent::McpConfigKind::ClaudeJson => {
            let cfg = serde_json::json!({
                "mcpServers": {
                    "agtx": { "command": agtx_bin, "args": ["mcp-serve", &project_path_str] }
                }
            });
            let _ = std::fs::write(
                Path::new(worktree_path).join(".mcp.json"),
                serde_json::to_string_pretty(&cfg).unwrap_or_default(),
            );
            // Merge into any existing settings rather than replacing them:
            // `.claude` is in AGENT_CONFIG_DIRS, so a project that ships its own
            // settings.local.json has it copied into every worktree, and a plain
            // write would silently drop the user's permissions/env/hooks.
            // Same merge-don't-overwrite rule the grok and antigravity writers follow.
            let claude_dir = Path::new(worktree_path).join(".claude");
            let _ = std::fs::create_dir_all(&claude_dir);
            let settings_path = claude_dir.join("settings.local.json");
            let mut settings = std::fs::read_to_string(&settings_path)
                .ok()
                .and_then(|raw| serde_json::from_str::<serde_json::Value>(&raw).ok())
                .filter(|v| v.is_object())
                .unwrap_or_else(|| serde_json::json!({}));

            if let Some(obj) = settings.as_object_mut() {
                // Pre-trust the agtx MCP server so Claude doesn't show an interactive
                // trust dialog when the agent window opens for the first time.
                obj.insert(
                    "enableAllProjectMcpServers".to_string(),
                    serde_json::json!(true),
                );
                // agtx always launches Claude with --dangerously-skip-permissions, and
                // since Claude Code ~2.1 that mode is gated behind an interactive
                // "Yes, I accept" dialog. A worktree is a brand-new directory every
                // time, so without this the agent parks on that dialog and the task
                // prompt is typed into the menu. (IS_SANDBOX=1 covers only the
                // separate root-user check, not this one.)
                //
                // Note this is a *settings* key, so unlike `hasTrustDialogAccepted`
                // (a ~/.claude.json project record) a worktree-local file is enough.
                obj.insert(
                    "skipDangerousModePermissionPrompt".to_string(),
                    serde_json::json!(true),
                );
            }
            let _ = std::fs::write(
                &settings_path,
                serde_json::to_string_pretty(&settings).unwrap_or_default(),
            );
        }
        agent::McpConfigKind::CodexToml => {
            let toml = format!(
                "[mcp_servers.agtx]\ncommand = \"{}\"\nargs = [\"mcp-serve\", \"{}\"]\n",
                agtx_bin, project_path_str
            );
            let dir = Path::new(worktree_path).join(".codex");
            let _ = std::fs::create_dir_all(&dir);
            let _ = std::fs::write(dir.join("config.toml"), toml);

            // No `[projects."<worktree>"] trust_level = "trusted"` entry is
            // written into the user's global ~/.codex/config.toml. Measured
            // against codex 0.144.5: codex resolves trust to the **git
            // repository root** — its own dialog says so, "You're in a
            // subdirectory of a Git project. Trusting will apply to the
            // repository root." With only the root trusted, a worktree beneath
            // it shows no dialog *and* loads its own .codex/config.toml, and
            // `/mcp` lists agtx either way. A per-worktree entry buys nothing
            // and accumulates one line per worktree in the user's config.
            //
            // That leaves the case where the user never trusted the project at
            // all. It is a decision for them, surfaced rather than made here —
            // see `agent_trust`.
        }
        agent::McpConfigKind::GeminiJson => {
            // Merge, don't overwrite. `.gemini` is in AGENT_CONFIG_DIRS, so a
            // project shipping its own settings.json has it copied into every
            // worktree, and a plain write drops the user's theme, model and any
            // `mcpServers` besides agtx. Same rule as the Claude writer above.
            let dir = Path::new(worktree_path).join(".gemini");
            let _ = std::fs::create_dir_all(&dir);
            let path = dir.join("settings.json");
            let mut settings = read_json_object(&path);
            let mut servers = settings
                .get("mcpServers")
                .and_then(|v| v.as_object().cloned())
                .unwrap_or_default();
            servers.insert(
                "agtx".to_string(),
                serde_json::json!({
                    "command": agtx_bin,
                    "args": ["mcp-serve", &project_path_str],
                    "trust": true
                }),
            );
            settings.insert("mcpServers".to_string(), serde_json::Value::Object(servers));
            write_json(&path, &serde_json::Value::Object(settings));
        }
        agent::McpConfigKind::CursorJson => {
            let cfg = serde_json::json!({
                "mcpServers": {
                    "agtx": { "command": agtx_bin, "args": ["mcp-serve", &project_path_str] }
                }
            });
            let dir = Path::new(worktree_path).join(".cursor");
            let _ = std::fs::create_dir_all(&dir);
            let _ = std::fs::write(
                dir.join("mcp.json"),
                serde_json::to_string_pretty(&cfg).unwrap_or_default(),
            );
        }
        agent::McpConfigKind::GrokTomlMerge => {
            // Grok reads project-scoped MCP servers from .grok/config.toml (TOML, not JSON),
            // walking from the worktree up to the git root.
            let esc = |v: &str| v.replace('\\', "\\\\").replace('"', "\\\"");
            let cfg = format!(
                "[mcp_servers.agtx]\ncommand = \"{}\"\nargs = [\"mcp-serve\", \"{}\"]\n",
                esc(&agtx_bin),
                esc(&project_path_str)
            );
            let dir = Path::new(worktree_path).join(".grok");
            let _ = std::fs::create_dir_all(&dir);
            // A repo may already ship a .grok/config.toml — append the agtx table
            // instead of clobbering the project's own settings.
            let path = dir.join("config.toml");
            let existing = std::fs::read_to_string(&path).unwrap_or_default();
            if !existing.contains("[mcp_servers.agtx]") {
                let merged = if existing.trim().is_empty() {
                    cfg
                } else {
                    format!("{}\n\n{}", existing.trim_end(), cfg)
                };
                let _ = std::fs::write(&path, merged);
            }
        }
        agent::McpConfigKind::AntigravityJsonMerge => {
            // Antigravity reads workspace MCP servers from .agents/mcp_config.json
            // (JSON, `mcpServers`). `.agents/` is vendor-neutral and may already be
            // tracked in the repo, so merge the agtx entry into any existing file
            // instead of clobbering the project's own servers.
            merge_mcp_servers_json(
                &Path::new(worktree_path).join(".agents"),
                "mcp_config.json",
                &agtx_bin,
                &project_path_str,
            );
        }
        agent::McpConfigKind::PiJsonMerge => {
            // pi itself has no MCP client; the `pi-mcp-adapter` package provides
            // one and reads `.pi/mcp.json` as its highest-precedence project
            // layer, in the standard `mcpServers` shape. Merged rather than
            // overwritten because the adapter also persists its own per-server
            // `disabled` flags into this file.
            merge_mcp_servers_json(
                &Path::new(worktree_path).join(".pi"),
                "mcp.json",
                &agtx_bin,
                &project_path_str,
            );
        }
        agent::McpConfigKind::OpenCode => {
            let cfg = serde_json::json!({
                "mcp": {
                    "agtx": {
                        "type": "local",
                        "command": [&agtx_bin, "mcp-serve", &project_path_str]
                    }
                }
            });
            let _ = std::fs::write(
                Path::new(worktree_path).join("opencode.json"),
                serde_json::to_string_pretty(&cfg).unwrap_or_default(),
            );
        }
    }
}

/// Write one skill into an agent's native discovery directory, in that agent's
/// layout.
///
/// `native_dir` is the already-created base directory (plus namespace subdir if
/// the agent uses one). Selected by [`SkillLayout`] rather than by agent name, so
/// an agent reusing an existing layout needs no code here.
///
/// This is the single implementation behind both [`deploy_skill`] and
/// [`write_skills_to_worktree`], which each carried their own copy of this branch
/// and had already drifted: the latter treated Claude's format as its `_`
/// fallback, so a future agent with a skill dir but no arm would silently get
/// Claude's `.md` layout from one and nothing from the other.
fn write_skill_file(spec: &agent::AgentSpec, skill_name: &str, content: &str, native_dir: &Path) {
    match spec.skill_layout {
        agent::SkillLayout::CommandFile => {
            let transformed = transform_skill_frontmatter(content);
            let filename = skills::skill_dir_to_filename(skill_name, spec.name);
            let _ = std::fs::write(native_dir.join(&filename), transformed);
        }
        agent::SkillLayout::GeminiToml => {
            let description = skills::extract_description(content)
                .unwrap_or_else(|| format!("agtx {} skill", skill_name));
            let toml_content = skills::skill_to_gemini_toml(&description, content);
            let filename = skills::skill_dir_to_filename(skill_name, spec.name);
            let _ = std::fs::write(native_dir.join(&filename), toml_content);
        }
        agent::SkillLayout::SkillDir => {
            let skill_subdir = native_dir.join(skill_name);
            let _ = std::fs::create_dir_all(&skill_subdir);
            let _ = std::fs::write(skill_subdir.join("SKILL.md"), content);
        }
        agent::SkillLayout::OpenCodeFlat => {
            let oc_content = transform_skill_for_opencode(content);
            let filename = skills::skill_dir_to_filename(skill_name, spec.name);
            let _ = std::fs::write(native_dir.join(&filename), oc_content);
        }
    }
}

/// Deploy a single skill to a target directory for the given agent.
/// Writes both the canonical `.agtx/skills/` copy and the agent-native discovery path.
fn deploy_skill(target_dir: &Path, skill_name: &str, content: &str, agent_name: &str) {
    // Write canonical copy
    let canonical_dir = target_dir.join(".agtx/skills").join(skill_name);
    let _ = std::fs::create_dir_all(&canonical_dir);
    let _ = std::fs::write(canonical_dir.join("SKILL.md"), content);

    // Write to agent-native discovery path
    let Some(spec) = agent::spec(agent_name) else {
        return;
    };
    if let Some((base_dir, namespace)) = spec.skill_dir {
        let native_dir = if namespace.is_empty() {
            target_dir.join(base_dir)
        } else {
            target_dir.join(base_dir).join(namespace)
        };
        let _ = std::fs::create_dir_all(&native_dir);
        write_skill_file(spec, skill_name, content, &native_dir);
    }
}

/// Transform YAML frontmatter `name: agtx-plan` → `name: agtx:plan` for agent commands
fn transform_skill_frontmatter(content: &str) -> String {
    if let Some(start) = content.find("name: agtx-") {
        let after_name = &content[start + 6..]; // after "name: "
        if let Some(newline) = after_name.find('\n') {
            let old_name = after_name[..newline].trim();
            let new_name = skills::skill_name_to_command(old_name);
            return content.replacen(
                &format!("name: {}", old_name),
                &format!("name: {}", new_name),
                1,
            );
        }
    }
    content.to_string()
}

/// Transform skill content for OpenCode: strip frontmatter, keep as .md
/// OpenCode uses flat command files and hyphen-separated names (no colon namespace)
fn transform_skill_for_opencode(content: &str) -> String {
    // OpenCode commands use description frontmatter + prompt body
    let description =
        skills::extract_description(content).unwrap_or_else(|| "agtx skill".to_string());
    let body = skills::strip_frontmatter(content);
    format!("---\ndescription: \"{}\"\n---\n{}", description, body)
}

/// Resolve skill content: check plugin override, then fall back to default
fn resolve_skill_content(
    plugin: &Option<WorkflowPlugin>,
    skill_name: &str,
    project_path: &Path,
    default: &str,
) -> String {
    if let Some(ref p) = plugin {
        if let Some(plugin_dir) = WorkflowPlugin::plugin_dir(&p.name, Some(project_path)) {
            let src = plugin_dir.join(skill_name).join("SKILL.md");
            if src.exists() {
                if let Ok(content) = std::fs::read_to_string(&src) {
                    return content;
                }
            }
        }
    }
    default.to_string()
}

#[cfg(test)]
#[path = "app_tests.rs"]
mod tests;

/// The fields a trust prompt is asking permission for, with their values.
///
/// These are exactly the three `App::new` strips from an untrusted project, and
/// the prompt shows them verbatim: consenting to a script you cannot see is not
/// consent. Order is fixed so the dialog does not reshuffle between launches.
fn dangerous_fields(config: &ProjectConfig) -> Vec<(&'static str, String)> {
    [
        ("init_script", config.init_script.as_ref()),
        ("cleanup_script", config.cleanup_script.as_ref()),
        ("copy_files", config.copy_files.as_ref()),
    ]
    .into_iter()
    .filter_map(|(name, value)| value.map(|v| (name, v.clone())))
    .collect()
}

/// Draw the config editor: sections down the left, the selected section's
/// fields on the right, and the selected field's help line at the bottom.
///
/// The help line is where a setting that only affects *new* worktrees says so,
/// rather than leaving the user to discover that the change looked like it
/// applied and did not.
fn draw_config_editor(
    state: &AppState,
    editor: &super::config_editor::ConfigEditor,
    frame: &mut Frame,
    area: Rect,
) {
    // Size to the content rather than to a percentage of the screen: a fixed
    // 72x78% box left everything huddled in the top-left corner of a mostly
    // empty dialog. Measured across *all* sections so switching tabs does not
    // resize the box under the cursor.
    let popup_area = config_editor_area(editor, area);
    frame.render_widget(Clear, popup_area);

    let selected = hex_to_color(&state.config.theme.color_selected);
    let text_color = hex_to_color(&state.config.theme.color_text);
    let dimmed = hex_to_color(&state.config.theme.color_dimmed);
    let accent = hex_to_color(&state.config.theme.color_accent);
    let desc = hex_to_color(&state.config.theme.color_description);

    let dirty_marker = if editor.dirty { " ●" } else { "" };
    let block = Block::default()
        .title(format!(" Configuration{dirty_marker} "))
        .borders(Borders::ALL)
        .border_style(Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)));
    let inner = block.inner(popup_area);
    frame.render_widget(block, popup_area);

    let rows = Layout::default()
        .direction(Direction::Vertical)
        .constraints([
            Constraint::Length(1), // section tabs
            Constraint::Min(3),    // fields
            Constraint::Length(2), // help
            Constraint::Length(1), // footer
        ])
        .split(inner);

    // --- section tabs ---
    let mut tab_spans: Vec<Span<'static>> = vec![Span::raw(" ".to_string())];
    for (i, section) in editor.sections.iter().enumerate() {
        let style = if i == editor.section {
            Style::default().fg(selected).add_modifier(Modifier::BOLD)
        } else {
            Style::default().fg(dimmed)
        };
        tab_spans.push(Span::styled(section.title.to_string(), style));
        if i + 1 < editor.sections.len() {
            tab_spans.push(Span::styled(
                "  ·  ".to_string(),
                Style::default().fg(dimmed),
            ));
        }
    }
    frame.render_widget(Paragraph::new(Line::from(tab_spans)), rows[0]);

    // --- fields ---
    let label_width = editor
        .current_section()
        .fields
        .iter()
        .map(|f| f.label.len())
        .max()
        .unwrap_or(12)
        .max(12);

    let mut lines: Vec<Line<'static>> = Vec::new();
    for (i, field) in editor.current_section().fields.iter().enumerate() {
        let is_selected = i == editor.field;
        let marker = if is_selected { " > " } else { "   " };
        let label_style = if is_selected {
            Style::default().fg(selected).add_modifier(Modifier::BOLD)
        } else {
            Style::default().fg(text_color)
        };

        let mut spans = vec![
            Span::styled(marker.to_string(), label_style),
            Span::styled(format!("{:<label_width$}  ", field.label), label_style),
        ];

        let editing_here = is_selected.then_some(editor.editing.as_ref()).flatten();
        match (&field.kind, editing_here) {
            // A text or colour field open for typing shows a caret.
            (_, Some(super::config_editor::EditState::Text(input))) => {
                spans.push(Span::styled(
                    format!("{}▏", input.as_str()),
                    Style::default().fg(accent).add_modifier(Modifier::BOLD),
                ));
            }
            (FieldKind::Toggle, _) => {
                let on = editor.value(field.id).as_bool();
                spans.push(Span::styled(
                    if on { "[x] on" } else { "[ ] off" }.to_string(),
                    Style::default().fg(if on { accent } else { dimmed }),
                ));
            }
            (FieldKind::Color, _) => {
                let value = editor.value(field.id);
                let hex = value.as_text().to_string();
                // The swatch is the point: a hex string is not a colour anyone
                // can read off the page.
                spans.push(Span::styled(
                    "███ ".to_string(),
                    Style::default().fg(hex_to_color(&hex)),
                ));
                spans.push(Span::styled(hex, Style::default().fg(text_color)));
            }
            (kind, _) => {
                let value = editor.value(field.id);
                let raw = value.as_text();
                let shown = match kind {
                    FieldKind::Choice(choices) => choices
                        .iter()
                        .find(|c| c.value == raw)
                        .map(|c| c.label.clone())
                        .unwrap_or_else(|| raw.to_string()),
                    _ if raw.is_empty() => "(unset)".to_string(),
                    _ => raw.to_string(),
                };
                let style = if raw.is_empty() {
                    Style::default().fg(dimmed)
                } else {
                    Style::default().fg(text_color)
                };
                spans.push(Span::styled(shown, style));
            }
        }
        lines.push(Line::from(spans));
    }

    // Keep the selected row on screen without a scrollbar's worth of machinery:
    // the field list is short and the cursor moves one row at a time.
    let viewport = rows[1].height as usize;
    let offset = editor.field.saturating_sub(viewport.saturating_sub(1));
    frame.render_widget(
        Paragraph::new(Text::from(lines)).scroll((offset as u16, 0)),
        rows[1],
    );

    // --- help / status ---
    let help = editor
        .current_field()
        .map(|f| f.help.to_string())
        .unwrap_or_default();
    let mut help_lines = vec![Line::from(Span::styled(
        format!(" {help}"),
        Style::default().fg(desc),
    ))];
    if let Some(ref status) = editor.status {
        help_lines.push(Line::from(Span::styled(
            format!(" {status}"),
            Style::default().fg(Color::Yellow),
        )));
    }
    frame.render_widget(Paragraph::new(Text::from(help_lines)), rows[2]);

    // --- footer ---
    let footer = if editor.confirming_discard {
        " Unsaved changes. [y] discard  [s] save  [any] back ".to_string()
    } else if let Some(super::config_editor::EditState::Choice { .. }) = editor.editing {
        " [j/k] choose  [Enter] pick  [Esc] cancel ".to_string()
    } else if editor.editing.is_some() {
        " [Enter] accept  [Esc] cancel ".to_string()
    } else {
        " [h/l] section  [j/k] field  [Enter] edit  [C-s] save  [Esc] close ".to_string()
    };
    frame.render_widget(
        Paragraph::new(Line::from(Span::styled(
            footer,
            Style::default().fg(dimmed),
        ))),
        rows[3],
    );

    // --- open choice list, drawn over the form ---
    if let Some(super::config_editor::EditState::Choice { selected: pick }) = editor.editing {
        if let Some(FieldKind::Choice(choices)) = editor.current_field().map(|f| &f.kind) {
            let height = (choices.len() as u16 + 2).min(rows[1].height.max(3));
            // Anchor under the *value* column and one row below the field, so
            // the list reads as a dropdown from the thing it is replacing
            // rather than covering the labels beside it.
            let value_column = 3 + label_width as u16 + 2;
            let row = (editor.field.saturating_sub(offset) as u16).saturating_add(1);
            let list_area = Rect {
                x: rows[1].x + value_column,
                y: rows[1].y + row.min(rows[1].height),
                width: rows[1]
                    .width
                    .saturating_sub(value_column + 2)
                    .min(40)
                    .max(12),
                height,
            };
            let list_area = if list_area.y + list_area.height > inner.y + inner.height {
                Rect {
                    y: (inner.y + inner.height).saturating_sub(list_area.height),
                    ..list_area
                }
            } else {
                list_area
            };
            frame.render_widget(Clear, list_area);
            let items: Vec<ListItem> = choices
                .iter()
                .enumerate()
                .map(|(i, choice)| {
                    let style = if i == pick {
                        Style::default().bg(selected).fg(Color::Black)
                    } else {
                        Style::default().fg(text_color)
                    };
                    ListItem::new(format!(" {} ", choice.label)).style(style)
                })
                .collect();
            frame.render_widget(
                List::new(items).block(
                    Block::default()
                        .borders(Borders::ALL)
                        .border_style(Style::default().fg(accent)),
                ),
                list_area,
            );
        }
    }
}

/// How wide the value column has to be for one field, in cells.
fn config_field_value_width(
    editor: &super::config_editor::ConfigEditor,
    field: &super::config_editor::Field,
) -> usize {
    use super::config_editor::FieldKind;
    match &field.kind {
        FieldKind::Toggle => "[ ] off".len(),
        // The stored value is a swatch plus the hex it names.
        FieldKind::Color => "███ #ffffff".chars().count(),
        // A choice field must fit its longest label, not just the current one:
        // the value changes as the user picks, and a box that grew mid-edit
        // would be worse than one that was always big enough.
        FieldKind::Choice(choices) => choices
            .iter()
            .map(|c| c.label.chars().count())
            .max()
            .unwrap_or(0),
        FieldKind::Text => editor
            .value(field.id)
            .as_text()
            .chars()
            .count()
            .max("(unset)".len()),
    }
}

/// The config editor's box: as small as its content allows, centred, and
/// clamped to the terminal.
fn config_editor_area(editor: &super::config_editor::ConfigEditor, area: Rect) -> Rect {
    const MARKER: usize = 3; // " > "
    const GAP: usize = 2; // between label and value
    const BORDERS: u16 = 2;
    const CHROME_ROWS: u16 = 1 /* tabs */ + 2 /* help + status */ + 1 /* footer */;

    let mut content_width = 0usize;
    let mut rows = 0usize;
    for section in &editor.sections {
        let label_width = section
            .fields
            .iter()
            .map(|f| f.label.chars().count())
            .max()
            .unwrap_or(12)
            .max(12);
        for field in &section.fields {
            let width = MARKER + label_width + GAP + config_field_value_width(editor, field);
            content_width = content_width.max(width);
            // The help line sits inside the same box, so it is part of how wide
            // the box has to be.
            content_width = content_width.max(field.help.chars().count() + 1);
        }
        rows = rows.max(section.fields.len());
    }

    // The tab strip and the footer are as long as they are, whatever the fields
    // measure.
    let tabs: usize = editor
        .sections
        .iter()
        .map(|s| s.title.chars().count())
        .sum::<usize>()
        + editor.sections.len().saturating_sub(1) * 5
        + 1;
    content_width = content_width.max(tabs);
    content_width = content_width
        .max(" [h/l] section  [j/k] field  [Enter] edit  [C-s] save  [Esc] close ".len());

    let width = (content_width as u16 + BORDERS).min(area.width.saturating_sub(4));
    let height = (rows as u16 + CHROME_ROWS + BORDERS).min(area.height.saturating_sub(2));

    Rect {
        x: area.x + area.width.saturating_sub(width) / 2,
        y: area.y + area.height.saturating_sub(height) / 2,
        width,
        height,
    }
}

/// Draw the `?` overlay: every binding, grouped, scrollable.
///
/// Two columns where the terminal is wide enough, which roughly halves the
/// height — in one column the whole reference is a tall thin strip that has to
/// be scrolled even in a large window. Falls back to one column on a narrow
/// terminal, where two would not fit side by side at all.
fn draw_help(state: &AppState, scroll: usize, frame: &mut Frame, area: Rect) {
    const PADDING: u16 = 2;
    const GUTTER: u16 = 3;

    let column_width = help::content_width() as u16;
    let chrome = 2 + PADDING * 2; // borders + padding
    let two_columns = area.width.saturating_sub(4) >= column_width * 2 + GUTTER + chrome;
    let columns = help::columns(if two_columns { 2 } else { 1 });

    let tallest = columns.iter().map(|c| c.len()).max().unwrap_or(0);
    let inner_width = if two_columns {
        column_width * 2 + GUTTER
    } else {
        column_width
    };
    let width = (inner_width + chrome).min(area.width.saturating_sub(4));
    // +2 borders, +1 footer.
    let height = (tallest as u16 + 3).min(area.height.saturating_sub(2));
    let popup_area = Rect {
        x: area.x + area.width.saturating_sub(width) / 2,
        y: area.y + area.height.saturating_sub(height) / 2,
        width,
        height,
    };
    frame.render_widget(Clear, popup_area);

    let title_color = hex_to_color(&state.config.theme.color_selected);
    let key_color = hex_to_color(&state.config.theme.color_accent);
    let text_color = hex_to_color(&state.config.theme.color_text);
    let dimmed = hex_to_color(&state.config.theme.color_dimmed);

    let block = Block::default()
        .title(" Keys ")
        .borders(Borders::ALL)
        .padding(Padding::horizontal(PADDING))
        .border_style(Style::default().fg(hex_to_color(&state.config.theme.color_popup_border)));
    let inner = block.inner(popup_area);
    frame.render_widget(block, popup_area);

    let body = Rect {
        height: inner.height.saturating_sub(1),
        ..inner
    };
    let visible = body.height as usize;
    // Never scroll past the last screenful — an overlay that can be scrolled
    // into empty space looks broken. Paced by the tallest column so the two
    // stay in step.
    let max_scroll = tallest.saturating_sub(visible);
    state.help_max_scroll.set(max_scroll);
    let scroll = scroll.min(max_scroll);

    let areas: Vec<Rect> = if two_columns {
        Layout::default()
            .direction(Direction::Horizontal)
            .constraints([
                Constraint::Length(column_width),
                Constraint::Length(GUTTER),
                Constraint::Min(0),
            ])
            .split(body)
            .to_vec()
    } else {
        vec![body]
    };

    for (index, column) in columns.iter().enumerate() {
        // The gutter is chunk 1, so the second column is chunk 2.
        let Some(target) = areas.get(if index == 0 { 0 } else { 2 }) else {
            continue;
        };
        let lines: Vec<Line<'static>> = column
            .iter()
            .skip(scroll)
            .take(visible)
            .map(|(indent, text)| {
                if !*indent {
                    return Line::from(Span::styled(
                        text.clone(),
                        Style::default()
                            .fg(title_color)
                            .add_modifier(Modifier::BOLD),
                    ));
                }
                // The key column is fixed-width in `help::rows`, so splitting on
                // it keeps the two colours aligned without measuring anything.
                let split = text.char_indices().nth(18).map_or(text.len(), |(i, _)| i);
                let (keys, action) = text.split_at(split);
                Line::from(vec![
                    Span::raw("  ".to_string()),
                    Span::styled(keys.to_string(), Style::default().fg(key_color)),
                    Span::styled(action.to_string(), Style::default().fg(text_color)),
                ])
            })
            .collect();
        frame.render_widget(Paragraph::new(Text::from(lines)), *target);
    }

    let more = if max_scroll > 0 {
        format!("  ({}/{})", scroll + 1, max_scroll + 1)
    } else {
        String::new()
    };
    let hint = if max_scroll > 0 {
        format!("[C-d/u] page  [j/k] line  [Esc] close{more}")
    } else {
        "[Esc] close".to_string()
    };
    frame.render_widget(
        Paragraph::new(Line::from(Span::styled(hint, Style::default().fg(dimmed)))),
        Rect {
            y: inner.y + inner.height.saturating_sub(1),
            height: 1,
            ..inner
        },
    );
}

/// Draw the task wizard./// Draw the task wizard.
///
/// A real `Layout` — breadcrumb, the steps already behind you, the active step,
/// a validation line — rather than one flat `Paragraph` of pre-wrapped lines.
/// The old shape meant the plugin list scrolled by hand (bottom-anchored, no
/// scrollbar) and the prompt ran edge to edge with no frame around it.
fn draw_wizard(
    state: &AppState,
    wizard: &super::wizard::WizardState,
    frame: &mut Frame,
    area: Rect,
) {
    frame.render_widget(Clear, area);

    let selected = hex_to_color(&state.config.theme.color_selected);
    let text_color = hex_to_color(&state.config.theme.color_text);
    let dimmed = hex_to_color(&state.config.theme.color_dimmed);
    let accent = hex_to_color(&state.config.theme.color_accent);

    let block = Block::default()
        .title(if wizard.is_editing() {
            " Edit Task "
        } else {
            " New Task "
        })
        .borders(Borders::ALL)
        .padding(Padding::horizontal(WIZARD_PADDING))
        .border_style(Style::default().fg(selected));
    let inner = block.inner(area);
    frame.render_widget(block, area);

    // Rows behind the cursor are read-only context; the prompt is never one of
    // them, so it is excluded rather than special-cased below.
    let steps = wizard.steps();
    let index = wizard.step_index();
    let context: Vec<(&str, String)> = steps
        .iter()
        .take(index)
        .filter_map(|step| match step {
            WizardStep::Title => Some(("Title", wizard.title.as_str().to_string())),
            WizardStep::Agent => Some((
                "Agent",
                wizard.agent_name().unwrap_or("default").to_string(),
            )),
            WizardStep::Plugin => Some(("Plugin", wizard.plugin_label().to_string())),
            WizardStep::Prompt => None,
        })
        .collect();

    // A title is one line; a prompt and a list want the room. The trailing
    // slack is what stops a short body stretching to fill the popup.
    let title_step = wizard.step() == WizardStep::Title;
    let rows = Layout::default()
        .direction(Direction::Vertical)
        .constraints([
            Constraint::Length(1),                    // breadcrumb
            Constraint::Length(1),                    // rule
            Constraint::Length(context.len() as u16), // completed steps
            Constraint::Length(if context.is_empty() { 0 } else { 1 }),
            // A title is one line; a prompt and a list take the rest.
            if title_step {
                Constraint::Length(3)
            } else {
                Constraint::Min(3)
            },
            // The validation row exists only while there is something in it.
            Constraint::Length(u16::from(wizard.validation.is_some())),
            // Slack, so a fixed-height body does not stretch to fill. A body
            // that already fills needs none, and a second `Min` here would take
            // space from it.
            if title_step {
                Constraint::Min(0)
            } else {
                Constraint::Length(0)
            },
        ])
        .split(inner);

    // --- breadcrumb ---
    let mut crumbs: Vec<Span<'static>> = Vec::new();
    for (i, step) in steps.iter().enumerate() {
        let style = if i == index {
            Style::default().fg(selected).add_modifier(Modifier::BOLD)
        } else if i < index {
            Style::default().fg(accent)
        } else {
            Style::default().fg(dimmed)
        };
        crumbs.push(Span::styled(step.label().to_string(), style));
        if i + 1 < steps.len() {
            crumbs.push(Span::styled(
                "  ›  ".to_string(),
                Style::default().fg(dimmed),
            ));
        }
    }
    frame.render_widget(Paragraph::new(Line::from(crumbs)), rows[0]);
    frame.render_widget(
        Paragraph::new(Line::from(Span::styled(
            "─".repeat(rows[1].width as usize),
            Style::default().fg(dimmed),
        ))),
        rows[1],
    );

    // --- completed steps ---
    let context_lines: Vec<Line<'static>> = context
        .into_iter()
        .map(|(label, value)| {
            Line::from(vec![
                Span::styled(format!("{label}: "), Style::default().fg(dimmed)),
                Span::styled(value, Style::default().fg(text_color)),
            ])
        })
        .collect();
    frame.render_widget(Paragraph::new(Text::from(context_lines)), rows[2]);

    // --- the active step ---
    let body = rows[4];
    match wizard.step() {
        WizardStep::Title => draw_wizard_text_field(
            "Title",
            &wizard.title,
            state,
            frame,
            body,
            "What should this task be called?",
            &HashSet::new(),
        ),
        WizardStep::Prompt => draw_wizard_text_field(
            "Prompt",
            &wizard.prompt,
            state,
            frame,
            body,
            "# files   / skills   ! tasks",
            &wizard.highlighted_references,
        ),
        WizardStep::Agent | WizardStep::Plugin => {
            if let Some(list) = wizard.current_list() {
                draw_wizard_list(wizard.step().label(), list, state, frame, body);
            }
        }
    }

    // --- validation ---
    //
    // Drawn inside the wizard rather than in the footer because the footer is
    // also the background-warning channel, and an unrelated warning must not be
    // able to replace this while the user is reading it.
    if let Some(ref message) = wizard.validation {
        frame.render_widget(
            Paragraph::new(Line::from(Span::styled(
                message.clone(),
                Style::default().fg(Color::Yellow),
            ))),
            rows[5],
        );
    }
}

/// A bordered text area with the caret anchored in it.
///
/// The caret is a real terminal cursor rather than a drawn block so the OS can
/// render IME composition (Korean, Japanese, Chinese) inline where the text
/// will land.
fn draw_wizard_text_field(
    title: &str,
    input: &TextInput,
    state: &AppState,
    frame: &mut Frame,
    area: Rect,
    hint: &str,
    highlights: &HashSet<String>,
) {
    let text_color = hex_to_color(&state.config.theme.color_text);
    let accent = hex_to_color(&state.config.theme.color_accent);
    let dimmed = hex_to_color(&state.config.theme.color_dimmed);

    let block = Block::default()
        .title(format!(" {title} "))
        .borders(Borders::ALL)
        .padding(Padding::horizontal(1))
        .border_style(Style::default().fg(accent));
    let inner = block.inner(area);
    frame.render_widget(block, area);

    if input.is_empty() {
        frame.render_widget(
            Paragraph::new(Line::from(Span::styled(
                hint.to_string(),
                Style::default().fg(dimmed),
            ))),
            inner,
        );
    } else {
        let wrap_width = inner.width as usize;
        let mut lines: Vec<Line<'static>> = Vec::new();
        for part in input.as_str().split('\n') {
            let spans: Vec<Span<'static>> = if highlights.is_empty() {
                vec![Span::styled(
                    part.to_string(),
                    Style::default().fg(text_color),
                )]
            } else {
                build_highlighted_text(part, highlights, text_color, accent)
                    .lines
                    .into_iter()
                    .flat_map(|l| l.spans)
                    .map(|s| Span::styled(s.content.into_owned(), s.style))
                    .collect()
            };
            lines.extend(wrap_spans(spans, wrap_width));
        }
        frame.render_widget(Paragraph::new(Text::from(lines)), inner);
    }

    // No prefix any more: the field's own border is the label, so the caret
    // starts at column 0 of the inner area.
    let (col, row) = wrapped_cursor_pos(input.as_str(), input.cursor, 0, inner.width as usize);
    let x = inner.x.saturating_add(col as u16);
    let y = inner.y.saturating_add(row as u16);
    if x < inner.x + inner.width && y < inner.y + inner.height {
        frame.set_cursor_position((x, y));
    }
}

/// A pick-one list with a scrollbar and, when filtering, the pattern in its
/// border.
///
/// Ratatui's own `List` does the scrolling, so the selection stays in view and
/// the scrollbar shows how much more there is.
fn draw_wizard_list(
    title: &str,
    list: &super::wizard::ListPick,
    state: &AppState,
    frame: &mut Frame,
    area: Rect,
) {
    let selected = hex_to_color(&state.config.theme.color_selected);
    let text_color = hex_to_color(&state.config.theme.color_text);
    let dimmed = hex_to_color(&state.config.theme.color_description);
    let accent = hex_to_color(&state.config.theme.color_accent);

    let block_title = match list.filter.as_ref() {
        Some(filter) => format!(" {title}  /{}▏", filter.as_str()),
        None => format!(" {title} "),
    };
    let block = Block::default()
        .title(block_title)
        .borders(Borders::ALL)
        .padding(Padding::horizontal(1))
        .border_style(Style::default().fg(accent));
    let inner = block.inner(area);
    frame.render_widget(block, area);

    let visible = list.matching();
    if visible.is_empty() {
        frame.render_widget(
            Paragraph::new(Line::from(Span::styled(
                "Nothing matches that.".to_string(),
                Style::default().fg(dimmed),
            ))),
            inner,
        );
        return;
    }

    let items: Vec<ListItem> = visible
        .iter()
        .map(|i| {
            let option = &list.options[*i];
            let is_selected = *i == list.selected;
            let name_style = if is_selected {
                Style::default().fg(selected).add_modifier(Modifier::BOLD)
            } else {
                Style::default().fg(text_color)
            };
            let mut spans = vec![
                Span::styled(
                    if is_selected { "› " } else { "  " }.to_string(),
                    name_style,
                ),
                Span::styled(
                    format!("{:<14}", truncate_str(&option.label, 14)),
                    name_style,
                ),
            ];
            if option.active {
                spans.push(Span::styled(
                    "✓ ".to_string(),
                    Style::default().fg(Color::Green),
                ));
            } else {
                spans.push(Span::raw("  ".to_string()));
            }
            spans.push(Span::styled(
                option.description.clone(),
                Style::default().fg(dimmed),
            ));
            ListItem::new(Line::from(spans))
        })
        .collect();

    let mut list_state = ListState::default().with_selected(Some(list.position()));
    frame.render_stateful_widget(List::new(items), inner, &mut list_state);

    if visible.len() > inner.height as usize {
        let mut scrollbar_state = ScrollbarState::new(visible.len()).position(list.position());
        // Inset to the rows the list actually occupies. Handed the whole `area`
        // the track starts on the block's top border and eats its corners.
        let track = Rect {
            y: area.y + 1,
            height: area.height.saturating_sub(2),
            ..area
        };
        frame.render_stateful_widget(
            Scrollbar::new(ScrollbarOrientation::VerticalRight)
                .begin_symbol(None)
                .end_symbol(None)
                .style(Style::default().fg(dimmed)),
            track,
            &mut scrollbar_state,
        );
    }
}

/// A QR module grid as ratatui lines.
///
/// `▀` splits each cell into an upper and a lower module, coloured
/// independently, so the code is square in a terminal whose cells are about
/// twice as tall as they are wide — and half as tall as one module per cell.
///
/// The colours are set explicitly, not left to the theme: a QR must be
/// dark-on-light to scan, and most terminals running agtx are the other way
/// round.
fn qr_lines(total: usize, dark: &[bool]) -> Vec<Line<'static>> {
    let at = |x: usize, y: usize| -> bool { y < total && dark[y * total + x] };
    (0..total)
        .step_by(2)
        .map(|row| {
            let spans: Vec<Span> = (0..total)
                .map(|x| {
                    let upper = at(x, row);
                    let lower = at(x, row + 1);
                    Span::styled(
                        "▀",
                        Style::default()
                            .fg(if upper { Color::Black } else { Color::White })
                            .bg(if lower { Color::Black } else { Color::White }),
                    )
                })
                .collect();
            Line::from(spans)
        })
        .collect()
}

/// Narrowest the `W` overlay may be.
///
/// Wide enough for its longest sentence: the body is drawn unwrapped, because
/// wrapping would break the QR's rows, so a narrower box truncates text rather
/// than reflowing it.
const MOBILE_POPUP_MIN_WIDTH: u16 = 64;