Fix concurrency issues in TimerAutomationEngine and PermissionManager

.agent-os/specs/2025-07-24-concurrency-crash-fixes/spec.md

@@ -0,0 +1,73 @@
+# Spec Requirements Document
+
+> Spec: Critical Concurrency Crash Fixes
+> Created: 2025-07-24
+> Status: Planning
+
+## Overview
+
+Fix critical concurrency race conditions in timer callbacks and app initialization that cause immediate app crashes when Accessibility permissions are toggled ON/OFF, while preserving all advanced functionality implemented since version 1.4.15.
+
+## User Stories
+
+### Application Stability Recovery
+
+As a ClickIt user, I want to toggle Accessibility permissions ON/OFF in System Settings without the app crashing, so that I can manage permissions normally and continue using the application reliably.
+
+**Detailed Workflow:**
+1. User opens ClickIt application successfully
+2. User opens System Settings → Privacy & Security → Accessibility
+3. User toggles ClickIt permission OFF then ON (or vice versa)
+4. Application continues running without crashes
+5. Permission status updates correctly in the UI
+6. All timer-based functionality continues working properly
+
+### Developer Debugging Experience
+
+As a developer debugging ClickIt, I want clear concurrency patterns that follow Swift's MainActor isolation rules, so that I can maintain and extend the codebase without introducing race conditions.
+
+**Detailed Workflow:**
+1. Developer identifies concurrency issues in timer callbacks
+2. Fixed patterns use proper MainActor isolation without nested tasks
+3. Code is maintainable and follows Swift concurrency best practices
+4. Future timer implementations follow established safe patterns
+
+### Preservation of Advanced Features
+
+As a ClickIt user, I want all advanced features implemented since version 1.4.15 to continue working exactly as before, so that the stability fix doesn't break any existing functionality.
+
+**Detailed Workflow:**
+1. All timer automation continues with sub-10ms precision
+2. Permission monitoring works correctly without crashes
+3. Visual feedback system remains fully functional
+4. All UI panels and controls work as expected
+
+## Spec Scope
+
+1. **PermissionManager Concurrency Fix** - Replace problematic `Task { @MainActor in }` pattern in timer callback (line 190-194)
+2. **TimerAutomationEngine High-Precision Timer Fix** - Fix MainActor race condition in HighPrecisionTimer callback (lines 288-292)
+3. **TimerAutomationEngine Status Update Timer Fix** - Fix concurrency issue in status update timer (lines 389-393)
+4. **ClickItApp Initialization Fix** - Resolve MainActor task conflict in app initialization (lines 18-20)
+5. **Validation Testing** - Comprehensive testing to ensure crashes are eliminated during permission toggling
+
+## Out of Scope
+
+- Rewriting the entire timer system architecture
+- Changing the MainActor isolation strategy for classes
+- Modifying the permission monitoring frequency or behavior
+- Altering any user-facing functionality or UI behavior
+- Performance optimizations beyond fixing the race conditions
+
+## Expected Deliverable
+
+1. **Crash-Free Permission Toggling** - App no longer crashes when Accessibility permissions are toggled in System Settings
+2. **Proper MainActor Patterns** - All timer callbacks use safe concurrency patterns compatible with @MainActor classes
+3. **Preserved Functionality** - All existing features work identically to pre-fix behavior
+4. **Code Quality Improvement** - Cleaner, more maintainable concurrency patterns following Swift best practices
+5. **Comprehensive Testing Validation** - Thorough testing confirms stability across permission state changes
+
+## Spec Documentation
+
+- Tasks: @.agent-os/specs/2025-07-24-concurrency-crash-fixes/tasks.md
+- Technical Specification: @.agent-os/specs/2025-07-24-concurrency-crash-fixes/sub-specs/technical-spec.md
+- Tests Specification: @.agent-os/specs/2025-07-24-concurrency-crash-fixes/sub-specs/tests.md

.agent-os/specs/2025-07-24-concurrency-crash-fixes/sub-specs/technical-spec.md

@@ -0,0 +1,112 @@
+# Technical Specification
+
+This is the technical specification for the spec detailed in @.agent-os/specs/2025-07-24-concurrency-crash-fixes/spec.md
+
+> Created: 2025-07-24
+> Version: 1.0.0
+
+## Technical Requirements
+
+### Root Cause Analysis
+
+The application crashes are caused by improper MainActor concurrency patterns in timer callbacks where @MainActor-isolated classes use `Task { @MainActor in }` wrappers, creating race conditions and concurrency conflicts.
+
+**Specific Problem Pattern:**
+```swift
+// PROBLEMATIC - Creates race condition
+Timer.scheduledTimer(withTimeInterval: interval, repeats: true) { _ in
+    Task { @MainActor in  // ❌ Already on MainActor, creates conflict
+        // MainActor-isolated code
+    }
+}
+```
+
+**Required Safe Pattern:**
+```swift
+// SAFE - Properly dispatches to MainActor
+Timer.scheduledTimer(withTimeInterval: interval, repeats: true) { _ in
+    DispatchQueue.main.async {  // ✅ Safe MainActor dispatch
+        // MainActor-isolated code
+    }
+}
+```
+
+### File-Specific Technical Requirements
+
+#### 1. PermissionManager.swift (Lines 190-194)
+- **Current Issue:** Timer callback using `Task { @MainActor in }` when class is @MainActor
+- **Required Fix:** Replace with `DispatchQueue.main.async` 
+- **Critical Constraint:** Must preserve exact permission monitoring timing and behavior
+- **Performance Requirement:** No degradation in permission status update frequency
+
+#### 2. TimerAutomationEngine.swift (Lines 288-292) - HighPrecisionTimer Callback
+- **Current Issue:** High-precision timer callback using nested MainActor task
+- **Required Fix:** Use `DispatchQueue.main.async` for MainActor work
+- **Critical Constraint:** Must maintain sub-10ms timing accuracy
+- **Performance Requirement:** No impact on clicking precision or timing stability
+
+#### 3. TimerAutomationEngine.swift (Lines 389-393) - Status Update Timer
+- **Current Issue:** Status update timer using problematic MainActor pattern
+- **Required Fix:** Safe MainActor dispatch for UI updates
+- **Critical Constraint:** Preserve real-time status updates and statistics tracking
+- **Performance Requirement:** No delay in UI refresh or status synchronization
+
+#### 4. ClickItApp.swift (Lines 18-20) - App Initialization
+- **Current Issue:** App initialization using `Task { @MainActor in }` in main context
+- **Required Fix:** Proper initialization sequence without nested MainActor tasks
+- **Critical Constraint:** Maintain exact app startup behavior and initialization order
+- **Performance Requirement:** No impact on app launch time or startup reliability
+
+## Approach Options
+
+**Option A: DispatchQueue.main.async Pattern (Selected)**
+- Pros: Proven safe pattern, widely used, explicit about MainActor dispatch
+- Cons: Slightly more verbose than Task syntax
+- Rationale: Industry standard, no concurrency conflicts, maintains timing precision
+
+**Option B: Remove Task Wrappers Entirely** 
+- Pros: Minimal code changes, relies on existing MainActor isolation
+- Cons: May not work for all timer callback contexts, potential threading issues
+- Rationale: Not selected due to potential threading safety concerns
+
+**Option C: Rewrite with AsyncTimer and Swift Concurrency**
+- Pros: Modern Swift concurrency, potentially better performance
+- Cons: Major architectural change, risk of introducing new issues
+- Rationale: Not selected due to scope constraints and unnecessary complexity
+
+## External Dependencies
+
+**No New Dependencies Required**
+- All fixes use existing Foundation and Dispatch APIs
+- No additional frameworks or third-party libraries needed
+- Pure Swift standard library solutions
+
+## Implementation Strategy
+
+### Phase 1: Critical Timer Callback Fixes
+1. **PermissionManager Timer Fix** - Replace Task wrapper with DispatchQueue pattern
+2. **TimerAutomationEngine HighPrecisionTimer Fix** - Safe MainActor dispatch for precision timing
+3. **TimerAutomationEngine Status Timer Fix** - Proper UI update dispatching
+
+### Phase 2: App Initialization Fix
+1. **ClickItApp Initialization** - Remove nested MainActor task conflicts
+2. **Startup Sequence Validation** - Ensure proper initialization order maintained
+
+### Phase 3: Comprehensive Testing
+1. **Permission Toggle Testing** - Validate no crashes during permission changes
+2. **Timer Precision Validation** - Confirm sub-10ms timing accuracy preserved
+3. **Functional Regression Testing** - Verify all features work identically
+
+## Performance Considerations
+
+### Timing Precision Requirements
+- **Sub-10ms Click Timing:** Must be preserved exactly
+- **Permission Monitoring:** Real-time status updates without delay  
+- **UI Responsiveness:** No degradation in interface responsiveness
+- **Memory Usage:** No increase in memory footprint from concurrency changes
+
+### Concurrency Safety Requirements
+- **Thread Safety:** All MainActor-isolated code properly dispatched
+- **Race Condition Elimination:** No concurrent access to shared state
+- **Timer Callback Safety:** All timer callbacks use safe MainActor patterns
+- **Resource Cleanup:** Proper timer cleanup and resource management

.agent-os/specs/2025-07-24-concurrency-crash-fixes/sub-specs/tests.md

@@ -0,0 +1,143 @@
+# Tests Specification
+
+This is the tests coverage details for the spec detailed in @.agent-os/specs/2025-07-24-concurrency-crash-fixes/spec.md
+
+> Created: 2025-07-24
+> Version: 1.0.0
+
+## Test Coverage
+
+### Unit Tests
+
+**PermissionManager**
+- Test timer callback execution without MainActor conflicts
+- Test permission status monitoring during rapid state changes
+- Test proper cleanup of timer resources
+- Test thread safety of permission status updates
+
+**TimerAutomationEngine**
+- Test high-precision timer callback safety under MainActor isolation
+- Test status update timer concurrent access patterns
+- Test timer lifecycle management with proper resource cleanup
+- Test precision timing accuracy after concurrency fixes
+
+**ClickItApp**
+- Test app initialization sequence without MainActor task conflicts
+- Test startup stability with proper concurrency patterns
+- Test app lifecycle management with timer-based components
+
+### Integration Tests
+
+**Permission Toggle Workflow**
+- Test complete permission ON → OFF → ON cycle without crashes
+- Test permission status UI updates during system changes
+- Test app resilience during System Settings permission modifications
+- Test multiple rapid permission toggles for race condition detection
+
+**Timer System Integration**
+- Test all timer systems working together without conflicts
+- Test coordinated timer execution with MainActor-isolated components
+- Test timer precision under concurrent permission monitoring
+- Test error recovery when timers encounter MainActor conflicts
+
+**App Stability Under Concurrency**
+- Test app stability during rapid user interactions
+- Test concurrent timer execution with UI updates
+- Test memory management during high-frequency timer callbacks
+- Test resource cleanup during abnormal termination scenarios
+
+### Performance Tests
+
+**Timing Precision Validation**
+- Test sub-10ms click timing accuracy preserved after fixes
+- Test permission monitoring frequency unchanged
+- Test UI responsiveness during concurrent timer operations
+- Test memory usage stability with corrected concurrency patterns
+
+**Concurrency Performance**
+- Test MainActor dispatch performance vs. Task pattern
+- Test timer callback execution time consistency
+- Test UI update latency with DispatchQueue.main.async pattern
+- Test overall app performance impact of concurrency fixes
+
+### Crash Prevention Tests
+
+**Permission Toggle Crash Prevention**
+- Test Accessibility permission toggle ON without crash
+- Test Accessibility permission toggle OFF without crash
+- Test rapid permission state changes without instability
+- Test permission monitoring resilience during system changes
+
+**MainActor Concurrency Safety**
+- Test all timer callbacks execute safely on MainActor
+- Test no nested MainActor task conflicts in any code path
+- Test proper thread isolation for MainActor-bound components
+- Test race condition elimination in permission monitoring
+
+**Error Recovery Testing**
+- Test graceful handling of timer callback exceptions
+- Test app recovery from MainActor-related errors
+- Test proper error reporting without masking concurrency issues
+- Test automatic timer restart after concurrency-related failures
+
+### Regression Tests
+
+**Feature Preservation Validation**
+- Test all clicking functionality works identically to pre-fix behavior
+- Test permission UI panels function exactly as before
+- Test visual feedback system maintains all capabilities
+- Test preset system and configuration preservation
+
+**Performance Regression Prevention**
+- Test no degradation in click timing precision
+- Test no increase in memory usage
+- Test no reduction in UI responsiveness
+- Test no impact on app startup time
+
+### Manual Testing Scenarios
+
+**Real-World Permission Management**
+1. Open ClickIt application
+2. Navigate to System Settings → Privacy & Security → Accessibility
+3. Toggle ClickIt permission OFF
+4. Verify app continues running, UI updates correctly
+5. Toggle ClickIt permission ON
+6. Verify app functions normally, no crashes or errors
+7. Repeat cycle 10 times rapidly
+8. Confirm consistent behavior and stability
+
+**Concurrency Stress Testing**
+1. Start clicking automation with high CPS rate
+2. While clicking is active, toggle Accessibility permission
+3. Verify automation stops/resumes correctly without crashes
+4. Test with multiple simultaneous actions (clicking + permission changes)
+5. Monitor for any MainActor-related warnings or crashes
+
+## Mocking Requirements
+
+**System Permission APIs**
+- Mock Accessibility API responses for permission state changes
+- Mock System Settings integration for automated testing
+- Mock timer execution environment for controlled concurrency testing
+
+**MainActor Execution Context**
+- Mock MainActor dispatch behavior for testing race conditions
+- Mock timer callback execution in controlled threading environment
+- Mock UI update scheduling for testing dispatch patterns
+
+## Testing Tools and Framework
+
+**XCTest Integration**
+- Unit tests for all concurrency-related methods
+- Integration tests for timer and permission system interaction
+- Performance tests for timing accuracy validation
+
+**Manual Testing Protocol**
+- Structured permission toggle testing procedure
+- Crash reproduction and validation methodology
+- Performance benchmarking for regression detection
+
+**Automated Testing Pipeline**
+- CI integration for concurrency safety validation
+- Automated crash detection and reporting
+- Performance regression testing in build pipeline

.agent-os/specs/2025-07-24-concurrency-crash-fixes/tasks.md

@@ -0,0 +1,56 @@
+# Spec Tasks
+
+These are the tasks to be completed for the spec detailed in @.agent-os/specs/2025-07-24-concurrency-crash-fixes/spec.md
+
+> Created: 2025-07-24
+> Status: Ready for Implementation
+
+## Tasks
+
+- [x] 1. Fix PermissionManager Timer Concurrency Issue
+  - [x] 1.1 Write tests for PermissionManager timer callback safety
+  - [x] 1.2 Identify exact location of problematic `Task { @MainActor in }` pattern (lines 190-194)
+  - [x] 1.3 Replace with `DispatchQueue.main.async` pattern for safe MainActor dispatch
+  - [x] 1.4 Validate permission monitoring timing and behavior preserved
+  - [x] 1.5 Test permission toggle scenarios to confirm crash elimination
+  - [x] 1.6 Verify all tests pass with new concurrency pattern
+
+- [ ] 2. Fix TimerAutomationEngine HighPrecisionTimer Concurrency
+  - [ ] 2.1 Write tests for high-precision timer MainActor safety
+  - [ ] 2.2 Locate problematic MainActor pattern in HighPrecisionTimer callback (lines 288-292)
+  - [ ] 2.3 Implement safe MainActor dispatch using DispatchQueue.main.async
+  - [ ] 2.4 Validate sub-10ms timing accuracy preservation
+  - [ ] 2.5 Test click precision under concurrent permission monitoring
+  - [ ] 2.6 Verify all timer precision tests pass
+
+- [ ] 3. Fix TimerAutomationEngine Status Update Timer Concurrency
+  - [ ] 3.1 Write tests for status update timer thread safety
+  - [ ] 3.2 Fix MainActor concurrency issue in status update timer (lines 389-393)
+  - [ ] 3.3 Replace nested MainActor task with proper dispatch pattern
+  - [ ] 3.4 Validate real-time UI status updates preserved
+  - [ ] 3.5 Test statistics tracking and UI synchronization
+  - [ ] 3.6 Verify all status update functionality tests pass
+
+- [ ] 4. Fix ClickItApp Initialization Concurrency
+  - [ ] 4.1 Write tests for app initialization MainActor patterns
+  - [ ] 4.2 Identify and fix MainActor task conflict in app init (lines 18-20)
+  - [ ] 4.3 Implement proper initialization sequence without nested MainActor tasks
+  - [ ] 4.4 Validate app startup behavior and initialization order preserved
+  - [ ] 4.5 Test app launch stability under various conditions
+  - [ ] 4.6 Verify all app initialization tests pass
+
+- [ ] 5. Comprehensive Crash Prevention Testing
+  - [ ] 5.1 Write comprehensive permission toggle crash tests
+  - [ ] 5.2 Implement automated testing for Accessibility permission ON/OFF cycles
+  - [ ] 5.3 Test rapid permission state changes for race condition detection
+  - [ ] 5.4 Validate no crashes occur during any permission management scenario
+  - [ ] 5.5 Test app stability under concurrent timer operations
+  - [ ] 5.6 Verify all crash prevention tests pass
+
+- [ ] 6. Performance and Regression Validation
+  - [ ] 6.1 Write performance tests for timing precision validation
+  - [ ] 6.2 Benchmark sub-10ms click timing accuracy after concurrency fixes
+  - [ ] 6.3 Validate no performance degradation in any timer-based functionality
+  - [ ] 6.4 Test all existing features work identically to pre-fix behavior
+  - [ ] 6.5 Verify memory usage and CPU performance unchanged
+  - [ ] 6.6 Confirm all performance and regression tests pass