fix: resolve 6 installation bugs in setup.sh and docker-compose

- Bug 1: QDRANT_API_KEY unbound variable (default to empty)
- Bug 2: Qdrant v1.17+ auth with empty key (conditional config)
- Bug 3: Redis crash with empty requirepass (conditional config)
- Bug 4: grep pattern now covers OPENROUTER_DS_API_KEY
- Bug 5: worker container healthcheck added
- Bug 7: execution-agent protocol installed during setup

Author: ClaudioDrews

docker/docker-compose.yml

@@ -10,7 +10,10 @@ services:
     command: >
       sh -c '
         mkdir -p /usr/local/etc/redis &&
-        echo "requirepass $${REDIS_PASSWORD}" > /usr/local/etc/redis/redis.conf &&
+        : > /usr/local/etc/redis/redis.conf &&
+        if [ -n "$${REDIS_PASSWORD}" ]; then
+          echo "requirepass $${REDIS_PASSWORD}" >> /usr/local/etc/redis/redis.conf;
+        fi &&
         echo "bind 0.0.0.0" >> /usr/local/etc/redis/redis.conf &&
         echo "appendonly yes" >> /usr/local/etc/redis/redis.conf &&
         echo "maxmemory 512mb" >> /usr/local/etc/redis/redis.conf &&
@@ -24,7 +27,7 @@ services:
     volumes:
       - redis_data:/data
     healthcheck:
-      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
+      test: ["CMD-SHELL", "redis-cli ${REDIS_PASSWORD:+-a $REDIS_PASSWORD} ping"]
       interval: 5s
       timeout: 3s
       retries: 5
@@ -62,7 +65,7 @@ services:
       REDIS_PASSWORD: ${REDIS_PASSWORD}
       QDRANT_HOST: qdrant
       QDRANT_PORT: "6333"
-      QDRANT_API_KEY: ${QDRANT_API_KEY}
+      QDRANT_API_KEY: ${QDRANT_API_KEY:-}
       OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
       EMBEDDING_DIMS: "${EMBEDDING_DIMS:-4096}"
       COLLECTION_NAME: "${COLLECTION_NAME:-knowledge_base}"
@@ -74,6 +77,15 @@ services:
       - ${MEMORY_OS_WIKI_PATH:-./wiki}:/wiki:ro
       - ${MEMORY_OS_HERMES_HOME:-./hermes}:/hermes:rw
       - ${MEMORY_OS_FABRIC_DIR:-./fabric}:/fabric:rw
+    healthcheck:
+      # Verifies the worker can reach Redis with auth — if this passes the ARQ
+      # event loop is operational.  Overrides the Dockerfile HEALTHCHECK which
+      # does not include REDIS_PASSWORD.
+      test: ["CMD-SHELL", "python -c \"import os,redis; r=redis.Redis(host='redis',port=6379,password=os.environ.get('REDIS_PASSWORD') or None,socket_connect_timeout=3); r.ping()\""]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
 
 volumes:
   redis_data:

modifications/execution-agent-protocol.md

@@ -30,9 +30,19 @@ In the left column, "relevante" could describe any block in any session — it c
 - If no injected entry addresses the request: state explicitly: "No injected context covers [X]. Proceeding with tool verification."
 - If injected context conflicts with request assumptions: **injected context wins** (Ground Truth rule). Adjust your approach.
 
-### Step 4 — Then act
+### Step 4 — Gate: plane, present, wait
 
-Only after completing Steps 1-3 may you make your first tool call. This sequence must be visible in your response.
+- If your response requires **more than one tool call**, you MUST present a plan first.
+- Show the plan. Do NOT execute any tool calls in the same turn.
+- Wait for explicit user authorization before proceeding.
+- If the user asks questions about the plan → answer them, but **do not execute anything**.
+- Only when the user says "ok", "execute", "vá", "prossiga", or equivalent → then execute.
+- **No exceptions for triviality.** Even actions that seem obvious require authorization.
+- This gate applies even when injected memory provides clear answers — the user may have new context.
+
+### Step 5 — Then act
+
+Only after completing Steps 1-4, and only after user authorization, may you make your first tool call. This sequence must be visible in your response.
 
 ### Why this exists
 

setup.sh

@@ -25,6 +25,12 @@
 # ──────────────────────────────────────────────────────────────────────────────
 set -euo pipefail
 
+# ── Safe defaults for optional env vars ──────────────────────────────────────
+# Must come before any reference to these names.  set -u would abort with
+# \"unbound variable\" if they were never exported by the caller.
+QDRANT_API_KEY="${QDRANT_API_KEY:-}"
+REDIS_PASSWORD="${REDIS_PASSWORD:-}"
+
 # ── Colors ────────────────────────────────────────────────────────────────────
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -212,7 +218,7 @@ cd "${DOCKER_DIR}"
 # Detect API key from Hermes .env
 OPENROUTER_KEY=""
 if [ -f "${ENV_FILE}" ]; then
-    OPENROUTER_KEY=$(grep -oP 'OPENROUTER_API_KEY=\K.*' "${ENV_FILE}" 2>/dev/null | head -1 || true)
+    OPENROUTER_KEY=$(grep -oP '(?:OPENROUTER.*API_KEY|LLM_API_KEY)=\K.*' "${ENV_FILE}" 2>/dev/null | head -1 || true)
 fi
 
 if [ -z "${OPENROUTER_KEY}" ]; then
@@ -334,23 +340,38 @@ ok "Environment variables added to Hermes .env"
 # ──────────────────────────────────────────────────────────────────────────────
 banner "Phase 9: Rulebook"
 
+SOUL_FILE="${HERMES_HOME}/SOUL.md"
 RULEBOOK="${HERMES_HOME}/rulebook.md"
+PROTOCOL_FILE="${REPO_DIR}/modifications/execution-agent-protocol.md"
+MARKER="Mandatory Pre-Action Protocol"
 
-if [ -f "${RULEBOOK}" ]; then
-    if grep -q "Mandatory Pre-Action Protocol" "${RULEBOOK}" 2>/dev/null; then
-        ok "Rulebook amendments already applied"
-    else
-        PROTOCOL_FILE="${REPO_DIR}/modifications/execution-agent-protocol.md"
-        if [ -f "${PROTOCOL_FILE}" ]; then
+if [ ! -f "${PROTOCOL_FILE}" ]; then
+    warn "execution-agent-protocol.md not found — skipping modifications"
+else
+    # Try SOUL.md first — behavioral tests show 3/6 compliance when protocol
+    # is in SOUL.md vs 0/6 when it is only in rulebook.md.
+    if [ -f "${SOUL_FILE}" ]; then
+        if grep -q "${MARKER}" "${SOUL_FILE}" 2>/dev/null; then
+            ok "Mandatory Pre-Action Protocol already in SOUL.md"
+        else
+            echo "" >> "${SOUL_FILE}"
+            echo "<!-- Memory OS additions — do not duplicate -->" >> "${SOUL_FILE}"
+            cat "${PROTOCOL_FILE}" >> "${SOUL_FILE}"
+            ok "Mandatory Pre-Action Protocol appended to SOUL.md"
+        fi
+    elif [ -f "${RULEBOOK}" ]; then
+        if grep -q "${MARKER}" "${RULEBOOK}" 2>/dev/null; then
+            ok "Rulebook amendments already applied"
+        else
             echo "" >> "${RULEBOOK}"
             cat "${PROTOCOL_FILE}" >> "${RULEBOOK}"
             ok "Mandatory Pre-Action Protocol appended to rulebook"
-        else
-            warn "execution-agent-protocol.md not found — skipping"
         fi
+    else
+        warn "Neither SOUL.md nor rulebook.md found"
+        info "To install the protocol manually:"
+        info "  cat ${PROTOCOL_FILE} >> ${HERMES_HOME}/SOUL.md"
     fi
-else
-    warn "${RULEBOOK} not found — skipping modifications"
 fi
 
 # ──────────────────────────────────────────────────────────────────────────────