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). Seit 12.07.2026 markiert das Auftragsbuch solche Karten („kein gemeinsamer Ursprung", Annehmen-Knopf weg) → ablehnen mit Grund, Idee neu in die Queue. Prävention steht in der werkstatt-SOUL (voll klonen + merge-base-Selbstcheck).
• Ehrlich-veraltete Branches (echter Merge-Konflikt): die Annahme versucht seit 12.07.2026 automatisch einen Rebase auf main (isolierter Worktree, Gates laufen danach normal). Nur wenn AUCH der Rebase kollidiert, fällt die Karte durch — dann ablehnen und die Idee frisch einqueuen statt „am PC auflösen".

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

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

Mem0 / Gedächtnis

• mem0_service/requirements.txt ist GEPINNT (wir nutzen Interna: NoThink-Swap, Roh-Chroma) — blindes Upgrade bricht still; vorher/nachher smoke_test.py, Prozedur docs/UPGRADE.md.
• Qwen3.6 ist ein Thinking-Modell: JSON-Extraktion nur mit enable_thinking:false (NoThinkLLM im Sidecar), sonst leere Extraktion.
• Delete-Resurrection: gelöschter Fakt kann beim nächsten learn() wieder auftauchen, solange die Original-Nachricht in history.db liegt (mem0-Design, kein Bug).
• sync_turn läuft im Hintergrund → in kurzlebigen Prozessen (hermes -z) verpufft das Lernen; nur langlebige Sessions lernen zuverlässig.
• Frontend: reagraph auf 4.22.0 gepinnt (4.23+ zieht React 19 → Crash).

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.