Summary

During a thorough code audit, I found several minor bugs, stale documentation, typos, and inconsistencies across the codebase. None are individually critical, but together they represent code quality improvements worth addressing.

1. Wildly wrong percentage comments in toolset_distributions.py

Lines 48-52, 199-204

The inline comments describing toolset probabilities are completely wrong — they appear to be stale from an earlier version:

# image_gen distribution:
"image_gen": 90,  # 80% chance   ← actual is 90
"vision": 90,     # 60% chance   ← actual is 90
"web": 55,        # 40% chance   ← actual is 55
"moa": 10         # 20% chance   ← actual is 10

# terminal_tasks distribution:
"web": 97,        # 15%          ← actual is 97
"browser": 75,    # 10%          ← actual is 75
"vision": 50,     # 8%           ← actual is 50
"image_gen": 10   # 3%           ← actual is 10

Fix: Update comments to match actual values, or remove them since the values are self-documenting.

2. hermes_time.py references non-existent reset_cache() function

Lines 31, 81

Both the module comment and get_timezone() docstring say "Call reset_cache() after config changes", but no reset_cache() function exists in the file. The timezone cache (_cache_resolved) has no public API to reset it.

Fix: Add a reset_cache() function, or remove the references.

3. Stale docstring in memory_tool.py mentions removed read action

Line 20

Module docstring says:

- Single `memory` tool with action parameter: add, replace, remove, read

But the schema (line 683) only allows ["add", "replace", "remove"] and the handler returns an error for read. The read action was intentionally removed but the docstring wasn't updated.

Fix: Change line 20 to add, replace, remove.

4. fuzzy_match.py docstring says "8-strategy chain" but code has 9

Line 9

The unicode_normalized strategy was added but the docstring wasn't updated. The numbered list (lines 10-17) also only lists 8 items.

Fix: Update to "9-strategy chain" and add unicode_normalized to the numbered list.

5. LIKE used for "exact" name matching in holographic memory store

File: plugins/memory/holographic/store.py, line 440

# Comment says "Exact name match" but LIKE treats _ and % as wildcards
row = self._conn.execute(
    "SELECT entity_id FROM entities WHERE name LIKE ?", (name,)
).fetchone()

Confirmed: LIKE 'test_entity' matches both test_entity AND testXentity because _ is a single-character wildcard.

Fix: Use = ? for exact matching, or LOWER(name) = LOWER(?) for case-insensitive exact matching.

6. Docker config inconsistency between terminal, file, and code-exec tools

terminal_tool.py passes docker_env and docker_extra_args in container_config (lines 1823-1825), but file_tools.py (lines 469-481) and code_execution_tool.py (lines 614-624) omit these keys. Users who configure TERMINAL_DOCKER_ENV or TERMINAL_DOCKER_EXTRA_ARGS will see those settings applied to terminal commands but silently ignored for file and code execution operations.

Fix: Add the missing keys to container_config in file_tools.py and code_execution_tool.py.

7. _set_interrupt(False) called without thread_id in _hydrate_todo_store

File: run_agent.py, line 2286

All other _set_interrupt calls pass self._execution_thread_id, but this one omits it, defaulting to the current thread. In gateway mode where _hydrate_todo_store may be called from a different thread than the execution thread, this clears the interrupt for the wrong thread.

Fix: _set_interrupt(False, self._execution_thread_id)

8. unittest.mock.Mock imported in production code

File: run_agent.py, lines 2519, 2669

from unittest.mock import Mock
if isinstance(client, Mock):
    return False

Test infrastructure leaking into production code paths. This import runs on every call to _is_openai_client_closed and _create_request_openai_client.

Fix: Guard with if os.environ.get("HERMES_TESTING"): or use a protocol/flag instead.

9. Corrupted Unicode emoji (mojibake)

File: batch_runner.py, line 1013

print(f"âš ï¸  Warning: Failed to save final checkpoint: {ckpt_err}")

The bytes c3 a2 c5 a1 c2 a0 c3 af c2 b8 c2 8f are double-encoded UTF-8, rendering as garbled text instead of ⚠️.

Fix: Replace with proper Unicode: print(f"⚠️ Warning: ...")

10. Lowercase any used as type annotation

Files:

• toolset_distributions.py:223 — def get_distribution(name: str) -> Optional[Dict[str, any]]:
• cli.py:2835 — def save_config_value(key_path: str, value: any) -> bool:

any (lowercase) is the builtin any() function, not typing.Any.

Fix: Import and use Any from typing.

11. Logging setup idempotency guard placed after handler addition

File: hermes_logging.py, lines 216-258

The _logging_initialized guard is checked after _add_rotating_handler calls. While handlers themselves are deduplicated, root logger level changes in subsequent calls are skipped silently.

12. #<TBD> placeholder in comment

File: run_agent.py, line 1253

# ...causing the empty-retry loop to fire forever. See #<TBD>.

Issue number was never filled in.

13. Lowercase callable in type annotations

Files:

• plugins/disk-cleanup/disk_cleanup.py:343 — Optional[callable]
• agent/conversation_loop.py:269 — Optional[callable]

Should be Optional[Callable] from typing.