chore(local-mounts): 🔧 update SSH agent detection and improve README

- enhance SSH agent forwarding with runtime detection
- update README with clearer instructions and features
- bump version to 1.0.7 in devcontainer-feature.json

Author: baxyz

src/local-mounts/README.md

@@ -6,7 +6,7 @@ Mounts local Git, SSH, GPG, and npm configuration files into the devcontainer fo
 
 - **Git configuration**: Your `.gitconfig` is automatically mounted
 - **SSH keys**: Access your SSH keys for Git operations and remote connections  
-- **SSH agent forwarding (stable)**: Uses `~/.ssh/agent.sock` to avoid dynamic socket path issues
+- **SSH agent forwarding**: Runtime detection with fallback chain (stable socket → VS Code native → legacy)
 - **GPG keys**: Sign commits with your GPG keys
 - **npm authentication**: Your `.npmrc` for private registry access
 - **Post-start verification**: Validates mounted content and reports issues
@@ -49,26 +49,60 @@ This feature mounts host files/directories into the container. Docker bind mount
 - Docker running
 - Host paths to mount must exist (for example: `~/.gitconfig`, `~/.ssh`, `~/.gnupg`, `~/.npmrc`)
 
-### Required for SSH agent forwarding
+### SSH agent forwarding
 
-- An SSH agent must be running on the host
-- Recommended: expose a **stable** socket at `~/.ssh/agent.sock`
+SSH agent forwarding works **out of the box** via VS Code's native mechanism — no extra configuration needed.
 
-Check on host:
+For **optimal reliability** (especially across container rebuilds and reconnections), you can optionally configure a stable socket on your host:
+
+**macOS / Linux (zsh)** — add to `~/.zshrc`:
 
 ```bash
-echo "$SSH_AUTH_SOCK"
-test -S "$SSH_AUTH_SOCK" && echo OK || echo MISSING
-ssh-add -l
+# Stable SSH agent socket (optional, recommended for devcontainers)
+export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"
+if [[ ! -S "$SSH_AUTH_SOCK" ]]; then
+    rm -f "$SSH_AUTH_SOCK"
+    eval "$(ssh-agent -a "$SSH_AUTH_SOCK")" >/dev/null
+    ssh-add 2>/dev/null
+fi
+```
+
+**Linux (bash)** — add to `~/.bashrc`:
 
-# Recommended stable socket for this feature
+```bash
+# Stable SSH agent socket (optional, recommended for devcontainers)
+export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"
+if [ ! -S "$SSH_AUTH_SOCK" ]; then
+    rm -f "$SSH_AUTH_SOCK"
+    eval "$(ssh-agent -a "$SSH_AUTH_SOCK")" > /dev/null
+    ssh-add 2>/dev/null
+fi
+```
+
+**macOS with Keychain** — add to `~/.zshrc`:
+
+```bash
 export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"
 if [[ ! -S "$SSH_AUTH_SOCK" ]]; then
-   rm -f "$SSH_AUTH_SOCK"
-   eval "$(ssh-agent -a "$SSH_AUTH_SOCK")" >/dev/null
+    rm -f "$SSH_AUTH_SOCK"
+    eval "$(ssh-agent -a "$SSH_AUTH_SOCK")" >/dev/null
+    ssh-add --apple-use-keychain 2>/dev/null
 fi
 ```
 
+After adding the snippet, reload your shell (`source ~/.zshrc`) and verify:
+
+```bash
+echo "$SSH_AUTH_SOCK"       # Should show ~/.ssh/agent.sock
+ssh-add -l                  # Should list your keys
+```
+
+The feature detects the socket at **runtime** with this priority:
+
+1. **Stable socket** (`/tmp/local-mounts/.ssh/agent.sock`) — if exposed on the host
+2. **VS Code native forwarding** — automatic, works out of the box
+3. **Legacy `/ssh-agent`** — backward compatibility
+
 If one of these host paths does not exist, container startup can fail with a bind-mount error.
 
 ## Options
@@ -93,7 +127,7 @@ The feature automatically configures these environment variables:
 
 | Variable | Value | Purpose |
 |----------|-------|---------|
-| `SSH_AUTH_SOCK` | `/tmp/local-mounts/.ssh/agent.sock` | SSH agent socket forwarding |
+| `SSH_AUTH_SOCK` | *(set at runtime via `/etc/profile.d/`)* | SSH agent socket — detected with fallback chain |
 | `GPG_TTY` | `/dev/pts/0` | GPG tty for signing |
 
 ## How It Works
@@ -145,24 +179,28 @@ ls -la ~/.gitconfig
 git config --global user.name  # Should show your name
 ```
 
-### SSH keys not working
+### SSH agent not forwarded (Permission denied)
 
-1. Ensure SSH agent is running on host:
-   ```bash
-   ssh-add -l  # Should list your keys
-   ```
+If `git fetch` or `ssh -T git@github.com` fails with `Permission denied (publickey)`:
 
-2. Prefer a stable socket path on host:
+1. Check the socket inside the container:
    ```bash
-   export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"
+   echo "$SSH_AUTH_SOCK"
+   test -S "$SSH_AUTH_SOCK" && echo "OK" || echo "MISSING"
+   ssh-add -l
    ```
 
-3. Inside container, verify:
+2. If the socket is missing, check VS Code's native forwarding on the host:
    ```bash
-   env | grep SSH_AUTH_SOCK
-   ssh-add -l  # Should work
+   # On host
+   ssh-add -l           # Must show keys
+   echo "$SSH_AUTH_SOCK"  # Must point to a valid socket
    ```
 
+3. Optionally configure a stable socket on the host (see SSH section above).
+
+4. Rebuild the container after fixing the host configuration.
+
 ### GPG keys not found
 
 1. Verify GPG is set up locally:
@@ -188,7 +226,8 @@ The `install.sh` script verifies all mounts and provides clear feedback on what'
 
 ## Version History
 
-- **v1.0.5**: Removed fragile direct `$SSH_AUTH_SOCK` bind mount and switched to stable `~/.ssh/agent.sock` strategy
+- **v1.0.7**: Replaced static `containerEnv` SSH_AUTH_SOCK with runtime detection via `/etc/profile.d/` — preserves VS Code native forwarding as fallback
 - **v1.0.6**: Added `username` option with mount staging (`/tmp/local-mounts`) and sync to `/home/<username>`
+- **v1.0.5**: Removed fragile direct `$SSH_AUTH_SOCK` bind mount and switched to stable `~/.ssh/agent.sock` strategy
 - **v1.0.4**: Fixed `.npmrc` mounting with robust fallback verification
 - **v1.0.3**: Initial release

src/local-mounts/devcontainer-feature.json

@@ -1,8 +1,8 @@
 {
   "id": "local-mounts",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "name": "Local Development Files Mount",
-  "description": "Mounts local Git, SSH, GPG, and npm configuration files into the devcontainer with support for custom usernames. Uses a stable SSH socket strategy to avoid dynamic bind-mount failures.",
+  "description": "Mounts local Git, SSH, GPG, and npm configuration files into the devcontainer with support for custom usernames. Uses runtime SSH agent detection with fallback to VS Code native forwarding.",
   "documentationURL": "https://github.com/helpers4/devcontainer/tree/main/features/local-mounts",
   "options": {
     "username": {
@@ -34,8 +34,7 @@
     }
   ],
   "containerEnv": {
-    "GPG_TTY": "/dev/pts/0",
-    "SSH_AUTH_SOCK": "/tmp/local-mounts/.ssh/agent.sock"
+    "GPG_TTY": "/dev/pts/0"
   },
   "installsAfter": [
     "ghcr.io/devcontainers/features/common-utils"

src/local-mounts/install.sh

@@ -153,30 +153,52 @@ _check_mount_status "${TARGET_HOME}" ".gitconfig" ".gitconfig" || true
 
 echo ""
 
-# Test SSH agent forwarding
+# ============================================================================
+# SSH_AUTH_SOCK: Runtime detection with fallback chain
+# ============================================================================
+# containerEnv is static and overrides VS Code's native SSH forwarding.
+# Instead, detect at shell startup time with proper fallback.
+# Priority: 1) Stable host socket  2) VS Code native forwarding  3) Legacy /ssh-agent
+
+cat > /etc/profile.d/local-mounts-ssh.sh << 'PROFILE_EOF'
+# local-mounts: SSH agent socket detection (runtime)
+_LOCAL_MOUNTS_SSH_SOCK="/tmp/local-mounts/.ssh/agent.sock"
+
+if [ -S "$_LOCAL_MOUNTS_SSH_SOCK" ]; then
+    # Stable host socket is mounted and active
+    export SSH_AUTH_SOCK="$_LOCAL_MOUNTS_SSH_SOCK"
+elif [ -n "$SSH_AUTH_SOCK" ] && [ -S "$SSH_AUTH_SOCK" ]; then
+    # VS Code's native SSH agent forwarding is working — keep it
+    :
+elif [ -S "/ssh-agent" ]; then
+    # Legacy external mount
+    export SSH_AUTH_SOCK="/ssh-agent"
+fi
+
+unset _LOCAL_MOUNTS_SSH_SOCK
+PROFILE_EOF
+
+chmod +x /etc/profile.d/local-mounts-ssh.sh
+echo "✅ SSH agent detection installed (/etc/profile.d/local-mounts-ssh.sh)"
+
+# Test SSH agent forwarding at install time (informational only)
 STABLE_SSH_AGENT_SOCKET="${SOURCE_HOME}/.ssh/agent.sock"
 
 if [ -S "$STABLE_SSH_AGENT_SOCKET" ]; then
-    export SSH_AUTH_SOCK="$STABLE_SSH_AGENT_SOCKET"
-    echo "✅ SSH agent forwarding is working (stable socket: $SSH_AUTH_SOCK)"
+    echo "✅ SSH stable socket found at ${STABLE_SSH_AGENT_SOCKET}"
     if command -v ssh-add >/dev/null 2>&1; then
-        if ssh-add -l >/dev/null 2>&1; then
-            KEY_COUNT=$(ssh-add -l 2>/dev/null | wc -l)
-            echo "   - ${KEY_COUNT} SSH key(s) loaded"
-        else
-            echo "   - No SSH keys loaded in agent"
-        fi
+        SSH_AUTH_SOCK="$STABLE_SSH_AGENT_SOCKET" ssh-add -l >/dev/null 2>&1 \
+            && echo "   - SSH keys accessible via stable socket" \
+            || echo "   - No SSH keys loaded in agent"
     fi
 elif [ -n "$SSH_AUTH_SOCK" ] && [ -S "$SSH_AUTH_SOCK" ]; then
-    echo "✅ SSH agent forwarding is working"
+    echo "✅ SSH agent forwarding available (VS Code native: $SSH_AUTH_SOCK)"
 elif [ -S "/ssh-agent" ]; then
-    # Backward compatibility if an external config still mounts /ssh-agent
-    export SSH_AUTH_SOCK="/ssh-agent"
-    echo "✅ SSH agent forwarding is working (legacy socket: $SSH_AUTH_SOCK)"
+    echo "✅ SSH agent forwarding available (legacy socket: /ssh-agent)"
 elif [ -d "${TARGET_HOME}/.ssh" ]; then
-    echo "✅ SSH keys directory available at ${TARGET_HOME}/.ssh"
+    echo "ℹ️  No SSH agent socket found — VS Code native forwarding will be used at runtime"
     if [ -f "${TARGET_HOME}/.ssh/id_rsa" ] || [ -f "${TARGET_HOME}/.ssh/id_ed25519" ]; then
-        echo "   - SSH keys detected"
+        echo "   - SSH keys detected in ${TARGET_HOME}/.ssh"
     fi
 else
     echo "ℹ️  No SSH configuration detected (optional)"

test/local-mounts/test.sh

@@ -41,7 +41,16 @@ for mount in "${MOUNT_POINTS[@]}"; do
     fi
 done
 
-# Test 4: SSH agent socket strategy (informational)
+# Test 4: SSH agent runtime detection script exists
+PROFILE_SCRIPT="/etc/profile.d/local-mounts-ssh.sh"
+if [ -f "$PROFILE_SCRIPT" ]; then
+    echo "✅ PASS: SSH agent detection script installed at ${PROFILE_SCRIPT}"
+else
+    echo "❌ FAIL: SSH agent detection script not found at ${PROFILE_SCRIPT}"
+    exit 1
+fi
+
+# Test 5: SSH agent socket strategy (informational)
 if [ -n "$SSH_AUTH_SOCK" ]; then
     echo "ℹ️  INFO: SSH_AUTH_SOCK is set to: $SSH_AUTH_SOCK"
     if [ -S "$SSH_AUTH_SOCK" ]; then
@@ -50,7 +59,7 @@ if [ -n "$SSH_AUTH_SOCK" ]; then
         echo "⚠️  WARN: SSH_AUTH_SOCK is set but is not a valid socket"
     fi
 else
-    echo "ℹ️  INFO: SSH_AUTH_SOCK not set (SSH agent forwarding optional)"
+    echo "ℹ️  INFO: SSH_AUTH_SOCK not set (will be resolved at shell startup via profile.d)"
 fi
 
 STABLE_SOCKET="/tmp/local-mounts/.ssh/agent.sock"