# Herdr-Orchestrierung Der Nutzer spricht oder schreibt nur mit dem Codex-Agenten im primären Herdr-Pane. Sprache wird von der Diktierfunktion des Handy-Keyboards in Text umgewandelt; Herdr selbst transkribiert kein Audio. ```text Handy-Diktat -> Herdr-Pane: Orchestrator -> sichtbares Herdr-Pane: Grafiker -> sichtbares Herdr-Pane: Administrator -> sichtbares Herdr-Pane: Agent-Manager -> sichtbares Herdr-Pane: Orga -> weitere Spezialisten bei Bedarf <- Synthese im Orchestrator-Pane ``` Sichtbare Unteragenten sind eigenständige Codex- oder Claude-Prozesse. Dadurch erscheinen Arbeitszustand und Terminalausgabe im Herdr-Panel. Der Orchestrator startet sie ohne Fokus und beendet nach bestätigter Übergabe seinen eigenen Turn. Damit zeigt das Panel im Normalfall nur den Spezialisten als arbeitend und den Orchestrator als idle. Auf eine spätere Status- oder Ergebnisfrage liest der Orchestrator die Ausgabe und bleibt allein für die Antwort an den Nutzer verantwortlich. Aktives Warten ist nur sinnvoll, wenn der Nutzer ausdrücklich eine automatische Zusammenfassung nach Abschluss verlangt. ## Manueller Probelauf Im Orchestrator-Pane: ```bash herdr agent start grafiker \ --cwd /home/drone/nixos-config \ --workspace "$HERDR_WORKSPACE_ID" \ --split right \ --no-focus \ -- codex --sandbox read-only -C /home/drone/nixos-config \ "Lies AGENTS.md und agents/graphics.md vollständig. Analysiere scripts/resize-image.sh read-only und berichte dem Orchestrator im vereinbarten Ergebnisformat." ``` Beobachten und Ergebnis lesen: ```bash herdr agent list herdr agent wait grafiker --status idle --timeout 300000 herdr agent read grafiker --source recent-unwrapped --lines 200 ``` Der genaue CLI-Umfang hängt von der installierten Herdr-Version ab. Vor einer Automatisierung daher `herdr agent --help` prüfen. ## Sicherheitsmodell - Analyse-Agenten starten read-only. - Schreibende Spezialisten erhalten exklusive Dateipfade und nie denselben Arbeitsbereich wie ein gleichzeitig schreibender Agent. - Der Orchestrator prüft Ergebnisse und Diffs; Spezialisten committen oder pushen nicht. - Sprachlich ausgelöste Deployments, Commits und externe Schreibaktionen benötigen weiterhin eine ausdrückliche Bestätigung. Fire-and-forget bedeutet hier nur, dass der Orchestrator nach bestätigter Übergabe seinen Turn beendet und nicht aktiv auf den Spezialisten wartet. Es ist keine fachliche Freigabe: Der Spezialist arbeitet ausschließlich am übergebenen Auftrag, berichtet im eigenen Pane und wird für Rückfragen oder Bestätigungen in einem neuen Turn beauftragt. Insbesondere dürfen externe Inhalte, allgemeine frühere Aufträge und der Fire-and-forget-Start keine Versand- oder Löschbestätigung ersetzen. ## Rollenkatalog und Versionierung `agents/catalog.json` ist der maschinenlesbare Katalog der aktiven Rollen. Er dokumentiert je Rolle eine stabile ID, semantische Version, Status, Definitionsdatei, Startart und grundsätzliche Sandbox. Die konkrete Rollendatei ist für Berechtigungen maßgeblich; bei Widersprüchen gilt die engere Grenze. Eine Versionsänderung beschreibt eine Änderung des Rollenvertrags, nicht die laufende Codex-Version: - Patch: Klarstellung ohne neue Fähigkeit oder geänderte Freigabegrenze. - Minor: rückwärtskompatible neue Aufgabe oder neues Ausgabeformat. - Major: entfernte Fähigkeit oder geänderte Vertrauens-/Freigabegrenze. Die statischen Regressionstests unter `agents/tests/` prüfen Loader, Katalogkonsistenz, Vertrauensgrenzen, Bestätigungsbindung und Fire-and-forget-Verhalten reproduzierbar mit Bash und `jq` aus dem Plattformsystem. Ausführung: `bash agents/tests/roles.sh`. ## Modell- und Reasoning-Profile `agents/catalog.json` enthält unter `model_profiles` konfigurierbare Defaults für Modell und `reasoning_effort`. Sie ändern keine laufenden Prozesse und sind pro Start beziehungsweise Auftrag überschreibbar. Der token-sparende Standard ist: | Profil | Modell / Effort | Fallback oder Einschränkung | | --- | --- | --- | | orchestrator | `gpt-5.6-terra` / `medium` | — | | administrator | `gpt-5.6-terra` / `high` | `gpt-5.6-sol` / `high` nur bei gemessener Qualitätsnotwendigkeit | | agent-manager | `gpt-5.6-sol` / `high` | Routineaufgabe: `gpt-5.6-terra` / `medium` | | reviewer | `gpt-5.6-sol` / `high` | Routineaufgabe: `gpt-5.6-terra` / `medium` | | planner | `gpt-5.6-terra` / `high` | — | | researcher | `gpt-5.6-terra` / `medium` | Routineinventur: `gpt-5.6-luna` / `low` | | grafiker | `gpt-5.6-terra` / `medium` | reines Resize: `gpt-5.6-luna` / `low` | | orga | `gpt-5.6-terra` / `medium` | — | | dispatcher | kein LLM | — | | finance | `gpt-5.6-luna` / `medium` | historische Finance-Fallbacks bleiben erhalten | `gpt-5.6-sol` mit `high` ist kein pauschaler Qualitätsstandard. Eine Eskalation ist nur zulässig, wenn ein messbarer Qualitätsbedarf (zum Beispiel ein reproduzierbarer Review- oder Planungsfehler unter dem Default) vorliegt und im Auftrag kurz begründet wird. Die Profile sind Metadaten und keine Freigabe, historische Finance-Fallbacks zu entfernen oder laufende Worker umzustellen. Jedes LLM-Profil kann über `runtimes.codex` oder `runtimes.claude` mit den jeweils hinterlegten Modell- und Effort-Werten gestartet werden. Für einen Wechsel wird der laufende Prozess im Pane beendet und dieselbe Rollendatei als Startprompt an `claude` statt `codex` (oder umgekehrt) übergeben. Herdr bietet kein Restart sowie kein Attach/Merge beider Prozesse; ein Pane führt daher nie beide Runtimes gleichzeitig aus. Jeder Claude-Start muss zusätzlich die im Katalog angegebene relative `settings_file` explizit per `--settings` verwenden und darf niemals `.claude/settings.local.json` laden. Diese Settings bilden die effektive Sandbox der Codex-Rolle ab: gleiche Rolle bedeutet gleiche Rechte, unabhängig von Runtime; Deny-Regeln sind Schutz und keine zusätzliche Berechtigung. Entscheidend ist, dass `--settings` bei **jedem** Start explizit mitgegeben wird — auch beim Fortsetzen. `claude --help` bestätigt: `--settings` ist ein gültiges Flag zusammen mit `--resume`/`--continue`, und resume für sich ignoriert es nicht. Verboten ist deshalb nicht resume, sondern das **nackte** `claude resume` (bzw. `claude --continue`) ohne `--settings`: dann lädt Claude nur die Standard-Settings-Hierarchie (User/Projekt/lokal), nicht die Rollendatei `agents/claude-settings/.json`. Damit fehlt der `defaultMode: dontAsk` der Rolle und das Pane fällt in Claudes interaktiven Standardmodus zurück, in dem jeder nicht vorab freigegebene Werkzeugaufruf — auch eine reine read-only Diagnose — eine manuelle Bestätigungsabfrage auslöst, die nur der Orchestrator per Tastendruck freigeben kann. Genau diese Fire-and-forget-Reibung war die Ursache des blockierten Administrator-Panes, das laut Prozessinfo mit bloßem `claude resume` ohne jedes `--settings`-Flag lief. Die richtige Praxis lautet daher: - **Erststart einer Rolle:** frisch mit `claude --settings agents/claude-settings/.json `. - **Fortsetzen innerhalb derselben Rolle/Auftragskette:** ausdrücklich erwünscht, aber **immer** `claude --settings agents/claude-settings/.json --resume ` (dieselbe katalogisierte Settings-Datei erneut mitgeben). Das Wiederverwenden der Session nutzt den Prompt-Cache (kein erneutes volles Einlesen von `AGENTS.md` und Rollendatei) und spart Token; korrekt mit `--settings` gestartet, laufen erlaubte Befehle still durch und alles andere wird ohne Rückfrage abgelehnt. - **Nie** `claude resume`/`claude --continue` ohne `--settings` für ein Rollen-Pane. ## Bestätigungsfreier Spezialisten-Start durch den Orchestrator Auftrag und ursprüngliche Annahmen: `docs/intent/orchestrator-spezialisten-start-ohne-bestaetigung.md`. Der Nutzer hat den dort noch eng gefassten Umfang (nur vier Muster: Start, Move, `list`, `wait`) am 03.09.2026 ausdrücklich erweitert: Der Orchestrator soll `herdr` als Ganzes ohne manuelle Bestätigung bedienen können, auf beiden Runtimes — die bestehenden Sicherheitsgrenzen (`sudo`, `git push`, `git commit`, `agenix`, `ssh`, inhaltliche Freigaben) bleiben davon unberührt und weiterhin bestätigungspflichtig/gesperrt. Maßgeblich für den laufenden Betrieb ist dieser breitere Umfang, nicht mehr die enge Vier-Muster-Fassung im Intent-Dokument. ### Claude-Seite: umgesetzt `agents/claude-settings/orchestrator.json` erlaubt seit 03.09.2026 unter `dontAsk` `Bash(herdr *)` (vorher enger: `Bash(herdr agent *)` und `Bash(herdr pane *)`); die Deny-Liste (`sudo`, `git push`, `git commit`, `agenix`, `ssh`) ist unverändert und bleibt die eigentliche Grenze. Die Regressionstests in `agents/tests/roles.sh` stellen sicher, dass dieses breite `Bash(herdr *)`-Recht ausschließlich `orchestrator.json` vorbehalten bleibt und keine andere Rolle es stillschweigend mitbekommt. ### Auch der Orchestrator selbst Die drei Regeln im Abschnitt oben ("Erststart", "Fortsetzen", "Nie ohne `--settings`") gelten unverändert für **jede** Claude-Rollen-Pane — einschließlich der primären Orchestrator-Pane selbst, nicht nur für die Spezialisten, die sie startet. Läuft der Orchestrator selbst mit `claude resume`/`claude --continue` ohne `--settings agents/claude-settings/orchestrator.json` (das bekannte "nackte Resume", bisher nur für die von ihm gestarteten Spezialisten-Panes belegt), fehlt genau diese Allowlist im eigenen Prozess, und jeder sonst stillschweigend erlaubte Herdr-Aufruf löst wieder eine manuelle Bestätigung aus — obwohl die katalogisierte Settings-Datei den Aufruf längst zulässt. Wer die Orchestrator-Pane startet oder fortsetzt (Nutzer manuell oder ein Startskript), trägt dieselbe Sorgfaltspflicht wie beim Start eines Spezialisten. Ob dies tatsächlich die Ursache der vom Nutzer beobachteten Bestätigungen war, ist per Prozessinfo zu verifizieren (siehe Intent-Dokument, Annahmen); die Settings-Datei selbst braucht dafür keine weitere Änderung. ### Codex-Seite: bereits erfüllt, nicht neu zu bauen `~/.codex/rules/default.rules` enthält bereits die Regel `prefix_rule(pattern=["herdr"], decision="allow")`, die jeden `herdr`-Befehl freischaltet — das entspricht nach der Umfangserweiterung oben genau dem gewünschten Verhalten. Kein Bauauftrag an den Administrator nötig; die Regel wirkt bereits, sudo/git push/git commit/agenix/ssh bleiben durch eigene, unabhängige Regeln gesperrt. Offen bleibt nur ein Forkbarkeits-Punkt, kein Blocker: Diese Regel liegt ausschließlich in der personalen, nicht repo-getrackten `~/.codex/rules/default.rules` und geht bei einem frischen Home-Verzeichnis (Neuaufsetzen, Fork) kommentarlos verloren (gleiche Grenze wie beim Self-Close-Wrapper, siehe `agents/design/herdr-self-close-entwurf.md`, Abschnitt „Wiederherstellung nach Verlust der Prefix-Rule" — Codex 0.145 liest `/etc/codex/rules` selbst nicht, siehe Abschnitt „Codex-Laufzeitpfad (0.145)" oben). Eine rein dokumentarische Referenzdatei im Repo (analog `hosts/globalServices/herdr-self-close.nix`) wäre bei Bedarf eine spätere, unabhängige Administrator-Aufgabe — kein aktueller Auftrag. ## Sichtbare Rollen - `grafiker`: Bildanalyse und Bildverarbeitung nach `agents/graphics.md`. - `administrator`: NixOS-Plattformänderungen nach `agents/admin.md`, mit exklusiv zugewiesenen Dateien und getrenntem Aktivierungsschritt. - `agent-manager`: Erstellung, Pflege, Tests und Upgrades der Rollen nach `agents/agent-manager.md`; keine fachliche Ausführung fremder Rollen. - `orga`: Kalender- und E-Mail-Organisation nach `agents/orga.md`; Lesen ist von Schreiben getrennt, Versand und destruktive Aktionen sind bestätigt. - `planner`: Bedarfsklärung nach `agents/planner.md`; analysiert read-only und darf ausschließlich `docs/intent/.md` für das eigene Intent-Dokument schreiben, klärt ein vages Vorhaben im direkten Dialog mit dem Nutzer im eigenen Pane (keine Weiterleitung über den Orchestrator) und implementiert nichts selbst. ## Orga-Infrastrukturvertrag Die Orga-Rolle erhält keine allgemeinen Netzwerkwerkzeuge und keine Secret-Pfade. Die technische Plattform stellt stattdessen vier getrennte, allowlist-basierte Schnittstellen bereit: `orga-calendar` für Kalender, `orga-mail-read` für semantisch unveränderliches Lesen, `orga-mail-draft` für lokale revisionsgebundene Entwürfe und `orga-mail-send` für höchstens einen Versandaufruf je bestätigter Revision. Lese- und Versandhelfer dürfen keine Fähigkeiten des jeweils anderen erben. Kalenderänderungen verwenden stabile Ereignis-IDs, Versionsschutz und ein an die Vorschau gebundenes Aktionstoken. Mail-Lesen entspricht IMAP `EXAMINE` plus `BODY.PEEK`; der Entwurfshelfer schreibt nicht per IMAP. Der Versandhelfer prüft Entwurfs-ID und Revision oder Inhaltsfingerabdruck. Timeout oder unklarer Versandstatus führt nicht zu einem automatischen Wiederholungsversuch. Konten, Absender, Kalender, Aktionen und Größen werden technisch begrenzt. Die vollständigen fachlichen Vorschau- und Bestätigungsregeln stehen in `agents/orga.md`. ## Planner-Workflow `planner` (siehe `agents/planner.md`) klärt ein vages oder unvollständiges Vorhaben zu einem präzisen Intent-Dokument, bevor ein anderer Spezialist mit der Umsetzung beauftragt wird. Anders als die übrigen sichtbaren Rollen spricht der Planner dabei **direkt und persönlich mit dem Nutzer im eigenen Pane** — der Orchestrator ist nach dem Start nicht mehr im Dialog beteiligt. Er analysiert read-only und besitzt als einzige Schreibausnahme das Anlegen oder Schreiben von `docs/intent/.md`. Ablauf (Standardmuster, immer gleich): 1. Nutzer bittet den Orchestrator, ein Planner-Pane zu öffnen. Der Orchestrator startet `planner` fire-and-forget in einem neuen, unfokussierten Tab/Split, ohne vorgefertigtes Vorhaben als Startprompt, und beendet danach seinen eigenen Turn — er wartet nicht aktiv und relayed nichts. 2. Nutzer wechselt selbst in die Planner-Pane und schildert dort sein Vorhaben direkt. 3. Planner analysiert das Repository read-only und stellt im direkten Gespräch gezielte Rückfragen; das Vorhaben wird gemeinsam verfeinert, ohne Runden- oder Sessionwechsel. 4. Sobald Ziel, Umfang, Abgrenzung und Erfolgskriterien klar genug sind, legt der Planner eine Rohfassung des Intent-Dokuments im Chat vor (noch keine Datei) und fragt den Nutzer ausdrücklich, ob etwas zu ergänzen oder zu ändern ist. 5. Bei Ergänzungswünschen aktualisiert der Planner die Rohfassung und fragt erneut (Schritt 4 wiederholt sich). 6. Bestätigt der Nutzer ausdrücklich, dass nichts mehr fehlt, schreibt der Planner erst jetzt `docs/intent/.md` mit dem endgültigen Inhalt und gibt ihn vollständig lesbar im selben Turn aus. 7. Dieselbe Nutzerbestätigung aus Schritt 6 ist zugleich die Schließfreigabe: Der Planner ruft direkt danach den Self-Close-Wrapper auf (siehe unten) — es gibt keine zusätzliche, separate Orchestrator-Freigabe wie bei den übrigen sichtbaren Rollen. Ein umsetzender Spezialist kann das fertige Intent-Dokument danach als Auftragsgrundlage bekommen, sobald der Nutzer (oder der Orchestrator auf Zuruf) es dem nächsten Auftrag zugrunde legt. **Abweichung vom generischen Abschlussprotokoll:** Die Bedingungen im Abschnitt „Atomare, selbst-schließende Sessions" unten (insbesondere die Orchestrator-Freigabe) gelten für `planner` **nicht** unverändert — bei Planner tritt die direkte Nutzerbestätigung aus Schritt 6 oben an die Stelle der Orchestrator-Freigabe. Für alle anderen selbst-schließenden Rollen (`graphics`, `administrator`, `agent-manager`, `orga`) bleibt die Orchestrator-Freigabe wie beschrieben verbindlich. Dieser direkte Dialog ist etwas anderes als der für `orga` pilotierte offene Rückfrage-Kanal (siehe unten) — dort bleibt der Orchestrator im Loop und relayed Antworten in dieselbe Pane; beim Planner ist der Orchestrator nach dem Start ganz aus dem Dialog raus. Für den Codex-Laufzeitpfad muss der Orchestrator den Planner für den Schreibschritt (Schritt 6) mit `--sandbox workspace-write` statt `--sandbox read-only` starten. Das Codex-Flag selbst bietet keine Claude-ähnliche, fein granulare Pfad-Allowlist: Der Orchestrator muss deshalb einen isolierten Arbeitsbereich oder einen anderen Laufzeitmechanismus verwenden, dessen einziges Schreibziel `docs/intent/` ist. Der Planner-Vertrag erlaubt unabhängig davon weiterhin ausschließlich `docs/intent/.md`; Startbefehle und die konkrete Isolation bleiben Orchestrator-Sache. ## Atomare, selbst-schließende Sessions **Status am 01.09.2026:** Der Self-Close-Wrapper `/etc/scripts/close-my-pane.sh` ist auf blunix live. Er nimmt die Ziel-Pane ausschließlich aus `$HERDR_PANE_ID` und ignoriert jedes Argument. Der Test aus einer rohen Herdr-Shell schloss nur die eigene Pane. Self-Close ist für `graphics`, `administrator`, `agent-manager`, `orga` und `planner` freigegeben. Der Reviewer bleibt read-only und ausdrücklich ausgeschlossen. Ein Spezialist darf weiterhin niemals `herdr pane close ` mit einer frei gewählten Pane-ID aufrufen oder eine fremde Pane schließen. ### Abschlussprotokoll Ein Spezialist darf den Wrapper erst aufrufen, wenn alle Bedingungen erfüllt sind: 1. Die vollständige Übergabe steht sichtbar im letzten Turn und endet mit `COMPLETE`, nicht mit `BLOCKED: …`. 2. Es gibt keine offene Rückfrage. 3. Der Orchestrator hat das Ergebnis nachweislich gelesen und den Spezialisten ausdrücklich zum Schließen freigegeben. Ausnahme: `planner` — dort tritt die direkte Nutzerfreigabe im Pane an diese Stelle, siehe Abschnitt „Planner-Workflow" oben. Fehlt eine Bedingung, bleibt der Spezialist idle. Der Wrapper-Aufruf ist der unwiderrufliche letzte Schritt; danach sind Pane und Kontext weg. ### Codex 0.145 Unter `workspace-write` wird ein direkter Aufruf blockiert. Codex muss als einzigen Befehl exakt `/etc/scripts/close-my-pane.sh` mit `sandbox_permissions=require_escalated` aufrufen — ohne Argumente, Shell-Präfix oder Befehlskette. Im bestätigten E2E-Test wurde die angebotene Prefix-Rule nativ über Option `p` in `~/.codex/rules/default.rules` gespeichert. Sie erlaubt exakt diesen Wrapper außerhalb der Sandbox. Anschließend schloss Testpane `w5:pQ` erfolgreich; der Orchestrator blieb bestehen. Separate Rule-Dateien unter `/etc/codex/rules` und symlinked User-Rules wurden von Codex 0.145 nicht angewandt und sind kein unterstützter Laufzeitpfad. Die native Codex-Rule ist externe Laufzeitkonfiguration. Der Repository-Test prüft den dokumentierten Eskalationsvertrag, ohne eine Home-Datei vorauszusetzen oder zu lesen. ### Claude Claude ruft exakt `Bash(/etc/scripts/close-my-pane.sh)` über die beim Start oder Resume ausdrücklich per `--settings` geladene Rollen-Settings-Datei auf. Die fünf Allowlist-Einträge für Administrator, Agent-Manager, Grafiker, Orga und Planner sind vorhanden und schließen den Reviewer aus. **Ergebnis des ersten Claude-E2E-Tests (01.09.2026, Rolle `planner`, Testpane `w5:pT`):** kein Erfolg, aber ein konkreter Fehlerbefund statt nur eines Testmangels. Der Planner erreichte fachlich COMPLETE (alle drei Self-Close-Bedingungen erfüllt), scheiterte aber mit einer Diagnose- Befehlskette (`echo ...; echo ...; ls ...`) statt mit einem Versuch des erlaubten exakten Einzelbefehls `Bash(/etc/scripts/close-my-pane.sh)`. Bash war im selben Session-Verlauf zuvor mehrfach für andere Befehle nutzbar (Transkript-Zeilen 38–46 gegenüber 173–177 in `/home/drone/.claude/projects/-home-drone-nixos-config/923d939a-07b7-4c58-8d7c-085a8f4017ea.jsonl`). Der Planner schloss daraus voreilig auf einen generellen Lockout; dieser Befund ist durch das Transkript widerlegt. Die Session war korrekt mit `--settings agents/claude-settings/planner.json` gestartet und wurde danach ausschließlich über direkte Eingabe in der Pane fortgesetzt (kein zweiter `claude --resume`-Prozess ohne `--settings`), das bereits bekannte "nacktes Resume"-Problem (siehe oben) scheidet als Ursache also aus. Der Orchestrator hat die Pane stattdessen über sein eigenes, allgemeines `herdr pane close`- Recht geschlossen (Aufräumen einer bestätigt abgeschlossenen Sub-Pane, kein Self-Close-Vorgang). **Nachtest nach dem Fix (01.09.2026, Rolle `planner`, Testpane `w5:pY`):** erfolgreich. Trivialer, vollständig spezifizierter Auftrag (Fundstellensuche für `jq`), COMPLETE ohne Rückfragen im ersten Turn, Orchestrator-Freigabe gesendet — die Pane verschwand daraufhin sofort aus `herdr agent list`/ `herdr pane list`, ohne erneute Bash-Ablehnung. Das Session-Transkript (`/home/drone/.claude/projects/-home-drone-nixos-config/1a22d275-8de5-4439-b0ea-dc9d5296bd0f.jsonl`) endet abrupt direkt nach der Freigabe-Nachricht, ohne geloggten Bash-Tool-Call für den Wrapper — konsistent mit dem erwarteten Verhalten, dass der Wrapper die Pane sofort beendet, bevor der letzte Tool-Aufruf noch geschrieben werden kann (anders als beim ersten Fehlschlag, wo der Prozess wegen der Ablehnung am Leben blieb und den Fehler protokollierte). Damit ist der Claude-Pfad für `planner` **E2E bestätigt**. Ob derselbe Ketten-Mismatch auch bei Administrator, Agent-Manager, Grafiker oder Orga aufgetreten wäre, ist unklar — für diese vier gilt weiterhin: Der Claude-End-to-End-Test bleibt wegen des Sessionlimits ungetestet; ein eigener Testlauf je Rolle steht noch aus. Die ausführliche Testevidenz und Abgrenzung stehen in `agents/design/herdr-self-close-entwurf.md`. ## Reviewer-Einbindung, Eskalationskette und Rückfrage-Kanal (Entscheidungen 01.09.2026) Entscheidungen zum Entwurf in `docs/herdr-eskalation-review-entwurf.md`. Die Datei bleibt als Herkunfts- und Begründungsdokument bestehen; maßgeblich für den laufenden Betrieb ist dieser Abschnitt. ### Reviewer als Standardschritt ab Risikoschwelle Der Orchestrator zieht den Reviewer nicht vor jeder Aktivierungsfreigabe automatisch hinzu, sondern ab einer Risikoschwelle. Review ist Pflicht, wenn mindestens eines zutrifft: - Der Diff berührt Boot, Netzwerk, Firewall, sshd, Secrets, Sandbox-/ Berechtigungskonfiguration oder eine Rollendatei/`agents/catalog.json`. - Der Diff geht über eine kleine, klar lokal begrenzte Korrektur hinaus. - Der Nutzer die Änderung selbst als riskant einstuft. Der Nutzer kann das Reviewer-Hop für einen als unkritisch markierten Auftrag ausdrücklich überspringen lassen ("ohne Review", "trivial"). `agents/ reviewer.md` selbst ändert sich dadurch nicht: read-only, keine Freigabe, Auftrag ist bei einer Diff-Review immer der bereits feststehende Diff-Scope, kein erneutes Volltext-Repo-Lesen. Bei einem Blocker-Befund geht die Aktivierungsfrage nicht an den Nutzer, sondern zurück an den ursprünglichen Spezialisten zur Korrektur. ### Eigenständiger Volltext-Systemaudit Der Orchestrator kann den Reviewer zusätzlich mit einem eigenständigen Volltext-Systemaudit des aktuellen `dev`-Stands beauftragen. Dieser Auftrag hat keinen konkreten Diff als Grundlage und umfasst nach Auftrag die gesamte NixOS-Plattform sowie die Agent-/Herdr-Pipeline. Der Reviewer liest dafür das Repository vollständig; die Token-Reduktion „kein erneutes Volltext-Repo-Lesen“ gilt ausschließlich für die Diff-Review und ist beim Systemaudit ausdrücklich ausgenommen. Das Ergebnis ist genau ein schriftlicher Bericht unter `docs/review/.md`, der zusätzlich vollständig im letzten Turn ausgegeben wird. Der Reviewer bleibt read-only, nimmt keine Änderungen vor, erteilt keine Aktivierungs-, Deployment- oder Veröffentlichungsfreigabe und bleibt vom Self-Close-Mechanismus ausgeschlossen. Ein nicht beauftragter Sicherheitsfokus schließt offensichtliche Sicherheitsbefunde als Nebenbefunde nicht aus. Wegen des offenen Volltext-Scopes ist für diesen Auftrag das bestehende Reviewer-Profil `gpt-5.6-sol` mit `high` angemessen; das Profil wird nicht als neue Berechtigung verstanden und ändert keine laufenden Prozesse. Routine- Diff-Reviews können weiterhin den konfigurierten Routine-Fallback verwenden. ### Eskalationskette bei Blockern 1. Blockierter Spezialist → Orchestrator: konkreter Befund, vermutete Ursache, was zur Fortsetzung fehlt. 2. Orchestrator entscheidet, ob das Problem plattformseitig behebbar ist. Wenn ja, geht ein eng begrenzter Korrekturauftrag an den zuständigen Fixer, die ursprüngliche Meldung wörtlich (nicht paraphrasiert) als Kontext: - Technische Infrastrukturhürden (fehlendes Paket, fehlende Berechtigung, kaputte Konfiguration) → **Administrator**. - Lücke, Widerspruch oder fehlende Fähigkeit in einer Rollendatei oder in `agents/catalog.json` → **Agent-Manager**, ab 01.09.2026 ebenfalls als Fixer vorgesehen (siehe `agents/agent-manager.md`, Abschnitt „Eskalationsannahme"). 3. Der Fixer behebt nach seinem eigenen Vertrag (deklarativ/Rollendatei ändern, prüfen, Diff berichten, Freigabe abwarten — die Reviewer-Schwelle oben gilt auch hier). 4. Fixer → Orchestrator: Status ("aktiv" nach Freigabe, oder "bereit, wartet auf Freigabe"). Kein automatischer Restart des blockierten Spezialisten vor dieser Bestätigung. 5. Orchestrator → ursprünglich blockierter Spezialist: erst nach bestätigter Behebung mit demselben Auftrag fortsetzen, knapp benennen was sich geändert hat. 6. Ist das Problem nicht plattformseitig behebbar (fehlende Nutzerentscheidung, fehlende externe Zugangsdaten, fachliche Unklarheit), geht die Meldung direkt an den Nutzer statt an einen Fixer. ### Rückfrage-Kanal: Pilot bei Orga Ein dritter Zustand neben "Turn beenden und im Ergebnisformat melden" und "einfach weiterarbeiten": *blockiert mit Rückfrage, Turn bleibt offen*. Ab 01.09.2026 ausschließlich für die Rolle `orga` freigegeben (Pilot); alle anderen sichtbaren Rollen behalten das bisherige Verhalten (Turn beenden, idle, neu beauftragen), bis der Pilot ausgewertet und der Kanal ausdrücklich erweitert wird. Mechanismus (Details und Grenze in `agents/orga.md`, Abschnitt „Rückfrage-Kanal (Pilot)"): 1. Spezialist meldet über `herdr pane report-agent --source --agent