client/main.c

Go to the documentation of this file.

 
#include "main.h"
#include "../main.h" // Global exit API
#include "server.h"
#include "protocol.h"
#include "crypto.h"
#include "display.h"
#include "capture.h"
#include "audio.h"
#include <ascii-chat/ui/splash.h>
#include <ascii-chat/log/search.h>
#include <ascii-chat/session/session_log_buffer.h>
#include "session/client_like.h"
#include <ascii-chat/audio/analysis.h>
#include <ascii-chat/video/webcam/webcam.h>
#include <ascii-chat/ui/mdns.h>
#include <ascii-chat/network/mdns/discovery.h>
 
#include <ascii-chat/platform/abstraction.h>
#include <ascii-chat/platform/init.h>
#include <ascii-chat/platform/terminal.h>
#include <ascii-chat/platform/symbols.h>
#include <ascii-chat/platform/system.h>
#include <ascii-chat/common.h>
#include <ascii-chat/common/buffer_sizes.h>
#include <ascii-chat/log/log.h>
#include <ascii-chat/log/json.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/options/rcu.h> // For RCU-based options access
#include <ascii-chat/util/time.h>   // For time macros
#include <ascii-chat/util/url.h>    // For URL parsing and WebSocket detection
#include <ascii-chat/buffer_pool.h>
#include <ascii-chat/video/ascii/palette.h>
#include <ascii-chat/network/network.h>
#include <ascii-chat/network/tcp/client.h>
#include <ascii-chat/network/client.h>
#include <ascii-chat/network/acip/acds_client.h>
#include <ascii-chat/util/ip.h>
#include <ascii-chat/network/acip/acds.h>
#include <ascii-chat/network/acip/client.h>
#include "connection_state.h"
#include <ascii-chat/util/path.h>
#include <ascii-chat/app_callbacks.h>
 
#ifndef NDEBUG
#include <ascii-chat/debug/sync.h>
#ifdef DEBUG_MEMORY
#include <ascii-chat/debug/memory.h>
#endif
#endif
 
#include <signal.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ascii-chat/atomic.h>
#ifndef _WIN32
#include <unistd.h>
#endif
#include <fcntl.h>
 
/* ============================================================================
 * Global State Variables
 * ============================================================================ */
 
thread_pool_t *g_client_worker_pool = NULL;
 
app_client_t *g_client = NULL;
 
struct webrtc_peer_manager *g_peer_manager = NULL;
 
typedef struct {
  connection_attempt_context_t connection_ctx; // Fallback connection context (embedded)
  const char *discovered_address;              // From LAN/session discovery
  int discovered_port;                         // From LAN/session discovery
  int reconnect_attempt;                       // Current reconnection attempt number
  bool has_ever_connected;                     // Track if connection ever succeeded
} client_session_state_t;
 
static client_session_state_t g_client_session = {0};
 
/* Signal handling is now centralized in src/main.c via setup_signal_handlers()
 * Client mode uses set_interrupt_callback(server_connection_shutdown) to register
 * its network shutdown as the interrupt handler. SIGWINCH is still client-specific.
 */
 
#ifndef _WIN32
static void client_handle_sigwinch(int sigwinch) {
  (void)(sigwinch);
 
  // Terminal was resized, update dimensions and recalculate aspect ratio
  // ONLY if both width and height are auto (not manually set)
  if (GET_OPTION(auto_width) && GET_OPTION(auto_height)) {
    // Get terminal size and update via proper RCU setters
    unsigned short int term_width, term_height;
    if (get_terminal_size(&term_width, &term_height) == ASCIICHAT_OK) {
      options_set_int("width", (int)term_width);
      options_set_int("height", (int)term_height);
    }
 
    // Send new size to server if connected
    if (server_connection_is_active()) {
      if (threaded_send_terminal_size_with_auto_detect((int)terminal_get_effective_width(),
                                                       (int)terminal_get_effective_height()) < 0) {
        log_warn("Failed to send terminal capabilities to server: %s", network_error_string());
      } else {
        display_full_reset();
        log_set_terminal_output(false);
      }
    }
  }
}
#endif
 
static void shutdown_client() {
  // Guard against double cleanup (can be called explicitly + via atexit)
  static bool shutdown_done = false;
  if (shutdown_done) {
    return;
  }
  shutdown_done = true;
  log_debug("[SHUTDOWN] 1. Starting shutdown");
 
  // Set global shutdown flag to stop all threads
  signal_exit();
 
  // Stop splash animation thread before any resource cleanup
  splash_intro_done();
 
  // IMPORTANT: Stop all protocol threads BEFORE cleaning up resources
  // protocol_stop_connection() shuts down the socket to interrupt blocking recv(),
  // then waits for the data reception thread and capture thread to exit.
  // This prevents race conditions where threads access freed resources.
  log_debug("[SHUTDOWN] 4. About to call protocol_stop_connection()");
  protocol_stop_connection();
 
  // Destroy client worker thread pool (all threads already stopped by protocol_stop_connection)
  if (g_client_worker_pool) {
    thread_pool_destroy(g_client_worker_pool);
    g_client_worker_pool = NULL;
  }
 
  // Destroy application client context
  log_debug("[SHUTDOWN] 8. About to destroy app_client");
  if (g_client) {
    app_client_destroy(&g_client);
  }
 
  // Now safe to cleanup server connection (socket already closed by protocol_stop_connection)
  // Legacy cleanup - will be removed after full migration to tcp_client
  log_debug("[SHUTDOWN] 10. About to cleanup server connection");
  server_connection_cleanup();
 
  // Cleanup capture subsystems (capture thread already stopped by protocol_stop_connection)
  log_debug("[SHUTDOWN] 12. About to cleanup capture");
  audio_cleanup();
  capture_cleanup();
 
  // Cleanup H.265 encoder
  if (g_h265_encoder) {
    log_debug("[SHUTDOWN] 14a. About to cleanup H.265 encoder");
    h265_encoder_destroy(g_h265_encoder);
    g_h265_encoder = NULL;
  }
 
  // Print audio analysis report if enabled
  // Print audio analysis report if enabled
  if (GET_OPTION(audio_analysis_enabled)) {
    audio_analysis_print_report();
    audio_analysis_destroy();
  }
 
  // Cleanup display and terminal state
  // WORKAROUND: Skip cleanup during shutdown to avoid hanging
  // display_cleanup();
 
  // Cleanup core systems
  // WORKAROUND: Skip cleanup during shutdown to avoid hanging
  // buffer_pool_cleanup_global();
 
  // Disable keepawake mode (re-allow OS to sleep)
  platform_disable_keepawake();
 
  log_debug("Client shutdown complete");
  log_destroy();
}
 
static int initialize_client_systems(void) {
  // All shared subsystem initialization (timer, logging, platform, buffer pool)
  // is now done by asciichat_shared_init() in src/main.c BEFORE options_init()
 
  // Initialize client worker thread pool (needed for network protocol threads)
  // This is required for all modes that connect to the server, including snapshot mode
  if (!g_client_worker_pool) {
    g_client_worker_pool = thread_pool_create("client_workers");
    if (!g_client_worker_pool) {
      log_fatal("Failed to create client worker thread pool");
      return ERROR_THREAD;
    }
  }
 
  // Ensure logging output is available for connection attempts (unless it was disabled with --quiet)
  if (!GET_OPTION(quiet)) {
    log_set_terminal_output(true);
  }
  log_truncate_if_large();
 
  // Display subsystem is now initialized by session_client_like_run()
  // No need to call display_init() here
 
  // Initialize application client context
  if (!g_client) {
    g_client = app_client_create();
    if (!g_client) {
      log_fatal("Failed to create application client context");
      return ERROR_NETWORK;
    }
    log_debug("Application client context created successfully");
  }
 
  // Initialize server connection management (legacy - will be migrated to tcp_client)
  if (server_connection_init() != 0) {
    log_fatal("Failed to initialize server connection");
    return ERROR_NETWORK;
  }
 
  // Initialize capture subsystems
  int capture_result = capture_init();
  if (capture_result != 0) {
    log_fatal("Failed to initialize capture subsystem");
    return capture_result;
  }
 
  // Initialize H.265 encoder for video streaming
  // Use reasonable default dimensions (will adapt on first frame)
  if (!g_h265_encoder) {
    g_h265_encoder = h265_encoder_create(800, 600);
    if (!g_h265_encoder) {
      log_warn("Failed to initialize H.265 encoder (will fall back to raw frames)");
      // Don't fail - we can still use raw frames
    } else {
      log_debug("H.265 encoder initialized successfully");
    }
  }
 
  // Timed recordings capture call audio; immediate snapshots need only one frame.
  if (GET_OPTION(audio_enabled) && (!GET_OPTION(snapshot_mode) || GET_OPTION(snapshot_delay) > 0)) {
    if (audio_client_init() != 0) {
      log_warn("Failed to initialize audio system");
      // Continue without audio instead of crashing (e.g., ARM systems with audio device incompatibility)
    }
 
    // Initialize audio analysis if requested
    if (GET_OPTION(audio_analysis_enabled)) {
      if (audio_analysis_init() != 0) {
        log_warn("Failed to initialize audio analysis");
      }
    }
  }
 
  return 0;
}
 
/* ============================================================================
 * Client Connection/Reconnection Loop (run_fn for session_client_like)
 * ============================================================================
 *
 * This callback is executed after shared initialization (media/audio/display)
 * is complete. It manages the entire client connection lifecycle:
 * 1. Connect to server (with fallback stages: TCP, WebRTC+STUN, WebRTC+TURN)
 * 2. Exchange media/audio with server
 * 3. On disconnection, attempt reconnection based on policy
 * 4. Exit on user request or max reconnection limit
 */
 
static bool client_should_reconnect(asciichat_error_t last_error, int attempt_number, void *user_data) {
  (void)last_error;
  (void)attempt_number;
  (void)user_data;
 
  // In snapshot mode, don't reconnect - exit after first failure
  if (GET_OPTION(snapshot_mode)) {
    log_error("Connection lost in snapshot mode - not retrying");
    return false;
  }
 
  // Otherwise, allow reconnection (framework handles max_reconnect_attempts limit)
  return true;
}
 
static asciichat_error_t client_run(session_capture_ctx_t *capture, session_display_ctx_t *display, void *user_data) {
  (void)capture;   // Provided by session_client_like, used by protocol threads
  (void)user_data; // Unused
 
  // Make the framework-created display context available to protocol threads
  display_set_context(display);
 
  // Get the render loop's should_exit callback for monitoring
  bool (*render_should_exit)(void *) = session_client_like_get_render_should_exit();
  if (!render_should_exit) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Render should_exit callback not initialized");
  }
 
  // Attempt connection with fallback stages (TCP, WebRTC+STUN, WebRTC+TURN)
  asciichat_error_t connection_result = connection_attempt_tcp(
      &g_client_session.connection_ctx,
      g_client_session.discovered_address != NULL ? g_client_session.discovered_address : "",
      (uint16_t)(g_client_session.discovered_port > 0 ? g_client_session.discovered_port : 27224));
 
  // Check if shutdown was requested during connection attempt
  if (should_exit()) {
    log_info("Shutdown requested during connection attempt");
    return ERROR_NETWORK;
  }
 
  if (connection_result != ASCIICHAT_OK) {
    // Connection failed - need to stop audio threads that were initialized early
    // (even though protocol_start_connection was never called)
    audio_stop_thread();
    // Framework will handle retry based on config
    log_error("Connection attempt failed");
    return connection_result;
  }
 
  // Connection successful - integrate transport into server layer
  if (g_client_session.connection_ctx.connection.transport) {
    server_connection_set_transport(g_client_session.connection_ctx.connection.transport);
    g_client_session.connection_ctx.connection.transport = NULL;
  } else {
    log_error("Connection succeeded but no active transport");
    return ERROR_NETWORK;
  }
 
  // Log connection status
  if (!g_client_session.has_ever_connected) {
    log_info("Connected");
    g_client_session.has_ever_connected = true;
  } else {
    log_info("Reconnected");
  }
 
  // Start protocol worker threads for this connection
  if (protocol_start_connection() != 0) {
    log_error("Failed to start connection protocols");
    protocol_stop_connection();
    server_connection_close();
    return ERROR_NETWORK;
  }
 
  // Monitor connection until it breaks or shutdown is requested
  static bool snapshot_check_logged_once = false;
  while (!should_exit() && server_connection_is_active()) {
    if (protocol_connection_lost()) {
      log_debug("Connection lost detected");
      break;
    }
 
    // Check if snapshot_delay timer has fired (in case frames stopped arriving)
    // This is a safety check for when frame reception is sparse or stops entirely
    extern uint64_t g_snapshot_first_frame_time_ns;
    bool snapshot_mode_enabled = GET_OPTION(snapshot_mode);
 
    if (!snapshot_check_logged_once) {
      log_info("CLIENT_MAIN_LOOP: snapshot_mode=%d first_frame_time=%llu snapshot_delay=%.1f", snapshot_mode_enabled,
               (unsigned long long)g_snapshot_first_frame_time_ns, GET_OPTION(snapshot_delay));
      snapshot_check_logged_once = true;
    }
 
    if (snapshot_mode_enabled && g_snapshot_first_frame_time_ns > 0) {
      uint64_t current_time_ns = time_get_ns();
      double elapsed = time_ns_to_s(time_elapsed_ns(g_snapshot_first_frame_time_ns, current_time_ns));
      double snapshot_delay = GET_OPTION(snapshot_delay);
 
      // Log progress every 500ms
      static uint64_t last_progress_log_ns = 0;
      if (current_time_ns - last_progress_log_ns > 500 * 1000 * 1000) {
        log_debug("[MAIN_LOOP_SNAPSHOT_CHECK] elapsed=%.3f target=%.3f first_frame_ns=%llu current_ns=%llu", elapsed,
                  snapshot_delay, (unsigned long long)g_snapshot_first_frame_time_ns,
                  (unsigned long long)current_time_ns);
        last_progress_log_ns = current_time_ns;
      }
 
      if (elapsed >= snapshot_delay) {
        char duration_str[32];
        time_pretty((uint64_t)(elapsed * 1e9), -1, duration_str, sizeof(duration_str));
        log_info("🎬 SNAPSHOT TIMEOUT FIRED (IN_MAIN_LOOP): Snapshot captured after %s! (target=%.3f)", duration_str,
                 snapshot_delay);
        signal_exit();
        break; // Exit loop, proper shutdown will follow
      }
    }
 
    platform_sleep_us(100 * US_PER_MS_INT);
  }
 
  if (should_exit()) {
    log_debug("Shutdown requested, cleaning up connection");
  } else {
    log_info("[ELSE_BRANCH] Connection lost path (should_exit=0, connection_active=0)");
    // Connection lost - check if snapshot_delay timer has fired before exiting
    extern uint64_t g_snapshot_first_frame_time_ns;
    if (GET_OPTION(snapshot_mode) && g_snapshot_first_frame_time_ns > 0) {
      uint64_t current_time_ns = time_get_ns();
      double elapsed = time_ns_to_s(time_elapsed_ns(g_snapshot_first_frame_time_ns, current_time_ns));
      double snapshot_delay = GET_OPTION(snapshot_delay);
 
      log_info("[CONNECTION_LOSS_SNAPSHOT_CHECK] elapsed=%.3f target=%.3f (checking if timer fired)", elapsed,
               snapshot_delay);
 
      if (elapsed >= snapshot_delay) {
        char duration_str[32];
        time_pretty((uint64_t)(elapsed * 1e9), -1, duration_str, sizeof(duration_str));
        log_info("🎬 SNAPSHOT TIMEOUT FIRED (ON_CONNECTION_LOSS): Snapshot captured after %s! (target=%.3f)",
                 duration_str, snapshot_delay);
        signal_exit();
        // Don't return yet, allow normal cleanup to proceed below
      }
    }
 
    if (!should_exit()) {
      log_debug("Connection lost, preparing for reconnection attempt");
    }
  }
 
  // Clean up this connection for potential reconnection
  protocol_stop_connection();
  server_connection_close();
 
  // Clear transport reference from connection context since server_connection_close() already destroyed it
  // This prevents double-free when connection_context_cleanup() is called below
  g_client_session.connection_ctx.connection.transport = NULL;
 
  // Recreate thread pool for clean reconnection
  if (g_client_worker_pool) {
    thread_pool_destroy(g_client_worker_pool);
    g_client_worker_pool = NULL;
  }
  g_client_worker_pool = thread_pool_create("client_reconnect");
  if (!g_client_worker_pool) {
    log_error("Failed to recreate worker thread pool");
    return ERROR_THREAD;
  }
 
  // Reset connection context for next attempt
  connection_context_cleanup(&g_client_session.connection_ctx);
  memset(&g_client_session.connection_ctx, 0, sizeof(g_client_session.connection_ctx));
  if (connection_context_init(&g_client_session.connection_ctx) != ASCIICHAT_OK) {
    log_error("Failed to re-initialize connection context");
    return ERROR_NETWORK;
  }
 
  // A snapshot is complete once its first frame has been rendered. The peer
  // may close the connection while the snapshot shutdown is propagating, but
  // that is a successful snapshot rather than a reconnectable network error.
  extern uint64_t g_snapshot_first_frame_time_ns;
  if (GET_OPTION(snapshot_mode) && g_snapshot_first_frame_time_ns > 0 && should_exit()) {
    return ASCIICHAT_OK;
  }
 
  // Return error to signal reconnection needed (framework handles the retry)
  return ERROR_NETWORK;
}
 
int client_main(void) {
  log_debug("client_main() starting");
 
  // Register client crypto callbacks for TCP connection path
  // The TCP path in lib/network/connection_attempt.c relies on these callbacks
  // to handle cryptographic operations and key exchange
  static const app_callbacks_t client_crypto_callbacks = {
      .should_exit = should_exit,
      .signal_exit = signal_exit,
      .platform_get_monotonic_time_us = platform_get_monotonic_time_us,
      .platform_sleep_ms = platform_sleep_ms,
      .server_connection_set_ip = server_connection_set_ip,
      .server_connection_set_port = server_connection_set_port,
      .client_crypto_set_mode = client_crypto_set_mode,
      .client_crypto_init = client_crypto_init,
      .client_crypto_handshake = client_crypto_handshake,
      .crypto_client_is_ready = crypto_client_is_ready,
      .crypto_client_get_context = crypto_client_get_context,
  };
  app_callbacks_register(&client_crypto_callbacks);
 
  // Initialize client-specific systems (NOT shared with session_client_like)
  // This includes: thread pool, display layer, app client context, server connection
  int init_result = initialize_client_systems();
  if (init_result != 0) {
#ifndef NDEBUG
    // Debug builds: automatically fall back to test pattern if webcam is in use
    if (init_result == ERROR_WEBCAM_IN_USE && !GET_OPTION(test_pattern)) {
      log_warn("Webcam is in use - automatically falling back to test pattern mode (debug build only)");
 
      // Enable test pattern mode via RCU update
      asciichat_error_t update_result = options_set_bool("test_pattern", true);
      if (update_result != ASCIICHAT_OK) {
        log_error("Failed to update options for test pattern fallback");
        FATAL(init_result, "%s", asciichat_error_string(init_result));
      }
 
      // Retry initialization with test pattern enabled
      init_result = initialize_client_systems();
      if (init_result != 0) {
        log_error("Failed to initialize even with test pattern fallback");
        webcam_print_init_error_help(init_result);
        FATAL(init_result, "%s", asciichat_error_string(init_result));
      }
      log_debug("Successfully initialized with test pattern fallback");
 
      // Clear the error state since we successfully recovered
      CLEAR_ERRNO();
    } else
#endif
    {
      // Release builds or other errors: print help and exit
      if (init_result == ERROR_WEBCAM || init_result == ERROR_WEBCAM_IN_USE || init_result == ERROR_WEBCAM_PERMISSION) {
        webcam_print_init_error_help(init_result);
        FATAL(init_result, "%s", asciichat_error_string(init_result));
      }
      // For other errors, just exit with the error code
      return init_result;
    }
  }
 
  // Register cleanup function for graceful shutdown
  (void)atexit(shutdown_client);
 
  // Register client interrupt callback (socket shutdown on SIGTERM/Ctrl+C)
  // Global signal handlers (SIGTERM, SIGPIPE, Ctrl+C) are set up in setup_signal_handlers() in src/main.c
  set_interrupt_callback(server_connection_shutdown);
 
#ifndef _WIN32
  // Register SIGWINCH for terminal resize handling (client-specific, not in framework)
  platform_signal(SIGWINCH, client_handle_sigwinch);
#endif
 
  /* ========================================================================
   * Client-Specific: LAN/Session Discovery
   * ========================================================================
   * This phase discovers the server to connect to via:
   * - LAN discovery (mDNS)
   * - Session string lookup (ACDS)
   * - Direct address/port
   */
 
  // LAN Discovery: If --scan flag is set, discover servers on local network
  const options_t *opts = options_get();
  if (opts && opts->lan_discovery &&
      (opts->address[0] == '\0' || is_localhost_ipv4(opts->address) || strcmp(opts->address, "localhost") == 0)) {
    log_debug("LAN discovery: --scan flag set, querying for available servers");
 
    ui_mdns_config_t lan_config;
    memset(&lan_config, 0, sizeof(lan_config));
    lan_config.timeout_ms = 2 * MS_PER_SEC_INT; // Wait up to 2 seconds for responses
    lan_config.max_servers = 20;                // Support up to 20 servers on LAN
    lan_config.quiet = true;                    // Quiet during discovery, TUI will show status
 
    int discovered_count = 0;
    ui_mdns_server_t *discovered_servers = ui_mdns_query(&lan_config, &discovered_count);
 
    // Use TUI for server selection
    int selected_index = ui_mdns_select(discovered_servers, discovered_count);
 
    if (selected_index < 0) {
      // User cancelled or no servers found
      if (discovered_count == 0) {
        // No servers found - log message and prevent any further output
        // Lock the terminal so other threads can't write and our error
        // will be the last message
        log_lock_terminal();
 
        // Log single message with embedded newlines to prevent multiple log entries
        log_error("No ascii-chat servers found on the local network.\nUse 'ascii-chat client <address>' to connect "
                  "manually.");
 
        // Exit without cleanup
        platform_force_exit(1);
      }
      // User cancelled (had servers to choose from but pressed cancel)
      log_debug("LAN discovery: User cancelled server selection");
      if (discovered_servers) {
        ui_mdns_free_results(discovered_servers);
      }
      return 1; // User cancelled
    }
 
    // Update options with discovered server's address and port
    ui_mdns_server_t *selected = &discovered_servers[selected_index];
    const char *selected_address = ui_mdns_get_best_address(selected);
 
    // We need to modify options, but they're immutable via RCU
    // Create a new options copy with updated address/port
    options_t *opts_new = SAFE_MALLOC(sizeof(options_t), options_t *);
    if (opts_new) {
      memcpy(opts_new, opts, sizeof(options_t));
      SAFE_STRNCPY(opts_new->address, selected_address, sizeof(opts_new->address));
 
      opts_new->port = (int)selected->port;
 
      log_debug("LAN discovery: Selected server '%s' at %s:%d", selected->name, opts_new->address, opts_new->port);
 
      // Note: In a real scenario, we'd update the global options via RCU
      // For now, we'll use the updated values directly for connection
      // This is a known limitation - proper RCU update requires more infrastructure
    }
 
    ui_mdns_free_results(discovered_servers);
  }
 
  // =========================================================================
  // Client-Specific: Server Address Resolution
  // =========================================================================
  // Client mode supports:
  // 1. Direct address/port (--address HOST --port PORT) - handled by options
  // 2. LAN discovery (--scan) - handled above
  // 3. WebSocket URL (direct ws:// or wss:// connection string)
  //
  // Note: Session string discovery via ACDS is handled by discovery mode only.
  //       Client mode does NOT use ACDS or session strings.
 
  const char *discovered_address = NULL;
  int discovered_port = 0;
 
  // Check if user provided a WebSocket URL as the server address
  const options_t *opts_websocket = options_get();
  const char *provided_address = opts_websocket && opts_websocket->address[0] != '\0' ? opts_websocket->address : NULL;
 
  if (provided_address && url_is_websocket(provided_address)) {
    // Direct WebSocket connection
    log_debug("Client: Direct WebSocket URL: %s", provided_address);
    discovered_address = provided_address;
    discovered_port = 0; // Port is embedded in the URL
  }
 
  if (discovered_port > 0) {
    log_debug("Client: discovered_address=%s, discovered_port=%d", discovered_address ? discovered_address : "NULL",
              discovered_port);
  } else {
    log_debug("Client: discovered_address=%s", discovered_address ? discovered_address : "NULL");
  }
 
  // Store discovered address/port in session state for client_run() callback
  static char address_storage[BUFFER_SIZE_SMALL];
  if (discovered_address) {
    SAFE_STRNCPY(address_storage, discovered_address, sizeof(address_storage));
    g_client_session.discovered_address = address_storage;
    g_client_session.discovered_port = discovered_port;
  } else {
    const options_t *opts_fallback = options_get();
    if (opts_fallback && opts_fallback->address[0] != '\0') {
      SAFE_STRNCPY(address_storage, opts_fallback->address, sizeof(address_storage));
      g_client_session.discovered_address = address_storage;
      g_client_session.discovered_port = opts_fallback->port;
    } else {
      g_client_session.discovered_address = "localhost";
      g_client_session.discovered_port = 27224;
    }
  }
 
  // Initialize connection context for first attempt
  asciichat_error_t ctx_init_result = connection_context_init(&g_client_session.connection_ctx);
  if (ctx_init_result != ASCIICHAT_OK) {
    log_error("Failed to initialize connection context");
    return 1;
  }
 
  /* ========================================================================
   * Configure and Run Shared Client-Like Session Framework
   * ========================================================================
   * session_client_like_run() handles all shared initialization:
   * - Terminal output management (force stderr if piped)
   * - Keepawake system (platform sleep prevention)
   * - Splash screen lifecycle
   * - Media source selection (webcam, file, URL, test pattern)
   * - FPS probing for media files
   * - Audio initialization and lifecycle
   * - Display context creation
   * - Proper cleanup ordering (critical for PortAudio)
   *
   * Client mode provides:
   * - client_run() callback: connection loop, protocol startup, monitoring
   * - client_should_reconnect() callback: reconnection policy
   * - Reconnection configuration: attempts, delay, callbacks
   */
 
  // Get reconnect attempts setting (-1 = unlimited, 0 = no retry, >0 = retry N times)
  int reconnect_attempts = GET_OPTION(reconnect_attempts);
 
  // Configure session_client_like with client-specific settings
  session_client_like_config_t config = {
      .run_fn = client_run,
      .run_user_data = NULL,
      .kind = SESSION_CLIENT_LIKE_KIND_CLIENT,
      .discovery = NULL,
      .custom_should_exit = NULL,
      .exit_user_data = NULL,
      .keyboard_handler = NULL, // Client mode: server drives display
      .max_reconnect_attempts = reconnect_attempts,
      .should_reconnect_callback = client_should_reconnect,
      .reconnect_user_data = NULL,
      .reconnect_delay_ms = 1000,         // 1 second delay between reconnection attempts
      .print_newline_on_tty_exit = false, // Server/client manages cursor
  };
 
  log_debug("[CLIENT_MAIN] About to call session_client_like_run() with %d attempts", reconnect_attempts);
  asciichat_error_t session_result = session_client_like_run(&config);
  log_debug("[CLIENT_MAIN] session_client_like_run() returned %d", session_result);
 
  // Network client lifecycle is owned by connection_context_cleanup() after the session returns.
 
  // Cleanup connection context
  log_debug("[CLIENT_MAIN] About to call connection_context_cleanup()");
  connection_context_cleanup(&g_client_session.connection_ctx);
  log_debug("[CLIENT_MAIN] connection_context_cleanup() returned");
 
  // Cleanup session log buffer (used by splash screen in session_client_like)
  // NOTE: session_log_buffer_destroy() is already called in session_client_like_run()
  // during its cleanup phase, so we don't call it here to avoid double-destroy of mutex
 
  log_debug("[CLIENT_MAIN] ascii-chat client shutting down");
 
  // IMPORTANT: Stop worker threads and join them BEFORE memory report
  // atexit(shutdown_client) won't run if interrupted by SIGTERM, so call explicitly
  log_debug("[CLIENT_MAIN] About to call shutdown_client()");
  fflush(stderr);
  shutdown_client();
  log_debug("[CLIENT_MAIN] shutdown_client() returned");
  fflush(stderr);
 
  // Cleanup remaining shared subsystems (buffer pool, platform, etc.)
  log_debug("[CLIENT_MAIN] About to call asciichat_shared_destroy()");
  asciichat_shared_destroy();
 
  // Log final session statistics before exit
  // Note: Frame count is logged in protocol_stop_connection() if connection was established
  // This is a fallback in case the connection never started
  return (session_result == ASCIICHAT_OK) ? 0 : 1;
}