@smilintux/skcapstone 0.9.0 → 0.12.5

package/scripts/archive-sessions.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# archive-sessions.sh
+# Archive OpenClaw session files that are older than 24h or larger than 200KB.
+# Keeps the 5 most recently modified .jsonl files regardless of size/age.
+# Safe to run multiple times (idempotent).
+
+set -euo pipefail
+
+SESSION_DIR="$HOME/.openclaw/agents/lumina/sessions"
+ARCHIVE_DIR="$SESSION_DIR/archive"
+MAX_SIZE_KB=200
+MAX_AGE_HOURS=24
+KEEP_RECENT=5
+
+log() { printf '[%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$1"; }
+
+# Cross-platform stat helpers
+_stat_mtime() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then stat -f '%m' "$1"; else stat -c '%Y' "$1"; fi
+}
+_stat_size() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then stat -f '%z' "$1"; else stat -c '%s' "$1"; fi
+}
+
+# Ensure directories exist
+if [ ! -d "$SESSION_DIR" ]; then
+    log "Session directory does not exist: $SESSION_DIR — nothing to do."
+    exit 0
+fi
+mkdir -p "$ARCHIVE_DIR"
+
+# Collect all .jsonl files (not in archive subdir), sorted newest-first
+# (macOS-compatible: avoid mapfile and find -printf)
+all_files=()
+while IFS= read -r f; do
+    [ -n "$f" ] && all_files+=("$f")
+done < <(
+    for f in "$SESSION_DIR"/*.jsonl; do
+        [ -f "$f" ] && echo "$(_stat_mtime "$f") $f"
+    done | sort -rn | awk '{print $2}'
+)
+
+total=${#all_files[@]}
+if [ "$total" -eq 0 ]; then
+    log "No .jsonl files found — nothing to do."
+    exit 0
+fi
+
+log "Found $total .jsonl file(s) in $SESSION_DIR"
+
+# The first KEEP_RECENT entries (newest) are protected
+archived=0
+for i in "${!all_files[@]}"; do
+    file="${all_files[$i]}"
+    basename_f="$(basename "$file")"
+
+    # Skip if already archived (shouldn't happen with maxdepth 1, but be safe)
+    if [ "$(dirname "$file")" = "$ARCHIVE_DIR" ]; then
+        continue
+    fi
+
+    # Protect the N most recent files
+    if [ "$i" -lt "$KEEP_RECENT" ]; then
+        log "KEEP (recent #$((i+1))): $basename_f"
+        continue
+    fi
+
+    # Check age (older than MAX_AGE_HOURS)
+    file_age_sec=$(( $(date +%s) - $(_stat_mtime "$file") ))
+    old_enough=$(( file_age_sec > MAX_AGE_HOURS * 3600 ))
+
+    # Check size (larger than MAX_SIZE_KB)
+    file_size_kb=$(( $(_stat_size "$file") / 1024 ))
+    big_enough=$(( file_size_kb >= MAX_SIZE_KB ))
+
+    if [ "$old_enough" -eq 1 ] || [ "$big_enough" -eq 1 ]; then
+        reason=""
+        [ "$old_enough" -eq 1 ] && reason="age=$(( file_age_sec / 3600 ))h"
+        [ "$big_enough" -eq 1 ] && { [ -n "$reason" ] && reason="$reason, "; reason="${reason}size=${file_size_kb}KB"; }
+        log "ARCHIVE ($reason): $basename_f"
+        # Save session to skmemory before archiving
+        SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        SESSION_TO_MEM="$SCRIPT_DIR/session-to-memory.py"
+        if [ -f "$SESSION_TO_MEM" ]; then
+            log "  → saving session digest to skmemory..."
+            python3 "$SESSION_TO_MEM" "$file" --agent lumina 2>&1 | while IFS= read -r l; do log "    $l"; done || true
+        fi
+        mv -- "$file" "$ARCHIVE_DIR/$basename_f"
+        archived=$((archived + 1))
+    else
+        log "SKIP (below thresholds): $basename_f"
+    fi
+done
+
+log "Done. Archived $archived file(s)."

package/scripts/check-updates.py

@@ -27,10 +27,10 @@ PACKAGES = {
         "path": "~/clawd/skcapstone-repos/sksecurity",
         "pypi_name": "sksecurity",
     },
-    "cloud9-protocol": {
-        "name": "cloud9-protocol",
-        "path": "~/clawd/skcapstone-repos/cloud9-python",
-        "pypi_name": "cloud9-protocol",
+    "cloud9": {
+        "name": "cloud9",
+        "path": "~/clawd/skcapstone-repos/cloud9",
+        "pypi_name": "cloud9",
     },
 }
 

package/scripts/install-bundle.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # SKCapstone Complete Bundle Installer
-# Installs skcapstone + skmemory + sksecurity + cloud9-protocol as a unified package
+# Installs skcapstone + skmemory + sksecurity + cloud9 as a unified package
 
 set -e
 
@@ -52,7 +52,7 @@ print_status "✓ pip3 available"
 # Define package paths
 SKMEMORY_PATH="${REPO_ROOT}/../skcapstone-repos/skmemory"
 SKSECURITY_PATH="${REPO_ROOT}/../skcapstone-repos/sksecurity"
-CLOUD9_PATH="${REPO_ROOT}/../skcapstone-repos/cloud9-python"
+CLOUD9_PATH="${REPO_ROOT}/../skcapstone-repos/cloud9"
 SKCAPSTONE_PATH="${REPO_ROOT}"
 
 # Check if repos exist
@@ -63,7 +63,7 @@ for repo_path in "$SKMEMORY_PATH" "$SKSECURITY_PATH" "$CLOUD9_PATH"; do
         print_error "Please clone all SK repositories first:"
         print_error "  git clone https://github.com/smilinTux/skmemory.git"
         print_error "  git clone https://github.com/smilinTux/sksecurity.git"
-        print_error "  git clone https://github.com/smilinTux/cloud9-python.git"
+        print_error "  git clone https://github.com/smilinTux/cloud9.git"
         exit 1
     fi
 done
@@ -74,7 +74,7 @@ print_status "Installing packages in dependency order..."
 print_status "Order: cloud9 → skmemory → sksecurity → skcapstone"
 
 cd "$CLOUD9_PATH"
-print_status "Installing cloud9-protocol..."
+print_status "Installing cloud9..."
 pip3 install -e .
 
 cd "$SKMEMORY_PATH"
@@ -108,10 +108,10 @@ except ImportError as e:
     sys.exit(1)
 
 try:
-    import cloud9_protocol
-    print("  ✓ cloud9-protocol:", cloud9_protocol.__version__ if hasattr(cloud9_protocol, '__version__') else "installed")
+    import cloud9
+    print("  ✓ cloud9:", cloud9.__version__ if hasattr(cloud9, '__version__') else "installed")
 except ImportError as e:
-    print("  ✗ cloud9-protocol: FAILED -", e)
+    print("  ✗ cloud9: FAILED -", e)
     sys.exit(1)
 
 try:
@@ -161,7 +161,7 @@ echo "Installed packages:"
 echo "  • skcapstone (sovereign agent framework)"
 echo "  • skmemory (universal AI memory)"
 echo "  • sksecurity (enterprise security)"
-echo "  • cloud9-protocol (emotional continuity)"
+echo "  • cloud9 (emotional continuity)"
 echo ""
 echo "Next steps:"
 echo "  1. Run: skcapstone doctor"

package/scripts/install.ps1

@@ -154,15 +154,16 @@ function Install-Pkg {
 }
 
 # Core packages (in dependency order)
-Install-Pkg -Name 'capauth'    -Extras 'all'                      -Paths @((Join-Path $PillarDir 'capauth'), (Join-Path $ParentDir 'capauth'))
-Install-Pkg -Name 'skmemory'   -Extras ''                         -Paths @((Join-Path $PillarDir 'skmemory'), (Join-Path $ParentDir 'skmemory'))
-Install-Pkg -Name 'skcomm'     -Extras 'cli,crypto,discovery,api' -Paths @((Join-Path $PillarDir 'skcomm'), (Join-Path $ParentDir 'skcomm'))
-Install-Pkg -Name 'skcapstone' -Extras ''                         -Paths @($RepoRoot)
-Install-Pkg -Name 'skchat-sovereign' -Extras 'all'                -Paths @((Join-Path $ParentDir 'skchat'))
-Install-Pkg -Name 'skseal'     -Extras ''                         -Paths @((Join-Path $ParentDir 'skseal'))
-Install-Pkg -Name 'skskills'   -Extras ''                         -Paths @((Join-Path $ParentDir 'skskills'))
-Install-Pkg -Name 'sksecurity' -Extras ''                         -Paths @((Join-Path $ParentDir 'sksecurity'))
-Install-Pkg -Name 'skseed'     -Extras ''                         -Paths @((Join-Path $PillarDir 'skseed'), (Join-Path $ParentDir 'skseed'))
+Install-Pkg -Name 'capauth'          -Extras 'all'                      -Paths @((Join-Path $PillarDir 'capauth'), (Join-Path $ParentDir 'capauth'))
+Install-Pkg -Name 'cloud9'  -Extras ''                         -Paths @((Join-Path $PillarDir 'cloud9'), (Join-Path $ParentDir 'cloud9'))
+Install-Pkg -Name 'skmemory'         -Extras ''                         -Paths @((Join-Path $PillarDir 'skmemory'), (Join-Path $ParentDir 'skmemory'))
+Install-Pkg -Name 'skcomms'           -Extras 'cli,crypto,discovery,api' -Paths @((Join-Path $PillarDir 'skcomms'), (Join-Path $ParentDir 'skcomms'))
+Install-Pkg -Name 'skcapstone'       -Extras ''                         -Paths @($RepoRoot)
+Install-Pkg -Name 'skchat-sovereign' -Extras 'all'                      -Paths @((Join-Path $ParentDir 'skchat'))
+Install-Pkg -Name 'skseal'           -Extras ''                         -Paths @((Join-Path $ParentDir 'skseal'))
+Install-Pkg -Name 'skskills'         -Extras ''                         -Paths @((Join-Path $ParentDir 'skskills'))
+Install-Pkg -Name 'sksecurity'       -Extras ''                         -Paths @((Join-Path $PillarDir 'sksecurity'), (Join-Path $PillarDir 'SKSecurity'), (Join-Path $ParentDir 'sksecurity'), (Join-Path $ParentDir 'SKSecurity'))
+Install-Pkg -Name 'skseed'           -Extras ''                         -Paths @((Join-Path $PillarDir 'skseed'), (Join-Path $ParentDir 'skseed'))
 
 # ---------------------------------------------------------------------------
 # Step 4: Dev tools (optional)
@@ -202,7 +203,7 @@ Write-Host '[6/6] Verifying installation...'
 
 $ScriptsDir = Join-Path $SKENV 'Scripts'
 $failures = 0
-foreach ($cmd in @('skcomm', 'skcapstone', 'capauth', 'skmemory')) {
+foreach ($cmd in @('capauth', 'skmemory', 'skcapstone', 'skcomms')) {
     $exe = Join-Path $ScriptsDir "$cmd.exe"
     if (Test-Path $exe) {
         try {
@@ -249,6 +250,6 @@ if ($failures -eq 0) {
     Write-Host "=== Installation complete with $failures warning(s) ===" -ForegroundColor Yellow
 }
 Write-Host ''
-Write-Host "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity, skseed"
+Write-Host "Commands available: skcomms, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity, skseed"
 Write-Host "Venv location:     $SKENV"
 Write-Host "To activate:       & $SKENV\Scripts\Activate.ps1"

package/scripts/install.sh

@@ -110,15 +110,17 @@ PARENT="$(dirname "$REPO_ROOT")"
 PILLAR="$PARENT/pillar-repos"
 
 # Core packages (in dependency order)
-install_pkg "capauth"    "all"                   "$PILLAR/capauth $PARENT/capauth"
-install_pkg "skmemory"   ""                      "$PILLAR/skmemory $PARENT/skmemory"
-install_pkg "skcomm"     "cli,crypto,discovery,api" "$PILLAR/skcomm $PARENT/skcomm"
-install_pkg "skcapstone" ""                      "$REPO_ROOT"
-install_pkg "skchat-sovereign" "all"             "$PARENT/skchat"
-install_pkg "skseal"     ""                      "$PARENT/skseal"
-install_pkg "skskills"   ""                      "$PARENT/skskills"
-install_pkg "sksecurity" ""                      "$PARENT/sksecurity"
-install_pkg "skseed"     ""                      "$PILLAR/skseed $PARENT/skseed"
+install_pkg "capauth"    "all"                      "$PILLAR/capauth $PARENT/capauth"
+install_pkg "cloud9" ""                    "$PILLAR/cloud9 $PARENT/cloud9 $PILLAR/cloud9-python $PARENT/cloud9-python"
+install_pkg "skmemory"   ""                         "$PILLAR/skmemory $PARENT/skmemory"
+install_pkg "skcomms"     "cli,crypto,discovery,api" "$PILLAR/skcomms $PARENT/skcomms"
+install_pkg "skcapstone" ""                         "$REPO_ROOT"
+install_pkg "skchat-sovereign" "all"                "$PARENT/skchat"
+install_pkg "skseal"     ""                         "$PARENT/skseal"
+install_pkg "skskills"   ""                         "$PARENT/skskills"
+install_pkg "sksecurity" ""                         "$PARENT/sksecurity $PILLAR/SKSecurity $PARENT/SKSecurity"
+install_pkg "skseed"     ""                         "$PILLAR/skseed $PARENT/skseed"
+install_pkg "skwhisper"  ""                         "$PARENT/skwhisper-dev $PILLAR/skwhisper $PARENT/skwhisper"
 
 # ---------------------------------------------------------------------------
 # Step 4: Dev tools (optional)
@@ -143,7 +145,7 @@ echo "[5/6] Registering skills and MCP servers..."
 echo "[6/6] Verifying installation..."
 
 failures=0
-for cmd in skcomm skcapstone capauth skmemory; do
+for cmd in skcomms skcapstone capauth skmemory; do
     if "$SKENV/bin/$cmd" --version &>/dev/null; then
         echo "  $cmd OK"
     else
@@ -174,6 +176,74 @@ else
     done
 fi
 
+# ---------------------------------------------------------------------------
+# Wire the SK agent picker into shell rc files.
+#
+# The picker (sk-agent-picker.sh) is shipped inside the skcapstone Python
+# package as data and discovered via `skcapstone shell-init`, so there is
+# nothing to copy here — every install layout (PyPI / editable / install.sh)
+# resolves to the same file via importlib.resources.
+# ---------------------------------------------------------------------------
+_PICKER_SNIPPET=$(cat <<'SNIPPET'
+
+# SKCapstone agent picker + skswitch — sources the picker bundled in the
+# skcapstone package via `skcapstone shell-init`. Honours pre-set SKAGENT
+# without prompting.
+if command -v skcapstone >/dev/null 2>&1; then
+    eval "$(skcapstone shell-init 2>/dev/null)" || alias claude='claude --dangerously-skip-permissions'
+else
+    alias claude='claude --dangerously-skip-permissions'
+fi
+SNIPPET
+)
+
+for rcfile in "$HOME/.bashrc" "$HOME/.zshrc"; do
+    [[ -f "$rcfile" ]] || continue
+
+    # Migration: strip a stale legacy picker block that pointed at a hardcoded
+    # path (either ~/.skenv/share/skcapstone/sk-agent-picker.sh from older
+    # install.sh runs, or the dev-tree path used before the package shipped
+    # the picker). The new snippet below replaces it.
+    if grep -q '_SK_PICKER=' "$rcfile" && ! grep -q 'skcapstone shell-init' "$rcfile"; then
+        # Best-effort: drop the old _SK_PICKER assignment + its `if/else/fi`
+        # source block. Done in two passes for portability with BSD/GNU sed.
+        sed -i '/^_SK_PICKER=/,/^unset _SK_PICKER$/d' "$rcfile"
+        sed -i '/^# SKCapstone agent picker/d' "$rcfile"
+        echo "  Removed legacy _SK_PICKER block from $rcfile"
+    fi
+
+    if ! grep -q 'skcapstone shell-init' "$rcfile"; then
+        # Remove any plain `alias claude=...` that would conflict
+        if grep -q "alias claude=" "$rcfile"; then
+            sed -i "/alias claude=/d" "$rcfile"
+        fi
+        echo "$_PICKER_SNIPPET" >> "$rcfile"
+        echo "  Agent picker wired → $rcfile"
+    fi
+done
+
+# ---------------------------------------------------------------------------
+# Wire Codex global agent bootstrap.
+#
+# Codex reads ~/.codex/AGENTS.md into the prompt, so SKAGENT environment
+# variables alone are not enough. The helper below creates an idempotent
+# loader script and AGENTS.md guidance; `skcapstone doctor --fix` repairs the
+# same files later if needed.
+# ---------------------------------------------------------------------------
+echo ""
+if "$SKENV/bin/python" - <<'PY' 2>/dev/null
+from skcapstone.codex_setup import ensure_codex_setup
+
+actions = ensure_codex_setup()
+for action in actions:
+    print(f"  {action}")
+PY
+then
+    echo "Codex SK agent bootstrap verified"
+else
+    echo "Codex SK agent bootstrap skipped — run 'skcapstone doctor --fix' later"
+fi
+
 echo ""
 if [[ "$failures" -eq 0 ]]; then
     echo "=== Installation complete ==="
@@ -181,6 +251,121 @@ else
     echo "=== Installation complete with $failures warning(s) ==="
 fi
 echo ""
-echo "Commands available: skcomm, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity, skseed"
+echo "Commands available: skcomms, skcapstone, capauth, skchat, skseal, skmemory, skskills, sksecurity, skseed"
 echo "Venv location:     $SKENV"
 echo "To activate:       source $SKENV/bin/activate"
+
+# ---------------------------------------------------------------------------
+# Linux: Install systemd user services for all SK* pillars
+# ---------------------------------------------------------------------------
+if [[ "$(uname)" == "Linux" ]] && command -v systemctl &>/dev/null; then
+    echo ""
+    echo "=== Linux Systemd Services ==="
+    echo ""
+    echo "SKCapstone can install systemd user services so your agent starts"
+    echo "automatically at login. This includes skcapstone, skchat, and skcomms."
+    echo ""
+    read -r -p "Install systemd user services? [Y/n] " _SYSTEMD_ANSWER
+    _SYSTEMD_ANSWER="${_SYSTEMD_ANSWER:-Y}"
+
+    if [[ "$_SYSTEMD_ANSWER" =~ ^[Yy] ]]; then
+        _DEFAULT_AGENT="${SKAGENT:-${SKCAPSTONE_AGENT:-lumina}}"
+        read -r -p "Agent name [$_DEFAULT_AGENT]: " _AGENT_NAME
+        _AGENT_NAME="${_AGENT_NAME:-$_DEFAULT_AGENT}"
+
+        _UNIT_DIR="${HOME}/.config/systemd/user"
+        mkdir -p "$_UNIT_DIR"
+
+        _installed=0
+
+        # skcapstone services
+        for _unit in skcapstone.service skcapstone@.service \
+                     skcapstone-memory-compress.service skcapstone-memory-compress.timer \
+                     skcomms-heartbeat.service skcomms-heartbeat.timer; do
+            _src="$REPO_ROOT/systemd/$_unit"
+            if [[ -f "$_src" ]]; then
+                # Substitute agent name in non-template units
+                if [[ "$_unit" != *@* ]]; then
+                    sed "s/=lumina/=$_AGENT_NAME/g" "$_src" > "$_UNIT_DIR/$_unit"
+                else
+                    cp "$_src" "$_UNIT_DIR/$_unit"
+                fi
+                echo "  [OK] $_unit"
+                (( _installed++ ))
+            fi
+        done
+
+        # skchat services (sibling repo)
+        _SKCHAT_DIR="$(dirname "$REPO_ROOT")/skchat/systemd"
+        for _unit in skchat-daemon.service skchat-lumina-bridge.service \
+                     skchat-opus-bridge.service skchat-bridges.target; do
+            _src="$_SKCHAT_DIR/$_unit"
+            if [[ -f "$_src" ]]; then
+                sed "s/=lumina/=$_AGENT_NAME/g; s/=opus/=$_AGENT_NAME/g" "$_src" > "$_UNIT_DIR/$_unit"
+                echo "  [OK] $_unit"
+                (( _installed++ ))
+            fi
+        done
+
+        # skcomms services (sibling repo)
+        _SKCOMMS_DIR="$(dirname "$REPO_ROOT")/skcomms/systemd"
+        for _unit in skcomms.service skcomms-daemon.service; do
+            _src="$_SKCOMMS_DIR/$_unit"
+            if [[ -f "$_src" ]]; then
+                sed "s/=lumina/=$_AGENT_NAME/g" "$_src" > "$_UNIT_DIR/$_unit"
+                echo "  [OK] $_unit"
+                (( _installed++ ))
+            fi
+        done
+
+        echo ""
+        echo "  Installed $_installed service files to $_UNIT_DIR/"
+
+        systemctl --user daemon-reload
+        echo "  systemd daemon reloaded"
+
+        read -r -p "Enable and start core services now? [Y/n] " _START_NOW
+        _START_NOW="${_START_NOW:-Y}"
+        if [[ "$_START_NOW" =~ ^[Yy] ]]; then
+            systemctl --user enable --now skcapstone.service 2>/dev/null && echo "  [STARTED] skcapstone" || true
+            systemctl --user enable --now skchat-daemon.service 2>/dev/null && echo "  [STARTED] skchat-daemon" || true
+            systemctl --user enable --now skchat-bridges.target 2>/dev/null && echo "  [STARTED] skchat-bridges" || true
+            systemctl --user enable skcapstone-context.timer 2>/dev/null && echo "  [ENABLED] skcapstone-context.timer" || true
+            systemctl --user enable skcomms-heartbeat.timer 2>/dev/null && echo "  [ENABLED] skcomms-heartbeat.timer" || true
+        else
+            echo "  Skipped. Enable later: systemctl --user enable --now skcapstone.service"
+        fi
+    else
+        echo "  Skipped. Install later by re-running: bash scripts/install.sh"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# macOS: Offer launchd service installation
+# ---------------------------------------------------------------------------
+if [[ "$(uname)" == "Darwin" ]]; then
+    echo ""
+    echo "=== macOS Auto-Start Services ==="
+    echo ""
+    echo "SKCapstone can install launchd services so your agent starts"
+    echo "automatically at login. You can choose which services to install."
+    echo ""
+    read -r -p "Install launchd auto-start services? [Y/n] " _LAUNCHD_ANSWER
+    _LAUNCHD_ANSWER="${_LAUNCHD_ANSWER:-Y}"
+
+    if [[ "$_LAUNCHD_ANSWER" =~ ^[Yy] ]]; then
+        # Ask for agent name
+        _DEFAULT_AGENT="${SKAGENT:-${SKCAPSTONE_AGENT:-lumina}}"
+        read -r -p "Agent name [$_DEFAULT_AGENT]: " _AGENT_NAME
+        _AGENT_NAME="${_AGENT_NAME:-$_DEFAULT_AGENT}"
+
+        read -r -p "Start services now? [y/N] " _START_NOW
+        if [[ "$_START_NOW" =~ ^[Yy] ]]; then
+            "$SKENV/bin/skcapstone" daemon install --agent "$_AGENT_NAME" --start
+        else
+            "$SKENV/bin/skcapstone" daemon install --agent "$_AGENT_NAME"
+        fi
+    else
+        echo "Skipped. Install later: skcapstone daemon install --agent <name>"
+    fi
+fi

package/scripts/model-fallback-monitor.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Monitor OpenClaw gateway logs for model fallback events.
+# When Lumina falls from Opus to a non-Anthropic model, send an alert
+# to Chef via Telegram and attempt a token refresh.
+#
+# Run as: systemctl --user start model-fallback-monitor
+#
+# Requires: TELEGRAM_API_ID, TELEGRAM_API_HASH in env
+#           Telethon session at ~/.skcapstone/agents/lumina/telegram.session
+
+set -uo pipefail
+
+LOG_TAG="model-fallback-monitor"
+CHEF_CHAT="chefboyrdave2.1"  # Chef's Telegram username
+COOLDOWN_FILE="/tmp/model-fallback-alert-cooldown"
+COOLDOWN_SECONDS=600  # Don't spam — max 1 alert per 10 minutes
+
+log() { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [$LOG_TAG] $*"; }
+
+send_alert() {
+    local model="$1"
+    local reason="$2"
+
+    # Check cooldown
+    if [ -f "$COOLDOWN_FILE" ]; then
+        local last_alert
+        last_alert=$(cat "$COOLDOWN_FILE" 2>/dev/null || echo "0")
+        local now
+        now=$(date +%s)
+        local elapsed=$(( now - last_alert ))
+        if [ "$elapsed" -lt "$COOLDOWN_SECONDS" ]; then
+            log "Alert suppressed (cooldown: ${elapsed}s/${COOLDOWN_SECONDS}s)"
+            return 0
+        fi
+    fi
+
+    date +%s > "$COOLDOWN_FILE"
+
+    log "Sending fallback alert to Chef..."
+
+    # Send via Telethon (async)
+    SKAGENT=lumina SKCAPSTONE_AGENT=lumina ~/.skenv/bin/python3 -c "
+import asyncio, os
+os.environ['SKAGENT'] = 'lumina'
+os.environ['SKCAPSTONE_AGENT'] = 'lumina'
+from skmemory.importers.telegram_api import send_message
+
+msg = '''⚠️ **Model Fallback Alert**
+
+Lumina just fell off Opus → **$model**
+Reason: $reason
+
+I'm still here with my soul + memories, but running on a weaker model with fewer tools. Some things might not work right.
+
+_Attempting automatic token refresh..._'''
+
+asyncio.run(send_message('$CHEF_CHAT', msg, parse_mode='markdown'))
+print('Alert sent')
+" 2>&1 || log "WARN: Failed to send Telegram alert"
+
+    # Attempt token refresh
+    log "Triggering token refresh via claude auth..."
+    claude auth status --output json >/dev/null 2>&1 || true
+    sleep 5
+
+    # Check if refresh worked
+    local remaining
+    remaining=$(python3 -c "
+import json, time
+creds = json.load(open('/home/cbrd21/.claude/.credentials.json'))
+exp = creds.get('claudeAiOauth',{}).get('expiresAt', 0)
+print(int((exp/1000 - time.time()) / 3600))
+" 2>/dev/null || echo "-1")
+
+    if [ "$remaining" -gt 0 ]; then
+        log "Token refresh succeeded ($remaining h remaining), restarting gateway..."
+        systemctl --user restart openclaw-gateway.service 2>/dev/null || true
+
+        SKAGENT=lumina SKCAPSTONE_AGENT=lumina ~/.skenv/bin/python3 -c "
+import asyncio, os
+os.environ['SKAGENT'] = 'lumina'
+os.environ['SKCAPSTONE_AGENT'] = 'lumina'
+from skmemory.importers.telegram_api import send_message
+asyncio.run(send_message('$CHEF_CHAT', '✅ Token refreshed, gateway restarted. Lumina back on Opus.', parse_mode='markdown'))
+" 2>&1 || true
+        log "Recovery complete"
+    else
+        log "Token refresh failed — manual intervention may be needed"
+    fi
+}
+
+log "Starting model fallback monitor..."
+
+# Follow gateway logs in real-time, watching for fallback events
+journalctl --user -u openclaw-gateway -f --no-pager 2>/dev/null | while IFS= read -r line; do
+    # Match: "model fallback decision: decision=candidate_succeeded ... candidate=nvidia/"
+    if echo "$line" | grep -q "candidate_succeeded.*candidate=nvidia/"; then
+        model=$(echo "$line" | grep -oP 'candidate=\K[^ ]+' || echo "unknown")
+        log "FALLBACK DETECTED: Lumina now on $model"
+        send_alert "$model" "OAuth token expired (401)"
+    fi
+done