functions.sh

#!/usr/bin/env -S bash
#
# Copyright 2024, Wim Bonis, Stylite AG
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

#####################
# Functions
#####################

#==============================================================================
# CONSTANTS
#==============================================================================

readonly PROC_SSH_RAGENT=" ragent "
readonly PROC_PYTHON_MUX="sshagentmux.py"
readonly PROC_RUST_MUX="ssh-agent-mux"

#==============================================================================
# COLOR AND LOGGING UTILITIES
#==============================================================================

# Color helper function
color() {
    # Skip colors if explicitly disabled
    [ -n "${NO_COLOR:-}" ] && return
    
    # Skip if TERM is "dumb" (no color support)
    [ "${TERM:-}" = "dumb" ] && return
    
    # Use colors if:
    # - stdout is a TTY (interactive terminal), OR
    # - FORCE_COLOR is explicitly set, OR
    # - TERM is set and stderr is also a TTY (indicates interactive session, not file redirect)
    # We check stderr TTY to distinguish interactive sessions from file redirects
    if command -v tput >/dev/null 2>&1; then
        if [ -t 1 ] || [ "${FORCE_COLOR:-0}" == "1" ] || ([ -n "${TERM:-}" ] && [ -t 2 ]); then
            tput "$@" 2>/dev/null || true
        fi
    fi
}

# Color helper for stderr (SCA uses stderr for logging)
color_stderr() {
    if [ -t 2 ] && [ -z "${NO_COLOR:-}" ] && command -v tput >/dev/null 2>&1; then
        tput "$@"
    fi
}

# Logging functions with colors (use color_stderr since output goes to stderr)
log_error() {
    echo "$(color_stderr setaf 1)$(color_stderr bold)ERROR:$(color_stderr sgr0) $(color_stderr setaf 1)$*$(color_stderr sgr0)" >&2
}

log_warn() {
    echo "$(color_stderr setaf 3)$(color_stderr bold)WARNING:$(color_stderr sgr0) $(color_stderr setaf 3)$*$(color_stderr sgr0)" >&2
}

log_info() {
    echo "$(color_stderr setaf 4)$(color_stderr bold)INFO:$(color_stderr sgr0) $(color_stderr setaf 4)$*$(color_stderr sgr0)" >&2
}

log_success() {
    echo "$(color_stderr setaf 2)$(color_stderr bold)✓$(color_stderr sgr0) $(color_stderr setaf 2)$*$(color_stderr sgr0)" >&2
}

log_debug() {
    if [ "${DEBUG:-0}" == "1" ]; then
        echo "$(color_stderr setaf 5)$(color_stderr bold)DEBUG:$(color_stderr sgr0) $(color_stderr setaf 5)$*$(color_stderr sgr0)" >&2
    fi
}

log_note() {
    echo "$(color_stderr setaf 6)$(color_stderr bold)NOTE:$(color_stderr sgr0) $(color_stderr setaf 6)$*$(color_stderr sgr0)" >&2
}

# Color codes for syntax highlighting
color_reset() {
    color sgr0
}

color_host() {
    color setaf 4  # Blue
    color bold
}

color_directive() {
    color setaf 6  # Cyan
}

color_value() {
    color setaf 3  # Yellow
}

color_comment() {
    # Try gray (8), fallback to dim white (7)
    if color setaf 8 >/dev/null 2>&1; then
        color setaf 8
    else
        color setaf 7
        color dim
    fi
}

color_file_header() {
    color setaf 5  # Magenta
    color dim
}

# Syntax highlight a line of SSH config
highlight_line() {
    local line="$1"

    # Host or Match directive (bold blue for keyword, yellow for values)
    if [[ "$line" =~ ^([[:space:]]*)(Host|Match)[[:space:]]+(.+)$ ]]; then
        local indent="${BASH_REMATCH[1]}"
        local keyword="${BASH_REMATCH[2]}"
        local values="${BASH_REMATCH[3]}"
        printf "%s%s%s%s %s%s%s\n" \
            "$indent" \
            "$(color_host)" \
            "$keyword" \
            "$(color_reset)" \
            "$(color_value)" \
            "$values" \
            "$(color_reset)"
        return
    fi

    # Comment lines (gray/dim)
    if [[ "$line" =~ ^[[:space:]]*# ]]; then
        printf "%s%s%s\n" "$(color_comment)" "$line" "$(color_reset)"
        return
    fi

    # Directives with values (cyan directive, yellow value)
    if [[ "$line" =~ ^([[:space:]]+)([A-Za-z][A-Za-z0-9]*)[[:space:]]+(.+)$ ]]; then
        local indent="${BASH_REMATCH[1]}"
        local directive="${BASH_REMATCH[2]}"
        local value="${BASH_REMATCH[3]}"
        printf "%s%s%s%s %s%s%s\n" \
            "$indent" \
            "$(color_directive)" \
            "$directive" \
            "$(color_reset)" \
            "$(color_value)" \
            "$value" \
            "$(color_reset)"
        return
    fi

    # Default: just print the line
    printf "%s\n" "$line"
}

#==============================================================================
# HOST MANAGEMENT FUNCTIONS
#==============================================================================

list() {
  echo "## Listing Hosts" >&2
  cat $PLAYBOOK_DIR/hosts/*
}

#==============================================================================
# HOST SEARCH HELPER FUNCTIONS
#==============================================================================

# Helper function to find Host block start line for any given line number
find_host_block_start() {
  local file="$1"
  local line_num="$2"
  local start_line=$line_num
  while [ $start_line -gt 0 ]; do
    local line_content=$(sed -n "${start_line}p" "$file" 2>/dev/null)
    # Check if this line starts with "Host " (with space) or "Match " (with space)
    if echo "$line_content" | grep -qiE "^[[:space:]]*(Host|Match)[[:space:]]"; then
      echo "$start_line"
      return 0
    fi
    start_line=$((start_line - 1))
  done
  return 1
}

# Helper function to search for matches in all lines
search_in_all_lines() {
  local file="$1"
  local hostname="$2"
  # Search for the hostname as a substring in all non-comment lines (case-insensitive)
  # Important: ignore standalone comments like "# Autoadded ..." to avoid jumping to the previous Host block.
  awk -v q="$hostname" '
    BEGIN { q = tolower(q) }
    /^[[:space:]]*#/ { next }
    { if (index(tolower($0), q) > 0) print NR }
  ' "$file" 2>/dev/null
}

# Process matching lines and extract host blocks
process_matching_lines() {
  local file="$1"
  local hostname="$2"
  local matching_lines=$(search_in_all_lines "$file" "$hostname")
  
  if [ -z "$matching_lines" ]; then
    return 1
  fi
  
  local unique_starts=""
  while IFS= read -r line_num; do
    local start_line=$(find_host_block_start "$file" "$line_num")
    if [ -n "$start_line" ]; then
      if ! echo "$unique_starts" | grep -q "^${start_line}$"; then
        unique_starts="${unique_starts}${start_line}"$'\n'
      fi
    fi
  done <<< "$matching_lines"
  
  if [ -n "$unique_starts" ]; then
    local sorted_starts
    sorted_starts=$(echo "$unique_starts" | grep -v '^$' | sort -n)
    while IFS= read -r start_line; do
      [ -z "$start_line" ] && continue
      extract_host_block "$file" "$start_line"
    done <<< "$sorted_starts"
    return 0
  fi
  return 1
}

# Helper function to extract and print Host block from a file
extract_host_block() {
  local file="$1"
  local line_num="$2"
  
  # Find the start of this Host block using the helper function
  local start_line
  start_line=$(find_host_block_start "$file" "$line_num")
  if [ $? -ne 0 ] || [ -z "$start_line" ]; then
    return 1
  fi
  
  local host_line_content=$(sed -n "${start_line}p" "$file" 2>/dev/null)
  # Verify it's actually a Host or Match line with space
  if ! echo "$host_line_content" | grep -qiE "^[[:space:]]*(Host|Match)[[:space:]]"; then
    return 1
  fi
  
  # Find the end of this Host block (next Host or Match line, or end of file)
  local total_lines=$(wc -l < "$file" 2>/dev/null)
  local end_line=$total_lines
  local next_line=$((start_line + 1))
  
  while [ $next_line -le $total_lines ]; do
    local line_content=$(sed -n "${next_line}p" "$file" 2>/dev/null)
    # Check if this line starts a new Host or Match block (with space)
    if echo "$line_content" | grep -qiE "^[[:space:]]*(Host|Match)[[:space:]]"; then
      end_line=$((next_line - 1))
      break
    fi
    next_line=$((next_line + 1))
  done
  
  # Extract the block starting from the Host line
  local block_content=$(sed -n "${start_line},${end_line}p" "$file" 2>/dev/null)
  
  # Always start with the Host line (remove any trailing whitespace)
  local clean_host_line=$(echo "$host_line_content" | sed 's/[[:space:]]*$//')
  
  # Filter the rest: remove empty lines and standalone (non-indented) comment lines
  # Note: we keep this streaming below to preserve colors and avoid buffering.
  
  # Build output: always start with Host line
  # Ensure clean_host_line is not empty
  if [ -z "$clean_host_line" ]; then
    clean_host_line=$(sed -n "${start_line}p" "$file" 2>/dev/null | sed 's/[[:space:]]*$//')
  fi
  
  # Print file header with color
  echo -n "$(color_file_header)"
  echo "--- $file (lines $start_line-$end_line) ---"
  echo -n "$(color_reset)"
  
  # Always print the Host line first with highlighting
  highlight_line "$clean_host_line"
  
  # Print rest of block with highlighting - process line by line directly
  echo "$block_content" | tail -n +2 | while IFS= read -r line || [ -n "$line" ]; do
    # Skip empty lines and standalone (non-indented) comment lines
    if [ -z "$line" ]; then
      continue
    fi
    # Standalone comment (not indented) - skip
    [[ "$line" == \#* ]] && continue
    # Print the line with highlighting
    highlight_line "$line"
  done
  echo ""
}

find() {
  local hostname="$1"
  local config_file="$PLAYBOOK_DIR/config"
  local hosts_dir="$PLAYBOOK_DIR/hosts"
  local found_any=false
  
  echo "Searching for host: $hostname" >&2
  
  # Search in config file
  if [ -f "$config_file" ]; then
    process_matching_lines "$config_file" "$hostname" && found_any=true
  fi
  
  # Search in hosts/* files
  if [ -d "$hosts_dir" ]; then
    for host_file in "$hosts_dir"/*; do
      if [ -f "$host_file" ]; then
        process_matching_lines "$host_file" "$hostname" && found_any=true
      fi
    done
  fi
  
  # Display results
  if [ "$found_any" != "true" ]; then
    echo "No host found matching: $hostname" >&2
    return 1
  fi
}

add() {
  echo "Adding Host: $*" >&2
  (cd "$PLAYBOOK_DIR" && ./addhost "$@")
}

do_cmd() {
    CMD="$1"
    shift
    ARGS="$*"
    echo "CMD: $CMD" >&2
    echo "ARGS: $ARGS" >&2
    # Is function $CMD defined?
    if type "$CMD" >/dev/null 2>&1; then
      "$CMD" $ARGS
    else
      echo "Command $CMD not found" >&2
    fi
}

# Cleanup function for background processes
cleanup() {
    SCA_EXITING=true
    
    # Check if we have anything to clean up
    local has_cleanup=false
    [ -n "$SSH_PID" ] && has_cleanup=true
    [ -n "$MUX_PID" ] && has_cleanup=true
    [ -n "$TAIL_LOG_PID" ] && has_cleanup=true
    [ -n "$RUST_MUX_LOG" ] && [ -f "$RUST_MUX_LOG" ] && has_cleanup=true
    [ -n "$TEMP_AGENT_PID" ] && has_cleanup=true
    
    if [ "$has_cleanup" != "true" ]; then
        return
    fi
    
    log_info "Cleaning up background processes..."
    
    # Kill SSH agent forwarder
    if [ -n "$SSH_PID" ]; then
        kill_if_exists "$SSH_PID" "SSH agent forwarder"
        kill_processes "$PROC_SSH_RAGENT" "SSH agent forwarder"
        log_info "Removing SSH agent socket: $SCA_SSH_AUTH_SOCK"
        rm -f "$SCA_SSH_AUTH_SOCK" 2>/dev/null || true
    fi
    
    # Kill multiplexer processes
    if [ -n "$MUX_PID" ]; then
        kill_if_exists "$MUX_PID" "multiplexer"
        kill_processes "$PROC_PYTHON_MUX" "Python multiplexer"
        if [ -n "$RUST_MUX_PID" ]; then
            kill_if_exists "$RUST_MUX_PID" "ssh-agent-mux"
        fi
        kill_process_by_name "$PROC_RUST_MUX"
        log_info "Removing mux socket: $MUX_SSH_AUTH_SOCK"
        rm -f "$MUX_SSH_AUTH_SOCK" 2>/dev/null || true
    fi
    
    # Kill log tail process
    if [ -n "$TAIL_LOG_PID" ]; then
        if kill -0 "$TAIL_LOG_PID" 2>/dev/null; then
            log_info "Stopping log tail process (PID $TAIL_LOG_PID)"
            kill -TERM "$TAIL_LOG_PID" 2>/dev/null || true
        fi
    fi
    
    # Clean up temp log file if it exists
    if [ -n "$RUST_MUX_LOG" ] && [ -f "$RUST_MUX_LOG" ]; then
        log_info "Removing temp log file: $RUST_MUX_LOG"
        rm -f "$RUST_MUX_LOG" 2>/dev/null || true
    fi
    
    # Clean up temporary SSH agent if it exists
    if [ -n "$TEMP_AGENT_PID" ]; then
        cleanup_temp_agent
    fi
    
    log_info "Cleanup complete"
}

# Kill a process if it exists
kill_if_exists() {
    local pid=$1
    local name=$2
    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
        log_info "Killing $name (PID $pid)"
        kill -TERM "$pid" 2>/dev/null || true
    fi
}

# Kill processes by pattern
kill_processes() {
    local pattern=$1
    local name=$2
    if pkill -f "$pattern" 2>/dev/null; then
        log_info "Killed $name processes"
    fi
}

# Kill processes by exact name
kill_process_by_name() {
    local name=$1
    if pkill -x "$name" 2>/dev/null; then
        log_info "Killed $name processes"
    fi
}

# Kill all SCA-related processes
kill_all_sca_processes() {
    kill_processes "$PROC_SSH_RAGENT" "SSH agent forwarder"
    kill_processes "$PROC_PYTHON_MUX" "Python multiplexer"
    kill_process_by_name "$PROC_RUST_MUX"
}

# Check if an SSH agent socket is working
check_agent_socket() {
    local socket=$1
    SSH_AUTH_SOCK="$socket" ssh-add -l >/dev/null 2>&1
}

# Check if SSH process with ragent is still running
check_ssh_agent_running() {
    pgrep -f "$PROC_SSH_RAGENT" >/dev/null 2>&1
}

# Verify socket exists and is working (combined check)
verify_socket_working() {
    local socket=$1
    [ -S "$socket" ] && check_agent_socket "$socket"
}

# Verify socket exists, is working, and SSH process is running
verify_remote_agent_working() {
    local socket=$1
    [ -S "$socket" ] && check_agent_socket "$socket" && check_ssh_agent_running
}

# Display harmless error note for ssh-agent-mux
show_harmless_error_note() {
    log_note "You can safely ignore these harmless errors:"
    echo "  $(color_stderr setaf 3)-$(color_stderr sgr0) 'ERROR [ssh_agent_mux] Unexpected error on socket ... when requesting session-bind@openssh.com extension: Agent: Protocol error: Unexpected response received'" >&2
    echo "  $(color_stderr setaf 3)-$(color_stderr sgr0) 'ERROR [ssh_agent_lib::agent] Error handling message: Failure'" >&2
}

# Filter out harmless Rust mux errors from log output
filter_rust_mux_errors() {
    grep -vE "ERROR \[ssh_agent_lib::agent\] Error handling message: Failure|ERROR \[ssh_agent_mux\] Unexpected error on socket.*when requesting session-bind@openssh.com extension.*Protocol error.*Unexpected response received"
}

# Find identity file in common locations
find_identity_file() {
    local key_file
    
    # First, check if MY_SSH_KEY is set (from localvars.yml via playbook)
    if [ -n "$MY_SSH_KEY" ] && [ "$MY_SSH_KEY" != "~/.ssh/id_unused" ]; then
        # Expand ~ to $HOME if needed
        key_file=$(echo "$MY_SSH_KEY" | sed "s|^~|$HOME|")
        if [ -f "$key_file" ] && [ -r "$key_file" ]; then
            echo "$key_file"
            return 0
        fi
    fi

    # Fall back to standard identity file locations
    for key_file in ~/.ssh/id_ed25519 ~/.ssh/id_rsa ~/.ssh/id_ecdsa; do
        if [ -f "$key_file" ] && [ -r "$key_file" ]; then
            echo "$key_file"
            return 0
        fi
    done
    return 1
}

# Setup temporary SSH agent for identity file
setup_temp_agent() {
    local identity_file=$1
    local temp_socket temp_pid
    
    if [ -z "$identity_file" ] || [ ! -f "$identity_file" ]; then
        log_error "Invalid identity file: $identity_file"
        return 1
    fi
    
    log_info "Creating temporary SSH agent for identity file..."
    
    # Start ssh-agent and capture output
    local agent_output
    agent_output=$(ssh-agent -s 2>/dev/null)
    if [ $? -ne 0 ]; then
        log_error "Failed to start temporary SSH agent"
        return 1
    fi
    
    # Extract socket and PID from agent output
    # Handle formats like: SSH_AUTH_SOCK=/tmp/ssh-XXXXXX/agent.12345; export SSH_AUTH_SOCK;
    # or: SSH_AUTH_SOCK=/tmp/ssh-XXXXXX/agent.12345
    temp_socket=$(echo "$agent_output" | grep "SSH_AUTH_SOCK" | sed -E 's/.*SSH_AUTH_SOCK=([^;[:space:]]+).*/\1/' | head -1)
    temp_pid=$(echo "$agent_output" | grep "SSH_AGENT_PID" | sed -E 's/.*SSH_AGENT_PID=([^;[:space:]]+).*/\1/' | head -1)
    
    if [ -z "$temp_socket" ] || [ -z "$temp_pid" ]; then
        log_error "Failed to parse ssh-agent output"
        log_debug "ssh-agent output: $agent_output"
        return 1
    fi
    
    # Export variables for use in this shell
    export SSH_AUTH_SOCK="$temp_socket"
    export SSH_AGENT_PID="$temp_pid"
    
    # Add the identity file to the agent (this will prompt for passphrase once)
    log_info "Adding identity file to temporary agent (you will be prompted for passphrase once)..."
    if ! ssh-add "$identity_file"; then
        log_error "Failed to add identity file to temporary agent"
        cleanup_temp_agent
        return 1
    fi
    
    # Set global variables
    TEMP_AGENT_SOCK="$temp_socket"
    TEMP_AGENT_PID="$temp_pid"
    
    log_success "Temporary SSH agent created (PID: $temp_pid, Socket: $temp_socket)"
    if [ "${DEBUG:-0}" == "1" ]; then
      log_debug "Temporary agent details:"
      log_debug "  PID: $temp_pid"
      log_debug "  Socket: $temp_socket"
      log_debug "  Keys in temporary agent:"
      SSH_AUTH_SOCK="$temp_socket" ssh-add -l 2>&1 | while IFS= read -r line; do
        log_debug "    $line"
      done
    fi
    return 0
}

# Cleanup temporary SSH agent
cleanup_temp_agent() {
    if [ -n "$TEMP_AGENT_PID" ]; then
        if kill -0 "$TEMP_AGENT_PID" 2>/dev/null; then
            log_info "Stopping temporary SSH agent (PID $TEMP_AGENT_PID)"
            kill -TERM "$TEMP_AGENT_PID" 2>/dev/null || true
            # Wait a bit for clean shutdown
            sleep 0.5
            # Force kill if still running
            if kill -0 "$TEMP_AGENT_PID" 2>/dev/null; then
                kill -KILL "$TEMP_AGENT_PID" 2>/dev/null || true
            fi
        fi
        TEMP_AGENT_PID=""
    fi
    
    if [ -n "$TEMP_AGENT_SOCK" ] && [ -S "$TEMP_AGENT_SOCK" ]; then
        log_info "Removing temporary SSH agent socket: $TEMP_AGENT_SOCK"
        rm -f "$TEMP_AGENT_SOCK" 2>/dev/null || true
        TEMP_AGENT_SOCK=""
    fi
}

# Build SSH command with optional identity file
build_ssh_cmd() {
    local cmd="ssh -a -F $PLAYBOOK_DIR/${SSH_CONFIG_FILE}_single"
    # If we have a temporary agent, use it instead of -i to avoid multiple passphrase prompts
    if [ -n "$TEMP_AGENT_SOCK" ]; then
        # Use equals format to avoid quote issues when eval'd
        cmd="$cmd -o IdentityAgent=$TEMP_AGENT_SOCK"
    elif [ "$USE_IDENTITY_FILE" == "true" ] && [ -n "$IDENTITY_FILE" ]; then
        cmd="$cmd -i \"$IDENTITY_FILE\""
    fi
    echo "$cmd"
}

# Determine user security level
determine_security_level() {
    local ssh_cmd ssh_output ssh_exit_code my_level
    
    # If we have a mux socket with the local key, use it directly
    # Otherwise, use build_ssh_cmd which will use temp agent or identity file
    if verify_socket_working "$MUX_SSH_AUTH_SOCK"; then
        # Check if mux socket has the local key (needed for sca-key connection)
        IDENTITY_FILE=$(find_identity_file)
        if [ -n "$IDENTITY_FILE" ]; then
            local id_fingerprint
            id_fingerprint=$(ssh-keygen -lf "$IDENTITY_FILE" 2>/dev/null | awk '{print $2}')
            if [ -n "$id_fingerprint" ]; then
                if SSH_AUTH_SOCK="$MUX_SSH_AUTH_SOCK" ssh-add -l 2>/dev/null | grep -q "$id_fingerprint"; then
                    # Mux socket has the local key, use it
                    ssh_cmd="ssh -a -F $PLAYBOOK_DIR/${SSH_CONFIG_FILE}_single -o IdentityAgent=$MUX_SSH_AUTH_SOCK"
                    log_debug "Determining security level with mux socket: $ssh_cmd"
                else
                    # Mux socket doesn't have local key, use build_ssh_cmd
                    ssh_cmd=$(build_ssh_cmd)
                    log_debug "Determining security level with: $ssh_cmd"
                fi
            else
                # Can't get fingerprint, use build_ssh_cmd
                ssh_cmd=$(build_ssh_cmd)
                log_debug "Determining security level with: $ssh_cmd"
            fi
        else
            # No identity file, use build_ssh_cmd
            ssh_cmd=$(build_ssh_cmd)
            log_debug "Determining security level with: $ssh_cmd"
        fi
    else
        # No mux socket, use build_ssh_cmd
        ssh_cmd=$(build_ssh_cmd)
        log_debug "Determining security level with: $ssh_cmd"
    fi
    
    ssh_output=$(eval "$ssh_cmd -o \"SetEnv SCA_NOLEVEL=1\" sca-key groups 2>&1")
    ssh_exit_code=$?
    
    if [ "$ssh_exit_code" -ne 0 ]; then
        log_error "SSH connection failed with exit code $ssh_exit_code"
        log_error "SSH output: $ssh_output"
        return 1
    fi
    
    my_level=$(echo "$ssh_output" | grep "level-" | grep -o -E "level-([0-9]*)" | cut -d"-" -f2 | sort -u | tail -1)
    
    if [ -z "$my_level" ]; then
        log_error "Could not determine your security level. Check your SSH connection."
        if [ -n "$ssh_output" ]; then
            log_error "SSH command output: $ssh_output"
        fi
        return 1
    fi
    
    echo "$my_level"
    return 0
}

# Start remote SSH agent forwarder
start_remote_agent() {
    local level=$1
    local ssh_cmd ssh_pid
    
    ssh_cmd=$(build_ssh_cmd)
    
    log_info "Starting SSH agent forwarder (level $level)..."
    SCA_LOCALUSER=$LOGNAME SCA_REMOTEUSER=$RUSERNAME SCA_IP=$(hostname) \
        eval "$ssh_cmd -tt -a -L $SCA_SSH_AUTH_SOCK:/home/$RUSERNAME/yubikey-agent.sock -o \"SetEnv STY_LEVEL=$level SCA_LEVEL=$level\" sca-key ragent \"$LOGNAME,$USER,$RUSERNAME,$level,$LEVEL,$HOSTNAME,$HOME\"" >/dev/null 2>&1 &
    
    ssh_pid=$!
    log_success "SSH agent forwarder is running as PID $ssh_pid"
    
    # Wait for connection to establish
    sleep $SSH_INITIAL_DELAY
    local iterations=0
    while [ $iterations -lt $SSH_RETRY_MAX ]; do
        ((iterations++))
        # Check if SSH process is still running
        if ! kill -0 "$ssh_pid" 2>/dev/null; then
            log_error "SSH process (PID $ssh_pid) died unexpectedly"
            return 1
        fi
        # Check if socket exists and is working
        if verify_socket_working "$SCA_SSH_AUTH_SOCK"; then
            echo "$ssh_pid"
            return 0
        fi
        log_info "Trying to connect to agent ($iterations/$SSH_RETRY_MAX)"
        sleep $SSH_RETRY_DELAY
    done
    
    log_error "Cannot connect to agent after $SSH_RETRY_MAX attempts"
    # Check if SSH process is still running
    if kill -0 "$ssh_pid" 2>/dev/null; then
        log_error "SSH process (PID $ssh_pid) is still running but socket is not working"
        kill -TERM "$ssh_pid" 2>/dev/null
    fi
    return 1
}

# Wait for socket to be created
wait_for_socket() {
    local socket=$1
    local max_iterations=${2:-${SOCKET_WAIT_MAX:-10}}
    local delay=${3:-${SOCKET_WAIT_DELAY:-0.1}}
    local iterations=0
    
    while [ ! -S "$socket" ] && [ "$iterations" -lt "$max_iterations" ]; do
        ((iterations++))
        sleep "$delay"
    done
    
    [ -S "$socket" ]
}

#==============================================================================
# MULTIPLEXER SETUP
#==============================================================================

# Setup Python multiplexer (sshagentmux.py)
setup_python_multiplexer() {
    log_info "Starting Python multiplexer (sshagentmux.py)..."
    # The Python multiplexer uses SSH_AUTH_SOCK as the primary agent and --socket as the alternate
    # We set SSH_AUTH_SOCK to the remote agent, and pass the local/temporary agent as --socket
    # If ORG_SSH_AUTH_SOCK is /dev/null (no local agent), the multiplexer will detect it's invalid
    # and just use the remote agent (SSH_AUTH_SOCK)

    # Build level argument if MY_LEVEL is set
    local level_arg=""
    if [ -n "$MY_LEVEL" ]; then
        level_arg="--level $MY_LEVEL"
    fi

    if [ "$REVERSE" == "1" ]; then
        log_info "Reversing the order of the agents"
        SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK
        # shellcheck disable=SC1054,SC1009,SC1056,SC1072,SC1073
        eval "$($PLAYBOOK_DIR/sshagentmux.py --socket "${ORG_SSH_AUTH_SOCK}" --envname OMUX_)"
    else
        # Set SSH_AUTH_SOCK to remote agent (primary)
        SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK
        eval "$($PLAYBOOK_DIR/sshagentmux.py --socket "${ORG_SSH_AUTH_SOCK}" --envname OMUX_)"
    fi
    log_info "Python multiplexer started (PID: $OMUX_SSH_AGENT_PID)"
}

# Execute command or start shell
execute_command_or_shell() {
  if [ "$SHELL_MODE" == "1" ]; then
    # Shell Mode: Output environment variables in ssh-agent format
    # Disable cleanup trap so background processes keep running
    trap - EXIT INT TERM
    echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK; export SSH_AUTH_SOCK;"
    # Output PID if available (prefer MUX_PID, fallback to SSH_PID)
    AGENT_PID="${MUX_PID:-${SSH_PID:-}}"
    if [ -n "$AGENT_PID" ]; then
      echo "SSH_AGENT_PID=$AGENT_PID; export SSH_AGENT_PID;"
      echo "echo Agent pid $AGENT_PID;"
    fi
    exit 0
    
  elif [ "$SSH_MODE" == "1" ]; then
    # SSH Mode: Direct SSH connection
    # Disable cleanup trap since we're not starting any background processes
    trap - EXIT INT TERM
    # Select socket based on --key option (default: mux)
    if [ "$KEY" == "mux" ]; then
      SSH_SOCKET="$MUX_SSH_AUTH_SOCK"
    elif [ "$KEY" == "local" ]; then
      SSH_SOCKET="$ORG_SSH_AUTH_SOCK"
    else
      # Default to mux (KEY=remote or empty)
      SSH_SOCKET="$MUX_SSH_AUTH_SOCK"
    fi
    # Verify socket exists and is working
    if [ ! -S "$SSH_SOCKET" ] && [ ! -L "$SSH_SOCKET" ]; then
      log_error "Socket does not exist: $SSH_SOCKET"
      exit 1
    fi
    # Check if it's a symlink and resolve it
    local resolved_socket="$SSH_SOCKET"
    if [ -L "$SSH_SOCKET" ]; then
      resolved_socket=$(readlink -f "$SSH_SOCKET" 2>/dev/null || readlink "$SSH_SOCKET")
      log_debug "Socket $SSH_SOCKET is a symlink pointing to: $resolved_socket"
    fi
    if [ ! -S "$resolved_socket" ]; then
      log_error "Socket symlink target does not exist: $resolved_socket"
      exit 1
    fi
    if ! verify_socket_working "$SSH_SOCKET"; then
      log_error "Socket is not working: $SSH_SOCKET"
      exit 1
    fi
    # Debug: Show socket details and available keys
    if [ "${DEBUG:-0}" == "1" ]; then
      log_debug "Socket details:"
      log_debug "  Selected socket: $SSH_SOCKET"
      if [ -L "$SSH_SOCKET" ]; then
        log_debug "  Type: symlink -> $resolved_socket"
      else
        log_debug "  Type: regular socket"
      fi
      log_debug "  Available keys:"
      SSH_AUTH_SOCK="$SSH_SOCKET" ssh-add -l 2>&1 | while IFS= read -r line; do
        log_debug "    $line"
      done
      log_debug "  Other socket paths:"
      log_debug "    MUX_SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK"
      log_debug "    SCA_SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK"
      log_debug "    ORG_SSH_AUTH_SOCK=$ORG_SSH_AUTH_SOCK"
      if [ -n "$TEMP_AGENT_SOCK" ]; then
        log_debug "    TEMP_AGENT_SOCK=$TEMP_AGENT_SOCK"
      fi
    fi
    log_info "Connecting via SSH config (IdentityAgent will use $SSH_SOCKET): ssh $SSH_ARGS"
    # SSH config already has IdentityAgent set to mux socket, so just run ssh normally
    local ssh_cmd="ssh"
    # Add verbose flag in debug mode
    if [ "${DEBUG:-0}" == "1" ]; then
      ssh_cmd="$ssh_cmd -v"
    fi
    ssh_cmd="$ssh_cmd $SSH_ARGS"
    if [ "${DEBUG:-0}" == "1" ]; then
      log_debug "Executing SSH command: $ssh_cmd"
      log_debug "SSH_AUTH_SOCK environment variable: ${SSH_AUTH_SOCK:-not set}"
      # Show what SSH config resolves to for the target host
      local target_host
      target_host=$(echo "$SSH_ARGS" | awk '{print $1}')
      if [ -n "$target_host" ]; then
        log_debug "SSH config resolution for host '$target_host':"
        ssh -G "$target_host" 2>/dev/null | grep -E "^identityagent" | while IFS= read -r line; do
          log_debug "  Config: $line"
        done
        # Resolve the IdentityAgent path from config
        local config_identityagent
        config_identityagent=$(ssh -G "$target_host" 2>/dev/null | grep "^identityagent " | sed 's/^identityagent //')
        if [ -n "$config_identityagent" ]; then
          log_debug "  SSH config IdentityAgent resolves to: $config_identityagent"
          if [ -L "$config_identityagent" ]; then
            local resolved_agent
            resolved_agent=$(readlink -f "$config_identityagent" 2>/dev/null || readlink "$config_identityagent")
            log_debug "  Which is a symlink to: $resolved_agent"
            log_debug "  Keys in resolved agent:"
            SSH_AUTH_SOCK="$config_identityagent" ssh-add -l 2>&1 | while IFS= read -r line; do
              log_debug "    $line"
            done
          elif [ -S "$config_identityagent" ]; then
            log_debug "  Which is a regular socket"
            log_debug "  Keys in this agent:"
            SSH_AUTH_SOCK="$config_identityagent" ssh-add -l 2>&1 | while IFS= read -r line; do
              log_debug "    $line"
            done
          fi
        fi
      fi
      log_debug "Command will be executed with: eval"
      log_debug "Environment variables that will be set:"
      log_debug "  SSH_AUTH_SOCK=$SSH_SOCKET (will be set to this value)"
      # Verify the agent socket before executing
      log_debug "Verifying agent socket before SSH execution:"
      SSH_AUTH_SOCK="$SSH_SOCKET" ssh-add -l 2>&1 | while IFS= read -r line; do
        log_debug "  Agent keys: $line"
      done
    fi
    SSH_AUTH_SOCK="$SSH_SOCKET" eval "$ssh_cmd"
    local ssh_exit_code=$?
    if [ $ssh_exit_code -ne 0 ]; then
      log_error "SSH command failed with exit code $ssh_exit_code"
    fi
    # Clean up temporary agent after SSH connection completes
    # The temporary agent was multiplexed with the remote agent, so it's no longer needed
    if [ -n "$TEMP_AGENT_PID" ]; then
      log_info "Cleaning up temporary SSH agent after SSH connection"
      cleanup_temp_agent
    fi
    exit $ssh_exit_code
    
  elif [ "$SUBSHELL_MODE" == "1" ]; then
    # Subshell Mode: Open a subshell with the MUX agent environment set
    log_info "Starting subshell with MUX agent environment"
    $SHELL

  elif [ -n "$CMD" ]; then
    log_info "STARTING: $CMD"
    eval $CMD

  elif [ -n "$WAIT" ]; then
    # Wait Mode: Monitor connection and restart if needed
    log_info "WAIT in a Loop and check every $CHECK_SECONDS if the Connection is dead"
    while true; do
      # Check if we're intentionally exiting (Ctrl-C, etc.)
      if [ "$SCA_EXITING" == "true" ]; then
        log_info "Exiting..."
        break
      fi
      
      # Check the appropriate socket based on whether we're using multiplexer
      SOCKET_TO_CHECK="$MUX_SSH_AUTH_SOCK"
      if [ ! -S "$MUX_SSH_AUTH_SOCK" ] || [ "$MUX_SSH_AUTH_SOCK" == "$SCA_SSH_AUTH_SOCK" ]; then
        # No multiplexer, check remote agent directly
        SOCKET_TO_CHECK="$SCA_SSH_AUTH_SOCK"
      fi
      
      if ! verify_socket_working "$SOCKET_TO_CHECK"; then
        # Don't restart if we're intentionally exiting
        if [ "$SCA_EXITING" == "true" ]; then
          log_info "Exiting due to intentional termination"
          break
        fi
        log_error "Can not Connect to agent!"
        log_info "Stopping background processes before restart..."
        kill_if_exists "$SSH_PID" "SSH"
        kill_if_exists "$MUX_PID" "MUX"
        # Restart Myself
        export SCA_SUBSHELL=
        export SSH_AUTH_SOCK=$ORG_SSH_AUTH_SOCK
        log_info "Restarting MYSELF: $SCA_SCRIPT $ORG_ARGS"
        exec $SCA_SCRIPT $ORG_ARGS
        exit 255 # Should never be reached
      else
        echo -n "." >&2
      fi
      sleep $CHECK_SECONDS
    done
    
  else
    # Default: Start Interactive Subshell
    log_info "Starting Subshell"
    $SHELL
  fi
}

# Patch SSH config: add jump aliases (sca-jump, jump, etc.) to the Host line for
# this user's level in config_single.
# - 1st sed: strip any existing aliases after -sca-magic-jump (reset before re-apply)
# - 2nd sed: append "jump jump_local jump_my sca-jump ..." to L$MY_LEVEL-sca-magic-jump
#
# Only patches when needed; uses $PLAYBOOK_DIR/.sca-jump-level to remember:
# - LEVEL: last patched level. Re-patch if MY_LEVEL != LEVEL (backend or --level change).
# - If config_single is newer than the status file, re-patch (Ansible overwrote).
patch_jump_aliases() {
  local f single status need=0
  status="$PLAYBOOK_DIR/.sca-jump-level"
  single="$PLAYBOOK_DIR/${SSH_CONFIG_FILE}_single"

  log_info "Patching jump aliases (sca-jump, jump, etc.) for level $MY_LEVEL in SSH config"

  # Need to patch if: no status yet, level changed, or config was overwritten (e.g. Ansible)
  if [ ! -f "$status" ]; then
    need=1
    log_debug "Patch: no status file, will patch"
  else
    local stored
    stored=$(grep -E '^LEVEL=' "$status" 2>/dev/null | cut -d= -f2)
    if [ "$stored" != "$MY_LEVEL" ]; then
      need=1
      log_info "Patch: level changed ($stored -> $MY_LEVEL), will patch"
    elif [ -f "$single" ] && [ "$single" -nt "$status" ]; then
      need=1
      log_info "Patch: ${SSH_CONFIG_FILE}_single newer than status (e.g. Ansible), will patch"
    fi
  fi

  [ "$need" -eq 0 ] && log_debug "Patch: level $MY_LEVEL already applied, skip" && return 0

  log_info "Patching jump aliases (sca-jump, jump, etc.) for level $MY_LEVEL in SSH config"
  for f in "$single"; do
    if [ ! -f "$f" ]; then
      log_debug "  Skip (not a file): $f"
      continue
    fi
    log_info "  Patching: $f"
    sed -i.bak \
      -e "s/\(-sca-magic-jump\)\(.*\)$/\1/g" \
      -e "s/\(L$MY_LEVEL-sca-magic-jump\)/\1 jump jump_local jump_my sca-jump sca-jump_org sca-jump_local sca-jump_my sca-jump_mux/g" \
      "$f"
  done
  echo "LEVEL=$MY_LEVEL" > "$status"
  touch "$status"
}

# Setup new connection
setup_new_connection() {
  log_info "No working agent found: Starting new connection"
  rm -f $SCA_SSH_AUTH_SOCK
  rm -f $MUX_SSH_AUTH_SOCK

  # Determine User Security Level
  MY_LEVEL=$(determine_security_level)
  if [ $? -ne 0 ]; then
    exit 1
  fi
  
  log_info "You are a Level $MY_LEVEL user"
  
  if [ -n "$LEVEL" ]; then
    if [ "$LEVEL" -ne "$MAX_LEVEL" ] && [ "$LEVEL" -lt "$MY_LEVEL" ]; then
      # User Requesting Lower Level, allow it
      log_warn "LOWER level to $LEVEL"
      MY_LEVEL=$LEVEL
    fi
  else
    log_error "Can not find your level (Maybe something is not working). Stopping"
    exit 1
  fi

  # Start Remote SSH Agent Forwarder
  # We must use an "interactive" ssh shell here, because we rely on running
  # a few commands in the global bashrc on the jumphost
  SSH_PID=$(start_remote_agent "$MY_LEVEL")
  if [ $? -ne 0 ]; then
    exit 1
  fi

  # Configure SSH Config for Jump Host Selection (adds sca-jump etc. for this level)
  patch_jump_aliases

  log_success "Successfully started a remote agent at $SCA_SSH_AUTH_SOCK"
  
  # Keep temporary agent alive - it will be multiplexed with remote agent
  if [ -n "$TEMP_AGENT_PID" ]; then
    log_info "Keeping temporary SSH agent (will be multiplexed with remote agent)"
    if [ "${DEBUG:-0}" == "1" ]; then
      log_debug "Temporary agent details:"
      log_debug "  PID: $TEMP_AGENT_PID"
      log_debug "  Socket: $TEMP_AGENT_SOCK"
      log_debug "  Will be multiplexed with remote agent"
    fi
    # Don't reset LOCAL_SOCK - we still have the temporary agent
  fi
  
  # Setup Agent Multiplexer
  # If we have a temporary agent (from identity file), use it as the local agent
  # Otherwise, use the original SSH_AUTH_SOCK as the local agent
  local local_agent_sock=""
  if [ -n "$TEMP_AGENT_SOCK" ] && [ -S "$TEMP_AGENT_SOCK" ]; then
    # Use temporary agent as the local agent for multiplexing
    local_agent_sock="$TEMP_AGENT_SOCK"
    log_info "Will multiplex temporary agent (local key) with remote agent"
  elif [ "$LOCAL_SOCK" == "true" ] && [ -n "$ORG_SSH_AUTH_SOCK" ] && [ -S "$ORG_SSH_AUTH_SOCK" ]; then
    # Use original local agent
    local_agent_sock="$ORG_SSH_AUTH_SOCK"
    log_info "Will multiplex local agent with remote agent"
  else
    log_info "No local agent, will use remote agent only"
  fi
  
  # Always set up multiplexer when we have a remote agent
  # If we have a local/temporary agent, multiplex them
  # If not, the multiplexer will just forward to the remote agent
  if verify_socket_working "$SCA_SSH_AUTH_SOCK"; then
    log_info "Muxing the agents to one"
    USE_RUST_MUX=false
    [ "$MUX_TYPE" = "rust" ] && USE_RUST_MUX=true
    
    # Save original local agent socket before setting up multiplexer
    # The multiplexer functions expect ORG_SSH_AUTH_SOCK to be the local agent
    local saved_org_sock="$ORG_SSH_AUTH_SOCK"
    if [ -n "$local_agent_sock" ] && [ -S "$local_agent_sock" ]; then
      # We have a local/temporary agent - use it for multiplexing
      ORG_SSH_AUTH_SOCK="$local_agent_sock"
    else
      # No local agent - pass a dummy path that the multiplexer will detect as invalid
      # The multiplexer will then just use the remote agent (SSH_AUTH_SOCK)
      ORG_SSH_AUTH_SOCK="/dev/null"
    fi
    
    if [ "$USE_RUST_MUX" == "true" ]; then
      setup_rust_multiplexer
    else
      setup_python_multiplexer
    fi
    
    # Restore original ORG_SSH_AUTH_SOCK
    ORG_SSH_AUTH_SOCK="$saved_org_sock"
      
    # Set up multiplexer socket link
    MUX_PID=$OMUX_SSH_AGENT_PID
    # Only create symlink if socket path is different from target
    # Skip symlink creation for Rust mux direct mode since socket is already at target location
    if [ "${SKIP_SYMLINK:-false}" != "true" ]; then
        # Expand paths for comparison (handle ~ expansion)
        OMUX_EXPANDED=$(echo "$OMUX_SSH_AUTH_SOCK" | sed "s|^~|$HOME|")
        TARGET_EXPANDED=$(echo "$MUX_SSH_AUTH_SOCK" | sed "s|^~|$HOME|")
        if [ "$OMUX_EXPANDED" != "$TARGET_EXPANDED" ]; then
            ln -sf "$OMUX_SSH_AUTH_SOCK" $MUX_SSH_AUTH_SOCK
        fi
    fi
    export ORG_MUX_SSH_AUTH_SOCK=$OMUX_SSH_AUTH_SOCK
    export SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK
    
    log_info "Verifying with: 'SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK ssh-add -l'"
    log_success "You can now use this key (even not in this SUBSHELL, thanks to .ssh/config magic)"
    SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK ssh-add -l 2>&1 | while IFS= read -r line; do
      log_info "$line"
    done
  else
    log_error "Remote agent socket not available"
    exit 1
  fi
}

#==============================================================================
# CONNECTION MANAGEMENT
#==============================================================================

# Validate local SSH agent or identity file
validate_local_agent() {
  # Check if local SSH agent is working
  LOCAL_SOCK=false
  USE_IDENTITY_FILE=false
  IDENTITY_FILE=""

  check_agent_socket "$SSH_AUTH_SOCK" && LOCAL_SOCK=true

  if [ "$LOCAL_SOCK" == "false" ]; then
    # No agent found, check for identity files
    log_info "No local SSH agent found, checking for identity files..."
    IDENTITY_FILE=$(find_identity_file)
    if [ -n "$IDENTITY_FILE" ]; then
      USE_IDENTITY_FILE=true
      log_success "Found identity file: $IDENTITY_FILE"
      # Create temporary agent to avoid multiple passphrase prompts
      if setup_temp_agent "$IDENTITY_FILE"; then
        LOCAL_SOCK=true  # We now have a temporary agent
        log_info "Using temporary SSH agent for initial connections"
      else
        log_error "Failed to set up temporary SSH agent"
        exit 1
      fi
    else
      log_error 'No local SSH agent or identity file found.'
      log_error 'Either start an agent with "eval $(ssh-agent)" and add your keys,'
      log_error 'or ensure you have an identity file at ~/.ssh/id_ed25519, ~/.ssh/id_rsa, etc.'
      exit 1
    fi
  else
    # Agent exists, check if it has keys loaded
    LOCAL_KEYS_NUM=$(ssh-add -l 2>/dev/null | wc -l)
    if [ -z "$LOCAL_KEYS_NUM" ] || [ "$LOCAL_KEYS_NUM" == "0" ]; then
      log_warn "Your local agent has no keys loaded"
      log_info "Checking for identity files as fallback..."
      IDENTITY_FILE=$(find_identity_file)
      if [ -n "$IDENTITY_FILE" ]; then
        USE_IDENTITY_FILE=true
        log_success "Found identity file: $IDENTITY_FILE (will use instead of empty agent)"
        # Create temporary agent to avoid multiple passphrase prompts
        if setup_temp_agent "$IDENTITY_FILE"; then
          LOCAL_SOCK=true  # We now have a temporary agent
          log_info "Using temporary SSH agent for initial connections"
        else
          log_error "Failed to set up temporary SSH agent"
          exit 1
        fi
      else
        log_error "You have no key in your local agent and no identity file found!"
        exit 1
      fi
    else
      MYKEYS=$(ssh-add -l | wc -l)
      log_success "You have $MYKEYS keys in your local agent"
    fi
  fi
}

# Check existing connections and clean up stale ones
check_existing_connections() {
  SCA_SOCK=false
  MUX_SOCK=false
  MY_SOCKS_WORKING=true

  # Check if socket exists and is working, AND if the SSH process is still running
  if verify_remote_agent_working "$SCA_SSH_AUTH_SOCK"; then
    SCA_SOCK=true
  fi

  # Only check for mux socket if we're using multiplexer (will be determined later)
  # For now, check if it exists and is working
  if [ -S "$MUX_SSH_AUTH_SOCK" ]; then
    if check_agent_socket "$MUX_SSH_AUTH_SOCK" && check_ssh_agent_running; then
      MUX_SOCK=true
    fi
  fi

  # If remote socket is not working or SSH process is dead, we need to restart
  # If mux socket doesn't exist but remote does, that's OK (might be identity-file-only mode)
  if [ "$SCA_SOCK" == "false" ]; then
    log_info "Cleaning up stale connections"
    kill_all_sca_processes
    log_info "Removing stale socket files"
    rm -f "$SCA_SSH_AUTH_SOCK" 2>/dev/null || true
    rm -f "$MUX_SSH_AUTH_SOCK" 2>/dev/null || true
    MY_SOCKS_WORKING=false
  elif [ "$MUX_SOCK" == "false" ] && [ -S "$MUX_SSH_AUTH_SOCK" ]; then
    # Mux socket exists but not working - restart multiplexer
    log_info "Mux socket exists but not working, restarting multiplexer"
    kill_processes "$PROC_PYTHON_MUX" "Python multiplexer"
    kill_process_by_name "$PROC_RUST_MUX"
    rm -f "$MUX_SSH_AUTH_SOCK" 2>/dev/null || true
    MY_SOCKS_WORKING=false
  fi
}

# Use existing connection
use_existing_connection() {
  # If we need a local key (for determine_security_level or ProxyCommand),
  # check if we need to create a temporary agent BEFORE calling determine_security_level
  # This avoids prompting for passphrase twice
  if [ -z "$TEMP_AGENT_SOCK" ]; then
    # Check if we have a local agent (original SSH_AUTH_SOCK or ORG_SSH_AUTH_SOCK)
    local has_local_agent=false
    if verify_socket_working "$ORG_SSH_AUTH_SOCK"; then
      has_local_agent=true
    elif verify_socket_working "$SSH_AUTH_SOCK"; then
      # Check if this is not the remote agent socket
      if [ "$SSH_AUTH_SOCK" != "$SCA_SSH_AUTH_SOCK" ] && [ "$SSH_AUTH_SOCK" != "$MUX_SSH_AUTH_SOCK" ]; then
        has_local_agent=true
      fi
    fi
    
    if [ "$has_local_agent" == "false" ]; then
      # No local agent - check if mux socket has local key
      local needs_local_key=true
      IDENTITY_FILE=$(find_identity_file)
      if [ -n "$IDENTITY_FILE" ] && verify_socket_working "$MUX_SSH_AUTH_SOCK"; then
        # Try to get fingerprint of identity file
        local id_fingerprint
        id_fingerprint=$(ssh-keygen -lf "$IDENTITY_FILE" 2>/dev/null | awk '{print $2}')
        if [ -n "$id_fingerprint" ]; then
          # Check if mux socket has this key
          if SSH_AUTH_SOCK="$MUX_SSH_AUTH_SOCK" ssh-add -l 2>/dev/null | grep -q "$id_fingerprint"; then
            needs_local_key=false
            log_info "Mux socket already has local key, no need to create temporary agent"
          fi
        fi
      fi
      
      # If we need a local key and have an identity file, create temporary agent
      # This is needed for determine_security_level() and potentially for ProxyCommand
      if [ "$needs_local_key" == "true" ] && [ -n "$IDENTITY_FILE" ]; then
        log_info "Creating temporary SSH agent for local key (needed for connection)..."
        if setup_temp_agent "$IDENTITY_FILE"; then
          USE_IDENTITY_FILE=true
          log_info "Temporary SSH agent created"
        else
          log_warn "Failed to create temporary agent, connection may fail"
        fi
      fi
    fi
  fi
  
  # Now determine level (will use temp agent if we just created one)
  MY_LEVEL=$(determine_security_level)
  if [ $? -ne 0 ]; then
    log_error "Failed to determine security level for existing connection"
    exit 1
  fi
  
  # Ensure SSH config is patched with jump aliases for this level
  # This is needed because Ansible might have regenerated the config,
  # or the level might have changed
  patch_jump_aliases
  
  # Keep temporary agent alive - it will be multiplexed with remote agent
  if [ -n "$TEMP_AGENT_PID" ]; then
    log_info "Keeping temporary SSH agent (will be multiplexed with remote agent)"
    if [ "${DEBUG:-0}" == "1" ]; then
      log_debug "Temporary agent details:"
      log_debug "  PID: $TEMP_AGENT_PID"
      log_debug "  Socket: $TEMP_AGENT_SOCK"
      log_debug "  Will be multiplexed with remote agent"
    fi
  fi
  
  if [ -n "$LEVEL" ]; then
    if [ "$LEVEL" -ne "$MAX_LEVEL" ] && [ "$LEVEL" -lt "$MY_LEVEL" ]; then
      # User Requesting Lower Level, allow it
      log_warn "LOWER level to $LEVEL"
      MY_LEVEL=$LEVEL
    fi
  fi

  # If we have a temporary agent and a remote agent, set up multiplexer
  # This ensures both keys are available (temp agent for ProxyCommand, remote for main connection)
  if [ -n "$TEMP_AGENT_SOCK" ] && [ -S "$TEMP_AGENT_SOCK" ] && verify_socket_working "$SCA_SSH_AUTH_SOCK"; then
    # Check if mux socket already exists and has both keys
    local needs_mux_setup=true
    if verify_socket_working "$MUX_SSH_AUTH_SOCK"; then
      # Check if mux socket has the temporary agent's key
      local temp_key_fingerprint
      temp_key_fingerprint=$(SSH_AUTH_SOCK="$TEMP_AGENT_SOCK" ssh-add -l 2>/dev/null | head -1 | awk '{print $2}')
      if [ -n "$temp_key_fingerprint" ]; then
        if SSH_AUTH_SOCK="$MUX_SSH_AUTH_SOCK" ssh-add -l 2>/dev/null | grep -q "$temp_key_fingerprint"; then
          needs_mux_setup=false
        fi
      fi
    fi
    
    if [ "$needs_mux_setup" == "true" ]; then
      log_info "Setting up multiplexer for temporary agent + remote agent"
      local local_agent_sock="$TEMP_AGENT_SOCK"
      USE_RUST_MUX=false
      [ "$MUX_TYPE" = "rust" ] && USE_RUST_MUX=true
      
      local saved_org_sock="$ORG_SSH_AUTH_SOCK"
      ORG_SSH_AUTH_SOCK="$local_agent_sock"
      
      if [ "$USE_RUST_MUX" == "true" ]; then
        setup_rust_multiplexer
      else
        setup_python_multiplexer
      fi
      
      ORG_SSH_AUTH_SOCK="$saved_org_sock"
      
      MUX_PID=$OMUX_SSH_AGENT_PID
      if [ "${SKIP_SYMLINK:-false}" != "true" ]; then
        OMUX_EXPANDED=$(echo "$OMUX_SSH_AUTH_SOCK" | sed "s|^~|$HOME|")
        TARGET_EXPANDED=$(echo "$MUX_SSH_AUTH_SOCK" | sed "s|^~|$HOME|")
        if [ "$OMUX_EXPANDED" != "$TARGET_EXPANDED" ]; then
          ln -sf "$OMUX_SSH_AUTH_SOCK" $MUX_SSH_AUTH_SOCK
        fi
      fi
      export ORG_MUX_SSH_AUTH_SOCK=$OMUX_SSH_AUTH_SOCK
      export SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK
    fi
  fi

  # Use the multiplexed socket if available, otherwise use remote agent
  if verify_socket_working "$MUX_SSH_AUTH_SOCK"; then
    log_info "Using working multiplexed SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK"
    export SSH_AUTH_SOCK=$MUX_SSH_AUTH_SOCK
  elif verify_socket_working "$SCA_SSH_AUTH_SOCK"; then
    log_info "Using working remote SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK"
    export SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK
    export MUX_SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK
  else
    log_error "No working agent socket found"
    exit 1
  fi
  
  # Show available keys from the mux socket (which has both local and remote keys if multiplexed)
  log_info "Verifying with: 'SSH_AUTH_SOCK=$SSH_AUTH_SOCK ssh-add -l'"
  SSH_AUTH_SOCK=$SSH_AUTH_SOCK ssh-add -l 2>&1 | while IFS= read -r line; do
    log_info "$line"
  done
}

# Check if ssh-agent-mux is installed and config exists
check_rust_mux_installed() {
    if ! command -v ssh-agent-mux >/dev/null 2>&1; then
        log_error "ssh-agent-mux not found in PATH"
        log_info "Hint: Install it from https://github.com/overhacked/ssh-agent-mux"
        log_info "Hint: cargo install ssh-agent-mux"
        log_info "Hint: Or download binary from releases page"
        exit 1
    fi

    CONFIG_FILE="$HOME/.config/ssh-agent-mux/ssh-agent-mux.toml"
    if [ ! -f "$CONFIG_FILE" ]; then
        log_error "Config file not found at $CONFIG_FILE"
        log_info "Hint: Create it with the following content:"
        echo 'agent_sock_paths = [' >&2
        echo '    "'"$SSH_AUTH_SOCK"'",  # Your local agent' >&2
        echo '    "~/.ssh/scadev-agent.sock",  # Remote agent' >&2
        echo ']' >&2
        echo 'listen_path = "~/.ssh/ssh-agent-mux.sock"' >&2
        exit 1
    fi
    echo "$CONFIG_FILE"
}

# Check if ssh-agent-mux is running as a service
check_rust_mux_service() {
    if [[ "$OSTYPE" == "darwin"* ]]; then
        PLIST_FILE="$HOME/Library/LaunchAgents/net.ross-williams.ssh-agent-mux.plist"
        if [ -f "$PLIST_FILE" ] && launchctl list 2>/dev/null | grep -q "net.ross-williams.ssh-agent-mux"; then
            log_success "Detected ssh-agent-mux as launchd service"
            return 0
        fi
    elif command -v systemctl >/dev/null 2>&1; then
        if systemctl --user list-unit-files 2>/dev/null | grep -q "ssh-agent-mux.service"; then
            log_success "Detected ssh-agent-mux as systemd service"
            return 0
        fi
    fi
    return 1
}

# Setup Rust multiplexer in service mode
setup_rust_mux_service_mode() {
    local config_file=$1
    local rust_mux_socket
    
    # Extract socket path from config (default: ~/.ssh/ssh-agent-mux.sock)
    rust_mux_socket=$(grep -E '^\s*listen_path\s*=' "$config_file" | sed -E 's/^[^"]*"([^"]+)".*/\1/' | sed "s|~|$HOME|")
    rust_mux_socket="${rust_mux_socket:-$HOME/.ssh/ssh-agent-mux.sock}"

    if ! pgrep -x "$PROC_RUST_MUX" >/dev/null; then
        log_error "ssh-agent-mux service is not running"
        log_info "Hint: Start it with: ssh-agent-mux --restart-service"
        if [[ "$OSTYPE" == "darwin"* ]]; then
            log_info "Hint: Or (macOS): launchctl kickstart -k gui/$(id -u)/net.ross-williams.ssh-agent-mux"
        elif command -v systemctl >/dev/null 2>&1; then
            log_info "Hint: Or (Linux): systemctl --user start ssh-agent-mux.service"
        fi
        exit 1
    fi

    # Configure macOS logging if needed
    if [[ "$OSTYPE" == "darwin"* ]]; then
        local plist_file="$HOME/Library/LaunchAgents/net.ross-williams.ssh-agent-mux.plist"
        if [ -f "$plist_file" ] && { ! grep -q "StandardOutPath" "$plist_file" || ! grep -q "StandardErrorPath" "$plist_file"; }; then
            log_info "Configuring file-based logging in launchd plist..."
            cp "$plist_file" "$plist_file.bak"
            sed -i '' '/<\/dict>/i\
        <key>StandardOutPath</key>\
        <string>'"$HOME"'/Library/Logs/ssh-agent-mux.log</string>\
        <key>StandardErrorPath</key>\
        <string>'"$HOME"'/Library/Logs/ssh-agent-mux.err.log</string>
' "$plist_file"
            log_info "Restarting ssh-agent-mux service to apply logging configuration..."
            launchctl bootout gui/$(id -u)/net.ross-williams.ssh-agent-mux
            launchctl bootstrap gui/$(id -u) "$plist_file"
            sleep 1
        fi
        
        # Display logs if available
        local macos_log_file="$HOME/Library/Logs/ssh-agent-mux.log"
        if [ -f "$macos_log_file" ]; then
            log_info "ssh-agent-mux logs: $macos_log_file"
            show_harmless_error_note
            echo "$(color_stderr setaf 6)--- Recent log entries (filtered) ---$(color_stderr sgr0)" >&2
            tail -n 50 "$macos_log_file" | filter_rust_mux_errors | tail -n 10 >&2
            echo "$(color_stderr setaf 6)--- Tailing logs (filtered, PID will be cleaned up on exit) ---$(color_stderr sgr0)" >&2
            tail -Fq "$macos_log_file" 2>&1 | filter_rust_mux_errors >&2 &
            TAIL_LOG_PID=$!
        else
            log_info "To view ssh-agent-mux logs (macOS):"
            echo "  log stream --predicate 'process == \"ssh-agent-mux\"' --level debug" >&2
            show_harmless_error_note
        fi
    elif command -v journalctl >/dev/null 2>&1; then
        log_info "ssh-agent-mux logs (Linux systemd):"
        show_harmless_error_note
        echo "$(color_stderr setaf 6)--- Recent log entries (filtered) ---$(color_stderr sgr0)" >&2
        journalctl --user -u ssh-agent-mux -n 50 --no-pager 2>/dev/null | filter_rust_mux_errors | tail -n 10 >&2
        echo "$(color_stderr setaf 6)--- Tailing logs (filtered, PID will be cleaned up on exit) ---$(color_stderr sgr0)" >&2
        journalctl --user -u ssh-agent-mux -f 2>&1 | filter_rust_mux_errors >&2 &
        TAIL_LOG_PID=$!
    fi

    # Warn if remote agent socket is not in config
    if ! grep -q "scadev-agent.sock" "$config_file"; then
        log_warn "Your ssh-agent-mux config does not seem to include ~/.ssh/scadev-agent.sock"
        log_info "Hint: Add it to agent_sock_paths in $config_file:"
        echo 'agent_sock_paths = ["'"$SSH_AUTH_SOCK"'", "~/.ssh/scadev-agent.sock"]' >&2
    fi

    OMUX_SSH_AUTH_SOCK=$rust_mux_socket
    OMUX_SSH_AGENT_PID=""
    SKIP_SYMLINK=false
}

# Setup Rust multiplexer in direct mode
setup_rust_mux_direct_mode() {
    local rust_mux_socket=$MUX_SSH_AUTH_SOCK
    local agent1 agent2 temp_config rust_mux_log
    
    log_info "ssh-agent-mux is not installed as a service, starting it directly"
    rm -f "$rust_mux_socket"
    
    # Determine agent order based on REVERSE flag
    if [ "$REVERSE" == "1" ]; then
        agent1="$SCA_SSH_AUTH_SOCK"
        agent2="$SSH_AUTH_SOCK"
    else
        agent1="$SSH_AUTH_SOCK"
        agent2="$SCA_SSH_AUTH_SOCK"
    fi
    
    # Create temporary config file
    temp_config=$(mktemp)
    cat > "$temp_config" <<EOF
agent_sock_paths = [
    "$agent1",
    "$agent2",
]
listen_path = "$rust_mux_socket"
log_level = "info"
EOF
    
    # Start ssh-agent-mux
    log_info "Starting ssh-agent-mux directly..."
    rust_mux_log=$(mktemp)
    ssh-agent-mux --config "$temp_config" > "$rust_mux_log" 2>&1 &
    RUST_MUX_PID=$!
    log_info "Started ssh-agent-mux as PID $RUST_MUX_PID"
    
    # Tail logs with filtering
    log_info "Starting log tail process for ssh-agent-mux..."
    tail -Fq "$rust_mux_log" 2>&1 | filter_rust_mux_errors >&2 &
    TAIL_LOG_PID=$!
    log_info "Started log tail process as PID $TAIL_LOG_PID"
    
    # Clean up temp config after delay
    (sleep 1 && rm -f "$temp_config") &
    
    # Wait for socket and verify
    if ! wait_for_socket "$rust_mux_socket"; then
        log_error "Failed to start ssh-agent-mux or create socket at $rust_mux_socket"
        kill $RUST_MUX_PID 2>/dev/null
        exit 1
    fi
    
    if ! verify_socket_working "$rust_mux_socket"; then
        log_error "ssh-agent-mux socket created but not responding"
        kill $RUST_MUX_PID 2>/dev/null
        exit 1
    fi
    
    OMUX_SSH_AUTH_SOCK=$rust_mux_socket
    OMUX_SSH_AGENT_PID=$RUST_MUX_PID
    SKIP_SYMLINK=true
    RUST_MUX_LOG=$rust_mux_log
    log_success "Started ssh-agent-mux directly (PID: $RUST_MUX_PID)"
}

# Setup Rust multiplexer (ssh-agent-mux)
setup_rust_multiplexer() {
    local config_file
    
    log_info "Using ssh-agent-mux (Rust)"
    config_file=$(check_rust_mux_installed)
    
    if check_rust_mux_service; then
        setup_rust_mux_service_mode "$config_file"
    else
        setup_rust_mux_direct_mode
    fi
}

#==============================================================================
# ARGUMENT PARSING
#==============================================================================

# Parse command-line arguments
parse_arguments() {
  # Parse arguments manually for cleaner handling of both short and long options
  while [ $# -gt 0 ]; do
  case "$1" in
    -h|--help)
      print_help
      exit 1
      ;;
    -v|--version)
      echo "SCA - SSH Central Agent (Shell version)" >&2
      echo "Script: $SCA_SCRIPT" >&2
      # Expand socket paths (handle ~)
      local sca_sock="${SCA_SSH_AUTH_SOCK:-~/.ssh/scadev-agent.sock}"
      local mux_sock="${MUX_SSH_AUTH_SOCK:-~/.ssh/scadev-mux.sock}"
      local local_sock="${ORG_SSH_AUTH_SOCK:-${SSH_AUTH_SOCK:-}}"
      # Expand ~ to home directory
      sca_sock="${sca_sock/#\~/$HOME}"
      mux_sock="${mux_sock/#\~/$HOME}"
      if [ -n "$local_sock" ]; then
        local_sock="${local_sock/#\~/$HOME}"
      else
        local_sock="(not set)"
      fi
      echo "Remote agent socket: $sca_sock" >&2
      echo "Multiplexer socket: $mux_sock" >&2
      echo "Local agent socket: $local_sock" >&2
      exit 0
      ;;
    -d|--debug)
      DEBUG=1
      shift
      ;;
    -r|--reverse)
      REVERSE=1
      shift
      ;;
    -w|--wait)
      WAIT=1
      shift
      ;;
    -e|--env)
      SHELL_MODE=1
      shift
      ;;
    -l|--level)
      if [ -z "$2" ]; then
        log_error "Option $1 requires an argument"
        exit 1
      fi
      LEVEL="$2"
      shift 2
      ;;
    --level=*)
      LEVEL="${1#*=}"
      shift
      ;;
    --key=local)
      KEY=local
      shift
      ;;
    --key=remote)
      KEY=remote
      shift
      ;;
    --key=mux)
      KEY=mux
      shift
      ;;
    --mux=*)
      MUX_TYPE="${1#*=}"
      shift
      ;;
    --list)
      do_cmd "list"
      exit 1
      ;;
    --find|--add)
      CMD_NAME="${1#--}"
      if [ -z "$2" ]; then
        log_error "Option $1 requires an argument"
        exit 1
      fi
      do_cmd "$CMD_NAME" "$2"
      exit 1
      ;;
    --shell)
      SUBSHELL_MODE=1
      shift
      ;;
    --kill)
      log_info "Killing all agents and remote connections..."
      kill_all_sca_processes
      log_info "Removing socket files"
      rm -f "$SCA_SSH_AUTH_SOCK" "$MUX_SSH_AUTH_SOCK"
      log_success "All agents and connections killed"
      exit 0
      ;;
    --)
      # End of options marker: treat all remaining arguments as SSH arguments
      shift
      SSH_ARGS="$*"
      SSH_MODE=1
      break
      ;;
    --*)
      log_error "Unknown option: $1"
      exit 1
      ;;
    -*)
      # Handle short options that can be combined (e.g., -dr)
      OPTARG="${1#-}"
      while [ -n "$OPTARG" ]; do
        case "${OPTARG:0:1}" in
          h)
            print_help
            exit 1
            ;;
          v)
            echo "SCA - SSH Central Agent (Shell version)" >&2
            echo "Script: $SCA_SCRIPT" >&2
            # Expand socket paths (handle ~)
            local sca_sock="${SCA_SSH_AUTH_SOCK:-~/.ssh/scadev-agent.sock}"
            local mux_sock="${MUX_SSH_AUTH_SOCK:-~/.ssh/scadev-mux.sock}"
            local local_sock="${ORG_SSH_AUTH_SOCK:-${SSH_AUTH_SOCK:-}}"
            # Expand ~ to home directory
            sca_sock="${sca_sock/#\~/$HOME}"
            mux_sock="${mux_sock/#\~/$HOME}"
            if [ -n "$local_sock" ]; then
              local_sock="${local_sock/#\~/$HOME}"
            else
              local_sock="(not set)"
            fi
            echo "Remote agent socket: $sca_sock" >&2
            echo "Multiplexer socket: $mux_sock" >&2
            echo "Local agent socket: $local_sock" >&2
            exit 0
            ;;
          d)
            DEBUG=1
            OPTARG="${OPTARG#?}"
            ;;
          r)
            REVERSE=1
            OPTARG="${OPTARG#?}"
            ;;
          w)
            WAIT=1
            OPTARG="${OPTARG#?}"
            ;;
          e)
            SHELL_MODE=1
            OPTARG="${OPTARG#?}"
            ;;
          s)
            SUBSHELL_MODE=1
            OPTARG="${OPTARG#?}"
            ;;
          l)
            if [ -z "$2" ]; then
              log_error "Option -l requires an argument"
              exit 1
            fi
            LEVEL="$2"
            shift
            OPTARG=""
            ;;
          *)
            log_error "Unknown option: -${OPTARG:0:1}"
            exit 1
            ;;
        esac
      done
      shift
      ;;
    *)
      # Non-option argument - treat as SSH arguments (alias: "sca host" = "sca --ssh host")
      SSH_ARGS="$*"
      SSH_MODE=1
      break
      ;;
  esac
  done
}

#==============================================================================
# MAIN FUNCTION
#==============================================================================

sca_main() {
# Constants
readonly MAX_LEVEL=99                    # Maximum security level to try
readonly SSH_RETRY_MAX=10                # Maximum retries for SSH connection
readonly SSH_RETRY_DELAY=1               # Delay between SSH retries (seconds)
readonly SSH_INITIAL_DELAY=0.1           # Initial delay before checking socket (seconds)
readonly SOCKET_WAIT_MAX=10              # Maximum wait iterations for socket creation
readonly SOCKET_WAIT_DELAY=0.1           # Delay between socket checks (seconds)

# Default values
LEVEL=$MAX_LEVEL            # Maximum security level to try
REVERSE=0                   # Reverse agent order when multiplexing
MUX_TYPE="python"           # Multiplexer type: python (default), rust
CHECK_SECONDS=30            # Seconds between connection checks in wait mode
SHELL_MODE=0                # Output env vars in shell format (like ssh-agent -s)

# Runtime variables
KEY=
ORG_ARGS=$*
ORG_SSH_AUTH_SOCK=$SSH_AUTH_SOCK
SSH_MODE=0                # Direct SSH connection mode
SSH_ARGS=                 # Arguments for SSH command
SUBSHELL_MODE=0           # Open subshell with MUX agent environment
# CMD will be set after argument parsing


print_help() {
  local R B C G Y BL D GR
  local R B C G Y CM
  if [ -t 2 ] && [ -z "${NO_COLOR:-}" ] && command -v tput >/dev/null 2>&1; then
    R=$(tput sgr0)
    B=$(tput bold)
    C=$(tput setaf 6)
    G=$(tput setaf 2)
    Y=$(tput setaf 3)
    CM=$(tput setaf 8 2>/dev/null || tput setaf 7)
  else
    R="" B="" C="" G="" Y="" CM=""
  fi
  local S N P
  S=$(basename "$SCA_SCRIPT")
  N=${#S}
  # ex: print example line with comment aligned at column 48
  # usage: ex <visible_cmd_len> <colored_cmd> <comment>
  ex() {
    local vlen=$1 cmd=$2 cmt=$3
    local pad=$(( 48 - 2 - vlen ))
    [ $pad -lt 2 ] && pad=2
    printf "  %s%*s${CM}# %s${R}\n" "$cmd" "$pad" "" "$cmt"
  }
  cat >&2 <<HELPEOF
${B}${G}SCA - SSH Central Agent${R} - Cross-platform SSH agent multiplexing system

${B}Usage:${R}  $S [OPTIONS] [user@]hostname [ssh-args ...]
        $S -s [OPTIONS]

${B}Options:${R}
  ${C}-h${R}, ${C}--help${R}              Show this help message and exit
  ${C}-v${R}, ${C}--version${R}           Show version information and exit
  ${C}-d${R}, ${C}--debug${R}             Enable debug mode (verbose output)
  ${C}-r${R}, ${C}--reverse${R}           Reverse the order of agents when multiplexing
  ${C}-w${R}, ${C}--wait${R}              Run in background and monitor connection
  ${C}-e${R}, ${C}--env${R}               Output environment variables in shell format
  ${C}-l${R}, ${C}--level${R} ${Y}LEVEL${R}       Set security level (0-3, default: auto-detect)
  ${C}--key${R} ${Y}{local,remote,mux}${R}
                          Specify which key to use
                            ${Y}local${R}:  Use local SSH agent only
                            ${Y}remote${R}: Use remote SSH agent only (default)
                            ${Y}mux${R}:    Use multiplexed agent (local + remote)
  ${C}--mux${R} ${Y}{python,rust}${R}
                          Choose multiplexer type (default: python)
                            ${Y}python${R}: Use Python multiplexer (sshagentmux.py)
                            ${Y}rust${R}:   Use Rust multiplexer (ssh-agent-mux)
                            ${Y}none${R}:   Skip multiplexer, use remote agent only
  ${C}-s${R}, ${C}--shell${R}             Open a subshell with the MUX agent environment set
  ${C}--list${R}                List all configured hosts
  ${C}--find${R} ${Y}HOSTNAME${R}       Find and display information about a specific host
  ${C}--add${R} ${Y}HOSTNAME${R}        Add a new host to the configuration
  ${C}--kill${R}                Kill all agents and remote connections
  ${C}--${R}                    End of options; remaining args passed to ssh

${B}Examples:${R}
  ${CM}# Direct SSH connection (default)${R}
HELPEOF
  ex $((N+1+9))        "$S ${Y}user@host${R}"                                    "Connect using remote agent"      >&2
  ex $((N+12+1+9))     "$S ${C}--key=local${R} ${Y}user@host${R}"                "Connect using local agent"       >&2
  ex $((N+10+1+9))     "$S ${C}--key=mux${R} ${Y}user@host${R}"                  "Connect using multiplexed agent" >&2
  ex $((N+13+1+19))    "$S ${C}--key=remote${R} ${C}--${R} ${Y}-p9922 root@host${R}" "SSH options after --"         >&2
  echo >&2
  echo "  ${CM}# Subshell mode${R}" >&2
  ex $((N+3))          "$S ${C}-s${R}"                                            "Open subshell with MUX agent env"  >&2
  ex $((N+8+1+11))     "$S ${C}--shell${R} ${C}--key=local${R}"                   "Subshell with local agent only"    >&2
  echo >&2
  echo "  ${CM}# Environment & management${R}" >&2
  ex $((6+N+16))       "eval \`$S ${C}-e${R} ${C}--key=local${R}\`"               "Set SSH_AUTH_SOCK in current shell" >&2
  ex $((N+7))          "$S ${C}--list${R}"                                        "List all configured hosts"         >&2
  ex $((N+7+1+8))      "$S ${C}--find${R} ${Y}myserver${R}"                       "Find host 'myserver'"              >&2
  ex $((N+7))          "$S ${C}--wait${R}"                                        "Background monitoring mode"        >&2
  ex $((N+7))          "$S ${C}--kill${R}"                                        "Clean up all agents"               >&2
}

# Parse arguments
# If no arguments provided, show help
if [ $# -eq 0 ]; then
  print_help
  exit 1
fi
parse_arguments "$@"

# Set up exit trap for cleanup
SCA_EXITING=false
trap cleanup EXIT INT TERM

# Check for existing connections first
check_existing_connections

#==============================================================================
# SETUP NEW CONNECTION (if needed)
#==============================================================================

if [ "$MY_SOCKS_WORKING" == "false" ]; then
  # Need to set up a new connection - validate local agent first
  validate_local_agent
  setup_new_connection
else
  # Using existing connection - use_existing_connection will handle local key if needed
  use_existing_connection
fi

#==============================================================================
# SETUP ENVIRONMENT VARIABLES
#==============================================================================

# SSH_AUTH_SOCK and MUX_SSH_AUTH_SOCK are already set above based on whether
# we're using multiplexer or not. Ensure all environment variables are exported.
export SCA_SSH_AUTH_SOCK=$SCA_SSH_AUTH_SOCK
# Ensure MUX_SSH_AUTH_SOCK is set (may be same as SCA_SSH_AUTH_SOCK if no multiplexer)
export MUX_SSH_AUTH_SOCK=${MUX_SSH_AUTH_SOCK:-$SCA_SSH_AUTH_SOCK}
export SCA_SUBSHELL=SCA-KEY
export SCA_USER=$RUSERNAME
export SCA_JUMPHOST=sca-jump-level$MY_LEVEL
export SCA_LEVEL=$MY_LEVEL

log_success "Hello $RUSERNAME($LOGNAME) you are level $SCA_LEVEL and using $SCA_JUMPHOST"

execute_command_or_shell

#==============================================================================
# CLEANUP (fallback - trap handles most cases)
#==============================================================================

kill_if_exists "$SSH_PID" "SSH"
kill_if_exists "$MUX_PID" "MUX"
kill_if_exists "$TAIL_LOG_PID" "log tail"

exit 0
}