fix: Improve jump host authentication error messages and documentation

- Add debug logging for config jump_host resolution in dispatcher
- Enhance authentication error messages to clearly indicate which host
  (jump host vs destination) failed and what method was attempted
- Log auto-detected username when not specified in jump_host
- Update --help for -J option with username behavior examples
- Document user field vs jump_host user distinction in README.md
- Add clear examples in example-config.yaml showing user field scope
- Fix flaky tests by adding serial_test annotation

Author: inureyes

README.md

@@ -779,6 +779,24 @@ clusters:
 - Environment variables (`${VAR}` or `$VAR`) are expanded in jump_host values
 - Node-level jump_host requires detailed node syntax (not simple hostname strings)
 
+**Important: Username Handling**
+
+The `user` field in config applies only to **destination nodes**, not to jump hosts:
+
+```yaml
+clusters:
+  internal:
+    nodes:
+      - 192.168.0.100
+    user: admin              # Used for destination (192.168.0.100)
+    jump_host: bai@bastion   # User 'bai' for bastion (jump host)
+```
+
+- **With username in jump_host:** `bai@bastion:4300` → uses "bai" for bastion
+- **Without username:** `bastion:4300` → uses your current local username (like OpenSSH)
+
+If jump host authentication fails due to username mismatch, specify the username explicitly in the `jump_host` field.
+
 ## SSH Configuration Support
 
 bssh fully supports OpenSSH-compatible configuration files via the `-F` flag or default SSH config locations (`~/.ssh/config`, `/etc/ssh/ssh_config`). In addition to standard SSH directives, bssh supports advanced options for certificate-based authentication and port forwarding control.
@@ -1135,7 +1153,7 @@ Options:
   -A, --use-agent                         Use SSH agent for authentication (Unix/Linux/macOS only)
   -P, --password                          Use password authentication (will prompt for password)
   -S, --sudo-password                     Prompt for sudo password to auto-respond to sudo prompts
-  -J, --jump-host <JUMP_HOSTS>            Comma-separated list of jump hosts (ProxyJump)
+  -J, --jump-host <JUMP_HOSTS>            Jump hosts: [user@]host[:port],... (uses local user if not specified)
   -L, --local-forward <SPEC>              Local port forwarding [bind_address:]port:host:hostport
   -R, --remote-forward <SPEC>             Remote port forwarding [bind_address:]port:host:hostport
   -D, --dynamic-forward <SPEC>            Dynamic port forwarding (SOCKS) [bind_address:]port[/version]

example-config.yaml

@@ -1,4 +1,14 @@
 # Example configuration for bssh
+#
+# USER FIELD BEHAVIOR:
+# - 'user' in defaults/cluster applies to DESTINATION nodes only
+# - For jump hosts, specify username in jump_host string: user@jumphost:port
+# - If no username in jump_host, your current local username ($USER) is used
+#
+# Example:
+#   user: admin              # Used for destination nodes
+#   jump_host: bai@bastion   # User 'bai' for bastion, 'admin' for destination
+#
 defaults:
   user: ubuntu
   port: 22
@@ -38,13 +48,17 @@ clusters:
     # jump_host: prod-bastion.example.com
 
   # Example: Cluster behind a jump host/bastion
+  # IMPORTANT: 'user' field applies to DESTINATION nodes only.
+  # For jump host authentication, specify username in jump_host string: user@host:port
+  # If no username is specified in jump_host, your current local username is used.
   internal:
     nodes:
       - host: internal1.private
       - host: internal2.private
       - host: internal3.private
-    user: admin
-    jump_host: bastion.example.com  # All nodes accessible via bastion
+    user: admin  # User for internal*.private (destination nodes)
+    jump_host: [email protected]  # User 'jumpuser' for bastion (jump host)
+    # Alternative: jump_host: bastion.example.com  # Uses your local username for bastion
 
   # Example: Mixed direct and jump host access
   hybrid:

src/app/dispatcher.rs

@@ -416,10 +416,22 @@ async fn handle_exec_command(cli: &Cli, ctx: &AppContext, command: &str) -> Resu
         };
 
         // Resolve jump_hosts: CLI takes precedence, then config
-        let jump_hosts = cli.jump_hosts.clone().or_else(|| {
-            ctx.config
-                .get_cluster_jump_host(ctx.cluster_name.as_deref().or(cli.cluster.as_deref()))
-        });
+        let effective_cluster_name = ctx.cluster_name.as_deref().or(cli.cluster.as_deref());
+        let config_jump_host = ctx.config.get_cluster_jump_host(effective_cluster_name);
+        let jump_hosts = cli.jump_hosts.clone().or(config_jump_host.clone());
+
+        // Debug logging for jump host resolution
+        tracing::debug!(
+            "Jump host resolution: cli={:?}, config={:?}, effective={:?}, cluster={:?}",
+            cli.jump_hosts,
+            config_jump_host,
+            jump_hosts,
+            effective_cluster_name
+        );
+
+        if let Some(ref jh) = jump_hosts {
+            tracing::info!("Using jump host: {}", jh);
+        }
 
         let params = ExecuteCommandParams {
             nodes: ctx.nodes.clone(),

src/cli/bssh.rs

@@ -114,7 +114,14 @@ pub struct Cli {
     #[arg(
         short = 'J',
         long = "jump-host",
-        help = "Comma-separated list of jump hosts (ProxyJump)\nSpecify in [user@]hostname[:port] format, e.g.: 'jump1.example.com' or 'user@jump1:2222,jump2'\nSupports multiple hops for complex network topologies"
+        help = "Comma-separated list of jump hosts (ProxyJump)\n\
+               Format: [user@]hostname[:port]\n\
+               Examples:\n  \
+                 bai@bastion:4300          (user 'bai' on port 4300)\n  \
+                 bastion.example.com       (current local user, port 22)\n  \
+                 user@hop1:22,admin@hop2   (multi-hop chain)\n\
+               Note: If no username specified, your current local username is used.\n\
+               This is separate from -u/--user which sets the destination server user."
     )]
     pub jump_hosts: Option<String>,
 

src/jump/chain.rs

@@ -342,6 +342,24 @@ impl JumpHostChain {
             .await
             .with_context(|| format!("Rate limited for jump host {}", jump_host.host))?;
 
+        // Log the effective username being used, especially helpful when auto-detected
+        let effective_user = jump_host.effective_user();
+        if jump_host.user.is_none() {
+            tracing::info!(
+                "Connecting to jump host {}:{} as user '{}' (auto-detected from current user)",
+                jump_host.host,
+                jump_host.effective_port(),
+                effective_user
+            );
+        } else {
+            tracing::info!(
+                "Connecting to jump host {}:{} as user '{}'",
+                jump_host.host,
+                jump_host.effective_port(),
+                effective_user
+            );
+        }
+
         let auth_method = auth::determine_auth_method(
             jump_host,
             key_path,
@@ -356,7 +374,7 @@ impl JumpHostChain {
             self.connect_timeout,
             crate::ssh::tokio_client::Client::connect(
                 (jump_host.host.as_str(), jump_host.effective_port()),
-                &jump_host.effective_user(),
+                &effective_user,
                 auth_method,
                 check_method,
             ),