hermes - 💡(How to fix) Fix Feature: `hermes doctor` — one-command system health diagnostics

Problem

A significant portion of "it doesn't work" issues stem from silent failures that are invisible at the default log level. In the past week alone:

Users currently need to:

1. Know which log file to check (agent.log? gateway.log? errors.log?)
2. Run at DEBUG level (noisy, expensive)
3. Interpret stack traces to find the root cause

This creates friction for both users (can't self-diagnose) and maintainers (issues lack diagnostic context).

Proposal

Add a hermes doctor CLI command that runs a suite of health checks and outputs a clear, actionable report:

$ hermes doctor
✓ Config        — valid, 3 profiles loaded
✓ Credentials   — 2/2 providers reachable (zhipu, openrouter)
⚠ Plugins       — 5/6 loaded (clitoolkit: pandoc binary not found in PATH)
⚠ Skills        — 2 name conflicts in external_dirs
✗ Logging       — gateway.log missing component prefix "hermes_plugins"
✓ Connectivity  — Feishu WS connected, API server reachable on :8080
✓ Database      — state.db healthy (47 sessions, 2.1 MB)
✓ Cron          — 4/4 jobs healthy, last run 12 min ago
✓ Disk          — logs/ 340 MB (within limit)

2 warnings, 1 issue found. Run `hermes doctor --fix` for auto-remediation.

Check Categories

--fix flag (optional, Phase 2)

Auto-remediate where safe:

• Add missing component prefixes to logging config
• Clean stale session files
• Re-link orphan skill symlinks
• Reset stuck cron jobs

--json flag

Machine-readable output for programmatic consumption:

$ hermes doctor --json | jq ".checks.plugins"
{
  "status": "warning",
  "loaded": 5,
  "total": 6,
  "failures": [{"plugin": "clitoolkit", "reason": "pandoc binary not found"}]
}

Implementation Sketch

The command would live in hermes_cli/commands/doctor.py as a new CLI subcommand. Each check is an independent function returning {status, message, details} — easy to extend and test.

# Pseudo-structure
CHECKS = [
    ("config",       check_config),
    ("credentials",  check_credentials),
    ("plugins",      check_plugins),
    ("skills",       check_skills),
    ("logging",      check_logging),
    ("connectivity", check_connectivity),
    ("database",     check_database),
    ("cron",         check_cron),
    ("disk",         check_disk),
]

def run_doctor(fix: bool = False, json_output: bool = False):
    results = [(name, fn()) for name, fn in CHECKS]
    # render table / JSON

Why This Matters

1. Reduces issue triage cost — maintainers can ask for hermes doctor output instead of guessing
2. Empowers self-service — users catch 80% of setup problems before filing issues
3. Single source of truth — replaces scattered hermes config check, manual log inspection, and "is my setup correct?" questions in Discord
4. Extensible — plugins can register their own health checks via entry point

Related

• #27931 (CI environment drift — no local detection)
• #28137 (discover_plugins silent failure)
• #28138 (plugin log prefix mismatch)
• #28126 (sync_skills collision)