---
name: chatto-plugin-update
description: "Use when a local Chatto plugin checkout maintained with git must catch up to its remote and the changes must go live in the running Hermes gateway."
version: 1.1.0
author: Paul Klumpp
license: MIT
metadata:
  hermes:
    tags: [chatto, plugin, update, git, gateway]
---

# Chatto-Plugin updaten und Changes aktivieren

## When to Use

Ein lokaler Chatto-Plugin-Checkout, der mit **git gepflegt** wird, soll auf den
Stand seines eigenen Remotes gebracht werden, und die Änderungen sollen im
laufenden Hermes Gateway aktiv werden.

Der Remote steht hier bewusst **nicht**: er gehört der Installation, nicht dem
Plugin. `git remote -v` des Checkouts ist die Wahrheit, und für einen
selbst geklonten Checkout ist das ein privater Remote, den kein mitgeliefertes
Dokument kennen kann.

**Nicht anwendbar auf eine per `hermes plugins install` installierte Instanz.**
Deren Checkout gehört Hermes, nicht dem User; dort ist `hermes plugins update
chatto-platform` der Weg (Schritt 2b). Ein `git pull` darin umgeht die
Install-Metadaten, die den eingespielten Stand festhalten.

## Ablauf

1. **Checkout auflösen.** Es gibt zwei dokumentierte Layouts; welches zutrifft,
   lässt sich nicht raten, also prüfen:
   ```bash
   ls -d ~/.hermes/plugins/chatto-platform \
         ~/.hermes/plugins/platforms/hermes-chatto-plugin 2>/dev/null
   ```
   `REPO` auf den existierenden Pfad setzen und **in allen folgenden Schritten
   mit `git -C "$REPO"` arbeiten** — ohne das laufen die Kommandos im cwd der
   Session, im schlimmsten Fall in einem fremden Repository.
2. **Remote-Status PRÜFEN, nie behaupten:**
   ```bash
   git -C "$REPO" fetch --all
   git -C "$REPO" status -sb
   git -C "$REPO" branch -avv
   git -C "$REPO" remote -v        # der Remote, von dem gepullt wird
   ```
   Erst fetchen, dann Sync-Status (ahead/behind) reporten. Aussagen wie
   „synchron" nur NACH einem `fetch` — der lokale `status -sb` ohne fetch zeigt
   ahead/behind nur gegen den zuletzt bekannten Remote-Stand. Aktueller Branch:
   `git -C "$REPO" branch --show-current`. Den alten Stand aus `branch -avv`
   ablesen und für Schritt 3 festhalten.
3. **Zusammenführen.** Bei einem selbst geklonten Checkout: `git -C "$REPO" pull`
   (Fast-forward). Bei Divergenz: mit dem User abklären, NICHT automatisch
   mergen/rebasen.
   Bei einer per `hermes plugins install` installierten Instanz stattdessen:
   ```bash
   hermes plugins update chatto-platform
   ```
4. **Commits zusammenfassen (Nutzersicht):**
   ```bash
   git -C "$REPO" log <alter_stand>..<neuer_stand>          # oneline
   git -C "$REPO" log <alter_stand>..<neuer_stand> --stat   # Datei-Umfang
   ```
   `<alter_stand>`/`<neuer_stand>` sind aus Schritt 2 — den alten Stand dort
   abgelesen, nicht geraten, sonst zeigt das Log einen leeren oder zu großen
   Bereich. Commits haben ausführliche Messages — daraus eine
   nutzerverständliche Zusammenfassung machen: WAS ändert sich für den
   Bot-Nutzer, nicht Implementierungsdetails. Für jede Änderung eine Quelle
   angeben (Commit-Hash).
5. **Gateway-Neustart ANBIETEN (nie selbst ausführen):** Plugin-Code-Änderungen
   werden erst nach einem Neustart des Hermes-Gateways aktiv — die laufende
   Session hält das alte Modul im Speicher.
   - **Einfachster Weg: `/restart` als Chat-Nachricht** (Gateway-Slash-Command,
     „Restart gateway after draining active runs"). Der User tippt es direkt im
     Channel/DM. IMMER zuerst diesen Weg nennen.
   - **Aus der laufenden Agent-Session heraus ist ein Restart UNMÖGLICH:** der
     Lifecycle-Guard blockiert jeden Versuch aus dieser Session, weil der
     Restart die eigene Session killt. Nicht umgehen versuchen; keine
     Restart-Skripte/Aliase bauen, wenn `/restart` genügt.
   - Ein `hermes gateway restart` oder `systemctl restart …` aus einer
     Bediener-Shell **außerhalb** des Gateway-Prozesses funktioniert — aber nur
     dort. Aus einem Tool-Aufruf dieser Session heraus ist es derselbe
     blockierte Fall. Bei benannten Profilen heißt der Unit
     `hermes-gateway-<profil>`, nicht `hermes-gateway.service`.
   - User fragen, ob jetzt neu gestartet werden soll (der laufende Bot ist dann
     kurz offline).
6. **Nach dem Neustart verifizieren:** Plugin-Tools live testen
   (`chatto_list_rooms` via tool_call), im Log prüfen, dass der Adapter sauber
   lädt.

## Fallstricke

- Aussagen über Sync-Status („synchron", „aktuell") NUR NACH `git fetch` treffen —
  ohne fetch ist der lokale Status wertlos.
- **`git -C` in JEDEM Kommando.** `git pull` ohne `-C` trifft den Checkout der
  Session, nicht den Plugin-Checkout.
- Vendored Updates (chattolib) kommen als dist-info-Rename + RECORD-Änderungen
  im Pull — normal, und über den ganz normalen Neustart aus Schritt 5 hinaus
  ohne Handlungsbedarf.
- Der Lifecycle-Guard prüft **den Inhalt** eines Skripts, sobald ein
  Shell-Interpreter es referenziert: `bash -n skript.sh` mit
  `hermes gateway restart` darin wird abgelehnt — auch unter einem anderen
  Dateinamen und auch als `sh -n`. `chmod`, `mv` und `cp` sind nicht betroffen.
  Ein Skript also nicht an den Interpreter geben, um es zu prüfen: Inhalt mit den
  Datei-Tools lesen. Es lohnt auch nicht, es umzubenennen — der Guard liest
  Bytes, nicht Namen.
- Das Ausführen von `/dev/null` (oder `/dev/zero`, `/dev/fd/N`) lässt der Guard
  bewusst fehlschlagen. Das ist keine Störung, sondern das gewollte Verhalten.
  Eine Umleitung nach `> /dev/null` in einer Shell-Datei ist davon nicht
  betroffen — die wird maskiert.