quality: dead code, dedup, constants, docs (audit Group E)

Quality fixes from the comprehensive audit. No behavior changes — all
syntactic/cosmetic/traceability improvements.

- E1: delete debug-model-options.py. Confirmed dead — not COPY'd into
the image (Dockerfile only copies start.sh, health-server.js,
hermes-sync.py, cloudflare-*.py), no caller anywhere, replaced by the
inline Python probe in health-server.js (/hm/debug/model-options-trace).
Also hardcoded a python3.12 site-packages path that may not match the
container's Python version.
- E7: remove unused 'import time' in cloudflare-proxy-setup.py.
- E11: re-declare ARG HERMES_AGENT_VERSION after FROM so the ENV line
'HERMES_AGENT_VERSION=${HERMES_AGENT_VERSION}' expands correctly
under the classic builder (pre-FROM ARGs are only visible in FROM).
- E12: LOG_ROTATE_BYTES env var replaces the magic 5242880 literal in
the boot log-rotation block.
- E13: record the resolved WebUI commit (git rev-parse HEAD >
/opt/hermes-webui/WEBUI_COMMIT) so a build can be traced to an exact
upstream revision. WEBUI_REF defaults to master (moving target).
- E15: export BACKUP_DATASET consistently (hermes-sync.py reads
BACKUP_DATASET_NAME from env; the shell var was never exported).
- E16: write_status now logs OSError to stderr instead of swallowing it
silently — if /tmp is unwritable the status page shows stale data with
no log line to explain why. Same for the STATE_FILE atomic write.
- E17: factor the duplicated STATE_FILE parse block (sync_once + loop)
into a load_state() helper.
- E18: port the HTTPError body-parsing from cloudflare-keepalive-setup.py
into cloudflare-proxy-setup.py's cf_request so a CF 4xx/5xx surfaces
the API error message instead of a raw 'HTTP Error 401: Unauthorized'.

Skipped the riskier refactors (launch_logged helper, buildProxyHeaders/
bufferRequestBody extraction, module-scope dashboardRootRoutes Set,
parse-req.url-once) to honor 'be careful not breaking' — they touch
hot request paths and the dedup benefit isn't worth the behavior risk.

Dockerfile

@@ -4,6 +4,10 @@
 ARG HERMES_AGENT_VERSION=latest
 FROM nousresearch/hermes-agent:${HERMES_AGENT_VERSION}
 
+# Re-declare so the ARG is in scope after FROM (a pre-FROM ARG is only
+# visible inside the FROM instruction under the classic builder; BuildKit
+# is more permissive but re-declaring is portable).
+ARG HERMES_AGENT_VERSION
 ARG WEBUI_REF=master
 
 USER root
@@ -42,9 +46,13 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && uv pip install --python /opt/hermes/.venv/bin/python --no-cache-dir \
         huggingface_hub hf_transfer pyyaml
 
-# Clone nesquena/hermes-webui (install deps into the agent venv so imports resolve)
+# Clone nesquena/hermes-webui (install deps into the agent venv so imports resolve).
+# WEBUI_REF defaults to master (moving target) — record the resolved commit so
+# a build can be traced back to an exact upstream revision. Combined with the
+# build-time patches below, this makes silent patch-skip failures debuggable.
 RUN git clone --depth 1 --branch ${WEBUI_REF} \
         https://github.com/nesquena/hermes-webui.git /opt/hermes-webui \
+ && cd /opt/hermes-webui && git rev-parse HEAD > /opt/hermes-webui/WEBUI_COMMIT \
  && ( [ -f /opt/hermes-webui/requirements.txt ] \
       && /opt/hermes/.venv/bin/pip install --no-cache-dir -r /opt/hermes-webui/requirements.txt \
       || true ) \

cloudflare-proxy-setup.py

@@ -11,8 +11,8 @@ import os
 import re
 import secrets
 import sys
-import time
 import urllib.request
+import urllib.error
 from pathlib import Path
 
 API_BASE = "https://api.cloudflare.com/client/v4"
@@ -43,8 +43,20 @@ def cf_request(method: str, path: str, token: str, body: bytes | None = None, co
         method=method,
         headers={"Authorization": f"Bearer {token}", "Content-Type": content_type},
     )
-    with urllib.request.urlopen(req, timeout=30) as response:
-        payload = json.loads(response.read().decode("utf-8"))
+    # E18: parse HTTPError bodies like the keepalive script does. Previously
+    # a 4xx/5xx from CF surfaced as a raw 'HTTP Error 401: Unauthorized' in
+    # the generic except Exception block with no body context.
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        try:
+            error_body = json.loads(e.read().decode("utf-8"))
+            errors = error_body.get("errors") or [{"message": "Unknown error"}]
+            error_msg = errors[0].get("message", "Unknown error") if errors else "Unknown error"
+        except Exception:
+            error_msg = f"HTTP {e.code}: {e.reason}"
+        raise RuntimeError(f"Cloudflare API {e.code}: {error_msg}")
     if not payload.get("success"):
         errors = payload.get("errors") or [{"message": "Unknown Cloudflare API error"}]
         raise RuntimeError(errors[0].get("message", "Unknown Cloudflare API error"))

debug-model-options.py

@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-"""Debug script: call build_models_payload() directly and print the traceback."""
-import os, sys, traceback, json
-
-os.environ.setdefault("HERMES_HOME", "/opt/data")
-sys.path.insert(0, "/opt/hermes")
-sys.path.insert(0, "/opt/hermes/.venv/lib/python3.12/site-packages")
-
-try:
-    from hermes_cli.inventory import build_models_payload, load_picker_context
-    ctx = load_picker_context()
-    print("=== load_picker_context OK ===")
-    print(f"  current_model: {ctx.current_model!r}")
-    print(f"  current_provider: {ctx.current_provider!r}")
-    print(f"  current_base_url: {ctx.current_base_url!r}")
-    print(f"  user_providers: {list(ctx.user_providers.keys()) if isinstance(ctx.user_providers, dict) else type(ctx.user_providers)}")
-    print(f"  custom_providers: {list(ctx.custom_providers.keys()) if isinstance(ctx.custom_providers, dict) else type(ctx.custom_providers)}")
-except Exception:
-    print("=== load_picker_context FAILED ===")
-    traceback.print_exc()
-    sys.exit(0)
-
-try:
-    result = build_models_payload(ctx, max_models=50, include_unconfigured=True, picker_hints=True, canonical_order=True, pricing=True, capabilities=True)
-    print("=== build_models_payload OK ===")
-    print(f"  providers count: {len(result.get('providers', []))}")
-    print(f"  model: {result.get('model')!r}")
-    print(f"  provider: {result.get('provider')!r}")
-except Exception:
-    print("=== build_models_payload FAILED ===")
-    traceback.print_exc()

hermes-sync.py

@@ -158,8 +158,11 @@ def write_status(status: str, message: str, fingerprint: str | None = None, mark
     try:
         tmp_path.write_text(json.dumps(payload), encoding="utf-8")
         tmp_path.replace(STATUS_FILE)
-    except OSError:
-        pass
+    except OSError as exc:
+        # E16: surface status write failures instead of swallowing silently.
+        # If /tmp is unwritable (read-only FS, full disk) the status page
+        # shows stale data with no log line to explain why.
+        print(f"Warning: could not write sync status to {STATUS_FILE}: {exc}", file=sys.stderr)
 
     if fingerprint or marker:
         state = {}
@@ -180,8 +183,8 @@ def write_status(status: str, message: str, fingerprint: str | None = None, mark
             tmp_state = STATE_FILE.with_suffix(".tmp")
             tmp_state.write_text(json.dumps(state), encoding="utf-8")
             os.replace(tmp_state, STATE_FILE)
-        except OSError:
-            pass
+        except OSError as exc:
+            print(f"Warning: could not write sync state to {STATE_FILE}: {exc}", file=sys.stderr)
 
 
 def resolve_backup_repo() -> str:
@@ -460,6 +463,24 @@ def restore() -> bool:
         return False
 
 
+def load_state() -> tuple[str | None, tuple[int, int, int] | None]:
+    """E17: load (last_fingerprint, last_marker) from STATE_FILE.
+
+    Factored from the duplicated parse block that appeared in both sync_once
+    and loop. Returns (None, None) if the file is missing/corrupt.
+    """
+    if not STATE_FILE.exists():
+        return (None, None)
+    try:
+        state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+        last_fingerprint = state.get("last_fingerprint")
+        m = state.get("last_marker")
+        last_marker = tuple(m) if m and len(m) == 3 else None
+        return (last_fingerprint, last_marker)
+    except Exception:
+        return (None, None)
+
+
 def sync_once(last_fingerprint: str | None = None, last_marker: tuple[int, int, int] | None = None):
     # Inter-process lock: the loop process and a separate CLI sync-once
     # (run by start.sh's graceful_shutdown / exit handler) can both call
@@ -480,15 +501,7 @@ def sync_once(last_fingerprint: str | None = None, last_marker: tuple[int, int,
         except OSError:
             _LOCK_HANDLE = None  # non-fatal; proceed without the lock
     if last_fingerprint is None and last_marker is None:
-        if STATE_FILE.exists():
-            try:
-                state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
-                last_fingerprint = state.get("last_fingerprint")
-                m = state.get("last_marker")
-                if m and len(m) == 3:
-                    last_marker = tuple(m)
-            except Exception:
-                pass
+        last_fingerprint, last_marker = load_state()
 
     repo_id = ensure_repo_exists()
     current_marker = metadata_marker(HERMES_HOME)
@@ -547,15 +560,7 @@ def loop() -> int:
     # Seed from any prior run so we don't re-upload an identical tree.
     last_fingerprint: str | None = None
     last_marker: tuple[int, int, int] | None = None
-    if STATE_FILE.exists():
-        try:
-            state = json.loads(STATE_FILE.read_text(encoding="utf-8"))
-            last_fingerprint = state.get("last_fingerprint")
-            m = state.get("last_marker")
-            if m and len(m) == 3:
-                last_marker = tuple(m)
-        except Exception:
-            pass
+    last_fingerprint, last_marker = load_state()
     if last_marker is None:
         last_marker = metadata_marker(HERMES_HOME)
 

start.sh

@@ -20,7 +20,10 @@ TELEGRAM_WEBHOOK_PORT="${TELEGRAM_WEBHOOK_PORT:-8765}"
 WEBUI_PORT="${HERMES_WEBUI_PORT:-8787}"
 
 SYNC_INTERVAL="${SYNC_INTERVAL:-60}"
-BACKUP_DATASET="${BACKUP_DATASET_NAME:-huggingmes-backup}"
+# E15: export so downstream scripts could read it if needed; hermes-sync.py
+# reads BACKUP_DATASET_NAME from env directly, so this is for the startup
+# summary + any future callers.
+export BACKUP_DATASET="${BACKUP_DATASET_NAME:-huggingmes-backup}"
 CF_PROXY_ENV_FILE="/tmp/huggingmes-cloudflare-proxy.env"
 
 export HERMES_HOME
@@ -69,11 +72,13 @@ cd "$HERMES_HOME/workspace" || cd "$HERMES_HOME"
 # rotation those files grow forever and end up in the HF Dataset backup.
 # Strategy: if a log is >5MB, rename to .1 (overwriting any previous .1)
 # and start fresh. Cheap, deterministic, no cron needed.
+# Threshold is env-configurable (default 5 MiB) so a noisy space can tune it.
+LOG_ROTATE_BYTES="${LOG_ROTATE_BYTES:-5242880}"
 if [ -d "$HERMES_HOME/logs" ]; then
   for f in "$HERMES_HOME/logs"/*.log; do
     [ -f "$f" ] || continue
     sz=$(stat -c%s "$f" 2>/dev/null || echo 0)
-    if [ "$sz" -gt 5242880 ]; then
+    if [ "$sz" -gt "$LOG_ROTATE_BYTES" ]; then
       mv -f "$f" "${f}.1"
       : > "$f"
       echo "rotated $(basename "$f") ($sz bytes -> .1)"