feat: Add comprehensive authentication cache reset utility

Added cj/reset-auth-cache function to recover from incorrect password
entry for encrypted files like authinfo.gpg. Resolves "Bad session key"
and "Decryption failed" errors.

Key features:
- Smart cache clearing: preserves 400-day GPG/SSH cache by default
- Optional prefix arg (C-u) to also clear gpg-agent cache
- Clears auth-source, EPA file handler, and optionally gpg-agent caches
- Bound to C-; A for easy access (removed from debug menu C-c d)

Also added cj/kill-gpg-agent for aggressive agent reset when needed.

Consolidates and replaces simpler auth-source-only version that was
previously in config-utilities.el.

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

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

2 files changed, 62 insertions, 11 deletions

diff --git a/modules/auth-config.el b/modules/auth-config.el
index 8376a2c0..2b52087e 100644
--- a/modules/auth-config.el
+++ b/modules/auth-config.el
@@ -55,5 +55,66 @@
   ;; Allow gpg-agent to cache the passphrase (400 days per gpg-agent.conf)
   (setq plstore-encrypt-to nil)) ;; Use symmetric encryption, not key-based
 
+;; ------------------------ Authentication Reset Utility -----------------------
+
+(defun cj/reset-auth-cache (&optional include-gpg-agent)
+  "Reset authentication caches when wrong password was entered.
+
+By default, only clears Emacs-side caches (auth-source, EPA file
+handler) and leaves gpg-agent's long-term cache intact.  This preserves
+your 400-day cache for GPG and SSH passphrases.
+
+With prefix argument INCLUDE-GPG-AGENT (\\[universal-argument]), also
+clears gpg-agent's password cache.  Use this when gpg-agent itself has
+cached an incorrect password.
+
+Clears:
+1. auth-source cache (Emacs-level credential cache)
+2. EPA file handler cache (encrypted file cache)
+3. gpg-agent cache (only if INCLUDE-GPG-AGENT is non-nil)
+
+Use this when you see errors like:
+  - \"Bad session key\"
+  - \"Decryption failed\"
+  - GPG repeatedly using wrong cached password"
+  (interactive "P")
+  (message "Resetting authentication caches...")
+
+  ;; Clear auth-source cache (Emacs credential cache)
+  (auth-source-forget-all-cached)
+
+  ;; Clear EPA file handler cache
+  (when (fboundp 'epa-file-clear-cache)
+    (epa-file-clear-cache))
+
+  ;; Only clear gpg-agent cache if explicitly requested
+  (if include-gpg-agent
+      (let ((result (shell-command "echo RELOADAGENT | gpg-connect-agent")))
+        (if (zerop result)
+            (message "✓ Emacs and gpg-agent caches cleared. Next access will prompt for password.")
+          (message "⚠ Warning: Failed to clear gpg-agent cache")))
+    (message "✓ Emacs caches cleared. GPG/SSH passphrases preserved for session.")))
+
+(defun cj/kill-gpg-agent ()
+  "Force kill gpg-agent (it will restart automatically on next use).
+
+This is a more aggressive reset than `cj/reset-auth-cache'.  Use this
+when gpg-agent is stuck or behaving incorrectly.
+
+The gpg-agent will automatically restart on the next GPG operation."
+  (interactive)
+  (let ((result (shell-command "gpgconf --kill gpg-agent")))
+    (if (zerop result)
+        (message "✓ gpg-agent killed. It will restart automatically on next use.")
+      (message "⚠ Warning: Failed to kill gpg-agent"))))
+
+;; Keybindings
+(with-eval-after-load 'keybindings
+  (keymap-set cj/custom-keymap "A" #'cj/reset-auth-cache))
+
+(with-eval-after-load 'which-key
+  (which-key-add-key-based-replacements
+    "C-; A" "reset auth cache"))
+
 (provide 'auth-config)
 ;;; auth-config.el ends here.
diff --git a/modules/config-utilities.el b/modules/config-utilities.el
index 32018371..2af3effa 100644
--- a/modules/config-utilities.el
+++ b/modules/config-utilities.el
@@ -33,8 +33,7 @@
     "C-c d i b" "info build"
     "C-c d i p" "info packages"
     "C-c d i f" "info features"
-    "C-c d r" "reload init"
-    "C-c d a" "reset auth cache"))
+    "C-c d r" "reload init"))
 
 ;;; --------------------------------- Profiling ---------------------------------
 
@@ -283,15 +282,6 @@ Recompile natively when supported, otherwise fall back to byte compilation."
   (load-file user-init-file))
 (keymap-set cj/debug-config-keymap "r" 'cj/reload-init-file)
 
-;; ----------------------------- Reset-Auth-Sources ----------------------------
-
-(defun cj/reset-auth-cache ()
-  "Clear Emacs auth-source cache."
-  (interactive)
-  (auth-source-forget-all-cached)
-  (message "Emacs auth-source cache cleared."))
-(keymap-set cj/debug-config-keymap "a" 'cj/reset-auth-cache)
-
 ;; ------------------------ Validate Org Agenda Entries ------------------------
 
 (defun cj/validate-org-agenda-timestamps ()