fix(config): align prefill messages key handling

tests/cli/test_prefill_config.py

@@ -0,0 +1,35 @@
+"""Regression tests for CLI prefill config key compatibility."""
+
+from __future__ import annotations
+
+import cli
+
+
+def test_resolve_prefill_messages_file_uses_top_level(monkeypatch):
+    monkeypatch.delenv("HERMES_PREFILL_MESSAGES_FILE", raising=False)
+
+    assert cli._resolve_prefill_messages_file(
+        {
+            "prefill_messages_file": "top.json",
+            "agent": {"prefill_messages_file": "legacy.json"},
+        }
+    ) == "top.json"
+
+
+def test_resolve_prefill_messages_file_accepts_legacy_agent_key(monkeypatch):
+    monkeypatch.delenv("HERMES_PREFILL_MESSAGES_FILE", raising=False)
+
+    assert cli._resolve_prefill_messages_file(
+        {"agent": {"prefill_messages_file": "legacy.json"}}
+    ) == "legacy.json"
+
+
+def test_resolve_prefill_messages_file_prefers_env(monkeypatch):
+    monkeypatch.setenv("HERMES_PREFILL_MESSAGES_FILE", "env.json")
+
+    assert cli._resolve_prefill_messages_file(
+        {
+            "prefill_messages_file": "top.json",
+            "agent": {"prefill_messages_file": "legacy.json"},
+        }
+    ) == "env.json"

tests/cron/test_scheduler.py

@@ -1546,6 +1546,36 @@ class TestRunJobConfigEnvVarExpansion:
             "config.yaml ${VAR} was not expanded in the cron execution path."
         )
 
+    def test_legacy_agent_prefill_messages_file_is_loaded(self, tmp_path, monkeypatch):
+        """Cron accepts the legacy agent.prefill_messages_file fallback."""
+        prefill = [{"role": "system", "content": "legacy cron prefill"}]
+        (tmp_path / "prefill.json").write_text(json.dumps(prefill), encoding="utf-8")
+        (tmp_path / "config.yaml").write_text(
+            "agent:\n"
+            "  prefill_messages_file: prefill.json\n",
+            encoding="utf-8",
+        )
+
+        job = {"id": "prefill-job", "name": "prefill test", "prompt": "hi"}
+        fake_db = MagicMock()
+
+        with patch("cron.scheduler._hermes_home", tmp_path), \
+             patch("cron.scheduler._resolve_origin", return_value=None), \
+             patch("dotenv.load_dotenv"), \
+             patch("hermes_state.SessionDB", return_value=fake_db), \
+             patch("hermes_cli.runtime_provider.resolve_runtime_provider",
+                   return_value=self._RUNTIME), \
+             patch("tools.mcp_tool.discover_mcp_tools", return_value=[]), \
+             patch("run_agent.AIAgent") as mock_agent_cls:
+            mock_agent = MagicMock()
+            mock_agent.run_conversation.return_value = {"final_response": "ok"}
+            mock_agent_cls.return_value = mock_agent
+            success, _, _, error = run_job(job)
+
+        assert success is True
+        assert error is None
+        assert mock_agent_cls.call_args.kwargs["prefill_messages"] == prefill
+
     def test_fallback_model_env_ref_in_config_yaml_is_expanded(self, tmp_path, monkeypatch):
         """${VAR} in config.yaml fallback_providers model: is expanded."""
         (tmp_path / "config.yaml").write_text(

tests/gateway/test_runtime_config_env_expansion.py

@@ -33,6 +33,29 @@ def test_load_prefill_messages_expands_env_var_path(monkeypatch, gateway_home):
     assert gateway_run.GatewayRunner._load_prefill_messages() == prefill
 
 
+def test_load_prefill_messages_accepts_legacy_agent_key(monkeypatch, gateway_home):
+    prefill = [{"role": "system", "content": "legacy few-shot"}]
+    (gateway_home / "prefill.json").write_text(json.dumps(prefill), encoding="utf-8")
+    _write_config(gateway_home, "agent:\n  prefill_messages_file: prefill.json\n")
+
+    assert gateway_run.GatewayRunner._load_prefill_messages() == prefill
+
+
+def test_load_prefill_messages_prefers_top_level_over_legacy(monkeypatch, gateway_home):
+    top_level = [{"role": "system", "content": "top-level"}]
+    legacy = [{"role": "system", "content": "legacy"}]
+    (gateway_home / "top.json").write_text(json.dumps(top_level), encoding="utf-8")
+    (gateway_home / "legacy.json").write_text(json.dumps(legacy), encoding="utf-8")
+    _write_config(
+        gateway_home,
+        "prefill_messages_file: top.json\n"
+        "agent:\n"
+        "  prefill_messages_file: legacy.json\n",
+    )
+
+    assert gateway_run.GatewayRunner._load_prefill_messages() == top_level
+
+
 @pytest.mark.parametrize(
     ("config_body", "env_name", "env_value", "loader_name", "expected"),
     [