fix(app): force WS reconnect on app-foreground (B10 recovery path)

Author: leduckhc

app/lib/main.dart

@@ -9,6 +9,7 @@ import 'app/router.dart';
 import 'app/theme.dart';
 import 'app/test_bootstrap.dart';
 import 'notifications/notification_observer.dart';
+import 'store/connection.dart';
 import 'store/store.dart';
 import 'ui/widgets/pino_mark.dart';
 import 'ui/widgets/srv_request_handler.dart';
@@ -47,9 +48,32 @@ class PinoApp extends ConsumerStatefulWidget {
   ConsumerState<PinoApp> createState() => _PinoAppState();
 }
 
-class _PinoAppState extends ConsumerState<PinoApp> {
+class _PinoAppState extends ConsumerState<PinoApp>
+    with WidgetsBindingObserver {
   bool _showSplash = true;
 
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addObserver(this);
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    super.dispose();
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    // On foreground, nudge a stalled WS connection to reconnect immediately
+    // instead of waiting out backoff (iOS suspends sockets/timers in the
+    // background). No-op when already connected.
+    if (state == AppLifecycleState.resumed) {
+      ref.read(connectionControllerProvider.notifier).onAppResumed();
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
     if (_showSplash) {

app/lib/store/connection.dart

@@ -138,6 +138,17 @@ class ConnectionController extends StateNotifier<PinoConnState> {
     send(Envelope(t: MsgType.srvResponse, id: requestId, body: body));
   }
 
+  /// Called when the app returns to the foreground. iOS suspends sockets and
+  /// backoff timers while backgrounded, so a stalled connection can otherwise
+  /// sit in "reconnecting" for a full backoff interval (up to ~30s) after
+  /// resume. Nudge the transport to reconnect immediately — but only when we
+  /// aren't already connected, so a healthy socket isn't needlessly dropped.
+  void onAppResumed() {
+    if (state.wsState != WsState.connected) {
+      _ws?.forceReconnect();
+    }
+  }
+
   Future<void> _boot() async {
     if (_wsUrl.isNotEmpty) {
       // Dev override: connect directly, no pairing.

app/lib/transport/transport.dart

@@ -29,4 +29,10 @@ abstract class Transport {
 
   /// Send an envelope, preserving its caller-supplied id.
   void sendEnvelope(Envelope env);
+
+  /// Force an immediate reconnect: cancel any pending backoff, reset attempt
+  /// counters, tear down a stale socket, and open a fresh connection now.
+  /// No-op if the transport was never connected. Called on app-foreground so
+  /// a stalled connection recovers instantly instead of waiting out backoff.
+  void forceReconnect();
 }

app/lib/transport/ws_client.dart

@@ -99,6 +99,24 @@ class WsClient implements Transport {
     _send(env);
   }
 
+  /// Force an immediate reconnect (e.g. on app-foreground). Cancels pending
+  /// backoff, resets the attempt counter, tears down any stale channel, and
+  /// opens a fresh connection right away. No-op if never connected.
+  @override
+  void forceReconnect() {
+    if (_url == null) return;
+    _retry?.cancel();
+    _pinger?.cancel();
+    _attempt = 0;
+    unawaited(_sub?.cancel());
+    _sub = null;
+    try {
+      unawaited(_ch?.sink.close());
+    } catch (_) {}
+    _ch = null;
+    unawaited(_open());
+  }
+
   // ---- internals -----------------------------------------------------------
 
   void _setState(WsState s) {

app/test/connection_controller_test.dart

@@ -56,6 +56,13 @@ class FakeTransport implements Transport {
 
   @override
   void sendEnvelope(Envelope env) {}
+
+  int forceReconnectCount = 0;
+  @override
+  void forceReconnect() {
+    forceReconnectCount++;
+    if (emitConnected) _state.add(WsState.connected);
+  }
 }
 
 /// In-memory [FlutterSecureStorage] so the controller can persist without the
@@ -229,4 +236,54 @@ void main() {
       },
     );
   });
+
+  group('ConnectionController app-lifecycle reconnect (B10)', () {
+    test('onAppResumed forces an immediate transport reconnect when not connected', () async {
+      final storage = _seededStorage();
+      final transports = <FakeTransport>[];
+      final controller = ConnectionController(
+        storage,
+        // Never emits connected → controller stays in connecting/reconnecting.
+        transportFactory: () {
+          final t = FakeTransport();
+          transports.add(t);
+          return t;
+        },
+        browseLan: _fixedBrowse(const []),
+        rediscoverStall: const Duration(seconds: 30),
+      );
+      await Future<void>.delayed(Duration.zero);
+      expect(transports, hasLength(1));
+      expect(transports[0].forceReconnectCount, 0);
+
+      controller.onAppResumed();
+
+      expect(transports[0].forceReconnectCount, 1,
+          reason: 'foreground should nudge a stalled connection to retry now');
+      controller.dispose();
+    });
+
+    test('onAppResumed does NOT force a reconnect while already connected', () async {
+      final storage = _seededStorage();
+      final transports = <FakeTransport>[];
+      final controller = ConnectionController(
+        storage,
+        transportFactory: () {
+          final t = FakeTransport(emitConnected: true); // healthy connection
+          transports.add(t);
+          return t;
+        },
+        browseLan: _fixedBrowse(const []),
+        rediscoverStall: const Duration(seconds: 30),
+      );
+      await Future<void>.delayed(Duration.zero);
+      expect(transports, hasLength(1));
+
+      controller.onAppResumed();
+
+      expect(transports[0].forceReconnectCount, 0,
+          reason: 'a healthy socket must not be dropped on every foreground');
+      controller.dispose();
+    });
+  });
 }