Add troubleshooting for wrong SSH_AUTH_SOCK socket issue

Addresses the issue where multiple ssh-agent processes run and the shell
uses /tmp/ssh-* socket instead of systemd's socket.

Improvements:
- Enhanced diagnostic script detects wrong socket usage automatically
- New troubleshooting section for "Multiple ssh-agent processes running"
- Step-by-step fix to clean up ~/.bashrc and use correct socket
- Verification steps to confirm fix

Fixes the symptom: 12 agents running, SSH_AUTH_SOCK pointing to /tmp
instead of ${XDG_RUNTIME_DIR}/ssh-agent.socket

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

VPS-SSH-KEY-SETUP.md

@@ -172,16 +172,42 @@ cat > ~/ssh-diag.sh << 'DIAGEOF'
 #!/bin/bash
 echo "=== SSH Agent Diagnostic ==="
 echo ""
+
+AGENT_COUNT=$(pgrep -u "$USER" ssh-agent | wc -l)
+EXPECTED_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
+
 echo "1. SSH_AUTH_SOCK: $SSH_AUTH_SOCK"
-echo "2. Running agents: $(pgrep -u "$USER" ssh-agent | wc -l)"
-echo "3. Loaded keys:"
+echo "2. Expected socket: $EXPECTED_SOCK"
+echo "3. Running agents: $AGENT_COUNT"
+echo "4. Loaded keys:"
 ssh-add -l 2>&1
 echo ""
-echo "4. Systemd service:"
+echo "5. Systemd service:"
 systemctl --user status ssh-agent 2>&1 | head -5
 echo ""
-echo "5. Shell RC has SSH code:"
+echo "6. Shell RC has SSH code:"
 grep -q "SSH Agent" ~/.bashrc && echo "   ✓ Found" || echo "   ✗ Not found"
+echo ""
+
+# Detect issues
+if [[ "$AGENT_COUNT" -gt 1 ]]; then
+    echo "⚠ WARNING: $AGENT_COUNT agents running (should be 1)"
+    echo "   Fix: See 'Multiple ssh-agent processes' section"
+fi
+
+if [[ "$SSH_AUTH_SOCK" != "$EXPECTED_SOCK" ]]; then
+    echo "⚠ WARNING: Using wrong socket!"
+    echo "   Current: $SSH_AUTH_SOCK"
+    echo "   Should be: $EXPECTED_SOCK"
+    echo "   Fix: See 'Multiple ssh-agent processes' section"
+fi
+
+if systemctl --user is-active ssh-agent >/dev/null 2>&1; then
+    echo "✓ Systemd service is running"
+else
+    echo "✗ Systemd service NOT running"
+    echo "   Fix: systemctl --user start ssh-agent"
+fi
 DIAGEOF
 
 chmod +x ~/ssh-diag.sh
@@ -237,19 +263,46 @@ systemctl --user daemon-reload
 systemctl --user restart ssh-agent
 ```
 
-**Multiple ssh-agent processes running**
+**Multiple ssh-agent processes running (shell using wrong socket)**
+
+If diagnostic shows many agents (e.g., 12) and SSH_AUTH_SOCK points to `/tmp/ssh-*` instead of `${XDG_RUNTIME_DIR}/ssh-agent.socket`:
 
 ```bash
-# Kill all agents
+# 1. Kill all agents and restart systemd service cleanly
 pkill -u "$USER" ssh-agent
-
-# Restart systemd service cleanly
 systemctl --user restart ssh-agent
 
-# Reload shell
+# 2. Check your runtime directory
+echo "Should use: ${XDG_RUNTIME_DIR}/ssh-agent.socket"
+echo "Currently using: $SSH_AUTH_SOCK"
+
+# 3. Clean up ~/.bashrc - remove OLD/duplicate SSH agent code
+cp ~/.bashrc ~/.bashrc.backup
+sed -i '/# SSH Agent/,/fi$/d' ~/.bashrc
+
+# 4. Add clean version
+cat >> ~/.bashrc << 'BASHEOF'
+
+# SSH Agent - Use systemd user service
+export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
+
+# Auto-add key on login
+if [ -z "$(ssh-add -l 2>/dev/null | grep id_ed25519)" ]; then
+    ssh-add ~/.ssh/id_ed25519 2>/dev/null
+fi
+BASHEOF
+
+# 5. Apply immediately
 source ~/.bashrc
+
+# 6. Verify fix
+echo "Agents running: $(pgrep -u "$USER" ssh-agent | wc -l)"  # Should be 1
+echo "Using socket: $SSH_AUTH_SOCK"  # Should contain XDG_RUNTIME_DIR
+ssh-add -l  # Should show your key
 ```
 
+The issue happens when old SSH agent code in ~/.bashrc conflicts with the systemd method.
+
 **"identity_sign: private key contents do not match public"**
 
 This critical error means the public key on Gitea doesn't match your private key.