# Portabilität: UNIVERSAL
# Version: 1.0.1
# Zuletzt validiert: 2026-05-17
# Nächste Prüfung: 2026-08-17

BACH WARTUNG (System-Jobs)
==========================

Der Wartungs-Handler führt automatisch geplante System-Jobs aus - z.B. Backups,
Token-Checks, Datenbereinigung oder eigene Scripts.

HANDLER:  system/hub/scheduler.py (ehemals: daemon.py)
SERVICE:  system/gui/daemon_service.py + DB (scheduler_jobs, scheduler_runs)
GUI:      /daemon (http://localhost:8000/daemon)

Hinweis: "bach daemon ..." und "bach scheduler ..." sind Aliases.


BEFEHLE
-------

  bach daemon start          Wartungs-Daemon im Vordergrund starten (Ctrl+C beendet)
  bach daemon start --bg     Wartungs-Daemon im Hintergrund starten
  bach daemon stop           Laufenden Daemon stoppen
  bach daemon status         Status und letzte Laeufe anzeigen
  bach daemon jobs           Alle definierten Jobs auflisten
  bach daemon run <ID>       Job manuell ausführen
  bach daemon logs [N]       Letzte N Log-Zeilen anzeigen (Standard: 20)


SESSION-BEFEHLE (Session-Daemon für automatische Claude-Sessions)
------------------------------------------------------------------

  bach daemon session start [--profile NAME]   Session-Daemon starten
  bach daemon session stop                     Session-Daemon stoppen
  bach daemon session status                   Session-Status anzeigen
  bach daemon session trigger [--profile NAME] Session manuell auslösen
  bach daemon session profiles                 Verfügbare Profile auflisten


JOB-TYPEN
---------

  interval    Periodisch (z.B. "30m", "1h", "24h")
  cron        Cron-Ausdruck (z.B. "0 3 * * *" = täglich 03:00)
  manual      Nur manuell ausführbar
  chain       Chain-Ausführung (job.command = chain_id)
  event       Event-basiert (TODO)


BEISPIEL-JOBS
-------------

  Name           Typ        Schedule    Beschreibung
  ----------------------------------------------------------------
  backup-daily   interval   24h         Tägliches Backup erstellen
  token-check    interval   30m         Token-Verbrauch prüfen
  cleanup        cron       0 4 * * *   Alte Logs bereinigen


JOBS ERSTELLEN
--------------

Via GUI-Dashboard (http://localhost:8000/daemon):
  - Wartung > "Neuer Job"

Via API:
  POST /api/daemon/jobs
  {
    "name": "mein-job",
    "job_type": "interval",
    "schedule": "1h",
    "command": "python tools/mein_script.py"
  }


LOG-DATEIEN
-----------

  data/logs/daemon.log                     Wartungs-Aktivitäten
  data/logs/session_daemon.log             Session-Aktivitäten
  data/daemon.pid                          PID-Datei (wenn laufend)
  hub/_services/daemon/daemon.pid          Session-Daemon PID


TECHNISCHE DETAILS
------------------

- Jobs werden aus bach.db geladen (Tabelle: scheduler_jobs)
- Ausführungen in scheduler_runs protokolliert
- Timeout pro Job konfigurierbar (Standard: 300s)
- Bei Fehler optional Retry (max_retries konfigurierbar)
- Alle 5 Minuten werden Jobs neu geladen
- EIGENER DAEMON-PROZESS (Python Interval-Loop)
- OneDrive wird während Daemon-Betrieb pausiert (Windows)
- Verhindert Sync-Konflikte bei Datei-Operationen
- Integration mit Recurring Tasks (Check alle 5 Min)

Optional: pip install croniter (für erweiterte Cron-Ausdrücke)


ABGRENZUNG: DREI HANDLER-SYSTEME
--------------------------------

  ┌─────────────────────────────────────────────────────────────────┐
  │  WARTUNG                                                        │
  ├─────────────────────────────────────────────────────────────────┤
  │  Führt Shell/Python-Befehle AUS                                │
  │  Zeitgesteuert (cron/interval)                                  │
  │  Ohne Claude-Beteiligung                                        │
  │  Handler:  system/hub/daemon.py                                  │
  │  Service:  system/gui/daemon_service.py + DB                    │
  │  GUI:      /daemon (vorhanden)                                  │
  │  Daemon:   JA (eigener Prozess)                                 │
  └─────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────┐
  │  RECURRING                                                      │
  ├─────────────────────────────────────────────────────────────────┤
  │  Erstellt TASKS als Erinnerungen                                │
  │  Intervall-basiert (Tage)                                       │
  │  Für Claude/User zur Bearbeitung                               │
  │  Handler:  system/hub/recurring.py                              │
  │  Service:  system/hub/_services/recurring/                      │
  │  GUI:      KEINE (nur CLI + in /daemon integriert)              │
  │  Daemon:   NEIN (Check bei Aufruf)                              │
  └─────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────┐
  │  PROMPT-GENERATOR                                               │
  ├─────────────────────────────────────────────────────────────────┤
  │  Sendet Prompts an Claude-Sessions                              │
  │  Manuell oder automatisiert                                     │
  │  Vorlagen-System mit Editor                                     │
  │  Handler:  (in Entwicklung)                                     │
  │  Service:  system/hub/_services/prompt_generator/                │
  │  GUI:      /prompt-generator (geplant)                          │
  │  Daemon:   JA (session_daemon.py)                               │
  └─────────────────────────────────────────────────────────────────┘

  Beispiel Wartung:          "bach backup create" täglich um 03:00
  Beispiel Recurring:        "Self-Check fällig" -> Task für Claude
  Beispiel Prompt-Generator: Prompt alle 30 Min an ATI Agent senden


SIEHE AUCH
----------

  bach gui start              Web-Dashboard mit Job-Verwaltung
  bach --help backup          Backup-System
  bach --help dirscan            Directory Scanner
  bach --help recurring       Wiederkehrende Tasks (keine GUI)
  bach --help prompt-generator  Prompt-Management (GUI geplant)
