nixos-config/docs/herdr-orchestration.md

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.

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:

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:

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/<rolle>.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/<rolle>.json <startprompt>.
• Fortsetzen innerhalb derselben Rolle/Auftragskette: ausdrücklich erwünscht, aber immer claude --settings agents/claude-settings/<rolle>.json --resume <session> (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/<slug>.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/<slug>.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/<slug>.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/<slug>.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 <pane-id> 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/<slug>.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 <pane_id> --source <id> --agent <label> --state blocked --message "<konkrete Frage>" und wartet, statt den Turn zu beenden.
2. Orchestrator bekommt das über herdr agent wait <target> --status blocked --timeout <ms> mit.
3. Orchestrator schickt die Antwort in dieselbe Pane (herdr pane run <pane_id> "<Antwort>" + herdr pane send-keys <pane_id> Enter) — Session, Kontext und Prompt-Cache bleiben erhalten.
4. Spezialist arbeitet im selben Turn weiter.

Grenze, nicht verhandelbar: ausschließlich für fehlende fachliche Angaben oder Nutzerentscheidungen (Datum, Ziel, Formulierung, Auswahl zwischen Optionen). Ersetzt nicht die Capability-Handoff-Kette aus agents/orga.md und ist kein Weg, eine Berechtigungs- oder Scope-Ausweitung "schnell" über einen relayten Chat-Text bestätigen zu lassen — siehe der Vorfall vom 31.08.2026 in agents/orga.md (Referenzhandoff). Eine automatische technische Durchsetzung dieser Grenze (z. B. Ablehnung von --state blocked-Nachrichten mit erkennbaren Capability-Schlüsselwörtern) ist bewusst noch nicht gebaut — der Pilot läuft zunächst mit ausschließlich promptbasierter Grenze bei einer einzigen Rolle, bevor sich zusätzlicher technischer Aufwand rechtfertigt.

Token-Reduktion

Aus dem Entwurf übernommen, keine Kürzung von Sicherheitsregeln:

• Reviewer-Scope auf den feststehenden Diff begrenzen, kein erneutes Volltext-Repo-Lesen. Ausnahme: Der eigenständige Volltext-Systemaudit ist ausdrücklich auf das vollständige Lesen des aktuellen Repository-Stands ausgelegt.
• Eskalationsmeldungen wörtlich weiterreichen statt sie zusammenzufassen.
• Reasoning-Effort nach Aufgabentyp: eng spezifizierte Korrektur → Standardprofil, offene Fehlersuche → sol/high nur bei tatsächlichem Bedarf (bestehende Regel oben gilt unverändert).
• Panes innerhalb einer zusammenhängenden Auftragskette wiederverwenden statt neu spawnen, wenn derselbe Spezialist ohnehin für einen Folgeauftrag im selben Kontext gebraucht wird.