Claude Code: Review Cain's error handling implementation across the application. Spec

ERROR_HANDLING_AUDIT_REPORT.md

@@ -0,0 +1,585 @@
+# Cain Error Handling Audit Report
+**Date:** 2026-03-14
+**Scope:** Full application error handling review
+**Focus:** User-facing error messages, graceful degradation, crash loop prevention
+
+---
+
+## Executive Summary
+
+Cain demonstrates **moderate to strong error handling** across backend components, but has **significant gaps in frontend error boundaries** and user-facing feedback mechanisms. The application handles network failures gracefully in most cases, but lacks comprehensive error reporting to end users.
+
+**Overall Rating:** 6.5/10
+- Backend Error Handling: 8/10
+- Frontend Error Handling: 4/10
+- User Communication: 5/10
+- Crash Prevention: 7/10
+
+---
+
+## 1. Backend Error Handling Analysis
+
+### 1.1 Main Application Entry Point (`app.py`)
+
+**Status:** ⚠️ INSUFFICIENT
+
+```python
+# Current: app.py (lines 1-8)
+import subprocess
+import sys
+
+if __name__ == "__main__":
+    print("Starting OpenClaw Sync Wrapper...")
+    subprocess.run([sys.executable, "scripts/sync_hf.py"], check=True)
+```
+
+**Issues:**
+- No try-catch block around subprocess execution
+- No graceful shutdown on failure
+- `check=True` will raise CalledProcessError without handling
+- No user-friendly error message if script fails
+
+**Recommendation:**
+```python
+try:
+    subprocess.run([sys.executable, "scripts/sync_hf.py"], check=True)
+except subprocess.CalledProcessError as e:
+    print(f"ERROR: Failed to start sync process (exit code {e.returncode})")
+    sys.exit(1)
+except Exception as e:
+    print(f"ERROR: Unexpected error: {e}")
+    sys.exit(1)
+```
+
+### 1.2 Core Sync Handler (`scripts/sync_hf.py`)
+
+**Status:** ✅ EXCELLENT
+
+**Strengths:**
+- Comprehensive try-catch blocks throughout
+- Custom exception classes for Git operations (`GitTimeoutError`, `GitOperationError`)
+- Timeout-controlled git operations with retry logic (up to 3 retries)
+- Exponential backoff for retries (2^attempt, max 30s)
+- Graceful degradation when git/huggingface APIs fail
+- Detailed logging at each failure point
+
+**Key Error Handling Patterns:**
+```python
+# Lines 256-273: Dataset creation with graceful failure
+try:
+    self.api.repo_info(repo_id=HF_REPO_ID, repo_type="dataset")
+    print(f"[SYNC] Dataset repo found: {HF_REPO_ID}")
+    return True
+except Exception:
+    if not AUTO_CREATE_DATASET:
+        print(f"[SYNC] Dataset repo NOT found: {HF_REPO_ID}")
+        print(f"[SYNC]   Set AUTO_CREATE_DATASET=true to auto-create.")
+        print(f"[SYNC] Persistence disabled (app will still run normally).")
+        return False
+```
+
+```python
+# Lines 325-327: Restore failure handling
+except Exception as e:
+    print(f"[SYNC] ✗ Restore failed: {e}")
+    traceback.print_exc()
+```
+
+### 1.3 Memory System (`memory/memory_system.py`, `memory/git_repo.py`)
+
+**Status:** ✅ VERY GOOD
+
+**Strengths:**
+- Separate custom exception types for different failure modes
+- Timeout configuration per git operation type
+- Atomic writes for memory state (temp file + rename)
+- Corrupt state file detection and recovery
+- Detailed logging for debugging
+- Local save succeeds even if remote sync fails
+
+**Example - Corrupt Config Recovery (sync_hf.py:480-518):**
+```python
+try:
+    with open(config_path, "r") as f:
+        data = json.load(f)
+except (json.JSONDecodeError, ValueError) as e:
+    # Config is corrupt — back up and start fresh
+    print(f"[SYNC] Config JSON is corrupt: {e}")
+    backup = config_path.with_suffix(f".corrupt_{int(time.time())}")
+    shutil.copy2(config_path, backup)
+    print(f"[SYNC] Backed up corrupt config to {backup.name}")
+    # Create valid default structure
+    data = {...default_config...}
+```
+
+### 1.4 Office Agent Push Script (`frontend/office-agent-push.py`)
+
+**Status:** ⚠️ MIXED
+
+**Strengths:**
+- Try-catch around API calls
+- Graceful handling of 403/404 responses
+- Automatic exit when removed from office
+
+**Weaknesses:**
+```python
+# Lines 73-74: Silent failure
+def post_chatlog(entries):
+    try:
+        requests.post(f"{OFFICE}/api/chatlog", json={"messages": entries[-30:]}, timeout=5)
+    except:
+        pass  # ❌ Silent failure - no logging
+```
+
+**Recommendation:**
+```python
+except requests.RequestException as e:
+    print(f"Warning: Failed to post chat log: {e}")
+```
+
+### 1.5 Coding Agent Extension (`extensions/coding-agent/index.ts`)
+
+**Status:** ✅ GOOD
+
+**Strengths:**
+- Proper async error handling with try-catch
+- Type-safe error handling (`e instanceof Error`)
+- User-friendly error messages for common failures
+- Timeout protection (5 minute CLAUDE_TIMEOUT)
+- Graceful git re-clone on fetch failure
+
+**Example (lines 190-193):**
+```typescript
+} catch (e: unknown) {
+  const msg = e instanceof Error ? e.message : String(e);
+  return text(`Claude Code failed:\n${msg.slice(0, 3000)}`);
+}
+```
+
+---
+
+## 2. Frontend Error Handling Analysis
+
+### 2.1 Main Application (`frontend/electron-standalone.html`)
+
+**Status:** ⚠️ INSUFFICIENT
+
+**Findings:**
+- No React-style error boundary component
+- Try-catch blocks exist but mostly silent failures
+- Many `catch (_) {}` or `catch (e) {}` blocks that suppress errors
+- No global error handler for uncaught exceptions
+- localStorage operations wrapped in try-catch but no user feedback
+
+**Problematic Patterns:**
+```javascript
+// Lines 2513, 2528: Silent localStorage failures
+try { localStorage.setItem('speedMode', speedMode); } catch(e) {}
+try { localStorage.removeItem('assetPositionOverrides'); } catch (e) {}
+```
+
+**Recommendation:**
+```javascript
+try {
+    localStorage.setItem('speedMode', speedMode);
+} catch(e) {
+    console.warn('Failed to save speed mode:', e);
+    // Optionally show user toast: "Settings couldn't be saved"
+}
+```
+
+### 2.2 Network Request Error Handling
+
+**Status:** ⚠️ INCONSISTENT
+
+**Issues:**
+- No retry logic for failed network requests
+- No exponential backoff
+- No timeout configuration visible
+- Some fetch calls have error handling, others don't
+
+**Example with error handling:**
+```javascript
+// Lines 4294, 4311, 4328: Good pattern
+fetch(...)
+    .then(...)
+    .catch(error => {
+        console.error('Fetch failed:', error);
+        // Some error handling present
+    });
+```
+
+**Missing:**
+- No automatic retry on 5xx errors
+- No offline detection
+- No user notification of network failures
+
+---
+
+## 3. Network Failure Handling
+
+### 3.1 HuggingFace API Interactions
+
+**Status:** ✅ GOOD
+
+**Strengths:**
+- Timeout environment variables configured:
+  - `HF_HUB_DOWNLOAD_TIMEOUT=300`
+  - `HF_HUB_UPLOAD_TIMEOUT=600`
+- Retry logic with exponential backoff in git operations
+- Graceful degradation when dataset sync fails
+
+**Timeout Configuration (sync_hf.py:16-25):**
+```python
+TIMEOUT_CONFIG = {
+    "fetch": 60,
+    "pull": 90,
+    "push": 120,
+    "commit": 30,
+    "status": 15,
+    "add": 20,
+    "reset": 30,
+    "default": 45,
+}
+```
+
+### 3.2 Dataset Sync Failures
+
+**Status:** ✅ EXCELLENT
+
+**Graceful Degradation:**
+- Local save succeeds even if remote sync fails
+- Change detection prevents unnecessary uploads
+- Detailed error messages for each failure type
+- No crash loops from sync failures
+
+**Example (sync_hf.py:404-412):**
+```python
+except Exception as e:
+    error_msg = str(e)
+    # Handle empty commit gracefully - this is not an error
+    if "No files have been modified" in error_msg or "empty commit" in error_msg.lower():
+        print(f"[SYNC] No changes to commit (already in sync)")
+        self._last_upload_hash = self._compute_files_hash()
+        return
+    print(f"[SYNC] ✗ Upload failed: {e}")
+    traceback.print_exc()
+```
+
+### 3.3 Telegram API Failures
+
+**Status:** ✅ EXCELLENT
+
+**Auto-Probe Mechanism (sync_hf.py:159-184):**
+```python
+def probe_telegram_api(timeout: int = 8) -> str:
+    """Probe Telegram API endpoints and return the first reachable one."""
+    for base in TELEGRAM_API_BASES:
+        try:
+            resp = urllib.request.urlopen(req, timeout=timeout, context=ctx)
+            print(f"[TELEGRAM] ✓ Reachable: {base} (HTTP {resp.status})")
+            return base.rstrip("/")
+        except urllib.error.HTTPError as e:
+            # HTTP error (4xx/5xx) still means the host IS reachable
+            print(f"[TELEGRAM] ✓ Reachable: {base} (HTTP {e.code})")
+            return base.rstrip("/")
+        except Exception as e:
+            print(f"[TELEGRAM] ✗ Unreachable: {base} ({reason})")
+            continue
+    print("[TELEGRAM] WARNING: All API endpoints unreachable!")
+    return ""
+```
+
+---
+
+## 4. Crash Loop Prevention
+
+### 4.1 Conversation Loop Auto-Restart
+
+**Status:** ✅ GOOD
+
+**Implementation (sync_hf.py:878-911):**
+```python
+def run_conversation_loop_forever():
+    """Launch conversation-loop with auto-restart on crash."""
+    while not stop_event.is_set():
+        print("[SYNC] Starting conversation-loop.py...")
+        conv_loop_proc = subprocess.Popen(...)
+        exit_code = conv_loop_proc.wait()
+        if stop_event.is_set():
+            break
+        print(f"[SYNC] conversation-loop.py exited ({exit_code}), restarting in 30s...")
+        time.sleep(30)  # Prevent tight crash loop
+```
+
+**Strengths:**
+- 30-second delay between restart attempts
+- Respects stop_event for graceful shutdown
+- Logs exit codes for debugging
+
+### 4.2 Git Operation Retries
+
+**Status:** ✅ EXCELLENT
+
+**Retry with Exponential Backoff (git_repo.py:114-150):**
+```python
+attempt = 0
+while attempt <= self.max_retries:
+    try:
+        result = subprocess.run(...)
+        return result
+    except subprocess.TimeoutExpired as e:
+        if attempt < self.max_retries:
+            backoff = min(2 ** attempt, 30)  # Exponential backoff, max 30s
+            logger.info(f"Retrying in {backoff}s...")
+            time.sleep(backoff)
+        else:
+            raise GitTimeoutError(...) from e
+    attempt += 1
+```
+
+---
+
+## 5. User-Facing Error Messages
+
+### 5.1 Current State
+
+**Status:** ⚠️ NEEDS IMPROVEMENT
+
+**Backend:** Console logs are detailed, but users don't see them
+**Frontend:** Mostly silent failures with no user notification
+
+**Examples of Silent Failures:**
+```javascript
+// localStorage failures - silent
+try { localStorage.setItem(...); } catch(e) {}
+
+// Asset loading failures - no user feedback
+.catch((e) => { console.error(e); });
+
+// Network failures - sometimes no indication
+.catch(() => {});
+```
+
+### 5.2 Recommended Improvements
+
+1. **Add Toast Notification System:**
+```javascript
+function showToast(message, type = 'info') {
+    const toast = document.createElement('div');
+    toast.className = `toast toast-${type}`;
+    toast.textContent = message;
+    document.body.appendChild(toast);
+    setTimeout(() => toast.remove(), 5000);
+}
+
+// Usage
+try {
+    localStorage.setItem('speedMode', speedMode);
+} catch(e) {
+    showToast('Could not save settings. Storage may be full.', 'error');
+}
+```
+
+2. **Add Error State to UI:**
+```javascript
+// Show error indicator in corner of office
+function showErrorIndicator(message) {
+    const indicator = document.getElementById('error-indicator');
+    indicator.textContent = '⚠️';
+    indicator.title = message;
+    indicator.style.display = 'block';
+}
+```
+
+3. **Network Status Indicator:**
+```javascript
+window.addEventListener('online', () => showToast('Back online', 'success'));
+window.addEventListener('offline', () => showToast('Connection lost', 'error'));
+```
+
+---
+
+## 6. Missing Error Cases
+
+### 6.1 Critical Gaps
+
+1. **No global error boundary in frontend**
+   - Unhandled JavaScript exceptions will crash the UI
+   - No recovery mechanism for component failures
+
+2. **No offline mode**
+   - Application fails gracefully but doesn't indicate offline state
+   - No queue for pending operations when offline
+
+3. **Silent localStorage failures**
+   - Private browsing mode prevents localStorage
+   - No fallback or user notification
+
+4. **No asset loading error feedback**
+   - Images/sprites that fail to load show nothing
+   - No fallback UI
+
+5. **No API rate limiting handling**
+   - HuggingFace API rate limits not handled gracefully
+   - No exponential backoff for 429 responses
+
+### 6.2 Recommendations for Addition
+
+| Priority | Component | Issue | Recommendation |
+|----------|-----------|-------|----------------|
+| HIGH | Frontend | No error boundary | Add global error boundary component |
+| HIGH | Frontend | Silent localStorage | Add storage check and fallback |
+| MEDIUM | Network | No retry logic | Implement retry with backoff |
+| MEDIUM | Frontend | No offline indicator | Add connection status UI |
+| LOW | Frontend | Asset loading | Add fallback images |
+
+---
+
+## 7. Crash Loop Analysis
+
+### 7.1 Potential Crash Loop Sources
+
+**Identified Risks:**
+
+1. ✅ **MITIGATED:** Git operation failures
+   - Has retry logic with exponential backoff
+   - Max 3 retries before giving up
+
+2. ✅ **MITIGATED:** Conversation loop crashes
+   - Has 30-second delay between restarts
+   - Logs exit codes
+
+3. ⚠️ **POTENTIAL ISSUE:** Subprocess with `check=True` in app.py
+   - Will raise exception immediately
+   - No backoff before retry
+
+4. ⚠️ **POTENTIAL ISSUE:** Frontend initialization failures
+   - No error boundary
+   - Could cause page reload loop
+
+### 7.2 Recommendations
+
+**app.py should be updated to:**
+```python
+import time
+import subprocess
+import sys
+
+MAX_RESTARTS = 3
+RESTART_DELAY = 10  # seconds
+
+for attempt in range(MAX_RESTARTS):
+    try:
+        result = subprocess.run(
+            [sys.executable, "scripts/sync_hf.py"],
+            check=True
+        )
+        sys.exit(result.returncode)
+    except subprocess.CalledProcessError as e:
+        if attempt < MAX_RESTARTS - 1:
+            print(f"Restart failed (attempt {attempt + 1}/{MAX_RESTARTS}), retrying in {RESTART_DELAY}s...")
+            time.sleep(RESTART_DELAY)
+        else:
+            print(f"ERROR: Failed after {MAX_RESTARTS} attempts")
+            sys.exit(1)
+```
+
+---
+
+## 8. Graceful Degradation Analysis
+
+### 8.1 What Works Well
+
+| Component | Failure Mode | Degradation Behavior |
+|-----------|--------------|---------------------|
+| Git Sync | Network timeout | Local save succeeds, logs error |
+| Dataset Upload | Repository not found | Continues normally, logs warning |
+| Telegram API | All endpoints unreachable | Continues without Telegram |
+| Config Load | Corrupt JSON | Backs up, creates default |
+| Memory Save | Git push fails | Local file saved, logs error |
+
+### 8.2 What Needs Improvement
+
+| Component | Issue | Recommendation |
+|-----------|-------|----------------|
+| Frontend | No offline mode | Show "Offline" banner, queue operations |
+| localStorage | Private mode fails | Use sessionStorage or memory fallback |
+| Asset loading | No fallback images | Show placeholder graphics |
+| API calls | No retry | Implement retry with backoff |
+
+---
+
+## 9. Recommendations Summary
+
+### High Priority
+
+1. **Add error boundary to frontend** (`electron-standalone.html`)
+   - Wrap Phaser game in error boundary
+   - Show user-friendly error page on crash
+
+2. **Fix app.py subprocess handling**
+   - Add try-catch around subprocess.run
+   - Add restart delay to prevent crash loops
+
+3. **Add user-facing error notifications**
+   - Implement toast notification system
+   - Show errors for critical failures
+
+4. **Improve localStorage error handling**
+   - Detect private browsing mode
+   - Provide fallback storage mechanism
+
+### Medium Priority
+
+5. **Add network retry logic to frontend**
+   - Retry failed fetch requests with exponential backoff
+   - Show retry indicator to user
+
+6. **Add offline mode support**
+   - Detect online/offline status
+   - Queue operations for when back online
+
+7. **Improve error message consistency**
+   - Standardize error message format
+   - Add error codes for support
+
+### Low Priority
+
+8. **Add asset loading fallbacks**
+   - Placeholder images for missing sprites
+   - Progressive loading for large assets
+
+9. **Add error telemetry**
+   - Log errors to external service
+   - Track error rates over time
+
+---
+
+## 10. Conclusion
+
+Cain's error handling is **strongest in backend operations** (git, dataset sync, API calls) but **weakest in user-facing communication**. The application gracefully degrades when backend services fail, but users are often unaware of failures or their causes.
+
+**Key Strengths:**
+- Comprehensive backend error handling with retries
+- Graceful degradation for network failures
+- Good timeout configuration
+- Detailed logging for debugging
+
+**Key Weaknesses:**
+- Silent frontend errors with no user feedback
+- No error boundary to prevent UI crashes
+- No offline mode or network status indication
+- Silent localStorage failures
+
+**Immediate Actions:**
+1. Fix app.py subprocess error handling
+2. Add global error boundary to frontend
+3. Implement toast notification system for errors
+4. Add network status indicator
+
+---
+
+**Report Generated:** 2026-03-14
+**Auditor:** Claude Code Agent
+**Next Review:** After implementing high-priority recommendations

ERROR_HANDLING_QUICK_REFERENCE.md

@@ -0,0 +1,442 @@
+# Error Handling Quick Reference Guide
+**For Cain Developers**
+
+This guide provides quick examples of proper error handling patterns used in Cain.
+
+---
+
+## Python Error Handling Patterns
+
+### 1. Subprocess Execution with Retry
+
+```python
+import subprocess
+import time
+
+MAX_RETRIES = 3
+BASE_TIMEOUT = 30  # seconds
+
+def run_with_retry(command, timeout=BASE_TIMEOUT):
+    """Run subprocess with retry and exponential backoff."""
+    for attempt in range(MAX_RETRIES):
+        try:
+            result = subprocess.run(
+                command,
+                timeout=timeout,
+                check=True,
+                capture_output=True,
+                text=True
+            )
+            return result
+        except subprocess.TimeoutExpired:
+            if attempt < MAX_RETRIES - 1:
+                backoff = min(2 ** attempt, 30)  # Max 30s
+                print(f"Timeout, retrying in {backoff}s...")
+                time.sleep(backoff)
+            else:
+                raise
+        except subprocess.CalledProcessError as e:
+            print(f"Command failed: {e.stderr}")
+            raise
+```
+
+### 2. Network API Call with Timeout
+
+```python
+import requests
+from requests.adapters import HTTPAdapter
+from requests.packages.urllib3.util.retry import Retry
+
+def create_resilient_session():
+    """Create a requests session with automatic retry."""
+    session = requests.Session()
+    retry = Retry(
+        total=3,
+        backoff_factor=1,
+        status_forcelist=[429, 500, 502, 503, 504],
+    )
+    adapter = HTTPAdapter(max_retries=retry)
+    session.mount('http://', adapter)
+    session.mount('https://', adapter)
+    return session
+
+def safe_api_call(url, timeout=30):
+    """Make API call with proper error handling."""
+    try:
+        response = create_resilient_session().get(url, timeout=timeout)
+        response.raise_for_status()
+        return response.json()
+    except requests.Timeout:
+        print(f"API timeout: {url}")
+        return None
+    except requests.ConnectionError:
+        print(f"Connection failed: {url}")
+        return None
+    except requests.HTTPError as e:
+        print(f"HTTP error {e.response.status_code}: {url}")
+        return None
+```
+
+### 3. File Operations with Atomic Write
+
+```python
+import os
+import json
+
+def save_atomically(filepath, data):
+    """Save data atomically to prevent corruption."""
+    temp_path = filepath + ".tmp"
+    try:
+        # Write to temp file first
+        with open(temp_path, 'w') as f:
+            json.dump(data, f)
+        # Atomic rename
+        os.rename(temp_path, filepath)
+        return True
+    except (OSError, IOError) as e:
+        print(f"Failed to save {filepath}: {e}")
+        # Clean up temp file
+        if os.path.exists(temp_path):
+            os.unlink(temp_path)
+        return False
+
+def load_with_fallback(filepath, default=None):
+    """Load file with corrupt data recovery."""
+    try:
+        with open(filepath, 'r') as f:
+            return json.load(f)
+    except (json.JSONDecodeError, ValueError) as e:
+        print(f"Corrupt file {filepath}: {e}")
+        # Backup corrupt file
+        backup_path = f"{filepath}.corrupt.{int(time.time())}"
+        os.rename(filepath, backup_path)
+        print(f"Backed up to {backup_path}")
+        return default if default is not None else {}
+    except (OSError, IOError) as e:
+        print(f"Cannot read {filepath}: {e}")
+        return default if default is not None else {}
+```
+
+### 4. Context Manager for Resources
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def safe_resource(resource):
+    """Context manager that guarantees cleanup."""
+    try:
+        yield resource
+    except Exception as e:
+        print(f"Error with {resource}: {e}")
+        raise
+    finally:
+        # Always cleanup, even on error
+        resource.cleanup()
+```
+
+---
+
+## JavaScript/TypeScript Error Handling Patterns
+
+### 1. Async Function with Timeout
+
+```javascript
+async function withTimeout(promise, timeoutMs, errorMessage = "Operation timed out") {
+    const timeout = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(errorMessage)), timeoutMs)
+    );
+    try {
+        return await Promise.race([promise, timeout]);
+    } catch (error) {
+        console.error(`${errorMessage}:`, error);
+        throw error;
+    }
+}
+
+// Usage
+const result = await withTimeout(
+    fetch('/api/data'),
+    10000,
+    'API request timeout'
+);
+```
+
+### 2. Fetch with Retry and Backoff
+
+```javascript
+async function fetchWithRetry(url, options = {}, maxRetries = 3) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: AbortSignal.timeout(30000) // 30s timeout
+            });
+            if (response.ok) return response;
+            if (response.status >= 500 && attempt < maxRetries - 1) {
+                // Retry server errors with backoff
+                const backoff = Math.min(1000 * Math.pow(2, attempt), 10000);
+                console.log(`Retry ${attempt + 1}/${maxRetries} after ${backoff}ms`);
+                await new Promise(r => setTimeout(r, backoff));
+                continue;
+            }
+            return response;
+        } catch (error) {
+            if (attempt === maxRetries - 1) throw error;
+            const backoff = Math.min(1000 * Math.pow(2, attempt), 10000);
+            console.log(`Network error, retry ${attempt + 1}/${maxRetries} after ${backoff}ms`);
+            await new Promise(r => setTimeout(r, backoff));
+        }
+    }
+}
+```
+
+### 3. localStorage with Fallback
+
+```javascript
+class SafeStorage {
+    constructor() {
+        this.memory = new Map();
+        this.available = this._checkAvailable();
+    }
+
+    _checkAvailable() {
+        try {
+            const test = '__storage_test__';
+            localStorage.setItem(test, test);
+            localStorage.removeItem(test);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    setItem(key, value) {
+        if (this.available) {
+            try {
+                localStorage.setItem(key, value);
+                return true;
+            } catch (e) {
+                console.warn('localStorage failed, using memory:', e);
+            }
+        }
+        this.memory.set(key, value);
+        return false;
+    }
+
+    getItem(key) {
+        if (this.available) {
+            const value = localStorage.getItem(key);
+            if (value !== null) return value;
+        }
+        return this.memory.get(key) || null;
+    }
+}
+
+const storage = new SafeStorage();
+```
+
+### 4. Error Boundary (React-like pattern)
+
+```javascript
+function wrapWithErrorBoundary(fn) {
+    return function(...args) {
+        try {
+            return fn(...args);
+        } catch (error) {
+            console.error('Error in', fn.name, ':', error);
+            // Show user-friendly error
+            showErrorToUser('An unexpected error occurred. Please refresh.');
+            // Optionally send to error tracking
+            reportError(error, fn.name, args);
+            return null; // or fallback value
+        };
+    };
+}
+
+// Or for async functions
+async function wrapAsyncWithErrorBoundary(fn) {
+    return async function(...args) {
+        try {
+            return await fn(...args);
+        } catch (error) {
+            console.error('Async error in', fn.name, ':', error);
+            showErrorToUser('Operation failed. Please try again.');
+            reportError(error, fn.name, args);
+            return null;
+        }
+    };
+}
+```
+
+---
+
+## Git Operations Error Handling
+
+### Pattern from Cain (git_repo.py)
+
+```python
+import subprocess
+import time
+from typing import List, Optional
+
+class GitTimeoutError(Exception):
+    """Git operation timed out."""
+    pass
+
+class GitOperationError(Exception):
+    """Git operation failed."""
+    pass
+
+def run_git_command(
+    args: List[str],
+    timeout: int = 45,
+    max_retries: int = 3,
+    cwd: str = "."
+) -> subprocess.CompletedProcess:
+    """Run git command with timeout and retry."""
+    attempt = 0
+    while attempt <= max_retries:
+        try:
+            start = time.time()
+            result = subprocess.run(
+                ["git"] + args,
+                cwd=cwd,
+                timeout=timeout,
+                check=True,
+                capture_output=True,
+                text=True
+            )
+            elapsed = time.time() - start
+            print(f"Git completed in {elapsed:.2f}s: {args[0]}")
+            return result
+
+        except subprocess.TimeoutExpired:
+            attempt += 1
+            if attempt <= max_retries:
+                backoff = min(2 ** (attempt - 1), 30)
+                print(f"Git timeout, retry {attempt}/{max_retries} in {backoff}s")
+                time.sleep(backoff)
+            else:
+                raise GitTimeoutError(f"Git timed out after {max_retries} retries")
+
+        except subprocess.CalledProcessError as e:
+            # Don't retry on fatal errors
+            if "fatal:" in (e.stderr or ""):
+                raise GitOperationError(f"Git fatal error: {e.stderr}")
+            attempt += 1
+            if attempt <= max_retries:
+                backoff = min(2 ** (attempt - 1), 30)
+                print(f"Git failed, retry {attempt}/{max_retries} in {backoff}s")
+                time.sleep(backoff)
+            else:
+                raise GitOperationError(f"Git failed: {e.stderr}")
+```
+
+---
+
+## Toast Notification System
+
+```javascript
+// Add to electron-standalone.html
+const toastContainer = document.createElement('div');
+toastContainer.id = 'toast-container';
+toastContainer.style.cssText = `
+    position: fixed;
+    top: 20px;
+    right: 20px;
+    z-index: 10000;
+`;
+document.body.appendChild(toastContainer);
+
+function showToast(message, type = 'info', duration = 5000) {
+    const toast = document.createElement('div');
+    toast.className = `toast toast-${type}`;
+    toast.textContent = message;
+    toast.style.cssText = `
+        padding: 12px 20px;
+        margin-bottom: 10px;
+        border-radius: 8px;
+        background: ${type === 'error' ? '#e94560' : type === 'success' ? '#4caf50' : '#333'};
+        color: white;
+        box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+        animation: slideIn 0.3s ease;
+    `;
+    toastContainer.appendChild(toast);
+
+    setTimeout(() => {
+        toast.style.animation = 'slideOut 0.3s ease';
+        setTimeout(() => toast.remove(), 300);
+    }, duration);
+}
+
+// Usage examples
+try {
+    localStorage.setItem('setting', value);
+} catch (e) {
+    showToast('Could not save settings', 'error');
+}
+
+// Network status
+window.addEventListener('offline', () => showToast('Connection lost', 'error'));
+window.addEventListener('online', () => showToast('Back online', 'success'));
+```
+
+---
+
+## Best Practices Summary
+
+1. **Always handle timeouts** - Network operations should have explicit timeouts
+2. **Use atomic writes** - Write to temp file, then rename
+3. **Log before suppressing** - Never silently catch without logging
+4. **Provide user feedback** - Show toasts for user-facing errors
+5. **Retry with backoff** - Exponential backoff prevents thundering herd
+6. **Degrade gracefully** - Local should work when remote fails
+7. **Clean up resources** - Use try/finally or context managers
+8. **Validate early** - Check prerequisites before attempting operations
+9. **Use specific exceptions** - Custom exception types for different errors
+10. **Document error codes** - For support and debugging
+
+---
+
+## Common Pitfalls to Avoid
+
+❌ **DON'T:**
+```python
+try:
+    risky_operation()
+except:
+    pass  # Silent failure - hard to debug!
+```
+
+✅ **DO:**
+```python
+try:
+    risky_operation()
+except SpecificError as e:
+    logger.warning(f"Operation failed: {e}")
+    # Handle appropriately
+```
+
+❌ **DON'T:**
+```python
+subprocess.run(command, check=True)  # Crashes on failure
+```
+
+✅ **DO:**
+```python
+try:
+    result = subprocess.run(command, check=True, timeout=30)
+except subprocess.TimeoutExpired:
+    logger.error("Command timed out")
+except subprocess.CalledProcessError as e:
+    logger.error(f"Command failed: {e}")
+```
+
+---
+
+**Remember:** Good error handling makes your application:
+- More reliable (fewer crashes)
+- Easier to debug (better logging)
+- Better for users (clear feedback)
+- Easier to maintain (predictable behavior)

app.py

@@ -1,8 +1,46 @@
 import subprocess
 import sys
+import time
+
+# Restart configuration to prevent crash loops
+MAX_RESTARTS = 3
+RESTART_DELAY = 10  # seconds between restart attempts
 
 if __name__ == "__main__":
     # In a generic Docker Space, this might not be executed if CMD is set in Dockerfile.
     # But if the user switches to generic Python SDK or wants to run it manually:
-    print("Starting OpenClaw Sync Wrapper...")
-    subprocess.run([sys.executable, "scripts/sync_hf.py"], check=True)
+
+    for attempt in range(MAX_RESTARTS):
+        try:
+            print("Starting OpenClaw Sync Wrapper...")
+            if attempt > 0:
+                print(f"Restart attempt {attempt + 1}/{MAX_RESTARTS}...")
+
+            result = subprocess.run(
+                [sys.executable, "scripts/sync_hf.py"],
+                check=True
+            )
+            # Success - exit with the subprocess's return code
+            sys.exit(result.returncode)
+
+        except subprocess.CalledProcessError as e:
+            print(f"ERROR: Sync process failed with exit code {e.returncode}", file=sys.stderr)
+            if attempt < MAX_RESTARTS - 1:
+                print(f"Retrying in {RESTART_DELAY} seconds...", file=sys.stderr)
+                time.sleep(RESTART_DELAY)
+            else:
+                print(f"ERROR: Failed after {MAX_RESTARTS} attempts. Giving up.", file=sys.stderr)
+                sys.exit(1)
+
+        except KeyboardInterrupt:
+            print("\nInterrupted by user.")
+            sys.exit(130)  # Standard exit code for SIGINT
+
+        except Exception as e:
+            print(f"ERROR: Unexpected error: {e}", file=sys.stderr)
+            if attempt < MAX_RESTARTS - 1:
+                print(f"Retrying in {RESTART_DELAY} seconds...", file=sys.stderr)
+                time.sleep(RESTART_DELAY)
+            else:
+                print(f"ERROR: Failed after {MAX_RESTARTS} attempts. Giving up.", file=sys.stderr)
+                sys.exit(1)