Monitoring controller

Coordinates monitoring sessions, worker threads, scheduled lifecycle events, startup housekeeping, and report access.

Scheduling helpers

def seconds_until_midnight(
    now:NoneType=None
):

Return the number of seconds from now until the next midnight.

def MonitorController(
    debug:bool=True
):

Own monitoring session state, worker threads, timers, and UI callbacks.

def start_monitoring():

Start a new session and its process and foreground monitoring threads.

def stop_monitoring(
    stop_reason:str='None'
):

Stop active workers, close the session, and record its stop reason.

def is_running():

Return whether a monitoring session is currently running.

def run_startup_housekeeping():

Close stale sessions and delete data older than the retention cutoff.

def generate_current_session_stats():

Build report data for the active session, or return {} when none exists.

def generate_last_report_data():

Build report data for the latest completed session, or return {}.

def is_paused():

Return whether the configured pause end time is still in the future.

def pause_for(
    minutes:NoneType=None
):

Stop active monitoring, schedule automatic resume, and return the pause end time.

def resume_now():

Cancel any pending resume timer and resume monitoring immediately.

stop_monitoring() uses the literal string "None" as its default stop_reason. Confirm whether this should remain "None", become Python None, or use a defined reason such as "unknown".
Constructing MonitorController immediately runs database housekeeping. Confirm that this constructor side effect is intentional.
resume_now() calls _auto_resume() even when no pause is active. If the controller was manually stopped, this starts a new monitoring session and emits resume callbacks. Confirm that this is the intended distinction between “resume” and “start”.
The callback contracts are implicit: on_notify is called with one string, while on_state_change is called without arguments. They may also be invoked from timer threads. Confirm that the tray layer safely transfers any Tkinter work to the Tk main thread.
start_monitoring() does not reset session_stop, so while a later session is running that attribute may still contain the previous session’s stop time. Confirm whether consumers rely on it being None during an active session.