eagle-mem 4.10.10 → 4.10.12

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,60 @@ _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="" ;;
+        *)
+            eagle_log "WARN" "agent_cli unsupported preferred target: $preferred"
+            preferred_target=""
             ;;
     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 +458,36 @@ _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=$? ;;
+            *)
+                eagle_log "WARN" "agent_cli unsupported target: $target"
+                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 +689,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 +717,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.12",
   "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

@@ -39,22 +39,20 @@ EOF
 
 parse_consolidations_json() {
     local result="$1"
-    local trimmed json_payload
-
-    trimmed=$(printf '%s' "$result" | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
-    case "$trimmed" in
-        ""|NONE|none|null)
-            printf '[]\n'
-            return 0
-            ;;
-    esac
-
-    json_payload=$(printf '%s' "$result" \
-        | sed -e '1s/^[[:space:]]*```json[[:space:]]*$//' \
-              -e '1s/^[[:space:]]*```[[:space:]]*$//' \
-              -e '$s/^[[:space:]]*```[[:space:]]*$//')
-
-    printf '%s' "$json_payload" | jq -c '
+    printf '%s' "$result" | jq -Rrs -c '
+        def text_trim: gsub("^\\s+|\\s+$"; "");
+        def parse_payload:
+            gsub("\r"; "")
+            | gsub("^\\s*```json\\s*\\n"; "")
+            | gsub("^\\s*```\\s*\\n"; "")
+            | gsub("\\n\\s*```\\s*$"; "")
+            | text_trim
+            | if . == "" or . == "NONE" or . == "none" or . == "null" then []
+              else
+                  try fromjson catch (
+                      ([match("(?s)(\\{.*\\}|\\[.*\\])")? | .string][0] // "[]") | fromjson
+                  )
+              end;
         def trim: gsub("^\\s+|\\s+$"; "");
         def names:
             if type == "array" then map(tostring | trim) | map(select(length > 0))
@@ -66,7 +64,8 @@ parse_consolidations_json() {
             elif type == "object" then (.consolidations // .items // .instructions // [])
             else []
             end;
-        root
+        parse_payload
+        | root
         | map({
             source_names: ((.source_names // .sourceNames // .source_memories // .sourceMemories // .original_names // .originalNames // .originals // .names) | names),
             new_name: ((.new_name // .newName // .name // .title // "") | tostring | trim),
@@ -100,19 +99,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/prune 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,144 @@
+#!/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|prune] [run-id-or-filename]
+
+Commands:
+  list                    Show recent command-scoped run logs
+  tail [id|filename]      Tail a run log, or the latest run log when omitted
+  show <id|filename>      Print a run log
+  prune [--days N] [--keep N]
+                          Delete old run logs (defaults: 14 days, latest 50)
+EOF
+}
+
+resolve_log_path() {
+    local ref="${1:-}"
+    local runs_root="${EAGLE_RUNS_DIR%/}" rel_ref
+    if [ -z "$ref" ]; then
+        ls -t "$runs_root"/*.log 2>/dev/null | while IFS= read -r candidate; do
+            [ -L "$candidate" ] && continue
+            [ -f "$candidate" ] && printf '%s\n' "$candidate" && break
+        done
+        return 0
+    fi
+
+    case "$ref" in
+        *$'\n'*|*..*) return 1 ;;
+        /*)
+            rel_ref="${ref#"$runs_root"/}"
+            [ "$rel_ref" != "$ref" ] || return 1
+            case "$rel_ref" in ""|*/*) return 1 ;; esac
+            [ -L "$runs_root/$rel_ref" ] && return 1
+            [ -f "$runs_root/$rel_ref" ] && printf '%s\n' "$runs_root/$rel_ref" && return 0
+            return 1
+            ;;
+        */*) return 1 ;;
+    esac
+
+    if [ ! -L "$runs_root/$ref" ] && [ -f "$runs_root/$ref" ]; then
+        printf '%s\n' "$runs_root/$ref"
+        return 0
+    fi
+    if [ ! -L "$runs_root/$ref.log" ] && [ -f "$runs_root/$ref.log" ]; then
+        printf '%s\n' "$runs_root/$ref.log"
+        return 0
+    fi
+    return 1
+}
+
+run_log_count() {
+    [ -d "$EAGLE_RUNS_DIR" ] || {
+        printf '0\n'
+        return 0
+    }
+    find "$EAGLE_RUNS_DIR" -type f -name '*.log' -print 2>/dev/null | wc -l | tr -d ' '
+}
+
+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
+            [ -L "$log_path" ] && continue
+            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"
+        ;;
+    prune)
+        days="${EAGLE_RUN_LOG_RETENTION_DAYS:-14}"
+        keep="${EAGLE_RUN_LOG_MAX_COUNT:-50}"
+        while [ $# -gt 0 ]; do
+            case "$1" in
+                --days)
+                    days="${2:-}"
+                    shift 2
+                    ;;
+                --keep)
+                    keep="${2:-}"
+                    shift 2
+                    ;;
+                *)
+                    eagle_err "Unknown prune option: $1"
+                    show_help
+                    exit 1
+                    ;;
+            esac
+        done
+        case "$days" in ""|*[!0-9]*)
+            eagle_err "Invalid --days value: $days"
+            exit 1
+            ;;
+        esac
+        case "$keep" in ""|*[!0-9]*)
+            eagle_err "Invalid --keep value: $keep"
+            exit 1
+            ;;
+        esac
+        before=$(run_log_count)
+        eagle_run_prune_logs "$days" "$keep"
+        after=$(run_log_count)
+        eagle_ok "Pruned run logs: before=$before after=$after days=$days keep=$keep"
+        ;;
+    *)
+        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