PR #13629: fix(gateway-config): warn when non-secret settings conflict between config.yaml and .env (#13582)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/13629

Description (problem / solution / changelog)

Fixes #13582.

TL;DR

Stale non-secret entries in ~/.hermes/.env silently override their config.yaml counterparts. Reporter hit it with DISCORD_REPLY_TO_MODE=off in .env winning over discord.reply_to_mode: first in config.yaml, with no diagnostic.

Fix: add a non-breaking warning pass that surfaces these conflicts. Env still wins (behavior unchanged); users just see which setting got overridden so they can clean up their .env.

Approach

The issue proposed two options:

• Option A: make config.yaml authoritative for non-secrets (breaking change)
• Option B: warn when both sources specify the same setting (non-breaking)

This PR is Option B. A stricter Option A — flipping precedence — is intentionally left for a separate, larger-scope discussion.

Fix

A small static allow-list of non-secret settings known to have both YAML and env-var forms:

_YAML_ENV_NON_SECRET_MAPPINGS: tuple[tuple[str, str], ...] = (
    # Discord
    ("discord.reply_to_mode",           "DISCORD_REPLY_TO_MODE"),  # reporter's case
    ("discord.require_mention",         "DISCORD_REQUIRE_MENTION"),
    ("discord.auto_thread",             "DISCORD_AUTO_THREAD"),
    ("discord.reactions",               "DISCORD_REACTIONS"),
    ("discord.free_response_channels",  "DISCORD_FREE_RESPONSE_CHANNELS"),
    ("discord.ignored_channels",        "DISCORD_IGNORED_CHANNELS"),
    ("discord.allowed_channels",        "DISCORD_ALLOWED_CHANNELS"),
    ("discord.no_thread_channels",      "DISCORD_NO_THREAD_CHANNELS"),
    # Telegram
    ("telegram.reply_to_mode",          "TELEGRAM_REPLY_TO_MODE"),
    ("telegram.require_mention",        "TELEGRAM_REQUIRE_MENTION"),
    ("telegram.reactions",              "TELEGRAM_REACTIONS"),
    ("telegram.free_response_chats",    "TELEGRAM_FREE_RESPONSE_CHATS"),
    ("telegram.ignored_threads",        "TELEGRAM_IGNORED_THREADS"),
    ("telegram.proxy_url",              "TELEGRAM_PROXY"),
    # Slack
    ("slack.require_mention",           "SLACK_REQUIRE_MENTION"),
    ("slack.allow_bots",                "SLACK_ALLOW_BOTS"),
    ("slack.free_response_channels",    "SLACK_FREE_RESPONSE_CHANNELS"),
)

And a single helper called once near the top of load_gateway_config:

def _warn_yaml_env_conflicts(yaml_cfg, config_yaml_path):
    for dotted_key, env_var in _YAML_ENV_NON_SECRET_MAPPINGS:
        # walk dotted path, skip if YAML key absent
        # skip if env var absent or empty
        # skip if values match (case-insensitive, same bool/list serialization)
        logger.warning(
            "Gateway config conflict: %s in %s is %r but %s=%r is set in "
            "your environment (typically ~/.hermes/.env). The env var takes "
            "priority by design, so the config.yaml value will have no effect. "
            "Remove %s from .env to make config.yaml authoritative, or update "
            "the .env value to match. (#13582)",
            dotted_key, config_yaml_path.name, yaml_val,
            env_var, env_val, env_var,
        )

Behaviour matrix

Narrow scope — explicitly not changed

• Precedence order. Env still wins. This PR does NOT implement the reporter's Option A (YAML authoritative) because that would break existing deployments relying on .env overrides.
• Tokens / credentials / home-channel IDs. Deliberately absent from the allow-list. Secrets are env-first by convention. Pinned by test_tokens_not_covered.
• YAML → env bridges. The existing bridges (and not os.getenv(...)) are untouched — the warning runs before them and doesn't interfere.
• Output level. WARNING is the right severity: actionable, not fatal. Users can silence it with log config if intentional.

Regression coverage

tests/gateway/test_config.py::TestYamlEnvConflictWarnings — 12 new cases:

Bug-surfacing (5):

• test_reporter_repro_discord_reply_to_mode_warns — reporter's exact scenario
• test_boolean_yaml_compared_as_lowercased_string — bool YAML vs "true"/"false" env
• test_list_yaml_compared_as_comma_joined — list YAML vs comma-joined env
• test_multiple_conflicts_each_warn_once — independent warnings per setting
• test_slack_mappings_covered — non-Discord mappings also fire

Preserved-behaviour canaries (5):

• test_no_warning_when_yaml_only
• test_no_warning_when_env_only
• test_no_warning_when_values_match
• test_value_match_is_case_insensitive
• test_empty_env_value_treated_as_unset

Narrow-scope canaries (2):

• test_tokens_not_covered — DISCORD_BOT_TOKEN etc. must NOT trigger
• test_nested_missing_path_no_warning — walker doesn't raise

5 of 12 fail on clean origin/main (04f9ffb7) with assert 0 == 1 (expected 1 warning, got 0) — the scan isn't there yet. The 7 remaining pin preserved behaviour.

Validation

source venv/bin/activate
python -m pytest tests/gateway/test_config.py::TestYamlEnvConflictWarnings -q
# 12 passed

Broader config-related suites (test_config.py, test_config_cwd_bridge.py, test_display_config.py, test_session_env.py, test_stt_config.py) → 102 passed, 0 regressions.

Pre-empted review questions

Q. Why a static allow-list instead of introspecting the schema? The YAML→env bridges in this file are hand-written per setting — there's no unified schema to derive from. A static allow-list is the minimal, auditable surface that matches reality. If future refactors unify the bridges into a schema, the allow-list can be replaced by that schema.

Q. Why not make this an error at startup? Env is legitimately authoritative in many deployment patterns (Docker, Kubernetes secrets). A warning surfaces the conflict without blocking startup for setups that know what they're doing.

Q. What if a user sets ANTHROPIC_API_KEY in both places? Not covered — tokens/credentials are intentionally absent from the allow-list. Secrets belong in env; duplicating them in YAML is a different class of bug (and a security problem in itself). Separate fix if anyone cares about that.

Q. Could the warning mention which file the env var came from specifically (.env vs shell vs Docker)? The Python process can't reliably distinguish — os.getenv returns a merged view. The warning says "typically ~/.hermes/.env" because that's the most common source; the env var name is named explicitly so the user can grep for it wherever.

_{Co-authored via LLM assistance; I've reviewed every line and am responsible for correctness.}

Changed files

• gateway/config.py (modified, +125/-0)
• tests/gateway/test_config.py (modified, +254/-0)