Add Bugs.CheckNativeStatus diagnostics ping for the mobile app

Adds an open Bugs.CheckNativeStatus RPC that logs an append-only row to a new
logging.native_diagnostics table (app/build, OTA bundle, push state, device
info, time since last open) and returns a CheckNativeStatusRes the client can
use to drive a force-update flow. The mobile app pings on cold start and on
each background→foreground transition, throttled to once per 30 minutes.

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

Author: aapeliv

app/backend/src/couchers/migrations/versions/0158_add_native_diagnostics_table.py

@@ -0,0 +1,72 @@
+"""Add native_diagnostics table
+
+Revision ID: 0158
+Revises: 0157
+Create Date: 2026-05-27 00:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "0158"
+down_revision = "0157"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "native_diagnostics",
+        sa.Column("id", sa.BigInteger(), nullable=False),
+        sa.Column("created", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("occurred", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("install_id", sa.String(), nullable=True),
+        sa.Column("idfv", sa.String(), nullable=True),
+        sa.Column("android_id", sa.String(), nullable=True),
+        sa.Column("user_id", sa.BigInteger(), nullable=True),
+        sa.Column("sofa", sa.String(), nullable=True),
+        sa.Column("user_state", sa.String(), nullable=True),
+        sa.Column("app_version", sa.String(), nullable=True),
+        sa.Column("git_hash", sa.String(), nullable=True),
+        sa.Column("native_build", sa.String(), nullable=True),
+        sa.Column("platform", sa.String(), nullable=True),
+        sa.Column("os_version", sa.String(), nullable=True),
+        sa.Column("device_name", sa.String(), nullable=True),
+        sa.Column("locale", sa.String(), nullable=True),
+        sa.Column("ota_update_id", sa.String(), nullable=True),
+        sa.Column("runtime_version", sa.String(), nullable=True),
+        sa.Column("ota_channel", sa.String(), nullable=True),
+        sa.Column("is_embedded", sa.Boolean(), nullable=True),
+        sa.Column("ota_created_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("push_permission", sa.String(), nullable=True),
+        sa.Column("push_token", sa.String(), nullable=True),
+        sa.Column("time_since_last_open_seconds", sa.Float(), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_native_diagnostics")),
+        schema="logging",
+    )
+    op.create_index(
+        "ix_logging_native_diagnostics_created", "native_diagnostics", ["created"], unique=False, schema="logging"
+    )
+    op.create_index(
+        "ix_logging_native_diagnostics_install_id_created",
+        "native_diagnostics",
+        ["install_id", "created"],
+        unique=False,
+        schema="logging",
+    )
+    op.create_index(
+        "ix_logging_native_diagnostics_user_id_created",
+        "native_diagnostics",
+        ["user_id", "created"],
+        unique=False,
+        schema="logging",
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_logging_native_diagnostics_user_id_created", table_name="native_diagnostics", schema="logging")
+    op.drop_index("ix_logging_native_diagnostics_install_id_created", table_name="native_diagnostics", schema="logging")
+    op.drop_index("ix_logging_native_diagnostics_created", table_name="native_diagnostics", schema="logging")
+    op.drop_table("native_diagnostics", schema="logging")

app/backend/src/couchers/models/logging.py

@@ -186,3 +186,66 @@ class FeatureUsage(Base, kw_only=True):
         Index("ix_logging_feature_usage_user_id_time", "user_id", "time"),
         {"schema": "logging"},
     )
+
+
+class NativeDiagnostics(Base, kw_only=True):
+    """
+    Append-only diagnostics pings from the native mobile apps.
+
+    One row per ping (typically emitted on app open / foreground). Lets us see which app versions
+    and OTA bundles are in the wild, push registration state, last-seen times, etc. Distinct from
+    the generic event_log; this has structured columns so it can be queried directly.
+    """
+
+    __tablename__ = "native_diagnostics"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, init=False)
+
+    # when the row was inserted into the DB
+    created: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), init=False)
+
+    # when the ping was generated client-side (may lag created if the app was offline)
+    occurred: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    # stable-ish device identifiers (see proto for semantics)
+    install_id: Mapped[str | None] = mapped_column(String, default=None)
+    idfv: Mapped[str | None] = mapped_column(String, default=None)
+    android_id: Mapped[str | None] = mapped_column(String, default=None)
+
+    # session context, pulled server-side from the request
+    user_id: Mapped[int | None] = mapped_column(BigInteger, default=None)
+    sofa: Mapped[str | None] = mapped_column(String, default=None)
+    # client's view of its auth state: "logged_out" or "authenticated"
+    user_state: Mapped[str | None] = mapped_column(String, default=None)
+
+    # app/build identity
+    app_version: Mapped[str | None] = mapped_column(String, default=None)
+    git_hash: Mapped[str | None] = mapped_column(String, default=None)
+    native_build: Mapped[str | None] = mapped_column(String, default=None)
+
+    # platform/device
+    platform: Mapped[str | None] = mapped_column(String, default=None)
+    os_version: Mapped[str | None] = mapped_column(String, default=None)
+    device_name: Mapped[str | None] = mapped_column(String, default=None)
+    locale: Mapped[str | None] = mapped_column(String, default=None)
+
+    # OTA / expo-updates state
+    ota_update_id: Mapped[str | None] = mapped_column(String, default=None)
+    runtime_version: Mapped[str | None] = mapped_column(String, default=None)
+    ota_channel: Mapped[str | None] = mapped_column(String, default=None)
+    is_embedded: Mapped[bool | None] = mapped_column(Boolean, default=None)
+    ota_created_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), default=None)
+
+    # push state; push_token lets us correlate reachability with delivery receipts
+    push_permission: Mapped[str | None] = mapped_column(String, default=None)
+    push_token: Mapped[str | None] = mapped_column(String, default=None)
+
+    # seconds since the app was last opened (null on a fresh install / first open)
+    time_since_last_open_seconds: Mapped[float | None] = mapped_column(Float, default=None)
+
+    __table_args__ = (
+        Index("ix_logging_native_diagnostics_created", "created"),
+        Index("ix_logging_native_diagnostics_install_id_created", "install_id", "created"),
+        Index("ix_logging_native_diagnostics_user_id_created", "user_id", "created"),
+        {"schema": "logging"},
+    )

app/backend/src/couchers/servicers/bugs.py

@@ -16,7 +16,7 @@
 from couchers.context import CouchersContext
 from couchers.descriptor_pool import get_descriptors_pb
 from couchers.models import User
-from couchers.models.logging import EventLog, EventSource
+from couchers.models.logging import EventLog, EventSource, NativeDiagnostics
 from couchers.proto import bugs_pb2, bugs_pb2_grpc
 from couchers.proto.google.api import httpbody_pb2
 
@@ -190,6 +190,50 @@ def ReportDiagnostics(
 
         return empty_pb2.Empty()
 
+    def CheckNativeStatus(
+        self, request: bugs_pb2.CheckNativeStatusReq, context: CouchersContext, session: Session
+    ) -> bugs_pb2.CheckNativeStatusRes:
+        occurred = request.occurred.ToDatetime(tzinfo=UTC) if request.HasField("occurred") else datetime.now(UTC)
+        ota_created_at = request.ota_created_at.ToDatetime(tzinfo=UTC) if request.HasField("ota_created_at") else None
+
+        session.add(
+            NativeDiagnostics(
+                occurred=occurred,
+                install_id=request.install_id or None,
+                idfv=request.idfv or None,
+                android_id=request.android_id or None,
+                user_id=context._user_id,
+                sofa=context._sofa,
+                user_state=request.user_state or None,
+                app_version=request.app_version or None,
+                git_hash=request.git_hash or None,
+                native_build=request.native_build or None,
+                platform=request.platform or None,
+                os_version=request.os_version or None,
+                device_name=request.device_name or None,
+                locale=request.locale or None,
+                ota_update_id=request.ota_update_id or None,
+                runtime_version=request.runtime_version or None,
+                ota_channel=request.ota_channel or None,
+                is_embedded=request.is_embedded,
+                ota_created_at=ota_created_at,
+                push_permission=request.push_permission or None,
+                push_token=request.push_token or None,
+                time_since_last_open_seconds=(
+                    request.time_since_last_open_seconds if request.HasField("time_since_last_open_seconds") else None
+                ),
+            )
+        )
+
+        # TODO: decide based on platform/app_version/native_build whether this client is below a
+        # minimum supported version and should be force-updated.
+        return bugs_pb2.CheckNativeStatusRes(
+            update_required=False,
+            update_available=False,
+            update_url="",
+            update_message="",
+        )
+
     def GeolocationSearchInfo(
         self, request: bugs_pb2.GeolocationSearchInfoReq, context: CouchersContext, session: Session
     ) -> empty_pb2.Empty:

app/backend/src/tests/test_bugs.py

@@ -10,7 +10,7 @@
 from couchers.config import config
 from couchers.crypto import random_hex
 from couchers.db import session_scope
-from couchers.models.logging import EventLog, EventSource
+from couchers.models.logging import EventLog, EventSource, NativeDiagnostics
 from couchers.proto import bugs_pb2
 from couchers.proto.google.api import httpbody_pb2
 from tests.fixtures.db import generate_user
@@ -395,6 +395,109 @@ def test_report_diagnostics_frontend_version(db):
         assert events[0].version == "abc-def-123"
 
 
+def _get_native_diagnostics(session):
+    return session.execute(select(NativeDiagnostics).order_by(NativeDiagnostics.id)).scalars().all()
+
+
+def test_check_native_status_anonymous(db):
+    with bugs_session() as bugs:
+        res = bugs.CheckNativeStatus(
+            bugs_pb2.CheckNativeStatusReq(
+                install_id="abc-123",
+                idfv="idfv-1",
+                user_state="logged_out",
+                app_version="1.1.20",
+                git_hash="deadbeef",
+                native_build="42",
+                platform="ios",
+                os_version="17.4",
+                device_name="Test iPhone",
+                locale="en",
+                ota_update_id="ota-1",
+                runtime_version="rt-1",
+                ota_channel="production",
+                is_embedded=False,
+                push_permission="granted",
+                push_token="ExpoToken[xyz]",
+            )
+        )
+
+    # Force-update decision logic isn't wired yet; for now the response is always permissive.
+    assert res.update_required is False
+    assert res.update_available is False
+    assert res.update_url == ""
+    assert res.update_message == ""
+
+    with session_scope() as session:
+        rows = _get_native_diagnostics(session)
+        assert len(rows) == 1
+        row = rows[0]
+        assert row.install_id == "abc-123"
+        assert row.idfv == "idfv-1"
+        assert row.android_id is None
+        assert row.user_id is None
+        assert row.user_state == "logged_out"
+        assert row.app_version == "1.1.20"
+        assert row.git_hash == "deadbeef"
+        assert row.native_build == "42"
+        assert row.platform == "ios"
+        assert row.os_version == "17.4"
+        assert row.device_name == "Test iPhone"
+        assert row.ota_update_id == "ota-1"
+        assert row.runtime_version == "rt-1"
+        assert row.ota_channel == "production"
+        assert row.is_embedded is False
+        assert row.push_permission == "granted"
+        assert row.push_token == "ExpoToken[xyz]"
+        assert row.time_since_last_open_seconds is None
+
+
+def test_check_native_status_authenticated(db):
+    user, token = generate_user()
+
+    with bugs_session(token) as bugs:
+        bugs.CheckNativeStatus(
+            bugs_pb2.CheckNativeStatusReq(
+                install_id="abc-123",
+                user_state="authenticated",
+                platform="android",
+                android_id="ssaid-1",
+                time_since_last_open_seconds=3600.0,
+            )
+        )
+
+    with session_scope() as session:
+        rows = _get_native_diagnostics(session)
+        assert len(rows) == 1
+        assert rows[0].user_id == user.id
+        assert rows[0].user_state == "authenticated"
+        assert rows[0].platform == "android"
+        assert rows[0].android_id == "ssaid-1"
+        assert rows[0].time_since_last_open_seconds == pytest.approx(3600.0)
+
+
+def test_check_native_status_occurred_and_ota_created_at(db):
+    occurred = timestamp_pb2.Timestamp()
+    occurred.FromDatetime(datetime(2026, 1, 15, 10, 30, 0, tzinfo=UTC))
+    ota_created = timestamp_pb2.Timestamp()
+    ota_created.FromDatetime(datetime(2026, 1, 10, 8, 0, 0, tzinfo=UTC))
+
+    with bugs_session() as bugs:
+        bugs.CheckNativeStatus(
+            bugs_pb2.CheckNativeStatusReq(
+                install_id="abc-123",
+                occurred=occurred,
+                ota_created_at=ota_created,
+            )
+        )
+
+    with session_scope() as session:
+        rows = _get_native_diagnostics(session)
+        assert len(rows) == 1
+        assert rows[0].occurred == datetime(2026, 1, 15, 10, 30, 0, tzinfo=UTC)
+        assert rows[0].ota_created_at == datetime(2026, 1, 10, 8, 0, 0, tzinfo=UTC)
+
+
 def _multipart_part_json(body, name):
     """Extract and parse the JSON body of a named part from a multipart/mixed body."""
     marker = f'name="{name}"'

app/mobile/app/_layout.tsx

@@ -28,6 +28,7 @@ import { SafeAreaProvider } from "react-native-safe-area-context";
 import DevSettingsButton from "@/components/DevSettingsButton";
 import { hydrateUrlOverrides } from "@/config/urls";
 import { AuthProvider, useAuthContext } from "@/features/auth/AuthContext";
+import { useNativeDiagnostics } from "@/features/diagnostics/useNativeDiagnostics";
 import { useRegisterPushNotifications } from "@/features/notifications/useRegisterPushNotifications";
 import { reconfigureApiClient } from "@/service/client";
 import { getNotificationPath } from "@/utils/getNotificationPath";
@@ -203,5 +204,6 @@ function useNotificationObserver() {
 function PushNotificationsRegistrar() {
   useRegisterPushNotifications();
   useNotificationObserver();
+  useNativeDiagnostics();
   return null;
 }

app/mobile/features/diagnostics/installId.ts

@@ -0,0 +1,49 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import * as Application from "expo-application";
+import { Platform } from "react-native";
+
+// A UUID we generate and persist on first launch. It's the primary key for a device install in the
+// diagnostics pipeline. It survives app restarts and OTA updates, but resets on reinstall (the
+// platform identifiers below cover cross-install correlation where the OS allows it).
+const INSTALL_ID_KEY = "diagnostics.installId";
+
+function uuidv4(): string {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export async function getInstallId(): Promise<string> {
+  const existing = await AsyncStorage.getItem(INSTALL_ID_KEY);
+  if (existing) {
+    return existing;
+  }
+  const id = uuidv4();
+  await AsyncStorage.setItem(INSTALL_ID_KEY, id);
+  return id;
+}
+
+// Best-effort platform identifiers reported alongside install_id for cross-install correlation.
+// - iOS: identifierForVendor persists across reinstall only while another app from our Apple Team
+//   is installed; otherwise it regenerates.
+// - Android: ANDROID_ID (SSAID) is stable across reinstalls of apps signed with the same key and
+//   resets only on factory reset.
+export async function getPlatformDeviceIds(): Promise<{
+  idfv?: string;
+  androidId?: string;
+}> {
+  try {
+    if (Platform.OS === "ios") {
+      const idfv = await Application.getIosIdForVendorAsync();
+      return { idfv: idfv ?? undefined };
+    }
+    if (Platform.OS === "android") {
+      return { androidId: Application.getAndroidId() ?? undefined };
+    }
+  } catch {
+    // Identifiers are best-effort; never block a diagnostics ping on them.
+  }
+  return {};
+}

app/mobile/features/diagnostics/pushTokenStore.ts

@@ -0,0 +1,14 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+// The last Expo push token we successfully registered with the backend. Persisted so the
+// diagnostics ping can report it (letting the backend correlate push reachability with delivery
+// receipts) without re-fetching a token on every app open.
+const PUSH_TOKEN_KEY = "diagnostics.pushToken";
+
+export async function setStoredPushToken(token: string): Promise<void> {
+  await AsyncStorage.setItem(PUSH_TOKEN_KEY, token);
+}
+
+export async function getStoredPushToken(): Promise<string | null> {
+  return AsyncStorage.getItem(PUSH_TOKEN_KEY);
+}