fix: batch merge of bug fixes (PR #288) - issues #2756, #2758, #2759, #2760, #2761, #2762, #2763, #2764, #2765, #2766

Fixes:
- #2756: Add user-friendly error message for address-in-use errors in cortex serve
- #2758: Add proxy error detection and user-friendly messages for proxy failures
- #2759: Add session file size warning and monitoring for large sessions
- #2760: Add graceful handling of malformed markdown (auto-close code blocks/tables)
- #2761: Add HTTP/2 GOAWAY detection and retry logic for transient errors
- #2762: Add user-friendly config parse error messages with line/column info
- #2763: Add TTY detection and NO_COLOR support for ANSI escape codes
- #2764: Document tab completion limits for large directories
- #2766: Add signal handler documentation and improved panic hook for terminal cleanup

Author: factorydroid

cortex-cli/src/completion_setup.rs

@@ -221,6 +221,10 @@ fn install_completions(shell: Shell) -> io::Result<()> {
     Ok(())
 }
 
+/// Maximum number of completions to return for file/directory listings.
+/// This prevents shell hangs when completing in directories with many files.
+pub const MAX_COMPLETION_RESULTS: usize = 1000;
+
 /// Prompt the user to install shell completions on first run.
 ///
 /// This function checks if:
@@ -229,6 +233,9 @@ fn install_completions(shell: Shell) -> io::Result<()> {
 /// 3. We can detect the user's shell
 ///
 /// If all conditions are met, it prompts the user and optionally installs completions.
+///
+/// Note: For large directories (>1000 files), completion may be slow.
+/// Consider using more specific paths or limiting directory size.
 pub fn maybe_prompt_completion_setup() {
     // Only prompt in interactive terminals
     if !is_interactive_terminal() {

cortex-cli/src/main.rs

@@ -2118,7 +2118,7 @@ async fn run_serve(serve_cli: ServeCommand) -> Result<()> {
         None
     };
 
-    // Run the server - capture any errors and sanitize them to prevent token leakage
+    // Run the server with user-friendly error handling for common issues (#2756)
     let result = cortex_app_server::run(config).await;
 
     // Stop mDNS advertising on shutdown
@@ -2128,19 +2128,48 @@ async fn run_serve(serve_cli: ServeCommand) -> Result<()> {
         }
     }
 
-    // Sanitize error messages to prevent auth token leakage
-    result.map_err(|e| {
-        let error_msg = e.to_string();
-        // If an auth token was provided, ensure it's not in any error messages
-        if let Some(ref token) = serve_cli.auth_token {
-            if !token.is_empty() && error_msg.contains(token) {
-                // Mask the token in the error message
-                let sanitized = error_msg.replace(token, "[REDACTED]");
-                return anyhow::anyhow!("{}", sanitized);
+    // Convert errors to user-friendly messages and sanitize tokens
+    match result {
+        Ok(()) => Ok(()),
+        Err(e) => {
+            let err_str = e.to_string();
+
+            // Sanitize error messages to prevent auth token leakage
+            let sanitized_err = if let Some(ref token) = serve_cli.auth_token {
+                if !token.is_empty() && err_str.contains(token) {
+                    err_str.replace(token, "[REDACTED]")
+                } else {
+                    err_str.clone()
+                }
+            } else {
+                err_str.clone()
+            };
+
+            // Check for address-in-use error (EADDRINUSE is error 98 on Linux, 48 on macOS)
+            if sanitized_err.contains("Address already in use")
+                || sanitized_err.contains("address already in use")
+                || sanitized_err.contains("os error 98")
+                || sanitized_err.contains("os error 48")
+            {
+                bail!(
+                    "Error: Port {} is already in use. Another process may be running on this port.\n\
+                     Hint: Use `lsof -i :{}` or `ss -tlnp | grep {}` to find the process, or try a different port with --port",
+                    serve_cli.port,
+                    serve_cli.port,
+                    serve_cli.port
+                );
+            }
+            // Check for permission denied (trying to bind to privileged port)
+            if sanitized_err.contains("Permission denied") || sanitized_err.contains("os error 13") {
+                bail!(
+                    "Error: Permission denied binding to port {}.\n\
+                     Hint: Ports below 1024 require root/admin privileges. Try a port >= 1024.",
+                    serve_cli.port
+                );
             }
+            Err(anyhow::anyhow!("{}", sanitized_err))
         }
-        e.into()
-    })
+    }
 }
 
 async fn run_servers(servers_cli: ServersCommand) -> Result<()> {

cortex-cli/src/run_cmd.rs

@@ -289,6 +289,57 @@ impl TermColor {
             TermColor::Default => "\x1b[0m",
         }
     }
+
+    /// Get ANSI code only if colors should be shown (stdout is a TTY and NO_COLOR is not set).
+    fn code_if_tty(&self) -> &'static str {
+        if should_use_colors() {
+            self.ansi_code()
+        } else {
+            ""
+        }
+    }
+}
+
+/// Check if colors should be used in output.
+/// Respects NO_COLOR environment variable and checks if stdout is a TTY.
+fn should_use_colors() -> bool {
+    // Respect NO_COLOR environment variable (https://no-color.org/)
+    if std::env::var("NO_COLOR").is_ok() {
+        return false;
+    }
+
+    // Check if stdout is a terminal
+    io::stdout().is_terminal()
+}
+
+/// Strip ANSI escape codes from a string.
+/// Use this when outputting to non-TTY destinations.
+fn strip_ansi_codes(s: &str) -> String {
+    // Simple regex-free approach: remove ESC [ ... m sequences
+    let mut result = String::with_capacity(s.len());
+    let mut chars = s.chars().peekable();
+
+    while let Some(c) = chars.next() {
+        if c == '\x1b' {
+            // Check for CSI sequence
+            if chars.peek() == Some(&'[') {
+                chars.next(); // consume '['
+                // Skip until we find the terminating character (letter)
+                while let Some(&next) = chars.peek() {
+                    chars.next();
+                    if next.is_ascii_alphabetic() {
+                        break;
+                    }
+                }
+            } else {
+                result.push(c);
+            }
+        } else {
+            result.push(c);
+        }
+    }
+
+    result
 }
 
 /// Get tool display information.

cortex-core/src/markdown/renderer.rs

@@ -820,6 +820,53 @@ impl<'a> RenderState<'a> {
 
     /// Finish rendering and return the accumulated lines.
     fn finish(mut self) -> Vec<Line<'static>> {
+        // Handle unclosed code blocks gracefully (auto-close them)
+        if self.in_code_block {
+            // Auto-close the code block to prevent rendering issues
+            self.in_code_block = false;
+
+            // Render the code block even if unclosed
+            let code_lines = if let Some(ref code_renderer) = self.renderer.code_renderer {
+                code_renderer.render(
+                    &self.code_buffer,
+                    self.code_language.as_deref(),
+                    self.renderer.width,
+                )
+            } else {
+                self.render_simple_code_block()
+            };
+
+            // Add blockquote prefix to each line if needed
+            if self.blockquote_depth > 0 {
+                for line in code_lines {
+                    let mut prefixed_spans = self.get_blockquote_prefix();
+                    prefixed_spans.extend(line.spans);
+                    self.lines.push(Line::from(prefixed_spans));
+                }
+            } else {
+                self.lines.extend(code_lines);
+            }
+
+            self.code_buffer.clear();
+            self.code_language = None;
+        }
+
+        // Close any unclosed tables
+        if let Some(builder) = self.table_builder.take() {
+            let mut table = builder.build();
+            table.calculate_column_widths(self.renderer.width);
+
+            let table_lines = render_table(
+                &table,
+                self.renderer.theme.table_border,
+                self.renderer.theme.table_header_text,
+                self.renderer.theme.table_cell_text,
+                self.renderer.width,
+            );
+
+            self.lines.extend(table_lines);
+        }
+
         // Flush any remaining content
         self.flush_line();
         self.lines

cortex-engine/src/api_client.rs

@@ -311,10 +311,18 @@ impl ApiClient {
                         message: format!("HTTP {status}: {error_body}"),
                     });
                 }
-                Err(e) if attempt < self.config.max_retries => {
-                    last_error = Some(e);
+                Err(e) if attempt < self.config.max_retries && Self::is_retryable_error(&e) => {
+                    tracing::debug!(
+                        attempt = attempt,
+                        error = %e,
+                        "Retrying request after transient error (possibly HTTP/2 GOAWAY)"
+                    );
+                    last_error = Some(CortexError::ConnectionFailed {
+                        endpoint: url.clone(),
+                        message: e.to_string(),
+                    });
                 }
-                Err(e) => return Err(e),
+                Err(e) => return Err(CortexError::from_reqwest_with_proxy_check(e, &url)),
             }
         }
 
@@ -325,19 +333,20 @@ impl ApiClient {
     }
 
     /// Execute a single request.
+    /// Returns the raw reqwest error for better error handling at the call site.
     async fn execute_request<B: Serialize>(
         &self,
         method: &Method,
         url: &str,
         body: &Option<B>,
-    ) -> Result<Response> {
+    ) -> std::result::Result<Response, reqwest::Error> {
         let mut request = self.client.request(method.clone(), url);
 
         if let Some(body) = body {
             request = request.json(body);
         }
 
-        request.send().await.map_err(std::convert::Into::into)
+        request.send().await
     }
 
     /// Check if status is retryable.
@@ -351,6 +360,19 @@ impl ApiClient {
         )
     }
 
+    /// Check if an error is retryable (including HTTP/2 GOAWAY).
+    fn is_retryable_error(err: &reqwest::Error) -> bool {
+        // Check for HTTP/2 GOAWAY or connection reset errors
+        let err_str = err.to_string().to_lowercase();
+        err_str.contains("goaway")
+            || err_str.contains("stream was reset")
+            || err_str.contains("connection reset")
+            || err_str.contains("connection was reset")
+            || err_str.contains("h2 protocol error")
+            || err.is_connect()
+            || err.is_timeout()
+    }
+
     /// Get raw response.
     pub async fn get_raw(&self, path: &str) -> Result<String> {
         let url = format!("{}{}", self.config.base_url, path);

cortex-engine/src/client/cortex.rs

@@ -514,7 +514,7 @@ impl ModelClient for CortexClient {
 
         let resp = req.json(&body).send().await.map_err(|e| {
             tracing::error!(error = %e, "Failed to send request");
-            CortexError::BackendUnavailable(format!("Failed to connect to Cortex: {}", e))
+            CortexError::from_reqwest_with_proxy_check(e, &url)
         })?;
 
         tracing::info!(

cortex-engine/src/config/loader.rs

@@ -424,21 +424,95 @@ pub fn parse_config_content(content: &str, format: ConfigFormat) -> std::io::Res
         ConfigFormat::Toml => toml::from_str(content).map_err(|e| {
             std::io::Error::new(
                 std::io::ErrorKind::InvalidData,
-                format!("Failed to parse TOML config: {e}"),
+                format_toml_error(&e, content),
             )
         }),
         ConfigFormat::JsonC => {
             let stripped = strip_json_comments(content);
             serde_json::from_str(&stripped).map_err(|e| {
                 std::io::Error::new(
                     std::io::ErrorKind::InvalidData,
-                    format!("Failed to parse JSON config: {e}"),
+                    format_json_error(&e, &stripped),
                 )
             })
         }
     }
 }
 
+/// Format a TOML parse error with user-friendly context.
+fn format_toml_error(e: &toml::de::Error, content: &str) -> String {
+    let lines: Vec<&str> = content.lines().collect();
+    let mut msg = String::from("Configuration error in TOML file:\n");
+
+    // Try to extract line/column information
+    let err_str = e.to_string();
+    if let Some(span) = e.span() {
+        // Calculate line number from byte offset
+        let mut line_num = 1;
+        let mut col = 1;
+        for (i, c) in content.chars().enumerate() {
+            if i >= span.start {
+                break;
+            }
+            if c == '\n' {
+                line_num += 1;
+                col = 1;
+            } else {
+                col += 1;
+            }
+        }
+
+        msg.push_str(&format!("  Error at line {}, column {}:\n", line_num, col));
+
+        // Show the problematic line if available
+        if line_num > 0 && line_num <= lines.len() {
+            let line_content = lines[line_num - 1];
+            msg.push_str(&format!("    {}: {}\n", line_num, line_content));
+            // Show pointer to the column
+            if col > 0 {
+                msg.push_str(&format!(
+                    "    {}  {}\n",
+                    " ".repeat(line_num.to_string().len()),
+                    " ".repeat(col - 1) + "^"
+                ));
+            }
+        }
+    }
+
+    msg.push_str(&format!("  Problem: {}\n", err_str));
+    msg.push_str("  Hint: Check for missing quotes, unclosed brackets, or invalid syntax.");
+    msg
+}
+
+/// Format a JSON parse error with user-friendly context.
+fn format_json_error(e: &serde_json::Error, content: &str) -> String {
+    let lines: Vec<&str> = content.lines().collect();
+    let mut msg = String::from("Configuration error in JSON file:\n");
+
+    let line_num = e.line();
+    let col = e.column();
+
+    msg.push_str(&format!("  Error at line {}, column {}:\n", line_num, col));
+
+    // Show the problematic line if available
+    if line_num > 0 && line_num <= lines.len() {
+        let line_content = lines[line_num - 1];
+        msg.push_str(&format!("    {}: {}\n", line_num, line_content));
+        // Show pointer to the column
+        if col > 0 {
+            msg.push_str(&format!(
+                "    {}  {}\n",
+                " ".repeat(line_num.to_string().len()),
+                " ".repeat(col.saturating_sub(1)) + "^"
+            ));
+        }
+    }
+
+    msg.push_str(&format!("  Problem: {}\n", e));
+    msg.push_str("  Hint: Check for missing commas, unclosed braces, or trailing commas.");
+    msg
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;