agentty 0.11.1

use std::borrow::Borrow;
use std::collections::VecDeque;
use std::fmt;
use std::ops::Deref;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use std::sync::{Arc, Mutex};

use serde::de::{self, Deserializer};
use serde::ser::Serializer;
use serde::{Deserialize, Serialize};
use tokio_util::sync::CancellationToken;

use super::agent::{AgentSelection, ReasoningLevel};
use crate::domain::question::QuestionItem;
use crate::domain::turn_prompt::{TurnPrompt, TurnPromptAttachment};

/// Folder name under a project root that stores Agentty session metadata.
pub const SESSION_DATA_DIR: &str = ".agentty";

/// Full in-progress loader label shown while post-turn commit-message
/// generation and git commit orchestration are running.
pub(crate) const COMMITTING_PROGRESS_LABEL: &str = "Committing...";

/// Lead sentence used when seeding a follow-on prompt from a terminal session.
const TERMINAL_CONTINUATION_PROMPT_INTRO: &str =
    "Continue the work from this previous Agentty session.";

/// Shared stable identifier for one session.
///
/// The app clones session identifiers heavily across maps, events, and worker
/// tasks. Wrapping the identifier in `Arc<str>` keeps those clones to a cheap
/// reference-count bump while still supporting borrowed `&str` lookups in
/// `HashMap<SessionId, _>`.
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct SessionId(Arc<str>);

impl SessionId {
    /// Returns the session identifier as a string slice.
    pub fn as_str(&self) -> &str {
        self.0.as_ref()
    }
}

impl AsRef<str> for SessionId {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl AsRef<Path> for SessionId {
    fn as_ref(&self) -> &Path {
        Path::new(self.as_str())
    }
}

impl Borrow<str> for SessionId {
    fn borrow(&self) -> &str {
        self.as_str()
    }
}

impl Deref for SessionId {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        self.as_str()
    }
}

impl fmt::Display for SessionId {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl From<&str> for SessionId {
    fn from(value: &str) -> Self {
        Self(Arc::<str>::from(value))
    }
}

impl From<String> for SessionId {
    fn from(value: String) -> Self {
        Self(Arc::<str>::from(value))
    }
}

impl From<Arc<str>> for SessionId {
    fn from(value: Arc<str>) -> Self {
        Self(value)
    }
}

impl From<SessionId> for String {
    fn from(value: SessionId) -> Self {
        value.as_str().to_string()
    }
}

impl PartialEq<str> for SessionId {
    fn eq(&self, other: &str) -> bool {
        self.as_str() == other
    }
}

impl PartialEq<&str> for SessionId {
    fn eq(&self, other: &&str) -> bool {
        self.as_str() == *other
    }
}

impl PartialEq<String> for SessionId {
    fn eq(&self, other: &String) -> bool {
        self.as_str() == other
    }
}

impl PartialEq<&String> for SessionId {
    fn eq(&self, other: &&String) -> bool {
        self.as_str() == other.as_str()
    }
}

impl Serialize for SessionId {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for SessionId {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        String::deserialize(deserializer)
            .map(Self::from)
            .map_err(de::Error::custom)
    }
}

/// High-level lifecycle state for one session.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Status {
    /// Session has been created but has not started its first agent turn yet.
    Draft,
    InProgress,
    Review,
    /// Session is generating focused-review output while keeping the
    /// review-oriented shortcuts available and temporarily hiding rebase.
    AgentReview,
    /// Session is waiting for model clarification responses.
    Question,
    /// Session is waiting in the merge queue for its turn to merge.
    Queued,
    Rebasing,
    Merging,
    Done,
    Canceled,
}

impl Status {
    /// Ordered list of all session statuses used for UI sizing and iteration.
    pub const ALL: [Status; 10] = [
        Status::Draft,
        Status::InProgress,
        Status::Review,
        Status::AgentReview,
        Status::Question,
        Status::Queued,
        Status::Rebasing,
        Status::Merging,
        Status::Done,
        Status::Canceled,
    ];

    /// Returns whether this status keeps the review shortcut set enabled.
    pub fn allows_review_actions(self) -> bool {
        matches!(self, Status::Review | Status::AgentReview)
    }

    /// Returns whether this status can seed a follow-on continuation session.
    pub fn allows_terminal_continuation(self) -> bool {
        matches!(self, Status::Done)
    }

    /// Returns whether this status is stable enough for a stacked draft child
    /// to materialize from the parent branch.
    pub fn allows_stacked_child_start(self) -> bool {
        self.allows_review_actions()
    }

    /// Returns whether this status represents branch work that should be the
    /// only branch-mutating operation in a one-level stack.
    pub fn is_stack_branch_mutating(self) -> bool {
        matches!(
            self,
            Status::InProgress
                | Status::Question
                | Status::Queued
                | Status::Rebasing
                | Status::Merging
        )
    }

    /// Returns whether a transition to `next` is valid.
    ///
    /// Draft-session-only guards still live on [`Session`] methods, so
    /// callers must separately prevent regular `Draft` sessions from taking
    /// the `Canceled` path. Running sessions may also move directly to
    /// `Canceled` after the UI signals the active turn's cancellation token.
    pub fn can_transition_to(self, next: Status) -> bool {
        if self == next {
            return true;
        }

        matches!(
            (self, next),
            (Status::Draft, Status::InProgress | Status::Canceled)
                | (Status::Draft | Status::InProgress, Status::Rebasing)
                | (Status::InProgress, Status::Canceled)
                | (Status::Review, Status::AgentReview)
                | (Status::AgentReview, Status::Review)
                | (
                    Status::Review | Status::AgentReview | Status::Question,
                    Status::InProgress
                        | Status::Queued
                        | Status::Rebasing
                        | Status::Merging
                        | Status::Canceled
                )
                | (Status::Review | Status::AgentReview, Status::Done)
                | (
                    Status::Queued,
                    Status::Merging | Status::Review | Status::AgentReview
                )
                | (
                    Status::InProgress | Status::Rebasing,
                    Status::Review | Status::AgentReview | Status::Question
                )
                | (
                    Status::Merging,
                    Status::Done | Status::Review | Status::AgentReview
                )
        )
    }
}

impl fmt::Display for Status {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Status::Draft => write!(f, "Draft"),
            Status::InProgress => write!(f, "InProgress"),
            Status::Review => write!(f, "Review"),
            Status::AgentReview => write!(f, "AgentReview"),
            Status::Question => write!(f, "Question"),
            Status::Queued => write!(f, "Queued"),
            Status::Rebasing => write!(f, "Rebasing"),
            Status::Merging => write!(f, "Merging"),
            Status::Done => write!(f, "Done"),
            Status::Canceled => write!(f, "Canceled"),
        }
    }
}

impl FromStr for Status {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "Draft" => Ok(Status::Draft),
            "InProgress" | "Committing" => Ok(Status::InProgress),
            "Review" => Ok(Status::Review),
            "AgentReview" => Ok(Status::AgentReview),
            "Question" => Ok(Status::Question),
            "Queued" => Ok(Status::Queued),
            "Rebasing" => Ok(Status::Rebasing),
            "Merging" => Ok(Status::Merging),
            "Done" => Ok(Status::Done),
            "Canceled" => Ok(Status::Canceled),
            _ => Err(format!("Unknown status: {s}")),
        }
    }
}

/// Size bucket derived from a session's git diff.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum SessionSize {
    #[default]
    Xs,
    S,
    M,
    L,
    Xl,
    Xxl,
}

impl SessionSize {
    /// Ordered list of all session size buckets from smallest to largest.
    pub const ALL: [SessionSize; 6] = [
        SessionSize::Xs,
        SessionSize::S,
        SessionSize::M,
        SessionSize::L,
        SessionSize::Xl,
        SessionSize::Xxl,
    ];

    /// Classifies one git diff into a session size bucket.
    pub fn from_diff(diff: &str) -> Self {
        let (added_lines, deleted_lines) = SessionStats::line_change_counts(diff);
        let changed_line_count =
            usize::try_from(added_lines.saturating_add(deleted_lines)).unwrap_or(usize::MAX);

        Self::from_changed_line_count(changed_line_count)
    }

    fn from_changed_line_count(changed_line_count: usize) -> Self {
        match changed_line_count {
            0..=10 => SessionSize::Xs,
            11..=30 => SessionSize::S,
            31..=80 => SessionSize::M,
            81..=200 => SessionSize::L,
            201..=500 => SessionSize::Xl,
            _ => SessionSize::Xxl,
        }
    }

    /// Returns a short UI label for this size bucket.
    pub fn label(self) -> &'static str {
        match self {
            SessionSize::Xs => "XS",
            SessionSize::S => "S",
            SessionSize::M => "M",
            SessionSize::L => "L",
            SessionSize::Xl => "XL",
            SessionSize::Xxl => "XXL",
        }
    }
}

impl fmt::Display for SessionSize {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.label())
    }
}

impl FromStr for SessionSize {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "XS" | "Xs" | "xs" => Ok(SessionSize::Xs),
            "S" | "s" => Ok(SessionSize::S),
            "M" | "m" => Ok(SessionSize::M),
            "L" | "l" => Ok(SessionSize::L),
            "XL" | "Xl" | "xl" => Ok(SessionSize::Xl),
            "XXL" | "Xxl" | "xxl" => Ok(SessionSize::Xxl),
            _ => Err(format!("Unknown session size: {s}")),
        }
    }
}

/// Supported forge families for persisted session review-request links.
pub use ag_forge::ForgeKind;
/// Normalized remote lifecycle state for one linked review request.
pub use ag_forge::ReviewRequestState;
/// Normalized remote summary for one linked review request.
pub use ag_forge::ReviewRequestSummary;

/// Persisted forge linkage for one session.
///
/// This wraps the normalized remote summary with the last successful refresh
/// timestamp recorded by Agentty.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ReviewRequest {
    /// Unix timestamp of the most recent successful refresh.
    pub last_refreshed_at: i64,
    /// Normalized remote summary captured at `last_refreshed_at`.
    pub summary: ReviewRequestSummary,
}

/// Session-view action currently available for manual session-branch
/// publication.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PublishBranchAction {
    /// Pushes the session branch to the configured Git remote.
    Push,
    /// Pushes the session branch and creates or refreshes the forge review
    /// request for it.
    PublishPullRequest,
}

/// Launch action currently available for one persisted follow-up task.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FollowUpTaskAction {
    /// Starts a new sibling session from the selected task text.
    Launch,
    /// Opens the already launched sibling session linked to the task.
    Open,
}

/// Auto-push state for one already-published session branch.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum PublishedBranchSyncStatus {
    /// No background sync push is currently active and the last push did not
    /// fail.
    #[default]
    Idle,
    /// A completed turn is currently pushing the published branch upstream.
    InProgress,
    /// The latest automatic push attempt updated the published branch.
    Succeeded,
    /// The latest automatic push attempt failed and left the branch stale.
    Failed,
}

/// Per-session usage and diff statistics.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct SessionStats {
    /// Added diff lines currently attributed to the session worktree.
    pub added_lines: u64,
    /// Deleted diff lines currently attributed to the session worktree.
    pub deleted_lines: u64,
    /// Input/prompt tokens consumed by this session.
    pub input_tokens: u64,
    /// Output/response tokens produced by this session.
    pub output_tokens: u64,
}

impl SessionStats {
    /// Counts added and deleted lines in one git patch while ignoring file
    /// header markers such as `+++` and `---`.
    pub fn line_change_counts(diff: &str) -> (u64, u64) {
        diff.lines()
            .fold((0_u64, 0_u64), |(added_lines, deleted_lines), line| {
                if line.starts_with('+') && !line.starts_with("+++") {
                    return (added_lines.saturating_add(1), deleted_lines);
                }

                if line.starts_with('-') && !line.starts_with("---") {
                    return (added_lines, deleted_lines.saturating_add(1));
                }

                (added_lines, deleted_lines)
            })
    }
}

/// Aggregated activity count for one day key.
///
/// `day_key` is the number of days since Unix epoch (`1970-01-01`).
/// App/session loading stores local day keys derived from immutable
/// session-creation activity history so heatmap remains visible after session
/// deletion.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct DailyActivity {
    /// Day key measured as whole days since Unix epoch.
    pub day_key: i64,
    /// Number of sessions created on the corresponding day.
    pub session_count: u32,
}

/// Persisted read-only follow-up task rendered alongside one session.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SessionFollowUpTask {
    /// Stable database identifier for the persisted follow-up task row.
    pub id: i64,
    /// Previously launched sibling session linked to this task, when one has
    /// already been created.
    pub launched_session_id: Option<SessionId>,
    /// Stable display-order position persisted for this follow-up task.
    pub position: usize,
    /// User-visible task text emitted by the agent.
    pub text: String,
}

impl SessionFollowUpTask {
    /// Returns the action the session view should expose for this task.
    pub fn action(&self) -> FollowUpTaskAction {
        if self.launched_session_id.is_some() {
            return FollowUpTaskAction::Open;
        }

        FollowUpTaskAction::Launch
    }
}
/// In-memory snapshot of one persisted session row used by the UI and app
/// orchestration layers.
pub struct Session {
    /// Agent provider and model selected for this session.
    pub agent: AgentSelection,
    /// Base branch used to create the session worktree.
    pub base_branch: String,
    /// Session creation timestamp (Unix seconds).
    pub created_at: i64,
    /// Ordered image attachments staged for the draft-session prompt stored in
    /// `prompt` while the session remains `Draft`.
    pub draft_attachments: Vec<TurnPromptAttachment>,
    /// Planned or active worktree folder path for this session.
    pub folder: PathBuf,
    /// Persisted read-only follow-up tasks emitted after the latest turn.
    pub follow_up_tasks: Vec<SessionFollowUpTask>,
    /// Stable session identifier.
    pub id: SessionId,
    /// Unix timestamp when the current active-work interval started, if the
    /// session is presently accumulating `InProgress` time.
    pub in_progress_started_at: Option<i64>,
    /// Cumulative active-work time already completed by this session, in whole
    /// seconds.
    pub in_progress_total_seconds: i64,
    /// Whether the session was created through the explicit draft workflow
    /// from the sessions list.
    pub is_draft: bool,
    /// Captured output transcript.
    pub output: String,
    /// Parent session this stacked session is based on while its parent branch
    /// remains active.
    pub parent_session_id: Option<SessionId>,
    /// Human-readable project name associated with the session.
    pub project_name: String,
    /// Initial user prompt used to create the session.
    pub prompt: String,
    /// Transcript text for each chat message queued while the active turn is
    /// running, mirrored from [`SessionHandles::queued_messages`] for render.
    pub queued_messages: Vec<String>,
    /// Session-scoped reasoning override selected through prompt slash
    /// commands.
    pub reasoning_level_override: Option<ReasoningLevel>,
    /// Upstream reference recorded after the latest successful branch publish,
    /// for example `origin/wt/session-id`.
    pub published_upstream_ref: Option<String>,
    /// Background auto-push state for the already-published upstream branch.
    pub published_branch_sync_status: PublishedBranchSyncStatus,
    /// Model clarification questions emitted by the agent.
    pub questions: Vec<QuestionItem>,
    /// Persisted forge review-request link for this session, when available.
    pub review_request: Option<ReviewRequest>,
    /// Derived size bucket computed from diff size.
    pub size: SessionSize,
    /// Token usage statistics associated with this session.
    pub stats: SessionStats,
    /// Current lifecycle status.
    pub status: Status,
    /// Optional persisted session summary text sourced from the raw agent
    /// `summary` payload, applied immediately from reducer events during
    /// review/question states and, once the session reaches `Done`,
    /// formatted with `# Summary` and `# Commit` sections using the canonical
    /// session commit message. This text is also reused as review-assist
    /// context.
    pub summary: Option<String>,
    /// Optional explicit session title.
    pub title: Option<String>,
    /// Last update timestamp (Unix seconds).
    pub updated_at: i64,
    /// Transient workflow notice block shown in the output panel without
    /// being appended to the persisted transcript.
    pub workflow_notice: Option<String>,
}

impl Session {
    /// Returns the display title for this session.
    pub fn display_title(&self) -> &str {
        self.title.as_deref().unwrap_or("No title")
    }

    /// Returns whether the session should use staged-draft behavior before
    /// its first live turn starts.
    pub fn is_draft_session(&self) -> bool {
        self.is_draft
    }

    /// Returns whether the session currently has one or more staged draft
    /// prompts waiting for an explicit start action.
    pub fn has_staged_drafts(&self) -> bool {
        self.is_draft_session() && self.status == Status::Draft && !self.prompt.is_empty()
    }

    /// Returns whether this session can create a one-level stacked draft
    /// child.
    ///
    /// Only root sessions with materialized branches can be parents in the
    /// first stacked-session version. Explicit draft sessions are excluded
    /// because their worktree branch is deferred until start, and terminal
    /// sessions no longer provide an active branch to stack on.
    pub fn allows_stacked_child_creation(&self) -> bool {
        self.parent_session_id.is_none()
            && !self.is_draft_session()
            && !matches!(self.status, Status::Done | Status::Canceled)
    }

    /// Returns whether this session belongs to a one-level stack beneath a
    /// parent session branch.
    pub fn is_stacked_child(&self) -> bool {
        self.parent_session_id.is_some()
    }

    /// Returns whether the staged draft bundle can start its first live turn.
    pub fn can_start_staged_session(&self) -> bool {
        self.is_draft_session() && self.status == Status::Draft && self.has_staged_drafts()
    }

    /// Returns whether the session can be canceled by the user.
    ///
    /// Running sessions can be canceled from the list after their active turn
    /// is signaled to stop. Review-oriented sessions remain cancelable, and
    /// unstarted draft sessions can also be canceled before they materialize a
    /// worktree.
    pub fn allows_cancel_action(&self) -> bool {
        self.status == Status::InProgress
            || self.status.allows_review_actions()
            || (self.status == Status::Draft && self.is_draft_session())
    }

    /// Returns whether this terminal session can launch a seeded follow-on
    /// session from view mode.
    pub fn allows_terminal_continuation(&self) -> bool {
        self.status.allows_terminal_continuation()
    }

    /// Returns one seeded first-prompt body for a follow-on session launched
    /// from a terminal session view.
    pub fn continuation_prompt_seed(&self) -> Option<String> {
        if !self.allows_terminal_continuation() {
            return None;
        }

        let (context_label, context_text) = self.continuation_context()?;

        Some(format!(
            "{TERMINAL_CONTINUATION_PROMPT_INTRO}\n\nPrevious session: {}\nProject: {}\nStatus: \
             {}\n\n{context_label}:\n{context_text}\n",
            self.display_title(),
            self.project_name,
            self.status,
        ))
    }

    /// Returns whether session chat should render the cumulative active-work
    /// timer for this session.
    pub fn has_in_progress_timer(&self) -> bool {
        self.in_progress_total_seconds > 0 || self.in_progress_started_at.is_some()
    }

    /// Returns the reasoning level that will be used for the next turn.
    pub fn effective_reasoning_level(
        &self,
        default_reasoning_level: ReasoningLevel,
    ) -> ReasoningLevel {
        self.reasoning_level_override
            .unwrap_or(default_reasoning_level)
    }

    /// Returns whether this session currently inherits the project default
    /// reasoning level.
    pub fn uses_default_reasoning_level(&self) -> bool {
        self.reasoning_level_override.is_none()
    }

    /// Returns cumulative active-work time including any open `InProgress`
    /// interval measured at `wall_clock_unix_seconds`.
    pub fn in_progress_duration_seconds(&self, wall_clock_unix_seconds: i64) -> i64 {
        let open_interval_seconds = self.in_progress_started_at.map_or(0, |started_at| {
            wall_clock_unix_seconds.saturating_sub(started_at).max(0)
        });

        self.in_progress_total_seconds
            .saturating_add(open_interval_seconds)
    }

    /// Returns a short forge indicator suffix for the session list status
    /// column.
    ///
    /// The indicator reflects the most specific known forge state:
    /// - `↑` when the branch was pushed but no review request is linked.
    /// - `⊙ #N` when a linked review request is open.
    /// - `✓ #N` when a linked review request was merged.
    /// - `✗ #N` when a linked review request was closed without merge.
    /// - Empty when neither published nor linked.
    pub fn forge_indicator(&self) -> String {
        if let Some(review_request) = &self.review_request {
            let display_id = &review_request.summary.display_id;

            return match review_request.summary.state {
                ReviewRequestState::Open => format!("⊙ {display_id}"),
                ReviewRequestState::Merged => format!("✓ {display_id}"),
                ReviewRequestState::Closed => format!("✗ {display_id}"),
            };
        }

        if self.published_upstream_ref.is_some() {
            return "↑".to_string();
        }

        String::new()
    }

    /// Returns whether this session can trigger a forge review request sync.
    ///
    /// Sync is available when the session has a published branch or a linked
    /// review request and the status allows review actions.
    pub fn can_sync_review_request(&self) -> bool {
        let has_forge_context =
            self.published_upstream_ref.is_some() || self.review_request.is_some();

        has_forge_context && matches!(self.status, Status::Review | Status::AgentReview)
    }

    /// Returns one UI message describing the current published-branch sync
    /// state when the session tracks an upstream branch.
    pub fn published_branch_sync_message(&self) -> Option<&'static str> {
        self.published_upstream_ref.as_ref()?;

        match self.published_branch_sync_status {
            PublishedBranchSyncStatus::Idle => None,
            PublishedBranchSyncStatus::InProgress => {
                Some("Auto-pushing published branch after completed turn...")
            }
            PublishedBranchSyncStatus::Succeeded => {
                Some("Auto-pushed published branch after completed turn.")
            }
            PublishedBranchSyncStatus::Failed => Some("Published branch sync failed."),
        }
    }

    /// Returns the review-request publish action currently available in session
    /// view.
    pub fn publish_pull_request_action(&self) -> Option<PublishBranchAction> {
        self.status
            .allows_review_actions()
            .then_some(PublishBranchAction::PublishPullRequest)
    }

    /// Returns the follow-up task at `position`, when present.
    pub fn follow_up_task(&self, position: usize) -> Option<&SessionFollowUpTask> {
        self.follow_up_tasks
            .iter()
            .find(|task| task.position == position)
    }

    /// Returns the best persisted context section for a continuation prompt.
    fn continuation_context(&self) -> Option<(&'static str, &str)> {
        self.non_empty_summary()
            .map(|summary| ("Previous session summary", summary))
            .or_else(|| {
                self.non_empty_output()
                    .map(|output| ("Previous session transcript", output))
            })
            .or_else(|| {
                self.non_empty_prompt()
                    .map(|prompt| ("Previous session prompt", prompt))
            })
    }

    /// Returns the trimmed persisted summary text when it is non-empty.
    fn non_empty_summary(&self) -> Option<&str> {
        self.summary
            .as_deref()
            .and_then(Self::trimmed_non_empty_text)
    }

    /// Returns the trimmed persisted transcript output when it is non-empty.
    fn non_empty_output(&self) -> Option<&str> {
        Self::trimmed_non_empty_text(&self.output)
    }

    /// Returns the trimmed persisted initial prompt when it is non-empty.
    fn non_empty_prompt(&self) -> Option<&str> {
        Self::trimmed_non_empty_text(&self.prompt)
    }

    /// Returns `value` trimmed to a non-empty slice when any content remains.
    fn trimmed_non_empty_text(value: &str) -> Option<&str> {
        let trimmed = value.trim();
        (!trimmed.is_empty()).then_some(trimmed)
    }
}

/// Returns whether the staged draft identified by `session_id` can start
/// under the currently loaded one-level stack.
///
/// Root drafts only need their own staged prompt state. Stacked drafts also
/// require a review-ready parent and no sibling/parent branch work already
/// running or queued in the same stack.
pub(crate) fn can_start_staged_session_in_stack(sessions: &[Session], session_id: &str) -> bool {
    let Some(stack) = SessionStack::for_session(sessions, session_id) else {
        return false;
    };
    let session = stack.requested_session();
    if !session.can_start_staged_session() {
        return false;
    }

    if session.parent_session_id.is_none() {
        return true;
    }
    if !stack.root_allows_stacked_child_start() {
        return false;
    }

    !stack.has_branch_mutating_member_except(session_id)
}

/// Returns whether the session identified by `session_id` can start branch
/// mutation while preserving one active branch worker per one-level stack.
///
/// This blocks parent branch edits once a child branch has materialized, and
/// blocks any stack member from starting branch work while a different member
/// is already running, queued, rebasing, merging, or waiting on a question.
pub(crate) fn can_mutate_session_branch_in_stack(sessions: &[Session], session_id: &str) -> bool {
    let Some(stack) = SessionStack::for_session(sessions, session_id) else {
        return false;
    };

    if stack.has_branch_mutating_member_except(session_id) {
        return false;
    }

    if stack.requested_session_is_root() && stack.has_materialized_child() {
        return false;
    }

    true
}

/// Returns whether a session can start session sync while preserving stack
/// consistency.
///
/// Unlike merge and slash-command branch edits, syncing a parent with idle
/// materialized children is allowed because the successful parent sync fans out
/// child syncs afterward. Active stack members still block the request so the
/// stack does not run competing branch work.
pub(crate) fn can_rebase_session_branch_in_stack(sessions: &[Session], session_id: &str) -> bool {
    let Some(stack) = SessionStack::for_session(sessions, session_id) else {
        return false;
    };

    !stack.has_branch_mutating_member_except(session_id)
}

/// Returns whether a session can accept a chat reply under one-level stack
/// constraints.
///
/// Replies are allowed when the stack has no other member actively running or
/// reserving branch work. Unlike merge or sync gates, an idle review-ready
/// materialized child does not block parent replies; the child can be synced
/// again after the parent produces its next review state.
pub(crate) fn can_reply_to_session_in_stack(sessions: &[Session], session_id: &str) -> bool {
    let Some(stack) = SessionStack::for_session(sessions, session_id) else {
        return false;
    };

    !stack.has_branch_mutating_member_except(session_id)
}

/// Snapshot of a loaded one-level stack for branch-work policy checks.
struct SessionStack<'a> {
    members: Vec<&'a Session>,
    requested_session: &'a Session,
    root_session: &'a Session,
}

impl<'a> SessionStack<'a> {
    /// Builds the stack containing `session_id` from the loaded session list.
    fn for_session(sessions: &'a [Session], session_id: &str) -> Option<Self> {
        let requested_session = find_session(sessions, session_id)?;
        let root_session = match requested_session.parent_session_id.as_ref() {
            Some(parent_session_id) => find_session(sessions, parent_session_id.as_str())?,
            None => requested_session,
        };
        let members = sessions
            .iter()
            .filter(|session| Self::session_belongs_to_root(session, root_session.id.as_str()))
            .collect();

        Some(Self {
            members,
            requested_session,
            root_session,
        })
    }

    /// Returns the session whose action is being evaluated.
    fn requested_session(&self) -> &'a Session {
        self.requested_session
    }

    /// Returns whether the requested session is the stack root.
    fn requested_session_is_root(&self) -> bool {
        self.requested_session.parent_session_id.is_none()
    }

    /// Returns whether another stack member is currently reserving or
    /// performing branch-mutating work.
    fn has_branch_mutating_member_except(&self, ignored_session_id: &str) -> bool {
        self.members
            .iter()
            .filter(|session| session.id.as_str() != ignored_session_id)
            .any(|session| session.status.is_stack_branch_mutating())
    }

    /// Returns whether the root already has a non-terminal child branch that
    /// has started at least one live turn.
    fn has_materialized_child(&self) -> bool {
        self.members.iter().any(|session| {
            session.parent_session_id.is_some()
                && !matches!(
                    session.status,
                    Status::Draft | Status::Done | Status::Canceled
                )
        })
    }

    /// Returns whether the root is in a state that lets a stacked draft child
    /// materialize.
    fn root_allows_stacked_child_start(&self) -> bool {
        self.root_session.status.allows_stacked_child_start()
    }

    /// Returns whether `session` belongs to the one-level stack rooted at
    /// `root_session_id`.
    fn session_belongs_to_root(session: &Session, root_session_id: &str) -> bool {
        session.id.as_str() == root_session_id
            || session
                .parent_session_id
                .as_ref()
                .is_some_and(|parent_session_id| parent_session_id.as_str() == root_session_id)
    }
}

/// Finds one loaded session by id.
fn find_session<'a>(sessions: &'a [Session], session_id: &str) -> Option<&'a Session> {
    sessions
        .iter()
        .find(|session| session.id.as_str() == session_id)
}

/// Shared runtime handles for one active session worker.
pub struct SessionHandles {
    /// Per-turn cancellation token shared between the UI and the worker.
    ///
    /// The worker swaps in a fresh [`CancellationToken`] at the start of
    /// each turn. The UI calls `cancel()` on the current token to
    /// interrupt the running turn. Because each turn gets its own token,
    /// stale cancellations from previous turns cannot affect new work.
    pub cancel_token: Arc<Mutex<CancellationToken>>,
    /// Child process identifier for the running agent command, when present.
    pub child_pid: Arc<Mutex<Option<u32>>>,
    /// Shared output buffer mirrored to persistence/UI.
    pub output: Arc<Mutex<String>>,
    /// In-memory queue of prompts staged while the current turn is running.
    ///
    /// Pushed by the chat composer when the user submits while the session is
    /// `InProgress`; popped by the session worker between turns. The queue is
    /// session-local and discarded on app restart.
    pub queued_messages: Arc<Mutex<VecDeque<TurnPrompt>>>,
    /// Shared mutable status synchronized with persistence/UI.
    pub status: Arc<Mutex<Status>>,
}

impl SessionHandles {
    /// Creates handles initialized with the given values.
    pub fn new(output: String, status: Status) -> Self {
        Self {
            cancel_token: Arc::new(Mutex::new(CancellationToken::new())),
            child_pid: Arc::new(Mutex::new(None)),
            output: Arc::new(Mutex::new(output)),
            queued_messages: Arc::new(Mutex::new(VecDeque::new())),
            status: Arc::new(Mutex::new(status)),
        }
    }

    /// Appends text to the output buffer.
    pub fn append_output(&self, message: &str) {
        // Sync critical section (string push, no `.await`); `std::sync::Mutex`
        // is the correct choice per CLAUDE.md §"Mutex Selection".
        if let Ok(mut buf) = self.output.lock() {
            buf.push_str(message);
        }
    }

    /// Returns the transcript text for each queued message in submission
    /// order so callers can mirror queue contents into render snapshots.
    pub fn queued_message_transcripts(&self) -> Vec<String> {
        // Sync critical section (read-only clone, no `.await`);
        // `std::sync::Mutex` is the correct choice per CLAUDE.md §"Mutex
        // Selection".
        self.queued_messages
            .lock()
            .map(|guard| {
                guard
                    .iter()
                    .map(TurnPrompt::transcript_text)
                    .collect::<Vec<_>>()
            })
            .unwrap_or_default()
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use std::collections::HashMap;

    use super::*;
    use crate::domain::agent::AgentModel;

    /// Chainable builder that produces deterministic `Session` values for unit
    /// tests. Consolidates the session struct-literal previously duplicated
    /// across test modules into one shared place so new fields only need to be
    /// wired in once.
    pub(crate) struct SessionFixtureBuilder {
        session: Session,
    }

    impl SessionFixtureBuilder {
        /// Creates a builder seeded with minimal deterministic defaults that
        /// match the common case used across UI and runtime unit tests.
        pub(crate) fn new() -> Self {
            Self {
                session: Session {
                    agent: AgentSelection::new(
                        crate::domain::agent::AgentKind::Antigravity,
                        AgentModel::Gemini3FlashPreview,
                    ),
                    base_branch: "main".to_string(),
                    created_at: 0,
                    draft_attachments: Vec::new(),
                    folder: PathBuf::new(),
                    follow_up_tasks: Vec::new(),
                    id: SessionId::from("session-id"),
                    in_progress_started_at: None,
                    in_progress_total_seconds: 0,
                    is_draft: false,
                    output: String::new(),
                    parent_session_id: None,
                    project_name: "project".to_string(),
                    prompt: String::new(),
                    queued_messages: Vec::new(),
                    reasoning_level_override: None,
                    published_upstream_ref: None,
                    published_branch_sync_status: PublishedBranchSyncStatus::Idle,
                    questions: Vec::new(),
                    review_request: None,
                    size: SessionSize::Xs,
                    stats: SessionStats::default(),
                    status: Status::Review,
                    summary: None,
                    title: None,
                    updated_at: 0,
                    workflow_notice: None,
                },
            }
        }

        /// Overrides the stable session identifier.
        pub(crate) fn id(mut self, id: impl Into<SessionId>) -> Self {
            self.session.id = id.into();

            self
        }

        /// Overrides the lifecycle status.
        pub(crate) fn status(mut self, status: Status) -> Self {
            self.session.status = status;

            self
        }

        /// Overrides the draft flag.
        pub(crate) fn draft(mut self, is_draft: bool) -> Self {
            self.session.is_draft = is_draft;

            self
        }

        /// Overrides the worktree folder.
        pub(crate) fn folder(mut self, folder: PathBuf) -> Self {
            self.session.folder = folder;

            self
        }

        /// Overrides the project name.
        pub(crate) fn project_name(mut self, project_name: impl Into<String>) -> Self {
            self.session.project_name = project_name.into();

            self
        }

        /// Overrides the agent model.
        pub(crate) fn model(mut self, model: AgentModel) -> Self {
            self.session.agent = AgentSelection::new(self.session.agent.kind(), model);

            self
        }

        /// Overrides the captured output transcript.
        pub(crate) fn output(mut self, output: impl Into<String>) -> Self {
            self.session.output = output.into();

            self
        }

        /// Overrides the user prompt text.
        pub(crate) fn prompt(mut self, prompt: impl Into<String>) -> Self {
            self.session.prompt = prompt.into();

            self
        }

        /// Overrides the optional stacked-session parent identifier.
        pub(crate) fn parent_session_id(mut self, parent_session_id: Option<SessionId>) -> Self {
            self.session.parent_session_id = parent_session_id;

            self
        }

        /// Overrides the optional explicit session title.
        pub(crate) fn title(mut self, title: Option<String>) -> Self {
            self.session.title = title;

            self
        }

        /// Overrides the optional persisted session summary text.
        pub(crate) fn summary(mut self, summary: Option<String>) -> Self {
            self.session.summary = summary;

            self
        }

        /// Overrides the session-scoped reasoning level override.
        pub(crate) fn reasoning_level_override(
            mut self,
            reasoning_level_override: Option<ReasoningLevel>,
        ) -> Self {
            self.session.reasoning_level_override = reasoning_level_override;

            self
        }

        /// Consumes the builder and returns the fully populated fixture.
        pub(crate) fn build(self) -> Session {
            self.session
        }
    }

    #[test]
    fn test_allows_stacked_child_creation_returns_true_for_root_active_session() {
        // Arrange
        let session = SessionFixtureBuilder::new()
            .draft(false)
            .status(Status::Review)
            .build();

        // Act
        let allows_stacked_child = session.allows_stacked_child_creation();

        // Assert
        assert!(allows_stacked_child);
    }

    #[test]
    fn test_allows_stacked_child_creation_rejects_drafts_children_and_terminal_sessions() {
        // Arrange
        let draft_session = SessionFixtureBuilder::new()
            .draft(true)
            .status(Status::Draft)
            .build();
        let child_session = SessionFixtureBuilder::new()
            .parent_session_id(Some(SessionId::from("parent-session")))
            .status(Status::Review)
            .build();
        let done_session = SessionFixtureBuilder::new().status(Status::Done).build();
        let canceled_session = SessionFixtureBuilder::new()
            .status(Status::Canceled)
            .build();

        // Act
        let allows_draft_child = draft_session.allows_stacked_child_creation();
        let allows_nested_child = child_session.allows_stacked_child_creation();
        let allows_done_child = done_session.allows_stacked_child_creation();
        let allows_canceled_child = canceled_session.allows_stacked_child_creation();

        // Assert
        assert!(!allows_draft_child);
        assert!(!allows_nested_child);
        assert!(!allows_done_child);
        assert!(!allows_canceled_child);
    }

    #[test]
    fn test_can_start_staged_session_checks_only_draft_readiness() {
        // Arrange
        let root_draft_session = SessionFixtureBuilder::new()
            .draft(true)
            .status(Status::Draft)
            .prompt("Ready to start")
            .build();
        let stacked_draft_session = SessionFixtureBuilder::new()
            .draft(true)
            .status(Status::Draft)
            .prompt("Waiting on parent")
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();

        // Act
        let can_start_root_draft = root_draft_session.can_start_staged_session();
        let can_start_stacked_draft = stacked_draft_session.can_start_staged_session();

        // Assert
        assert!(can_start_root_draft);
        assert!(can_start_stacked_draft);
    }

    #[test]
    fn test_can_start_staged_session_in_stack_requires_parent_review() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::InProgress)
            .build();
        let child_session = SessionFixtureBuilder::new()
            .id("child-session")
            .draft(true)
            .status(Status::Draft)
            .prompt("Ready child draft")
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, child_session];

        // Act
        let can_start_child = can_start_staged_session_in_stack(&sessions, "child-session");

        // Assert
        assert!(!can_start_child);
    }

    #[test]
    fn test_can_start_staged_session_in_stack_blocks_active_stack_member() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let running_child_session = SessionFixtureBuilder::new()
            .id("running-child")
            .draft(true)
            .status(Status::InProgress)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let staged_child_session = SessionFixtureBuilder::new()
            .id("staged-child")
            .draft(true)
            .status(Status::Draft)
            .prompt("Ready child draft")
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, running_child_session, staged_child_session];

        // Act
        let can_start_child = can_start_staged_session_in_stack(&sessions, "staged-child");

        // Assert
        assert!(!can_start_child);
    }

    #[test]
    fn test_can_start_staged_session_in_stack_allows_review_ready_parent() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let child_session = SessionFixtureBuilder::new()
            .id("child-session")
            .draft(true)
            .status(Status::Draft)
            .prompt("Ready child draft")
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, child_session];

        // Act
        let can_start_child = can_start_staged_session_in_stack(&sessions, "child-session");

        // Assert
        assert!(can_start_child);
    }

    #[test]
    fn test_can_mutate_session_branch_in_stack_blocks_parent_with_materialized_child() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let child_session = SessionFixtureBuilder::new()
            .id("child-session")
            .draft(true)
            .status(Status::Review)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, child_session];

        // Act
        let can_mutate_parent = can_mutate_session_branch_in_stack(&sessions, "parent-session");

        // Assert
        assert!(!can_mutate_parent);
    }

    #[test]
    fn test_can_mutate_session_branch_in_stack_blocks_concurrent_stack_member() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let running_child_session = SessionFixtureBuilder::new()
            .id("running-child")
            .draft(true)
            .status(Status::InProgress)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let review_child_session = SessionFixtureBuilder::new()
            .id("review-child")
            .draft(true)
            .status(Status::Review)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, running_child_session, review_child_session];

        // Act
        let can_mutate_review_child = can_mutate_session_branch_in_stack(&sessions, "review-child");

        // Assert
        assert!(!can_mutate_review_child);
    }

    #[test]
    fn test_can_rebase_session_branch_in_stack_allows_parent_with_review_child() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let child_session = SessionFixtureBuilder::new()
            .id("child-session")
            .draft(true)
            .status(Status::Review)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, child_session];

        // Act
        let can_rebase_parent = can_rebase_session_branch_in_stack(&sessions, "parent-session");

        // Assert
        assert!(can_rebase_parent);
    }

    #[test]
    fn test_can_rebase_session_branch_in_stack_blocks_concurrent_stack_member() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let running_child_session = SessionFixtureBuilder::new()
            .id("running-child")
            .draft(true)
            .status(Status::InProgress)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let review_child_session = SessionFixtureBuilder::new()
            .id("review-child")
            .draft(true)
            .status(Status::Review)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, running_child_session, review_child_session];

        // Act
        let can_rebase_review_child = can_rebase_session_branch_in_stack(&sessions, "review-child");

        // Assert
        assert!(!can_rebase_review_child);
    }

    #[test]
    fn test_can_reply_to_session_in_stack_allows_parent_with_review_child() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let child_session = SessionFixtureBuilder::new()
            .id("child-session")
            .draft(true)
            .status(Status::Review)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, child_session];

        // Act
        let can_reply_to_parent = can_reply_to_session_in_stack(&sessions, "parent-session");

        // Assert
        assert!(can_reply_to_parent);
    }

    #[test]
    fn test_can_reply_to_session_in_stack_blocks_active_stack_member() {
        // Arrange
        let parent_session = SessionFixtureBuilder::new()
            .id("parent-session")
            .draft(false)
            .status(Status::Review)
            .build();
        let running_child_session = SessionFixtureBuilder::new()
            .id("running-child")
            .draft(true)
            .status(Status::InProgress)
            .parent_session_id(Some(SessionId::from("parent-session")))
            .build();
        let sessions = vec![parent_session, running_child_session];

        // Act
        let can_reply_to_parent = can_reply_to_session_in_stack(&sessions, "parent-session");

        // Assert
        assert!(!can_reply_to_parent);
    }

    /// Builds a minimal session fixture for reasoning-level tests.
    fn test_session(reasoning_level_override: Option<ReasoningLevel>) -> Session {
        SessionFixtureBuilder::new()
            .reasoning_level_override(reasoning_level_override)
            .build()
    }

    #[test]
    fn test_status_from_str_queued() {
        // Arrange
        let raw_status = "Queued";

        // Act
        let status = raw_status
            .parse::<Status>()
            .expect("failed to parse status");

        // Assert
        assert_eq!(status, Status::Queued);
    }

    #[test]
    fn test_status_display_queued() {
        // Arrange
        let status = Status::Queued;

        // Act
        let displayed_status = status.to_string();

        // Assert
        assert_eq!(displayed_status, "Queued");
    }

    #[test]
    fn test_status_from_str_draft() {
        // Arrange
        let raw_status = "Draft";

        // Act
        let status = raw_status
            .parse::<Status>()
            .expect("failed to parse status");

        // Assert
        assert_eq!(status, Status::Draft);
    }

    #[test]
    fn test_status_display_draft() {
        // Arrange
        let status = Status::Draft;

        // Act
        let displayed_status = status.to_string();

        // Assert
        assert_eq!(displayed_status, "Draft");
    }

    #[test]
    fn test_session_id_hash_map_borrowed_lookup() {
        // Arrange
        let session_id = SessionId::from("session-id");
        let sessions = HashMap::from([(session_id, "ready")]);

        // Act
        let status = sessions.get("session-id");

        // Assert
        assert_eq!(status, Some(&"ready"));
    }

    #[test]
    fn test_session_id_serde_serializes_as_plain_string() {
        // Arrange
        let session_id = SessionId::from("session-id");

        // Act
        let serialized_session_id =
            serde_json::to_string(&session_id).expect("session id should serialize");
        let deserialized_session_id: SessionId =
            serde_json::from_str(&serialized_session_id).expect("session id should deserialize");

        // Assert
        assert_eq!(serialized_session_id, "\"session-id\"");
        assert_eq!(deserialized_session_id, session_id);
    }

    #[test]
    fn test_status_all_lists_every_supported_status_in_display_order() {
        // Arrange
        let expected_statuses = [
            Status::Draft,
            Status::InProgress,
            Status::Review,
            Status::AgentReview,
            Status::Question,
            Status::Queued,
            Status::Rebasing,
            Status::Merging,
            Status::Done,
            Status::Canceled,
        ];

        // Act
        let all_statuses = Status::ALL;

        // Assert
        assert_eq!(all_statuses, expected_statuses);
    }

    #[test]
    fn test_status_transition_review_to_queued() {
        // Arrange
        let current_status = Status::Review;

        // Act
        let can_transition = current_status.can_transition_to(Status::Queued);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_transition_review_to_agent_review() {
        // Arrange
        let current_status = Status::Review;

        // Act
        let can_transition = current_status.can_transition_to(Status::AgentReview);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_allows_review_actions_for_agent_review() {
        // Arrange
        let status = Status::AgentReview;

        // Act
        let allows_review_actions = status.allows_review_actions();

        // Assert
        assert!(allows_review_actions);
    }

    #[test]
    fn test_status_allows_terminal_continuation_only_for_done() {
        // Arrange
        let done_status = Status::Done;
        let canceled_status = Status::Canceled;
        let review_status = Status::Review;

        // Act
        let done_allows_continuation = done_status.allows_terminal_continuation();
        let canceled_allows_continuation = canceled_status.allows_terminal_continuation();
        let review_allows_continuation = review_status.allows_terminal_continuation();

        // Assert
        assert!(done_allows_continuation);
        assert!(!canceled_allows_continuation);
        assert!(!review_allows_continuation);
    }

    #[test]
    fn test_status_transition_draft_to_canceled() {
        // Arrange
        let current_status = Status::Draft;

        // Act
        let can_transition = current_status.can_transition_to(Status::Canceled);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_transition_in_progress_to_canceled() {
        // Arrange
        let current_status = Status::InProgress;

        // Act
        let can_transition = current_status.can_transition_to(Status::Canceled);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_transition_queued_to_merging() {
        // Arrange
        let current_status = Status::Queued;

        // Act
        let can_transition = current_status.can_transition_to(Status::Merging);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_transition_queued_to_in_progress_is_rejected() {
        // Arrange
        let current_status = Status::Queued;

        // Act
        let can_transition = current_status.can_transition_to(Status::InProgress);

        // Assert
        assert!(!can_transition);
    }

    #[test]
    fn test_session_stats_line_change_counts_ignore_diff_headers() {
        // Arrange
        let diff = "\
diff --git a/src/lib.rs b/src/lib.rs\nindex 1111111..2222222 100644\n--- a/src/lib.rs\n+++ \
                    b/src/lib.rs\n@@ -1,2 +1,3 @@\n-old line\n+new line\n+another line\n";

        // Act
        let (added_lines, deleted_lines) = SessionStats::line_change_counts(diff);

        // Assert
        assert_eq!(added_lines, 2);
        assert_eq!(deleted_lines, 1);
    }

    #[test]
    fn test_session_size_from_diff_counts_added_and_deleted_lines() {
        // Arrange
        let diff = "\
diff --git a/src/lib.rs b/src/lib.rs\n@@ -1 +1,2 @@\n-old line\n+new line\n+another line\n";

        // Act
        let session_size = SessionSize::from_diff(diff);

        // Assert
        assert_eq!(session_size, SessionSize::Xs);
    }

    #[test]
    /// Ensures sessions without an override inherit the provided default
    /// reasoning level.
    fn test_effective_reasoning_level_uses_default_when_override_is_missing() {
        // Arrange
        let session = test_session(None);

        // Act
        let effective_reasoning_level = session.effective_reasoning_level(ReasoningLevel::Medium);
        let uses_default_reasoning_level = session.uses_default_reasoning_level();

        // Assert
        assert_eq!(effective_reasoning_level, ReasoningLevel::Medium);
        assert!(uses_default_reasoning_level);
    }

    #[test]
    /// Ensures sessions with an override use that override instead of the
    /// provided default.
    fn test_effective_reasoning_level_prefers_session_override() {
        // Arrange
        let session = test_session(Some(ReasoningLevel::High));

        // Act
        let effective_reasoning_level = session.effective_reasoning_level(ReasoningLevel::Low);
        let uses_default_reasoning_level = session.uses_default_reasoning_level();

        // Assert
        assert_eq!(effective_reasoning_level, ReasoningLevel::High);
        assert!(!uses_default_reasoning_level);
    }

    #[test]
    /// Ensures clearing a session override restores inheritance from the
    /// provided default reasoning level.
    fn test_effective_reasoning_level_returns_to_default_after_override_is_cleared() {
        // Arrange
        let mut session = test_session(Some(ReasoningLevel::XHigh));
        session.reasoning_level_override = None;

        // Act
        let effective_reasoning_level = session.effective_reasoning_level(ReasoningLevel::Low);
        let uses_default_reasoning_level = session.uses_default_reasoning_level();

        // Assert
        assert_eq!(effective_reasoning_level, ReasoningLevel::Low);
        assert!(uses_default_reasoning_level);
    }

    #[test]
    fn test_session_continuation_prompt_seed_prefers_summary_for_terminal_session() {
        // Arrange
        let session = SessionFixtureBuilder::new()
            .status(Status::Done)
            .project_name("project-alpha")
            .summary(Some("# Summary\n\nShip it.".to_string()))
            .output("assistant transcript")
            .title(Some("Terminal session".to_string()))
            .build();

        // Act
        let continuation_prompt_seed = session
            .continuation_prompt_seed()
            .expect("expected continuation prompt seed");

        // Assert
        assert!(continuation_prompt_seed.contains(TERMINAL_CONTINUATION_PROMPT_INTRO));
        assert!(continuation_prompt_seed.contains("Previous session: Terminal session"));
        assert!(continuation_prompt_seed.contains("Project: project-alpha"));
        assert!(continuation_prompt_seed.contains("Status: Done"));
        assert!(continuation_prompt_seed.contains("Previous session summary:\n# Summary"));
        assert!(!continuation_prompt_seed.contains("assistant transcript"));
    }

    #[test]
    fn test_session_continuation_prompt_seed_disabled_for_canceled_session() {
        // Arrange
        let session = SessionFixtureBuilder::new()
            .status(Status::Canceled)
            .project_name("project-beta")
            .build();

        // Act
        let continuation_prompt_seed = session.continuation_prompt_seed();

        // Assert
        assert_eq!(continuation_prompt_seed, None);
    }

    #[test]
    fn test_session_continuation_prompt_seed_rejects_non_terminal_session() {
        // Arrange
        let session = SessionFixtureBuilder::new()
            .status(Status::Review)
            .summary(Some("summary".to_string()))
            .build();

        // Act
        let continuation_prompt_seed = session.continuation_prompt_seed();

        // Assert
        assert_eq!(continuation_prompt_seed, None);
    }

    #[test]
    fn test_forge_kind_from_str_github() {
        // Arrange
        let raw_forge_kind = "GitHub";

        // Act
        let forge_kind = raw_forge_kind
            .parse::<ForgeKind>()
            .expect("failed to parse review-request forge");

        // Assert
        assert_eq!(forge_kind, ForgeKind::GitHub);
    }

    #[test]
    fn test_forge_kind_from_str_gitlab() {
        // Arrange
        let raw_forge_kind = "GitLab";

        // Act
        let forge_kind = raw_forge_kind
            .parse::<ForgeKind>()
            .expect("failed to parse review-request forge");

        // Assert
        assert_eq!(forge_kind, ForgeKind::GitLab);
    }

    #[test]
    fn test_review_request_state_display_merged() {
        // Arrange
        let review_request_state = ReviewRequestState::Merged;

        // Act
        let displayed_state = review_request_state.to_string();

        // Assert
        assert_eq!(displayed_state, "Merged");
    }

    #[test]
    fn test_publish_pull_request_action_returns_publish_for_review_session() {
        // Arrange
        let session = Session {
            base_branch: "main".to_string(),
            created_at: 0,
            draft_attachments: Vec::new(),
            folder: PathBuf::new(),
            follow_up_tasks: Vec::new(),
            id: "session-id".into(),
            in_progress_started_at: None,
            in_progress_total_seconds: 0,
            is_draft: false,
            agent: AgentSelection::new(
                crate::domain::agent::AgentKind::Antigravity,
                AgentModel::Gemini3FlashPreview,
            ),
            output: String::new(),
            parent_session_id: None,
            project_name: "project".to_string(),
            prompt: String::new(),
            queued_messages: Vec::new(),
            reasoning_level_override: None,
            published_upstream_ref: None,
            published_branch_sync_status: PublishedBranchSyncStatus::Idle,
            questions: Vec::new(),
            review_request: None,
            size: SessionSize::Xs,
            stats: SessionStats::default(),
            status: Status::Review,
            summary: None,
            title: None,
            updated_at: 0,
            workflow_notice: None,
        };

        // Act
        let action = session.publish_pull_request_action();

        // Assert
        assert_eq!(action, Some(PublishBranchAction::PublishPullRequest));
    }

    #[test]
    fn test_publish_pull_request_action_returns_publish_for_agent_review_session() {
        // Arrange
        let session = Session {
            base_branch: "main".to_string(),
            created_at: 0,
            draft_attachments: Vec::new(),
            folder: PathBuf::new(),
            follow_up_tasks: Vec::new(),
            id: "session-id".into(),
            in_progress_started_at: None,
            in_progress_total_seconds: 0,
            is_draft: false,
            agent: AgentSelection::new(
                crate::domain::agent::AgentKind::Antigravity,
                AgentModel::Gemini3FlashPreview,
            ),
            output: String::new(),
            parent_session_id: None,
            project_name: "project".to_string(),
            prompt: String::new(),
            queued_messages: Vec::new(),
            reasoning_level_override: None,
            published_upstream_ref: None,
            published_branch_sync_status: PublishedBranchSyncStatus::Idle,
            questions: Vec::new(),
            review_request: None,
            size: SessionSize::Xs,
            stats: SessionStats::default(),
            status: Status::AgentReview,
            summary: None,
            title: None,
            updated_at: 0,
            workflow_notice: None,
        };

        // Act
        let action = session.publish_pull_request_action();

        // Assert
        assert_eq!(action, Some(PublishBranchAction::PublishPullRequest));
    }

    #[test]
    fn test_publish_pull_request_action_returns_none_for_in_progress_session() {
        // Arrange
        let session = Session {
            base_branch: "main".to_string(),
            created_at: 0,
            draft_attachments: Vec::new(),
            folder: PathBuf::new(),
            follow_up_tasks: Vec::new(),
            id: "session-id".into(),
            in_progress_started_at: Some(60),
            in_progress_total_seconds: 120,
            is_draft: false,
            agent: AgentSelection::new(
                crate::domain::agent::AgentKind::Antigravity,
                AgentModel::Gemini3FlashPreview,
            ),
            output: String::new(),
            parent_session_id: None,
            project_name: "project".to_string(),
            prompt: String::new(),
            queued_messages: Vec::new(),
            reasoning_level_override: None,
            published_upstream_ref: Some("origin/wt/session-id".to_string()),
            published_branch_sync_status: PublishedBranchSyncStatus::Idle,
            questions: Vec::new(),
            review_request: None,
            size: SessionSize::Xs,
            stats: SessionStats::default(),
            status: Status::InProgress,
            summary: None,
            title: None,
            updated_at: 0,
            workflow_notice: None,
        };

        // Act
        let action = session.publish_pull_request_action();

        // Assert
        assert_eq!(action, None);
    }

    #[test]
    fn test_publish_pull_request_action_returns_none_for_done_session() {
        // Arrange
        let session = Session {
            base_branch: "main".to_string(),
            created_at: 0,
            draft_attachments: Vec::new(),
            folder: PathBuf::new(),
            follow_up_tasks: Vec::new(),
            id: "session-id".into(),
            in_progress_started_at: None,
            in_progress_total_seconds: 180,
            is_draft: false,
            agent: AgentSelection::new(
                crate::domain::agent::AgentKind::Antigravity,
                AgentModel::Gemini3FlashPreview,
            ),
            output: String::new(),
            parent_session_id: None,
            project_name: "project".to_string(),
            prompt: String::new(),
            queued_messages: Vec::new(),
            reasoning_level_override: None,
            published_upstream_ref: Some("origin/wt/session-id".to_string()),
            published_branch_sync_status: PublishedBranchSyncStatus::Idle,
            questions: Vec::new(),
            review_request: None,
            size: SessionSize::Xs,
            stats: SessionStats::default(),
            status: Status::Done,
            summary: None,
            title: None,
            updated_at: 0,
            workflow_notice: None,
        };

        // Act
        let action = session.publish_pull_request_action();

        // Assert
        assert_eq!(action, None);
    }

    #[test]
    fn test_has_in_progress_timer_returns_true_for_open_interval() {
        // Arrange
        let session = Session {
            base_branch: "main".to_string(),
            created_at: 0,
            draft_attachments: Vec::new(),
            folder: PathBuf::new(),
            follow_up_tasks: Vec::new(),
            id: "session-id".into(),
            in_progress_started_at: Some(120),
            in_progress_total_seconds: 0,
            is_draft: false,
            agent: AgentSelection::new(
                crate::domain::agent::AgentKind::Antigravity,
                AgentModel::Gemini3FlashPreview,
            ),
            output: String::new(),
            parent_session_id: None,
            project_name: "project".to_string(),
            prompt: String::new(),
            queued_messages: Vec::new(),
            reasoning_level_override: None,
            published_upstream_ref: None,
            published_branch_sync_status: PublishedBranchSyncStatus::Idle,
            questions: Vec::new(),
            review_request: None,
            size: SessionSize::Xs,
            stats: SessionStats::default(),
            status: Status::InProgress,
            summary: None,
            title: None,
            updated_at: 0,
            workflow_notice: None,
        };

        // Act
        let shows_timer = session.has_in_progress_timer();

        // Assert
        assert!(shows_timer);
    }

    #[test]
    fn test_in_progress_duration_seconds_accumulates_closed_and_open_intervals() {
        // Arrange
        let session = Session {
            base_branch: "main".to_string(),
            created_at: 0,
            draft_attachments: Vec::new(),
            folder: PathBuf::new(),
            follow_up_tasks: Vec::new(),
            id: "session-id".into(),
            in_progress_started_at: Some(200),
            in_progress_total_seconds: 90,
            is_draft: false,
            agent: AgentSelection::new(
                crate::domain::agent::AgentKind::Antigravity,
                AgentModel::Gemini3FlashPreview,
            ),
            output: String::new(),
            parent_session_id: None,
            project_name: "project".to_string(),
            prompt: String::new(),
            queued_messages: Vec::new(),
            reasoning_level_override: None,
            published_upstream_ref: None,
            published_branch_sync_status: PublishedBranchSyncStatus::Idle,
            questions: Vec::new(),
            review_request: None,
            size: SessionSize::Xs,
            stats: SessionStats::default(),
            status: Status::InProgress,
            summary: None,
            title: None,
            updated_at: 0,
            workflow_notice: None,
        };

        // Act
        let duration_seconds = session.in_progress_duration_seconds(260);

        // Assert
        assert_eq!(duration_seconds, 150);
    }

    // -- forge_indicator tests -----------------------------------------------

    #[test]
    fn test_forge_indicator_returns_open_symbol_with_display_id() {
        // Arrange
        let mut session = test_session(None);
        session.review_request = Some(ReviewRequest {
            last_refreshed_at: 0,
            summary: ReviewRequestSummary {
                display_id: "#42".to_string(),
                forge_kind: ForgeKind::GitHub,
                source_branch: "wt/session-id".to_string(),
                state: ReviewRequestState::Open,
                status_summary: None,
                target_branch: "main".to_string(),
                title: "feat".to_string(),
                web_url: String::new(),
            },
        });

        // Act
        let indicator = session.forge_indicator();

        // Assert
        assert_eq!(indicator, "⊙ #42");
    }

    #[test]
    fn test_forge_indicator_returns_merged_symbol_with_display_id() {
        // Arrange
        let mut session = test_session(None);
        session.review_request = Some(ReviewRequest {
            last_refreshed_at: 0,
            summary: ReviewRequestSummary {
                display_id: "#99".to_string(),
                forge_kind: ForgeKind::GitHub,
                source_branch: "wt/session-id".to_string(),
                state: ReviewRequestState::Merged,
                status_summary: None,
                target_branch: "main".to_string(),
                title: "feat".to_string(),
                web_url: String::new(),
            },
        });

        // Act
        let indicator = session.forge_indicator();

        // Assert
        assert_eq!(indicator, "✓ #99");
    }

    #[test]
    fn test_forge_indicator_returns_closed_symbol_with_display_id() {
        // Arrange
        let mut session = test_session(None);
        session.review_request = Some(ReviewRequest {
            last_refreshed_at: 0,
            summary: ReviewRequestSummary {
                display_id: "#7".to_string(),
                forge_kind: ForgeKind::GitHub,
                source_branch: "wt/session-id".to_string(),
                state: ReviewRequestState::Closed,
                status_summary: None,
                target_branch: "main".to_string(),
                title: "feat".to_string(),
                web_url: String::new(),
            },
        });

        // Act
        let indicator = session.forge_indicator();

        // Assert
        assert_eq!(indicator, "✗ #7");
    }

    #[test]
    fn test_forge_indicator_returns_arrow_for_published_branch_without_review_request() {
        // Arrange
        let mut session = test_session(None);
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());

        // Act
        let indicator = session.forge_indicator();

        // Assert
        assert_eq!(indicator, "↑");
    }

    #[test]
    fn test_forge_indicator_returns_empty_when_no_forge_context() {
        // Arrange
        let session = test_session(None);

        // Act
        let indicator = session.forge_indicator();

        // Assert
        assert_eq!(indicator, "");
    }

    #[test]
    fn test_forge_indicator_prefers_review_request_over_published_ref() {
        // Arrange
        let mut session = test_session(None);
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());
        session.review_request = Some(ReviewRequest {
            last_refreshed_at: 0,
            summary: ReviewRequestSummary {
                display_id: "#10".to_string(),
                forge_kind: ForgeKind::GitHub,
                source_branch: "wt/session-id".to_string(),
                state: ReviewRequestState::Open,
                status_summary: None,
                target_branch: "main".to_string(),
                title: "feat".to_string(),
                web_url: String::new(),
            },
        });

        // Act
        let indicator = session.forge_indicator();

        // Assert
        assert_eq!(indicator, "⊙ #10");
    }

    // -- can_sync_review_request tests ---------------------------------------

    #[test]
    fn test_can_sync_review_request_true_for_review_with_published_ref() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::Review;
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());

        // Act / Assert
        assert!(session.can_sync_review_request());
    }

    #[test]
    fn test_can_sync_review_request_true_for_agent_review_with_review_request() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::AgentReview;
        session.review_request = Some(ReviewRequest {
            last_refreshed_at: 0,
            summary: ReviewRequestSummary {
                display_id: "#1".to_string(),
                forge_kind: ForgeKind::GitHub,
                source_branch: "wt/session-id".to_string(),
                state: ReviewRequestState::Open,
                status_summary: None,
                target_branch: "main".to_string(),
                title: "feat".to_string(),
                web_url: String::new(),
            },
        });

        // Act / Assert
        assert!(session.can_sync_review_request());
    }

    #[test]
    fn test_can_sync_review_request_false_for_question_with_published_ref() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::Question;
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());

        // Act / Assert
        assert!(!session.can_sync_review_request());
    }

    #[test]
    fn test_can_sync_review_request_false_for_in_progress() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::InProgress;
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());

        // Act / Assert
        assert!(!session.can_sync_review_request());
    }

    #[test]
    fn test_can_sync_review_request_false_for_done() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::Done;
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());

        // Act / Assert
        assert!(!session.can_sync_review_request());
    }

    #[test]
    fn test_can_sync_review_request_false_without_forge_context() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::Review;

        // Act / Assert
        assert!(!session.can_sync_review_request());
    }

    #[test]
    fn test_published_branch_sync_message_returns_in_progress_copy() {
        // Arrange
        let mut session = test_session(None);
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());
        session.published_branch_sync_status = PublishedBranchSyncStatus::InProgress;

        // Act
        let sync_message = session.published_branch_sync_message();

        // Assert
        assert_eq!(
            sync_message,
            Some("Auto-pushing published branch after completed turn...")
        );
    }

    #[test]
    fn test_published_branch_sync_message_returns_succeeded_copy() {
        // Arrange
        let mut session = test_session(None);
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());
        session.published_branch_sync_status = PublishedBranchSyncStatus::Succeeded;

        // Act
        let sync_message = session.published_branch_sync_message();

        // Assert
        assert_eq!(
            sync_message,
            Some("Auto-pushed published branch after completed turn.")
        );
    }

    #[test]
    fn test_published_branch_sync_message_returns_failed_copy() {
        // Arrange
        let mut session = test_session(None);
        session.published_upstream_ref = Some("origin/wt/session-id".to_string());
        session.published_branch_sync_status = PublishedBranchSyncStatus::Failed;

        // Act
        let sync_message = session.published_branch_sync_message();

        // Assert
        assert_eq!(sync_message, Some("Published branch sync failed."));
    }

    #[test]
    fn test_session_allows_cancel_action_for_unstarted_draft_session() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::Draft;
        session.is_draft = true;

        // Act
        let allows_cancel_action = session.allows_cancel_action();

        // Assert
        assert!(allows_cancel_action);
    }

    #[test]
    fn test_session_allows_cancel_action_for_running_session() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::InProgress;

        // Act
        let allows_cancel_action = session.allows_cancel_action();

        // Assert
        assert!(allows_cancel_action);
    }

    #[test]
    fn test_session_allows_cancel_action_rejects_regular_draft_session() {
        // Arrange
        let mut session = test_session(None);
        session.status = Status::Draft;

        // Act
        let allows_cancel_action = session.allows_cancel_action();

        // Assert
        assert!(!allows_cancel_action);
    }

    // -- status transition: Review/AgentReview/Question → Done ---------------

    #[test]
    fn test_status_transition_review_to_done() {
        // Arrange
        let current_status = Status::Review;

        // Act
        let can_transition = current_status.can_transition_to(Status::Done);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_transition_agent_review_to_done() {
        // Arrange
        let current_status = Status::AgentReview;

        // Act
        let can_transition = current_status.can_transition_to(Status::Done);

        // Assert
        assert!(can_transition);
    }

    #[test]
    fn test_status_transition_question_to_done_rejected() {
        // Arrange
        let current_status = Status::Question;

        // Act
        let can_transition = current_status.can_transition_to(Status::Done);

        // Assert
        assert!(!can_transition);
    }
}