lib.sh

#!/usr/bin/env bash
# Bahn: bash | Gegenstueck: lib.psm1
# team/lib.sh — gemeinsame Bibliothek der T.E.A.M.-Rollen (siehe CLAUDE.md, Anhang A).
# Wird per `source` eingebunden, nicht direkt ausgeführt.

# --- Projekt-Konfiguration (T.E.A.M.-Starterkit) ------------------------------
# Alle projektspezifischen Werte stehen in team.config.sh. Sie wird ZUERST
# gesourct, damit die ${VAR:-default}-Zuweisungen unten sie stehen lassen.
# Fehlt die Datei, laufen die Rollen mit den Defaults dieser Bibliothek weiter —
# so bricht ein Lauf nie an einer fehlenden Konfigdatei ab (gleiche Logik wie
# der Pflicht-Fallback in team_briefing).
# lib.sh liegt in team/, team.config.sh eine Ebene darüber in der Repo-Wurzel.
if [ -f "$(dirname "${BASH_SOURCE[0]}")/../team.config.sh" ]; then
    # shellcheck source=../team.config.sh disable=SC1091
    source "$(dirname "${BASH_SOURCE[0]}")/../team.config.sh"
else
    echo "[team-lib] WARNUNG: team.config.sh fehlt — Bibliotheks-Defaults aktiv." >&2
fi

# --- Ein Platzhalter ist kein Befehl (BL-149) ---------------------------------
# Jede Weiche unterhalb unterscheidet "konfiguriert" von "nicht konfiguriert"
# ueber leer/nicht-leer. Das ist richtig — nur ist "noch nicht ausgefuellt" im
# Kit jahrelang als TODO-SATZ geschrieben worden, und der ist nicht leer.
#
# Im Feld traf das jede erste Kaskade: Der Satz "TODO: noch keiner — Stufe 1
# der ersten Kaskade" stand als Vorbelegung in team.config.sh, galt damit als
# Befehl, landete im Prompt jeder bauenden Rolle ("Smoke-Test ausfuehren:
# TODO: …"), in der Werkzeug-Allowlist des Red Teams (Bash(TODO …)) und wurde
# von team_quittung_selbstpruefung WOERTLICH ausgefuehrt — Exit 127, Meldung
# "ist ROT". Der vierte Ausgang aus BL-41 konnte in Stufe 1 damit nie
# automatisch quittieren, obwohl genau diese Stufe die Aufgabe hat, den
# Smoke-Test ueberhaupt erst zu bauen.
#
# Die Vorbelegung ist weg (der Installer fuellt team.config.* jetzt LEER). Diese
# Weiche steht trotzdem hier, und zwar aus zwei Gruenden: Ein Mensch traegt in
# eine leere Zeile gern selbst ein "TODO" ein, und ein Platzhalter dieser Sorte
# wird im Kit erfahrungsgemaess an anderer Stelle wieder eingefuehrt. Sie
# normalisiert EINMAL, oben, statt an drei Verbrauchsstellen einzeln.
#
# Bewusst nur der Praefix und bewusst gross geschrieben: "TODO" am Anfang ist
# im ganzen Kit die Marke fuer "noch nicht ausgefuellt". Ein echter Pruefbefehl
# faengt nicht so an; ein Skript namens ./todo.sh bleibt unangetastet.
case "${TEAM_SMOKE_TEST:-}" in
    TODO*) TEAM_SMOKE_TEST="" ;;
esac

# --- Wie lange der Verifikationsbefehl im Vordergrund laufen darf (BL-207) ----
# Die Auflage "im Vordergrund, nie als Hintergrund-Task" (unten) ist richtig,
# war aber NICHT ERFUELLBAR, sobald die Suite laenger lief als die
# Vordergrundgrenze des Agenten-Werkzeugs (120 s Default). Feld B, 2026-08-28:
# Suite 149-220 s, in EINEM Lauf dreimal in den vierten Ausgang gelaufen
# (Ralph einmal, Frank zweimal), zusammen 4,9480 USD = 32 % der Rollenkosten.
# Die Rolle stand vor der Wahl zwischen Regelverletzung und Werkzeug-Timeout
# und waehlte in drei von drei Faellen dieselbe Verletzung.
#
# BL-201 hatte dieselbe Bauform zweimal mit einer SCHAERFEREN Auflage
# beantwortet. Das hier ist der Beleg, dass Schaerfe nicht hilft: Es ist kein
# Disziplinproblem. Eine Auflage, die die Rolle nicht einhalten KANN, erzeugt
# genau das Verhalten, das sie verbieten soll. Deshalb bekommt die Auflage eine
# Zahl, die die Rolle im Werkzeug einstellen kann — und die Zahl steht im
# Prompt, nicht nur in der Konfiguration.
#
# Default 600 s: grosszuegig gegenueber der 120-s-Wand des Werkzeugs und immer
# noch eine Grenze. Wer laenger braucht, traegt es in team.config.sh ein.
TEAM_SMOKE_TEST_TIMEOUT="${TEAM_SMOKE_TEST_TIMEOUT:-600}"

# --- Der Suitenstand ueberlebt die Rolle, die ihn gemessen hat (BL-256) -------
# WARUM ES DIESE DATEI GIBT. Im Feld aktivierte ein KORREKTER Frank-Fix einen
# latenten Defekt in einem aelteren Waechter. Frank trug den Beifang als
# eigenen Fund ein und belegte regelkonform, dass SEIN Fix keinen NEUEN
# Fehlschlag erzeugt (BL-205). Der Fund bekam Status `offen`; die Fixphase
# fragt nach `an Frank uebergeben` und meldete folgerichtig *nichts zu tun*.
# Der Abschlussbericht meldete den Lauf als fertig, waehrend der Baum seit
# einer Stunde rot war.
#
# JEDE ROLLE HAT SICH REGELKONFORM VERHALTEN. Strukturell fehlte ein ORT: Jede
# Rolle misst den Suitenstand einzeln und keine gibt ihn weiter - und was
# nirgends steht, kann keine Zusammenfassung lesen. Die Regel *ein Fix
# scheitert nicht an fremdem Flackern* bleibt unangetastet; was hier entsteht,
# ist ihre GEGENRICHTUNG: Der Lauf darf weiterlaufen, aber er darf sich nicht
# als fertig melden.
#
# WARUM DIE FUND-EBENE NICHT REICHT: Ein rotes Gate kann ohne Fundeintrag
# entstehen, und ein offener Fund heisst umgekehrt nicht, dass die Suite rot
# ist. Der Suitenstand gehoert an den Suitenstand gebunden.
#
# STEHT HIER und nicht bei den Funktionen weiter unten: Der Prompt-Baustein
# gleich darunter NENNT die Datei. Auf der bash-Bahn faellt eine spaetere
# Definition unter `set -u` sofort auf; auf der pwsh-Bahn waere sie still zu
# einem Leerstring geworden - eine Auflage ohne Ziel.
TEAM_GATE_DATEI="${TEAM_GATE_DATEI:-.team-gate-rot}"

# --- Abgeleitete Prompt-Bausteine (Starterkit) --------------------------------
# Smoke-Test-Zeile für die bauenden Rollen. Ist kein Befehl konfiguriert, wird
# der Schritt AUSDRÜCKLICH als offener Punkt benannt, statt still zu
# verschwinden — sonst merkt niemand, dass das Sicherheitsnetz fehlt.
if [ -n "${TEAM_SMOKE_TEST:-}" ]; then
    # Der Nachsatz ist eine Notbremse gegen einen teuren Fehlermodus, nicht
    # Ausschmückung (BL-41, Feld A K27/K28): Eine bauende Rolle
    # startete den Smoke-Test als HINTERGRUND-Task und wartete danach auf eine
    # Benachrichtigung, die in einer headless-Sitzung nie eintrifft. Der Lauf
    # endet mit subtype=success und is_error=false — er SIEHT AUS WIE EIN
    # ERFOLG —, gibt aber kein Promise und committet nicht. Dreimal passiert,
    # zusammen 13,25 USD, jedes Mal für Arbeit, die bereits fertig und grün
    # war. Der Satz steht hier statt in den Rollen-Briefings, weil er hier
    # JEDE bauende Rolle trifft statt nur eine. Die Begründung gehört in den
    # Prompt, damit die Regel nicht als willkürlich gelesen wird.
    SMOKE_ZEILE="Smoke-Test ausführen: ${TEAM_SMOKE_TEST} — muss grün sein.
   Führe ihn im VORDERGRUND aus und warte auf seine Ausgabe. Starte ihn
   NIEMALS als Hintergrund-Task und plane keinen Wakeup darauf: Diese Sitzung
   ist headless, es kommt keine Benachrichtigung, und du wartest bis zum
   Zeitlimit auf ein Ereignis, das nicht eintreten kann.
   Er darf dafür bis zu ${TEAM_SMOKE_TEST_TIMEOUT} Sekunden brauchen: Erhöhe das
   Zeitlimit deines Werkzeugs entsprechend, statt in den Hintergrund
   auszuweichen — viele Werkzeuge erwarten MILLISEKUNDEN, das wären
   ${TEAM_SMOKE_TEST_TIMEOUT}000 (BL-258). Läuft er länger, ist das ein Befund
   für den Menschen — melde ihn, weiche nicht aus.
   War der Baum schon VOR deiner Arbeit rot, hänge eine Zeile
   '<ISO-Zeit> | <deine Rolle> | <Namen der roten Tests>' an
   ${TEAM_GATE_DATEI} an (BL-256). Dein Auftrag scheitert daran NICHT — aber
   ohne diese Zeile meldet sich der Lauf am Ende als fertig, während das Gate
   aus ist. Ist der Baum am Ende grün, lösche die Datei wieder."
    # BL-207: Frank bekommt NUR diesen Nachsatz, nicht SMOKE_ZEILE — und er
    # faehrt den Smoke-Test oefter als Ralph. Im Feld endeten 10 von 28
    # Frank-Laeufen ohne Promise, bei 9 davon stand das Warten auf einen
    # Hintergrundlauf woertlich im Log-Feld `result` (10,7249 USD an EINEM
    # Tag). Bei ihm kostet der vierte Ausgang zusaetzlich einen
    # Fehlversuch (.frank-attempts) und eskaliert ab dem dritten an Axel —
    # das teure Modell wird also fuer einen Formfehler gerufen. Deshalb
    # steht die Auflage hier ausgeschrieben statt nur bei Ralph.
    SMOKE_SUFFIX=" Smoke-Test grün: ${TEAM_SMOKE_TEST}. Führe ihn im VORDERGRUND aus und warte auf seine Ausgabe — er darf bis zu ${TEAM_SMOKE_TEST_TIMEOUT} Sekunden brauchen, erhöhe das Zeitlimit deines Werkzeugs entsprechend (viele Werkzeuge erwarten MILLISEKUNDEN — das wären ${TEAM_SMOKE_TEST_TIMEOUT}000, BL-258). NIEMALS als Hintergrund-Task und kein Wakeup darauf: Diese Sitzung ist headless, es kommt keine Benachrichtigung, und der Lauf endet als Erfolg ohne Quittung (BL-41). War die Suite schon VOR deinem Fix rot, brich nicht ab: Miss beide Staende und belege, dass durch DEINEN Fix kein NEUER Fehlschlag entsteht (BL-205) — und haenge die Zeile '<ISO-Zeit> | frank | <Namen der roten Tests>' an ${TEAM_GATE_DATEI} an, sonst meldet sich der Lauf am Ende als fertig, waehrend das Gate aus ist (BL-256). Ist der Baum am Ende gruen, loesche die Datei wieder."
else
    SMOKE_ZEILE="(Kein Smoke-Test konfiguriert — Schritt entfällt. Das Team arbeitet ohne Sicherheitsnetz; TEAM_SMOKE_TEST in team.config.sh nachtragen.)"
    SMOKE_SUFFIX=""
fi

# --- Bedienung: Hilfe und Zurueckweisung (BL-223) -----------------------------
# Warum das in der Bibliothek steht und nicht siebenmal daneben: Eine
# Konvention, die nur dasteht, wird an der Haelfte der Stellen nicht befolgt —
# und genau so ist BL-223 entstanden. Von vierzehn Einstiegspunkten hatten
# DREI eine Hilfe, und die Rollen-Skripte lasen ihre Argumente ueberhaupt
# nicht: `./ralph.sh --hilfe` zeigte keine Hilfe, wies nichts zurueck und
# startete einen bezahlten Rollenlauf. Das ist BL-222 eine Stufe teurer — dort
# war die Folge eine falsche Statusausgabe, hier ein Modellaufruf, den niemand
# bestellt hat.

# team_hilfe_kopf [datei]: der DATEIKOPF ist der Hilfetext, keine zweite
# Fassung daneben (dieselbe Bauart wie `install.sh --hilfe`, BL-154/BL-156) —
# eine Abschrift laeuft irgendwann auseinander, und dann sagt --hilfe etwas
# anderes als die Datei. Gelesen wird ab Zeile 3 (1 = Shebang, 2 =
# Bahn-Kopfzeile, beides Maschinensache) bis zur ersten Zeile, die kein
# Kommentar mehr ist. Waechst der Kopf, waechst die Hilfe mit.
#
# Default ist der BASENAME: Jeder Entrypoint wechselt vorher in sein eigenes
# Verzeichnis, ein relativer Pfad zeigt danach ins Leere.
team_hilfe_kopf() {
    local datei="${1:-$0}"
    [ -f "$datei" ] || datei="$(basename "$datei")"
    sed -n '3,${
        /^#/!q
        s/^# \{0,1\}//
        p
    }' "$datei"
}

# team_argumente_pruefen "$@": fuer Skripte, die KEINE Argumente kennen.
# --hilfe/--help/-h druckt den Kopf und endet mit 0; jedes andere Argument
# endet mit 2 auf stderr. Der argumentlose Aufruf laeuft unveraendert durch.
#
# Der EXIT-CODE ist die Zusicherung, nicht der Text: Er ist das, was ein
# aufrufendes Skript auswerten kann (dieselbe Trennung wie bei den
# Buchungsverben aus BL-222).
team_argumente_pruefen() {
    case "${1:-}" in
        "") return 0 ;;
        --hilfe|--help|-h) team_hilfe_kopf; exit 0 ;;
        *) echo "$(basename "$0"): unbekanntes Argument '$1' — dieses Skript nimmt keine Argumente. '--hilfe' zeigt den Dateikopf." >&2
           exit 2 ;;
    esac
}

# team_hilfe_wenn_gefragt "$@": fuer Skripte, die ihre uebrigen Argumente
# WEITERREICHEN (team-test.sh und kit-test.sh reichen an pytest durch). Hier
# darf nichts zurueckgewiesen werden — sonst faengt der Riegel genau die
# Argumente, wegen derer es die Durchreiche gibt. Abgefangen wird deshalb nur
# `--hilfe`: die deutsche Schreibweise, die pytest nicht kennt. `--help`/`-h`
# gehen bewusst weiter an pytest, das dafuer eine eigene, bessere Hilfe hat.
team_hilfe_wenn_gefragt() {
    [ "${1:-}" = "--hilfe" ] || return 0
    team_hilfe_kopf
    exit 0
}

# team_allowed_tools <redteam|axel>: Werkzeug-Allowlist für Guard-Linie 2.
# Axel bekommt NUR den Plan-Ordner, das Red Team zusätzlich den Test-Ordner.
team_allowed_tools() {
    local basis="Read Grep Glob Bash(${TEAM_BEUTEBUCH_TOOL}:*) Bash(git log:*) Bash(git diff:*) Bash(git show:*)"
    [ -n "${TEAM_SMOKE_TEST:-}" ] && basis="$basis Bash(${TEAM_SMOKE_TEST})"
    local plan="Edit(${TEAM_PLAN_ORDNER%/}/**) Write(${TEAM_PLAN_ORDNER%/}/**)"
    case "$1" in
        axel) echo "$basis $plan" ;;
        *)    echo "$basis $plan Edit(${TEAM_TEST_ORDNER%/}/**) Write(${TEAM_TEST_ORDNER%/}/**)" ;;
    esac
}

# --- Modelle -----------------------------------------------------------------
# Loop-Rollen (Ralph, Harry, Marv, Frank): günstiges Modell.
# Axel & Der Architekt: starkes Modell, immer API.
TEAM_MODEL_LOOP="${TEAM_MODEL_LOOP:-sonnet}"
TEAM_MODEL_STRONG="${TEAM_MODEL_STRONG:-opus}"

# --- Budget pro Rolle (Zwei-Schwellen-Modell) --------------------------------
# Stakeholder-Entscheid 2026-07-12 (realer Auslöser HM-32): Ein zu tiefes
# Pro-Rolle-Budget ist ökonomisch absurd — der alte 1-USD-Frank-Cap griff ERST
# NACH dem (bereits bezahlten) Claude-Aufruf und warf über den Rollback die
# schon bezahlte Arbeit weg, der nächste Versuch kostete erneut: der Cap
# "sparte" nichts, er vervielfachte die Kosten und blockierte obendrein den Fund.
#
# Neues Modell — EINE zentrale Basiszahl statt drei divergierender Defaults:
#   TEAM_ROLE_BUDGET_USD   (Default 5) — Soft-Cap, gilt für ALLE Rollen.
#   TEAM_ROLE_HARDCAP_USD  (Default 10) — Hard-Cap für die iterierenden
#                          "Sorgenkinder" Frank & Axel (2× Soft).
#
# Zwei Schwellen (siehe team_budget_check):
#   - Frank & Axel: SOFT-Cap = nur deutlicher Hinweis, KEIN Rollback, der Fix
#     bleibt gültig und wird normal geprüft; erst der HARD-Cap (Ausreißer:
#     Endlosschleife/kaputter Prompt) bricht mit Rollback+Cleanup ab.
#   - Ralph/Harry/Marv: sofortiger HART-Cap beim Soft-Wert (kein Soft-Fenster) —
#     Ralph hat nach dem Commit ohnehin Feierabend (kein Rollback, Mensch
#     schaltet weiter), Harry/Marv sind read-only (nichts Bezahltes geht verloren).
# BL-131: Wie der Python-Interpreter heisst, ist eine Eigenschaft der
# MASCHINE, nicht der Bahn. Bis hierher stand `python3` dreizehnmal fest im
# Text — mit der Begruendung, diese Bahn laufe unter Linux. Unter Git-Bash auf
# Windows laeuft sie das nicht, und dort ist `python3` der App-Execution-Alias
# aus dem Microsoft Store: Er startet den Store, schreibt "Python was not
# found" und endet mit 49. Jeder dieser dreizehn Aufrufe war damit tot.
# Die pwsh-Bahn hatte das Problem nie — sie hat dieselben dreizehn Bloecke
# durch native Ausdruecke ersetzt. Der Default hier bleibt `python3`, weil er
# unter POSIX richtig ist; der Installer traegt in team.config.sh ein, was er
# auf der Maschine wirklich gefunden hat.
TEAM_PYTHON="${TEAM_PYTHON:-python3}"
TEAM_ROLE_BUDGET_USD="${TEAM_ROLE_BUDGET_USD:-5}"
TEAM_ROLE_HARDCAP_USD="${TEAM_ROLE_HARDCAP_USD:-10}"

# --- Auth-Modus --------------------------------------------------------------
# team_resolve_auth_mode [rollen-default]
#
# Auflösung (Prio absteigend):
#   1. Env AUTH_MODE            — explizite Übersteuerung pro Aufruf
#   2. ~/.config/claude-team/auth-mode  — maschinenlokaler Default
#   3. Rollen-Default ($1)      — Loop-Rollen übergeben "abo",
#                                 starke Rollen (Axel/Architekt) nichts → "api"
#
# "abo" = Claude-Abo via `claude login`. Der API-Key wird aus der Umgebung
#         entfernt, damit die CLI sicher über das Abo abrechnet.
# "api" = Pay-per-Use. Key-Quelle: Env ANTHROPIC_API_KEY, sonst
#         ~/.config/claude-team/api-key (eine Zeile, chmod 600).
#         Der Key gehört bewusst NICHT in .bashrc — sonst greifen ihn auch
#         interaktive Abo-Sessions auf.
# team_auth_mode_effektiv [rollen-default] — löst NUR den Modus auf
# (Env AUTH_MODE → ~/.config/claude-team/auth-mode → Rollen-Default) und gibt ihn
# auf stdout aus. KEINE Seiteneffekte (kein unset, kein Key-Laden). Erlaubt
# Orchestratoren (vollautomatik.sh/halbautomatik.sh), den effektiven Modus zu
# prüfen, ohne die Prozess-Umgebung anzufassen.
team_auth_mode_effektiv() {
    local rollen_default="${1:-api}"
    local cfg="$HOME/.config/claude-team/auth-mode"
    if [ -n "${AUTH_MODE:-}" ]; then
        printf '%s\n' "$AUTH_MODE"
    elif [ -f "$cfg" ]; then
        head -n1 "$cfg" | tr -d '[:space:]'
    else
        printf '%s\n' "$rollen_default"
    fi
}

# team_warnung_abo_key — warnt EINMAL pro Prozessbaum, wenn im Abo-Modus ein
# ANTHROPIC_API_KEY in der Umgebung liegt (das Abo-first-Design still aushebelt).
# Idempotent: setzt beim ersten Auslösen TEAM_ABO_KEY_WARNUNG_GEZEIGT=1
# (exportiert), sodass alle NACHKOMMEN-Prozesse schweigen. Damit „einmal pro
# Prozessbaum" auch über die SIBLING-Rollenprozesse von vollautomatik.sh/
# halbautomatik.sh hält (HM-32), seeden die Orchestratoren diese Funktion selbst
# EINMAL im eigenen Prozess — analog team_lock/TEAM_LOCK_HELD.
team_warnung_abo_key() {
    if [ -n "${ANTHROPIC_API_KEY:-}" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG:-1}" != "0" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG_GEZEIGT:-0}" != "1" ] \
        && [ "${TEAM_KEY_AUS_FALLBACK:-0}" = "1" ]; then
        # BL-48 (Feld K29/136): Der Key stammt NICHT aus der Umgebung des
        # Menschen, sondern aus einem API-Fallback derselben Prozesskette —
        # team_resolve_auth_mode hat ihn selbst exportiert und dort bleibt er
        # für die Folgestufe stehen. Die .bashrc-Empfehlung unten zeigt dann
        # auf eine Datei, in der nichts steht, und beschreibt eine Ursache, die
        # nicht vorlag; im Feld wurde real per /proc/<pid>/environ nachgesehen.
        # Deshalb: eigener Satz, der sagt was wirklich passiert ist — und
        # KEIN TEAM_ABO_KEY_WARNUNG_GEZEIGT. Das eine Warnfenster pro
        # Prozessbaum gehört dem echten Fall (Key aus .bashrc, ~13,8 USD
        # Leerlauf über API), nicht diesem Fehlalarm.
        echo "Hinweis: ANTHROPIC_API_KEY liegt in der Prozess-Umgebung, gesetzt vom API-Fallback" >&2
        echo "  eines vorigen Aufrufs (nicht aus .bashrc). Er wird für diesen Abo-Aufruf" >&2
        echo "  unmittelbar entfernt — kein Handlungsbedarf (BL-48)." >&2
        return 0
    fi
    if [ -n "${ANTHROPIC_API_KEY:-}" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG:-1}" != "0" ] \
        && [ "${TEAM_ABO_KEY_WARNUNG_GEZEIGT:-0}" != "1" ]; then
        echo "WARNUNG: AUTH_MODE=abo, aber ANTHROPIC_API_KEY liegt in der Prozess-Umgebung —" >&2
        echo "  die Claude-CLI kann dann den (teuren) API-Weg dem Abo vorziehen." >&2
        echo "  Empfohlen: den Key aus .bashrc/der Shell-Env nehmen und stattdessen in" >&2
        echo "  ~/.config/claude-team/api-key (chmod 600) ablegen — siehe CLAUDE.md 'Auth-Modi'." >&2
        echo "  Selbstprüfen: echo \"\${ANTHROPIC_API_KEY:+gesetzt}\" (leer = ok)." >&2
        export TEAM_ABO_KEY_WARNUNG_GEZEIGT=1
    fi
}

# team_api_weg_vorhanden: Gibt es ueberhaupt einen API-Schluessel? (0 = ja)
#
# BL-174: Reine ABFRAGE, ohne etwas zu setzen und ohne zu meckern. Sie
# beantwortet die Frage, die team_claude vor dem Fallback stellen muss —
# `team_resolve_auth_mode` kann das nicht, weil sie im Fehlerfall MELDET und
# der Aufrufer ihren Rueckgabewert bisher als Abbruch gelesen hat.
#
# In einer reinen Abo-Installation ist ein fehlender Schluessel kein Fehler,
# sondern der ERWARTETE Zustand — seit dem Entscheid "keine Rolle ist fest
# api" ist das der empfohlene Normalfall.
# BL-173: WIE die Agenten-CLI heisst, entscheidet die Maschine — nicht diese
# Datei. Dieselbe Lehre wie TEAM_PYTHON (BL-131), und sie wiegt hier schwerer:
# Claude Code wird legitim IDE-GEBUENDELT ausgeliefert (VS Code / VSCodium,
# Binary unter resources/native-binary/claude). Eine Maschine kann eine
# vollstaendig eingerichtete, angemeldete Installation haben, ohne dass
# `claude` in irgendeinem PATH aufloesbar ist — genau die Lage lag im Feld vor:
# ~/.claude/.credentials.json vorhanden, Abo aktiv, Erweiterung lief, und
# `command -v claude` leer.
TEAM_CLAUDE_BIN="${TEAM_CLAUDE_BIN:-claude}"

# team_cli_vorhanden: Ist die Agenten-CLI ueberhaupt aufloesbar? (0 = ja)
#
# BL-173, die WICHTIGERE Haelfte. Ohne diese Pruefung war der Ablauf:
# `claude: command not found` (eine Zeile, scrollt vorbei) -> ein 0-Byte-Log
# -> team_bewerte_ergebnis schreibt einen ERSATZZETTEL fuer einen Aufruf, der
# nie stattgefunden hat -> der Abo-Fehler loest planmaessig den API-Fallback
# aus -> und der bricht mit der Meldung ab, die stehen bleibt und die der
# Mensch liest: "FEHLER: AUTH_MODE=api, aber weder ANTHROPIC_API_KEY gesetzt
# noch …/api-key lesbar."
#
# Diagnostiziert wird ein Auth-Problem; vorliegt ein PATH-Problem. Wer dieser
# Meldung folgt, besorgt einen API-Schluessel — und scheitert ein zweites Mal
# an derselben Stelle, weil auch der API-Weg dasselbe `claude` aufruft.
#
# Eine fehlende Programmdatei ist KEINE Fehlerklasse, die ein Auth-Fallback
# heilen kann. Dieselbe Erwaegung wie bei Exit 42/43: eine eigene Klasse, die
# man BENENNT, statt sie in eine bestehende zu pressen.
team_cli_vorhanden() {
    case "$TEAM_CLAUDE_BIN" in
        */*) [ -x "$TEAM_CLAUDE_BIN" ] && return 0 ;;
        *)   command -v "$TEAM_CLAUDE_BIN" >/dev/null 2>&1 && return 0 ;;
    esac
    return 1
}

team_cli_fehlt_melden() {
    local rolle="${1:-team}"
    echo "[$rolle] FEHLER: Die Agenten-CLI ist nicht auffindbar (gesucht: '$TEAM_CLAUDE_BIN')." >&2
    echo "  Das ist KEIN Auth-Problem — ein API-Schluessel hilft hier nicht." >&2
    echo "  Ist Claude Code als IDE-Erweiterung installiert, liegt die Binaerdatei" >&2
    echo "  meist unter <erweiterung>/resources/native-binary/claude und nicht im PATH." >&2
    echo "  Trag den vollen Pfad als TEAM_CLAUDE_BIN in team.config.sh ein." >&2
}

team_api_weg_vorhanden() {
    [ -n "${ANTHROPIC_API_KEY:-}" ] && return 0
    [ -r "$HOME/.config/claude-team/api-key" ] && return 0
    return 1
}

team_resolve_auth_mode() {
    local rollen_default="${1:-api}"
    local keyfile="$HOME/.config/claude-team/api-key"

    AUTH_MODE="$(team_auth_mode_effektiv "$rollen_default")"

    case "$AUTH_MODE" in
        api)
            if [ -z "${ANTHROPIC_API_KEY:-}" ]; then
                if [ -r "$keyfile" ]; then
                    ANTHROPIC_API_KEY="$(head -n1 "$keyfile" | tr -d '[:space:]')"
                    export ANTHROPIC_API_KEY
                    # BL-48: Merken, dass DIESE Kette den Key gesetzt hat. Ein
                    # späterer Abo-Aufruf im selben Prozessbaum erbt ihn und
                    # bekäme sonst die .bashrc-Warnung für eine Ursache, die
                    # nie vorlag (siehe team_warnung_abo_key).
                    export TEAM_KEY_AUS_FALLBACK=1
                else
                    echo "FEHLER: AUTH_MODE=api, aber weder ANTHROPIC_API_KEY gesetzt noch $keyfile lesbar." >&2
                    return 1
                fi
            fi
            ;;
        abo)
            team_warnung_abo_key
            # Abo-Abrechnung erzwingen: API-Key aus der Umgebung nehmen.
            unset ANTHROPIC_API_KEY
            ;;
        *)
            echo "FEHLER: Unbekannter AUTH_MODE '$AUTH_MODE' (erlaubt: api|abo)." >&2
            return 1
            ;;
    esac
    echo "Auth-Modus: $AUTH_MODE"
}

# --- Zentraler Claude-Aufruf ---------------------------------------------------
# team_claude <rolle> <modell> <outfile> <prompt> [weitere claude-Flags …]
#
# Abo-first mit automatischem API-Fallback (Stakeholder-Entscheid 2026-07-10:
# gilt für ALLE Rollen, auch Axel): Auth wird pro Aufruf frisch aufgelöst;
# scheitert der Abo-Aufruf (Exit ≠ 0 oder is_error), folgt genau EIN API-Retry.
# Nach dem Aufruf stehen TEAM_LAST_COST (USD) und TEAM_LAST_OUT (Log-Datei).
# TEAM_LAST_COST ist die Summe ALLER Versuche dieses Aufrufs (gescheiterter
# Abo-Versuch + API-Fallback + 429-Retries), nicht nur des letzten — sonst waere
# der Pro-Stufe-Budget-Cap durch einen teuren Fehlversuch umgehbar (BL-55).
# TEAM_LAST_OUT bleibt das FINALE Log (Promise-Pruefung, HM-20).
#
# Session-Limit (429, Kaskade 9 / Stufe 30, Strategie A+B; API-Fallback-Reihenfolge
# per Stakeholder-Entscheid 2026-07-11 umgestellt, Commit f787936): Bei JEDEM
# Abo-Fehler — Timeout, normaler Fehler ODER 429/Session-Limit — versucht
# team_claude SOFORT den einmaligen API-Fallback (eigenes, separates Kontingent;
# hilft auch bei einem Abo-429). Erst wenn AUCH das finale (ggf. API-)Ergebnis
# noch ein 429 ist (team_result_is_429), greift die Warte-und-Wiederhol-Logik
# (A). Ist der Reset unbekannt, zu weit in der Zukunft, oder sind die Retries
# erschöpft, gibt team_claude ein eindeutiges Pausen-Signal zurück (B):
# Exit-Code 42, TEAM_LAST_PAUSE=1 und TEAM_LAST_RESET="HH:MM". Ein normaler
# (nicht-429) Fehler, der auch über API scheitert, endet mit Exit 1.
#
#   TEAM_429_MAX_RETRIES  Anzahl Warte-und-Wiederhol-Zyklen (Default 2).
#   TEAM_429_MAX_WARTEN   Harte Obergrenze der Wartezeit in Sekunden
#                         (Default 1800 = 30 Min); 0 schaltet A komplett ab
#                         (nur B, reiner Pausen-Exit).
#   TEAM_429_PUFFER       Sicherheitspuffer nach dem Reset-Zeitpunkt in
#                         Sekunden (Default 30).
#
# TEAM_DRY_RUN=1: kein echter Aufruf — schreibt ein Stub-JSON mit dem Inhalt
# von TEAM_DRY_RESULT (Default leer) für Mechanik-Tests der Pipeline.
TEAM_AUTH_USER="${AUTH_MODE:-}"
TEAM_429_MAX_RETRIES="${TEAM_429_MAX_RETRIES:-2}"
TEAM_429_MAX_WARTEN="${TEAM_429_MAX_WARTEN:-1800}"
TEAM_429_PUFFER="${TEAM_429_PUFFER:-30}"

# team_429_env_int <variablenname> <default>
# Erzwingt, dass die benannte TEAM_429_*-Variable eine reine, nicht-negative
# Ganzzahl ist, BEVOR sie in $(( … ))/[ … ] verwendet wird. Ein aus der
# Umgebung übernommener Wert wie "$(beliebiger Befehl)" würde in einer
# Bash-Arithmetik-Expansion sonst ausgeführt (Command-Injection, HM-17); ein
# nicht-numerischer Wert wie "abc" ließe `test` stillschweigend scheitern und
# den TEAM_429_MAX_WARTEN-Deckel fail-open statt fail-safe wirkungslos werden
# (ebenfalls HM-17). Bei ungültigem Wert: Fehlermeldung + Fallback auf Default.
team_429_env_int() {
    local name="$1" default="$2" wert
    eval "wert=\"\${$name}\""
    case "$wert" in
        ''|*[!0-9]*)
            echo "[team_claude] Ungültiger Wert für ${name}=\"${wert}\" (muss eine nicht-negative Ganzzahl sein) — falle auf Default ${default} zurück." >&2
            eval "$name=\"$default\""
            ;;
    esac
}
team_429_env_int TEAM_429_MAX_RETRIES 2
team_429_env_int TEAM_429_MAX_WARTEN 1800
team_429_env_int TEAM_429_PUFFER 30

# team_429_sleep <sekunden>
# Kapselt `sleep` fürs Warten auf einen Session-Limit-Reset. TEAM_DRY_RUN=1
# oder TEAM_429_SKIP_SLEEP=1 überspringen das echte Warten — so darf ein Test
# niemals real bis zu 30 Minuten blockieren (Verifikationspflicht Stufe 30).
team_429_sleep() {
    local sekunden="$1"
    if [ "${TEAM_DRY_RUN:-0}" = "1" ] || [ "${TEAM_429_SKIP_SLEEP:-0}" = "1" ]; then
        echo "[429] (Test) sleep ${sekunden}s übersprungen." >&2
        return 0
    fi
    sleep "$sekunden"
}

# team_versuch_sichern <rolle> <json-datei> <dauer-sekunden>
# BL-46 (Feld K29/135, 2026-08-10): Ein gescheiterter Abo-Anlauf hinterließ ein
# Log von 0 Byte — nach 47 Minuten Laufzeit. Eine Quittung über null ist von
# „hat nichts gekostet" nicht zu unterscheiden: `kosten.py summe` addierte
# stillschweigend 0.0000, der Pro-Stufe-Deckel bekam auf diese Hälfte keinen
# Griff, und die Stufe erschien in der Kostentabelle als die BILLIGSTE der
# Kaskade, obwohl sie als teuerste angesetzt war. Wer diese Tabelle später als
# Vergleichsband liest, schreibt eine Zahl fort, die eine halbe Stufe beschreibt.
#
# Deshalb: Ist das Versuchslog nicht als JSON lesbar, tritt an seine Stelle ein
# ERSATZZETTEL mit dem, was belegbar ist — Dauer und die ausdrückliche Aussage
# „Kosten unbekannt". NICHT geschätzt: Der Zettel behauptet keine Zahl, er macht
# die Lücke sichtbar. `is_error` bleibt gesetzt, damit der bestehende
# Fehlerpfad (API-Fallback) unverändert greift — vorher war die unlesbare Datei
# über team_result_is_error genau das, und das soll sie bleiben.
# Rückgabe 0, wenn ein Zettel geschrieben wurde (Aufrufer meldet es).
team_versuch_sichern() {
    local rolle="$1" out="$2" dauer="$3"
    "$TEAM_PYTHON" - "$out" "$dauer" <<'PY'
import json, sys
pfad, dauer = sys.argv[1], sys.argv[2]
try:
    with open(pfad) as fh:
        json.load(fh)
    sys.exit(1)          # brauchbares Log — nichts zu tun
except Exception:
    pass
try:
    sekunden = int(float(dauer))
except (TypeError, ValueError):
    sekunden = None
json.dump({"is_error": True, "result": "", "total_cost_usd": None,
           "team_versuch": "verworfen", "team_dauer_s": sekunden},
          open(pfad, "w"))
sys.exit(0)
PY
}

# team_versuch_melden <rolle> <json-datei> <start-epoch>
# Bequemer Aufrufer von team_versuch_sichern: rechnet die Dauer selbst aus und
# sagt laut, dass hier ein bezahlter Anlauf ohne Quittung liegt. Die Meldung ist
# der eigentliche Zweck — im Feld fiel die 0-Byte-Datei nur auf, weil ein Mensch
# den Ordner ansah (BL-46).
team_versuch_melden() {
    local rolle="$1" out="$2" t0="$3" dauer
    dauer=$(( $(date +%s) - t0 ))
    if team_versuch_sichern "$rolle" "$out" "$dauer"; then
        echo "[$rolle] VERWORFENER VERSUCH: '$out' war nach ${dauer}s nicht als JSON lesbar (0 Byte/abgeschnitten)." >&2
        echo "  Ersatzzettel geschrieben — die Dauer ist belegt, die Kosten sind UNBEKANNT und werden" >&2
        echo "  in keiner Summe geschätzt. Der Aufruf gilt weiter als Fehler (API-Fallback greift)." >&2
    fi
}

team_claude() {
    local rolle="$1" modell="$2" out="$3" prompt="$4"
    shift 4
    TEAM_LAST_PAUSE=0
    TEAM_LAST_RESET=""
    TEAM_LAST_KEIN_ZUG=0

    if [ "${TEAM_DRY_RUN:-0}" = "1" ]; then
        "$TEAM_PYTHON" - "$out" "${TEAM_DRY_RESULT:-}" <<'PY'
import json, sys
json.dump({"result": sys.argv[2], "total_cost_usd": 0.01, "is_error": False},
          open(sys.argv[1], "w"))
PY
        TEAM_LAST_COST="0.01"; TEAM_LAST_OUT="$out"
        echo "[$rolle] DRY-RUN — kein Claude-Aufruf."
        return 0
    fi

    # BL-173: VOR dem ersten Aufruf pruefen, ob es die CLI ueberhaupt gibt.
    # Kein API-Fallback, kein Ersatzzettel, kein Fehlversuchs-Zaehler —
    # nichts davon passt auf "das Programm gibt es nicht".
    if ! team_cli_vorhanden; then
        team_cli_fehlt_melden "$rolle"
        return 1
    fi

    AUTH_MODE="$TEAM_AUTH_USER"
    team_resolve_auth_mode abo || return 1

    local fehler=0 cli_exit=0 t0=0
    # Alle Logs DIESES Aufrufs — auch die gescheiterten Vorversuche. TEAM_LAST_COST
    # ist die Summe darueber, nicht nur der letzte Versuch (BL-55).
    local -a versuch_logs=()
    t0="$(date +%s)"
    "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
    team_versuch_melden "$rolle" "$out" "$t0"
    versuch_logs+=("$out")
    if team_bewerte_ergebnis "$rolle" "$out" "$cli_exit"; then fehler=0; else fehler=1; fi

    # Stakeholder-Entscheid (2026-07-11): Bei JEDEM Abo-Fehler — egal ob
    # Timeout, normaler Fehler ODER 429/Session-Limit — SOFORT den API-Fallback
    # versuchen. Der API-Key hat ein eigenes, separates Kontingent (bewiesen
    # 2026-07-11: bei erschöpftem Abo-Kontingent liefert derselbe Prompt mit dem
    # Key erfolgreich `result:ok`), daher hilft der Fallback auch bei einem
    # Abo-429. Erst wenn AUCH der API-Weg scheitert, greift die 429-Warte-/
    # Retry-/Pausen-Logik weiter unten.
    #
    # WICHTIG (Bugfix 2026-07-11): Der Key wird dem `claude`-Aufruf EXPLIZIT als
    # Aufruf-lokales Environment vorangestellt (ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
    # claude …). Ein bloßes `export` über team_resolve_auth_mode reicht NICHT:
    # die CLI bevorzugte im selben Prozess weiterhin die (limitierte) Abo-Session
    # und ignorierte den frisch exportierten Key — der Fallback lief real erneut
    # ins Abo-429. Mit dem vorangestellten Key greift der API-Weg zuverlässig.
    # BL-174: ZUERST fragen, ob es ueberhaupt einen API-Weg gibt.
    #
    # Vorher stand hier `team_resolve_auth_mode || return 1`. In einer reinen
    # Abo-Installation gibt die Funktion fuer AUTH_MODE=api eine 1 zurueck —
    # das `|| return 1` verliess team_claude also SOFORT, und die gesamte
    # 429-Sonderbehandlung darunter wurde nie erreicht. Ein Session-Limit,
    # also genau die Klasse, fuer die BL-20/BL-25 den Exit 42 eingefuehrt
    # haben ("weder ein sauberer Erfolg noch ein echter Fehler, sondern eine
    # eigene, klar benannte Klasse"), kam als Exit 1 heraus: "ECHTER Fehler,
    # Mensch gefragt". Kein Warten bis zum Reset, kein Pausen-Signal, keine
    # der drei dokumentierten Zusicherungen.
    #
    # Der Airbag war damit ausgerechnet im empfohlenen Normalfall ausgebaut,
    # und zwar unsichtbar: Der Fehler zeigt sich erst, wenn das Kontingent
    # voll ist — nach Stunden Laufzeit, an der teuersten Stelle.
    #
    # Ein fehlender Schluessel ist hier kein Fehler, sondern der erwartete
    # Zustand. Er darf den Ablauf nicht abschneiden.
    if [ "$fehler" -eq 1 ] && [ "$AUTH_MODE" = "abo" ] && ! team_api_weg_vorhanden; then
        echo "[$rolle] Abo-Aufruf fehlgeschlagen — kein API-Schluessel hinterlegt, also kein Fallback. Weiter mit der regulaeren Limit-Behandlung." >&2
    elif [ "$fehler" -eq 1 ] && [ "$AUTH_MODE" = "abo" ]; then
        echo "[$rolle] Abo-Aufruf fehlgeschlagen (Timeout/Limit/429?) — einmaliger API-Fallback. Log: $out"
        AUTH_MODE=api
        team_resolve_auth_mode || return 1
        out="${out%.json}-api-fallback.json"
        cli_exit=0
        t0="$(date +%s)"
        ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
        team_versuch_melden "$rolle" "$out" "$t0"
        versuch_logs+=("$out")
        if team_bewerte_ergebnis "$rolle" "$out" "$cli_exit"; then fehler=0; else fehler=1; fi
    fi

    # 429-Sonderbehandlung jetzt auf dem FINALEN (ggf. API-)Ergebnis: nur wenn
    # auch der API-Weg noch einen 429 liefert, wird gewartet/gepausiert.
    if [ "$fehler" -eq 1 ] && team_result_is_429 "$out"; then
        local versuch=1 reset_epoch jetzt warten reset_hhmm pausieren=1
        while [ "$versuch" -le "$TEAM_429_MAX_RETRIES" ]; do
            reset_epoch="$(team_429_reset_epoch "$out")" || reset_epoch=""
            if [ -z "$reset_epoch" ]; then
                echo "[$rolle] 429 erkannt, Reset-Zeit unbekannt — kein Warten, Pausen-Signal." >&2
                break
            fi
            jetzt="$(date +%s)"
            warten=$(( reset_epoch - jetzt + TEAM_429_PUFFER ))
            reset_hhmm="$(date -d "@$reset_epoch" +%H:%M 2>/dev/null || date -r "$reset_epoch" +%H:%M)"
            if [ "$TEAM_429_MAX_WARTEN" -le 0 ] || [ "$warten" -gt "$TEAM_429_MAX_WARTEN" ]; then
                echo "[$rolle] 429 erkannt, Reset erst in ${warten}s (> TEAM_429_MAX_WARTEN=${TEAM_429_MAX_WARTEN}s) — kein Warten, Pausen-Signal." >&2
                break
            fi

            echo "[$rolle] 429/Session-Limit erkannt (Versuch $versuch/$TEAM_429_MAX_RETRIES) — warte ${warten}s bis Reset (${reset_hhmm}) + Puffer." >&2
            team_429_sleep "$warten"

            out="${out%.json}-429-retry${versuch}.json"
            cli_exit=0
            t0="$(date +%s)"
            # Wie beim API-Fallback oben: Key explizit voranstellen, falls der
            # aktuelle AUTH_MODE api ist (sonst greift die CLI ggf. die Abo-Session).
            if [ "$AUTH_MODE" = "api" ]; then
                ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
            else
                "$TEAM_CLAUDE_BIN" -p "$prompt" --model "$modell" --output-format json "$@" > "$out" || cli_exit=1
            fi
            team_versuch_melden "$rolle" "$out" "$t0"
            versuch_logs+=("$out")
            if team_bewerte_ergebnis "$rolle" "$out" "$cli_exit"; then fehler=0; else fehler=1; fi

            if [ "$fehler" -eq 0 ]; then
                echo "[$rolle] Retry nach 429 erfolgreich. Log: $out" >&2
                pausieren=0
                break
            fi
            if ! team_result_is_429 "$out"; then
                echo "[$rolle] Retry lieferte einen normalen (nicht-429) Fehler — weiter im normalen Fehlerpfad." >&2
                pausieren=0
                break
            fi
            versuch=$((versuch + 1))
        done

        if [ "$fehler" -eq 1 ] && [ "$pausieren" -eq 1 ]; then
            TEAM_LAST_PAUSE=1
            TEAM_LAST_RESET="${reset_hhmm:-unbekannt}"
            TEAM_LAST_COST="$(team_summe_cost_usd "${versuch_logs[@]}")"
            TEAM_LAST_OUT="$out"
            echo "[$rolle] 429/Session-Limit — Retries erschöpft oder Reset zu weit entfernt. Pausen-Signal (Reset: $TEAM_LAST_RESET)." >&2
            return 42
        fi
    fi

    TEAM_LAST_COST="$(team_summe_cost_usd "${versuch_logs[@]}")"
    TEAM_LAST_OUT="$out"
    if [ "$fehler" -eq 1 ]; then
        # BL-228: Kam überhaupt ein Modell zum Zug? Der Rückgabewert bleibt 1 —
        # ein Lauf ohne Ergebnis ist ein Lauf ohne Ergebnis, und die
        # Stagnations-Bremse der Vollautomatik muss ihn weiter sehen. Was sich
        # ändert, ist die ZURECHNUNG: Der Aufrufer erfährt über
        # TEAM_LAST_KEIN_ZUG, dass die Rolle nichts dafür kann.
        if team_kein_zug "${versuch_logs[@]}"; then
            TEAM_LAST_KEIN_ZUG=1
            echo "[$rolle] Kein Modell kam zum Zug (0 Turns, 0.0000 USD) — Netz/Proxy vor dem ersten Token. Log: $out" >&2
        else
            echo "[$rolle] Claude-Aufruf endgültig fehlgeschlagen, Log: $out" >&2
        fi
        return 1
    fi
    return 0
}

# team_kein_zug <json-datei>...
# War in diesem Aufruf überhaupt ein Modell am Zug? (BL-228)
#
# Ein Netzfehler VOR dem ersten Token — Proxy nicht gesetzt, VPN-Aussetzer,
# kurzer Abriss — endet mit `num_turns: 0` und `total_cost_usd: 0.0000`: Kein
# Modell hat den Auftrag je gesehen. Für die Rolle ist das derselbe Fall wie
# das Session-Limit (Exit 42, HM-24) — kein INHALTLICHER Fehlversuch, sondern
# gar keiner. Im Feld standen nach zwei solchen Aussetzern zwei Fehlversuche
# gegen einen Fund, den nie ein Modell gelesen hatte; nach dreien hätte der
# Fund auf „an Axel übergeben" gestanden, also auf der teuersten Rolle.
#
# WARUM AN DEN ZAHLEN UND NICHT AM FEHLERTEXT: Der Text der CLI ist ihre Sache
# und ändert sich ("Connection refused", "a firewall or proxy may be blocking
# it"); die beiden Zahlen sind der Vertrag. Es ist zudem die dritte Variante
# desselben Musters (Session-Limit, unquittierte Sitzung, Netzfehler) — ein
# dritter Textzweig wäre genau die Bauform, die BL-214 beim Abtragen eng
# ziehen musste. „0 Turns und 0.0000 USD" trifft alle drei und ist maschinell
# prüfbar.
#
# BEWEISLAST STATT VERMUTUNG: Verlangt werden BEIDE Zahlen, in JEDEM Log dieses
# Aufrufs (Abo-Versuch, API-Fallback, 429-Retries). Fehlt `num_turns` — etwa im
# Ersatzzettel nach einem abgeschnittenen Log (BL-46) — oder fehlt die Datei,
# sind die Kosten UNBEKANNT, und dann bleibt es ein gewöhnlicher Fehlversuch.
# Die Fehlerrichtung ist gewollt: lieber einen Fehlversuch zu viel zählen als
# einen echten verschlucken (BL-160).
team_kein_zug() {
    [ "$#" -gt 0 ] || return 1
    "$TEAM_PYTHON" - "$@" <<'PY'
import json, sys
for pfad in sys.argv[1:]:
    try:
        daten = json.load(open(pfad))
    except Exception:
        sys.exit(1)
    turns, kosten = daten.get("num_turns"), daten.get("total_cost_usd")
    if turns is None or kosten is None:
        sys.exit(1)
    try:
        if float(turns) != 0 or float(kosten) != 0:
            sys.exit(1)
    except (TypeError, ValueError):
        sys.exit(1)
sys.exit(0)
PY
}

# team_promise_in <json-datei> <promise-text>
# Rückgabe 0, wenn das Ergebnis <promise>TEXT</promise> enthält.
team_promise_in() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)
result = data.get("result", "") or ""
sys.exit(0 if f"<promise>{sys.argv[2]}</promise>" in result else 1)
' "$1" "$2"
}

# --- Planmaessig uebersprungene Stufe (BL-255) ---------------------------------
# WARUM ES DIE ZWEITE QUITTUNGSFORM GIBT. Eine Stufe mit im Plan
# ausgeschriebener ABBRUCHBEDINGUNG trat im Feld ein: Die Rolle hat gemessen,
# die Konfiguration unangetastet gelassen, den Befund in den [Unreleased]-Block
# eingetragen, committet — und REGELKONFORM kein Promise gegeben, weil die
# Stufe nicht abgeschlossen, sondern abgebrochen wurde.
#
# Fuer diese Lage gab es keine Vokabel. Es gab Promise oder kein Promise, und
# *kein Promise* ist mit dem teuersten Bericht des Werkzeugs belegt (BL-41,
# Exit 43). Die Selbstpruefung machte es nicht besser, sondern zweideutig:
# Pruefung 1 (*hat die Sitzung Arbeit hinterlassen*) trifft zu, Pruefung 2
# (*gibt es eine beruehrte Testdatei*) in der Regel nicht — also faellt sie
# durch, und der Lauf landet im Exit 43 mit der Begruendung *Produktivcode ohne
# Zusicherung*, die ebenfalls nicht zutrifft. Der Mensch bekommt in BEIDEN
# Zweigen eine falsche Diagnose; eine abgebrochene Stufe, die zufaellig doch
# eine Testdatei angefasst hat, wuerde sogar still als abgeschlossen
# durchgewunken.
#
# WARUM DAS MEHR IST ALS KOSMETIK: Der vierte Ausgang ist die teuerste Meldung
# des Werkzeugs. Wird sie bei einem GEORDNETEN Abschluss gedruckt, stumpft sie
# ab und wird beim naechsten echten Fall weggeklickt.
#
# team_plan_erlaubt_uebersprung <stufe> [plan-datei]
# Rueckgabe 0, wenn der PLAN die zweite Quittungsform fuer genau diese Stufe
# ausschreibt. Das ist der Riegel (a) gegen ein Schlupfloch: Die Vokabel gilt
# nur dort, wo der Architekt die Abbruchbedingung vorher hingeschrieben hat.
# Geprueft wird die Zeichenkette selbst — sie traegt die Stufennummer, kann
# also nicht aus dem Block einer anderen Stufe stammen.
team_plan_erlaubt_uebersprung() {
    local stufe="$1" plan="${2:-$(team_plan_datei)}"
    [ -n "$plan" ] && [ -f "$plan" ] || return 1
    grep -q "STUFE_${stufe}_UEBERSPRUNGEN" "$plan"
}


# team_gate_rot_seit: erste Zeile der Gate-Datei, oder leer. Der Aufrufer
# entscheidet, was er damit tut — gelesen wird an genau einer Stelle.
team_gate_rot_seit() {
    [ -s "$TEAM_GATE_DATEI" ] || return 1
    head -n1 "$TEAM_GATE_DATEI"
}

# --- Vierte Fehlerklasse: Sitzung beendet, Auftrag unquittiert (BL-41) --------
# Neben Erfolg, echtem Fehler und Session-Limit gibt es einen vierten Ausgang:
# Die Rolle beendet ihre Antwort freiwillig, ohne den Auftrag zu quittieren —
# typischerweise, weil sie einen Hintergrund-Task/Monitor/Wakeup gestartet hat
# und auf eine Benachrichtigung wartet, die in einer headless-Sitzung nie
# eintrifft. Das Ergebnis-JSON trägt dann `subtype: "success"`, `is_error:
# false`, `stop_reason: end_turn` — für team_result_is_error ein sauberer
# Erfolg. Nur das fehlende Promise verrät den Fall, und die bisherige Meldung
# ("KEIN Promise — Log prüfen") schickte den Menschen ins Log, das Erfolg meldet,
# und von dort in den PLAN statt in den Fehlermodus.
#
# Vier Vorfälle im Feld (K27/125, K28/131, K28/133, K33/154), zusammen
# 19,47 USD — jedes Mal für Arbeit, die fertig und grün war. Der Neustart wirft
# sie weg; von Hand quittieren rettet sie (im Feld belegt, Commit 458f660).
#
# WARUM NICHT AUF VOKABELN GEPRÜFT WIRD: Die drei Vorfälle formulierten es
# dreimal anders ("background pytest run and monitor", "fallback check /
# wakeup", "set up a monitor to catch its completion") — die vierte Variante
# schreibt jemand morgen. Geprüft wird deshalb die STRUKTUR: kein Promise, aber
# das Log erklärt sich selbst für erfolgreich.
#
# Abgrenzung zur Prävention (SMOKE_ZEILE, oben): Die Auflage steht am
# Prompt-Anfang, der Vorfall passiert nach 65 Turns — Prävention per Prompt
# skaliert gegenläufig zur Stufenlänge. Sie senkt die Wahrscheinlichkeit; DIESE
# Erkennung fängt den Rest.

# team_result_meldet_erfolg <json-datei>
# Rückgabe 0, wenn das Log sich selbst für erfolgreich erklärt (lesbar,
# is_error falsch und subtype "success" — beides muss zutreffen, sonst wäre
# jedes lesbare Log ohne is_error-Feld schon ein "Erfolg").
team_result_meldet_erfolg() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)
if data.get("is_error"):
    sys.exit(1)
sys.exit(0 if data.get("subtype") == "success" else 1)
' "$1"
}

# team_quittung_fehlt_melden <rolle> <json-datei> <was-fehlt> <weiterweg…>
# Druckt die BENANNTE Meldung für den Fall oben. Der Aufrufer ruft sie NUR,
# wenn die Quittung fehlt; ob der Fall vorliegt, entscheidet diese Funktion.
# Rückgabe 0 = benannter Fall erkannt und gemeldet, 1 = gewöhnlicher Fehlschlag
# (der Aufrufer meldet dann wie bisher).
team_quittung_fehlt_melden() {
    local rolle="$1" out="$2" was="$3"; shift 3
    team_result_meldet_erfolg "$out" || return 1
    echo "[$rolle] STUFE FERTIG, QUITTUNG FEHLT (BL-41) — $was" >&2
    echo "  Das Log meldet sich selbst als Erfolg (subtype=success, is_error=false), gibt aber" >&2
    echo "  keine Quittung. Das ist der benannte vierte Ausgang: Die Sitzung hat sich beendet," >&2
    echo "  meist im Warten auf einen Hintergrund-Task/Monitor/Wakeup, den es headless nicht gibt." >&2
    echo "  Die Arbeit ist in diesem Fall meist FERTIG — viermal im Feld, 19,47 USD. Prüfe in" >&2
    echo "  dieser Reihenfolge, BEVOR du neu startest (ein Neulauf wirft die bezahlte Arbeit weg):" >&2
    local schritt
    for schritt in "$@"; do
        echo "    - $schritt" >&2
    done
    # BL-201: Der kuerzeste Weg zur richtigen Diagnose, und er kostet eine
    # Zeile. Im Feld loeste den Fall ALLEIN das Feld `result` im Lauf-Log —
    # dort stand die Ursache woertlich ("waiting for the background test
    # run"). Die Anleitung erwaehnte es an keiner Stelle; ohne den Hinweis
    # sucht der Mensch in der Pruefreihenfolge weiter, deren beide Zweige
    # einen roten Baum voraussetzen, und wirft im zweiten eine fertige,
    # bezahlte Stufe weg.
    echo "  Log: $out" >&2
    echo "  Lies dort ZUERST das Feld \`result\` — die Rolle sagt darin meist selbst," >&2
    echo "  worauf sie gewartet hat. Neunmal im Feld stand dort das Warten auf einen" >&2
    echo "  Hintergrundlauf, und kein einziger erfolgreicher Lauf zeigte dieses Muster." >&2
    return 0
}

# --- Laeuft der Verifikationsbefehl schon? (BL-207) ---------------------------
# team_smoke_parallel_lauf
#   0 = ein ZWEITER Lauf des Verifikationsbefehls ist nachweisbar
#   1 = keiner nachweisbar (das schliesst "auf diesem Wirt nicht feststellbar"
#       ein — im Zweifel bleibt es beim bisherigen Verhalten)
#
# WARUM ES SIE GIBT (Feld B, 2026-08-28): Die Selbstpruefung startete den
# Verifikationsbefehl bedingungslos ein zweites Mal. Im Feld lief der
# Hintergrund-pytest der Rolle noch, als die Selbstpruefung IHREN eigenen
# startete. Zwei gleichzeitige Testlaeufe kollidieren (Datenbankdateien, Ports,
# App-Nutzerverzeichnisse); die Selbstpruefung meldete daraufhin ROT fuer einen
# Baum, der allein gefahren gruen war (199 passed, im Closeout nachgemessen) —
# und schickte den Menschen per BL-61-Text ausdruecklich auf die falsche
# Faehrte "Testaufbau". Wer ihr geglaubt und die Stufe neu gebaut haette,
# haette 2,36 USD bezahlte, fertige Arbeit weggeworfen.
#
# Eine Selbstpruefung, die im Zweifel "rot" BEHAUPTET, ist schlimmer als eine,
# die schweigt. Deshalb: erkannter Parallellauf ⇒ UNBEKANNT, nicht rot.
#
# Die gefundene Zeile wird mitgegeben (TEAM_SMOKE_PARALLEL_ZEILE), damit ein
# Fehlalarm — ein Dauerlaeufer wie pytest-watch, der den Befehl in seiner
# Kommandozeile traegt — in einem Blick als solcher erkennbar ist statt als
# Raetsel.
TEAM_SMOKE_PARALLEL_ZEILE=""
team_smoke_parallel_lauf() {
    local muster="${TEAM_SMOKE_TEST:-}" tabelle treffer
    TEAM_SMOKE_PARALLEL_ZEILE=""
    [ -z "$muster" ] && return 1
    tabelle="$(ps -eo args= 2>/dev/null || ps ax 2>/dev/null || true)"
    [ -z "$tabelle" ] && return 1
    treffer="$(echo "$tabelle" | grep -F -- "$muster" | head -1 || true)"
    [ -z "$treffer" ] && return 1
    TEAM_SMOKE_PARALLEL_ZEILE="$treffer"
    return 0
}

# --- Der vierte Ausgang, selbst geprüft (BL-41 automatisiert) -----------------
# team_quittung_selbstpruefung <rolle> <stufe>
#
# WARUM ES SIE GIBT: Die Erkennung oben ist richtig, aber sie hält den Lauf an
# und legt einem Menschen eine Prüfliste vor, deren drei Schritte IMMER
# dieselben sind. Im Feld (Feld A) ist der Fall in neun Kaskaden
# aufgetreten — K27, K28, K29, K33, K34, K35 (dort dreimal), K36, K37 — und
# JEDES Mal lautete das Ergebnis "Arbeit fertig, nur die Quittung fehlt". Eine
# Prüfliste, die neunmal dasselbe ergibt, ist eine Funktion, die noch niemand
# geschrieben hat. Der Stopp kostet dabei mehr als nur Wartezeit: Er
# unterbricht die Vollautomatik mitten in der Kaskade, und der Mensch muss den
# Lauf von Hand fortsetzen.
#
# WAS SIE NICHT TUT: Sie quittiert NICHT auf Verdacht. Sie prüft genau das,
# was der Mensch geprüft hätte — plus den Punkt, an dem die Prüfliste selbst
# blind war (BL-135: Commit und grüner Baum unterscheiden eine HALB gebaute
# Stufe nicht von einer fertigen; sie fragen nicht nach der Existenz der
# Zusicherungen). Fällt auch nur eine Prüfung durch, gibt sie 1 zurück und der
# Aufrufer meldet unverändert an den Menschen. Der teure Fehler wäre, eine
# unfertige Stufe durchzuwinken — deshalb ist jede Prüfung ein UND, keine
# Mehrheit, und im Zweifel gilt "nicht bestanden".
#
# Rückgabe 0 = alle Prüfungen bestanden, der Aufrufer darf selbst quittieren.
#          1 = mindestens eine Prüfung offen (Grund steht auf stderr).
#
# Abschaltbar über TEAM_QUITTUNG_AUTO=0 (Default an). Aus bleibt die alte
# Prüflisten-Meldung, unverändert.
team_quittung_selbstpruefung() {
    local rolle="$1" stufe="$2"
    local test_ordner="${TEAM_TEST_ORDNER:-tests/}"
    local smoke="${TEAM_SMOKE_TEST:-}"

    if [ "${TEAM_QUITTUNG_AUTO:-1}" != "1" ]; then
        return 1
    fi

    echo "[$rolle] Selbstprüfung des vierten Ausgangs (BL-41) für Stufe $stufe:" >&2

    # (1) Hat die Sitzung überhaupt etwas hinterlassen? Ohne Arbeit gibt es
    #     nichts zu quittieren — dann ist es kein "fertig ohne Quittung",
    #     sondern eine Stufe, die nie angefangen hat.
    local uncommittet betreff hat_arbeit=0
    uncommittet="$(git status --porcelain 2>/dev/null)"
    betreff="$(git log -1 --pretty=%s 2>/dev/null)"
    [ -n "$uncommittet" ] && hat_arbeit=1
    case "$betreff" in *"stufe$stufe"*|*"Stufe $stufe"*) hat_arbeit=1 ;; esac
    if [ "$hat_arbeit" -eq 0 ]; then
        echo "    ✗ Kein Commit für Stufe $stufe und keine uncommitteten Änderungen." >&2
        echo "      Die Sitzung hat nichts hinterlassen — das ist NICHT der vierte Ausgang." >&2
        return 1
    fi
    echo "    ✓ Arbeit vorhanden (uncommittet und/oder Commit der Stufe)." >&2

    # (2) BL-135: Gibt es eine ZUSICHERUNG? Genau der Punkt, an dem die
    #     Prüfliste für den Menschen blind war. Eine Stufe, die Produktivcode
    #     baut und keine einzige Testdatei berührt, ist nach den
    #     Verifikationsregeln dieses Projekts nicht fertig — egal wie grün der
    #     Baum ist, denn der bestehende Bestand deckt das Neue nicht ab.
    local dateien
    if [ -n "$uncommittet" ]; then
        dateien="$(printf '%s\n' "$uncommittet" | sed 's/^...//')"
    else
        dateien="$(git show --name-only --pretty=format: HEAD 2>/dev/null)"
    fi
    if ! printf '%s\n' "$dateien" | grep -q "^\"\?${test_ordner}"; then
        echo "    ✗ Keine Datei unter ${test_ordner} berührt (BL-135)." >&2
        echo "      Die Stufe hat keine nachweisbare Zusicherung — grüner Baum beweist hier" >&2
        echo "      nichts, weil der Bestand das Neue nicht prüft. Das gehört an den Menschen." >&2
        return 1
    fi
    echo "    ✓ Zusicherung vorhanden — mindestens eine Datei unter ${test_ordner} berührt (BL-135)." >&2

    # (3) Ist der Baum grün? Der teuerste, aber unverzichtbare Schritt — er
    #     ist derselbe Befehl, den die Prüfliste dem Menschen nennt.
    if [ -z "$smoke" ]; then
        echo "    ✗ Kein TEAM_SMOKE_TEST konfiguriert — ohne Verifikationsbefehl wird nicht" >&2
        echo "      automatisch quittiert." >&2
        return 1
    fi
    # BL-207: Kein zweiter Lauf neben einen laufenden stellen. Zwei
    #     gleichzeitige Testlaeufe kollidieren, und das Ergebnis waere eine
    #     Eigenschaft der MASCHINE statt eine des Codes.
    if team_smoke_parallel_lauf; then
        echo "    ? Es läuft bereits ein Verifikationslauf — Ergebnis UNBEKANNT, nicht rot (BL-207)." >&2
        echo "      Gefunden: $TEAM_SMOKE_PARALLEL_ZEILE" >&2
        echo "      Ein zweiter Lauf daneben kollidiert (Datenbankdateien, Ports," >&2
        echo "      Nutzerverzeichnisse) und meldete ROT für einen Baum, der allein gefahren" >&2
        echo "      grün ist. Es wird deshalb NICHT automatisch quittiert und NICHTS behauptet." >&2
        echo "      Miss von Hand nach, wenn der laufende Test fertig ist: $smoke" >&2
        return 1
    fi
    echo "    … Smoke-Test läuft ($smoke) …" >&2
    if ! $smoke >/dev/null 2>&1; then
        echo "    ✗ $smoke ist ROT." >&2
        echo "      Das gehört an den Menschen: Erst prüfen, WO — sind ausschließlich die von" >&2
        echo "      DIESER Stufe neu angelegten Testdateien rot, ist der Testaufbau der" >&2
        echo "      wahrscheinlichere Schuldige als der Produktivcode (BL-61)." >&2
        # BL-201: Der Befund kann eine Eigenschaft des LAUFS statt des Codes
        # sein. Ein Hintergrundlauf, den die Rolle angestossen und nie zu Ende
        # gefuehrt hat, hinterlaesst einen halben Zustand (halb geschriebene
        # Datenbankdateien, belegte Ports) — im Feld meldete die
        # Selbstpruefung daraufhin ROT, obwohl der Baum gruen war. Ein Befund,
        # der als sicher gelesen wird, obwohl er es nicht ist, schickt den
        # Menschen in einen Zweig, der eine fertige Stufe wegwirft.
        echo "      ABER: Dieser Befund ist nicht sicher. Wurde der Test vorher als" >&2
        echo "      Hintergrundlauf angestossen und nie zu Ende gefuehrt, misst du seinen" >&2
        echo "      halben Zustand statt deinen Code. Miss im VORDERGRUND nach, bevor du den" >&2
        echo "      Befund verwendest — und lies das Feld \`result\` im Lauf-Log (BL-201)." >&2
        return 1
    fi
    echo "    ✓ $smoke ist grün." >&2

    echo "[$rolle] Alle drei Prüfungen bestanden — Stufe $stufe wird automatisch quittiert." >&2
    return 0
}

# --- Rollen-Briefings (Stufe 90) ----------------------------------------------
# team_briefing <rolle>: gibt den Inhalt von team/prompts/rolle-<rolle>.md aus —
# ersetzt die frühere Prompt-Zeile "Rolle siehe CLAUDE.md — lies sie zuerst.",
# die jeden Rollenaufruf einen zusätzlichen Voll-Read von CLAUDE.md auslösen
# ließ. Fallback (Pflicht, Selbstbezugs-Risiko dieser Kaskade): fehlt die Datei
# oder ist sie leer, liefert der Helfer exakt die alte Zeile zurück — kein
# Abbruch, keine stderr-Fehlermeldung, damit ein Fehler hier nie einen Lauf
# lahmlegt.
team_briefing() {
    local datei="team/prompts/rolle-$1.md"
    if [ -s "$datei" ]; then
        cat "$datei"
    else
        echo "Rolle siehe CLAUDE.md — lies sie zuerst."
    fi
}

# --- Read-Only-Guard (Linie 3 — deterministisch, CHIRURGISCH) -------------------
# team_guard_begin: merkt sich HEAD als Rollback-Punkt UND den Ausgangszustand
#   des Arbeitsbaums (BL-16).
# team_guard_verify <rolle> <whitelist-regex>:
#   Ermittelt geänderte Pfade (committet seit Start + Arbeitsverzeichnis), die
#   NICHT auf die Whitelist passen. Bei Verletzung wird NUR jeder einzelne
#   Verletzer-Pfad zurückgesetzt — niemals blanko `git reset --hard`/`clean -fd`.
#   (Lektion 2026-07-10: ein blindes reset+clean löschte einmal die gesamte
#   uncommittete Team-Infrastruktur. Nie wieder.)
#
# WARUM ES DEN SCHNAPPSCHUSS GIBT (BL-16, Feld K2 2026-08-01)
#   Der Guard hatte KEINEN Ausgangszustand: Er las nur "welche Pfade sind jetzt
#   schmutzig" und schrieb jeden davon der laufenden Rolle zu. Jeder fremde
#   Schreiber — eine parallele Sitzung, eine Handänderung, ein abgebrochenes
#   Werkzeug — wurde damit angelastet UND hart zurückgesetzt. Der Kommentar
#   "schützt parallele/legitime uncommittete Arbeit" galt nur gegenüber dem
#   blanko `reset --hard`, das dieser Guard ablöste; das chirurgische
#   `git checkout -- <pfad>` zerstört fremde Arbeit genauso, nur gezielter.
#   Real eingetreten: Axels korrekte Ermittlung zählte als Fehlschlag (dritte
#   Stagnation → Lauf gestoppt), und die zurückgerollten Pfade waren die
#   unbeteiligte Arbeit einer parallel laufenden Sitzung.
#   Der Schnappschuss hält BLOB-HASHES, nicht nur Pfade: Ein reiner Pfadabgleich
#   würde eine Rolle freisprechen, die eine ohnehin schon schmutzige Datei
#   zusätzlich verändert. Unverändert ⇒ fremd. Verändert ⇒ ihre Sache.
team_guard_schnappschuss() {
    # Je schmutzigem Pfad eine Zeile "<blob-hash> <pfad>". Was sich nicht als
    # Datei lesen lässt (Löschung, Umbenennung, untracked Verzeichnis) bekommt
    # "-" und gilt nur dann als fremd, wenn es das auch bleibt.
    local pfad
    git status --porcelain 2>/dev/null | cut -c4- | while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        if [ -f "$pfad" ]; then
            printf '%s %s\n' "$(git hash-object -- "$pfad" 2>/dev/null || echo -)" "$pfad"
        else
            printf '%s %s\n' "-" "$pfad"
        fi
    done
}

team_guard_begin() {
    TEAM_GUARD_HASH="$(git rev-parse HEAD)"
    TEAM_GUARD_VORHER="$(team_guard_schnappschuss)"
    if [ -n "$TEAM_GUARD_VORHER" ]; then
        # Laut warnen, statt still weiterzulaufen: Der Lauf soll gar nicht erst
        # blind starten, und der Mensch am Terminal soll wissen, dass hier zwei
        # Schreiber unterwegs sein könnten.
        echo "[guard] WARNUNG: Der Arbeitsbaum ist beim Rollenstart NICHT sauber:" >&2
        printf '%s\n' "$TEAM_GUARD_VORHER" | sed 's/^[^ ]* /  /' >&2
        echo "[guard] Diese Pfade werden der Rolle nicht angelastet, solange sie unverändert bleiben." >&2
        echo "[guard] Zwei schreibende Instanzen auf einem Arbeitsbaum sind trotzdem unzulässig — bitte committen." >&2
    fi
    # BL-263: Git sieht die Rohmaterial-Zone nicht, also braucht sie ihren
    # eigenen Startstand. Hier statt in jedem Aufrufer: Wer den Guard beginnt,
    # hat damit auch die Zone erfasst.
    team_raw_begin
}

# Pfade aus dem Schnappschuss, die sich seit dem Rollenstart NICHT verändert
# haben. Sie gehören nicht dieser Rolle.
team_guard_fremdpfade() {
    local eintrag hash pfad jetzt
    [ -z "${TEAM_GUARD_VORHER:-}" ] && return 0
    printf '%s\n' "$TEAM_GUARD_VORHER" | while IFS= read -r eintrag; do
        [ -z "$eintrag" ] && continue
        hash="${eintrag%% *}"
        pfad="${eintrag#* }"
        if [ -f "$pfad" ]; then
            jetzt="$(git hash-object -- "$pfad" 2>/dev/null || echo -)"
        else
            jetzt="-"
        fi
        if [ "$jetzt" = "$hash" ]; then
            printf '%s\n' "$pfad"
        fi
    done
    return 0
}

# Laufzeitartefakte, die die SHELL um den Rollenaufruf herum schreibt — nicht
# die Rolle. Sie stehen im gitignore-Fragment; fehlt es (Einzug in eine
# gewachsene Codebasis, in der der Anwender das Fragment abgelehnt hat),
# tauchen sie in `git status --porcelain` auf und sähen wie ein Übergriff aus.
#
# BL-24 macht diese Liste zur Pflicht statt zur Kosmetik: Seit der Rollback
# Verzeichnisse wirklich entfernen kann, würde er hier die Kostenlogs DES
# LAUFENDEN AUFRUFS löschen — ein selbstverschuldeter BL-4 (verlorene
# Kostenhistorie), ausgelöst ausgerechnet vom Wächter. Vorher scheiterte das
# `rm -f` an ihnen still; dass das gut ging, war Zufall, kein Entwurf.
TEAM_GUARD_LAUFZEIT='^(\.team-logs/|\.ralph-logs/|\.team-loop\.lock$|\.ralph-state$|\.harry-state$|\.marv-state$|\.frank-attempts$|\.team-focus-[a-z]+$)'

# Werkzeug-Ordner des Stakeholders, die das T.E.A.M. KOMPLETT ignoriert
# (BL-263): weder angelastet noch zurueckgesetzt, weder gelesen noch
# ueberwacht. Heute `.obsidian/` — Obsidian schreibt dort bei jedem Klick
# (workspace.json). Das gitignore-Fragment nimmt den Ordner aus Git; diese
# Ausnahme haelt, wenn die Zeile im Projekt fehlt (vor dem Update angelegt, von
# Hand entfernt). Ohne sie haette der Guard die Arbeitsflaeche des Menschen
# einer Rolle angelastet und zurueckgerollt. Angelegt wird der Ordner vom Kit
# nie — er taucht auf, sobald der Stakeholder das Projekt als Vault oeffnet.
TEAM_GUARD_IGNORIERT='^\.obsidian(/|$)'

# --- Rohmaterial-Zonen des Stakeholders (BL-263) ------------------------------
# TEAM_ROHMATERIAL_ORDNER ist der Eingang des Menschen — eine Leerliste von
# Ordnern (Default `raw/ Clippings/`), in die NUR er ablegt; jede Rolle liest
# dort nur. `raw/` legt der Installer an, `Clippings/` taucht auf, sobald der
# Stakeholder Web-Clippings ablegt. Beide stehen im gitignore-Fragment — Git
# und damit Guard und Rollback sehen sie nicht. Zwei Dinge sichern sie trotzdem:
#
#   * team_pfade_zuruecksetzen fasst keinen Pfad darunter an. Das deckt die
#     Wege, auf denen eine Zone doch in eine Pfadliste geraet: Eine Rolle hat
#     Material mit `git add -f` committet, oder das Fragment fehlt im Projekt.
#     Wie knapp das ist, zeigt BL-24: Dort ueberlebte ein manueller
#     Input-Ordner namens `raw/` nur, weil der Rollback an Verzeichnissen
#     scheiterte. Seit dem Fix haette er ihn geloescht.
#   * Ein Schnappschuss (Pfad, Groesse, Zeitstempel) beim Rollenstart und der
#     Abgleich danach machen jeden Schreibzugriff sichtbar. Gemeldet wird er
#     als Uebergriff; geloescht oder zurueckgesetzt wird NICHTS. Ob eine
#     Aenderung von der Rolle oder vom Stakeholder stammt, ist nicht zu
#     unterscheiden — und fremdes Material wegzuraeumen waere schlimmer als
#     jeder Rest (dieselbe Abwaegung wie in team_fremd_ausfiltern).
#
# Der Wert bleibt, wie die Konfiguration ihn gesetzt hat — normalisiert wird
# nur beim Gebrauch (team_raw_zonen). Die Bibliothek reicht
# Konfigurationswerte unveraendert durch; auf der pwsh-Bahn prueft BL-182 genau
# das, und beide Bahnen sollen hier dasselbe tun.
TEAM_ROHMATERIAL_ORDNER="${TEAM_ROHMATERIAL_ORDNER:-raw/ Clippings/}"

# team_raw_zonen — die Zonen einzeln, je Zeile eine, ohne abschliessenden
# Schraegstrich (so nennen Git-Pfade sie). Ordnernamen mit Leerzeichen werden
# nicht unterstuetzt — dieselbe Grenze wie bei TEAM_WEITERER_CODE.
team_raw_zonen() {
    local -a zonen=()
    local zone
    read -r -a zonen <<< "${TEAM_ROHMATERIAL_ORDNER:-}" || true
    for zone in "${zonen[@]+"${zonen[@]}"}"; do
        zone="${zone%/}"
        if [ -n "$zone" ]; then printf '%s\n' "$zone"; fi
    done
    return 0
}

# team_raw_pfad <pfad> — Exit 0, wenn <pfad> in einer Rohmaterial-Zone liegt;
# auch der Ordner selbst, wie `git status` ihn als EINEN Eintrag meldet.
team_raw_pfad() {
    local zone
    while IFS= read -r zone; do
        case "$1" in
            "$zone"|"$zone"/*) return 0 ;;
        esac
    done < <(team_raw_zonen)
    return 1
}

# team_raw_stand — je Eintrag unter den Zonen eine Zeile, sortiert:
#   "d<TAB><pfad>" fuer Ordner, "f<TAB><pfad><TAB><bytes><TAB><mtime>" sonst,
#   Pfade ab der Repo-Wurzel — wie Git und jede andere Guard-Meldung sie nennen.
# Eine Zone, die es (noch) nicht gibt, traegt nichts bei. Scheitert `find` an
# einem Eintrag, bleibt der Rest gueltig: Eine Pruefung darf den Rollenlauf
# nicht abbrechen.
team_raw_stand() {
    local zone
    while IFS= read -r zone; do
        [ -d "$zone" ] || continue
        find "$zone" -mindepth 1 \( -type d -printf 'd\t%p\n' \) \
            -o \( -printf 'f\t%p\t%s\t%T@\n' \) 2>/dev/null || true
    done < <(team_raw_zonen) | LC_ALL=C sort
    return 0
}

team_raw_begin() {
    TEAM_RAW_VORHER="$(team_raw_stand)"
    TEAM_RAW_ERFASST=1
}

# team_raw_pruefen <rolle>
#   Exit 0 = die Zonen sind unveraendert · 1 = Uebergriff, laut gemeldet.
#   Faengt nie etwas an: kein Loeschen, kein Zuruecksetzen, kein Commit.
team_raw_pruefen() {
    local rolle="$1" nachher abweichung
    if [ "${TEAM_RAW_ERFASST:-0}" != 1 ]; then
        echo "[$rolle] Rohmaterial-Zone (${TEAM_ROHMATERIAL_ORDNER}): kein Startstand erfasst — NICHT geprüft." >&2
        return 0
    fi
    nachher="$(team_raw_stand)"
    if [ "$nachher" = "$TEAM_RAW_VORHER" ]; then
        return 0
    fi
    abweichung="$( { awk -F'\t' '
        NR == FNR { if ($0 != "") vorher[$2] = $0; next }
        $0 != "" { jetzt[$2] = $0 }
        END {
            for (p in jetzt)
                if (!(p in vorher)) print "neu:       " p
                else if (vorher[p] != jetzt[p]) print "geändert:  " p
            for (p in vorher)
                if (!(p in jetzt)) print "entfernt:  " p
        }' <(printf '%s\n' "$TEAM_RAW_VORHER") <(printf '%s\n' "$nachher") || true; } \
        | LC_ALL=C sort -k2)"
    echo "[$rolle] ÜBERGRIFF in der Rohmaterial-Zone (${TEAM_ROHMATERIAL_ORDNER}) — sie gehört dem Stakeholder, jede Rolle liest dort nur:" >&2
    printf '%s\n' "$abweichung" | sed 's/^/  /' >&2
    echo "  Nichts davon wurde angefasst (BL-263). Stammt eine Änderung nicht vom Stakeholder, hat die Rolle die Zone verletzt — von Hand prüfen." >&2
    return 1
}

# team_fremd_ausfiltern <pfadliste>
#   Entfernt aus <pfadliste> alles, was team_guard_fremdpfade als fremd
#   ausweist — mit einer Feinheit, die beim Bau von BL-114 aufgefallen ist und
#   die auch den Guard betraf:
#
#   `git status --porcelain` meldet ein untracked VERZEICHNIS als EINEN
#   Eintrag mit Schrägstrich (`plans/`), nicht als Liste seiner Dateien —
#   dieselbe Eigenheit, an der BL-24 haengt. Der Startschnappschuss haelt
#   deshalb `plans/` fest. Committet eine Rolle eine fremde Datei aus so einem
#   Ordner versehentlich mit (`git add -A` ist bei bypassPermissions der
#   Normalfall), taucht sie danach als `plans/closeout.md` auf und passt auf
#   KEINEN Eintrag der Fremdliste mehr. Ein reiner Zeichenvergleich haette sie
#   geloescht — also genau die uncommittete Closeout-Ausgabe, wegen der
#   BL-114 geschrieben wurde. Deshalb gilt ein Pfad auch dann als fremd, wenn
#   er UNTER einem fremden Ordnereintrag liegt.
#
#   Bewusst in diese Richtung konservativ: Legt die Rolle eine eigene Datei in
#   einen bereits fremden Ordner, bleibt sie liegen. Ein Rest, der liegen
#   bleibt, ist sichtbar und behebbar; fremde Arbeit, die geloescht wurde, ist
#   weg.
team_fremd_ausfiltern() {
    local liste="$1" fremd pfad eintrag behalten
    [ -z "$liste" ] && return 0
    fremd="$(team_guard_fremdpfade)"
    if [ -z "$fremd" ]; then
        printf '%s\n' "$liste"
        return 0
    fi
    while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        behalten=1
        while IFS= read -r eintrag; do
            [ -z "$eintrag" ] && continue
            if [ "$pfad" = "$eintrag" ]; then
                behalten=0
            else
                case "$eintrag" in
                    */) [ "${pfad#"$eintrag"}" != "$pfad" ] && behalten=0 ;;
                esac
            fi
        done <<< "$fremd"
        [ "$behalten" -eq 1 ] && printf '%s\n' "$pfad"
    done <<< "$liste"
    return 0
}

# team_eigene_pfade <pathspec…>
#   Gibt die abweichenden Pfade unter <pathspec…> aus, die dieser Rolle
#   GEHOEREN — fremde sind ausgefiltert. Leere Ausgabe = nichts Eigenes.
#
#   WARUM ES SIE GIBT (BL-206, Feld B): Der Commit-Block des Red-Team-Sweeps
#   war die DRITTE Stelle mit derselben Zustaendigkeit und die einzige ohne
#   den Filter. team_guard_verify und team_rollback_rolle rufen beide
#   team_fremd_ausfiltern; der Sweep staged stattdessen `git add <testordner>`
#   blanko — und `git add` auf einen Ordner nimmt JEDE untracked Datei darin
#   mit, auch die fremde. Sie landet dann unter der Sweep-Botschaft, also
#   unter einer Urheberschaft, die nicht stimmt. Woertlich die Bauform von
#   BL-114 (dort war der `git clean` eingeschraenkt, das `git reset --hard`
#   daneben nicht): zwei Stellen nachgezogen, die dritte nicht.
#
#   WARUM --untracked-files=all: `git status --porcelain` meldet ein untracked
#   VERZEICHNIS als EINEN Eintrag mit Schraegstrich. Wer den blanko staged,
#   hat wieder den Ordner adressiert statt der Datei — der Fix waere keiner.
#   team_fremd_ausfiltern kennt die Ordner-Schreibweise auf der FREMD-Seite
#   und faengt eine Datei auch unter einem fremden Ordnereintrag ab; die
#   Aufloesung hier kostet also nichts und schliesst die Luecke.
team_eigene_pfade() {
    local roh eigene pfad
    roh="$(git status --porcelain --untracked-files=all -- "$@" 2>/dev/null | cut -c4- | grep -v '^$' || true)"
    [ -z "$roh" ] && return 0
    eigene="$(team_fremd_ausfiltern "$roh")"
    # Sichtbar machen statt still weglassen: Wer den Sweep-Commit liest, soll
    # wissen, dass hier fremde Arbeit lag — und dass sie unangetastet blieb.
    # Ein stilles Auslassen waere die Fehlerrichtung von BL-160.
    while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        if ! echo "$eigene" | grep -Fxq -- "$pfad"; then
            echo "[guard] Nicht angefasst, lag vor dem Rollenstart im Baum (BL-206): $pfad" >&2
        fi
    done <<< "$roh"
    echo "$eigene"
    return 0
}

# team_pfade_zuruecksetzen <rolle> <hash> <pfadliste>
#   Setzt JEDEN uebergebenen Pfad EINZELN auf den Stand von <hash> zurueck:
#   beim Start getrackt → `git checkout <hash> -- <pfad>`, neu entstanden →
#   gezielt entfernen. Gibt auf STDOUT die Pfade aus, die danach WEITERHIN
#   abweichen (leer = vollzogen); Meldungen gehen nach stderr.
#
#   Herausgeloest aus team_guard_verify (BL-114). Der Grund ist nicht
#   Aufraeumen: Die Einstiegsskripte rollten bis dahin mit einem blanken
#   `git reset --hard` + `git clean -fd` zurueck — also mit genau dem, was der
#   Kopf dieses Abschnitts sich seit dem 2026-07-10 verbietet. Die Lehre war am
#   Guard angewandt und am Aufrufer nicht. Eine gemeinsame Funktion macht das
#   Auseinanderlaufen unmoeglich, statt es nur zu verbieten.
team_pfade_zuruecksetzen() {
    local rolle="$1" hash="$2" liste="$3" pfad rest=""
    [ -z "$liste" ] && return 0
    while IFS= read -r pfad; do
        [ -z "$pfad" ] && continue
        if team_raw_pfad "$pfad"; then
            # BL-263: Die Rohmaterial-Zone gehoert dem Stakeholder — nie
            # zuruecksetzen, nie loeschen. Hoechstens aus dem INDEX nehmen, was
            # eine Rolle dort neu eingetragen hat (`git add -f`): Die Datei
            # bleibt liegen, der Ordner bleibt unversioniert.
            if ! git cat-file -e "$hash:$pfad" 2>/dev/null; then
                git rm -r --cached --quiet -- "$pfad" >/dev/null 2>&1 || true
            fi
            echo "[$rolle] Guard: '$pfad' liegt in der Rohmaterial-Zone — Stakeholder-Eigentum, NICHT angefasst (BL-263)." >&2
            continue
        fi
        if git cat-file -e "$hash:$pfad" 2>/dev/null; then
            # War beim Start getrackt → auf Startstand zurückholen.
            git checkout "$hash" -- "$pfad" 2>/dev/null || true
        else
            # Neu entstanden (committet oder untracked) → gezielt entfernen.
            #
            # `-r` ist hier nötig (Verzeichnisse), und `-r` auf einem Pfad aus
            # `git status` ist genau die Zeile, die man einmal richtig schreibt
            # und nie wieder ansieht. Deshalb die Plausibilitätsprüfung davor:
            # Der Pfad kommt ausschließlich aus `git status --porcelain`
            # innerhalb des Repos, ist also relativ und ohne führenden
            # Schrägstrich. Alles andere wird NICHT entfernt, sondern gemeldet.
            case "$pfad" in
                /*|*..*|"")
                    echo "[$rolle] Guard: '$pfad' sieht nicht nach einem Repo-Pfad aus — NICHT entfernt." >&2
                    rest="$rest$pfad"$'\n'
                    continue ;;
            esac
            git rm -rf --cached -- "$pfad" >/dev/null 2>&1 || true
            rm -rf -- "$pfad"
        fi
        # Der Erfolg wird GEPRÜFT, nicht angenommen. Sonst wiederholt sich die
        # eigentliche Lehre dieses Fundes bei der nächsten Ursache.
        if [ -e "$pfad" ] && ! git diff --quiet "$hash" -- "$pfad" 2>/dev/null; then
            rest="$rest$pfad"$'\n'
        fi
    done <<< "$liste"
    printf '%s' "$rest"
}

# team_rollback_rolle <rolle> <start-hash>
#   Verwirft den GESAMTEN Beitrag eines Rollenlaufs — Commits, Aenderungen an
#   getrackten Dateien und neu angelegte Dateien —, aber NUR seinen.
#
#   BL-114: Hier stand in frank.sh, axel.sh und redteam.sh ein blankes
#   `git reset --hard "$START_HASH"` (in frank zusaetzlich `git clean -fd`
#   ohne Pfadeinschraenkung). Das trifft JEDE uncommittete Arbeit im
#   Zielprojekt, nicht nur die der Rolle: eine parallele Sitzung, eine
#   Handaenderung, eine noch nicht committete Closeout-Ausgabe des
#   Architekten. Der Guard nebenan arbeitet seit derselben Lehre chirurgisch
#   und kennt ueber team_guard_begin sogar den Ausgangszustand des
#   Arbeitsbaums (BL-16) — zwei Zeilen weiter warf der Aufrufer weg, was der
#   Guard gerade sorgfaeltig geschont hatte.
#
#   Drei Dinge bleiben ausdruecklich unangetastet:
#     * Pfade aus dem Startschnappschuss, die sich seither nicht veraendert
#       haben (team_guard_fremdpfade) — fremde Arbeit.
#     * Laufzeitartefakte (TEAM_GUARD_LAUFZEIT) — dort liegen die Kostenlogs
#       DIESES Aufrufs; sie zu loeschen waere ein selbstverschuldeter BL-4.
#     * Gestagte fremde Aenderungen: HEAD wandert mit `--soft` zurueck, der
#       Arbeitsbaum bleibt dabei unberuehrt.
#
#   `git clean -fd` deckte den Fall ab, dass Frank mit bypassPermissions auch
#   AUSSERHALB des Produktivordners Dateien anlegt (HM-29). Das leistet die
#   Pfadliste weiter: `git status --porcelain` meldet jede nicht ignorierte
#   neue Datei im ganzen Repo — nur eben namentlich statt pauschal.
team_rollback_rolle() {
    local rolle="$1" start="$2" pfade rest
    pfade="$( { git diff --name-only "$start" HEAD 2>/dev/null;
                git status --porcelain | cut -c4-; } | sort -u \
              | grep -Ev "$TEAM_GUARD_LAUFZEIT" \
              | grep -Ev "$TEAM_GUARD_IGNORIERT" || true)"
    pfade="$(team_fremd_ausfiltern "$pfade")"
    if [ "$(git rev-parse HEAD)" != "$start" ]; then
        git reset --soft "$start" >/dev/null 2>&1 || true
    fi
    rest="$(team_pfade_zuruecksetzen "$rolle" "$start" "$pfade")"
    if [ -n "$rest" ]; then
        echo "[$rolle] ROLLBACK UNVOLLSTÄNDIG — diese Pfade stehen weiterhin abweichend im Baum:" >&2
        printf '%s' "$rest" | sed 's/^/  /' >&2
        echo "  Von Hand prüfen und zurücknehmen." >&2
        return 1
    fi
    return 0
}

team_guard_verify() {
    local rolle="$1" whitelist="$2" roh nicht_angelastet verletzungen raw_rc=0
    # BL-263: Die Rohmaterial-Zone prueft ihr eigener Schnappschuss — Git sieht
    # sie nicht. Ein Uebergriff dort zaehlt wie jeder andere, nur ohne Rollback.
    team_raw_pruefen "$rolle" || raw_rc=1
    roh="$( { git diff --name-only "$TEAM_GUARD_HASH" HEAD 2>/dev/null;
              git status --porcelain | cut -c4-; } | sort -u \
            | grep -Ev "$whitelist" \
            | grep -Ev "$TEAM_GUARD_LAUFZEIT" \
            | grep -Ev "$TEAM_GUARD_IGNORIERT" || true)"
    [ -z "$roh" ] && return "$raw_rc"

    # BL-114: derselbe Filter wie im Rollback — er kennt auch den Fall, dass
    # eine fremde Datei aus einem untracked ORDNER mitcommittet wurde und
    # danach unter ihrem vollen Pfad auftaucht.
    verletzungen="$(team_fremd_ausfiltern "$roh")"
    if [ -n "$verletzungen" ]; then
        nicht_angelastet="$(printf '%s\n' "$roh" \
                            | grep -Fxvf <(printf '%s\n' "$verletzungen") || true)"
    else
        nicht_angelastet="$roh"
    fi

    if [ -z "$verletzungen" ]; then
        # Der Verdacht löst sich auf. Genau dieser Fall wurde im Feld einer
        # Rolle angelastet, die ihn nicht verursacht hatte.
        echo "[$rolle] Guard: Pfade außerhalb der Whitelist geändert, aber ALLE waren beim Rollenstart bereits geändert und sind es unverändert — nicht dieser Rolle zugeschrieben, kein Rollback:" >&2
        printf '%s\n' "$nicht_angelastet" | sed 's/^/  /' >&2
        return "$raw_rc"
    fi

    # Die Meldung trennt die beiden Fälle ausdrücklich sprachlich. Im Feld wurde
    # der Übergriff zunächst der falschen Rolle zugeschrieben, weil die Pfadliste
    # im Log neben ihrem Namen stand — belegt war das nirgends.
    #
    # BL-24: Die Vollzugsmeldung steht bewusst NICHT mehr vor dem Aufräumen.
    # `rm -f` (ohne -r) kann kein Verzeichnis entfernen, und `git status
    # --porcelain` meldet ein untracked Verzeichnis als EINEN Eintrag mit
    # Schrägstrich (`raw/`), nicht als Liste seiner Dateien. Der Rollback
    # scheiterte damit still, während elf Zeilen vorher schon "chirurgischer
    # Rollback" gedruckt war — der Guard behauptete einen Vollzug, den es
    # nicht gab. Im Feld an einem Harry-Sweep beobachtet; dort ein Glücksfall,
    # weil der Ordner erhalten bleiben sollte. Legt eine Rolle selbst ein
    # Verzeichnis an (Wegwerf-Skripte, `__pycache__` unter einem neuen Pfad),
    # bleibt es samt Inhalt liegen, während der Lauf Vollzug protokolliert.
    echo "[$rolle] GUARD-VERLETZUNG — DIESE ROLLE hat die folgenden Pfade geändert:" >&2
    printf '%s\n' "$verletzungen" >&2
    if [ -n "$nicht_angelastet" ]; then
        echo "[$rolle] NICHT angelastet (beim Rollenstart bereits geändert, seither unverändert):" >&2
        printf '%s\n' "$nicht_angelastet" | sed 's/^/  /' >&2
    fi
    local rest p raw_ausgenommen=0
    rest="$(team_pfade_zuruecksetzen "$rolle" "$TEAM_GUARD_HASH" "$verletzungen")"
    while IFS= read -r p; do
        if [ -n "$p" ] && team_raw_pfad "$p"; then raw_ausgenommen=1; fi
    done <<< "$verletzungen"
    if [ -n "$rest" ]; then
        echo "[$rolle] Guard: ROLLBACK UNVOLLSTÄNDIG — diese Pfade stehen weiterhin abweichend im Baum:" >&2
        printf '%s' "$rest" | sed 's/^/  /' >&2
        echo "  Von Hand prüfen und zurücknehmen; der Lauf gilt als Übergriff." >&2
    elif [ "$raw_ausgenommen" -eq 1 ]; then
        # BL-24-Lehre: Die Vollzugsmeldung darf nicht mehr behaupten, als
        # geschehen ist. Die Zone blieb bewusst stehen — das steht hier.
        echo "[$rolle] Guard: chirurgischer Rollback vollzogen — AUSGENOMMEN die Rohmaterial-Zone (siehe oben, von Hand prüfen)." >&2
    else
        echo "[$rolle] Guard: chirurgischer Rollback vollzogen." >&2
    fi
    return 1
}

# team_guard_urteil <rolle> <uebergriff 0|1> <ergebnis-liegt-vor 0|1>
#   Exit 0 = die Runde zählt · 1 = der Aufruf gilt als gescheitert.
#
# BL-16 Ebene 2 (Stakeholder-Entscheid 2026-08-02): Ein Guard-Übergriff
# kassiert den ÜBERGRIFF, nicht die Arbeit. Liegt das eigentliche Ergebnis der
# Rolle vor, ist die Leistung erbracht — der Grenzübertritt ist bereits
# chirurgisch zurückgerollt und laut gemeldet, und ein zusätzlicher Fehlschlag
# bestraft nur noch das Falsche: Er speist den Stagnationszähler und stoppt den
# Lauf. Genau so ging im Feld ein fertiger, korrekter Ermittlungsbericht als
# "Aufruf fehlgeschlagen" durch. Fehlt das Ergebnis, bleibt es beim Fehlschlag.
team_guard_urteil() {
    local rolle="$1" uebergriff="$2" ergebnis="$3"
    [ "$uebergriff" -eq 0 ] && return 0
    if [ "$ergebnis" -eq 1 ]; then
        echo "[$rolle] Guard-Übergriff kassiert, Ergebnis zählt — die Arbeit ist geleistet, zurückgerollt wurde nur der Grenzübertritt." >&2
        return 0
    fi
    echo "[$rolle] Guard-Übergriff UND kein vollständiges Ergebnis — Aufruf gilt als gescheitert." >&2
    return 1
}

# --- Substanz-Anker für Frank (HM-29) -----------------------------------------
# team_diff_beruehrt_fund <HM-Nr> <start-hash>
# Franks Dreisatz-Verifikation prüfte bislang nur FORM (Promise, Commit-
# Message-Muster, Beutebuch-Status), nie, ob der committete Diff überhaupt mit
# dem gemeldeten Fund zu tun hat — ein Fund konnte so fälschlich als "erledigt"
# verbucht werden, obwohl die eigentliche Fundstelle nie angefasst wurde
# (HM-29). Diese Funktion prüft LOSE, ob mindestens eine der im Beutebuch-Block
# per Backtick referenzierten Dateien (team/tools/beutebuch.py dateien) im Diff
# seit start-hash vorkommt. Nennt der Fund KEINE Datei, gilt die Prüfung als
# bestanden (kein falscher Blocker bei rein beschreibenden Funden).
team_diff_beruehrt_fund() {
    local hm="$1" start="$2" fund_dateien diff_dateien f d
    fund_dateien="$($TEAM_BEUTEBUCH_TOOL dateien "$hm" 2>/dev/null || true)"
    [ -z "$fund_dateien" ] && return 0
    diff_dateien="$(git diff --name-only "$start" HEAD)"
    while IFS= read -r f; do
        [ -z "$f" ] && continue
        while IFS= read -r d; do
            case "$d" in
                *"$f") return 0 ;;
            esac
        done <<< "$diff_dateien"
    done <<< "$fund_dateien"
    return 1
}

# team_reproducer_liegt_vor <HM-Nr>
# BL-28: Der Substanz-Anker oben besteht, sobald IRGENDEINE im Fundblock
# referenzierte Datei im Diff liegt — und das ist regelmäßig die
# Produktivdatei, die der Fix ohnehin anfasst. Im Feld reservierte `HM-30`
# einen Reproducer-Pfad, Franks Fix berührte CHANGELOG und Produktivdatei, die
# Testdatei entstand NIE, und der Anker war zufrieden. Damit ist die
# Absicherung genau dort wirkungslos, wo BL-15 sie einführen wollte.
#
# Diese Funktion prüft die EINE Datei, deren Zweck die Absicherung ist: den
# Pfad aus der `Reproducer-Test`-Zeile. Rückgabe 0, wenn er existiert ODER der
# Fund keine lesbare solche Zeile trägt (dafür ist `beutebuch.py lint` vor dem
# Lauf zuständig, BL-29 — nicht diese Prüfung nach dem Lauf).
# Rückgabe 1 nur im benannten Fall: Pfad reserviert, Datei nicht angelegt.
team_reproducer_liegt_vor() {
    local hm="$1" pfad
    pfad="$($TEAM_BEUTEBUCH_TOOL reproducer "$hm" 2>/dev/null || true)"
    [ -z "$pfad" ] && return 0
    [ -e "$pfad" ] && return 0
    return 1
}

# --- Lock (eine Pipeline zur Zeit) -----------------------------------------------
# Zwei Verfahren, EIN Versprechen. Der Normalfall ist `flock`; fehlt es, nimmt
# das Kit einen Sperrordner.
#
# BL-190: Vorher entschied EINE Bedingung (`if ! flock -n 9`) ueber beides —
# ein FEHLENDES PROGRAMM lieferte dort denselben Nicht-Null-Status wie eine
# BELEGTE SPERRE. Unter Git for Windows gibt es `flock` nicht (es gehoert nicht
# zum MSYS2-Kern, den Git mitliefert), und dort brach damit JEDE Rolle der
# bash-Bahn sofort ab — mit einer Meldung, die auf einen
# Nebenlaeufigkeitskonflikt zeigte, den es nicht gab. Wer ihr folgte, suchte
# einen zweiten Lauf, killte Prozesse oder loeschte die Lock-Datei; nichts
# davon half, weil die Datei nie das Problem war. Dieselbe
# Fehlerklassen-Verwechslung wie BL-173 (ein PATH-Problem als Auth-Fehler) und
# dieselbe Abhilfe: die Klasse TRENNEN, bevor man handelt.
#
# Warum ein ORDNER und nicht "laut ohne Sperre weiterlaufen": `mkdir` ist auf
# jedem POSIX-Dateisystem und unter MSYS atomar — Pruefen und Anlegen sind EIN
# Schritt, es gibt kein Fenster dazwischen. Damit bleibt die Zusicherung "eine
# Pipeline zur Zeit" ERHALTEN, statt gegen eine Meldung getauscht zu werden.
# Zwei Rollen gleichzeitig im selben Arbeitsbaum sind der Schaden, den BL-12
# teuer belegt hat.
#
# Der Ordner ist der ERSATZ, nicht der Normalfall: Wo `flock` da ist, bleibt
# es. Sonst laegen zwei Sperrmechaniken im Feld, und bei einem Vorfall wuesste
# niemand, welche gegriffen hat — genau deshalb sagt der Ersatzweg einmal
# ausdruecklich an, dass er laeuft.
TEAM_LOCK_DATEI=".team-loop.lock"
TEAM_LOCK_ORDNER=".team-loop.lock.d"

# team_flock_vorhanden: Ist `flock` aufloesbar? (0 = ja)
# Reine ABFRAGE, ohne zu melden — Bauart team_cli_vorhanden (BL-173).
team_flock_vorhanden() {
    command -v flock >/dev/null 2>&1
}

# team_flock_fehlt_melden <label>: sagt den Ersatzweg an, mit dem Werkzeug beim
# Namen.
#
# Das ist kein Fehler und keine Warnung, sondern eine Bestandsangabe: Bei einem
# Vorfall muss ohne Nachforschen feststehen, WELCHE der beiden Sperren gegriffen
# hat. Sie erscheint hoechstens einmal je Pipeline — die Kind-Skripte laufen
# unter TEAM_LOCK_HELD=1 und kommen hier nie an.
team_flock_fehlt_melden() {
    echo "[${1:-team}] Hinweis: 'flock' ist auf dieser Maschine nicht vorhanden." >&2
    echo "  Die Sperre läuft deshalb über den Ordner $TEAM_LOCK_ORDNER (gleichwertig, BL-190)." >&2
    echo "  Das ist KEIN Sperrkonflikt — es läuft keine zweite Pipeline." >&2
}

# team_lock_ordner_verwaist: Haelt den Sperrordner noch ein LEBENDER Prozess?
# (0 = verwaist, darf uebernommen werden)
#
# Die hinterlegte PID ist genau dafuer da. Ohne diesen Teil tauscht man einen
# Fehlalarm gegen einen DAUERHAFTEN: Ein Lauf, der abstuerzt, blockierte sonst
# jeden folgenden, und niemand koennte den Unterschied zu einem echten
# Doppellauf sehen.
#
# Uebernommen wird STILL. Ein toter Prozess haelt nichts — das ist kein Befund,
# und eine Meldung, die nach jedem regulaeren Lauf erscheint, waere nach BL-14
# keine.
team_lock_ordner_verwaist() {
    local pid
    pid="$(cat "$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)"
    # Keine lesbare PID: Der Ordner steht, aber niemand bekennt sich zu ihm —
    # der Lauf ist zwischen mkdir und dem Schreiben gestorben. Als "gehalten"
    # zu werten machte die Ablage dauerhaft unbrauchbar, und zwar durch genau
    # den Fehlalarm, den dieser Eintrag abstellt.
    [ -n "$pid" ] || return 0
    kill -0 "$pid" 2>/dev/null && return 1
    return 0
}

# team_lock_ordner_nehmen <label>: der Ersatzweg. 0 = Sperre gehoert uns.
team_lock_ordner_nehmen() {
    local label="$1" pid
    if ! mkdir "$TEAM_LOCK_ORDNER" 2>/dev/null; then
        if ! team_lock_ordner_verwaist; then
            pid="$(cat "$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)"
            echo "[$label] Eine andere T.E.A.M.-Pipeline läuft bereits ($TEAM_LOCK_ORDNER, PID ${pid:-?}) — Abbruch." >&2
            return 1
        fi
        rm -rf "$TEAM_LOCK_ORDNER"
        if ! mkdir "$TEAM_LOCK_ORDNER" 2>/dev/null; then
            # Zwischen Pruefung und Anlegen war ein anderer schneller. DAS ist
            # der Konfliktfall, und hier heisst die Meldung zu Recht so.
            echo "[$label] Eine andere T.E.A.M.-Pipeline läuft bereits ($TEAM_LOCK_ORDNER) — Abbruch." >&2
            return 1
        fi
    fi
    printf '%s\n' "$$" > "$TEAM_LOCK_ORDNER/pid"
    # BL-199: Zusaetzlich die WINDOWS-PID, wenn der Wirt eine hat. Sie ist das
    # einzige Lebendigkeitsmerkmal, das die pwsh-Bahn auswerten KANN — `$$` ist
    # eine MSYS-PID aus einem eigenen Prozessraum. Gemessen: Git-Bash meldete
    # `$$` = 15946, `Get-Process -Id 15946` fand zeitgleich nichts; ueber
    # /proc/<pid>/winpid dagegen findet PowerShell den Prozess (nachgemessen
    # am 2026-08-28, Hin- und Rueckweg). Unter Linux gibt es die Datei nicht;
    # dann bleibt es bei `pid`, und die pwsh-Seite meldet ehrlich "unbekannt"
    # statt zu raten.
    if [ -r "/proc/$$/winpid" ]; then
        cat "/proc/$$/winpid" > "$TEAM_LOCK_ORDNER/winpid" 2>/dev/null || true
    fi
    team_lock_aufraeumen_anmelden
    return 0
}

# team_lock_aufraeumen_anmelden: gibt den Sperrordner beim Prozessende frei.
#
# Beim flock-Weg macht das der Kernel — der Deskriptor faellt beim Exit weg.
# Ein Ordner faellt nicht weg. Die PID-Uebernahme oben fuehrt zwar auch ohne
# diesen Teil zum Ziel, hinterliesse aber nach JEDEM Lauf ein Verzeichnis in
# der Ablage des Anwenders (dieselbe Gattung wie BL-196).
#
# Gesetzt wird der Trap nur, wenn EXIT noch FREI ist: Ein `trap ... EXIT` aus
# einer Bibliothek ueberschreibt still, was das aufrufende Skript dort schon
# haengen hat — ein teurer Nebeneffekt fuer eine Aufraeumarbeit. Ist EXIT
# belegt, bleibt die PID-Uebernahme der Weg. Sie ist der Grund, warum dieser
# Teil eine Bequemlichkeit sein DARF und keine Zusicherung sein MUSS.
team_lock_aufraeumen_anmelden() {
    if [ -n "$(trap -p EXIT)" ]; then return 0; fi
    trap 'team_unlock' EXIT
}

# team_unlock: Gegenstueck zu team_lock, mit dem pwsh-Zweig gleichgezogen.
# Gibt NUR frei, was dieser Prozess selbst haelt — sonst raeumte ein Lauf die
# Sperre eines fremden weg und machte aus der Zusicherung das Gegenteil.
team_unlock() {
    if [ -d "$TEAM_LOCK_ORDNER" ] \
       && [ "$(cat "$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)" = "$$" ]; then
        rm -rf "$TEAM_LOCK_ORDNER"
    fi
    # Und der flock-Weg: Beim Prozessende faellt der Deskriptor ohnehin weg,
    # aber wer team_unlock RUFT, will die Sperre JETZT los — sonst gaebe die
    # Funktion auf dem einen Weg frei und auf dem anderen nur den Anschein.
    # Auf einem nie geoeffneten Deskriptor ist das folgenlos.
    exec 9>&- 2>/dev/null || true
    unset TEAM_LOCK_HELD
    return 0
}

# team_lock <label>: nimmt die Sperre (non-blocking). Läuft das Skript
# unterhalb der Vollautomatik (TEAM_LOCK_HELD=1), wird nicht erneut gelockt.
team_lock() {
    if [ "${TEAM_LOCK_HELD:-0}" = "1" ]; then return 0; fi
    if team_flock_vorhanden; then
        exec 9>"$TEAM_LOCK_DATEI"
        if ! flock -n 9; then
            echo "[$1] Eine andere T.E.A.M.-Pipeline läuft bereits ($TEAM_LOCK_DATEI) — Abbruch." >&2
            return 1
        fi
    else
        team_flock_fehlt_melden "$1"
        team_lock_ordner_nehmen "$1" || return 1
    fi
    export TEAM_LOCK_HELD=1
}

# team_pipeline_laeuft [wurzel]: Haelt gerade jemand die Sperre?
#   0 = ja   1 = nein   2 = UNKLAR (BL-199)
#
# Der dritte Zustand ist der Inhalt von BL-199 und keine Bequemlichkeit: Es
# gibt seit BL-190 ZWEI Sperrartefakte, und ihr Lebendigkeitsmerkmal ist nicht
# auf jeder Bahn auswertbar. Wer daraus ein Ja/Nein presst, luegt in eine von
# beiden Richtungen — und beide Luegen sind teuer: "idle" auf einen laufenden
# Lauf ist ein Bericht, dem man nicht mehr glauben darf; "laeuft" auf einen
# toten Rest ist der Dauer-Fehlalarm, den BL-190 gerade abgestellt hat.
# Der Aufrufer entscheidet, was Vorsicht bei IHM heisst: der BL-10-Schutz im
# Installer bricht bei 2 ab, der Statusbericht sagt "unbekannt".
#
# BL-190 ist eine GATTUNG, keine Stelle (BL-154): Die Frage "laeuft gerade eine
# Pipeline?" wird an DREI Orten gestellt — hier, in `team-status.sh` (Zeile
# "Pipeline: laeuft/idle") und in `install.sh` vor einem `--update`. Alle drei
# fragten `flock`, und alle drei gaben ohne `flock` die falsche Antwort:
#
#   * `install.sh` las `! flock -n … true` als "gehalten", weil ein fehlendes
#     Programm Nicht-Null liefert — ein `--update` brach also ab, sobald die
#     Datei ueberhaupt existierte. Derselbe Fehler wie in `team_lock`, an einer
#     zweiten Stelle.
#   * `team-status.sh` hatte `command -v flock` davor und meldete deshalb
#     "idle" — was ab jetzt falsch ist, weil der Ersatzweg eine Sperre haelt,
#     von der die Zeile nichts weiss. Ein Bericht, der eine laufende Pipeline
#     als idle ausweist, ist schlimmer als gar keiner.
#
# Beide Mechaniken werden gefragt, und der Ordner zuerst: Wo er liegt, ist er
# die gueltige Sperre.
team_pipeline_laeuft() {
    local wurzel="${1:-.}" pid
    if [ -d "$wurzel/$TEAM_LOCK_ORDNER" ]; then
        pid="$(cat "$wurzel/$TEAM_LOCK_ORDNER/pid" 2>/dev/null || true)"
        if [ -n "$pid" ]; then
            # Lesbares eigenes Merkmal: Es wird ausgewertet, und sein
            # Ergebnis gilt. Eine tote PID heisst verwaist — nicht unklar.
            kill -0 "$pid" 2>/dev/null && return 0
        elif [ -s "$wurzel/$TEAM_LOCK_ORDNER/winpid" ]; then
            # BL-199: Kein lesbares `pid`, aber ein `winpid` — der Ordner
            # stammt dann von einem Lauf, dessen Merkmal DIESE Bahn nicht
            # auswerten kann (eine Windows-PID liegt ausserhalb des
            # MSYS-Prozessraums, gemessen). "Verwaist" waere hier eine
            # Behauptung, "gehalten" ebenfalls.
            return 2
        fi
    fi
    if [ -e "$wurzel/$TEAM_LOCK_DATEI" ]; then
        # (a) Der eigene, kooperative Weg.
        if command -v flock >/dev/null 2>&1 \
           && ! flock -n "$wurzel/$TEAM_LOCK_DATEI" true 2>/dev/null; then
            return 0
        fi
        # (b) BL-199: Dieselbe Datei haelt die pwsh-Bahn mit FileShare::None —
        # eine Sperre, die das BETRIEBSSYSTEM durchsetzt und die `flock` nicht
        # sieht. Gemessen: Ein Schreib-Oeffnen scheitert dann mit "Device or
        # resource busy". Unter Linux setzt .NET FileShare nicht durch, dort
        # gelingt das Oeffnen immer — die Probe ist also genau dort still, wo
        # sie nichts zusichern koennte. In einer SUBSHELL, damit der Deskriptor
        # 9 des Aufrufers (team_lock!) unangetastet bleibt.
        if ! ( exec 9>>"$wurzel/$TEAM_LOCK_DATEI" ) 2>/dev/null; then
            return 0
        fi
    fi
    return 1
}

# --- Ergebnis-Prüfung --------------------------------------------------------
# team_result_is_error <json-datei>
# Rückgabe 0, wenn die JSON-Ausgabe von `claude -p` einen Fehler meldet
# (is_error) oder gar nicht lesbar ist — dann greift z. B. Ralphs API-Fallback.
team_result_is_error() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(0)
sys.exit(0 if data.get("is_error") else 1)
' "$1"
}

# team_bewerte_ergebnis <rolle> <out-datei> <cli-exit-code>
# HM-33: Der reine Prozess-Exit-Code der `claude`-CLI darf ein geschriebenes
# Erfolgs-JSON (is_error:false) nicht überstimmen — z. B. endet die CLI bei
# gesetztem ANTHROPIC_API_KEY mit einer reinen "connectors disabled"-Warnung
# und Exit≠0, obwohl das Ergebnis inhaltlich erfolgreich ist. Das geschriebene
# JSON ist die letzte Instanz: Rückgabe 1 (Fehler) NUR wenn team_result_is_error
# zutrifft (Datei nicht lesbar ODER is_error:true) — der CLI-Exit-Code fließt
# nur noch in die Warnzeile ein, nicht mehr in die Erfolgs-/Fehler-Entscheidung.
team_bewerte_ergebnis() {
    local rolle="$1" out="$2" cli_exit="$3"
    if team_result_is_error "$out"; then
        return 1
    fi
    if [ "$cli_exit" -ne 0 ]; then
        echo "[$rolle] CLI-Exit≠0 trotz gültigem Erfolgs-JSON — werte als Erfolg (vermutlich reine CLI-Warnung, siehe HM-33)." >&2
    fi
    return 0
}

# --- Session-Limit (429) -------------------------------------------------------
# Kaskade 9 / Stufe 29 (plans/ralph-kaskade-9-session-limit.md): reine
# Erkennungs-/Parse-Logik. Warten/Retry folgt in Stufe 30.

# team_result_is_429 <json-datei>
# Rückgabe 0, wenn die JSON-Ausgabe von `claude -p` ein Session-Limit (429)
# meldet — über zwei Signale: das starke Feld api_error_status == 429, oder
# (Fallback für CLI-Versionen ohne dieses Feld) das Feld "result" IST IN
# GÄNZE (nicht nur als Teilstring irgendwo enthalten, HM-21) exakt die CLI-
# Systemmeldung "You've hit your session limit · resets HH[:MM]pm[ (Zone)]" —
# die Minuten sind OPTIONAL (BL-32): die CLI schreibt bei vollen Stunden nur
# "resets 3pm" (ohne ":00"), belegt durch den echten Vorfall in
# .ralph-logs/archiv/stufe-49-20260712-134536.json — ohne diese Optionalität
# wurde ein Doppel-429 (Abo UND API) fälschlich als "echter Fehler" (Exit 1)
# statt als Session-Limit gewertet und die Auto-Warte-/Retry-Logik übersprungen.
# belegt durch den echten Vorfall in .team-logs/harry-20260711-184756.json
# ("You've hit your session limit · resets 6:50pm (Europe/Berlin)", ganzes
# result-Feld, num_turns 1: die CLI liefert diesen Satz unverändert und
# OHNE umgebenden Fließtext, weil dabei nie ein Modell-Turn stattfindet).
# HM-19 hatte den Anker bereits auf "hit your session limit" + wortgrenzen-
# geschütztes Reset-Muster verengt, blieb aber ein Teilstring-Suche — dadurch
# genügte weiterhin ein Claude-generierter Erklärtext, der das Beutebuch/den
# Kaskade-9-Plan wörtlich zitiert (HM-21: genau dieses Zitat steht jetzt
# dauerhaft im Repo). Ein bloßes Zitat mitten in längerem Fließtext hat immer
# zusätzliche Wörter davor/danach im result-Feld und besteht den vollständigen
# Abgleich (re.fullmatch auf den getrimmten String) deshalb NICHT mehr.
# Nicht lesbare Datei → kein 429 (Rückgabe 1), das bleibt Sache von
# team_result_is_error.
team_result_is_429() {
    "$TEAM_PYTHON" -c '
import json, re, sys
try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)
if data.get("api_error_status") == 429:
    sys.exit(0)
text = str(data.get("result") or "").strip()
# BL-32: Minuten optional (\d{1,2}(:\d{2})?) — die CLI schreibt bei vollen
# Stunden nur "resets 3pm" ohne ":00" (echter Vorfall stufe-49).
pattern = r"you.ve hit your session limit\s*[·\-–:]\s*resets\s+\d{1,2}(:\d{2})?\s*[ap]m(\s*\([^)]*\))?\.?"
if re.fullmatch(pattern, text, re.IGNORECASE):
    sys.exit(0)
sys.exit(1)
' "$1"
}

# team_429_reset_epoch <json-datei>
# Liest die Reset-Uhrzeit aus dem freien Ergebnistext ("resets HH:MMpm",
# 12h-Format, lokale Zeitzone) und gibt einen Unix-Epoch-Zeitpunkt in der
# Zukunft aus. Liegt die geparste Uhrzeit heute schon in der Vergangenheit,
# gilt sie für morgen (Reset über Mitternacht). Kein/unlesbares Datum → leere
# Ausgabe, Exit 1 — der Aufrufer behandelt das wie "Reset unbekannt".
# HM-22: durchsucht wie team_result_is_429 NUR das Feld "result" (nicht den
# kompletten JSON-Dump, der Zitate/andere Felder mit "resets HH:MMpm" enthalten
# kann) und verlangt Wortgrenzen um "resets ... [ap]m" — sonst kann ein Treffer
# aus falscher Fundstelle (z. B. einem Doku-Zitat) einen falschen Reset-
# Zeitpunkt liefern.
team_429_reset_epoch() {
    "$TEAM_PYTHON" -c '
import json, re, sys
from datetime import datetime, timedelta

try:
    data = json.load(open(sys.argv[1]))
except Exception:
    sys.exit(1)

text = str(data.get("result") or "")
# BL-32: Minuten-Gruppe optional; bei "resets 3pm" (volle Stunde ohne ":MM")
# ist die Minute 0. Ohne diese Optionalität lieferte die Funktion "Reset
# unbekannt", wodurch die Auto-Warte-/Retry-Logik (Strategie A) übersprungen
# und ein Doppel-429 fälschlich als harter Fehler (Exit 1) behandelt wurde.
m = re.search(r"\bresets\s+(\d{1,2})(?::(\d{2}))?\s*([ap]m)\b", text, re.IGNORECASE)
if not m:
    sys.exit(1)

hour = int(m.group(1)) % 12
if m.group(3).lower() == "pm":
    hour += 12
minute = int(m.group(2)) if m.group(2) else 0
if minute > 59:
    sys.exit(1)

now = datetime.now()
reset = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
if reset <= now:
    reset += timedelta(days=1)

print(int(reset.timestamp()))
' "$1"
}

# --- Kosten ------------------------------------------------------------------
# team_summe_cost_usd <json-datei…>
# Summe von total_cost_usd über MEHRERE Logs — die Kosten EINES team_claude-
# Aufrufs inklusive aller gescheiterten Vorversuche (Abo-Versuch vor dem
# API-Fallback, 429-Zwischenversuche). Fehlende/kaputte Dateien zaehlen als 0.
# Hintergrund (BL-55, real erlebt 2026-08-01, Kaskade 22 Stufe 93): Der Abo-
# Versuch scheiterte NACH 1.6806 USD, der API-Fallback kostete 0.3984 — gemeldet
# und gegen den Pro-Stufe-Cap geprueft wurden nur die 0.3984, weil TEAM_LAST_COST
# allein aus dem FINALEN Log gelesen wurde. Damit war der Cap umgehbar: 4.9 USD
# Abo-Fehlversuch + 4.9 USD API meldeten 4.9 gegen einen 5-USD-Deckel.
team_summe_cost_usd() {
    "$TEAM_PYTHON" -c '
import json, sys
gesamt = 0.0
for pfad in sys.argv[1:]:
    try:
        gesamt += float(json.load(open(pfad)).get("total_cost_usd", 0) or 0)
    except Exception:
        pass
print(f"{gesamt:.10f}")
' "$@"
}

# team_extract_cost_usd <json-datei>
# Liest total_cost_usd aus der JSON-Ausgabe von `claude -p --output-format json`.
team_extract_cost_usd() {
    "$TEAM_PYTHON" -c '
import json, sys
try:
    data = json.load(open(sys.argv[1]))
    print(data.get("total_cost_usd", 0) or 0)
except Exception:
    print(0)
' "$1"
}

# --- Kosten-Summierung (zentral, dedupliziert vollautomatik.sh/team-status.sh) -
# Kapselt team/tools/kosten.py — vorher existierte dieselbe Python-Summierung
# doppelt/dreifach als Inline-Heredoc in vollautomatik.sh und team-status.sh.

# team_kosten_summe <dir…>: Gesamtsumme total_cost_usd über alle *.json in
# den angegebenen Log-Ordnern (Abo + API zusammen).
team_kosten_summe() {
    $TEAM_KOSTEN_TOOL summe "$@"
}

# team_kosten_seit <epoch> <dir…>: Summe total_cost_usd nur über *.json, deren
# mtime >= <epoch> ist — die Kosten EINES Laufs (seit dem gemerkten Startpunkt),
# nicht lebenslang. Grundlage der Pro-Lauf-Deckel-Durchsetzung in vollautomatik.sh
# (BL-18, Stakeholder-Entscheid: „Pro-Lauf-Deckel = operative Grenze,
# Gesamtrahmen nur dokumentiert" — CLAUDE.md/BL-13). Der lebenslange Kontostand
# bleibt team_kontostand_gesamt (Anzeige, nicht Durchsetzung).
team_kosten_seit() {
    local seit="$1"; shift
    $TEAM_KOSTEN_TOOL summe --since "$seit" "$@"
}

# team_kosten_split <dir…>: wie team_kosten_summe, aber getrennt nach
# Abo-Gegenwert (nicht abgerechnet) und real abgerechneter API — Ausgabe
# "abo<TAB>api" (Klassifizierung über den Dateinamen, siehe team_claude:
# API-Fallback-Logs enden auf "-api-fallback.json").
team_kosten_split() {
    $TEAM_KOSTEN_TOOL summe --split "$@"
}

# team_ledger_summe [pfad]: historische Basissumme aus der committeten
# .budget-ledger (append-only, Stufe 18 in
# plans/ralph-kaskade-6-budget-governance.md). Kommentarzeilen (#) und
# Leerzeilen werden ignoriert; fehlende Datei ergibt 0.
team_ledger_summe() {
    $TEAM_KOSTEN_TOOL ledger "${1:-.budget-ledger}"
}

# team_ledger_domaene <website|team> [pfad]: Ledger-Summe gefiltert auf eine
# Domaene (BL-29, Kaskade 13/Stufe 41/44). Altzeilen ohne Domaenenfeld (vor
# Kaskade 13) zaehlen hier NIE mit — sie bleiben "unzugeordnet" (Differenz aus
# team_ledger_summe minus website minus team).
team_ledger_domaene() {
    local domaene="$1" pfad="${2:-.budget-ledger}"
    $TEAM_KOSTEN_TOOL ledger "$pfad" --domaene "$domaene"
}

# team_ledger_split [pfad]: wie team_ledger_summe, aber die usd-Spalte nach
# auth-Bucket getrennt — Ausgabe "abo<TAB>api<TAB>gemischt" (BL-17-Restpunkt/
# BL-29-"1b", Kaskade 16/Stufe 53). "gemischt" sammelt alles, was NICHT exakt
# auth=="abo" oder auth=="api" ist (v. a. "abo/api", aber auch Altzeilen ohne
# auth-Wert) — ehrlich statt geraten, es gilt immer
# abo+api+gemischt == team_ledger_summe.
team_ledger_split() {
    $TEAM_KOSTEN_TOOL ledger "${1:-.budget-ledger}" --split
}

# team_akteur_abschluss <rolle> <auth:abo|api> <usd> <domaene:website|team>
# [notiz] [pfad] [repo]: rollen-agnostischer A1-Abschluss (BL-33, Kaskade 15/
# Stufe 51) — duenner Wrapper um `kosten.py akteur-abschluss` fuer JEDE
# interaktiv (ausserhalb team_claude) arbeitende Rolle (Architekt, Frank im
# Abomodus, …), analog den bestehenden team_ledger_*-Wrappern. Alle Werte
# gehen als eigene argv-Elemente an Python (kein `python -c` mit roher
# Interpolation — Lehre aus BL-23/HM-17). pfad/repo optional, Default wie
# kosten.py (".budget-ledger"/"."), damit Fixture-Tests isoliert gegen ein
# Test-Ledger pruefen koennen.
# BL-26: Alles ab Position 8 sind Schalter des WERKZEUGS (--kaskade,
# --addieren, --ersetzen) und werden unveraendert durchgereicht. Vorher
# endete der Wrapper bei Position 7 und liess alles Weitere kommentarlos
# fallen — im Feld buchte ein Aufruf mit `--kaskade vor-23` dadurch auf die
# Kaskade aus .ralph-plan und ersetzte dort eine abgeschlossene Zeile ueber
# 8,4678 USD. Ein Wrapper, der Schalter still verschluckt, ist bei JEDER
# Erweiterung des Werkzeugs eine neue Falle; unbekannte Schalter lehnt
# kosten.py selbst ab, laut statt leise.
team_akteur_abschluss() {
    local rolle="$1" auth="$2" usd="$3" domaene="$4" notiz="${5:-}"
    local pfad="${6:-.budget-ledger}" repo="${7:-.}"
    if [ "$#" -gt 7 ]; then shift 7; else set --; fi
    if [ -n "$notiz" ]; then
        $TEAM_KOSTEN_TOOL akteur-abschluss --usd "$usd" \
            --domaene "$domaene" --rolle "$rolle" --auth "$auth" \
            --notiz "$notiz" --pfad "$pfad" --repo "$repo" "$@"
    else
        $TEAM_KOSTEN_TOOL akteur-abschluss --usd "$usd" \
            --domaene "$domaene" --rolle "$rolle" --auth "$auth" \
            --pfad "$pfad" --repo "$repo" "$@"
    fi
}

# team_architekt_kaskade [plan-datei]: Nummer der AKTIVEN Kaskade, aus dem
# Namen der Plan-Datei gelesen ("plans/ralph-kaskade-13-…" -> "13"). Leer,
# wenn keine Nummer erkennbar ist (frisches Projekt, benannte Kaskade,
# fehlende .ralph-plan) — der Aufrufer entscheidet dann selbst, ob er ohne
# Kaskadenbezug weitermacht.
#
# BL-18: Herausgeloest aus team_architekt_stand, weil die ANZEIGE die Nummer
# braucht, ohne dass die Zwei-Felder-Schnittstelle "USD<TAB>status" um ein
# drittes Feld wachsen muss (die haengt an mehreren Tests und an
# team-status.sh gleichzeitig). Eine Quelle fuer das Muster statt zwei.
team_architekt_kaskade() {
    local plan_datei="${1:-$(team_plan_datei)}"
    # Ein Projekt OHNE erkennbare Kaskadennummer (benannte Kaskade, frisches
    # Projekt) darf den Aufrufer nicht wegreissen. `| head -1` allein leistet
    # das nur unter `set -e`: Unter `set -o pipefail` bestimmt der ERSTE
    # fehlschlagende Teil den Status der Pipeline, also der leere grep (rc 1)
    # — egal was head zurueckgibt. Gemessen (BL-111): `set -e` und `set -eu`
    # gaben rc=0, `set -euo pipefail` riss den Aufrufer weg. Alle bauenden und
    # pruefenden Rollen laufen mit voller Strenge; die Zusicherung muss also
    # dort gelten, wo sie gebraucht wird, nicht nur eine Stufe darunter.
    # BL-209/BL-202: BEIDE Praefixe. `ralph-kaskade-` nennt eine Rolle,
    # obwohl die Datei das ganze Team bindet; kuenftige Projekte bekommen
    # `team-kaskade-`. Bestandsprojekte behalten ihre Namen — beide Formen
    # muessen deshalb NEBENEINANDER erkannt werden. Ohne das schaltet eine
    # Umbenennung diese Ableitung STUMM ab: Sie gibt dann leer zurueck, und
    # leer ist hier ein gueltiger Wert (benannte Kaskade), kein Fehler.
    { printf '%s' "$plan_datei" \
        | grep -oE '(ralph|team)-kaskade-[0-9]+' | grep -oE '[0-9]+' | head -1; } || true
}

# team_bau_notiz [plan-datei]: Notiztext fuer die ralph-(Bau-)Ledgerzeile,
# ABGELEITET aus dem Namen der Plandatei statt vom Menschen abgeschrieben.
# "plans/ralph-kaskade-22-doku-konsolidierung.md" -> "K22 doku-konsolidierung".
# Leer, wenn kein Muster erkennbar ist — dann schreibt kosten.py seinen
# eigenen Vorspann, und niemand behauptet etwas Falsches.
#
# BL-34: --rollen-abschluss schreibt ZWEI Zeilen (roles + ralph) und trug
# bisher in beide DENSELBEN, von Hand getippten Text. Der Mensch denkt beim
# Abschluss an das Red Team, also stand ueber Ralphs vier Baustufen die Notiz
# "Harry/Marv-Sweeps + Frank HM-9/HM-10". Zweimal im Feld passiert, beide Male
# von jemandem, der die Regel kurz vorher gelesen bzw. zitiert hatte — die
# Disziplinloesung traegt hier nachweislich nicht. Diese Ableitung ist die
# Variante (2) der Fix-Skizze: Die Information liegt in .ralph-plan vor und
# ist fuer eine Bau-Zeile die richtige.
team_bau_notiz() {
    local plan_datei="${1:-$(team_plan_datei)}" name nummer thema
    name="$(basename -- "$plan_datei" 2>/dev/null)"
    name="${name%.md}"
    # BL-209/BL-202: beide Praefixe, siehe team_kaskaden_nummer daneben.
    case "$name" in
        ralph-kaskade-[0-9]*|team-kaskade-[0-9]*)
            nummer="$(printf '%s' "$name" | grep -oE '[0-9]+' | head -1)"
            thema="${name#*-kaskade-${nummer}}"
            thema="${thema#-}"
            [ -n "$thema" ] && printf 'K%s %s' "$nummer" "$thema" \
                            || printf 'K%s' "$nummer"
            ;;
        *) ;;
    esac
}

# team_architekt_stand [ledger-pfad] [plan-datei]: liefert "USD<TAB>status"
# fuer die Architekt-Kosten der AKTIVEN Kaskade — BL-28-Hybrid A2->A1
# (Kaskade 13/Stufe 44): Hat der Stakeholder fuer diese Kaskade bereits
# eine echte Architekt-Zeile per `architekt-abschluss` (Stufe 43)
# eingetragen, ist status "echt" und der Wert kommt aus der Ledger. Sonst
# status "geschaetzt" mit der A2-Live-Schaetzung (team_architekt_schaetzung).
# Beide Pfade optional (Default ".budget-ledger"/aktives .ralph-plan) —
# Fixture-Tests koennen so isoliert gegen ein Test-Ledger/-Plan pruefen.
# HM-46: Existenz einer echten Zeile wird ueber die TREFFERANZAHL
# (--anzahl) geprueft, nicht mehr ueber einen Wertevergleich der Summe
# gegen den String "0.0000" — eine echte Zeile mit usd=0.0000 (z. B. eine
# Kaskade, in der der Architekt nachweislich 0 USD kostete) ist am
# Summenwert allein nicht von "keine Zeile vorhanden" zu unterscheiden.
team_architekt_stand() {
    local ledger_pfad="${1:-.budget-ledger}" plan_datei="${2:-$(team_plan_datei)}"
    local kaskade anzahl echt
    kaskade="$(team_architekt_kaskade "$plan_datei")"
    if [ -n "$kaskade" ]; then
        anzahl="$($TEAM_KOSTEN_TOOL ledger "$ledger_pfad" --rolle architekt --kaskade "$kaskade" --anzahl 2>/dev/null)"
        if [ -n "$anzahl" ] && [ "$anzahl" -gt 0 ] 2>/dev/null; then
            echt="$($TEAM_KOSTEN_TOOL ledger "$ledger_pfad" --rolle architekt --kaskade "$kaskade" 2>/dev/null)"
            printf '%s\techt\n' "$echt"
            return 0
        fi
    fi
    # BL-141: NICHT mehr "geschätzt" — der Wert ist Zeilen-Churn mal
    # Eichfaktor, misst also die Groesse des Diffs und nicht die Arbeit.
    # Im Feld lag er 35 % zu niedrig, und die alte Beschriftung liess
    # offen, woraus geschaetzt wurde. Gemessen wird mit
    # `kosten.py sitzung-messen`.
    printf '%s\tChurn-Proxy\n' "$(team_architekt_schaetzung)"
}

# team_architekt_schaetzung: A2-Live-Schaetzung der Architekt-Kosten (BL-28,
# Kaskade 13/Stufe 42) — der Architekt laeuft interaktiv ausserhalb von
# team_claude und schreibt keine total_cost_usd-JSONs. Proxy: Zeilen-Churn
# (git diff --numstat) ueber plans/** + CLAUDE.md seit dem letzten
# .budget-ledger-Commit, mal Eichfaktor (siehe team/tools/kosten.py). Bewusst
# eine GROBE Groessenordnung — Stufe 43 ersetzt sie beim Kaskaden-Abschluss
# durch den echten Konsolenwert (A1). Ohne bisherigen Ledger-Commit (frisches
# Repo) ist die Ausgabe 0.0000 statt eines Abbruchs.
team_architekt_schaetzung() {
    local ref
    ref="$(git log -1 --format=%H -- .budget-ledger 2>/dev/null)"
    if [ -z "$ref" ]; then
        echo "0.0000"
        return 0
    fi
    $TEAM_KOSTEN_TOOL architekt-schaetzung --since "$ref" 2>/dev/null \
        || echo "0.0000"
}

# --- Deckel-Empfehlung (Governance, Stufe 19) --------------------------------
# Der Architekt hinterlegt im Kopf des aktiven Kaskaden-Plans eine Zeile
# `BUDGET_EMPFEHLUNG_USD=<zahl>` (siehe
# plans/ralph-kaskade-6-budget-governance.md). vollautomatik.sh/halbautomatik.sh lesen sie hier
# zentral, statt das grep-Muster mehrfach zu duplizieren.

# team_plan_datei: aktive Plan-Datei aus der Zeiger-Datei .ralph-plan (eine
# Zeile, Pfad — Stufe 20 in plans/ralph-kaskade-6-budget-governance.md). Fehlt
# die Zeiger-Datei, ist die Ausgabe leer — der Aufrufer fällt auf seinen
# Default zurück (kein Abbruch hier; ralph.sh selbst bricht beim Bau ab).
team_plan_datei() {
    # Starterkit-Fix: `|| true` — sonst reisst der RC!=0 einer fehlenden
    # Zeiger-Datei den Aufrufer unter `set -e` weg, obwohl die Doku oben
    # ausdruecklich "kein Abbruch hier" zusagt (frisches Projekt = Normalfall).
    { head -n1 .ralph-plan 2>/dev/null || true; } | tr -d '[:space:]'
}

# team_plankopf_wert <schluessel> <plan-datei>: liest eine `<SCHLUESSEL>=<wert>`-
# Zeile aus dem Kopf einer Plan-Datei. Gemeinsame Ableitung von team_ralph_cap
# und team_budget_empfehlung — zwei Kopien derselben Pipeline waren schon
# einmal der eigentliche Befund (BL-151).
#
# BL-150: DER PLANKOPF IST MARKDOWN, NICHT KONFIGURATION.
#
# Die Anker standen auf `^[[:space:]]*` und lasen den Rest bis Zeilenende. Der
# Architekt legte den Plankopf aber als `**RALPH_CAP=5**` an — und das ist
# nicht sein Fehler: Der uebrige Plankopf (`**Plan:**`, `**Stufen:**`,
# `**Typ:**`) ist durchgehend fett, und sein Briefing verlangte die Zeilen,
# ohne ein Wort ueber Blank-Pflicht zu sagen. Ein Architekt, der sich exakt an
# sein Briefing haelt und dem Stil des eigenen Dokuments folgt, blockierte
# damit den Bau: Ralph stieg mit Exit 1 aus, team-status.sh zeigte `Cap ?`,
# und die Deckel-Anhebung der Vollautomatik bekam nie einen Wert — ein
# fehlender Wert, den niemand vermisst, weil sein Fehlen wie ein bewusst
# niedriger Deckel aussieht.
#
# Gefunden im Feld (Feld D) beim ALLERERSTEN Vollautomatik-Start. Das
# Zeitfenster ist genau ein Plan pro Projekt: Danach wird die Schreibweise vom
# ersten Plan abgeschrieben und der Fehler ist fuer immer unsichtbar.
#
# Geduldet wird deshalb die Auszeichnung, nicht der Sonderfall: fuehrende
# Auszeichnungs- und Aufzaehlungszeichen vor dem Schluessel, nachlaufende
# hinter dem Wert. Die Werte sind Zahlen, also kann alles davon spurlos weg.
team_plankopf_wert() {
    local schluessel="$1" plan="$2"
    [ -n "$plan" ] && [ -f "$plan" ] || return 0
    # `|| true` aus demselben Grund wie in team_architekt_kaskade (BL-111):
    # Eine Plandatei OHNE die Zeile ist der dokumentierte Normalfall, unter
    # `set -o pipefail` machte der leere grep daraus einen Abbruch.
    { grep -E "^[[:space:]*_\`>#+-]*${schluessel}=" "$plan" \
        | head -1 | cut -d= -f2 | tr -d '[:space:]*_`'; } || true
}

# team_ralph_cap [plan-datei]: liest RALPH_CAP aus der angegebenen (oder sonst
# der aktiven) Plan-Datei — dasselbe Muster wie team_budget_empfehlung. Fehlt
# Datei/Zeile, ist die Ausgabe leer.
team_ralph_cap() {
    team_plankopf_wert RALPH_CAP "${1:-$(team_plan_datei)}"
}

# team_budget_empfehlung [plan-datei]: liest BUDGET_EMPFEHLUNG_USD aus der
# angegebenen (oder sonst der aktiven) Plan-Datei. Fehlt Datei/Zeile, ist die
# Ausgabe leer — der Aufrufer fällt dann auf seinen Default zurück (kein
# Abbruch, keine Rateraterei).
team_budget_empfehlung() {
    team_plankopf_wert BUDGET_EMPFEHLUNG_USD "${1:-$(team_plan_datei)}"
}

# team_kontostand_gesamt: kumulierter Kontostand wie `team-status.sh --budget`
# ("Gesamt"-Zeile) = historische .budget-ledger-Basis + aktuelle lokale Logs
# (.ralph-logs + .team-logs).
team_kontostand_gesamt() {
    local basis abo api
    basis="$(team_ledger_summe)"
    IFS=$'\t' read -r abo api <<<"$(team_kosten_split .ralph-logs .team-logs)"
    # kein rohes ${…}-Interpolieren — BL-23/HM-17/HM-34/HM-42: Werte als
    # eigene sys.argv-Elemente uebergeben statt in den Python-Quelltext.
    "$TEAM_PYTHON" -c "import sys; print(f'{float(sys.argv[1]) + float(sys.argv[2]) + float(sys.argv[3]):.4f}')" "$basis" "$abo" "$api"
}

# team_logs_archivieren <dir>: verschiebt die aktuell in <dir> liegenden
# *.json-Rohlogs nach <dir>/archiv/ (bleiben lokal erhalten, zaehlen aber
# wegen des nicht-rekursiven glob() in team/tools/kosten.py nicht mehr in
# team_kosten_summe/team_kontostand_gesamt mit). AUFRUFEN, direkt NACHDEM
# eine neue .budget-ledger-Zeile fuer eine abgeschlossene Kaskade angehaengt
# wurde — sonst zaehlt der Kontostand dieselben Kosten doppelt (Ledger-Zeile
# + Rohlog), siehe BL-17. Ohne diesen Schritt bleibt die Ledger-Zeile die
# einzige Quelle, die je nach Log-Rotation ueberlebt; das war die urspruengliche
# Absicherungsidee hinter der Ledger (siehe Stufe 18,
# plans/ralph-kaskade-6-budget-governance.md) — bislang fehlte nur der
# Vollzug.
#
# BL-4/2026-08-01: Der regulaere Weg laeuft NICHT mehr hierueber. Sowohl die
# .team-logs als auch die .ralph-logs werden vom jeweiligen kosten.py-Verb
# (rollen-abschluss / ralph-abschluss) INTERN archiviert — im selben Prozess
# und auf demselben Snapshot, mit dem gezaehlt wurde (HM-39/AX-4-Fix; ein
# Zwei-Schritt-Ablauf aus Zaehlen hier und Archivieren dort war genau der
# Race). Diese Funktion bleibt als manuelles Werkzeug fuer Sonderfaelle
# bestehen — wer sie aufruft, archiviert OHNE zu ledgern und muss die
# passende Ledger-Zeile selbst verantworten.
team_logs_archivieren() {
    local dir="$1" archiv
    [ -d "$dir" ] || return 0
    archiv="$dir/archiv"
    mkdir -p "$archiv"
    find "$dir" -maxdepth 1 -name '*.json' -exec mv -t "$archiv" {} + 2>/dev/null
    return 0
}

# team_redteam_auftrag <grundauftrag> <stackneutraler-default>
#
# BL-172: Fokus und Grundauftrag VERKETTEN statt gegeneinander ausspielen.
#
# Bis hierher lautete die Kette `${TEAM_REDTEAM_FOCUS:-${GRUNDAUFTRAG:-...}}`
# — ein gesetzter Fokus ERSETZTE den Grundauftrag. Das kollidiert mit einer
# normativen Aussage der Regeldatei: Der Fokus wird bei JEDER Kaskade gesetzt
# und hat kein Verfallsdatum. Wird er pflichtgemaess immer gesetzt, greift der
# Grundauftrag NIE — er wirkte allein in dem Lauf, den es laut Regel nicht
# geben soll. `TEAM_REDTEAM_AUFTRAG_*` war damit strukturell tot.
#
# Die beiden tragen verschiedene Zeitraeume, und genau darum brauchen beide
# Platz: Der Grundauftrag traegt, was sich NICHT pro Kaskade aendert (etwa,
# dass in diesem Projekt personenbezogene Daten Minderjaehriger in einer
# lokalen Datenbank liegen), der Fokus das, was DIESE Kaskade beruehrt. Beides
# zugleich zu brauchen ist der Normalfall, nicht die Ausnahme.
#
# NUR HIER, NICHT BEI SCOPE_LINE: `TEAM_REDTEAM_FOCUS` steuert zwei Dinge, die
# auseinanderfallen — WO geprueft wird (SCOPE_LINE; dort ist Ersetzen richtig,
# ein Fokus schneidet den Umfang bewusst zu) und WORAUF geachtet wird (hier;
# dort ist Ersetzen falsch). Der Fix gehoert an die zweite Stelle.
#
# Der Schaden war leise: Der Sweep laeuft, findet etwas, und niemand sieht,
# dass die dauerhafte Kenntnis der Angriffsflaeche in diesem Lauf gar nicht im
# Prompt stand.
team_redteam_auftrag() {
    local grund="${1:-}" standard="${2:-}" fokus="${TEAM_REDTEAM_FOCUS:-}"
    local basis="${grund:-$standard}"
    if [ -n "$fokus" ]; then
        printf '%s\n\nSCHWERPUNKT DIESER KASKADE (zusaetzlich, nicht statt des Obigen): %s\n' \
               "$basis" "$fokus"
    else
        printf '%s\n' "$basis"
    fi
}

# team_resolve_budget_cap <aktueller-deckel> <user-hat-gesetzt:0|1> <empfehlung>
# Reine Rechenlogik der "nur anheben, nie senken"-Regel (Stakeholder-
# Entscheid 2, Stufe 19) — isoliert testbar ohne echten vollautomatik.sh-Lauf:
#   - hat der User TEAM_BUDGET_USD explizit gesetzt, gewinnt IMMER der
#     aktuelle Wert (auch wenn die Empfehlung höher läge);
#   - sonst gewinnt die Empfehlung, aber nur wenn sie größer als der aktuelle
#     (Default-)Deckel ist — eine niedrigere Empfehlung senkt nie.
# team_budget_cap_hinweis <gefahrener-deckel> <user-hat-gesetzt:0|1> <empfehlung>
#
# BL-185: Die GEGENRICHTUNG war stumm. Gemeldet wurde nur, wenn eine Empfehlung
# den Deckel ANHEBT — wird sie verworfen, stand die falsche Zahl nirgends.
#
# Im Feld: Der Plan empfahl 34, gefahren wurde mit 26 — dem Wert der
# VORKASKADE, der in derselben interaktiven Shell weiterlebte. Folgenlos blieb
# das nur, weil der Lauf mit 18,20 unter beiden Deckeln blieb; ein 8 USD zu
# tiefer Deckel bricht mitten in der Fixphase ab und rollt bezahlte Arbeit
# zurueck (BL-32-Muster).
#
# Der Mensch behaelt den Vorrang — er erfaehrt jetzt nur, dass er ihn ausuebt.
# Der Unterschied zwischen den beiden Werten ist ihre LEBENSDAUER:
# BUDGET_EMPFEHLUNG_USD haengt am Plan und altert mit ihm, TEAM_BUDGET_USD ist
# eine Umgebungsvariable ohne Verfallsdatum.
#
# Isoliert testbar, aus demselben Grund wie team_resolve_budget_cap: Ein
# Nachweis, der einen echten vollautomatik-Lauf braucht, wird nicht gefahren.
# Leere Ausgabe = nichts zu melden.
team_budget_cap_hinweis() {
    local gefahren="$1" user_gesetzt="$2" empfehlung="$3"
    [ -n "$empfehlung" ] || return 0
    [ "$empfehlung" != "$gefahren" ] || return 0
    echo "Deckel: Der Plan empfiehlt $empfehlung USD, gefahren wird mit $gefahren USD."
    if [ "$user_gesetzt" = "1" ]; then
        echo "  Grund: TEAM_BUDGET_USD ist gesetzt und hat Vorrang. Stammt der Wert noch aus einer frueheren Kaskade dieser Shell, jetzt korrigieren — die Empfehlung altert mit dem Plan, die Variable nicht."
    else
        echo "  Grund: Eine Empfehlung senkt den Deckel nie, sie hebt ihn nur an."
    fi
}

team_resolve_budget_cap() {
    local aktuell="$1" user_gesetzt="$2" empfehlung="$3"
    if [ "$user_gesetzt" = "1" ]; then
        echo "$aktuell"; return 0
    fi
    if [ -n "$empfehlung" ] \
       && "$TEAM_PYTHON" -c "import sys; sys.exit(0 if float(sys.argv[1]) > float(sys.argv[2]) else 1)" "$empfehlung" "$aktuell" 2>/dev/null; then
        echo "$empfehlung"; return 0
    fi
    echo "$aktuell"
}

# team_budget_check <kosten> <soft-limit> <label> [hard-limit]
#
# Zwei-Schwellen-Modell (Stakeholder-Entscheid 2026-07-12, HM-32).
# Rückgabe:
#   0 = ok (unter der Warnschwelle)
#   1 = Warnschwelle (80 % des Soft-Limits) erreicht — reiner Hinweis
#   2 = SOFT-Limit überschritten — deutlicher Hinweis; der Aufrufer entscheidet,
#       ob das ein weicher (weitermachen) oder harter (Abbruch) Fall ist:
#         * Frank/Axel behandeln 2 als WEICH (kein Rollback, Fix bleibt gültig),
#         * Ralph/Harry/Marv rufen OHNE hard-limit auf und behandeln 2 als HART.
#   3 = HARD-Limit überschritten — IMMER harter Abbruch (nur bei gesetztem
#       hard-limit > soft-limit möglich; die iterierenden Rollen Frank/Axel).
#
# Rückwärtskompatibel: Ohne <hard-limit> verhält sich die Funktion wie zuvor
# (0/1/2), 2 bleibt "Soft-Limit überschritten". Der neue Zustand 3 tritt nur
# auf, wenn ein sinnvolles hard-limit (> soft-limit) übergeben wird.
team_budget_check() {
    "$TEAM_PYTHON" -c '
import sys
cost = float(sys.argv[1])
soft = float(sys.argv[2])
label = sys.argv[3]
hard = float(sys.argv[4]) if len(sys.argv) > 4 and sys.argv[4] else None

if hard is not None and hard > soft and cost >= hard:
    print(f"HARD-CAP ÜBERSCHRITTEN ({label}): {cost:.2f} USD >= Hard-Cap {hard:.2f} USD — harter Abbruch.")
    sys.exit(3)
if cost >= soft:
    print(f"SOFT-CAP ÜBERSCHRITTEN ({label}): {cost:.2f} USD >= Soft-Cap {soft:.2f} USD.")
    sys.exit(2)
if cost >= 0.8 * soft:
    print(f"WARNSCHWELLE ({label}): {cost:.2f} USD >= 80 % von {soft:.2f} USD — Stakeholder informieren.")
    sys.exit(1)
sys.exit(0)
' "$1" "$2" "$3" "${4:-}"
}