Single Instance Lock Reliability Issues Preventing Testing

[doobidoo]

Issue Summary

The dashboard fails to start during automated testing due to single instance lock conflicts, preventing comprehensive performance verification and debugging.

Problem Description

Expected Behavior

• Dashboard should start reliably for testing and development
• Clear error messages when instance conflicts occur
• Graceful handling of startup failures

Actual Behavior

• Dashboard startup fails with "Failed to get single instance lock, quitting"
• No clear indication of existing running instances
• Testing scripts unable to verify performance optimizations
• Immediate quit without user-friendly error handling

Error Encountered

🔒 Requesting single instance lock...
❌ Failed to get single instance lock, quitting...
⚠️ App will-quit event triggered

Root Cause Analysis

Single Instance Implementation Issues

• No detection of existing running instances
• No user notification when startup fails due to instance conflicts
• No option to force-restart or connect to existing instance
• Testing automation blocked by this restriction

Impact on Development

• Performance testing blocked: Cannot verify Issue Performance Bottleneck: Stats queries taking 8-10 seconds #10 optimizations
• Development workflow disrupted: Manual instance management required
• Automated testing impossible: CI/CD pipelines would fail
• User experience degraded: Unclear error states

Proposed Solutions

Option 1: Improved Instance Detection (Recommended)

// Enhanced startup logic
if (!app.requestSingleInstanceLock()) {
  // Show user-friendly notification
  const response = dialog.showMessageBoxSync({
    type: 'info',
    title: 'Memory Dashboard Already Running',
    message: 'Memory Dashboard is already running.',
    buttons: ['Show Existing Window', 'Force Restart', 'Cancel'],
    defaultId: 0
  });
  
  if (response === 1) {
    // Force restart: kill existing and start new
  } else if (response === 0) {
    // Focus existing window
  }
}

Option 2: Testing Mode Override

// Allow bypass for testing
const TESTING_MODE = process.env.NODE_ENV === 'test' || process.argv.includes('--allow-multiple');
if (!TESTING_MODE && !app.requestSingleInstanceLock()) {
  // Handle conflict
}

Option 3: Better Process Management

# Enhanced startup scripts
if pgrep -f "memory.*dashboard" > /dev/null; then
  echo "Dashboard already running, focusing existing window..."
  # Focus mechanism
else
  echo "Starting new dashboard instance..."
  npm start
fi

Technical Details

Current Single Instance Implementation

• Uses Electron's app.requestSingleInstanceLock()
• Immediately quits on conflict without user interaction
• No graceful degradation or alternative behaviors

System Environment

• Version: v1.3.1
• Platform: macOS (affects across platforms)
• Electron Version: 32.0.0
• Node Environment: Development and testing

Related Code Locations

• electron/main.ts - Single instance lock implementation
• Startup scripts - Need instance detection
• Testing infrastructure - Blocked by this issue

User Experience Impact

For Developers

• Blocked Performance Testing: Cannot verify Issue Performance Bottleneck: Stats queries taking 8-10 seconds #10 optimizations
• Manual Process Management: Must manually kill processes for testing
• Development Friction: Additional steps for routine testing

For End Users

• Confusing Startup Failures: No clear explanation when startup fails
• No Recovery Options: Can't easily resolve instance conflicts
• Reduced Reliability: Startup success depends on perfect cleanup

Acceptance Criteria

Must Have

• Clear error messages when instance conflicts occur
• User-friendly options to resolve conflicts (focus existing, restart, cancel)
• Testing mode that allows multiple instances for automation
• Graceful startup failure handling

Should Have

• Automatic detection and focusing of existing instances
• Command-line flags for testing scenarios
• Better process cleanup on shutdown
• Startup scripts with instance detection

Nice to Have

• Visual indication of running instances in system tray
• Health check endpoint for testing automation
• Instance management utilities
• Recovery mechanisms for orphaned processes

Environment

• Operating System: macOS (affects all platforms)
• Node.js Version: Current LTS
• Electron Version: 32.0.0
• Testing Framework: Custom bash scripts, npm scripts

Related Issues

• Issue Performance Bottleneck: Stats queries taking 8-10 seconds #10: Performance optimization testing blocked by this issue
• Testing Infrastructure: Automated testing reliability affected
• Development Workflow: Manual workarounds required

Priority

High - Blocks performance verification, testing automation, and impacts development workflow

Labels

• bug - Startup reliability issue
• testing - Blocks automated testing
• reliability - Affects startup reliability
• electron - Electron app lifecycle issue
• high-priority - Blocks other development work