auto-sync SOUL.md on hermes restart + tighter loop caps (max_turns=20)

Two recurring pain points from the last few operator chats:

1. SOUL.md propagation. Every code change to
   /usr/share/mios/ai/hermes-soul.md required a manual touch +
   systemctl restart on every host because the firstboot seed-
   logic only runs at boot. Worse: `cp` preserves mtime by default,
   so the firstboot-style content-diff check said "no change" and
   the new prose never reached the agent (operator-flagged earlier
   today -- WSLg rule didn't take effect after the deploy).

   Fix: new `mios-hermes-soul-sync` shim does ONLY the SOUL re-seed:
     * Compares source body (BEFORE marker) byte-by-byte with the
       matching prefix of target -- mtime-independent
     * cp + chown + chmod on diff
     * Preserves any `### MIOS-RUNTIME-CONTEXT-BEGIN` block firstboot
       appended (Discord defaults, etc.)
     * Exit 0 on noop OR sync; safe as an ExecStartPre
     * 1 = source missing, 2 = ownership failure (rare)

   Wired via a hermes-agent.service drop-in
   (etc/systemd/system/hermes-agent.service.d/50-soul-sync.conf)
   so every `systemctl restart hermes-agent.service` re-seeds.
   Verified live: restart logged "[mios-hermes-soul-sync] body
   current (23195 bytes) -- noop".

2. Tool-loop guardrails were too loose. Recent chats had agent
   running 19-24 tool calls before giving up. Two layers fixed:

   a. New `agent.max_turns: 20` config (was using upstream default
      90). This caps the OPERATOR-facing turn at 20 iterations.
      delegate_task children still get their own 90-turn budget.
      Most operator asks resolve in 1-3 calls; 20 is generous for
      the multi-step ones.

   b. tool_loop_guardrails thresholds tightened:
        warn_after:      exact 2 -> 1, same_tool 3 -> 2, no_progress 2 -> 1
        hard_stop_after: exact 5 -> 3, same_tool 8 -> 4, no_progress 5 -> 3
      Original incident class: agent called web_extract 4 times in
      a row against searxng (which can only search, not extract)
      before giving up. New thresholds stop after 2 same-tool
      failures (warn) / 4 (hard stop). Idempotent no-progress
      (browser_navigate without CDP) cuts off at 3 calls.

Both changes mirrored in mios-hermes-firstboot so fresh image
builds get them out of the box. Live config patched in-place via
yaml.safe_dump; old config saved to config.yaml.bak-caps.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mios-dev

etc/systemd/system/hermes-agent.service.d/50-soul-sync.conf

@@ -0,0 +1,17 @@
+# /etc/systemd/system/hermes-agent.service.d/50-soul-sync.conf
+#
+# Re-sync /var/lib/mios/hermes/SOUL.md from
+# /usr/share/mios/ai/hermes-soul.md on every service start so SOUL.md
+# updates propagate without a manual touch+restart. Operator-flagged
+# 2026-05-17: WSLg rule didn't take effect after my deploy because
+# `cp` preserved mtime, so the firstboot-style content-diff check
+# said "no change" -- the new prose never reached the agent.
+#
+# mios-hermes-soul-sync exits 0 on noop OR successful sync, so this
+# ExecStartPre is safe to keep enabled even when SOUL.md is current.
+# It also preserves any operator-appended runtime-context block (the
+# ### MIOS-RUNTIME-CONTEXT-BEGIN section firstboot adds for Discord
+# defaults, etc.).
+
+[Service]
+ExecStartPre=/usr/libexec/mios/mios-hermes-soul-sync

usr/libexec/mios/mios-hermes-firstboot

@@ -816,19 +816,28 @@ approvals:
 
 # Tool-loop guardrails. The agent can loop forever on bad tool calls;
 # hard_stop_enabled aborts after N consecutive same-kind failures so
-# a stuck delegate doesn't burn the whole agent budget. Thresholds
-# match the upstream-recommended wizard defaults.
+# a stuck delegate doesn't burn the whole agent budget.
+#
+# Operator-flagged 2026-05-17: chats hitting 19-24 tool calls were
+# below upstream's 5/8/5 thresholds (because each call was a
+# DIFFERENT tool -- agent thrashing across browser/web_extract/
+# skill_view rather than failing the same one repeatedly). The
+# total-call cap (agent.max_turns: 20 above) handles thrashing
+# across different tools; the per-failure thresholds below are now
+# tightened so the agent backs off SOONER on a single tool that
+# keeps erroring (web_extract returning "searxng is search-only"
+# four times before the agent gives up was the original incident).
 tool_loop_guardrails:
   warnings_enabled: true
   hard_stop_enabled: true
   warn_after:
-    exact_failure: 2
-    same_tool_failure: 3
-    idempotent_no_progress: 2
+    exact_failure: 1
+    same_tool_failure: 2
+    idempotent_no_progress: 1
   hard_stop_after:
-    exact_failure: 5
-    same_tool_failure: 8
-    idempotent_no_progress: 5
+    exact_failure: 3
+    same_tool_failure: 4
+    idempotent_no_progress: 3
 
 # Sessions: prune old sessions automatically. Keeps $HERMES_HOME clean
 # without manual \`hermes session prune\` after every long-running build
@@ -853,6 +862,13 @@ sessions:
 # ~2-3s typical restart, 30s worst case. Operator directive 2026-05-15.
 agent:
   restart_drain_timeout: 20
+  # Hard cap on tool-call iterations per chat. Upstream default is 90;
+  # operator-flagged 2026-05-17 had chats running 19-24 tool calls
+  # before giving up. For an OWUI conversational agent 20 is plenty
+  # (most asks resolve in 1-3 calls; multi-step in ~10). Sub-agents
+  # spawned via delegate_task still get their own 90-turn budget --
+  # this cap is for the OPERATOR-facing turn, not the children.
+  max_turns: 20
 EOF
     umask 0022
     chown 820:820 "$HERMES_DATA_CFG" 2>/dev/null || true

usr/libexec/mios/mios-hermes-soul-sync

@@ -0,0 +1,117 @@
+#!/bin/bash
+# /usr/libexec/mios/mios-hermes-soul-sync
+#
+# Idempotent SOUL.md propagation. The hardened vendor SOUL.md lives at
+# /usr/share/mios/ai/hermes-soul.md and is updated by code changes
+# (commit/rebuild). The agent reads $HERMES_HOME/SOUL.md fresh on every
+# message, but only after firstboot has SEEDED that path. Without this
+# shim, SOUL.md updates between firstboot runs require a manual
+# touch+restart on every operator host (operator-flagged 2026-05-17:
+# WSLg rule didn't propagate after my deploy because cp preserved
+# mtime).
+#
+# What this does:
+#   1. Resolve $HERMES_HOME (defaults to /var/lib/mios/hermes).
+#   2. If target SOUL.md exists AND lacks 'MiOS-managed' marker, leave
+#      it alone -- the operator has taken ownership.
+#   3. If source body (BEFORE any appended runtime-context block) is
+#      byte-identical to target body, noop (preserves operator's
+#      appended Discord context, etc.).
+#   4. Otherwise: cp source over target, restore ownership +
+#      permissions, log.
+#
+# Wired as ExecStartPre to hermes-agent.service via a drop-in so SOUL.md
+# is always fresh when hermes boots. Also runnable from firstboot, the
+# operator console, or an "update SOUL.md" automation.
+#
+# Exit codes:
+#   0 = noop or successful sync
+#   1 = source missing (logged, non-fatal -- hermes still starts)
+#   2 = target ownership/permission failure (rare)
+
+set -uo pipefail
+
+SRC="${MIOS_HERMES_SOUL_SRC:-/usr/share/mios/ai/hermes-soul.md}"
+HERMES_HOME="${HERMES_HOME:-/var/lib/mios/hermes}"
+TARGET="${HERMES_HOME}/SOUL.md"
+SOUL_USER="${MIOS_HERMES_USER:-mios-hermes}"
+SOUL_GROUP="${MIOS_HERMES_GROUP:-mios-hermes}"
+# Match the marker firstboot uses; preserve appended context across syncs.
+SOUL_CTX_MARKER="### MIOS-RUNTIME-CONTEXT-BEGIN"
+
+log() { echo "[mios-hermes-soul-sync] $*"; }
+
+if [ ! -r "$SRC" ]; then
+    log "source missing: $SRC -- nothing to sync"
+    exit 1
+fi
+
+# If target absent or shorter than source, just copy.
+if [ ! -f "$TARGET" ]; then
+    install -d -m 0755 -o "$SOUL_USER" -g "$SOUL_GROUP" "$HERMES_HOME" 2>/dev/null || \
+    install -d -m 0755 "$HERMES_HOME"
+    cp -f "$SRC" "$TARGET"
+    chown "$SOUL_USER:$SOUL_GROUP" "$TARGET" 2>/dev/null || true
+    chmod 0644 "$TARGET"
+    log "seeded $TARGET (target absent)"
+    exit 0
+fi
+
+# Operator-owned? Don't touch.
+if ! grep -q 'MiOS-managed' "$TARGET" 2>/dev/null; then
+    log "target lacks 'MiOS-managed' marker -- operator-owned, leaving alone"
+    exit 0
+fi
+
+# Compare body-only. Body is everything BEFORE the runtime-context
+# marker in the TARGET; everything in SOURCE is body (source has no
+# runtime-context, firstboot appends it after copy).
+SRC_BYTES=$(wc -c < "$SRC")
+# Extract the matching prefix of the target (up to the marker line).
+TARGET_BODY_TMP=$(mktemp)
+awk -v m="$SOUL_CTX_MARKER" '
+    { if (index($0, m) > 0) { exit } else { print } }
+' "$TARGET" > "$TARGET_BODY_TMP"
+TARGET_BODY_BYTES=$(wc -c < "$TARGET_BODY_TMP")
+
+# Strip trailing whitespace from target body so the comparison ignores
+# the blank-line padding firstboot adds before the marker.
+sed -i -e '$ { /^$/d; }' "$TARGET_BODY_TMP" 2>/dev/null || true
+# Re-measure after the trim.
+TARGET_BODY_BYTES=$(wc -c < "$TARGET_BODY_TMP")
+
+# If sizes match within a small tolerance AND cmp matches on the
+# source byte length, the body is current.
+if [ "$TARGET_BODY_BYTES" -ge "$SRC_BYTES" ] && \
+   cmp -s -n "$SRC_BYTES" "$SRC" "$TARGET"; then
+    log "body current ($SRC_BYTES bytes) -- noop"
+    rm -f "$TARGET_BODY_TMP"
+    exit 0
+fi
+
+# Body differs -- preserve any appended runtime-context block, then
+# rewrite the body from source.
+RUNTIME_CTX_TMP=$(mktemp)
+# Lines from marker onwards (inclusive of marker). awk '/marker/,EOF'
+# would include the marker; cleaner: print from marker hit onwards.
+awk -v m="$SOUL_CTX_MARKER" '
+    BEGIN { keep = 0 }
+    { if (index($0, m) > 0) keep = 1; if (keep) print }
+' "$TARGET" > "$RUNTIME_CTX_TMP"
+
+NEW_TMP=$(mktemp)
+cat "$SRC" > "$NEW_TMP"
+if [ -s "$RUNTIME_CTX_TMP" ]; then
+    printf '\n\n' >> "$NEW_TMP"
+    cat "$RUNTIME_CTX_TMP" >> "$NEW_TMP"
+fi
+
+# Atomic write, preserving target ownership.
+cp -f "$NEW_TMP" "$TARGET"
+chown "$SOUL_USER:$SOUL_GROUP" "$TARGET" 2>/dev/null || true
+chmod 0644 "$TARGET"
+rm -f "$TARGET_BODY_TMP" "$RUNTIME_CTX_TMP" "$NEW_TMP"
+
+NEW_BYTES=$(wc -c < "$TARGET")
+log "synced $TARGET (body=$SRC_BYTES bytes, total=$NEW_BYTES bytes with runtime-context)"
+exit 0