The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
refactor(config): ship the seam with the file backend only
Tekniumbbe207c5935e
diff --git a/hermes_cli/backup.py b/hermes_cli/backup.pyindex 3f4d95fce92..d65ef2bdb65 100644--- a/hermes_cli/backup.py+++ b/hermes_cli/backup.py@@ -43,7 +43,6 @@ from hermes_cli.backup_restore import (_set_config_path_value,_validate_backup_zip,)-from hermes_cli.config_backend import require_file_toolinglogger = logging.getLogger(__name__)@@ -598,7 +597,6 @@ def run_backup(args) -> bool:the caller turns False into exit status 1 so a cron/systemd timer never publishes a "successful"archive that is missing state.db. Hard failures keep raising ``SystemExit``."""- require_file_tooling("`hermes backup`")hermes_root = get_default_hermes_root()if not hermes_root.is_dir():@@ -735,7 +733,6 @@ def _import_member_rel(member: str, prefix: str) -> tuple[str, bool]:def run_import(args) -> Optional[int]:"""Restore a Hermes backup; return 1 on damaged archives or incomplete restores."""- require_file_tooling("`hermes import`")zip_path = Path(args.zipfile).expanduser().resolve()if not zip_path.is_file():@@ -1542,7 +1539,6 @@ def restore_quick_snapshot(Returns True if at least one file was restored and the listed auth.jsonwas not refused or skipped."""- require_file_tooling("Snapshot restore")from gateway.runtime_ownership import OwnershipConflict, exclusive_maintenancehome = hermes_home or get_hermes_home()try:diff --git a/hermes_cli/config.py b/hermes_cli/config.pyindex bbf0f32f661..d47899f732a 100644--- a/hermes_cli/config.py+++ b/hermes_cli/config.py@@ -46,7 +46,7 @@ from hermes_constants import get_hermes_home, get_process_hermes_homefrom utils import atomic_replace, fast_safe_load, file_signature, mkstemp_besidefrom hermes_cli.config_issues import ConfigIssue, _issuefrom hermes_cli.config_backend import (- config_exists, config_version, probe_config_readable, read_config_doc, supports_file_tooling,+ config_exists, config_version, probe_config_readable, read_config_doc,write_config_document)from hermes_cli.config_read_errors import (_CONFIG_PARSE_FAILURES, _FIX_PERMS, _FIX_YAML, FailedConfigRead, _backups_dir_display,@@ -1180,12 +1180,9 @@ def _persist_migration(config: dict[str, Any]) -> None:persist values that DIFFER from the schema default, plus explicit removals/renames of userdata. Every migration step MUST write through here (``save_config`` with default-strippingON, no ``merge_existing``) so the invariant cannot regress one migration at a time. A migration- is Hermes' own write, never a user turning a feature off. A backend without file tooling- migrates in memory on read and never writes back (D12)."""+ is Hermes' own write, never a user turning a feature off."""from hermes_cli.observability.shared_metrics_disabled import hermes_applied_write- if not supports_file_tooling():- returnwith hermes_applied_write():save_config(config)@@ -2919,12 +2916,8 @@ def edit_config():if is_managed():managed_error("edit configuration")return- if not supports_file_tooling():- print("`hermes config edit` opens the local config file, and this config backend has none. "- "Use `hermes config set <key> <value>` instead.", file=sys.stderr)- returnconfig_path = get_config_path()- if not config_path.exists(): # config-reader: ok — file tooling, gated on supports_file_tooling()+ if not config_path.exists(): # config-reader: ok — file tooling (edits the local file)seed_config_file(config_path)print(f"Created {config_path}")diff --git a/hermes_cli/config_backend.py b/hermes_cli/config_backend.pyindex dfbed76be55..789c16e1a33 100644--- a/hermes_cli/config_backend.py+++ b/hermes_cli/config_backend.py@@ -1,4 +1,4 @@-"""Where the user config layer lives: the ``ConfigBackend`` seam (config-config design §4.1, D10/D11).+"""Where the user config layer lives: the ``ConfigBackend`` seam (config-config design §4.1, D10).Every read and write of a profile's user ``config.yaml`` goes through the backend returned by:func:`get_config_backend` (``scripts/check_config_yaml_readers.py`` and@@ -6,7 +6,7 @@ Every read and write of a profile's user ``config.yaml`` goes through the backenthe hermes home (profile): one multiplexed process serves N profiles, and every config cachealready keys on the config path, so a backend keeps per-home state.-:class:`FileBackend` is the only backend in this build and is today's behaviour byte for byte:+:class:`FileBackend` is the only backend and is today's behaviour byte for byte:the version is the ``file_signature`` stat tuple, reads are ``open`` + ``fast_safe_load`` and raiseexactly what those raise (``FileNotFoundError`` for an absent file, ``OSError``, YAML errors), andwrites are the ruamel round-trip writers in ``utils``. Callers keep their own error handling, so a@@ -23,7 +23,6 @@ from pathlib import Pathfrom typing import Any, Mapping, Optional, Protocol, Union, runtime_checkableCONFIG_FILENAME = "config.yaml"-BACKEND_ENV = "HERMES_CONFIG_BACKEND"PathLike = Union[str, "os.PathLike[str]"]@@ -32,9 +31,7 @@ PathLike = Union[str, "os.PathLike[str]"]class UserLayer:"""One read of a profile's user layer."""doc: Any # the parsed root as written (None for an empty document)- version: tuple[Any, ...] # the cache signature this doc was read at (etag for a remote backend)- locks: Mapping[str, str] = field(default_factory=dict) # dotted prefix -> level that locks it- provenance: str = "" # where the doc came from, for diagnostics+ version: tuple[Any, ...] # the cache signature this doc was read at@dataclass(frozen=True)@@ -67,22 +64,11 @@ class ConfigBackend(Protocol):def exists(self, home: Path) -> bool: ...- def write_changes(self, home: Path, changes: Changes) -> None: ...-- def locked(self, home: Path, dotted: str) -> Optional[str]:- """The level that locks ``dotted`` (prefix-aware), or None."""- ...-- def supports_file_tooling(self) -> bool:- """Whether tools that copy/edit/back up the config FILE (profile clone, backup/restore,- ``config edit``, last-known-good backups, ``migrate_config`` write-back) may run."""+ def probe_readable(self, home: Path) -> None:+ """Raise ``OSError`` while the user layer cannot be read; no parse."""...--class ConfigBackendUnavailable(SystemExit):- """The selected backend cannot serve config. A ``SystemExit`` on purpose: many config readers- fail open with ``except Exception`` → defaults, and serving defaults instead of the selected- backend's config is exactly the silent failure this must not become."""+ def write_changes(self, home: Path, changes: Changes) -> None: ...class FileBackend:@@ -125,7 +111,7 @@ class FileBackend:def read_user_layer(self, home: Path) -> UserLayer:path = self.config_path(home)version = self.version_path(path)- return UserLayer(doc=self.read_path(path), version=version, provenance=str(path))+ return UserLayer(doc=self.read_path(path), version=version)def read_user_doc_readonly(self, home: Path) -> Any:return self.read_path_readonly(self.config_path(home))@@ -136,54 +122,21 @@ class FileBackend:def exists(self, home: Path) -> bool:return self.config_path(home).exists()+ def probe_readable(self, home: Path) -> None:+ path = self.config_path(home)+ with open(path, "rb") as f:+ f.read(1)+def write_changes(self, home: Path, changes: Changes) -> None:self.write_path(self.config_path(home), changes)- def locked(self, home: Path, dotted: str) -> Optional[str]:- return None # a local file has no levels; the managed scope is a separate overlay-- def supports_file_tooling(self) -> bool:- return True-_FILE_BACKEND = FileBackend()-def _dotenv_backend_override() -> Optional[str]:- """``HERMES_CONFIG_BACKEND`` as the launch home's ``.env`` then the managed ``.env`` set it- (both load with override), or None. Consulted only on the refusal path."""- try:- from agent.secret_scope import load_env_file- from hermes_cli import managed_scope- from hermes_constants import get_process_hermes_home- except ImportError: # a bare tree without the dotenv stack (pm runtime fixtures) has no .env layer- return None- value = load_env_file(get_process_hermes_home() / ".env").get(BACKEND_ENV)- managed_dir = managed_scope.get_managed_dir()- if managed_dir is not None:- value = load_env_file(managed_dir / ".env").get(BACKEND_ENV, value)- return value--def get_config_backend() -> ConfigBackend:- """The backend selected by ``HERMES_CONFIG_BACKEND`` (default ``file``).-- Read from the environment on every call, before any config read, so no config value can- select it (D11). Raises :class:`ConfigBackendUnavailable` for a backend this build lacks.- """- kind = os.environ.get(BACKEND_ENV, "").strip().lower() or "file"- if kind != "file":- # A config read can run before load_hermes_dotenv() (hermes_cli.config reads at import time):- # refuse only a value the launch home's .env / managed .env do not override, as that load will.- override = _dotenv_backend_override() # None = no .env sets it; "" = an explicit reset to file- kind = (kind if override is None else override).strip().lower() or "file"- if kind == "file":- return _FILE_BACKEND- if kind == "remote":- raise ConfigBackendUnavailable(- f"{BACKEND_ENV}=remote: the remote config backend is not available in this build of "- "Hermes. Unset it to use the local config.yaml.")- raise ConfigBackendUnavailable(f"{BACKEND_ENV}={kind!r} is not a config backend (expected 'file').")+ """The backend serving every home's user layer: the file backend, the only one there is."""+ return _FILE_BACKENDclass _ExplicitFile(FileBackend):@@ -237,7 +190,8 @@ def config_version_or_none(config_path: PathLike) -> Optional[tuple[Any, ...]]:def version_token(version: Optional[tuple[Any, ...]]) -> float:"""A number that changes with a backend ``version`` (0 = no config), for clients that only- compare successive values: the file backend's version leads with ``st_mtime_ns``, kept as seconds."""+ compare successive values: the file backend's version leads with ``st_mtime_ns``, kept as seconds.+ Any other int-led version is scaled the same way, which is fine: only changes are compared."""if not version:return 0if isinstance(version[0], int):@@ -247,13 +201,9 @@ def version_token(version: Optional[tuple[Any, ...]]) -> float:def probe_config_readable(config_path: PathLike) -> None:- """Raise ``OSError`` while a local config file cannot be opened; no parse. A non-file user- layer has no local read to fail."""+ """Raise ``OSError`` while a config file cannot be read; no parse."""backend, home = _route(config_path)- if isinstance(backend, FileBackend):- path = backend.config_path(home)- with open(path, "rb") as f:- f.read(1)+ backend.probe_readable(home)def config_exists(config_path: PathLike) -> bool:@@ -271,16 +221,3 @@ def write_config_key(config_path: PathLike, key_path: str, value: Any) -> None:"""Set one dotted key (``None`` removes it) — ``atomic_roundtrip_yaml_update`` semantics."""backend, home = _route(config_path)backend.write_changes(home, Changes(unset=(key_path,)) if value is None else Changes(set={key_path: value}))---def supports_file_tooling() -> bool:- """Gate for tools that copy, edit or back up the config FILE itself (§4.3, §4.7)."""- return get_config_backend().supports_file_tooling()---def require_file_tooling(what: str) -> None:- """Refuse *what* (a file-copy tool) with a clear message when the backend has no config file."""- if not supports_file_tooling():- raise ConfigBackendUnavailable(- f"{what} copies the local config.yaml, and the {get_config_backend().name!r} config "- "backend has none. It is not available with this backend.")diff --git a/hermes_cli/config_backups.py b/hermes_cli/config_backups.pyindex 0fd922aee46..a776f4eb297 100644--- a/hermes_cli/config_backups.py+++ b/hermes_cli/config_backups.py@@ -46,13 +46,9 @@ def backup_config(config_path: Path, reason: str, *, keep: int = DEFAULT_KEEP) -Skips when the file is missing/empty, or when the newest backup for *reason* already holdsidentical bytes. Never raises: a failed backup must not block the write it precedes.- Skipped entirely for a config backend without file tooling (no local copies, D2)."""- from hermes_cli.config_backend import supports_file_tooling- if not supports_file_tooling():- return Nonetry:- if not config_path.is_file() or config_path.stat().st_size == 0: # config-reader: ok — file tooling, gated above+ if not config_path.is_file() or config_path.stat().st_size == 0: # config-reader: ok — file tooling (copies the local file)return Noneroot = backups_dir(config_path)root.mkdir(parents=True, exist_ok=True)@@ -60,12 +56,12 @@ def backup_config(config_path: Path, reason: str, *, keep: int = DEFAULT_KEEP) -existing = list_config_backups(config_path, reason)# Not filecmp.cmp: its process-wide cache keys on (size, mtime), so an equal-size edit# within one mtime tick of an earlier comparison is reported identical and never backed up.- if existing and config_path.read_bytes() == existing[0].read_bytes(): # config-reader: ok — file tooling, gated above+ if existing and config_path.read_bytes() == existing[0].read_bytes(): # config-reader: ok — file tooling (copies the local file)return Nonedest = root / f"{config_path.name}.{reason}.{time.strftime('%Y%m%d-%H%M%S')}"if dest.is_symlink() or dest.exists(): # never write through a planted linkreturn None- shutil.copy2(config_path, dest) # config-reader: ok — file tooling, gated above+ shutil.copy2(config_path, dest) # config-reader: ok — file tooling (copies the local file)for stale in [dest, *existing][keep:]:stale.unlink(missing_ok=True)return dest@@ -81,9 +77,6 @@ def load_newest_good_backup(config_path: Path) -> Optional[dict]:tried: a backup that fails to parse means the on-disk copy was damaged after the fact, andguessing further back would serve a config the user never saw as current."""- from hermes_cli.config_backend import supports_file_tooling- if not supports_file_tooling():- return Nonenewest = list_config_backups(config_path, "good")[:1]if not newest:return Nonediff --git a/hermes_cli/env_loader.py b/hermes_cli/env_loader.pyindex e3727e8d956..b8e007bf13f 100644--- a/hermes_cli/env_loader.py+++ b/hermes_cli/env_loader.py@@ -581,13 +581,6 @@ def load_hermes_dotenv(if os.environ.get(name) != value:os.environ[name] = value- # The config backend is selected here — after the .env files, before the first config.yaml read- # (``_apply_external_secret_sources`` reads ``secrets:``) — so an unavailable backend stops the- # process before any reader could fall back to defaults (config-config design §4.4, D11/D32).- from hermes_cli.config_backend import get_config_backend-- get_config_backend()-# External sources are skipped for the updater (dotenv + managed env still load): ``update`` must not# import optional secret-manager libs (Bitwarden → cryptography → _rust.pyd) into the process replacing# that env on Windows, and a fresh retry after a deferred dependency install would otherwise make thediff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.pyindex d488d06fd18..007b2f41964 100644--- a/hermes_cli/profile_distribution.py+++ b/hermes_cli/profile_distribution.py@@ -539,8 +539,6 @@ def _copy_dist_payload(staged: Path, target: Path, manifest: DistributionManifesA top-level owned directory, and an owned container (``_is_container``), is merged perauthored root. ``cron/jobs.json`` is special: it is one multi-record runtime store, soshipped definitions merge by job id instead of replacing the file."""- from hermes_cli.config_backend import require_file_tooling- require_file_tooling("Profile distribution install")target.mkdir(parents=True, exist_ok=True)entries = list(_owned_entries(staged, manifest))_refuse_symlinked_targets(target, entries)diff --git a/hermes_cli/profiles.py b/hermes_cli/profiles.pyindex 28af9e57f57..7be9481a419 100644--- a/hermes_cli/profiles.py+++ b/hermes_cli/profiles.py@@ -24,7 +24,7 @@ from hermes_constants import (LOCAL_RUNTIME_ROOT_DIRS, PROFILE_ID_RE, clear_named_profile_deleted, mark_named_profile_deleted,named_profile_has_identity, named_profile_is_deleted, named_profile_is_live,)-from hermes_cli.config_backend import config_exists, config_version, config_version_or_none, require_file_tooling+from hermes_cli.config_backend import config_exists, config_version, config_version_or_nonefrom hermes_cli.profiles_cache import _PROFILE_FILE_CACHE, _cached_profile_readlogger = logging.getLogger(__name__)@@ -1128,7 +1128,6 @@ def profiles_to_serve(multiplex: bool, *, include_standalone: bool = False,def _resolve_clone_source(clone_from: Optional[str]) -> Path:"""Directory to clone from: the named profile, or the active profile when ``None``."""- require_file_tooling("Profile clone")if clone_from is None:from hermes_constants import get_hermes_homesource_dir = get_hermes_home()diff --git a/hermes_cli/web_routers/analytics.py b/hermes_cli/web_routers/analytics.pyindex 253e5bb85ca..ae732bcab7f 100644--- a/hermes_cli/web_routers/analytics.py+++ b/hermes_cli/web_routers/analytics.py@@ -41,15 +41,11 @@ async def get_config_raw(profile: Optional[str] = None):process's own profile, which is wrong under the global profile switcher."""def _run():- from hermes_cli.config_backend import supports_file_tooling- if not supports_file_tooling():- # The raw editor shows the file's bytes; a non-file backend has no file.- raise HTTPException(status_code=409, detail="This config backend has no raw config file")with _profile_scope(profile):path = get_config_path()- if not path.exists(): # config-reader: ok — file tooling (gated above)+ if not path.exists(): # config-reader: ok — file tooling (the local file itself)return {"yaml": "", "path": str(path)}- return {"yaml": path.read_text(encoding="utf-8-sig"), "path": str(path)} # config-reader: ok — file tooling (gated above)+ return {"yaml": path.read_text(encoding="utf-8-sig"), "path": str(path)} # config-reader: ok — file tooling (the local file itself)return await asyncio.to_thread(_run)diff --git a/hermes_cli/xai_retirement.py b/hermes_cli/xai_retirement.pyindex 43a2837f64c..e7fa6bc0587 100644--- a/hermes_cli/xai_retirement.py+++ b/hermes_cli/xai_retirement.py@@ -131,11 +131,8 @@ def apply_migration(Unless ``backup=False`` a copy goes to ``backups/config/`` (reason ``pre-migrate-xai``)."""from ruamel.yaml import YAML # local import — avoid hard dep at module load- from hermes_cli.config_backend import require_file_tooling- # A type-literal-preserving rewrite of the file itself; a non-file backend has no file.- require_file_tooling("The xAI model migration")config_path = Path(config_path)- if not config_path.exists(): # config-reader: ok — file tooling, gated on supports_file_tooling()+ if not config_path.exists(): # config-reader: ok — file tooling (edits the local file)raise FileNotFoundError(config_path)unchanged = ApplyResult(file_path=config_path, backup_path=None, issues_resolved=[], config_changed=False)if not issues:@@ -145,7 +142,7 @@ def apply_migration(yaml = YAML(typ="rt")yaml.width = ROUNDTRIP_YAML_WIDTHyaml.preserve_quotes = True- with config_path.open("r", encoding="utf-8-sig") as fh: # config-reader: ok — file tooling (gated above)+ with config_path.open("r", encoding="utf-8-sig") as fh: # config-reader: ok — file tooling (the local file itself)doc = yaml.load(fh)if doc is None:return unchanged@@ -178,5 +175,5 @@ def apply_migration(# 0640 / container installs; a root-run migration must not flip ownership).buf = io.StringIO()yaml.dump(doc, buf)- atomic_write_text(config_path, buf.getvalue(), preserve_mode=True) # config-reader: ok — file tooling (gated above)+ atomic_write_text(config_path, buf.getvalue(), preserve_mode=True) # config-reader: ok — file tooling (the local file itself)return ApplyResult(file_path=config_path, backup_path=backup_path, issues_resolved=resolved, config_changed=True)diff --git a/tests/hermes_cli/test_config_backend.py b/tests/hermes_cli/test_config_backend.pyindex 4bded8a61f9..22b2e211221 100644--- a/tests/hermes_cli/test_config_backend.py+++ b/tests/hermes_cli/test_config_backend.py@@ -1,4 +1,4 @@-"""The ConfigBackend seam (config-config design §4.1, D10/D11) and its reader gate."""+"""The ConfigBackend seam (config-config design §4.1, D10) and its reader gate."""import sysfrom pathlib import Path@@ -12,46 +12,21 @@ REPO = Path(__file__).resolve().parents[2]@pytest.fixture-def home(tmp_path, monkeypatch):- monkeypatch.delenv(cb.BACKEND_ENV, raising=False)+def home(tmp_path):h = tmp_path / "home"h.mkdir()return h-class TestSelection:-- def test_default_is_file(self, home):- assert cb.get_config_backend().name == "file"- assert cb.supports_file_tooling() is True-- @pytest.mark.parametrize("value", ["remote", "bogus"])- def test_unavailable_backend_fails_closed(self, home, monkeypatch, value):- # No config value can select the backend, and an unknown one never falls back to the file.- monkeypatch.setenv(cb.BACKEND_ENV, value)- with pytest.raises(cb.ConfigBackendUnavailable):- cb.get_config_backend()- with pytest.raises(cb.ConfigBackendUnavailable):- cb.read_config_doc(home / "config.yaml")-- def test_launch_env_file_overrides_a_stale_shell_value_before_dotenv_loads(self, home, monkeypatch):- # A config read can precede load_hermes_dotenv(); the launch home's .env wins, as that load will.- monkeypatch.setenv("HERMES_HOME", str(home))- monkeypatch.setenv(cb.BACKEND_ENV, "remote")- (home / ".env").write_text(f"{cb.BACKEND_ENV}=file\n", encoding="utf-8")- assert cb.get_config_backend().name == "file"-- def test_empty_launch_env_value_resets_a_stale_shell_value_to_file(self, home, monkeypatch):- # ``HERMES_CONFIG_BACKEND=`` in the launch .env loads over the shell value as "", i.e. the default.- monkeypatch.setenv("HERMES_HOME", str(home))- monkeypatch.setenv(cb.BACKEND_ENV, "remote")- (home / ".env").write_text(f"{cb.BACKEND_ENV}=\n", encoding="utf-8")- assert cb.get_config_backend().name == "file"-- def test_explicit_non_config_file_ignores_backend(self, home, monkeypatch):+class TestRouting:++ def test_explicit_non_config_file_never_reaches_the_backend(self, home, monkeypatch):+ # Only ``<home>/config.yaml`` is a user layer; any other file is read where it is.+ def no_backend():+ raise AssertionError("an explicit file must not consult the backend")+ monkeypatch.setattr(cb, "get_config_backend", no_backend)other = home / "import-source.yaml"other.write_text("a: 1\n", encoding="utf-8")- monkeypatch.setenv(cb.BACKEND_ENV, "remote")assert cb.read_config_doc(other) == {"a": 1}@@ -144,7 +119,6 @@ def recording(monkeypatch, tmp_path):(home / "config.yaml").write_text("# hand-tuned\nmodel:\n default: my-model\nsecrets:\n sources: []\n", encoding="utf-8")monkeypatch.setenv("HERMES_HOME", str(home))- monkeypatch.delenv(cb.BACKEND_ENV, raising=False)for cache in (config_mod._LOAD_CONFIG_CACHE, config_mod._RAW_CONFIG_CACHE):cache.clear()backend = _RecordingBackend()@@ -206,26 +180,6 @@ class TestPipelinesConsultTheBackend:assert "# hand-tuned" in text and "other-model" in text and "kawaii" in text-class TestFileTooling:-- def test_file_backend_allows_it(self, home):- cb.require_file_tooling("x")-- def test_backend_without_a_file_refuses_it(self, home, monkeypatch):- class NoFile(cb.FileBackend):- name = "nofile"-- def supports_file_tooling(self):- return False- monkeypatch.setattr(cb, "get_config_backend", NoFile)- from hermes_cli.config_backups import backup_config- (home / "config.yaml").write_text("a: 1\n", encoding="utf-8")- assert backup_config(home / "config.yaml", "test") is None- with pytest.raises(cb.ConfigBackendUnavailable, match="Profile clone"):- from hermes_cli.profiles import _resolve_clone_source- _resolve_clone_source(None)--class TestReaderGate:def _guard(self):diff --git a/website/docs/developer-guide/config-backend.md b/website/docs/developer-guide/config-backend.mdindex aa93f55b41a..8c3afdf9499 100644--- a/website/docs/developer-guide/config-backend.md+++ b/website/docs/developer-guide/config-backend.md@@ -1,15 +1,17 @@---sidebar_position: 12title: "Config Backend Seam"-description: "Where a profile's user config.yaml is read and written: the ConfigBackend seam, the file and remote backends, and the CI lints that keep every caller on it"+description: "Where a profile's user config.yaml is read and written: the ConfigBackend seam, its file backend, and the CI lints that keep every caller on it"---# Config Backend SeamEvery read, stat, existence check and write of a profile's user `config.yaml` goes through-`hermes_cli/config_backend.py`. The backend is chosen once per process from-`HERMES_CONFIG_BACKEND`, never from a config value: `file` (the default) is the only backend in-this build; any other value stops the process with a clear error instead of falling back to defaults.+`hermes_cli/config_backend.py`. `get_config_backend()` returns the backend for every home; today+that is `FileBackend`, the local `config.yaml` with exactly the primitives Hermes used before the+seam (stat signature, `fast_safe_load`, the ruamel round-trip writers). A backend that does not+store the layer as a local file implements the same `ConfigBackend` protocol, and every caller+already reaches it.## Helpers@@ -19,10 +21,12 @@ this build; any other value stops the process with a clear error instead of fall| `read_config_doc_readonly(path)` | Signature-cached read; never mutate the result || `config_version(path)` | Cache signature (the file's stat tuple) || `config_exists(path)` | Whether the layer exists |+| `probe_config_readable(path)` | Raise `OSError` while the layer cannot be read (no parse) || `write_config_document(path, doc)` / `write_config_key(path, key, value)` | Writes; callers normally use `atomic_config_write` / `atomic_config_replace` |-| `supports_file_tooling()` / `require_file_tooling(what)` | Gate for tools that copy, edit or back up the file itself (`config edit`, backup/restore, profile clone) |-Caches keyed on `config_version` miss whenever the backend's layer changes. The managed scope (`/etc/hermes`) stays an overlay on top+Only `<home>/config.yaml` is a user layer. Any other file passed to these helpers (an import+source, a fixture) is read and written where it is. Caches keyed on `config_version` miss+whenever the backend's layer changes. The managed scope (`/etc/hermes`) stays an overlay on topof whatever user layer the backend returns.## Lints@@ -30,5 +34,5 @@ of whatever user layer the backend returns.- `scripts/check_config_yaml_writers.py` rejects a direct YAML dump of a config path.- `scripts/check_config_yaml_readers.py` rejects a direct `open` / `read_text` / `stat` /`exists` / YAML load of a config path. A true false positive (another product's config- file, or file tooling already gated on `supports_file_tooling()`) carries- `# config-reader: ok — <why>` on the line.+ file, or a tool that copies or edits the local file itself: `config edit`, backups, profile+ clone) carries `# config-reader: ok — <why>` on the line.diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.mdindex 88a3094b39c..dba43302610 100644--- a/website/docs/reference/environment-variables.md+++ b/website/docs/reference/environment-variables.md@@ -125,7 +125,6 @@ Hermes reads environment variables from the process environment and, for user-ma| `HERMES_LOCAL_STT_COMMAND` | Optional local speech-to-text command template. Supports `{input_path}`, `{output_dir}`, `{language}`, and `{model}` placeholders || `HERMES_LOCAL_STT_LANGUAGE` | Default language hint for STT. Used by the `local` (faster-whisper) provider, `HERMES_LOCAL_STT_COMMAND`, the local `whisper` CLI fallback (default: `en`), Groq, and xAI when no per-provider `language` is set in `config.yaml` || `HERMES_HOME` | Select the configuration and user-data home. A literal `~` or `$VAR` in the value is expanded (fish does not expand `~` inside `VAR=~/…`), so it never resolves relative to the current directory. Defaults to `~/.hermes` on POSIX and `%LOCALAPPDATA%\hermes` on Windows; the official Docker image uses `/opt/data`. Profile/runtime context can select a more specific home. |-| `HERMES_CONFIG_BACKEND` | Select where the profile's `config.yaml` user layer is read and written. Only `file` (the default, the local `config.yaml`) exists in this build; any other value stops Hermes at startup with an error instead of falling back to defaults. Read from the launch environment, the launch home's `.env` and the managed `.env`, never from `config.yaml`. See [Config backend](../developer-guide/config-backend.md). || `HERMES_DISABLE_WINDOWS_UTF8` | **Windows only.** Set to `1` to disable the UTF-8 stdio shim (`configure_windows_stdio()`) and fall back to the console's locale code page. Useful for bisecting encoding bugs; rarely the right setting in normal operation || `HERMES_KANBAN_HOME` | Override the shared Hermes root that anchors the kanban board (db + workspaces + worker logs). Falls back to `get_default_hermes_root()` (the parent of any active profile). Useful for tests and unusual deployments || `HERMES_KANBAN_BOARD` | Pin the active kanban board for this process. Takes precedence over `~/.hermes/kanban/current`; the dispatcher injects this into worker subprocess env so workers physically cannot see tasks on other boards. Defaults to `default`. Slug validation: lowercase alphanumerics + hyphens + underscores, 1-64 chars |