Skip to content

The agent that grows with you

refactor(config): ship the seam with the file backend only

Tekniumbbe207c5935e
diff --git a/hermes_cli/backup.py b/hermes_cli/backup.py
index 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_tooling
logger = 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.json
was not refused or skipped.
"""
- require_file_tooling("Snapshot restore")
from gateway.runtime_ownership import OwnershipConflict, exclusive_maintenance
home = hermes_home or get_hermes_home()
try:
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 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_home
from utils import atomic_replace, fast_safe_load, file_signature, mkstemp_beside
from hermes_cli.config_issues import ConfigIssue, _issue
from 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 user
data. Every migration step MUST write through here (``save_config`` with default-stripping
ON, 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():
- return
with 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)
- return
config_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.py
index 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 backen
the hermes home (profile): one multiplexed process serves N profiles, and every config cache
already 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 raise
exactly what those raise (``FileNotFoundError`` for an absent file, ``OSError``, YAML errors), and
writes are the ruamel round-trip writers in ``utils``. Callers keep their own error handling, so a
@@ -23,7 +23,6 @@ from pathlib import Path
from typing import Any, Mapping, Optional, Protocol, Union, runtime_checkable
CONFIG_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_BACKEND
class _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 0
if 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.py
index 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 holds
identical 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 None
try:
- 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 None
root = 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 None
dest = 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 link
return 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, and
guessing 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 None
newest = list_config_backups(config_path, "good")[:1]
if not newest:
return None
diff --git a/hermes_cli/env_loader.py b/hermes_cli/env_loader.py
index 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 the
diff --git a/hermes_cli/profile_distribution.py b/hermes_cli/profile_distribution.py
index 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: DistributionManifes
A top-level owned directory, and an owned container (``_is_container``), is merged per
authored root. ``cron/jobs.json`` is special: it is one multi-record runtime store, so
shipped 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.py
index 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_none
from hermes_cli.profiles_cache import _PROFILE_FILE_CACHE, _cached_profile_read
logger = 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_home
source_dir = get_hermes_home()
diff --git a/hermes_cli/web_routers/analytics.py b/hermes_cli/web_routers/analytics.py
index 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.py
index 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_WIDTH
yaml.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.py
index 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 sys
from 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.md
index 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: 12
title: "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 Seam
Every 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 top
of 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.md
index 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 |