mission-control-v2/docs/wissen/FALLEN.md

# Betriebs-Fallen — hart erarbeitet, nicht nochmal reintreten

_Kuratiert 10.07.2026. Jede Falle hat hier mindestens einmal real Zeit gekostet.
Neue Fallen: hier eintragen, mit Datum und Symptom._

## Git & Deploy

- **deploy.sh resettet sich SELBST mitten im Lauf.** Es macht früh `git reset --hard
  origin/main`; bash liest aber aus dem alten File-Descriptor weiter → neue Install-Schritte
  (z. B. neue `cp`-Zeilen) greifen beim ERSTEN Deploy nach der Änderung NICHT.
  → deploy.sh ein ZWEITES Mal laufen lassen oder Artefakte von Hand nachinstallieren.
  Danach IMMER verifizieren, dass die neuen Dateien/Units wirklich da sind.
- **deploy.sh-enable-Zeilen können User-Entscheide zurückdrehen.** Beispiel mc2-autoupdate:
  „einmalig deaktiviert" wurde von jedem Deploy still re-enabled, bis die Zeile raus war.
  Bei Entscheiden der Form „X bleibt aus" immer deploy.sh gegenprüfen.
- **Paralleler Git-Zugriff auf den Shared-Checkout:** Mehrere Agenten/Sessions arbeiten
  zeitweise im selben `F:\`-Verzeichnis — HEAD kann unter einem wandern, uncommittete Edits
  verschwinden. → Änderungen sofort committen; zum Landen auf main einen ISOLIERTEN Worktree
  nutzen: `git worktree add --detach <tmp> origin/main` → cherry-pick → rebase →
  `git push origin HEAD:main` → Worktree weg.
- **Gitea-Push:** nur via PowerShell/GCM (Bash-Tool scheitert an der Credential-Auth);
  „Failed to authenticate user" heißt oft nur „3 s warten, Retry" — Auth ist flatterhaft.
  Wenn der nicht-interaktive Push hart scheitert: User pusht EINMAL interaktiv, danach geht's.
- **CRLF:** Box-git hat `core.autocrlf false` + `.gitattributes` erzwingt LF für
  `*.sh/*.service/*.timer` — sonst `pipefail\r`-Abbrüche. Windows-Pipe auf die Box:
  CR-Falle (`sed 's/\r$//'`).
- **Stale `index.lock`** im Box-Repo nach Deploy-Abbruch: Alter prüfen, dann löschen.
- **`hermes` ist über SSH nicht im PATH** → immer `bash -lc 'hermes …'`.
- **Werkstatt-Orphan-Branches („refusing to merge unrelated histories"):** macht ein
  Worker `git init`/Shallow statt voll zu klonen, entsteht ein Branch OHNE gemeinsamen
  Vorfahren — Erkennungsmuster auf der Karte: **Diff „0 Dateien" + „hinter main" ≈ ganze
  Historie** (z. B. 386). Merge ist NIE möglich; oft ist der Inhalt obendrein Müll
  (~/.hermes-Dateien statt Repo-Dateien). (Historisch: das Auftragsbuch markierte solche Branches; es ist seit 04.09.2026
  ausgebaut.) Erkennung heute: `git merge-base main <branch>` leer → Branch verwerfen. Prävention steht in der werkstatt-SOUL (voll klonen + merge-base-Selbstcheck).
- **Ehrlich-veraltete Branches (echter Merge-Konflikt):** vor dem Merge `git rebase main`
  auf dem Branch; kollidiert auch das, Branch verwerfen und die Idee frisch aufsetzen.

## Box / systemd / llama-swap

- **User-Units über SSH:** erst `export XDG_RUNTIME_DIR=/run/user/$(id -u)`, sonst sieht
  `systemctl --user` nichts.
- **llama-swap:** Schutz-Key heißt **`persistent:`** — `persist:` wird still ignoriert
  (dieser Tippfehler hat wochenlang den Verdrängungsschutz deaktiviert). `persistent`
  schützt NUR gegen Verdrängung, NICHT gegen ttl-Selbstentladen → **jedes brains-Mitglied
  braucht ttl:0.** Nach jedem Config-Reload (auch scp!) ist das Warm-Set LEER → Mini-Requests
  an hermes/embed(/reranker) schicken.
- **`warmup.sh` liegt als Root-Kopie** unter `/usr/local/bin/llama-swap-warmup.sh` und wird
  vom sudo-freien deploy.sh NICHT aktualisiert → nach Änderung manuell `sudo install`.
- **llama-swap NIE neustarten**, wenn es nicht sein muss (Warm-Set weg = Lucy-Latenz).
- **Nie zwei ~70-GB-Benches direkt nacheinander** (OOM-Kill beim zweiten).
- **Box ist deutschsprachig (de_DE):** jeder CLI-Output-Parser braucht `LC_ALL=C`
  (apt sagt sonst „aktualisierbar von:" statt „upgradable from:").
- **`pkill -f` über SSH matcht die eigene Remote-Shell** → Muster als `'[g]en…'` klammern.
- **Deploy restartet voice-service** → Übernacht-Jobs mit STT-QA-Gate brauchen
  Wiederanlauf-Logik (Backoff-Retry im hear()-Pfad).
- **llama.cpp streicht Flags ohne Vorwarnung:** `--no-mmap` gibt es seit b10936 nicht mehr
  (`error: invalid argument`) → JEDES Modell stirbt 2 s nach dem Start, llama-swap meldet nur
  „upstream command exited prematurely", der Stack-Check nur „rot". Ersatz: `--load-mode none`
  (gleiche Leistung, gemessen 17.09.2026: Coder 32 t/s, Hirn 85 t/s). Vor einem Engine-Sprung
  jede Config-Kommandozeile mit dem neuen `llama-server` parsen lassen (Port 5899, `timeout 6`,
  `${PORT}` ersetzen) — Argumentfehler kommen sofort, vor dem Laden.

## Hermes

- **Toolsets haben ZWEI Ebenen:** aktiv = NICHT in `agent.disabled_toolsets` UND in
  `platform_toolsets.<platform>`. api_server (Voice) hat eine bewusste Diät-Allowlist;
  MCP-Server sind namentlich allowlistbar (Key `mcp_servers`, snake_case).
  `hermes prompt-size` ist Allowlist-BLIND — echte Kontrolle nur per Live-Call.
- **`MINIMUM_CONTEXT_LENGTH = 64000`:** Modelle mit kleinerem Kontext (heavy 32k, vision 32k)
  sind als delegate_task-Ziel tot — der Fehler kann STILL ausfallen. Fremd-Kritik deshalb via
  fremdblick.sh (Ein-Schuss), nie via Delegation.
- **delegate_task läuft top-level IMMER background** → in `hermes -z`/Cron-Ein-Schuss stirbt
  das Kind mit dem Prozess. Nur langlebige Sessions (Chat/Desktop/Telegram) profitieren.
- **Cron-Fallen:** kein TZ-Feld (next_run_at = System-TZ zum Anlege-Zeitpunkt; nach
  TZ-Wechsel `cron edit --schedule "<gleich>"` zum Neuberechnen) · Prompt/Positionsargumente
  MÜSSEN vor die Flags · `--script` allein reicht nicht (braucht Prompt oder Skill) ·
  Cron-Kontext hat `HERMES_CRON_SESSION=1` und `approvals.cron_mode: deny`.
- **Feed-Skripte: Pipe + Heredoc gleichzeitig = Heredoc gewinnt stdin** → JSON via Temp-Datei
  übergeben. Außerdem ehrlichen Blind-Pfad einbauen (API kaputt → „AUSGEFALLEN", nicht „0 Funde").
- **Hooks:** Consent persistiert NUR über CLI-/Gateway-Start mit `HERMES_ACCEPT_HOOKS=1`;
  `hermes hooks test` schreibt die Allowlist NICHT; Skript-Änderung invalidiert Consent (mtime).
- **GLM-Modelle sind Reasoning-Modelle:** content kommt NACH reasoning_content →
  max_tokens großzügig (fremdblick: FREMDBLICK_MAXTOK bis 4500), sonst leeres Urteil.
- **Manager-Konfabulation:** Das Hirn überspringt Delegation gern „aus Bequemlichkeit" mit
  erfundener Begründung („worker.sh existiert nicht"). Gegenmittel: worker.log als harter
  Nachweis + Skill-Regel „du baust NICHT selbst" + Transcript prüfen, nie der Erzählung glauben.
- **Kritiker == Worker = blinder Fleck** („benotet eigene Hausaufgaben") → Zwei-Kritiker-Gate,
  Urteil REPRODUZIERT-ODER-ABGELEHNT.
- **stage-vor-Diff:** untracked Dateien → `git diff origin/main` leer → Kritiker prüfen NICHTS.
  Erst `git add -A`, dann `git diff --cached`, „Diff leer → STOPP".
- **Werkstatt-Gate:** `git -C ~/mission-control-v2 status --porcelain -uno` MUSS leer sein
  (curl /api/health allein ist ein Loch — alter Code läuft im RAM weiter).
- **`hermes update` meldet Exit 1 trotz Erfolg:** nach seinem eigenen Gateway-Neustart erwartet es
  Zeilen vom „Fleet version check"; unter systemd kommen keine → Exit 1 (#93406). Der MC2-Job
  bricht dann die `&&`-Kette ab (kein doctor, UI ohne `/hermes-ui/`-Basis), autoupdate.sh rollt
  zurück und PINNT — obwohl der Gehirn-Check grün war (06. und 17.09.2026). Deshalb
  `--no-gateway-restart`: Neustart und Urteil gehören dem Job. Pins stehen in
  `/srv/models/mc2-pins.json` und werden NUR von Hand gelöst — gepinnt = still eingefroren.


## Lucy / Windows-PC

- **file://-Fallen im Electron-Build:** Asset-Pfade relativ; `import()` verzeiht KEINE
  relativen Prefixe (onnxruntime-WASM brauchte `new URL("vad/", document.baseURI)`) —
  fetch täuscht, import() nicht.
- **Lucy IMMER über `Lucy-Neustart.bat` neu starten** — hartes Kill hinterlässt
  pocket_server-Waisen auf :8130 („Stimme startet nicht"); die BATs killen Waisen mit.
- `LUCY_WORKERS=2` (User-Env) — 4 Worker = ~4×1,9 GB Stimm-Modell-Kopien.
- Gerade `"` in config.ts-Prompt-Strings zerschießen den String → immer „…" nutzen.
- Zustands-Features IMMER mit sichtbarem Zustand + Sofort-Feedback bauen — der User testet
  blind per Produkt-Gefühl.
- **Executor-Task** `HermesPCExecutor` läuft aus dem Repo mit pythonw → nach
  executor.py-Änderung Task neu starten; Logs in `%LOCALAPPDATA%\HermesPCExecutor\`.
- **`Start-Process -ArgumentList` quotet NICHT** (PS 5.1): Elemente werden mit Leerzeichen
  zusammengefügt — ein Pfad wie `F:\Coding Stuff\…` zerbricht, die gespawnte powershell
  stirbt STILL (kein Fenster, kein Log). → Anführungszeichen ins Element einbetten:
  `'-File','"F:\Coding Stuff\…\skript.ps1"'`. Kostete den ersten Lucy-Annahme-Lauf (12.07.).
- **`\"` in f-String-AUSDRÜCKEN ist seit Python 3.12 ein SyntaxError** (Alt-Stil
  `f"{d.get(\"x\")}"` lief nur pre-3.12; Box hat 3.14). In bash-eingebetteten
  `python3 -c '…'`-Snippets braucht es die Escapes eh nicht (single-quoted) — Werte vorab
  in Variablen ziehen statt Quote-Akrobatik. Kostete denselben Lauf (Poll parste nie).
- **pythonw + subprocess ohne `CREATE_NO_WINDOW`** = jedes gespawnte Konsolenprogramm
  bekommt ein SICHTBARES Fenster (Executor-Polling blitzte im 10-s-Takt auf dem Desktop).
- **MSIX-Sandbox-Falle (Claude-Desktop-Tools):** Tools der Claude-App laufen im
  MSIX-Container — Writes nach `AppData\Local\<app>` landen in
  `AppData\Local\Packages\Claude_*\LocalCache\` (Merge-Read täuscht!). Windows-Apps NIE über
  Agent-Tools nach AppData installieren/verwalten; Installer startet der USER per Doppelklick.
  Die Packages-Kopie ist KEINE Dublette, sondern die virtualisierte echte Install.
- **Hermes Desktop:** NIE „Update / Repair install" klicken (pullt main, desynchronisiert
  das Runtime-Repo → Boot-Fehler). Bei „tot": `git status -uno` im Runtime-Repo; Fehler
  stehen in `logs/bootstrap-*.log`, nicht in desktop.log.

## Colab / Training (Mini-Stimme)

- Live-Drive-Sync JE Epoche einbauen (Session-Tod frisst sonst das Training).
- Notebook-Zellen vor Abgabe ast-prüfen; Colab-Patches nie durch Shell-Heredocs.
- **QA-Gate für synthetische Datensätze:** jeden Clip durch STT-Roundtrip — der ungeprüfte
  XTTS-Datensatz war komplett unbrauchbar (sogar whisper-medium verstand ihn falsch).
- Kokoro-Output peakt >1.0 → Peak-Normalisierung 0.95 + Onset-Trim/Fade-In gehören in
  JEDE künftige KokoroTtsEngine.