nixos-config/docs/intent/builder-self-deploy-without-self-termination.md

# Intent: Builder-Deploy ohne Self-Termination und Doppelverarbeitung

## Ziel

Ein vom Board ausgelöster Builder darf beim automatischen Deployment auf
`blunix` weder seinen eigenen Prozess noch das Intent Board in einem
halbaktivierten Zustand zurücklassen. Nach Commit und Push muss das
Deployment außerhalb des Lebenszyklus von `agent-codex-builder.service`
ausgeführt werden und bei Unterbrechungen idempotent fortsetzbar sein.

## Beobachteter Produktionsfehler

Beim Lauf für
`board-keep-cards-visible-during-builder-stash` trat am 07.09.2026
folgender Ablauf auf:

1. Um 12:49:29 startete der Board-Job.
2. Der Builder erzeugte und pushte Commit `62c9ce2`.
3. Um 12:50:56 startete `deploy_blunix()` synchron
   `nixos-rebuild switch` innerhalb von `agent-codex-builder.service`.
4. Während der Aktivierung stoppte systemd um 12:51:31
   `board-agent-trigger.service` und anschließend den Builder-Prozess mit
   `SIGTERM` beziehungsweise Status 143.
5. Der SIGTERM-Handler legte denselben Job wieder in die Queue.
6. Der zweite Modelllauf erzeugte und pushte den zusätzlichen Commit
   `90ef0c8` und startete erneut ein Deployment.
7. Derselbe Self-Termination-Ablauf wiederholte sich um 12:53:27.
8. Erst ein dritter Lauf endete ohne weiteres Deployment, weil keine
   zusätzlichen Änderungen mehr entstanden waren.
9. `board-agent-trigger.service` blieb `inactive (dead)`, obwohl er
   deklarativ aktiviert und mit `Restart=always` konfiguriert ist.

Das war kein Python-Crash des Board-Servers. Der Prozess wurde im Rahmen
einer vom Builder selbst gestarteten, dann unterbrochenen NixOS-Aktivierung
geordnet mit `SIGTERM` beendet.

## Belegte Ursache

- `builder.py:deploy_blunix()` führt `sudo nixos-rebuild switch` synchron
  als Kindprozess des Builders aus.
- `agent-codex-builder.service` ist die Unit, aus der dieser Rebuild
  gestartet wird. Sobald die neue Konfiguration diese Unit während der
  Aktivierung stoppt, werden Builder und dessen Rebuild-Prozess gemeinsam
  beendet.
- `builder.py:_handle_sigterm()` requeued jeden aktiven Job unabhängig
  davon, ob Modelllauf, Commit und Push bereits erfolgreich abgeschlossen
  sind.
- `apply_commit()` führt Commit, Push und Deployment als einen nicht
  persistent phasierten Ablauf aus. Nach dem Requeue ist nicht erkennbar,
  welche Schritte bereits dauerhaft erfolgt sind.
- Der Retry startet deshalb erneut das Modell und kann einen zweiten
  Commit für denselben Intent erzeugen.
- Das unterbrochene `nixos-rebuild switch` hatte den Board-Dienst bereits
  gestoppt, erreichte dessen anschließenden Start aber nicht mehr.

## Umfang / Auftrag an den Builder

### Deployment entkoppeln

- `nixos-rebuild switch` nicht mehr synchron im Prozessbaum von
  `agent-codex-builder.service` ausführen.
- Einen separaten, eng begrenzten Deployment-Runner mit eigenem
  systemd-Lebenszyklus definieren. Er erhält einen persistierten Auftrag
  mit Commit-Hash, Host und Flake-Pfad und führt ausschließlich den
  freigegebenen `blunix`-Switch aus.
- Der Deployment-Runner muss eine Aktivierung seiner eigenen deklarativen
  Umgebung überleben. Seine Unit darf während des Switch nicht als Teil
  des Builder-Neustarts beendet werden.
- Builder und Board dürfen ein erfolgreich gestartetes Deployment nicht
  mit einem erfolgreich abgeschlossenen Deployment verwechseln.

### Persistente Zustandsmaschine

- Den Ablauf pro stabiler Board-Job-ID atomar mindestens in folgende
  Zustände aufteilen:
  `building -> committed -> deploying -> deployed` beziehungsweise
  `build_failed` oder `deploy_failed`.
- Commit-Hash und Push-Ergebnis unmittelbar nach ihrem Erfolg persistent
  speichern, bevor ein Deployment gestartet wird.
- Bei Neustart anhand dieses Zustands fortsetzen: Ein bereits committed
  Job darf weder erneut das Modell ausführen noch einen weiteren Commit
  erzeugen.
- Requeue im SIGTERM-Handler nur zulassen, solange nachweislich noch kein
  Commit für diesen Job gespeichert wurde. Nach `committed` darf höchstens
  der separate Deployment-Schritt erneut beziehungsweise kontrolliert
  fortgesetzt werden.
- Einen Idempotency-Key aus Board-Job-ID und Intent-Slug verwenden und
  doppelte Queue-/Completion-Einträge sicher deduplizieren.

### Fehler- und Retry-Verhalten

- Zwischen Build-, Push- und Deployment-Fehlern unterscheiden und den
  Status dem Board explizit melden.
- Ein gepushter Commit bei fehlgeschlagener oder partieller Aktivierung
  darf nicht als `deployed` gelten.
- Deployment-Retries begrenzen und mit Backoff versehen. Wiederholte
  Self-Termination, SIGTERM oder Aktivierungsfehler müssen in einem
  sichtbaren `deploy_failed`-Zustand enden statt den Modelllauf erneut zu
  starten.
- Der Completion-Watcher muss doppelte Records sowie bereits verarbeitete
  Commit-Hashes ignorieren.
- Nach einem fehlgeschlagenen Deployment muss das Board den Commit-Hash,
  den Deployment-Status und einen manuellen Recovery-Hinweis anzeigen.

### Betriebsstabilität

- Sicherstellen, dass `board-agent-trigger.service` nach erfolgreicher
  Aktivierung läuft.
- Wird eine Aktivierung unterbrochen, muss der Deployment-Runner den
  tatsächlichen Unit-Zustand prüfen und einen klaren Fehler melden. Kein
  stilles Zurücklassen eines deklarativ aktivierten, aber faktisch
  gestoppten Boards.
- Die Lösung darf keine allgemein nutzbare Root-Shell oder zusätzliche
  Modellberechtigung schaffen. Das Modell erzeugt weiterhin nur die
  Änderung; der eng definierte Wrapper führt den Deployment-Auftrag aus.

## Tests

- Unit-Test: SIGTERM vor dem Commit requeued genau einmal.
- Unit-Test: SIGTERM nach gespeichertem Commit startet das Modell nicht
  erneut und erzeugt keinen zweiten Commit.
- Unit-Test: Doppelte Queue- und Completion-Einträge werden anhand der
  Job-ID dedupliziert.
- Unit-Test: Ein gepushter Commit mit fehlgeschlagenem Switch endet in
  `deploy_failed`, nicht in `deployed` oder einem neuen Builder-Lauf.
- Integrationstest mit Fake-Deployment-Runner: Builder übergibt den
  Auftrag und kann beendet werden, ohne den Runner zu terminieren.
- Integrationstest: Der Runner meldet nach erfolgreicher Aktivierung den
  Zustand des Board-Dienstes und den aktivierten Systempfad zurück.
- Bestehende Board-, Builder-, Rollen- und Nix-Evaluierungstests müssen
  grün bleiben.

## Ausgeschlossen

- Kein erneuter Modelllauf als allgemeine Recovery-Strategie nach bereits
  erfolgreichem Commit.
- Kein Zurücksetzen oder Umschreiben der bereits gepushten Commits
  `62c9ce2` und `90ef0c8`.
- Keine Abschaffung der bestehenden Sandbox- und Rollenbegrenzungen.
- Kein automatisches Deployment auf andere Hosts als `blunix`.
- Keine imperative Aktivierung allein durch das Vorhandensein dieses
  Intent-Dokuments.

## Erfolgskriterien

- Ein Board-Job erzeugt auch bei einem Dienstneustart höchstens einen
  fachlichen Commit.
- Der Builder wird nicht durch seinen eigenen Deployment-Kindprozess in
  eine Requeue-Schleife gebracht.
- Ein unterbrochener Switch hinterlässt keinen fälschlich erfolgreichen
  Board-Status.
- Nach erfolgreichem Switch antwortet das Board wieder; nach einem Fehler
  zeigt es einen eindeutigen, persistenten Recovery-Status.
- Commit-/Push- und Deployment-Ergebnisse sind getrennt nachvollziehbar.
- Der aktuelle Produktionsfehler lässt sich mit einem Test reproduzieren,
  der vor der Änderung fehlschlägt und danach besteht.

## Aktueller Recovery-Hinweis

Zum Zeitpunkt der Diagnose ist `board-agent-trigger.service` auf `blunix`
seit 12:51:31 `inactive (dead)`. Eine manuelle Wiederinbetriebnahme oder
ein vollständiger erneuter `nixos-rebuild switch` ist eine separate
betriebliche Aktion und nicht durch diesen Intent freigegeben.