r3bl_tui 0.7.7

// Copyright (c) 2025 R3BL LLC. Licensed under Apache License, Version 2.0.

use crate::{Continuation, Controlled, ControlledChild, Controller, ControllerReader,
            ControllerWriter, LINE_FEED_BYTE, PtyCommandBuilder, PtyInputEvent,
            PtyReadWriteOutputEvent, PtyReadWriteSession, READ_BUFFER_SIZE, ok,
            pty_common_io::{create_pty_pair, spawn_command_in_pty}};
use miette::{IntoDiagnostic, miette};
use portable_pty::PtySize;
use std::{io::{Read, Write},
          sync::mpsc::RecvTimeoutError,
          time::Duration};

impl PtyCommandBuilder {
    /// Spawns a read-write PTY session; it spawns three Tokio tasks and one OS child
    /// process with bidirectional communication.
    ///
    /// ```text
    /// ┌──────────────────────────┐ ◄── output ◄── ┌───────────────────────────────┐
    /// │ Your Program             │     events     │ Spawned Task (1) in Read      │
    /// │                          │                │          Write session        │
    /// │                          │ ──► input ───► │               ↓               │
    /// │ a) Handle output events  │     events     │ ◄─── PTY creates pair ──────► │
    /// │    from                  │                │ ┊Controller┊     ┊Controlled┊ │
    /// │ b) Send input events to  │                │     ↓                 ↓       │
    /// │ c) Process completion of │                │ Spawn Tokio       Controlled  │
    /// │ read/write session       │                │ blocking task     spawns      │
    /// │                          │                │ (3) to read       child       │
    /// │                          │                │ from              process (2) │
    /// │                          │                │ Controller and    + Spawn     │
    /// │                          │                │ generate events   bridge      │
    /// │                          │                │ for your program  task (4)    │
    /// │                          │                │                   for input   │
    /// └──────────────────────────┘                └───────────────────────────────┘
    /// ```
    ///
    /// # Why 4 Tasks?
    ///
    /// 1. **Background orchestration task [`tokio::spawn`]** -> Required because this
    ///    function needs to return immediately with a session handle, allowing the caller
    ///    to start processing events and sending input while the PTY command runs in the
    ///    background. Without this, the function would block until the entire PTY session
    ///    completes.
    ///
    /// 2. **OS child process [`ControlledChild`]** -> The actual command being executed
    ///    in the PTY. This is not a Tokio task but a system process that runs your
    ///    command with terminal emulation (the child thinks it is in an interactive
    ///    terminal).
    ///
    /// 3. **Blocking reader task [`spawn_blocking`]** -> Required because PTY file
    ///    descriptors only provide synchronous [`std::io::Read`] APIs, not async
    ///    [`tokio::io::AsyncRead`]. Using regular [`tokio::spawn`] with blocking reads
    ///    would block the entire async runtime. [`spawn_blocking`] runs these synchronous
    ///    reads on a dedicated thread pool.
    ///
    /// 4. **Bridge task [`tokio::spawn`]** -> Unique to read-write mode (the 3 above are
    ///    the same for read-only mode). Converts async input from your program to sync
    ///    channel for the blocking input handler. This enables bidirectional
    ///    communication while maintaining proper async/sync boundaries. The bridge task
    ///    serves as an async-to-sync adapter, necessary because [`mod@portable_pty`] only
    ///    provides synchronous I/O APIs, while the input handler must run in
    ///    [`spawn_blocking`] context to avoid blocking the tokio runtime. Without this
    ///    bridge, async code couldn't send input to the synchronous PTY writer.
    ///
    /// # Design Decisions
    ///
    /// ## Mostly "Dumb Pipes" Approach
    ///
    /// The API treats input and output channels as mostly "dumb pipes" of events, making
    /// minimal assumptions about the child process. The child determines terminal modes
    /// (cooked/raw), interprets environment variables, and handles all terminal-specific
    /// behavior. We primarily provide the transport layer.
    ///
    /// **Exception**: The output reader task performs intelligent cursor mode detection
    /// by scanning for terminal escape sequences (`\x1B[?1h`/`\x1B[?1l`) to automatically
    /// adapt cursor key sequences (Application vs Normal mode). This selective parsing
    /// ensures correct arrow key behavior with applications like htop, while still
    /// passing all data through unchanged to maintain the dumb pipe philosophy. For
    /// details on cursor mode and detection, see
    /// [`mod@crate::pty_core::pty_output_events`].
    ///
    /// ## Single Input Handler Architecture
    ///
    /// A single task owns the [`portable_pty::MasterPty`] and handles all input
    /// operations including resize. This avoids complex synchronization and ensures
    /// clean resource management.
    ///
    /// ## Error Handling
    ///
    /// Write errors terminate the session (no automatic retry). Errors are reported via
    /// [`PtyReadWriteOutputEvent::WriteError`] before termination. Three termination
    /// scenarios:
    /// 1. Child process self-terminates (normal or crash)
    /// 2. Explicit session termination via [`PtyInputEvent::Close`]
    /// 3. Unexpected termination (reported as [`PtyReadWriteOutputEvent::UnexpectedExit`]
    ///    event)
    ///
    /// # Returns
    ///
    /// A session with:
    /// - `input_event_sender_half` for sending input events to the PTY
    /// - `output_event_receiver_half` combined stdout/stderr of child process -> events
    /// - `completion_handle` to await spawned child process completion
    ///
    /// # Example: Interactive shell session with input/output
    ///
    /// ```no_run
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// use r3bl_tui::{PtyCommandBuilder, PtyInputEvent, PtyReadWriteOutputEvent};
    /// use portable_pty::PtySize;
    /// use tokio::time::{sleep, Duration};
    ///
    /// // Start an interactive shell
    /// let mut session = PtyCommandBuilder::new("sh")
    ///     .spawn_read_write(PtySize::default())?;
    ///
    /// // Send commands to the shell
    /// session.input_event_ch_tx_half.send(PtyInputEvent::WriteLine("echo 'Hello from shell'".into()))?;
    /// session.input_event_ch_tx_half.send(PtyInputEvent::WriteLine("date".into()))?;
    /// session.input_event_ch_tx_half.send(PtyInputEvent::WriteLine("exit".into()))?;
    ///
    /// // Process output events
    /// let mut output = Vec::new();
    /// while let Some(event) = session.output_event_receiver_half.recv().await {
    ///     match event {
    ///         PtyReadWriteOutputEvent::Output(data) => {
    ///             output.extend_from_slice(&data);
    ///             print!("{}", String::from_utf8_lossy(&data));
    ///         }
    ///         PtyReadWriteOutputEvent::Exit(status) if status.success() => {
    ///             println!("Shell session completed successfully");
    ///             break;
    ///         }
    ///         PtyReadWriteOutputEvent::Exit(status) => {
    ///             eprintln!("Shell exited with: {:?}", status);
    ///             break;
    ///         }
    ///         PtyReadWriteOutputEvent::WriteError(err) => {
    ///             eprintln!("Write error: {}", err);
    ///             break;
    ///         }
    ///         _ => {}
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if the PTY fails to spawn or initialize properly.
    ///
    /// [`portable_pty::MasterPty`]: portable_pty::MasterPty
    /// [`spawn_blocking`]: tokio::task::spawn_blocking
    /// [`std::io::Read`]: std::io::Read
    /// [`tokio::io::AsyncRead`]: tokio::io::AsyncRead
    /// [`tokio::spawn`]: tokio::spawn
    pub fn spawn_read_write(
        self,
        pty_size: PtySize,
    ) -> miette::Result<PtyReadWriteSession> {
        // 1. Async channel for output from spawned process → your program.
        let (
            /* used by 2 tasks for sending output and error */
            output_evt_ch_tx_half,
            /* return this to your program */ output_evt_ch_rx_half,
        ) = tokio::sync::mpsc::unbounded_channel::<PtyReadWriteOutputEvent>();

        // 2. Async channel for input from your program → spawned process.
        let (
            /* return this to your program */ input_evt_ch_tx_half,
            /* bridge (async side) task relays input events from your program to PTY */
            input_evt_ch_rx_half,
        ) = tokio::sync::mpsc::unbounded_channel::<PtyInputEvent>();

        // Build the command, ensuring CWD is set.
        let command = self.build()?;

        // Create PTY pair: controller (master) for bidirectional I/O, controlled
        // (slave) for spawned process
        let (controller, controlled): (Controller, Controlled) =
            create_pty_pair(pty_size)?;

        // [🛫 SPAWN 1] Spawn the command with PTY (makes is_terminal() return true).
        // The child process uses the controlled side as its stdin/stdout/stderr.
        let mut controlled_child: ControlledChild =
            spawn_command_in_pty(&controlled, command)?;

        // Clone the killer handle before moving the child into the completion task.
        let child_process_terminate_handle = controlled_child.clone_killer();

        // [🛫 SPAWN 0] Spawn the main orchestration task. This is returned to your
        // program, which waits for this to complete.
        let session_completion_handle = tokio::spawn(async move {
            // [🛫 SPAWN 2] Start the passthrough reader task with mode detection for
            // interactive sessions. This directly writes PTY output to stdout
            // for immediate display and detects cursor mode changes.
            // NOTE: Critical resource management - see module docs for PTY lifecycle
            // details.
            let output_reader_task_handle = {
                let controller_reader = controller
                    .try_clone_reader()
                    .map_err(|e| miette!("Failed to clone reader: {}", e))?;
                spawn_blocking_passthrough_with_mode_detection_reader_task(
                    controller_reader,
                    output_evt_ch_tx_half.clone(),
                )
            };

            // [🛫 SPAWN 3 & 4] The input writer task owns the controller and handles all
            // input operations, along with its bridge task for async-to-sync conversion.
            // These two tasks are now encapsulated together.
            let input_writer_task_handle = create_controller_input_writer_task(
                controller,
                input_evt_ch_rx_half,
                output_evt_ch_tx_half.clone(),
            );

            // [🛬 WAIT 1] Wait for the child process to complete.
            let status = tokio::task::spawn_blocking(move || controlled_child.wait())
                .await
                .into_diagnostic()?
                .into_diagnostic()?;

            // Store exit code before moving status.
            let exit_code = status.exit_code();

            // Send exit event.
            let _unused =
                output_evt_ch_tx_half.send(PtyReadWriteOutputEvent::Exit(status));

            // CRITICAL: Drop the controlled half to signal EOF to reader.
            // See module docs for detailed PTY lifecycle management explanation.
            drop(controlled);

            // Wait for all tasks to complete in proper order.
            // [🛬 WAIT 3 & 4] Wait for the input writer task (which includes bridge) to
            // complete.
            let _unused = input_writer_task_handle.await;
            // [🛬 WAIT 2] Wait for the reader task to complete.
            let _unused = output_reader_task_handle.await;

            // Return the exit status.
            Ok(portable_pty::ExitStatus::with_exit_code(exit_code))
        });

        Ok(PtyReadWriteSession {
            input_event_ch_tx_half: input_evt_ch_tx_half,
            output_event_receiver_half: output_evt_ch_rx_half,
            // Pin the completion handle: JoinHandle is not Unpin but select! requires it
            // for efficient polling without moving.
            pinned_boxed_session_completion_handle: Box::pin(session_completion_handle),
            child_process_terminate_handle,
        })
    }
}

/// Creates an input handler task that sends input to the PTY and handles resize.
///
/// Flow: your program → async input channel → this task (bridge + writer) → PTY
///
/// This task:
/// - Reads input commands from a channel
/// - Writes data to the PTY master
/// - Handles control characters and text input
/// - Handles PTY resize commands
/// - Reports write errors through the output event channel, that is sent to your program
///
/// This single task owns the [`MasterPty`] and handles all input operations.
/// It internally spawns both a bridge task (for async-to-sync conversion) and
/// a blocking writer task, returning a combined handle.
///
/// Returns a [`JoinHandle`] for the combined tasks.
///
/// [`JoinHandle`]: tokio::task::JoinHandle
/// [`MasterPty`]: portable_pty::MasterPty
#[must_use]
fn create_controller_input_writer_task(
    controller: Controller,
    /* async */
    input_evt_ch_rx_half: tokio::sync::mpsc::UnboundedReceiver<PtyInputEvent>,
    /* async */
    output_evt_ch_tx_half: tokio::sync::mpsc::UnboundedSender<PtyReadWriteOutputEvent>,
) -> tokio::task::JoinHandle<miette::Result<()>> {
    // Create a sync channel for the input writer task to actually write to PTY
    // (which is sync). The bridge task allows async input channel to perform sync
    // blocking PTY I/O operations via this channel.
    // Flow: (your program) async → bridge → sync channel → writer → PTY (child process).
    let (
        /* Bridge task sends input events from your program (async side) to sync
         * channel */
        input_evt_bridge_sync_tx_half,
        /* Writer task receives input events from sync channel and writes to PTY */
        input_evt_bridge_sync_rx_half,
    ) = std::sync::mpsc::channel::<PtyInputEvent>();

    // [🛫 SPAWN 3] The input writer task owns the controller and handles all
    // input operations. This task writes input from your program to
    // the spawned process via controller.
    let input_writer_task_handle = spawn_blocking_writer_task(
        controller,
        input_evt_bridge_sync_rx_half,
        output_evt_ch_tx_half.clone(),
    );

    // [🛫 SPAWN 4] Spawn a bridge task to convert async input
    // channel to sync channel for input handler. This allows async input from your
    // program to be processed by the blocking input handler.
    let input_writer_bridge_handle = spawn_async_to_sync_bridge_task(
        input_evt_ch_rx_half,
        input_evt_bridge_sync_tx_half,
    );

    // Return combined handle using tokio::join! that waits for both tasks.
    tokio::spawn(async move {
        // [🛬 WAIT 3 & 4] Wait for both the input writer and bridge tasks
        let (_bridge, writer) =
            tokio::join!(input_writer_bridge_handle, input_writer_task_handle);
        writer.map_err(|e| miette!("Input writer task failed: {}", e))?
    })
}

/// Spawns a bridge task to convert async input channel to sync
/// channel.
///
/// Flow: your program → async input channel → this task → sync channel → writer task
///
/// This task:
/// - Reads input events from an async unbounded channel
/// - Forwards them to a sync channel for the blocking writer task
/// - Handles channel closure gracefully
/// - Ensures the writer task receives a Close signal when done
///
/// This bridge enables async input from your program to be processed by
/// the blocking PTY writer task running in [`tokio::task::spawn_blocking`]
/// context. This conversion is necessary because [`portable_pty`] provides
/// only synchronous APIs, not async ones, like our code in this module,
/// while the input must come from async channels.
///
/// Returns a `JoinHandle` for the spawned async task.
///
/// [`portable_pty`]: mod@portable_pty
/// [`tokio::task::spawn_blocking`]: tokio::task::spawn_blocking
#[must_use]
fn spawn_async_to_sync_bridge_task(
    mut input_evt_ch_rx_half: tokio::sync::mpsc::UnboundedReceiver<PtyInputEvent>,
    input_evt_bridge_sync_tx_half: std::sync::mpsc::Sender<PtyInputEvent>,
) -> tokio::task::JoinHandle<()> {
    tokio::spawn(async move {
        while let Some(input) = input_evt_ch_rx_half.recv().await {
            if input_evt_bridge_sync_tx_half.send(input).is_err() {
                // input writer task has exited.
                break;
            }
        }

        // Ensure input handler gets Close signal.
        let _unused = input_evt_bridge_sync_tx_half.send(PtyInputEvent::Close);
    })
}

/// Handles writing input events to the PTY controller in a blocking context.
///
/// Flow: your program → async input channel → bridge task → sync channel → this task →
/// PTY
///
/// This task:
/// - Reads input commands from a sync channel
/// - Writes data to the PTY master using [`tokio::task::spawn_blocking`] because
///   [`portable_pty`] provides only synchronous I/O APIs, not async ones, like our code
///   in this module
/// - Handles control characters and text input
/// - Handles PTY resize commands
/// - Reports write errors through the output event channel, that is sent to your program
///
/// This task owns the `Controller` and handles all input operations in a
/// blocking thread to avoid blocking the async runtime.
///
/// Returns a `JoinHandle` for the spawned blocking task.
///
/// [`portable_pty`]: mod@portable_pty
/// [`tokio::task::spawn_blocking`]: tokio::task::spawn_blocking
#[must_use]
fn spawn_blocking_writer_task(
    controller: Controller,
    input_evt_bridge_sync_rx_half: std::sync::mpsc::Receiver<PtyInputEvent>,
    output_evt_ch_tx_half: tokio::sync::mpsc::UnboundedSender<PtyReadWriteOutputEvent>,
) -> tokio::task::JoinHandle<miette::Result<()>> {
    tokio::task::spawn_blocking(move || -> miette::Result<()> {
        // Get a writer from the controller.
        let mut writer = controller
            .take_writer()
            .map_err(|e| miette!("Failed to take PTY writer: {}", e))?;

        // Process input commands until channel closes or Close command received.
        loop {
            // Use timeout to periodically check if we should exit. If not, the blocking
            // recv() will block indefinitely. The actual exit is handled by the
            // `Err(RecvTimeoutError::Disconnected)` branch.
            match input_evt_bridge_sync_rx_half.recv_timeout(Duration::from_millis(100)) {
                Err(RecvTimeoutError::Disconnected) => {
                    // Channel closed, exit gracefully.
                    break;
                }
                Err(RecvTimeoutError::Timeout) => {
                    // Timeout is normal, continue checking.
                }
                Ok(input) => {
                    match handle_pty_input_event(
                        input,
                        &mut writer,
                        &controller,
                        &output_evt_ch_tx_half,
                    )? {
                        Continuation::Continue => {
                            // Continue processing.
                        }
                        Continuation::Stop => {
                            // Close command received, exit the task.
                            break;
                        }
                    }
                }
            }
        }

        // Controller drops here automatically when the closure ends. So we don't have to
        // explicitly close it (like we do in the read-only code).
        drop(controller);

        Ok(())
    })
}

/// Handles a single PTY input event, writing data and reporting errors as needed.
/// Returns the loop continuation state.
fn handle_pty_input_event(
    input: PtyInputEvent,
    writer: &mut ControllerWriter,
    controller: &Controller,
    output_evt_ch_tx_half: &tokio::sync::mpsc::UnboundedSender<PtyReadWriteOutputEvent>,
) -> miette::Result<Continuation> {
    match input {
        PtyInputEvent::Write(bytes) => write_to_pty_with_flush(
            writer,
            &bytes,
            "Failed to write to PTY",
            output_evt_ch_tx_half,
        )?,
        PtyInputEvent::WriteLine(text) => write_to_pty_with_flush(
            writer,
            &{
                let mut data = text.into_bytes();
                data.push(LINE_FEED_BYTE);
                data
            },
            "Failed to write line to PTY",
            output_evt_ch_tx_half,
        )?,
        PtyInputEvent::SendControl(ctrl, mode) => write_to_pty_with_flush(
            writer,
            &ctrl.to_bytes(mode),
            "Failed to send control char to PTY",
            output_evt_ch_tx_half,
        )?,
        PtyInputEvent::Resize(size) => controller.resize(size).map_err(|e| {
            let _unused = output_evt_ch_tx_half.send(
                PtyReadWriteOutputEvent::WriteError(miette!("Resize failed: {e}")),
            );
            miette!("Failed to resize PTY")
        })?,
        PtyInputEvent::Flush => writer.flush().map_err(|e| {
            let _unused = output_evt_ch_tx_half.send(
                PtyReadWriteOutputEvent::WriteError(miette!("Flush failed: {e}")),
            );
            miette!("Failed to flush PTY")
        })?,
        PtyInputEvent::Close => return Ok(Continuation::Stop),
    }

    Ok(Continuation::Continue)
}

/// Writes data to PTY and flushes, sending error events on failure.
fn write_to_pty_with_flush(
    writer: &mut ControllerWriter,
    data: &[u8],
    error_msg: &str,
    output_evt_ch_tx_half: &tokio::sync::mpsc::UnboundedSender<PtyReadWriteOutputEvent>,
) -> miette::Result<()> {
    writer.write_all(data).map_err(|e| {
        let _unused = output_evt_ch_tx_half.send(PtyReadWriteOutputEvent::WriteError(
            miette!("Write failed: {}", e),
        ));
        miette!("{error_msg}")
    })?;

    writer.flush().map_err(|e| {
        let _unused = output_evt_ch_tx_half.send(PtyReadWriteOutputEvent::WriteError(
            miette!("Flush failed: {}", e),
        ));
        miette!("{error_msg}")
    })?;

    ok!()
}

/// Spawns a blocking task that reads PTY output, detects cursor mode changes, and sends
/// events.
///
/// This is used for read-write sessions to capture output from the PTY while also
/// monitoring for terminal mode switching sequences. The caller is responsible for
/// writing the output to the appropriate device and tracking mode changes.
///
/// Even though we parse the output data for cursor mode changes, we do not consume it,
/// and pass it through to the caller as raw data. When a mode change is detected,
/// we send a separate event indicating the new mode, before the raw data is sent in
/// an event.
///
/// More info about cursor modes (Application vs Normal) and their detection is in
/// [`mod@crate::pty_core::pty_output_events`].
///
/// Mode detection watches for:
/// - `\x1B[?1h` - Enable application cursor keys
/// - `\x1B[?1l` - Disable application cursor keys (back to normal)
fn spawn_blocking_passthrough_with_mode_detection_reader_task(
    mut controller_reader: ControllerReader,
    output_evt_ch_tx_half: tokio::sync::mpsc::UnboundedSender<PtyReadWriteOutputEvent>,
) -> tokio::task::JoinHandle<miette::Result<()>> {
    tokio::task::spawn_blocking(move || -> miette::Result<()> {
        let mut read_buffer = [0u8; READ_BUFFER_SIZE];
        let mut mode_detector =
            crate::pty_core::pty_output_events::CursorModeDetector::new();

        loop {
            // This is a synchronous blocking read operation.
            match controller_reader.read(&mut read_buffer) {
                Ok(0) => {
                    // EOF - PTY closed normally.
                    // We don't have the actual exit status here, just send
                    // UnexpectedExit.
                    let _unused = output_evt_ch_tx_half.send(
                        PtyReadWriteOutputEvent::UnexpectedExit(
                            "PTY closed (EOF)".to_string(),
                        ),
                    );
                    break;
                }
                Err(e) => {
                    // Error reading - PTY closed or error.
                    let _unused = output_evt_ch_tx_half.send(
                        PtyReadWriteOutputEvent::UnexpectedExit(format!(
                            "Read error: {e}"
                        )),
                    );
                    break;
                }
                Ok(n) => {
                    let data = &read_buffer[..n];

                    // Check for cursor mode changes BEFORE sending raw data.
                    if let Some(new_mode) = mode_detector.scan_for_mode_change(data) {
                        let _unused = output_evt_ch_tx_half
                            .send(PtyReadWriteOutputEvent::CursorModeChange(new_mode));
                    }

                    // Always send raw data (dumb pipe philosophy)
                    let _unused = output_evt_ch_tx_half
                        .send(PtyReadWriteOutputEvent::Output(data.to_vec()));
                }
            }
        }

        // Reader drops here automatically when the closure ends.
        drop(controller_reader);

        Ok(())
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{ControlSequence, CursorKeyMode, try_create_temp_dir};
    use tokio::sync::mpsc::unbounded_channel;

    // XMARK: Process isolated test functions using env vars.

    /// This test coordinator runs each PTY read-write test in its own isolated process.
    /// This ensures that PTY resources (file descriptors, child processes, etc.) are
    /// completely isolated between tests, eliminating any potential side effects
    /// or resource contention.
    ///
    /// The issue is that when these tests are run by cargo test (in parallel in the SAME
    /// process), it leads to resource contention and flaky test failures, since PTY
    /// resources are limited per process and tests compete for file descriptors.
    ///
    /// By running each individual test in its own isolated process, we ensure that:
    /// - Each test gets fresh system resources
    /// - No resource leaks from one test can affect others
    /// - File descriptor limits are not shared between tests
    /// - PTY allocation is completely clean for each test
    ///
    /// Note: PTY tests can be flaky in certain environments (CI, containers, etc.)
    /// due to limited PTY resources or system configuration. This is expected behavior.
    #[test]
    fn test_all_pty_read_write_in_isolated_process() {
        // Skip PTY tests in known problematic environments.
        if is_ci::uncached() {
            println!(
                "Skipping PTY tests in CI environment due to PTY resource limitations"
            );
            return;
        }
        // Check if we're running a single specific test.
        if let Ok(test_name) = std::env::var("ISOLATED_PTY_SINGLE_TEST") {
            // This is a single test running in an isolated process.
            run_single_pty_test_by_name(&test_name);
            // If we reach here without errors, exit normally.
            std::process::exit(0);
        }

        // This is the test coordinator - run each test in its own isolated process.
        let tests = vec![
            "test_simple_command_lifecycle",
            "test_cat_with_input",
            #[cfg(not(target_os = "windows"))]
            "test_shell_calculation",
            #[cfg(not(target_os = "windows"))]
            "test_shell_echo_output",
            "test_multiple_control_characters",
            "test_raw_escape_sequences",
            #[cfg(not(target_os = "windows"))]
            "test_htop_interactive_with_cursor_modes",
        ];

        let mut failed_tests = Vec::new();

        for &test_name in &tests {
            println!("Running {test_name} in isolated process...");
            let output = run_single_pty_test_in_isolated_process(test_name);

            let stderr = String::from_utf8_lossy(&output.stderr).to_string();
            let stdout = String::from_utf8_lossy(&output.stdout).to_string();

            if !output.status.success()
                || stderr.contains("panicked at")
                || stderr.contains("Test failed with error")
            {
                failed_tests.push(test_name);
                eprintln!("❌ {test_name} failed:");
                eprintln!("   Exit status: {:?}", output.status);
                eprintln!("   Stdout: {stdout}");
                eprintln!("   Stderr: {stderr}");
            } else {
                println!("✅ {test_name} passed");
            }
        }

        if !failed_tests.is_empty() {
            eprintln!("⚠️  The following PTY tests failed: {failed_tests:?}");
            eprintln!(
                "This may be due to PTY environment limitations in the test environment."
            );
            eprintln!(
                "PTY tests can be sensitive to system resources, configuration, and CI environments."
            );

            // If more than half the tests fail, then there's likely a real issue.
            if failed_tests.len() > tests.len() / 2 {
                panic!(
                    "Too many PTY tests failed ({}/{}). This indicates a serious PTY system issue.",
                    failed_tests.len(),
                    tests.len()
                );
            } else {
                println!(
                    "Continuing despite {} PTY test failures - this is acceptable for environment-sensitive tests.",
                    failed_tests.len()
                );
            }
        }

        // Print success message for visibility.
        println!("All PTY read-write tests completed successfully in isolated processes");
    }

    /// Helper function to run a single PTY test in an isolated process.
    /// Each test gets its own process to avoid any resource sharing or contamination.
    ///
    /// Creates a unique temp directory for each test to ensure complete cwd isolation.
    /// This prevents "No such file or directory" errors when the parent's cwd becomes
    /// invalid during test execution. Uses [`crate::TempDir`] RAII guard for automatic
    /// cleanup.
    fn run_single_pty_test_in_isolated_process(test_name: &str) -> std::process::Output {
        // Create a unique temp directory for this test to ensure cwd isolation.
        // TempDir automatically cleans up on drop (RAII pattern).
        let temp_dir =
            try_create_temp_dir().expect("Failed to create temp dir for PTY test");

        let current_exe = std::env::current_exe().unwrap();
        let mut cmd = std::process::Command::new(&current_exe);
        cmd.current_dir(temp_dir.as_ref())
            .env("ISOLATED_PTY_SINGLE_TEST", test_name)
            .env("RUST_BACKTRACE", "1")
            .args([
                "--test-threads",
                "1",
                "test_all_pty_read_write_in_isolated_process",
            ]);

        // temp_dir is automatically cleaned up when dropped at end of scope.
        cmd.output().expect("Failed to run isolated PTY test")
    }

    /// This function runs a single PTY test based on the environment variable.
    /// This is called when we're in the isolated process mode for a specific test.
    #[allow(clippy::missing_errors_doc)]
    fn run_single_pty_test_by_name(test_name: &str) {
        // Create a Tokio runtime for running the async test.
        let runtime = tokio::runtime::Runtime::new()
            .expect("Failed to create Tokio runtime for PTY test");

        // Run the specific test.
        runtime.block_on(async {
            let result = match test_name {
                "test_simple_command_lifecycle" => test_simple_command_lifecycle().await,
                "test_cat_with_input" => test_cat_with_input().await,
                #[cfg(not(target_os = "windows"))]
                "test_shell_calculation" => test_shell_calculation().await,
                #[cfg(not(target_os = "windows"))]
                "test_shell_echo_output" => test_shell_echo_output().await,
                "test_multiple_control_characters" => {
                    test_multiple_control_characters().await
                }
                "test_raw_escape_sequences" => test_raw_escape_sequences().await,
                #[cfg(not(target_os = "windows"))]
                "test_htop_interactive_with_cursor_modes" => {
                    test_htop_interactive_with_cursor_modes().await
                }
                _ => panic!("Unknown test name: {test_name}"),
            };

            if let Err(e) = result {
                panic!("{test_name} failed: {e}");
            }

            println!("{test_name} completed successfully!");
        });
    }

    async fn test_simple_command_lifecycle() -> miette::Result<()> {
        use tokio::time::timeout;

        // Create a temporary directory for the test.
        let temp_dir = std::env::temp_dir();

        let mut session = PtyCommandBuilder::new("echo")
            .args(["Hello, PTY!"])
            .cwd(temp_dir)
            .spawn_read_write(PtySize::default())
            .unwrap();

        // Give the echo command more time to start and produce output.
        tokio::time::sleep(Duration::from_millis(50)).await;

        let mut output = String::new();
        let mut events_received = Vec::new();
        let mut saw_exit = false;

        // Add timeout to prevent hanging.
        let result = timeout(Duration::from_secs(10), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match &event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        let data_str = String::from_utf8_lossy(data);
                        output.push_str(&data_str);
                        events_received.push(format!(
                            "Output({} bytes): '{}'",
                            data.len(),
                            data_str
                        ));
                    }
                    PtyReadWriteOutputEvent::Exit(status) => {
                        saw_exit = true;
                        events_received.push(format!("Exit({status:?})"));
                        assert!(
                            status.success(),
                            "Command should succeed with status: {status:?}"
                        );
                        break;
                    }
                    other => {
                        events_received.push(format!("{other:?}"));
                    }
                }
            }
        })
        .await;

        assert!(
            result.is_ok(),
            "Test timed out after 10 seconds. Events received: {events_received:?}, Output so far: '{output}'"
        );

        assert!(
            saw_exit,
            "Should see exit event. Events received: {events_received:?}, Output: '{output}'"
        );

        assert!(
            output.contains("Hello, PTY!"),
            "Output should contain 'Hello, PTY!'. Events received: {events_received:?}, Full output was: '{output}'"
        );

        Ok(())
    }

    async fn test_cat_with_input() -> miette::Result<()> {
        use tokio::time::timeout;

        // Create a temporary directory for the test.
        let temp_dir = std::env::temp_dir();

        let mut session = PtyCommandBuilder::new("cat")
            .cwd(temp_dir)
            .spawn_read_write(PtySize::default())
            .unwrap();

        // Send some text
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::WriteLine("test input".into()))
            .unwrap();

        // Send EOF to make cat exit.
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::CtrlD,
                CursorKeyMode::default(),
            ))
            .unwrap();

        let mut output = String::new();
        let mut events_received = Vec::new();
        let mut saw_exit = false;

        let result = timeout(Duration::from_secs(10), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match &event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        let data_str = String::from_utf8_lossy(data);
                        output.push_str(&data_str);
                        events_received.push(format!(
                            "Output({} bytes): '{}'",
                            data.len(),
                            data_str
                        ));
                    }
                    PtyReadWriteOutputEvent::Exit(status) => {
                        saw_exit = true;
                        events_received.push(format!("Exit({status:?})"));
                        assert!(
                            status.success(),
                            "Cat should succeed with status: {status:?}"
                        );
                        break;
                    }
                    other => {
                        events_received.push(format!("{other:?}"));
                    }
                }
            }
        })
        .await;

        assert!(
            result.is_ok(),
            "Test timed out after 10 seconds. Events received: {events_received:?}, Output so far: '{output}'"
        );

        assert!(
            saw_exit,
            "Should see exit event. Events received: {events_received:?}, Output: '{output}'"
        );

        assert!(
            output.contains("test input"),
            "Output should contain 'test input'. Events received: {events_received:?}, Full output was: '{output}'"
        );

        Ok(())
    }

    #[cfg(not(target_os = "windows"))]
    async fn test_shell_calculation() -> miette::Result<()> {
        use tokio::time::timeout;

        // Create a temporary directory for the test.
        let temp_dir = std::env::temp_dir();

        // Use sh for calculation - POSIX compliant and always available on Unix.
        let mut session = PtyCommandBuilder::new("sh")
            .args(["-c", "echo $((2+3)); echo 'Hello from Shell'"])
            .cwd(temp_dir)
            .spawn_read_write(PtySize::default())
            .unwrap();

        // Collect output with timeout.
        let mut output = String::new();
        let mut events_received = Vec::new();
        let mut saw_exit = false;

        let result = timeout(Duration::from_secs(10), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match &event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        let data_str = String::from_utf8_lossy(data);
                        output.push_str(&data_str);
                        events_received.push(format!(
                            "Output({} bytes): '{}'",
                            data.len(),
                            data_str
                        ));
                    }
                    PtyReadWriteOutputEvent::Exit(status) => {
                        saw_exit = true;
                        events_received.push(format!("Exit({status:?})"));
                        break;
                    }
                    other => {
                        events_received.push(format!("{other:?}"));
                    }
                }
            }
        })
        .await;

        assert!(
            result.is_ok(),
            "Shell session timed out after 10 seconds. Events received: {events_received:?}, Output so far: '{output}'"
        );

        assert!(
            saw_exit,
            "Should see exit event. Events received: {events_received:?}, Output: '{output}'"
        );

        // Verify we got expected output.
        assert!(
            output.contains('5'),
            "Should see result of 2+3. Events received: {events_received:?}, Full output was: '{output}'"
        );
        assert!(
            output.contains("Hello from Shell"),
            "Should see hello message. Events received: {events_received:?}, Full output was: '{output}'"
        );

        Ok(())
    }

    #[cfg(not(target_os = "windows"))]
    async fn test_shell_echo_output() -> miette::Result<()> {
        use tokio::time::timeout;

        // Use a more reliable command - use /bin/echo directly instead of shell
        let mut session = PtyCommandBuilder::new("/bin/echo")
            .args(["Test output from echo"])
            .spawn_read_write(PtySize::default())
            .unwrap();

        // Give the command more time to start and produce output.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Collect output
        let mut output = String::new();
        let mut events_received = Vec::new();
        let mut saw_exit = false;

        let result = timeout(Duration::from_secs(10), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match &event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        let data_str = String::from_utf8_lossy(data);
                        output.push_str(&data_str);
                        events_received.push(format!(
                            "Output({} bytes): '{}'",
                            data.len(),
                            data_str
                        ));
                    }
                    PtyReadWriteOutputEvent::Exit(status) => {
                        saw_exit = true;
                        events_received.push(format!("Exit({status:?})"));
                        assert!(
                            status.success(),
                            "Shell should succeed with status: {status:?}"
                        );
                        break;
                    }
                    other => {
                        events_received.push(format!("{other:?}"));
                    }
                }
            }
        })
        .await;

        assert!(
            result.is_ok(),
            "Test timed out after 10 seconds. Events received: {events_received:?}, Output so far: '{output}'"
        );

        assert!(
            saw_exit,
            "Should see exit event. Events received: {events_received:?}, Output: '{output}'"
        );

        assert!(
            output.contains("Test output from echo"),
            "Should see echo output. Events received: {events_received:?}, Full output was: '{output}'"
        );

        Ok(())
    }

    async fn test_multiple_control_characters() -> miette::Result<()> {
        use tokio::time::timeout;

        let mut session = PtyCommandBuilder::new("cat")
            .spawn_read_write(PtySize::default())
            .unwrap();

        // Test various control characters with delays for PTY processing.
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::WriteLine("Test line".into()))
            .unwrap();

        tokio::time::sleep(Duration::from_millis(10)).await;

        // Check if the session is still alive before sending.
        if session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::Enter,
                CursorKeyMode::default(),
            ))
            .is_err()
        {
            // Session ended early, check output.
            let mut output = String::new();
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        output.push_str(&String::from_utf8_lossy(&data));
                    }
                    PtyReadWriteOutputEvent::Exit(status) => {
                        panic!(
                            "PTY exited early with status: {status:?}, output: '{output}'"
                        );
                    }
                    _ => {}
                }
            }
            panic!("Failed to send Enter control character, output so far: '{output}'");
        }

        tokio::time::sleep(Duration::from_millis(10)).await;

        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::Write(b"No newline".to_vec()))
            .unwrap();

        tokio::time::sleep(Duration::from_millis(10)).await;

        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::Tab,
                CursorKeyMode::default(),
            ))
            .unwrap();

        tokio::time::sleep(Duration::from_millis(10)).await;

        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::Write(b"After tab".to_vec()))
            .unwrap();

        tokio::time::sleep(Duration::from_millis(10)).await;

        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::Enter,
                CursorKeyMode::default(),
            ))
            .unwrap();

        // Allow time for all output to be processed before EOF.
        tokio::time::sleep(Duration::from_millis(50)).await;

        // Send EOF to exit.
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::CtrlD,
                CursorKeyMode::default(),
            ))
            .unwrap();

        let mut output = String::new();

        // Add timeout to prevent hanging.
        let result = timeout(Duration::from_secs(5), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        output.push_str(&String::from_utf8_lossy(&data));
                    }
                    PtyReadWriteOutputEvent::Exit(_) => break,
                    _ => {}
                }
            }
        })
        .await;

        assert!(result.is_ok(), "Test timed out. Output: '{output}'");
        assert!(
            output.contains("Test line"),
            "Output should contain 'Test line' but was: '{output}'"
        );
        assert!(
            output.contains("No newline"),
            "Output should contain 'No newline' but was: '{output}'"
        );
        assert!(
            output.contains("After tab"),
            "Output should contain 'After tab' but was: '{output}'"
        );

        Ok(())
    }

    async fn test_raw_escape_sequences() -> miette::Result<()> {
        use tokio::time::timeout;

        // Skip this test in CI environments due to terminal emulation differences.
        if is_ci::uncached() {
            eprintln!("Skipping test_raw_escape_sequences in CI environment");
            return Ok(());
        }

        // Create a temporary directory for the test.
        let temp_dir = std::env::temp_dir();

        let mut session = PtyCommandBuilder::new("cat")
            .cwd(temp_dir)
            .spawn_read_write(PtySize::default())
            .unwrap();

        // Send some text with ANSI color codes using raw sequences.
        let red_text = b"\x1b[31mRed Text\x1b[0m";
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::Write(red_text.to_vec()))
            .unwrap();
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::Enter,
                CursorKeyMode::default(),
            ))
            .unwrap();

        // Add a delay to ensure the first line is processed.
        tokio::time::sleep(Duration::from_millis(50)).await;

        // Send using RawSequence variant.
        let blue_seq = vec![0x1b, b'[', b'3', b'4', b'm']; // Blue color
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::RawSequence(blue_seq),
                CursorKeyMode::default(),
            ))
            .unwrap();
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::Write(b"Blue Text".to_vec()))
            .unwrap();

        // Send reset sequence after blue text.
        let reset_seq = vec![0x1b, b'[', b'0', b'm']; // Reset color
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::RawSequence(reset_seq),
                CursorKeyMode::default(),
            ))
            .unwrap();

        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::Enter,
                CursorKeyMode::default(),
            ))
            .unwrap();

        // Add a delay to ensure all input is processed before EOF.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // EOF to exit
        session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::CtrlD,
                CursorKeyMode::default(),
            ))
            .unwrap();

        let mut output = Vec::new();
        let mut events_received = Vec::new();
        let mut saw_exit = false;

        let result = timeout(Duration::from_secs(10), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                match &event {
                    PtyReadWriteOutputEvent::Output(data) => {
                        output.extend_from_slice(data);
                        events_received.push(format!("Output({} bytes)", data.len()));
                    }
                    PtyReadWriteOutputEvent::Exit(status) => {
                        saw_exit = true;
                        events_received.push(format!("Exit({status:?})"));
                        break;
                    }
                    other => {
                        events_received.push(format!("{other:?}"));
                    }
                }
            }
        })
        .await;

        let output_str = String::from_utf8_lossy(&output);

        assert!(
            result.is_ok(),
            "Test timed out after 10 seconds. Events received: {events_received:?}, Output so far: '{output_str}'"
        );

        assert!(
            saw_exit,
            "Should see exit event. Events received: {events_received:?}, Output: '{output_str}'"
        );

        // Check we got the ANSI sequences back.
        assert!(
            output_str.contains("Red Text"),
            "Output should contain 'Red Text'. Events received: {events_received:?}, Full output was: '{output_str}'"
        );
        assert!(
            output_str.contains("Blue Text"),
            "Output should contain 'Blue Text'. Events received: {events_received:?}, Full output was: '{output_str}'"
        );
        // The actual ANSI codes might be echoed back.
        // Note: cat may not preserve exact ANSI sequences depending on terminal settings.

        Ok(())
    }

    /// Comprehensive integration test for PTY input events using htop as a real
    /// interactive application.
    ///
    /// This test validates the new `ControlSequence` + `CursorKeyMode` architecture by
    /// interacting with htop, ensuring that PTY input events are properly translated
    /// to terminal sequences and that the application responds correctly.
    ///
    /// ## Test Flow
    ///
    /// **Initialization:**
    /// - Checks htop installation (fails hard if missing)
    /// - Launches htop with `--delay 100` (10-second auto-refresh to prevent
    ///   interference)
    /// - Waits 1 second for htop to fully initialize and display process list
    ///
    /// **Phase 1 - Baseline Capture:**
    /// - Input: None (capture initial htop display)
    /// - Expected: Process list with system information, highlighted selection row
    /// - Validation: Asserts substantial output indicating htop is running
    ///
    /// **Phase 2 - Arrow Navigation:**
    /// - Input: `ControlSequence::ArrowDown` with `CursorKeyMode::Normal`
    /// - Expected: Selection moves to next process in list (visual highlight changes)
    /// - Validation: Asserts output changed after arrow key, indicating UI response
    ///
    /// **Phase 3 - Screen Refresh:**
    /// - Input: `ControlSequence::CtrlL` (Ctrl+L)
    /// - Expected: Screen clears and redraws with current process state
    /// - Validation: Asserts new output received after Ctrl+L, confirming refresh
    ///
    /// **Phase 4 - Cursor Mode Compatibility:**
    /// - Input: `ControlSequence::ArrowUp` in both `CursorKeyMode::Normal` and
    ///   `Application`
    /// - Expected: htop handles both terminal cursor modes correctly without errors
    /// - Validation: Asserts commands were sent successfully in both modes
    ///
    /// **Phase 5 - Function Key Testing:**
    /// - Input: `ControlSequence::F(2)` (F2 key - Setup menu)
    /// - Expected: htop opens Setup/Configuration menu with different display containing
    ///   setup options
    /// - Validation: Asserts setup menu content differs from normal display and contains
    ///   expected keywords
    ///
    /// **Phase 6 - Graceful Exit:**
    /// - Input: `q` (quit command) followed by optional `ControlSequence::CtrlC` if
    ///   needed
    /// - Expected: htop exits cleanly with status 0
    /// - Validation: Asserts process terminates within timeout
    ///
    /// ## Key Features Tested
    ///
    /// - **Control sequence generation**: Validates that `ControlSequence` enum properly
    ///   generates terminal escape sequences
    /// - **Cursor mode handling**: Tests compatibility between `CursorKeyMode::Normal`
    ///   and `Application` modes
    /// - **Function key support**: Tests F2 key handling and menu navigation
    /// - **Real application interaction**: Uses htop's actual UI behavior instead of
    ///   synthetic test cases
    /// - **Timeout resilience**: All operations have strict timeouts to prevent test
    ///   hangs
    /// - **Cross-platform support**: Linux/macOS only (Windows has no htop equivalent)
    ///
    /// ## Environment Requirements
    ///
    /// - htop must be installed (bootstrap.sh handles this automatically)
    /// - Test fails hard if htop missing (not skipped) to ensure proper CI setup
    /// - Requires PTY support (not available in all containerized environments)
    #[cfg(not(target_os = "windows"))] // Linux and macOS only
    #[allow(clippy::too_many_lines)]
    async fn test_htop_interactive_with_cursor_modes() -> miette::Result<()> {
        use std::process::Command;
        use tokio::time::timeout;

        println!("Starting htop integration test...");

        // Check if htop is installed - FAIL if not installed.
        let htop_check = Command::new("which")
            .arg("htop")
            .output()
            .expect("Failed to check for htop");

        assert!(
            htop_check.status.success(),
            "htop is required for this test but is not installed!\n\
                 Please install htop:\n\
                 - Linux: Use your package manager (apt, dnf, pacman, etc.)\n\
                 - macOS: brew install htop\n\
                 - Or run: ./bootstrap.sh"
        );

        println!("htop found, launching with 10-second refresh delay...");

        // Launch htop with 10-second refresh delay (100 tenths = 10 seconds)
        let mut session = timeout(Duration::from_secs(5), async {
            PtyCommandBuilder::new("htop")
                .args(["--delay", "100"])
                .spawn_read_write(PtySize::default())
        })
        .await
        .map_err(|_| miette::miette!("Timeout launching htop"))?
        .unwrap();

        println!("htop launched successfully, waiting for initialization...");

        // Wait for htop to fully initialize with timeout.
        tokio::time::sleep(Duration::from_millis(1000)).await;

        // Phase 1: Capture initial output - ASSERT htop is running properly
        println!("Phase 1: Capturing initial htop display...");
        let initial_output = timeout(Duration::from_secs(2), async {
            capture_output_snapshot(&mut session, Duration::from_millis(500)).await
        })
        .await
        .map_err(|_| miette::miette!("Timeout capturing initial output"))?
        .unwrap_or_else(|_| String::new());

        println!("Initial output captured: {} chars", initial_output.len());

        // Phase 1 Assertion: Verify htop is actually running and showing process data
        assert!(
            initial_output.len() > 200,
            "htop should display substantial process information. Got {} chars: {}",
            initial_output.len(),
            initial_output.chars().take(100).collect::<String>()
        );

        // Look for typical htop content indicators.
        let htop_indicators = initial_output.contains("Tasks:")
            || initial_output.contains("Load average:")
            || initial_output.contains("Memory:")
            || initial_output.contains("PID")
            || initial_output.contains("CPU%")
            || initial_output.len() > 500; // Large output suggests active display

        assert!(
            htop_indicators,
            "htop should display typical process manager content (Tasks, Load average, Memory, PID, CPU%). \
             First 200 chars: {}",
            initial_output.chars().take(200).collect::<String>()
        );

        // Phase 2: Test arrow down navigation - ASSERT UI changes
        println!("Phase 2: Testing arrow down navigation...");
        let send_result =
            session
                .input_event_ch_tx_half
                .send(PtyInputEvent::SendControl(
                    ControlSequence::ArrowDown,
                    CursorKeyMode::Normal,
                ));

        assert!(send_result.is_ok(), "Failed to send arrow down key");

        // Brief wait for UI response.
        tokio::time::sleep(Duration::from_millis(300)).await;

        let after_arrow = timeout(Duration::from_secs(2), async {
            capture_output_snapshot(&mut session, Duration::from_millis(500)).await
        })
        .await
        .map_err(|_| miette::miette!("Timeout capturing post-arrow output"))?
        .unwrap_or_else(|_| String::new());

        println!("Post-arrow output captured: {} chars", after_arrow.len());

        // Phase 2 Assertion: Verify arrow key caused UI change
        assert!(
            after_arrow.len() > 100
                && (after_arrow != initial_output
                    || after_arrow.len() != initial_output.len()),
            "Arrow down should cause visible UI change in htop. \
             Initial: {} chars, After arrow: {} chars",
            initial_output.len(),
            after_arrow.len()
        );

        // Phase 3: Test Ctrl+L screen refresh - ASSERT screen redraw occurs
        println!("Phase 3: Testing Ctrl+L screen refresh...");
        let ctrl_l_result =
            session
                .input_event_ch_tx_half
                .send(PtyInputEvent::SendControl(
                    ControlSequence::CtrlL,
                    CursorKeyMode::default(),
                ));

        assert!(ctrl_l_result.is_ok(), "Failed to send Ctrl+L");

        tokio::time::sleep(Duration::from_millis(300)).await;

        let after_ctrl_l = timeout(Duration::from_secs(2), async {
            capture_output_snapshot(&mut session, Duration::from_millis(400)).await
        })
        .await
        .map_err(|_| miette::miette!("Timeout capturing post-Ctrl+L output"))?
        .unwrap_or_else(|_| String::new());

        // Phase 3 Assertion: Verify Ctrl+L caused screen refresh
        assert!(
            after_ctrl_l.len() > 100,
            "Ctrl+L should trigger screen redraw with substantial output. Got {} chars",
            after_ctrl_l.len()
        );

        // Phase 4: Test cursor mode compatibility - ASSERT both modes work
        println!("Phase 4: Testing cursor mode compatibility...");
        let mut mode_success_count = 0;

        for (mode, mode_name) in [
            (CursorKeyMode::Normal, "Normal"),
            (CursorKeyMode::Application, "Application"),
        ] {
            let arrow_result = session
                .input_event_ch_tx_half
                .send(PtyInputEvent::SendControl(ControlSequence::ArrowUp, mode));

            if arrow_result.is_ok() {
                mode_success_count += 1;
                println!("✓ Arrow key sent successfully in {mode_name} mode");
            } else {
                println!("✗ Failed to send arrow key in {mode_name} mode");
            }

            tokio::time::sleep(Duration::from_millis(50)).await;
        }

        // Phase 4 Assertion: Verify both cursor modes work
        assert_eq!(
            mode_success_count, 2,
            "Both cursor modes (Normal and Application) should work. Only {mode_success_count} succeeded"
        );

        // Capture baseline before F2 for comparison.
        println!("Capturing normal display before F2...");
        let before_f2 = timeout(Duration::from_secs(2), async {
            capture_output_snapshot(&mut session, Duration::from_millis(300)).await
        })
        .await
        .map_err(|_| miette::miette!("Timeout capturing pre-F2 output"))?
        .unwrap_or_else(|_| String::new());

        // Phase 5: Test F2 setup menu - ASSERT menu actually opens
        println!("Phase 5: Testing F2 key (Setup menu)...");
        let f2_result = session
            .input_event_ch_tx_half
            .send(PtyInputEvent::SendControl(
                ControlSequence::F(2),
                CursorKeyMode::default(),
            ));

        assert!(f2_result.is_ok(), "Failed to send F2 key");

        // Wait for setup menu to appear.
        tokio::time::sleep(Duration::from_millis(400)).await;

        let setup_output = timeout(Duration::from_secs(2), async {
            capture_output_snapshot(&mut session, Duration::from_millis(500)).await
        })
        .await
        .map_err(|_| miette::miette!("Timeout capturing setup menu output"))?
        .unwrap_or_else(|_| String::new());

        println!("Setup menu output captured: {} chars", setup_output.len());

        // Phase 5 Assertion: Verify F2 opened setup menu with different content
        let setup_menu_appeared = setup_output != before_f2
            && (setup_output.contains("Setup")
                || setup_output.contains("Meters")
                || setup_output.contains("Display")
                || setup_output.contains("Colors")
                || setup_output.contains("Columns")
                || (!setup_output.is_empty() && setup_output.len() != before_f2.len()));

        assert!(
            setup_menu_appeared,
            "F2 key should open setup menu with different content than normal display.\n\
             Before F2: {} chars, Setup menu: {} chars\n\
             Setup contains expected keywords: {}\n\
             First 200 chars of setup output: {}",
            before_f2.len(),
            setup_output.len(),
            setup_output.contains("Setup")
                || setup_output.contains("Meters")
                || setup_output.contains("Display"),
            setup_output.chars().take(200).collect::<String>()
        );

        // Exit setup menu with Escape.
        println!("Exiting setup menu with Escape...");
        let escape_result =
            session
                .input_event_ch_tx_half
                .send(PtyInputEvent::SendControl(
                    ControlSequence::Escape,
                    CursorKeyMode::default(),
                ));

        assert!(escape_result.is_ok(), "Failed to send Escape key");
        tokio::time::sleep(Duration::from_millis(200)).await;

        // Phase 6: Graceful shutdown - ASSERT clean exit
        println!("Phase 6: Testing graceful shutdown...");

        let quit_result = session
            .input_event_ch_tx_half
            .send(PtyInputEvent::Write(b"q".to_vec()));

        assert!(quit_result.is_ok(), "Failed to send quit command");

        // Wait for exit with timeout.
        let exit_result = timeout(Duration::from_secs(2), async {
            while let Some(event) = session.output_event_receiver_half.recv().await {
                if let PtyReadWriteOutputEvent::Exit(status) = event {
                    return Ok(status);
                }
            }
            Err(miette::miette!("No exit event received"))
        })
        .await;

        // Phase 6 Assertion: Verify htop exited properly or handle timeout gracefully
        match exit_result {
            Ok(Ok(status)) => {
                println!("✓ htop exited cleanly with status: {status:?}");
                // For most cases, htop should exit with success.
                if !status.success() {
                    println!(
                        "⚠ htop exited with non-zero status, but this may be acceptable in test environments"
                    );
                }
            }
            Ok(Err(_)) | Err(_) => {
                println!(
                    "⚠ htop did not exit gracefully within timeout - applying force termination"
                );
                // Try Ctrl+C as fallback.
                let ctrl_c_result =
                    session
                        .input_event_ch_tx_half
                        .send(PtyInputEvent::SendControl(
                            ControlSequence::CtrlC,
                            CursorKeyMode::default(),
                        ));

                if ctrl_c_result.is_ok() {
                    tokio::time::sleep(Duration::from_millis(100)).await;
                    println!("✓ Sent Ctrl+C as fallback termination");
                } else {
                    println!("⚠ Failed to send Ctrl+C fallback - process may be hung");
                }
            }
        }

        // Final validation - ensure all phases produced meaningful output.
        println!("All phases completed - validating overall test success...");

        assert!(
            initial_output.len() > 200
                || after_arrow.len() > 200
                || setup_output.len() > 50,
            "Expected substantial output from at least one phase. \
             Initial: {} chars, After arrow: {} chars, Setup menu: {} chars",
            initial_output.len(),
            after_arrow.len(),
            setup_output.len()
        );

        println!("✅ htop integration test completed successfully!");
        Ok(())
    }

    /// Capture output snapshot without consuming all events
    async fn capture_output_snapshot(
        session: &mut PtyReadWriteSession,
        timeout_duration: Duration,
    ) -> miette::Result<String> {
        let mut output = String::new();
        let deadline = tokio::time::Instant::now() + timeout_duration;

        while tokio::time::Instant::now() < deadline {
            tokio::select! {
                Some(event) = session.output_event_receiver_half.recv() => {
                    if let PtyReadWriteOutputEvent::Output(data) = event {
                        output.push_str(&String::from_utf8_lossy(&data));
                    }
                }
                () = tokio::time::sleep_until(deadline) => break,
            }
        }

        Ok(output)
    }

    // XMARK: Input handler task tests.

    #[tokio::test]
    async fn test_create_input_handler_task_write() {
        let (controller, _controlled) = create_pty_pair(PtySize::default()).unwrap();

        let (input_sender, input_receiver) = unbounded_channel();
        let (event_sender, _event_receiver) = unbounded_channel();

        let handle =
            create_controller_input_writer_task(controller, input_receiver, event_sender);

        // Send write command.
        let test_data = b"test input";
        input_sender
            .send(PtyInputEvent::Write(test_data.to_vec()))
            .unwrap();

        // Send close to terminate task.
        input_sender.send(PtyInputEvent::Close).unwrap();

        // Give a bit of time for the close event to be processed.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Drop sender to close the channel.
        drop(input_sender);

        // Task should complete successfully.
        let result = tokio::time::timeout(Duration::from_millis(2000), handle).await;
        assert!(result.is_ok(), "Task timed out");
    }

    #[tokio::test]
    async fn test_create_input_handler_task_write_line() {
        let (controller, _controlled) = create_pty_pair(PtySize::default()).unwrap();

        let (input_sender, input_receiver) = unbounded_channel();
        let (event_sender, _event_receiver) = unbounded_channel();

        let handle =
            create_controller_input_writer_task(controller, input_receiver, event_sender);

        // Send write line command.
        input_sender
            .send(PtyInputEvent::WriteLine("test line".to_string()))
            .unwrap();

        // Send close to terminate task.
        input_sender.send(PtyInputEvent::Close).unwrap();

        // Give a bit of time for the close event to be processed.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Drop sender to close the channel.
        drop(input_sender);

        // Task should complete successfully.
        let result = tokio::time::timeout(Duration::from_millis(2000), handle).await;
        assert!(result.is_ok(), "Task timed out");
    }

    #[tokio::test]
    async fn test_create_input_handler_task_control_char() {
        let (controller, _controlled) = create_pty_pair(PtySize::default()).unwrap();

        let (input_sender, input_receiver) = unbounded_channel();
        let (event_sender, _event_receiver) = unbounded_channel();

        let handle =
            create_controller_input_writer_task(controller, input_receiver, event_sender);

        // Send control character.
        input_sender
            .send(PtyInputEvent::SendControl(
                ControlSequence::CtrlC,
                CursorKeyMode::default(),
            ))
            .unwrap();

        // Send close to terminate task.
        input_sender.send(PtyInputEvent::Close).unwrap();

        // Give a bit of time for the close event to be processed.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Drop sender to close the channel.
        drop(input_sender);

        // Task should complete successfully.
        let result = tokio::time::timeout(Duration::from_millis(2000), handle).await;
        assert!(result.is_ok(), "Task timed out");
    }

    #[tokio::test]
    async fn test_create_input_handler_task_resize() {
        let (controller, _controlled) = create_pty_pair(PtySize::default()).unwrap();

        let (input_sender, input_receiver) = unbounded_channel();
        let (event_sender, _event_receiver) = unbounded_channel();

        let handle =
            create_controller_input_writer_task(controller, input_receiver, event_sender);

        // Send resize command.
        let new_size = PtySize {
            rows: 40,
            cols: 120,
            pixel_width: 0,
            pixel_height: 0,
        };
        input_sender.send(PtyInputEvent::Resize(new_size)).unwrap();

        // Send close to terminate task.
        input_sender.send(PtyInputEvent::Close).unwrap();

        // Give a bit of time for the close event to be processed.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Drop sender to close the channel.
        drop(input_sender);

        // Task should complete successfully.
        let result = tokio::time::timeout(Duration::from_millis(2000), handle).await;
        assert!(result.is_ok(), "Task timed out");
    }

    #[tokio::test]
    async fn test_create_input_handler_task_flush() {
        let (controller, _controlled) = create_pty_pair(PtySize::default()).unwrap();

        let (input_sender, input_receiver) = unbounded_channel();
        let (event_sender, _event_receiver) = unbounded_channel();

        let handle =
            create_controller_input_writer_task(controller, input_receiver, event_sender);

        // Send flush command.
        input_sender.send(PtyInputEvent::Flush).unwrap();

        // Send close to terminate task.
        input_sender.send(PtyInputEvent::Close).unwrap();

        // Give a bit of time for the close event to be processed.
        tokio::time::sleep(Duration::from_millis(100)).await;

        // Drop sender to close the channel.
        drop(input_sender);

        // Task should complete successfully.
        let result = tokio::time::timeout(Duration::from_millis(2000), handle).await;
        assert!(result.is_ok(), "Task timed out");
    }

    #[tokio::test]
    async fn test_create_input_handler_task_channel_disconnect() {
        let (controller, _controlled) = create_pty_pair(PtySize::default()).unwrap();

        let (input_sender, input_receiver) = unbounded_channel();
        let (event_sender, _event_receiver) = unbounded_channel();

        let handle =
            create_controller_input_writer_task(controller, input_receiver, event_sender);

        // Drop sender to disconnect channel.
        drop(input_sender);

        // Task should complete successfully when channel disconnects.
        let result = tokio::time::timeout(Duration::from_millis(500), handle).await;
        assert!(result.is_ok());
    }
}