fix: clearer terminal backend requirement errors

Salvaged from PR #979 onto current main.

Preserve the current terminal backend checks while surfacing actionable
preflight errors for unknown TERMINAL_ENV values, missing SSH host/user
configuration, and missing Modal credentials/config. Tighten the modal
regression test so it deterministically exercises the config-missing
path.

tests/tools/test_terminal_requirements.py

@@ -1,15 +1,77 @@
+import importlib
 import logging
 
-from tools.terminal_tool import check_terminal_requirements
+terminal_tool_module = importlib.import_module("tools.terminal_tool")
+
+
+def _clear_terminal_env(monkeypatch):
+    """Remove terminal env vars that could affect requirements checks."""
+    keys = [
+        "TERMINAL_ENV",
+        "TERMINAL_SSH_HOST",
+        "TERMINAL_SSH_USER",
+        "MODAL_TOKEN_ID",
+        "HOME",
+        "USERPROFILE",
+    ]
+    for key in keys:
+        monkeypatch.delenv(key, raising=False)
 
 
 def test_local_terminal_requirements_do_not_depend_on_minisweagent(monkeypatch, caplog):
     """Local backend uses Hermes' own LocalEnvironment wrapper and should not
     be marked unavailable just because `minisweagent` isn't importable."""
+    _clear_terminal_env(monkeypatch)
     monkeypatch.setenv("TERMINAL_ENV", "local")
 
     with caplog.at_level(logging.ERROR):
-        ok = check_terminal_requirements()
+        ok = terminal_tool_module.check_terminal_requirements()
 
     assert ok is True
     assert "Terminal requirements check failed" not in caplog.text
+
+
+def test_unknown_terminal_env_logs_error_and_returns_false(monkeypatch, caplog):
+    _clear_terminal_env(monkeypatch)
+    monkeypatch.setenv("TERMINAL_ENV", "unknown-backend")
+
+    with caplog.at_level(logging.ERROR):
+        ok = terminal_tool_module.check_terminal_requirements()
+
+    assert ok is False
+    assert any(
+        "Unknown TERMINAL_ENV 'unknown-backend'" in record.getMessage()
+        for record in caplog.records
+    )
+
+
+def test_ssh_backend_without_host_or_user_logs_and_returns_false(monkeypatch, caplog):
+    _clear_terminal_env(monkeypatch)
+    monkeypatch.setenv("TERMINAL_ENV", "ssh")
+
+    with caplog.at_level(logging.ERROR):
+        ok = terminal_tool_module.check_terminal_requirements()
+
+    assert ok is False
+    assert any(
+        "SSH backend selected but TERMINAL_SSH_HOST and TERMINAL_SSH_USER" in record.getMessage()
+        for record in caplog.records
+    )
+
+
+def test_modal_backend_without_token_or_config_logs_specific_error(monkeypatch, caplog, tmp_path):
+    _clear_terminal_env(monkeypatch)
+    monkeypatch.setenv("TERMINAL_ENV", "modal")
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    monkeypatch.setattr(terminal_tool_module, "ensure_minisweagent_on_path", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(terminal_tool_module.importlib.util, "find_spec", lambda _name: object())
+
+    with caplog.at_level(logging.ERROR):
+        ok = terminal_tool_module.check_terminal_requirements()
+
+    assert ok is False
+    assert any(
+        "Modal backend selected but no MODAL_TOKEN_ID environment variable" in record.getMessage()
+        for record in caplog.records
+    )