fix(hermes): separate policy observations from fault findings

Contract design defect: 'uses a non-harness provider' (POLICY) and
'cannot authenticate' (FAULT) were printed as the same violation class.
A policy observation must never be phrased as if the agent were broken.

Changes:
1. Added 'Violation Classification' section to all three contracts
2. Separated POLICY (observation only) from FAULT (requires request-level evidence)
3. Rules:
   - Do NOT infer runtime credential resolution from config text alone
   - Require request-level evidence before calling a FAULT: observed auth failure
     or absence of successful calls
   - If calls are succeeding, output is 'POLICY: uses <provider> directly; calls
     succeeding' - not a violation
   - State what you OBSERVED, not what the field implies

Files changed (3):
- hermes-key-enforcement.prose.md
- hermes-config-template.prose.md
- hermes-agent-baseline.prose.md

hermes-agent-baseline.prose.md

@@ -11,6 +11,24 @@ author: Abiba (pi agent)
 
 # Hermes Agent Baseline — Canonical Good State
 
+## Reachability Detection
+
+Before checking agent baseline, verify the host is reachable and can be audited. Use the shared reachability helper from the clone root:
+
+```bash
+# Run on each host to check reachability (Tanko, Mumuni, Koonimo, Koby)
+scripts/hermes-reachability-check.sh <host> "api_key:" "/root/.hermes/config.yaml"
+# Example: scripts/hermes-reachability-check.sh 192.168.68.122 "api_key:" "/root/.hermes/config.yaml"
+
+# Expected outcomes:
+# - UNREACHABLE: SSH connection failed (host is down)
+# - VIOLATION: SSH succeeded and found matches (report the finding)
+# - COMPLIANT: SSH succeeded and found no matches (no api_key in config)
+#
+# NOTE: The bug this replaces was deriving reachability from the remote grep's exit code.
+# The correct pattern: remote side always succeeds (grep ...; true), so ssh status = connection only.
+```
+
 ## Quick Restore
 
 ```bash
@@ -103,6 +121,26 @@ auxiliary:
     timeout: 120
 ```
 
+## Violation Classification
+
+When reporting findings, separate POLICY observations from FAULT findings:
+
+### POLICY (observation only, not a fault)
+- Agent uses a non-internal-harness provider (e.g., direct DeepSeek, Tencent, OpenRouter)
+- Config text has a field that looks unusual but the agent's calls are succeeding
+- Example: "POLICY: Koonimo uses deepseek directly; calls succeeding in last hour"
+
+### FAULT (requires request-level evidence)
+- Agent's calls are failing with auth errors (401/403 in logs)
+- Agent's config has no valid API key AND calls are failing
+- Example: "FAULT: Koby's LiteLLM key expired; 401 observed at 2026-09-14 11:42:00"
+
+### Rules
+1. Do NOT infer the runtime's credential resolution from config text alone.
+2. Require request-level evidence before calling something a FAULT: an observed auth failure in the agent's log, or the absence of successful calls in the window.
+3. If calls are succeeding, the correct output is "POLICY: uses <provider> directly; calls succeeding" - not a violation.
+4. State what you OBSERVED, not what the field implies.
+
 ## Known Bug: `api_key_env` Ignored by Auxiliary Client
 
 **Bug location**: `agent/auxiliary_client.py` → `_resolve_task_provider_model()` (line ~5478)

hermes-config-template.prose.md

@@ -19,6 +19,24 @@ description: >
 - agent_keys: map (see Agent Keys section)
 - infra_endpoints_verified: array
 
+## Reachability Detection
+
+Before auditing the config template, verify the host is reachable and can be checked. Use the shared reachability helper from the clone root:
+
+```bash
+# Run on each host to check reachability (Tanko, Mumuni, Koonimo, Koby)
+scripts/hermes-reachability-check.sh <host> "base_url:" "/root/.hermes/config.yaml"
+# Example: scripts/hermes-reachability-check.sh 192.168.68.122 "base_url:" "/root/.hermes/config.yaml"
+
+# Expected outcomes:
+# - UNREACHABLE: SSH connection failed (host is down)
+# - VIOLATION: SSH succeeded and found matches (report the finding)
+# - COMPLIANT: SSH succeeded and found no matches (no base_url in config)
+#
+# NOTE: The bug this replaces was deriving reachability from the remote grep's exit code.
+# The correct pattern: remote side always succeeds (grep ...; true), so ssh status = connection only.
+```
+
 ## Agent Keys (LiteLLM — Current 2026-07-11)
 
 Each agent has a unique LiteLLM API key (virtual key) generated against the LiteLLM
@@ -199,6 +217,26 @@ When LiteLLM keys are regenerated (e.g., after infrastructure changes):
 3. **After update**: Restart Hermes on the agent host
 4. **Verify**: `curl -H "Authorization: Bearer sk-<KEY>" http://192.168.68.116/v1/models`
 
+## Violation Classification
+
+When reporting findings, separate POLICY observations from FAULT findings:
+
+### POLICY (observation only, not a fault)
+- Agent uses a non-internal-harness provider (e.g., direct DeepSeek, Tencent, OpenRouter)
+- Config text has a field that looks unusual but the agent's calls are succeeding
+- Example: "POLICY: Koonimo uses deepseek directly; calls succeeding in last hour"
+
+### FAULT (requires request-level evidence)
+- Agent's calls are failing with auth errors (401/403 in logs)
+- Agent's config has no valid API key AND calls are failing
+- Example: "FAULT: Koby's LiteLLM key expired; 401 observed at 2026-09-14 11:42:00"
+
+### Rules
+1. Do NOT infer the runtime's credential resolution from config text alone.
+2. Require request-level evidence before calling something a FAULT: an observed auth failure in the agent's log, or the absence of successful calls in the window.
+3. If calls are succeeding, the correct output is "POLICY: uses <provider> directly; calls succeeding" - not a violation.
+4. State what you OBSERVED, not what the field implies.
+
 ## Configuration Rules
 
 ### Rule 1: Shared Infra Is Locked

hermes-key-enforcement.prose.md

@@ -117,6 +117,44 @@ model:
   api_key_env: LITELLM_API_KEY
 ```
 
+## Reachability Detection
+
+Before checking for hardcoded keys, verify the host is reachable and can be audited. Use the shared reachability helper from the clone root:
+
+```bash
+# Run on each host to check reachability (Tanko, Mumuni, Koonimo, Koby)
+scripts/hermes-reachability-check.sh <host> "api_key: sk-" "/root/.hermes/"
+# Example: scripts/hermes-reachability-check.sh 192.168.68.122 "api_key: sk-" "/root/.hermes/"
+
+# Expected outcomes:
+# - UNREACHABLE: SSH connection failed (host is down)
+# - VIOLATION: SSH succeeded and found matches (report the finding)
+# - COMPLIANT: SSH succeeded and found no matches (no hardcoded keys in config)
+#
+# NOTE: The bug this replaces was deriving reachability from the remote grep's exit code.
+# The correct pattern: remote side always succeeds (grep ...; true), so ssh status = connection only.
+```
+
+## Violation Classification
+
+When reporting findings, separate POLICY observations from FAULT findings:
+
+### POLICY (observation only, not a fault)
+- Agent uses a non-internal-harness provider (e.g., direct DeepSeek, Tencent, OpenRouter)
+- Config text has a field that looks unusual but the agent's calls are succeeding
+- Example: "POLICY: Koonimo uses deepseek directly; calls succeeding in last hour"
+
+### FAULT (requires request-level evidence)
+- Agent's calls are failing with auth errors (401/403 in logs)
+- Agent's config has no valid API key AND calls are failing
+- Example: "FAULT: Koby's LiteLLM key expired; 401 observed at 2026-09-14 11:42:00"
+
+### Rules
+1. Do NOT infer the runtime's credential resolution from config text alone.
+2. Require request-level evidence before calling something a FAULT: an observed auth failure in the agent's log, or the absence of successful calls in the window.
+3. If calls are succeeding, the correct output is "POLICY: uses <provider> directly; calls succeeding" - not a violation.
+4. State what you OBSERVED, not what the field implies.
+
 ## Detection Query
 
 Run on any Hermes host to detect violations:

scripts/hermes-reachability-check.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Shared helper for Hermes contract reachability checks
+# Separates SSH exit status from remote command result
+
+hermes_check_host() {
+    local host=$1
+    local pattern=$2
+    local path=$3
+    
+    # Remote side always succeeds (grep ...; true), so ssh exit code = connection status only
+    local out
+    out=$(ssh -o BatchMode=yes -o ConnectTimeout=3 root@"$host" "grep -RIn '$pattern' '$path' 2>/dev/null; true" 2>/dev/null)
+    local status=$?
+    
+    if [ $status -ne 0 ]; then
+        echo "$host: UNREACHABLE (ssh exit $status)"
+    elif [ -n "$out" ]; then
+        echo "$host: VIOLATION: $out"
+    else
+        echo "$host: COMPLIANT (no matches found)"
+    fi
+}
+
+# Standalone mode: scripts/hermes-reachability-check.sh <host> <pattern> <path>
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+    if [ $# -ne 3 ]; then
+        echo "Usage: $0 <host> <pattern> <path>" >&2
+        exit 2
+    fi
+    hermes_check_host "$1" "$2" "$3"
+    exit 0
+fi