Refactored events (#621)

Event handling:

- Added unified event handling for application, system, and Wi‑Fi events.
- Updated all apps to reflect event handling changes

Wi-Fi:

- Refactored event handling from listener interface to task & event group.
- Added direct Wi‑Fi radio controls and improved event subscriptions.
- Wi‑Fi screens now refresh asynchronously and handle unavailable devices more gracefully.
- Enabled Wi‑Fi by default on in dts files, but radio on/off is still done by code. The main reason was reliable event subscription and consistent devicetree states.
- Improved Wi‑Fi shutdown cleanup and radio-state handling.

Other:
- Renamed the Kernel Display app to Display.

Modules/app-module/include/app/event.h

@@ -6,15 +6,14 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#include <tactility/concurrent/task_event_group.h>
 #include <tactility/error.h>
-#include <tactility/freertos/freertos.h>
-#include <tactility/freertos/task.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/** Identifies the kind of app-lifecycle event delivered through app_event_await(). */
+/** Identifies the kind of app-lifecycle event delivered through app_event_poll(). */
 enum AppEventType {
     APP_EVENT_RESULT, // struct AppResultEventData
     APP_EVENT_CLOSE,  // no data - terminate now, permanently
@@ -51,30 +50,62 @@ struct AppEvent {
  * Caller-owned subscription node. Unlike TactilityKernel's system_event poll subscription
  * (which coalesces to the latest value), this queues events by value (FIFO) since dropping an
  * APP_EVENT_RESULT would be unacceptable.
- * @warning Fields other than `app_instance_id` are for internal use only; do not read or write
- * them directly.
+ * @warning Fields other than `bit` are for internal use only; do not read or write them
+ * directly.
  */
 struct AppEventSubscription {
-    /** The app instance this subscription receives events for; set by the caller before app_event_subscribe(). */
-    AppInstanceId app_instance_id;
+    /** Set by app_event_subscribe()/app_event_subscribe_with_app_id(). Read-only for the
+     * caller: OR it into a task_event_group_wait() mask (alongside other subscriptions sharing
+     * the same `event_group`) to block on this subscription and other event sources with one
+     * call. */
+    uint32_t bit;
 
-    TaskHandle_t task;
+    struct {
+        /** The app instance this subscription receives events for; set by
+         * app_event_subscribe()/app_event_subscribe_with_app_id(). */
+        AppInstanceId app_instance_id;
 
-    struct AppEvent queue[APP_EVENT_QUEUE_CAPACITY];
-    uint8_t head;
-    uint8_t count;
+        /** Caller-owned, borrowed; set by app_event_subscribe(). */
+        struct TaskEventGroup* event_group;
 
-    struct AppEventSubscription* next;
+        struct AppEvent queue[APP_EVENT_QUEUE_CAPACITY];
+        uint8_t head;
+        uint8_t count;
+
+        struct AppEventSubscription* next;
+    } internal;
 };
 
 /**
- * Register a subscription for events addressed to @a sub->app_instance_id.
- * @warning Does not work in ISR context.
- * @param[in,out] sub subscription to register; caller sets @a sub->app_instance_id beforehand,
- * owns the storage, and must keep it alive (and stationary) until unsubscribed
- * @return ERROR_NONE on success
+ * Register a subscription for events addressed to the calling app's own instance (identified via
+ * app_scheduler_current_app_id()).
+ * @warning Does not work in ISR context. Must be called from the app's own task.
+ * @param[in,out] sub subscription to register; owns the storage, must stay alive (and
+ * stationary) until unsubscribed
+ * @param[in] event_group caller-owned group to wait on; must outlive @a sub (i.e. be
+ * destructed only after app_event_unsubscribe()). To block for an event, call
+ * task_event_group_wait()/task_event_group_wait_any() on this group (OR sub->bit into the mask,
+ * or use _wait_any() to include every subscription sharing it), then drain with app_event_poll().
+ * @retval ERROR_NONE on success
+ * @retval ERROR_RESOURCE @a event_group has no free bits left to claim; @a sub was not registered
+ * @retval ERROR_INVALID_STATE @a sub is already registered
  */
-error_t app_event_subscribe(struct AppEventSubscription* sub);
+error_t app_event_subscribe(struct AppEventSubscription* sub, struct TaskEventGroup* event_group);
+
+/**
+ * Same as app_event_subscribe(), but for a caller that isn't running on @a app_instance_id's own
+ * task (e.g. test code simulating multiple distinct app instances from one thread). Production
+ * app code should use app_event_subscribe() instead.
+ * @warning Does not work in ISR context.
+ * @param[in,out] sub subscription to register; owns the storage, must stay alive (and
+ * stationary) until unsubscribed
+ * @param[in] event_group caller-owned group to wait on; same contract as app_event_subscribe()
+ * @param[in] app_instance_id the app instance this subscription receives events for
+ * @retval ERROR_NONE on success
+ * @retval ERROR_RESOURCE @a event_group has no free bits left to claim; @a sub was not registered
+ * @retval ERROR_INVALID_STATE @a sub is already registered
+ */
+error_t app_event_subscribe_with_app_id(struct AppEventSubscription* sub, struct TaskEventGroup* event_group, AppInstanceId app_instance_id);
 
 /**
  * Remove a previously registered subscription.
@@ -94,11 +125,14 @@ error_t app_event_unsubscribe(struct AppEventSubscription* sub);
 error_t app_event_emit(AppInstanceId app_instance_id, const struct AppEvent* event);
 
 /**
- * Pop the next event for @a sub, blocking up to @a timeout if the queue is currently empty.
+ * Non-blocking: pop the next event for @a sub if one is already queued.
+ * @warning Never blocks. To wait for an event, block in task_event_group_wait()/
+ * task_event_group_wait_any() on @a sub's event group first (see app_event_subscribe()), then
+ * drain with this in a loop.
  * @retval ERROR_NONE @a out_event was filled
- * @retval ERROR_TIMEOUT no event arrived before the timeout elapsed
+ * @retval ERROR_TIMEOUT nothing queued right now
  */
-error_t app_event_await(struct AppEventSubscription* sub, struct AppEvent* out_event, TickType_t timeout);
+error_t app_event_poll(struct AppEventSubscription* sub, struct AppEvent* out_event);
 
 #ifdef __cplusplus
 }

Modules/app-module/include/app/loader.h

@@ -21,13 +21,13 @@ extern "C" {
 /**
  * Entry point signature for an APP_LOCATION_MEMORY app: a function linked directly into this
  * firmware binary. Called on the dedicated task app-module's scheduler spawns for this instance,
- * blocking for the app's whole lifetime - same contract as an external app's main(), plus
- * @a app_instance_id identifying this running instance (use it with
+ * blocking for the app's whole lifetime - same contract as an external app's main(). Use
+ * app_scheduler_current_app_id() to identify this running instance (e.g. with
  * app_event_subscribe()/window_manager_create()/etc.). The instance closes when this function
  * returns - no separate call is needed.
  * AppManifest::location.location holds this cast to void*.
  */
-typedef int32_t (*AppMainFn)(uint32_t app_instance_id, int argc, char* argv[]);
+typedef int32_t (*AppMainFn)(int argc, char* argv[]);
 
 typedef void* AppRuntime;
 

Modules/app-module/source/app_internal_loader.cpp

@@ -16,9 +16,9 @@ error_t api_load(AppLocation location, AppRuntime* out_runtime) {
     return ERROR_NONE;
 }
 
-int32_t api_run(AppRuntime runtime, uint32_t app_instance_id, int argc, char* argv[]) {
+int32_t api_run(AppRuntime runtime, uint32_t /*app_instance_id*/, int argc, char* argv[]) {
     auto entry = reinterpret_cast<AppMainFn>(runtime);
-    return entry(app_instance_id, argc, argv);
+    return entry(argc, argv);
 }
 
 void api_unload(AppRuntime /*unused*/) {

Modules/app-module/source/event.cpp

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 #include <app/event.h>
+#include <app/scheduler.h>
 
 #include <tactility/concurrent/mutex.h>
 #include <tactility/time.h>
@@ -7,7 +8,7 @@
 /**
  * Intrusive singly-linked list of subscriptions, keyed by app_instance_id.
  * Guarded by a single coarse-grained mutex, notifying a subscriber here never invokes caller code
- * (just a struct copy and an xTaskNotifyGive), so there is no reentrancy concern requiring a snapshot-then-unlock dance.
+ * (just a struct copy and a task_event_group_signal), so there is no reentrancy concern requiring a snapshot-then-unlock dance.
  */
 static AppEventSubscription* subscriptions = nullptr;
 
@@ -21,32 +22,55 @@ static AppEventMutex subscriptions_mutex;
 
 extern "C" {
 
-error_t app_event_subscribe(AppEventSubscription* sub) {
-    sub->task = xTaskGetCurrentTaskHandle();
-    sub->head = 0;
-    sub->count = 0;
+error_t app_event_subscribe_with_app_id(AppEventSubscription* sub, TaskEventGroup* event_group, AppInstanceId app_instance_id) {
+    uint32_t bit;
+    error_t claim_result = task_event_group_claim_bit(event_group, &bit);
+    if (claim_result != ERROR_NONE) {
+        return claim_result;
+    }
 
     mutex_lock(&subscriptions_mutex.handle);
-    sub->next = subscriptions;
+
+    // Avoid cyclic subscription list that would loop forever
+    if (subscriptions == sub) {
+        mutex_unlock(&subscriptions_mutex.handle);
+        task_event_group_release_bit(event_group, bit);
+        return ERROR_INVALID_STATE;
+    }
+
+    sub->bit = bit;
+    sub->internal.app_instance_id = app_instance_id;
+    sub->internal.event_group = event_group;
+    sub->internal.head = 0;
+    sub->internal.count = 0;
+    sub->internal.next = subscriptions;
     subscriptions = sub;
     mutex_unlock(&subscriptions_mutex.handle);
 
     return ERROR_NONE;
 }
 
+error_t app_event_subscribe(AppEventSubscription* sub, TaskEventGroup* event_group) {
+    return app_event_subscribe_with_app_id(sub, event_group, app_scheduler_current_app_id());
+}
+
 error_t app_event_unsubscribe(AppEventSubscription* sub) {
     error_t result = ERROR_NOT_FOUND;
 
     mutex_lock(&subscriptions_mutex.handle);
-    for (AppEventSubscription** link = &subscriptions; *link != nullptr; link = &(*link)->next) {
+    for (AppEventSubscription** link = &subscriptions; *link != nullptr; link = &(*link)->internal.next) {
         if (*link == sub) {
-            *link = sub->next;
+            *link = sub->internal.next;
             result = ERROR_NONE;
             break;
         }
     }
     mutex_unlock(&subscriptions_mutex.handle);
 
+    if (result == ERROR_NONE) {
+        task_event_group_release_bit(sub->internal.event_group, sub->bit);
+    }
+
     return result;
 }
 
@@ -57,23 +81,23 @@ error_t app_event_emit(AppInstanceId app_instance_id, const AppEvent* event) {
     error_t result = ERROR_NOT_FOUND;
 
     mutex_lock(&subscriptions_mutex.handle);
-    for (AppEventSubscription* sub = subscriptions; sub != nullptr; sub = sub->next) {
-        if (sub->app_instance_id != app_instance_id) {
+    for (AppEventSubscription* sub = subscriptions; sub != nullptr; sub = sub->internal.next) {
+        if (sub->internal.app_instance_id != app_instance_id) {
             continue;
         }
 
-        if (sub->count >= APP_EVENT_QUEUE_CAPACITY) {
+        if (sub->internal.count >= APP_EVENT_QUEUE_CAPACITY) {
             result = ERROR_RESOURCE;
             continue;
         }
 
-        uint8_t tail = (sub->head + sub->count) % APP_EVENT_QUEUE_CAPACITY;
-        sub->queue[tail] = stamped_event;
-        sub->count++;
+        uint8_t tail = (sub->internal.head + sub->internal.count) % APP_EVENT_QUEUE_CAPACITY;
+        sub->internal.queue[tail] = stamped_event;
+        sub->internal.count++;
         if (result != ERROR_RESOURCE) {
             result = ERROR_NONE;
         }
-        xTaskNotifyGive(sub->task);
+        task_event_group_signal(sub->internal.event_group, sub->bit);
     }
     mutex_unlock(&subscriptions_mutex.handle);
 
@@ -82,33 +106,17 @@ error_t app_event_emit(AppInstanceId app_instance_id, const AppEvent* event) {
 
 static bool try_pop(AppEventSubscription* sub, AppEvent* out_event) {
     mutex_lock(&subscriptions_mutex.handle);
-    bool has_event = sub->count > 0;
+    bool has_event = sub->internal.count > 0;
     if (has_event) {
-        *out_event = sub->queue[sub->head];
-        sub->head = (sub->head + 1) % APP_EVENT_QUEUE_CAPACITY;
-        sub->count--;
+        *out_event = sub->internal.queue[sub->internal.head];
+        sub->internal.head = (sub->internal.head + 1) % APP_EVENT_QUEUE_CAPACITY;
+        sub->internal.count--;
     }
     mutex_unlock(&subscriptions_mutex.handle);
     return has_event;
 }
 
-error_t app_event_await(AppEventSubscription* sub, AppEvent* out_event, TickType_t timeout) {
-    if (try_pop(sub, out_event)) {
-        // Drain any notification credit this (or an earlier) push accumulated on this task's
-        // FreeRTOS notification value: each app_event_emit() calls xTaskNotifyGive() regardless
-        // of whether the consumer takes this fast path or the blocking path below, so without
-        // this the credit would carry over and cause a future ulTaskNotifyTake() below to
-        // return immediately for a notification that was already accounted for here.
-        ulTaskNotifyTake(pdTRUE, 0);
-        return ERROR_NONE;
-    }
-
-    if (ulTaskNotifyTake(pdTRUE, timeout) == 0) {
-        return ERROR_TIMEOUT;
-    }
-
-    // Single-consumer by design (one task per subscription), so a wakeup implies the event
-    // this call was notified for is still there for us to pop.
+error_t app_event_poll(AppEventSubscription* sub, AppEvent* out_event) {
     return try_pop(sub, out_event) ? ERROR_NONE : ERROR_TIMEOUT;
 }
 

Modules/app-module/source/symbols.cpp

@@ -8,6 +8,7 @@
 
 #include <service/manager.h>
 
+#include <tactility/concurrent/task_event_group.h>
 #include <tactility/error.h>
 #include <tactility/module.h>
 
@@ -18,9 +19,10 @@ extern ServiceManifest app_internal_loader_service_manifest;
 const ModuleSymbol app_module_symbols[] = {
     // app/event
     DEFINE_MODULE_SYMBOL(app_event_subscribe),
+    DEFINE_MODULE_SYMBOL(app_event_subscribe_with_app_id),
     DEFINE_MODULE_SYMBOL(app_event_unsubscribe),
     DEFINE_MODULE_SYMBOL(app_event_emit),
-    DEFINE_MODULE_SYMBOL(app_event_await),
+    DEFINE_MODULE_SYMBOL(app_event_poll),
     // app/install
     DEFINE_MODULE_SYMBOL(app_get_install_path),
     DEFINE_MODULE_SYMBOL(app_install),

Modules/app-module/tests/source/app_event_test.cpp

@@ -6,10 +6,12 @@
 #include <tactility/delay.h>
 #include <tactility/time.h>
 
-TEST_CASE("app_event_subscribe/_await deliver events in FIFO order") {
+TEST_CASE("app_event_subscribe/_poll deliver events in FIFO order") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 1;
-    CHECK_EQ(app_event_subscribe(&sub), ERROR_NONE);
+    CHECK_EQ(app_event_subscribe_with_app_id(&sub, &event_group, 1), ERROR_NONE);
 
     for (uint32_t i = 0; i < 3; i++) {
         AppEvent event { .type = APP_EVENT_RESULT, .timestamp = 0, .result = { .launch_id = i, .result = 0 } };
@@ -18,32 +20,38 @@ TEST_CASE("app_event_subscribe/_await deliver events in FIFO order") {
 
     for (uint32_t i = 0; i < 3; i++) {
         AppEvent out {};
-        CHECK_EQ(app_event_await(&sub, &out, 0), ERROR_NONE);
+        CHECK_EQ(app_event_poll(&sub, &out), ERROR_NONE);
         CHECK_EQ(out.type, APP_EVENT_RESULT);
         CHECK_EQ(out.result.launch_id, i);
     }
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
 }
 
 TEST_CASE("app_event_emit only delivers to subscriptions for that app_instance_id") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 10;
-    app_event_subscribe(&sub);
+    app_event_subscribe_with_app_id(&sub, &event_group, 10);
 
     AppEvent event { .type = APP_EVENT_CLOSE, .timestamp = 0, .result = {} };
     CHECK_EQ(app_event_emit(11, &event), ERROR_NOT_FOUND);
 
     AppEvent out {};
-    CHECK_EQ(app_event_await(&sub, &out, 0), ERROR_TIMEOUT);
+    CHECK_EQ(app_event_poll(&sub, &out), ERROR_TIMEOUT);
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
 }
 
 TEST_CASE("app_event_emit returns ERROR_RESOURCE and drops the newest event once a subscription's queue is full") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 20;
-    app_event_subscribe(&sub);
+    app_event_subscribe_with_app_id(&sub, &event_group, 20);
 
     for (uint32_t i = 0; i < APP_EVENT_QUEUE_CAPACITY; i++) {
         AppEvent event { .type = APP_EVENT_RESULT, .timestamp = 0, .result = { .launch_id = i, .result = 0 } };
@@ -57,42 +65,52 @@ TEST_CASE("app_event_emit returns ERROR_RESOURCE and drops the newest event once
     // The already-queued events survive, in order, and the dropped one never arrives.
     for (uint32_t i = 0; i < APP_EVENT_QUEUE_CAPACITY; i++) {
         AppEvent out {};
-        CHECK_EQ(app_event_await(&sub, &out, 0), ERROR_NONE);
+        CHECK_EQ(app_event_poll(&sub, &out), ERROR_NONE);
         CHECK_EQ(out.result.launch_id, i);
     }
     AppEvent out {};
-    CHECK_EQ(app_event_await(&sub, &out, 0), ERROR_TIMEOUT);
+    CHECK_EQ(app_event_poll(&sub, &out), ERROR_TIMEOUT);
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
 }
 
 TEST_CASE("app_event_unsubscribe stops further delivery") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 30;
-    app_event_subscribe(&sub);
+    app_event_subscribe_with_app_id(&sub, &event_group, 30);
 
     CHECK_EQ(app_event_unsubscribe(&sub), ERROR_NONE);
     CHECK_EQ(app_event_unsubscribe(&sub), ERROR_NOT_FOUND);
 
     AppEvent event { .type = APP_EVENT_CLOSE, .timestamp = 0, .result = {} };
     CHECK_EQ(app_event_emit(30, &event), ERROR_NOT_FOUND);
+
+    task_event_group_destruct(&event_group);
 }
 
-TEST_CASE("app_event_await times out when no event has arrived") {
+TEST_CASE("app_event_poll times out when no event has arrived") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 40;
-    app_event_subscribe(&sub);
+    app_event_subscribe_with_app_id(&sub, &event_group, 40);
 
     AppEvent out {};
-    CHECK_EQ(app_event_await(&sub, &out, 0), ERROR_TIMEOUT);
+    CHECK_EQ(app_event_poll(&sub, &out), ERROR_TIMEOUT);
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
 }
 
 TEST_CASE("app_event_emit stamps the event with the current boot-relative time") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 50;
-    app_event_subscribe(&sub);
+    app_event_subscribe_with_app_id(&sub, &event_group, 50);
 
     auto before = static_cast<uint64_t>(get_micros_since_boot());
     AppEvent event { .type = APP_EVENT_CLOSE, .timestamp = 0, .result = {} };
@@ -100,17 +118,20 @@ TEST_CASE("app_event_emit stamps the event with the current boot-relative time")
     auto after = static_cast<uint64_t>(get_micros_since_boot());
 
     AppEvent out {};
-    REQUIRE_EQ(app_event_await(&sub, &out, 0), ERROR_NONE);
+    REQUIRE_EQ(app_event_poll(&sub, &out), ERROR_NONE);
     CHECK_GE(out.timestamp, before);
     CHECK_LE(out.timestamp, after);
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
 }
 
-TEST_CASE("app_event_await wakes when the event is emitted from another task") {
+TEST_CASE("task_event_group_wait wakes when the event is emitted from another task") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = 60;
-    CHECK_EQ(app_event_subscribe(&sub), ERROR_NONE);
+    CHECK_EQ(app_event_subscribe_with_app_id(&sub, &event_group, 60), ERROR_NONE);
 
     auto* thread = thread_alloc_full(
         "app-event-emitter",
@@ -126,12 +147,14 @@ TEST_CASE("app_event_await wakes when the event is emitted from another task") {
     );
     CHECK_EQ(thread_start(thread), ERROR_NONE);
 
+    CHECK_EQ(task_event_group_wait(&event_group, sub.bit, false, nullptr, pdMS_TO_TICKS(2000)), ERROR_NONE);
     AppEvent out {};
-    CHECK_EQ(app_event_await(&sub, &out, pdMS_TO_TICKS(2000)), ERROR_NONE);
+    CHECK_EQ(app_event_poll(&sub, &out), ERROR_NONE);
     CHECK_EQ(out.type, APP_EVENT_CLOSE);
 
     CHECK_EQ(thread_join(thread, pdMS_TO_TICKS(2000), 1), ERROR_NONE);
     thread_free(thread);
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
 }

Modules/app-module/tests/source/app_manager_test.cpp

@@ -3,6 +3,7 @@
 #include <app/event.h>
 #include <app/loader.h>
 #include <app/manager.h>
+#include <app/scheduler.h>
 
 #include <service/manager.h>
 
@@ -55,7 +56,7 @@ void stash_received_arguments(int argc, char* argv[]) {
 // parameter (app_manager_start_for_result()), acts as a modal dialog instead: returns the
 // requested result (argv[0], parsed as an int) immediately (the app's own return value IS the
 // delivered APP_EVENT_RESULT.result - see app_scheduler.cpp's thread_main()).
-int32_t fake_run(void*, uint32_t app_instance_id, int argc, char* argv[]) {
+int32_t fake_run(void*, uint32_t /*app_instance_id*/, int argc, char* argv[]) {
     stash_received_arguments(argc, argv);
 
     if (argc == 1) {
@@ -66,21 +67,30 @@ int32_t fake_run(void*, uint32_t app_instance_id, int argc, char* argv[]) {
         return static_cast<int32_t>(strtol(argv[0], nullptr, 10));
     }
 
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
     AppEventSubscription sub {};
-    sub.app_instance_id = app_instance_id;
-    app_event_subscribe(&sub);
+    app_event_subscribe(&sub, &event_group);
 
     while (true) {
-        AppEvent event {};
-        if (app_event_await(&sub, &event, pdMS_TO_TICKS(5000)) != ERROR_NONE) {
+        if (task_event_group_wait_any(&event_group, nullptr, pdMS_TO_TICKS(5000)) != ERROR_NONE) {
             break; // safety net so a bug here can't hang the test suite
         }
-        if (event.type == APP_EVENT_CLOSE) {
-            break;
+
+        bool done = false;
+        AppEvent event {};
+        while (app_event_poll(&sub, &event) == ERROR_NONE) {
+            if (event.type == APP_EVENT_CLOSE) {
+                done = true;
+                break;
+            }
         }
+        if (done) break;
     }
 
     app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
     return 0;
 }
 
@@ -129,8 +139,8 @@ void ensure_memory_loader_registered() {
 
 // Same subscribe-until-close contract as fake_run() above, but called directly as an AppMainFn -
 // this is what a real internal app's entry point looks like.
-int32_t fake_app_main(uint32_t app_instance_id, int argc, char* argv[]) {
-    return fake_run(nullptr, app_instance_id, argc, argv);
+int32_t fake_app_main(int argc, char* argv[]) {
+    return fake_run(nullptr, app_scheduler_current_app_id(), argc, argv);
 }
 
 // Wraps app_manager_get_topmost_instance_id() for terse assertions: 0 if no app is Active.
@@ -329,9 +339,11 @@ TEST_CASE("app_manager_start_for_result delivers APP_EVENT_RESULT to the parent,
     REQUIRE_EQ(app_manager_start("test.app.parent", &parent_id), ERROR_NONE);
     CHECK(wait_for_state(parent_id, APP_INSTANCE_STATE_ACTIVE, 1000));
 
+    TaskEventGroup parent_event_group {};
+    task_event_group_construct(&parent_event_group);
+
     AppEventSubscription parent_sub {};
-    parent_sub.app_instance_id = parent_id;
-    REQUIRE_EQ(app_event_subscribe(&parent_sub), ERROR_NONE);
+    REQUIRE_EQ(app_event_subscribe_with_app_id(&parent_sub, &parent_event_group, parent_id), ERROR_NONE);
 
     const char* argv[] = { "42" };
     uint32_t child_id = 0;
@@ -340,13 +352,15 @@ TEST_CASE("app_manager_start_for_result delivers APP_EVENT_RESULT to the parent,
     // Launching a modal child never touches the parent's own task/state.
     CHECK_EQ(app_manager_get_state(parent_id), APP_INSTANCE_STATE_ACTIVE);
 
+    REQUIRE_EQ(task_event_group_wait(&parent_event_group, parent_sub.bit, false, nullptr, pdMS_TO_TICKS(2000)), ERROR_NONE);
     AppEvent event {};
-    REQUIRE_EQ(app_event_await(&parent_sub, &event, pdMS_TO_TICKS(2000)), ERROR_NONE);
+    REQUIRE_EQ(app_event_poll(&parent_sub, &event), ERROR_NONE);
     CHECK_EQ(event.type, APP_EVENT_RESULT);
     CHECK_EQ(event.result.launch_id, child_id);
     CHECK_EQ(event.result.result, 42);
 
     app_event_unsubscribe(&parent_sub);
+    task_event_group_destruct(&parent_event_group);
     app_manager_stop(child_id);
     app_manager_stop(parent_id);
     app_manager_remove("test.app.parent");
@@ -365,9 +379,11 @@ TEST_CASE("app_manager_start_for_result delivers the child's own return value as
     REQUIRE_EQ(app_manager_start("test.app.parent2", &parent_id), ERROR_NONE);
     CHECK(wait_for_state(parent_id, APP_INSTANCE_STATE_ACTIVE, 1000));
 
+    TaskEventGroup parent_event_group {};
+    task_event_group_construct(&parent_event_group);
+
     AppEventSubscription parent_sub {};
-    parent_sub.app_instance_id = parent_id;
-    REQUIRE_EQ(app_event_subscribe(&parent_sub), ERROR_NONE);
+    REQUIRE_EQ(app_event_subscribe_with_app_id(&parent_sub, &parent_event_group, parent_id), ERROR_NONE);
 
     uint32_t child_id = 0;
     // No parameters - fake_run falls through to its normal CLOSE loop instead of acting as a
@@ -377,13 +393,15 @@ TEST_CASE("app_manager_start_for_result delivers the child's own return value as
 
     app_manager_stop(child_id); // force-close
 
+    REQUIRE_EQ(task_event_group_wait(&parent_event_group, parent_sub.bit, false, nullptr, pdMS_TO_TICKS(2000)), ERROR_NONE);
     AppEvent event {};
-    REQUIRE_EQ(app_event_await(&parent_sub, &event, pdMS_TO_TICKS(2000)), ERROR_NONE);
+    REQUIRE_EQ(app_event_poll(&parent_sub, &event), ERROR_NONE);
     CHECK_EQ(event.type, APP_EVENT_RESULT);
     CHECK_EQ(event.result.launch_id, child_id);
     CHECK_EQ(event.result.result, 0); // fake_run's CLOSE loop always returns 0
 
     app_event_unsubscribe(&parent_sub);
+    task_event_group_destruct(&parent_event_group);
     app_manager_stop(parent_id);
     app_manager_remove("test.app.parent2");
     app_manager_remove("test.app.child2");

Modules/app-module/tests/source/combined_event_test.cpp

@@ -0,0 +1,71 @@
+#include "doctest.h"
+
+#include <app/event.h>
+
+#include <tactility/system_event.h>
+
+// Regression coverage for the primary motivation behind TaskEventGroup: a task subscribed to
+// both an app_event and a system_event must be able to block once and wake for either, without
+// losing an event or regressing either subsystem's own delivery semantics (FIFO for app_event,
+// coalescing for system_event).
+
+TEST_CASE("a task can wait on app_event and system_event together via one TaskEventGroup") {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    AppEventSubscription app_sub {};
+    CHECK_EQ(app_event_subscribe_with_app_id(&app_sub, &event_group, 100), ERROR_NONE);
+
+    SystemEventSubscription sys_sub {};
+    sys_sub.event.type = KERNEL_EVENT_BOOT_COMPLETED;
+    CHECK_EQ(system_event_subscribe(&sys_sub, &event_group), ERROR_NONE);
+
+    // Distinct bits, so a combined wait can tell (via out_flags) which source(s) fired.
+    CHECK_NE(app_sub.bit, sys_sub.bit);
+
+    uint32_t both_bits = app_sub.bit | sys_sub.bit;
+
+    // Only app_event fires: combined wait matches just that bit, and only app_event_poll()
+    // finds something to pop.
+    AppEvent emitted { .type = APP_EVENT_CLOSE, .timestamp = 0, .result = {} };
+    CHECK_EQ(app_event_emit(100, &emitted), ERROR_NONE);
+
+    uint32_t out_flags = 0;
+    CHECK_EQ(task_event_group_wait(&event_group, both_bits, false, &out_flags, 0), ERROR_NONE);
+    CHECK_EQ(out_flags, app_sub.bit);
+
+    AppEvent app_out {};
+    CHECK_EQ(app_event_poll(&app_sub, &app_out), ERROR_NONE);
+    CHECK_EQ(app_out.type, APP_EVENT_CLOSE);
+    CHECK_EQ(system_event_poll(&sys_sub), ERROR_TIMEOUT);
+
+    // Only system_event fires: combined wait matches just that bit, and only
+    // system_event_poll() finds something pending.
+    CHECK_EQ(system_event_emit(KERNEL_EVENT_BOOT_COMPLETED, nullptr, 0), ERROR_NONE);
+
+    out_flags = 0;
+    CHECK_EQ(task_event_group_wait(&event_group, both_bits, false, &out_flags, 0), ERROR_NONE);
+    CHECK_EQ(out_flags, sys_sub.bit);
+
+    CHECK_EQ(system_event_poll(&sys_sub), ERROR_NONE);
+    AppEvent app_out2 {};
+    CHECK_EQ(app_event_poll(&app_sub, &app_out2), ERROR_TIMEOUT);
+
+    // Both fire before the wait: combined wait matches both bits, and both subsystems' own
+    // polls (which re-check their own state rather than trusting the bit) still deliver.
+    CHECK_EQ(app_event_emit(100, &emitted), ERROR_NONE);
+    CHECK_EQ(system_event_emit(KERNEL_EVENT_BOOT_COMPLETED, nullptr, 0), ERROR_NONE);
+
+    out_flags = 0;
+    CHECK_EQ(task_event_group_wait(&event_group, both_bits, false, &out_flags, 0), ERROR_NONE);
+    CHECK_EQ(out_flags, both_bits);
+
+    CHECK_EQ(app_event_poll(&app_sub, &app_out), ERROR_NONE);
+    CHECK_EQ(system_event_poll(&sys_sub), ERROR_NONE);
+
+    // Unsubscribe order (system_event before app_event) must not matter - the group outlives
+    // both and is destructed last.
+    system_event_unsubscribe(&sys_sub);
+    app_event_unsubscribe(&app_sub);
+    task_event_group_destruct(&event_group);
+}