clawdex-mobile 5.2.0 → 5.2.3

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.2.3 - 2026-05-30
+
+### Added
+- Push notifications for agent turn completion and approval requests. Because the app's WebSocket closes when backgrounded, the always-on bridge is the sender: devices register an Expo push token (`bridge/push/register`/`unregister`/`list`) and the bridge POSTs a minimal payload to the Expo push service, which relays via APNs (iOS) and FCM (Android). Auto-enabled on first bridge connect; Settings → Notifications is the override (opt out + per-event toggles). Foreground banners are suppressed; tapping a notification deep-links to the thread.
+- Reply preview on turn-completed notifications: the agent's last reply line, whitespace-collapsed and capped at 140 characters. A reply snippet therefore transits Expo/Apple/Google when notifications are enabled; disclosed in the privacy policy and store data-safety answers.
+- Actionable Approve/Deny buttons on approval notifications, resolved over the authenticated bridge WebSocket without opening the conversation.
+- Android push support (Firebase project + FCM v1 credentials).
+- Prompt library in the composer: save and one-tap-insert reusable prompts, with search and inline add/edit/delete.
+
+### Improved
+- Push delivery hardened for scale: retry with exponential backoff on Expo 429/5xx and transport errors, plus delayed receipt polling that prunes unregistered device tokens.
+- Version synced to 5.2.3 across the monorepo (CLI, mobile app, and Rust bridge).
+
 ## 5.2.0 - 2026-05-18
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.2.0",
+  "version": "5.2.3",
   "description": "Private-network mobile bridge and CLI for Codex, OpenCode, and Cursor",
   "keywords": [
     "codex",

package/services/rust-bridge/Cargo.lock

@@ -149,7 +149,7 @@ dependencies = [
 
 [[package]]
 name = "codex-rust-bridge"
-version = "5.2.0"
+version = "5.2.3"
 dependencies = [
  "axum",
  "base64",

package/services/rust-bridge/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codex-rust-bridge"
-version = "5.2.0"
+version = "5.2.3"
 edition = "2021"
 
 [dependencies]

package/services/rust-bridge/src/main.rs

@@ -663,6 +663,552 @@ async fn configure_git_credential_store(
     Ok(())
 }
 
+// ---- Push notifications ----------------------------------------------------
+//
+// The mobile app can only run JavaScript (and therefore keep its WebSocket
+// open) while it is foregrounded. The moment it is backgrounded or killed the
+// socket closes, so the *phone* can never observe a turn completing. The bridge
+// is the only component reliably alive at that moment, so it is the sender:
+// devices register an Expo push token, and the bridge POSTs a minimal,
+// content-free payload to the Expo push service when a turn completes or an
+// approval is requested. Expo relays to APNs/FCM, which wakes the app.
+
+const PUSH_REGISTRY_FILE_NAME: &str = ".clawdex-push-registry.json";
+const EXPO_PUSH_SEND_ENDPOINT: &str = "https://exp.host/--/api/v2/push/send";
+const EXPO_PUSH_RECEIPTS_ENDPOINT: &str = "https://exp.host/--/api/v2/push/getReceipts";
+const EXPO_PUSH_BATCH_SIZE: usize = 100;
+// Reply-preview tuning: cap how much streamed text we buffer per thread, and how
+// many characters of the first line we surface in the notification body.
+const PUSH_PREVIEW_ACCUMULATE_CAP: usize = 8000;
+const PUSH_PREVIEW_MAX_CHARS: usize = 140;
+const EXPO_RECEIPT_BATCH_SIZE: usize = 1000;
+// Expo asks senders to wait at least ~15 minutes before fetching delivery receipts.
+const RECEIPT_CHECK_DELAY_SECS: u64 = 900;
+const PUSH_SEND_MAX_ATTEMPTS: u32 = 4;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PushEventPreferences {
+    #[serde(default = "default_true")]
+    turn_completed: bool,
+    #[serde(default = "default_true")]
+    approval_requested: bool,
+}
+
+fn default_true() -> bool {
+    true
+}
+
+impl Default for PushEventPreferences {
+    fn default() -> Self {
+        Self {
+            turn_completed: true,
+            approval_requested: true,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PushDeviceRegistration {
+    token: String,
+    #[serde(default)]
+    platform: String,
+    #[serde(default)]
+    device_name: String,
+    #[serde(default)]
+    events: PushEventPreferences,
+    created_at: String,
+    updated_at: String,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct PushRegistry {
+    #[serde(default)]
+    devices: Vec<PushDeviceRegistration>,
+}
+
+struct PushService {
+    registry: RwLock<PushRegistry>,
+    registry_path: PathBuf,
+    project_label: String,
+    http: reqwest::Client,
+    access_token: Option<String>,
+    // Accumulates the in-flight agent reply text per thread (keyed by threadId),
+    // so a turn/completed push can include a short preview of what the agent said.
+    recent_replies: RwLock<HashMap<String, String>>,
+}
+
+impl PushService {
+    async fn load(workdir: &Path, project_label: String) -> Arc<Self> {
+        let registry_path = workdir.join(PUSH_REGISTRY_FILE_NAME);
+        let registry = match tokio::fs::read_to_string(&registry_path).await {
+            Ok(contents) => serde_json::from_str::<PushRegistry>(&contents).unwrap_or_default(),
+            Err(_) => PushRegistry::default(),
+        };
+        let access_token = env::var("EXPO_ACCESS_TOKEN")
+            .ok()
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty());
+        Arc::new(Self {
+            registry: RwLock::new(registry),
+            registry_path,
+            project_label,
+            http: reqwest::Client::new(),
+            access_token,
+            recent_replies: RwLock::new(HashMap::new()),
+        })
+    }
+
+    fn spawn_event_loop(self: &Arc<Self>, hub: &Arc<ClientHub>) {
+        let this = Arc::clone(self);
+        let mut receiver = hub.subscribe_notifications();
+        tokio::spawn(async move {
+            loop {
+                match receiver.recv().await {
+                    Ok(notification) => {
+                        this.handle_notification(&notification.method, &notification.params)
+                            .await;
+                    }
+                    Err(broadcast::error::RecvError::Lagged(_)) => continue,
+                    Err(broadcast::error::RecvError::Closed) => break,
+                }
+            }
+        });
+    }
+
+    async fn persist(&self) {
+        let snapshot = { self.registry.read().await.clone() };
+        match serde_json::to_string_pretty(&snapshot) {
+            Ok(contents) => {
+                if let Err(error) = tokio::fs::write(&self.registry_path, contents).await {
+                    eprintln!("failed to persist push registry: {error}");
+                }
+            }
+            Err(error) => eprintln!("failed to serialize push registry: {error}"),
+        }
+    }
+
+    async fn register(
+        &self,
+        token: String,
+        platform: String,
+        device_name: String,
+        events: PushEventPreferences,
+    ) -> usize {
+        let now = now_iso();
+        let count = {
+            let mut registry = self.registry.write().await;
+            if let Some(existing) = registry
+                .devices
+                .iter_mut()
+                .find(|device| device.token == token)
+            {
+                existing.platform = platform;
+                existing.device_name = device_name;
+                existing.events = events;
+                existing.updated_at = now;
+            } else {
+                registry.devices.push(PushDeviceRegistration {
+                    token,
+                    platform,
+                    device_name,
+                    events,
+                    created_at: now.clone(),
+                    updated_at: now,
+                });
+            }
+            registry.devices.len()
+        };
+        self.persist().await;
+        count
+    }
+
+    async fn unregister(&self, token: &str) -> bool {
+        let removed = {
+            let mut registry = self.registry.write().await;
+            let before = registry.devices.len();
+            registry.devices.retain(|device| device.token != token);
+            registry.devices.len() != before
+        };
+        if removed {
+            self.persist().await;
+        }
+        removed
+    }
+
+    async fn list(&self) -> Vec<Value> {
+        let registry = self.registry.read().await;
+        registry
+            .devices
+            .iter()
+            .map(|device| {
+                json!({
+                    "platform": device.platform,
+                    "deviceName": device.device_name,
+                    "events": device.events,
+                    "createdAt": device.created_at,
+                    "updatedAt": device.updated_at,
+                    // Never echo full tokens back to clients; expose only a short suffix.
+                    "tokenSuffix": token_suffix(&device.token),
+                })
+            })
+            .collect()
+    }
+
+    /// Pull params.threadId (or thread_id), trimmed and non-empty.
+    fn read_thread_id(params: &Value) -> Option<String> {
+        read_string(params.get("threadId"))
+            .or_else(|| read_string(params.get("thread_id")))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty())
+    }
+
+    /// Accumulate streamed agent reply text per thread so a completed turn can
+    /// include a short preview. Handles the app-server delta method and the
+    /// codex-event variant; only text deltas are captured. Returns true if the
+    /// notification was a reply delta (and thus fully handled here).
+    async fn accumulate_reply(&self, method: &str, params: &Value) -> bool {
+        let is_delta = matches!(
+            method,
+            "item/agentMessage/delta" | "codex/event/agent_message_delta"
+        );
+        if !is_delta {
+            return false;
+        }
+        let field_is_text = read_string(params.get("field"))
+            .map(|value| value == "text")
+            .unwrap_or(true);
+        let delta = read_string(params.get("delta"))
+            .or_else(|| read_string(params.get("text")))
+            .unwrap_or_default();
+        if !field_is_text || delta.is_empty() {
+            return true;
+        }
+        if let Some(thread_id) = Self::read_thread_id(params) {
+            let mut replies = self.recent_replies.write().await;
+            let entry = replies.entry(thread_id).or_default();
+            // Cap accumulation so a long turn cannot grow this unbounded.
+            if entry.len() < PUSH_PREVIEW_ACCUMULATE_CAP {
+                entry.push_str(&delta);
+            }
+        }
+        true
+    }
+
+    /// Remove and format the accumulated reply for a thread into a one-line
+    /// preview: last non-empty line (agents usually end with the conclusion),
+    /// whitespace-collapsed, length-capped.
+    async fn take_reply_preview(&self, thread_id: &str) -> Option<String> {
+        let raw = {
+            let mut replies = self.recent_replies.write().await;
+            replies.remove(thread_id)?
+        };
+        let last_line = raw
+            .lines()
+            .map(str::trim)
+            .filter(|line| !line.is_empty())
+            .next_back()?;
+        let collapsed = last_line.split_whitespace().collect::<Vec<_>>().join(" ");
+        if collapsed.is_empty() {
+            return None;
+        }
+        Some(truncate_chars(&collapsed, PUSH_PREVIEW_MAX_CHARS))
+    }
+
+    async fn handle_notification(self: &Arc<Self>, method: &str, params: &Value) {
+        if self.accumulate_reply(method, params).await {
+            return;
+        }
+        let event = match method {
+            "turn/completed" => PushEvent::TurnCompleted,
+            "bridge/approval.requested" => PushEvent::ApprovalRequested,
+            _ => return,
+        };
+
+        let thread_id = read_string(params.get("threadId"))
+            .or_else(|| read_string(params.get("thread_id")))
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty());
+
+        // For approval events, carry the approval id so a notification action can
+        // resolve exactly this approval without opening the conversation first.
+        let approval_id = match event {
+            PushEvent::ApprovalRequested => read_string(params.get("id"))
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty()),
+            PushEvent::TurnCompleted => None,
+        };
+
+        // Drain the accumulated reply buffer on completion regardless of whether
+        // any device is registered, otherwise threads streamed while no device
+        // is subscribed would leak their buffers indefinitely.
+        let reply_preview = match event {
+            PushEvent::TurnCompleted => match thread_id.as_deref() {
+                Some(tid) => self.take_reply_preview(tid).await,
+                None => None,
+            },
+            PushEvent::ApprovalRequested => None,
+        };
+
+        let targets: Vec<String> = {
+            let registry = self.registry.read().await;
+            registry
+                .devices
+                .iter()
+                .filter(|device| match event {
+                    PushEvent::TurnCompleted => device.events.turn_completed,
+                    PushEvent::ApprovalRequested => device.events.approval_requested,
+                })
+                .map(|device| device.token.clone())
+                .collect()
+        };
+        if targets.is_empty() {
+            return;
+        }
+        let (title, body) = match event {
+            PushEvent::TurnCompleted => (
+                "Turn finished".to_string(),
+                reply_preview
+                    .unwrap_or_else(|| format!("Codex finished working in {}", self.project_label)),
+            ),
+            PushEvent::ApprovalRequested => (
+                "Approval needed".to_string(),
+                format!(
+                    "Codex is waiting for your approval in {}",
+                    self.project_label
+                ),
+            ),
+        };
+        let data = json!({
+            "type": event.as_str(),
+            "threadId": thread_id,
+            "approvalId": approval_id,
+        });
+        // Only approval pushes get the actionable category; turn-complete pushes
+        // have nothing to act on.
+        let category_id = match event {
+            PushEvent::ApprovalRequested if approval_id.is_some() => Some("approval"),
+            _ => None,
+        };
+
+        self.send(&title, &body, &data, category_id, targets).await;
+    }
+
+    async fn send(
+        self: &Arc<Self>,
+        title: &str,
+        body: &str,
+        data: &Value,
+        category_id: Option<&str>,
+        tokens: Vec<String>,
+    ) {
+        for chunk in tokens.chunks(EXPO_PUSH_BATCH_SIZE) {
+            let messages: Vec<Value> = chunk
+                .iter()
+                .map(|token| {
+                    let mut message = json!({
+                        "to": token,
+                        "title": title,
+                        "body": body,
+                        "data": data,
+                        "sound": "default",
+                        "priority": "high",
+                    });
+                    // iOS action buttons are driven by a registered category; the
+                    // app maps this id to its Approve/Deny actions.
+                    if let Some(category) = category_id {
+                        message["categoryId"] = json!(category);
+                    }
+                    message
+                })
+                .collect();
+
+            let Some(payload) = self
+                .post_with_retry(EXPO_PUSH_SEND_ENDPOINT, &Value::Array(messages))
+                .await
+            else {
+                continue;
+            };
+
+            // Expo returns one ticket per message, in request order. status="error"
+            // is an immediate failure; status="ok" carries a receipt id that we
+            // re-check later, because DeviceNotRegistered (and APNs/FCM delivery
+            // failures) frequently only surface in the receipt, not the ticket.
+            let Some(tickets) = payload.get("data").and_then(Value::as_array) else {
+                continue;
+            };
+            let mut stale: Vec<String> = Vec::new();
+            let mut pending_receipts: Vec<(String, String)> = Vec::new();
+            for (index, ticket) in tickets.iter().enumerate() {
+                let Some(token) = chunk.get(index).cloned() else {
+                    continue;
+                };
+                match read_string(ticket.get("status")).as_deref() {
+                    Some("ok") => {
+                        if let Some(receipt_id) = read_string(ticket.get("id")) {
+                            pending_receipts.push((receipt_id, token));
+                        }
+                    }
+                    Some("error") => {
+                        let error_kind = ticket
+                            .get("details")
+                            .and_then(|details| read_string(details.get("error")));
+                        if error_kind.as_deref() == Some("DeviceNotRegistered") {
+                            stale.push(token);
+                        }
+                    }
+                    _ => {}
+                }
+            }
+            for token in stale {
+                self.unregister(&token).await;
+            }
+            if !pending_receipts.is_empty() {
+                self.spawn_receipt_check(pending_receipts);
+            }
+        }
+    }
+
+    /// POST JSON to Expo, retrying on 429 / 5xx / transport errors with
+    /// exponential backoff (honoring Retry-After). Returns the parsed body, or
+    /// None once attempts are exhausted.
+    async fn post_with_retry(&self, url: &str, body: &Value) -> Option<Value> {
+        let mut delay_ms: u64 = 500;
+        for attempt in 1..=PUSH_SEND_MAX_ATTEMPTS {
+            let mut request = self.http.post(url).json(body);
+            if let Some(token) = &self.access_token {
+                request = request.bearer_auth(token);
+            }
+            match request.send().await {
+                Ok(response) => {
+                    let status = response.status();
+                    if status.as_u16() == 429 || status.is_server_error() {
+                        if attempt >= PUSH_SEND_MAX_ATTEMPTS {
+                            eprintln!(
+                                "push request to {url} gave up after {attempt} attempts (status {status})"
+                            );
+                            return None;
+                        }
+                        let wait_ms = response
+                            .headers()
+                            .get("retry-after")
+                            .and_then(|value| value.to_str().ok())
+                            .and_then(|value| value.parse::<u64>().ok())
+                            .map(|secs| secs.saturating_mul(1000))
+                            .unwrap_or(delay_ms);
+                        tokio::time::sleep(std::time::Duration::from_millis(wait_ms)).await;
+                        delay_ms = (delay_ms * 2).min(8000);
+                        continue;
+                    }
+                    match response.json::<Value>().await {
+                        Ok(value) => return Some(value),
+                        Err(error) => {
+                            eprintln!("push response parse failed: {error}");
+                            return None;
+                        }
+                    }
+                }
+                Err(error) => {
+                    if attempt >= PUSH_SEND_MAX_ATTEMPTS {
+                        eprintln!("push request to {url} failed after {attempt} attempts: {error}");
+                        return None;
+                    }
+                    tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
+                    delay_ms = (delay_ms * 2).min(8000);
+                }
+            }
+        }
+        None
+    }
+
+    /// After Expo's recommended delay, fetch delivery receipts for the given
+    /// (receiptId, token) pairs and prune tokens reported DeviceNotRegistered.
+    fn spawn_receipt_check(self: &Arc<Self>, receipts: Vec<(String, String)>) {
+        let this = Arc::clone(self);
+        tokio::spawn(async move {
+            tokio::time::sleep(std::time::Duration::from_secs(RECEIPT_CHECK_DELAY_SECS)).await;
+            this.check_receipts(receipts).await;
+        });
+    }
+
+    async fn check_receipts(&self, receipts: Vec<(String, String)>) {
+        for chunk in receipts.chunks(EXPO_RECEIPT_BATCH_SIZE) {
+            let ids: Vec<&str> = chunk.iter().map(|(id, _)| id.as_str()).collect();
+            let Some(payload) = self
+                .post_with_retry(EXPO_PUSH_RECEIPTS_ENDPOINT, &json!({ "ids": ids }))
+                .await
+            else {
+                continue;
+            };
+            let Some(map) = payload.get("data").and_then(Value::as_object) else {
+                continue;
+            };
+            let mut stale: Vec<String> = Vec::new();
+            for (receipt_id, receipt) in map {
+                if read_string(receipt.get("status")).as_deref() != Some("error") {
+                    continue;
+                }
+                let error_kind = receipt
+                    .get("details")
+                    .and_then(|details| read_string(details.get("error")));
+                if error_kind.as_deref() == Some("DeviceNotRegistered") {
+                    if let Some((_, token)) = chunk.iter().find(|(id, _)| id == receipt_id) {
+                        stale.push(token.clone());
+                    }
+                }
+            }
+            for token in stale {
+                self.unregister(&token).await;
+            }
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+enum PushEvent {
+    TurnCompleted,
+    ApprovalRequested,
+}
+
+impl PushEvent {
+    fn as_str(self) -> &'static str {
+        match self {
+            PushEvent::TurnCompleted => "turn_completed",
+            PushEvent::ApprovalRequested => "approval_requested",
+        }
+    }
+}
+
+/// Truncate to at most `max_chars` characters (char-safe), appending an ellipsis
+/// when content was dropped.
+fn truncate_chars(text: &str, max_chars: usize) -> String {
+    if text.chars().count() <= max_chars {
+        return text.to_string();
+    }
+    let truncated: String = text.chars().take(max_chars.saturating_sub(1)).collect();
+    format!("{}…", truncated.trim_end())
+}
+
+fn token_suffix(token: &str) -> String {
+    let visible: String = token.chars().rev().take(6).collect::<String>();
+    visible.chars().rev().collect()
+}
+
+fn parse_push_event_preferences(value: Option<&Value>) -> PushEventPreferences {
+    let defaults = PushEventPreferences::default();
+    match value {
+        Some(object) => PushEventPreferences {
+            turn_completed: read_bool(object.get("turnCompleted"))
+                .unwrap_or(defaults.turn_completed),
+            approval_requested: read_bool(object.get("approvalRequested"))
+                .unwrap_or(defaults.approval_requested),
+        },
+        None => defaults,
+    }
+}
+
 #[derive(Clone)]
 struct AppState {
     config: Arc<BridgeConfig>,
@@ -675,6 +1221,7 @@ struct AppState {
     git: Arc<GitService>,
     updater: Arc<UpdateService>,
     preview: Arc<BrowserPreviewService>,
+    push: Arc<PushService>,
 }
 
 #[allow(dead_code)]
@@ -6880,6 +7427,15 @@ async fn main() {
     ));
     let queue = BridgeQueueService::new(backend.clone(), hub.clone());
 
+    let project_label = config
+        .workdir
+        .file_name()
+        .map(|name| name.to_string_lossy().to_string())
+        .filter(|name| !name.is_empty())
+        .unwrap_or_else(|| "Clawdex".to_string());
+    let push = PushService::load(&config.workdir, project_label).await;
+    push.spawn_event_loop(&hub);
+
     let state = Arc::new(AppState {
         config: config.clone(),
         started_at: Instant::now(),
@@ -6891,6 +7447,7 @@ async fn main() {
         git,
         updater,
         preview,
+        push,
     });
 
     let app = Router::new()
@@ -7776,6 +8333,36 @@ async fn handle_bridge_method(
             .map_err(|error| BridgeError::server(&error.to_string())),
         "bridge/runtime/read" => serde_json::to_value(state.updater.runtime_info().await)
             .map_err(|error| BridgeError::server(&error.to_string())),
+        "bridge/push/register" => {
+            let params = params.unwrap_or_else(|| json!({}));
+            let token = read_string(params.get("token"))
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty())
+                .ok_or_else(|| BridgeError::invalid_params("push token is required"))?;
+            let platform = read_string(params.get("platform"))
+                .map(|value| value.trim().to_lowercase())
+                .unwrap_or_else(|| "unknown".to_string());
+            let device_name = read_string(params.get("deviceName"))
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty())
+                .unwrap_or_else(|| "Unknown device".to_string());
+            let events = parse_push_event_preferences(params.get("events"));
+            let count = state
+                .push
+                .register(token, platform, device_name, events)
+                .await;
+            Ok(json!({ "ok": true, "deviceCount": count }))
+        }
+        "bridge/push/unregister" => {
+            let params = params.unwrap_or_else(|| json!({}));
+            let token = read_string(params.get("token"))
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty())
+                .ok_or_else(|| BridgeError::invalid_params("push token is required"))?;
+            let removed = state.push.unregister(&token).await;
+            Ok(json!({ "ok": true, "removed": removed }))
+        }
+        "bridge/push/list" => Ok(json!({ "devices": state.push.list().await })),
         "bridge/cursor/credentials/read" => {
             let status = read_cursor_credential_status(state).await?;
             serde_json::to_value(status).map_err(|error| BridgeError::server(&error.to_string()))
@@ -14012,6 +14599,150 @@ fn normalize_path(path: &Path) -> PathBuf {
 mod tests {
     use super::*;
 
+    #[test]
+    fn token_suffix_masks_all_but_last_six_chars() {
+        assert_eq!(token_suffix("ExponentPushToken[abcdef123456]"), "23456]");
+        assert_eq!(token_suffix("abc"), "abc");
+        assert_eq!(token_suffix(""), "");
+    }
+
+    #[test]
+    fn truncate_chars_caps_and_ellipsizes() {
+        assert_eq!(truncate_chars("short", 140), "short");
+        let long = "a".repeat(200);
+        let out = truncate_chars(&long, 140);
+        assert_eq!(out.chars().count(), 140); // 139 chars + ellipsis
+        assert!(out.ends_with('…'));
+        // Char-safe: must not split a multi-byte char mid-way.
+        let emoji = "🚀".repeat(10);
+        let out = truncate_chars(&emoji, 4);
+        assert_eq!(out.chars().count(), 4);
+    }
+
+    #[tokio::test]
+    async fn take_reply_preview_uses_last_nonempty_line() {
+        let dir = std::env::temp_dir().join(format!("clawdex-preview-{}", std::process::id()));
+        let _ = tokio::fs::create_dir_all(&dir).await;
+        let service = PushService::load(&dir, "demo".to_string()).await;
+        service
+            .accumulate_reply(
+                "item/agentMessage/delta",
+                &json!({ "threadId": "t1", "field": "text", "delta": "Working on it\n Done: fixed the bug \n\n" }),
+            )
+            .await;
+        let preview = service.take_reply_preview("t1").await;
+        assert_eq!(preview.as_deref(), Some("Done: fixed the bug"));
+        // Buffer is consumed.
+        assert!(service.take_reply_preview("t1").await.is_none());
+        let _ = tokio::fs::remove_dir_all(&dir).await;
+    }
+
+    #[tokio::test]
+    async fn turn_completed_drains_reply_buffer_with_no_devices() {
+        let dir = std::env::temp_dir().join(format!("clawdex-drain-{}", std::process::id()));
+        let _ = tokio::fs::create_dir_all(&dir).await;
+        let service = PushService::load(&dir, "demo".to_string()).await;
+        // Stream a reply with no devices registered.
+        service
+            .accumulate_reply(
+                "item/agentMessage/delta",
+                &json!({ "threadId": "t1", "field": "text", "delta": "All done" }),
+            )
+            .await;
+        // Completion with an empty registry must still drain the buffer, not leak it.
+        service
+            .handle_notification("turn/completed", &json!({ "threadId": "t1" }))
+            .await;
+        assert!(service.take_reply_preview("t1").await.is_none());
+        let _ = tokio::fs::remove_dir_all(&dir).await;
+    }
+
+    #[test]
+    fn parse_push_event_preferences_defaults_to_enabled() {
+        let defaults = parse_push_event_preferences(None);
+        assert!(defaults.turn_completed);
+        assert!(defaults.approval_requested);
+
+        let partial = parse_push_event_preferences(Some(&json!({ "approvalRequested": false })));
+        assert!(partial.turn_completed);
+        assert!(!partial.approval_requested);
+    }
+
+    #[test]
+    fn push_registry_round_trips_and_tolerates_missing_fields() {
+        let raw = json!({
+            "devices": [
+                {
+                    "token": "ExponentPushToken[one]",
+                    "platform": "ios",
+                    "deviceName": "iPhone",
+                    "events": { "turnCompleted": true, "approvalRequested": false },
+                    "createdAt": "2026-05-29T00:00:00Z",
+                    "updatedAt": "2026-05-29T00:00:00Z"
+                },
+                {
+                    "token": "ExponentPushToken[two]",
+                    "createdAt": "2026-05-29T00:00:00Z",
+                    "updatedAt": "2026-05-29T00:00:00Z"
+                }
+            ]
+        });
+        let registry: PushRegistry = serde_json::from_value(raw).expect("parse registry");
+        assert_eq!(registry.devices.len(), 2);
+        // Missing event prefs fall back to enabled.
+        assert!(registry.devices[1].events.turn_completed);
+        assert!(registry.devices[1].events.approval_requested);
+
+        let serialized = serde_json::to_string(&registry).expect("serialize");
+        let reparsed: PushRegistry = serde_json::from_str(&serialized).expect("reparse");
+        assert_eq!(reparsed.devices[0].token, "ExponentPushToken[one]");
+        assert!(!reparsed.devices[0].events.approval_requested);
+    }
+
+    #[tokio::test]
+    async fn push_service_registers_dedupes_and_unregisters() {
+        let dir = std::env::temp_dir().join(format!("clawdex-push-test-{}", std::process::id()));
+        let _ = tokio::fs::create_dir_all(&dir).await;
+        let service = PushService::load(&dir, "demo".to_string()).await;
+
+        let prefs = PushEventPreferences::default();
+        let count = service
+            .register(
+                "ExponentPushToken[a]".to_string(),
+                "ios".to_string(),
+                "Phone".to_string(),
+                prefs.clone(),
+            )
+            .await;
+        assert_eq!(count, 1);
+
+        // Re-registering the same token updates in place rather than duplicating.
+        let count = service
+            .register(
+                "ExponentPushToken[a]".to_string(),
+                "ios".to_string(),
+                "Phone Renamed".to_string(),
+                prefs,
+            )
+            .await;
+        assert_eq!(count, 1);
+
+        let listed = service.list().await;
+        assert_eq!(listed.len(), 1);
+        assert_eq!(
+            listed[0].get("deviceName").and_then(Value::as_str),
+            Some("Phone Renamed")
+        );
+        // Full tokens are never echoed back.
+        assert!(listed[0].get("token").is_none());
+
+        assert!(service.unregister("ExponentPushToken[a]").await);
+        assert!(!service.unregister("ExponentPushToken[a]").await);
+        assert!(service.list().await.is_empty());
+
+        let _ = tokio::fs::remove_dir_all(&dir).await;
+    }
+
     fn bridge_chatgpt_auth_test_lock() -> &'static std::sync::Mutex<()> {
         static LOCK: OnceLock<std::sync::Mutex<()>> = OnceLock::new();
         LOCK.get_or_init(|| std::sync::Mutex::new(()))
@@ -14208,6 +14939,7 @@ mod tests {
             config.preview_connect_url.clone(),
         ));
         let queue = BridgeQueueService::new(backend.clone(), hub.clone());
+        let push = PushService::load(&config.workdir, "Clawdex".to_string()).await;
 
         Arc::new(AppState {
             config,
@@ -14220,6 +14952,7 @@ mod tests {
             git,
             updater,
             preview,
+            push,
         })
     }