Document Hermes update operation and verified stable no-op fix

2026-10-21 16:30:25 +02:00
1 parent 8a4a01c42f
commit 7006991843
@@ -14,7 +14,7 @@ Reproduzierbares Benutzer-Deployment für Hermes Agent auf Arch Linux mit:
 - optionalem CUDA-Build von llama-server, llama-cli und llama-bench
 - Qwen-/RTX-3080-Profilen mit prüfbarem Wechsel und Rückweg

-Stand: 2026-10-12. Für deine **bestehende Workstation** zuerst
+Stand: 2026-10-21. Für deine **bestehende Workstation** zuerst
 [`docs/WORKSTATION.md`](docs/WORKSTATION.md) lesen. Der Schnellstart unten ist für
 eine neue Maschine. Hardware-Leistungsgewinne sind noch nicht auf deiner GPU
 gemessen; die kurze Funktions- und VRAM-Abnahme vom 12.10.2026 ist in
@@ -150,7 +150,7 @@ Update-Lock und löst bei Backend-HTTP-Timeouts keine Inferenz-Neustarts mehr au

 1. exklusives Lock und Prüfung auf lokale Änderungen
 2. `origin/main`-Fetch mit begrenzten Retries und letztem HTTP/1.1-Fallback
-3. schneller Abschluss ohne Backup, wenn kein Update vorliegt
+3. schneller Abschluss ohne Backup, wenn Checkout und gefetchter Branch identisch sind
 4. komprimiertes Backup vor jeder Änderung
 5. Stoppen des Gateways und Aufruf von `hermes update`
 6. einmaliger Retry bei eindeutig transientem Fetch-Fehler
@@ -159,9 +159,17 @@ Update-Lock und löst bei Backend-HTTP-Timeouts keine Inferenz-Neustarts mehr au
 9. separater llama.cpp-Healthcheck ohne unsinnigen Hermes-Rollback
 10. Aufbewahrung der drei neuesten Hermes-Backups

+Den Zielstand wählt `hermes update` anhand des konfigurierten Update-Kanals.
+Bei Stable kann der Checkout bereits aktuell sein, obwohl `origin/main` weiter
+ist. Ein unveränderter Commit bei Updater-Exitcode 0 und gesundem Gateway gilt
+deshalb als Erfolg. Dabei können Backup und Gateway-Neustart trotzdem stattfinden.
+Ein fehlgeschlagener Updater bei unverändertem Commit bleibt ein Fehler.
+
 Ein Fehler von Telegram oder Signal kann den Updateprozess niemals fehlschlagen
 lassen. Detaillierte Zwischenstände landen im Journal; nur zusammengefasste
-Ergebnisse werden versendet.
+Ergebnisse werden versendet. Abschlussmeldungen stehen auch direkt im Journal
+von `hermes-stack-hermes-update.service`. Diagnose, gezielte Installation und
+Prüfung sind in [HERMES_UPDATE.md](docs/HERMES_UPDATE.md) beschrieben.

 ## Bedienung

@@ -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).
@@ -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
@@ -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).