Document Hermes update operation and verified stable no-op fix

docs/HERMES_UPDATE.md

@@ -0,0 +1,69 @@
+# Hermes-Update betreiben und prüfen
+
+## Bereits aktuelle Stable-Version
+
+Der Updater prüft zunächst den konfigurierten Remote-Branch (standardmäßig
+`origin/main`). Den tatsächlichen Zielstand wählt anschließend `hermes update`
+anhand des Hermes-Update-Kanals. Bei Stable kann der installierte Release-Commit
+aktuell sein, obwohl auf `main` neuere Entwicklungscommits liegen.
+
+Bis zur Korrektur vom 21.10.2026 endete dieser Fall trotz `Already up to date!`
+und Updater-Exitcode 0 mit einem fehlgeschlagenen Wartungsdienst. Das Skript
+forderte fälschlich einen Commitwechsel. Jetzt endet ein erfolgreicher Updater
+mit unverändertem Commit nach den Konfigurations- und Gateway-Prüfungen
+erfolgreich. Der Kanal wird durch diese Korrektur nicht geändert.
+
+Ein fehlgeschlagener Updater bei unverändertem Commit liefert weiterhin Exitcode
+1. Ein ungesunder Gateway löst weiterhin den vorhandenen Rollback aus. Der
+separate llama-Endpunkt wird unabhängig geprüft; dessen Ausfall führt nicht zu
+einem Hermes-Rollback.
+
+## Nur den korrigierten Wrapper installieren
+
+Im Repository-Verzeichnis ausführen, wenn gerade kein Update läuft. Vorher
+laufende Hermes-Aufgaben beenden lassen. Diese gezielte Installation ersetzt nur
+den Wrapper; `./install.sh` installiert dagegen alle versionierten Wrapper/Units.
+
+```bash
+make test
+backup_dir="$(mktemp -d "$HOME/.local/state/hermes-update-wrapper.XXXXXXXX")"
+cp -p ~/.local/libexec/hermes-stack-hermes-update "$backup_dir/"
+printf 'Wrapper-Sicherung: %s\n' "$backup_dir"
+install -m 0755 libexec/hermes-stack-hermes-update \
+  ~/.local/libexec/hermes-stack-hermes-update
+cmp libexec/hermes-stack-hermes-update \
+  ~/.local/libexec/hermes-stack-hermes-update
+```
+
+Die Unit bleibt unverändert; dafür ist kein `daemon-reload` erforderlich.
+Die vorherige Wrapper-Version liegt im ausgegebenen bzw. in `$backup_dir`
+gespeicherten Sicherungsverzeichnis. Bei Bedarf dieselbe Datei mit `install
+-m 0755` zurückkopieren, während kein Update läuft.
+
+## Manueller Lauf und Diagnose
+
+Der Lauf kann den Gateway kurz stoppen und neu starten. Er erzeugt nach dem
+Remote-Vergleich gegebenenfalls auch dann ein Backup, wenn Stable bereits aktuell
+ist. Standardmäßig werden die drei neuesten Hermes-Backups behalten.
+
+```bash
+systemctl --user start hermes-stack-hermes-update.service
+systemctl --user show hermes-stack-hermes-update.service \
+  -p ActiveState -p SubState -p Result -p ExecMainStatus
+systemctl --user is-active hermes-gateway.service
+journalctl --user -u hermes-stack-hermes-update.service -n 100 --no-pager
+journalctl --user -t hermes-stack-maintenance -n 100 --no-pager
+```
+
+Erwartet: `Result=success`, `ExecMainStatus=0` und ein aktiver Gateway. Als
+`Type=oneshot` ist der Update-Dienst nach erfolgreichem Abschluss selbst wieder
+`inactive/dead`. Die Meldung `Hermes ist im konfigurierten Update-Kanal bereits
+aktuell` bestätigt den erfolgreichen Lauf ohne Versionswechsel.
+
+Updater-Ausgaben liegen zusätzlich unter
+`~/.local/state/hermes-stack-maintenance/hermes-update-*.log`.
+Wrapper-Abschlussmeldungen stehen im Dienstjournal; die Benachrichtigung schreibt
+zusätzlich unter dem Tag `hermes-stack-maintenance`.
+
+Die Abnahme auf Archwork und ihre Prüfgrenzen stehen in
+[VALIDATION.md](VALIDATION.md).

docs/VALIDATION.md

@@ -1,3 +1,20 @@
+# Validierung vom 2026-10-21
+
+- `make test`: Syntax- und Secret-Musterprüfung sowie **31 Funktionstests
+  bestanden** (26 vorhandene Tests und fünf neue Updater-Regressionstests).
+- Neue isolierte Tests: unveränderter Stable-Commit bei neuerem `main`,
+  fehlgeschlagener Updater ohne Commitwechsel, erfolgreicher Commitwechsel,
+  Commitwechsel mit Updater-Restartwarnung und Gateway-Rollback.
+  Externe Programme werden simuliert; kein echtes Netzwerk oder systemd darin.
+- `git diff --check`: erfolgreich. ShellCheck ist lokal nicht installiert.
+- Korrigierter Wrapper auf Archwork installiert und bytegleich geprüft.
+- Echter Update-Dienstlauf am 21.10.2026, 16:26 MESZ: Stable v0.22.3 blieb auf
+  Commit `5b147ab036d6d19131bff8d20701b5001eab844a`; Abschluss nach rund 47 Sekunden
+  mit `Result=success` und `ExecMainStatus=0`. Gateway danach `active/running`.
+  Die neue Erfolgsmeldung erschien im Journal des Update-Dienstes.
+- Ein echter Versionswechsel und ein echter Rollback wurden bei dieser Abnahme
+  nicht ausgelöst. Ein vollständiger Installer-Lauf wurde nicht durchgeführt.
+
 # Validierung vom 2026-10-12
 
 - `make test`: Shell-Syntaxprüfung, Secret-Mustercheck und **26 isolierte

docs/WORKSTATION.md

@@ -147,3 +147,16 @@ Repo-Dateien wurden danach aufgenommen und getestet, aber nicht erneut über
 `install.sh` auf die Workstation ausgerollt. Der aktuelle Betrieb bleibt bei den
 bereits geprüften Einstellungen. Details zur Übertragung und zu bestehenden
 Units/Drop-ins stehen in [RTX3080.md](RTX3080.md).
+
+## Hermes-Update-Korrektur vom 2026-10-21
+
+Der korrigierte `hermes-stack-hermes-update` ist gezielt auf der Workstation
+installiert und mit der Repository-Datei bytegleich geprüft. Der echte
+Dienstlauf mit bereits aktuellem Stable v0.22.3 endete erfolgreich
+(`Result=success`, `ExecMainStatus=0`); der Gateway war danach `active/running`.
+Abschlussmeldungen erscheinen jetzt direkt im Dienstjournal.
+
+Vorherige Wrapper-Version:
+`~/.local/libexec/hermes-stack-hermes-update.before-noop-fix-20261021`.
+Ein vollständiger Installer-Lauf war für diese Korrektur nicht erforderlich.
+Betrieb und Fehlerdiagnose: [HERMES_UPDATE.md](HERMES_UPDATE.md).