agentty 0.12.6

//! Session task execution helpers for process running, output capture, and
//! status persistence.

use std::path::Path;
use std::sync::{Arc, Mutex};

use ag_agent::agent;
use ag_git::{self as git, GitClient};
use askama::Template;
use tokio::sync::mpsc;
use tracing::warn;

use crate::app::assist::{
    AssistContext, AssistPolicy, FailureTracker, append_assist_header, format_detail_lines,
    run_agent_assist,
};
use crate::app::service::{AppServices, SessionUpdateVersionMap};
use crate::app::session::{Clock, SessionError, unix_timestamp_from_system_time};
use crate::app::{AppEvent, SessionManager, setting};
use crate::domain::agent::{AgentKind, AgentSelection};
#[cfg(test)]
use crate::domain::agent::{AgentModel, AgentSelectionMetadata};
use crate::domain::session::{
    COMMITTING_PROGRESS_LABEL, SessionHandles, SessionId, SessionSize, Status,
};
use crate::domain::session_message::{SessionMessageKind, SessionTranscript};
use crate::domain::setting::SettingName;
use crate::domain::transcript_notice::TranscriptNotice;
use crate::infra::db::AppRepositories;
use crate::infra::fs::FsClient;

const AUTO_COMMIT_ASSIST_POLICY: AssistPolicy = AssistPolicy {
    max_attempts: 10,
    max_identical_failure_streak: 3,
};
const SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER: &str =
    "Co-Authored-By: [Agentty](https://github.com/agentty-xyz/agentty)";
const SESSION_COMMIT_DIFF_TRUNCATION_LIMIT: usize = 60_000;
const SESSION_COMMIT_DIFF_TRUNCATED_SECTION_MARKER: &str =
    "[Commit message diff was truncated to fit context window]";
const AUTO_COMMIT_ERROR_TRUNCATION_LIMIT: usize = 20_000;
const AUTO_COMMIT_ERROR_TRUNCATED_SECTION_MARKER: &str =
    "[Commit error was truncated to fit context window]";
/// Askama view model for rendering auto-commit recovery prompts.
#[derive(Template)]
#[template(path = "auto_commit_assist_prompt.md", escape = "none")]
struct AutoCommitAssistPromptTemplate<'a> {
    commit_error: &'a str,
}

/// Askama view model for rendering session commit-message generation prompts.
#[derive(Template)]
#[template(path = "session_commit_message_prompt.md", escape = "none")]
struct SessionCommitMessagePromptTemplate<'a> {
    /// Existing commit message continuity after removing Agentty's trailer.
    current_commit_message: &'a str,
    /// Full cumulative diff payload wrapped in a Markdown fence sized for its
    /// content.
    fenced_diff: &'a str,
}

/// Stateless helpers for session process execution and output handling.
pub(crate) struct SessionTaskService;

/// Bound context for applying status transitions to one live session.
pub(crate) struct StatusTransition {
    /// App event sender used for session-update notifications.
    app_event_tx: mpsc::UnboundedSender<AppEvent>,
    /// Clock used for persisted status timing.
    clock: Arc<dyn Clock>,
    /// Repository bundle used for status persistence.
    db: AppRepositories,
    /// Stable session identifier receiving the transition.
    session_id: SessionId,
    /// Per-app session update versions shared with the main runtime.
    session_update_versions: SessionUpdateVersionMap,
    /// Shared in-memory status handle synchronized with persistence.
    status: Arc<Mutex<Status>>,
}

impl StatusTransition {
    /// Creates a transition context from shared services and runtime handles.
    pub(crate) fn from_services(
        services: &AppServices,
        handles: &SessionHandles,
        session_id: impl Into<SessionId>,
    ) -> Self {
        Self {
            app_event_tx: services.event_sender(),
            clock: services.clock(),
            db: services.db().clone(),
            session_id: session_id.into(),
            session_update_versions: services.session_update_versions(),
            status: Arc::clone(&handles.status),
        }
    }

    /// Creates a transition context from already-decomposed workflow inputs.
    pub(crate) fn from_parts(
        app_event_tx: mpsc::UnboundedSender<AppEvent>,
        clock: Arc<dyn Clock>,
        db: AppRepositories,
        session_id: impl Into<SessionId>,
        session_update_versions: SessionUpdateVersionMap,
        status: Arc<Mutex<Status>>,
    ) -> Self {
        Self {
            app_event_tx,
            clock,
            db,
            session_id: session_id.into(),
            session_update_versions,
            status,
        }
    }

    /// Applies a status transition using the bound session dependencies.
    pub(crate) async fn apply(&self, status: Status) -> bool {
        SessionTaskService::update_status(
            self.status.as_ref(),
            self.clock.as_ref(),
            &self.db,
            &self.app_event_tx,
            &self.session_update_versions,
            self.session_id.as_str(),
            status,
        )
        .await
    }

    /// Applies a status transition or returns a workflow error for invalid
    /// state-machine edges.
    pub(crate) async fn apply_or_invalid_transition(
        &self,
        status: Status,
    ) -> Result<(), SessionError> {
        if self.apply(status).await {
            return Ok(());
        }

        Err(SessionError::Workflow(format!(
            "Invalid status transition to {status}"
        )))
    }
}

/// Generated session commit details for one successful auto-commit run.
pub(crate) struct SessionCommitOutcome {
    /// Short hash of the rewritten or created `HEAD` commit.
    pub(crate) commit_hash: String,
    /// Canonical commit title/body stored on the session branch `HEAD`.
    pub(crate) commit_message: String,
}

/// Inputs needed to execute an agent-assisted edit task.
pub(crate) struct RunAgentAssistTaskInput {
    /// App event sender used for progress and status updates.
    pub(crate) app_event_tx: mpsc::UnboundedSender<AppEvent>,
    /// Shared process identifier slot used for cancellation.
    pub(crate) child_pid: Arc<Mutex<Option<u32>>>,
    /// Repository bundle used for transcript and status persistence.
    pub(crate) db: AppRepositories,
    /// Session worktree folder where the assist prompt runs.
    pub(crate) folder: std::path::PathBuf,
    /// Session identifier for persisted updates.
    pub(crate) id: String,
    /// One-shot assist prompt submitted to the agent.
    pub(crate) prompt: String,
    /// Session agent/model selection used for agent metadata and parsing.
    pub(crate) session_agent: AgentSelection,
    /// Per-app session update versions shared with the main runtime.
    pub(crate) session_update_versions: SessionUpdateVersionMap,
    /// Shared typed transcript snapshot mirrored to the render layer.
    pub(crate) transcript: Arc<Mutex<SessionTranscript>>,
}

/// Typed payload for appending one raw conversation message to the transcript
/// and durable message table.
pub(crate) struct SessionTranscriptMessageAppend<'a> {
    /// Raw conversation message kind persisted in `session_message`.
    pub(crate) kind: SessionMessageKind,
    /// Raw user or assistant content persisted without TUI formatting.
    pub(crate) raw_content: &'a str,
}

impl SessionTaskService {
    /// Increments and returns the latest observable-state version for one
    /// session handle bundle within the current app runtime.
    pub(crate) fn next_session_update_version(
        session_update_versions: &SessionUpdateVersionMap,
        id: &str,
    ) -> u64 {
        let mut session_update_versions = session_update_versions
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let entry = session_update_versions
            .entry(SessionId::from(id))
            .or_insert(0);
        *entry += 1;

        *entry
    }

    /// Removes the cached observable-state version for one deleted session so
    /// the current app runtime does not accumulate stale version entries.
    pub(crate) fn remove_session_update_version(
        session_update_versions: &SessionUpdateVersionMap,
        id: &str,
    ) {
        let mut session_update_versions = session_update_versions
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);

        session_update_versions.remove(id);
    }

    /// Bumps one session's observable-state version and emits a matching
    /// [`AppEvent::SessionUpdated`] event for targeted snapshot sync.
    ///
    /// Returns the emitted version so callers and tests can observe the exact
    /// version recorded in the shared update map.
    pub(crate) fn emit_session_updated(
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        session_update_versions: &SessionUpdateVersionMap,
        id: &str,
    ) -> u64 {
        let version = Self::next_session_update_version(session_update_versions, id);
        Self::send_app_event(
            app_event_tx,
            AppEvent::SessionUpdated {
                session_id: SessionId::from(id),
                version,
            },
            Some(id),
            "SessionUpdated",
        );

        version
    }

    /// Recomputes and persists diff-derived size and line-count totals using
    /// the session worktree diff.
    ///
    /// Returns the recomputed size plus added/deleted line totals when the
    /// base-branch lookup and persistence both succeed.
    pub(crate) async fn refresh_persisted_session_diff_stats(
        db: &AppRepositories,
        fs_client: &dyn FsClient,
        git_client: &dyn GitClient,
        session_id: &str,
        folder: &Path,
    ) -> Option<(SessionSize, u64, u64)> {
        let base_branch = match db.sessions().get_session_base_branch(session_id).await {
            Ok(base_branch) => base_branch?,
            Err(error) => {
                warn!(
                    session_id = session_id,
                    error = %error,
                    "failed to load session base branch while refreshing diff stats"
                );

                return None;
            }
        };

        let (computed_size, added_lines, deleted_lines) =
            SessionManager::session_diff_stats_for_folder(
                fs_client,
                git_client,
                folder,
                &base_branch,
            )
            .await;
        if let Err(error) = db
            .sessions()
            .update_session_diff_stats(
                added_lines,
                deleted_lines,
                session_id,
                &computed_size.to_string(),
            )
            .await
        {
            warn!(
                session_id = session_id,
                error = %error,
                "failed to persist refreshed session diff stats"
            );

            return None;
        }

        Some((computed_size, added_lines, deleted_lines))
    }

    /// Commits pending worktree changes and reports user-visible outcomes.
    ///
    /// Successful commit hashes and no-op commit notices are emitted as
    /// transient workflow notices so the transcript stays focused on agent
    /// output. Commit errors remain persisted in session output for diagnostic
    /// history. Commit-message generation and any auto-commit recovery prompt
    /// use the resolved auto-commit model for the session. Successful commits
    /// also request an immediate git-status refresh so footer ahead/behind
    /// counts do not wait for the background poller. The active loader shows a
    /// dedicated committing label for the full auto-commit phase.
    pub(in crate::app) async fn handle_auto_commit(
        context: AssistContext,
    ) -> Option<SessionCommitOutcome> {
        Self::set_session_progress(
            &context.app_event_tx,
            &context.id,
            Some(COMMITTING_PROGRESS_LABEL.to_string()),
        );

        let outcome = match Self::commit_changes_with_assist(&context).await {
            Ok(Some(outcome)) => {
                SessionManager::update_session_title_from_commit_message(
                    &context.db,
                    &context.id,
                    &outcome.commit_message,
                    &context.app_event_tx,
                )
                .await;

                let message = TranscriptNotice::Commit
                    .format_line(format!("committed with hash `{}`", outcome.commit_hash));
                Self::emit_session_workflow_notice(&context.app_event_tx, &context.id, message);
                Self::request_git_status_refresh(&context.app_event_tx);

                Some(outcome)
            }
            Ok(None) => {
                let message = TranscriptNotice::Commit.format_line("No changes to commit.");
                Self::emit_session_workflow_notice(&context.app_event_tx, &context.id, message);

                None
            }
            Err(commit_error) => {
                let message = TranscriptNotice::CommitError.format(&commit_error);
                Self::append_workflow_notice(
                    &context.transcript,
                    &context.db,
                    &context.app_event_tx,
                    &context.session_update_versions,
                    &context.id,
                    &message,
                )
                .await;

                None
            }
        };

        Self::clear_session_progress(&context.app_event_tx, &context.id);

        outcome
    }

    /// Requests one immediate reducer-driven git-status refresh.
    pub(super) fn request_git_status_refresh(app_event_tx: &mpsc::UnboundedSender<AppEvent>) {
        Self::send_app_event(
            app_event_tx,
            AppEvent::RefreshGitStatus,
            None,
            "RefreshGitStatus",
        );
    }

    /// Emits one transient workflow notice for the session output panel.
    pub(super) fn emit_session_workflow_notice(
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        id: &str,
        message: String,
    ) {
        Self::send_app_event(
            app_event_tx,
            AppEvent::SessionWorkflowNoticeUpdated {
                notice: message,
                session_id: SessionId::from(id),
            },
            Some(id),
            "SessionWorkflowNoticeUpdated",
        );
    }

    /// Loads the project-scoped toggle that controls whether generated session
    /// commit messages include the Agentty coauthor trailer.
    ///
    /// New projects default this toggle to disabled until a valid persisted
    /// boolean overrides it.
    pub(crate) async fn load_include_coauthored_by_agentty_setting(
        db: &AppRepositories,
        session_id: &str,
    ) -> bool {
        let project_id = match db.sessions().load_session_project_id(session_id).await {
            Ok(project_id) => project_id,
            Err(error) => {
                warn!(
                    session_id = session_id,
                    error = %error,
                    "failed to load session project while reading coauthor setting"
                );

                return false;
            }
        };
        let Some(project_id) = project_id else {
            return false;
        };

        let persisted_value = match db
            .settings()
            .get_project_setting(project_id, SettingName::IncludeCoauthoredByAgentty)
            .await
        {
            Ok(persisted_value) => persisted_value,
            Err(error) => {
                warn!(
                    project_id,
                    error = %error,
                    "failed to load include-coauthored-by-agentty setting"
                );

                return false;
            }
        };
        let Some(setting_value) = persisted_value else {
            return false;
        };

        match setting_value.parse::<bool>() {
            Ok(parsed_value) => parsed_value,
            Err(error) => {
                warn!(
                    project_id,
                    value = setting_value,
                    error = %error,
                    "failed to parse persisted include-coauthored-by-agentty setting"
                );

                false
            }
        }
    }

    /// Loads the agent/model selection used by auto-commit utility prompts for
    /// one session.
    ///
    /// This prefers the active project's `DefaultFastAgent` and
    /// `DefaultFastModel`, falls back through the smart defaults, and finally
    /// returns `fallback_selection` when no persisted setting can be parsed.
    pub(crate) async fn load_auto_commit_agent_setting(
        db: &AppRepositories,
        session_id: &str,
        fallback_selection: AgentSelection,
    ) -> AgentSelection {
        let project_id = match db.sessions().load_session_project_id(session_id).await {
            Ok(project_id) => project_id,
            Err(error) => {
                warn!(
                    session_id = session_id,
                    error = %error,
                    "failed to load session project while resolving auto-commit model"
                );

                return fallback_selection;
            }
        };

        setting::load_default_fast_agent_selection_from_repositories(
            db,
            project_id,
            fallback_selection,
            AgentKind::ALL,
        )
        .await
    }

    async fn commit_changes_with_assist(
        context: &AssistContext,
    ) -> Result<Option<SessionCommitOutcome>, SessionError> {
        let mut failure_tracker =
            FailureTracker::new(AUTO_COMMIT_ASSIST_POLICY.max_identical_failure_streak);
        // Test repos do not install hooks deterministically; skip hook
        // execution in tests to keep auto-commit behavior stable.
        let skip_verify_hooks = cfg!(test);

        for assist_attempt in 1..=AUTO_COMMIT_ASSIST_POLICY.max_attempts + 1 {
            match Self::commit_changes_with_git_client(context, skip_verify_hooks).await {
                Ok(commit_outcome) => {
                    return Ok(Some(commit_outcome));
                }
                Err(commit_error) if commit_error.to_string().contains("Nothing to commit") => {
                    return Ok(None);
                }
                Err(commit_error) => {
                    // Keep test execution deterministic and offline by skipping
                    // model-assisted commit retries.
                    if cfg!(test) {
                        return Err(commit_error);
                    }

                    let commit_error_str = commit_error.to_string();
                    if failure_tracker.observe(&commit_error_str) {
                        return Err(SessionError::Workflow(format!(
                            "Auto-commit assistance made no progress: repeated identical commit \
                             failure. Last error: {commit_error_str}"
                        )));
                    }

                    if assist_attempt > AUTO_COMMIT_ASSIST_POLICY.max_attempts {
                        return Err(commit_error);
                    }

                    Self::append_commit_assist_header(context, assist_attempt, &commit_error_str)
                        .await;
                    Self::run_commit_assist_for_error(context, &commit_error_str).await?;
                }
            }
        }

        Err(SessionError::Workflow(
            "Failed to auto-commit after assistance attempts".to_string(),
        ))
    }

    /// Commits all worktree changes and returns the current `HEAD` short hash.
    ///
    /// Pass `no_verify` to skip commit hooks (used in tests for deterministic
    /// execution without local `prek` hook setup). The model used for
    /// commit-message generation is resolved from the session's auto-commit
    /// settings before the git commit is attempted.
    ///
    /// # Errors
    /// Returns an error if commit-message generation, staging/commit, or
    /// `HEAD` resolution fails.
    async fn commit_changes_with_git_client(
        context: &AssistContext,
        no_verify: bool,
    ) -> Result<SessionCommitOutcome, SessionError> {
        let base_branch = context
            .db
            .sessions()
            .get_session_base_branch(&context.id)
            .await?
            .ok_or_else(|| {
                SessionError::Workflow("Missing session base branch for auto-commit".to_string())
            })?;
        let auto_commit_agent =
            Self::load_auto_commit_agent_setting(&context.db, &context.id, context.session_agent)
                .await;

        Self::commit_session_changes(
            context.git_client.as_ref(),
            &context.folder,
            &base_branch,
            auto_commit_agent,
            no_verify,
            Self::load_include_coauthored_by_agentty_setting(&context.db, &context.id).await,
        )
        .await
    }

    async fn append_commit_assist_header(
        context: &AssistContext,
        assist_attempt: usize,
        commit_error: &str,
    ) {
        let formatted_error = Self::format_commit_error_for_display(commit_error);
        append_assist_header(
            context,
            TranscriptNotice::CommitAssist,
            assist_attempt,
            AUTO_COMMIT_ASSIST_POLICY.max_attempts,
            "Resolving auto-commit failure:",
            &formatted_error,
        )
        .await;
    }

    async fn run_commit_assist_for_error(
        context: &AssistContext,
        commit_error: &str,
    ) -> Result<(), SessionError> {
        let compacted_error = compact_commit_error_for_assist(commit_error);
        let prompt = Self::auto_commit_assist_prompt(&compacted_error)?;
        let assist_context = AssistContext {
            app_event_tx: context.app_event_tx.clone(),
            child_pid: Arc::clone(&context.child_pid),
            db: context.db.clone(),
            folder: context.folder.clone(),
            git_client: Arc::clone(&context.git_client),
            id: context.id.clone(),
            session_agent: context.session_agent,
            session_update_versions: context.session_update_versions.clone(),
            transcript: Arc::clone(&context.transcript),
        };

        run_agent_assist(&assist_context, &prompt)
            .await
            .map_err(|error| error.with_context("Commit assistance failed"))
    }

    /// Renders the commit-assistance prompt from the markdown template.
    ///
    /// # Errors
    /// Returns an error if Askama template rendering fails.
    fn auto_commit_assist_prompt(commit_error: &str) -> Result<String, SessionError> {
        let commit_error = commit_error.trim();
        let template = AutoCommitAssistPromptTemplate { commit_error };

        template.render().map_err(|error| {
            SessionError::Workflow(format!(
                "Failed to render `auto_commit_assist_prompt.md`: {error}"
            ))
        })
    }

    fn format_commit_error_for_display(commit_error: &str) -> String {
        format_detail_lines(commit_error)
    }

    /// Renders the commit-message generation prompt from the markdown
    /// template.
    ///
    /// # Errors
    /// Returns an error if Askama template rendering fails.
    fn session_commit_message_prompt(
        diff: &str,
        current_commit_message: Option<&str>,
    ) -> Result<String, SessionError> {
        let stripped_current_commit_message =
            current_commit_message.map_or_else(String::new, strip_agentty_coauthor_trailer);
        let fence = agent::diff_fence(diff);
        let fenced_diff = format!("{fence}diff\n{diff}\n{fence}");
        let template = SessionCommitMessagePromptTemplate {
            current_commit_message: stripped_current_commit_message.trim(),
            fenced_diff: &fenced_diff,
        };

        template.render().map_err(|error| {
            SessionError::Workflow(format!(
                "Failed to render `session_commit_message_prompt.md`: {error}"
            ))
        })
    }

    /// Generates the canonical session commit message, commits the current
    /// worktree state, and returns the rewritten `HEAD` details.
    ///
    /// # Errors
    /// Returns an error if the worktree is clean, the cumulative session diff
    /// cannot be generated, commit-message generation fails, or the git commit
    /// cannot be created/amended.
    pub(crate) async fn commit_session_changes(
        git_client: &dyn GitClient,
        folder: &Path,
        base_branch: &str,
        session_agent: AgentSelection,
        no_verify: bool,
        include_coauthored_by_agentty: bool,
    ) -> Result<SessionCommitOutcome, SessionError> {
        if cfg!(test) {
            let folder = folder.to_path_buf();
            if git_client.is_worktree_clean(folder.clone()).await? {
                return Err(SessionError::Workflow(
                    "Nothing to commit: no changes detected".to_string(),
                ));
            }

            let has_session_commit = git_client
                .has_commits_since(folder.clone(), base_branch.to_string())
                .await?;
            let current_commit_message = if has_session_commit {
                git_client.head_commit_message(folder.clone()).await?
            } else {
                None
            };
            let Some(current_commit_message) = current_commit_message.as_deref().map(str::trim)
            else {
                return Err(SessionError::Workflow(
                    "Session commit generation requires an existing commit message during tests"
                        .to_string(),
                ));
            };
            if current_commit_message.is_empty() {
                return Err(SessionError::Workflow(
                    "Session commit generation requires a non-blank existing commit message \
                     during tests"
                        .to_string(),
                ));
            }
            let commit_message = append_agentty_coauthor_trailer(
                strip_agentty_coauthor_trailer(current_commit_message).trim(),
                include_coauthored_by_agentty,
            );
            git_client
                .commit_all_preserving_single_commit(
                    folder.clone(),
                    base_branch.to_string(),
                    commit_message.clone(),
                    git::SingleCommitMessageStrategy::Replace,
                    no_verify,
                )
                .await?;
            let commit_hash = git_client.head_short_hash(folder).await?;

            return Ok(SessionCommitOutcome {
                commit_hash,
                commit_message,
            });
        }

        let backend = agent::create_backend(session_agent.kind());

        Self::commit_session_changes_with_backend(
            git_client,
            folder,
            base_branch,
            session_agent,
            backend.as_ref(),
            no_verify,
            include_coauthored_by_agentty,
        )
        .await
    }

    /// Testable variant of [`SessionTaskService::commit_session_changes`] that
    /// accepts an injected backend for deterministic prompt generation.
    ///
    /// # Errors
    /// Returns an error if the worktree is clean, the cumulative session diff
    /// cannot be generated, commit-message generation fails, or the git commit
    /// cannot be created/amended.
    async fn commit_session_changes_with_backend(
        git_client: &dyn GitClient,
        folder: &Path,
        base_branch: &str,
        session_agent: AgentSelection,
        backend: &dyn agent::AgentBackend,
        no_verify: bool,
        include_coauthored_by_agentty: bool,
    ) -> Result<SessionCommitOutcome, SessionError> {
        let folder = folder.to_path_buf();
        if git_client.is_worktree_clean(folder.clone()).await? {
            return Err(SessionError::Workflow(
                "Nothing to commit: no changes detected".to_string(),
            ));
        }

        let diff = git_client
            .diff(folder.clone(), base_branch.to_string())
            .await?;
        let has_session_commit = git_client
            .has_commits_since(folder.clone(), base_branch.to_string())
            .await?;
        let current_commit_message = if has_session_commit {
            git_client.head_commit_message(folder.clone()).await?
        } else {
            None
        };
        let generated_commit_message = Self::generate_session_commit_message_with_backend(
            folder.as_path(),
            session_agent,
            diff.as_str(),
            current_commit_message.as_deref(),
            backend,
            include_coauthored_by_agentty,
        )
        .await?;

        git_client
            .commit_all_preserving_single_commit(
                folder.clone(),
                base_branch.to_string(),
                generated_commit_message.clone(),
                git::SingleCommitMessageStrategy::Replace,
                no_verify,
            )
            .await?;

        let commit_hash = git_client.head_short_hash(folder).await?;

        Ok(SessionCommitOutcome {
            commit_hash,
            commit_message: generated_commit_message,
        })
    }

    /// Renders the session commit-message prompt, submits it to the injected
    /// backend, validates the returned text, and appends the optional
    /// coauthor trailer in code.
    ///
    /// # Errors
    /// Returns an error when prompt rendering fails, the one-shot agent call
    /// fails, or fallback retry with a truncated diff fails after a
    /// context-window error.
    async fn generate_session_commit_message_with_backend(
        folder: &Path,
        session_agent: AgentSelection,
        diff: &str,
        current_commit_message: Option<&str>,
        backend: &dyn agent::AgentBackend,
        include_coauthored_by_agentty: bool,
    ) -> Result<String, SessionError> {
        let prompt = Self::session_commit_message_prompt(diff, current_commit_message)?;
        let submission = match Self::submit_utility_prompt_with_backend(
            session_agent,
            backend,
            agent::OneShotRequest {
                agent_kind: session_agent.kind(),
                child_pid: None,
                folder,
                model: session_agent.model(),
                prompt: &prompt,
                request_kind: ag_agent::channel::AgentRequestKind::UtilityPrompt,
                reasoning_level: crate::domain::agent::ReasoningLevel::default(),
            },
        )
        .await
        {
            Ok(submission) => submission,
            Err(error) if is_context_window_exceeded_error(&error) => {
                let Some(truncated_diff) = truncate_session_diff_for_commit_message(diff) else {
                    return Err(error);
                };
                let truncated_prompt =
                    Self::session_commit_message_prompt(&truncated_diff, current_commit_message)?;

                Self::submit_utility_prompt_with_backend(
                    session_agent,
                    backend,
                    agent::OneShotRequest {
                        agent_kind: session_agent.kind(),
                        child_pid: None,
                        folder,
                        model: session_agent.model(),
                        prompt: &truncated_prompt,
                        request_kind: ag_agent::channel::AgentRequestKind::UtilityPrompt,
                        reasoning_level: crate::domain::agent::ReasoningLevel::default(),
                    },
                )
                .await?
            }
            Err(error) => return Err(error),
        };
        let answer_text = submission.response.to_answer_display_text();
        let trimmed_answer_text = answer_text.trim();
        let validated_message = if trimmed_answer_text.is_empty() {
            fallback_session_commit_message(current_commit_message)
        } else {
            trimmed_answer_text.to_string()
        };
        validate_generated_commit_message(&validated_message)?;

        Ok(append_agentty_coauthor_trailer(
            validated_message.as_str(),
            include_coauthored_by_agentty,
        ))
    }

    /// Executes one isolated assist prompt and appends the normalized answer
    /// text to the session transcript.
    ///
    /// # Errors
    /// Returns an error when the one-shot prompt fails or returns invalid
    /// protocol output.
    pub(crate) async fn run_agent_assist_task(
        input: RunAgentAssistTaskInput,
    ) -> Result<(), SessionError> {
        let backend = agent::create_backend(input.session_agent.kind());

        Self::run_agent_assist_task_with_backend(input, backend.as_ref()).await
    }

    /// Executes one isolated assist prompt using the provided backend.
    ///
    /// # Errors
    /// Returns an error when the one-shot prompt fails or returns invalid
    /// protocol output.
    async fn run_agent_assist_task_with_backend(
        input: RunAgentAssistTaskInput,
        backend: &dyn agent::AgentBackend,
    ) -> Result<(), SessionError> {
        let RunAgentAssistTaskInput {
            app_event_tx,
            child_pid,
            db,
            folder,
            id,
            prompt,
            session_agent,
            session_update_versions,
            transcript,
        } = input;
        let assist_submission = Self::submit_utility_prompt_with_backend(
            session_agent,
            backend,
            agent::OneShotRequest {
                agent_kind: session_agent.kind(),
                child_pid: Some(child_pid.as_ref()),
                folder: &folder,
                model: session_agent.model(),
                prompt: &prompt,
                request_kind: ag_agent::channel::AgentRequestKind::UtilityPrompt,
                reasoning_level: crate::domain::agent::ReasoningLevel::default(),
            },
        )
        .await?;

        let answer_text = assist_submission.response.to_answer_display_text();
        if !answer_text.trim().is_empty() {
            Self::append_session_transcript_message(
                &transcript,
                &db,
                &app_event_tx,
                &session_update_versions,
                &id,
                SessionTranscriptMessageAppend {
                    kind: SessionMessageKind::AssistantAnswer,
                    raw_content: &answer_text,
                },
            )
            .await;
        }

        if let Err(error) = db
            .sessions()
            .update_session_stats(&id, &assist_submission.stats)
            .await
        {
            warn!(
                session_id = id,
                error = %error,
                "failed to persist session stats after utility prompt"
            );
        }

        if let Err(error) = db
            .usage()
            .upsert_session_usage(
                &id,
                session_agent.model().as_str(),
                &assist_submission.stats,
            )
            .await
        {
            warn!(
                session_id = id,
                model = %session_agent.model().as_str(),
                error = %error,
                "failed to persist session usage after utility prompt"
            );
        }

        Ok(())
    }

    /// Executes one isolated utility prompt, routing app-server-backed models
    /// through the shared app-server client while preserving backend injection
    /// for direct CLI providers in tests and production.
    ///
    /// # Errors
    /// Returns an error when the one-shot prompt fails or the response does
    /// not satisfy the structured protocol schema.
    async fn submit_utility_prompt_with_backend(
        session_agent: AgentSelection,
        backend: &dyn agent::AgentBackend,
        request: agent::OneShotRequest<'_>,
    ) -> Result<agent::OneShotSubmission, SessionError> {
        if agent::transport_mode(session_agent.kind()).uses_app_server() {
            let app_server_client = agent::create_app_server_client(session_agent.kind(), None)
                .ok_or_else(|| {
                    SessionError::Workflow(format!(
                        "{} provider did not provide an app-server client",
                        session_agent.kind()
                    ))
                })?;

            return agent::submit_one_shot_with_app_server_client(
                app_server_client.as_ref(),
                request,
            )
            .await
            .map_err(SessionError::Workflow);
        }

        agent::submit_one_shot_with_backend(backend, request)
            .await
            .map_err(SessionError::Workflow)
    }

    /// Applies a status transition to memory and database when valid.
    ///
    /// This bumps the session-update version, emits
    /// [`AppEvent::SessionUpdated`] for targeted snapshot sync, and emits
    /// session/project refresh events for transitions that affect list
    /// snapshots or project session aggregates.
    pub(crate) async fn update_status(
        status: &Mutex<Status>,
        clock: &dyn Clock,
        db: &AppRepositories,
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        session_update_versions: &SessionUpdateVersionMap,
        id: &str,
        new: Status,
    ) -> bool {
        let should_update = if let Ok(mut current) = status.lock() {
            if (*current).can_transition_to(new) {
                *current = new;
                true
            } else {
                false
            }
        } else {
            false
        };
        if !should_update {
            return false;
        }

        let timestamp_seconds = unix_timestamp_from_system_time(clock.now_system_time());

        if let Err(error) = db
            .sessions()
            .update_session_status_with_timing_at(id, &new.to_string(), timestamp_seconds)
            .await
        {
            warn!(
                session_id = id,
                status = %new,
                error = %error,
                "failed to persist session status update"
            );
        }
        Self::emit_session_updated(app_event_tx, session_update_versions, id);
        if Self::status_requires_full_refresh(new) {
            Self::send_session_and_project_refresh_events(app_event_tx, id);
        }

        true
    }

    /// Appends one formatted workflow notice to the in-memory transcript and
    /// durable message store.
    pub(crate) async fn append_workflow_notice(
        transcript: &Arc<Mutex<SessionTranscript>>,
        db: &AppRepositories,
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        session_update_versions: &SessionUpdateVersionMap,
        id: &str,
        message: &str,
    ) {
        Self::append_live_transcript_message(
            transcript,
            id,
            SessionMessageKind::WorkflowNotice,
            message,
        );
        if let Err(error) = db
            .sessions()
            .append_session_message(id, SessionMessageKind::WorkflowNotice, message)
            .await
        {
            warn!(
                session_id = id,
                error = %error,
                "failed to persist workflow notice"
            );
        }
        Self::emit_session_updated(app_event_tx, session_update_versions, id);
    }

    /// Appends one raw user/assistant message to the in-memory transcript and
    /// durable message store.
    pub(crate) async fn append_session_transcript_message(
        transcript: &Arc<Mutex<SessionTranscript>>,
        db: &AppRepositories,
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        session_update_versions: &SessionUpdateVersionMap,
        id: &str,
        message: SessionTranscriptMessageAppend<'_>,
    ) {
        Self::append_live_transcript_message(transcript, id, message.kind, message.raw_content);
        if let Err(error) = db
            .sessions()
            .append_session_message(id, message.kind, message.raw_content)
            .await
        {
            warn!(
                session_id = id,
                error = %error,
                "failed to persist session transcript message"
            );
        }
        Self::emit_session_updated(app_event_tx, session_update_versions, id);
    }

    /// Appends one typed message to the live transcript snapshot.
    fn append_live_transcript_message(
        transcript: &Arc<Mutex<SessionTranscript>>,
        id: &str,
        kind: SessionMessageKind,
        content: &str,
    ) {
        match transcript.lock() {
            Ok(mut transcript) => transcript.append_message(kind, content),
            Err(error) => {
                warn!(
                    session_id = id,
                    error = %error,
                    "failed to lock session transcript buffer"
                );
            }
        }
    }

    /// Clears the transient thinking message for one session.
    pub(crate) fn clear_session_progress(app_event_tx: &mpsc::UnboundedSender<AppEvent>, id: &str) {
        Self::set_session_progress(app_event_tx, id, None);
    }

    /// Emits a transient thinking message update for one session.
    pub(crate) fn set_session_progress(
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        id: &str,
        progress_message: Option<String>,
    ) {
        Self::send_app_event(
            app_event_tx,
            AppEvent::SessionProgressUpdated {
                progress_message,
                session_id: SessionId::from(id),
            },
            Some(id),
            "SessionProgressUpdated",
        );
    }

    fn status_requires_full_refresh(status: Status) -> bool {
        matches!(
            status,
            Status::InProgress | Status::Review | Status::Merging | Status::Done | Status::Canceled
        )
    }

    /// Emits session and project refresh events for persisted lifecycle
    /// changes that can alter both session rows and project aggregates.
    fn send_session_and_project_refresh_events(
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        session_id: &str,
    ) {
        Self::send_app_event(
            app_event_tx,
            AppEvent::RefreshSessions,
            Some(session_id),
            "RefreshSessions",
        );
        Self::send_app_event(
            app_event_tx,
            AppEvent::RefreshProjects,
            Some(session_id),
            "RefreshProjects",
        );
    }

    /// Emits one app event and warns when the reducer side has already shut
    /// down.
    fn send_app_event(
        app_event_tx: &mpsc::UnboundedSender<AppEvent>,
        event: AppEvent,
        session_id: Option<&str>,
        event_name: &str,
    ) {
        if app_event_tx.send(event).is_err() {
            if let Some(session_id) = session_id {
                warn!(
                    session_id = session_id,
                    event = event_name,
                    "failed to send app event because the receiver is closed"
                );
            } else {
                warn!(
                    event = event_name,
                    "failed to send app event because the receiver is closed"
                );
            }
        }
    }
}

/// Removes the Agentty coauthor trailer from one commit message so prompt
/// continuity and test-mode reuse operate on body/title content only.
fn strip_agentty_coauthor_trailer(commit_message: &str) -> String {
    commit_message
        .lines()
        .filter(|line| line.trim() != SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER)
        .collect::<Vec<_>>()
        .join("\n")
}

/// Returns a deterministic fallback commit message when protocol `answer` text
/// is blank.
///
/// Prefers the first non-empty continuity line (without trailer noise) when
/// available and otherwise falls back to a generic session-update title.
fn fallback_session_commit_message(current_commit_message: Option<&str>) -> String {
    let stripped_current_commit_message = current_commit_message
        .map(strip_agentty_coauthor_trailer)
        .unwrap_or_default();
    if stripped_current_commit_message.trim().is_empty() {
        return "Apply session updates".to_string();
    }

    stripped_current_commit_message
        .lines()
        .map(str::trim)
        .find(|line| !line.is_empty())
        .unwrap_or("Apply session updates")
        .to_string()
}

/// Validates generated commit-message output before git commit creation.
///
/// # Errors
/// Returns an error when the generated message already contains the Agentty
/// coauthor trailer, which is appended by code instead of model output.
fn validate_generated_commit_message(commit_message: &str) -> Result<(), SessionError> {
    if commit_message
        .lines()
        .any(|line| line.trim() == SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER)
    {
        return Err(SessionError::Workflow(
            "Session commit message model must not emit the Agentty coauthor trailer".to_string(),
        ));
    }

    Ok(())
}

/// Appends the Agentty coauthor trailer when the project setting enables it.
fn append_agentty_coauthor_trailer(
    commit_message: &str,
    include_coauthored_by_agentty: bool,
) -> String {
    let trimmed_commit_message = commit_message.trim().to_string();

    if !include_coauthored_by_agentty || trimmed_commit_message.is_empty() {
        return trimmed_commit_message;
    }

    format!("{trimmed_commit_message}\n\n{SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER}")
}

/// Returns true when a commit-generation error indicates a failed app-server
/// one-shot flow due to provider context limits.
fn is_context_window_exceeded_error(error: &SessionError) -> bool {
    match error {
        SessionError::Workflow(message) => is_context_window_exceeded_error_message(message),
        _ => false,
    }
}

/// Returns whether a commit-assist error message indicates a provider context
/// window overflow and is therefore a candidate for error compaction.
fn is_context_window_exceeded_error_message(message: &str) -> bool {
    message.contains("contextWindowExceeded")
        || message.contains("context_window_exceeded")
        || message.contains("context window exceeded")
}

/// Returns a commit-assist error compacted for prompt context when the
/// model-reported context window has already been exceeded.
///
/// The helper keeps both the head and tail of the error text and inserts a
/// small marker between them so critical diagnostics and retry details remain
/// visible while trimming duplicated or excessive payload.
fn compact_commit_error_for_assist(commit_error: &str) -> String {
    if !is_context_window_exceeded_error_message(commit_error) {
        return commit_error.to_string();
    }

    if commit_error.chars().count() <= AUTO_COMMIT_ERROR_TRUNCATION_LIMIT {
        return commit_error.to_string();
    }

    let half_limit = AUTO_COMMIT_ERROR_TRUNCATION_LIMIT / 2;
    let error_head = commit_error.chars().take(half_limit).collect::<String>();
    let error_tail = commit_error
        .chars()
        .rev()
        .take(half_limit)
        .collect::<String>()
        .chars()
        .rev()
        .collect::<String>();

    format!("{error_head}\n\n{AUTO_COMMIT_ERROR_TRUNCATED_SECTION_MARKER}\n\n{error_tail}")
}

/// Returns a truncated diff payload if the input exceeds the safe assistant
/// window.
///
/// Keeps the head and tail of the diff, inserts a marker, and returns `None`
/// when truncation is unnecessary.
fn truncate_session_diff_for_commit_message(diff: &str) -> Option<String> {
    if diff.chars().count() <= SESSION_COMMIT_DIFF_TRUNCATION_LIMIT {
        return None;
    }

    let half_limit = SESSION_COMMIT_DIFF_TRUNCATION_LIMIT / 2;
    let diff_head = diff.chars().take(half_limit).collect::<String>();
    let diff_tail = diff
        .chars()
        .rev()
        .take(half_limit)
        .collect::<String>()
        .chars()
        .rev()
        .collect::<String>();

    Some(format!(
        "{diff_head}\n\n{SESSION_COMMIT_DIFF_TRUNCATED_SECTION_MARKER}\n\n{diff_tail}"
    ))
}

#[cfg(test)]
mod tests {
    use std::fmt::Write as _;
    use std::path::PathBuf;
    use std::process::Command;
    use std::sync::Mutex as StdMutex;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::time::{Duration, Instant, SystemTime};

    use ag_agent::agent::tests::MockAgentBackend;
    use ag_agent::channel::AgentRequestKind;
    use ag_git::{GitError, MockGitClient};

    use super::*;
    use crate::app::service::AppServiceDeps;
    use crate::db::AppRepositories;
    use crate::domain::agent::AgentCliInfo;
    use crate::domain::session_message::SessionMessage;
    use crate::infra::fs;

    /// Mutable test clock used to drive deterministic status-transition timing
    /// assertions.
    struct StaticClock {
        now_system_time: StdMutex<SystemTime>,
    }

    impl StaticClock {
        /// Creates a test clock seeded with one wall-clock timestamp.
        fn new(now_system_time: SystemTime) -> Self {
            Self {
                now_system_time: StdMutex::new(now_system_time),
            }
        }

        /// Replaces the current wall-clock timestamp returned by the clock.
        fn set_now_system_time(&self, now_system_time: SystemTime) {
            *self
                .now_system_time
                .lock()
                .expect("static clock lock should not be poisoned") = now_system_time;
        }
    }

    impl Clock for StaticClock {
        fn now_instant(&self) -> Instant {
            Instant::now()
        }

        fn now_system_time(&self) -> SystemTime {
            *self
                .now_system_time
                .lock()
                .expect("static clock lock should not be poisoned")
        }
    }

    /// Builds one deterministic shell command used by mocked backends.
    fn mock_shell_command(stdout: &str, stderr: &str, exit_code: i32) -> Command {
        let mut command = Command::new("sh");
        command.arg("-c").arg(
            "printf '%s' \"$ASSIST_STDOUT\"; printf '%s' \"$ASSIST_STDERR\" >&2; exit \
             \"$ASSIST_EXIT\"",
        );
        command.env("ASSIST_STDOUT", stdout);
        command.env("ASSIST_STDERR", stderr);
        command.env("ASSIST_EXIT", exit_code.to_string());
        command.stdout(std::process::Stdio::piped());
        command.stderr(std::process::Stdio::piped());

        command
    }

    /// Inserts one review session used by assist-task tests.
    async fn insert_review_session(database: &AppRepositories, model: &str) {
        let project_id = database
            .projects()
            .upsert_project("/tmp/project", Some("main".to_string()))
            .await
            .expect("failed to upsert project");
        database
            .sessions()
            .insert_session("session-id", model, "main", "Review", project_id)
            .await
            .expect("failed to insert session");
    }

    #[tokio::test]
    async fn test_append_workflow_notice_updates_live_and_durable_workflow_transcript() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let session_update_versions = Arc::default();

        // Act
        SessionTaskService::append_workflow_notice(
            &transcript,
            &database,
            &app_event_tx,
            &session_update_versions,
            "session-id",
            "\n[Commit] No changes to commit.\n",
        )
        .await;

        // Assert
        assert_eq!(
            transcript
                .lock()
                .expect("transcript lock should not be poisoned")
                .replay_text()
                .expect("transcript should have replay text"),
            "\n[Commit] No changes to commit.\n"
        );
        assert_eq!(
            transcript
                .lock()
                .expect("transcript lock should not be poisoned")
                .messages(),
            &[SessionMessage::new(
                0,
                SessionMessageKind::WorkflowNotice,
                "\n[Commit] No changes to commit.\n"
            )]
        );
        let messages = database
            .sessions()
            .load_session_messages("session-id")
            .await
            .expect("failed to load persisted session messages");
        assert_eq!(messages.len(), 1);
        assert_eq!(messages[0].kind, "workflow_notice");
        assert_eq!(messages[0].content, "\n[Commit] No changes to commit.\n");
    }

    #[tokio::test]
    async fn test_append_session_transcript_message_updates_live_and_durable_typed_transcript() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let session_update_versions = Arc::default();

        // Act
        SessionTaskService::append_session_transcript_message(
            &transcript,
            &database,
            &app_event_tx,
            &session_update_versions,
            "session-id",
            SessionTranscriptMessageAppend {
                kind: SessionMessageKind::UserPrompt,
                raw_content: " hello ",
            },
        )
        .await;

        // Assert
        assert_eq!(
            transcript
                .lock()
                .expect("transcript lock should not be poisoned")
                .replay_text()
                .expect("transcript should have replay text"),
            " › hello\n\n"
        );
        assert_eq!(
            transcript
                .lock()
                .expect("transcript lock should not be poisoned")
                .messages(),
            &[SessionMessage::conversation(
                0,
                SessionMessageKind::UserPrompt,
                "hello"
            )]
        );
        let messages = database
            .sessions()
            .load_session_messages("session-id")
            .await
            .expect("failed to load persisted session messages");
        assert_eq!(messages.len(), 1);
        assert_eq!(messages[0].kind, "user_prompt");
        assert_eq!(messages[0].content, "hello");
    }

    #[test]
    /// Verifies lifecycle statuses that require full list refreshes are
    /// enumerated correctly.
    fn test_status_requires_full_refresh_for_lifecycle_statuses() {
        // Arrange
        let refresh_statuses = [
            Status::InProgress,
            Status::Review,
            Status::Merging,
            Status::Done,
            Status::Canceled,
        ];

        // Act & Assert
        for status in refresh_statuses {
            assert!(SessionTaskService::status_requires_full_refresh(status));
        }
        assert!(!SessionTaskService::status_requires_full_refresh(
            Status::Draft
        ));
    }

    #[tokio::test]
    async fn test_update_status_accumulates_repeated_in_progress_intervals() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        let project_id = database
            .projects()
            .upsert_project("/tmp/project", Some("main".to_string()))
            .await
            .expect("failed to upsert project");
        database
            .sessions()
            .insert_session(
                "session-id",
                "gpt-5.5",
                "main",
                &Status::Draft.to_string(),
                project_id,
            )
            .await
            .expect("failed to insert session");
        let status = Mutex::new(Status::Draft);
        let clock = StaticClock::new(SystemTime::UNIX_EPOCH + Duration::from_secs(10));
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let session_update_versions = Arc::default();

        // Act
        let entered_first_interval = SessionTaskService::update_status(
            &status,
            &clock,
            &database,
            &app_event_tx,
            &session_update_versions,
            "session-id",
            Status::InProgress,
        )
        .await;
        clock.set_now_system_time(SystemTime::UNIX_EPOCH + Duration::from_secs(70));
        let left_first_interval = SessionTaskService::update_status(
            &status,
            &clock,
            &database,
            &app_event_tx,
            &session_update_versions,
            "session-id",
            Status::Review,
        )
        .await;
        clock.set_now_system_time(SystemTime::UNIX_EPOCH + Duration::from_secs(100));
        let entered_second_interval = SessionTaskService::update_status(
            &status,
            &clock,
            &database,
            &app_event_tx,
            &session_update_versions,
            "session-id",
            Status::InProgress,
        )
        .await;
        clock.set_now_system_time(SystemTime::UNIX_EPOCH + Duration::from_secs(190));
        let left_second_interval = SessionTaskService::update_status(
            &status,
            &clock,
            &database,
            &app_event_tx,
            &session_update_versions,
            "session-id",
            Status::Question,
        )
        .await;
        let session_row = database
            .sessions()
            .load_sessions()
            .await
            .expect("failed to load sessions")
            .into_iter()
            .find(|row| row.id == "session-id")
            .expect("missing session row");

        // Assert
        assert!(entered_first_interval);
        assert!(left_first_interval);
        assert!(entered_second_interval);
        assert!(left_second_interval);
        assert_eq!(session_row.status, "Question");
        assert_eq!(session_row.in_progress_started_at, None);
        assert_eq!(session_row.in_progress_total_seconds, 150);
    }

    /// Verifies the status-transition context updates both live handles and
    /// persisted rows when built from shared services.
    #[tokio::test]
    async fn test_status_transition_from_services_updates_handle_and_persistence() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, "gpt-5.5").await;
        let handles = SessionHandles::new(Status::Review);
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let services = AppServices::new_with_agent_clis(
            PathBuf::from("/tmp/agentty-tests"),
            Arc::new(StaticClock::new(
                SystemTime::UNIX_EPOCH + Duration::from_secs(42),
            )),
            app_event_tx,
            AppServiceDeps {
                app_server_client_override: Some(crate::test_support::mock_app_server()),
                available_agent_kinds: AgentKind::ALL.to_vec(),
                clipboard_image_client_override: None,
                fs_client: Arc::new(fs::MockFsClient::new()),
                git_client: Arc::new(MockGitClient::new()),
                repositories: database.clone(),
                review_request_client: Arc::new(ag_forge::MockReviewRequestClient::new()),
            },
            AgentCliInfo::from_kinds(AgentKind::ALL),
        );
        let status_transition = StatusTransition::from_services(&services, &handles, "session-id");

        // Act
        let status_updated = status_transition.apply(Status::InProgress).await;
        let live_status = handles
            .status
            .lock()
            .expect("status lock should not be poisoned")
            .to_string();
        let session_row = database
            .sessions()
            .load_sessions()
            .await
            .expect("failed to load sessions")
            .into_iter()
            .find(|row| row.id == "session-id")
            .expect("missing session row");

        // Assert
        assert!(status_updated);
        assert_eq!(live_status, Status::InProgress.to_string());
        assert_eq!(session_row.status, Status::InProgress.to_string());
    }

    #[test]
    /// Ensures commit assistance prompts include the raw git failure details.
    fn test_auto_commit_assist_prompt_includes_commit_error() {
        // Arrange
        let commit_error = "Failed to commit: merge conflict remains";

        // Act
        let prompt = SessionTaskService::auto_commit_assist_prompt(commit_error)
            .expect("auto commit assist prompt should render");

        // Assert
        assert!(prompt.contains("Failed to commit: merge conflict remains"));
        assert!(prompt.contains("return the required protocol JSON object"));
        assert!(prompt.contains("was fixed in `answer`"));
        assert!(prompt.contains("leave `questions` empty"));
        assert!(prompt.contains("set `summary` to null"));
    }

    #[test]
    /// Ensures commit error formatting normalizes output as bullet lines.
    fn test_format_commit_error_for_display_returns_bulleted_lines() {
        // Arrange
        let commit_error = "line one\nline two";

        // Act
        let formatted = SessionTaskService::format_commit_error_for_display(commit_error);

        // Assert
        assert_eq!(formatted, "- line one\n- line two");
    }

    #[test]
    /// Verifies session commit-message prompts include continuity, the
    /// cumulative diff, and current skill-directory guidance.
    fn test_session_commit_message_prompt_includes_continuity_and_diff() {
        // Arrange
        let diff = "diff --git a/a.rs b/a.rs";
        let current_commit_message = Some("Keep session commit accurate");

        // Act
        let prompt =
            SessionTaskService::session_commit_message_prompt(diff, current_commit_message)
                .expect("prompt should render");

        // Assert
        assert!(prompt.contains("Keep session commit accurate"));
        assert!(prompt.contains(diff));
        assert!(prompt.contains("required protocol JSON object"));
        assert!(prompt.contains("Apply this precedence order"));
        assert!(prompt.contains("`.agents/skills/`"));
        assert!(!prompt.contains("`.gemini/skills/`"));
        assert!(!prompt.contains("Return one plain-text commit message"));
        assert!(!prompt.contains(SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER));
        let fenced_diff = format!("```diff\n{diff}\n```");
        assert!(
            prompt.contains(&fenced_diff),
            "commit-message prompt must wrap the diff in a ```diff``` fence so `@`-prefixed \
             decorator tokens are not misread as file mentions"
        );
    }

    #[test]
    /// Ensures the commit-message prompt escapes a triple-backtick fence that
    /// appears inside the diff itself (for example when committing changes to
    /// a Markdown or prompt-template file) by widening the outer fence so it
    /// cannot be terminated by the diff content.
    fn test_session_commit_message_prompt_escapes_triple_backtick_fence_in_diff() {
        // Arrange
        let diff = concat!(
            "diff --git a/a.md b/a.md\n",
            "+```\n",
            "+example fenced block\n",
            "+```\n",
        );
        let current_commit_message: Option<&str> = None;

        // Act
        let prompt =
            SessionTaskService::session_commit_message_prompt(diff, current_commit_message)
                .expect("prompt should render");

        // Assert
        assert!(
            prompt.contains("````diff\n"),
            "outer fence must be longer than the longest backtick run in the diff to preserve \
             prompt boundaries"
        );
        let matches = prompt.matches("\n````").count();
        assert!(
            matches >= 2,
            "prompt must contain an opening and closing 4-backtick fence, got {matches} \
             occurrences"
        );
        assert!(prompt.contains("+```\n"));
    }

    #[test]
    /// Verifies prompt rendering strips the Agentty trailer from existing
    /// commit-message continuity before sending it back to the model.
    fn test_session_commit_message_prompt_strips_coauthor_trailer_from_continuity() {
        // Arrange
        let diff = "diff --git a/a.rs b/a.rs";
        let current_commit_message = format!(
            "Keep session commit accurate\n\n{SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER}"
        );

        // Act
        let prompt = SessionTaskService::session_commit_message_prompt(
            diff,
            Some(current_commit_message.as_str()),
        )
        .expect("prompt should render");

        // Assert
        assert!(!prompt.contains(SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER));
        assert!(prompt.contains("Keep session commit accurate"));
    }

    #[tokio::test]
    /// Verifies plain-text one-shot output is rejected for session commit
    /// message generation after both the original parse and the
    /// protocol-repair retry fail.
    async fn test_generate_session_commit_message_with_backend_rejects_plain_text_output() {
        // Arrange — use a CLI-backed model so the mock backend is exercised.
        // App-server-backed Codex models bypass `build_command` entirely and
        // route through the shared app-server client.
        let temp_directory = tempfile::tempdir().expect("failed to create temp dir");
        let mut backend = MockAgentBackend::new();
        backend
            .expect_build_command()
            .times(2)
            .returning(|request| {
                assert!(matches!(
                    request.request_kind,
                    AgentRequestKind::UtilityPrompt
                ));

                Ok(mock_shell_command(
                    "Refactor agent prompt and protocol handling",
                    "",
                    0,
                ))
            });

        // Act
        let error = SessionTaskService::generate_session_commit_message_with_backend(
            temp_directory.path(),
            AgentSelection::new(AgentKind::Claude, AgentModel::ClaudeSonnet5),
            "diff --git a/a.rs b/a.rs",
            None,
            &backend,
            false,
        )
        .await
        .expect_err("plain-text one-shot commit message should fail");

        // Assert
        assert!(
            error
                .to_string()
                .contains("did not match the required JSON schema")
        );
        assert!(
            error
                .to_string()
                .contains("response:\nRefactor agent prompt and protocol handling")
        );
    }

    #[tokio::test]
    /// Verifies blank commit-message protocol output falls back to the
    /// continuity title and keeps auto-commit progressing.
    async fn test_generate_session_commit_message_with_backend_falls_back_for_blank_answer() {
        // Arrange
        let temp_directory = tempfile::tempdir().expect("failed to create temp dir");
        let mut backend = MockAgentBackend::new();
        backend
            .expect_build_command()
            .times(1)
            .returning(|request| {
                assert!(matches!(
                    request.request_kind,
                    AgentRequestKind::UtilityPrompt
                ));

                Ok(mock_shell_command(
                    r#"{"answer":"","questions":[],"summary":null}"#,
                    "",
                    0,
                ))
            });

        // Act
        let generated_message = SessionTaskService::generate_session_commit_message_with_backend(
            temp_directory.path(),
            AgentSelection::new(AgentKind::Claude, AgentModel::ClaudeSonnet5),
            "diff --git a/a.rs b/a.rs",
            Some("Keep session commit accurate\n\n- Preserve existing behavior"),
            &backend,
            false,
        )
        .await
        .expect("blank answer should fall back to continuity title");

        // Assert
        assert_eq!(generated_message, "Keep session commit accurate");
    }

    #[tokio::test]
    /// Verifies large diffs are retried with truncation after a
    /// context-window-overflow one-shot failure.
    async fn test_generate_session_commit_message_with_backend_retries_with_truncated_diff() {
        // Arrange
        let temp_directory = tempfile::tempdir().expect("failed to create temp dir");
        let diff = "diff line\n".repeat(SESSION_COMMIT_DIFF_TRUNCATION_LIMIT + 1);
        let call_count = Arc::new(AtomicUsize::new(0));
        let call_count_for_build = Arc::clone(&call_count);
        let mut backend = MockAgentBackend::new();
        backend
            .expect_build_command()
            .times(2)
            .returning(move |request| {
                let request_index = call_count_for_build.fetch_add(1, Ordering::SeqCst) + 1;
                assert!(matches!(
                    request.request_kind,
                    AgentRequestKind::UtilityPrompt
                ));

                if request_index == 1 {
                    assert!(request.prompt.contains("diff line"));

                    return Ok(mock_shell_command("", "contextWindowExceeded", 1));
                }

                assert!(
                    request
                        .prompt
                        .contains(SESSION_COMMIT_DIFF_TRUNCATED_SECTION_MARKER)
                );
                assert!(request.prompt.len() < SESSION_COMMIT_DIFF_TRUNCATION_LIMIT * 2);

                Ok(mock_shell_command(
                    r#"{"answer":"Truncated diff commit","questions":[],"summary":null}"#,
                    "",
                    0,
                ))
            });

        // Act
        let generated_message = SessionTaskService::generate_session_commit_message_with_backend(
            temp_directory.path(),
            AgentSelection::new(AgentKind::Claude, AgentModel::ClaudeSonnet5),
            diff.as_str(),
            None,
            &backend,
            false,
        )
        .await
        .expect("truncated retry should succeed");

        // Assert
        assert_eq!(generated_message, "Truncated diff commit");
        assert_eq!(call_count.load(Ordering::SeqCst), 2);
    }

    #[test]
    /// Verifies context-window overflow error detection recognizes provider
    /// diagnostics.
    fn test_is_context_window_exceeded_error_detects_window_limits() {
        // Arrange
        let overflow_error =
            SessionError::Workflow("Codex app-server failed: contextWindowExceeded".to_string());
        let other_error = SessionError::Workflow("network timeout".to_string());

        // Act
        let overflow_is_detected = is_context_window_exceeded_error(&overflow_error);
        let other_is_detected = is_context_window_exceeded_error(&other_error);

        // Assert
        assert!(overflow_is_detected);
        assert!(!other_is_detected);
    }

    #[test]
    /// Verifies long context-window overflow messages are compacted for
    /// auto-commit assistance prompts.
    fn test_compact_commit_error_for_assist_truncates_overflow_messages() {
        // Arrange
        let commit_error = "contextWindowExceeded\n".repeat(10_000);

        // Act
        let compacted = compact_commit_error_for_assist(&commit_error);

        // Assert
        assert!(compacted.len() < commit_error.len());
        assert!(compacted.contains(AUTO_COMMIT_ERROR_TRUNCATED_SECTION_MARKER));
    }

    #[test]
    /// Verifies non-window-overflow messages are left unchanged.
    fn test_compact_commit_error_for_assist_keeps_non_overflow_messages() {
        // Arrange
        let commit_error = "network timeout while pushing";

        // Act
        let compacted = compact_commit_error_for_assist(commit_error);

        // Assert
        assert_eq!(compacted, commit_error);
    }

    #[test]
    /// Verifies diff truncation removes middle content and adds a marker.
    fn test_truncate_session_commit_diff_preserves_edge_content() {
        // Arrange
        let mut diff = String::new();
        for index in 0..=SESSION_COMMIT_DIFF_TRUNCATION_LIMIT {
            writeln!(&mut diff, "file {index}").expect("writing to string should succeed");
        }

        // Act
        let truncated =
            truncate_session_diff_for_commit_message(&diff).expect("long diff should be truncated");

        // Assert
        assert!(truncated.contains(SESSION_COMMIT_DIFF_TRUNCATED_SECTION_MARKER));
        assert!(truncated.len() < diff.len());
        assert!(truncated.starts_with("file 0"));
        assert!(truncated.contains("file 60000"));
    }

    #[test]
    /// Verifies append-only handling adds the coauthor trailer once
    /// when the setting is enabled.
    fn test_append_agentty_coauthor_trailer_appends_trailer_once() {
        // Arrange
        let commit_message = "Refine settings page";

        // Act
        let appended_commit_message = append_agentty_coauthor_trailer(commit_message, true);

        // Assert
        assert_eq!(
            appended_commit_message,
            format!("Refine settings page\n\n{SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER}")
        );
    }

    #[test]
    /// Verifies append-only handling leaves the generated message unchanged
    /// when the setting is disabled.
    fn test_append_agentty_coauthor_trailer_leaves_message_unchanged_when_disabled() {
        // Arrange
        let commit_message = "Refine settings page";

        // Act
        let appended_commit_message = append_agentty_coauthor_trailer(commit_message, false);

        // Assert
        assert_eq!(appended_commit_message, "Refine settings page");
    }

    #[test]
    /// Verifies generated commit-message validation rejects model output that
    /// already includes the Agentty trailer.
    fn test_validate_generated_commit_message_rejects_agentty_trailer() {
        // Arrange
        let commit_message =
            format!("Refine settings page\n\n{SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER}");

        // Act
        let error = validate_generated_commit_message(&commit_message)
            .expect_err("generated trailer should fail validation");

        // Assert
        assert_eq!(
            error.to_string(),
            "Session commit message model must not emit the Agentty coauthor trailer"
        );
    }

    #[test]
    /// Verifies trailer stripping removes the Agentty trailer from reused
    /// commit-message continuity.
    fn test_strip_agentty_coauthor_trailer_removes_trailer_line() {
        // Arrange
        let commit_message =
            format!("Refine settings page\n\n{SESSION_COMMIT_COAUTHORED_BY_AGENTTY_TRAILER}");

        // Act
        let stripped_commit_message = strip_agentty_coauthor_trailer(&commit_message);

        // Assert
        assert_eq!(stripped_commit_message, "Refine settings page\n");
    }

    #[tokio::test]
    /// Verifies commit helper failure appends a commit error message without
    /// invoking real git or agent subprocesses.
    async fn test_handle_auto_commit_appends_commit_error_from_mock_git_client() {
        // Arrange
        let mut mock_git_client = MockGitClient::new();
        mock_git_client
            .expect_is_worktree_clean()
            .times(1)
            .returning(|_| {
                Box::pin(async { Err(GitError::OutputParse("commit failed".to_string())) })
            });
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let context = AssistContext {
            app_event_tx,
            child_pid: Arc::new(Mutex::new(None)),
            db: database.clone(),
            folder: PathBuf::from("/tmp/project"),
            git_client: Arc::new(mock_git_client),
            id: "session-id".to_string(),
            session_agent: AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55),
            session_update_versions: Arc::default(),
            transcript: Arc::clone(&transcript),
        };

        // Act
        SessionTaskService::handle_auto_commit(context).await;

        // Assert
        let output_text = transcript
            .lock()
            .ok()
            .and_then(|buffer| buffer.replay_text())
            .unwrap_or_default();
        assert!(output_text.contains("[Commit Error] commit failed"));
    }

    #[tokio::test]
    /// Verifies auto-commit reports clean-worktree no-op commits as transient
    /// workflow notices without appending to the transcript.
    async fn test_handle_auto_commit_reports_when_no_changes_exist() {
        // Arrange
        let mut mock_git_client = MockGitClient::new();
        mock_git_client
            .expect_is_worktree_clean()
            .times(1)
            .returning(|_| Box::pin(async { Ok::<_, GitError>(true) }));
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let (app_event_tx, mut app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let context = AssistContext {
            app_event_tx,
            child_pid: Arc::new(Mutex::new(None)),
            db: database.clone(),
            folder: PathBuf::from("/tmp/project"),
            git_client: Arc::new(mock_git_client),
            id: "session-id".to_string(),
            session_agent: AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55),
            session_update_versions: Arc::default(),
            transcript: Arc::clone(&transcript),
        };

        // Act
        SessionTaskService::handle_auto_commit(context).await;

        // Assert
        let output_text = transcript
            .lock()
            .ok()
            .and_then(|buffer| buffer.replay_text())
            .unwrap_or_default();
        let events = std::iter::from_fn(|| app_event_rx.try_recv().ok()).collect::<Vec<_>>();
        assert!(!output_text.contains("[Commit] No changes to commit."));
        assert!(events.contains(&AppEvent::SessionProgressUpdated {
            progress_message: Some(COMMITTING_PROGRESS_LABEL.to_string()),
            session_id: "session-id".into(),
        }));
        assert!(events.iter().any(|event| matches!(
            event,
            AppEvent::SessionWorkflowNoticeUpdated {
                notice,
                session_id,
            } if session_id.as_str() == "session-id"
                && notice == "[Commit] No changes to commit."
        )));
        assert!(events.contains(&AppEvent::SessionProgressUpdated {
            progress_message: None,
            session_id: "session-id".into(),
        }));
    }

    #[tokio::test]
    /// Verifies the coauthor trailer setting defaults to disabled when the
    /// project has not persisted a value yet.
    async fn test_load_include_coauthored_by_agentty_setting_defaults_to_false() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;

        // Act
        let include_coauthored_by_agentty =
            SessionTaskService::load_include_coauthored_by_agentty_setting(&database, "session-id")
                .await;

        // Assert
        assert!(!include_coauthored_by_agentty);
    }

    #[tokio::test]
    /// Verifies the coauthor trailer setting defaults to disabled when the
    /// stored value cannot be parsed as a boolean.
    async fn test_load_include_coauthored_by_agentty_setting_defaults_invalid_value_to_false() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let project_id = database
            .sessions()
            .load_session_project_id("session-id")
            .await
            .expect("failed to load session project id")
            .expect("session should have project id");
        database
            .settings()
            .upsert_project_setting(
                project_id,
                SettingName::IncludeCoauthoredByAgentty,
                "invalid-bool",
            )
            .await
            .expect("failed to persist invalid coauthor flag");

        // Act
        let include_coauthored_by_agentty =
            SessionTaskService::load_include_coauthored_by_agentty_setting(&database, "session-id")
                .await;

        // Assert
        assert!(!include_coauthored_by_agentty);
    }

    #[tokio::test]
    /// Verifies successful auto-commit updates the title while preserving the
    /// persisted agent session summary text.
    async fn test_handle_auto_commit_preserves_agent_session_summary() {
        // Arrange
        let mut mock_git_client = MockGitClient::new();
        mock_git_client
            .expect_is_worktree_clean()
            .times(1)
            .returning(|_| Box::pin(async { Ok::<_, GitError>(false) }));
        mock_git_client
            .expect_has_commits_since()
            .times(1)
            .returning(|_, _| Box::pin(async { Ok::<_, GitError>(true) }));
        mock_git_client
            .expect_head_commit_message()
            .times(1)
            .returning(|_| {
                Box::pin(async {
                    Ok::<_, GitError>(Some(
                        "Refine README updates\n\n- Keep title aligned with commit".to_string(),
                    ))
                })
            });
        mock_git_client
            .expect_commit_all_preserving_single_commit()
            .times(1)
            .returning(|_, _, _, _, _| Box::pin(async { Ok::<_, GitError>(()) }));
        mock_git_client
            .expect_head_short_hash()
            .times(1)
            .returning(|_| Box::pin(async { Ok::<_, GitError>("abc1234".to_string()) }));
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let summary_payload = "- Session branch updates README formatting.".to_string();
        database
            .sessions()
            .update_session_summary("session-id", &summary_payload)
            .await
            .expect("failed to persist summary text");
        let (app_event_tx, mut app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let context = AssistContext {
            app_event_tx,
            child_pid: Arc::new(Mutex::new(None)),
            db: database.clone(),
            folder: PathBuf::from("/tmp/project"),
            git_client: Arc::new(mock_git_client),
            id: "session-id".to_string(),
            session_agent: AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55),
            session_update_versions: Arc::default(),
            transcript: Arc::clone(&transcript),
        };

        // Act
        SessionTaskService::handle_auto_commit(context).await;
        let sessions = database
            .sessions()
            .load_sessions()
            .await
            .expect("failed to load sessions");

        // Assert
        assert_eq!(sessions[0].title.as_deref(), Some("Refine README updates"));
        assert_eq!(
            sessions[0].summary.as_deref(),
            Some("- Session branch updates README formatting.")
        );
        let events = std::iter::from_fn(|| app_event_rx.try_recv().ok()).collect::<Vec<_>>();
        let output_text = transcript
            .lock()
            .ok()
            .and_then(|buffer| buffer.replay_text())
            .unwrap_or_default();
        assert!(!output_text.contains("[Commit] committed with hash `abc1234`"));
        assert!(events.iter().any(|event| matches!(
            event,
            AppEvent::SessionWorkflowNoticeUpdated {
                notice,
                session_id,
            } if session_id.as_str() == "session-id"
                && notice == "[Commit] committed with hash `abc1234`"
        )));
        assert!(events.contains(&AppEvent::RefreshGitStatus));
    }

    #[tokio::test]
    /// Verifies auto-commit prefers the project fast agent/model selection
    /// before other fallback settings.
    async fn test_load_auto_commit_agent_setting_prefers_project_fast_selection() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let project_id = database
            .sessions()
            .load_session_project_id("session-id")
            .await
            .expect("failed to load session project id")
            .expect("session should have project id");
        database
            .settings()
            .upsert_project_setting(
                project_id,
                SettingName::DefaultFastModel,
                AgentModel::Gemini31ProPreview.as_str(),
            )
            .await
            .expect("failed to persist default fast model");
        database
            .settings()
            .upsert_project_setting(
                project_id,
                SettingName::DefaultFastAgent,
                AgentKind::Antigravity.name(),
            )
            .await
            .expect("failed to persist default fast agent");
        database
            .settings()
            .upsert_project_setting(
                project_id,
                SettingName::DefaultSmartModel,
                AgentModel::Gemini31ProPreview.as_str(),
            )
            .await
            .expect("failed to persist default smart model");

        // Act
        let auto_commit_agent = SessionTaskService::load_auto_commit_agent_setting(
            &database,
            "session-id",
            AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55),
        )
        .await;

        // Assert
        assert_eq!(
            auto_commit_agent,
            AgentSelection::new(AgentKind::Antigravity, AgentModel::Gemini31ProPreview)
        );
    }

    #[tokio::test]
    /// Verifies auto-commit falls back through smart and session selections
    /// when the fast-model setting is absent.
    async fn test_load_auto_commit_agent_setting_falls_back_through_defaults() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::Gpt55.as_str()).await;
        let project_id = database
            .sessions()
            .load_session_project_id("session-id")
            .await
            .expect("failed to load session project id")
            .expect("session should have project id");
        database
            .settings()
            .upsert_project_setting(
                project_id,
                SettingName::DefaultSmartModel,
                AgentModel::Gemini31ProPreview.as_str(),
            )
            .await
            .expect("failed to persist default smart model");
        database
            .settings()
            .upsert_project_setting(
                project_id,
                SettingName::DefaultSmartAgent,
                AgentKind::Antigravity.name(),
            )
            .await
            .expect("failed to persist default smart agent");

        // Act
        let smart_fallback_agent = SessionTaskService::load_auto_commit_agent_setting(
            &database,
            "session-id",
            AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55),
        )
        .await;

        // Assert
        assert_eq!(
            smart_fallback_agent,
            AgentSelection::new(AgentKind::Antigravity, AgentModel::Gemini31ProPreview)
        );

        // Arrange
        database
            .settings()
            .upsert_project_setting(project_id, SettingName::DefaultSmartModel, "invalid")
            .await
            .expect("failed to persist invalid smart model");

        // Act
        let session_fallback_agent = SessionTaskService::load_auto_commit_agent_setting(
            &database,
            "session-id",
            AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55),
        )
        .await;

        // Assert
        assert_eq!(
            session_fallback_agent,
            AgentSelection::new(AgentKind::Codex, AgentModel::Gpt55)
        );
    }

    #[tokio::test]
    /// Verifies one-shot assist output unwraps structured protocol answers
    /// before persistence and session usage updates.
    async fn test_run_agent_assist_task_unwraps_one_shot_answer_without_raw_json() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::ClaudeOpus48.as_str()).await;
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let child_pid = Arc::new(Mutex::new(None));
        let temp_dir = tempfile::tempdir().expect("failed to create temp dir");
        let mut backend = MockAgentBackend::new();
        backend.expect_build_command().times(1).returning(|request| {
            assert!(matches!(
                request.request_kind,
                AgentRequestKind::UtilityPrompt
            ));
            assert_eq!(request.prompt, "Resolve conflict");

            Ok(mock_shell_command(
                r#"{"result":"{\"answer\":\"Resolved the rebase conflict.\",\"questions\":[],\"summary\":null}","usage":{"input_tokens":11,"output_tokens":7}}"#,
                "",
                0,
            ))
        });

        // Act
        let result = SessionTaskService::run_agent_assist_task_with_backend(
            RunAgentAssistTaskInput {
                app_event_tx,
                child_pid: Arc::clone(&child_pid),
                db: database.clone(),
                folder: temp_dir.path().to_path_buf(),
                id: "session-id".to_string(),
                prompt: "Resolve conflict".to_string(),
                session_agent: AgentSelection::new(AgentKind::Claude, AgentModel::ClaudeOpus48),
                session_update_versions: Arc::default(),
                transcript: Arc::clone(&transcript),
            },
            &backend,
        )
        .await;

        // Assert
        assert!(
            result.is_ok(),
            "assist task should succeed: {:?}",
            result.err()
        );
        let output_text = transcript
            .lock()
            .ok()
            .and_then(|transcript| transcript.replay_text())
            .unwrap_or_default();
        assert!(output_text.contains("Resolved the rebase conflict."));
        assert!(!output_text.contains(r#"{"answer""#));
        assert_eq!(*child_pid.lock().expect("failed to lock child pid"), None);
        let sessions = database
            .sessions()
            .load_sessions()
            .await
            .expect("failed to load sessions");
        assert_eq!(sessions[0].input_tokens, 11);
        assert_eq!(sessions[0].output_tokens, 7);
    }

    #[tokio::test]
    /// Verifies assist tasks reject plain-text one-shot output after both the
    /// original parse and the protocol-repair retry fail.
    async fn test_run_agent_assist_task_rejects_plain_text_output() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::ClaudeOpus48.as_str()).await;
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let transcript = Arc::new(Mutex::new(SessionTranscript::default()));
        let temp_dir = tempfile::tempdir().expect("failed to create temp dir");
        let mut backend = MockAgentBackend::new();
        backend
            .expect_build_command()
            .times(2)
            .returning(|request| {
                assert!(matches!(
                    request.request_kind,
                    AgentRequestKind::UtilityPrompt
                ));

                Ok(mock_shell_command(
                    r#"{"result":"plain text","usage":{"input_tokens":2,"output_tokens":1}}"#,
                    "",
                    0,
                ))
            });

        // Act
        let error = SessionTaskService::run_agent_assist_task_with_backend(
            RunAgentAssistTaskInput {
                app_event_tx,
                child_pid: Arc::new(Mutex::new(None)),
                db: database.clone(),
                folder: temp_dir.path().to_path_buf(),
                id: "session-id".to_string(),
                prompt: "Resolve conflict".to_string(),
                session_agent: AgentSelection::new(AgentKind::Claude, AgentModel::ClaudeOpus48),
                session_update_versions: Arc::default(),
                transcript: Arc::clone(&transcript),
            },
            &backend,
        )
        .await
        .expect_err("plain-text utility output should fail");

        // Assert
        assert!(
            error
                .to_string()
                .contains("did not match the required JSON schema")
        );
        assert!(error.to_string().contains("response:\nplain text"));
        let output_text = transcript
            .lock()
            .ok()
            .and_then(|transcript| transcript.replay_text());
        assert_eq!(output_text, None);
        let sessions = database
            .sessions()
            .load_sessions()
            .await
            .expect("failed to load sessions");
        assert_eq!(sessions[0].input_tokens, 0);
        assert_eq!(sessions[0].output_tokens, 0);
    }

    #[tokio::test]
    /// Verifies non-zero assist subprocess exits surface the one-shot command
    /// error details.
    async fn test_run_agent_assist_task_returns_error_for_non_zero_exit_status() {
        // Arrange
        let database = AppRepositories::in_memory().await;
        insert_review_session(&database, AgentModel::ClaudeOpus48.as_str()).await;
        let (app_event_tx, _app_event_rx) = mpsc::unbounded_channel();
        let temp_dir = tempfile::tempdir().expect("failed to create temp dir");
        let mut backend = MockAgentBackend::new();
        backend
            .expect_build_command()
            .times(1)
            .returning(|_| Ok(mock_shell_command("", "assist failed", 7)));

        // Act
        let result = SessionTaskService::run_agent_assist_task_with_backend(
            RunAgentAssistTaskInput {
                app_event_tx,
                child_pid: Arc::new(Mutex::new(None)),
                db: database.clone(),
                folder: temp_dir.path().to_path_buf(),
                id: "session-id".to_string(),
                prompt: "Resolve conflict".to_string(),
                session_agent: AgentSelection::new(AgentKind::Claude, AgentModel::ClaudeOpus48),
                session_update_versions: Arc::default(),
                transcript: Arc::new(Mutex::new(SessionTranscript::default())),
            },
            &backend,
        )
        .await;

        // Assert
        assert!(result.is_err());
        let error_text = result.expect_err("expected non-zero exit to fail");
        assert!(error_text.to_string().contains("exit code 7"));
        assert!(error_text.to_string().contains("assist failed"));
    }
}