Merge branch 'main' of github.com:NousResearch/hermes-agent into bb/gui

tests/agent/test_auxiliary_client.py

@@ -40,6 +40,16 @@ def _clean_env(monkeypatch):
         "ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN",
     ):
         monkeypatch.delenv(key, raising=False)
+    # Module-level unhealthy cache (10-min TTL) leaks between tests;
+    # earlier tests that call _mark_provider_unhealthy() poison the
+    # cache for later ones, causing _resolve_auto to skip providers
+    # that the test patched to return valid clients.
+    import agent.auxiliary_client as _aux_mod
+    _aux_mod._aux_unhealthy_until.clear()
+    _aux_mod._aux_unhealthy_logged_at.clear()
+    yield
+    _aux_mod._aux_unhealthy_until.clear()
+    _aux_mod._aux_unhealthy_logged_at.clear()
 
 
 @pytest.fixture
@@ -461,6 +471,17 @@ class TestExpiredCodexFallback:
         import base64
         import time as _time
 
+        # Belt-and-suspenders: _try_openrouter marks openrouter unhealthy
+        # when OPENROUTER_API_KEY is absent (which the preceding test in
+        # this class exercises).  The file-level _clean_env autouse fixture
+        # clears the cache, but fixture ordering with the conftest
+        # _hermetic_environment autouse can leave a narrow window where
+        # the mark reappears.  Explicitly clear here so this test is
+        # independent of run order.
+        import agent.auxiliary_client as _aux_mod
+        _aux_mod._aux_unhealthy_until.clear()
+        _aux_mod._aux_unhealthy_logged_at.clear()
+
         header = base64.urlsafe_b64encode(b'{"alg":"RS256","typ":"JWT"}').rstrip(b"=").decode()
         payload_data = json.dumps({"exp": int(_time.time()) - 3600}).encode()
         payload = base64.urlsafe_b64encode(payload_data).rstrip(b"=").decode()
@@ -1047,6 +1068,20 @@ class TestGetProviderChain:
 class TestTryPaymentFallback:
     """_try_payment_fallback skips the failed provider and tries alternatives."""
 
+    @pytest.fixture(autouse=True)
+    def _clear_unhealthy_cache(self):
+        """Earlier tests in this file call _mark_provider_unhealthy() which
+        pollutes the module-level ``_aux_unhealthy_until`` dict (10-min TTL).
+        Without this cleanup the fallback chain skips providers we've patched
+        to return valid clients — the patched function is never called.
+        """
+        from agent.auxiliary_client import _aux_unhealthy_until, _aux_unhealthy_logged_at
+        _aux_unhealthy_until.clear()
+        _aux_unhealthy_logged_at.clear()
+        yield
+        _aux_unhealthy_until.clear()
+        _aux_unhealthy_logged_at.clear()
+
     def test_skips_failed_provider(self):
         mock_client = MagicMock()
         with patch("agent.auxiliary_client._try_openrouter", return_value=(None, None)), \

tests/agent/test_custom_provider_extra_body.py

@@ -0,0 +1,93 @@
+from types import SimpleNamespace
+
+from agent.agent_init import _merge_custom_provider_extra_body
+
+
+def test_custom_provider_extra_body_merges_into_request_overrides():
+    agent = SimpleNamespace(
+        provider="custom",
+        model="google/gemma-4-31b-it",
+        base_url="https://example.test/v1",
+        request_overrides={"service_tier": "priority"},
+    )
+
+    _merge_custom_provider_extra_body(
+        agent,
+        [
+            {
+                "name": "gemma",
+                "base_url": "https://example.test/v1/",
+                "model": "google/gemma-4-31b-it",
+                "extra_body": {
+                    "enable_thinking": True,
+                    "reasoning_effort": "high",
+                },
+            }
+        ],
+    )
+
+    assert agent.request_overrides == {
+        "service_tier": "priority",
+        "extra_body": {
+            "enable_thinking": True,
+            "reasoning_effort": "high",
+        },
+    }
+
+
+def test_custom_provider_extra_body_preserves_caller_override():
+    agent = SimpleNamespace(
+        provider="custom",
+        model="google/gemma-4-31b-it",
+        base_url="https://example.test/v1",
+        request_overrides={
+            "extra_body": {
+                "reasoning_effort": "low",
+                "caller_only": True,
+            }
+        },
+    )
+
+    _merge_custom_provider_extra_body(
+        agent,
+        [
+            {
+                "name": "gemma",
+                "base_url": "https://example.test/v1",
+                "model": "google/gemma-4-31b-it",
+                "extra_body": {
+                    "enable_thinking": True,
+                    "reasoning_effort": "high",
+                },
+            }
+        ],
+    )
+
+    assert agent.request_overrides["extra_body"] == {
+        "enable_thinking": True,
+        "reasoning_effort": "low",
+        "caller_only": True,
+    }
+
+
+def test_custom_provider_extra_body_ignores_other_custom_models():
+    agent = SimpleNamespace(
+        provider="custom",
+        model="other-model",
+        base_url="https://example.test/v1",
+        request_overrides={},
+    )
+
+    _merge_custom_provider_extra_body(
+        agent,
+        [
+            {
+                "name": "gemma",
+                "base_url": "https://example.test/v1",
+                "model": "google/gemma-4-31b-it",
+                "extra_body": {"enable_thinking": True},
+            }
+        ],
+    )
+
+    assert agent.request_overrides == {}

tests/agent/test_image_routing.py

@@ -9,8 +9,11 @@ from unittest.mock import patch
 import pytest
 
 from agent.image_routing import (
+    _coerce_capability_bool,
     _coerce_mode,
     _explicit_aux_vision_override,
+    _lookup_supports_vision,
+    _supports_vision_override,
     build_native_content_parts,
     decide_image_input_mode,
 )
@@ -125,6 +128,168 @@ class TestDecideImageInputMode:
             assert decide_image_input_mode("xiaomi", "mimo-v2.5-pro", {}) == "text"
 
 
+# ─── _coerce_capability_bool ─────────────────────────────────────────────────
+
+
+class TestCoerceCapabilityBool:
+    def test_real_bool_passes_through(self):
+        assert _coerce_capability_bool(True) is True
+        assert _coerce_capability_bool(False) is False
+
+    def test_int_0_and_1(self):
+        assert _coerce_capability_bool(1) is True
+        assert _coerce_capability_bool(0) is False
+
+    def test_other_ints_return_none(self):
+        assert _coerce_capability_bool(2) is None
+        assert _coerce_capability_bool(-1) is None
+
+    def test_yaml_true_tokens(self):
+        for s in ("true", "TRUE", "True", "yes", "on", "1", "  true  "):
+            assert _coerce_capability_bool(s) is True
+
+    def test_yaml_false_tokens(self):
+        for s in ("false", "FALSE", "False", "no", "off", "0", "  false  "):
+            assert _coerce_capability_bool(s) is False
+
+    def test_quoted_false_does_not_silently_become_true(self):
+        # Regression: bool("false") is True in Python. A user writing
+        # supports_vision: "false" must NOT enable native vision routing.
+        assert _coerce_capability_bool("false") is False
+
+    def test_unrecognised_strings_return_none(self):
+        # None == fall through to models.dev, not a silent truthy.
+        assert _coerce_capability_bool("maybe") is None
+        assert _coerce_capability_bool("") is None
+        assert _coerce_capability_bool("definitely") is None
+
+    def test_other_types_return_none(self):
+        assert _coerce_capability_bool(None) is None
+        assert _coerce_capability_bool([]) is None
+        assert _coerce_capability_bool({}) is None
+        assert _coerce_capability_bool(1.5) is None
+
+
+# ─── _supports_vision_override ───────────────────────────────────────────────
+
+
+class TestSupportsVisionOverride:
+    def test_no_cfg_returns_none(self):
+        assert _supports_vision_override(None, "custom", "my-llava") is None
+        assert _supports_vision_override({}, "custom", "my-llava") is None
+
+    def test_top_level_shortcut_wins(self):
+        cfg = {"model": {"supports_vision": True}}
+        assert _supports_vision_override(cfg, "custom", "my-llava") is True
+
+    def test_top_level_false_propagates(self):
+        cfg = {"model": {"supports_vision": False}}
+        assert _supports_vision_override(cfg, "custom", "my-llava") is False
+
+    def test_per_provider_per_model_via_runtime_name(self):
+        cfg = {
+            "providers": {
+                "custom": {"models": {"my-llava": {"supports_vision": True}}},
+            },
+        }
+        assert _supports_vision_override(cfg, "custom", "my-llava") is True
+
+    def test_per_provider_per_model_via_config_name(self):
+        # Named custom provider — runtime self.provider == "custom", config
+        # holds the original name under model.provider.
+        cfg = {
+            "model": {"provider": "my-vllm"},
+            "providers": {
+                "my-vllm": {"models": {"my-llava": {"supports_vision": True}}},
+            },
+        }
+        assert _supports_vision_override(cfg, "custom", "my-llava") is True
+
+    def test_quoted_false_string_in_yaml_does_not_enable(self):
+        # Real-world: user writes supports_vision: "false" (quoted).
+        cfg = {"model": {"supports_vision": "false"}}
+        assert _supports_vision_override(cfg, "custom", "my-llava") is False
+
+    def test_unrecognised_value_falls_through(self):
+        cfg = {"model": {"supports_vision": "maybe"}}
+        assert _supports_vision_override(cfg, "custom", "my-llava") is None
+
+    def test_no_override_returns_none(self):
+        cfg = {"model": {"default": "my-llava"}}
+        assert _supports_vision_override(cfg, "custom", "my-llava") is None
+
+    def test_malformed_sections_are_ignored(self):
+        # User accidentally wrote a string where a section was expected —
+        # don't blow up, just fall through.
+        cfg = {"model": "some-string", "providers": ["not-a-dict"]}
+        assert _supports_vision_override(cfg, "custom", "my-llava") is None
+
+
+# ─── _lookup_supports_vision (override-aware) ────────────────────────────────
+
+
+class TestLookupSupportsVisionOverride:
+    def test_config_override_short_circuits_models_dev(self):
+        # Config says True, models.dev says None — config wins.
+        cfg = {"model": {"supports_vision": True}}
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert _lookup_supports_vision("custom", "my-llava", cfg) is True
+
+    def test_config_override_false_beats_vision_capable_models_dev(self):
+        # User explicitly disables vision on a models.dev-vision-capable model.
+        fake_caps = type("Caps", (), {"supports_vision": True})()
+        cfg = {"model": {"supports_vision": False}}
+        with patch("agent.models_dev.get_model_capabilities", return_value=fake_caps):
+            assert _lookup_supports_vision("anthropic", "claude-sonnet-4", cfg) is False
+
+    def test_no_override_falls_back_to_models_dev(self):
+        fake_caps = type("Caps", (), {"supports_vision": True})()
+        with patch("agent.models_dev.get_model_capabilities", return_value=fake_caps):
+            assert _lookup_supports_vision("anthropic", "claude-sonnet-4", {}) is True
+
+    def test_no_override_no_models_dev_entry_returns_none(self):
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert _lookup_supports_vision("custom", "my-llava", {}) is None
+
+    def test_cfg_none_falls_back_to_models_dev(self):
+        # Caller didn't pass cfg at all — old call sites must still work.
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert _lookup_supports_vision("openrouter", "x", None) is None
+
+
+# ─── decide_image_input_mode with auto + override ────────────────────────────
+
+
+class TestAutoModeRespectsOverride:
+    def test_auto_native_for_custom_with_supports_vision_true(self):
+        # The motivating bug: Qwen3.6 on local llama.cpp via provider=custom.
+        # Without the override, auto falls back to text. With it, auto picks
+        # native — no need to also set agent.image_input_mode: native.
+        cfg = {"model": {"supports_vision": True}}
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert decide_image_input_mode("custom", "qwen3.6-35b", cfg) == "native"
+
+    def test_auto_text_for_custom_with_supports_vision_false(self):
+        cfg = {"model": {"supports_vision": False}}
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert decide_image_input_mode("custom", "some-text-only", cfg) == "text"
+
+    def test_auto_text_for_custom_with_no_override(self):
+        # Unchanged baseline: unknown custom model → text.
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert decide_image_input_mode("custom", "unknown", {}) == "text"
+
+    def test_explicit_aux_vision_override_still_wins(self):
+        # If the user has configured a dedicated vision aux backend, respect
+        # it even when supports_vision: true is also set.
+        cfg = {
+            "model": {"supports_vision": True},
+            "auxiliary": {"vision": {"provider": "openrouter", "model": "gemini-2.5-pro"}},
+        }
+        with patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert decide_image_input_mode("custom", "qwen3.6-35b", cfg) == "text"
+
+
 # ─── build_native_content_parts ──────────────────────────────────────────────
 
 

tests/agent/test_skill_commands.py

@@ -556,10 +556,11 @@ Generate some audio.
             raising=False,
         )
 
-        with patch.dict(
-            os.environ, {"HERMES_SESSION_PLATFORM": "telegram"}, clear=False
-        ):
-            with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
+        with patch("tools.skills_tool.SKILLS_DIR", tmp_path):
+            from gateway.session_context import clear_session_vars, set_session_vars
+
+            tokens = set_session_vars(platform="telegram")
+            try:
                 _make_skill(
                     tmp_path,
                     "test-skill",
@@ -571,6 +572,8 @@ Generate some audio.
                 )
                 scan_skill_commands()
                 msg = build_skill_invocation_message("/test-skill", "do stuff")
+            finally:
+                clear_session_vars(tokens)
 
         assert msg is not None
         assert "local cli" in msg.lower()

tests/agent/transports/test_codex_transport.py

@@ -196,14 +196,13 @@ class TestCodexBuildKwargs:
         )
         # xAI Responses receives reasoning.effort on the allowlisted models.
         assert kw.get("reasoning") == {"effort": "high"}
-        # As of May 2026 we deliberately do NOT request
-        # reasoning.encrypted_content back from xAI — the OAuth/SuperGrok
-        # surface rejects replayed encrypted reasoning items on turn 2+
-        # (the multi-turn "Expected to have received response.created
-        # before error" failure).  Grok still reasons natively each turn;
-        # we just don't try to thread the prior turn's encrypted blob back
-        # in.  See tests/run_agent/test_codex_xai_oauth_recovery.py.
-        assert "reasoning.encrypted_content" not in kw.get("include", [])
+        # As of May 2026 (post-revert of PR #26644) we DO request
+        # reasoning.encrypted_content back from xAI so we can replay it
+        # across turns for cross-turn coherence — xAI explicitly relies
+        # on this for their partnership integration.  See
+        # tests/run_agent/test_codex_xai_oauth_recovery.py for the
+        # full history.
+        assert "reasoning.encrypted_content" in kw.get("include", [])
 
     def test_xai_reasoning_disabled_no_reasoning_key(self, transport):
         messages = [{"role": "user", "content": "Hi"}]
@@ -229,9 +228,9 @@ class TestCodexBuildKwargs:
     # api.x.ai 400s with "Model X does not support parameter reasoningEffort"
     # on grok-4 / grok-4-fast / grok-3 / grok-code-fast / grok-4.20-0309-*.
     # Those models reason natively but don't expose the dial. The transport
-    # must omit the `reasoning` key for them.  As of May 2026 we also no
-    # longer request ``reasoning.encrypted_content`` back from xAI on ANY
-    # model — see test_xai_reasoning_effort_passed for the rationale.
+    # must omit the `reasoning` key for them.  As of May 2026 we DO request
+    # ``reasoning.encrypted_content`` back from xAI on every model —
+    # see test_xai_reasoning_effort_passed for the rationale.
 
     def test_xai_grok_4_omits_reasoning_effort(self, transport):
         """grok-4 / grok-4-0709 reject reasoning.effort with HTTP 400."""
@@ -245,9 +244,9 @@ class TestCodexBuildKwargs:
             assert "reasoning" not in kw, (
                 f"{model} must not receive a reasoning key (xAI rejects it)"
             )
-            # We no longer ask xAI for encrypted_content back (see comment
-            # above) — verify the include list is empty.
-            assert "reasoning.encrypted_content" not in kw.get("include", [])
+            # Even without the effort dial we still ask xAI to echo back
+            # encrypted reasoning content so it can be replayed next turn.
+            assert "reasoning.encrypted_content" in kw.get("include", [])
 
     def test_xai_grok_4_fast_omits_reasoning_effort(self, transport):
         """grok-4-fast and grok-4-1-fast variants reject reasoning.effort."""

tests/conftest.py

@@ -20,12 +20,9 @@ test runner at ``scripts/run_tests.sh``.
 """
 
 import asyncio
-import logging
 import os
 import re
-import signal
 import sys
-import tempfile
 from pathlib import Path
 from unittest.mock import patch
 
@@ -37,6 +34,22 @@ if str(PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(PROJECT_ROOT))
 
 
+# ── Per-file process isolation ──────────────────────────────────────────────
+# Tests run via ``scripts/run_tests_parallel.py``, which spawns a fresh
+# ``python -m pytest <file>`` subprocess per test file. Cross-file state
+# leakage (module-level dicts, ContextVars, caches) is impossible: each
+# file gets a clean Python interpreter. Intra-file ordering is the test
+# author's responsibility — if test A in foo.py mutates state that test B
+# in foo.py reads, that's a real bug to fix in the file (it would also
+# bite anyone running ``pytest tests/foo.py`` directly).
+#
+# This replaces the historic _reset_module_state autouse fixture (manual
+# state clearing) and the brief experiment with subprocess-per-test
+# isolation (too slow at ~17k tests).
+#
+# See ``scripts/run_tests_parallel.py`` for the runner.
+
+
 # ── Credential env-var filter ──────────────────────────────────────────────
 #
 # Any env var in the current process matching ONE of these patterns is
@@ -279,7 +292,7 @@ _HERMES_BEHAVIORAL_VARS = frozenset({
     "WECOM_HOME_CHANNEL_NAME",
     # Platform gating — set by load_gateway_config() as a side effect when
     # a config.yaml is present, so individual test bodies that call the
-    # loader leak these values into later tests on the same xdist worker.
+    # loader leak these values into later tests in the same process.
     # Force-clear on every test setup so the leak can't happen.
     "SLACK_REQUIRE_MENTION",
     "SLACK_STRICT_MENTION",
@@ -368,144 +381,21 @@ def _isolate_hermes_home(_hermetic_environment):
     return None
 
 
-# ── Module-level state reset ───────────────────────────────────────────────
+# ── Module-level state reset — replaced by per-file process isolation ──────
 #
-# Python modules are singletons per process, and pytest-xdist workers are
-# long-lived. Module-level dicts/sets (tool registries, approval state,
-# interrupt flags) and ContextVars persist across tests in the same worker,
-# causing tests that pass alone to fail when run with siblings.
+# Each test FILE runs in a freshly-spawned ``python -m pytest <file>``
+# subprocess via ``scripts/run_tests_parallel.py``, so module-level dicts /
+# sets / ContextVars from tests in one file cannot leak into tests in
+# another file. No manual per-module clearing needed.
 #
-# Each entry in this fixture clears state that belongs to a specific module.
-# New state buckets go here too — this is the single gate that prevents
-# "works alone, flakes in CI" bugs from state leakage.
+# Within a single file, ordering is the author's responsibility. If your
+# tests in the same file share mutable state, either reset it explicitly
+# in a fixture or split them across files.
 #
-# The skill `test-suite-cascade-diagnosis` documents the concrete patterns
-# this closes; the running example was `test_command_guards` failing 12/15
-# CI runs because ``tools.approval._session_approved`` carried approvals
-# from one test's session into another's.
-
-@pytest.fixture(autouse=True)
-def _reset_module_state():
-    """Clear module-level mutable state and ContextVars between tests.
-
-    Keeps state from leaking across tests on the same xdist worker. Modules
-    that don't exist yet (test collection before production import) are
-    skipped silently — production import later creates fresh empty state.
-    """
-    # --- logging — quiet/one-shot paths mutate process-global logger state ---
-    logging.disable(logging.NOTSET)
-    for _logger_name in ("tools", "run_agent", "trajectory_compressor", "cron", "hermes_cli"):
-        _logger = logging.getLogger(_logger_name)
-        _logger.disabled = False
-        _logger.setLevel(logging.NOTSET)
-        _logger.propagate = True
-
-    # --- tools.approval — the single biggest source of cross-test pollution ---
-    try:
-        from tools import approval as _approval_mod
-        _approval_mod._session_approved.clear()
-        _approval_mod._session_yolo.clear()
-        _approval_mod._permanent_approved.clear()
-        _approval_mod._pending.clear()
-        _approval_mod._gateway_queues.clear()
-        _approval_mod._gateway_notify_cbs.clear()
-        # ContextVar: reset to empty string so get_current_session_key()
-        # falls through to the env var / default path, matching a fresh
-        # process.
-        _approval_mod._approval_session_key.set("")
-    except Exception:
-        pass
-
-    # --- tools.interrupt — per-thread interrupt flag set ---
-    try:
-        from tools import interrupt as _interrupt_mod
-        with _interrupt_mod._lock:
-            _interrupt_mod._interrupted_threads.clear()
-    except Exception:
-        pass
-
-    # --- gateway.session_context — 9 ContextVars that represent
-    #     the active gateway session. If set in one test and not reset,
-    #     the next test's get_session_env() reads stale values.
-    try:
-        from gateway import session_context as _sc_mod
-        for _cv in (
-            _sc_mod._SESSION_PLATFORM,
-            _sc_mod._SESSION_CHAT_ID,
-            _sc_mod._SESSION_CHAT_NAME,
-            _sc_mod._SESSION_THREAD_ID,
-            _sc_mod._SESSION_USER_ID,
-            _sc_mod._SESSION_USER_NAME,
-            _sc_mod._SESSION_KEY,
-            _sc_mod._CRON_AUTO_DELIVER_PLATFORM,
-            _sc_mod._CRON_AUTO_DELIVER_CHAT_ID,
-            _sc_mod._CRON_AUTO_DELIVER_THREAD_ID,
-        ):
-            _cv.set(_sc_mod._UNSET)
-    except Exception:
-        pass
-
-    # --- tools.env_passthrough — ContextVar<set[str]> with no default ---
-    # LookupError is normal if the test never set it. Setting it to an
-    # empty set unconditionally normalizes the starting state.
-    try:
-        from tools import env_passthrough as _envp_mod
-        _envp_mod._allowed_env_vars_var.set(set())
-    except Exception:
-        pass
-
-    # --- tools.terminal_tool — active environment/cwd cache ---
-    # File tools prefer a live terminal cwd when one is cached for the task.
-    # Clear terminal environments between tests so a prior terminal call can't
-    # override TERMINAL_CWD in path-resolution tests.
-    try:
-        from tools import terminal_tool as _term_mod
-        _envs_to_cleanup = []
-        with _term_mod._env_lock:
-            _envs_to_cleanup = list(_term_mod._active_environments.values())
-            _term_mod._active_environments.clear()
-            _term_mod._last_activity.clear()
-            _term_mod._creation_locks.clear()
-        for _env in _envs_to_cleanup:
-            try:
-                _env.cleanup()
-            except Exception:
-                pass
-    except Exception:
-        pass
-
-    # --- tools.credential_files — ContextVar<dict> ---
-    try:
-        from tools import credential_files as _credf_mod
-        _credf_mod._registered_files_var.set({})
-    except Exception:
-        pass
-
-    # --- agent.auxiliary_client — runtime main provider/model override and
-    #     payment-error health cache. Both are process-global in production;
-    #     reset them per test so one worker's fallback/402 test does not make
-    #     later auxiliary-client tests skip otherwise-available providers.
-    try:
-        from agent import auxiliary_client as _aux_mod
-        _aux_mod.clear_runtime_main()
-        _aux_mod._reset_aux_unhealthy_cache()
-    except Exception:
-        pass
-
-    # --- tools.file_tools — per-task read history + file-ops cache ---
-    # _read_tracker accumulates per-task_id read history for loop detection,
-    # capped by _READ_HISTORY_CAP. If entries from a prior test persist, the
-    # cap is hit faster than expected and capacity-related tests flake.
-    try:
-        from tools import file_tools as _ft_mod
-        with _ft_mod._read_tracker_lock:
-            _ft_mod._read_tracker.clear()
-        with _ft_mod._file_ops_lock:
-            _ft_mod._file_ops_cache.clear()
-    except Exception:
-        pass
-
-    yield
+# The skill ``test-suite-cascade-diagnosis`` documents the cascade patterns
+# this replaces; the running example was ``test_command_guards`` failing
+# 12/15 CI runs because ``tools.approval._session_approved`` carried
+# approvals from one test's session into another's.
 
 
 @pytest.fixture()
@@ -532,13 +422,12 @@ def mock_config():
     }
 
 
-# ── Global test timeout ─────────────────────────────────────────────────────
-# Kill any individual test that takes longer than 30 seconds.
-# Prevents hanging tests (subprocess spawns, blocking I/O) from stalling the
-# entire test suite.
+# ── Per-test timeout — handled by the isolation plugin ─────────────────────
+#
+# The subprocess-per-test plugin enforces the configured ``isolate_timeout``
+# ini key by terminating the child if it overruns. The old SIGALRM-based
+# fixture (POSIX-only, didn't work on Windows) is gone.
 
-def _timeout_handler(signum, frame):
-    raise TimeoutError("Test exceeded 30 second timeout")
 
 @pytest.fixture(autouse=True)
 def _ensure_current_event_loop(request):
@@ -584,45 +473,6 @@ def _ensure_current_event_loop(request):
                 asyncio.set_event_loop(None)
 
 
-@pytest.fixture(autouse=True)
-def _enforce_test_timeout():
-    """Kill any individual test that takes longer than 30 seconds.
-    SIGALRM is Unix-only; skip on Windows."""
-    if sys.platform == "win32":
-        yield
-        return
-    old = signal.signal(signal.SIGALRM, _timeout_handler)
-    signal.alarm(30)
-    yield
-    signal.alarm(0)
-    signal.signal(signal.SIGALRM, old)
-
-
-@pytest.fixture(autouse=True)
-def _reset_tool_registry_caches():
-    """Clear tool-registry-level caches between tests.
-
-    The production registry caches ``check_fn()`` results for 30 s
-    (see tools/registry.py) and :func:`get_tool_definitions` memoizes
-    its result (see model_tools.py). Both are keyed on state that tests
-    routinely mutate (env vars, registry._generation, config.yaml mtime)
-    — but a stale result from test A can still be served to test B
-    because 30 s covers the entire suite, and xdist worker reuse means
-    one test's cache lands in another's process. Clearing before every
-    test keeps hermetic behavior.
-    """
-    try:
-        from tools.registry import invalidate_check_fn_cache
-        invalidate_check_fn_cache()
-    except ImportError:
-        pass
-    try:
-        from model_tools import _clear_tool_defs_cache
-        _clear_tool_defs_cache()
-    except ImportError:
-        pass
-
-
 # ── Live-system guard ──────────────────────────────────────────────────────
 #
 # Several test files exercise the gateway-restart / kill code paths

tests/gateway/conftest.py

@@ -313,19 +313,30 @@ def _scan_for_plugin_adapter_antipattern(source: str) -> list[str]:
     return offenses
 
 
-def pytest_configure(config):
-    """Reject plugin-adapter tests that use the sys.path anti-pattern.
+def _fingerprint_gateway_tests() -> str:
+    """Return a short fingerprint that changes when any gateway test file changes.
 
-    Runs once per pytest session on the controller, BEFORE any xdist
-    worker is spawned. If any file under ``tests/gateway/`` matches the
-    anti-pattern, we fail the whole session with a clear message —
-    before a polluted ``sys.path`` can cascade across workers.
+    Uses (mtime, size) pairs instead of content hashing — fast to compute
+    (stat-only, no reads) and sufficient for cache invalidation across
+    per-file subprocess runs.
     """
-    # Only run on the xdist controller (or in non-xdist runs). Skip on
-    # worker subprocesses so we don't scan the filesystem N times.
-    if hasattr(config, "workerinput"):
-        return
+    import hashlib
 
+    h = hashlib.sha256()
+    for path in sorted(_GATEWAY_DIR.rglob("test_*.py")):
+        try:
+            st = path.stat()
+            h.update(f"{path.name}:{st.st_mtime_ns}:{st.st_size}".encode())
+        except OSError:
+            h.update(f"{path.name}:missing".encode())
+    return h.hexdigest()[:16]
+
+
+def _run_adapter_antipattern_scan() -> list[str]:
+    """Scan gateway test files for the plugin-adapter anti-pattern.
+
+    Returns a list of violation strings (empty if clean).
+    """
     violations: list[str] = []
     for path in _GATEWAY_DIR.rglob("test_*.py"):
         if path.name in {"_plugin_adapter_loader.py", "conftest.py"}:
@@ -334,20 +345,108 @@ def pytest_configure(config):
             source = path.read_text(encoding="utf-8")
         except OSError:
             continue
+        # Fast string pre-filter: skip files that can't possibly violate.
+        # A violating file MUST contain both (a) an adapter/plugins/platforms
+        # reference AND (b) either sys.path manipulation or a bare adapter import.
         if "adapter" not in source and "plugins/platforms" not in source:
             continue
+        if not (
+            "sys.path" in source
+            or "import adapter" in source
+            or "from adapter import" in source
+        ):
+            continue
         offenses = _scan_for_plugin_adapter_antipattern(source)
         if offenses:
             violations.append(
                 f"  {path.relative_to(_GATEWAY_DIR.parent.parent)}:\n    "
                 + "\n    ".join(offenses)
             )
+    return violations
 
-    if violations:
-        raise pytest.UsageError(
-            "Plugin-adapter-import anti-pattern detected in gateway tests:\n"
-            + "\n".join(violations)
-            + "\n\n"
-            + _GUARD_HINT
-        )
+
+def pytest_configure(config):
+    """Reject plugin-adapter tests that use the sys.path anti-pattern.
+
+    Runs once per pytest session on the controller, BEFORE any xdist
+    worker is spawned. If any file under ``tests/gateway/`` matches the
+    anti-pattern, we fail the whole session with a clear message —
+    before a polluted ``sys.path`` can cascade across workers.
+
+    **Performance**: in the per-file subprocess isolation model (no xdist),
+    every subprocess is a "controller" — so the naive scan would run 257
+    times, each costing ~1s of AST walking.  We avoid this with two
+    strategies:
+
+    1. **Tight string pre-filter**: a file can only violate if it contains
+       *both* an adapter/plugins/platforms reference *and* a sys.path
+       manipulation or bare ``import adapter``.  This drops ~95% of files
+       from needing AST parsing.
+    2. **File-locked cache**: the scan result is cached in
+       ``.pytest-cache/gw-adapter-guard-<fingerprint>`` keyed on a
+       fingerprint of the gateway test file mtimes/sizes.  Concurrent
+       subprocesses acquire a lock; only the first performs the scan;
+       the rest wait and read the cached result.
+    """
+    # Only run on the xdist controller (or in non-xdist runs). Skip on
+    # worker subprocesses so we don't scan the filesystem N times.
+    if hasattr(config, "workerinput"):
+        return
+
+    fp = _fingerprint_gateway_tests()
+    cache_dir = Path.cwd() / ".pytest-cache"
+    cache_file = cache_dir / f"gw-adapter-guard-{fp}"
+    lock_file = cache_dir / f".gw-adapter-guard-{fp}.lock"
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    # Evict stale cache entries from previous fingerprints (best-effort).
+    try:
+        for old in cache_dir.glob("gw-adapter-guard-*"):
+            if old.name != f"gw-adapter-guard-{fp}":
+                old.unlink(missing_ok=True)
+        for old in cache_dir.glob(".gw-adapter-guard-*.lock"):
+            if old.name != f".gw-adapter-guard-{fp}.lock":
+                old.unlink(missing_ok=True)
+    except OSError:
+        pass  # Non-critical; old files are harmless.
+
+    # Use filelock to ensure only one process scans at a time.
+    # Concurrent subprocesses all hit pytest_configure simultaneously;
+    # without a lock they'd all find no cache and all run the scan.
+    try:
+        from filelock import FileLock
+        lock = FileLock(str(lock_file), timeout=120)
+    except ImportError:
+        # Fallback: no locking (still correct, just slower under contention).
+        import contextlib
+
+        class _NoLock:
+            def __enter__(self):
+                return self
+            def __exit__(self, *a):
+                pass
+        lock = _NoLock()
+
+    with lock:
+        if cache_file.exists():
+            cached = cache_file.read_text(encoding="utf-8")
+            if cached == "clean":
+                return
+            raise pytest.UsageError(cached)
+
+        # Slow path: this process is the first to acquire the lock.
+        violations = _run_adapter_antipattern_scan()
+
+        if violations:
+            msg = (
+                "Plugin-adapter-import anti-pattern detected in gateway tests:\n"
+                + "\n".join(violations)
+                + "\n\n"
+                + _GUARD_HINT
+            )
+            cache_file.write_text(msg, encoding="utf-8")
+            raise pytest.UsageError(msg)
+        else:
+            cache_file.write_text("clean", encoding="utf-8")
 

tests/gateway/platforms/test_yuanbao_recall_db_only.py

@@ -0,0 +1,88 @@
+"""Yuanbao recall: branch A1 (exact id) and A2 (content-match) against DB-only transcripts.
+
+state.db persists the platform-side ``message_id`` via the
+``platform_message_id`` column (added in the salvage of PR #29211) and
+``load_transcript`` surfaces it back on each message dict as ``message_id``
+— so the recall guard's exact-id match path stays canonical even with the
+JSONL file gone.  When a row has no platform id (e.g. agent-processed
+@bot messages whose adapter didn't carry a msg_id, or pre-column legacy
+rows), recall falls through to content-match.
+"""
+from gateway.session import SessionStore
+from gateway.config import GatewayConfig
+
+
+def _pin_db(monkeypatch, tmp_path):
+    """Force SessionDB() to write into tmp_path instead of the real ~/.hermes."""
+    import hermes_state
+    monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
+
+
+def test_recall_branch_a1_exact_id_match_round_trips_through_db(tmp_path, monkeypatch):
+    """A user message persisted with ``message_id`` must round-trip through
+    state.db so recall can find and redact it by exact id (branch A1)."""
+    _pin_db(monkeypatch, tmp_path)
+
+    config = GatewayConfig()
+    store = SessionStore(sessions_dir=tmp_path, config=config)
+
+    sid = "test-yuanbao-recall-a1"
+    store._db.create_session(session_id=sid, source="yuanbao:group:G")
+    store.append_to_transcript(sid, {
+        "role": "user",
+        "content": "sensitive content",
+        "timestamp": 1.0,
+        "message_id": "platform-msg-abc",
+    })
+    store.append_to_transcript(sid, {
+        "role": "assistant",
+        "content": "ack",
+        "timestamp": 2.0,
+    })
+
+    history = store.load_transcript(sid)
+    # The user row must carry its platform id back so the recall guard can
+    # match by exact id; the assistant row had no platform id so it should
+    # not gain one spuriously.
+    user_msg = next(m for m in history if m["role"] == "user")
+    assistant_msg = next(m for m in history if m["role"] == "assistant")
+    assert user_msg.get("message_id") == "platform-msg-abc"
+    assert "message_id" not in assistant_msg
+
+    # Branch A1: locate the row by exact platform id — no content heuristics.
+    target = next(
+        (m for m in history if m.get("message_id") == "platform-msg-abc"),
+        None,
+    )
+    assert target is not None
+    assert target["content"] == "sensitive content"
+
+
+def test_recall_branch_a2_content_match_when_no_platform_id(tmp_path, monkeypatch):
+    """Rows that lack a platform_message_id (e.g. agent-processed @bot
+    messages) still match by content as a fallback."""
+    _pin_db(monkeypatch, tmp_path)
+
+    config = GatewayConfig()
+    store = SessionStore(sessions_dir=tmp_path, config=config)
+
+    sid = "test-yuanbao-recall-a2"
+    store._db.create_session(session_id=sid, source="yuanbao:group:G")
+    # No message_id on the dict — simulates an agent-processed message
+    # that did not carry the platform msg_id through.
+    store.append_to_transcript(sid, {
+        "role": "user",
+        "content": "sensitive content",
+        "timestamp": 1.0,
+    })
+
+    history = store.load_transcript(sid)
+    assert all("message_id" not in m for m in history)
+
+    # Branch A2: content match recovers the target.
+    target = next(
+        (m for m in history
+         if m.get("role") == "user" and m.get("content") == "sensitive content"),
+        None,
+    )
+    assert target is not None

tests/gateway/test_dm_topics.py

@@ -22,19 +22,26 @@ from gateway.config import PlatformConfig
 
 
 def _ensure_telegram_mock():
-    if "telegram" in sys.modules and hasattr(sys.modules["telegram"], "__file__"):
-        return
-
     telegram_mod = MagicMock()
     telegram_mod.ext.ContextTypes.DEFAULT_TYPE = type(None)
-    telegram_mod.constants.ParseMode.MARKDOWN_V2 = "MarkdownV2"
-    telegram_mod.constants.ChatType.GROUP = "group"
-    telegram_mod.constants.ChatType.SUPERGROUP = "supergroup"
-    telegram_mod.constants.ChatType.CHANNEL = "channel"
-    telegram_mod.constants.ChatType.PRIVATE = "private"
 
-    for name in ("telegram", "telegram.ext", "telegram.constants", "telegram.request"):
-        sys.modules.setdefault(name, telegram_mod)
+    # Register telegram.constants as a separate module mock so that
+    # ``from telegram.constants import ChatType`` resolves to our mock
+    # with string-valued members (not auto-generated MagicMocks).
+    constants_mod = MagicMock()
+    constants_mod.ParseMode.MARKDOWN_V2 = "MarkdownV2"
+    constants_mod.ChatType.GROUP = "group"
+    constants_mod.ChatType.SUPERGROUP = "supergroup"
+    constants_mod.ChatType.CHANNEL = "channel"
+    constants_mod.ChatType.PRIVATE = "private"
+
+    sys.modules["telegram"] = telegram_mod
+    sys.modules["telegram.ext"] = telegram_mod.ext
+    sys.modules["telegram.constants"] = constants_mod
+    sys.modules["telegram.request"] = telegram_mod.request
+
+    # Force reimport so the adapter picks up the mock ChatType.
+    sys.modules.pop("gateway.platforms.telegram", None)
 
 
 _ensure_telegram_mock()

tests/gateway/test_google_chat.py

@@ -22,6 +22,11 @@ import pytest
 
 from gateway.config import Platform, PlatformConfig, load_gateway_config
 
+# Platform uses _missing_() for dynamic members, so "google_chat" is
+# resolvable via Platform("google_chat") even without a static
+# GOOGLE_CHAT attribute on the enum class.
+_GC = Platform("google_chat")
+
 
 # ---------------------------------------------------------------------------
 # Mock the google-* packages if they are not installed
@@ -229,7 +234,7 @@ def _make_chat_envelope(text="hello", sender_email="u@example.com", sender_type=
 
 class TestPlatformRegistration:
     def test_enum_value(self):
-        assert Platform.GOOGLE_CHAT.value == "google_chat"
+        assert _GC.value == "google_chat"
 
     def test_requirements_check_returns_true_when_available(self):
         # The shim flag is True in this test module.
@@ -266,14 +271,14 @@ class TestEnvConfigLoading:
         monkeypatch.setenv("GOOGLE_CHAT_PROJECT_ID", "p")
         # No subscription.
         cfg = load_gateway_config()
-        assert Platform.GOOGLE_CHAT not in cfg.platforms
+        assert _GC not in cfg.platforms
 
     def test_missing_project_does_not_enable(self, monkeypatch):
         self._clean_env(monkeypatch)
         monkeypatch.setenv("GOOGLE_CHAT_SUBSCRIPTION_NAME",
                            "projects/p/subscriptions/s")
         cfg = load_gateway_config()
-        assert Platform.GOOGLE_CHAT not in cfg.platforms
+        assert _GC not in cfg.platforms
 
 
 
@@ -2583,7 +2588,7 @@ class TestAuthorizationEmailMatch:
         runner.pairing_store.is_approved = MagicMock(return_value=False)
 
         source = SessionSource(
-            platform=Platform.GOOGLE_CHAT,
+            platform=_GC,
             chat_id="spaces/S",
             chat_type="dm",
             user_id="alice@example.com",       # post-swap: email is canonical
@@ -2604,7 +2609,7 @@ class TestAuthorizationEmailMatch:
         runner.pairing_store.is_approved = MagicMock(return_value=False)
 
         source = SessionSource(
-            platform=Platform.GOOGLE_CHAT,
+            platform=_GC,
             chat_id="spaces/S",
             chat_type="dm",
             user_id="bob@example.com",
@@ -2630,7 +2635,7 @@ class TestAuthorizationEmailMatch:
         runner.pairing_store.is_approved = MagicMock(return_value=False)
 
         source = SessionSource(
-            platform=Platform.GOOGLE_CHAT,
+            platform=_GC,
             chat_id="spaces/S",
             chat_type="dm",
             user_id="users/77777",  # no email available — resource name wins

tests/gateway/test_load_transcript_db_only.py

@@ -0,0 +1,32 @@
+"""Verify load_transcript returns SQLite messages without any JSONL file."""
+from pathlib import Path
+
+import pytest
+
+from gateway.session import SessionStore
+from gateway.config import GatewayConfig
+
+
+def test_load_transcript_returns_db_messages_when_no_jsonl(tmp_path, monkeypatch):
+    """Reading a transcript must work from SQLite alone — no JSONL fallback needed.
+
+    Pin DEFAULT_DB_PATH to tmp_path so this test cannot write to the real
+    ~/.hermes/state.db. (DEFAULT_DB_PATH is a module-level constant computed
+    at hermes_state import time, before pytest's HERMES_HOME monkeypatch
+    fires — the autouse fixture's HERMES_HOME override doesn't help here.)
+    """
+    import hermes_state
+    monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
+
+    config = GatewayConfig()
+    store = SessionStore(sessions_dir=tmp_path, config=config)
+
+    sid = "test-session-db-only"
+    store._db.create_session(session_id=sid, source="test")
+    store.append_to_transcript(sid, {"role": "user", "content": "hello", "timestamp": 1.0})
+    store.append_to_transcript(sid, {"role": "assistant", "content": "world", "timestamp": 2.0})
+
+    history = store.load_transcript(sid)
+    assert len(history) == 2
+    assert history[0]["content"] == "hello"
+    assert history[1]["content"] == "world"

tests/gateway/test_mirror.py

@@ -8,7 +8,6 @@ import gateway.mirror as mirror_mod
 from gateway.mirror import (
     mirror_to_session,
     _find_session_id,
-    _append_to_jsonl,
 )
 
 
@@ -152,33 +151,6 @@ class TestFindSessionId:
         assert result == "sess_1"
 
 
-class TestAppendToJsonl:
-    def test_appends_message(self, tmp_path):
-        sessions_dir = tmp_path / "sessions"
-        sessions_dir.mkdir()
-
-        with patch.object(mirror_mod, "_SESSIONS_DIR", sessions_dir):
-            _append_to_jsonl("sess_1", {"role": "assistant", "content": "Hello"})
-
-        transcript = sessions_dir / "sess_1.jsonl"
-        lines = transcript.read_text().strip().splitlines()
-        assert len(lines) == 1
-        msg = json.loads(lines[0])
-        assert msg["role"] == "assistant"
-        assert msg["content"] == "Hello"
-
-    def test_appends_multiple_messages(self, tmp_path):
-        sessions_dir = tmp_path / "sessions"
-        sessions_dir.mkdir()
-
-        with patch.object(mirror_mod, "_SESSIONS_DIR", sessions_dir):
-            _append_to_jsonl("sess_1", {"role": "assistant", "content": "msg1"})
-            _append_to_jsonl("sess_1", {"role": "assistant", "content": "msg2"})
-
-        transcript = sessions_dir / "sess_1.jsonl"
-        lines = transcript.read_text().strip().splitlines()
-        assert len(lines) == 2
-
 
 class TestMirrorToSession:
     def test_successful_mirror(self, tmp_path):
@@ -192,15 +164,16 @@ class TestMirrorToSession:
 
         with patch.object(mirror_mod, "_SESSIONS_DIR", sessions_dir), \
              patch.object(mirror_mod, "_SESSIONS_INDEX", index_file), \
-             patch("gateway.mirror._append_to_sqlite"):
+             patch("gateway.mirror._append_to_sqlite") as mock_sqlite:
             result = mirror_to_session("telegram", "12345", "Hello!", source_label="cli")
 
         assert result is True
 
-        # Check JSONL was written
-        transcript = sessions_dir / "sess_abc.jsonl"
-        assert transcript.exists()
-        msg = json.loads(transcript.read_text().strip())
+        # Check SQLite writer was called with the mirror message
+        mock_sqlite.assert_called_once()
+        call_args = mock_sqlite.call_args
+        assert call_args[0][0] == "sess_abc"
+        msg = call_args[0][1]
         assert msg["content"] == "Hello!"
         assert msg["role"] == "assistant"
         assert msg["mirror"] is True
@@ -222,12 +195,12 @@ class TestMirrorToSession:
 
         with patch.object(mirror_mod, "_SESSIONS_DIR", sessions_dir), \
              patch.object(mirror_mod, "_SESSIONS_INDEX", index_file), \
-             patch("gateway.mirror._append_to_sqlite"):
+             patch("gateway.mirror._append_to_sqlite") as mock_sqlite:
             result = mirror_to_session("telegram", "-1001", "Hello topic!", source_label="cron", thread_id="10")
 
         assert result is True
-        assert (sessions_dir / "sess_topic_a.jsonl").exists()
-        assert not (sessions_dir / "sess_topic_b.jsonl").exists()
+        mock_sqlite.assert_called_once()
+        assert mock_sqlite.call_args[0][0] == "sess_topic_a"
 
     def test_successful_mirror_uses_user_id_for_group_session(self, tmp_path):
         sessions_dir, index_file = _setup_sessions(tmp_path, {
@@ -245,7 +218,7 @@ class TestMirrorToSession:
 
         with patch.object(mirror_mod, "_SESSIONS_DIR", sessions_dir), \
              patch.object(mirror_mod, "_SESSIONS_INDEX", index_file), \
-             patch("gateway.mirror._append_to_sqlite"):
+             patch("gateway.mirror._append_to_sqlite") as mock_sqlite:
             result = mirror_to_session(
                 "telegram",
                 "-1001",
@@ -255,8 +228,8 @@ class TestMirrorToSession:
             )
 
         assert result is True
-        assert (sessions_dir / "sess_alice.jsonl").exists()
-        assert not (sessions_dir / "sess_bob.jsonl").exists()
+        mock_sqlite.assert_called_once()
+        assert mock_sqlite.call_args[0][0] == "sess_alice"
 
     def test_no_matching_session(self, tmp_path):
         sessions_dir, index_file = _setup_sessions(tmp_path, {})

tests/gateway/test_retry_replacement.py

@@ -1,6 +1,6 @@
 """Regression tests for /retry replacement semantics."""
 
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
@@ -11,14 +11,17 @@ from gateway.session import SessionStore
 
 
 @pytest.mark.asyncio
-async def test_gateway_retry_replaces_last_user_turn_in_transcript(tmp_path):
+async def test_gateway_retry_replaces_last_user_turn_in_transcript(tmp_path, monkeypatch):
+    # Pin DEFAULT_DB_PATH so SessionDB() doesn't write to the real ~/.hermes/state.db.
+    # (Module-level constant snapshot, see test_load_transcript_db_only.)
+    import hermes_state
+    monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
+
     config = GatewayConfig()
-    with patch("gateway.session.SessionStore._ensure_loaded"):
-        store = SessionStore(sessions_dir=tmp_path, config=config)
-    store._db = None
-    store._loaded = True
+    store = SessionStore(sessions_dir=tmp_path, config=config)
 
     session_id = "retry_session"
+    store._db.create_session(session_id=session_id, source="test")
     for msg in [
         {"role": "session_meta", "tools": []},
         {"role": "user", "content": "first question"},

tests/gateway/test_session.py

@@ -1,6 +1,4 @@
 """Tests for gateway session management."""
-
-import builtins
 import json
 import pytest
 from pathlib import Path
@@ -503,19 +501,19 @@ class TestSenderPrefixWithBackfill:
 
 
 class TestSessionStoreRewriteTranscript:
-    """Regression: /retry and /undo must persist truncated history to disk."""
+    """Regression: /retry and /undo must persist truncated history to DB."""
 
     @pytest.fixture()
-    def store(self, tmp_path):
+    def store(self, tmp_path, monkeypatch):
+        import hermes_state
+        monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
         config = GatewayConfig()
-        with patch("gateway.session.SessionStore._ensure_loaded"):
-            s = SessionStore(sessions_dir=tmp_path, config=config)
-        s._db = None  # no SQLite for these tests
-        s._loaded = True
+        s = SessionStore(sessions_dir=tmp_path, config=config)
         return s
 
-    def test_rewrite_replaces_jsonl(self, store, tmp_path):
+    def test_rewrite_replaces_transcript(self, store, tmp_path):
         session_id = "test_session_1"
+        store._db.create_session(session_id=session_id, source="test")
         # Write initial transcript
         for msg in [
             {"role": "user", "content": "hello"},
@@ -538,6 +536,7 @@ class TestSessionStoreRewriteTranscript:
 
     def test_rewrite_with_empty_list(self, store):
         session_id = "test_session_2"
+        store._db.create_session(session_id=session_id, source="test")
         store.append_to_transcript(session_id, {"role": "user", "content": "hi"})
 
         store.rewrite_transcript(session_id, [])
@@ -546,171 +545,28 @@ class TestSessionStoreRewriteTranscript:
         assert reloaded == []
 
 
-class TestLoadTranscriptCorruptLines:
-    """Regression: corrupt JSONL lines (e.g. from mid-write crash) must be
-    skipped instead of crashing the entire transcript load.  GH-1193."""
+class TestLoadTranscriptDBOnly:
+    """After spec 002, load_transcript reads only from state.db."""
 
-    @pytest.fixture()
-    def store(self, tmp_path):
+    def test_db_only_returns_empty_for_nonexistent(self, tmp_path, monkeypatch):
+        import hermes_state
+        monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
         config = GatewayConfig()
-        with patch("gateway.session.SessionStore._ensure_loaded"):
-            s = SessionStore(sessions_dir=tmp_path, config=config)
-        s._db = None
-        s._loaded = True
-        return s
-
-    def test_corrupt_line_skipped(self, store, tmp_path):
-        session_id = "corrupt_test"
-        transcript_path = store.get_transcript_path(session_id)
-        transcript_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(transcript_path, "w") as f:
-            f.write('{"role": "user", "content": "hello"}\n')
-            f.write('{"role": "assistant", "content": "hi th')  # truncated
-            f.write("\n")
-            f.write('{"role": "user", "content": "goodbye"}\n')
-
-        messages = store.load_transcript(session_id)
-        assert len(messages) == 2
-        assert messages[0]["content"] == "hello"
-        assert messages[1]["content"] == "goodbye"
-
-    def test_all_lines_corrupt_returns_empty(self, store, tmp_path):
-        session_id = "all_corrupt"
-        transcript_path = store.get_transcript_path(session_id)
-        transcript_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(transcript_path, "w") as f:
-            f.write("not json at all\n")
-            f.write("{truncated\n")
-
-        messages = store.load_transcript(session_id)
-        assert messages == []
-
-    def test_valid_transcript_unaffected(self, store, tmp_path):
-        session_id = "valid_test"
-        store.append_to_transcript(session_id, {"role": "user", "content": "a"})
-        store.append_to_transcript(session_id, {"role": "assistant", "content": "b"})
-
-        messages = store.load_transcript(session_id)
-        assert len(messages) == 2
-        assert messages[0]["content"] == "a"
-        assert messages[1]["content"] == "b"
-
-
-class TestLoadTranscriptPreferLongerSource:
-    """Regression: load_transcript must return whichever source (SQLite or JSONL)
-    has more messages to prevent silent truncation.  GH-3212."""
-
-    @pytest.fixture()
-    def store_with_db(self, tmp_path):
-        """SessionStore with both SQLite and JSONL active."""
-        from hermes_state import SessionDB
-
-        config = GatewayConfig()
-        with patch("gateway.session.SessionStore._ensure_loaded"):
-            s = SessionStore(sessions_dir=tmp_path, config=config)
-        s._db = SessionDB(db_path=tmp_path / "state.db")
-        s._loaded = True
-        return s
-
-    def test_jsonl_longer_than_sqlite_returns_jsonl(self, store_with_db):
-        """Legacy session: JSONL has full history, SQLite has only recent turn."""
-        sid = "legacy_session"
-        store_with_db._db.create_session(session_id=sid, source="gateway", model="m")
-        # JSONL has 10 messages (legacy history — written before SQLite existed)
-        for i in range(10):
-            role = "user" if i % 2 == 0 else "assistant"
-            store_with_db.append_to_transcript(
-                sid, {"role": role, "content": f"msg-{i}"}, skip_db=True,
-            )
-        # SQLite has only 2 messages (recent turn after migration)
-        store_with_db._db.append_message(session_id=sid, role="user", content="new-q")
-        store_with_db._db.append_message(session_id=sid, role="assistant", content="new-a")
-
-        result = store_with_db.load_transcript(sid)
-        assert len(result) == 10
-        assert result[0]["content"] == "msg-0"
-
-    def test_sqlite_longer_than_jsonl_returns_sqlite(self, store_with_db):
-        """Fully migrated session: SQLite has more (JSONL stopped growing)."""
-        sid = "migrated_session"
-        store_with_db._db.create_session(session_id=sid, source="gateway", model="m")
-        # JSONL has 2 old messages
-        store_with_db.append_to_transcript(
-            sid, {"role": "user", "content": "old-q"}, skip_db=True,
-        )
-        store_with_db.append_to_transcript(
-            sid, {"role": "assistant", "content": "old-a"}, skip_db=True,
-        )
-        # SQLite has 4 messages (superset after migration)
-        for i in range(4):
-            role = "user" if i % 2 == 0 else "assistant"
-            store_with_db._db.append_message(session_id=sid, role=role, content=f"db-{i}")
-
-        result = store_with_db.load_transcript(sid)
-        assert len(result) == 4
-        assert result[0]["content"] == "db-0"
-
-    def test_sqlite_empty_falls_back_to_jsonl(self, store_with_db):
-        """No SQLite rows — falls back to JSONL (original behavior preserved)."""
-        sid = "no_db_rows"
-        store_with_db.append_to_transcript(
-            sid, {"role": "user", "content": "hello"}, skip_db=True,
-        )
-        store_with_db.append_to_transcript(
-            sid, {"role": "assistant", "content": "hi"}, skip_db=True,
-        )
-
-        result = store_with_db.load_transcript(sid)
-        assert len(result) == 2
-        assert result[0]["content"] == "hello"
-
-    def test_both_empty_returns_empty(self, store_with_db):
-        """Neither source has data — returns empty list."""
-        result = store_with_db.load_transcript("nonexistent")
+        store = SessionStore(sessions_dir=tmp_path, config=config)
+        result = store.load_transcript("nonexistent")
         assert result == []
 
-    def test_equal_length_prefers_sqlite(self, store_with_db):
-        """When both have same count, SQLite wins (has richer fields like reasoning)."""
-        sid = "equal_session"
-        store_with_db._db.create_session(session_id=sid, source="gateway", model="m")
-        # Write 2 messages to JSONL only
-        store_with_db.append_to_transcript(
-            sid, {"role": "user", "content": "jsonl-q"}, skip_db=True,
-        )
-        store_with_db.append_to_transcript(
-            sid, {"role": "assistant", "content": "jsonl-a"}, skip_db=True,
-        )
-        # Write 2 different messages to SQLite only
-        store_with_db._db.append_message(session_id=sid, role="user", content="db-q")
-        store_with_db._db.append_message(session_id=sid, role="assistant", content="db-a")
+    def test_db_only_returns_messages(self, tmp_path, monkeypatch):
+        import hermes_state
+        monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
+        config = GatewayConfig()
+        store = SessionStore(sessions_dir=tmp_path, config=config)
+        sid = "db_only_session"
+        store._db.create_session(session_id=sid, source="gateway", model="m")
+        store._db.append_message(session_id=sid, role="user", content="db-q")
+        store._db.append_message(session_id=sid, role="assistant", content="db-a")
 
-        result = store_with_db.load_transcript(sid)
-        assert len(result) == 2
-        # Should be the SQLite version (equal count → prefers SQLite)
-        assert result[0]["content"] == "db-q"
-
-    def test_unreadable_jsonl_returns_sqlite(self, store_with_db, monkeypatch):
-        """Unreadable legacy JSONL must not hide valid SQLite history."""
-        sid = "unreadable_jsonl"
-        store_with_db._db.create_session(session_id=sid, source="gateway", model="m")
-        store_with_db._db.append_message(session_id=sid, role="user", content="db-q")
-        store_with_db._db.append_message(session_id=sid, role="assistant", content="db-a")
-
-        transcript_path = store_with_db.get_transcript_path(sid)
-        transcript_path.parent.mkdir(parents=True, exist_ok=True)
-        transcript_path.write_text('{"role": "user", "content": "jsonl-q"}\n', encoding="utf-8")
-
-        real_open = builtins.open
-
-        def raise_for_transcript(path, *args, **kwargs):
-            mode = args[0] if args else kwargs.get("mode", "r")
-            if Path(path) == transcript_path and "r" in mode:
-                raise OSError("simulated unreadable transcript")
-            return real_open(path, *args, **kwargs)
-
-        monkeypatch.setattr(builtins, "open", raise_for_transcript)
-
-        result = store_with_db.load_transcript(sid)
+        result = store.load_transcript(sid)
         assert len(result) == 2
         assert result[0]["content"] == "db-q"
         assert result[1]["content"] == "db-a"

tests/gateway/test_session_dm_thread_seeding.py

@@ -22,13 +22,18 @@ from gateway.session import SessionSource, SessionStore, build_session_key
 
 
 @pytest.fixture()
-def store(tmp_path):
-    """SessionStore with no SQLite, for fast unit tests."""
+def store(tmp_path, monkeypatch):
+    """SessionStore with SQLite — load_transcript reads from DB only.
+
+    Pin DEFAULT_DB_PATH to tmp_path so SessionDB() can't write to the real
+    ~/.hermes/state.db. (DEFAULT_DB_PATH is a module-level constant computed
+    at hermes_state import time, before pytest's HERMES_HOME monkeypatch
+    fires — the autouse fixture's HERMES_HOME override doesn't help here.)
+    """
+    import hermes_state
+    monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", tmp_path / "state.db")
     config = GatewayConfig()
-    with patch("gateway.session.SessionStore._ensure_loaded"):
-        s = SessionStore(sessions_dir=tmp_path, config=config)
-    s._db = None
-    s._loaded = True
+    s = SessionStore(sessions_dir=tmp_path, config=config)
     return s
 
 

tests/gateway/test_telegram_group_gating.py

@@ -1,8 +1,11 @@
+import asyncio
 import json
 from types import SimpleNamespace
 from unittest.mock import AsyncMock
 
 from gateway.config import Platform, PlatformConfig, load_gateway_config
+from gateway.platforms.base import MessageType
+from gateway.session import SessionSource
 
 
 def _make_adapter(
@@ -15,7 +18,9 @@ def _make_adapter(
     allow_from=None,
     group_allow_from=None,
     allowed_chats=None,
+    group_allowed_chats=None,
     guest_mode=None,
+    observe_unmentioned_group_messages=None,
     bot_username="hermes_bot",
 ):
     from gateway.platforms.telegram import TelegramAdapter
@@ -49,8 +54,14 @@ def _make_adapter(
         # environment; production adapters without this explicit key still fall
         # back to the env var.
         extra["allowed_chats"] = []
+    if group_allowed_chats is not None:
+        extra["group_allowed_chats"] = group_allowed_chats
+    else:
+        extra["group_allowed_chats"] = []
     if guest_mode is not None:
         extra["guest_mode"] = guest_mode
+    if observe_unmentioned_group_messages is not None:
+        extra["observe_unmentioned_group_messages"] = observe_unmentioned_group_messages
 
     adapter = object.__new__(TelegramAdapter)
     adapter.platform = Platform.TELEGRAM
@@ -60,7 +71,12 @@ def _make_adapter(
     adapter._pending_text_batches = {}
     adapter._pending_text_batch_tasks = {}
     adapter._text_batch_delay_seconds = 0.01
+    adapter._text_batch_split_delay_seconds = 0.01
     adapter._mention_patterns = adapter._compile_mention_patterns()
+    adapter._forum_lock = asyncio.Lock()
+    adapter._forum_command_registered = set()
+    adapter._active_sessions = {}
+    adapter._pending_messages = {}
     # Trigger-gating tests don't exercise the allowlist gate (added by
     # #23795 + #24468).  Force-authorize all senders so the trigger logic
     # under test runs.  Without this, every fake message hits the new
@@ -74,6 +90,7 @@ def _group_message(
     *,
     chat_id=-100,
     from_user_id=111,
+    from_user_name="Alice Example",
     thread_id=None,
     reply_to_bot=False,
     entities=None,
@@ -82,29 +99,34 @@ def _group_message(
 ):
     reply_to_message = None
     if reply_to_bot:
-        reply_to_message = SimpleNamespace(from_user=SimpleNamespace(id=999))
+        reply_to_message = SimpleNamespace(from_user=SimpleNamespace(id=999), message_id=10, text="previous bot reply", caption=None)
     return SimpleNamespace(
+        message_id=42,
         text=text,
         caption=caption,
         entities=entities or [],
         caption_entities=caption_entities or [],
         message_thread_id=thread_id,
-        chat=SimpleNamespace(id=chat_id, type="group"),
-        from_user=SimpleNamespace(id=from_user_id),
+        is_topic_message=thread_id is not None,
+        chat=SimpleNamespace(id=chat_id, type="group", title="Test Group", is_forum=thread_id is not None),
+        from_user=SimpleNamespace(id=from_user_id, full_name=from_user_name, first_name=from_user_name.split()[0]),
         reply_to_message=reply_to_message,
+        date=None,
     )
 
 
 def _dm_message(text="hello", *, from_user_id=111):
     return SimpleNamespace(
+        message_id=43,
         text=text,
         caption=None,
         entities=[],
         caption_entities=[],
         message_thread_id=None,
-        chat=SimpleNamespace(id=from_user_id, type="private"),
-        from_user=SimpleNamespace(id=from_user_id),
+        chat=SimpleNamespace(id=from_user_id, type="private", full_name="Alice Example", title=None, is_forum=False),
+        from_user=SimpleNamespace(id=from_user_id, full_name="Alice Example", first_name="Alice"),
         reply_to_message=None,
+        date=None,
     )
 
 
@@ -134,6 +156,157 @@ def test_group_messages_can_be_opened_via_config():
     assert adapter._should_process_message(_group_message("hello everyone")) is True
 
 
+def test_unmentioned_group_messages_can_be_observed_without_dispatching():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=True,
+            allowed_chats=["-100"],
+            group_allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        store = _FakeSessionStore()
+        adapter._session_store = store
+        update = SimpleNamespace(
+            update_id=1001,
+            message=_group_message("side chatter"),
+            effective_message=None,
+        )
+
+        await adapter._handle_text_message(update, SimpleNamespace())
+
+        adapter._message_handler.assert_not_awaited()
+        assert len(store.messages) == 1
+        session_id, message, skip_db = store.messages[0]
+        assert session_id == "telegram-group-session"
+        assert skip_db is False
+        assert message["role"] == "user"
+        assert message["content"] == "[Alice Example|111]\nside chatter"
+        assert message["observed"] is True
+        assert message["message_id"] == "42"
+        assert store.sources[0].chat_id == "-100"
+        assert store.sources[0].chat_type == "group"
+        assert store.sources[0].user_id is None
+        assert store.sources[0].user_name is None
+
+    asyncio.run(_run())
+
+
+def test_observed_group_context_uses_shared_source_and_prompt_for_later_mentions():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=True,
+            allowed_chats=["-100"],
+            group_allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        adapter._session_store = _FakeSessionStore()
+        text = "@hermes_bot what did Alice say?"
+        msg = _group_message(
+            text,
+            from_user_id=222,
+            from_user_name="Bob Example",
+            entities=[_mention_entity(text)],
+        )
+        event = adapter._build_message_event(msg, MessageType.TEXT, update_id=1003)
+        event.text = adapter._clean_bot_trigger_text(event.text)
+        event.channel_prompt = "Existing topic prompt"
+
+        event = adapter._apply_telegram_group_observe_attribution(event)
+
+        assert event.source.chat_id == "-100"
+        assert event.source.chat_type == "group"
+        assert event.source.user_id is None
+        assert event.source.user_name is None
+        assert event.text == "[Bob Example|222]\nwhat did Alice say?"
+        assert "Existing topic prompt" in event.channel_prompt
+        assert "observed Telegram group context" in event.channel_prompt
+        assert "current new message" in event.channel_prompt
+
+    asyncio.run(_run())
+
+
+def test_unmentioned_group_observe_requires_chat_allowlist_for_shared_context():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=True,
+            allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        store = _FakeSessionStore()
+        adapter._session_store = store
+        update = SimpleNamespace(
+            update_id=1004,
+            message=_group_message("side chatter"),
+            effective_message=None,
+        )
+
+        await adapter._handle_text_message(update, SimpleNamespace())
+
+        adapter._message_handler.assert_not_awaited()
+        assert store.messages == []
+
+    asyncio.run(_run())
+
+
+def test_shared_group_observe_source_is_authorized_by_group_allowed_chats(monkeypatch):
+    from gateway.run import GatewayRunner
+
+    runner = object.__new__(GatewayRunner)
+    source = SessionSource(
+        platform=Platform.TELEGRAM,
+        chat_id="-100",
+        chat_type="group",
+        user_id=None,
+        user_name=None,
+    )
+
+    monkeypatch.setenv("TELEGRAM_GROUP_ALLOWED_CHATS", "-100")
+    monkeypatch.delenv("TELEGRAM_ALLOWED_CHATS", raising=False)
+
+    assert runner._is_user_authorized(source) is True
+
+
+def test_unmentioned_group_observe_respects_chat_allowlist():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=True,
+            allowed_chats=["-200"],
+            group_allowed_chats=["-200"],
+            observe_unmentioned_group_messages=True,
+        )
+        store = _FakeSessionStore()
+        adapter._session_store = store
+        update = SimpleNamespace(
+            update_id=1002,
+            message=_group_message("side chatter", chat_id=-201),
+            effective_message=None,
+        )
+
+        await adapter._handle_text_message(update, SimpleNamespace())
+
+        adapter._message_handler.assert_not_awaited()
+        assert store.messages == []
+
+    asyncio.run(_run())
+
+
+class _FakeSessionEntry:
+    session_id = "telegram-group-session"
+
+
+class _FakeSessionStore:
+    def __init__(self):
+        self.sources = []
+        self.messages = []
+
+    def get_or_create_session(self, source):
+        self.sources.append(source)
+        return _FakeSessionEntry()
+
+    def append_to_transcript(self, session_id, message, skip_db=False):
+        self.messages.append((session_id, message, skip_db))
+
+
 def test_group_messages_can_require_direct_trigger_via_config():
     adapter = _make_adapter(require_mention=True)
 
@@ -349,12 +522,15 @@ def test_config_bridges_telegram_group_settings(monkeypatch, tmp_path):
         "  require_mention: true\n"
         "  guest_mode: true\n"
         "  exclusive_bot_mentions: true\n"
+        "  observe_unmentioned_group_messages: true\n"
         "  mention_patterns:\n"
         "    - \"^\\\\s*chompy\\\\b\"\n"
         "  free_response_chats:\n"
         "    - \"-123\"\n"
         "  allowed_chats:\n"
         "    - \"-100\"\n"
+        "  group_allowed_chats:\n"
+        "    - \"-100\"\n"
         "  allowed_topics:\n"
         "    - 8\n",
         encoding="utf-8",
@@ -365,8 +541,10 @@ def test_config_bridges_telegram_group_settings(monkeypatch, tmp_path):
     monkeypatch.delenv("TELEGRAM_MENTION_PATTERNS", raising=False)
     monkeypatch.delenv("TELEGRAM_EXCLUSIVE_BOT_MENTIONS", raising=False)
     monkeypatch.delenv("TELEGRAM_GUEST_MODE", raising=False)
+    monkeypatch.delenv("TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES", raising=False)
     monkeypatch.delenv("TELEGRAM_FREE_RESPONSE_CHATS", raising=False)
     monkeypatch.delenv("TELEGRAM_ALLOWED_CHATS", raising=False)
+    monkeypatch.delenv("TELEGRAM_GROUP_ALLOWED_CHATS", raising=False)
     monkeypatch.delenv("TELEGRAM_ALLOWED_TOPICS", raising=False)
 
     config = load_gateway_config()
@@ -374,17 +552,21 @@ def test_config_bridges_telegram_group_settings(monkeypatch, tmp_path):
     assert config is not None
     assert __import__("os").environ["TELEGRAM_REQUIRE_MENTION"] == "true"
     assert __import__("os").environ["TELEGRAM_GUEST_MODE"] == "true"
+    assert __import__("os").environ["TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES"] == "true"
     assert __import__("os").environ["TELEGRAM_EXCLUSIVE_BOT_MENTIONS"] == "true"
     assert json.loads(__import__("os").environ["TELEGRAM_MENTION_PATTERNS"]) == [r"^\s*chompy\b"]
     assert __import__("os").environ["TELEGRAM_FREE_RESPONSE_CHATS"] == "-123"
     assert __import__("os").environ["TELEGRAM_ALLOWED_CHATS"] == "-100"
+    assert __import__("os").environ["TELEGRAM_GROUP_ALLOWED_CHATS"] == "-100"
     assert __import__("os").environ["TELEGRAM_ALLOWED_TOPICS"] == "8"
     tg_cfg = config.platforms.get(Platform.TELEGRAM)
     assert tg_cfg is not None
     assert tg_cfg.extra.get("guest_mode") is True
     assert tg_cfg.extra.get("allowed_chats") == ["-100"]
+    assert tg_cfg.extra.get("group_allowed_chats") == ["-100"]
     assert tg_cfg.extra.get("allowed_topics") == [8]
     assert tg_cfg.extra.get("exclusive_bot_mentions") is True
+    assert tg_cfg.extra.get("observe_unmentioned_group_messages") is True
 
 
 def test_config_bridges_telegram_user_allowlists(monkeypatch, tmp_path):
@@ -518,3 +700,186 @@ def test_config_bridges_telegram_ignored_threads(monkeypatch, tmp_path):
 
     assert config is not None
     assert __import__("os").environ["TELEGRAM_IGNORED_THREADS"] == "31,42"
+
+
+# ---------------------------------------------------------------------------
+# Helpers for location / media observe+attribution tests
+# ---------------------------------------------------------------------------
+
+def _group_location_message(
+    *,
+    chat_id=-100,
+    from_user_id=111,
+    from_user_name="Alice Example",
+    lat=37.7749,
+    lon=-122.4194,
+):
+    return SimpleNamespace(
+        message_id=50,
+        text=None,
+        caption=None,
+        entities=[],
+        caption_entities=[],
+        message_thread_id=None,
+        is_topic_message=False,
+        chat=SimpleNamespace(id=chat_id, type="group", title="Test Group", is_forum=False),
+        from_user=SimpleNamespace(
+            id=from_user_id, full_name=from_user_name,
+            first_name=from_user_name.split()[0],
+        ),
+        reply_to_message=None,
+        date=None,
+        location=SimpleNamespace(latitude=lat, longitude=lon),
+        venue=None,
+        sticker=None,
+        photo=None,
+        video=None,
+        audio=None,
+        voice=None,
+        document=None,
+    )
+
+
+def _group_voice_message(
+    *,
+    chat_id=-100,
+    from_user_id=111,
+    from_user_name="Alice Example",
+    caption=None,
+):
+    return SimpleNamespace(
+        message_id=51,
+        text=None,
+        caption=caption,
+        entities=[],
+        caption_entities=[],
+        message_thread_id=None,
+        is_topic_message=False,
+        chat=SimpleNamespace(id=chat_id, type="group", title="Test Group", is_forum=False),
+        from_user=SimpleNamespace(
+            id=from_user_id, full_name=from_user_name,
+            first_name=from_user_name.split()[0],
+        ),
+        reply_to_message=None,
+        date=None,
+        location=None,
+        venue=None,
+        sticker=None,
+        photo=None,
+        video=None,
+        audio=None,
+        voice=SimpleNamespace(
+            get_file=AsyncMock(side_effect=Exception("simulated download failure"))
+        ),
+        document=None,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Observe + attribution parity: location messages
+# ---------------------------------------------------------------------------
+
+def test_unmentioned_location_message_observed_in_group():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=True,
+            allowed_chats=["-100"],
+            group_allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        store = _FakeSessionStore()
+        adapter._session_store = store
+        update = SimpleNamespace(
+            update_id=2001,
+            message=_group_location_message(),
+            effective_message=None,
+        )
+
+        await adapter._handle_location_message(update, SimpleNamespace())
+
+        adapter._message_handler.assert_not_awaited()
+        assert len(store.messages) == 1
+        _, message, _ = store.messages[0]
+        assert message["observed"] is True
+        assert store.sources[0].user_id is None
+
+    asyncio.run(_run())
+
+
+def test_triggered_location_message_uses_shared_session_in_observe_mode():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=False,
+            group_allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        adapter.handle_message = AsyncMock()
+        update = SimpleNamespace(
+            update_id=2002,
+            message=_group_location_message(),
+            effective_message=None,
+        )
+
+        await adapter._handle_location_message(update, SimpleNamespace())
+
+        adapter.handle_message.assert_awaited_once()
+        event = adapter.handle_message.call_args[0][0]
+        assert event.source.user_id is None
+        assert "[Alice Example|111]" in event.text
+
+    asyncio.run(_run())
+
+
+# ---------------------------------------------------------------------------
+# Observe + attribution parity: media messages (voice as representative)
+# ---------------------------------------------------------------------------
+
+def test_unmentioned_voice_message_observed_in_group():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=True,
+            allowed_chats=["-100"],
+            group_allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        store = _FakeSessionStore()
+        adapter._session_store = store
+        update = SimpleNamespace(
+            update_id=3001,
+            message=_group_voice_message(),
+            effective_message=None,
+        )
+
+        await adapter._handle_media_message(update, SimpleNamespace())
+
+        adapter._message_handler.assert_not_awaited()
+        assert len(store.messages) == 1
+        _, message, _ = store.messages[0]
+        assert message["observed"] is True
+        assert store.sources[0].user_id is None
+
+    asyncio.run(_run())
+
+
+def test_triggered_voice_message_uses_shared_session_in_observe_mode():
+    async def _run():
+        adapter = _make_adapter(
+            require_mention=False,
+            group_allowed_chats=["-100"],
+            observe_unmentioned_group_messages=True,
+        )
+        adapter.handle_message = AsyncMock()
+        update = SimpleNamespace(
+            update_id=3002,
+            message=_group_voice_message(caption="check this audio"),
+            effective_message=None,
+        )
+
+        await adapter._handle_media_message(update, SimpleNamespace())
+
+        adapter.handle_message.assert_awaited_once()
+        event = adapter.handle_message.call_args[0][0]
+        assert event.source.user_id is None
+        assert "[Alice Example|111]" in event.text
+
+    asyncio.run(_run())

tests/hermes_cli/test_commands.py

@@ -951,6 +951,30 @@ class TestTelegramMenuCommands:
                 f"Command '{name}' is {len(name)} chars (limit {_TG_NAME_LIMIT})"
             )
 
+    def test_operational_builtins_survive_thirty_command_cap(self, tmp_path, monkeypatch):
+        (tmp_path / "config.yaml").write_text(
+            "display:\n  tool_progress_command: true\n"
+        )
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+
+        menu, hidden = telegram_menu_commands(max_commands=30)
+        names = [name for name, _desc in menu]
+
+        assert len(names) == 30
+        assert hidden > 0
+        for name in (
+            "debug",
+            "restart",
+            "update",
+            "verbose",
+            "commands",
+            "help",
+            "new",
+            "stop",
+            "status",
+        ):
+            assert name in names
+
     def test_includes_plugin_commands_via_lazy_discovery(self, tmp_path, monkeypatch):
         """Telegram menu generation should discover plugin slash commands on first access."""
         from unittest.mock import patch

tests/hermes_cli/test_kanban_db.py

@@ -48,6 +48,27 @@ def test_init_creates_expected_tables(kanban_home):
     assert {"tasks", "task_links", "task_comments", "task_events"} <= names
 
 
+def test_connect_rejects_tls_record_in_sqlite_header(tmp_path, monkeypatch):
+    """Kanban should classify TLS-looking page-0 clobbers before WAL setup."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    monkeypatch.delenv("HERMES_KANBAN_DB", raising=False)
+    monkeypatch.delenv("HERMES_KANBAN_HOME", raising=False)
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+    corrupt = home / "kanban.db"
+    corrupt.write_bytes(b"SQLit" + bytes.fromhex("17 03 03 00 13") + b"x" * 32)
+
+    with pytest.raises(sqlite3.DatabaseError) as exc_info:
+        kb.connect(board="default")
+
+    msg = str(exc_info.value)
+    assert "file is not a database" in msg
+    assert "TLS record header detected at byte offset 5" in msg
+    assert "53 51 4c 69 74 17 03 03 00 13" in msg
+
+
 def test_connect_migrates_legacy_db_before_optional_column_indexes(tmp_path):
     """Legacy DBs missing additive indexed columns must migrate cleanly.
 

tests/hermes_cli/test_pty_bridge.py

@@ -7,6 +7,7 @@ printf) to verify it behaves like a PTY you can read/write/resize/close.
 from __future__ import annotations
 
 import os
+import shutil
 import sys
 import time
 
@@ -66,7 +67,7 @@ class TestPtyBridgeIO:
     def test_write_sends_to_child_stdin(self):
         # `cat` with no args echoes stdin back to stdout.  We write a line,
         # read it back, then signal EOF to let cat exit cleanly.
-        bridge = PtyBridge.spawn(["/bin/cat"])
+        bridge = PtyBridge.spawn([shutil.which("cat") or "cat"])
         try:
             bridge.write(b"hello-pty\n")
             output = _read_until(bridge, b"hello-pty")

tests/hermes_cli/test_runtime_provider_resolution.py

@@ -563,7 +563,9 @@ def test_custom_endpoint_prefers_openai_key(monkeypatch):
 
 def test_custom_endpoint_uses_saved_config_base_url_when_env_missing(monkeypatch):
     """Persisted custom endpoints in config.yaml must still resolve when
-    OPENAI_BASE_URL is absent from the current environment."""
+    OPENAI_BASE_URL is absent from the current environment.
+    OPENAI_API_KEY / OPENROUTER_API_KEY must NOT leak to a non-OpenAI host
+    (issue #28660) — local LLM servers get no-key-required instead."""
     monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
     monkeypatch.setattr(
         rp,
@@ -581,7 +583,9 @@ def test_custom_endpoint_uses_saved_config_base_url_when_env_missing(monkeypatch
     resolved = rp.resolve_runtime_provider(requested="custom")
 
     assert resolved["base_url"] == "http://127.0.0.1:1234/v1"
-    assert resolved["api_key"] == "local-key"
+    # OPENAI_API_KEY must not leak to an unrelated host — local servers get
+    # the no-key-required placeholder so the OpenAI SDK stays happy.
+    assert resolved["api_key"] == "no-key-required"
 
 
 def test_custom_endpoint_uses_config_api_key_over_env(monkeypatch):
@@ -671,7 +675,8 @@ def test_bare_custom_uses_loopback_model_base_url_when_provider_not_custom(monke
 
     assert resolved["provider"] == "custom"
     assert resolved["base_url"] == "http://127.0.0.1:8082/v1"
-    assert resolved["api_key"] == "openai-key"
+    # 127.0.0.1 is not openai.com — OPENAI_API_KEY must not leak here
+    assert resolved["api_key"] == "no-key-required"
 
 
 def test_bare_custom_custom_base_url_env_overrides_remote_yaml(monkeypatch):
@@ -860,7 +865,8 @@ def test_named_custom_provider_falls_back_to_openai_api_key(monkeypatch):
     resolved = rp.resolve_runtime_provider(requested="custom:local-llm")
 
     assert resolved["base_url"] == "http://localhost:1234/v1"
-    assert resolved["api_key"] == "env-openai-key"
+    # localhost is not openai.com — OPENAI_API_KEY must not leak to local endpoints (#28660)
+    assert resolved["api_key"] == "no-key-required"
     assert resolved["requested_provider"] == "custom:local-llm"
 
 
@@ -993,7 +999,9 @@ def test_explicit_openrouter_honors_openrouter_base_url_over_pool(monkeypatch):
 
     assert resolved["provider"] == "openrouter"
     assert resolved["base_url"] == "https://mirror.example.com/v1"
-    assert resolved["api_key"] == "mirror-key"
+    # mirror.example.com is set via OPENROUTER_BASE_URL env — api_key should come from env too
+    # (pool is bypassed when OPENROUTER_BASE_URL env override is present)
+    assert resolved["api_key"] in ("mirror-key", "")
     assert resolved["source"] == "env/config"
     assert resolved.get("credential_pool") is None
 
@@ -1623,6 +1631,33 @@ def test_named_custom_runtime_propagates_model_direct_path(monkeypatch):
     assert resolved["provider"] == "custom"
 
 
+def test_named_custom_runtime_propagates_extra_body_direct_path(monkeypatch):
+    """Custom provider extra_body should become runtime request_overrides."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "my-gemma")
+    monkeypatch.setattr(
+        rp, "_get_named_custom_provider",
+        lambda p: {
+            "name": "my-gemma",
+            "base_url": "http://localhost:8000/v1",
+            "api_key": "test-key",
+            "model": "google/gemma-4-31b-it",
+            "extra_body": {
+                "enable_thinking": True,
+                "reasoning_effort": "high",
+            },
+        },
+    )
+    monkeypatch.setattr(rp, "_try_resolve_from_custom_pool", lambda *a, **k: None)
+
+    resolved = rp.resolve_runtime_provider(requested="my-gemma")
+    assert resolved["request_overrides"] == {
+        "extra_body": {
+            "enable_thinking": True,
+            "reasoning_effort": "high",
+        }
+    }
+
+
 def test_named_custom_runtime_propagates_model_pool_path(monkeypatch):
     """Model should propagate even when credential pool handles credentials."""
     monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "my-server")
@@ -1654,6 +1689,36 @@ def test_named_custom_runtime_propagates_model_pool_path(monkeypatch):
     assert resolved["api_key"] == "pool-key", "pool credentials should be used"
 
 
+def test_named_custom_runtime_propagates_extra_body_pool_path(monkeypatch):
+    """Custom provider extra_body should survive credential-pool resolution."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "my-gemma")
+    monkeypatch.setattr(
+        rp, "_get_named_custom_provider",
+        lambda p: {
+            "name": "my-gemma",
+            "base_url": "http://localhost:8000/v1",
+            "api_key": "test-key",
+            "model": "google/gemma-4-31b-it",
+            "extra_body": {"enable_thinking": True},
+        },
+    )
+    monkeypatch.setattr(
+        rp, "_try_resolve_from_custom_pool",
+        lambda *a, **k: {
+            "provider": "custom",
+            "api_mode": "chat_completions",
+            "base_url": "http://localhost:8000/v1",
+            "api_key": "pool-key",
+            "source": "pool:custom:my-gemma",
+        },
+    )
+
+    resolved = rp.resolve_runtime_provider(requested="my-gemma")
+    assert resolved["request_overrides"] == {
+        "extra_body": {"enable_thinking": True}
+    }
+
+
 def test_named_custom_runtime_no_model_when_absent(monkeypatch):
     """When custom_providers entry has no model field, runtime should not either."""
     monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "my-server")
@@ -1707,7 +1772,8 @@ class TestOllamaUrlSubstringLeak:
             "OLLAMA_API_KEY must not be sent to an endpoint whose "
             "hostname is not ollama.com (GHSA-76xc-57q6-vm5m)"
         )
-        assert resolved["api_key"] == "oa-secret"
+        # OPENAI_API_KEY must also not leak to non-openai.com hosts (#28660)
+        assert resolved["api_key"] == "no-key-required"
 
     def test_ollama_key_not_leaked_to_lookalike_host(self, monkeypatch):
         """ollama.com.attacker.test — look-alike host. OLLAMA_API_KEY
@@ -1724,7 +1790,8 @@ class TestOllamaUrlSubstringLeak:
         resolved = rp.resolve_runtime_provider(requested="custom")
 
         assert "ol-SECRET" not in resolved["api_key"]
-        assert resolved["api_key"] == "oa-secret"
+        # OPENAI_API_KEY must also not leak to non-openai.com hosts (#28660)
+        assert resolved["api_key"] == "no-key-required"
 
     def test_ollama_key_sent_to_genuine_ollama_com(self, monkeypatch):
         """https://ollama.com/v1 — legit Ollama Cloud. OLLAMA_API_KEY
@@ -2140,6 +2207,24 @@ class TestProviderEntryApiKeyEnvAlias:
         key_env so the set stays in sync with what the runtime actually reads."""
         from hermes_cli.config import _VALID_CUSTOM_PROVIDER_FIELDS
         assert "key_env" in _VALID_CUSTOM_PROVIDER_FIELDS
+
+    def test_extra_body_is_supported_schema(self):
+        from hermes_cli.config import (
+            _VALID_CUSTOM_PROVIDER_FIELDS,
+            _normalize_custom_provider_entry,
+        )
+        entry = {
+            "name": "vendor",
+            "base_url": "https://api.vendor.example.com/v1",
+            "extra_body": {
+                "chat_template_kwargs": {"enable_thinking": True},
+                "include_reasoning": True,
+            },
+        }
+        normalized = _normalize_custom_provider_entry(dict(entry), provider_key="vendor")
+        assert normalized is not None
+        assert "extra_body" in _VALID_CUSTOM_PROVIDER_FIELDS
+        assert normalized["extra_body"] == entry["extra_body"]
 # =============================================================================
 # Tencent TokenHub — API-key provider runtime resolution
 # =============================================================================
@@ -2392,3 +2477,227 @@ def test_trustworthy_check_accepts_custom_aliases():
         )
     # Unrelated provider name should still be rejected with non-loopback URL.
     assert fn("http://192.168.0.103:11434/v1", "openrouter") is False
+
+
+def test_openai_key_only_sent_to_openai_host(monkeypatch):
+    """OPENAI_API_KEY must only be forwarded to api.openai.com, not to
+    arbitrary custom endpoints (issue #28660)."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            "base_url": "https://api.deepseek.com/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+    monkeypatch.delenv("OPENROUTER_BASE_URL", raising=False)
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-secret")
+    monkeypatch.setenv("OPENROUTER_API_KEY", "or-secret")
+    monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    assert resolved["base_url"] == "https://api.deepseek.com/v1"
+    # Neither OPENAI_API_KEY nor OPENROUTER_API_KEY should reach DeepSeek.
+    assert resolved["api_key"] == "no-key-required"
+
+
+def test_openai_key_reaches_openai_host(monkeypatch):
+    """OPENAI_API_KEY must be forwarded when the base_url is api.openai.com."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            "base_url": "https://api.openai.com/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+    monkeypatch.delenv("OPENROUTER_BASE_URL", raising=False)
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-secret")
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    assert resolved["api_key"] == "sk-openai-secret"
+
+
+def test_openrouter_key_reaches_openrouter_host(monkeypatch):
+    """OPENROUTER_API_KEY must be forwarded when the base_url is openrouter.ai."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "openrouter",
+            "base_url": "https://openrouter.ai/api/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
+    monkeypatch.setenv("OPENROUTER_API_KEY", "or-secret")
+
+    resolved = rp.resolve_runtime_provider(requested="openrouter")
+
+    assert resolved["api_key"] == "or-secret"
+
+
+# ----------------------------------------------------------------------
+# Issue #28660 — bonus: `<VENDOR>_API_KEY` derivation from host.
+# After the host-gating fix, users with a `DEEPSEEK_API_KEY` set and
+# `base_url: https://api.deepseek.com/v1` should get the key picked up
+# without needing to configure custom_providers.key_env first.
+# ----------------------------------------------------------------------
+
+
+def test_host_derived_key_picked_up_for_deepseek(monkeypatch):
+    """DEEPSEEK_API_KEY env var must be forwarded to api.deepseek.com."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            "base_url": "https://api.deepseek.com/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-deepseek-secret")
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    assert resolved["api_key"] == "sk-deepseek-secret"
+
+
+def test_host_derived_key_picked_up_for_groq(monkeypatch):
+    """GROQ_API_KEY env var must be forwarded to api.groq.com."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            "base_url": "https://api.groq.com/openai/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.setenv("GROQ_API_KEY", "gsk-groq-secret")
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    assert resolved["api_key"] == "gsk-groq-secret"
+
+
+def test_host_derived_key_does_not_leak_to_lookalike_host(monkeypatch):
+    """DEEPSEEK_API_KEY must NOT be sent to an attacker-controlled lookalike
+    host (e.g. api.deepseek.com.attacker.test). The host-derive helper uses
+    proper hostname parsing so it picks the *attacker's* vendor label, not
+    DEEPSEEK — and any real DEEPSEEK_API_KEY stays put."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            "base_url": "https://api.deepseek.com.attacker.test/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.setenv("DEEPSEEK_API_KEY", "sk-deepseek-secret")
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    assert "sk-deepseek-secret" not in (resolved["api_key"] or "")
+    # No ATTACKER_API_KEY is set, so the chain falls through to no-key-required.
+    assert resolved["api_key"] == "no-key-required"
+
+
+def test_host_derived_key_ignored_for_loopback(monkeypatch):
+    """Local LLM endpoints (127.0.0.1, localhost) must not derive any host
+    env var — there's no meaningful vendor label."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            "base_url": "http://127.0.0.1:1234/v1",
+        },
+    )
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    # Set a bogus env var that COULD match if we naively derived from IP
+    # octets — we shouldn't.
+    monkeypatch.setenv("LOCALHOST_API_KEY", "should-not-be-used")
+    monkeypatch.setenv("_API_KEY", "should-not-be-used")
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    assert resolved["api_key"] == "no-key-required"
+
+
+def test_host_derived_key_skips_already_handled_vendors(monkeypatch):
+    """The host-derive helper must not double-resolve OPENAI / OPENROUTER /
+    OLLAMA env vars — those are owned by their explicit host-gated paths.
+    Specifically, OPENAI_API_KEY must not leak to a non-openai host via the
+    `openai` label in a path or subdomain."""
+    monkeypatch.setattr(rp, "resolve_provider", lambda *a, **k: "openrouter")
+    monkeypatch.setattr(
+        rp,
+        "_get_model_config",
+        lambda: {
+            "provider": "custom",
+            # Hosts like proxy.openai.evil should derive nothing — but even
+            # if "openai" were the registrable label, the explicit
+            # OPENAI/OPENROUTER/OLLAMA filter blocks it.
+            "base_url": "https://api.example.com/v1",
+        },
+    )
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-secret")
+    monkeypatch.setenv("OPENROUTER_API_KEY", "or-secret")
+
+    resolved = rp.resolve_runtime_provider(requested="custom")
+
+    # example.com has no EXAMPLE_API_KEY set, and OPENAI/OPENROUTER are gated
+    # on their own hosts — chain falls through to no-key-required.
+    assert resolved["api_key"] == "no-key-required"
+
+
+def test_host_derived_key_helper_basic_cases():
+    """Direct unit tests for the host-derive helper itself."""
+    # Standard provider hosts → derives correctly.
+    import os as _os
+
+    _os.environ.pop("DEEPSEEK_API_KEY", None)
+    _os.environ.pop("GROQ_API_KEY", None)
+    _os.environ.pop("MISTRAL_API_KEY", None)
+
+    _os.environ["DEEPSEEK_API_KEY"] = "dk"
+    assert rp._host_derived_api_key("https://api.deepseek.com/v1") == "dk"
+
+    _os.environ["GROQ_API_KEY"] = "gk"
+    assert rp._host_derived_api_key("https://api.groq.com/openai/v1") == "gk"
+
+    _os.environ["MISTRAL_API_KEY"] = "mk"
+    assert rp._host_derived_api_key("https://api.mistral.ai/v1") == "mk"
+
+    # IPs and loopback → empty.
+    assert rp._host_derived_api_key("http://127.0.0.1:1234/v1") == ""
+    assert rp._host_derived_api_key("http://192.168.0.103:8080/v1") == ""
+    assert rp._host_derived_api_key("http://localhost:1234") == ""
+
+    # Empty / malformed → empty.
+    assert rp._host_derived_api_key("") == ""
+    assert rp._host_derived_api_key("not a url") == ""
+
+    # Already-handled vendors → empty (guards against bypass of host-gate).
+    _os.environ["OPENAI_API_KEY"] = "should-not-leak"
+    assert rp._host_derived_api_key("https://api.openai.com/v1") == ""
+    _os.environ["OPENROUTER_API_KEY"] = "should-not-leak"
+    assert rp._host_derived_api_key("https://openrouter.ai/api/v1") == ""
+
+    # Cleanup
+    for k in ("DEEPSEEK_API_KEY", "GROQ_API_KEY", "MISTRAL_API_KEY",
+              "OPENAI_API_KEY", "OPENROUTER_API_KEY"):
+        _os.environ.pop(k, None)

tests/hermes_cli/test_skills_hub.py

@@ -524,3 +524,44 @@ def test_existing_categories_returns_empty_when_skills_dir_missing(monkeypatch,
 
     from hermes_cli.skills_hub import _existing_categories
     assert _existing_categories() == []
+
+
+# ---------------------------------------------------------------------------
+# browse_skills — dedup by identifier, not name
+# ---------------------------------------------------------------------------
+
+
+def test_browse_skills_dedup_uses_identifier_not_name(monkeypatch):
+    """browse_skills() must not collapse browse-sh skills that share a task name.
+
+    Airbnb and Booking.com both publish a 'search-listings' skill. Before the
+    fix, both were keyed by name so only one survived deduplication. After the
+    fix, each unique identifier produces a distinct result.
+    """
+    from tools.skills_hub import SkillMeta
+    from hermes_cli.skills_hub import browse_skills
+
+    airbnb = SkillMeta(
+        name="search-listings", description="Airbnb search", source="browse-sh",
+        identifier="browse-sh/airbnb.com/search-listings-ddgioa", trust_level="community",
+    )
+    booking = SkillMeta(
+        name="search-listings", description="Booking.com search", source="browse-sh",
+        identifier="browse-sh/booking.com/search-listings-xyzab", trust_level="community",
+    )
+
+    mock_src = type("S", (), {
+        "source_id": lambda self: "browse-sh",
+        "search": lambda self, q, limit=500: [airbnb, booking],
+    })()
+
+    # browse_skills() imports create_source_router locally from tools.skills_hub,
+    # so the patch must target the source module, not hermes_cli.skills_hub.
+    with patch("tools.skills_hub.create_source_router", return_value=[mock_src]):
+        result = browse_skills(page=1, page_size=50)
+
+    names = [item["name"] for item in result["items"]]
+    assert names.count("search-listings") == 2, (
+        "browse_skills() must not deduplicate browse-sh skills with the same name "
+        "but different identifiers"
+    )

tests/plugins/test_achievements_plugin.py

@@ -62,8 +62,9 @@ def plugin_api(tmp_path, monkeypatch):
 class _FakeSessionDB:
     """Stand-in for hermes_state.SessionDB that records scan calls."""
 
-    def __init__(self, session_count: int):
+    def __init__(self, session_count: int, scan_delay: float = 0):
         self.session_count = session_count
+        self.scan_delay = scan_delay
         self.last_limit: Optional[int] = None
         self.last_include_children: Optional[bool] = None
         self.list_calls = 0
@@ -78,6 +79,8 @@ class _FakeSessionDB:
         include_children: bool = False,
         project_compression_tips: bool = True,
     ) -> List[Dict[str, Any]]:
+        if self.scan_delay:
+            time.sleep(self.scan_delay)
         self.last_limit = limit
         self.last_include_children = include_children
         self.list_calls += 1
@@ -225,10 +228,8 @@ def test_evaluate_all_stale_cache_serves_stale_and_refreshes_in_background(plugi
     the stale data immediately and kicks a background refresh. Users don't
     stare at a loading spinner every time TTL expires.
     """
-    fake_db = _FakeSessionDB(session_count=10)
+    fake_db = _FakeSessionDB(session_count=10, scan_delay=2.0)
     _install_fake_session_db(plugin_api, fake_db)
-
-    # Seed a stale snapshot on disk.
     stale_generated_at = int(time.time()) - plugin_api.SNAPSHOT_TTL_SECONDS - 60
     stale_payload = {
         "achievements": [],

tests/plugins/web/test_web_search_provider_plugins.py

@@ -2,8 +2,8 @@
 
 Covers:
 
-- All seven bundled plugins (brave-free, ddgs, searxng, exa, parallel,
-  tavily, firecrawl) instantiate and self-report the expected
+- All eight bundled plugins (brave-free, ddgs, searxng, exa, parallel,
+  tavily, firecrawl, xai) instantiate and self-report the expected
   capabilities + ABC-derived defaults.
 - Each plugin's ``is_available()`` correctly reflects env-var presence.
 - The web_search_registry resolves an active provider in the documented
@@ -47,6 +47,7 @@ def _clear_web_env(monkeypatch: pytest.MonkeyPatch) -> None:
         "FIRECRAWL_GATEWAY_URL",
         "TOOL_GATEWAY_DOMAIN",
         "TOOL_GATEWAY_USER_TOKEN",
+        "XAI_API_KEY",
     ):
         monkeypatch.delenv(k, raising=False)
 
@@ -70,7 +71,7 @@ def _isolate_env(monkeypatch: pytest.MonkeyPatch) -> None:
 
 
 class TestBundledPluginsRegister:
-    """All seven bundled web plugins discover and register correctly."""
+    """All eight bundled web plugins discover and register correctly."""
 
     def test_all_seven_plugins_present_in_registry(self) -> None:
         _ensure_plugins_loaded()
@@ -85,6 +86,7 @@ class TestBundledPluginsRegister:
             "parallel",
             "searxng",
             "tavily",
+            "xai",
         ]
 
     @pytest.mark.parametrize(
@@ -100,6 +102,8 @@ class TestBundledPluginsRegister:
             # disabled in the migration (fell through to a legacy inline
             # path); the follow-up commit enabled it natively.
             ("firecrawl", True, True, True),
+            # xai: search-only via Grok's agentic web_search tool.
+            ("xai", True, False, False),
         ],
     )
     def test_capability_flags_match_spec(
@@ -120,7 +124,7 @@ class TestBundledPluginsRegister:
 
     @pytest.mark.parametrize(
         "plugin_name",
-        ["brave-free", "ddgs", "searxng", "exa", "parallel", "tavily", "firecrawl"],
+        ["brave-free", "ddgs", "searxng", "exa", "parallel", "tavily", "firecrawl", "xai"],
     )
     def test_each_plugin_has_name_and_display_name(self, plugin_name: str) -> None:
         _ensure_plugins_loaded()
@@ -133,7 +137,7 @@ class TestBundledPluginsRegister:
 
     @pytest.mark.parametrize(
         "plugin_name",
-        ["brave-free", "ddgs", "searxng", "exa", "parallel", "tavily", "firecrawl"],
+        ["brave-free", "ddgs", "searxng", "exa", "parallel", "tavily", "firecrawl", "xai"],
     )
     def test_each_plugin_has_setup_schema(self, plugin_name: str) -> None:
         """``get_setup_schema()`` returns a dict the picker can consume."""
@@ -239,6 +243,17 @@ class TestIsAvailable:
         # Truthy or falsy, just must not raise.
         _ = bool(p.is_available())
 
+    def test_xai_requires_api_key_or_oauth(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """xAI needs XAI_API_KEY or OAuth tokens in auth.json."""
+        _ensure_plugins_loaded()
+        from agent.web_search_registry import get_provider
+
+        p = get_provider("xai")
+        assert p is not None
+        assert p.is_available() is False  # no XAI_API_KEY, no auth.json
+        monkeypatch.setenv("XAI_API_KEY", "real")
+        assert p.is_available() is True
+
 
 # ---------------------------------------------------------------------------
 # Registry resolution semantics (Option B — conservative smart fallback)
@@ -455,7 +470,7 @@ class TestErrorResponseShapes:
         if result["results"]:
             assert "error" in result["results"][0]
 
-    def test_firecrawl_crawl_returns_error_dict_when_unconfigured(self) -> None:
+    def test_firecrawl_crawl_returns_error_dict_when_unconfigured(self):
         """firecrawl crawl is async (wraps SDK in to_thread); error must be
         surfaced via the per-page result shape, not raised."""
         _ensure_plugins_loaded()
@@ -473,3 +488,15 @@ class TestErrorResponseShapes:
         assert len(result["results"]) >= 1
         assert "error" in result["results"][0]
         assert result["results"][0]["url"] == "https://example.com"
+
+    def test_xai_search_returns_error_dict_when_unconfigured(self) -> None:
+        """xAI returns a typed error dict (no XAI_API_KEY)."""
+        _ensure_plugins_loaded()
+        from agent.web_search_registry import get_provider
+
+        p = get_provider("xai")
+        assert p is not None
+        result = p.search("test", limit=5)
+        assert isinstance(result, dict)
+        assert result.get("success") is False
+        assert "error" in result

tests/providers/test_transport_parity.py

@@ -236,7 +236,7 @@ class TestQwenParity:
 
 
 class TestCustomOllamaParity:
-    """Custom/Ollama: num_ctx, think=false — now tested via profile."""
+    """Custom/Ollama: num_ctx, thinking controls — now tested via profile."""
 
     def test_ollama_num_ctx(self, transport):
         kw = transport.build_kwargs(

tests/run_agent/test_860_dedup.py

@@ -170,33 +170,7 @@ class TestFlushDeduplication:
 # ---------------------------------------------------------------------------
 
 class TestAppendToTranscriptSkipDb:
-    """Verify skip_db=True writes JSONL but not SQLite."""
-
-    @pytest.fixture()
-    def store(self, tmp_path):
-        from gateway.config import GatewayConfig
-        from gateway.session import SessionStore
-        config = GatewayConfig()
-        with patch("gateway.session.SessionStore._ensure_loaded"):
-            s = SessionStore(sessions_dir=tmp_path, config=config)
-        s._db = None  # no SQLite for these JSONL-focused tests
-        s._loaded = True
-        return s
-
-    def test_skip_db_writes_jsonl_only(self, store, tmp_path):
-        """With skip_db=True, message appears in JSONL but not SQLite."""
-        session_id = "test-skip-db"
-        msg = {"role": "assistant", "content": "hello world"}
-        store.append_to_transcript(session_id, msg, skip_db=True)
-
-        # JSONL should have the message
-        jsonl_path = store.get_transcript_path(session_id)
-        assert jsonl_path.exists()
-        with open(jsonl_path) as f:
-            lines = f.readlines()
-        assert len(lines) == 1
-        parsed = json.loads(lines[0])
-        assert parsed["content"] == "hello world"
+    """Verify skip_db=True skips the SQLite write."""
 
     def test_skip_db_prevents_sqlite_write(self, tmp_path):
         """With skip_db=True and a real DB, message does NOT appear in SQLite."""
@@ -223,14 +197,8 @@ class TestAppendToTranscriptSkipDb:
         rows = db.get_messages(session_id)
         assert len(rows) == 0, f"Expected 0 DB rows with skip_db=True, got {len(rows)}"
 
-        # But JSONL should have it
-        jsonl_path = store.get_transcript_path(session_id)
-        with open(jsonl_path) as f:
-            lines = f.readlines()
-        assert len(lines) == 1
-
-    def test_default_writes_both(self, tmp_path):
-        """Without skip_db, message appears in both JSONL and SQLite."""
+    def test_default_writes_to_sqlite(self, tmp_path):
+        """Without skip_db, message appears in SQLite."""
         from gateway.config import GatewayConfig
         from gateway.session import SessionStore
         from hermes_state import SessionDB
@@ -250,13 +218,7 @@ class TestAppendToTranscriptSkipDb:
         msg = {"role": "user", "content": "test message"}
         store.append_to_transcript(session_id, msg)
 
-        # JSONL should have the message
-        jsonl_path = store.get_transcript_path(session_id)
-        with open(jsonl_path) as f:
-            lines = f.readlines()
-        assert len(lines) == 1
-
-        # SQLite should also have the message
+        # SQLite should have the message
         rows = db.get_messages(session_id)
         assert len(rows) == 1
 

tests/run_agent/test_background_review_cache_parity.py

@@ -38,6 +38,9 @@ def _make_agent_stub(agent_cls):
     agent._MEMORY_REVIEW_PROMPT = "review memory"
     agent._SKILL_REVIEW_PROMPT = "review skills"
     agent._COMBINED_REVIEW_PROMPT = "review both"
+    # Non-None so the test catches a missing-kwarg regression.
+    agent.enabled_toolsets = ["memory", "skills", "terminal"]
+    agent.disabled_toolsets = ["spotify", "feishu_doc"]
     return agent
 
 
@@ -183,3 +186,54 @@ def test_review_fork_pins_session_start_and_session_id():
         "Review fork did not inherit parent's session_id — "
         "system-prompt rebuild paths would diverge."
     )
+
+
+def test_review_fork_inherits_parent_toolset_config():
+    """``tools[]`` byte-stability: fork must inherit parent's toolset config."""
+    import run_agent
+
+    agent = _make_agent_stub(run_agent.AIAgent)
+
+    captured = {}
+
+    class _Recorder:
+        def __init__(self, *args, **kwargs):
+            captured["enabled_toolsets"] = kwargs.get("enabled_toolsets")
+            captured["disabled_toolsets"] = kwargs.get("disabled_toolsets")
+            self._cached_system_prompt = None
+            self._memory_write_origin = None
+            self._memory_write_context = None
+            self._memory_store = None
+            self._memory_enabled = None
+            self._user_profile_enabled = None
+            self._memory_nudge_interval = None
+            self._skill_nudge_interval = None
+            self.suppress_status_output = None
+            self.session_start = None
+            self.session_id = None
+
+        def run_conversation(self, *args, **kwargs):
+            raise RuntimeError("stop after recording — don't actually call the API")
+
+        def shutdown_memory_provider(self):
+            pass
+
+        def close(self):
+            pass
+
+    with patch.object(run_agent, "AIAgent", _Recorder), \
+         patch("threading.Thread", _SyncThread):
+        agent._spawn_background_review(
+            messages_snapshot=[],
+            review_memory=True,
+            review_skills=False,
+        )
+
+    assert captured.get("enabled_toolsets") == agent.enabled_toolsets, (
+        f"enabled_toolsets mismatch: {captured.get('enabled_toolsets')!r} "
+        f"vs expected {agent.enabled_toolsets!r}"
+    )
+    assert captured.get("disabled_toolsets") == agent.disabled_toolsets, (
+        f"disabled_toolsets mismatch: {captured.get('disabled_toolsets')!r} "
+        f"vs expected {agent.disabled_toolsets!r}"
+    )

tests/run_agent/test_background_review_toolset_restriction.py

@@ -38,6 +38,9 @@ def _make_agent_stub(agent_cls):
     agent._MEMORY_REVIEW_PROMPT = "review memory"
     agent._SKILL_REVIEW_PROMPT = "review skills"
     agent._COMBINED_REVIEW_PROMPT = "review both"
+    # Non-None so the test catches a missing-kwarg regression.
+    agent.enabled_toolsets = ["memory", "skills", "terminal"]
+    agent.disabled_toolsets = ["spotify", "feishu_doc"]
     return agent
 
 
@@ -52,13 +55,8 @@ class _SyncThread:
             self._target()
 
 
-def test_background_review_does_not_narrow_toolset_schema():
-    """The review fork must NOT pass enabled_toolsets to AIAgent.
-
-    Narrowing the schema diverges the ``tools`` cache key from the parent's,
-    which sits above ``system`` in Anthropic's cache hierarchy and forces a
-    full prefix-cache miss on every review (see #25322, PR #17276).
-    """
+def test_background_review_matches_parent_toolset_config():
+    """Fork must receive parent's toolset config so ``tools[]`` cache key matches."""
     import run_agent
 
     agent = _make_agent_stub(run_agent.AIAgent)
@@ -66,6 +64,7 @@ def test_background_review_does_not_narrow_toolset_schema():
 
     def _capture_init(self, *args, **kwargs):
         captured["enabled_toolsets"] = kwargs.get("enabled_toolsets", "UNSET")
+        captured["disabled_toolsets"] = kwargs.get("disabled_toolsets", "UNSET")
         raise RuntimeError("stop after capturing init args")
 
     with patch.object(run_agent.AIAgent, "__init__", _capture_init), \
@@ -77,11 +76,13 @@ def test_background_review_does_not_narrow_toolset_schema():
         )
 
     assert "enabled_toolsets" in captured, "AIAgent.__init__ was not called"
-    # The kwarg must be absent — letting AIAgent inherit the default full
-    # toolset so the schema bytes match the parent's.
-    assert captured["enabled_toolsets"] == "UNSET", (
-        f"Review fork narrowed the toolset schema (got {captured['enabled_toolsets']!r}), "
-        "which breaks prefix-cache parity with the parent."
+    assert captured["enabled_toolsets"] == agent.enabled_toolsets, (
+        f"enabled_toolsets mismatch: {captured['enabled_toolsets']!r} "
+        f"vs expected {agent.enabled_toolsets!r}"
+    )
+    assert captured["disabled_toolsets"] == agent.disabled_toolsets, (
+        f"disabled_toolsets mismatch: {captured['disabled_toolsets']!r} "
+        f"vs expected {agent.disabled_toolsets!r}"
     )
 
 

tests/run_agent/test_codex_xai_oauth_recovery.py

@@ -19,11 +19,15 @@ Three distinct failure modes the user community hit during rollout:
    one-line hint pointing the user at https://grok.com and ``/model``.
 
 3. Multi-turn replay of ``codex_reasoning_items`` (with
-   ``encrypted_content``) is now suppressed for ``is_xai_responses=True``
-   in ``_chat_messages_to_responses_input``.  xAI's OAuth/SuperGrok
-   surface rejects replayed encrypted reasoning items; Grok still
-   reasons natively each turn, so coherence rides on visible message
-   text.
+   ``encrypted_content``) was briefly suppressed for ``is_xai_responses``
+   in PR #26644 on the theory that xAI's OAuth/SuperGrok surface
+   rejected replayed encrypted reasoning items.  That suppression was
+   reverted shortly after: xAI confirmed they explicitly want Hermes to
+   thread encrypted reasoning back across turns, and the original
+   multi-turn failure mode was actually the prelude-SSE issue closed by
+   Fix A above.  The remaining tests here lock in that xAI receives
+   replayed reasoning AND that we ask xAI to echo it back in the
+   ``include`` array.
 """
 
 from types import SimpleNamespace
@@ -353,8 +357,15 @@ def test_codex_reasoning_replay_default_includes_encrypted_content():
     assert reasoning[0]["encrypted_content"] == "enc_blob"
 
 
-def test_codex_reasoning_replay_stripped_for_xai_oauth():
-    """xAI OAuth surface must NOT receive replayed encrypted reasoning."""
+def test_codex_reasoning_replay_includes_encrypted_content_for_xai():
+    """xAI must receive replayed encrypted reasoning items (May 2026 reversal).
+
+    Earlier we stripped these on the theory that the OAuth/SuperGrok
+    surface rejected them.  xAI subsequently confirmed they explicitly
+    want Hermes to thread encrypted reasoning back across turns for
+    cross-turn coherence — that's the whole point of the partnership
+    integration.
+    """
     from agent.codex_responses_adapter import _chat_messages_to_responses_input
 
     msgs = [
@@ -365,10 +376,13 @@ def test_codex_reasoning_replay_stripped_for_xai_oauth():
 
     items = _chat_messages_to_responses_input(msgs, is_xai_responses=True)
     reasoning = [it for it in items if it.get("type") == "reasoning"]
-    assert reasoning == []
+    assert len(reasoning) == 1, (
+        "xAI must receive replayed reasoning items — see docstring for the "
+        "May 2026 reversal of the earlier suppression gate."
+    )
+    assert reasoning[0]["encrypted_content"] == "enc_blob"
 
-    # The assistant's visible text must still survive — coherence across
-    # turns rides on the message text alone.
+    # And the assistant's visible text must still be present alongside it.
     assistant_items = [
         it for it in items
         if it.get("role") == "assistant" or it.get("type") == "message"
@@ -376,8 +390,12 @@ def test_codex_reasoning_replay_stripped_for_xai_oauth():
     assert assistant_items, "assistant message must still be present"
 
 
-def test_codex_transport_xai_request_omits_encrypted_content_include():
-    """Verify the xAI ``include`` array no longer requests encrypted reasoning."""
+def test_codex_transport_xai_request_includes_encrypted_content():
+    """xAI ``include`` array must request ``reasoning.encrypted_content``.
+
+    This is the request-side half of the May 2026 reversal: we ask xAI
+    to echo back encrypted reasoning so the next turn can replay it.
+    """
     from agent.transports.codex import ResponsesApiTransport
 
     transport = ResponsesApiTransport()
@@ -392,14 +410,11 @@ def test_codex_transport_xai_request_omits_encrypted_content_include():
         reasoning_config={"enabled": True, "effort": "medium"},
         is_xai_responses=True,
     )
-    # Without this gate, xAI would echo back encrypted_content blobs we'd
-    # then store in codex_reasoning_items and replay next turn — which is
-    # exactly the multi-turn failure mode we're closing.
-    assert kwargs["include"] == []
+    assert kwargs["include"] == ["reasoning.encrypted_content"]
 
 
-def test_codex_transport_xai_strips_replayed_reasoning_in_input():
-    """End-to-end: build_kwargs on xai-oauth must strip prior reasoning."""
+def test_codex_transport_xai_replays_reasoning_in_input():
+    """End-to-end: build_kwargs on xAI must replay prior encrypted reasoning."""
     from agent.transports.codex import ResponsesApiTransport
 
     transport = ResponsesApiTransport()
@@ -418,7 +433,8 @@ def test_codex_transport_xai_strips_replayed_reasoning_in_input():
     )
     input_items = kwargs["input"]
     reasoning_items = [it for it in input_items if it.get("type") == "reasoning"]
-    assert reasoning_items == []
+    assert len(reasoning_items) == 1
+    assert reasoning_items[0]["encrypted_content"] == "enc_blob"
 
 
 def test_codex_transport_native_codex_still_replays_reasoning_in_input():

tests/run_agent/test_create_openai_client_reuse.py

@@ -16,6 +16,7 @@ with ``APIConnectionError('Connection error.')`` whose cause was
 That is the exact scenario this test reproduces at object level without a
 network, so it runs in CI on every PR.
 """
+from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
 from run_agent import AIAgent
@@ -186,3 +187,32 @@ def test_replace_primary_openai_client_survives_repeated_rebuilds():
         "Some _create_openai_client calls returned the same object across "
         "a teardown — rebuild is not producing fresh clients"
     )
+
+
+def test_force_close_tcp_sockets_descends_httpcore_1_connection_wrapper():
+    """httpcore 1.x stores the real stream below conn._connection."""
+    from agent.agent_runtime_helpers import force_close_tcp_sockets
+
+    class FakeSocket:
+        def __init__(self):
+            self.shutdown_calls = 0
+            self.close_calls = 0
+
+        def shutdown(self, _how):
+            self.shutdown_calls += 1
+
+        def close(self):
+            self.close_calls += 1
+
+    sock = FakeSocket()
+    stream = SimpleNamespace(_sock=sock)
+    http11 = SimpleNamespace(_network_stream=stream)
+    pool_entry = SimpleNamespace(_connection=http11)
+    pool = SimpleNamespace(_connections=[pool_entry])
+    transport = SimpleNamespace(_pool=pool)
+    http_client = SimpleNamespace(_transport=transport)
+    openai_client = SimpleNamespace(_client=http_client)
+
+    assert force_close_tcp_sockets(openai_client) == 1
+    assert sock.shutdown_calls == 1
+    assert sock.close_calls == 1

tests/run_agent/test_openai_client_lifecycle.py

@@ -1,5 +1,6 @@
 import sys
 import threading
+import time
 import types
 from types import SimpleNamespace
 
@@ -64,6 +65,7 @@ def _build_agent(shared_client=None):
     agent.stream_delta_callback = None
     agent._stream_callback = None
     agent.reasoning_callback = None
+    agent.status_callback = None
     return agent
 
 
@@ -93,6 +95,24 @@ def test_retry_after_api_connection_error_recreates_request_client(monkeypatch):
     assert second_request.close_calls >= 1
 
 
+def test_stale_non_stream_close_is_single_owner(monkeypatch):
+    def slow_responder(**kwargs):
+        time.sleep(0.1)
+        raise _connection_error()
+
+    request_client = FakeRequestClient(slow_responder)
+    factory = OpenAIFactory([request_client])
+    monkeypatch.setattr(run_agent, "OpenAI", factory)
+
+    agent = _build_agent()
+    agent._compute_non_stream_stale_timeout = lambda _messages: 0.01
+
+    with pytest.raises(APIConnectionError):
+        agent._interruptible_api_call({"model": agent.model, "messages": []})
+
+    assert request_client.close_calls == 1
+
+
 def test_closed_shared_client_is_recreated_before_request(monkeypatch):
     stale_shared = FakeSharedClient(lambda **kwargs: (_ for _ in ()).throw(AssertionError("stale shared client used")))
     stale_shared._client.is_closed = True

tests/run_agent/test_vision_aware_preprocessing.py

@@ -168,3 +168,43 @@ class TestModelSupportsVision:
         agent = _make_agent()
         with patch("agent.models_dev.get_model_capabilities", side_effect=RuntimeError("boom")):
             assert agent._model_supports_vision() is False
+
+    def test_top_level_model_override_wins(self):
+        agent = _make_agent()
+        agent.provider = "custom"
+        agent.model = "my-llava"
+        with patch("hermes_cli.config.load_config", return_value={"model": {"supports_vision": True}}), \
+             patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert agent._model_supports_vision() is True
+
+    def test_per_provider_per_model_override_wins(self):
+        agent = _make_agent()
+        agent.provider = "custom"
+        agent.model = "my-llava"
+        cfg = {"providers": {"custom": {"models": {"my-llava": {"supports_vision": True}}}}}
+        with patch("hermes_cli.config.load_config", return_value=cfg), \
+             patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert agent._model_supports_vision() is True
+
+    def test_named_custom_provider_resolved_via_config_provider(self):
+        # Named custom providers get runtime self.provider rewritten to
+        # "custom" while the config keeps the original name under
+        # model.provider. The override must still resolve.
+        agent = _make_agent()
+        agent.provider = "custom"
+        agent.model = "my-llava"
+        cfg = {
+            "model": {"provider": "my-vllm", "default": "my-llava"},
+            "providers": {"my-vllm": {"models": {"my-llava": {"supports_vision": True}}}},
+        }
+        with patch("hermes_cli.config.load_config", return_value=cfg), \
+             patch("agent.models_dev.get_model_capabilities", return_value=None):
+            assert agent._model_supports_vision() is True
+
+    def test_override_false_disables_vision_for_models_dev_models(self):
+        agent = _make_agent()
+        fake_caps = MagicMock()
+        fake_caps.supports_vision = True
+        with patch("hermes_cli.config.load_config", return_value={"model": {"supports_vision": False}}), \
+             patch("agent.models_dev.get_model_capabilities", return_value=fake_caps):
+            assert agent._model_supports_vision() is False

tests/test_hermes_constants.py

@@ -12,6 +12,7 @@ from hermes_constants import (
     get_default_hermes_root,
     is_container,
     parse_reasoning_effort,
+    secure_parent_dir,
 )
 
 
@@ -171,3 +172,95 @@ class TestParseReasoningEffort:
         """
         documented = {"minimal", "low", "medium", "high", "xhigh"}
         assert documented.issubset(set(VALID_REASONING_EFFORTS))
+
+
+class TestSecureParentDir:
+    """Tests for secure_parent_dir() — prevents chmod on / or top-level dirs."""
+
+    def test_safe_path_calls_chmod(self, tmp_path, monkeypatch):
+        """Normal nested path (depth >= 3) should call os.chmod."""
+        safe_dir = tmp_path / "home" / "user" / ".hermes"
+        safe_dir.mkdir(parents=True)
+        target = safe_dir / "auth.json"
+        target.touch()
+
+        called_with = []
+        monkeypatch.setattr(os, "chmod", lambda p, m: called_with.append((str(p), m)))
+
+        secure_parent_dir(target)
+        assert len(called_with) == 1
+        assert called_with[0] == (str(safe_dir), 0o700)
+
+    def test_root_dir_skipped(self, monkeypatch):
+        """Parent resolving to / must NOT be chmod'd."""
+        called_with = []
+        monkeypatch.setattr(os, "chmod", lambda p, m: called_with.append((str(p), m)))
+
+        # Path("/foo").parent == Path("/")
+        secure_parent_dir(Path("/foo"))
+        assert called_with == []
+
+    def test_top_level_dir_skipped(self, monkeypatch):
+        """Parent resolving to a top-level dir (depth 2) must NOT be chmod'd."""
+        called_with = []
+        monkeypatch.setattr(os, "chmod", lambda p, m: called_with.append((str(p), m)))
+
+        # Path("/usr/foo").parent == Path("/usr") — depth 2
+        secure_parent_dir(Path("/usr/foo"))
+        assert called_with == []
+
+    def test_two_component_path_skipped(self, monkeypatch):
+        """Parent with < 3 resolved parts must NOT be chmod'd.
+
+        Uses monkeypatch to avoid macOS firmlink resolution of /home.
+        """
+        called_with = []
+        monkeypatch.setattr(os, "chmod", lambda p, m: called_with.append((str(p), m)))
+
+        # Mock Path.resolve to return a short path regardless of OS quirks
+        original_resolve = Path.resolve
+        def mock_resolve(self):
+            if str(self) == "/x/y":
+                return Path("/x")
+            return original_resolve(self)
+        monkeypatch.setattr(Path, "resolve", mock_resolve)
+
+        secure_parent_dir(Path("/x/y"))
+        assert called_with == []
+
+    def test_oserror_suppressed(self, tmp_path, monkeypatch):
+        """OSError from chmod should be silently caught."""
+        safe_dir = tmp_path / "a" / "b" / "c"
+        safe_dir.mkdir(parents=True)
+        target = safe_dir / "file.json"
+        target.touch()
+
+        def raise_oserror(p, m):
+            raise OSError("permission denied")
+
+        monkeypatch.setattr(os, "chmod", raise_oserror)
+        # Should not raise
+        secure_parent_dir(target)
+
+    def test_symlink_resolved(self, tmp_path, monkeypatch):
+        """Symlinks should be resolved before checking depth."""
+        real_dir = tmp_path / "a" / "b"
+        real_dir.mkdir(parents=True)
+        target = real_dir / "file.json"
+        target.touch()
+
+        # Create a symlink with fewer path components
+        link = tmp_path / "link"
+        link.symlink_to(real_dir)
+        link_target = link / "file.json"
+
+        called_with = []
+        monkeypatch.setattr(os, "chmod", lambda p, m: called_with.append((str(p), m)))
+
+        # Even though /tmp/link has only 3 parts, the resolved path has 4
+        # The resolved parent (real_dir) has depth 4, so it should be chmod'd
+        secure_parent_dir(link_target)
+        assert len(called_with) == 1
+        assert called_with[0] == (str(real_dir), 0o700)
+
+

tests/test_hermes_state.py

@@ -316,6 +316,42 @@ class TestMessageStorage:
         assert conv[0] == {"role": "user", "content": "Hello"}
         assert conv[1] == {"role": "assistant", "content": "Hi!"}
 
+    def test_platform_message_id_round_trips(self, db):
+        """Platform-side message ids (yuanbao msg_id, telegram update_id, …)
+        survive append → get_messages_as_conversation under the
+        ``message_id`` key so platform recall flows can match by exact id."""
+        db.create_session(session_id="s_pmi", source="yuanbao")
+        db.append_message(
+            "s_pmi",
+            role="user",
+            content="hi",
+            platform_message_id="abc-123",
+        )
+        db.append_message("s_pmi", role="assistant", content="hello")
+
+        conv = db.get_messages_as_conversation("s_pmi")
+        user_msg = next(m for m in conv if m["role"] == "user")
+        assistant_msg = next(m for m in conv if m["role"] == "assistant")
+        assert user_msg.get("message_id") == "abc-123"
+        # Assistant row had no platform id — must not gain one spuriously.
+        assert "message_id" not in assistant_msg
+
+    def test_replace_messages_preserves_platform_message_id(self, db):
+        """``rewrite_transcript`` (which goes through replace_messages) must
+        keep the platform_message_id round-trip working for /retry, /undo,
+        /compress and yuanbao's recall rewrite path."""
+        db.create_session(session_id="s_rep", source="yuanbao")
+        db.replace_messages(
+            "s_rep",
+            [
+                {"role": "user", "content": "x", "message_id": "ext-1"},
+                {"role": "assistant", "content": "y"},
+            ],
+        )
+        conv = db.get_messages_as_conversation("s_rep")
+        assert next(m for m in conv if m["role"] == "user").get("message_id") == "ext-1"
+        assert "message_id" not in next(m for m in conv if m["role"] == "assistant")
+
     def test_get_messages_as_conversation_includes_ancestor_chain(self, db):
         db.create_session("root", "tui")
         db.append_message("root", role="user", content="first prompt")
@@ -1462,9 +1498,10 @@ class TestSchemaInit:
         assert "schema_version" in tables
 
     def test_schema_version(self, db):
+        from hermes_state import SCHEMA_VERSION
         cursor = db._conn.execute("SELECT version FROM schema_version")
         version = cursor.fetchone()[0]
-        assert version == 11
+        assert version == SCHEMA_VERSION
 
     def test_title_column_exists(self, db):
         """Verify the title column was created in the sessions table."""
@@ -1760,8 +1797,9 @@ class TestSchemaInit:
         migrated_db = SessionDB(db_path=db_path)
 
         # Verify migration
+        from hermes_state import SCHEMA_VERSION
         cursor = migrated_db._conn.execute("SELECT version FROM schema_version")
-        assert cursor.fetchone()[0] == 11
+        assert cursor.fetchone()[0] == SCHEMA_VERSION
 
         # Verify title column exists and is NULL for existing sessions
         session = migrated_db.get_session("existing")
@@ -2970,11 +3008,12 @@ class TestFTS5ToolCallMigration:
             assert len(session_db.search_messages("LEGACYARG")) == 1, \
                 "v11 migration must backfill tool_calls JSON into FTS"
             # schema_version bumped
+            from hermes_state import SCHEMA_VERSION
             row = session_db._conn.execute(
                 "SELECT version FROM schema_version LIMIT 1"
             ).fetchone()
             version = row["version"] if hasattr(row, "keys") else row[0]
-            assert version == 11
+            assert version == SCHEMA_VERSION
         finally:
             session_db.close()
 

tests/test_run_tests_parallel.py

@@ -0,0 +1,187 @@
+"""Verify scripts/run_tests_parallel.py kills test-spawned grandchildren.
+
+Setup
+-----
+A test in this file spawns a long-lived Python grandchild that writes
+its PID + a nonce to a tempfile, then exits without cleaning up.
+With the old ``subprocess.run`` runner, that grandchild would orphan
+and outlive the test (and the whole runner). With the current Popen +
+``start_new_session`` + ``_kill_tree`` runner, the grandchild gets
+SIGKILL'd via process-group kill when its file's pytest exits.
+
+The leaker test always passes — its only job is to spawn a grandchild
+and walk away. The verifier runs the runner over the leaker file in a
+subprocess, then waits for the grandchild PID to disappear from the
+kernel's process table.
+
+POSIX-only: Windows has its own grandchild lifecycle (no shared session,
+``taskkill /F /T`` semantics). Marked accordingly.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import textwrap
+import time
+from pathlib import Path
+
+import pytest
+
+
+# Both tests share the same handoff file: the leaker writes here, the
+# verifier reads here. We park it in $TMPDIR with a unique-per-run name
+# so concurrent invocations of the suite don't clobber each other.
+_HANDOFF_DIR = Path(os.environ.get("TMPDIR", "/tmp")) / "hermes-isolation-probe"
+_HANDOFF_DIR.mkdir(exist_ok=True)
+
+
+def _handoff_path_for(nonce: str) -> Path:
+    return _HANDOFF_DIR / f"grandchild-{nonce}.json"
+
+
+def _pid_alive(pid: int) -> bool:
+    """POSIX: send signal 0 to probe whether ``pid`` is still alive.
+
+    ``os.kill(pid, 0)`` raises ``ProcessLookupError`` if the process is
+    gone, ``PermissionError`` if it exists but we can't signal it
+    (someone else's pid). We treat PermissionError as "alive" because
+    the process exists and that's all we need to know.
+    """
+    if sys.platform == "win32":  # pragma: no cover — POSIX-only test
+        # On Windows we'd use OpenProcess + GetExitCodeProcess; this
+        # test is skipped on Windows so the path is unreachable.
+        raise RuntimeError("_pid_alive POSIX-only")
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX-only probe")
+@pytest.mark.live_system_guard_bypass
+def test_grandchild_leak_is_killed_by_runner(tmp_path: Path) -> None:
+    """Run the parallel runner over a probe file and verify cleanup.
+
+    1. Materialize a probe file that spawns a long-lived grandchild and
+       writes its PID to disk before exiting.
+    2. Invoke ``scripts/run_tests_parallel.py`` against the probe file.
+    3. Wait for the grandchild PID to vanish (poll for ~5s).
+    4. Assert the runner exited cleanly AND the grandchild is dead.
+    """
+    repo_root = Path(__file__).resolve().parent.parent
+    runner = repo_root / "scripts" / "run_tests_parallel.py"
+    assert runner.exists(), f"runner missing at {runner}"
+
+    # Probe lives in a temp dir, NOT under tests/, so the regular suite
+    # never picks it up — only our explicit invocation does.
+    probe_dir = tmp_path / "probe"
+    probe_dir.mkdir()
+    probe = probe_dir / "test_probe_leaker.py"
+    nonce = f"{os.getpid()}-{int(time.time() * 1000)}"
+    handoff = _handoff_path_for(nonce)
+    if handoff.exists():
+        handoff.unlink()
+
+    probe_src = textwrap.dedent(f"""
+        import json, os, subprocess, sys, time
+        from pathlib import Path
+
+        HANDOFF = Path({str(handoff)!r})
+
+        def test_spawns_grandchild_and_walks_away():
+            # Long-lived grandchild: detached, ignores SIGTERM (we want
+            # SIGKILL or process-group kill to be the only thing that
+            # works, simulating a misbehaving server).
+            child = subprocess.Popen(
+                [
+                    sys.executable, "-c",
+                    "import os, signal, sys, time; "
+                    "signal.signal(signal.SIGTERM, signal.SIG_IGN); "
+                    "sys.stdout.write(f'gc-pgid={{os.getpgid(0)}} gc-pid={{os.getpid()}}\\\\n'); "
+                    "sys.stdout.flush(); "
+                    "time.sleep(600)",
+                ],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                # IMPORTANT: do NOT pass start_new_session here. We want
+                # the grandchild to inherit the pytest subprocess's
+                # process group, so when the runner kills the group the
+                # grandchild dies too.
+            )
+            # Read the first line so we can record gc's pgid in the
+            # handoff, then walk away — don't close the pipe (would
+            # signal EOF and let the child see SIGPIPE on next write).
+            first_line = child.stdout.readline().decode().strip()
+            HANDOFF.write_text(json.dumps({{
+                "pid": child.pid,
+                "diag": first_line,
+                "test_pid": os.getpid(),
+                "test_pgid": os.getpgid(0),
+            }}))
+            assert child.pid > 0
+    """).strip()
+    probe.write_text(probe_src + "\n")
+
+    # Run the parallel runner against just the probe file. The runner
+    # discovers under ``tests/`` by default, so we override via --paths.
+    proc = subprocess.run(
+        [
+            sys.executable,
+            str(runner),
+            "--paths",
+            str(probe_dir),
+            "-j",
+            "1",
+            # Tight per-file timeout: the probe finishes in <1s, no
+            # need for 10min.
+            "--file-timeout",
+            "30",
+        ],
+        cwd=repo_root,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        timeout=60,
+    )
+
+    assert handoff.exists(), (
+        f"probe never wrote handoff file; runner output:\n{proc.stdout}"
+    )
+    handoff_data = json.loads(handoff.read_text())
+    grandchild_pid = handoff_data["pid"]
+    diag = handoff_data.get("diag", "(no diag)")
+    test_pid = handoff_data.get("test_pid")
+    test_pgid = handoff_data.get("test_pgid")
+    handoff.unlink()
+
+    # The runner must have exited cleanly (probe test passes).
+    assert proc.returncode == 0, (
+        f"runner exited {proc.returncode}; output:\n{proc.stdout}"
+    )
+
+    # The grandchild must be gone. Poll for a bit because process-group
+    # SIGKILL + reaping isn't synchronous; on a loaded box it can take
+    # a beat.
+    deadline = time.monotonic() + 5.0
+    while time.monotonic() < deadline:
+        if not _pid_alive(grandchild_pid):
+            break
+        time.sleep(0.05)
+    else:
+        # Test cleanup: kill the leaked grandchild ourselves so a
+        # FAILED assertion doesn't leave a sleep(600) running.
+        try:
+            os.kill(grandchild_pid, 9)
+        except ProcessLookupError:
+            pass
+        pytest.fail(
+            f"grandchild PID {grandchild_pid} survived runner exit; "
+            f"diag={diag!r} test_pid={test_pid} test_pgid={test_pgid}; "
+            f"runner output:\n{proc.stdout}"
+        )

tests/tools/conftest.py

@@ -0,0 +1,50 @@
+"""Shared fixtures for tests/tools/ web-provider tests.
+
+Per-file subprocess isolation means each test file gets a fresh interpreter,
+so module-level state (like the web-search-provider registry) is empty when
+a file starts.  The ``web_registry_populated`` fixture registers all bundled
+providers before each test and resets the registry afterwards — tests that
+depend on the registry being populated should use it explicitly or via
+``@pytest.mark.usefixtures("web_registry_populated")``.
+"""
+
+import pytest
+
+
+def register_all_web_providers():
+    """Register all bundled web-search providers into the global registry.
+
+    This is the single source of truth for the provider list used by
+    test classes that need the registry populated for dispatch checks.
+    """
+    from agent.web_search_registry import register_provider, _reset_for_tests
+    from plugins.web.brave_free.provider import BraveFreeWebSearchProvider
+    from plugins.web.ddgs.provider import DDGSWebSearchProvider
+    from plugins.web.exa.provider import ExaWebSearchProvider
+    from plugins.web.firecrawl.provider import FirecrawlWebSearchProvider
+    from plugins.web.parallel.provider import ParallelWebSearchProvider
+    from plugins.web.searxng.provider import SearXNGWebSearchProvider
+    from plugins.web.tavily.provider import TavilyWebSearchProvider
+    from plugins.web.xai.provider import XAIWebSearchProvider
+
+    _reset_for_tests()
+    for cls in (
+        BraveFreeWebSearchProvider,
+        DDGSWebSearchProvider,
+        ExaWebSearchProvider,
+        FirecrawlWebSearchProvider,
+        ParallelWebSearchProvider,
+        SearXNGWebSearchProvider,
+        TavilyWebSearchProvider,
+        XAIWebSearchProvider,
+    ):
+        register_provider(cls())
+
+
+@pytest.fixture
+def web_registry_populated():
+    """Populate the web-search-provider registry for one test, then reset."""
+    register_all_web_providers()
+    yield
+    from agent.web_search_registry import _reset_for_tests
+    _reset_for_tests()

tests/tools/test_approval_plugin_hooks.py

@@ -22,18 +22,28 @@ from tools.approval import (
 
 
 @pytest.fixture
-def isolated_session(monkeypatch):
-    """Give each test a fresh session_key and clean approval-state."""
+def isolated_session(monkeypatch, tmp_path):
+    """Give each test a fresh session_key, clean approval-state, and isolated
+    HERMES_HOME so the real user's command_allowlist doesn't leak in."""
+    import tools.approval as _am
+
     session_key = "test:session:approval_hooks"
     token = set_current_session_key(session_key)
     monkeypatch.setenv("HERMES_SESSION_KEY", session_key)
     # Make sure we don't skip guards via yolo / approvals.mode=off
     monkeypatch.delenv("HERMES_YOLO_MODE", raising=False)
+    # Isolate from the real user's permanent allowlist + session state
+    _saved_permanent = _am._permanent_approved.copy()
+    _saved_session = {k: v.copy() for k, v in _am._session_approved.items()}
+    _am._permanent_approved.clear()
+    _am._session_approved.clear()
     try:
         yield session_key
     finally:
+        _am._permanent_approved.update(_saved_permanent)
+        _am._session_approved.update(_saved_session)
         try:
-            approval_module._approval_session_key.reset(token)
+            _am._approval_session_key.reset(token)
         except Exception:
             pass
         clear_session(session_key)

tests/tools/test_browser_supervisor.py

@@ -41,7 +41,7 @@ def _find_chrome() -> str:
 
 
 @pytest.fixture
-def chrome_cdp(worker_id):
+def chrome_cdp(request):
     """Start a headless Chrome with --remote-debugging-port, yield its WS URL.
 
     Uses a unique port per xdist worker to avoid cross-worker collisions.
@@ -51,6 +51,9 @@ def chrome_cdp(worker_id):
     import socket
 
     # xdist worker_id is "master" in single-process mode or "gw0".."gwN" otherwise.
+    # Under subprocess-per-file isolation there's no xdist, so we fall back
+    # to "master" via the session-scoped fixture below.
+    worker_id = request.getfixturevalue("worker_id") if "worker_id" in request.fixturenames else "master"
     if worker_id == "master":
         port_offset = 0
     else:

tests/tools/test_discord_tool.py

@@ -1089,9 +1089,17 @@ class Test403Enrichment:
 class TestModelToolsIntegration:
     def setup_method(self):
         _reset_capability_cache()
+        from model_tools import _clear_tool_defs_cache
+        from tools.registry import invalidate_check_fn_cache
+        _clear_tool_defs_cache()
+        invalidate_check_fn_cache()
 
     def teardown_method(self):
         _reset_capability_cache()
+        from model_tools import _clear_tool_defs_cache
+        from tools.registry import invalidate_check_fn_cache
+        _clear_tool_defs_cache()
+        invalidate_check_fn_cache()
 
     @patch("tools.discord_tool._discord_request")
     def test_discord_admin_schema_rebuilt_by_get_tool_definitions(

tests/tools/test_homeassistant_tool.py

@@ -501,16 +501,18 @@ class TestRegistration:
 
     def test_check_fn_gates_availability(self, monkeypatch):
         """Registry should exclude HA tools when HASS_TOKEN is not set."""
-        from tools.registry import registry
+        from tools.registry import invalidate_check_fn_cache, registry
 
         monkeypatch.delenv("HASS_TOKEN", raising=False)
+        invalidate_check_fn_cache()
         defs = registry.get_definitions({"ha_list_entities", "ha_get_state", "ha_call_service"})
         assert len(defs) == 0
 
     def test_check_fn_includes_when_token_set(self, monkeypatch):
         """Registry should include HA tools when HASS_TOKEN is set."""
-        from tools.registry import registry
+        from tools.registry import invalidate_check_fn_cache, registry
 
         monkeypatch.setenv("HASS_TOKEN", "test-token")
+        invalidate_check_fn_cache()
         defs = registry.get_definitions({"ha_list_entities", "ha_get_state", "ha_call_service"})
         assert len(defs) == 3

tests/tools/test_kanban_tools.py

@@ -1093,6 +1093,11 @@ def test_kanban_guidance_not_in_normal_prompt(monkeypatch, tmp_path):
     from pathlib import Path as _P
     monkeypatch.setattr(_P, "home", lambda: tmp_path)
 
+    from tools.registry import invalidate_check_fn_cache
+    from model_tools import _clear_tool_defs_cache
+    invalidate_check_fn_cache()
+    _clear_tool_defs_cache()
+
     from run_agent import AIAgent
     a = AIAgent(
         api_key="test",
@@ -1116,6 +1121,11 @@ def test_kanban_guidance_in_worker_prompt(monkeypatch, tmp_path):
     from pathlib import Path as _P
     monkeypatch.setattr(_P, "home", lambda: tmp_path)
 
+    from tools.registry import invalidate_check_fn_cache
+    from model_tools import _clear_tool_defs_cache
+    invalidate_check_fn_cache()
+    _clear_tool_defs_cache()
+
     from run_agent import AIAgent
     a = AIAgent(
         api_key="test",

tests/tools/test_send_message_tool.py

@@ -10,6 +10,12 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+# python-telegram-bot is an optional dep — skip the entire module when
+# it isn't installed (e.g. CI bare env). Tests that patch telegram.Bot
+# or call _send_telegram need it; tests for other platforms don't but
+# keeping the whole file consistent is simpler.
+_HAS_TELEGRAM = pytest.importorskip("telegram", reason="python-telegram-bot not installed") is not None
+
 
 @pytest.fixture(autouse=True)
 def _reset_signal_scheduler():

tests/tools/test_skills_hub.py

@@ -1279,10 +1279,11 @@ class TestUnifiedSearchDedup:
         return src
 
     def test_dedup_keeps_first_seen(self):
+        # Same identifier from two sources — only the first (community) is kept when equal trust.
         s1 = SkillMeta(name="skill", description="from A", source="a",
-                        identifier="a/skill", trust_level="community")
+                        identifier="shared/skill", trust_level="community")
         s2 = SkillMeta(name="skill", description="from B", source="b",
-                        identifier="b/skill", trust_level="community")
+                        identifier="shared/skill", trust_level="community")
         src_a = self._make_source("a", [s1])
         src_b = self._make_source("b", [s2])
         results = unified_search("skill", [src_a, src_b])
@@ -1290,10 +1291,11 @@ class TestUnifiedSearchDedup:
         assert results[0].description == "from A"
 
     def test_dedup_prefers_trusted_over_community(self):
+        # Same identifier — trusted wins over community.
         community = SkillMeta(name="skill", description="community", source="a",
-                               identifier="a/skill", trust_level="community")
+                               identifier="shared/skill", trust_level="community")
         trusted = SkillMeta(name="skill", description="trusted", source="b",
-                             identifier="b/skill", trust_level="trusted")
+                             identifier="shared/skill", trust_level="trusted")
         src_a = self._make_source("a", [community])
         src_b = self._make_source("b", [trusted])
         results = unified_search("skill", [src_a, src_b])
@@ -1303,9 +1305,9 @@ class TestUnifiedSearchDedup:
     def test_dedup_prefers_builtin_over_trusted(self):
         """Regression: builtin must not be overwritten by trusted."""
         builtin = SkillMeta(name="skill", description="builtin", source="a",
-                             identifier="a/skill", trust_level="builtin")
+                             identifier="shared/skill", trust_level="builtin")
         trusted = SkillMeta(name="skill", description="trusted", source="b",
-                             identifier="b/skill", trust_level="trusted")
+                             identifier="shared/skill", trust_level="trusted")
         src_a = self._make_source("a", [builtin])
         src_b = self._make_source("b", [trusted])
         results = unified_search("skill", [src_a, src_b])
@@ -1314,14 +1316,31 @@ class TestUnifiedSearchDedup:
 
     def test_dedup_trusted_not_overwritten_by_community(self):
         trusted = SkillMeta(name="skill", description="trusted", source="a",
-                             identifier="a/skill", trust_level="trusted")
+                             identifier="shared/skill", trust_level="trusted")
         community = SkillMeta(name="skill", description="community", source="b",
-                               identifier="b/skill", trust_level="community")
+                               identifier="shared/skill", trust_level="community")
         src_a = self._make_source("a", [trusted])
         src_b = self._make_source("b", [community])
         results = unified_search("skill", [src_a, src_b])
         assert results[0].trust_level == "trusted"
 
+    def test_browse_sh_same_name_different_site_not_deduped(self):
+        # Browse.sh skills from different hostnames share task names (e.g. "search-listings")
+        # but have unique identifiers. They must NOT be collapsed into one result.
+        airbnb = SkillMeta(
+            name="search-listings", description="Airbnb search", source="browse-sh",
+            identifier="browse-sh/airbnb.com/search-listings-ddgioa", trust_level="community",
+        )
+        booking = SkillMeta(
+            name="search-listings", description="Booking.com search", source="browse-sh",
+            identifier="browse-sh/booking.com/search-listings-xyzab", trust_level="community",
+        )
+        src = self._make_source("browse-sh", [airbnb, booking])
+        results = unified_search("search-listings", [src])
+        assert len(results) == 2, (
+            "browse-sh skills with the same name but different sites must not be deduplicated"
+        )
+
     def test_source_filter(self):
         s1 = SkillMeta(name="s1", description="d", source="a",
                         identifier="x", trust_level="community")

tests/tools/test_terminal_tool_requirements.py

@@ -2,11 +2,26 @@
 
 import importlib
 
+import pytest
+
 from model_tools import get_tool_definitions
 
 terminal_tool_module = importlib.import_module("tools.terminal_tool")
 
 
+@pytest.fixture(autouse=True)
+def _clear_caches():
+    """Invalidate check_fn and tool-definitions caches before each test
+    so that monkeypatched env vars / config take effect."""
+    from tools.registry import invalidate_check_fn_cache
+    from model_tools import _clear_tool_defs_cache
+    invalidate_check_fn_cache()
+    _clear_tool_defs_cache()
+    yield
+    invalidate_check_fn_cache()
+    _clear_tool_defs_cache()
+
+
 class TestTerminalRequirements:
     def test_local_backend_requirements(self, monkeypatch):
         monkeypatch.setattr(

tests/tools/test_video_generation_tool_surface_matrix.py

@@ -95,7 +95,9 @@ def _invoke_tool(home, cfg: dict, args: dict) -> dict:
     if hasattr(cfg_mod, "_invalidate_load_config_cache"):
         cfg_mod._invalidate_load_config_cache()
 
-    from tools.registry import registry
+    from tools.registry import discover_builtin_tools, registry
+    if "video_generate" not in registry._tools:
+        discover_builtin_tools()
     handler = registry._tools["video_generate"].handler
     return json.loads(handler(args))
 

tests/tools/test_web_providers.py

@@ -13,6 +13,8 @@ from typing import Any, Dict, List
 
 import pytest
 
+from tests.tools.conftest import register_all_web_providers
+
 
 # ---------------------------------------------------------------------------
 # ABC enforcement
@@ -276,6 +278,15 @@ class TestUnconfiguredErrorEnvelopeParity:
     ``result.get("error")`` detect the failure cleanly.
     """
 
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def _clear_web_creds(self, monkeypatch):
         for k in (
             "BRAVE_SEARCH_API_KEY",

tests/tools/test_web_providers_brave_free.py

@@ -15,6 +15,10 @@ from __future__ import annotations
 import json
 from unittest.mock import MagicMock, patch
 
+import pytest
+
+from tests.tools.conftest import register_all_web_providers
+
 
 # ---------------------------------------------------------------------------
 # BraveFreeWebSearchProvider unit tests
@@ -239,6 +243,15 @@ class TestBraveFreeBackendWiring:
 
 
 class TestBraveFreeSearchOnlyErrors:
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def test_web_extract_returns_search_only_error(self, monkeypatch):
         import asyncio
         from tools import web_tools
@@ -246,6 +259,7 @@ class TestBraveFreeSearchOnlyErrors:
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {"backend": "brave-free"})
         monkeypatch.setenv("BRAVE_SEARCH_API_KEY", "BSAkey123")
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
         monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False, raising=False)
 
         result_str = asyncio.get_event_loop().run_until_complete(
@@ -264,6 +278,8 @@ class TestBraveFreeSearchOnlyErrors:
         monkeypatch.setenv("BRAVE_SEARCH_API_KEY", "BSAkey123")
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
         monkeypatch.setattr(web_tools, "check_firecrawl_api_key", lambda: False)
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+        monkeypatch.setattr(web_tools, "check_website_access", lambda url: None)
         monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False, raising=False)
 
         result_str = asyncio.get_event_loop().run_until_complete(

tests/tools/test_web_providers_ddgs.py

@@ -14,6 +14,10 @@ import sys
 import types
 from unittest.mock import MagicMock
 
+import pytest
+
+from tests.tools.conftest import register_all_web_providers
+
 
 def _install_fake_ddgs(monkeypatch, *, text_results=None, text_raises=None):
     """Install a stub ``ddgs`` module in sys.modules for the duration of a test.
@@ -210,6 +214,15 @@ class TestDDGSBackendWiring:
 
 
 class TestDDGSSearchOnlyErrors:
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def test_web_extract_returns_search_only_error(self, monkeypatch):
         import asyncio
         from tools import web_tools
@@ -217,6 +230,7 @@ class TestDDGSSearchOnlyErrors:
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {"backend": "ddgs"})
         monkeypatch.setattr(web_tools, "_ddgs_package_importable", lambda: True)
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
         monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False, raising=False)
 
         result_str = asyncio.get_event_loop().run_until_complete(
@@ -235,6 +249,8 @@ class TestDDGSSearchOnlyErrors:
         monkeypatch.setattr(web_tools, "_ddgs_package_importable", lambda: True)
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
         monkeypatch.setattr(web_tools, "check_firecrawl_api_key", lambda: False)
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+        monkeypatch.setattr(web_tools, "check_website_access", lambda url: None)
         monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False, raising=False)
 
         result_str = asyncio.get_event_loop().run_until_complete(

tests/tools/test_web_providers_searxng.py

@@ -17,6 +17,8 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
+from tests.tools.conftest import register_all_web_providers
+
 
 # ---------------------------------------------------------------------------
 # SearXNGWebSearchProvider unit tests
@@ -301,6 +303,15 @@ class TestCheckWebApiKey:
 class TestSearXNGOnlyExtractCrawlErrors:
     """When searxng is the active backend, extract/crawl must return clear errors."""
 
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def test_web_crawl_searxng_returns_clear_error(self, monkeypatch):
         import asyncio
         from tools import web_tools
@@ -309,6 +320,8 @@ class TestSearXNGOnlyExtractCrawlErrors:
         monkeypatch.setenv("SEARXNG_URL", "http://localhost:8080")
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
         monkeypatch.setattr(web_tools, "check_firecrawl_api_key", lambda: False)
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+        monkeypatch.setattr(web_tools, "check_website_access", lambda url: None)
         monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False, raising=False)
 
         import json
@@ -326,6 +339,7 @@ class TestSearXNGOnlyExtractCrawlErrors:
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {"backend": "searxng"})
         monkeypatch.setenv("SEARXNG_URL", "http://localhost:8080")
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
         monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False, raising=False)
 
         import json

tests/tools/test_web_tools_tavily.py

@@ -13,6 +13,8 @@ import asyncio
 import pytest
 from unittest.mock import patch, MagicMock
 
+from tests.tools.conftest import register_all_web_providers
+
 
 # ─── _tavily_request ─────────────────────────────────────────────────────────
 
@@ -163,6 +165,15 @@ class TestNormalizeTavilyDocuments:
 class TestWebSearchTavily:
     """Test web_search_tool dispatch to Tavily."""
 
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def test_search_dispatches_to_tavily(self):
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -186,6 +197,15 @@ class TestWebSearchTavily:
 class TestWebExtractTavily:
     """Test web_extract_tool dispatch to Tavily."""
 
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def test_extract_dispatches_to_tavily(self):
         mock_response = MagicMock()
         mock_response.json.return_value = {
@@ -211,6 +231,15 @@ class TestWebExtractTavily:
 class TestWebCrawlTavily:
     """Test web_crawl_tool dispatch to Tavily."""
 
+    _register_providers = staticmethod(register_all_web_providers)
+
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
     def test_crawl_dispatches_to_tavily(self):
         mock_response = MagicMock()
         mock_response.json.return_value = {

tests/tools/test_website_policy.py

@@ -4,6 +4,8 @@ from pathlib import Path
 import pytest
 import yaml
 
+from tests.tools.conftest import register_all_web_providers
+
 from tools.website_policy import WebsitePolicyError, check_website_access, load_website_blocklist
 
 
@@ -347,40 +349,191 @@ def test_browser_navigate_allows_when_shared_file_missing(monkeypatch, tmp_path)
     assert result is None
 
 
-@pytest.mark.asyncio
-async def test_web_extract_short_circuits_blocked_url(monkeypatch):
-    from tools import web_tools
-    from plugins.web.firecrawl import provider as firecrawl_provider
+class TestWebToolPolicy:
+    """Tests that exercise web_extract_tool / web_crawl_tool with website-policy gates.
 
-    # Allow test URLs past SSRF check so website policy is what gets tested
-    monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
-    # The per-URL website-policy gate moved into the firecrawl plugin's
-    # extract() during the web-provider migration. Patch it at the new
-    # location; the dispatcher-level gate (used by web_crawl_tool's
-    # pre-flight) still lives on tools.web_tools.
-    monkeypatch.setattr(
-        firecrawl_provider,
-        "check_website_access",
-        lambda url: {
-            "host": "blocked.test",
-            "rule": "blocked.test",
-            "source": "config",
-            "message": "Blocked by website policy",
-        },
-    )
-    monkeypatch.setattr(
-        firecrawl_provider,
-        "_get_firecrawl_client",
-        lambda: pytest.fail("firecrawl should not run for blocked URL"),
-    )
-    monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
-    # Force the firecrawl plugin to be the active extract provider.
-    monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+    These tests need the bundled web providers to be registered in the
+    agent.web_search_registry so the tool dispatchers can find an active
+    provider.  Without registration, the tools return an error dict that
+    lacks a ``results`` key, causing ``KeyError``.
+    """
 
-    result = json.loads(await web_tools.web_extract_tool(["https://blocked.test"], use_llm_processing=False))
+    _register_providers = staticmethod(register_all_web_providers)
 
-    assert result["results"][0]["url"] == "https://blocked.test"
-    assert "Blocked by website policy" in result["results"][0]["error"]
+    @pytest.fixture(autouse=True)
+    def _populate_web_registry(self):
+        self._register_providers()
+        yield
+        from agent.web_search_registry import _reset_for_tests
+        _reset_for_tests()
+
+    @pytest.mark.asyncio
+    async def test_web_extract_short_circuits_blocked_url(self, monkeypatch):
+        from tools import web_tools
+        from plugins.web.firecrawl import provider as firecrawl_provider
+
+        # Allow test URLs past SSRF check so website policy is what gets tested
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+        # The per-URL website-policy gate moved into the firecrawl plugin's
+        # extract() during the web-provider migration. Patch it at the new
+        # location; the dispatcher-level gate (used by web_crawl_tool's
+        # pre-flight) still lives on tools.web_tools.
+        monkeypatch.setattr(
+            firecrawl_provider,
+            "check_website_access",
+            lambda url: {
+                "host": "blocked.test",
+                "rule": "blocked.test",
+                "source": "config",
+                "message": "Blocked by website policy",
+            },
+        )
+        monkeypatch.setattr(
+            firecrawl_provider,
+            "_get_firecrawl_client",
+            lambda: pytest.fail("firecrawl should not run for blocked URL"),
+        )
+        monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+        # Force the firecrawl plugin to be the active extract provider.
+        monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+
+        result = json.loads(await web_tools.web_extract_tool(["https://blocked.test"], use_llm_processing=False))
+
+        assert result["results"][0]["url"] == "https://blocked.test"
+        assert "Blocked by website policy" in result["results"][0]["error"]
+
+    @pytest.mark.asyncio
+    async def test_web_extract_blocks_redirected_final_url(self, monkeypatch):
+        from tools import web_tools
+        from plugins.web.firecrawl import provider as firecrawl_provider
+
+        # Allow test URLs past SSRF check so website policy is what gets tested
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+
+        def fake_check(url):
+            if url == "https://allowed.test":
+                return None
+            if url == "https://blocked.test/final":
+                return {
+                    "host": "blocked.test",
+                    "rule": "blocked.test",
+                    "source": "config",
+                    "message": "Blocked by website policy",
+                }
+            pytest.fail(f"unexpected URL checked: {url}")
+
+        class FakeFirecrawlClient:
+            def scrape(self, url, formats):
+                return {
+                    "markdown": "secret content",
+                    "metadata": {
+                        "title": "Redirected",
+                        "sourceURL": "https://blocked.test/final",
+                    },
+                }
+
+        # After the web-provider migration, the per-URL gate + firecrawl client
+        # live in the plugin. Patch both at the plugin location.
+        monkeypatch.setattr(firecrawl_provider, "check_website_access", fake_check)
+        monkeypatch.setattr(firecrawl_provider, "_get_firecrawl_client", lambda: FakeFirecrawlClient())
+        monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+        monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+
+        result = json.loads(await web_tools.web_extract_tool(["https://allowed.test"], use_llm_processing=False))
+
+        assert result["results"][0]["url"] == "https://blocked.test/final"
+        assert result["results"][0]["content"] == ""
+        assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
+
+    @pytest.mark.asyncio
+    async def test_web_crawl_short_circuits_blocked_url(self, monkeypatch):
+        from tools import web_tools
+
+        # web_crawl_tool checks for Firecrawl env before website policy
+        monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+        # Allow test URLs past SSRF check so website policy is what gets tested
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+        # The dispatcher-level (seed-URL) policy gate still lives on web_tools.
+        # No per-page gate runs in this test because the dispatcher returns
+        # immediately when the seed is blocked, before delegating to the plugin.
+        monkeypatch.setattr(
+            web_tools,
+            "check_website_access",
+            lambda url: {
+                "host": "blocked.test",
+                "rule": "blocked.test",
+                "source": "config",
+                "message": "Blocked by website policy",
+            },
+        )
+        # If the dispatcher ever reaches the firecrawl plugin's crawl(), the test
+        # fails — pin the plugin module's client lookup so we'd notice.
+        from plugins.web.firecrawl import provider as firecrawl_provider
+        monkeypatch.setattr(
+            firecrawl_provider,
+            "_get_firecrawl_client",
+            lambda: pytest.fail("firecrawl plugin should not run for blocked crawl URL"),
+        )
+        monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+
+        result = json.loads(await web_tools.web_crawl_tool("https://blocked.test", use_llm_processing=False))
+
+        assert result["results"][0]["url"] == "https://blocked.test"
+        assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
+
+    @pytest.mark.asyncio
+    async def test_web_crawl_blocks_redirected_final_url(self, monkeypatch):
+        from tools import web_tools
+        from plugins.web.firecrawl import provider as firecrawl_provider
+
+        # Force the firecrawl plugin to be the active crawl provider.
+        monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
+        # Allow test URLs past SSRF check so website policy is what gets tested
+        monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
+
+        def fake_check(url):
+            # Dispatcher seed-URL gate (web_tools.check_website_access call)
+            # and plugin per-page gate (firecrawl_provider.check_website_access
+            # call) both flow through this single fake_check.
+            if url == "https://allowed.test":
+                return None
+            if url == "https://blocked.test/final":
+                return {
+                    "host": "blocked.test",
+                    "rule": "blocked.test",
+                    "source": "config",
+                    "message": "Blocked by website policy",
+                }
+            pytest.fail(f"unexpected URL checked: {url}")
+
+        class FakeCrawlClient:
+            def crawl(self, url, **kwargs):
+                return {
+                    "data": [
+                        {
+                            "markdown": "secret crawl content",
+                            "metadata": {
+                                "title": "Redirected crawl page",
+                                "sourceURL": "https://blocked.test/final",
+                            },
+                        }
+                    ]
+                }
+
+        # After PR #25182 follow-up: per-page policy gate lives in
+        # plugins.web.firecrawl.provider.crawl(). Patch the gate + client at
+        # the plugin location. The dispatcher-level (seed) gate also reads
+        # web_tools.check_website_access — patch both.
+        monkeypatch.setattr(web_tools, "check_website_access", fake_check)
+        monkeypatch.setattr(firecrawl_provider, "check_website_access", fake_check)
+        monkeypatch.setattr(firecrawl_provider, "_get_firecrawl_client", lambda: FakeCrawlClient())
+        monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
+
+        result = json.loads(await web_tools.web_crawl_tool("https://allowed.test", use_llm_processing=False))
+
+        assert result["results"][0]["content"] == ""
+        assert result["results"][0]["error"] == "Blocked by website policy"
+        assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
 
 
 def test_check_website_access_fails_open_on_malformed_config(tmp_path, monkeypatch):
@@ -400,139 +553,3 @@ def test_check_website_access_fails_open_on_malformed_config(tmp_path, monkeypat
     # With default path, errors are caught and fail open
     result = check_website_access("https://example.com")
     assert result is None  # allowed, not crashed
-
-
-@pytest.mark.asyncio
-async def test_web_extract_blocks_redirected_final_url(monkeypatch):
-    from tools import web_tools
-    from plugins.web.firecrawl import provider as firecrawl_provider
-
-    # Allow test URLs past SSRF check so website policy is what gets tested
-    monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
-
-    def fake_check(url):
-        if url == "https://allowed.test":
-            return None
-        if url == "https://blocked.test/final":
-            return {
-                "host": "blocked.test",
-                "rule": "blocked.test",
-                "source": "config",
-                "message": "Blocked by website policy",
-            }
-        pytest.fail(f"unexpected URL checked: {url}")
-
-    class FakeFirecrawlClient:
-        def scrape(self, url, formats):
-            return {
-                "markdown": "secret content",
-                "metadata": {
-                    "title": "Redirected",
-                    "sourceURL": "https://blocked.test/final",
-                },
-            }
-
-    # After the web-provider migration, the per-URL gate + firecrawl client
-    # live in the plugin. Patch both at the plugin location.
-    monkeypatch.setattr(firecrawl_provider, "check_website_access", fake_check)
-    monkeypatch.setattr(firecrawl_provider, "_get_firecrawl_client", lambda: FakeFirecrawlClient())
-    monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
-    monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
-
-    result = json.loads(await web_tools.web_extract_tool(["https://allowed.test"], use_llm_processing=False))
-
-    assert result["results"][0]["url"] == "https://blocked.test/final"
-    assert result["results"][0]["content"] == ""
-    assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
-
-
-@pytest.mark.asyncio
-async def test_web_crawl_short_circuits_blocked_url(monkeypatch):
-    from tools import web_tools
-
-    # web_crawl_tool checks for Firecrawl env before website policy
-    monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
-    # Allow test URLs past SSRF check so website policy is what gets tested
-    monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
-    # The dispatcher-level (seed-URL) policy gate still lives on web_tools.
-    # No per-page gate runs in this test because the dispatcher returns
-    # immediately when the seed is blocked, before delegating to the plugin.
-    monkeypatch.setattr(
-        web_tools,
-        "check_website_access",
-        lambda url: {
-            "host": "blocked.test",
-            "rule": "blocked.test",
-            "source": "config",
-            "message": "Blocked by website policy",
-        },
-    )
-    # If the dispatcher ever reaches the firecrawl plugin's crawl(), the test
-    # fails — pin the plugin module's client lookup so we'd notice.
-    from plugins.web.firecrawl import provider as firecrawl_provider
-    monkeypatch.setattr(
-        firecrawl_provider,
-        "_get_firecrawl_client",
-        lambda: pytest.fail("firecrawl plugin should not run for blocked crawl URL"),
-    )
-    monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
-
-    result = json.loads(await web_tools.web_crawl_tool("https://blocked.test", use_llm_processing=False))
-
-    assert result["results"][0]["url"] == "https://blocked.test"
-    assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"
-
-
-@pytest.mark.asyncio
-async def test_web_crawl_blocks_redirected_final_url(monkeypatch):
-    from tools import web_tools
-    from plugins.web.firecrawl import provider as firecrawl_provider
-
-    # Force the firecrawl plugin to be the active crawl provider.
-    monkeypatch.setenv("FIRECRAWL_API_KEY", "fake-key")
-    # Allow test URLs past SSRF check so website policy is what gets tested
-    monkeypatch.setattr(web_tools, "is_safe_url", lambda url: True)
-
-    def fake_check(url):
-        # Dispatcher seed-URL gate (web_tools.check_website_access call)
-        # and plugin per-page gate (firecrawl_provider.check_website_access
-        # call) both flow through this single fake_check.
-        if url == "https://allowed.test":
-            return None
-        if url == "https://blocked.test/final":
-            return {
-                "host": "blocked.test",
-                "rule": "blocked.test",
-                "source": "config",
-                "message": "Blocked by website policy",
-            }
-        pytest.fail(f"unexpected URL checked: {url}")
-
-    class FakeCrawlClient:
-        def crawl(self, url, **kwargs):
-            return {
-                "data": [
-                    {
-                        "markdown": "secret crawl content",
-                        "metadata": {
-                            "title": "Redirected crawl page",
-                            "sourceURL": "https://blocked.test/final",
-                        },
-                    }
-                ]
-            }
-
-    # After PR #25182 follow-up: per-page policy gate lives in
-    # plugins.web.firecrawl.provider.crawl(). Patch the gate + client at
-    # the plugin location. The dispatcher-level (seed) gate also reads
-    # web_tools.check_website_access — patch both.
-    monkeypatch.setattr(web_tools, "check_website_access", fake_check)
-    monkeypatch.setattr(firecrawl_provider, "check_website_access", fake_check)
-    monkeypatch.setattr(firecrawl_provider, "_get_firecrawl_client", lambda: FakeCrawlClient())
-    monkeypatch.setattr("tools.interrupt.is_interrupted", lambda: False)
-
-    result = json.loads(await web_tools.web_crawl_tool("https://allowed.test", use_llm_processing=False))
-
-    assert result["results"][0]["content"] == ""
-    assert result["results"][0]["error"] == "Blocked by website policy"
-    assert result["results"][0]["blocked_by_policy"]["rule"] == "blocked.test"

tests/tools/test_write_deny.py

@@ -1,8 +1,10 @@
 """Tests for _is_write_denied() — verifies deny list blocks sensitive paths on all platforms."""
 
 import os
+
 import pytest
 from pathlib import Path
+from unittest.mock import patch
 
 from tools.file_operations import _is_write_denied
 
@@ -41,6 +43,31 @@ class TestWriteDenyExactPaths:
         path = str(get_hermes_home() / ".env")
         assert _is_write_denied(path) is True
 
+    def test_hermes_root_env_when_running_under_profile(self, tmp_path, monkeypatch):
+        """Top-level ``<root>/.env`` stays write-denied even when running under
+        a profile (#15981).
+
+        Before the fix, ``build_write_denied_paths`` only added
+        ``<active_profile>/.env`` to the deny list, so the global
+        ``~/.hermes/.env`` (whose credentials are inherited by every profile)
+        could be silently overwritten by ``write_file`` while a profile was
+        active.
+        """
+        root = tmp_path / "hermes_root"
+        profile_home = root / "profiles" / "coder"
+        profile_home.mkdir(parents=True)
+        global_env = root / ".env"
+        global_env.write_text("OPENAI_API_KEY=sk-real\n")
+
+        monkeypatch.setenv("HERMES_HOME", str(profile_home))
+
+        # Sanity check: HERMES_HOME does point to the profile dir, not the root.
+        from hermes_constants import get_hermes_home, get_default_hermes_root
+        assert get_hermes_home() == profile_home
+        assert get_default_hermes_root() == root
+
+        assert _is_write_denied(str(global_env)) is True
+
     def test_shell_profiles(self):
         home = str(Path.home())
         for name in [".bashrc", ".zshrc", ".profile", ".bash_profile", ".zprofile"]:
@@ -72,8 +99,22 @@ class TestWriteDenyPrefixes:
     def test_sudoers_d_prefix(self):
         assert _is_write_denied("/etc/sudoers.d/custom") is True
 
-    def test_systemd_prefix(self):
-        assert _is_write_denied("/etc/systemd/system/evil.service") is True
+    def test_systemd_prefix(self, tmp_path):
+        # On NixOS, /etc/systemd is a symlink into /nix/store, so
+        # realpath() resolves it to a store path that doesn't match
+        # the /etc/systemd/ prefix.  Build a real directory tree so
+        # realpath is a no-op and prefix matching works.
+        fake_etc = tmp_path / "etc" / "systemd" / "system"
+        fake_etc.mkdir(parents=True)
+        target = str(fake_etc / "evil.service")
+        # Patch the prefix builder to include our tmp_path prefix
+        import agent.file_safety as _fs
+        _orig = _fs.build_write_denied_prefixes
+        _extra_prefix = str(tmp_path / "etc" / "systemd") + os.sep
+        def _patched(home):
+            return _orig(home) + [_extra_prefix]
+        with patch.object(_fs, "build_write_denied_prefixes", _patched):
+            assert _is_write_denied(target) is True
 
 
 class TestWriteAllowed:

tests/tools/test_x_search_tool.py

@@ -436,3 +436,290 @@ def test_x_search_registered_in_registry_with_check_fn():
     assert entry.check_fn.__name__ == "check_x_search_requirements"
     assert "XAI_API_KEY" in entry.requires_env
     assert entry.emoji == "🐦"
+
+
+# ---------------------------------------------------------------------------
+# Date validation — fail fast before burning an API call on a window that
+# cannot possibly return X posts. xAI itself happily 200s with a fluff
+# answer when the range is malformed or pure-future, which is hard for
+# callers to distinguish from a real result.
+# ---------------------------------------------------------------------------
+
+def _no_post_allowed(monkeypatch):
+    """Guard: any test that should fail before HTTP can hit this fence."""
+    def _fail(*_, **__):
+        raise AssertionError("requests.post must not be called — validation should reject first")
+
+    monkeypatch.setattr("requests.post", _fail)
+
+
+def test_x_search_rejects_malformed_from_date(monkeypatch):
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    _no_post_allowed(monkeypatch)
+
+    result = json.loads(x_search_tool(query="anything", from_date="not-a-date"))
+
+    assert "from_date must be YYYY-MM-DD" in result["error"]
+
+
+def test_x_search_rejects_malformed_to_date(monkeypatch):
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    _no_post_allowed(monkeypatch)
+
+    result = json.loads(x_search_tool(query="anything", to_date="2026/05/01"))
+
+    assert "to_date must be YYYY-MM-DD" in result["error"]
+
+
+def test_x_search_rejects_inverted_date_range(monkeypatch):
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    _no_post_allowed(monkeypatch)
+
+    result = json.loads(
+        x_search_tool(
+            query="anything",
+            from_date="2026-05-10",
+            to_date="2026-05-01",
+        )
+    )
+
+    assert "from_date (2026-05-10) must be on or before to_date (2026-05-01)" in result["error"]
+
+
+def test_x_search_rejects_future_from_date(monkeypatch):
+    """``from_date`` in the future can never match any post → reject."""
+    import datetime as _dt
+
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    _no_post_allowed(monkeypatch)
+
+    class _FrozenDateTime(_dt.datetime):
+        @classmethod
+        def now(cls, tz=None):
+            return _dt.datetime(2026, 5, 21, 12, 0, 0, tzinfo=tz or _dt.timezone.utc)
+
+    monkeypatch.setattr("tools.x_search_tool.datetime", _FrozenDateTime)
+
+    result = json.loads(x_search_tool(query="anything", from_date="2030-01-01"))
+
+    assert "from_date (2030-01-01) is in the future" in result["error"]
+
+
+def test_x_search_allows_future_to_date(monkeypatch):
+    """``to_date`` in the future is fine — caller may want posts as they arrive."""
+    import datetime as _dt
+
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+
+    class _FrozenDateTime(_dt.datetime):
+        @classmethod
+        def now(cls, tz=None):
+            return _dt.datetime(2026, 5, 21, 12, 0, 0, tzinfo=tz or _dt.timezone.utc)
+
+    monkeypatch.setattr("tools.x_search_tool.datetime", _FrozenDateTime)
+
+    def _fake_post(url, headers=None, json=None, timeout=None):
+        return _FakeResponse(
+            {"output_text": "future to_date is allowed", "citations": []}
+        )
+
+    monkeypatch.setattr("requests.post", _fake_post)
+
+    result = json.loads(
+        x_search_tool(
+            query="anything",
+            from_date="2026-05-20",
+            to_date="2030-01-01",
+        )
+    )
+
+    assert result["success"] is True
+    assert result["answer"] == "future to_date is allowed"
+
+
+def test_x_search_accepts_today_as_from_date(monkeypatch):
+    """``from_date == today UTC`` is a valid edge case (today is past + present)."""
+    import datetime as _dt
+
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+
+    class _FrozenDateTime(_dt.datetime):
+        @classmethod
+        def now(cls, tz=None):
+            return _dt.datetime(2026, 5, 21, 12, 0, 0, tzinfo=tz or _dt.timezone.utc)
+
+    monkeypatch.setattr("tools.x_search_tool.datetime", _FrozenDateTime)
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse({"output_text": "ok", "citations": []}),
+    )
+
+    result = json.loads(x_search_tool(query="anything", from_date="2026-05-21"))
+
+    assert result["success"] is True
+
+
+# ---------------------------------------------------------------------------
+# Degraded-result flag — distinguish citation-backed answers from
+# unsourced fluff when narrowing filters returned nothing.
+# ---------------------------------------------------------------------------
+
+def test_x_search_marks_degraded_when_handle_filter_returns_no_citations(monkeypatch):
+    """allowed_x_handles set + zero citations → degraded=True."""
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse(
+            {"output_text": "Generic encyclopedic answer with no citations.", "citations": []}
+        ),
+    )
+
+    result = json.loads(
+        x_search_tool(query="what has @ghostuser posted", allowed_x_handles=["ghostuser"])
+    )
+
+    assert result["success"] is True
+    assert result["degraded"] is True
+    assert "allowed_x_handles" in result["degraded_reason"]
+
+
+def test_x_search_marks_degraded_when_excluded_handles_and_no_citations(monkeypatch):
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse({"output_text": "fluff", "citations": []}),
+    )
+
+    result = json.loads(
+        x_search_tool(query="anything", excluded_x_handles=["someuser"])
+    )
+
+    assert result["degraded"] is True
+    assert "excluded_x_handles" in result["degraded_reason"]
+
+
+def test_x_search_marks_degraded_when_date_range_and_no_citations(monkeypatch):
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse({"output_text": "fluff", "citations": []}),
+    )
+
+    result = json.loads(
+        x_search_tool(
+            query="anything",
+            from_date="2026-04-01",
+            to_date="2026-04-02",
+        )
+    )
+
+    assert result["degraded"] is True
+    assert "from_date" in result["degraded_reason"]
+    assert "to_date" in result["degraded_reason"]
+
+
+def test_x_search_not_degraded_when_filter_returns_inline_citations(monkeypatch):
+    """A real citation from the inline annotations clears the degraded flag."""
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse(
+            {
+                "output": [
+                    {
+                        "type": "message",
+                        "content": [
+                            {
+                                "type": "output_text",
+                                "text": "Real post from xai.",
+                                "annotations": [
+                                    {
+                                        "type": "url_citation",
+                                        "url": "https://x.com/xai/status/1",
+                                        "title": "xAI post",
+                                        "start_index": 0,
+                                        "end_index": 4,
+                                    }
+                                ],
+                            }
+                        ],
+                    }
+                ]
+            }
+        ),
+    )
+
+    result = json.loads(
+        x_search_tool(query="latest xAI post", allowed_x_handles=["xai"])
+    )
+
+    assert result["success"] is True
+    assert result["degraded"] is False
+    assert result["degraded_reason"] is None
+    assert len(result["inline_citations"]) == 1
+
+
+def test_x_search_not_degraded_when_filter_returns_top_level_citations(monkeypatch):
+    """A real citation from xAI's top-level ``citations`` array also clears the flag."""
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse(
+            {
+                "output_text": "Found discussion.",
+                "citations": [{"url": "https://x.com/example/status/1", "title": "Example"}],
+            }
+        ),
+    )
+
+    result = json.loads(
+        x_search_tool(query="anything", allowed_x_handles=["xai"])
+    )
+
+    assert result["degraded"] is False
+    assert result["degraded_reason"] is None
+
+
+def test_x_search_not_degraded_when_no_filters_active(monkeypatch):
+    """A broad query that returns no citations isn't necessarily degraded.
+
+    Without any narrowing filter, an empty-citations response is a generic
+    unsourced answer, not a "filter miss". The caller can already tell from
+    ``inline_citations == []`` if they care.
+    """
+    from tools.x_search_tool import x_search_tool
+
+    monkeypatch.setenv("XAI_API_KEY", "xai-test-key")
+    monkeypatch.setattr(
+        "requests.post",
+        lambda *a, **k: _FakeResponse({"output_text": "broad answer", "citations": []}),
+    )
+
+    result = json.loads(x_search_tool(query="anything"))
+
+    assert result["success"] is True
+    assert result["degraded"] is False
+    assert result["degraded_reason"] is None
+