# Intent: Codex-Nutzungsquelle im Board-Usage-Endpunkt

## Ziel

Die in der Vorkarte `board-usage-endpoint-claude` bereits vorgesehene,
aber leere Codex-Seite von `GET /api/board/usage` mit echten Werten
befüllen: verbrauchte Prozent im 5-Stunden- und im Wochenfenster der
geteilten interaktiven `drone`-Codex-Identität.

## Umfang

- In `hosts/blunix/localServices/board-agent/trigger.py`:
  - `codex app-server` als kurzlebigen Kindprozess starten und über
    dessen Stdio-JSON-RPC-Protokoll zuerst `initialize`, danach
    `account/rateLimits/read` senden.
  - Aus der Antwort `rateLimits.primary.usedPercent` (5-Stunden-Fenster)
    und `rateLimits.secondary.usedPercent` (Wochenfenster) sowie die
    jeweiligen `resetsAt`-Zeitstempel auslesen und in die bestehenden
    `codex`-Felder der Antwort schreiben. Der Antwortvertrag der
    Vorkarte bleibt unverändert.
  - Kurzes Timeout (wenige Sekunden) und garantiertes Aufräumen des
    Kindprozesses (auch bei Timeout) sicherstellen.
  - Vollständige Fehlerisolierung: jeder Fehler führt nur zu `null` auf
    der Codex-Seite; die Claude-Seite bleibt unabhängig nutzbar.
- In `hosts/blunix/localServices/board-agent.nix`:
  - Ein eigenes, dauerhaftes und beschreibbares Probe-`CODEX_HOME`
    unterhalb des bestehenden `stateDir` (`/var/lib/board-agent`)
    definieren und dem Trigger-Service über eine Umgebungsvariable
    bekannt machen. Es ist bewusst getrennt vom bestehenden
    `codexHome` der isolierten Builder-Identität.
  - `ProtectHome = "read-only"` bleibt unverändert; es wird kein
    Sandbox-Downgrade vorgenommen.
- `auth.json` wird vor *jeder* Abfrage frisch aus
  `/home/drone/.codex/auth.json` in das Probe-`CODEX_HOME` kopiert (nicht
  nur einmalig beim Servicestart wie beim bestehenden
  `prepareCodexHome`-Muster), damit ein rotiertes Token ohne Neustart des
  dauerhaft laufenden Dienstes wirksam wird.
- Tests in `test_board_agent.py` mit gefälschtem Subprozess:
  Erfolgsfall, fehlendes Binary, Timeout, kaputte/unerwartete
  RPC-Antwort, frisches Kopieren von `auth.json`.
- Kurze Ergänzung in `README.md` zum Probe-`CODEX_HOME` und zur
  Codex-Quelle.

## Explizit ausgeschlossen

- Keine Änderung am Antwortvertrag oder an der Claude-Seite des
  Endpunkts.
- Keine UI-Änderung in `board.html` (eigene Folgekarte).
- Kein dauerhaft laufender `codex app-server`-Dienst; pro Abfrage ein
  kurzlebiger Kindprozess.
- Kein Abschwächen von `ProtectHome` oder anderer Sandbox-Optionen.
- Kein Verlauf/Graph, keine Alarmierung, keine Aufschlüsselung pro Rolle.

## Annahmen

- `codex app-server` beantwortet `account/rateLimits/read` nach einem
  `initialize`-Handshake nicht-interaktiv und in deutlich unter einer
  Sekunde; eine laufende Instanz ist nicht nötig.
- `codex app-server` schreibt beim Start breit in sein `CODEX_HOME`
  (SQLite-Dateien, Caches), weshalb ein eigenes beschreibbares
  Probe-Verzeichnis nötig ist.
- Die Kopierkosten von `auth.json` (wenige KB) sind bei einem
  Poll-Intervall von rund 60 Sekunden vernachlässigbar.

## Offene Risiken

- `codex app-server` ist als "[experimental]" markiert; Methodenname und
  Antwortstruktur können sich ändern. Die Fehlerisolierung ist deshalb
  verpflichtend.
- Der Kindprozess darf bei Fehlern nicht als Zombie zurückbleiben oder
  den Request blockieren.

## Erfolgskriterien

- `GET /api/board/usage` liefert echte Codex-Prozentwerte, bei Fehlern
  eine Leerdarstellung, und die Claude-Seite bleibt davon unberührt.
- Nix-Auswertung der geänderten `board-agent.nix` und der Testlauf von
  `test_board_agent.py` sind fehlerfrei.
- Keine Secrets oder Rohdaten verlassen den Endpunkt.