aidlc-docs/features/gitea-deployment-workflow/audit.md

@@ -1367,3 +1367,14 @@ by Infrastructure Design. U5 carries REF-U3-01's Umami origin gate plus FR-21 an
 **Context**: OPERATIONS — Deployment Setup, host-setup troubleshooting captured in documentation
 
 ---
+## Deployment Setup — Confirmed Root Cause: su - Does Not Set XDG_RUNTIME_DIR
+
+**Timestamp**: 2026-07-29T00:20:00Z
+
+**User Input**: "oh, ik logde elke keer in met `su - gitea-workflow`. Is dat het probleem geweest?"
+
+**AI Response**: "Confirmed: su - (and sudo -i -u, and sudo -u) don't reliably invoke pam_systemd on Debian-based systems, since /etc/pam.d/su typically lacks that module unlike /etc/pam.d/sshd. Real SSH login as the user works correctly; a manual `export XDG_RUNTIME_DIR=/run/user/$(id -u)` also fixes it per-shell. Confirmed this does not affect the real deploy pipeline, which always connects via genuine SSH. Rewrote deployment-instructions.md's troubleshooting note to name su - explicitly as a confirmed-in-practice cause, not just a theoretical one."
+
+**Context**: OPERATIONS — Deployment Setup, host-setup troubleshooting root cause confirmed and documented
+
+---

aidlc-docs/features/gitea-deployment-workflow/operations/deployment/deployment-instructions.md

@@ -72,9 +72,26 @@ manually:
 ```bash
 sudo systemctl start user@$(id -u gitea-workflow).service
 ```
-And run `systemctl --user` commands from a **real login shell** for that account
-(`sudo -i -u gitea-workflow`), not `sudo -u gitea-workflow systemctl --user ...` from your own
-session — the latter often doesn't carry `XDG_RUNTIME_DIR` along, which produces this exact error.
+And run `systemctl --user` commands from a **real login shell** for that account — not
+`sudo -u gitea-workflow systemctl --user ...`, `sudo -i -u gitea-workflow`, **or `su - gitea-workflow`**
+from your own session. All three are common ways to reach this exact error even when the user
+manager is already running and `/run/user/<uid>/bus` already exists: none of them reliably go
+through `pam_systemd` (the PAM module that actually exports `XDG_RUNTIME_DIR`), because
+`/etc/pam.d/su` and most `sudo` PAM configs don't include it, unlike `/etc/pam.d/sshd` or
+`/etc/pam.d/login`. Confirmed in practice: `su - gitea-workflow` reproduces this exactly.
+
+Two fixes, in order of preference:
+- **SSH in directly as `gitea-workflow`** instead of logging in as yourself and switching user —
+  a real SSH login does go through `sshd`'s PAM stack and sets `XDG_RUNTIME_DIR` correctly
+- Or, after `su -`/`sudo -i -u`, just set it by hand once per shell:
+  ```bash
+  export XDG_RUNTIME_DIR=/run/user/$(id -u)
+  ```
+
+**This does not affect the actual deploy workflow** — `deploy-scp.yaml` always connects over a
+genuine SSH session (`sshpass ssh ...`), which sets `XDG_RUNTIME_DIR` correctly on its own. This
+whole gotcha is specific to poking around on the host by hand via `su`/`sudo -i`.
+
 Verify with `loginctl show-user gitea-workflow | grep Linger` (expect `Linger=yes`) and
 `ls /run/user/<uid>` (should exist once the user manager has actually started).