log.c

Go to the documentation of this file.

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define LOG_BUFFER_BUFFER_SIZE 8192
#define LOG_LOG_MSG_BUFFER_SIZE 256
#define LOG_PARSE_TIMESTAMP_BUFFER_SIZE 64
#define LOG_LEVEL_BUFFER_SIZE 16
#define LOG_FILE_PATH_BUFFER_SIZE 256
#define LOG_FUNC_NAME_BUFFER_SIZE 256
 
#include <ascii-chat/otel.h>
#include <ascii-chat/network/acip/send.h>
 
#include <ascii-chat/tui/notice.h>
 
#include <ascii-chat/tui/controller.h>
#include <ascii-chat/common.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/options/rcu.h> // For RCU-based options access
#include <libplatform/compiler.h>
#include <libplatform/system.h>
#include <libplatform/terminal.h>
#include <libplatform/system.h>
#include <ascii-chat/util/path.h>
#include <ascii-chat/util/string.h>
#include <ascii-chat/util/time.h>
#include <ascii-chat/util/utf8.h>
#include <libplatform/lifecycle.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <fcntl.h>
#include <sys/stat.h>
#include <ctype.h>
 
#include <ascii-chat/log/log.h>
 
int terminal_choose_log_fd(int level);
#include <ascii-chat/log/format.h>
#include <ascii-chat/log/colorize.h>
#include <ascii-chat/log/mmap.h>
#include <ascii-chat/log/grep.h>
#include <ascii-chat/log/json.h>
#include <libplatform/terminal.h>
#include <libplatform/systemd.h>
#include <ascii-chat/session/session_log_buffer.h>
#include <ascii-chat/log/search.h>
#include <ascii-chat/options/colorscheme.h>
#include <libplatform/thread.h>
#include <libplatform/mutex.h>
#include <ascii-chat/network/packet/packet.h>
#include <ascii-chat/video/terminal/ansi.h>
#include <ascii-chat/debug/backtrace.h>
 
// Readers pin the session buffer until unregister has drained their appends.
static atomic_t g_session_log_readers = {0};
 
/* Platform-specific log hook (weak, can be overridden by platform implementations) */
__attribute__((weak)) void platform_log_hook(log_level_t level, const char *message) {
  (void)level;
  (void)message;
  // Default: no-op
}
 
/* ============================================================================
 * Logging System Internal State
 * ============================================================================ */
 
/* Log context struct - Lock-free logging with mutex-protected rotation
 *
 * Design: Logging itself is lock-free using atomic operations and atomic write() syscalls.
 * Only log rotation uses a mutex, since it involves multiple file operations that must
 * be atomic as a group (close, read tail, write temp, rename, reopen).
 *
 * This structure consolidates all logging system state into a single, named struct
 * for better auditability and easier initialization/cleanup.
 */
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wmissing-field-initializers"
// Console logs never draw over a live screen, even from its rendering callback.
static void log_terminal_printf(int fd, const char *format, ...) {
  if (ui_controller_is_presenting())
    return;
  char buffer[LOG_TERMINAL_BUFFER_SIZE];
  va_list args;
  va_start(args, format);
  int length = vsnprintf(buffer, sizeof(buffer), format, args);
  va_end(args);
  if (length > 0) {
    size_t bytes = (size_t)length < sizeof(buffer) ? (size_t)length : sizeof(buffer) - 1;
    ui_controller_write(fd, buffer, bytes);
  }
}
 
static struct log_system_t {
  /* Core logging I/O and state */
  atomic_t file;                      /* File descriptor (atomic for safe access) */
  atomic_t json_file;                 /* JSON output file descriptor (-1 = disabled) */
  atomic_t level;                     /* Log level as int for atomic ops */
  lifecycle_t lifecycle;              /* Initialization state machine */
  char filename[LOG_MSG_BUFFER_SIZE]; /* Store filename (set once at init) */
  atomic_t current_size;              /* Track current file size */
 
  /* Terminal output control */
  atomic_t terminal_output_enabled; /* Control stderr output to terminal */
  atomic_t force_stderr;            /* Force all terminal logs to stderr (client mode) */
  atomic_t terminal_locked;         /* True when a thread has exclusive terminal access */
  atomic_t terminal_owner_thread;   /* Thread that owns terminal output (stored as uint64) */
 
  /* Log level and formatting */
  atomic_t level_manually_set;         /* Track if level was set manually */
  atomic_t flush_delay_ms;             /* Delay between each buffered log flush (0 = disabled) */
  log_template_t *format;              /* Compiled log format (NULL = use default) */
  log_template_t *format_console_only; /* Console-only format variant */
  atomic_t has_custom_format;          /* True if format was customized */
 
  /* Terminal capability detection and color scheme */
  terminal_capabilities_t terminal_caps; /* Detected terminal capabilities */
  bool terminal_caps_initialized;        /* Whether terminal caps were detected */
  bool terminal_caps_detecting;          /* Guard against recursion during detection */
 
  /* Shutdown state management */
  bool shutdown_saved_terminal_output; /* Saved state for log_shutdown_begin/end */
  bool shutdown_in_progress;           /* Track if shutdown phase is active */
 
  /* Log rotation */
  mutex_t rotation_mutex;               /* Mutex for log rotation only (not for logging!) */
  lifecycle_t rotation_mutex_lifecycle; /* Rotation mutex initialization state machine */
 
  /* Session-specific logging (splash/status screens) */
  atomic_ptr_t session_log_buffer; /* Pointer to registered session log buffer (can be NULL) */
} g_log = {
    .file = {0},                         /* STDERR_FILENO (fd 2) - fd 0 is STDIN (read-only!) */
    .json_file = {.impl = (uint64_t)-1}, /* -1 = disabled (atomic_t initialized as uint64_t -1) */
    .level = {0},                        /* DEFAULT_LOG_LEVEL */
    .lifecycle = LIFECYCLE_INIT,
    .filename = {0},
    .current_size = {0},
    .terminal_output_enabled = {1}, /* true */
    .force_stderr = {0},            /* false */
    .terminal_locked = {0},         /* false */
    .terminal_owner_thread = {0},
    .level_manually_set = {0}, /* false */
    .flush_delay_ms = {0},
    .format = NULL,
    .format_console_only = NULL,
    .has_custom_format = {0}, /* false */
    .terminal_caps = {0},
    .terminal_caps_initialized = false,
    .terminal_caps_detecting = false,
    .shutdown_saved_terminal_output = true,
    .shutdown_in_progress = false,
    .rotation_mutex_lifecycle = LIFECYCLE_INIT,
    .session_log_buffer = {0}, /* NULL */
};
#pragma GCC diagnostic pop
 
/* Level strings are defined in format.c (get_level_string_padded / get_level_string) */
 
/* ============================================================================
 * Level Strings
 * ============================================================================
 * The actual default log format is defined in lib/log/format.c
 * and accessed via OPT_LOG_TEMPLATE_DEFAULT macro to support different modes.
 */

const char *get_level_string_padded(log_level_t level) {
  const char *result;
  switch (level) {
  case LOG_INFO:
    result = "INFO "; // 5 chars: INFO + 1 space
    break;
  case LOG_WARN:
    result = "WARN "; // 5 chars: WARN + 1 space
    break;
  case LOG_DEV:
    result = "DEV  "; // 5 chars: DEV + 2 spaces
    break;
  case LOG_DEBUG:
    result = "DEBUG"; // 5 chars: DEBUG (no padding needed)
    break;
  case LOG_ERROR:
    result = "ERROR"; // 5 chars: ERROR (no padding needed)
    break;
  case LOG_FATAL:
    result = "FATAL"; // 5 chars: FATAL (no padding needed)
    break;
  default:
    result = "?????"; // Invalid level - return 5 question marks
  }
  // Verify length
  if (strlen(result) != 5) {
    log_terminal_printf(STDERR_FILENO, "ERROR: get_level_string_padded() returned non-5-char string: '%s' (len=%zu)\n",
                        result, strlen(result));
  }
  return result;
}
 
#define LOG_COLOR_COUNT 8 /* DEV, DEBUG, WARN, INFO, ERROR, FATAL, GREY, RESET */
 
/* Semantic colors are resolved through the shared live palette API. */
 
/* Internal error macro - uses g_log directly, only used in this file */
#ifdef NDEBUG
#define LOGGING_INTERNAL_ERROR(error, message, ...)                                                                    \
  do {                                                                                                                 \
    errno_set_with_message(error, NULL, 0, NULL, message, ##__VA_ARGS__);                                              \
    static const char *msg_header = "CRITICAL LOGGING SYSTEM ERROR: ";                                                 \
    log_terminal_printf(STDERR_FILENO, "%s %s\n", colored_string(LOG_COLOR_ERROR, msg_header), message);               \
    int _log_fd = atomic_load_int(&g_log.file);                                                                        \
    platform_write(_log_fd, msg_header, strlen(msg_header));                                                           \
    platform_write(_log_fd, message, strlen(message));                                                                 \
    platform_write(_log_fd, "\n", 1);                                                                                  \
    backtrace_print_simple(0);                                                                                         \
  } while (0)
#else
#define LOGGING_INTERNAL_ERROR(error, message, ...)                                                                    \
  do {                                                                                                                 \
    errno_set_with_message(error, __FILE__, __LINE__, __func__, message, ##__VA_ARGS__);                               \
    static const char *msg_header = "CRITICAL LOGGING SYSTEM ERROR: ";                                                 \
    log_terminal_printf(STDERR_FILENO, "%s %s\n", colored_string(LOG_COLOR_ERROR, msg_header), message);               \
    int _log_fd = atomic_load_int(&g_log.file);                                                                        \
    platform_write(_log_fd, msg_header, strlen(msg_header));                                                           \
    platform_write(_log_fd, message, strlen(message));                                                                 \
    platform_write(_log_fd, "\n", 1);                                                                                  \
    backtrace_print_simple(0);                                                                                         \
  } while (0)
#endif
 
size_t get_current_time_formatted(char *time_buf) {
  /* Get wall-clock time in nanoseconds */
  uint64_t ts_ns = time_get_realtime_ns();
  // Extract seconds and nanoseconds from total nanoseconds
  time_t seconds = (time_t)(ts_ns / NS_PER_SEC_INT);
  long nanoseconds = (long)(ts_ns % NS_PER_SEC_INT);
  struct tm tm_info;
  platform_localtime(&seconds, &tm_info);
  // Format the time part first
  // strftime returns 0 on error, not negative (and len is size_t/unsigned)
  size_t len = strftime(time_buf, 32, "%H:%M:%S", &tm_info);
  if (len == 0 || len >= 32) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format time");
    return 0;
  }
 
  // Add microseconds manually (convert nanoseconds to microseconds for display)
  long microseconds = nanoseconds / 1000;
  if (microseconds < 0)
    microseconds = 0;
  if (microseconds > 999999)
    microseconds = 999999;
 
  int result = safe_snprintf(time_buf + len, 32 - len, ".%06ld", microseconds);
  if (result < 0 || result >= (int)(32 - len)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format microseconds");
    return 0;
  }
 
  return len + (size_t)result;
}
 
char *format_message(const char *format, va_list args) {
  if (!format) {
    return NULL;
  }
 
  // First, determine the size needed
  va_list args_copy;
  va_copy(args_copy, args);
  int size = safe_vsnprintf(NULL, 0, format, args_copy);
  va_end(args_copy);
 
  if (size < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format context message");
    return NULL;
  }
 
  // Allocate and format the message
  char *message = SAFE_MALLOC(size + 1, char *);
  int result = safe_vsnprintf(message, (size_t)size + 1, format, args);
  if (result < 0) {
    SAFE_FREE(message);
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format context message");
    return NULL;
  }
 
  return message;
}

static int truncate_at_whole_line(char *buffer, int current_len, size_t max_len) {
  if (current_len < 0 || (size_t)current_len <= max_len) {
    return current_len; // No truncation needed
  }
 
  // Search backwards from max_len position for last newline
  int truncate_pos = (int)max_len - 1;
  while (truncate_pos > 0 && buffer[truncate_pos] != '\n') {
    truncate_pos--;
  }
 
  // If we found a newline, truncate after it
  if (truncate_pos > 0 && buffer[truncate_pos] == '\n') {
    truncate_pos++; // Include the newline
    // NOLINTNEXTLINE(clang-analyzer-security.ArrayBound) - truncate_pos validated by max_len
    buffer[truncate_pos] = '\0';
    return truncate_pos;
  }
 
  // No newline found, truncate at max_len to be safe
  truncate_pos = (int)max_len - 1;
  buffer[truncate_pos] = '\0';
  return truncate_pos;
}

static void validate_log_message_utf8(const char *message, const char *source) {
  if (!message || !source) {
    return;
  }
 
  if (!utf8_is_valid(message)) {
    // Use fprintf instead of log_warn to avoid infinite recursion
    // (this function is called from log_msg, which would create a loop)
    log_terminal_printf(STDERR_FILENO, "[WARN] Invalid UTF-8 detected in %s\n", source);
    log_terminal_printf(STDERR_FILENO, "[DEBUG] Invalid UTF-8 data: %s\n", message);
  }
}
 
/* ============================================================================
 * Logging Implementation
 * ============================================================================
 */
 
/* Parse LOG_LEVEL environment variable */
static log_level_t parse_log_level_from_env(void) {
  const char *env_level = SAFE_GETENV("LOG_LEVEL");
  if (!env_level) {
    return DEFAULT_LOG_LEVEL; // Default level based on build type
  }
 
  // Case-insensitive comparison
  if (platform_strcasecmp(env_level, "DEV") == 0 || strcmp(env_level, "0") == 0) {
    return LOG_DEV;
  }
  if (platform_strcasecmp(env_level, "DEBUG") == 0 || strcmp(env_level, "1") == 0) {
    return LOG_DEBUG;
  }
  if (platform_strcasecmp(env_level, "INFO") == 0 || strcmp(env_level, "2") == 0) {
    return LOG_INFO;
  }
  if (platform_strcasecmp(env_level, "WARN") == 0 || strcmp(env_level, "3") == 0) {
    return LOG_WARN;
  }
  if (platform_strcasecmp(env_level, "ERROR") == 0 || strcmp(env_level, "4") == 0) {
    return LOG_ERROR;
  }
  if (platform_strcasecmp(env_level, "FATAL") == 0 || strcmp(env_level, "5") == 0) {
    return LOG_FATAL;
  }
 
  // Invalid value - return default
  log_warn("Invalid LOG_LEVEL: %s", env_level);
  return DEFAULT_LOG_LEVEL;
}
 
/* Log rotation function - keeps the tail (recent entries)
 * REQUIRES: rotation_mutex must be held by caller
 * This is the only operation that uses a mutex - regular logging is lock-free.
 */
static void rotate_log_locked(void) {
  int file = atomic_load_int(&g_log.file);
  size_t current_size = atomic_load_u64(&g_log.current_size);
 
  if (file < 0 || file == STDERR_FILENO || strlen(g_log.filename) == 0) {
    return;
  }
 
  if (current_size < MAX_LOG_SIZE) {
    return;
  }
 
  platform_close(file);
  atomic_store_int(&g_log.file, -1);
 
  /* Open file for reading to get the tail */
  int read_file = platform_open("log_file_read", g_log.filename, O_RDONLY, 0);
  if (read_file < 0) {
    log_error("Failed to open file descriptor for log rotation: fd=%d, path=%s", read_file, g_log.filename);
    /* Fall back to regular truncation */
    int fd = platform_open("log_file_write", g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store_int(&g_log.file, fd);
    atomic_store_u64(&g_log.current_size, 0);
    return;
  }
 
  /* Seek to position where we want to start keeping data (keep last 2MB) */
  size_t keep_size = MAX_LOG_SIZE * 2 / 3; /* Keep last 2MB of 3MB file */
  if (current_size < keep_size) {
    platform_close(read_file);
    /* Fall back to truncation since we don't have enough data to rotate */
    int fd = platform_open("log_file_write", g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store_int(&g_log.file, fd);
    atomic_store_u64(&g_log.current_size, 0);
    return;
  }
  if (lseek(read_file, (off_t)(current_size - keep_size), SEEK_SET) == (off_t)-1) {
    platform_close(read_file);
    /* Fall back to truncation */
    int fd = platform_open("log_file_write", g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store_int(&g_log.file, fd);
    atomic_store_u64(&g_log.current_size, 0);
    return;
  }
 
  /* Skip to next line boundary to avoid partial lines */
  char c;
  while (platform_read(read_file, &c, 1) > 0 && c != '\n') {
    /* Skip characters until newline */
  }
 
  /* Read the tail into a temporary file */
  char temp_filename[PLATFORM_MAX_PATH_LENGTH];
  int result = safe_snprintf(temp_filename, sizeof(temp_filename), "%s.tmp", g_log.filename);
  if (result <= 0 || result >= (int)sizeof(temp_filename)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format temp filename");
    platform_close(read_file);
    int fd = platform_open("log_file_append", g_log.filename, O_CREAT | O_RDWR | O_APPEND, FILE_PERM_PRIVATE);
    atomic_store_int(&g_log.file, fd);
    return;
  }
 
  int temp_file = platform_open("log_file_temp", temp_filename, O_CREAT | O_WRONLY | O_TRUNC, FILE_PERM_PRIVATE);
  if (temp_file < 0) {
    log_warn("Failed to open temporary file descriptor for log rotation: fd=%d, path=%s", temp_file, temp_filename);
    platform_close(read_file);
    /* Fall back to truncation */
    int fd = platform_open("log_file_write", g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store_int(&g_log.file, fd);
    atomic_store_u64(&g_log.current_size, 0);
    return;
  }
 
  /* Copy tail to temp file */
  char buffer[LOG_BUFFER_BUFFER_SIZE];
  ssize_t bytes_read;
  size_t new_size = 0;
  while ((bytes_read = platform_read(read_file, buffer, sizeof(buffer))) > 0) {
    ssize_t written = platform_write(temp_file, buffer, (size_t)bytes_read);
    if (written != bytes_read) {
      platform_close(read_file);
      platform_close(temp_file);
      unlink(temp_filename);
      /* Fall back to truncation */
      int fd = platform_open("log_file_write", g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
      atomic_store_int(&g_log.file, fd);
      atomic_store_u64(&g_log.current_size, 0);
      return;
    }
    new_size += (size_t)bytes_read;
  }
 
  platform_close(read_file);
  platform_close(temp_file);
 
  /* Replace original with temp file */
  if (rename(temp_filename, g_log.filename) != 0) {
    unlink(temp_filename); /* Clean up temp file */
    /* Fall back to truncation */
    int fd = platform_open("log_file_write", g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store_int(&g_log.file, fd);
    atomic_store_u64(&g_log.current_size, 0);
    return;
  }
 
  /* Reopen for appending */
  int new_fd = platform_open("log_file_append", g_log.filename, O_CREAT | O_RDWR | O_APPEND, FILE_PERM_PRIVATE);
  if (new_fd < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to reopen rotated log file: %s", g_log.filename);
    atomic_store_int(&g_log.file, STDERR_FILENO);
    g_log.filename[0] = '\0';
    atomic_store_u64(&g_log.current_size, 0);
    return;
  }
  atomic_store_int(&g_log.file, new_fd);
  atomic_store_u64(&g_log.current_size, new_size);
 
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  get_current_time_formatted(time_buf);
 
  char log_msg[LOG_LOG_MSG_BUFFER_SIZE];
  int log_msg_len =
      safe_snprintf(log_msg, sizeof(log_msg), "[%s] [INFO] Log tail-rotated (kept %zu bytes)\n", time_buf, new_size);
  if (log_msg_len > 0 && log_msg_len < (int)sizeof(log_msg)) {
    (void)platform_write(new_fd, log_msg, (size_t)log_msg_len);
  }
}
 
/* Check if rotation is needed and perform it (acquires mutex only if needed) */
static void maybe_rotate_log(void) {
  /* Rotation mutex not initialized - skip rotation */
  if (!lifecycle_is_initialized(&g_log.rotation_mutex_lifecycle)) {
    return;
  }
 
  /* Check mmap path first */
  if (log_mmap_is_active()) {
    size_t used = 0, capacity = 0;
    if (log_mmap_get_usage(&used, &capacity) && capacity > 0) {
      /* Rotate when 90% full to leave room for writes */
      if (used > capacity * 9 / 10) {
        mutex_lock(&g_log.rotation_mutex);
        log_mmap_rotate();
        mutex_unlock(&g_log.rotation_mutex);
      }
    }
    return;
  }
 
  /* File path: quick atomic check - avoid mutex if not needed */
  size_t current_size = atomic_load_u64(&g_log.current_size);
  if (current_size < MAX_LOG_SIZE) {
    return;
  }
 
  /* Size exceeded - acquire mutex and rotate */
  mutex_lock(&g_log.rotation_mutex);
  rotate_log_locked();
  mutex_unlock(&g_log.rotation_mutex);
}
 
static session_log_buffer_t *g_history;
 
session_log_buffer_t *log_get_history_buffer(void) {
  return g_history;
}
 
void log_init(const char *filename, log_level_t level, bool force_stderr, bool use_mmap) {
 
  if (!g_history)
    g_history = session_log_buffer_create();
 
  // Initialize rotation mutex (only operation that uses a mutex)
  g_log.rotation_mutex_lifecycle.sync_type = LIFECYCLE_SYNC_MUTEX;
  g_log.rotation_mutex_lifecycle.sync.mutex = &g_log.rotation_mutex;
  lifecycle_init(&g_log.rotation_mutex_lifecycle, "log_rotation");
 
  // Set basic config using atomic stores
  atomic_store_u64(&g_log.force_stderr, force_stderr);
  bool preserve_terminal_output = atomic_load_u64(&g_log.terminal_output_enabled);
 
  // Force logs to stderr if stdout is piped/redirected
  // This prevents logs from contaminating piped/redirected output in snapshot/batch modes
  // Per terminal.h: "force stderr when piped to prevent data corruption"
  if (terminal_is_piped_output()) {
    atomic_store_bool(&g_log.force_stderr, true);
  }
 
  // Close any existing file (atomic load/store)
  int old_file = atomic_load_int(&g_log.file);
  if (lifecycle_is_initialized(&g_log.lifecycle) && old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
    atomic_store_int(&g_log.file, -1);
  }
 
  // Check LOG_LEVEL environment variable
  const char *env_level_str = SAFE_GETENV("LOG_LEVEL");
  if (env_level_str) {
    atomic_store_u64(&g_log.level, (int)parse_log_level_from_env());
  } else {
    atomic_store_u64(&g_log.level, (int)level);
  }
 
  atomic_store_bool(&g_log.level_manually_set, false);
  atomic_store_u64(&g_log.current_size, 0);
 
  if (filename && strcmp(filename, "/dev/null") == 0) {
    g_log.filename[0] = '\0';
    atomic_store_int(&g_log.file, -1);
    atomic_store_bool(&g_log.terminal_output_enabled, false);
  } else if (filename) {
    SAFE_STRNCPY(g_log.filename, filename, sizeof(g_log.filename) - 1);
 
    if (use_mmap) {
      // Lock-free mmap path - writes go to mmap'd file
      asciichat_error_t mmap_result = log_mmap_init_simple(filename, 0);
      if (mmap_result == ASCIICHAT_OK) {
        atomic_store_int(&g_log.file, -1); // No regular fd - using mmap for file output
      } else {
        // Mmap failed - use stderr only (atomic writes, lock-free)
        if (preserve_terminal_output) {
          log_terminal_printf(STDERR_FILENO, "Mmap logging failed for %s, using stderr only (lock-free)\n", filename);
        }
        atomic_store_int(&g_log.file, STDERR_FILENO);
        g_log.filename[0] = '\0';
      }
    } else {
      // Lock-free file I/O path - uses atomic write() syscalls
      int fd = platform_open("log_file", filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
      atomic_store_int(&g_log.file, (fd >= 0) ? fd : STDERR_FILENO);
      if (fd < 0) {
        if (preserve_terminal_output) {
          log_terminal_printf(STDERR_FILENO, "Failed to open log file: %s\n", filename);
        }
        g_log.filename[0] = '\0';
      }
    }
  } else {
    atomic_store_int(&g_log.file, STDERR_FILENO);
    g_log.filename[0] = '\0';
  }
 
  /* Initialize default log format (NULL means use mode-specific default) */
  log_set_format(NULL, false);
 
  /* Mark logging system as initialized (state machine transition) */
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    lifecycle_init(&g_log.lifecycle, "logging");
  }
 
  atomic_store_u64(&g_log.terminal_output_enabled, preserve_terminal_output);
 
  // Reset terminal detection if needed
  if (g_log.terminal_caps_initialized && !g_log.terminal_caps.detection_reliable) {
    g_log.terminal_caps_initialized = false;
  }
 
  // Detect terminal capabilities
  log_redetect_terminal_capabilities();
 
  // NOTE: Color initialization happens separately via log_set_color_scheme()
  // after options are parsed. Logging works without colors until then.
  // NOTE: Grep filter initialization happens in main.c after options_init() completes.
}
 
void log_destroy(void) {
  // Destroy mmap logging first (if active)
  if (log_mmap_is_active()) {
    log_mmap_destroy();
  }
 
  // Cleanup grep filter
  grep_destroy();
 
  /* Mark logging system as shutdown FIRST (state machine transition)
   * This signals worker threads to stop logging immediately before we free memory.
   * This prevents TOCTOU race where a worker thread could see non-NULL format pointer
   * after we've freed it but before lifecycle_shutdown() is called. */
  lifecycle_shutdown(&g_log.lifecycle);
 
  // Cleanup custom format structures: All worker threads have been signaled to stop by this point.
  // Safe to free templates now without use-after-free concerns.
  if (g_log.format) {
    log_template_free(g_log.format);
    g_log.format = NULL;
  }
  if (g_log.format_console_only) {
    log_template_free(g_log.format_console_only);
    g_log.format_console_only = NULL;
  }
  atomic_store_bool(&g_log.has_custom_format, false);
 
  // Lock-free cleanup using atomic operations
  int old_file = atomic_load_int(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  atomic_store_int(&g_log.file, -1);
 
  // Destroy rotation mutex
  lifecycle_shutdown(&g_log.rotation_mutex_lifecycle);
}

void log_system_init(void) {
 
  // Detect terminal capabilities if not already done
  log_redetect_terminal_capabilities();
 
  // Initialize color scheme based on terminal capabilities
  log_init_colors();
}

void log_system_destroy(void) {
  // Unregister session log buffer if registered
  log_clear_session_log_buffer();
  log_search_destroy();
  session_log_buffer_destroy(g_history);
  g_history = NULL;
}
 
void log_set_level(log_level_t level) {
  atomic_store_u64(&g_log.level, (int)level);
  atomic_store_bool(&g_log.level_manually_set, true);
}
 
log_level_t log_get_level(void) {
  return (log_level_t)atomic_load_u64(&g_log.level);
}
 
void log_set_terminal_output(bool enabled) {
  // Respect --quiet flag: if quiet is set, never enable terminal output
  // But allow disabling even if options are unavailable (for shutdown cleanup)
 
  // Only check quiet flag when ENABLING output to avoid deadlock with
  // concurrent logging from other threads (options_get() can deadlock when
  // called while other threads are actively logging due to RCU synchronization)
  if (enabled) {
    const options_t *opts = options_get();
    if (opts && opts->quiet) {
      return; // Silently ignore attempts to enable terminal output when --quiet is set
    }
  }
 
  atomic_store_u64(&g_log.terminal_output_enabled, enabled);
}
 
bool log_get_terminal_output(void) {
  return atomic_load_u64(&g_log.terminal_output_enabled);
}
 
void log_set_force_stderr(bool enabled) {
  atomic_store_u64(&g_log.force_stderr, enabled);
}
 
bool log_get_force_stderr(void) {
  return atomic_load_u64(&g_log.force_stderr);
}
 
void log_set_json_output(int fd) {
  atomic_store_int(&g_log.json_file, fd);
}
 
void log_disable_file_output(void) {
  /* Close the current file if it's not stderr */
  int old_file = atomic_load_int(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  /* Redirect file output to stderr */
  atomic_store_int(&g_log.file, STDERR_FILENO);
  g_log.filename[0] = '\0';
}
 
asciichat_error_t log_set_format(const char *format_str, bool console_only) {
  /* Free old format if it exists */
  if (g_log.format) {
    log_template_free(g_log.format);
    g_log.format = NULL;
  }
  if (g_log.format_console_only) {
    log_template_free(g_log.format_console_only);
    g_log.format_console_only = NULL;
  }
 
  /* Use default format if NULL or empty string */
  const char *format_to_use = (format_str && format_str[0] != '\0') ? format_str : OPT_LOG_TEMPLATE_DEFAULT;
  bool is_custom = (format_str && format_str[0] != '\0');
 
  /* Parse the format string (always parse, never skip) */
  log_template_t *parsed_format = log_template_parse(format_to_use, false);
 
  if (!parsed_format) {
    log_error("Failed to parse log format: %s", format_to_use);
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid log format string");
  }
 
  /* If console_only is true, we also need the default format for file output */
  if (console_only && is_custom) {
    log_template_t *default_format = log_template_parse(OPT_LOG_TEMPLATE_DEFAULT, false);
 
    if (!default_format) {
      log_template_free(parsed_format);
      log_error("Failed to parse default log format");
      return SET_ERRNO(ERROR_INVALID_STATE, "Failed to parse default format");
    }
    g_log.format = default_format;
    g_log.format_console_only = parsed_format;
  } else {
    g_log.format = parsed_format;
    g_log.format_console_only = NULL;
  }
 
  atomic_store_u64(&g_log.has_custom_format, is_custom);
  return ASCIICHAT_OK;
}
 
bool log_lock_terminal(void) {
  bool expected = atomic_load_bool(&g_log.terminal_locked);
  while (!atomic_cas_bool(&g_log.terminal_locked, &expected, true)) {
    // Retry if CAS failed
  }
  atomic_store_u64(&g_log.terminal_owner_thread, (uint64_t)thread_self());
  return expected;
}
 
void log_unlock_terminal(bool previous_state) {
  atomic_store_u64(&g_log.terminal_locked, previous_state);
  if (!previous_state) {
    atomic_store_u64(&g_log.terminal_owner_thread, 0);
  }
}
 
void log_set_flush_delay(unsigned int delay_ms) {
  atomic_store_u64(&g_log.flush_delay_ms, delay_ms);
}
 
void log_truncate_if_large(void) {
  // Log rotation is inherently racy without locks - best-effort only
  // For reliable rotation, use mmap mode or external logrotate
  int file = atomic_load_int(&g_log.file);
  if (file >= 0 && file != STDERR_FILENO && strlen(g_log.filename) > 0) {
    struct stat st;
    if (fstat(file, &st) == 0 && st.st_size > MAX_LOG_SIZE) {
      atomic_store_u64(&g_log.current_size, (size_t)st.st_size);
    }
  }
}
 
/* Helper: Write formatted log entry to file using atomic write() syscall
 * POSIX guarantees write() is atomic for sizes <= PIPE_BUF (typically 4096 bytes)
 * Strips ANSI escape codes from the buffer before writing to ensure clean log files.
 */
static void write_to_log_file_atomic(const char *buffer, int length, const char *stripped_buffer) {
  if (length <= 0 || buffer == NULL) {
    return;
  }
 
  if (length > MAX_LOG_SIZE) {
    return;
  }
 
  int file = atomic_load_int(&g_log.file);
  if (file < 0 || file == STDERR_FILENO) {
    return;
  }
 
  // Use pre-stripped buffer if available (already stripped by caller), otherwise use original
  const char *write_buf = stripped_buffer ? stripped_buffer : buffer;
  size_t write_len = stripped_buffer ? strlen(stripped_buffer) : (size_t)length;
 
  // Single atomic write() call - no locking needed
  ssize_t written = platform_write(file, write_buf, write_len);
  if (written > 0) {
    atomic_fetch_add_u64(&g_log.current_size, (uint64_t)written);
    maybe_rotate_log();
  }
}
 
/* Helper: Format log message header using the format system
 * Returns the number of characters written to the buffer
 */
static int format_log_header(char *buffer, size_t buffer_size, log_level_t level, const char *timestamp,
                             const char *file, int line, const char *func, bool use_colors, uint64_t time_nanoseconds) {
  const log_template_t *format = g_log.format;
  if (!format) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Log format not initialized");
    return -1;
  }
 
  /* Use log_template_apply() to generate the complete formatted output
   * Safety: reload format immediately before use. Format is never freed to avoid TOCTOU races. */
  const log_template_t *format_check = g_log.format;
  if (!format_check) {
    /* Format not available - return minimal output */
    return -1;
  }
 
  int written = log_template_apply(format_check, buffer, buffer_size, level, timestamp, file, line, func,
                                   thread_current_id(), "", use_colors, time_nanoseconds);
  if (written < 0 || written >= (int)buffer_size) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log header");
    return -1;
  }
 
  return written;
}
 
/* Note: Terminal buffering removed for lock-free design.
 * When terminal is locked, other threads' output goes to file only.
 */
 
/* Helper: Write colored log entry to terminal (lock-free)
 * Uses atomic loads for state checks, skips output if terminal is locked by another thread
 */
static _Atomic bool g_terminal_log_colors;
 
static void write_to_terminal_atomic(log_level_t level, const char *timestamp, const char *file, int line,
                                     const char *func, const char *fmt, va_list args, uint64_t time_nanoseconds,
                                     bool capture_history) {
  // Prevent logging during shutdown - if logging lifecycle is being destroyed,
  // bail out to avoid use-after-free of the log template
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return; /* Logging is being shut down, skip */
  }
 
  // Choose output file descriptor using unified routing logic
  bool presenting = ui_controller_is_presenting();
  int fd = presenting ? STDERR_FILENO : terminal_choose_log_fd(level);
  FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
  // Captured session logs still need formatting, but detecting the console
  // again would block their producer behind the presentation worker's writes.
  bool use_colors =
      presenting ? atomic_load(&g_terminal_log_colors) : terminal_should_color_output(fd, options_terminal_settings());
  if (!presenting)
    atomic_store(&g_terminal_log_colors, use_colors);
 
  // Format message first (needed for status screen capture even if terminal output disabled)
  char msg_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args_copy;
  va_copy(args_copy, args);
  int msg_len = safe_vsnprintf(msg_buffer, sizeof(msg_buffer), fmt, args_copy);
  va_end(args_copy);
 
  // Use message buffer directly as clean message
  // Stack allocation avoids heap corruption during shutdown signal handling
  const char *clean_msg = msg_buffer;
 
  // Use format system to generate the complete log line
  char colored_log_line[LOG_MSG_BUFFER_SIZE + LOG_HEADER_BUFFER_SIZE];
  char plain_log_line[LOG_MSG_BUFFER_SIZE + LOG_HEADER_BUFFER_SIZE];
 
  /* Apply format without colors first (plain version for grep matching)
   * Load format pointer once to prevent TOCTOU race condition where another
   * thread frees the format between our check and use. */
  const log_template_t *format = g_log.format_console_only ? g_log.format_console_only : g_log.format;
  int plain_len = 0;
  if (format && lifecycle_is_initialized(&g_log.lifecycle)) { /* Double-check lifecycle is still active */
    plain_len = log_template_apply(format, plain_log_line, sizeof(plain_log_line), level, timestamp, file, line, func,
                                   thread_current_id(), clean_msg, false, time_nanoseconds);
  }
 
  /* For colored output, apply format with colors enabled */
  int colored_len = 0;
  if (use_colors && plain_len > 0) {
    const log_template_t *format_check = g_log.format_console_only ? g_log.format_console_only : g_log.format;
    if (format_check && lifecycle_is_initialized(&g_log.lifecycle)) { /* Re-verify lifecycle before use */
      colored_len = log_template_apply(format_check, colored_log_line, sizeof(colored_log_line), level, timestamp, file,
                                       line, func, thread_current_id(), clean_msg, true, time_nanoseconds);
    }
    /* If applying with colors failed, fall back to plain text */
    if (colored_len <= 0) {
      // Applying with colors failed - use plain text (no colors)
      colored_len = plain_len;
      if (plain_len > 0 && plain_len < (int)sizeof(colored_log_line)) {
        memcpy(colored_log_line, plain_log_line, (size_t)plain_len + 1);
      }
    }
  } else {
    /* No colors - use plain text */
    colored_len = plain_len;
    if (plain_len > 0 && plain_len < (int)sizeof(colored_log_line)) {
      memcpy(colored_log_line, plain_log_line, (size_t)plain_len + 1);
    }
  }
 
  if (capture_history)
    session_log_buffer_append(g_history, colored_len > 0 ? colored_log_line : clean_msg);
 
  // Feed log to registered session log buffer (use colored version if available, otherwise plain)
  atomic_fetch_add_u64_impl(&g_session_log_readers, 1);
  session_log_buffer_t *buf = (session_log_buffer_t *)atomic_ptr_load(&g_log.session_log_buffer);
  if (buf && buf != g_history) {
    if (colored_len > 0 && colored_len < (int)sizeof(colored_log_line)) {
      session_log_buffer_append(buf, colored_log_line);
    } else if (plain_len > 0 && plain_len < (int)sizeof(plain_log_line)) {
      session_log_buffer_append(buf, plain_log_line);
    }
  }
 
  atomic_fetch_sub_u64_impl(&g_session_log_readers, 1);
 
  // The session now owns this log entry. Do not filter or flush a suppressed
  // stdio write: fflush can wait on console/stdio activity on another thread.
  if (presenting)
    return;
 
  // Check if terminal output is enabled (atomic load)
  bool is_enabled = atomic_load_u64(&g_log.terminal_output_enabled);
  if (!is_enabled) {
    // Terminal output disabled - return (status screen already captured)
    return;
  }
 
  // Check if terminal is locked by another thread
  if (atomic_load_u64(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load_u64(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)thread_self()) {
      // Terminal locked by another thread - return
      return;
    }
  }
 
  // Handle message formatting errors for terminal output
  if (msg_len <= 0 || msg_len >= (int)sizeof(msg_buffer)) {
    // Message formatting failed - skip filtering and try direct output
    /* A failed format is omitted; args may already have been consumed. */
    log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "\n");
    (void)fflush(output_stream);
    return;
  }
 
  // Handle log formatting errors
  if (colored_len <= 0 || colored_len >= (int)sizeof(colored_log_line) || plain_len <= 0 ||
      plain_len >= (int)sizeof(plain_log_line)) {
    // Formatting failed - try to output something
    log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s\n", clean_msg);
    (void)fflush(output_stream);
    return;
  }
 
  // Apply grep filter (terminal output only - file logs are unfiltered)
  // Match against PLAIN text (no ANSI codes) so offsets are correct
  size_t match_start = 0, match_len = 0;
  if (!grep_should_output(plain_log_line, &match_start, &match_len)) {
    return; // No match - suppress terminal output
  }
 
  // Output with colors
  if (use_colors) {
    const char **colors = log_get_color_array();
 
    // When grep matches, highlight in the colored line
    if (match_len > 0 && colors != NULL) {
      // Apply highlighting to the full line, respecting existing ANSI codes
      const char *highlighted_line = grep_highlight_colored(colored_log_line, plain_log_line, match_start, match_len);
      log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s\n", highlighted_line);
    } else {
      // No grep match - output colored line as-is
      log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s\n", colored_log_line);
    }
  } else {
    // No colors - output plain line
    log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s\n", plain_log_line);
  }
 
  (void)fflush(output_stream);
}
 
static _Thread_local const char *g_notice_text;
static _Thread_local ui_notice_severity_t g_notice_severity;
static _Thread_local bool g_notice_record_only;
static _Thread_local bool g_notice_unfiltered;
 
static void output_notice(log_level_t level, const char *file, int line, const char *func) {
  if (g_notice_record_only)
    return;
  const char *text = g_notice_text;
  ui_notice_severity_t severity = g_notice_severity;
  g_notice_text = NULL;
  atomic_fetch_add_u64_impl(&g_session_log_readers, 1);
  session_log_buffer_t *buffer = log_get_session_log_buffer();
  session_log_buffer_append(g_history, text);
  if (buffer && buffer != g_history)
    session_log_buffer_append(buffer, text);
  atomic_fetch_sub_u64_impl(&g_session_log_readers, 1);
  // Match the same uncolored template as ordinary terminal logs, including metadata.
  // Keep the complete body for notices that span multiple file-log records.
  size_t capacity = strlen(text) + LOG_MSG_BUFFER_SIZE + LOG_HEADER_BUFFER_SIZE;
  char *plain_log_line = SAFE_MALLOC(capacity, char *);
  char timestamp[LOG_PARSE_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(timestamp);
  const log_template_t *format = g_log.format;
  int plain_len = format && plain_log_line
                      ? log_template_apply(format, plain_log_line, capacity, level, timestamp, file, line, func,
                                           thread_current_id(), text, false, time_ns)
                      : -1;
  size_t start = 0, length = 0;
  if (!GET_OPTION(quiet) &&
      (log_get_terminal_output() || ui_controller_is_presenting() || severity == UI_NOTICE_FATAL) && plain_len > 0 &&
      (size_t)plain_len < capacity && grep_should_output(plain_log_line, &start, &length))
#ifdef EMSCRIPTEN_BUILD
    log_plain("%s", text);
#else
    if (ui_notice_present(severity, text) == ERROR_BUFFER_FULL)
      log_warn_every(US_PER_SEC_INT, "Notice display queue is full; additional notices remain in the log");
#endif
  SAFE_FREE(plain_log_line);
  g_notice_text = text;
}
 
static void notice_logv(ui_notice_severity_t severity, bool unfiltered, const char *file, int line, const char *func,
                        const char *title, const char *format, va_list args) {
  if (!title || !format || !lifecycle_is_initialized(&g_log.lifecycle))
    return;
  char *body = format_message(format, args);
  if (!body)
    return;
  size_t size = strlen(title) + strlen(body) + 2;
  char *message = SAFE_MALLOC(size, char *);
  if (!message) {
    SAFE_FREE(body);
    return;
  }
  safe_snprintf(message, size, "%s\n%s", title, body);
  const char *previous = g_notice_text;
  ui_notice_severity_t previous_severity = g_notice_severity;
  bool previous_unfiltered = g_notice_unfiltered;
  g_notice_text = message;
  g_notice_severity = severity;
  g_notice_unfiltered = unfiltered;
  log_level_t level = severity == UI_NOTICE_FATAL     ? LOG_FATAL
                      : severity == UI_NOTICE_DANGER  ? LOG_ERROR
                      : severity == UI_NOTICE_WARNING ? LOG_WARN
                                                      : LOG_INFO;
  if (strlen(message) < 3000) {
    log_msg(level, file, line, func, "%s", message);
  } else {
    bool previous_record_only = g_notice_record_only;
    g_notice_record_only = true;
    const char *cursor = message;
    while (*cursor) {
      size_t bytes = strlen(cursor);
      if (bytes > 3000) {
        bytes = 3000;
        while (bytes && ((unsigned char)cursor[bytes] & 0xc0) == 0x80)
          --bytes;
        if (!bytes)
          bytes = 3000; // Malformed UTF-8 must still make progress.
      }
      log_msg(level, file, line, func, "%.*s", (int)bytes, cursor);
      cursor += bytes;
    }
    g_notice_record_only = previous_record_only;
    if ((unfiltered || level >= log_get_level()) && atomic_load_int(&g_log.json_file) < 0)
      output_notice(level, file, line, func);
  }
  g_notice_text = previous;
  g_notice_severity = previous_severity;
  g_notice_unfiltered = previous_unfiltered;
  SAFE_FREE(message);
  SAFE_FREE(body);
}
 
void ui_notice_log(ui_notice_severity_t severity, const char *file, int line, const char *func, const char *title,
                   const char *format, ...) {
  va_list args;
  va_start(args, format);
  notice_logv(severity, false, file, line, func, title, format, args);
  va_end(args);
}
 
void ui_notice_announce(const char *file, int line, const char *func, const char *title, const char *format, ...) {
  va_list args;
  va_start(args, format);
  notice_logv(UI_NOTICE_INFO, true, file, line, func, title, format, args);
  va_end(args);
}
 
void log_msg(log_level_t level, const char *file, int line, const char *func, const char *fmt, ...) {
#ifndef __EMSCRIPTEN__
  va_list telemetry_args;
  va_start(telemetry_args, fmt);
  ascii_otel_log((int)level, file, line, func, fmt, telemetry_args);
  va_end(telemetry_args);
#endif
 
  // All state access uses atomic operations - fully lock-free
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  // Safety check: if main format template has been freed during shutdown, skip logging
  // This prevents heap-use-after-free when threads call logging after log_destroy() has freed g_log.format
  if (!g_log.format) {
    return;
  }
 
  uint64_t loaded_level = atomic_load_u64(&g_log.level);
 
  if (level < (log_level_t)loaded_level && !(g_notice_text && g_notice_unfiltered)) {
    return;
  }
  /* =========================================================================
   * MMAP PATH: When mmap logging is active, writes go to mmap'd file
   * ========================================================================= */
  bool mmap_active = log_mmap_is_active();
 
  if (mmap_active) {
    maybe_rotate_log();
 
    va_list args;
    va_start(args, fmt);
    char msg_buffer[LOG_MMAP_MSG_BUFFER_SIZE];
    int msg_len = safe_vsnprintf(msg_buffer, sizeof(msg_buffer), fmt, args);
    va_end(args);
 
    // Truncate at whole line boundaries to avoid UTF-8 issues
    if (msg_len > 0) {
      msg_len = truncate_at_whole_line(msg_buffer, msg_len, sizeof(msg_buffer));
    }
 
    // Validate UTF-8 in formatted message
    validate_log_message_utf8(msg_buffer, "mmap log message");
 
    if (!g_notice_text)
      session_log_buffer_append(g_history, msg_buffer);
    log_mmap_write(level, file, line, func, "%s", msg_buffer);
    platform_systemd_journal_log(level, msg_buffer, "ascii-chat", file, line, func);
 
    if (g_notice_text) {
      output_notice(level, file, line, func);
      return;
    }
 
    // Terminal output (check with atomic loads)
    if (atomic_load_u64(&g_log.terminal_output_enabled) && !atomic_load_bool(&g_log.terminal_locked) &&
        !ui_controller_is_presenting()) {
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      // Choose output stream using unified routing logic
      int fd = terminal_choose_log_fd(level);
      FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
      bool use_colors = terminal_should_color_output(fd, options_terminal_settings());
 
      char header_buffer[LOG_HEADER_BUFFER_SIZE];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), level, time_buf, file, line, func,
                                         use_colors, time_ns);
 
      if (header_len >= 0 && header_len < (int)sizeof(header_buffer)) {
        if (use_colors) {
          const char *colorized_msg = colorize_log_message(msg_buffer);
          const char **colors = log_get_color_array();
          if (colors) {
            log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s%s%s%s\n", header_buffer,
                                colors[LOG_COLOR_RESET], colorized_msg, colors[LOG_COLOR_RESET]);
          } else {
            log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s%s\n", header_buffer,
                                colorized_msg);
          }
        } else {
          log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s%s\n", header_buffer,
                              msg_buffer);
        }
        (void)fflush(output_stream);
      }
    } else {
    }
    return;
  }
  /* =========================================================================
   * FILE I/O PATH: Lock-free using atomic write() syscalls
   * ========================================================================= */
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
  // Format message for file output
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int header_len = format_log_header(log_buffer, sizeof(log_buffer), level, time_buf, file, line, func, false, time_ns);
  if (header_len < 0 || header_len >= (int)sizeof(log_buffer)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log header");
    va_end(args);
    return;
  }
  int msg_len = header_len;
  int formatted_len = safe_vsnprintf(log_buffer + header_len, sizeof(log_buffer) - (size_t)header_len, fmt, args);
  if (formatted_len < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log message");
    va_end(args);
    return;
  }
 
  msg_len += formatted_len;
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
  // Add newline if there's room and message doesn't already end with one
  if (msg_len > 0 && msg_len < (int)sizeof(log_buffer) - 1) {
    if (log_buffer[msg_len - 1] != '\n') {
      log_buffer[msg_len++] = '\n';
      log_buffer[msg_len] = '\0';
    }
  }
  va_end(args);
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "leveled log message");
  platform_systemd_journal_log(level, log_buffer + header_len, "ascii-chat", file, line, func);
 
  // Extract the user message part (without header) for JSON logging
  const char *user_message = log_buffer + header_len;
 
  // For JSON output: strip automatic trailing newline (keep explicit ones)
  char json_message_buf[LOG_MSG_BUFFER_SIZE];
  const char *json_message = user_message;
  size_t user_msg_len = strlen(user_message);
 
  // If message ends with newline and it was added automatically (not in original message)
  if (user_msg_len > 0 && user_message[user_msg_len - 1] == '\n') {
    // The newline was added automatically if the message part didn't end with one
    // before we added it on line 1067. We can check this by looking at msg_len - 1
    // If msg_len >= header_len + 2, then msg_len - 2 would be the char before the newline
    int msg_content_len = msg_len - header_len;
    // NOLINTNEXTLINE(clang-analyzer-security.ArrayBound) - msg_content_len > 1 bounds check above
    if (msg_content_len > 1 && log_buffer[msg_len - 2] != '\n') {
      // Newline was added automatically - strip it for JSON
      if (user_msg_len - 1 < sizeof(json_message_buf)) {
        memcpy(json_message_buf, user_message, user_msg_len - 1);
        json_message_buf[user_msg_len - 1] = '\0';
        json_message = json_message_buf;
      }
    }
  }
 
  // Check if JSON format is enabled
  int json_fd = atomic_load_int(&g_log.json_file);
  bool json_format_enabled = (json_fd >= 0);
 
  // If JSON format is enabled, output ONLY JSON (skip text output)
  if (json_format_enabled) {
    session_log_buffer_append(g_history, log_buffer);
    // Output JSON to the JSON file descriptor
    log_json_write(json_fd, level, time_ns, file, line, func, json_message);
    // Also output JSON to console using unified routing logic, respecting quiet flag
    if (atomic_load_u64(&g_log.terminal_output_enabled)) {
      int console_fd = terminal_choose_log_fd(level);
      log_json_write(console_fd, level, time_ns, file, line, func, json_message);
    }
  } else {
    // Text format: output to file and terminal
    // No heap allocation - use log_buffer directly
    // Write to file (atomic write syscall) - use original buffer (with ANSI codes)
    int file_fd = (int)atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
    }
 
    if (g_notice_text) {
      output_notice(level, file, line, func);
      return;
    }
 
    // Write to terminal (atomic state checks)
    va_list args_terminal;
    va_start(args_terminal, fmt);
    write_to_terminal_atomic(level, time_buf, file, line, func, fmt, args_terminal, time_ns, true);
    va_end(args_terminal);
  }
}
 
void log_terminal_msg(log_level_t level, const char *file, int line, const char *func, const char *fmt, ...) {
  // Lock-free: only uses atomic loads, no mutex
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  if (level < (log_level_t)atomic_load_u64(&g_log.level)) {
    return;
  }
 
  // Terminal output only - no file/mmap writing
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
 
  va_list args;
  va_start(args, fmt);
  write_to_terminal_atomic(level, time_buf, file, line, func, fmt, args, time_ns, true);
  va_end(args);
}
 
static void log_colored_msg_internal(log_level_t level, const char *file, int line, const char *func,
                                     const char *colored_message, const char *plain_message, bool persist) {
  if (!colored_message || !plain_message || !lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (level < (log_level_t)atomic_load_u64(&g_log.level)) {
    return;
  }
 
  bool presenting = ui_controller_is_presenting();
  int fd = presenting ? STDERR_FILENO : terminal_choose_log_fd(level);
  bool use_colors =
      presenting ? atomic_load(&g_terminal_log_colors) : terminal_should_color_output(fd, options_terminal_settings());
  if (!presenting) {
    atomic_store(&g_terminal_log_colors, use_colors);
  }
 
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
 
  char colored_header[LOG_HEADER_BUFFER_SIZE] = {0};
  char plain_header[LOG_HEADER_BUFFER_SIZE] = {0};
  if (format_log_header(colored_header, sizeof(colored_header), level, time_buf, file, line, func, use_colors,
                        time_ns) < 0) {
    colored_header[0] = '\0';
  }
  if (format_log_header(plain_header, sizeof(plain_header), level, time_buf, file, line, func, false, time_ns) < 0) {
    plain_header[0] = '\0';
  }
 
  char colored_entry[LOG_TERMINAL_ENTRY_BUFFER_SIZE];
  char plain_entry[LOG_TERMINAL_ENTRY_BUFFER_SIZE];
  safe_snprintf(colored_entry, sizeof(colored_entry), "%s%s", colored_header, colored_message);
  safe_snprintf(plain_entry, sizeof(plain_entry), "%s%s", plain_header, plain_message);
 
  int json_fd = atomic_load_int(&g_log.json_file);
  if (persist && json_fd >= 0) {
    log_json_write(json_fd, level, time_ns, file, line, func, plain_message);
  } else if (persist && log_mmap_is_active()) {
    log_mmap_write(level, file, line, func, "%s", plain_message);
  } else if (persist) {
    int file_fd = atomic_load_int(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(plain_entry, (int)strlen(plain_entry), NULL);
    }
  }
 
  const char *terminal_message = use_colors ? colored_entry : plain_entry;
  session_log_buffer_append(g_history, json_fd >= 0 ? plain_message : terminal_message);
  atomic_fetch_add_u64_impl(&g_session_log_readers, 1);
  session_log_buffer_t *buffer = (session_log_buffer_t *)atomic_ptr_load(&g_log.session_log_buffer);
  if (buffer && buffer != g_history) {
    session_log_buffer_append(buffer, json_fd >= 0 ? plain_message : terminal_message);
  }
  atomic_fetch_sub_u64_impl(&g_session_log_readers, 1);
 
  if (presenting || !atomic_load_u64(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load_u64(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load_u64(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)thread_self()) {
      return;
    }
  }
 
  if (json_fd >= 0) {
    log_json_write(fd, level, time_ns, file, line, func, plain_message);
    return;
  }
 
  size_t match_start = 0;
  size_t match_len = 0;
  if (!grep_should_output(plain_entry, &match_start, &match_len)) {
    return;
  }
 
  const char *output = terminal_message;
  if (use_colors && match_len > 0 && log_get_color_array() != NULL) {
    output = grep_highlight_colored(colored_entry, plain_entry, match_start, match_len);
  }
  size_t output_len = strlen(output);
  ui_controller_write(fd, output, output_len);
  if (output_len == 0 || output[output_len - 1] != '\n') {
    ui_controller_write(fd, "\n", 1);
  }
}
 
void log_colored_msg_impl(log_level_t level, const char *file, int line, const char *func, const char *colored_message,
                          const char *plain_message) {
  log_colored_msg_internal(level, file, line, func, colored_message, plain_message, true);
}
 
void log_terminal_colored_msg_impl(log_level_t level, const char *file, int line, const char *func,
                                   const char *colored_message, const char *plain_message) {
  log_colored_msg_internal(level, file, line, func, colored_message, plain_message, false);
}
 
void log_plain_msg(const char *fmt, ...) {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "plain text log");
 
  session_log_buffer_append(g_history, log_buffer);
 
  // Write to mmap if active
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    // Write to file with headers (atomic write syscall)
    int file_fd = atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      // Add header with timestamp and log level to file output
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      char header_buffer[LOG_HEADER_BUFFER_SIZE];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), LOG_INFO, time_buf, "lib/log/logging.c",
                                         0, "log_plain_msg", false, time_ns);
 
      if (header_len > 0) {
        write_to_log_file_atomic(header_buffer, header_len, NULL);
      }
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
      write_to_log_file_atomic("\n", 1, NULL);
    }
  }
 
  // Preserve diagnostics in the log file during shutdown without repainting the terminal.
  if (shutdown_is_requested())
    return;
 
  // Terminal output (atomic state checks)
  if (!atomic_load_u64(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load_u64(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load_u64(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)thread_self()) {
      return;
    }
  }
 
  // Check if JSON format is enabled
  int json_fd = atomic_load_int(&g_log.json_file);
  bool json_format_enabled = (json_fd >= 0);
 
  if (json_format_enabled) {
    // Output JSON for plain messages too
    uint64_t time_ns = time_get_realtime_ns();
    int console_fd = terminal_choose_log_fd(LOG_INFO);
    log_json_write(console_fd, LOG_INFO, time_ns, __FILE__, __LINE__, "log_plain_msg", log_buffer);
  } else {
    // Choose output stream using unified routing logic (LOG_INFO level)
    int fd = terminal_choose_log_fd(LOG_INFO);
    FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
 
    // Apply colorization for TTY output
    if (terminal_should_color_output(fd, options_terminal_settings())) {
      const char *colorized_msg = colorize_log_message(log_buffer);
      log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s\n", colorized_msg);
    } else {
      log_terminal_printf(output_stream == stdout ? STDOUT_FILENO : STDERR_FILENO, "%s\n", log_buffer);
    }
    (void)fflush(output_stream);
  }
}
 
// Helper for log_plain_stderr variants (lock-free)
static void log_plain_stderr_internal_atomic(const char *fmt, va_list args, bool add_newline) {
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "stderr log");
  session_log_buffer_append(g_history, log_buffer);
 
  // Write to mmap if active
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    // Write to file with headers (atomic write syscall)
    int file_fd = atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      // Add header with timestamp and log level to file output
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      char header_buffer[LOG_HEADER_BUFFER_SIZE];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), LOG_INFO, time_buf, "lib/log/logging.c",
                                         0, "log_plain_stderr_msg", false, time_ns);
 
      if (header_len > 0) {
        write_to_log_file_atomic(header_buffer, header_len, NULL);
      }
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
      if (add_newline) {
        write_to_log_file_atomic("\n", 1, NULL);
      }
    }
  }
 
  // Terminal output (atomic state checks)
  if (!atomic_load_u64(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load_u64(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load_u64(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)thread_self()) {
      return;
    }
  }
 
  // Write to stderr without colorization (plain output)
  if (add_newline) {
    log_terminal_printf(STDERR_FILENO, "%s\n", log_buffer);
  } else {
    log_terminal_printf(STDERR_FILENO, "%s", log_buffer);
  }
  (void)fflush(stderr);
}
 
void log_plain_stderr_msg(const char *fmt, ...) {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stderr_internal_atomic(fmt, args, true);
  va_end(args);
}
 
void log_plain_stderr_nonewline_msg(const char *fmt, ...) {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stderr_internal_atomic(fmt, args, false);
  va_end(args);
}

static void log_plain_stdout_internal_atomic(const char *fmt, va_list args, bool add_newline) {
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "stdout log");
  session_log_buffer_append(g_history, log_buffer);
 
  // Write to mmap if active
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    // Write to file with headers (atomic write syscall)
    int file_fd = atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDOUT_FILENO) {
      // Add header with timestamp and log level to file output
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      char header_buffer[LOG_HEADER_BUFFER_SIZE];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), LOG_INFO, time_buf, "lib/log/logging.c",
                                         0, "log_plain_stdout_msg", false, time_ns);
 
      if (header_len > 0) {
        write_to_log_file_atomic(header_buffer, header_len, NULL);
      }
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
      if (add_newline) {
        write_to_log_file_atomic("\n", 1, NULL);
      }
    }
  }
 
  // Terminal output (atomic state checks)
  if (!atomic_load_u64(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load_u64(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load_u64(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)thread_self()) {
      return;
    }
  }
 
  // Write to stdout without colorization (plain output)
  if (add_newline) {
    log_terminal_printf(STDOUT_FILENO, "%s\n", log_buffer);
  } else {
    log_terminal_printf(STDOUT_FILENO, "%s", log_buffer);
  }
}
 
void log_plain_stdout_msg(const char *fmt, ...) {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stdout_internal_atomic(fmt, args, true);
  va_end(args);
}
 
void log_file_msg(const char *fmt, ...) {
  if (!lifecycle_is_initialized(&g_log.lifecycle)) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "file-only log");
  session_log_buffer_append(g_history, log_buffer);
 
  // Write to mmap if active, else to file
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    int file_fd = atomic_load_u64(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len, NULL);
      write_to_log_file_atomic("\n", 1, NULL);
    }
  }
}
 
static const char *log_network_direction_label(remote_log_direction_t direction) {
  switch (direction) {
  case REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT:
    return "server→client";
  case REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER:
    return "client→server";
  default:
    return "network";
  }
}
 
asciichat_error_t log_net_message(struct acip_transport *transport, log_level_t level, remote_log_direction_t direction,
                                  const char *file, int line, const char *func, const char *fmt, ...) {
  if (!fmt) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Format string is NULL");
  }
 
  va_list args_copy;
  va_start(args_copy, fmt);
  asciichat_errno_scope_t format_scope = errno_checkpoint();
  char *formatted = format_message(fmt, args_copy);
  va_end(args_copy);
 
  if (!formatted) {
    asciichat_error_context_t current;
    asciichat_error_t current_error = errno_peek_since(format_scope, &current) ? current.code : ASCIICHAT_OK;
    if (current_error == ASCIICHAT_OK) {
      current_error = SET_ERRNO(ERROR_MEMORY, "Failed to format network log message");
    }
    return current_error;
  }
 
  asciichat_error_t send_result = ASCIICHAT_OK;
  if (!transport) {
    send_result = SET_ERRNO(ERROR_INVALID_PARAM, "Missing log transport");
    log_msg(LOG_WARN, file, line, func, "Skipping remote log message: transport unavailable");
  } else {
    send_result = acip_send_remote_log(transport, level, direction, formatted);
    if (send_result != ASCIICHAT_OK) {
      log_msg(LOG_WARN, file, line, func, "Failed to send remote log message: %s", asciichat_error_string(send_result));
    }
  }
 
  const char *direction_label = log_network_direction_label(direction);
  log_msg(level, file, line, func, "[NET %s] %s", direction_label, formatted);
 
  SAFE_FREE(formatted);
  return send_result;
}
 
/* ============================================================================
 * Color Helper Functions
 * ============================================================================ */
 
/* Initialize terminal capabilities if not already done */
static void init_terminal_capabilities(void) {
  // Guard against recursion - this can be called indirectly via log_get_color_array()
  // from detect_terminal_capabilities() which uses logging
  if (g_log.terminal_caps_detecting) {
    return;
  }
 
  // Terminal capabilities should already be initialized via log_system_init()
  // This function is now just a safety guard for any edge cases before init
  if (!g_log.terminal_caps_initialized) {
    // Set detecting flag to prevent recursion
    g_log.terminal_caps_detecting = true;
 
    // Use safe fallback during very early initialization to avoid recursion
    g_log.terminal_caps.color_level = TERM_COLOR_16;
    g_log.terminal_caps.capabilities = TERM_CAP_COLOR_16;
    g_log.terminal_caps.color_count = 16;
    g_log.terminal_caps.detection_reliable = false;
    g_log.terminal_caps_initialized = true;
 
    // Clear detecting flag
    g_log.terminal_caps_detecting = false;
  }
}
 
/* Re-detect terminal capabilities after logging is initialized */
void log_redetect_terminal_capabilities(void) {
 
  // Guard against recursion
  if (g_log.terminal_caps_detecting) {
    return;
  }
 
  // Detect if not initialized, or if we're using defaults (not reliably detected)
  // This ensures we get proper detection after logging is ready, replacing any defaults
  // Once we have reliable detection, never re-detect to keep colors consistent
  if (!g_log.terminal_caps_initialized || !g_log.terminal_caps.detection_reliable) {
    g_log.terminal_caps_detecting = true;
    detect_terminal_capabilities_into(options_terminal_settings(), &g_log.terminal_caps);
    g_log.terminal_caps_detecting = false;
    g_log.terminal_caps_initialized = true;
 
    // Now log the capabilities AFTER colors are set, so this log uses the correct colors
    log_debug("Terminal capabilities: color_level=%d, capabilities=0x%x, utf8=%s, fps=%d",
              g_log.terminal_caps.color_level, g_log.terminal_caps.capabilities,
              g_log.terminal_caps.utf8_support ? "yes" : "no", g_log.terminal_caps.desired_fps);
 
    // Now that we've detected once with reliable results, keep these colors consistent for all future logs
  } else {
  }
  // Once initialized with reliable detection, never re-detect to keep colors consistent
}
 
/* Get the appropriate color array based on terminal capabilities */
static _Thread_local colorscheme_palette_t live_log_palette;
static _Thread_local const char *live_log_codes[COLORSCHEME_LOG_COLOR_COUNT];
 
const char **log_get_color_array(void) {
  init_terminal_capabilities();
  colorscheme_current_palette(&live_log_palette, g_log.terminal_caps.color_level);
  for (int i = 0; i < 8; ++i)
    live_log_codes[i] = live_log_palette.codes[i];
  return live_log_codes;
}
 
int log_get_color_mode(void) {
  init_terminal_capabilities();
  return g_log.terminal_caps.color_level;
}
 
const char *log_get_foreground_color(void) {
  log_get_color_array();
  return live_log_palette.foreground;
}
 
const char *log_level_color(log_color_t color) {
  if (color == LOG_COLOR_WHITE)
    return "\033[37m";
  const char **colors = log_get_color_array();
  if (colors == NULL) {
    return ""; /* Return empty string if colors not available */
  }
  if (color >= 0 && color <= LOG_COLOR_RESET) {
    return colors[color];
  }
  return colors[LOG_COLOR_RESET]; /* Return reset color if invalid */
}
 
const char *log_level_color_for_output(log_color_t color, bool enabled) {
  if (!enabled)
    return "";
  if (color == LOG_COLOR_WHITE)
    return "\033[37m";
  static _Thread_local colorscheme_palette_t palette;
  // The caller already resolved whether this destination accepts color. Do not
  // re-check stdout here: reports can target a terminal independent of stdout.
  terminal_color_mode_t mode = GET_OPTION(color_mode);
  if (mode == TERM_COLOR_AUTO)
    mode = (terminal_color_mode_t)log_get_color_mode();
  if (mode == TERM_COLOR_NONE && GET_OPTION(color_mode) == TERM_COLOR_AUTO)
    mode = TERM_COLOR_16;
  colorscheme_current_palette(&palette, mode);
  return palette.codes[color >= 0 && color <= LOG_COLOR_RESET ? color : LOG_COLOR_RESET];
}
 
/* ============================================================================
 * Color Scheme Management
 * ============================================================================ */
 
void log_init_colors(void) {
  if (g_log.terminal_caps_detecting || !lifecycle_is_initialized(&g_log.lifecycle))
    return;
  colorscheme_get_active_scheme();
}
 
void log_set_color_scheme(const color_scheme_t *scheme) {
  colorscheme_apply(scheme);
}
 
/* ============================================================================
 * Lock-Free MMAP Logging Integration
 * ============================================================================ */
 
asciichat_error_t log_enable_mmap(const char *log_path) {
  return log_enable_mmap_sized(log_path, 0); /* Use default size */
}
 
asciichat_error_t log_enable_mmap_sized(const char *log_path, size_t max_size) {
  if (!log_path) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "log_path is required");
  }
 
  // Initialize mmap logging - text is written directly to the mmap'd file
  asciichat_error_t result = log_mmap_init_simple(log_path, max_size);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  log_info("Lock-free mmap logging enabled: %s", log_path);
  return ASCIICHAT_OK;
}
 
void log_disable_mmap(void) {
  if (log_mmap_is_active()) {
    log_mmap_destroy();
    log_info("Lock-free mmap logging disabled");
  }
}
 
/* ============================================================================
 * Shutdown Logging Control
 * ============================================================================ */
 
void log_shutdown_begin(void) {
  if (g_log.shutdown_in_progress) {
    return; /* Already in shutdown phase */
  }
 
  /* Save current terminal output state and disable console output */
  g_log.shutdown_saved_terminal_output = atomic_load_u64(&g_log.terminal_output_enabled);
  atomic_store_bool(&g_log.terminal_output_enabled, false);
  g_log.shutdown_in_progress = true;
}
 
void log_shutdown_end(void) {
  if (!g_log.shutdown_in_progress) {
    return; /* Not in shutdown phase, skip terminal state restoration */
  }
 
  /* Restore previous terminal output state */
  atomic_store_u64(&g_log.terminal_output_enabled, g_log.shutdown_saved_terminal_output);
  g_log.shutdown_in_progress = false;
}

void log_cleanup_colors(void) {}
 
/* ============================================================================
 * Session Log Buffer Registration
 * ============================================================================ */

void log_set_session_log_buffer(session_log_buffer_t *buf) {
  atomic_ptr_store(&g_log.session_log_buffer, (void *)buf);
}

void log_clear_session_log_buffer(void) {
  atomic_ptr_store(&g_log.session_log_buffer, NULL);
  // An atomic pointer swap alone does not protect a writer that loaded the old
  // buffer. Wait for those writers before the UI releases its storage.
  while (atomic_load_u64_impl(&g_session_log_readers))
    platform_sleep_us(100);
}

session_log_buffer_t *log_get_session_log_buffer(void) {
  return (session_log_buffer_t *)atomic_ptr_load(&g_log.session_log_buffer);
}
 
/* ============================================================================
 * Log Recoloring for Plain Text Entries
 * ============================================================================ */

size_t log_recolor_plain_entry(const char *plain_line, char *colored_buf, size_t buf_size) {
  if (!plain_line || !colored_buf || buf_size < 128) {
    return 0;
  }
 
  static char work_buffer[LOG_MSG_BUFFER_SIZE + 1024];
 
  // Parse format FIRST, regardless of color availability
  // Parse format: [TIMESTAMP] [LEVEL] [tid:THREAD_ID] FILE:LINE in FUNC(): MESSAGE
  const char *p = plain_line;
 
  // Extract timestamp [TIMESTAMP]
  if (*p != '[') {
    return 0; // Invalid format
  }
  p++;
  const char *timestamp_start = p;
 
  // Find the closing ] for timestamp - look for pattern that ends with proper timestamp format
  // Valid timestamp: HH:MM:SS.UUUUUU (time with microseconds, no date)
  while (*p && *p != ']') {
    p++;
  }
  if (*p != ']') {
    return 0; // Malformed - no closing bracket
  }
 
  size_t timestamp_len = p - timestamp_start;
  char timestamp[LOG_PARSE_TIMESTAMP_BUFFER_SIZE];
  if (timestamp_len >= sizeof(timestamp) || timestamp_len == 0) {
    return 0; // Invalid timestamp - empty or too long
  }
  SAFE_STRNCPY(timestamp, timestamp_start, timestamp_len);
  timestamp[timestamp_len] = '\0';
  p++; // Skip ]
 
  // Skip whitespace after timestamp
  while (*p && *p == ' ') {
    p++;
  }
 
  // Extract level [LEVEL]
  if (*p != '[') {
    return 0; // Missing opening bracket for level
  }
  p++;
  const char *level_start = p;
  while (*p && *p != ']') {
    p++;
  }
  if (*p != ']') {
    return 0; // Missing closing bracket for level
  }
  size_t level_len = p - level_start;
  char level_str[LOG_LEVEL_BUFFER_SIZE];
  if (level_len >= sizeof(level_str) || level_len == 0) {
    return 0; // Level string too long or empty
  }
  memcpy(level_str, level_start, level_len);
  level_str[level_len] = '\0';
 
  // Determine log level for color selection
  log_level_t level = LOG_INFO; // Default
  if (strstr(level_str, "DEV") || strstr(level_str, "DEBUG")) {
    level = LOG_DEBUG;
  } else if (strstr(level_str, "INFO")) {
    level = LOG_INFO;
  } else if (strstr(level_str, "WARN")) {
    level = LOG_WARN;
  } else if (strstr(level_str, "ERROR")) {
    level = LOG_ERROR;
  } else if (strstr(level_str, "FATAL")) {
    level = LOG_FATAL;
  }
 
  p++; // Skip ]
 
  // Skip whitespace after level
  while (*p && *p == ' ') {
    p++;
  }
 
  // Extract thread ID [tid:THREAD_ID] - optional field
  uint64_t tid = 0;
  if (*p == '[' && strncmp(p, "[tid:", 5) == 0) {
    p += 5;
    char *tid_end = NULL;
    tid = strtoull(p, &tid_end, 10);
    if (!tid_end || *tid_end != ']') {
      // tid parsing failed, but continue anyway (might still recover)
      // Try to find the closing bracket
      while (*p && *p != ']') {
        p++;
      }
      if (*p == ']') {
        p++;
      }
    } else {
      p = tid_end + 1; // Skip past the ]
    }
    // Skip whitespace after tid
    while (*p && *p == ' ') {
      p++;
    }
  }
  // tid is optional - continue parsing if not present
 
  // Extract file path (everything up to :LINE)
  const char *file_start = p;
  while (*p && *p != ':') {
    p++;
  }
  if (*p != ':') {
    return 0; // Malformed
  }
  size_t file_len = p - file_start;
  char file_path[LOG_FILE_PATH_BUFFER_SIZE];
  if (file_len >= sizeof(file_path)) {
    return 0;
  }
  memcpy(file_path, file_start, file_len);
  file_path[file_len] = '\0';
  p++; // Skip :
 
  // Extract line number (digits only)
  int line_num = 0;
  const char *line_start = p;
  while (*p && isdigit((unsigned char)*p)) {
    p++;
  }
  if (p == line_start) {
    return 0; // No line number
  }
  line_num = (int)strtol(line_start, NULL, 10);
 
  // Skip whitespace and find "in" keyword (be very lenient)
  while (*p && (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r')) {
    p++;
  }
 
  // Try to find "in " - if not found, might still be valid, just harder to parse
  if (strncmp(p, "in ", 3) == 0) {
    p += 3; // Skip "in "
  } else if (*p == 'i' && *(p + 1) == 'n' && (*(p + 2) == ' ' || *(p + 2) == '\t')) {
    // Allow tab after "in"
    p += 2; // Skip "in"
    while (*p && (*p == ' ' || *p == '\t')) {
      p++;
    }
  } else {
    // Missing "in" keyword - this is a format error
    return 0;
  }
 
  // Extract function name (everything up to "()")
  const char *func_start = p;
  while (*p && *p != '(') {
    p++;
  }
  if (*p != '(' || func_start == p) {
    return 0; // Missing function name or parentheses
  }
  size_t func_len = p - func_start;
 
  // Trim trailing whitespace from function name
  while (func_len > 0 && (func_start[func_len - 1] == ' ' || func_start[func_len - 1] == '\t')) {
    func_len--;
  }
 
  char func_name[LOG_FUNC_NAME_BUFFER_SIZE];
  if (func_len >= sizeof(func_name)) {
    func_len = sizeof(func_name) - 1;
  }
  if (func_len > 0) {
    memcpy(func_name, func_start, func_len);
  }
  func_name[func_len] = '\0';
 
  // Skip "(" and ")" - be lenient about what's between them
  if (*p == '(') {
    p++;
    while (*p && *p != ')') {
      p++;
    }
    if (*p == ')') {
      p++;
    }
  }
 
  // Skip whitespace and optional colon(s) and other separators
  while (*p && (*p == ' ' || *p == ':' || *p == '\t')) {
    p++;
  }
 
  // Remaining is the message
  const char *message = p;
 
  // Format is valid, get colors from logging system
  const char **colors = log_get_color_array();
  if (!colors) {
    // No colors available, return plain text
    static bool warned_once = false;
    if (!warned_once) {
      log_debug("Colors not initialized - returning plain text");
      warned_once = true;
    }
    size_t len = strlen(plain_line);
    if (len >= buf_size) {
      return 0;
    }
    SAFE_STRNCPY(colored_buf, plain_line, buf_size - 1);
    colored_buf[buf_size - 1] = '\0';
    return len;
  }
 
  // Build colored output
  const char *level_color = colors[level];
  const char *reset = colors[LOG_COLOR_RESET];
  const char *file_color = colors[1]; // DEBUG/Cyan
  const char *line_color = colors[6]; // GREY (matching tid)
  const char *func_color = colors[0]; // DEV/Orange
  const char *tid_color = colors[6];  // GREY
 
  int len = safe_snprintf(work_buffer, sizeof(work_buffer),
                          "[%s%s%s] [%s%s%s] [tid:%s%llu%s] %s%s%s:%s%d%s in %s%s%s(): %s", level_color, timestamp,
                          reset, level_color, level_str, reset, tid_color, (unsigned long long)tid, reset, file_color,
                          file_path, reset, line_color, line_num, reset, func_color, func_name, reset, message);
 
  if (len <= 0 || len >= (int)sizeof(work_buffer)) {
    return 0;
  }
 
  // Colorize the message part
  const char *colorized_msg = colorize_log_message(message);
  len = safe_snprintf(work_buffer, sizeof(work_buffer),
                      "[%s%s%s] [%s%s%s] [tid:%s%llu%s] %s%s%s:%s%d%s in %s%s%s(): %s", level_color, timestamp, reset,
                      level_color, level_str, reset, tid_color, (unsigned long long)tid, reset, file_color, file_path,
                      reset, line_color, line_num, reset, func_color, func_name, reset, colorized_msg);
 
  if (len <= 0 || len >= (int)sizeof(work_buffer) || len >= (int)buf_size) {
    return 0;
  }
 
  SAFE_STRNCPY(colored_buf, work_buffer, buf_size - 1);
  colored_buf[buf_size - 1] = '\0';
  return (size_t)len;
}
 
// Internal implementation - don't use directly, use log_console_impl macro
void log_console_impl(log_level_t level, const char *file, int line, const char *func, const char *message) {
  if (!message) {
    return;
  }
 
  int fd = terminal_choose_log_fd(level);
  if (fd < 0) {
    return;
  }
 
  // Presentation owns terminal output, but never changes the caller's logging preference.
  if (ui_controller_is_presenting() && (ui_controller_is_owner() || platform_isatty(fd))) {
    return;
  }
 
  // Check if JSON output is enabled (json_file >= 0 means enabled)
  int json_fd = atomic_load_int(&g_log.json_file);
  bool use_json = (json_fd >= 0);
 
  if (use_json) {
    // Use async-safe JSON formatter (safe for signal handlers)
    log_json_async_safe(fd, level, file, line, func, message);
  } else {
    // Text output to console using platform_write_all to handle partial writes
    size_t msg_len = strlen(message);
    ui_controller_write(fd, message, msg_len);
    if (msg_len == 0 || message[msg_len - 1] != '\n') {
      ui_controller_write(fd, "\n", 1);
    }
  }
}

void *log_get_template(void) {
  return (void *)g_log.format;
}