eagle-mem 4.10.10 → 4.10.11

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to the **Eagle Mem** project are documented here.
 
 ---
 
+## v4.10.11 Reliability Guards and Provider Fallback
+
+This patch closes the active reliability items that remained after the Dream Cycle hotfix:
+
+- **Command-Scoped Logs**: `scan`, `index`, and `curate` now write per-run logs under `~/.eagle-mem/runs`, preserve normal CLI output, and print the log path on command failure. Added `eagle-mem logs list|tail|show` for inspection.
+- **Provider Fallback Transparency**: Provider calls now use an explicit fallback chain. `agent_cli` can fall through from a failed preferred Codex call to Claude Code when available, and provider display now shows the actual chain instead of `unknown`.
+- **Read Prediction / Token Guard Scoring**: `PreToolUse` now scores repeated, large, or recently modified reads and emits a targeted read-score nudge. A configurable `read_guard.mode=block` path is available for stricter high-confidence duplicate-read gating.
+- **Auto-Scan Retry Reliability**: SessionStart auto-scan/index freshness markers are now cleared when the background job fails, so failed scans do not block retries for the next 24 hours.
+- **Hook Field Parsing**: Hook JSON field extraction now uses the intended unit separator in `PreToolUse`, `UserPromptSubmit`, and `Stop`, preserving clean `tool_name`, `session_id`, and `cwd` parsing.
+- **Regression Coverage**: Added an isolated reliability test for provider fallback, read scoring, auto-scan failure state cleanup, and run-log creation.
+
+---
+
 ## v4.10.10 Dream Cycle Consolidation Hardening
 
 This patch closes the review findings from the multi-model Spectral pass:

package/README.md

@@ -146,6 +146,7 @@ Eagle Mem prevents Claude from repeating past mistakes:
 | `eagle-mem search` | Search past sessions, memories, and code |
 | `eagle-mem health` | Diagnose pipeline health and background automation |
 | `eagle-mem doctor` | Verify installed runtime files, hooks, SQLite/FTS5, statusline, manifest, and drift |
+| `eagle-mem logs` | Inspect command-scoped `scan`, `index`, and `curate` run logs |
 | `eagle-mem config` | View or change LLM provider and token-guard settings |
 | `eagle-mem updates` | View or change auto-update policy |
 | `eagle-mem guard` | Manage regression guardrails for files |
@@ -346,6 +347,8 @@ eagle-mem config set agent_cli.preferred current
 
 Provider preference is local-first: Ollama is auto-detected when running, then Eagle Mem can use the installed Codex/Claude CLI via `agent_cli` before falling back to explicit Anthropic/OpenAI API providers. Eagle Mem works fully without a provider — LLM features gracefully degrade to heuristic fallbacks.
 
+Provider calls use an explicit fallback chain by default. For example, `agent_cli` can try the preferred/current agent first and then fall through to another supported local CLI when available. `eagle-mem config`, `eagle-mem health`, and `eagle-mem curate` display the resolved provider path so failed or unavailable agent CLIs are visible instead of appearing as `unknown`.
+
 RTK is configured separately from the LLM provider:
 
 ```bash
@@ -353,6 +356,8 @@ eagle-mem config set token_guard.rtk auto      # default: use RTK when available
 eagle-mem config set token_guard.rtk enforce   # block known raw-output commands if RTK is missing
 eagle-mem config set token_guard.rtk off       # disable RTK behavior
 eagle-mem config set token_guard.raw_bash block
+eagle-mem config set read_guard.mode advisory  # score repeated reads and nudge
+eagle-mem config set read_guard.mode block     # optionally block high-confidence duplicate reads
 ```
 
 ## Long-term Direction

package/bin/eagle-mem

@@ -22,6 +22,7 @@ case "$command" in
     search)     bash "$SCRIPTS_DIR/search.sh" "$@" ;;
     health)     bash "$SCRIPTS_DIR/health.sh" "$@" ;;
     doctor)     bash "$SCRIPTS_DIR/doctor.sh" "$PACKAGE_DIR" "$@" ;;
+    logs)       bash "$SCRIPTS_DIR/logs.sh" "$@" ;;
     config)     bash "$SCRIPTS_DIR/config.sh" "$@" ;;
     updates)    bash "$SCRIPTS_DIR/updates.sh" "$@" ;;
     statusline) "$SCRIPTS_DIR/statusline-em.sh" "$@" ;;

package/hooks/post-tool-use.sh

@@ -18,7 +18,7 @@ input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
 
 IFS=$'\x1f' read -r session_id cwd tool_name hook_event <<< \
-    "$(echo "$input" | jq -r '[.session_id, .cwd, .tool_name, .hook_event_name] | map(. // "") | join("")')"
+    "$(echo "$input" | jq -r '[.session_id, .cwd, .tool_name, .hook_event_name] | map(. // "") | join("\u001f")')"
 agent=$(eagle_agent_source_from_json "$input")
 
 if [ -z "$session_id" ]; then exit 0; fi
@@ -173,12 +173,15 @@ if [ -n "$fp" ] && [ -n "$session_id" ] && eagle_validate_session_id "$session_i
             mod_dir="$EAGLE_MEM_DIR/mod-tracker"
             mkdir -p "$mod_dir" 2>/dev/null
             mod_file="$mod_dir/${session_id}"
-            echo "$fp" >> "$mod_file"
-            # Keep only last 3 entries — use per-process tmp to avoid
-            # race when parallel PostToolUse hooks fire on same session
-            if [ -f "$mod_file" ]; then
+            mod_lock="${mod_file}.lock"
+            if mkdir "$mod_lock" 2>/dev/null; then
                 _mod_tmp=$(mktemp "${mod_file}.XXXXXX" 2>/dev/null) || _mod_tmp="${mod_file}.$$"
-                tail -3 "$mod_file" > "$_mod_tmp" && mv "$_mod_tmp" "$mod_file" || rm -f "$_mod_tmp"
+                (cat "$mod_file" 2>/dev/null; printf '%s\n' "$fp") | tail -3 > "$_mod_tmp"
+                mv "$_mod_tmp" "$mod_file" 2>/dev/null || rm -f "$_mod_tmp"
+                rmdir "$mod_lock" 2>/dev/null || true
+            else
+                # If another hook is trimming, append is still safer than losing the edit.
+                printf '%s\n' "$fp" >> "$mod_file"
             fi
 
             # Full edit history for stuck loop detection (not truncated)

package/hooks/pre-tool-use.sh

@@ -22,7 +22,7 @@ input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
 
 IFS=$'\x1f' read -r tool_name session_id cwd <<< \
-    "$(echo "$input" | jq -r '[.tool_name, .session_id, .cwd] | map(. // "") | join("")')"
+    "$(echo "$input" | jq -r '[.tool_name, .session_id, .cwd] | map(. // "") | join("\u001f")')"
 agent=$(eagle_agent_source_from_json "$input")
 
 case "$tool_name" in
@@ -295,11 +295,15 @@ Edit|Write|apply_patch)
 Read)
     fp=$(echo "$input" | jq -r '.tool_input.file_path // empty')
     if [ -n "$fp" ] && [ -n "$session_id" ] && eagle_validate_session_id "$session_id"; then
+        read_score=0
+        read_reasons=""
 
         # ─── Read-after-modify detection ──────────────────────
         mod_file="$EAGLE_MEM_DIR/mod-tracker/${session_id}"
         if [ -f "$mod_file" ] && grep -qFx -- "$fp" "$mod_file" 2>/dev/null; then
             context+="Eagle Mem recall: '$(basename "$fp")' was just edited/written — the diff is already in context from the tool output. "
+            read_score=$((read_score + 45))
+            read_reasons="${read_reasons}recently modified; "
         fi
 
         # ─── Read dedup tracker (soft nudge) ──────────────────
@@ -312,6 +316,69 @@ Read)
         if [ "$read_count" -ge 3 ]; then
             context+="Eagle Mem recall: '$(basename "$fp")' has been read ${read_count} times this session. Its contents are likely already in context."
         fi
+
+        if [ "$read_count" -ge 2 ]; then
+            repeat_score=$((20 + (read_count - 2) * 10))
+            [ "$repeat_score" -gt 40 ] && repeat_score=40
+            read_score=$((read_score + repeat_score))
+            read_reasons="${read_reasons}${read_count} reads this session; "
+        fi
+
+        hot_files=$(eagle_get_hot_files "$project" 2>/dev/null || true)
+        if [ -n "$hot_files" ]; then
+            fp_base=$(basename "$fp")
+            case ",$hot_files," in
+                *"/$fp_base,"*|*",$fp_base,"*)
+                    read_score=$((read_score + 10))
+                    read_reasons="${read_reasons}hot file; "
+                    ;;
+            esac
+        fi
+
+        full_fp="$fp"
+        if [ ! -f "$full_fp" ] && [ -n "$cwd" ] && [ -f "$cwd/$fp" ]; then
+            full_fp="$cwd/$fp"
+        fi
+        if [ -f "$full_fp" ]; then
+            file_size=$(wc -c < "$full_fp" 2>/dev/null | tr -d ' ')
+            file_size=${file_size:-0}
+            if [ "$file_size" -ge 500000 ] 2>/dev/null; then
+                read_score=$((read_score + 20))
+                read_reasons="${read_reasons}large file; "
+            elif [ "$file_size" -ge 150000 ] 2>/dev/null; then
+                read_score=$((read_score + 10))
+                read_reasons="${read_reasons}medium-large file; "
+            fi
+        fi
+
+        [ "$read_score" -gt 100 ] && read_score=100
+        score_threshold=$(eagle_read_guard_score_threshold)
+        block_threshold=$(eagle_read_guard_block_threshold)
+        read_guard_mode=$(eagle_read_guard_mode)
+        read_reasons=${read_reasons%; }
+        if [ "$read_score" -ge "$score_threshold" ] 2>/dev/null; then
+            context+=" Eagle Mem read score: ${read_score}/100 for '$(basename "$fp")'"
+            [ -n "$read_reasons" ] && context+=" (${read_reasons})"
+            context+=". Prefer the existing context, recent diff, or targeted search unless you need exact fresh lines."
+        fi
+        if [ "$read_guard_mode" = "block" ] && [ "$read_score" -ge "$block_threshold" ] 2>/dev/null && ! eagle_raw_bash_unlock_active; then
+            reason="Eagle Mem blocked this high-confidence duplicate read to save context tokens.
+
+File: $(basename "$fp")
+Score: ${read_score}/100
+Reason: ${read_reasons:-repeated read}
+
+Use the existing context, run a narrower search, or bypass once with:
+  touch $EAGLE_RAW_BASH_UNLOCK"
+            jq -nc --arg reason "$reason" '{
+                "hookSpecificOutput":{
+                    "hookEventName":"PreToolUse",
+                    "permissionDecision":"deny",
+                    "permissionDecisionReason":$reason
+                }
+            }'
+            exit 0
+        fi
     fi
     ;;
 esac

package/hooks/stop.sh

@@ -22,7 +22,7 @@ input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
 
 IFS=$'\x1f' read -r session_id cwd transcript_path agent_type <<< \
-    "$(echo "$input" | jq -r '[.session_id, .cwd, .transcript_path, .agent_type] | map(. // "") | join("")')"
+    "$(echo "$input" | jq -r '[.session_id, .cwd, .transcript_path, .agent_type] | map(. // "") | join("\u001f")')"
 last_assistant_message=$(echo "$input" | jq -r '.last_assistant_message // empty')
 agent=$(eagle_agent_source_from_json "$input")
 

package/hooks/user-prompt-submit.sh

@@ -19,7 +19,7 @@ input=$(eagle_read_stdin)
 [ -z "$input" ] && exit 0
 
 IFS=$'\x1f' read -r session_id cwd <<< \
-    "$(echo "$input" | jq -r '[.session_id, .cwd] | map(. // "") | join("")')"
+    "$(echo "$input" | jq -r '[.session_id, .cwd] | map(. // "") | join("\u001f")')"
 user_prompt=$(echo "$input" | jq -r '.prompt // empty')
 agent=$(eagle_agent_source_from_json "$input")
 

package/lib/common.sh

@@ -7,6 +7,7 @@
 EAGLE_MEM_DIR="${EAGLE_MEM_DIR:-$HOME/.eagle-mem}"
 EAGLE_MEM_DB="$EAGLE_MEM_DIR/memory.db"
 EAGLE_MEM_LOG="$EAGLE_MEM_DIR/eagle-mem.log"
+EAGLE_RUNS_DIR="${EAGLE_RUNS_DIR:-$EAGLE_MEM_DIR/runs}"
 EAGLE_SETTINGS="${EAGLE_SETTINGS:-$HOME/.claude/settings.json}"
 EAGLE_SKILLS_DIR="${EAGLE_SKILLS_DIR:-$HOME/.claude/skills}"
 EAGLE_CLAUDE_PROJECTS_DIR="${EAGLE_CLAUDE_PROJECTS_DIR:-$HOME/.claude/projects}"
@@ -112,6 +113,60 @@ eagle_log() {
     echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [$level] $*" >> "$EAGLE_MEM_LOG" 2>/dev/null || true
 }
 
+eagle_run_slug() {
+    printf '%s' "${1:-command}" \
+        | tr -c 'A-Za-z0-9._-' '-' \
+        | sed 's/^-*//;s/-*$//' \
+        | cut -c1-48
+}
+
+eagle_run_start() {
+    [ "${EAGLE_RUN_ACTIVE:-0}" = "1" ] && return 0
+
+    local command_name="$1" project="${2:-}" target="${3:-}"
+    local slug
+    slug=$(eagle_run_slug "$command_name")
+    [ -n "$slug" ] || slug="command"
+
+    mkdir -p "$EAGLE_RUNS_DIR" "$EAGLE_MEM_DIR" 2>/dev/null || true
+    EAGLE_RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-${slug}-$$"
+    EAGLE_RUN_LOG="$EAGLE_RUNS_DIR/${EAGLE_RUN_ID}.log"
+    EAGLE_RUN_COMMAND="$command_name"
+    EAGLE_RUN_PROJECT="$project"
+    EAGLE_RUN_TARGET="$target"
+    EAGLE_RUN_ACTIVE=1
+    export EAGLE_RUN_ID EAGLE_RUN_LOG EAGLE_RUN_COMMAND EAGLE_RUN_PROJECT EAGLE_RUN_TARGET EAGLE_RUN_ACTIVE
+
+    touch "$EAGLE_RUN_LOG" 2>/dev/null && chmod 600 "$EAGLE_RUN_LOG" 2>/dev/null || true
+    {
+        printf '[%s] [INFO] run_start id=%s command=%s project=%s target=%s cwd=%s\n' \
+            "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$EAGLE_RUN_ID" "$command_name" "$project" "$target" "$(pwd)"
+    } >> "$EAGLE_RUN_LOG" 2>/dev/null || true
+
+    # Keep normal CLI output intact while also preserving a command-scoped log.
+    exec > >(tee -a "$EAGLE_RUN_LOG") 2> >(tee -a "$EAGLE_RUN_LOG" >&2)
+    eagle_log "INFO" "Run started: id=$EAGLE_RUN_ID command=$command_name project=$project log=$EAGLE_RUN_LOG"
+}
+
+eagle_run_step() {
+    [ "${EAGLE_RUN_ACTIVE:-0}" = "1" ] || return 0
+    printf '[%s] [STEP] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" >> "$EAGLE_RUN_LOG" 2>/dev/null || true
+}
+
+eagle_run_finish() {
+    [ "${EAGLE_RUN_ACTIVE:-0}" = "1" ] || return 0
+    local rc="${1:-0}" line="${2:-unknown}"
+    printf '[%s] [INFO] run_finish id=%s rc=%s line=%s\n' \
+        "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$EAGLE_RUN_ID" "$rc" "$line" >> "$EAGLE_RUN_LOG" 2>/dev/null || true
+    if [ "$rc" -ne 0 ] 2>/dev/null; then
+        eagle_log "ERROR" "Run failed: id=$EAGLE_RUN_ID command=${EAGLE_RUN_COMMAND:-unknown} rc=$rc line=$line log=${EAGLE_RUN_LOG:-}"
+        printf '\nEagle Mem command failed: %s (exit %s, line %s)\nLog: %s\n' \
+            "${EAGLE_RUN_COMMAND:-unknown}" "$rc" "$line" "${EAGLE_RUN_LOG:-unknown}" >&2
+    else
+        eagle_log "INFO" "Run finished: id=$EAGLE_RUN_ID command=${EAGLE_RUN_COMMAND:-unknown} rc=0"
+    fi
+}
+
 eagle_normalize_project_path() {
     local path="${1:-$(pwd)}"
 
@@ -925,6 +980,36 @@ eagle_token_guard_raw_bash_mode() {
     fi
 }
 
+eagle_read_guard_mode() {
+    if declare -F eagle_config_get >/dev/null 2>&1; then
+        eagle_config_get "read_guard" "mode" "advisory"
+    else
+        eagle_config_get_light "read_guard" "mode" "advisory"
+    fi
+}
+
+eagle_read_guard_score_threshold() {
+    local threshold
+    if declare -F eagle_config_get >/dev/null 2>&1; then
+        threshold=$(eagle_config_get "read_guard" "score_threshold" "70")
+    else
+        threshold=$(eagle_config_get_light "read_guard" "score_threshold" "70")
+    fi
+    case "$threshold" in *[!0-9]*|"") threshold=70 ;; esac
+    printf '%s\n' "$threshold"
+}
+
+eagle_read_guard_block_threshold() {
+    local threshold
+    if declare -F eagle_config_get >/dev/null 2>&1; then
+        threshold=$(eagle_config_get "read_guard" "block_threshold" "90")
+    else
+        threshold=$(eagle_config_get_light "read_guard" "block_threshold" "90")
+    fi
+    case "$threshold" in *[!0-9]*|"") threshold=90 ;; esac
+    printf '%s\n' "$threshold"
+}
+
 eagle_raw_output_command_needs_guard() {
     local cmd="$1"
     local first

package/lib/hooks-sessionstart.sh

@@ -12,18 +12,23 @@ _eagle_state_slug() {
     printf '%s' "$1" | shasum | cut -c1-12
 }
 
+_eagle_state_file() {
+    local key="$1" project="$2"
+    local safe_project; safe_project=$(_eagle_state_slug "$project")
+    printf '%s/%s-%s\n' "$_state_dir" "$key" "$safe_project"
+}
+
 _eagle_state_fresh() {
     local key="$1" project="$2" max_age_days="${3:-1}"
-    local safe_project; safe_project=$(_eagle_state_slug "$project")
-    local state_file="$_state_dir/${key}-${safe_project}"
+    local state_file; state_file=$(_eagle_state_file "$key" "$project")
     [ -f "$state_file" ] && [ -z "$(find "$state_file" -mtime +${max_age_days} 2>/dev/null)" ]
 }
 
 _eagle_state_touch() {
     local key="$1" project="$2"
-    local safe_project; safe_project=$(_eagle_state_slug "$project")
+    local state_file; state_file=$(_eagle_state_file "$key" "$project")
     mkdir -p "$_state_dir" 2>/dev/null
-    touch "$_state_dir/${key}-${safe_project}"
+    touch "$state_file"
 }
 
 eagle_sessionstart_auto_provision() {
@@ -51,15 +56,63 @@ eagle_sessionstart_auto_provision() {
         eagle_log "INFO" "SessionStart: first-session provision — scan then index"
         _eagle_state_touch "scan" "$project"
         _eagle_state_touch "index" "$project"
-        nohup bash -c "bash '$scripts_dir/scan.sh' '$cwd' >> '$EAGLE_MEM_LOG' 2>&1; bash '$scripts_dir/index.sh' '$cwd' >> '$EAGLE_MEM_LOG' 2>&1" &
+        scan_state=$(_eagle_state_file "scan" "$project")
+        index_state=$(_eagle_state_file "index" "$project")
+        nohup bash -c '
+            scripts_dir="$1"; cwd="$2"; log="$3"; scan_state="$4"; index_state="$5"
+            bash "$scripts_dir/scan.sh" "$cwd" >> "$log" 2>&1
+            scan_rc=$?
+            if [ "$scan_rc" -eq 0 ]; then
+                touch "$scan_state" 2>/dev/null || true
+            else
+                rm -f "$scan_state" 2>/dev/null || true
+                printf "[%s] [ERROR] SessionStart: auto-scan failed rc=%s\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$scan_rc" >> "$log" 2>/dev/null || true
+            fi
+
+            bash "$scripts_dir/index.sh" "$cwd" >> "$log" 2>&1
+            index_rc=$?
+            if [ "$index_rc" -eq 0 ]; then
+                touch "$index_state" 2>/dev/null || true
+            else
+                rm -f "$index_state" 2>/dev/null || true
+                printf "[%s] [ERROR] SessionStart: auto-index failed rc=%s\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$index_rc" >> "$log" 2>/dev/null || true
+            fi
+
+            [ "$scan_rc" -eq 0 ] && exit "$index_rc"
+            exit "$scan_rc"
+        ' eagle-auto "$scripts_dir" "$cwd" "$EAGLE_MEM_LOG" "$scan_state" "$index_state" &
     elif [ "$needs_scan" = true ]; then
         eagle_log "INFO" "SessionStart: auto-scan triggered"
         _eagle_state_touch "scan" "$project"
-        nohup bash "$scripts_dir/scan.sh" "$cwd" >> "$EAGLE_MEM_LOG" 2>&1 &
+        scan_state=$(_eagle_state_file "scan" "$project")
+        nohup bash -c '
+            scripts_dir="$1"; cwd="$2"; log="$3"; scan_state="$4"
+            bash "$scripts_dir/scan.sh" "$cwd" >> "$log" 2>&1
+            rc=$?
+            if [ "$rc" -eq 0 ]; then
+                touch "$scan_state" 2>/dev/null || true
+            else
+                rm -f "$scan_state" 2>/dev/null || true
+                printf "[%s] [ERROR] SessionStart: auto-scan failed rc=%s\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$rc" >> "$log" 2>/dev/null || true
+            fi
+            exit "$rc"
+        ' eagle-auto "$scripts_dir" "$cwd" "$EAGLE_MEM_LOG" "$scan_state" &
     elif [ "$needs_index" = true ]; then
         eagle_log "INFO" "SessionStart: auto-index triggered"
         _eagle_state_touch "index" "$project"
-        nohup bash "$scripts_dir/index.sh" "$cwd" >> "$EAGLE_MEM_LOG" 2>&1 &
+        index_state=$(_eagle_state_file "index" "$project")
+        nohup bash -c '
+            scripts_dir="$1"; cwd="$2"; log="$3"; index_state="$4"
+            bash "$scripts_dir/index.sh" "$cwd" >> "$log" 2>&1
+            rc=$?
+            if [ "$rc" -eq 0 ]; then
+                touch "$index_state" 2>/dev/null || true
+            else
+                rm -f "$index_state" 2>/dev/null || true
+                printf "[%s] [ERROR] SessionStart: auto-index failed rc=%s\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$rc" >> "$log" 2>/dev/null || true
+            fi
+            exit "$rc"
+        ' eagle-auto "$scripts_dir" "$cwd" "$EAGLE_MEM_LOG" "$index_state" &
     fi
 }
 

package/lib/provider.sh

@@ -152,6 +152,8 @@ eagle_config_init() {
 # Which LLM provider to use for the curator and analysis features
 # Options: "ollama" (free, local), "agent_cli" (Codex/Claude CLI auth), "anthropic", "openai"
 type = "$provider"
+# "auto" retries local/agent/API fallbacks when the primary provider fails.
+fallback = "auto"
 
 [ollama]
 url = "$ollama_url"
@@ -207,6 +209,12 @@ rtk = "auto"
 # "allow" keeps RTK advisory only.
 raw_bash = "block"
 
+[read_guard]
+# advisory = score repeated/expensive reads and nudge; block = deny high-score rereads.
+mode = "advisory"
+score_threshold = "70"
+block_threshold = "90"
+
 [redaction]
 # Additional secret patterns (regex) beyond built-in defaults
 # extra_patterns = ["MY_CUSTOM_SECRET_.*"]
@@ -223,14 +231,39 @@ eagle_llm_call() {
     local system_prompt="${2:-You are a helpful assistant that analyzes software development sessions.}"
     local max_tokens="${3:-1024}"
 
-    local provider
+    local provider chain candidate result rc tried=0
     provider=$(eagle_config_get "provider" "type" "none")
+    chain=$(_eagle_provider_chain "$provider")
+
+    if [ -z "$chain" ]; then
+        eagle_log "ERROR" "No LLM provider configured or available. Run: eagle-mem config"
+        return 1
+    fi
+
+    while IFS= read -r candidate; do
+        [ -z "$candidate" ] && continue
+        tried=$((tried + 1))
+        result=$(_eagle_call_provider_once "$candidate" "$prompt" "$system_prompt" "$max_tokens")
+        rc=$?
+        if [ "$rc" -eq 0 ] && [ -n "$result" ]; then
+            [ "$candidate" != "$provider" ] && eagle_log "INFO" "LLM provider fallback succeeded: primary=$provider used=$candidate"
+            printf '%s\n' "$result"
+            return 0
+        fi
+        eagle_log "WARN" "LLM provider candidate failed: primary=$provider candidate=$candidate rc=$rc"
+    done <<< "$chain"
+
+    eagle_log "ERROR" "All LLM provider candidates failed: primary=$provider tried=$tried"
+    return 1
+}
 
+_eagle_call_provider_once() {
+    local provider="$1" prompt="$2" system_prompt="$3" max_tokens="$4"
     case "$provider" in
-        ollama)   _eagle_call_ollama "$prompt" "$system_prompt" "$max_tokens" ;;
+        ollama)    _eagle_call_ollama "$prompt" "$system_prompt" "$max_tokens" ;;
         agent_cli) _eagle_call_agent_cli "$prompt" "$system_prompt" "$max_tokens" ;;
         anthropic) _eagle_call_anthropic "$prompt" "$system_prompt" "$max_tokens" ;;
-        openai)   _eagle_call_openai "$prompt" "$system_prompt" "$max_tokens" ;;
+        openai)    _eagle_call_openai "$prompt" "$system_prompt" "$max_tokens" ;;
         none)
             eagle_log "ERROR" "No LLM provider configured. Run: eagle-mem config"
             return 1
@@ -242,6 +275,79 @@ eagle_llm_call() {
     esac
 }
 
+_eagle_provider_chain() {
+    local primary="${1:-none}" fallback
+    fallback=$(eagle_config_get "provider" "fallback" "auto")
+
+    local chain=""
+    _eagle_provider_chain_add() {
+        local candidate="$1" required="${2:-available}"
+        [ -n "$candidate" ] || return 0
+        case " $chain " in *" $candidate "*) return 0 ;; esac
+        if [ "$required" = "available" ] && ! _eagle_provider_available "$candidate"; then
+            return 0
+        fi
+        chain="${chain}${chain:+ }$candidate"
+    }
+
+    if [ "$primary" != "none" ]; then
+        _eagle_provider_chain_add "$primary" "always"
+    fi
+
+    if [ "$fallback" != "off" ]; then
+        case "$primary" in
+            ollama)    _eagle_provider_chain_add "agent_cli"; _eagle_provider_chain_add "anthropic"; _eagle_provider_chain_add "openai" ;;
+            agent_cli) _eagle_provider_chain_add "ollama"; _eagle_provider_chain_add "anthropic"; _eagle_provider_chain_add "openai" ;;
+            anthropic) _eagle_provider_chain_add "ollama"; _eagle_provider_chain_add "agent_cli"; _eagle_provider_chain_add "openai" ;;
+            openai)    _eagle_provider_chain_add "ollama"; _eagle_provider_chain_add "agent_cli"; _eagle_provider_chain_add "anthropic" ;;
+            none|"")   _eagle_provider_chain_add "ollama"; _eagle_provider_chain_add "agent_cli"; _eagle_provider_chain_add "anthropic"; _eagle_provider_chain_add "openai" ;;
+        esac
+    fi
+
+    printf '%s\n' "$chain" | tr ' ' '\n' | sed '/^$/d'
+}
+
+_eagle_provider_available() {
+    case "$1" in
+        ollama)
+            [ -n "$(eagle_detect_ollama "$(eagle_config_get "ollama" "url" "$EAGLE_DEFAULT_OLLAMA_URL")" 2>/dev/null || true)" ]
+            ;;
+        agent_cli)
+            [ -n "$(_eagle_agent_cli_target_chain)" ]
+            ;;
+        anthropic)
+            [ -n "${ANTHROPIC_API_KEY:-}" ]
+            ;;
+        openai)
+            [ -n "${OPENAI_API_KEY:-}" ]
+            ;;
+        *) return 1 ;;
+    esac
+}
+
+_eagle_provider_model_label() {
+    case "$1" in
+        ollama)    printf 'ollama:%s' "$(eagle_config_get "ollama" "model" "mistral")" ;;
+        agent_cli) printf 'agent_cli:%s' "$(_eagle_agent_cli_target_summary)" ;;
+        anthropic) printf 'anthropic:%s' "$(eagle_config_get "anthropic" "model" "claude-haiku-4-5-20251001")" ;;
+        openai)    printf 'openai:%s' "$(eagle_config_get "openai" "model" "gpt-4o-mini")" ;;
+        *)         printf '%s' "$1" ;;
+    esac
+}
+
+eagle_llm_provider_label() {
+    local provider chain labels="" candidate sep=""
+    provider=$(eagle_config_get "provider" "type" "none")
+    chain=$(_eagle_provider_chain "$provider")
+    while IFS= read -r candidate; do
+        [ -z "$candidate" ] && continue
+        labels="${labels}${sep}$(_eagle_provider_model_label "$candidate")"
+        sep=" -> "
+    done <<< "$chain"
+    [ -n "$labels" ] || labels="none"
+    printf '%s\n' "$labels"
+}
+
 _eagle_call_ollama() {
     local prompt="$1" system="$2" max_tokens="$3"
     local url model
@@ -281,35 +387,57 @@ _eagle_call_ollama() {
 }
 
 _eagle_agent_cli_target() {
-    local preferred
+    local first
+    first=$(_eagle_agent_cli_target_chain | sed -n '1p')
+    if [ -n "$first" ]; then
+        printf '%s\n' "$first"
+    else
+        printf 'none\n'
+    fi
+}
+
+_eagle_agent_cli_target_chain() {
+    local preferred current preferred_target targets="" candidate
     preferred=$(eagle_config_get "agent_cli" "preferred" "current")
+    current=""
+    if [ -n "${EAGLE_AGENT_SOURCE:-${EAGLE_AGENT:-}}" ]; then
+        current=$(eagle_agent_source)
+    fi
 
     case "$preferred" in
-        codex|openai-codex) echo "codex"; return 0 ;;
-        claude|claude-code|cloud-code) echo "claude-code"; return 0 ;;
-        auto)
-            if [ -n "${EAGLE_AGENT_SOURCE:-${EAGLE_AGENT:-}}" ]; then
-                eagle_agent_source
-            elif command -v codex &>/dev/null; then
-                echo "codex"
-            elif command -v claude &>/dev/null; then
-                echo "claude-code"
-            else
-                echo "none"
-            fi
-            ;;
-        current|*)
-            if [ -n "${EAGLE_AGENT_SOURCE:-${EAGLE_AGENT:-}}" ]; then
-                eagle_agent_source
-            elif command -v codex &>/dev/null; then
-                echo "codex"
-            elif command -v claude &>/dev/null; then
-                echo "claude-code"
-            else
-                echo "none"
-            fi
-            ;;
+        codex|openai-codex) preferred_target="codex" ;;
+        claude|claude-code|cloud-code) preferred_target="claude-code" ;;
+        current) preferred_target="$current" ;;
+        auto|"") preferred_target="" ;;
+        *) preferred_target="$preferred" ;;
     esac
+
+    for candidate in "$preferred_target" "$current" codex claude-code; do
+        case "$candidate" in
+            codex|claude-code) ;;
+            *) continue ;;
+        esac
+        case "$candidate" in
+            codex) command -v codex >/dev/null 2>&1 || continue ;;
+            claude-code) command -v claude >/dev/null 2>&1 || continue ;;
+        esac
+        case " $targets " in *" $candidate "*) continue ;; esac
+        targets="${targets}${targets:+ }$candidate"
+    done
+
+    printf '%s\n' "$targets" | tr ' ' '\n' | sed '/^$/d'
+}
+
+_eagle_agent_cli_target_summary() {
+    local chain summary="" sep="" target
+    chain=$(_eagle_agent_cli_target_chain)
+    while IFS= read -r target; do
+        [ -z "$target" ] && continue
+        summary="${summary}${sep}${target}"
+        sep=" -> "
+    done <<< "$chain"
+    [ -n "$summary" ] || summary="none"
+    printf '%s\n' "$summary"
 }
 
 _eagle_agent_cli_prompt_file() {
@@ -327,17 +455,32 @@ _eagle_agent_cli_prompt_file() {
 
 _eagle_call_agent_cli() {
     local prompt="$1" system="$2" max_tokens="$3"
-    local target
-    target=$(_eagle_agent_cli_target)
+    local target targets result rc tried=0
+    targets=$(_eagle_agent_cli_target_chain)
 
-    case "$target" in
-        codex) _eagle_call_codex_cli "$prompt" "$system" "$max_tokens" ;;
-        claude-code) _eagle_call_claude_cli "$prompt" "$system" "$max_tokens" ;;
-        *)
-            eagle_log "ERROR" "agent_cli provider unavailable: no Codex or Claude CLI found"
-            return 1
-            ;;
-    esac
+    if [ -z "$targets" ]; then
+        eagle_log "ERROR" "agent_cli provider unavailable: no supported Codex or Claude CLI found"
+        return 1
+    fi
+
+    while IFS= read -r target; do
+        [ -z "$target" ] && continue
+        tried=$((tried + 1))
+        case "$target" in
+            codex) result=$(_eagle_call_codex_cli "$prompt" "$system" "$max_tokens"); rc=$? ;;
+            claude-code) result=$(_eagle_call_claude_cli "$prompt" "$system" "$max_tokens"); rc=$? ;;
+            *) rc=1; result="" ;;
+        esac
+        if [ "$rc" -eq 0 ] && [ -n "$result" ]; then
+            [ "$tried" -gt 1 ] && eagle_log "INFO" "agent_cli fallback succeeded with $target"
+            printf '%s\n' "$result"
+            return 0
+        fi
+        eagle_log "WARN" "agent_cli target failed: target=$target rc=$rc"
+    done <<< "$targets"
+
+    eagle_log "ERROR" "All agent_cli targets failed: targets=$(printf '%s' "$targets" | tr '\n' ',')"
+    return 1
 }
 
 _eagle_call_codex_cli() {
@@ -539,16 +682,19 @@ eagle_show_config() {
         return 1
     fi
 
-    local provider model
+    local provider model fallback
     provider=$(eagle_config_get "provider" "type" "none")
+    fallback=$(eagle_config_get "provider" "fallback" "auto")
     if [ "$provider" = "agent_cli" ]; then
-        model=$(_eagle_agent_cli_target)
+        model=$(_eagle_agent_cli_target_summary)
     else
         model=$(eagle_config_get "$provider" "model" "unknown")
     fi
 
     echo "Provider: $provider"
     echo "Model:    $model"
+    echo "Fallback: $fallback"
+    echo "Chain:    $(eagle_llm_provider_label)"
 
     if [ "$provider" = "ollama" ]; then
         local url
@@ -564,6 +710,7 @@ eagle_show_config() {
         fi
     elif [ "$provider" = "agent_cli" ]; then
         echo "Preferred: $(eagle_config_get "agent_cli" "preferred" "current")"
+        echo "Targets:   $(_eagle_agent_cli_target_summary)"
         echo "Codex:     $(command -v codex 2>/dev/null || echo "not found")"
         echo "Claude:    $(command -v claude 2>/dev/null || echo "not found")"
     fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.10.10",
+  "version": "4.10.11",
   "description": "Shared memory, release guardrails, RTK token protection, and worker lanes for Claude Code, Codex, Grok, and Google Antigravity",
   "bin": {
     "eagle-mem": "bin/eagle-mem"

package/scripts/config.sh

@@ -36,6 +36,7 @@ show_help() {
     echo -e "    eagle-mem config set updates.allow patch"
     echo -e "    eagle-mem config set token_guard.rtk enforce"
     echo -e "    eagle-mem config set token_guard.raw_bash block"
+    echo -e "    eagle-mem config set read_guard.mode advisory"
     echo ""
     exit 0
 }
@@ -72,6 +73,7 @@ case "$subcommand" in
             eagle_info "  eagle-mem config set anthropic.model claude-haiku-4-5-20251001"
             eagle_info "  eagle-mem config set token_guard.rtk enforce"
             eagle_info "  eagle-mem config set token_guard.raw_bash block"
+            eagle_info "  eagle-mem config set read_guard.mode advisory"
             exit 1
         fi
         section="${key%%.*}"

package/scripts/curate.sh

@@ -100,19 +100,27 @@ fi
 
 p_esc=$(eagle_sql_escape "$project")
 
+cleanup_curate() {
+    local rc=$?
+    eagle_run_finish "$rc" "$LINENO"
+}
+eagle_run_start "curate" "$project" "$(pwd)"
+trap cleanup_curate EXIT
+
 # Verify provider is configured
 provider=$(eagle_config_get "provider" "type" "none")
 if [ "$provider" = "none" ]; then
     eagle_err "No LLM provider configured. Run: eagle-mem config init"
     exit 1
 fi
-eagle_info "Provider: $provider ($(eagle_config_get "$provider" "model" "unknown"))"
+eagle_info "Provider: $(eagle_llm_provider_label)"
 eagle_info "Project: $project"
 [ "$DRY_RUN" -eq 1 ] && eagle_info "Dry run — no changes will be made"
 echo ""
 
 # ─── 1. Analyze gotchas for promotion ─────────────────────
 
+eagle_run_step "promote_gotchas"
 eagle_info "Analyzing gotchas for promotion..."
 
 recent_gotchas=$(eagle_db "SELECT gotchas, created_at

package/scripts/health.sh

@@ -136,14 +136,11 @@ max_score=$((max_score + 15))
 
 provider=$(eagle_config_get "provider" "type" "none")
 if [ "$provider" != "none" ]; then
-    if [ "$provider" = "agent_cli" ]; then
-        model=$(_eagle_agent_cli_target)
-    else
-        model=$(eagle_config_get "$provider" "model" "default")
-    fi
-    eagle_ok "Provider: ${provider} (${model})"
+    provider_chain=$(eagle_llm_provider_label)
+    eagle_ok "Provider: ${provider_chain}"
     score=$((score + 15))
 else
+    provider_chain="none"
     eagle_fail "No LLM provider — curator and enrichment disabled"
     issues+=("Configure a provider: eagle-mem config init")
 fi
@@ -321,6 +318,7 @@ if [ "$JSON_OUT" -eq 1 ]; then
         --argjson enriched_summaries "${enriched_summaries:-0}" \
         --argjson features "${feature_count:-0}" \
         --arg provider "$provider" \
+        --arg provider_chain "$provider_chain" \
         --arg token_guard_rtk "$rtk_mode" \
         --arg token_guard_raw_bash "$raw_bash_mode" \
         --arg rtk_bin "${rtk_bin:-}" \
@@ -345,7 +343,7 @@ if [ "$JSON_OUT" -eq 1 ]; then
         '{project:$project, score:$score, max:$max_score, pct:$pct, grade:$grade,
           capture:{sessions:$total_sessions, summaries:$total_summaries, heuristic:$heuristic_summaries},
           enrichment:$enriched_summaries,
-          features:$features, provider:$provider,
+          features:$features, provider:$provider, provider_chain:$provider_chain,
           token_guard:{rtk:$token_guard_rtk, raw_bash:$token_guard_raw_bash, rtk_bin:$rtk_bin},
           orchestration:{
             route:$orchestration_route,

package/scripts/help.sh

@@ -23,6 +23,7 @@ echo -e "    ${CYAN}uninstall${RESET}   Remove hooks and optionally delete data"
 echo -e "    ${CYAN}search${RESET}      Search past sessions, memories, and code"
 echo -e "    ${CYAN}health${RESET}      Diagnose pipeline health and background automation"
 echo -e "    ${CYAN}doctor${RESET}      Show install footprint, hooks, SQLite, manifest, and runtime drift"
+echo -e "    ${CYAN}logs${RESET}        Inspect command-scoped scan/index/curate logs"
 echo -e "    ${CYAN}updates${RESET}     Auto-update status and policy"
 echo -e "    ${CYAN}overview${RESET}    Build or view project overview"
 echo -e "    ${CYAN}session${RESET}     Save a manual session summary"

package/scripts/index.sh

@@ -40,6 +40,15 @@ TARGET_DIR="${args[0]:-.}"
 TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
 PROJECT=$(eagle_project_from_cwd "$TARGET_DIR")
 
+TMPDIR_IDX=""
+cleanup_index() {
+    local rc=$?
+    [ -n "${TMPDIR_IDX:-}" ] && rm -rf "$TMPDIR_IDX" 2>/dev/null || true
+    eagle_run_finish "$rc" "$LINENO"
+}
+eagle_run_start "index" "$PROJECT" "$TARGET_DIR"
+trap cleanup_index EXIT
+
 CHUNK_SIZE="${EAGLE_MEM_CHUNK_SIZE:-80}"
 if ! [[ "$CHUNK_SIZE" =~ ^[0-9]+$ ]] || [ "$CHUNK_SIZE" -lt 1 ]; then
     CHUNK_SIZE=80
@@ -111,10 +120,10 @@ sql_literal_expr() {
 # ─── Collect files ─────────────────────────────────────────
 
 TMPDIR_IDX=$(mktemp -d)
-trap 'rm -rf "$TMPDIR_IDX"' EXIT
 
 ALL_FILES="$TMPDIR_IDX/all_files"
 
+eagle_run_step "collect_files"
 eagle_collect_files "$TARGET_DIR" "$ALL_FILES"
 
 # Filter to source files only, skip large files
@@ -147,6 +156,7 @@ NEEDS_INDEX="$TMPDIR_IDX/needs_index"
 skipped_count=0
 
 if [ "$force" = true ]; then
+    eagle_run_step "force_clear_index_state"
     eagle_info "Force rebuild requested: clearing chunks, declarations, and import edges"
     eagle_graph_clear_index_state "$PROJECT"
 fi
@@ -183,6 +193,7 @@ if [ "$needs_count" -eq 0 ]; then
 fi
 
 eagle_info "$needs_count files to index"
+eagle_run_step "index_files count=$needs_count"
 
 # ─── Chunk and index files ─────────────────────────────────
 

package/scripts/logs.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════
+# Eagle Mem — Command Run Logs
+# ═══════════════════════════════════════════════════════════
+set -euo pipefail
+
+SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$SCRIPTS_DIR/../lib"
+
+. "$SCRIPTS_DIR/style.sh"
+. "$LIB_DIR/common.sh"
+
+cmd="${1:-list}"
+[ $# -gt 0 ] && shift || true
+
+show_help() {
+    cat <<EOF
+Usage: eagle-mem logs [list|tail|show] [run-id-or-path]
+
+Commands:
+  list              Show recent command-scoped run logs
+  tail [id|path]    Tail a run log, or the latest run log when omitted
+  show <id|path>    Print a run log
+EOF
+}
+
+resolve_log_path() {
+    local ref="${1:-}"
+    if [ -z "$ref" ]; then
+        ls -t "$EAGLE_RUNS_DIR"/*.log 2>/dev/null | sed -n '1p'
+        return 0
+    fi
+    if [ -f "$ref" ]; then
+        printf '%s\n' "$ref"
+        return 0
+    fi
+    if [ -f "$EAGLE_RUNS_DIR/$ref" ]; then
+        printf '%s\n' "$EAGLE_RUNS_DIR/$ref"
+        return 0
+    fi
+    if [ -f "$EAGLE_RUNS_DIR/$ref.log" ]; then
+        printf '%s\n' "$EAGLE_RUNS_DIR/$ref.log"
+        return 0
+    fi
+    return 1
+}
+
+case "$cmd" in
+    -h|--help|help)
+        show_help
+        ;;
+    list)
+        eagle_header "Run Logs"
+        if ! ls "$EAGLE_RUNS_DIR"/*.log >/dev/null 2>&1; then
+            eagle_info "No run logs found yet"
+            eagle_dim "Run eagle-mem scan, index, or curate to create command-scoped logs."
+            exit 0
+        fi
+        ls -t "$EAGLE_RUNS_DIR"/*.log 2>/dev/null | head -20 | while IFS= read -r log_path; do
+            first_line=$(sed -n '1p' "$log_path" 2>/dev/null)
+            run_id=$(basename "$log_path" .log)
+            printf '  %s  %s\n' "$run_id" "$first_line"
+        done
+        ;;
+    tail)
+        log_path=$(resolve_log_path "${1:-}") || {
+            eagle_err "Run log not found"
+            exit 1
+        }
+        tail -n "${EAGLE_LOG_TAIL_LINES:-80}" "$log_path"
+        ;;
+    show)
+        log_path=$(resolve_log_path "${1:-}") || {
+            eagle_err "Run log not found"
+            exit 1
+        }
+        cat "$log_path"
+        ;;
+    *)
+        eagle_err "Unknown logs command: $cmd"
+        show_help
+        exit 1
+        ;;
+esac

package/scripts/scan.sh

@@ -29,6 +29,15 @@ TARGET_DIR="${args[0]:-.}"
 TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
 PROJECT=$(eagle_project_from_cwd "$TARGET_DIR")
 
+TMPFILE=""
+cleanup_scan() {
+    local rc=$?
+    [ -n "${TMPFILE:-}" ] && rm -f "$TMPFILE" "${TMPFILE}.analysis" 2>/dev/null || true
+    eagle_run_finish "$rc" "$LINENO"
+}
+eagle_run_start "scan" "$PROJECT" "$TARGET_DIR"
+trap cleanup_scan EXIT
+
 eagle_header "Scan"
 eagle_info "Scanning ${BOLD}$PROJECT${RESET} at $TARGET_DIR"
 echo ""
@@ -52,8 +61,8 @@ if git -C "$TARGET_DIR" rev-parse --is-inside-work-tree &>/dev/null; then
 fi
 
 TMPFILE=$(mktemp)
-trap 'rm -f "$TMPFILE"' EXIT
 
+eagle_run_step "collect_files"
 eagle_collect_files "$TARGET_DIR" "$TMPFILE"
 
 total_files=$(wc -l < "$TMPFILE" | tr -d ' ')
@@ -67,6 +76,7 @@ eagle_ok "$total_files files found"
 
 # ─── Language breakdown (bash 3 compatible — no assoc arrays) ──
 
+eagle_run_step "language_breakdown"
 while IFS= read -r file; do
     ext="${file##*.}"
     [ "$ext" = "$file" ] && continue

package/scripts/test.sh

@@ -53,6 +53,7 @@ run_check "Installer And Updater (install / update syntax)" "bash -n \"$SCRIPTS_
 run_check "Code Scan And Index (scan / index syntax)" "bash -n \"$SCRIPTS_DIR/scan.sh\" && bash -n \"$SCRIPTS_DIR/index.sh\""
 run_check "Graph Memory Rebuild (isolated regression suite)" "bash \"$SCRIPTS_DIR/../tests/test_graph_memory.sh\""
 run_check "Dream Cycle Memory Graph Wiring (isolated regression suite)" "bash \"$SCRIPTS_DIR/../tests/test_curate_graph_memories.sh\""
+run_check "Reliability Guards (provider fallback, logs, autoscan, read scoring)" "bash \"$SCRIPTS_DIR/../tests/test_reliability_guards.sh\""
 
 echo ""
 if [ "$errors" -eq 0 ]; then

package/tests/test_reliability_guards.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+tmp_dir=$(mktemp -d)
+trap 'rm -rf "$tmp_dir"' EXIT
+
+assert_contains() {
+    local haystack="$1" needle="$2" message="$3"
+    case "$haystack" in
+        *"$needle"*) ;;
+        *)
+            echo "$message" >&2
+            echo "Expected to find: $needle" >&2
+            echo "Actual: $haystack" >&2
+            exit 1
+            ;;
+    esac
+}
+
+# Provider fallback: a failed preferred Codex CLI should fall through to Claude.
+provider_home="$tmp_dir/provider-home"
+fake_bin="$tmp_dir/bin"
+mkdir -p "$provider_home" "$fake_bin"
+cat > "$fake_bin/codex" <<'SH'
+#!/usr/bin/env bash
+exit 42
+SH
+cat > "$fake_bin/claude" <<'SH'
+#!/usr/bin/env bash
+printf 'claude fallback ok\n'
+SH
+chmod +x "$fake_bin/codex" "$fake_bin/claude"
+cat > "$provider_home/config.toml" <<'TOML'
+[provider]
+type = "agent_cli"
+fallback = "auto"
+
+[agent_cli]
+preferred = "codex"
+codex_model = ""
+claude_model = ""
+TOML
+provider_result=$(EAGLE_MEM_DIR="$provider_home" PATH="$fake_bin:$PATH" bash -c "
+    . '$ROOT_DIR/lib/common.sh'
+    . '$ROOT_DIR/lib/provider.sh'
+    eagle_llm_call 'say ok' 'system' 20
+")
+assert_contains "$provider_result" "claude fallback ok" "agent_cli fallback did not use Claude after Codex failed"
+
+# PreToolUse parsing + read scoring: repeated large read after modification should emit scored context.
+hook_home="$tmp_dir/hook-home"
+repo="$tmp_dir/repo"
+mkdir -p "$hook_home/mod-tracker" "$repo"
+touch "$hook_home/memory.db"
+large_file="$repo/large.txt"
+dd if=/dev/zero bs=1024 count=600 2>/dev/null | tr '\0' 'x' > "$large_file"
+session_id="session_reliability_123"
+printf '%s\n' "$large_file" > "$hook_home/mod-tracker/$session_id"
+read_input=$(jq -nc --arg fp "$large_file" --arg sid "$session_id" --arg cwd "$repo" \
+    '{tool_name:"Read",session_id:$sid,cwd:$cwd,tool_input:{file_path:$fp}}')
+EAGLE_MEM_DIR="$hook_home" EAGLE_MEM_PROJECT="project-read" bash "$ROOT_DIR/hooks/pre-tool-use.sh" <<< "$read_input" >/dev/null
+EAGLE_MEM_DIR="$hook_home" EAGLE_MEM_PROJECT="project-read" bash "$ROOT_DIR/hooks/pre-tool-use.sh" <<< "$read_input" >/dev/null
+read_output=$(EAGLE_MEM_DIR="$hook_home" EAGLE_MEM_PROJECT="project-read" bash "$ROOT_DIR/hooks/pre-tool-use.sh" <<< "$read_input")
+assert_contains "$read_output" "Eagle Mem read score" "Read guard did not emit scored duplicate-read context"
+grep -q 'mod_file}.lock' "$ROOT_DIR/hooks/post-tool-use.sh" || {
+    echo "post-tool-use modification tracker should use a lock directory" >&2
+    exit 1
+}
+
+# Auto-scan state race: failed background scan must clear the freshness marker.
+state_home="$tmp_dir/state-home"
+auto_scripts="$tmp_dir/auto-scripts"
+auto_repo="$tmp_dir/auto-repo"
+mkdir -p "$state_home" "$auto_scripts" "$auto_repo"
+cat > "$auto_scripts/scan.sh" <<'SH'
+#!/usr/bin/env bash
+exit 9
+SH
+cat > "$auto_scripts/index.sh" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+EAGLE_MEM_DIR="$state_home" EAGLE_MEM_LOG="$state_home/eagle-mem.log" bash -c "
+    . '$ROOT_DIR/lib/common.sh'
+    . '$ROOT_DIR/lib/hooks-sessionstart.sh'
+    eagle_get_overview() { return 0; }
+    eagle_db() { printf '0\n'; }
+    eagle_sessionstart_auto_provision 'project-auto-fail' '$auto_repo' '$auto_scripts'
+    scan_state=\$(_eagle_state_file scan 'project-auto-fail')
+    for _i in 1 2 3 4 5 6 7 8 9 10; do
+        grep -q 'auto-scan failed' '$state_home/eagle-mem.log' 2>/dev/null && break
+        sleep 0.2
+    done
+    [ ! -f \"\$scan_state\" ]
+"
+
+# Command-scoped logs: scan should create an inspectable run log and logs list should show it.
+log_home="$tmp_dir/log-home"
+log_repo="$tmp_dir/log-repo"
+mkdir -p "$log_home" "$log_repo"
+printf '# demo\n' > "$log_repo/README.md"
+EAGLE_MEM_DIR="$log_home" bash "$ROOT_DIR/scripts/scan.sh" "$log_repo" >/dev/null
+log_list=$(EAGLE_MEM_DIR="$log_home" bash "$ROOT_DIR/bin/eagle-mem" logs list)
+assert_contains "$log_list" "command=scan" "logs list did not show the scan command run"
+
+echo "reliability guard regressions passed"