@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/interfaces/android/app/src/main/java/dev/agentprojectcontext/apx/ProximityNotification.java

@@ -0,0 +1,161 @@
+package dev.agentprojectcontext.apx;
+
+import android.app.Notification;
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.content.Context;
+import android.content.Intent;
+
+import androidx.core.app.NotificationCompat;
+
+/**
+ * The proximity card on the PHONE: "you are 1.4 km from Farmacia del Puente,
+ * Av. San Martín 1234 — Comprar ibuprofeno", and four buttons.
+ *
+ * WHY THIS IS NOT A CarMessageNotification. That one is a MessagingStyle
+ * conversation, and Android Auto only ever renders two controls on those —
+ * reply and mark-as-read. Four answers do not fit in a shape built for a chat.
+ * On the head unit the same alert is drawn by ApxCarAppService, which uses the
+ * Car App Library and can show all four; this class is the phone's copy.
+ *
+ * NOTHING HERE ADDS A GLYPH. The daemon sends the text already stripped
+ * (core/mobility/geofence.js) because Assistant reads it out loud, and
+ * decorating it here would put the emoji straight back into the sentence.
+ *
+ * ONE CARD PER ALERT, keyed by the alert id: two errands can come into range
+ * on the same GPS sample, and collapsing them into one notification would lose
+ * one of the two answers.
+ */
+final class ProximityNotification {
+    /**
+     * v2 because a channel is IMMUTABLE once created: createNotificationChannel
+     * on an existing id updates the name and description and silently ignores
+     * importance, sound and vibration. The v1 channel shipped soundless and
+     * therefore non-alerting, so fixing it in place would have changed nothing
+     * on any phone that had already run the app.
+     */
+    static final String CHANNEL = "apx_proximity_v2";
+    static final String ACTION_ANSWER = "dev.agentprojectcontext.apx.PROXIMITY_ANSWER";
+    static final String EXTRA_ALERT_ID = "alert_id";
+    static final String EXTRA_ACTION_ID = "action_id";
+    static final String EXTRA_URL = "url";
+    static final String EXTRA_NOTIFICATION_ID = "notification_id";
+
+    private ProximityNotification() {}
+
+    /** Stable per alert, so a re-sent card replaces itself instead of stacking. */
+    static int notificationId(String alertId) {
+        return 7200 + Math.abs(alertId.hashCode() % 700);
+    }
+
+    static void show(Context context, MessageFrameParser.MobilityAlert alert) {
+        ensureChannel(context);
+        int id = notificationId(alert.id());
+
+        NotificationCompat.Builder builder = new NotificationCompat.Builder(context, CHANNEL)
+            .setSmallIcon(R.drawable.ic_apx_notification)
+            .setContentTitle(alert.title())
+            .setContentText(alert.body())
+            .setStyle(new NotificationCompat.BigTextStyle().bigText(alert.body()))
+            // NAVIGATION, not MESSAGE: this is a place and a route, and the
+            // category is what tells the system (and the car) which it is.
+            .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
+            .setPriority(NotificationCompat.PRIORITY_HIGH)
+            .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+            // NOT onlyAlertOnce: each alert is its own place and its own
+            // decision, and the flag is what let the second one of a drive
+            // arrive without announcing itself.
+            .setAutoCancel(true)
+            // Its own bundle, so One UI does not fold it into the app's
+            // aggregated section where the actions are a tap away instead of
+            // on screen.
+            .setGroup("apx_proximity")
+            .setDefaults(NotificationCompat.DEFAULT_VIBRATE)
+            .setContentIntent(openApp(context, id));
+
+        // The daemon decides the four and their order — it owns the wording and
+        // the translations. Android draws what it is given rather than keeping
+        // its own copy of the list, so adding a fifth never needs a new APK.
+        int requestCode = 0;
+        for (MessageFrameParser.Action action : alert.actions()) {
+            String url = switch (action.id()) {
+                case "navigate" -> alert.navigateUrl();
+                case "add_stop" -> alert.addStopUrl();
+                default -> null;
+            };
+            builder.addAction(new NotificationCompat.Action.Builder(
+                R.drawable.ic_apx_notification,
+                action.label(),
+                answerIntent(context, alert.id(), action.id(), url, id, requestCode++)
+            ).build());
+        }
+
+        context.getSystemService(NotificationManager.class).notify(id, builder.build());
+    }
+
+    static void cancel(Context context, int id) {
+        context.getSystemService(NotificationManager.class).cancel(id);
+    }
+
+    private static PendingIntent answerIntent(
+        Context context, String alertId, String actionId, String url, int notificationId, int requestCode
+    ) {
+        Intent intent = new Intent(context, ProximityActionReceiver.class)
+            .setAction(ACTION_ANSWER)
+            .putExtra(EXTRA_ALERT_ID, alertId)
+            .putExtra(EXTRA_ACTION_ID, actionId)
+            .putExtra(EXTRA_NOTIFICATION_ID, notificationId);
+        if (url != null) intent.putExtra(EXTRA_URL, url);
+        return PendingIntent.getBroadcast(
+            context,
+            // The alert id is part of the request code or two open cards would
+            // share one PendingIntent and the second would answer the first.
+            notificationId * 10 + requestCode,
+            intent,
+            PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
+        );
+    }
+
+    private static PendingIntent openApp(Context context, int notificationId) {
+        Intent open = new Intent(context, MainActivity.class)
+            .putExtra(MainActivity.EXTRA_PATH, "/mobile")
+            .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_SINGLE_TOP);
+        return PendingIntent.getActivity(
+            context, notificationId, open,
+            PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
+        );
+    }
+
+    /** The soundless v1. Left behind by an upgrade, and dead. */
+    private static final String LEGACY_CHANNEL = "apx_proximity";
+
+    private static void ensureChannel(Context context) {
+        NotificationManager manager = context.getSystemService(NotificationManager.class);
+        // An abandoned channel does not disappear on its own: it stays listed
+        // in the app's notification settings forever, with the same name as the
+        // live one, and whatever the owner toggles on it does nothing.
+        manager.deleteNotificationChannel(LEGACY_CHANNEL);
+        NotificationChannel channel = new NotificationChannel(
+            CHANNEL,
+            context.getString(R.string.proximity_channel),
+            NotificationManager.IMPORTANCE_HIGH
+        );
+        channel.setDescription("Avisos de lugares cerca tuyo durante un viaje.");
+        // Silent, because MascotOverlayService already plays the one APX sound
+        // for the event and a channel tone would ring the same alert twice.
+        channel.setSound(null, null);
+        // BUT VIBRATING, and that pairing is the whole point. A channel with no
+        // sound AND no vibration is treated as non-alerting by One UI and
+        // MagicOS: the card was posted with its four actions, landed folded
+        // into the aggregated section, and never peeked — so the driver saw a
+        // line of text and no buttons, which is exactly the bug this is. The
+        // vibration keeps it a heads-up without a second sound.
+        channel.enableVibration(true);
+        channel.setVibrationPattern(new long[] { 0, 250 });
+        // A proximity alert is time-boxed by the car moving; it has to be
+        // readable on the lock screen while driving.
+        channel.setLockscreenVisibility(android.app.Notification.VISIBILITY_PUBLIC);
+        manager.createNotificationChannel(channel);
+    }
+}

package/src/interfaces/android/app/src/main/java/dev/agentprojectcontext/apx/StartupReceiver.java

@@ -0,0 +1,57 @@
+package dev.agentprojectcontext.apx;
+
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.os.Build;
+import android.util.Log;
+
+/**
+ * Brings the socket back after the two moments that silently kill it.
+ *
+ * MascotOverlayService is what holds the connection to the daemon and raises
+ * every bubble, sound and Android Auto card. Nothing but MainActivity used to
+ * start it, so the phone went quiet in two cases where the owner has no reason
+ * to suspect anything is wrong:
+ *
+ *  - a REBOOT: nothing runs until an app is opened, and APX was never opened;
+ *  - an UPDATE: installing an APK force-stops the package, and the service does
+ *    not come back on its own. Measured on both phones — zero ServiceRecords
+ *    right after `adb install -r`, back the instant MainActivity ran.
+ *
+ * "Notifications stopped working" and "I have not opened APX since Tuesday" are
+ * the same sentence, and only one of them is visible from the outside.
+ */
+public final class StartupReceiver extends BroadcastReceiver {
+    private static final String TAG = "APX";
+
+    @Override
+    public void onReceive(Context context, Intent intent) {
+        String action = intent == null ? null : intent.getAction();
+        if (!Intent.ACTION_BOOT_COMPLETED.equals(action)
+            && !Intent.ACTION_MY_PACKAGE_REPLACED.equals(action)) {
+            return;
+        }
+        // An unpaired install has nothing to connect to. The service would
+        // stopSelf() the moment it looked, so the cheaper answer is not to
+        // start it — and a phone that never finished pairing costs nothing.
+        if (!new ApxPreferences(context).paired()) return;
+
+        Intent service = new Intent(context, MascotOverlayService.class);
+        try {
+            if (Build.VERSION.SDK_INT >= 26) {
+                context.startForegroundService(service);
+            } else {
+                context.startService(service);
+            }
+        } catch (RuntimeException refused) {
+            // Same shape as TripLocationService: SecurityException (the app is
+            // not in an eligible state) and ForegroundServiceStartNotAllowedException
+            // are both RuntimeException, and a boot broadcast is exactly where
+            // Android is entitled to say no. Losing the notifications until the
+            // owner next opens APX is the old behaviour; taking the phone's boot
+            // down with an uncaught crash is not.
+            Log.w(TAG, "Android refused the startup service: " + refused.getMessage());
+        }
+    }
+}

package/src/interfaces/android/app/src/main/java/dev/agentprojectcontext/apx/TravelEventGate.java

@@ -0,0 +1,62 @@
+package dev.agentprojectcontext.apx;
+
+import java.util.Locale;
+
+final class TravelEventGate {
+    static final long KNOWN_DESTINATION_SETTLE_MS = 45_000L;
+
+    /**
+     * How long to wait before telling the daemon about a trip whose destination
+     * Maps has not published.
+     *
+     * WAS TEN MINUTES, and that was protecting the wrong thing. The long wait
+     * was there so a destination arriving late would be used instead of firing
+     * a "where are you going?" on a trip that was about to name itself — but
+     * MapsNavigationListenerService already handles that case directly: when
+     * the destination resolves it calls scheduleDaemonNotification(..., true),
+     * which REPLACES the pending notification with a 45 s known-destination
+     * one. The long settle never had to catch it.
+     *
+     * So on the case it actually governs — a drive with no route set, which is
+     * most short local ones — ten minutes was pure delay, and the trip-start
+     * message landed when the drive was half over. Three minutes still absorbs
+     * Maps posting and removing its notification while a route is being set up
+     * (the removal debounce covers the rest), and leaves the message useful.
+     *
+     * It does NOT gate proximity alerts. The state-only event and the GPS
+     * service start the moment navigation is detected — see the class comment
+     * in MapsNavigationListenerService and the rule in rules/android.md.
+     */
+    static final long UNKNOWN_DESTINATION_SETTLE_MS = 3 * 60_000L;
+    static final long DIFFERENT_DESTINATION_COOLDOWN_MS = 5 * 60_000L;
+    static final long SAME_DESTINATION_COOLDOWN_MS = 30 * 60_000L;
+
+    private TravelEventGate() {}
+
+    static long delayMs(long now, String destination, long lastSentAt, String lastDestination) {
+        String normalized = normalize(destination);
+        long settle = normalized.isBlank()
+            ? UNKNOWN_DESTINATION_SETTLE_MS
+            : KNOWN_DESTINATION_SETTLE_MS;
+        if (lastSentAt <= 0L) return settle;
+
+        long cooldown = normalized.equals(normalize(lastDestination))
+            ? SAME_DESTINATION_COOLDOWN_MS
+            : DIFFERENT_DESTINATION_COOLDOWN_MS;
+        long remaining = Math.max(0L, lastSentAt + cooldown - now);
+        return Math.max(settle, remaining);
+    }
+
+    static boolean coolingDown(long now, String destination, long lastSentAt, String lastDestination) {
+        if (lastSentAt <= 0L) return false;
+        String normalized = normalize(destination);
+        long cooldown = normalized.equals(normalize(lastDestination))
+            ? SAME_DESTINATION_COOLDOWN_MS
+            : DIFFERENT_DESTINATION_COOLDOWN_MS;
+        return now < lastSentAt + cooldown;
+    }
+
+    private static String normalize(String value) {
+        return value == null ? "" : value.trim().toLowerCase(Locale.ROOT);
+    }
+}

package/src/interfaces/android/app/src/main/java/dev/agentprojectcontext/apx/TravelStatusBanner.java

@@ -0,0 +1,116 @@
+package dev.agentprojectcontext.apx;
+
+import android.content.Context;
+import android.graphics.Color;
+import android.graphics.Typeface;
+import android.text.TextUtils;
+import android.view.Gravity;
+import android.view.View;
+import android.widget.ImageView;
+import android.widget.LinearLayout;
+import android.widget.TextView;
+
+/**
+ * The strip above `/mobile` that says a trip is in progress.
+ *
+ * It used to offer "Abrir Maps", which was the wrong destination: Maps is
+ * already open — it is what APX is reading the trip from. What the owner has
+ * no way to see is what APX is watching for on THIS drive, so the whole strip
+ * now opens that list instead (MainActivity.showTripPlaces).
+ */
+final class TravelStatusBanner extends LinearLayout {
+    private final TextView title;
+    private final TextView detail;
+    private final TextView affordance;
+
+    TravelStatusBanner(Context context) {
+        super(context);
+        setOrientation(HORIZONTAL);
+        setGravity(Gravity.CENTER_VERTICAL);
+        setPadding(dp(16), dp(11), dp(16), dp(11));
+        setBackgroundColor(Color.rgb(21, 48, 40));
+        setClickable(true);
+        setFocusable(true);
+
+        ImageView icon = new ImageView(context);
+        icon.setImageResource(R.drawable.ic_trip_car);
+        LayoutParams iconParams = new LayoutParams(dp(30), dp(30));
+        iconParams.rightMargin = dp(12);
+        addView(icon, iconParams);
+
+        LinearLayout copy = new LinearLayout(context);
+        copy.setOrientation(VERTICAL);
+        // One line each, ellipsized: the strip sits above the whole app and a
+        // subtitle that wraps pushes `/mobile` down and collides with the
+        // affordance on the right.
+        title = new TextView(context);
+        title.setTextColor(Color.WHITE);
+        title.setTextSize(15);
+        title.setTypeface(null, Typeface.BOLD);
+        title.setMaxLines(1);
+        title.setEllipsize(TextUtils.TruncateAt.END);
+        detail = new TextView(context);
+        detail.setTextColor(Color.rgb(166, 220, 202));
+        detail.setTextSize(12);
+        detail.setMaxLines(1);
+        detail.setEllipsize(TextUtils.TruncateAt.END);
+        copy.addView(title, new LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT));
+        copy.addView(detail, new LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT));
+        addView(copy, new LayoutParams(0, LayoutParams.WRAP_CONTENT, 1f));
+
+        affordance = new TextView(context);
+        affordance.setTextColor(Color.rgb(58, 231, 176));
+        affordance.setTextSize(12);
+        affordance.setTypeface(null, Typeface.BOLD);
+        affordance.setMaxLines(1);
+        LayoutParams affordanceParams = new LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT);
+        affordanceParams.leftMargin = dp(10);
+        addView(affordance, affordanceParams);
+        setVisibility(View.GONE);
+    }
+
+    void update(boolean active, String destination, String source) {
+        update(active, destination, source, -1);
+    }
+
+    /**
+     * `source` decides the sub-line, because "no destination yet" means two
+     * different things: Maps has not published one, or there is no route at all
+     * and APX only knows the phone is plugged into the car.
+     *
+     * `places` is how many errands APX is watching on this trip, or -1 while
+     * that is still unknown — the count comes from the daemon, so the banner
+     * has to render correctly before the first answer arrives.
+     */
+    void update(boolean active, String destination, String source, int places) {
+        if (!active) {
+            setVisibility(View.GONE);
+            return;
+        }
+        boolean known = destination != null && !destination.isBlank();
+        boolean sharedLink = known && (destination.startsWith("https://maps.app.goo.gl/")
+            || destination.startsWith("https://goo.gl/maps/"));
+        boolean projecting = ApxPreferences.SOURCE_ANDROID_AUTO.equals(source);
+        title.setText(known
+            ? "Estás en camino"
+            : projecting ? "Estás en el auto" : "Estás navegando por una ruta");
+        detail.setText(sharedLink
+            ? "Viaje compartido desde Google Maps"
+            : known ? "Destino: " + destination
+            : projecting ? "Android Auto conectado · sin ruta cargada"
+            : "Google Maps activo · destino todavía no disponible");
+        affordance.setText(placesLabel(places));
+        setVisibility(View.VISIBLE);
+    }
+
+    /** Kept short on purpose: it shares one line with the trip's own status. */
+    private String placesLabel(int places) {
+        if (places < 0) return "Pendientes ›";
+        if (places == 0) return "Nada cerca ›";
+        return places + " cerca ›";
+    }
+
+    private int dp(int value) {
+        return Math.round(value * getResources().getDisplayMetrics().density);
+    }
+}

package/src/interfaces/android/app/src/main/java/dev/agentprojectcontext/apx/TripLocationService.java

@@ -0,0 +1,272 @@
+package dev.agentprojectcontext.apx;
+
+import android.Manifest;
+import android.app.Notification;
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.app.Service;
+import android.content.Context;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.content.pm.ServiceInfo;
+import android.location.Location;
+import android.location.LocationListener;
+import android.location.LocationManager;
+import android.os.Build;
+import android.os.IBinder;
+import android.os.SystemClock;
+import android.util.Log;
+
+/**
+ * Streams the phone's position to the paired daemon while a trip is running.
+ *
+ * A foreground service, and not a timer inside the notification listener, for
+ * one reason: from Android 10 on, an app that is not in the foreground gets no
+ * location at all without ACCESS_BACKGROUND_LOCATION — and a foreground
+ * service typed `location` grants exactly the while-in-use access this needs
+ * without asking the owner for the far broader always-on permission. The
+ * ongoing notification it is obliged to show is a feature here, not a cost:
+ * the phone says out loud that APX is following the trip, and tapping it opens
+ * the app to stop.
+ *
+ * Nothing about a route is uploaded. Each sample is a point plus its accuracy,
+ * the daemon answers it with at most a proximity reminder, and no location
+ * history is written anywhere — see rules/android.md.
+ */
+public final class TripLocationService extends Service {
+    private static final String TAG = "APXTravel";
+    private static final String CHANNEL = "apx_trip_location";
+    private static final int NOTIFICATION_ID = 7300;
+    static final String EXTRA_TRIP_ID = "trip_id";
+
+    // 30 s / 150 m. Fast enough that a 2 km geofence cannot be crossed and
+    // left between two samples at city speed, slow enough that a whole drive
+    // costs a couple of hundred requests rather than a couple of thousand.
+    private static final long MIN_INTERVAL_MS = 30_000L;
+    private static final float MIN_DISTANCE_M = 150f;
+    // The provider can hand us a fix more often than we asked; this is the
+    // floor on what actually leaves the phone.
+    private static final long MIN_UPLOAD_INTERVAL_MS = 25_000L;
+
+    private ApxPreferences preferences;
+    private LocationManager locations;
+    private String tripId = "";
+    private long lastUploadElapsedMs;
+
+    private final LocationListener listener = new LocationListener() {
+        @Override
+        public void onLocationChanged(Location location) {
+            publish(location);
+        }
+
+        // Required on API < 30; harmless above it.
+        @Override
+        public void onProviderEnabled(String provider) {}
+
+        @Override
+        public void onProviderDisabled(String provider) {}
+    };
+
+    /**
+     * Begin reporting for `tripId`. Safe to call again for the same trip — the
+     * service just re-reads the id. Returns false when Android refused the
+     * start (a background foreground-service start is not always allowed), so
+     * the caller can log it rather than assume tracking is live.
+     */
+    static boolean start(Context context, String tripId) {
+        Intent intent = new Intent(context, TripLocationService.class).putExtra(EXTRA_TRIP_ID, tripId);
+        try {
+            context.startForegroundService(intent);
+            return true;
+        } catch (RuntimeException refused) {
+            Log.w(TAG, "Could not start trip location tracking", refused);
+            return false;
+        }
+    }
+
+    static void stop(Context context) {
+        try {
+            context.stopService(new Intent(context, TripLocationService.class));
+        } catch (RuntimeException ignored) {
+            // Already gone; nothing to stop.
+        }
+    }
+
+    /** Do we have the permission this service exists to use? */
+    static boolean canTrack(Context context) {
+        return context.checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
+            || context.checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
+    }
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        preferences = new ApxPreferences(this);
+        locations = (LocationManager) getSystemService(Context.LOCATION_SERVICE);
+        ensureChannel();
+    }
+
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        String requested = intent == null ? "" : String.valueOf(intent.getStringExtra(EXTRA_TRIP_ID));
+        if (requested != null && !requested.isBlank() && !"null".equals(requested)) tripId = requested;
+        // Permission first. startForeground() with the `location` type THROWS
+        // when the app may not use location, and this used to run before the
+        // check — so the whole app died with a SecurityException at the exact
+        // moment a trip began.
+        if (!canTrack(this)) {
+            Log.w(TAG, "Trip tracking asked for without location permission");
+            stopSelf();
+            return START_NOT_STICKY;
+        }
+        boolean foreground = startForegroundCompat();
+        // Announced either way: a trip we cannot FOLLOW is still a trip, and
+        // the daemon already has an origin to reason about.
+        announceTrip();
+        if (!foreground) {
+            stopSelf();
+            return START_NOT_STICKY;
+        }
+        requestUpdates();
+        // Send the fix we already have so the daemon can evaluate proximity
+        // immediately instead of waiting up to 30 s for the first update.
+        publish(newestFix());
+        // START_STICKY: a trip outlives a low-memory kill, and the listener
+        // service is what ends it — not the system.
+        return START_STICKY;
+    }
+
+    @Override
+    public void onDestroy() {
+        try {
+            locations.removeUpdates(listener);
+        } catch (RuntimeException ignored) {
+            // Never registered (missing permission) — nothing to remove.
+        }
+        super.onDestroy();
+    }
+
+    @Override
+    public IBinder onBind(Intent intent) {
+        return null;
+    }
+
+    private void requestUpdates() {
+        for (String provider : new String[] { LocationManager.GPS_PROVIDER, LocationManager.NETWORK_PROVIDER }) {
+            try {
+                if (!locations.isProviderEnabled(provider)) continue;
+                locations.requestLocationUpdates(provider, MIN_INTERVAL_MS, MIN_DISTANCE_M, listener);
+            } catch (SecurityException | IllegalArgumentException unavailable) {
+                Log.w(TAG, "Provider " + provider + " unavailable: " + unavailable.getMessage());
+            }
+        }
+    }
+
+    private Location newestFix() {
+        try {
+            Location newest = null;
+            for (String provider : locations.getProviders(true)) {
+                Location candidate = locations.getLastKnownLocation(provider);
+                if (candidate == null) continue;
+                if (newest == null || candidate.getTime() > newest.getTime()) newest = candidate;
+            }
+            return newest;
+        } catch (SecurityException denied) {
+            return null;
+        }
+    }
+
+    private void announceTrip() {
+        String trip = tripId.isBlank() ? preferences.travelTripId() : tripId;
+        if (trip.isBlank()) return;
+        DaemonClient.notifyTripContext(
+            preferences.daemonUrl(),
+            preferences.token(),
+            trip,
+            preferences.travelDestination(),
+            DeviceLocation.latest(this)
+        );
+    }
+
+    private void publish(Location location) {
+        if (location == null) return;
+        if (!preferences.travelActive()) {
+            // The trip ended between two fixes. Stop rather than report a
+            // position for a journey the daemon has already closed.
+            stopSelf();
+            return;
+        }
+        long now = SystemClock.elapsedRealtime();
+        if (lastUploadElapsedMs != 0L && now - lastUploadElapsedMs < MIN_UPLOAD_INTERVAL_MS) return;
+        lastUploadElapsedMs = now;
+        String trip = tripId.isBlank() ? preferences.travelTripId() : tripId;
+        if (trip.isBlank()) return;
+        DaemonClient.reportPosition(preferences.daemonUrl(), preferences.token(), trip, location);
+    }
+
+    /**
+     * Go foreground, or say why not.
+     *
+     * Holding ACCESS_FINE_LOCATION is not sufficient on its own: it is a
+     * while-in-use permission, so Android also requires the app to be in an
+     * "eligible state" to start a `location`-typed foreground service — and it
+     * refuses with a SecurityException when it is not. The refusal is routine
+     * rather than exceptional: the notification listener that detects a trip
+     * runs in the background, which is exactly the ineligible case, and this
+     * threw straight through onStartCommand and killed the app every time a
+     * drive began with APX not on screen.
+     *
+     * Losing the GPS stream is a real cost — no proximity reminders on this
+     * leg — but it is recoverable and a crash is not: MainActivity retries the
+     * start on resume, when the app IS eligible, and "APX menu → Remove battery
+     * restriction" makes the background start succeed on its own.
+     */
+    private boolean startForegroundCompat() {
+        Notification notice = buildNotification();
+        try {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+                startForeground(NOTIFICATION_ID, notice, ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION);
+            } else {
+                startForeground(NOTIFICATION_ID, notice);
+            }
+            return true;
+        } catch (RuntimeException refused) {
+            // SecurityException (not eligible) and
+            // ForegroundServiceStartNotAllowedException are both RuntimeException.
+            Log.w(TAG, "Android refused the trip tracking service: " + refused.getMessage());
+            return false;
+        }
+    }
+
+    private Notification buildNotification() {
+        Intent open = new Intent(this, MainActivity.class).putExtra(MainActivity.EXTRA_SETTINGS, true);
+        PendingIntent pending = PendingIntent.getActivity(
+            this,
+            8,
+            open,
+            PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
+        );
+        String destination = preferences.travelDestination();
+        return new Notification.Builder(this, CHANNEL)
+            .setSmallIcon(R.drawable.ic_apx_notification)
+            .setContentTitle(getString(R.string.trip_tracking_title))
+            .setContentText(destination.isBlank()
+                ? getString(R.string.trip_tracking_text)
+                : getString(R.string.trip_tracking_text_destination, destination))
+            .setContentIntent(pending)
+            .setOngoing(true)
+            .build();
+    }
+
+    private void ensureChannel() {
+        NotificationManager manager = getSystemService(NotificationManager.class);
+        NotificationChannel channel = new NotificationChannel(
+            CHANNEL,
+            getString(R.string.trip_tracking_channel),
+            NotificationManager.IMPORTANCE_LOW
+        );
+        channel.setDescription(getString(R.string.trip_tracking_channel_description));
+        manager.createNotificationChannel(channel);
+    }
+}