fix: bind the ssh agent socket from $SSH_AUTH_SOCK, not a guess at its path

`devpod up` refused the create outright on a host whose agent is not a
hand-rolled symlink:

    devcontainer up: runner run container: bind mount source path does not
    exist /home/kinisi/.ssh/agent.sock

The manifest bound ${localEnv:HOME}/.ssh/agent.sock and said so in a comment
calling it "an assumption -- stock OpenSSH puts its agent socket in /tmp --
but a pre-existing one, since containerEnv already hardcodes the same path".
The assumption is false for every agent that picks its own path: gpg-agent,
which is what a YubiKey OpenPGP setup gives you, listens on
$XDG_RUNTIME_DIR/gnupg/S.gpg-agent.ssh; ssh-agent(1) on a /tmp/ssh-XXXX
mktemp path; 1Password and gnome-keyring on paths of their own. None is under
~/.ssh, so the failure lands before the container exists and reads as a
broken tool rather than as this repository naming a path the host never had.

The reverse of the old comment's argument is what the fix rests on:
containerEnv hardcodes the *target*, and that stays hardcoded. Inside the
container SSH_AUTH_SOCK is /home/vscode/.ssh/agent.sock whatever the host
called it, so the source is the only half that has to vary.

init-host.sh cannot paper over this the way it does for known_hosts, which it
touches into existence: there is no touching a socket into being an agent.
What it can do is heal a stale one, and that list named the path the manifest
used to bind, so it moves too -- via $SSH_AUTH_SOCK with the old path kept
beside it, since a container created before this change still has a stale
mount at the old name. Run inside a container this repo built, $SSH_AUTH_SOCK
is the container path, which is exactly the mount that can be stale there: the
variable is the right name at both ends, where the literal was only ever right
by coincidence.

Two costs, both real and neither hidden. An unset SSH_AUTH_SOCK expands to
nothing and the mount is malformed rather than skipped, because
devcontainer.json has no conditional mounts -- a host with no agent at all was
already broken here and is now broken differently. And this is a change under
.devcontainer/, so the prebuild tag moves: every launch builds locally until
devcontainer-prebuild.yml republishes on main.

Two guards, because the target path and the heal list are hand-maintained
copies of the mount source and both had already drifted from it:
test_the_agent_socket_is_bound_from_the_variable_that_names_it and
test_the_host_hook_heals_the_socket_it_is_mounted_from. Both fail against the
old manifest.

Author: JSmithRobotics

.devcontainer/claude-code/init-host.sh

@@ -120,9 +120,20 @@ heal_stale_file_mount() {
     rm -f "$saved"
 }
 
+# The agent socket is named by $SSH_AUTH_SOCK and not as a path under ~/.ssh,
+# because that is the mount's source now: the consuming manifest binds
+# ${localEnv:SSH_AUTH_SOCK}, since ~/.ssh/agent.sock is where almost no agent
+# actually listens (gpg-agent answers under $XDG_RUNTIME_DIR, ssh-agent(1) on a
+# /tmp/ssh-XXXX path). The fallback keeps the old path in the list rather than
+# dropping it, so a container created before that change still has its stale
+# socket mount healed. Run *inside* a container this repo built, $SSH_AUTH_SOCK
+# is /home/vscode/.ssh/agent.sock, which is exactly the mount that can be stale
+# there -- so the variable is the right name to heal at both ends, which the
+# hardcoded path was only ever by coincidence.
 for mounted_file in "$HOME/.claude/CLAUDE.md" "$HOME/.claude/settings.json" \
     "$HOME/.claude/.credentials.json" "$HOME/.claude/.claude.json" \
-    "$HOME/.ssh/known_hosts" "$HOME/.ssh/agent.sock"; do
+    "$HOME/.ssh/known_hosts" "$HOME/.ssh/agent.sock" \
+    "${SSH_AUTH_SOCK:-$HOME/.ssh/agent.sock}"; do
     heal_stale_file_mount "$mounted_file"
 done
 #

.devcontainer/devcontainer.json

@@ -120,10 +120,33 @@
         // known_hosts is read-only because nothing in here has any business
         // adding hosts to the developer's list.
         //
-        // The HOME-relative socket path is an assumption -- stock OpenSSH puts
-        // its agent socket in /tmp -- but a pre-existing one, since
-        // containerEnv already hardcodes the same path.
-        "source=${localEnv:HOME}/.ssh/agent.sock,target=/home/vscode/.ssh/agent.sock,type=bind",
+        // The source is $SSH_AUTH_SOCK, because the agent's path is not
+        // something this file can know. It used to be
+        // ${localEnv:HOME}/.ssh/agent.sock, described here as "an assumption
+        // -- stock OpenSSH puts its agent socket in /tmp -- but a
+        // pre-existing one, since containerEnv already hardcodes the same
+        // path". The assumption is false for every agent that is not a
+        // hand-rolled symlink: gpg-agent (a YubiKey OpenPGP setup) answers on
+        // $XDG_RUNTIME_DIR/gnupg/S.gpg-agent.ssh, ssh-agent(1) on a
+        // /tmp/ssh-XXXX mktemp path, and 1Password and gnome-keyring on paths
+        // of their own. None of them is under ~/.ssh, so `devpod up` failed
+        // before the container existed with "bind mount source path does not
+        // exist", which reads as a broken workspace rather than a
+        // configuration this repository declared.
+        //
+        // The reverse argument, which is what the old comment was reaching
+        // for: containerEnv hardcodes the *target*, and that stays hardcoded.
+        // Inside the container SSH_AUTH_SOCK is /home/vscode/.ssh/agent.sock
+        // whatever the host called it, so the source is the only half that has
+        // to vary and the container end of the contract is unchanged.
+        //
+        // Costs, both real. An unset SSH_AUTH_SOCK expands to nothing and the
+        // mount is malformed rather than skipped, since devcontainer.json has
+        // no conditional mounts -- a host with no agent at all was already
+        // broken here and is now broken differently. And this is a change
+        // under .devcontainer/, so the prebuild tag moves and every launch
+        // builds locally until devcontainer-prebuild.yml republishes on main.
+        "source=${localEnv:SSH_AUTH_SOCK},target=/home/vscode/.ssh/agent.sock,type=bind",
         "source=${localEnv:HOME}/.ssh/known_hosts,target=/home/vscode/.ssh/known_hosts,type=bind,readonly",
         "source=${localEnv:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind"
     ],

test/unit/test_devcontainer_manifest.py

@@ -681,3 +681,45 @@ def test_the_devcontainer_installs_the_committed_lock_rather_than_solving_its_ow
             "create is free to discard the committed lock, solve its own environment over the "
             "network, and rewrite pixi.lock while it does it"
         )
+
+
+def test_the_agent_socket_is_bound_from_the_variable_that_names_it(devcontainer, mounts):
+    """The agent socket mount reads $SSH_AUTH_SOCK, not a guess at where it is.
+
+    This was ``${localEnv:HOME}/.ssh/agent.sock``, and the manifest said so with
+    a comment calling it "an assumption ... but a pre-existing one". It is not a
+    path any agent picks by itself: gpg-agent (a YubiKey OpenPGP setup) listens
+    on ``$XDG_RUNTIME_DIR/gnupg/S.gpg-agent.ssh`` and ``ssh-agent(1)`` on a
+    ``/tmp/ssh-XXXX`` mktemp path, so on such a host ``devpod up`` refused the
+    create outright with ``bind mount source path does not exist`` -- before the
+    container existed, which reads as a broken tool rather than as this file
+    naming a path the host never had.
+
+    ``init-host.sh`` cannot paper over it the way it does for ``known_hosts``:
+    that one is ``touch``ed into existence, and there is no touching a socket
+    into being an agent.
+    """
+    agent_socket = devcontainer["containerEnv"]["SSH_AUTH_SOCK"]
+    sources = {mount.get("source") for mount in mounts if mount.get("target") == agent_socket}
+    assert sources == {"${localEnv:SSH_AUTH_SOCK}"}, (
+        f"the agent socket must be bound from ${{localEnv:SSH_AUTH_SOCK}}; found {sources}"
+    )
+
+
+def test_the_host_hook_heals_the_socket_it_is_mounted_from(devcontainer, mounts):
+    """The heal list names the path the manifest actually binds.
+
+    Two hand-maintained copies of one fact: the mount source here, and the loop
+    in ``init-host.sh`` that detaches a stale one. They disagreed the moment the
+    mount moved, and a heal aimed at a path nothing mounts is a heal that never
+    fires -- silently, since a stale mount only bites a *nested* create.
+    """
+    hook = (REPO_ROOT / ".devcontainer" / "claude-code" / "init-host.sh").read_text()
+    agent_socket = devcontainer["containerEnv"]["SSH_AUTH_SOCK"]
+    source = next(mount["source"] for mount in mounts if mount.get("target") == agent_socket)
+    # "${localEnv:SSH_AUTH_SOCK}" in the manifest is "$SSH_AUTH_SOCK" in the shell.
+    variable = source.removeprefix("${localEnv:").removesuffix("}")
+    assert f"${{{variable}:-" in hook or f"${variable}" in hook, (
+        f"init-host.sh does not heal a stale mount at ${variable}, which is what "
+        "the manifest binds the agent socket from"
+    )