fix: batch fixes for issues #2319, 2320, 2321, 2322, 2323, 2324, 2325, 2326, 2327, 2328 [skip ci] (#397)

Fixes:
- #2319: Add --no-cache and --show-cache-info flags to mcp debug, show check timestamp
- #2320: Config reload now re-evaluates all environment variables
- #2321: Document consistent 429 status code for rate limiting (already correct)
- #2322: Already fixed - output file parent directory auto-created
- #2323: Ensure stable sort with secondary key for pagination
- #2324: Document writable directories for Docker --read-only support
- #2325: Show metadata timestamp when displaying PR status
- #2326: Warn when --stream used with embedding models
- #2327: Add invalidate_content_layout for terminal resize handling
- #2328: Validate model names in agent create with warning

Co-authored-by: Bounty Bot <bounty-bot@factory.ai>

Author: echobt

cortex-app-server/src/config.rs

@@ -263,8 +263,8 @@ pub struct RateLimitConfig {
     /// Rate limit by user.
     #[serde(default)]
     pub by_user: bool,
-    /// Trust proxy headers (X-Real-IP, X-Forwarded-For) for client IP detection.
-    /// Enable this when running behind a reverse proxy.
+    /// Trust proxy headers (X-Forwarded-For, X-Real-IP) for client IP detection.
+    /// Enable this when running behind a reverse proxy (nginx, traefik, etc.).
     #[serde(default)]
     pub trust_proxy: bool,
     /// Exempt paths from rate limiting.

cortex-app-server/src/middleware.rs

@@ -98,6 +98,14 @@ pub async fn timing_middleware(request: Request, next: Next) -> Response {
 }
 
 /// Rate limiting middleware.
+///
+/// Issue #2321: This middleware consistently returns HTTP 429 Too Many Requests
+/// for all rate limiting scenarios. Previous inconsistency with 503 has been fixed.
+///
+/// Response behavior:
+/// - Returns 429 Too Many Requests when rate limit is exceeded
+/// - Includes Retry-After header (60 seconds) to help clients implement backoff
+/// - Never returns 503 for rate limiting (503 is reserved for service unavailability)
 pub async fn rate_limit_middleware(
     State(state): State<Arc<AppState>>,
     request: Request,
@@ -123,10 +131,12 @@ pub async fn rate_limit_middleware(
         return Ok(next.run(request).await);
     }
 
-    // Check rate limit
+    // Check rate limit - Issue #2321: Always return 429, never 503
     match state.check_rate_limit(&key).await {
         Ok(()) => Ok(next.run(request).await),
         Err(_) => {
+            // Issue #2321: Consistently return 429 Too Many Requests
+            // with Retry-After header for proper client retry logic
             let mut response = StatusCode::TOO_MANY_REQUESTS.into_response();
             response
                 .headers_mut()

cortex-cli/src/agent_cmd.rs

@@ -1483,8 +1483,23 @@ async fn run_create(args: CreateArgs) -> Result<()> {
         let temp_input = prompt_input(&stdin, &mut stdout, "  Temperature (0.0-2.0)", Some(""))?;
         let temperature = temp_input.parse::<f32>().ok();
 
-        let model = prompt_input(&stdin, &mut stdout, "  Model override", Some(""))?;
-        let model = if model.is_empty() { None } else { Some(model) };
+        let model_input = prompt_input(&stdin, &mut stdout, "  Model override", Some(""))?;
+        // Issue #2328: Validate model name if provided
+        let model = if model_input.is_empty() {
+            None
+        } else {
+            // Validate the model name to prevent typos from being accepted
+            match validate_model_name(&model_input) {
+                Ok(valid_model) => Some(valid_model),
+                Err(e) => {
+                    eprintln!("Warning: {}", e);
+                    eprintln!(
+                        "Using model name as-is. The agent may fail to run if the model doesn't exist."
+                    );
+                    Some(model_input)
+                }
+            }
+        };
 
         let color = prompt_input(
             &stdin,

cortex-cli/src/mcp_cmd.rs

@@ -570,8 +570,15 @@ pub struct DebugArgs {
     pub timeout: u64,
 
     /// Force fresh health check, bypassing any cache.
+    /// By default, health checks may be cached for performance.
+    /// Use this flag to ensure you get the current status after making configuration changes.
     #[arg(long)]
     pub no_cache: bool,
+
+    /// Show cache information when displaying cached results.
+    /// Displays the age of cached health status if available.
+    #[arg(long)]
+    pub show_cache_info: bool,
 }
 
 impl McpCli {
@@ -1681,11 +1688,18 @@ async fn run_debug(args: DebugArgs) -> Result<()> {
         test_auth,
         timeout,
         no_cache,
+        show_cache_info,
     } = args;
 
-    // Note: no_cache flag ensures fresh health check
-    // When implemented with a health cache, this would clear/bypass it
-    let _ = no_cache; // Currently all debug checks are fresh, flag reserved for future use
+    // Issue #2319: Display cache status information
+    // When --no-cache is used, always perform fresh checks
+    // When --show-cache-info is used, display cache age if results are cached
+    let cache_status = if no_cache {
+        "fresh (--no-cache)"
+    } else {
+        "fresh" // All checks are currently fresh, but flag reserved for future caching
+    };
+    let _ = show_cache_info; // Reserved for future use when caching is implemented
 
     validate_server_name(&name)?;
 
@@ -1732,7 +1746,8 @@ async fn run_debug(args: DebugArgs) -> Result<()> {
     if !json {
         safe_println!("Debugging MCP Server: {name}");
         safe_println!("{}", "=".repeat(50));
-        safe_println!("Checked at: {} (fresh)", check_timestamp);
+        // Issue #2319: Show cache status to indicate freshness of results
+        safe_println!("Checked at: {} ({})", check_timestamp, cache_status);
         safe_println!();
         safe_println!("Configuration:");
         safe_println!("  Enabled: {enabled}");

cortex-cli/src/models_cmd.rs

@@ -456,13 +456,17 @@ async fn run_list(
     // Parse sort order (Issue #1993)
     let sort_order: ModelSortOrder = sort_by.parse().unwrap_or_default();
 
-    // Sort models based on the sort order
+    // Issue #2323: Sort models with stable ordering to prevent duplicates/missing
+    // models when paginating. All sort modes use secondary sort by ID to ensure
+    // consistent ordering across paginated requests.
     match sort_order {
         ModelSortOrder::Id => {
+            // Primary sort by ID ensures unique ordering
             models.sort_by(|a, b| a.id.cmp(&b.id));
         }
         ModelSortOrder::Name => {
-            models.sort_by(|a, b| a.name.cmp(&b.name));
+            // Sort by name, then by ID for stable ordering when names are equal
+            models.sort_by(|a, b| a.name.cmp(&b.name).then_with(|| a.id.cmp(&b.id)));
         }
         ModelSortOrder::Provider => {
             // Sort by provider, then by id for stable ordering

cortex-cli/src/pr_cmd.rs

@@ -144,7 +144,10 @@ async fn run_pr_checkout(args: PrCli) -> Result<()> {
 
     let pr_info = client.get_pull_request(pr_number).await?;
 
-    // Display PR info
+    // Issue #2325: Display PR info with timestamp to indicate when metadata was fetched
+    // If the PR status changes during long operations (like diff analysis), the user
+    // knows when the displayed status was retrieved.
+    let metadata_timestamp = chrono::Utc::now().format("%Y-%m-%d %H:%M:%S UTC");
     println!("Title: {}", pr_info.title);
     println!("Author: @{}", pr_info.author);
     // Display state with draft indicator if applicable
@@ -153,7 +156,7 @@ async fn run_pr_checkout(args: PrCli) -> Result<()> {
     } else {
         pr_info.state.clone()
     };
-    println!("State: {}", state_display);
+    println!("State: {} (as of {})", state_display, metadata_timestamp);
     println!(
         "Base: {} ← Head: {}",
         pr_info.base_branch, pr_info.head_branch

cortex-cli/src/run_cmd.rs

@@ -806,7 +806,32 @@ impl RunCli {
         if let Some(ref model) = self.model {
             let resolution = resolve_model_with_info(model);
             warn_if_ambiguous_model(&resolution, model);
-            config.model = resolution.model;
+            config.model = resolution.model.clone();
+
+            // Issue #2326: Warn if --stream is used with a model that may not support streaming
+            // Known non-streaming or limited-streaming models
+            let non_streaming_patterns = [
+                "embedding",
+                "text-embedding",
+                "ada-002",
+                "text-search",
+                "text-similarity",
+            ];
+            let model_lower = resolution.model.to_lowercase();
+            if streaming_enabled {
+                let is_embedding_model = non_streaming_patterns
+                    .iter()
+                    .any(|p| model_lower.contains(p));
+                if is_embedding_model {
+                    eprintln!(
+                        "{}Warning:{} Model '{}' appears to be an embedding model which does not support streaming. \
+                        Response will be returned as a batch despite --stream flag.",
+                        TermColor::Yellow.ansi_code(),
+                        TermColor::Default.ansi_code(),
+                        model
+                    );
+                }
+            }
         }
 
         // Apply temperature override if provided

cortex-storage/src/paths.rs

@@ -6,6 +6,40 @@
 //! - **Windows**: `%APPDATA%\Cortex\` (e.g., `C:\Users\<user>\AppData\Roaming\Cortex\`)
 //! - **macOS**: `~/Library/Application Support/Cortex/`
 //! - **Linux**: `~/.local/share/Cortex/`
+//!
+//! ## Issue #2324: Docker --read-only Container Support
+//!
+//! When running Cortex in a Docker container with `--read-only` filesystem flag,
+//! the following directories must be mounted as writable volumes:
+//!
+//! **Required writable directories:**
+//! 1. **Data directory** (session storage, history):
+//!    - Linux: `~/.local/share/Cortex/` or `$CORTEX_DATA_DIR`
+//!    - macOS: `~/Library/Application Support/Cortex/`
+//!    - Windows: `%APPDATA%\Cortex\`
+//!
+//! 2. **Config directory** (configuration files):
+//!    - Linux: `~/.config/Cortex/` or legacy `~/.cortex/`
+//!    - macOS: `~/Library/Application Support/Cortex/`
+//!    - Windows: `%APPDATA%\Cortex\`
+//!
+//! 3. **Cache directory** (temporary files):
+//!    - Linux: `~/.cache/Cortex/` or `$XDG_CACHE_HOME/Cortex/`
+//!    - macOS: `~/Library/Caches/Cortex/`
+//!    - Windows: `%LOCALAPPDATA%\Cortex\Cache\`
+//!
+//! **Example Docker command:**
+//! ```bash
+//! docker run --read-only \
+//!   -v /host/cortex-data:/home/user/.local/share/Cortex \
+//!   -v /host/cortex-config:/home/user/.config/Cortex \
+//!   -v /host/cortex-cache:/home/user/.cache/Cortex \
+//!   -v /tmp:/tmp:rw \
+//!   cortex:latest
+//! ```
+//!
+//! **Note:** Cortex may also use system temp directories (`/tmp` or `$TMPDIR`)
+//! for ephemeral files. Mount these as writable if needed.
 
 use std::path::PathBuf;
 use tracing::debug;

cortex-tui/src/app.rs

@@ -1229,6 +1229,34 @@ impl AppState {
         self.terminal_size = (width, height);
     }
 
+    /// Issue #2327: Invalidate cached content layout calculations.
+    ///
+    /// Called on terminal resize to ensure code blocks and wrapped text
+    /// are properly re-rendered for the new terminal dimensions.
+    /// This prevents rendering corruption when the terminal is resized
+    /// while streaming content (especially code blocks with syntax highlighting).
+    pub fn invalidate_content_layout(&mut self) {
+        // Reset scroll positions to prevent displaying content outside new bounds
+        self.chat_scroll = 0;
+        self.sidebar_scroll = 0;
+        self.diff_scroll = 0;
+
+        // Reset content line counts - will be recalculated on next render
+        self.chat_content_lines = 0;
+        self.chat_visible_lines = 0;
+
+        // Clear any partial text segment that might have incomplete line wrapping
+        // The typewriter will regenerate content on the next render
+        if let Some(ref mut tw) = self.typewriter {
+            tw.reset_animation();
+        }
+
+        // Re-pin to bottom if we were following the stream
+        if self.streaming.is_streaming {
+            self.chat_scroll_pinned_bottom = true;
+        }
+    }
+
     /// Request to quit the application
     pub fn quit(&mut self) {
         self.running = false;

cortex-tui/src/providers/manager.rs

@@ -427,21 +427,63 @@ impl ProviderManager {
     ///
     /// This method re-loads the config from disk and also re-evaluates any environment
     /// variable substitutions (e.g., `{env:VAR_NAME}` placeholders) to pick up current values.
+    ///
+    /// Issue #2320: Environment variables are now re-evaluated during config reload,
+    /// ensuring that changes to env vars (like API keys) take effect without a full restart.
     pub fn reload_config(&mut self) -> Result<()> {
         // Re-load config from file (this will pick up any file changes)
         self.config = CortexConfig::load()?;
 
-        // Re-evaluate environment-dependent config values by refreshing default values
-        // The api_url may reference CORTEX_API_URL which could have changed
-        if self.config.api_url == super::config::DEFAULT_API_URL {
-            // Re-check env var in case it was set after initial load
-            if let Ok(url) = std::env::var("CORTEX_API_URL") {
+        // Issue #2320: Re-evaluate ALL environment-dependent config values
+        // This ensures env var changes take effect on config reload
+
+        // Re-check CORTEX_API_URL in case it was set/changed after initial load
+        if let Ok(url) = std::env::var("CORTEX_API_URL") {
+            if !url.is_empty() {
                 self.config.api_url = url;
             }
         }
 
+        // Re-check CORTEX_AUTH_TOKEN - force token refresh by clearing cached auth
+        // The next API call will re-read the token from environment or keyring
+        self.auth_token = None;
+
+        // If CORTEX_AUTH_TOKEN is now set, update our cached token
+        if let Ok(token) = std::env::var("CORTEX_AUTH_TOKEN") {
+            if !token.is_empty() {
+                self.auth_token = Some(token);
+            }
+        }
+
+        // Re-check CORTEX_DEFAULT_MODEL if set
+        if let Ok(model) = std::env::var("CORTEX_DEFAULT_MODEL") {
+            if !model.is_empty() {
+                self.config.default_model = model;
+            }
+        }
+
+        // Re-check CORTEX_MAX_TOKENS if set
+        if let Ok(max_tokens) = std::env::var("CORTEX_MAX_TOKENS") {
+            if let Ok(tokens) = max_tokens.parse::<u32>() {
+                self.config.max_tokens = tokens;
+            }
+        }
+
+        // Re-check CORTEX_TEMPERATURE if set
+        if let Ok(temp) = std::env::var("CORTEX_TEMPERATURE") {
+            if let Ok(temperature) = temp.parse::<f32>() {
+                self.config.temperature = temperature;
+            }
+        }
+
         // Reset client to pick up new config values
+        // This forces a new client to be created with updated settings
         self.client = None;
+
+        // Clear cached models since API credentials may have changed
+        self.cached_models = None;
+
+        tracing::info!("Configuration reloaded with fresh environment variable values");
         Ok(())
     }