# Portabilität: SYSTEM
# Version: 1.0.0
# Zuletzt validiert: 2026-05-15
# Nächste Prüfung: 2026-11-15
# Ressourcen: [hub/scheduler.py, gui/daemon_service.py, scheduler_jobs, scheduler_runs]

SCHEDULER - Hintergrund-Jobs und Scheduler-Service
====================================================

STAND: 2026-02-28

Hinweis: `bach scheduler ...` ist der neue Name für den Scheduler.
Der alte Befehl `bach daemon ...` ist weiterhin als Alias verfügbar.

WICHTIGE POLICY
---------------
**ALLE SCHEDULER-JOBS SIND STANDARDMÄßIG DEAKTIVIERT.**

Grund: Automatische Prozesse können mit aktiven Chat-Sessions
und dem Prompt Generator kollidieren. Jobs werden nur manuell
aktiviert wenn benötigt.

Der Scheduler pausiert automatisch OneDrive-Sync während des Betriebs
um Sync-Konflikte zu vermeiden.

Siehe: docs/CONCEPT_daemon_policy.md

CLI-BEFEHLE (bach scheduler)
-----------------------------

  jobs              Alle Jobs anzeigen
  status            Scheduler-Status
  status --json     Scheduler-Status als JSON
  doctor            Scheduler-Preflight und Recovery-Hinweise
  doctor --json     Scheduler-Preflight als JSON
  start [--bg]      Scheduler-Service starten (--bg für Hintergrund)
  stop              Scheduler-Service stoppen
  run <ID>          Einzelnen Job manuell ausführen
  logs [N]          Letzte Log-Einträge anzeigen (Standard: 20)
  jobs --json       Scheduler-Jobs mit berechnetem Status als JSON

SESSION-SYSTEM
--------------

  session start [--profile NAME]   Session-Scheduler starten
  session stop                     Session-Scheduler stoppen
  session status                   Session-Status anzeigen
  session status --json            Session-Status als JSON
  session doctor                   Session-Preflight und Recovery-Hinweise
  session doctor --json            Session-Preflight als JSON
  session pause [--profile NAME] [Grund] Trigger für Profil pausieren
  session resume [--profile NAME]         Pause für Profil aufheben
  session steer [--profile NAME] "Text"   Steuerhinweis für die nächste Session vormerken
  session clear-steer [--profile NAME]    Steuerhinweise für Profil löschen
  session trigger [--profile NAME] Session manuell auslösen
  session profiles                 Verfügbare Profile auflisten

  Beispiel mit Dry-Run:
    bach scheduler session trigger --profile wartung --dry-run

  Beispiel mit Operator-Steuerung:
    bach scheduler session steer --profile ati "Bitte heute nur Health-Checks und Docs anfassen."
    bach scheduler session status --json

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

  interval    Wiederholung nach Zeitspanne (z.B. 24h, 30m)
  cron        Zeitplan-basiert (z.B. "0 2 * * *" = täglich 2 Uhr)
  event       Event-basierter Trigger (extern ausgelöst)
  manual      Nur manuell ausführbar
  chain       Verkettete Job-Ausführung (Chain-System)

Der Scheduler prüft automatisch alle 5 Minuten auf fällige Recurring Tasks.

VERFÜGBARE JOBS (alle standardmäßig AUS)
-------------------------------------------
Hinweis: Job-Liste ist dynamisch. Aktuelle Jobs via: bach scheduler jobs

Beispiel-Jobs:
  ID  Name                      Schedule    Funktion
  --  ------------------------  ----------  --------------------------------
  1   scanner                   60m         Software-Ordner nach Tasks scannen
  2   backup                    24h         Automatisches Backup
  3   inbox-scan                30m         Inbox-Ordner verarbeiten
  4   consolidate-weight        24h         Memory-Gewichtungen (Decay)
  5   consolidate-archive       24h         Alte Einträge archivieren
  6   consolidate-index         7d          Help/Wiki Index aktualisieren
  7   consolidate-compress      24h         Sessions komprimieren
  8   consolidate-we            7d          Woechentliche Konsolidierung
  9   Nightly Maintenance       cron 0 2    Naechliche Wartungskette
  10  Weekly Backup             cron 0 3 0  Woechentliches Backup

Connector-Jobs (v2.0, via bach connector setup-scheduler):
  --  connector_poll_and_route  2m          Connectors pollen + Inbox-Routing
  --  connector_dispatch        1m          Ausgehende Queue mit Retry versenden

JOB MANUELL AUSFÜHREN
----------------------
Empfohlene Methode statt automatischem Scheduler:

  # Job einmalig ausführen
  bach scheduler run 1         # Scanner einmal laufen lassen
  bach scheduler run 2         # Backup einmal erstellen
  bach scheduler jobs --json   # Jobs für externe Tools/Agenten

  # Oder direkt den Befehl
  bach scan run                # Scanner
  bach backup create           # Backup
  bach consolidate run         # Konsolidierung

GUI
---
  http://127.0.0.1:8000/scheduler    Scheduler-Dashboard

  - Jobs aktivieren/deaktivieren
  - Manuell ausführen
  - Letzte Ausführungen sehen

ALIAS: bach daemon ...
----------------------
Der frueherer Befehlsname `bach daemon` ist weiterhin als Alias
für Rückwaertskompatibilitaet verfügbar. Beide Befehlsformen
sind aequivalent:

  bach daemon jobs      ==  bach scheduler jobs
  bach daemon status    ==  bach scheduler status
  bach daemon start     ==  bach scheduler start

SIEHE AUCH
----------
  bach --help daemon           Ältere Dokumentation (Alias)
  docs/CONCEPT_daemon_policy.md    Scheduler-Richtlinien
  bach --help connector        Connector-System (Queue, Retry)
  bach --help maintain         Wartungs-Tools
  bach --help backup           Backup-System
  bach --help consolidation    Memory-Konsolidierung
