nixos-config/docs/intent/agent-codex-state-sqlite-migration.md

# Intent: agent-codex-State (Sessions, Freigaben) von Dateien auf SQLite umstellen

**Status:** Phase 1 umgesetzt, verifiziert (53 Tests, Smoke-Test gegen
den echten `AGENT_DB_PATH`) und auf blunix deployed (2026-09-05, Commit
fdf3ea9). Phase 2 (Freigabe-Workflows) weiterhin offen, eigener Auftrag.

## Ziel

Auslöser: ein per Tailscale zugesandtes PDF ("Bash versus SQL im
Agentic Workflow") mit der Kernthese, dass strukturierter Agenten-Zustand
(Memory, Freigaben, Relationships) deklarativ in SQL gehört, während
Bash/Shell die Ebene für offene Computerarbeit (Filesystem, Git, Prozesse)
bleibt. Eine Repo-Recherche hat `hosts/blunix/localServices/agent-codex/`
als konkreten, akuten Kandidaten identifiziert: der XMPP-Codex-Agent
(`agent@`/`builder@bot.0ff.space`) verwaltet Sessions, Erstkontakt-Marker
und beide Freigabe-Workflows (`/annehmen`+`/ablehnen`,
`/freigeben`+`/verwerfen`) komplett als JSON-Dateien in
Verzeichnissen — das im PDF beschriebene Muster ohne Schema,
Transaktionen oder Query-Planner. Das README dokumentiert bereits einen
daraus resultierenden Vorfall (30.07.2026): ein `nixos-rebuild switch`
killte per SIGTERM einen laufenden Builder-Job, der Datensatz blieb
verwaist in `builder-processing/` liegen, bis nachträglich ein
SIGTERM-Handler ergänzt wurde. Ziel dieses Auftrags: die
Freigabe-/Sitzungs-Datensätze in eine lokale SQLite-Datenbank
überführen, damit solche Zustände strukturell konsistent bleiben und per
SQL statt `ls`/`cat` einsehbar sind — ohne die Job-Queue- und
Ausführungsebene (pfadgetriggerte systemd-Services, Codex-Aufrufe,
Git-Operationen) anzutasten, die laut derselben PDF-Logik zu Recht
imperativ/dateibasiert bleibt.

## Umfang

Zwei Phasen, jede mit eigenem Abschluss und eigenem Deploy:

**Phase 1 — Sessions und Erstkontakt-Marker:**
- Neues gemeinsames Modul `hosts/blunix/localServices/agent-codex/db.py`
  (Python-Stdlib `sqlite3`, keine neue Abhängigkeit) mit Tabellen
  `sessions` und `introductions` (Spalten: `role`, `sender`,
  `session_id`/`introduced_at`, `updated_at`; Primärschlüssel
  `(role, sender)`).
- `worker.py` und `builder.py`: `session_path()`/`sender_marker()` und die
  zugehörigen Lese-/Schreibfunktionen (`load_session`, `save_session`,
  `reset_session`, `add_first_reply_notice`, `mark_introduced`) auf
  `db.py` umstellen.
- `agent-codex.nix`: neue `AGENT_DB_PATH`-Umgebungsvariable
  (`${stateDir}/agent.db`) in `commonEnvironment`.
- `test_agent_codex.py`: betroffene Tests auf eine temporäre
  SQLite-Datei pro Testfall umstellen statt Tempdir-Dateien.

**Phase 2 — Freigabe-Workflows (`builder-start-pending/`,
`builder-pending/`):**
- Tabellen `start_pending` (job_id, sender, requested_by, body,
  created_at) und `pending_approval`/`pending_approval_repo`
  (job_id, requested_by, commit_message, created_at bzw.
  job_id, repo_dir) in `db.py`.
- `builder.py`: `save_start_pending`/`load_start_pending`/
  `delete_start_pending` sowie `save_pending_approval`/
  `load_pending_approval`/`delete_pending_approval` auf `db.py`
  umstellen. `find_stash_ref()` (Suche nach dem Marker-String in `git
  stash list`) bleibt unverändert — der Datensatz selbst wird nur
  abfragbar statt nur als Datei lesbar.

Beide Phasen jeweils mit dem üblichen blunix-Verify-Pfad (`nix flake
check` → `drvPath`-Eval → Build → `diff-closures` → `dry-activate` →
`switch`) und dem bestehenden manuellen Vorsichtsschritt aus dem
README (`systemctl is-active agent-codex-builder.service` vor dem
Switch prüfen).

## Explizit ausgeschlossen

- Die Job-Queue selbst (`inbox/`, `processing/`, `failed/` und die
  `builder-*`-Pendants) bleibt dateibasiert — sie ist die
  pfadgetriggerte (`systemd.paths`, `PathExistsGlob`) Ausführungsebene,
  keine abzufragende Business-Struktur; eine Umstellung würde laut PDF
  ("SQL -> Queue -> Shell") nur eine schlechtere Shell hinter SQL
  verstecken.
- Kein automatisiertes Migrationsskript für bestehende
  Datei-Datensätze. Sessions/Introductions sind verlustlos ersetzbar
  (nächste Nachricht startet nötigenfalls neu); offene
  `start_pending`/`pending_approval`-Vorgänge werden vor dem jeweiligen
  Deploy im Chat manuell aufgelöst (`/annehmen`, `/ablehnen`,
  `/freigeben`, `/verwerfen`).
- Kein `job_events`-Audit-Log (PDF-Muster "Event Sourcing") — separat
  vormerken, nicht Teil dieses Auftrags.
- Keine Änderung an `find_stash_ref()`s String-Matching-Mechanik selbst
  (robusterer Stash-Bezug über Commit-Hash statt Marker-Text) — eigener,
  späterer Auftrag, falls gewünscht.
- Kein Eingriff in `hosts/pinix/localServices/webhook.nix` oder
  Vikunja/GoToSocial — laut Recherche bereits korrekt (Bash-only bzw.
  bereits SQL-gestützt).

## Annahmen

- Beide Rollen (`agent-codex-worker`, `agent-codex-builder`) laufen als
  `Type = "oneshot"`-Services, die von ihrem jeweiligen `systemd.paths`
  serialisiert getriggert werden -- pro Rolle läuft nie mehr als ein
  Prozess gleichzeitig gegen `agent.db`, SQLites Single-Writer-Grenze
  ist damit unkritisch.
- Eine gemeinsame Datei `agent.db` für beide Rollen (mit `role`-Spalte)
  ist einfacher zu betreiben als zwei getrennte Dateien, ohne die
  bestehende Rollentrennung (getrennte Queues, getrennte
  Sender-Allowlists) aufzuweichen -- die Trennung bleibt rein logisch
  über die `role`-Spalte bestehen.

## Offene Risiken

- Falls zum Deploy-Zeitpunkt tatsächlich ein `start_pending`- oder
  `pending_approval`-Vorgang offen ist und nicht rechtzeitig manuell
  aufgelöst wird, geht dieser Datensatz beim Umschalten verloren (die
  zugehörigen `git stash`-Einträge selbst bleiben aber erhalten und sind
  über `git stash list` von Hand wiederfindbar).
- Unklar, ob `sqlite3` unter dem bestehenden `systemd`-Sandboxing
  (`ProtectSystem = "strict"`, `ReadWritePaths`) ohne weitere Anpassung
  in `${stateDir}` schreiben kann -- vermutlich ja, da `StateDirectory`
  bereits schreibbar ist, aber nicht verifiziert.

## Erfolgskriterien

- Phase 1: `nix flake check` und Build von blunix erfolgreich;
  `test_agent_codex.py` grün; nach Deploy zeigt eine neue
  Chat-Nachricht weiterhin korrektes Sitzungsverhalten
  (Fortsetzung/`/neu`) und die Erstkontakt-Notiz erscheint nur beim
  ersten Kontakt -- beides jetzt aus `agent.db` gelesen, nicht mehr aus
  `sessions/`/`senders/`.
- Phase 2: ein kompletter `/annehmen`- und ein kompletter
  `/freigeben`-Durchlauf funktionieren unverändert aus Nutzersicht;
  `sqlite3 agent.db 'SELECT * FROM pending_approval'` zeigt einen
  offenen Vorgang korrekt an, solange er nicht abgeschlossen ist.
- Alte Zustandsverzeichnisse (`sessions/`, `builder-sessions/`,
  `senders/`, `builder-senders/`, `builder-start-pending/`,
  `builder-pending/`) sind nach beiden Phasen in einem Folgecommit
  entfernt.