cflx 0.6.45

//! Shared state management for orchestration operations.
//!
//! Provides a unified state structure that tracks orchestration progress
//! across different execution modes (serial CLI, TUI, parallel).
//!
//! ## Integration Status
//!
//! - **Serial Orchestrator** (`src/orchestrator.rs`): Fully integrated. The orchestrator
//!   maintains a `shared_state: Arc<RwLock<OrchestratorState>>` instance and updates it
//!   via `apply_execution_event` when processing changes (ProcessingStarted, ApplyStarted,
//!   ApplyCompleted, ChangeArchived). The shared state is wrapped in Arc<RwLock<>> to enable
//!   sharing with TUI and Web monitoring.
//!
//! - **TUI** (`src/tui/state/mod.rs`): Integrated via optional reference. TUI AppState has
//!   a `shared_orchestrator_state` field that can be set via `set_shared_state()`. TUI can
//!   query this for pending/archived status, apply counts, and current change tracking while
//!   maintaining its own UI-specific state for rendering and interaction.
//!
//! - **Web** (`src/web/state.rs`): Integrated via optional reference. WebState has a
//!   `shared_orchestrator_state` field set via `set_shared_state()` (called automatically
//!   by `Orchestrator::set_web_state()`). When generating `OrchestratorStateSnapshot` via
//!   `from_changes_with_shared_state()`, WebState queries shared state to enrich change
//!   metadata with apply counts, pending/archived status, and iteration numbers.
//!
//! ## Usage
//!
//! The shared state provides a single source of truth for tracking:
//! - Pending, completed, and archived changes
//! - Apply counts per change
//! - Current change being processed
//! - Iteration counters and limits
//!
//! ### Integration Pattern
//!
//! 1. **Orchestrator creates and owns shared state:**
//!    ```rust,ignore
//!    let shared_state = Arc::new(RwLock::new(OrchestratorState::new(changes, max_iters)));
//!    ```
//!
//! 2. **Orchestrator updates state via events:**
//!    ```rust,ignore
//!    shared_state.write().await.apply_execution_event(&event);
//!    ```
//!
//! 3. **TUI/Web receive shared state reference:**
//!    ```rust,ignore
//!    app_state.set_shared_state(shared_state.clone());
//!    web_state.set_shared_state(shared_state.clone()).await;
//!    ```
//!
//! 4. **TUI/Web query shared state when needed:**
//!    ```rust,ignore
//!    if let Some(shared) = &app_state.shared_orchestrator_state {
//!        let guard = shared.read().await;
//!        let apply_count = guard.apply_count(change_id);
//!        let is_pending = guard.is_pending(change_id);
//!    }
//!    ```
use std::collections::{HashMap, HashSet};

use crate::error_history::{CircuitBreakerConfig, ErrorHistory};

// ============================================================================
// Execution mode – determines terminal states for the state machine
// ============================================================================

/// Execution mode that determines how the state machine handles terminal states.
///
/// - **Serial**: `ChangeArchived` is the terminal state (no merge step).
/// - **Parallel**: `ChangeArchived` transitions to `MergeWait`; `MergeCompleted` is the terminal state.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub enum ExecutionMode {
    /// Serial execution: archive is the final step.
    #[default]
    Serial,
    /// Parallel execution: archive is followed by a merge step.
    Parallel,
}

// ============================================================================
// ChangeRuntimeState types (Phase 1 – reducer-owned state)
// ============================================================================

/// Intent to include or exclude a change from the execution queue.
#[derive(Debug, Clone, PartialEq, Default)]
pub enum QueueIntent {
    /// Not requested to be queued.
    #[default]
    NotQueued,
    /// Requested to be queued for execution.
    Queued,
}

/// Active execution stage for a change.
#[derive(Debug, Clone, PartialEq, Default)]
pub enum ActivityState {
    /// No active execution.
    #[default]
    Idle,
    /// Currently applying.
    Applying,
    /// Currently running acceptance checks.
    Accepting,
    /// Currently running dedicated rejection review.
    Rejecting,
    /// Currently archiving.
    Archiving,
    /// Currently executing a merge resolve.
    Resolving,
}

/// Reason a change is blocked waiting for an external condition.
#[derive(Debug, Clone, PartialEq, Default)]
pub enum WaitState {
    /// Not waiting.
    #[default]
    None,
    /// Waiting for a merge to be attempted (parallel only).
    MergeWait,
    /// Waiting for a resolve sub-task to start (queued resolve intent).
    ResolveWait,
    /// Waiting because a dependency has not yet completed.
    DependencyBlocked,
    /// Waiting because apply/rejecting reported a resumable hold.
    Stalled,
    /// Waiting because acceptance observed a gate before follow-up routing.
    AcceptanceGated,
}

/// Additional metadata preserved while a change is blocked.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct BlockedMetadata {
    /// Machine-readable blocker category.
    pub blocker_reason: Option<String>,
    /// Optional operator-facing unblock guidance.
    pub unblock_metadata: Option<String>,
    /// Optional snapshot of worktree context captured when blocker was recorded.
    pub worktree_snapshot: Option<String>,
}

/// Terminal outcome for a change (once reached, no further transitions).
#[derive(Debug, Clone, PartialEq, Default)]
pub enum TerminalState {
    /// Not yet in a terminal state.
    #[default]
    None,
    /// Successfully archived.
    Archived,
    /// Successfully merged to the base branch (parallel only).
    Merged,
    /// Rejected after acceptance blocker detection.
    Rejected(String),
    /// Encountered a non-recoverable error.
    Error(String),
    /// Stopped by user request.
    Stopped,
}

/// Observation derived from a workspace refresh scan.
/// Used by `apply_observation()` to reconcile MergeWait without overwriting
/// active activity.
#[derive(Debug, Clone, PartialEq, Default)]
pub enum WorkspaceObservation {
    /// No relevant observation.
    #[default]
    None,
    /// Workspace is in `Archived` state: change should enter `MergeWait`.
    WorkspaceArchived,
    /// Worktree is NOT ahead of base: `MergeWait` can be cleared.
    WorktreeNotAhead,
}

/// Full runtime state for a single change, owned by the reducer.
#[derive(Debug, Clone, Default)]
pub struct ChangeRuntimeState {
    /// Queue intent: whether the change has been requested to run.
    pub queue_intent: QueueIntent,
    /// Active execution stage.
    pub activity: ActivityState,
    /// Wait condition (may co-exist with `Queued` intent).
    pub wait_state: WaitState,
    /// Preserved metadata for blocked states.
    pub blocked_metadata: BlockedMetadata,
    /// Terminal outcome once reached.
    pub terminal: TerminalState,
    /// Latest workspace observation (used for reconcile only).
    pub observation: WorkspaceObservation,
    /// True when a change was explicitly force-stopped and dequeued.
    /// While true, stale in-flight execution events must not re-activate this change.
    pub dequeued: bool,
}

impl ChangeRuntimeState {
    fn clear_blocked_metadata(&mut self) {
        self.blocked_metadata = BlockedMetadata::default();
    }

    fn set_blocked_metadata(
        &mut self,
        blocker_reason: impl Into<String>,
        unblock_metadata: impl Into<String>,
        worktree_snapshot: impl Into<String>,
    ) {
        self.blocked_metadata = BlockedMetadata {
            blocker_reason: Some(blocker_reason.into()),
            unblock_metadata: Some(unblock_metadata.into()),
            worktree_snapshot: Some(worktree_snapshot.into()),
        };
    }

    /// Check whether this runtime state represents active execution
    /// (applying, accepting, archiving, or resolving).
    pub fn is_active(&self) -> bool {
        !matches!(self.activity, ActivityState::Idle)
    }

    /// Check whether the change is in a terminal state.
    pub fn is_terminal(&self) -> bool {
        !matches!(self.terminal, TerminalState::None)
    }

    /// Verify invariants. Returns `false` if an invalid combination is detected.
    ///
    /// Forbidden combinations:
    /// - `Merged` terminal + any non-Idle activity
    /// - `ResolveWait` + `Resolving` activity simultaneously
    /// - Any terminal state + active activity
    #[allow(dead_code)]
    pub fn invariants_hold(&self) -> bool {
        // Terminal changes must not have active activity.
        if self.is_terminal() && self.is_active() {
            return false;
        }
        // ResolveWait and Resolving cannot coexist.
        if matches!(self.wait_state, WaitState::ResolveWait)
            && matches!(self.activity, ActivityState::Resolving)
        {
            return false;
        }
        true
    }

    /// Derive the display status string used by TUI and Web.
    ///
    /// Returns one of: "not queued", "queued", "blocked", "stalled", "gated", "applying",
    /// "accepting", "rejecting", "archiving", "resolving", "merge wait", "resolve pending",
    /// "archived", "merged", "error", "stopped".
    pub fn display_status(&self) -> &'static str {
        // Terminal states take precedence.
        match &self.terminal {
            TerminalState::Archived => return "archived",
            TerminalState::Merged => return "merged",
            TerminalState::Rejected(_) => return "rejected",
            TerminalState::Error(_) => return "error",
            TerminalState::Stopped => return "stopped",
            TerminalState::None => {}
        }
        // Active execution stages next.
        match self.activity {
            ActivityState::Applying => return "applying",
            ActivityState::Accepting => return "accepting",
            ActivityState::Rejecting => return "rejecting",
            ActivityState::Archiving => return "archiving",
            ActivityState::Resolving => return "resolving",
            ActivityState::Idle => {}
        }
        // Wait conditions.
        match self.wait_state {
            WaitState::MergeWait => return "merge wait",
            WaitState::ResolveWait => return "resolve pending",
            WaitState::DependencyBlocked => return "blocked",
            WaitState::Stalled => return "stalled",
            WaitState::AcceptanceGated => return "gated",
            WaitState::None => {}
        }
        // Queue intent.
        match self.queue_intent {
            QueueIntent::Queued => "queued",
            QueueIntent::NotQueued => "not queued",
        }
    }

    /// Derive the display color used by TUI status rendering.
    #[allow(dead_code)]
    pub fn display_color(&self) -> ratatui::style::Color {
        match self.display_status() {
            "not queued" => ratatui::style::Color::DarkGray,
            "queued" => ratatui::style::Color::Yellow,
            "blocked" => ratatui::style::Color::Gray,
            "stalled" => ratatui::style::Color::LightYellow,
            "gated" => ratatui::style::Color::LightRed,
            "applying" => ratatui::style::Color::Cyan,
            "accepting" => ratatui::style::Color::LightGreen,
            "rejecting" => ratatui::style::Color::LightYellow,
            "archiving" => ratatui::style::Color::Magenta,
            "archived" => ratatui::style::Color::Blue,
            "merged" => ratatui::style::Color::LightBlue,
            "rejected" => ratatui::style::Color::LightRed,
            "merge wait" => ratatui::style::Color::LightMagenta,
            "resolving" => ratatui::style::Color::LightCyan,
            "resolve pending" => ratatui::style::Color::Magenta,
            "error" => ratatui::style::Color::Red,
            "stopped" => ratatui::style::Color::DarkGray,
            _ => ratatui::style::Color::DarkGray,
        }
    }

    /// Returns the terminal error message when in error state.
    #[allow(dead_code)]
    pub fn error_message(&self) -> Option<&str> {
        match &self.terminal {
            TerminalState::Error(message) => Some(message.as_str()),
            _ => None,
        }
    }
}

// ============================================================================
// Reducer API types (Phase 2)
// ============================================================================

/// Commands that express user intent and drive state transitions via the reducer.
#[derive(Debug, Clone)]
pub enum ReducerCommand {
    /// Request a change to be added to the execution queue.
    AddToQueue(String),
    /// Request a change to be removed from the execution queue.
    RemoveFromQueue(String),
    /// Request merge resolution for a change in MergeWait or ResolveWait.
    ResolveMerge(String),
    /// Force-stop a running or queued change and dequeue it back to not-queued.
    DequeueChange(String),
    /// Legacy stop command (terminal stopped). Prefer DequeueChange for stop-and-dequeue semantics.
    #[allow(dead_code)]
    StopChange(String),
}

/// Outcome of applying a reducer command.
#[derive(Debug, Clone)]
#[allow(dead_code)]
pub enum ReduceOutcome {
    /// The command produced a state change described by the effect.
    Changed(ReducerEffect),
    /// The command was a no-op (idempotent duplicate or invalid in current state).
    NoOp,
}

/// Side-effects produced by a successful reducer command.
#[derive(Debug, Clone)]
#[allow(clippy::enum_variant_names, dead_code)]
pub enum ReducerEffect {
    /// Queue intent was updated.
    QueueIntentSet {
        change_id: String,
        intent: QueueIntent,
    },
    /// Wait state was updated.
    WaitStateSet { change_id: String, wait: WaitState },
    /// Terminal state was set.
    TerminalStateSet {
        change_id: String,
        terminal: TerminalState,
    },
}

/// Shared state for orchestration operations.
///
/// This structure tracks:
/// - Which changes are pending, completed, or archived
/// - Apply counts per change
/// - Iteration counters and progress
#[derive(Debug, Clone)]
pub struct OrchestratorState {
    /// Change IDs captured at run start (snapshot).
    /// Only changes present in this snapshot will be processed.
    initial_change_ids: HashSet<String>,

    /// Changes that are still pending (not yet archived).
    pending_changes: HashSet<String>,

    /// Changes that have been archived.
    archived_changes: HashSet<String>,

    /// Apply counts per change (how many times each change has been applied).
    apply_counts: HashMap<String, u32>,

    /// Changes marked as stalled (failed due to no progress or blockers).
    stalled_change_ids: HashSet<String>,

    /// Changes skipped because one of their dependencies stalled.
    skipped_change_ids: HashSet<String>,

    /// Task progress per change (completed_tasks, total_tasks).
    task_progress: HashMap<String, (u32, u32)>,

    /// Error history per change for repeated failure detection.
    error_histories: HashMap<String, ErrorHistory>,

    /// Number of changes processed (archived).
    changes_processed: usize,

    /// Total number of changes at run start.
    total_changes: usize,

    /// Maximum iterations limit (0 = no limit).
    max_iterations: u32,

    /// Current iteration number.
    iteration: u32,

    /// Current change ID being processed.
    current_change_id: Option<String>,

    /// Reducer-owned runtime state per change.
    change_runtime: HashMap<String, ChangeRuntimeState>,

    /// Reducer-owned resolve-wait queue (FIFO list of change_ids awaiting resolve).
    resolve_wait_queue: Vec<String>,

    /// Execution mode: Serial or Parallel.
    /// Determines how `ChangeArchived` events are handled.
    execution_mode: ExecutionMode,
}

#[allow(dead_code)] // Public API for future use by TUI/Web states
impl OrchestratorState {
    /// Create a new orchestrator state with the given initial changes and execution mode.
    pub fn new(change_ids: Vec<String>, max_iterations: u32) -> Self {
        Self::with_mode(change_ids, max_iterations, ExecutionMode::Serial)
    }

    /// Create a new orchestrator state for a specific execution mode.
    pub fn with_mode(
        change_ids: Vec<String>,
        max_iterations: u32,
        execution_mode: ExecutionMode,
    ) -> Self {
        let initial_set: HashSet<String> = change_ids.iter().cloned().collect();
        let pending_set = initial_set.clone();
        let total = change_ids.len();

        // Initialise each change with the "not queued + idle + no wait + no terminal" state.
        let change_runtime: HashMap<String, ChangeRuntimeState> = change_ids
            .iter()
            .map(|id| (id.clone(), ChangeRuntimeState::default()))
            .collect();

        Self {
            initial_change_ids: initial_set,
            pending_changes: pending_set,
            archived_changes: HashSet::new(),
            apply_counts: HashMap::new(),
            stalled_change_ids: HashSet::new(),
            skipped_change_ids: HashSet::new(),
            task_progress: HashMap::new(),
            error_histories: HashMap::new(),
            changes_processed: 0,
            total_changes: total,
            max_iterations,
            iteration: 0,
            current_change_id: None,
            change_runtime,
            resolve_wait_queue: Vec::new(),
            execution_mode,
        }
    }

    /// Get the initial snapshot of change IDs.
    pub fn initial_change_ids(&self) -> &HashSet<String> {
        &self.initial_change_ids
    }

    /// Get the set of pending changes.
    pub fn pending_changes(&self) -> &HashSet<String> {
        &self.pending_changes
    }

    /// Get the set of archived changes.
    pub fn archived_changes(&self) -> &HashSet<String> {
        &self.archived_changes
    }

    /// Get stalled change IDs.
    pub fn stalled_change_ids(&self) -> &HashSet<String> {
        &self.stalled_change_ids
    }

    /// Get skipped change IDs.
    pub fn skipped_change_ids(&self) -> &HashSet<String> {
        &self.skipped_change_ids
    }

    /// Mark a change as stalled.
    pub fn mark_stalled(&mut self, change_id: String) {
        self.stalled_change_ids.insert(change_id);
    }

    /// Mark a change as skipped.
    ///
    /// Returns true when the value was newly inserted.
    pub fn mark_skipped(&mut self, change_id: String) -> bool {
        self.skipped_change_ids.insert(change_id)
    }

    /// Clear transient counters for a stalled change.
    pub fn clear_stalled_change(&mut self, change_id: &str) {
        self.skipped_change_ids.remove(change_id);
        self.apply_counts.remove(change_id);
        if self.current_change_id.as_deref() == Some(change_id) {
            self.current_change_id = None;
        }
    }

    /// Get the number of changes processed.
    pub fn changes_processed(&self) -> usize {
        self.changes_processed
    }

    /// Get the total number of changes.
    pub fn total_changes(&self) -> usize {
        self.total_changes
    }

    /// Get the number of remaining changes.
    pub fn remaining_changes(&self) -> usize {
        self.pending_changes.len()
    }

    /// Get the current iteration number.
    pub fn iteration(&self) -> u32 {
        self.iteration
    }

    /// Get the maximum iterations limit.
    pub fn max_iterations(&self) -> u32 {
        self.max_iterations
    }

    /// Get the current change ID being processed.
    pub fn current_change_id(&self) -> Option<&String> {
        self.current_change_id.as_ref()
    }

    /// Get the apply count for a specific change.
    pub fn apply_count(&self, change_id: &str) -> u32 {
        *self.apply_counts.get(change_id).unwrap_or(&0)
    }

    /// Get the task progress for a specific change (completed_tasks, total_tasks).
    pub fn task_progress(&self, change_id: &str) -> (u32, u32) {
        *self.task_progress.get(change_id).unwrap_or(&(0, 0))
    }

    /// Update task progress for a change.
    pub fn set_task_progress(&mut self, change_id: String, completed: u32, total: u32) {
        self.task_progress.insert(change_id, (completed, total));
    }

    /// Check if a change is in the initial snapshot.
    pub fn is_in_snapshot(&self, change_id: &str) -> bool {
        self.initial_change_ids.contains(change_id)
    }

    /// Check if a change is pending.
    pub fn is_pending(&self, change_id: &str) -> bool {
        self.pending_changes.contains(change_id)
    }

    /// Check if a change is archived.
    pub fn is_archived(&self, change_id: &str) -> bool {
        self.archived_changes.contains(change_id)
    }

    /// Check if all changes are done.
    pub fn is_complete(&self) -> bool {
        self.pending_changes.is_empty()
    }

    /// Check if max iterations has been reached.
    pub fn is_iteration_limit_reached(&self) -> bool {
        self.max_iterations > 0 && self.iteration >= self.max_iterations
    }

    /// Check if we're approaching the iteration limit (80%).
    pub fn is_approaching_iteration_limit(&self) -> bool {
        if self.max_iterations == 0 {
            return false;
        }
        let threshold = (self.max_iterations as f32 * 0.8) as u32;
        self.iteration == threshold
    }

    /// Increment the iteration counter.
    pub fn increment_iteration(&mut self) {
        self.iteration += 1;
    }

    /// Set the current change being processed.
    pub fn set_current_change(&mut self, change_id: Option<String>) {
        self.current_change_id = change_id;
    }

    /// Increment the apply count for a change and return the new count.
    pub fn increment_apply_count(&mut self, change_id: &str) -> u32 {
        let count = self.apply_counts.entry(change_id.to_string()).or_insert(0);
        *count += 1;
        *count
    }

    /// Mark a change as archived.
    ///
    /// This:
    /// - Moves the change from pending to archived
    /// - Increments the changes_processed counter
    /// - Clears the current change if it matches
    /// - Removes apply count tracking
    pub fn mark_archived(&mut self, change_id: &str) {
        if self.pending_changes.remove(change_id) {
            self.archived_changes.insert(change_id.to_string());
            self.changes_processed += 1;
            self.apply_counts.remove(change_id);

            if self.current_change_id.as_deref() == Some(change_id) {
                self.current_change_id = None;
            }
        }
    }

    /// Add a new change dynamically (during execution).
    ///
    /// This is used for dynamic queue support in TUI mode.
    pub fn add_dynamic_change(&mut self, change_id: String) {
        if !self.initial_change_ids.contains(&change_id)
            && !self.pending_changes.contains(&change_id)
            && !self.archived_changes.contains(&change_id)
        {
            self.initial_change_ids.insert(change_id.clone());
            self.pending_changes.insert(change_id.clone());
            self.total_changes += 1;
            // Initialise reducer runtime state for newly discovered change.
            self.change_runtime.entry(change_id).or_default();
        }
    }

    // -----------------------------------------------------------------------
    // Reducer-owned runtime state accessors (Phase 1)
    // -----------------------------------------------------------------------

    /// Get the runtime state for a change, creating a default entry if absent.
    fn runtime_entry(&mut self, change_id: &str) -> &mut ChangeRuntimeState {
        self.change_runtime
            .entry(change_id.to_string())
            .or_default()
    }

    /// Read-only access to the runtime state of a change.
    pub fn change_runtime(&self, change_id: &str) -> Option<&ChangeRuntimeState> {
        self.change_runtime.get(change_id)
    }

    /// Derive the UI display status string for a change (Phase 1.4).
    pub fn display_status(&self, change_id: &str) -> &'static str {
        match self.change_runtime.get(change_id) {
            Some(rt) => rt.display_status(),
            None => "not queued",
        }
    }

    /// Return true if the change is actively executing (applying/accepting/archiving/resolving).
    /// Used for parallel slot accounting (Phase 1.5).
    pub fn is_active_change(&self, change_id: &str) -> bool {
        self.change_runtime
            .get(change_id)
            .map(|rt| rt.is_active())
            .unwrap_or(false)
    }

    /// Return true when any change is currently in resolving activity.
    pub fn is_resolving_active(&self) -> bool {
        self.change_runtime
            .values()
            .any(|rt| matches!(rt.activity, ActivityState::Resolving) && !rt.is_terminal())
    }

    /// Return change IDs that are currently waiting for scheduler-owned resolve/merge retry.
    pub fn resolve_wait_change_ids(&self) -> Vec<String> {
        self.change_runtime
            .iter()
            .filter_map(|(id, rt)| {
                if matches!(rt.wait_state, WaitState::ResolveWait) && !rt.is_terminal() {
                    Some(id.clone())
                } else {
                    None
                }
            })
            .collect()
    }

    /// Return a snapshot of display status strings for all known changes.
    /// Used by the TUI to sync `ChangeState.queue_status` from the reducer.
    pub fn all_display_statuses(&self) -> HashMap<String, &'static str> {
        self.change_runtime
            .iter()
            .map(|(id, rt)| (id.clone(), rt.display_status()))
            .collect()
    }

    /// Return true if the change has reached a terminal state.
    pub fn is_terminal_change(&self, change_id: &str) -> bool {
        self.change_runtime
            .get(change_id)
            .map(|rt| rt.is_terminal())
            .unwrap_or(false)
    }

    /// Remove a change from pending (e.g., due to failure).
    pub fn remove_from_pending(&mut self, change_id: &str) {
        self.pending_changes.remove(change_id);
        if self.current_change_id.as_deref() == Some(change_id) {
            self.current_change_id = None;
        }
    }

    /// Remove a change from pending and decrement total_changes.
    ///
    /// Returns true when the change was pending and removed.
    pub fn drop_pending_change(&mut self, change_id: &str) -> bool {
        let removed = self.pending_changes.remove(change_id);
        if removed {
            self.total_changes = self.total_changes.saturating_sub(1);
        }
        if self.current_change_id.as_deref() == Some(change_id) {
            self.current_change_id = None;
        }
        removed
    }

    /// Clear all pending changes.
    pub fn clear_pending_changes(&mut self) {
        self.pending_changes.clear();
    }

    /// Record an error and return whether circuit breaker should trip.
    pub fn record_error_and_check_circuit_breaker(
        &mut self,
        change_id: &str,
        error: &str,
        config: CircuitBreakerConfig,
    ) -> bool {
        let history = self
            .error_histories
            .entry(change_id.to_string())
            .or_insert_with(|| ErrorHistory::new(config.clone()));

        history.record_error(error);
        history.detect_same_error()
    }

    /// Return the most recent normalized error for a change.
    pub fn last_error(&self, change_id: &str) -> Option<&str> {
        self.error_histories
            .get(change_id)
            .and_then(ErrorHistory::last_error)
    }

    /// Clear error history for a change.
    pub fn clear_error_history(&mut self, change_id: &str) {
        self.error_histories.remove(change_id);
    }

    // -----------------------------------------------------------------------
    // Reducer API (Phase 2)
    // -----------------------------------------------------------------------

    /// Apply a reducer command that expresses user intent (queue add/remove, resolve, stop).
    ///
    /// Returns the resulting `ReduceOutcome` describing what changed.
    pub fn apply_command(&mut self, cmd: ReducerCommand) -> ReduceOutcome {
        match cmd {
            ReducerCommand::AddToQueue(change_id) => {
                {
                    let rt = self.runtime_entry(&change_id);
                    if matches!(
                        rt.terminal,
                        TerminalState::Archived
                            | TerminalState::Merged
                            | TerminalState::Rejected(_)
                    ) {
                        return ReduceOutcome::NoOp;
                    }
                    if !rt.is_terminal()
                        && !rt.dequeued
                        && (rt.is_active() || rt.queue_intent == QueueIntent::Queued)
                    {
                        return ReduceOutcome::NoOp;
                    }
                    if rt.is_terminal() {
                        rt.terminal = TerminalState::None;
                        rt.activity = ActivityState::Idle;
                        rt.wait_state = WaitState::None;
                        rt.clear_blocked_metadata();
                    }
                    rt.dequeued = false;
                    rt.queue_intent = QueueIntent::Queued;
                    rt.wait_state = WaitState::None;
                    rt.clear_blocked_metadata();
                }
                self.add_dynamic_change(change_id.clone());
                ReduceOutcome::Changed(ReducerEffect::QueueIntentSet {
                    change_id,
                    intent: QueueIntent::Queued,
                })
            }
            ReducerCommand::RemoveFromQueue(change_id) => {
                let rt = self.runtime_entry(&change_id);
                if rt.queue_intent == QueueIntent::NotQueued {
                    return ReduceOutcome::NoOp;
                }
                rt.queue_intent = QueueIntent::NotQueued;
                ReduceOutcome::Changed(ReducerEffect::QueueIntentSet {
                    change_id,
                    intent: QueueIntent::NotQueued,
                })
            }
            ReducerCommand::ResolveMerge(change_id) => {
                let rt = self.runtime_entry(&change_id);
                if !matches!(rt.wait_state, WaitState::MergeWait | WaitState::ResolveWait) {
                    return ReduceOutcome::NoOp;
                }
                rt.wait_state = WaitState::ResolveWait;
                if !self.resolve_wait_queue.contains(&change_id) {
                    self.resolve_wait_queue.push(change_id.clone());
                }
                ReduceOutcome::Changed(ReducerEffect::WaitStateSet {
                    change_id,
                    wait: WaitState::ResolveWait,
                })
            }
            ReducerCommand::DequeueChange(change_id) => {
                let rt = self.runtime_entry(&change_id);
                if matches!(
                    rt.terminal,
                    TerminalState::Archived | TerminalState::Merged | TerminalState::Rejected(_)
                ) {
                    return ReduceOutcome::NoOp;
                }
                rt.terminal = TerminalState::None;
                rt.activity = ActivityState::Idle;
                rt.wait_state = WaitState::None;
                rt.clear_blocked_metadata();
                rt.queue_intent = QueueIntent::NotQueued;
                rt.dequeued = true;
                ReduceOutcome::Changed(ReducerEffect::QueueIntentSet {
                    change_id,
                    intent: QueueIntent::NotQueued,
                })
            }
            ReducerCommand::StopChange(change_id) => {
                let rt = self.runtime_entry(&change_id);
                if rt.is_terminal() {
                    return ReduceOutcome::NoOp;
                }
                rt.terminal = TerminalState::Stopped;
                rt.activity = ActivityState::Idle;
                rt.wait_state = WaitState::None;
                rt.clear_blocked_metadata();
                rt.queue_intent = QueueIntent::NotQueued;
                ReduceOutcome::Changed(ReducerEffect::TerminalStateSet {
                    change_id,
                    terminal: TerminalState::Stopped,
                })
            }
        }
    }

    /// Apply a workspace observation to reconcile wait states without overwriting
    /// active execution (Phase 2.4).
    pub fn apply_observation(&mut self, change_id: &str, obs: WorkspaceObservation) {
        let rt = self.runtime_entry(change_id);

        // Never overwrite an active execution stage.
        if rt.is_active() {
            return;
        }
        // Never overwrite a terminal state.
        if rt.is_terminal() {
            return;
        }

        match obs {
            WorkspaceObservation::WorkspaceArchived => {
                // Restore MergeWait only; ResolveWait is NOT re-created from workspace.
                if !matches!(rt.wait_state, WaitState::MergeWait | WaitState::ResolveWait) {
                    rt.wait_state = WaitState::MergeWait;
                    rt.observation = WorkspaceObservation::WorkspaceArchived;
                }
            }
            WorkspaceObservation::WorktreeNotAhead => {
                // Clear MergeWait when worktree is no longer ahead.
                if matches!(rt.wait_state, WaitState::MergeWait) {
                    rt.wait_state = WaitState::None;
                    rt.clear_blocked_metadata();
                }
                rt.observation = WorkspaceObservation::WorktreeNotAhead;
            }
            WorkspaceObservation::None => {
                rt.observation = WorkspaceObservation::None;
            }
        }
    }

    /// Apply an ExecutionEvent to update the shared state.
    ///
    /// This is the single source of truth for state mutations driven by execution events.
    ///
    /// ## Current Usage
    ///
    /// - **Serial Orchestrator**: Calls this method in `src/orchestrator.rs` to track:
    ///   - `ProcessingStarted` - When a change begins processing
    ///   - `ApplyStarted` - When apply operation starts
    ///   - `ApplyCompleted` - When apply operation completes (increments apply count)
    ///   - `ChangeArchived` - When a change is successfully archived
    ///
    /// - **TUI/Web**: Currently maintain their own ExecutionEvent-driven state independently.
    ///   Future refactoring can make them query this shared state for unified tracking.
    pub fn apply_execution_event(&mut self, event: &crate::events::ExecutionEvent) {
        use crate::events::ExecutionEvent;

        match event {
            // Processing lifecycle
            ExecutionEvent::ProcessingStarted(change_id) => {
                self.set_current_change(Some(change_id.clone()));
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.queue_intent = QueueIntent::Queued;
                }
            }
            ExecutionEvent::ProcessingCompleted(change_id) => {
                // Keep current_change_id set until archived
                let _ = change_id;
            }
            ExecutionEvent::ProcessingError { id, error } => {
                self.remove_from_pending(id);
                let rt = self.runtime_entry(id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.terminal = TerminalState::Error(error.clone());
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::None;
                    rt.clear_blocked_metadata();
                }
            }

            // Apply events
            ExecutionEvent::ApplyStarted {
                change_id,
                command: _,
            } => {
                let mut should_start = false;
                {
                    let rt = self.runtime_entry(change_id);
                    if !rt.is_terminal() && !rt.dequeued {
                        rt.activity = ActivityState::Applying;
                        rt.wait_state = WaitState::None;
                        rt.clear_blocked_metadata();
                        should_start = true;
                    }
                }
                if should_start {
                    self.set_current_change(Some(change_id.clone()));
                }
            }
            ExecutionEvent::ApplyCompleted { change_id, .. } => {
                self.increment_apply_count(change_id);
                let rt = self.runtime_entry(change_id);
                if matches!(rt.activity, ActivityState::Applying) {
                    rt.activity = ActivityState::Idle;
                }
            }
            ExecutionEvent::ApplyFailed { change_id, error } => {
                self.remove_from_pending(change_id);
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.terminal = TerminalState::Error(error.clone());
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::None;
                    rt.clear_blocked_metadata();
                }
            }

            // Acceptance events
            ExecutionEvent::AcceptanceStarted { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.activity = ActivityState::Accepting;
                }
            }
            ExecutionEvent::AcceptanceCompleted { change_id } => {
                let rt = self.runtime_entry(change_id);
                if matches!(rt.activity, ActivityState::Accepting) {
                    rt.activity = ActivityState::Idle;
                }
            }
            ExecutionEvent::AcceptanceFailed { change_id, error } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.terminal = TerminalState::Error(error.clone());
                    rt.activity = ActivityState::Idle;
                }
            }
            ExecutionEvent::ChangeRejected { change_id, reason } => {
                self.remove_from_pending(change_id);
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.terminal = TerminalState::Rejected(reason.clone());
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::None;
                    rt.clear_blocked_metadata();
                    rt.queue_intent = QueueIntent::NotQueued;
                }
            }
            ExecutionEvent::RejectionReviewCompleted { change_id, outcome } => {
                let should_mark_pending_removed =
                    matches!(outcome, crate::events::RejectionOutcome::Confirm);
                if should_mark_pending_removed {
                    self.remove_from_pending(change_id);
                }

                let rt = self.runtime_entry(change_id);
                if rt.is_terminal() || rt.dequeued {
                    return;
                }
                match *outcome {
                    crate::events::RejectionOutcome::Confirm => {
                        rt.activity = ActivityState::Idle;
                        rt.wait_state = WaitState::None;
                        rt.clear_blocked_metadata();
                        rt.queue_intent = QueueIntent::NotQueued;
                        rt.terminal = TerminalState::Rejected(
                            "rejecting review confirmed rejection".to_string(),
                        );
                    }
                    crate::events::RejectionOutcome::Resume => {
                        rt.activity = ActivityState::Applying;
                        rt.wait_state = WaitState::None;
                        rt.clear_blocked_metadata();
                        rt.terminal = TerminalState::None;
                    }
                    crate::events::RejectionOutcome::Block => {
                        rt.activity = ActivityState::Idle;
                        rt.wait_state = WaitState::Stalled;
                        rt.terminal = TerminalState::None;
                        rt.set_blocked_metadata(
                            "rejection review returned block; unresolved blocker remains",
                            "resolve unresolved blocker tasks in openspec/changes/<change_id>/tasks.md, then trigger explicit resume",
                            "existing worktree and WIP context are preserved for stalled rejection review",
                        );
                    }
                }
            }
            ExecutionEvent::RejectionReviewFailed { change_id, error } => {
                self.remove_from_pending(change_id);
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::None;
                    rt.terminal = TerminalState::Error(error.clone());
                }
            }

            // Workspace status synchronization events (parallel mode)
            ExecutionEvent::WorkspaceStatusUpdated {
                change_id,
                workspace_name: _,
                status,
            } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    match status {
                        crate::vcs::WorkspaceStatus::Applying => {
                            rt.activity = ActivityState::Applying;
                        }
                        crate::vcs::WorkspaceStatus::Accepting => {
                            rt.activity = ActivityState::Accepting;
                        }
                        crate::vcs::WorkspaceStatus::Blocked => {
                            rt.activity = ActivityState::Idle;
                            rt.wait_state = WaitState::Stalled;
                            rt.set_blocked_metadata(
                                "apply reported recoverable blocker; workspace remains stalled",
                                "resolve implementation blocker section and pending unblock tasks before explicit retry",
                                "existing worktree and WIP context are preserved while stalled",
                            );
                        }
                        crate::vcs::WorkspaceStatus::Rejecting => {
                            rt.activity = ActivityState::Rejecting;
                        }
                        crate::vcs::WorkspaceStatus::Archiving => {
                            rt.activity = ActivityState::Archiving;
                        }
                        crate::vcs::WorkspaceStatus::Resolving => {
                            rt.activity = ActivityState::Resolving;
                        }
                        _ => {}
                    }
                }
            }

            // Archive events
            ExecutionEvent::ArchiveStarted { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.activity = ActivityState::Archiving;
                }
            }
            ExecutionEvent::ArchiveResumed { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.activity = ActivityState::Archiving;
                }
            }
            ExecutionEvent::ArchiveRetryScheduled { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.activity = ActivityState::Archiving;
                }
            }
            ExecutionEvent::ChangeArchived(change_id) => {
                self.mark_archived(change_id);
                let mode = self.execution_mode;
                let has_other_resolving = self.change_runtime.iter().any(|(id, runtime)| {
                    id != change_id
                        && matches!(runtime.activity, ActivityState::Resolving)
                        && !runtime.is_terminal()
                });
                let rt = self.runtime_entry(change_id);
                rt.activity = ActivityState::Idle;

                match mode {
                    ExecutionMode::Serial => {
                        // Serial: archive is terminal.
                        rt.terminal = TerminalState::Archived;
                        rt.wait_state = WaitState::None;
                        rt.queue_intent = QueueIntent::NotQueued;
                    }
                    ExecutionMode::Parallel => {
                        // Parallel: archived changes defer to active resolve in the same reducer scope.
                        // If another change is resolving, keep this row in ResolveWait so it can
                        // continue automatically after the active resolve completes.
                        rt.wait_state = if has_other_resolving {
                            WaitState::ResolveWait
                        } else {
                            WaitState::MergeWait
                        };
                    }
                }
            }
            ExecutionEvent::ArchiveFailed {
                change_id, error, ..
            } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.terminal = TerminalState::Error(error.clone());
                    rt.activity = ActivityState::Idle;
                }
            }

            // Merge / resolve events (parallel mode)
            ExecutionEvent::MergeDeferred {
                change_id,
                auto_resumable,
                ..
            } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.is_active() {
                    if *auto_resumable {
                        // Auto-resumable: will be retried after a preceding merge/resolve
                        // completes. Use ResolveWait so workspace-refresh reconciliation
                        // does not regress it back to MergeWait.
                        rt.wait_state = WaitState::ResolveWait;
                        if !self.resolve_wait_queue.contains(change_id) {
                            self.resolve_wait_queue.push(change_id.clone());
                        }
                    } else {
                        // Manual intervention required.
                        rt.wait_state = WaitState::MergeWait;
                    }
                }
            }
            ExecutionEvent::MergeCompleted { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    rt.terminal = TerminalState::Merged;
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::None;
                    rt.queue_intent = QueueIntent::NotQueued;
                    // Remove from resolve queue if present.
                    self.resolve_wait_queue.retain(|id| id != change_id);
                }
            }
            ExecutionEvent::ResolveStarted { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.activity = ActivityState::Resolving;
                    rt.wait_state = WaitState::None;
                }
            }
            ExecutionEvent::ResolveCompleted { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal()
                    && !rt.dequeued
                    && (matches!(rt.activity, ActivityState::Resolving)
                        || matches!(rt.wait_state, WaitState::ResolveWait))
                {
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::None;
                    // Successful resolve means the change is now merged. Setting terminal
                    // prevents a subsequent ChangesRefreshed from resurrecting ResolveWait
                    // via apply_observation (which skips terminal entries).
                    rt.terminal = TerminalState::Merged;
                    rt.queue_intent = QueueIntent::NotQueued;
                    rt.clear_blocked_metadata();
                }
                self.resolve_wait_queue.retain(|id| id != change_id);
            }
            ExecutionEvent::ResolveFailed { change_id, .. } => {
                // Resolve failure does NOT regress a terminal state.
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() {
                    // Reset activity if we were actively resolving.
                    if matches!(rt.activity, ActivityState::Resolving) {
                        rt.activity = ActivityState::Idle;
                    }
                    // Restore MergeWait when the failure happened during Resolving,
                    // or before ResolveStarted was sent (early dirty-base check
                    // while still in ResolveWait from ReducerCommand::ResolveMerge).
                    if matches!(rt.activity, ActivityState::Idle)
                        && matches!(rt.wait_state, WaitState::ResolveWait | WaitState::None)
                    {
                        rt.wait_state = WaitState::MergeWait;
                        self.resolve_wait_queue.retain(|id| id != change_id);
                    }
                }
            }

            // Dependency events
            ExecutionEvent::DependencyBlocked { change_id, .. } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.is_active() {
                    rt.wait_state = WaitState::DependencyBlocked;
                    rt.set_blocked_metadata(
                        "dependency_blocked",
                        "resolve dependencies and retry queue",
                        "worktree snapshot not required for dependency blocker",
                    );
                }
            }
            ExecutionEvent::DependencyResolved { change_id } => {
                let rt = self.runtime_entry(change_id);
                if matches!(rt.wait_state, WaitState::DependencyBlocked) {
                    rt.wait_state = WaitState::None;
                    rt.clear_blocked_metadata();
                }
            }
            ExecutionEvent::AcceptanceGated { change_id, reason } => {
                let rt = self.runtime_entry(change_id);
                if !rt.is_terminal() && !rt.dequeued {
                    rt.activity = ActivityState::Idle;
                    rt.wait_state = WaitState::AcceptanceGated;
                    rt.terminal = TerminalState::None;
                    rt.set_blocked_metadata(
                        "acceptance-gated",
                        "review acceptance blocker evidence and decide resume/reject route",
                        reason.clone(),
                    );
                }
            }

            // Stop/dequeue events
            ExecutionEvent::ChangeDequeued { change_id }
            | ExecutionEvent::ChangeStopped { change_id } => {
                let rt = self.runtime_entry(change_id);
                if matches!(
                    rt.terminal,
                    TerminalState::Archived | TerminalState::Merged | TerminalState::Rejected(_)
                ) {
                    return;
                }
                rt.terminal = TerminalState::None;
                rt.activity = ActivityState::Idle;
                rt.wait_state = WaitState::None;
                rt.clear_blocked_metadata();
                rt.queue_intent = QueueIntent::NotQueued;
                rt.dequeued = true;
                self.resolve_wait_queue.retain(|id| id != change_id);
            }

            // Dynamic queue support
            ExecutionEvent::ChangesRefreshed {
                changes,
                merge_wait_ids,
                worktree_not_ahead_ids,
                ..
            } => {
                // Refresh the initial snapshot if new changes appeared
                let new_ids: Vec<String> = changes
                    .iter()
                    .filter(|c| {
                        !self.initial_change_ids.contains(&c.id)
                            && !self.archived_changes.contains(&c.id)
                    })
                    .map(|c| c.id.clone())
                    .collect();
                for id in new_ids {
                    self.add_dynamic_change(id);
                }

                // If a previously rejected change reappears in the active listing,
                // treat it as reactivated and reset runtime state to defaults.
                for change in changes {
                    let rt = self.runtime_entry(&change.id);
                    if matches!(rt.terminal, TerminalState::Rejected(_)) {
                        rt.terminal = TerminalState::None;
                        rt.activity = ActivityState::Idle;
                        rt.wait_state = WaitState::None;
                        rt.clear_blocked_metadata();
                        rt.queue_intent = QueueIntent::NotQueued;
                    }
                }

                // Apply workspace observations via the reconcile path.
                let mw: Vec<String> = merge_wait_ids.iter().cloned().collect();
                let nah: Vec<String> = worktree_not_ahead_ids.iter().cloned().collect();
                for id in mw {
                    self.apply_observation(&id.clone(), WorkspaceObservation::WorkspaceArchived);
                }
                for id in nah {
                    self.apply_observation(&id.clone(), WorkspaceObservation::WorktreeNotAhead);
                }
            }

            // Other events don't affect shared state directly
            _ => {}
        }
    }
}

impl Default for OrchestratorState {
    fn default() -> Self {
        Self::new(Vec::new(), 0)
    }
}

impl OrchestratorState {
    /// Get the execution mode.
    #[allow(dead_code)]
    pub fn execution_mode(&self) -> ExecutionMode {
        self.execution_mode
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_new_state() {
        let state =
            OrchestratorState::new(vec!["change-a".to_string(), "change-b".to_string()], 10);

        assert_eq!(state.total_changes(), 2);
        assert_eq!(state.remaining_changes(), 2);
        assert_eq!(state.changes_processed(), 0);
        assert_eq!(state.iteration(), 0);
        assert_eq!(state.max_iterations(), 10);
        assert!(state.current_change_id().is_none());
    }

    #[test]
    fn test_is_in_snapshot() {
        let state = OrchestratorState::new(vec!["change-a".to_string()], 0);

        assert!(state.is_in_snapshot("change-a"));
        assert!(!state.is_in_snapshot("change-b"));
    }

    #[test]
    fn test_apply_count_increment() {
        let mut state = OrchestratorState::new(vec!["change-a".to_string()], 0);

        assert_eq!(state.apply_count("change-a"), 0);
        assert_eq!(state.increment_apply_count("change-a"), 1);
        assert_eq!(state.increment_apply_count("change-a"), 2);
        assert_eq!(state.apply_count("change-a"), 2);
    }

    #[test]
    fn test_mark_archived() {
        let mut state =
            OrchestratorState::new(vec!["change-a".to_string(), "change-b".to_string()], 0);
        state.set_current_change(Some("change-a".to_string()));
        state.increment_apply_count("change-a");

        assert!(state.is_pending("change-a"));
        assert!(!state.is_archived("change-a"));
        assert_eq!(state.remaining_changes(), 2);

        state.mark_archived("change-a");

        assert!(!state.is_pending("change-a"));
        assert!(state.is_archived("change-a"));
        assert_eq!(state.remaining_changes(), 1);
        assert_eq!(state.changes_processed(), 1);
        assert!(state.current_change_id().is_none());
        assert_eq!(state.apply_count("change-a"), 0); // Cleared
    }

    #[test]
    fn test_is_complete() {
        let mut state = OrchestratorState::new(vec!["change-a".to_string()], 0);

        assert!(!state.is_complete());
        state.mark_archived("change-a");
        assert!(state.is_complete());
    }

    #[test]
    fn test_iteration_limit() {
        let mut state = OrchestratorState::new(vec![], 10);

        assert!(!state.is_iteration_limit_reached());

        for _ in 0..8 {
            state.increment_iteration();
        }
        assert!(state.is_approaching_iteration_limit()); // 80%
        assert!(!state.is_iteration_limit_reached());

        state.increment_iteration(); // 9
        assert!(!state.is_iteration_limit_reached());

        state.increment_iteration(); // 10
        assert!(state.is_iteration_limit_reached());
    }

    #[test]
    fn test_no_iteration_limit() {
        let mut state = OrchestratorState::new(vec![], 0);

        for _ in 0..100 {
            state.increment_iteration();
        }

        assert!(!state.is_iteration_limit_reached());
        assert!(!state.is_approaching_iteration_limit());
    }

    #[test]
    fn test_add_dynamic_change() {
        let mut state = OrchestratorState::new(vec!["change-a".to_string()], 0);

        assert_eq!(state.total_changes(), 1);
        assert!(!state.is_pending("change-b"));

        state.add_dynamic_change("change-b".to_string());

        assert_eq!(state.total_changes(), 2);
        assert!(state.is_pending("change-b"));
        assert!(state.is_in_snapshot("change-b"));
    }

    #[test]
    fn test_add_dynamic_change_idempotent() {
        let mut state = OrchestratorState::new(vec!["change-a".to_string()], 0);

        state.add_dynamic_change("change-a".to_string()); // Already exists
        state.add_dynamic_change("change-b".to_string());
        state.add_dynamic_change("change-b".to_string()); // Duplicate

        assert_eq!(state.total_changes(), 2); // Not 3 or 4
    }

    #[test]
    fn test_remove_from_pending() {
        let mut state = OrchestratorState::new(vec!["change-a".to_string()], 0);
        state.set_current_change(Some("change-a".to_string()));

        assert!(state.is_pending("change-a"));
        assert!(state.current_change_id().is_some());

        state.remove_from_pending("change-a");

        assert!(!state.is_pending("change-a"));
        assert!(!state.is_archived("change-a")); // Not archived, just removed
        assert!(state.current_change_id().is_none());
    }

    #[test]
    fn test_error_history_management_and_circuit_breaker() {
        let mut state = OrchestratorState::new(vec!["change-a".to_string()], 0);
        let config = CircuitBreakerConfig {
            enabled: true,
            threshold: 2,
        };

        assert!(!state.record_error_and_check_circuit_breaker(
            "change-a",
            "same error",
            config.clone()
        ));
        assert!(state.record_error_and_check_circuit_breaker("change-a", "same error", config));
        assert!(state.last_error("change-a").is_some());

        state.clear_error_history("change-a");
        assert!(state.last_error("change-a").is_none());
    }

    // -----------------------------------------------------------------------
    // Phase 1.2: change_runtime initialisation
    // -----------------------------------------------------------------------

    #[test]
    fn test_orchestrator_state_initializes_change_runtime() {
        let state = OrchestratorState::new(vec!["change-a".to_string(), "change-b".to_string()], 0);

        // Each change must have a runtime entry with the default (not-queued, idle) state.
        let rt_a = state
            .change_runtime("change-a")
            .expect("runtime for change-a");
        assert_eq!(rt_a.queue_intent, QueueIntent::NotQueued);
        assert_eq!(rt_a.activity, ActivityState::Idle);
        assert_eq!(rt_a.wait_state, WaitState::None);
        assert!(matches!(rt_a.terminal, TerminalState::None));

        let rt_b = state
            .change_runtime("change-b")
            .expect("runtime for change-b");
        assert_eq!(rt_b.queue_intent, QueueIntent::NotQueued);
    }

    // -----------------------------------------------------------------------
    // Phase 1.3: invariant helpers
    // -----------------------------------------------------------------------

    #[test]
    fn test_change_runtime_invariants() {
        // Valid: default state.
        let valid = ChangeRuntimeState::default();
        assert!(valid.invariants_hold());

        // Invalid: terminal + active activity.
        let invalid = ChangeRuntimeState {
            terminal: TerminalState::Merged,
            activity: ActivityState::Applying,
            ..Default::default()
        };
        assert!(!invalid.invariants_hold());

        // Invalid: ResolveWait + Resolving.
        let invalid2 = ChangeRuntimeState {
            wait_state: WaitState::ResolveWait,
            activity: ActivityState::Resolving,
            ..Default::default()
        };
        assert!(!invalid2.invariants_hold());

        // Valid: MergeWait + Idle.
        let ok = ChangeRuntimeState {
            wait_state: WaitState::MergeWait,
            ..Default::default()
        };
        assert!(ok.invariants_hold());

        // Rejecting + no terminal outcome is a valid in-flight state while review runs.
        let in_flight_rejecting = ChangeRuntimeState {
            activity: ActivityState::Rejecting,
            terminal: TerminalState::None,
            ..Default::default()
        };
        assert!(in_flight_rejecting.invariants_hold());
    }

    // -----------------------------------------------------------------------
    // Phase 1.4: display_status derivation
    // -----------------------------------------------------------------------

    #[test]
    fn test_display_status_derivation() {
        let state = OrchestratorState::new(vec!["c".to_string()], 0);
        // Default is not queued.
        assert_eq!(state.display_status("c"), "not queued");
        assert_eq!(state.display_status("unknown"), "not queued");

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert_eq!(state.display_status("c"), "queued");

        // Applying takes priority over queued.
        let rt = state.runtime_entry("c");
        rt.activity = ActivityState::Applying;
        assert_eq!(state.display_status("c"), "applying");

        // Terminal takes highest priority.
        let rt = state.runtime_entry("c");
        rt.terminal = TerminalState::Archived;
        assert_eq!(state.display_status("c"), "archived");
    }

    #[test]
    fn test_display_color_derivation() {
        let mut rt = ChangeRuntimeState::default();
        assert_eq!(rt.display_color(), ratatui::style::Color::DarkGray);

        rt.queue_intent = QueueIntent::Queued;
        assert_eq!(rt.display_color(), ratatui::style::Color::Yellow);

        rt.wait_state = WaitState::DependencyBlocked;
        assert_eq!(rt.display_color(), ratatui::style::Color::Gray);

        rt.activity = ActivityState::Applying;
        assert_eq!(rt.display_color(), ratatui::style::Color::Cyan);

        rt.activity = ActivityState::Accepting;
        assert_eq!(rt.display_color(), ratatui::style::Color::LightGreen);

        rt.activity = ActivityState::Archiving;
        assert_eq!(rt.display_color(), ratatui::style::Color::Magenta);

        rt.activity = ActivityState::Resolving;
        assert_eq!(rt.display_color(), ratatui::style::Color::LightCyan);

        rt.activity = ActivityState::Idle;
        rt.wait_state = WaitState::MergeWait;
        assert_eq!(rt.display_color(), ratatui::style::Color::LightMagenta);

        rt.wait_state = WaitState::ResolveWait;
        assert_eq!(rt.display_color(), ratatui::style::Color::Magenta);

        rt.wait_state = WaitState::None;
        rt.terminal = TerminalState::Archived;
        assert_eq!(rt.display_color(), ratatui::style::Color::Blue);

        rt.terminal = TerminalState::Merged;
        assert_eq!(rt.display_color(), ratatui::style::Color::LightBlue);

        rt.terminal = TerminalState::Rejected("blocked".to_string());
        assert_eq!(rt.display_color(), ratatui::style::Color::LightRed);

        rt.terminal = TerminalState::Stopped;
        assert_eq!(rt.display_color(), ratatui::style::Color::DarkGray);

        rt.terminal = TerminalState::Error("boom".to_string());
        assert_eq!(rt.display_color(), ratatui::style::Color::Red);
    }

    #[test]
    fn test_error_message_derivation() {
        let rt = ChangeRuntimeState {
            terminal: TerminalState::Error("fatal".to_string()),
            ..Default::default()
        };
        assert_eq!(rt.error_message(), Some("fatal"));

        let rt2 = ChangeRuntimeState {
            terminal: TerminalState::Merged,
            ..Default::default()
        };
        assert_eq!(rt2.error_message(), None);
    }

    // -----------------------------------------------------------------------
    // Phase 1.5: active/inactive classification
    // -----------------------------------------------------------------------

    #[test]
    fn test_runtime_state_active_classification() {
        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Idle → not active.
        assert!(!state.is_active_change("c"));

        // Applying → active.
        state.runtime_entry("c").activity = ActivityState::Applying;
        assert!(state.is_active_change("c"));

        // Terminal → not active (invariant-wise, but is_active_change checks activity).
        state.runtime_entry("c").terminal = TerminalState::Archived;
        state.runtime_entry("c").activity = ActivityState::Idle;
        assert!(!state.is_active_change("c"));
        assert!(state.is_terminal_change("c"));
    }

    // -----------------------------------------------------------------------
    // Phase 2.2: apply_command queue intent
    // -----------------------------------------------------------------------

    #[test]
    fn test_apply_command_queue_intent() {
        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // AddToQueue.
        let outcome = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(matches!(outcome, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "queued");

        // AddToQueue again → NoOp (idempotent).
        let outcome2 = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(matches!(outcome2, ReduceOutcome::NoOp));

        // RemoveFromQueue.
        let outcome3 = state.apply_command(ReducerCommand::RemoveFromQueue("c".to_string()));
        assert!(matches!(outcome3, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "not queued");

        // RemoveFromQueue again → NoOp.
        let outcome4 = state.apply_command(ReducerCommand::RemoveFromQueue("c".to_string()));
        assert!(matches!(outcome4, ReduceOutcome::NoOp));

        // DequeueChange.
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        let outcome5 = state.apply_command(ReducerCommand::DequeueChange("c".to_string()));
        assert!(matches!(outcome5, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "not queued");

        // DequeueChange on already not queued keeps queue-off state.
        let outcome6 = state.apply_command(ReducerCommand::DequeueChange("c".to_string()));
        assert!(matches!(outcome6, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "not queued");

        // Rejected cannot be re-queued until a refresh reactivates the change.
        state.runtime_entry("c").terminal = TerminalState::Rejected("blocked".to_string());
        let outcome7 = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(matches!(outcome7, ReduceOutcome::NoOp));

        // Reactivation path: when the change reappears in active listing after
        // REJECTED.md removal, ChangesRefreshed clears rejected terminal state.
        use crate::events::ExecutionEvent;
        use crate::openspec::{Change, ProposalMetadata};
        use std::collections::{HashMap, HashSet};
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![Change {
                id: "c".to_string(),
                completed_tasks: 0,
                total_tasks: 1,
                last_modified: "now".to_string(),
                dependencies: Vec::new(),
                metadata: ProposalMetadata::default(),
            }],
            committed_change_ids: HashSet::new(),
            uncommitted_file_change_ids: HashSet::new(),
            worktree_change_ids: HashSet::new(),
            worktree_paths: HashMap::new(),
            worktree_not_ahead_ids: HashSet::new(),
            merge_wait_ids: HashSet::new(),
        });
        assert_eq!(state.display_status("c"), "not queued");

        // AddToQueue must be accepted again after reactivation.
        let outcome8 = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(matches!(outcome8, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "queued");
    }

    // -----------------------------------------------------------------------
    // Phase 2.3: apply_execution_event transitions
    // -----------------------------------------------------------------------

    #[test]
    fn test_apply_execution_event_transitions() {
        use crate::events::{ExecutionEvent, RejectionOutcome};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        assert_eq!(state.display_status("c"), "applying");

        state.apply_execution_event(&ExecutionEvent::ApplyCompleted {
            change_id: "c".to_string(),
            revision: "rev1".to_string(),
        });
        assert_eq!(state.display_status("c"), "not queued");

        state.apply_execution_event(&ExecutionEvent::AcceptanceStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        assert_eq!(state.display_status("c"), "accepting");

        state.apply_execution_event(&ExecutionEvent::AcceptanceCompleted {
            change_id: "c".to_string(),
        });

        state.apply_execution_event(&ExecutionEvent::WorkspaceStatusUpdated {
            change_id: "c".to_string(),
            workspace_name: "ws-c".to_string(),
            status: crate::vcs::WorkspaceStatus::Rejecting,
        });
        assert_eq!(state.display_status("c"), "rejecting");

        state.apply_execution_event(&ExecutionEvent::RejectionReviewCompleted {
            change_id: "c".to_string(),
            outcome: RejectionOutcome::Resume,
        });
        assert_eq!(state.display_status("c"), "applying");
        assert_ne!(
            state
                .change_runtime("c")
                .expect("runtime for c after rejecting resume")
                .activity,
            ActivityState::Rejecting
        );

        state.apply_execution_event(&ExecutionEvent::RejectionReviewFailed {
            change_id: "c".to_string(),
            error: "rejecting failed".to_string(),
        });
        assert_eq!(state.display_status("c"), "error");
        assert_ne!(
            state
                .change_runtime("c")
                .expect("runtime for c after rejecting failure")
                .activity,
            ActivityState::Rejecting
        );

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_execution_event(&ExecutionEvent::ProcessingStarted("c".to_string()));
        state.apply_execution_event(&ExecutionEvent::WorkspaceStatusUpdated {
            change_id: "c".to_string(),
            workspace_name: "ws-c".to_string(),
            status: crate::vcs::WorkspaceStatus::Rejecting,
        });
        assert_eq!(state.display_status("c"), "rejecting");

        state.apply_execution_event(&ExecutionEvent::RejectionReviewCompleted {
            change_id: "c".to_string(),
            outcome: RejectionOutcome::Confirm,
        });
        assert_eq!(state.display_status("c"), "rejected");
        assert_ne!(
            state
                .change_runtime("c")
                .expect("runtime for c after rejecting confirm")
                .activity,
            ActivityState::Rejecting
        );
    }

    #[test]
    fn test_rejection_review_block_transitions_to_blocked_with_metadata() {
        use crate::events::{ExecutionEvent, RejectionOutcome};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_execution_event(&ExecutionEvent::ProcessingStarted("c".to_string()));
        state.apply_execution_event(&ExecutionEvent::WorkspaceStatusUpdated {
            change_id: "c".to_string(),
            workspace_name: "ws-c".to_string(),
            status: crate::vcs::WorkspaceStatus::Rejecting,
        });
        assert_eq!(state.display_status("c"), "rejecting");

        state.apply_execution_event(&ExecutionEvent::RejectionReviewCompleted {
            change_id: "c".to_string(),
            outcome: RejectionOutcome::Block,
        });

        let runtime = state
            .change_runtime("c")
            .expect("runtime for c after rejecting block");
        assert_eq!(state.display_status("c"), "stalled");
        assert_eq!(runtime.activity, ActivityState::Idle);
        assert_eq!(runtime.wait_state, WaitState::Stalled);
        assert!(matches!(runtime.terminal, TerminalState::None));
        assert_eq!(
            runtime.blocked_metadata.blocker_reason.as_deref(),
            Some("rejection review returned block; unresolved blocker remains")
        );
        assert_eq!(
            runtime.blocked_metadata.unblock_metadata.as_deref(),
            Some(
                "resolve unresolved blocker tasks in openspec/changes/<change_id>/tasks.md, then trigger explicit resume"
            )
        );
        assert_eq!(
            runtime.blocked_metadata.worktree_snapshot.as_deref(),
            Some("existing worktree and WIP context are preserved for stalled rejection review")
        );
    }

    #[test]
    fn test_rejection_review_resume_from_archived_workspace_context_sets_applying() {
        use crate::events::{ExecutionEvent, RejectionOutcome};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Resume path can start from an archived workspace that re-entered rejecting review.
        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);
        assert_eq!(state.display_status("c"), "merge wait");

        state.apply_execution_event(&ExecutionEvent::WorkspaceStatusUpdated {
            change_id: "c".to_string(),
            workspace_name: "ws-c".to_string(),
            status: crate::vcs::WorkspaceStatus::Rejecting,
        });
        assert_eq!(state.display_status("c"), "rejecting");

        state.apply_execution_event(&ExecutionEvent::RejectionReviewCompleted {
            change_id: "c".to_string(),
            outcome: RejectionOutcome::Resume,
        });

        assert_eq!(state.display_status("c"), "applying");
    }

    #[test]
    fn test_rejection_review_block_from_archived_workspace_context_sets_stalled() {
        use crate::events::{ExecutionEvent, RejectionOutcome};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);
        assert_eq!(state.display_status("c"), "merge wait");

        state.apply_execution_event(&ExecutionEvent::WorkspaceStatusUpdated {
            change_id: "c".to_string(),
            workspace_name: "ws-c".to_string(),
            status: crate::vcs::WorkspaceStatus::Rejecting,
        });
        assert_eq!(state.display_status("c"), "rejecting");

        state.apply_execution_event(&ExecutionEvent::RejectionReviewCompleted {
            change_id: "c".to_string(),
            outcome: RejectionOutcome::Block,
        });

        assert_eq!(state.display_status("c"), "stalled");
    }

    // -----------------------------------------------------------------------
    // Phase 2.4: apply_observation reconcile
    // -----------------------------------------------------------------------

    #[test]
    fn test_apply_observation_reconcile_merge_wait() {
        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // WorkspaceArchived → transitions to MergeWait.
        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);
        assert_eq!(state.display_status("c"), "merge wait");

        // WorktreeNotAhead → clears MergeWait.
        state.apply_observation("c", WorkspaceObservation::WorktreeNotAhead);
        assert_eq!(state.display_status("c"), "not queued");

        // Active execution prevents observation from overwriting.
        state.runtime_entry("c").activity = ActivityState::Applying;
        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);
        // Still applying (not overwritten).
        assert_eq!(state.display_status("c"), "applying");
    }

    // -----------------------------------------------------------------------
    // Phase 2.5: idempotency and late-event precedence
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // Phase 5.2: changes_refreshed uses reducer observation path
    // -----------------------------------------------------------------------

    #[test]
    fn test_changes_refreshed_uses_reducer_observation_path() {
        use crate::events::ExecutionEvent;
        use std::collections::{HashMap, HashSet};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Simulate a ChangesRefreshed with c in merge_wait_ids.
        let mut merge_wait_ids = HashSet::new();
        merge_wait_ids.insert("c".to_string());
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: HashSet::new(),
            uncommitted_file_change_ids: HashSet::new(),
            worktree_change_ids: HashSet::new(),
            worktree_paths: HashMap::new(),
            worktree_not_ahead_ids: HashSet::new(),
            merge_wait_ids,
        });

        // The reducer should have set MergeWait via apply_observation.
        assert_eq!(state.display_status("c"), "merge wait");
    }

    #[test]
    fn test_change_rejected_clears_only_target_queue_intent() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["a".to_string(), "b".to_string()], 0);

        state.apply_command(ReducerCommand::AddToQueue("a".to_string()));
        state.apply_command(ReducerCommand::AddToQueue("b".to_string()));
        assert_eq!(state.display_status("a"), "queued");
        assert_eq!(state.display_status("b"), "queued");

        state.apply_execution_event(&ExecutionEvent::ChangeRejected {
            change_id: "a".to_string(),
            reason: "blocked".to_string(),
        });

        assert_eq!(state.display_status("a"), "rejected");
        assert_eq!(state.display_status("b"), "queued");
    }

    #[test]
    fn test_changes_refreshed_reactivates_rejected_change() {
        use crate::events::ExecutionEvent;
        use crate::openspec::{Change, ProposalMetadata};
        use std::collections::{HashMap, HashSet};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Previously rejected and with stale non-default runtime fields.
        let rt = state.runtime_entry("c");
        rt.terminal = TerminalState::Rejected("blocked".to_string());
        rt.activity = ActivityState::Rejecting;
        rt.wait_state = WaitState::MergeWait;
        rt.queue_intent = QueueIntent::Queued;

        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![Change {
                id: "c".to_string(),
                completed_tasks: 0,
                total_tasks: 1,
                last_modified: "now".to_string(),
                dependencies: Vec::new(),
                metadata: ProposalMetadata::default(),
            }],
            committed_change_ids: HashSet::new(),
            uncommitted_file_change_ids: HashSet::new(),
            worktree_change_ids: HashSet::new(),
            worktree_paths: HashMap::new(),
            worktree_not_ahead_ids: HashSet::new(),
            merge_wait_ids: HashSet::new(),
        });

        let rt = state.change_runtime("c").expect("runtime for c");
        assert!(matches!(rt.terminal, TerminalState::None));
        assert!(matches!(rt.activity, ActivityState::Idle));
        assert!(matches!(rt.wait_state, WaitState::None));
        assert!(matches!(rt.queue_intent, QueueIntent::NotQueued));
        assert_eq!(state.display_status("c"), "not queued");
    }

    // -----------------------------------------------------------------------
    // Phase 5.3: merge wait release after external merge
    // -----------------------------------------------------------------------

    #[test]
    fn test_merge_wait_release_after_external_merge() {
        use crate::events::ExecutionEvent;
        use std::collections::{HashMap, HashSet};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Put into MergeWait.
        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);
        assert_eq!(state.display_status("c"), "merge wait");

        // Refreshed with c in worktree_not_ahead_ids → clears MergeWait.
        let mut not_ahead = HashSet::new();
        not_ahead.insert("c".to_string());
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: HashSet::new(),
            uncommitted_file_change_ids: HashSet::new(),
            worktree_change_ids: HashSet::new(),
            worktree_paths: HashMap::new(),
            worktree_not_ahead_ids: not_ahead,
            merge_wait_ids: HashSet::new(),
        });
        assert_eq!(state.display_status("c"), "not queued");
    }

    // -----------------------------------------------------------------------
    // Phase 5.4: WorkspaceState::Archived recovers MergeWait (not ResolveWait)
    // -----------------------------------------------------------------------

    #[test]
    fn test_workspace_archived_recovers_merge_wait() {
        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // WorkspaceArchived observation → MergeWait.
        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);
        assert_eq!(state.display_status("c"), "merge wait");
        assert!(
            matches!(
                state.change_runtime("c").unwrap().wait_state,
                WaitState::MergeWait
            ),
            "observation should set MergeWait, not ResolveWait"
        );
    }

    // -----------------------------------------------------------------------
    // Phase 5.5: queue-added change not overwritten by MergeWait refresh
    // -----------------------------------------------------------------------

    #[test]
    fn test_queue_add_not_overwritten_by_merge_wait_refresh() {
        use crate::events::ExecutionEvent;
        use std::collections::{HashMap, HashSet};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Queue the change.
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert_eq!(state.display_status("c"), "queued");

        // Simulate a refresh that tries to set MergeWait on "c".
        // Since "c" is actively queued (not in a MergeWait-worthy state),
        // apply_observation should NOT overwrite the queued state.
        // (WorkspaceArchived only sets MergeWait if not already in a wait/terminal state.)
        state.apply_observation("c", WorkspaceObservation::WorkspaceArchived);

        // Still queued because active wait/queue intent is not MergeWait-eligible.
        // Note: apply_observation sets MergeWait if not already in a wait state.
        // However, "queued" means QueueIntent::Queued, not a WaitState.
        // The reconcile only touches wait_state, not queue_intent.
        // So wait_state gets set to MergeWait, but display_status returns "merge wait"
        // only if there's no active activity. Let's verify the correct behavior:
        // - Queue intent: Queued
        // - Activity: Idle
        // - WaitState: set to MergeWait by observation
        // - Display precedence: terminal > activity > wait > queue_intent
        // So if WaitState=MergeWait, display shows "merge wait".
        // The test verifies that WorktreeNotAhead clears it back.
        let mut not_ahead = HashSet::new();
        not_ahead.insert("c".to_string());
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: HashSet::new(),
            uncommitted_file_change_ids: HashSet::new(),
            worktree_change_ids: HashSet::new(),
            worktree_paths: HashMap::new(),
            worktree_not_ahead_ids: not_ahead,
            merge_wait_ids: HashSet::new(),
        });
        // After clearing MergeWait, the queue intent (Queued) is visible again.
        assert_eq!(state.display_status("c"), "queued");
    }

    // -----------------------------------------------------------------------
    // Phase 4.3: parallel merge events drive reducer wait states
    // -----------------------------------------------------------------------

    #[test]
    fn test_parallel_merge_events_drive_reducer_wait_states() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // MergeDeferred (manual, not auto-resumable) → MergeWait
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "c".to_string(),
            reason: "base dirty".to_string(),
            auto_resumable: false,
        });
        assert_eq!(state.display_status("c"), "merge wait");

        // ResolveStarted → Resolving (clears MergeWait)
        state.apply_execution_event(&ExecutionEvent::ResolveStarted {
            change_id: "c".to_string(),
            command: "resolve".to_string(),
        });
        assert_eq!(state.display_status("c"), "resolving");

        // ResolveCompleted → Merged (terminal): successful resolve means the change is merged.
        state.apply_execution_event(&ExecutionEvent::ResolveCompleted {
            change_id: "c".to_string(),
            worktree_change_ids: None,
        });
        assert_eq!(state.display_status("c"), "merged");

        // MergeCompleted is idempotent once already terminal (parallel orchestrator path).
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "c".to_string(),
            revision: "rev".to_string(),
        });
        assert_eq!(state.display_status("c"), "merged");

        // ResolveFailed after Merged must NOT regress.
        state.apply_execution_event(&ExecutionEvent::ResolveFailed {
            change_id: "c".to_string(),
            error: "late".to_string(),
        });
        assert_eq!(state.display_status("c"), "merged");
    }

    // -----------------------------------------------------------------------
    // Regression: stale ResolveWait must not survive ResolveCompleted + refresh
    // -----------------------------------------------------------------------
    //
    // Scenario: base dirtiness caused MergeWait, user triggered manual resolve
    // (ResolveMerge command → ResolveWait), resolve succeeded, but the row was
    // previously stuck at "resolve pending" because ResolveCompleted was not
    // applied to the shared reducer before the next ChangesRefreshed.

    #[test]
    fn test_resolve_completed_clears_resolve_wait_and_survives_refresh() {
        use crate::events::ExecutionEvent;

        // Parallel mode is required to model MergeWait/ResolveWait lifecycle.
        let mut state =
            OrchestratorState::with_mode(vec!["c".to_string()], 0, ExecutionMode::Parallel);

        // Step 1: change archived -> enters MergeWait in parallel mode.
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));
        assert_eq!(state.display_status("c"), "merge wait");

        // Step 2: user triggers manual resolve → reducer transitions to ResolveWait.
        state.apply_command(ReducerCommand::ResolveMerge("c".to_string()));
        assert_eq!(state.display_status("c"), "resolve pending");
        assert_eq!(state.resolve_wait_change_ids(), vec!["c".to_string()]);

        // Step 3: a refresh still sees merge_wait/worktree branch and emits observations.
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: std::collections::HashSet::new(),
            uncommitted_file_change_ids: std::collections::HashSet::new(),
            worktree_change_ids: std::collections::HashSet::from(["c".to_string()]),
            worktree_paths: std::collections::HashMap::new(),
            worktree_not_ahead_ids: std::collections::HashSet::new(),
            merge_wait_ids: std::collections::HashSet::from(["c".to_string()]),
        });
        assert_eq!(state.display_status("c"), "resolve pending");

        // Step 4: resolve succeeds → must transition to merged, not stall at resolve pending.
        state.apply_execution_event(&ExecutionEvent::ResolveCompleted {
            change_id: "c".to_string(),
            worktree_change_ids: None,
        });
        assert_eq!(state.display_status("c"), "merged");
        assert!(
            state.resolve_wait_change_ids().is_empty(),
            "resolve completion must clear queued resolve intent"
        );

        // Step 5: another refresh still seeing stale merge_wait/worktree signals
        // must NOT regress the row back to "resolve pending" or "merge wait".
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: std::collections::HashSet::new(),
            uncommitted_file_change_ids: std::collections::HashSet::new(),
            worktree_change_ids: std::collections::HashSet::from(["c".to_string()]),
            worktree_paths: std::collections::HashMap::new(),
            worktree_not_ahead_ids: std::collections::HashSet::new(),
            merge_wait_ids: std::collections::HashSet::from(["c".to_string()]),
        });
        assert_eq!(state.display_status("c"), "merged");
        assert_ne!(
            state.display_status("c"),
            "resolve pending",
            "row must not regress to resolve pending after successful resolve + refresh"
        );
    }

    #[test]
    fn test_resolve_failed_restores_merge_wait() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Reach MergeWait via manual-intervention deferral, then promote to ResolveWait.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "c".to_string(),
            reason: "base dirty".to_string(),
            auto_resumable: false,
        });
        state.apply_command(ReducerCommand::ResolveMerge("c".to_string()));
        state.apply_execution_event(&ExecutionEvent::ResolveStarted {
            change_id: "c".to_string(),
            command: "resolve".to_string(),
        });

        // Resolve fails → must return to merge wait, not stay queued/idle.
        state.apply_execution_event(&ExecutionEvent::ResolveFailed {
            change_id: "c".to_string(),
            error: "conflict".to_string(),
        });
        assert_eq!(state.display_status("c"), "merge wait");

        // A subsequent RefreshFailed-after-terminal must not regress a Merged entry.
        let mut state2 = OrchestratorState::new(vec!["c".to_string()], 0);
        state2.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "c".to_string(),
            revision: "rev".to_string(),
        });
        state2.apply_execution_event(&ExecutionEvent::ResolveFailed {
            change_id: "c".to_string(),
            error: "late".to_string(),
        });
        assert_eq!(state2.display_status("c"), "merged");
    }

    // -----------------------------------------------------------------------
    // Phase 4.4: late events after stop do not regress state
    // -----------------------------------------------------------------------

    #[test]
    fn test_workspace_status_update_targets_explicit_change_id() {
        use crate::events::ExecutionEvent;
        use crate::vcs::WorkspaceStatus;

        let mut state = OrchestratorState::new(vec!["a".to_string(), "b".to_string()], 0);

        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "a".to_string(),
            command: "apply-a".to_string(),
        });
        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "b".to_string(),
            command: "apply-b".to_string(),
        });
        state.apply_execution_event(&ExecutionEvent::WorkspaceStatusUpdated {
            change_id: "b".to_string(),
            workspace_name: "ws-b".to_string(),
            status: WorkspaceStatus::Rejecting,
        });

        assert_eq!(state.display_status("a"), "applying");
        assert_eq!(state.display_status("b"), "rejecting");
    }

    #[test]
    fn test_late_events_after_stop_do_not_regress_state() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Dequeue the change.
        state.apply_execution_event(&ExecutionEvent::ChangeDequeued {
            change_id: "c".to_string(),
        });
        assert_eq!(state.display_status("c"), "not queued");

        // Late ApplyStarted must not regress from dequeued state.
        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        assert_eq!(state.display_status("c"), "not queued");

        // Late AcceptanceStarted must not regress from dequeued state.
        state.apply_execution_event(&ExecutionEvent::AcceptanceStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        assert_eq!(state.display_status("c"), "not queued");

        // Late ProcessingError must not regress from dequeued state.
        state.apply_execution_event(&ExecutionEvent::ProcessingError {
            id: "c".to_string(),
            error: "late error".to_string(),
        });
        assert_eq!(state.display_status("c"), "not queued");
    }

    // -----------------------------------------------------------------------
    // Phase 2.5: idempotency and late-event precedence
    // -----------------------------------------------------------------------

    #[test]
    fn test_reducer_idempotency_and_precedence() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Archive the change.
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));
        assert_eq!(state.display_status("c"), "archived");

        // Late ResolveFailed must NOT regress archived state.
        state.apply_execution_event(&ExecutionEvent::ResolveFailed {
            change_id: "c".to_string(),
            error: "late".to_string(),
        });
        assert_eq!(state.display_status("c"), "archived");

        // Duplicate ApplyStarted on a terminal change must be no-op.
        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        // Terminal wins: still archived.
        assert_eq!(state.display_status("c"), "archived");
    }

    /// Phase 7.2: reducer runtime state and legacy aggregates (pending_changes, archived_changes,
    /// current_change_id, apply_count) must agree on the canonical status of each change
    /// after a representative lifecycle sequence.
    #[test]
    fn test_reducer_runtime_and_legacy_aggregates_stay_consistent() {
        use crate::events::ExecutionEvent;

        let mut state =
            OrchestratorState::new(vec!["a".to_string(), "b".to_string(), "c".to_string()], 5);

        // ── Initial state ──────────────────────────────────────────────────
        // All changes start in pending_changes (from new()), but reducer says "not queued"
        // because no AddToQueue command has been issued yet.
        assert_eq!(state.display_status("a"), "not queued");
        assert_eq!(state.display_status("b"), "not queued");
        assert_eq!(state.display_status("c"), "not queued");
        assert!(state.is_pending("a"));
        assert!(state.is_pending("b"));
        assert!(state.is_pending("c"));

        // ── Queue a and b via reducer ──────────────────────────────────────
        state.apply_command(ReducerCommand::AddToQueue("a".to_string()));
        state.apply_command(ReducerCommand::AddToQueue("b".to_string()));

        assert_eq!(state.display_status("a"), "queued");
        assert_eq!(state.display_status("b"), "queued");
        assert!(state.is_pending("a"));
        assert!(state.is_pending("b"));

        // ── Start applying 'a' ─────────────────────────────────────────────
        state.set_current_change(Some("a".to_string()));
        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "a".to_string(),
            command: "cmd".to_string(),
        });
        state.increment_apply_count("a");

        assert_eq!(state.display_status("a"), "applying");
        assert_eq!(state.current_change_id(), Some(&"a".to_string()));
        assert_eq!(state.apply_count("a"), 1);

        // ── Archive 'a' ────────────────────────────────────────────────────
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("a".to_string()));
        state.mark_archived("a");

        // Reducer terminal and legacy archived set must agree.
        assert_eq!(state.display_status("a"), "archived");
        assert!(state.is_archived("a"));
        assert!(!state.is_pending("a"));

        // ── Dequeue 'b' ────────────────────────────────────────────────────
        state.apply_command(ReducerCommand::DequeueChange("b".to_string()));

        // Reducer returns b to not queued; legacy pending membership is unchanged.
        assert_eq!(state.display_status("b"), "not queued");
        // 'c' (never explicitly queued in reducer) is still "not queued" in reducer.
        assert_eq!(state.display_status("c"), "not queued");
        assert!(state.is_pending("c")); // legacy: still in pending set
        assert!(!state.is_archived("c"));
    }

    // -----------------------------------------------------------------------
    // Execution mode tests: Serial vs Parallel state machine
    // -----------------------------------------------------------------------

    #[test]
    fn test_serial_mode_change_archived_is_terminal() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        // Default is Serial mode.
        assert_eq!(state.execution_mode(), ExecutionMode::Serial);

        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));
        assert_eq!(state.display_status("c"), "archived");
        assert!(state.is_terminal_change("c"));

        // MergeCompleted after terminal Archived in serial mode is a no-op.
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "c".to_string(),
            revision: "rev".to_string(),
        });
        assert_eq!(
            state.display_status("c"),
            "archived",
            "Serial: MergeCompleted must not override Archived terminal"
        );
    }

    #[test]
    fn test_parallel_mode_change_archived_transitions_to_merge_wait() {
        use crate::events::ExecutionEvent;

        let mut state =
            OrchestratorState::with_mode(vec!["c".to_string()], 0, ExecutionMode::Parallel);
        assert_eq!(state.execution_mode(), ExecutionMode::Parallel);

        // Apply → Archive
        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        state.apply_execution_event(&ExecutionEvent::ApplyCompleted {
            change_id: "c".to_string(),
            revision: "rev1".to_string(),
        });
        state.apply_execution_event(&ExecutionEvent::ArchiveStarted {
            change_id: "c".to_string(),
            command: "archive".to_string(),
        });
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));

        // In parallel mode, ChangeArchived should NOT be terminal.
        assert_eq!(
            state.display_status("c"),
            "merge wait",
            "Parallel: ChangeArchived must transition to merge wait when no resolving change exists"
        );
        assert!(
            !state.is_terminal_change("c"),
            "Parallel: change must not be terminal after archive"
        );

        // MergeCompleted should now succeed.
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "c".to_string(),
            revision: "merge-rev".to_string(),
        });
        assert_eq!(
            state.display_status("c"),
            "merged",
            "Parallel: MergeCompleted must transition to merged terminal"
        );
        assert!(state.is_terminal_change("c"));
    }

    #[test]
    fn test_parallel_mode_change_archived_uses_resolve_pending_when_other_change_is_resolving() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::with_mode(
            vec!["resolving".to_string(), "archived".to_string()],
            0,
            ExecutionMode::Parallel,
        );

        state.apply_execution_event(&ExecutionEvent::ResolveStarted {
            change_id: "resolving".to_string(),
            command: "resolve resolving".to_string(),
        });
        assert_eq!(state.display_status("resolving"), "resolving");

        state.apply_execution_event(&ExecutionEvent::ChangeArchived("archived".to_string()));
        assert_eq!(
            state.display_status("archived"),
            "resolve pending",
            "Parallel: ChangeArchived must transition to resolve pending while another change is resolving"
        );
        assert!(!state.is_terminal_change("archived"));
    }

    #[test]
    fn test_parallel_mode_full_lifecycle() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::with_mode(
            vec!["a".to_string(), "b".to_string()],
            0,
            ExecutionMode::Parallel,
        );

        // Queue and process 'a'
        state.apply_command(ReducerCommand::AddToQueue("a".to_string()));
        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "a".to_string(),
            command: "cmd".to_string(),
        });
        assert_eq!(state.display_status("a"), "applying");

        state.apply_execution_event(&ExecutionEvent::ChangeArchived("a".to_string()));
        assert_eq!(state.display_status("a"), "merge wait");
        assert!(!state.is_terminal_change("a"));

        // Merge 'a'
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "a".to_string(),
            revision: "rev-a".to_string(),
        });
        assert_eq!(state.display_status("a"), "merged");
        assert!(state.is_terminal_change("a"));

        // 'b' is still not queued
        assert_eq!(state.display_status("b"), "not queued");
        assert!(!state.is_terminal_change("b"));
    }

    #[test]
    fn test_parallel_mode_merge_deferred_then_completed() {
        use crate::events::ExecutionEvent;

        let mut state =
            OrchestratorState::with_mode(vec!["c".to_string()], 0, ExecutionMode::Parallel);

        // Archive the change
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));
        assert_eq!(state.display_status("c"), "merge wait");

        // Merge deferred (manual, not auto-resumable)
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "c".to_string(),
            reason: "base dirty".to_string(),
            auto_resumable: false,
        });
        // Manual deferral: stays in merge wait.
        assert_eq!(state.display_status("c"), "merge wait");

        // Eventually merge succeeds
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "c".to_string(),
            revision: "rev".to_string(),
        });
        assert_eq!(state.display_status("c"), "merged");
        assert!(state.is_terminal_change("c"));
    }

    #[test]
    fn test_parallel_mode_late_events_do_not_regress_merged() {
        use crate::events::ExecutionEvent;

        let mut state =
            OrchestratorState::with_mode(vec!["c".to_string()], 0, ExecutionMode::Parallel);

        // Full lifecycle to merged
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "c".to_string(),
            revision: "rev".to_string(),
        });
        assert_eq!(state.display_status("c"), "merged");

        // Late events must not regress
        state.apply_execution_event(&ExecutionEvent::ResolveFailed {
            change_id: "c".to_string(),
            error: "late".to_string(),
        });
        assert_eq!(state.display_status("c"), "merged");

        state.apply_execution_event(&ExecutionEvent::ApplyStarted {
            change_id: "c".to_string(),
            command: "cmd".to_string(),
        });
        assert_eq!(state.display_status("c"), "merged");
    }

    // -----------------------------------------------------------------------
    // Regression: auto-resumable MergeDeferred must not stay in MergeWait
    // -----------------------------------------------------------------------

    /// `MergeDeferred(auto_resumable=true)` must set ResolveWait, not MergeWait.
    /// This prevents the "stuck after prior merge" scenario where a change
    /// appears to need manual M-press even though it can be resolved automatically.
    #[test]
    fn test_auto_resumable_merge_deferred_sets_resolve_wait() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["b".to_string()], 0);

        // change-b gets a MergeDeferred that is auto-resumable (dirty base caused by
        // change-a's merge being in progress).
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "b".to_string(),
            reason: "Merge in progress (MERGE_HEAD exists)".to_string(),
            auto_resumable: true,
        });

        // Must NOT land in merge wait (which would require manual M press).
        assert_eq!(
            state.display_status("b"),
            "resolve pending",
            "auto-resumable deferred change must enter ResolveWait, not MergeWait"
        );
    }

    /// Workspace refresh after auto-resumable deferral must not regress to MergeWait.
    #[test]
    fn test_auto_resumable_deferred_survives_workspace_refresh() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["b".to_string()], 0);

        // Auto-resumable deferral → ResolveWait.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "b".to_string(),
            reason: "Working tree has uncommitted changes".to_string(),
            auto_resumable: true,
        });
        assert_eq!(state.display_status("b"), "resolve pending");

        // Subsequent ChangesRefreshed sees the workspace as archived (still waiting).
        // It must NOT regress the auto-resolve intent back to merge wait.
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: Default::default(),
            uncommitted_file_change_ids: Default::default(),
            worktree_change_ids: Default::default(),
            worktree_paths: Default::default(),
            worktree_not_ahead_ids: Default::default(),
            merge_wait_ids: ["b".to_string()].into_iter().collect(),
        });

        assert_eq!(
            state.display_status("b"),
            "resolve pending",
            "workspace refresh must not regress auto-resumable deferred change to merge wait"
        );
    }

    /// After auto-resumable deferral, MergeCompleted (from retry) drives change to Merged.
    #[test]
    fn test_auto_resumable_deferred_then_merge_completed() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["b".to_string()], 0);

        // Auto-resumable deferral.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "b".to_string(),
            reason: "Merge in progress (MERGE_HEAD exists)".to_string(),
            auto_resumable: true,
        });
        assert_eq!(state.display_status("b"), "resolve pending");

        // Scheduler retries and merge succeeds.
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "b".to_string(),
            revision: "abc123".to_string(),
        });
        assert_eq!(state.display_status("b"), "merged");
        assert!(state.is_terminal_change("b"));
    }

    // -----------------------------------------------------------------------
    // Fix: manual resolve dirty-base classification (fix-resolve-dirty-base-transition)
    // -----------------------------------------------------------------------

    /// Manual resolve blocked by another merge in progress → MergeDeferred(auto_resumable=true)
    /// → ResolveWait ("resolve pending"), eligible for automatic retry.
    #[test]
    fn test_manual_resolve_blocked_by_merge_in_progress_becomes_resolve_pending() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Change starts in MergeWait.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "c".to_string(),
            reason: "base dirty".to_string(),
            auto_resumable: false,
        });
        assert_eq!(state.display_status("c"), "merge wait");

        // User requests resolve → ResolveWait.
        state.apply_command(ReducerCommand::ResolveMerge("c".to_string()));
        assert_eq!(state.display_status("c"), "resolve pending");

        // Dirty-base check discovers MERGE_HEAD → auto-resumable MergeDeferred.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "c".to_string(),
            reason: "Merge in progress (MERGE_HEAD exists)".to_string(),
            auto_resumable: true,
        });
        assert_eq!(
            state.display_status("c"),
            "resolve pending",
            "auto-resumable dirty base must stay as resolve pending"
        );
    }

    /// Manual resolve blocked by uncommitted changes → ResolveFailed → MergeWait.
    #[test]
    fn test_manual_resolve_blocked_by_uncommitted_changes_stays_merge_wait() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Change starts in MergeWait.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "c".to_string(),
            reason: "base dirty".to_string(),
            auto_resumable: false,
        });
        assert_eq!(state.display_status("c"), "merge wait");

        // User requests resolve → ResolveWait.
        state.apply_command(ReducerCommand::ResolveMerge("c".to_string()));
        assert_eq!(state.display_status("c"), "resolve pending");

        // Dirty-base check discovers uncommitted changes → ResolveFailed.
        // Note: No ResolveStarted was sent (early exit).
        state.apply_execution_event(&ExecutionEvent::ResolveFailed {
            change_id: "c".to_string(),
            error: "Base is dirty: Working tree has uncommitted changes".to_string(),
        });
        assert_eq!(
            state.display_status("c"),
            "merge wait",
            "uncommitted-changes dirty base must revert to merge wait"
        );
    }

    /// After auto-resumable deferral from manual resolve, a preceding resolve
    /// completes (ResolveCompleted for another change) → the deferred change is
    /// retried via retry_deferred_merges → MergeCompleted → Merged.
    #[test]
    fn test_auto_resumable_deferred_resolve_auto_retries_after_preceding_completes() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["a".to_string(), "b".to_string()], 0);

        // change-a is being resolved actively.
        state.apply_execution_event(&ExecutionEvent::ResolveStarted {
            change_id: "a".to_string(),
            command: "resolve a".to_string(),
        });
        assert_eq!(state.display_status("a"), "resolving");

        // change-b tries manual resolve → blocked by MERGE_HEAD → auto-resumable.
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "b".to_string(),
            reason: "Merge in progress (MERGE_HEAD exists)".to_string(),
            auto_resumable: true,
        });
        assert_eq!(state.display_status("b"), "resolve pending");

        // change-a resolve completes.
        state.apply_execution_event(&ExecutionEvent::ResolveCompleted {
            change_id: "a".to_string(),
            worktree_change_ids: None,
        });
        assert_eq!(state.display_status("a"), "merged");

        // retry_deferred_merges retries change-b and succeeds → MergeCompleted.
        state.apply_execution_event(&ExecutionEvent::MergeCompleted {
            change_id: "b".to_string(),
            revision: "rev-b".to_string(),
        });
        assert_eq!(state.display_status("b"), "merged");
        assert!(state.is_terminal_change("b"));
    }

    // -----------------------------------------------------------------------
    // Fix: parallel TUI queued/blocked state regression – reducer unit tests
    // -----------------------------------------------------------------------

    /// AddToQueue on a change in Error terminal state must clear the terminal and
    /// set queue_intent = Queued so that the TUI retry path works correctly.
    #[test]
    fn test_add_to_queue_retries_error_terminal() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Drive the change to an error terminal state.
        state.apply_execution_event(&ExecutionEvent::ProcessingError {
            id: "c".to_string(),
            error: "apply failed".to_string(),
        });
        assert_eq!(state.display_status("c"), "error");
        assert!(state.is_terminal_change("c"));

        // AddToQueue (retry) must clear the error terminal.
        let outcome = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(
            matches!(outcome, ReduceOutcome::Changed(_)),
            "AddToQueue on error change must be Changed, not NoOp"
        );
        assert_eq!(
            state.display_status("c"),
            "queued",
            "after retry, change must display as queued"
        );
        assert!(
            !state.is_terminal_change("c"),
            "error terminal must be cleared by AddToQueue"
        );
    }

    /// DequeueChange should clear runtime state to a non-terminal not-queued idle state.
    #[test]
    fn test_dequeue_change_resets_to_not_queued_idle() {
        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);

        // Start in queued/active-ish flow, then dequeue.
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        let outcome = state.apply_command(ReducerCommand::DequeueChange("c".to_string()));
        assert!(matches!(outcome, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "not queued");
        assert!(!state.is_terminal_change("c"));

        // Explicit re-queue remains possible only by user action.
        let outcome2 = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(matches!(outcome2, ReduceOutcome::Changed(_)));
        assert_eq!(state.display_status("c"), "queued");
    }

    /// AddToQueue on an Archived change must be a no-op (cannot re-queue a completed change).
    #[test]
    fn test_add_to_queue_noop_on_archived() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_execution_event(&ExecutionEvent::ChangeArchived("c".to_string()));
        assert_eq!(state.display_status("c"), "archived");

        let outcome = state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert!(
            matches!(outcome, ReduceOutcome::NoOp),
            "AddToQueue on archived change must be NoOp"
        );
        assert_eq!(state.display_status("c"), "archived");
    }

    /// After AddToQueue + DependencyBlocked + DependencyResolved, the display must
    /// return to "queued" (queue_intent is preserved through the block/resolve cycle).
    #[test]
    fn test_dependency_resolved_restores_queued_after_block() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert_eq!(state.display_status("c"), "queued");

        state.apply_execution_event(&ExecutionEvent::DependencyBlocked {
            change_id: "c".to_string(),
            dependency_ids: vec!["dep".to_string()],
        });
        assert_eq!(state.display_status("c"), "blocked");

        state.apply_execution_event(&ExecutionEvent::DependencyResolved {
            change_id: "c".to_string(),
        });
        assert_eq!(
            state.display_status("c"),
            "queued",
            "DependencyResolved must restore queued (not not-queued)"
        );
    }

    #[test]
    fn test_dependency_blocked_and_resolved_preserve_queue_intent_until_user_dequeue() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));

        state.apply_execution_event(&ExecutionEvent::DependencyBlocked {
            change_id: "c".to_string(),
            dependency_ids: vec!["dep-a".to_string()],
        });
        assert_eq!(state.display_status("c"), "blocked");

        state.apply_execution_event(&ExecutionEvent::DependencyResolved {
            change_id: "c".to_string(),
        });
        assert_eq!(state.display_status("c"), "queued");

        state.apply_command(ReducerCommand::RemoveFromQueue("c".to_string()));
        assert_eq!(
            state.display_status("c"),
            "not queued",
            "queue intent should only clear on explicit dequeue command"
        );
    }

    /// ChangesRefreshed must not overwrite queue_intent = Queued with "not queued".
    #[test]
    fn test_changes_refreshed_preserves_queue_intent() {
        use crate::events::ExecutionEvent;
        use std::collections::{HashMap, HashSet};

        let mut state = OrchestratorState::new(vec!["c".to_string()], 0);
        state.apply_command(ReducerCommand::AddToQueue("c".to_string()));
        assert_eq!(state.display_status("c"), "queued");

        // Simulate initial parallel ChangesRefreshed with no special observations.
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: HashSet::new(),
            uncommitted_file_change_ids: HashSet::new(),
            worktree_change_ids: HashSet::new(),
            worktree_paths: HashMap::new(),
            worktree_not_ahead_ids: HashSet::new(),
            merge_wait_ids: HashSet::new(),
        });

        assert_eq!(
            state.display_status("c"),
            "queued",
            "ChangesRefreshed must not overwrite queue_intent = Queued"
        );
    }

    /// Fast-forward resolve: terminal Merged set via ResolveCompleted must survive
    /// a subsequent ChangesRefreshed that still reports the workspace as archived
    /// (the workspace scan may lag behind the actual merge).
    #[test]
    fn test_fast_forward_merged_survives_archived_observation() {
        use crate::events::ExecutionEvent;

        let mut state = OrchestratorState::new(vec!["ff".to_string()], 0);

        // Change is archived and deferred to merge wait (manual, not auto-resumable).
        state.apply_execution_event(&ExecutionEvent::MergeDeferred {
            change_id: "ff".to_string(),
            reason: "base dirty".to_string(),
            auto_resumable: false,
        });
        assert_eq!(state.display_status("ff"), "merge wait");

        // Resolve starts.
        state.apply_command(ReducerCommand::ResolveMerge("ff".to_string()));
        assert_eq!(state.display_status("ff"), "resolve pending");
        state.apply_execution_event(&ExecutionEvent::ResolveStarted {
            change_id: "ff".to_string(),
            command: "resolve-cmd".to_string(),
        });
        assert_eq!(state.display_status("ff"), "resolving");

        // Resolve succeeds (fast-forward merge detected by the caller).
        state.apply_execution_event(&ExecutionEvent::ResolveCompleted {
            change_id: "ff".to_string(),
            worktree_change_ids: None,
        });
        assert_eq!(state.display_status("ff"), "merged");

        // Refresh still sees the worktree as archived (workspace scan lag).
        state.apply_execution_event(&ExecutionEvent::ChangesRefreshed {
            changes: vec![],
            committed_change_ids: Default::default(),
            uncommitted_file_change_ids: Default::default(),
            worktree_change_ids: Default::default(),
            worktree_paths: Default::default(),
            worktree_not_ahead_ids: Default::default(),
            merge_wait_ids: ["ff".to_string()].into_iter().collect(),
        });
        assert_eq!(
            state.display_status("ff"),
            "merged",
            "Terminal Merged from fast-forward resolve must not regress to merge wait"
        );
    }
}