"""``onboarding.run``: whether the desktop first-run onboarding opens on the next launch. The flag lives in the ROOT profile's ``config.yaml`` (``get_default_hermes_root()``), never in the launch profile's: a pooled backend launched under ``-p work`` must read and write the same file as one launched under ``default``, because onboarding always targets the default profile. Unset means "only on a machine that never used Hermes"; ``true`` re-runs it once; ``false`` means done. """ from __future__ import annotations from pathlib import Path from hermes_constants import get_default_hermes_root def _root_config() -> Path: return get_default_hermes_root() / "config.yaml" def should_run(*, assume_fresh: bool = False) -> bool: """The root config's explicit ``onboarding.run`` (managed overlay included) when it is a bool, else whether this machine has never used Hermes (``install_state``; *assume_fresh* is the unpackaged desktop's ``--fresh-install`` switch).""" value = _explicit_run() if value is not None: return value from hermes_cli.install_state import probe return assume_fresh or probe().fresh def _explicit_run() -> bool | None: from hermes_cli.config_effective import load_user_config_effective # Not load_config(): it resolves the launch profile and fills the default None for an unset flag. section = load_user_config_effective(_root_config()).get("onboarding") value = section.get("run") if isinstance(section, dict) else None return value if isinstance(value, bool) else None def latch_first_install() -> bool: """The desktop backend's first boot on a fresh install records the decision: ``onboarding.run: true`` and the trial reserved. A launch that misses the run (a late answer, the app closed, the user chatting first) then stays due until a run ends. True when it wrote them.""" from hermes_cli.install_state import probe, reserve_trial if _explicit_run() is not None or not probe().fresh: return False set_run(True) # first: a crash before the reservation still leaves a fresh probe for the claim reserve_trial() return True def set_run(value: bool, *, mark_profile_offered: bool = False) -> None: """Persist ``onboarding.run`` (and, with *mark_profile_offered*, ``onboarding.seen.profile_build_offered``) in the root ``config.yaml`` as one write, keeping every other key and comment. A failed write raises.""" from agent.onboarding import PROFILE_BUILD_FLAG from hermes_cli import config as config_mod path = _root_config() with config_mod._CONFIG_LOCK: config = config_mod.read_user_config_raw(path) section = config_mod._ensure_dict(config, "onboarding") section["run"] = value if mark_profile_offered: config_mod._ensure_dict(section, "seen")[PROFILE_BUILD_FLAG] = True config_mod.atomic_config_write(path, config) from hermes_cli import onboarding_due onboarding_due.invalidate()