openhuman/docs/feat/daemon-lifecycle-management.md

Daemon Lifecycle Management System

Status: ✅ Implemented Version: 1.0.0 Date: February 2026

Overview

The Daemon Lifecycle Management System provides comprehensive frontend integration with the alphahuman Rust daemon, enabling real-time health monitoring, automatic lifecycle management, and user-friendly daemon controls throughout the application.

Background

Problem Statement

The alphahuman application runs a sophisticated Rust daemon that manages critical backend services (gateway, channels, heartbeat, scheduler) and emits detailed health information every 5 seconds. However, the frontend previously had:

• Poor Visibility: Daemon controls buried in developer console only
• No Real-Time Monitoring: Manual status checks with raw JSON output
• No Automatic Management: No startup detection or error recovery
• Disconnected UX: Health events from Rust were ignored by frontend
• Manual Recovery: Users had to manually restart failed services

Solution Overview

This implementation creates a complete bridge between the Rust daemon's health system and the React frontend, providing:

• Real-time health monitoring with visual indicators
• Automatic daemon startup and error recovery
• User-friendly health displays in main UI
• Enhanced developer tools with live status
• Coordinated daemon and socket connection management

Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                    React Frontend                           │
├─────────────────────────────────────────────────────────────┤
│  UI Layer                                                   │
│  ├── DaemonHealthIndicator (Main UI)                       │
│  ├── DaemonHealthPanel (Detailed View)                     │
│  └── Enhanced TauriCommandsPanel (Dev Tools)               │
├─────────────────────────────────────────────────────────────┤
│  State Management                                           │
│  ├── daemonSlice.ts (Redux)                                │
│  ├── useDaemonHealth.ts (React Hook)                       │
│  └── useDaemonLifecycle.ts (Lifecycle Hook)                │
├─────────────────────────────────────────────────────────────┤
│  Services                                                   │
│  └── daemonHealthService.ts (Event Processing)             │
├─────────────────────────────────────────────────────────────┤
│  Integration Layer                                          │
│  ├── tauriSocket.ts (Event Listening)                      │
│  └── SocketProvider.tsx (Coordinated State)                │
└─────────────────────────────────────────────────────────────┘
                           │
                    Tauri Event Bridge
                           │
┌─────────────────────────────────────────────────────────────┐
│                    Rust Daemon                              │
├─────────────────────────────────────────────────────────────┤
│  Health System (src-tauri/src/alphahuman/health/mod.rs)    │
│  ├── Component Health Tracking                             │
│  ├── Health Snapshot Generation                            │
│  └── Event Emission (every 5s)                             │
├─────────────────────────────────────────────────────────────┤
│  Daemon Supervisor (src-tauri/src/alphahuman/daemon/mod.rs) │
│  ├── Component Management                                   │
│  ├── Automatic Restarts                                    │
│  └── Exponential Backoff                                   │
├─────────────────────────────────────────────────────────────┤
│  Components                                                 │
│  ├── Gateway (API Server)                                  │
│  ├── Channels (Communication)                              │
│  ├── Heartbeat (Health Monitor)                            │
│  └── Scheduler (Cron Jobs)                                 │
└─────────────────────────────────────────────────────────────┘

Event Flow

1. Health Generation: Rust daemon generates health snapshots every 5 seconds
2. Event Emission: Health data emitted via alphahuman:health Tauri event
3. Frontend Processing: daemonHealthService receives and parses events
4. State Updates: Redux state updated with component health information
5. UI Reactivity: React components automatically re-render with new status
6. User Actions: Manual controls trigger Tauri commands back to Rust

Implementation Details

Redux State Management

File: src/store/daemonSlice.ts

interface DaemonUserState {
  status: 'starting' | 'running' | 'error' | 'disconnected';
  healthSnapshot: HealthSnapshot | null;
  components: {
    gateway?: ComponentHealth;
    channels?: ComponentHealth;
    heartbeat?: ComponentHealth;
    scheduler?: ComponentHealth;
  };
  lastHealthUpdate: string | null;
  connectionAttempts: number;
  autoStartEnabled: boolean;
  isRecovering: boolean;
  healthTimeoutId: string | null;
}

Key Features:

• Per-user daemon state isolation (following existing patterns)
• Component-level health tracking with error details
• Connection attempt management with exponential backoff
• Auto-start preference persistence
• Timeout handling for health event detection

Health Monitoring Service

File: src/services/daemonHealthService.ts

export class DaemonHealthService {
  private healthTimeoutId: NodeJS.Timeout | null = null;
  private readonly HEALTH_TIMEOUT_MS = 30000; // 30 seconds

  async setupHealthListener(): Promise<UnlistenFn | null>;
  private parseHealthSnapshot(payload: unknown): HealthSnapshot | null;
  private updateReduxFromHealth(snapshot: HealthSnapshot): void;
  startHealthTimeout(): void;
}

Responsibilities:

• Listen for alphahuman:health Tauri events from Rust
• Parse and validate health snapshot data
• Update Redux state with component health information
• Manage 30-second timeout detection for disconnected daemon
• Handle cleanup and error recovery

UI Components

DaemonHealthIndicator

File: src/components/daemon/DaemonHealthIndicator.tsx

Purpose: Compact status indicator for main application UI

Visual States:

• 🟢 Green: All components running healthy (status: 'running')
• 🟡 Yellow: Daemon starting or recovering (status: 'starting')
• 🔴 Red: One or more components in error state (status: 'error')
• ⚪ Gray: Daemon disconnected or not running (status: 'disconnected')

Features:

• Click to open detailed health panel
• Tooltip showing component health summary
• Responsive sizing (sm/md/lg variants)
• Only visible in Tauri environments

DaemonHealthPanel

File: src/components/daemon/DaemonHealthPanel.tsx

Purpose: Detailed health breakdown and manual controls

Features:

• Component health table with status, last update, restart counts
• Manual restart buttons for individual components
• Auto-start toggle with persistence
• Connection retry controls
• Real-time health information display
• User-friendly error messages and troubleshooting hints

Lifecycle Management

File: src/hooks/useDaemonLifecycle.ts

Automatic Behaviors:

1. App Startup:

   • Detect existing daemon status
   • Auto-start daemon if enabled and not running
   • Setup health monitoring listeners

2. Error Recovery:

   • Exponential backoff retry attempts (1s → 2s → 4s → 8s → 30s max)
   • Maximum 5 retry attempts before requiring manual intervention
   • Clear error states on successful recovery

3. Background Handling:

   • Maintain health monitoring when app backgrounded
   • Reconnection logic without page refresh
   • Coordinate with socket connection management

4. Cleanup:

   • Proper event listener cleanup on unmount
   • Timeout cancellation to prevent memory leaks
   • Graceful shutdown coordination

Integration Points

Enhanced Service Management

File: src/components/settings/panels/TauriCommandsPanel.tsx

Improvements to Existing Developer Console:

• Live Status Display: Real-time daemon status with PID and uptime
• Component Health Grid: Visual status for all daemon components
• Enhanced Controls: Smart start/stop buttons with proper loading states
• Auto-Start Toggle: User preference for automatic daemon startup
• Connection Tracking: Display retry attempts and recovery status
• Better Error Messages: User-friendly errors with troubleshooting hints

Before vs After:

// Before: Manual status check
<PrimaryButton onClick={() => run(alphahumanServiceStatus, 'serviceStatus')}>
  Status
</PrimaryButton>

// After: Live status display
<div className="flex items-center gap-3">
  <DaemonHealthIndicator size="md" />
  <div>
    <div className="text-white font-medium">Daemon Status: {status}</div>
    <div className="text-xs text-gray-400">PID: {pid} | Uptime: {uptime}</div>
  </div>
</div>

Socket Provider Integration

File: src/providers/SocketProvider.tsx

Coordinated State Management:

• Check daemon health before attempting socket connections
• Display daemon-related errors in socket connection status
• Coordinate daemon startup with socket connection flows
• Provide daemon health context to socket consumers

Main UI Integration

File: src/components/MiniSidebar.tsx

User-Facing Integration:

• Daemon health indicator in main navigation (Tauri-only)
• Click to open detailed health modal
• Non-intrusive but easily accessible
• Consistent with existing UI patterns

User Experience

For End Users

1. Visible Status: Daemon health indicator in main UI shows system status at a glance
2. Automatic Operation: Daemon starts automatically and recovers from errors without user intervention
3. Clear Feedback: User-friendly messages explain daemon state and provide actionable guidance
4. Quick Access: Click health indicator to see detailed component status and manual controls

For Developers

1. Enhanced Console: Improved service management in settings with live status updates
2. Component Monitoring: Real-time visibility into all daemon components (gateway, channels, etc.)
3. Debug Information: Detailed health snapshots, retry attempts, and error history
4. Manual Override: Full control over daemon lifecycle with proper state management

Error Handling

1. Graceful Degradation: System works properly in non-Tauri environments
2. Timeout Management: 30-second timeout detection with automatic recovery attempts
3. User Guidance: Clear error messages with troubleshooting suggestions
4. Recovery Actions: Manual restart options when automatic recovery fails

Technical Benefits

Performance

• Efficient Updates: Debounced Redux updates prevent excessive re-renders
• Memory Management: Proper cleanup of timeouts and event listeners
• Background Optimization: Minimal resource usage when app backgrounded

Reliability

• Timeout Handling: Robust detection of daemon disconnection
• Exponential Backoff: Smart retry logic prevents resource exhaustion
• State Consistency: Coordinated daemon and socket connection states
• Error Recovery: Automatic recovery from transient failures

Maintainability

• TypeScript: Full type safety throughout the implementation
• Modular Design: Clear separation between state, services, and UI components
• Existing Patterns: Follows established Redux and component patterns
• Testing: Comprehensive error handling and edge case management

Configuration

Auto-Start Behavior

Users can control daemon auto-start behavior through:

1. UI Toggle: Available in both health panel and settings console
2. Persistence: Preference stored in Redux with persistence
3. Default: Auto-start enabled by default for better UX

Health Monitoring

• Event Frequency: Rust daemon emits health every 5 seconds
• Timeout Duration: 30 seconds without health events = disconnected
• Retry Logic: Maximum 5 attempts with exponential backoff
• Component Tracking: Gateway, channels, heartbeat, scheduler components

Future Enhancements

Potential Improvements

1. Health History: Track daemon health over time with charts/graphs
2. Performance Metrics: CPU/memory usage from daemon components
3. Log Integration: Show daemon logs directly in health panel
4. Mobile Optimization: Enhanced mobile-specific daemon management
5. Notification System: Push notifications for critical daemon events

Extensibility

The architecture supports easy extension for:

• Additional daemon components
• Custom health check logic
• Third-party integrations
• Advanced monitoring features

Conclusion

The Daemon Lifecycle Management System provides a complete bridge between the sophisticated Rust daemon infrastructure and the React frontend, delivering excellent user experience while maintaining the technical robustness required for a production application.

The implementation follows established patterns, provides comprehensive error handling, and creates a foundation for future daemon-related features while ensuring the system remains reliable and user-friendly.