fix(launcher-standard): move PID/log to XDG dirs (security: symlink-attack hardening) (#175)

## Summary

The launcher-standard specified `/tmp/{app-name}-server.pid` and
`/tmp/{app-name}-server.log` as the required runtime paths. Predictable
names in a world-writable directory are a **symlink-attack target** on
any shared host:

- An attacker can pre-create `/tmp/<app>-server.pid` containing their
  own PID. The launcher's `is_running()` returns true, and
  `stop_server()` will `kill <attacker-pid>` — DoS or signal-handling
  abuse.
- Similar pattern for the log: pre-symlink `/tmp/<app>-server.log` →
  some target the attacker wants clobbered, then the launcher's
  `nohup ... > LOG_FILE` does the write.
- The standard already warns "don't log sensitive information"
  (§Best Practices > Security), but the predictable-path defence is
  belt-and-braces.

## Fix

Route both to XDG dirs with documented fallback ladders:

- **PID** → `${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/<app>-server.pid`.
  `$XDG_RUNTIME_DIR` is mode `0700` and user-scoped per the XDG Base
  Directory spec (Linux). `$TMPDIR` covers macOS / BSDs (typically
  `/var/folders/.../T`, per-user). `/tmp` remains only as a last-resort
  fallback for hosts that set neither (rare).
- **Log** → `${XDG_STATE_HOME:-$HOME/.local/state}/<app>/server.log`.
  Per-user, survives reboot, not world-writable. The `<app>` subdir
  isolates each launcher's logs.

## Changes

Both files in the same commit per the lock-step requirement
(and the gate in #172):

- **`launcher/launcher-standard.a2ml`**
  - `[runtime].pid-file-pattern` / `log-file-pattern` updated with
    fallback ladders + commented rationale
  - `[disinteg].preserve` updated to reference the new log dir
- **`docs/UX-standards/launcher-standard.adoc`**
  - Standard Launcher Template snippet uses XDG paths + `mkdir -p`
    for the state dir
  - §What `--disinteg` removes / does not remove: paths updated
  - Desktop File `Exec=` example log-arg updated
  - Calling Convention daemon-chain example updated
  - Debugging Checklist now uses `$LOG_FILE` / `$PID_FILE` variable
    refs rather than literal paths
  - §Best Practices > Logging: lead bullet rewritten with rationale
  - §Best Practices > Security: new lead bullets explaining the
    attack vector and the XDG choice
  - §Compliance Checklist: "Log to predictable location (`/tmp/...`)"
    replaced with the XDG requirement

Remaining `/tmp/` mentions in the prose are in *forbidden-patterns*
text that explicitly tells readers NOT to use `/tmp` — intentional.

## Compatibility

Bash-expansion syntax (`${VAR:-${VAR2:-/literal}}`) matches the
shell-expansion style already in the a2ml (e.g.
`$HOME/.local/share/applications` in `[integration.linux]`). Any
consumer that already interpolates `$HOME` here will handle
`${...:-...}`
without changes.

Existing launchers that hard-coded `/tmp/<app>-server.pid` continue to
work but become non-compliant; no break for them, just a green-field
contract change for new launchers and a flagged migration for old
ones.

## Coordination

- Independent of #170, #171, #172, #173. No file overlap.
- Lock-step gate (#172) will go green on first push (both files in
  diff).

## Notes

- Spec `[spec].version` intentionally NOT bumped — five PRs (#170,
  #171, #173, this one, plus any future) all touch the contract; the
  merger sequences them.

## Test plan

- [x] a2ml parses (python tomllib): new patterns round-trip cleanly,
      `[disinteg].preserve` reflects the new log path
- [x] No `/tmp/` literals remain in non-forbidden-patterns prose
      (grep verified)
- [ ] Live lock-step gate (#172) goes green on first push

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

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

docs/UX-standards/launcher-standard.adoc

@@ -20,11 +20,16 @@ The reference implementation is provided in link:comprehensive-launcher-template
 ----
 # Standardized structure for all launchers
 APP_NAME="MyApp"              # Application name
-REPO_DIR="/path/to/repo"       # Repository directory  
+REPO_DIR="/path/to/repo"       # Repository directory
 COMMAND="command to run"      # Startup command
 URL="http://localhost:PORT"     # Web URL (if applicable)
-PID_FILE="/tmp/app-server.pid" # Process ID tracking
-LOG_FILE="/tmp/app-server.log" # Log file location
+# PID file in XDG_RUNTIME_DIR (mode 0700, user-scoped) — falls back to
+# $TMPDIR (macOS) then /tmp (last resort). See §Best Practices > Security.
+PID_FILE="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/${APP_NAME}-server.pid"
+# Log file in XDG_STATE_HOME (defaults to $HOME/.local/state per spec).
+LOG_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/${APP_NAME}"
+LOG_FILE="${LOG_DIR}/server.log"
+mkdir -p "$LOG_DIR"
 MODE="${1:---auto}"            # Default mode
 ----
 
@@ -289,13 +294,13 @@ system". The `--disinteg` mode is its exact inverse.
 
 Everything `--integ` created, plus:
 
-* The PID file (`/tmp/<app>-server.pid`)
+* The PID file (`$XDG_RUNTIME_DIR/<app>-server.pid`, or the resolved equivalent — see §Best Practices > Security)
 * Any `.bat` fallback shortcuts written when PowerShell wasn't available
 
 It deliberately **does not** remove:
 
 * `~/.config/<app>/` — user preferences survive reinstall
-* `/tmp/<app>-server.log` — logs stay for post-mortem
+* `$XDG_STATE_HOME/<app>/` (defaults to `$HOME/.local/state/<app>/`) — logs stay for post-mortem
 * The source repository at `REPO_DIR`
 
 The removal instructions for those are printed after `--disinteg` so the user
@@ -324,7 +329,7 @@ feedback.
 [Desktop Entry]
 Type=Application
 Name=Application Name
-Exec=/var/mnt/eclipse/repos/.desktop-tools/keepopen.sh "AppName" "/path/to/repo" "GUI_CMD" "TUI_CMD" "/tmp/app.log"
+Exec=/var/mnt/eclipse/repos/.desktop-tools/keepopen.sh "AppName" "/path/to/repo" "GUI_CMD" "TUI_CMD" "$HOME/.local/state/app/server.log"
 Terminal=true   # keepopen needs a terminal for its loud banners and shell fallback
 Icon=/path/to/icon.png
 Categories=Category;
@@ -398,7 +403,7 @@ a `tail -f LOG` after the launcher so the terminal stays open:
 
 [source,bash]
 ----
-"aerie-launcher.sh --auto && tail -f /tmp/aerie.log"
+"aerie-launcher.sh --auto && tail -f $HOME/.local/state/aerie/server.log"
 ----
 
 === The three stages
@@ -486,10 +491,10 @@ Exec=launcher.sh --auto
 
 === Debugging Checklist
 
-1. Check log file: `tail -f /tmp/app-server.log`
+1. Check log file: `tail -f "$LOG_FILE"` (resolves to `$XDG_STATE_HOME/<app>/server.log`)
 2. Verify process: `ps aux | grep app-name`
 3. Test URL manually: `curl -v http://localhost:PORT`
-4. Check PID file: `cat /tmp/app-server.pid`
+4. Check PID file: `cat "$PID_FILE"` (resolves to `$XDG_RUNTIME_DIR/<app>-server.pid`)
 5. Test browser opening: `xdg-open http://localhost:PORT`
 6. Verify dependencies: `command -v required-command`
 7. Check port availability: `ss -tlnp | grep PORT`
@@ -537,7 +542,7 @@ APP_NAME="AppName"
 [ ] Implement `wait_for_server()` with reasonable timeout
 [ ] Add proper error handling and user feedback
 [ ] Provide clear success/failure messages
-[ ] Log to predictable location (`/tmp/app-name.log`)
+[ ] Log to XDG state dir (`$XDG_STATE_HOME/<app>/server.log`, defaults to `$HOME/.local/state/<app>/server.log`); never use `/tmp/<app>.log`
 [ ] Handle browser launch failures gracefully
 [ ] Provide manual fallback instructions
 [ ] Implement `--start`, `--stop`, `--status` modes
@@ -548,7 +553,8 @@ APP_NAME="AppName"
 == Best Practices
 
 === Logging
-- Log to `/tmp/app-name.log` for easy debugging
+- Log to `$XDG_STATE_HOME/<app>/server.log` (defaults to `$HOME/.local/state/<app>/server.log` per XDG spec). Per-user, survives reboot, not world-writable.
+- Never log to `/tmp/<app>.log`. Predictable names in a world-writable dir are a symlink-attack target on shared hosts — see §Best Practices > Security.
 - Include timestamps for long-running processes
 - Rotate logs if they grow large
 - Provide log location in error messages
@@ -567,7 +573,9 @@ APP_NAME="AppName"
 - Optimize startup sequence
 
 === Security
-- Use predictable but unique PID file names
+- **PID files MUST go in `$XDG_RUNTIME_DIR`** (Linux) / `$TMPDIR` (macOS), not `/tmp`. `$XDG_RUNTIME_DIR` is mode `0700` and user-scoped per the XDG Base Directory spec; `$TMPDIR` on macOS is `/var/folders/.../T` (per-user). `/tmp` is world-writable: an attacker on a shared host can pre-create `/tmp/<app>-server.pid` containing their own PID, after which the launcher's `is_running()` returns true and `stop_server()` will `kill <attacker-pid>` — DoS or signal-handling abuse vector. The fallback ladder `${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}` exists only as a last resort for hosts that set neither (rare).
+- **Log files MUST go in `$XDG_STATE_HOME`** for the same reason — never `/tmp/<app>.log`.
+- Use predictable but unique PID file *names within the chosen dir* (not in `/tmp`).
 - Clean up PID files on exit
 - Don't log sensitive information
 - Validate URLs before opening

launcher/launcher-standard.a2ml

@@ -72,8 +72,18 @@ mode = "--auto"
 [runtime]
 # Required runtime behaviour.
 background = "nohup"
-pid-file-pattern = "/tmp/{app-name}-server.pid"
-log-file-pattern = "/tmp/{app-name}-server.log"
+# PID files live in the user's runtime-state dir — wiped on logout,
+# user-scoped (mode 0700 per XDG spec), no symlink-attack target.
+# Bash-expansion ladder:
+#   1. $XDG_RUNTIME_DIR — Linux per freedesktop XDG Base Directory spec
+#   2. $TMPDIR          — macOS / BSDs (typically /var/folders/.../T, per-user)
+#   3. /tmp             — last resort (predictable, world-writable; flagged
+#                         in §Best Practices > Security)
+pid-file-pattern = "${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/{app-name}-server.pid"
+# Logs go to XDG_STATE_HOME (per spec, defaults to $HOME/.local/state).
+# Per-user, survives reboot, not world-writable. The {app-name} subdir
+# isolates each launcher's logs.
+log-file-pattern = "${XDG_STATE_HOME:-$HOME/.local/state}/{app-name}/server.log"
 wait-for-url-timeout-seconds = 15
 startup-command-search = [
     "{repo-dir}/scripts/run.sh",
@@ -134,7 +144,7 @@ remove = [
 ]
 preserve = [
     "$HOME/.config/{app-name}/",
-    "/tmp/{app-name}-server.log",
+    "${XDG_STATE_HOME:-$HOME/.local/state}/{app-name}/",
     "{repo-dir}",
 ]