feat: SSH ControlMaster setup in INSTALL.md — auto-detect and configure connection multiplexing

INSTALL.md

@@ -62,6 +62,12 @@ who am i 2>/dev/null
 
 # Kitty remote control (only if kitty is installed)
 kitty @ ls 2>&1 | head -1 || true
+
+# SSH usage — does the user SSH to remote machines for work?
+ls ~/.ssh/config 2>/dev/null && echo "ssh config: found" || echo "ssh config: not found"
+grep -l "ControlMaster\|ControlPath" ~/.ssh/config 2>/dev/null && echo "ssh multiplexing: configured" || echo "ssh multiplexing: not configured"
+ls ~/.ssh/sockets/ 2>/dev/null && echo "ssh sockets dir: exists" || echo "ssh sockets dir: missing"
+ls ~/.ssh/known_hosts 2>/dev/null && wc -l < ~/.ssh/known_hosts 2>/dev/null && echo "known hosts (suggests SSH usage)" || true
 ```
 
 ## Step 2: Evaluate Options
@@ -151,7 +157,43 @@ Based on what the user chose:
    ```
    Without this, tmux intercepts mouse clicks and the user cannot interact with checkboxes, buttons, or inputs in the display pane.
 
-4. **Optional: install chafa** for ASCII art image fallback:
+4. **If the user SSHes to remote machines** (detected by known_hosts having entries, or the user mentions remote work), **set up SSH ControlMaster** so the AI CLI can reuse the user's authenticated SSH connections without needing to re-enter passwords or touch physical keys:
+
+   Ask the user: "Do you SSH into remote machines as part of your work? If so, I can configure SSH connection multiplexing — this lets you authenticate once, and my SSH commands piggyback on your open connection without needing a password."
+
+   If yes:
+   ```bash
+   mkdir -p ~/.ssh/sockets
+   chmod 700 ~/.ssh/sockets
+   ```
+
+   Check if ControlMaster is already configured:
+   ```bash
+   grep -q "ControlMaster" ~/.ssh/config 2>/dev/null && echo "Already configured" || echo "Not configured"
+   ```
+
+   If not configured, add to `~/.ssh/config` (create if needed):
+   ```bash
+   touch ~/.ssh/config
+   chmod 600 ~/.ssh/config
+   cat >> ~/.ssh/config << 'SSHEOF'
+
+   # Kitty-Workbench: SSH connection multiplexing
+   # First connection authenticates normally (password, key, etc.)
+   # Subsequent connections reuse the tunnel — no re-auth needed
+   Host *
+       ControlMaster auto
+       ControlPath ~/.ssh/sockets/%r@%h-%p
+       ControlPersist 600
+   SSHEOF
+   ```
+
+   Explain to the user how it works:
+   > **How this works:** When you SSH into a remote machine, the connection stays open in the background for 10 minutes (`ControlPersist 600`). During that time, any other SSH command to the same host — including ones I run — reuses your authenticated tunnel. No password prompt, no key tap. Just open an SSH session to your target machine before asking me to work on it.
+
+   If the user's `~/.ssh/config` already has Host-specific blocks, add the ControlMaster settings under a `Host *` block at the **end** of the file so it acts as a default without overriding specific host configs.
+
+5. **Optional: install chafa** for ASCII art image fallback:
    - Linux: `sudo apt install chafa` or `sudo pacman -S chafa`
    - macOS: `brew install chafa`