#+TITLE: Finalize the machine-wide SSH_AUTH_SOCK fix (from archangel)
#+DATE: 2026-05-22

* Why this is here

A machine-wide =SSH_AUTH_SOCK= change was started from an *archangel* session and lives in archsetup's =common= stow package, still uncommitted. The goal: every shell and session on a box — login shells, GUI apps, cron, and Claude's non-interactive Bash-tool shells — reaches gpg-agent for SSH keys with no per-script effort, so =ssh= / =ssh-add= to external hosts (e.g. truenas) work anywhere. gpg-agent already has =enable-ssh-support= (per-DE =gpg-agent.conf=); this just points =SSH_AUTH_SOCK= at its fixed socket.

* Current uncommitted state (dotfiles/common)

- =.config/environment.d/envvars.conf= — added =SSH_AUTH_SOCK=${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh= (modified, tracked).
- =.zshenv= — *new file*, exports the same (untracked).
- =~/.zshenv= was symlinked into the stow tree this session to activate it immediately; confirm stow owns it on the next =make restow=.

* The decision to make: one mechanism or two

- *1a — environment.d only.* Matches archsetup's existing convention (env vars already live in envvars.conf), one clean mechanism, no new dotfile type. Drop the =.zshenv=.
- *1b — environment.d + .zshenv.* Belt-and-suspenders: environment.d covers the systemd/GUI session, =.zshenv= guarantees *every* zsh including non-interactive ones (cron, tooling). Cost: a =.zshenv= convention the repo didn't have, and apparent redundancy.

** How to decide (empirically — couldn't be isolated from the archangel session)

The original problem was that *non-interactive* shells (Claude's Bash tool) didn't inherit =SSH_AUTH_SOCK=. The =.zshenv= path was *verified* to fix that; =environment.d=-alone was *not* isolated, because testing it needs the change committed/stowed and a fresh login.

After =make restow= + re-login, in a *non-interactive* shell check whether environment.d alone propagated:
#+begin_src bash
zsh -fc 'echo "${SSH_AUTH_SOCK:-UNSET}"'   # -f skips .zshenv, so this shows environment.d-only reach
#+end_src
- Prints the gpg-agent socket → environment.d reaches non-interactive shells → go *1a*, delete =dotfiles/common/.zshenv= and the =~/.zshenv= symlink.
- Prints =UNSET= → environment.d doesn't reach them → keep *1b*.

* Steps

1. =make restow <de>= so stow owns the symlink(s).
2. Re-login (environment.d reloads at session start).
3. Run the reachability check above; pick 1a or 1b.
4. Commit the dotfile change(s). Conventional-commit, no AI attribution. Suggested subject: =feat(dotfiles): route SSH_AUTH_SOCK through gpg-agent=.

Nothing personal-tooling/.ai is referenced in the dotfiles, so they're clean to commit as-is.