Skip to content

The agent that grows with you

fix(config-remote): stamp writerConfigVersion only when the profile level's stored data is current

Ben Barclayf0def49876ae
diff --git a/plugins/config_backends/remote/backend.py b/plugins/config_backends/remote/backend.py
index 5955080a302..f8b6a4ba705 100644
--- a/plugins/config_backends/remote/backend.py
+++ b/plugins/config_backends/remote/backend.py
@@ -68,6 +68,8 @@ class _ProfileState:
doc: Dict[str, Any] = field(default_factory=dict) # what readers get (+ _config_version, migrated)
etag: str = ""
profile_version: int = 0
+ # The profile level's stored writerConfigVersion: None = stored null, _UNKNOWN = not reported.
+ profile_writer: Any = None
locks: List[Tuple[KeyPath, str]] = field(default_factory=list)
provenance: Dict[str, str] = field(default_factory=dict)
changed_ns: int = 0
@@ -83,6 +85,18 @@ class _ProfileState:
lock: threading.RLock = field(default_factory=threading.RLock)
+_UNKNOWN = object()
+
+
+def _profile_writer(body: Dict[str, Any]) -> Any:
+ """The profile level's stored ``writerConfigVersion`` (int or None), or ``_UNKNOWN``."""
+ for lv in body.get("levels") or []:
+ if isinstance(lv, dict) and lv.get("kind") == "profile":
+ w = lv.get("writerConfigVersion")
+ return w if w is None or isinstance(w, int) else _UNKNOWN
+ return _UNKNOWN
+
+
def _effective_ok(body: Dict[str, Any]) -> bool:
return (isinstance(body.get("config"), dict) and isinstance(body.get("profileVersion"), int)
and isinstance(body.get("locks"), list))
@@ -209,6 +223,7 @@ class RemoteBackend:
st.doc = doc
st.etag = etag or str(body.get("etag") or "")
st.profile_version = int(body["profileVersion"])
+ st.profile_writer = _profile_writer(body)
st.locks = locks
st.provenance = dict(body.get("provenance") or {})
st.changed_ns = time.time_ns()
@@ -376,8 +391,15 @@ class RemoteBackend:
if not sets and not unsets:
return None
set_body, unset_body = encode_changes(sets, unsets)
- body: Dict[str, Any] = {"expectedVersion": st.profile_version,
- "writerConfigVersion": _latest_config_version()}
+ body: Dict[str, Any] = {"expectedVersion": st.profile_version}
+ # The stamp describes the profile level's STORED data (contract §5.3: absent = unchanged).
+ # Stamp only when that data is already at this agent's version, or unstamped (null: readers
+ # already treat it as current, R6). An older stamp means the level still holds pre-migration
+ # keys that D12 forbids writing back migrated; re-stamping would make later readers skip
+ # those migration steps. A newer stamp must not be lowered either.
+ latest = _latest_config_version()
+ if st.profile_writer is None or st.profile_writer == latest:
+ body["writerConfigVersion"] = latest
if set_body:
body["set"] = set_body
if unset_body:
diff --git a/tests/plugins/config_backends/stub_plane.py b/tests/plugins/config_backends/stub_plane.py
index 4a42500b3da..34fd2b0e082 100644
--- a/tests/plugins/config_backends/stub_plane.py
+++ b/tests/plugins/config_backends/stub_plane.py
@@ -178,7 +178,8 @@ class StubPlane:
if isinstance(node, dict):
node.pop(p[-1], None)
prof["version"] += 1
- prof["writer"] = body.get("writerConfigVersion")
+ if "writerConfigVersion" in body: # contract §5.3: absent = the stored value is unchanged
+ prof["writer"] = body["writerConfigVersion"]
eff = plane.effective(profile)
return self._send(200, eff, eff["etag"])
diff --git a/tests/plugins/config_backends/test_remote_backend.py b/tests/plugins/config_backends/test_remote_backend.py
index d61cb4a9a29..45d210d5699 100644
--- a/tests/plugins/config_backends/test_remote_backend.py
+++ b/tests/plugins/config_backends/test_remote_backend.py
@@ -621,6 +621,53 @@ def test_bulk_save_after_migration_sends_only_the_edit(plane):
assert "compression" not in json.dumps(p["body"])
+def test_unrelated_write_keeps_an_old_profile_stamp_so_later_reads_still_migrate(plane):
+ """Orchestrator ruling (option 1): the profile level stamped 46 still stores a pre-migration
+ key; an unrelated write must not re-stamp it, or every later reader would skip 46->47."""
+ from hermes_cli.config import read_raw_config, set_config_value
+ assert backend_mod._latest_config_version() > 46
+ plane.profile("default").update(values={"compression": {"threshold_tokens": 256000}}, writer=46)
+ assert "threshold_tokens" not in (read_raw_config().get("compression") or {}), "precondition"
+
+ set_config_value("display.personality", "pirate")
+
+ (patch,) = plane.patches()
+ assert "writerConfigVersion" not in patch["body"]
+ assert plane.profile("default")["writer"] == 46
+ assert plane.profile("default")["values"]["compression"] == {"threshold_tokens": 256000}
+
+ remote_pkg._reset_for_tests() # a later process reads the same profile level
+ doc = read_raw_config()
+ assert "threshold_tokens" not in (doc.get("compression") or {}) # 46->47 still ran
+ assert doc["display"]["personality"] == "pirate"
+ assert len(plane.patches()) == 1 # D12: the later read wrote nothing back
+
+
[email protected]("stored", ["latest", None])
+def test_write_stamps_a_current_or_unstamped_profile_level(plane, stored):
+ from hermes_cli.config import set_config_value
+ latest = backend_mod._latest_config_version()
+ plane.profile("default")["writer"] = latest if stored == "latest" else None
+
+ set_config_value("display.personality", "pirate")
+
+ (patch,) = plane.patches()
+ assert patch["body"]["writerConfigVersion"] == latest
+ assert plane.profile("default")["writer"] == latest
+
+
+def test_write_never_lowers_a_newer_profile_stamp(plane):
+ from hermes_cli.config import set_config_value
+ newer = backend_mod._latest_config_version() + 1
+ plane.profile("default")["writer"] = newer
+
+ set_config_value("display.personality", "pirate")
+
+ (patch,) = plane.patches()
+ assert "writerConfigVersion" not in patch["body"]
+ assert plane.profile("default")["writer"] == newer
+
+
def _dashboard_put(config):
import asyncio
diff --git a/website/docs/user-guide/remote-config.md b/website/docs/user-guide/remote-config.md
index fc0787087b5..28b59cbd467 100644
--- a/website/docs/user-guide/remote-config.md
+++ b/website/docs/user-guide/remote-config.md
@@ -74,7 +74,9 @@ start.
- **`secrets:` comes from the plane** like any other key, so administrators can
manage and lock secret-source settings centrally.
- **Schema migrations run in memory.** A document written by an older Hermes is
- migrated when it is read, and the result is not written back.
+ migrated when it is read, and the result is not written back. A later write
+ from a newer Hermes keeps the profile's stored schema version unless that
+ data is already current, so every later reader still migrates it.
- **Unknown keys** in the fetched document are ignored with a warning, for
example a key added by a newer Hermes.