# Portability: SYSTEM
# Last validated: 2026-05-17
# Next review: 2027-05-17
# Next exam: 2026-11-15
# Resources: [hub/scheduler.py, gui/daemon_service.py, scheduler_jobs, scheduler_runs]

SCHEDULER - background jobs and scheduler service
----------------------------------------------------

DATE: 2026-02-28

Note: `bach scheduler ...` is the new name for the scheduler.
The old command `bach daemon ...` is still available as an alias.

IMPORTANT POLICY
---------------
**ALL SCHEDULER JOBS ARE DISABLED BY DEFAULT.**

Reason: Automatic processes can work with active chat sessions
and the prompt generator collide. Jobs are only manual
activated if required.

The scheduler automatically pauses OneDrive sync during operation
to avoid sync conflicts.

See: docs/CONCEPT_daemon_policy.md

CLI COMMANDS (bach scheduler)
-----------------------------

  jobs Show all jobs
  status Scheduler status
  status --json Scheduler status as JSON
  doctor Scheduler preflight and recovery notes
  doctor --json Scheduler preflight as JSON
  start [--bg] Start scheduler service (--bg for background)
  stop Stop scheduler service
  run <ID> Run individual jobs manually
  logs [N] Show latest log entries (default: 20)
  jobs --json Scheduler jobs with calculated status as JSON

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

  session start [--profile NAME] Start session scheduler
  session stop Stop session scheduler
  session status Show session status
  session status --json Session status as JSON
  session doctor Session preflight and recovery notes
  session doctor --json Session preflight as JSON
  session pause [--profile NAME] [Reason] Pause trigger for profile
  session resume [--profile NAME] Unpause profile
  session steer [--profile NAME] "Text" Save control information for the next session
  session clear-steer [--profile NAME] Clear profile control instructions
  session trigger [--profile NAME] Trigger session manually
  session profiles List available profiles

  Example with dry run:
    bach scheduler session trigger --profile wartung --dry-run

  Example with operator control:
    bach scheduler session steer --profile ati "Bitte heute nur Health-Checks und Docs anfassen."
    bach scheduler session status --json

JOB TYPES
---------

  interval Repetition after a period of time (e.g. 24h, 30m)
  cron schedule-based (e.g. "0 2 * * *" = 2 a.m. daily)
  event Event-based trigger (triggered externally)
  manual Can only be executed manually
  chain Chained job execution (chain system)

The scheduler automatically checks every 5 minutes for due recurring tasks.

AVAILABLE JOBS (all OFF by default)
-------------------------------------------
Note: Job list is dynamic. Current jobs via: bach scheduler jobs

Example jobs:
  ID Name Schedule function
  -- ----------------------- --------- --------------------------------
  1 scanner 60m Scan software folders for tasks
  2 backup 24h Automatic backup
  3 inbox-scan process 30m inbox folders
  4 consolidate-weight 24h memory weights (decay)
  5 consolidate-archive 24h Archive old entries
  6 consolidate-index 7d Help/Wiki Update index
  7 consolidate-compress 24h compress sessions
  8 consolidate-we 7d Weekly consolidation
  9 Nightly Maintenance cron 0 2 Nightly maintenance chain
  10 Weekly Backup cron 0 3 0 Weekly backup

Connector jobs (v2.0, via bach connector setup-scheduler):
  -- connector_poll_and_route 2m connectors pollen + inbox routing
  -- connector_dispatch 1m Send outgoing queue with retry

EXECUTE JOB MANUALLY
----------------------
Recommended method instead of automatic scheduler:

  # Run job once
  bach scheduler run 1         # Run scanner once
  bach scheduler run 2         # Create backup once
  bach scheduler jobs --json   # Jobs for external tools/agents

  # Or directly the command
  bach scan run                # Scanner
  bach backup create           # Backup
  bach consolidate run         # Consolidation

GUI
---
  http://127.0.0.1:8000/scheduler scheduler dashboard

  - Enable/disable jobs
  - Run manually
  - See latest executions

ALIAS: bach daemon ...
----------------------
The previous command name `bach daemon` is still an alias
available for backward compatibility. Both forms of command
are equivalent:

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

SEE ALSO
----------
  bach --help daemon           Older documentation (alias)
docs/CONCEPT_daemon_policy.md Scheduler policies
  bach --help connector        Connector system (queue, retry)
  bach --help maintain         Maintenance tools
  bach --help backup           Backup system
  bach --help consolidation    Memory consolidation
