trusty-mpm 1.8.2

//! Supervisor configuration: poll cadence, auto-resume policy, idle classification.
//!
//! Why: the unattended supervisor must run with no live caller for hours, so its
//! behavior has to be driven entirely by *seed configuration* an operator sets
//! once (env vars / a struct) rather than by interactive prompts. Centralizing
//! the knobs in one struct keeps the env-var contract (`TRUSTY_MPM_AUTO_RESUME`,
//! `TRUSTY_MPM_SUPERVISOR_INTERVAL`, …) auditable and gives the loop a single
//! immutable config value to read each tick.
//! What: defines [`SupervisorConfig`] with the poll interval, the auto-resume
//! gate, and the idle-classification toggle; plus [`SupervisorConfig::from_env`]
//! which reads the documented env vars with safe defaults. #6288 removed the
//! metrics bind address: the supervisor publishes to a file instead of binding
//! `127.0.0.1:7881`.
//! Test: `config_defaults`, `auto_resume_env_parsing`, `interval_env_parsing`,
//! `classify_idle_env_parsing` in `super::tests`.

use std::time::Duration;

/// Environment variable that gates auto-resume of `stopped` sessions.
///
/// Why: auto-resume is the supervisor's most consequential action — it brings a
/// runtime back without a human present — so it MUST be opt-in via an explicit
/// env var, matching the existing reconcile-on-boot gate in `DaemonState`.
/// What: the canonical name an operator sets to `1` / `true` to enable resume.
/// Test: `auto_resume_env_parsing`.
pub const ENV_AUTO_RESUME: &str = "TRUSTY_MPM_AUTO_RESUME";

/// Environment variable that overrides the poll interval (in seconds).
///
/// Why: overnight fleets want a slow cadence (cheap); active debugging wants a
/// fast one. An env override lets operators tune without recompiling.
/// What: parsed as `u64` seconds; invalid / absent values fall back to the default.
/// Test: `interval_env_parsing`.
pub const ENV_INTERVAL_SECS: &str = "TRUSTY_MPM_SUPERVISOR_INTERVAL";

/// Environment variable that selects the LLM model for idle classification.
///
/// Why: idle-session activity classification calls an LLM through OpenRouter;
/// the model is operator-tunable (cost vs. accuracy) and must be read from one
/// named constant so the env contract is auditable alongside the other `ENV_*`
/// knobs rather than buried as a string literal at the read site.
/// What: the variable an operator sets to override the classification model;
/// when absent the supervisor falls back to [`DEFAULT_LLM_MODEL`].
/// Test: `default_llm_model_is_documented` asserts the constant + default pair.
/// #4427: aliased to the classifier's own key so the supervisor and the daemon
/// can never disagree about which variable configures the model.
pub const ENV_LLM_MODEL: &str = crate::activity::classifier::CLASSIFIER_MODEL_ENV;

/// Default LLM model used for idle classification when [`ENV_LLM_MODEL`] is unset.
///
/// Why: a cheap, capable default keeps token spend low for the common case while
/// still letting operators opt into a stronger model via [`ENV_LLM_MODEL`].
/// What: the fallback model id passed to the classifier when the env var is absent.
/// Test: `default_llm_model_is_documented`.
/// #4427: aliased to the classifier's own default so the supervisor cannot label
/// its metrics with a model the classifier never requests.
pub const DEFAULT_LLM_MODEL: &str = crate::activity::classifier::DEFAULT_CLASSIFIER_MODEL;

/// Environment variable that toggles idle-session activity classification.
///
/// Why: classification calls the activity monitor (which may call an LLM). On a
/// host with no `OPENROUTER_API_KEY`, or when an operator wants zero token spend,
/// this lets them turn classification off while keeping auto-resume + metrics.
/// What: set to `0` / `false` to disable; defaults to enabled.
/// Test: `classify_idle_env_parsing`.
pub const ENV_CLASSIFY_IDLE: &str = "TRUSTY_MPM_SUPERVISOR_CLASSIFY";

/// Default poll interval when [`ENV_INTERVAL_SECS`] is unset: 30 seconds.
///
/// Why: 30s balances responsiveness (a stopped session resumes within half a
/// minute) against load (the sweep lists sessions and may classify panes).
/// What: the fallback `Duration` used by [`SupervisorConfig::from_env`].
/// Test: `config_defaults`.
pub const DEFAULT_INTERVAL_SECS: u64 = 30;

/// Environment variable that overrides the post-merge cleanup cadence, in
/// seconds (#7275).
///
/// Why: the cleanup sweep costs one `gh pr view` per pending pull request, so
/// it must run far less often than the fleet sweep. A separate variable lets an
/// operator slow it down (or, with `0`, turn it off) without touching the
/// auto-resume cadence the fleet depends on.
/// What: parsed as `u64` seconds; `0` disables the sweep entirely; an absent or
/// unparsable value falls back to [`DEFAULT_PR_CLEANUP_SECS`].
/// Test: `pr_cleanup_interval_env_parsing`.
pub const ENV_PR_CLEANUP_SECS: &str = "TRUSTY_MPM_PR_CLEANUP_INTERVAL";

/// Default post-merge cleanup cadence when [`ENV_PR_CLEANUP_SECS`] is unset:
/// 5 minutes (#7275, owner amendment 2026-09-09).
///
/// Why: a merge is not time-critical to clean up after — the worktree and
/// branches cost only disk until they go — and five minutes bounds the sweep's
/// `gh` traffic to a rate GitHub's API budget never notices.
pub const DEFAULT_PR_CLEANUP_SECS: u64 = 300;

/// Upper bound on one whole sweep before the loop abandons it (#8335).
///
/// Why: a sweep awaiting a future that never wakes (an LLM reply that never
/// comes, a lock nobody releases), or blocked in a `gh`, `git` or tmux call,
/// stopped the loop for hours with no log line. Ten minutes is far past any
/// healthy sweep and past the default 300 s staleness window, so the heartbeat
/// watchdog reports the wedge first.
/// What: the `tick_timeout` default in [`SupervisorConfig::default`].
/// Test: `config_defaults`.
pub const DEFAULT_TICK_TIMEOUT_SECS: u64 = 600;

/// Upper bound on one per-session step of a fleet sweep (#8335).
///
/// Why: one session's hung resume or classification must not use up the whole
/// sweep's bound and starve every session after it. Two minutes covers a slow
/// LLM reply and a pane rebuild.
/// What: the `step_timeout` default in [`SupervisorConfig::default`].
/// Test: `config_defaults`.
pub const DEFAULT_STEP_TIMEOUT_SECS: u64 = 120;

/// Immutable configuration for one supervisor run.
///
/// Why: the loop reads its policy from one value per tick; bundling the knobs in
/// a small `Clone` struct makes the supervisor trivially testable — a test
/// constructs a config directly rather than mutating process-wide env vars.
/// What: carries the poll [`Duration`], the `auto_resume` gate, and the
/// `classify_idle` toggle.
/// Test: `config_defaults` and every loop test constructs one of these.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SupervisorConfig {
    /// How long to wait between fleet sweeps.
    pub interval: Duration,
    /// When `true`, `stopped` sessions are auto-resumed each sweep.
    pub auto_resume: bool,
    /// When `true`, idle `active` sessions have their pane classified.
    pub classify_idle: bool,
    /// How long to wait between post-merge cleanup sweeps; `None` disables them
    /// (#7275).
    pub pr_cleanup_interval: Option<Duration>,
    /// #8335: how long one fleet sweep, cleanup sweep or publish may run before
    /// the loop abandons it and logs at `error`.
    pub tick_timeout: Duration,
    /// #8335: how long one session's `resume_auto` or classification may await
    /// before the sweep abandons that step and moves to the next session.
    pub step_timeout: Duration,
}

impl Default for SupervisorConfig {
    /// Why: a sensible no-env default makes the type usable in tests and as a
    /// base to override; auto-resume defaults OFF (safety) and classification ON.
    /// The post-merge cleanup sweep follows auto-resume's precedent and defaults
    /// OFF here for the same reason (#7275): it spawns `gh` and deletes
    /// branches, so a hand-constructed config — every test's config — must never
    /// acquire that by omission. [`SupervisorConfig::from_env_with`] turns it on
    /// at [`DEFAULT_PR_CLEANUP_SECS`] for the real daemon.
    /// What: 30s interval, `auto_resume = false`, `classify_idle = true`,
    /// `pr_cleanup_interval = None`, `tick_timeout` = [`DEFAULT_TICK_TIMEOUT_SECS`],
    /// `step_timeout` = [`DEFAULT_STEP_TIMEOUT_SECS`].
    /// Test: `config_defaults`, `pr_cleanup_interval_env_parsing`.
    fn default() -> Self {
        Self {
            interval: Duration::from_secs(DEFAULT_INTERVAL_SECS),
            auto_resume: false,
            classify_idle: true,
            pr_cleanup_interval: None,
            tick_timeout: Duration::from_secs(DEFAULT_TICK_TIMEOUT_SECS),
            step_timeout: Duration::from_secs(DEFAULT_STEP_TIMEOUT_SECS),
        }
    }
}

impl SupervisorConfig {
    /// Build a config from the process environment.
    ///
    /// Why: the supervisor is launched unattended by launchd/systemd, which can
    /// only pass configuration through the environment; this is the production
    /// entry point that maps the real process env onto the typed config.
    /// What: delegates to [`Self::from_env_with`] with a resolver backed by
    /// [`std::env::var`], reading [`ENV_AUTO_RESUME`], [`ENV_INTERVAL_SECS`], and
    /// [`ENV_CLASSIFY_IDLE`], each falling back to its default on absence or a
    /// parse failure.
    /// Test: covered transitively by the `*_env_parsing` tests, which exercise the
    /// shared [`Self::from_env_with`] logic with an injected resolver.
    pub fn from_env() -> Self {
        Self::from_env_with(|key| std::env::var(key).ok())
    }

    /// Build a config from an injectable environment resolver.
    ///
    /// Why: the original `from_env` read the process-wide environment directly,
    /// which forced its tests to call `std::env::set_var`/`remove_var` — a global
    /// mutation that flakes under parallel test execution. Threading the env
    /// through a resolver closure lets tests inject a deterministic fake map with
    /// zero process-wide state, while production passes [`std::env::var`].
    /// What: for each documented variable, calls `get(key)` to obtain its raw
    /// value, parses it, and falls back to the [`Self::default`] value on absence
    /// or a parse failure; the parsing/fallback rules are identical to the legacy
    /// `from_env`.
    /// Test: `auto_resume_env_parsing`, `interval_env_parsing`,
    /// `classify_idle_env_parsing`, `config_defaults`.
    pub fn from_env_with(get: impl Fn(&str) -> Option<String>) -> Self {
        let defaults = Self::default();
        let auto_resume = env_bool(&get, ENV_AUTO_RESUME).unwrap_or(defaults.auto_resume);
        let classify_idle = env_bool(&get, ENV_CLASSIFY_IDLE).unwrap_or(defaults.classify_idle);
        let interval = get(ENV_INTERVAL_SECS)
            .and_then(|v| v.trim().parse::<u64>().ok())
            .filter(|s| *s > 0)
            .map(Duration::from_secs)
            .unwrap_or(defaults.interval);
        // #7275: `0` is the documented off switch, so it must not fall back to
        // the default the way an unparsable value does. The fallback is the
        // named constant, NOT `defaults` — `Default` leaves the sweep off so a
        // hand-constructed config cannot acquire it by omission, while the real
        // daemon reaches this path and gets the five-minute cadence.
        let pr_cleanup_interval = match get(ENV_PR_CLEANUP_SECS).map(|v| v.trim().parse::<u64>()) {
            Some(Ok(0)) => None,
            Some(Ok(secs)) => Some(Duration::from_secs(secs)),
            Some(Err(_)) | None => Some(Duration::from_secs(DEFAULT_PR_CLEANUP_SECS)),
        };
        Self {
            interval,
            auto_resume,
            classify_idle,
            pr_cleanup_interval,
            tick_timeout: defaults.tick_timeout,
            step_timeout: defaults.step_timeout,
        }
    }
}

/// Parse a boolean-ish environment variable via a resolver.
///
/// Why: the env contract accepts `1`/`true`/`yes`/`on` (and their negatives) so
/// operators are not surprised by which spelling works; sharing one parser keeps
/// every boolean flag consistent. Taking the value through a resolver (rather than
/// reading `std::env` directly) keeps [`SupervisorConfig::from_env_with`] testable
/// without process-wide mutation.
/// What: returns `Some(true)` for truthy spellings, `Some(false)` for falsy ones,
/// and `None` when the var is absent or unrecognized (so the caller keeps its default).
/// Test: `env_bool_recognizes_truthy_and_falsy`, `auto_resume_env_parsing`.
fn env_bool(get: impl Fn(&str) -> Option<String>, key: &str) -> Option<bool> {
    let raw = get(key)?;
    match raw.trim().to_ascii_lowercase().as_str() {
        "1" | "true" | "yes" | "on" => Some(true),
        "0" | "false" | "no" | "off" => Some(false),
        _ => None,
    }
}