feat: enhance debug system with task status tracking and configurable notifications

- Add TaskStatus.SCHEDULED notifications when tasks are registered
- Add TaskStatus.RESCHEDULED status to distinguish from RETRYING
- Fix notification flow: Started → Rescheduled → Retrying → Success
- Add configurable notification channels and grouping for debug handlers
- Update notification icons to cleaner symbols (▶️ ✅ ❌ 🔄 ⏹️ 📅)
- Add comprehensive task status documentation with platform differences
- Fix Android retry detection using runAttemptCount
- Remove duplicate exception notifications for normal task failures
- Update example apps to demonstrate new debug configuration

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ened

example/android/app/src/main/AndroidManifest.xml

@@ -1,10 +1,14 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
+  <!-- Required for notification debug handler -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
   <application
+    android:name="dev.fluttercommunity.workmanager_example.ExampleApplication"
     android:icon="@mipmap/ic_launcher"
     android:label="workmanager_example">
     <activity
-      android:name="io.flutter.embedding.android.FlutterActivity"
+      android:name="dev.fluttercommunity.workmanager_example.MainActivity"
       android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
       android:hardwareAccelerated="true"
       android:launchMode="singleTop"

example/android/app/src/main/kotlin/dev/fluttercommunity/workmanager_example/ExampleApplication.kt

@@ -0,0 +1,50 @@
+package dev.fluttercommunity.workmanager_example
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.os.Build
+import dev.fluttercommunity.workmanager.LoggingDebugHandler
+import dev.fluttercommunity.workmanager.NotificationDebugHandler
+import dev.fluttercommunity.workmanager.WorkmanagerDebug
+import io.flutter.app.FlutterApplication
+
+class ExampleApplication : FlutterApplication() {
+
+    override fun onCreate() {
+        super.onCreate()
+
+        // Create custom notification channel for debug notifications
+        val debugChannelId = "workmanager_debug"
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                debugChannelId,
+                "Workmanager Example Debug",
+                NotificationManager.IMPORTANCE_DEFAULT
+            ).apply {
+                description = "Debug notifications for background tasks in example app"
+            }
+            
+            val notificationManager = getSystemService(NotificationManager::class.java)
+            notificationManager.createNotificationChannel(channel)
+        }
+
+        // EXAMPLE: Enable debug handlers for background tasks
+        // Choose one of the following options:
+        
+        // Option 1: Custom notification handler using our custom channel
+        WorkmanagerDebug.setCurrent(NotificationDebugHandler(
+            channelId = debugChannelId,
+            channelName = "Workmanager Example Debug", 
+            groupKey = "workmanager_example_group"
+        ))
+        
+        // Option 2: Default notification handler (creates and uses default channel)
+        // WorkmanagerDebug.setCurrent(NotificationDebugHandler())
+        
+        // Option 3: Logging-based debug handler (writes to system log)
+        // WorkmanagerDebug.setCurrent(LoggingDebugHandler())
+        
+        // Note: For Android 13+, the app needs to request POST_NOTIFICATIONS permission
+        // at runtime from the Flutter side or in the first activity
+    }
+}

example/android/app/src/main/kotlin/dev/fluttercommunity/workmanager_example/MainActivity.kt

@@ -0,0 +1,51 @@
+package dev.fluttercommunity.workmanager_example
+
+import android.Manifest
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import io.flutter.embedding.android.FlutterActivity
+
+class MainActivity : FlutterActivity() {
+    companion object {
+        private const val NOTIFICATION_PERMISSION_REQUEST_CODE = 1001
+    }
+
+    override fun onStart() {
+        super.onStart()
+        
+        // Request notification permission for Android 13+ (API 33+)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            if (ContextCompat.checkSelfPermission(
+                    this,
+                    Manifest.permission.POST_NOTIFICATIONS
+                ) != PackageManager.PERMISSION_GRANTED
+            ) {
+                ActivityCompat.requestPermissions(
+                    this,
+                    arrayOf(Manifest.permission.POST_NOTIFICATIONS),
+                    NOTIFICATION_PERMISSION_REQUEST_CODE
+                )
+            }
+        }
+    }
+
+    override fun onRequestPermissionsResult(
+        requestCode: Int,
+        permissions: Array<out String>,
+        grantResults: IntArray
+    ) {
+        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
+        
+        if (requestCode == NOTIFICATION_PERMISSION_REQUEST_CODE) {
+            if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
+                // Permission granted - debug notifications will work
+                println("Notification permission granted for debug handler")
+            } else {
+                // Permission denied - debug notifications won't show
+                println("Notification permission denied - debug notifications will not be shown")
+            }
+        }
+    }
+}

example/ios/Runner/AppDelegate.swift

@@ -13,6 +13,24 @@ import workmanager_apple
         GeneratedPluginRegistrant.register(with: self)
         UNUserNotificationCenter.current().delegate = self
 
+        // Request notification permission for debug handler
+        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, error in
+            if granted {
+                print("Notification permission granted for debug handler")
+            } else if let error = error {
+                print("Error requesting notification permission: \(error)")
+            }
+        }
+
+        // EXAMPLE: Enable debug notifications for background tasks
+        // Uncomment one of the following lines to enable debug output:
+        
+        // Option 1: Notification-based debug handler (shows debug info as notifications)
+        WorkmanagerDebug.setCurrent(NotificationDebugHandler())
+        
+        // Option 2: Logging-based debug handler (writes to system log)
+        // WorkmanagerDebug.setCurrent(LoggingDebugHandler())
+
         WorkmanagerPlugin.setPluginRegistrantCallback { registry in
             // Registry in this case is the FlutterEngine that is created in Workmanager's
             // performFetchWithCompletionHandler or BGAppRefreshTask.