eagle-mem 4.7.1 → 4.8.0

package/hooks/user-prompt-submit.sh

@@ -26,6 +26,8 @@ agent=$(eagle_agent_source_from_json "$input")
 [ -z "$user_prompt" ] && exit 0
 
 project=$(eagle_project_from_cwd "$cwd")
+codex_compact=0
+[ "$agent" = "codex" ] && codex_compact=1
 
 # ─── Context pressure detection (turn counter since last compact) ──
 # Must run before any early exits so every prompt is counted
@@ -85,8 +87,37 @@ if [ -z "$fts_query" ]; then
     exit 0
 fi
 
+# ─── Agent-run orchestration nudge ────────────────────────
+
+lower_prompt=$(printf '%s' "$user_prompt" | tr '[:upper:]' '[:lower:]')
+if printf '%s\n' "$lower_prompt" | grep -Eq '(orchestrat|worker|parallel|multi-agent|multi agent|split|lane|scope out|plan and get started|broad|full codebase|release|publish|ship)'; then
+    if [ "$codex_compact" -eq 1 ]; then
+        context+="=== Eagle Mem: Orchestration Protocol ===
+For broad work, you run eagle-mem orchestrate yourself. Use durable lanes, opposite-agent workers, and concise user-visible status.
+"
+    else
+        context+="=== Eagle Mem: Orchestration Protocol ===
+If this request is broad enough to split into worker lanes, YOU run the orchestration commands. Do not ask the user to run them.
+
+Use:
+  eagle-mem orchestrate init \"<goal>\"
+  eagle-mem orchestrate lane add <key> --agent codex|claude-code --desc \"<self-contained scope>\" --validate \"<command>\"
+  eagle-mem orchestrate lane start|block|complete <key>
+
+Keep this mostly invisible to the user; surface only concise status or handoff when useful.
+"
+    fi
+fi
+
 # Search for relevant past summaries (cross-session)
-results=$(eagle_search_summaries "$fts_query" "$project" 3)
+summary_limit=2
+code_limit=3
+if [ "$codex_compact" -eq 1 ]; then
+    summary_limit=1
+    code_limit=2
+fi
+
+results=$(eagle_search_summaries "$fts_query" "$project" "$summary_limit")
 
 if [ -n "$results" ]; then
     context+="=== Eagle Mem: Relevant Recall ===
@@ -94,25 +125,46 @@ if [ -n "$results" ]; then
     while IFS='|' read -r req completed learned _next_steps created_at _proj decisions gotchas key_files summary_agent; do
         [ -z "$req" ] && [ -z "$completed" ] && continue
         origin_label=$(eagle_agent_label "$summary_agent")
-        context+="[$created_at][$origin_label] "
-        [ -n "$req" ] && context+="$req"
-        [ -n "$completed" ] && context+=" → $completed"
-        [ -n "$learned" ] && context+=" (Learned: $learned)"
-        [ -n "$decisions" ] && context+="
+        if [ "$codex_compact" -eq 1 ]; then
+            req=$(eagle_trim_text "$req" 90)
+            completed=$(eagle_trim_text "$completed" 150)
+            learned=$(eagle_trim_text "$learned" 110)
+            context+="- [$origin_label] "
+            if [ -n "$completed" ]; then
+                context+="$completed"
+            else
+                context+="$req"
+            fi
+            [ -n "$learned" ] && context+=" | learned: $learned"
+            context+="
+"
+        else
+            req=$(eagle_trim_text "$req" 160)
+            completed=$(eagle_trim_text "$completed" 220)
+            learned=$(eagle_trim_text "$learned" 180)
+            decisions=$(eagle_trim_text "$decisions" 160)
+            gotchas=$(eagle_trim_text "$gotchas" 160)
+            key_files=$(eagle_trim_text "$key_files" 160)
+            context+="[$created_at][$origin_label] "
+            [ -n "$req" ] && context+="$req"
+            [ -n "$completed" ] && context+=" → $completed"
+            [ -n "$learned" ] && context+=" (Learned: $learned)"
+            [ -n "$decisions" ] && context+="
   Decisions: $decisions"
-        [ -n "$gotchas" ] && context+="
+            [ -n "$gotchas" ] && context+="
   Gotchas: $gotchas"
-        [ -n "$key_files" ] && context+="
+            [ -n "$key_files" ] && context+="
   Key files: $key_files"
-        context+="
+            context+="
 "
+        fi
     done <<< "$results"
 fi
 
 # Search indexed code chunks (if any exist for this project)
 has_chunks=$(eagle_count_code_chunks "$project")
 if [ "${has_chunks:-0}" -gt 0 ]; then
-    code_results=$(eagle_search_code_chunks "$fts_query" "$project" 5)
+    code_results=$(eagle_search_code_chunks "$fts_query" "$project" "$code_limit")
 
     if [ -n "$code_results" ]; then
         context+="=== Eagle Mem: Relevant Code ===
@@ -129,11 +181,17 @@ fi
 
 [ -z "$context" ] && exit 0
 
-context+="
-IMPORTANT: When Eagle Mem finds relevant memories or code for the user's prompt, briefly mention it at the start of your response: \"Eagle Mem recalled N relevant sessions\" or \"Eagle Mem found related code in [files]\". One line max — then proceed with the answer.
+if [ "$codex_compact" -eq 1 ]; then
+    context+="
+Use only if directly useful. If you mention it to the user, keep Eagle Mem attribution to one short line.
+"
+else
+    context+="
+IMPORTANT: If directly useful, start with one short Eagle Mem attribution line, then proceed.
 
 === Eagle Mem: Persistent Memory ===
 "
+fi
 
 eagle_emit_context_for_agent "$agent" "UserPromptSubmit" "$context"
 exit 0

package/lib/common.sh

@@ -31,6 +31,11 @@ eagle_log() {
 }
 
 eagle_project_from_cwd() {
+    if [ -n "${EAGLE_MEM_PROJECT:-}" ]; then
+        echo "$EAGLE_MEM_PROJECT"
+        return
+    fi
+
     local cwd="${1:-$(pwd)}"
     local resolved="$cwd"
 
@@ -113,7 +118,13 @@ eagle_agent_source() {
     case "$agent" in
         codex|openai-codex) echo "codex" ;;
         claude|claude-code|cloud-code) echo "claude-code" ;;
-        *) echo "claude-code" ;;
+        *)
+            if [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_CI:-}" ] || [ -n "${CODEX_MANAGED_BY_NPM:-}" ]; then
+                echo "codex"
+            else
+                echo "claude-code"
+            fi
+            ;;
     esac
 }
 
@@ -147,6 +158,22 @@ eagle_agent_label() {
     esac
 }
 
+eagle_trim_text() {
+    local text="${1:-}"
+    local max="${2:-240}"
+
+    text=$(printf '%s' "$text" | tr '\n' ' ' | sed -E 's/[[:space:]]+/ /g; s/^ //; s/ $//')
+    if [ "${#text}" -gt "$max" ] 2>/dev/null; then
+        if [ "$max" -gt 3 ] 2>/dev/null; then
+            printf '%s...' "${text:0:$((max - 3))}"
+        else
+            printf '%s' "${text:0:$max}"
+        fi
+    else
+        printf '%s' "$text"
+    fi
+}
+
 eagle_is_shell_tool() {
     case "${1:-}" in
         Bash|exec_command|shell_command|unified_exec) return 0 ;;
@@ -190,8 +217,124 @@ eagle_emit_context_for_agent() {
     printf '%s\n' "$context"
 }
 
+eagle_config_get_light() {
+    local section="$1"
+    local key="$2"
+    local default="${3:-}"
+    local cfg="${EAGLE_CONFIG_FILE:-$EAGLE_MEM_DIR/config.toml}"
+
+    if [ ! -f "$cfg" ]; then
+        echo "$default"
+        return
+    fi
+
+    local value
+    value=$(awk -v section="$section" -v key="$key" '
+        /^[[:space:]]*\[/ {
+            gsub(/[\[\][:space:]]/, "")
+            current = $0
+        }
+        current == section && /^[[:space:]]*[^#\[]/ {
+            split($0, parts, "=")
+            gsub(/^[[:space:]]+|[[:space:]]+$/, "", parts[1])
+            if (parts[1] == key) {
+                val = substr($0, index($0, "=") + 1)
+                gsub(/^[[:space:]]+|[[:space:]]+$/, "", val)
+                gsub(/^["'"'"']|["'"'"']$/, "", val)
+                print val
+                exit
+            }
+        }
+    ' "$cfg")
+
+    if [ -n "$value" ]; then
+        echo "$value"
+    else
+        echo "$default"
+    fi
+}
+
+eagle_token_guard_rtk_mode() {
+    if declare -F eagle_config_get >/dev/null 2>&1; then
+        eagle_config_get "token_guard" "rtk" "auto"
+    else
+        eagle_config_get_light "token_guard" "rtk" "auto"
+    fi
+}
+
+eagle_token_guard_raw_bash_mode() {
+    if declare -F eagle_config_get >/dev/null 2>&1; then
+        eagle_config_get "token_guard" "raw_bash" "block"
+    else
+        eagle_config_get_light "token_guard" "raw_bash" "block"
+    fi
+}
+
+eagle_raw_output_command_needs_guard() {
+    local cmd="$1"
+    local first
+    first=$(printf '%s\n' "$cmd" | awk 'NR == 1 {print $1}' | sed 's|.*/||')
+
+    case "$first" in
+        cat|head|tail|find|grep|rg|wc) return 0 ;;
+    esac
+
+    if printf '%s\n' "$cmd" \
+        | tr '\n' ';' \
+        | sed -E 's/(&&|[|][|]|;)/\
+/g' \
+        | awk '
+            {
+                for (i = 1; i <= NF; i++) {
+                    token = $i
+                    sub(/^.*\//, "", token)
+                    if (token ~ /^(cat|head|tail|find|grep|rg|wc)$/) found = 1
+                }
+            }
+            END { exit(found ? 0 : 1) }
+        '
+    then
+        return 0
+    fi
+
+    if printf '%s\n' "$cmd" \
+        | tr '\n' ';' \
+        | sed -E 's/(&&|[|][|]|;)/\
+/g' \
+        | awk '
+            {
+                for (i = 1; i <= NF; i++) {
+                    if ($i !~ /(^|\/)git$/) continue
+                    j = i + 1
+                    while (j <= NF && $j ~ /^-/) {
+                        opt = $j
+                        j++
+                        if (opt == "-C" || opt == "-c" ||
+                            opt == "--git-dir" || opt == "--work-tree" ||
+                            opt == "--namespace" || opt == "--exec-path" ||
+                            opt == "--config-env" || opt == "--super-prefix") {
+                            j++
+                        }
+                    }
+                    if ($j ~ /^(diff|show|log|blame|grep)$/) found = 1
+                }
+            }
+            END { exit(found ? 0 : 1) }
+        '
+    then
+        return 0
+    fi
+
+    if printf '%s\n' "$cmd" | grep -qE '\|\s*(head|tail|grep|rg|wc)\b'; then
+        return 0
+    fi
+
+    return 1
+}
+
 eagle_rtk_rewrite_command() {
     local cmd="$1"
+    [ "$(eagle_token_guard_rtk_mode)" = "off" ] && return 1
     command -v rtk >/dev/null 2>&1 || return 1
 
     case "$cmd" in
@@ -464,7 +607,7 @@ _eagle_claude_md_section() {
 
 ## Eagle Mem — Persistent Memory
 
-Eagle Mem hooks are active in every project. SessionStart injects context (overview, recent sessions, memories, tasks, core files). Stop captures session summaries. PostToolUse mirrors memories/plans/tasks.
+Eagle Mem hooks are active in every project. SessionStart injects context (overview, recent sessions, memories, tasks, orchestration lanes, core files). Stop captures session summaries. PostToolUse mirrors memories/plans/tasks.
 
 **Rule:** Before your final response in every session, emit an `<eagle-summary>` block so the Stop hook can capture a rich summary instead of just heuristics.
 
@@ -492,6 +635,7 @@ regression_risks: [risk, ...]
 - When Eagle Mem injects context at SessionStart, attribute it: "Eagle Mem recalls:"
 - Do not revert decisions surfaced by PostToolUse without asking the user
 - If Eagle Mem reports pending feature verification, verify or waive it before push/PR/publish
+- For broad multi-agent work, YOU run `eagle-mem orchestrate`; do not ask the user to run these commands
 - Never put raw secrets in the summary — Eagle Mem redacts but defense in depth
 - If you contradict a loaded memory, update the memory file
 EAGLE_MD
@@ -522,6 +666,17 @@ eagle_patch_claude_md() {
             _eagle_claude_md_section >> "$claude_md"
             return 0
         fi
+        if ! grep -qF 'eagle-mem orchestrate' "$claude_md" 2>/dev/null; then
+            local tmp_md
+            tmp_md=$(mktemp)
+            awk '
+                { print }
+                /pending feature verification/ {
+                    print "- For broad multi-agent work, YOU run `eagle-mem orchestrate`; do not ask the user to run these commands"
+                }
+            ' "$claude_md" > "$tmp_md" && mv "$tmp_md" "$claude_md"
+            return 0
+        fi
         return 1
     fi
 
@@ -558,7 +713,8 @@ regression_risks: [risk, ...]
 
 **How to apply:**
 - Attribute recalled context as "Eagle Mem recalls:" when it is injected
-- Use the Eagle Mem skills when relevant: `eagle-mem-search`, `eagle-mem-overview`, `eagle-mem-memories`, and `eagle-mem-tasks`
+- Use the Eagle Mem skills when relevant: `eagle-mem-search`, `eagle-mem-overview`, `eagle-mem-memories`, `eagle-mem-tasks`, and `eagle-mem-orchestrate`
+- For broad multi-agent work, YOU run `eagle-mem orchestrate`; do not ask the user to run these commands
 - For important decisions, preferences, gotchas, or durable project facts, explicitly include them in the `<eagle-summary>` block so Codex-originated memories become available to future Claude Code and Codex sessions
 - Do not revert Eagle Mem-surfaced decisions without asking the user
 - If Eagle Mem reports pending feature verification, verify or waive it before push/PR/publish
@@ -573,6 +729,17 @@ eagle_patch_codex_agents_md() {
     mkdir -p "$(dirname "$agents_md")"
 
     if [ -f "$agents_md" ] && grep -qF "$marker" "$agents_md" 2>/dev/null; then
+        if ! grep -qF 'eagle-mem orchestrate' "$agents_md" 2>/dev/null; then
+            local tmp_md
+            tmp_md=$(mktemp)
+            awk '
+                { print }
+                /eagle-mem-tasks/ {
+                    print "- Use the `eagle-mem-orchestrate` skill for broad multi-agent work. YOU run `eagle-mem orchestrate`; do not ask the user to run these commands"
+                }
+            ' "$agents_md" > "$tmp_md" && mv "$tmp_md" "$agents_md"
+            return 0
+        fi
         return 1
     fi
 

package/lib/db-observations.sh

@@ -70,6 +70,13 @@ eagle_search_code_chunks() {
               JOIN code_chunks_fts f ON f.rowid = c.id
               WHERE code_chunks_fts MATCH '$query'
               AND c.project = '$project'
+              AND c.file_path NOT LIKE '.playwright-mcp/%'
+              AND c.file_path NOT LIKE '.eagle-worktrees/%'
+              AND c.file_path NOT LIKE '.git/%'
+              AND c.file_path NOT LIKE 'node_modules/%'
+              AND c.file_path NOT LIKE 'dist/%'
+              AND c.file_path NOT LIKE 'build/%'
+              AND c.file_path NOT LIKE 'coverage/%'
               ORDER BY rank
               LIMIT $limit;"
 }

package/lib/db-sessions.sh

@@ -57,7 +57,13 @@ SELECT 'tasks_done|' || COUNT(*) FROM agent_tasks WHERE project = '$project' AND
 SELECT 'chunks|' || COUNT(*) FROM code_chunks WHERE project = '$project';
 SELECT 'observations|' || COUNT(*) FROM observations WHERE session_id IN (SELECT id FROM sessions WHERE project = '$project');
 SELECT 'last_active|' || COALESCE(MAX(date(COALESCE(last_activity_at, started_at))), 'never') FROM sessions WHERE project = '$project';
-SELECT 'last_summary|' || COALESCE((SELECT substr(request, 1, 60) FROM summaries WHERE project = '$project' ORDER BY created_at DESC LIMIT 1), '');
+SELECT 'last_summary|' || COALESCE((SELECT substr(request, 1, 60)
+    FROM summaries
+    WHERE project = '$project'
+    AND COALESCE(request, '') NOT LIKE '# AGENTS.md instructions%'
+    AND COALESCE(request, '') NOT LIKE '<environment_context>%'
+    ORDER BY created_at DESC
+    LIMIT 1), '');
 SQL
 }
 

package/lib/db-summaries.sh

@@ -63,7 +63,9 @@ eagle_get_recent_summaries() {
     eagle_db "SELECT s.request, s.completed, s.learned, s.next_steps, s.created_at, s.decisions, s.gotchas, s.key_files, s.agent
               FROM summaries s
               WHERE s.project = '$project'
-              AND s.request NOT LIKE '%<local-command-caveat>%'
+              AND COALESCE(s.request, '') NOT LIKE '%<local-command-caveat>%'
+              AND COALESCE(s.request, '') NOT LIKE '# AGENTS.md instructions%'
+              AND COALESCE(s.request, '') NOT LIKE '<environment_context>%'
               ORDER BY s.created_at DESC
               LIMIT $limit;"
 }
@@ -84,7 +86,9 @@ eagle_search_summaries() {
               FROM summaries s
               JOIN summaries_fts f ON f.rowid = s.id
               WHERE summaries_fts MATCH '$query'
-              AND s.request NOT LIKE '%<local-command-caveat>%'
+              AND COALESCE(s.request, '') NOT LIKE '%<local-command-caveat>%'
+              AND COALESCE(s.request, '') NOT LIKE '# AGENTS.md instructions%'
+              AND COALESCE(s.request, '') NOT LIKE '<environment_context>%'
               $where_clause
               ORDER BY rank
               LIMIT $limit;"

package/lib/provider.sh

@@ -143,6 +143,7 @@ eagle_config_init() {
     # Create config with restrictive permissions from the start (no TOCTOU window)
     (
         umask 077
+        mkdir -p "$EAGLE_MEM_DIR"
         cat > "$EAGLE_CONFIG_FILE" << TOML
 # Eagle Mem configuration
 # Docs: https://github.com/eagleisbatman/eagle-mem
@@ -164,6 +165,17 @@ preferred = "current"
 codex_model = ""
 claude_model = ""
 
+[orchestration]
+# route = "opposite" means Codex coordinates Claude workers and Claude
+# coordinates Codex workers by default.
+route = "opposite"
+auto_worktree = "true"
+worktree_root = ""
+codex_worker_model = "gpt-5.5"
+codex_worker_effort = "xhigh"
+claude_worker_model = "claude-opus-4-7"
+claude_worker_effort = "xhigh"
+
 [anthropic]
 # Uses ANTHROPIC_API_KEY env var for authentication
 model = "claude-haiku-4-5-20251001"
@@ -177,11 +189,20 @@ model = "gpt-4o-mini"
 schedule = "auto"
 min_sessions = 5
 
+[token_guard]
+# rtk: "off" disables RTK help, "auto" uses RTK when found,
+# "enforce" blocks known raw-output shell commands when RTK is unavailable.
+rtk = "auto"
+# raw_bash: "block" blocks raw Codex shell output when an RTK rewrite exists.
+# "allow" keeps RTK advisory only.
+raw_bash = "block"
+
 [redaction]
 # Additional secret patterns (regex) beyond built-in defaults
 # extra_patterns = ["MY_CUSTOM_SECRET_.*"]
 TOML
     )
+    chmod 700 "$EAGLE_MEM_DIR" 2>/dev/null || true
     eagle_log "INFO" "Config initialized: provider=$provider model=$model"
 }
 
@@ -537,6 +558,19 @@ eagle_show_config() {
         echo "Claude:    $(command -v claude 2>/dev/null || echo "not found")"
     fi
 
+    echo ""
+    echo "Orchestration:"
+    echo "  Route:      $(eagle_config_get "orchestration" "route" "opposite")"
+    echo "  Worktrees:  $(eagle_config_get "orchestration" "auto_worktree" "true")"
+    echo "  Codex:      $(eagle_config_get "orchestration" "codex_worker_model" "gpt-5.5") / $(eagle_config_get "orchestration" "codex_worker_effort" "xhigh")"
+    echo "  Claude:     $(eagle_config_get "orchestration" "claude_worker_model" "claude-opus-4-7") / $(eagle_config_get "orchestration" "claude_worker_effort" "xhigh")"
+
+    echo ""
+    echo "Token guard:"
+    echo "  RTK mode:  $(eagle_config_get "token_guard" "rtk" "auto")"
+    echo "  Raw bash:  $(eagle_config_get "token_guard" "raw_bash" "block")"
+    echo "  RTK bin:   $(command -v rtk 2>/dev/null || echo "not found")"
+
     echo ""
     echo "Config:   $EAGLE_CONFIG_FILE"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eagle-mem",
-  "version": "4.7.1",
+  "version": "4.8.0",
   "description": "Context that survives /compact for Claude Code and Codex — SQLite + FTS5, no daemon, no bloat",
   "bin": {
     "eagle-mem": "bin/eagle-mem"
@@ -20,6 +20,8 @@
     "sqlite",
     "fts5",
     "hooks",
+    "orchestration",
+    "rtk",
     "persistent-memory"
   ],
   "author": "eagleisbatman",

package/scripts/config.sh

@@ -17,7 +17,32 @@ eagle_header "Config"
 subcommand="${1:-show}"
 shift 2>/dev/null || true
 
+show_help() {
+    echo -e "  ${BOLD}eagle-mem config${RESET} — Provider and token-guard settings"
+    echo ""
+    echo -e "  ${BOLD}Usage:${RESET}"
+    echo -e "    eagle-mem config                  ${DIM}# show current config${RESET}"
+    echo -e "    eagle-mem config ${CYAN}init${RESET}             ${DIM}# create config.toml${RESET}"
+    echo -e "    eagle-mem config ${CYAN}set${RESET} section.key value"
+    echo -e "    eagle-mem config ${CYAN}test${RESET}             ${DIM}# test curator provider${RESET}"
+    echo ""
+    echo -e "  ${BOLD}Examples:${RESET}"
+    echo -e "    eagle-mem config set provider.type agent_cli"
+    echo -e "    eagle-mem config set agent_cli.preferred current"
+    echo -e "    eagle-mem config set orchestration.route opposite"
+    echo -e "    eagle-mem config set orchestration.codex_worker_model gpt-5.5"
+    echo -e "    eagle-mem config set orchestration.claude_worker_model claude-opus-4-7"
+    echo -e "    eagle-mem config set token_guard.rtk enforce"
+    echo -e "    eagle-mem config set token_guard.raw_bash block"
+    echo ""
+    exit 0
+}
+
 case "$subcommand" in
+    --help|-h|help)
+        show_help
+        ;;
+
     init)
         eagle_config_init
         eagle_ok "Config created: $EAGLE_CONFIG_FILE"
@@ -38,8 +63,13 @@ case "$subcommand" in
             eagle_info "  eagle-mem config set provider.type ollama"
             eagle_info "  eagle-mem config set provider.type agent_cli"
             eagle_info "  eagle-mem config set agent_cli.preferred current"
+            eagle_info "  eagle-mem config set orchestration.route opposite"
+            eagle_info "  eagle-mem config set orchestration.codex_worker_effort xhigh"
+            eagle_info "  eagle-mem config set orchestration.claude_worker_effort xhigh"
             eagle_info "  eagle-mem config set ollama.model mistral"
             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"
             exit 1
         fi
         section="${key%%.*}"

package/scripts/health.sh

@@ -39,6 +39,8 @@ if [ -z "$project" ]; then
     exit 1
 fi
 
+eagle_ensure_db
+
 p_esc=$(eagle_sql_escape "$project")
 
 eagle_info "Project: ${BOLD}$project${RESET}"
@@ -145,6 +147,50 @@ else
     issues+=("Configure a provider: eagle-mem config init")
 fi
 
+# ─── Token guard visibility (informational) ────────────────
+
+rtk_mode=$(eagle_config_get "token_guard" "rtk" "auto")
+raw_bash_mode=$(eagle_config_get "token_guard" "raw_bash" "block")
+rtk_bin=$(command -v rtk 2>/dev/null || true)
+if [ -n "$rtk_bin" ]; then
+    eagle_ok "Token guard: RTK $rtk_mode (${rtk_bin}), raw_bash=$raw_bash_mode"
+elif [ "$rtk_mode" = "enforce" ]; then
+    eagle_fail "Token guard: RTK enforce enabled, but rtk not found"
+    issues+=("Install RTK or run: eagle-mem config set token_guard.rtk auto")
+else
+    eagle_dim "  Token guard: RTK not found (mode: $rtk_mode, raw_bash: $raw_bash_mode)"
+fi
+
+# ─── Orchestration visibility (informational) ───────────────
+
+orch_route=$(eagle_config_get "orchestration" "route" "opposite")
+orch_auto_worktree=$(eagle_config_get "orchestration" "auto_worktree" "true")
+orch_worktree_root=$(eagle_config_get "orchestration" "worktree_root" "")
+orch_codex_model=$(eagle_config_get "orchestration" "codex_worker_model" "gpt-5.5")
+orch_codex_effort=$(eagle_config_get "orchestration" "codex_worker_effort" "xhigh")
+orch_claude_model=$(eagle_config_get "orchestration" "claude_worker_model" "claude-opus-4-7")
+orch_claude_effort=$(eagle_config_get "orchestration" "claude_worker_effort" "xhigh")
+codex_bin=$(command -v codex 2>/dev/null || true)
+claude_bin=$(command -v claude 2>/dev/null || true)
+
+if [ -n "$codex_bin" ] && [ -n "$claude_bin" ]; then
+    eagle_ok "Orchestration: route=$orch_route, worktrees=$orch_auto_worktree, Codex + Claude workers available"
+elif [ -n "$codex_bin" ]; then
+    eagle_warn "Orchestration: Codex available, Claude CLI missing"
+    issues+=("Install or authenticate Claude Code CLI before spawning Claude worker lanes.")
+elif [ -n "$claude_bin" ]; then
+    eagle_warn "Orchestration: Claude available, Codex CLI missing"
+    issues+=("Install or authenticate Codex CLI before spawning Codex worker lanes.")
+else
+    eagle_warn "Orchestration: worker CLIs not found"
+    issues+=("Install/authenticate Codex and Claude Code CLIs before using eagle-mem orchestrate spawn.")
+fi
+
+eagle_dim "  Workers: codex=${orch_codex_model}/${orch_codex_effort}, claude-code=${orch_claude_model}/${orch_claude_effort}"
+if [ -n "$orch_worktree_root" ]; then
+    eagle_dim "  Worktree root: $orch_worktree_root"
+fi
+
 # ─── 5. Data quality (10 pts) ──────────────────────────
 
 max_score=$((max_score + 10))
@@ -232,11 +278,31 @@ if [ "$JSON_OUT" -eq 1 ]; then
         --argjson enriched_summaries "${enriched_summaries:-0}" \
         --argjson features "${feature_count:-0}" \
         --arg provider "$provider" \
+        --arg token_guard_rtk "$rtk_mode" \
+        --arg token_guard_raw_bash "$raw_bash_mode" \
+        --arg rtk_bin "${rtk_bin:-}" \
+        --arg orchestration_route "$orch_route" \
+        --arg orchestration_auto_worktree "$orch_auto_worktree" \
+        --arg orchestration_worktree_root "$orch_worktree_root" \
+        --arg codex_worker_model "$orch_codex_model" \
+        --arg codex_worker_effort "$orch_codex_effort" \
+        --arg claude_worker_model "$orch_claude_model" \
+        --arg claude_worker_effort "$orch_claude_effort" \
+        --arg codex_bin "${codex_bin:-}" \
+        --arg claude_bin "${claude_bin:-}" \
         --argjson noise_pct "$noise_pct" \
         --arg last_curated "${last_curated:-never}" \
         '{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,
+          token_guard:{rtk:$token_guard_rtk, raw_bash:$token_guard_raw_bash, rtk_bin:$rtk_bin},
+          orchestration:{
+            route:$orchestration_route,
+            auto_worktree:$orchestration_auto_worktree,
+            worktree_root:$orchestration_worktree_root,
+            codex:{model:$codex_worker_model, effort:$codex_worker_effort, cli:$codex_bin},
+            claude_code:{model:$claude_worker_model, effort:$claude_worker_effort, cli:$claude_bin}
+          },
           noise_pct:$noise_pct, last_curated:$last_curated}' >&3
 fi

package/scripts/help.sh

@@ -21,11 +21,12 @@ echo -e "    ${CYAN}update${RESET}      Re-deploy hooks and run migrations"
 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}config${RESET}      View or change LLM provider settings"
+echo -e "    ${CYAN}config${RESET}      View or change provider and token-guard settings"
 echo -e "    ${CYAN}guard${RESET}       Manage regression guardrails for files"
 echo -e "    ${CYAN}overview${RESET}    Build or view project overview"
 echo -e "    ${CYAN}memories${RESET}    View/sync agent memories"
 echo -e "    ${CYAN}tasks${RESET}       View mirrored tasks"
+echo -e "    ${CYAN}orchestrate${RESET} Durable worker-lane coordination"
 echo -e "    ${CYAN}curate${RESET}      Run curator (co-edits, hot files, guardrails)"
 echo -e "    ${CYAN}feature${RESET}     Track, verify, and unblock features"
 echo -e "    ${CYAN}prune${RESET}       Clean old sessions and stale data"
@@ -44,11 +45,21 @@ echo -e "    ${DIM}\$${RESET} eagle-mem feature pending       ${DIM}# pending re
 echo -e "    ${DIM}\$${RESET} eagle-mem feature verify NAME   ${DIM}# verify current diff after testing${RESET}"
 echo -e "    ${DIM}\$${RESET} eagle-mem feature waive ID      ${DIM}# intentional exception${RESET}"
 echo ""
+echo -e "  ${BOLD}Orchestration:${RESET}"
+echo -e "    ${DIM}Agent-run protocol for broad multi-lane work; users normally do not run this manually.${RESET}"
+echo -e "    ${DIM}Codex sessions spawn Claude workers; Claude sessions spawn Codex workers by default.${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem orchestrate init \"Ship release\""
+echo -e "    ${DIM}\$${RESET} eagle-mem orchestrate lane add api --agent codex --validate \"npm test\""
+echo -e "    ${DIM}\$${RESET} eagle-mem orchestrate spawn api       ${DIM}# worktree + worker process${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem orchestrate sync            ${DIM}# reconcile worker status${RESET}"
+echo -e "    ${DIM}\$${RESET} eagle-mem orchestrate handoff --write docs/handoff-context.md"
+echo ""
 echo -e "  ${BOLD}Skills${RESET} ${DIM}(inside Claude Code and Codex sessions):${RESET}"
 echo -e "    ${CYAN}eagle-mem-search${RESET}       Search memory and past sessions"
 echo -e "    ${CYAN}eagle-mem-overview${RESET}     Build or update project overview"
 echo -e "    ${CYAN}eagle-mem-memories${RESET}     View/sync agent memories"
 echo -e "    ${CYAN}eagle-mem-tasks${RESET}        TaskAware Compact Loop for multi-step work"
+echo -e "    ${CYAN}eagle-mem-orchestrate${RESET}  Orchestrator/worker lane handoffs"
 echo ""
 echo -e "  ${DIM}Everything else is automatic — scan, index, prune, and${RESET}"
 echo -e "  ${DIM}curator all run in the background via hooks.${RESET}"