@kraki/head 0.14.4 → 0.15.0

package/dist/server.js

@@ -1,6 +1,8 @@
 import { WebSocketServer, WebSocket } from 'ws';
 import { randomBytes, createVerify } from 'crypto';
 import { v4 as uuid } from 'uuid';
+import { HEAD_PULSE_TARGET } from '@kraki/protocol';
+import { PulseHub } from './pulse-hub.js';
 import { GitHubAuthProvider } from './auth.js';
 import { getLogger } from './logger.js';
 function importPublicKey(compactKey) {
@@ -17,17 +19,10 @@ const DEFAULT_VOICE_LEASE_QUOTA_SEC = 7_200;
 const DEFAULT_VOICE_DAILY_QUOTA_SEC = 7_200;
 const VALID_VOICE_RESOURCES = new Set(['voice/doubao']);
 const DEFAULT_MAX_PAYLOAD = 10 * 1024 * 1024;
-// ── Delivery assurance tuning ──────────────────────────────
-/** Max in-flight (unacked) messages per connection before forcing reconnect. */
-const MAX_IN_FLIGHT = 200;
-/** How long to wait for an ack before re-sending a message (ms). */
-const RETRY_AFTER_MS = 5_000;
-/** Max retries before closing the connection (forces clean reconnect). */
-const MAX_RETRIES = 3;
-/** How often the retry pass runs (ms). Independent of the slower 30s ping timer
- *  so detection latency tracks the recipient's ping cadence (~10s), not the
- *  liveness check cadence. */
-const RETRY_CHECK_INTERVAL_MS = 2_500;
+/** How often the liveness sweep runs (ms). Faster than the 30s ping timer so
+ *  device_pending detection latency tracks the recipient's ping cadence
+ *  (~10s), not the slower liveness check cadence. */
+const LIVENESS_SWEEP_INTERVAL_MS = 2_500;
 /** Grace period after ping before broadcasting device_pending (ms).
  *  Overridable via PONG_GRACE_MS environment variable. */
 const PONG_GRACE_MS = Math.max(1_000, parseInt(process.env.PONG_GRACE_MS ?? '8000', 10) || 8_000);
@@ -52,14 +47,6 @@ function isValidAuth(msg) {
         return false;
     return true;
 }
-function isValidUnicast(msg) {
-    return msg.type === 'unicast' && typeof msg.to === 'string'
-        && typeof msg.blob === 'string' && typeof msg.keys === 'object' && msg.keys !== null;
-}
-function isValidBroadcast(msg) {
-    return msg.type === 'broadcast'
-        && typeof msg.blob === 'string' && typeof msg.keys === 'object' && msg.keys !== null;
-}
 export class HeadServer {
     wss;
     storage;
@@ -71,7 +58,10 @@ export class HeadServer {
     userByDevice = new Map();
     clients = new Map();
     pingTimer = null;
-    retryTimer = null;
+    livenessTimer = null;
+    /** Per-hop pulse hub — the reliable-delivery layer for every connection. */
+    pulseHub;
+    pulseTickTimer = null;
     constructor(storage, options) {
         this.storage = storage;
         this.options = options;
@@ -81,12 +71,17 @@ export class HeadServer {
         });
         this.wss.on('connection', (ws, req) => this.onConnection(ws, req));
         this.startPingInterval();
-        this.startRetryInterval();
-        // Expire old pending messages on startup
-        const expired = this.storage.expirePending();
-        if (expired > 0) {
-            getLogger().info('Expired pending messages on startup', { count: expired });
-        }
+        this.startLivenessSweep();
+        // Pulse per-hop reliable delivery. Shares the Storage SQLite file.
+        this.pulseHub = new PulseHub(this.storage.rawDb, {
+            now: () => Date.now(),
+            sendPulseTo: (deviceId, pulseB64) => this.sendPulseFrameTo(deviceId, pulseB64),
+            broadcastTargets: (fromDevice) => this.pulseBroadcastTargets(fromDevice),
+            onDeliverToSelf: (fromDevice, payload) => this.deliverPulseToSelf(fromDevice, payload),
+        });
+        this.pulseHub.recoverOnBoot();
+        // Drive pulse heartbeat/liveness/durable-expiry every 5s.
+        this.pulseTickTimer = setInterval(() => this.pulseHub.tick(), 5_000);
     }
     startPingInterval() {
         this.pingTimer = setInterval(() => {
@@ -110,13 +105,8 @@ export class HeadServer {
                 try {
                     if (ws.readyState === WebSocket.OPEN) {
                         ws.ping(); // protocol-level ping (browsers auto-respond)
-                        // JSON ping for proxy keepalive — include ack so the peer can
-                        // prune its in-flight buffer even when no other traffic flows.
-                        const pingMsg = { type: 'ping' };
-                        if (state && state.lastReceivedRelaySeq > 0) {
-                            pingMsg.ack = state.lastReceivedRelaySeq;
-                        }
-                        ws.send(JSON.stringify(pingMsg));
+                        // JSON ping for proxy keepalive.
+                        ws.send(JSON.stringify({ type: 'ping' }));
                         if (state) {
                             state.pongOverdueAt = now + PONG_GRACE_MS;
                             state.pendingLivenessBroadcast = false;
@@ -143,178 +133,19 @@ export class HeadServer {
             }
         }, HeadServer.PING_INTERVAL);
     }
-    // ── Delivery assurance ───────────────────────────────────
-    /** Run the retry pass at a fixed cadence, independent of the slower liveness
-     *  ping. Detection latency for a dropped message is bounded by the recipient's
-     *  ping cadence (~10s) + this interval. */
-    startRetryInterval() {
-        this.retryTimer = setInterval(() => {
-            this.runRetryPass();
-        }, RETRY_CHECK_INTERVAL_MS);
+    // ── Liveness sweep ───────────────────────────────────────
+    /** Run the liveness sweep at a fixed cadence, independent of the slower
+     *  30s ping timer. Broadcasts device_pending when a peer's pong is overdue
+     *  so other devices see the "maybe offline" state quickly. */
+    startLivenessSweep() {
+        this.livenessTimer = setInterval(() => {
+            this.runLivenessSweep();
+        }, LIVENESS_SWEEP_INTERVAL_MS);
     }
-    /** Stamp a message with relaySeq, buffer for retry, and send. Use this for
-     *  any post-auth message head expects the peer to receive reliably. Skip for
-     *  pings, pongs, errors, and pre-auth handshake messages.
-     *
-     *  If the message has incoming `relaySeq`/`ack` fields from another hop
-     *  (e.g. a forwarded unicast/broadcast), they are stripped — these are
-     *  per-hop and not end-to-end. */
-    trackedSend(ws, state, msg) {
-        if (ws.readyState !== WebSocket.OPEN)
-            return;
-        state.relaySeqCounter += 1;
-        const relaySeq = state.relaySeqCounter;
-        // Strip any per-hop tracking fields from the source message, then stamp ours.
-        const { relaySeq: _ignoredSeq, ack: _ignoredAck, ...rest } = msg;
-        const stamped = { ...rest, relaySeq };
-        // Piggyback our own ack of what we've received from this peer on this connection.
-        if (state.lastReceivedRelaySeq > 0) {
-            stamped.ack = state.lastReceivedRelaySeq;
-        }
-        const payload = JSON.stringify(stamped);
-        // Buffer full: evict the oldest entry silently and continue.
-        // Connection is NOT killed — peer may simply be temporarily throttled
-        // (e.g. backgrounded browser tab). The 30s protocol-level ping/pong is
-        // the source of truth for liveness, not delivery exhaustion.
-        if (state.inFlight.length >= MAX_IN_FLIGHT) {
-            getLogger().warn('In-flight buffer full, evicting oldest entry', {
-                deviceId: state.deviceId,
-                inFlight: state.inFlight.length,
-            });
-            state.inFlight.shift();
-        }
-        state.inFlight.push({
-            relaySeq,
-            payload,
-            sentAt: Date.now(),
-            retries: 0,
-        });
-        try {
-            ws.send(payload);
-        }
-        catch {
-            // Send failed — connection is likely dead. Drop the connection so
-            // the client can reconnect cleanly. Retry pass will not re-send to
-            // a dead connection.
-            if (state.deviceId)
-                this.removeConnection(state.deviceId);
-        }
-    }
-    /** Track an incoming relaySeq from peer. Returns true if message is a
-     *  duplicate that should be dropped silently. */
-    trackInboundRelaySeq(state, msg) {
-        if (!('relaySeq' in msg))
-            return false;
-        const seq = msg.relaySeq;
-        if (typeof seq !== 'number' || !Number.isFinite(seq) || seq <= 0)
-            return false;
-        if (state.seenRelaySeqs.has(seq)) {
-            return true; // duplicate
-        }
-        // Bound the set so it doesn't grow unbounded. Drop the oldest tracked
-        // ack window when full — at this point any duplicate older than the
-        // window would have been delivered long ago.
-        if (state.seenRelaySeqs.size >= MAX_IN_FLIGHT) {
-            const iter = state.seenRelaySeqs.values().next();
-            if (!iter.done)
-                state.seenRelaySeqs.delete(iter.value);
-        }
-        state.seenRelaySeqs.add(seq);
-        if (seq > state.lastReceivedRelaySeq) {
-            state.lastReceivedRelaySeq = seq;
-        }
-        return false;
-    }
-    /** Process an incoming ack field from any message type. Prunes the in-flight
-     *  buffer and flips ackSupported on first sighting. */
-    processAck(state, msg) {
-        if (!('ack' in msg))
-            return;
-        const ack = msg.ack;
-        if (typeof ack !== 'number' || !Number.isFinite(ack))
-            return;
-        // Presence of the field at all marks the peer as ack-capable, even if
-        // ack: 0. Once flipped, it stays true for the lifetime of the connection.
-        state.ackSupported = true;
-        if (ack > state.lastAckedSeq) {
-            state.lastAckedSeq = ack;
-            // Prune everything ≤ ack from the in-flight buffer.
-            if (state.inFlight.length > 0) {
-                let firstUnacked = 0;
-                while (firstUnacked < state.inFlight.length && state.inFlight[firstUnacked].relaySeq <= ack) {
-                    firstUnacked += 1;
-                }
-                if (firstUnacked > 0) {
-                    state.inFlight.splice(0, firstUnacked);
-                }
-            }
-        }
-    }
-    /** Walk all connections; re-send unacked messages that have aged past
-     *  RETRY_AFTER_MS. When MAX_RETRIES is exceeded, mark the entry giveUp
-     *  but keep the connection alive — liveness is decided by the 30s
-     *  protocol-level ping/pong, not by delivery-retry exhaustion. */
-    runRetryPass() {
-        const logger = getLogger();
+    /** Broadcast device_pending for any authenticated connection whose pong has
+     *  gone overdue (and we haven't already broadcast for this ping cycle). */
+    runLivenessSweep() {
         const now = Date.now();
-        for (const [deviceId, ws] of this.connections) {
-            const state = this.clients.get(ws);
-            if (!state)
-                continue;
-            if (!state.ackSupported)
-                continue; // Old client — skip retry
-            if (state.inFlight.length === 0)
-                continue;
-            if (ws.readyState !== WebSocket.OPEN)
-                continue;
-            state.lastRetryAt = now;
-            let sendFailed = false;
-            for (const entry of state.inFlight) {
-                if (entry.giveUp)
-                    continue;
-                // Already acked? (Shouldn't normally happen — processAck prunes —
-                // but guard against races.)
-                if (entry.relaySeq <= state.lastAckedSeq)
-                    continue;
-                if (now - entry.sentAt < RETRY_AFTER_MS)
-                    continue;
-                if (entry.retries >= MAX_RETRIES) {
-                    // Give up retrying this entry. Don't kill the connection — the
-                    // peer may just be temporarily throttled (e.g. backgrounded
-                    // browser tab). If the peer later catches up and acks, this
-                    // entry is pruned normally. If the bytes were truly lost, the
-                    // application layer's per-session replay handles content recovery.
-                    logger.debug('Giving up retries for entry', {
-                        deviceId,
-                        relaySeq: entry.relaySeq,
-                        retries: entry.retries,
-                    });
-                    entry.giveUp = true;
-                    continue;
-                }
-                entry.retries += 1;
-                entry.sentAt = now;
-                try {
-                    ws.send(entry.payload);
-                    logger.debug('Retried unacked message', {
-                        deviceId,
-                        relaySeq: entry.relaySeq,
-                        attempt: entry.retries,
-                    });
-                }
-                catch {
-                    // ws.send threw — the underlying socket is dead. Close it so the
-                    // close handler can clean up. This is a transport failure, not a
-                    // delivery-retry failure.
-                    sendFailed = true;
-                    break;
-                }
-            }
-            if (sendFailed) {
-                this.removeConnection(deviceId);
-            }
-        }
-        // ── Liveness uncertainty: broadcast device_pending when pong is overdue ──
         for (const [deviceId, ws] of this.connections) {
             const state = this.clients.get(ws);
             if (!state?.authenticated || !state.userId)
@@ -330,7 +161,11 @@ export class HeadServer {
             this.broadcastDevicePending(state.userId, deviceId);
         }
     }
-    // ── End delivery assurance ──────────────────────────────
+    /** Test hook: force a liveness sweep without waiting for the timer. */
+    forceLivenessSweep() {
+        this.runLivenessSweep();
+    }
+    // ── End liveness sweep ──────────────────────────────────
     // --- Auth provider helpers ---
     getAuthProvider() {
         if (this.options.authProviders?.size) {
@@ -399,12 +234,6 @@ export class HeadServer {
             ip,
             pongOverdueAt: null,
             pendingLivenessBroadcast: false,
-            relaySeqCounter: 0,
-            inFlight: [],
-            lastAckedSeq: 0,
-            ackSupported: false,
-            lastReceivedRelaySeq: 0,
-            seenRelaySeqs: new Set(),
         };
         const logger = getLogger();
         this.clients.set(ws, state);
@@ -440,6 +269,7 @@ export class HeadServer {
                     catch { /* storage may be closed */ }
                     this.connections.delete(disconnectedDeviceId);
                     this.userByDevice.delete(disconnectedDeviceId);
+                    this.pulseHub.onDeviceDisconnected(disconnectedDeviceId);
                     logger.info('Device disconnected', {
                         deviceId: disconnectedDeviceId,
                         closeCode: code,
@@ -473,13 +303,6 @@ export class HeadServer {
         });
     }
     async onMessage(ws, state, msg) {
-        // Process ack field on every incoming message (post or pre-auth, doesn't matter —
-        // ack just prunes our outbound buffer for this peer).
-        this.processAck(state, msg);
-        // Track inbound relaySeq for sending acks back. Duplicates are dropped silently.
-        if (this.trackInboundRelaySeq(state, msg)) {
-            return;
-        }
         // One-shot pairing token request — before auth
         if (msg.type === 'request_pairing_token') {
             await this.handleRequestPairingToken(ws, state, msg);
@@ -542,78 +365,43 @@ export class HeadServer {
             return;
         }
         if (msg.type === 'unicast') {
-            if (!isValidUnicast(msg)) {
-                this.sendError(ws, 'Invalid unicast: to, blob, keys required');
+            // The hub (a pulse endpoint on each hop) handles reliable delivery + durable
+            // store-and-forward. The envelope MUST carry a pulse frame — the head is
+            // pulse-only; there is no raw-WS relay path.
+            if (typeof msg.pulse === 'string' && state.deviceId) {
+                this.pulseHub.onPulseEnvelope(state.deviceId, {
+                    pulse: msg.pulse,
+                    to: msg.to,
+                });
                 return;
             }
-            this.handleUnicast(ws, state, msg);
+            this.sendError(ws, 'unicast requires a pulse frame');
             return;
         }
         if (msg.type === 'broadcast') {
-            if (!isValidBroadcast(msg)) {
-                this.sendError(ws, 'Invalid broadcast: blob, keys required');
+            // Pulse broadcast frames (control: hello/ack/heartbeat) are addressed to a
+            // specific hop via the hub too; a producer fans out per-device unicasts.
+            if (typeof msg.pulse === 'string' && state.deviceId) {
+                // A pushPreview may ride the same pulse envelope — fire it for offline
+                // devices (the reliable message itself is delivered by the hub).
+                if (msg.pushPreview)
+                    this.firePushPreview(state, msg.pushPreview);
+                this.pulseHub.onPulseEnvelope(state.deviceId, { pulse: msg.pulse });
                 return;
             }
-            this.handleBroadcast(state, msg);
-            return;
-        }
-        if (msg.type === 'update_preferences') {
-            if (state.userId) {
-                const prefs = msg.preferences;
-                if (prefs && typeof prefs === 'object') {
-                    this.storage.updatePreferences(state.userId, prefs);
-                    // Read back the full merged preferences
-                    const fullUser = this.storage.getUser(state.userId);
-                    const merged = fullUser?.preferences ?? prefs;
-                    const confirmation = { type: 'preferences_updated', preferences: merged };
-                    // Send confirmation to sender (tracked — peer should see it)
-                    this.trackedSend(ws, state, confirmation);
-                    // Broadcast to all other devices of the same user
-                    const userDevices = (() => {
-                        try {
-                            return this.storage.getDevicesByUser(state.userId);
-                        }
-                        catch {
-                            return [];
-                        }
-                    })();
-                    for (const d of userDevices) {
-                        if (d.id === state.deviceId)
-                            continue;
-                        const other = this.connections.get(d.id);
-                        if (!other || other.readyState !== WebSocket.OPEN)
-                            continue;
-                        const otherState = this.clients.get(other);
-                        if (!otherState)
-                            continue;
-                        this.trackedSend(other, otherState, confirmation);
-                    }
-                }
-            }
-            return;
-        }
-        if (msg.type === 'remove_device') {
-            this.handleRemoveDevice(ws, state, msg.deviceId);
-            return;
-        }
-        if (msg.type === 'register_push_token') {
-            this.handleRegisterPushToken(ws, state, msg);
+            this.sendError(ws, 'broadcast requires a pulse frame');
             return;
         }
-        if (msg.type === 'unregister_push_token') {
-            this.handleUnregisterPushToken(ws, state, msg);
+        // Relay-terminated control ops (update_preferences / remove_device /
+        // (un)register_push_token). Arrive via pulse deliver-to-self (deliverPulseToSelf).
+        if (this.handleControlMessage(ws, state, msg))
             return;
-        }
         if (msg.type === 'request_voice_lease') {
             this.handleRequestVoiceLease(ws, state, msg);
             return;
         }
         if (msg.type === 'ping') {
-            const pongMsg = { type: 'pong' };
-            if (state.lastReceivedRelaySeq > 0) {
-                pongMsg.ack = state.lastReceivedRelaySeq;
-            }
-            ws.send(JSON.stringify(pongMsg));
+            ws.send(JSON.stringify({ type: 'pong' }));
             return;
         }
         if (msg.type === 'pong') {
@@ -637,39 +425,39 @@ export class HeadServer {
         }
         const issuer = this.options.leaseIssuer;
         if (!issuer) {
-            ws.send(JSON.stringify({
+            this.sendControlToDevice(deviceId, {
                 type: 'voice_lease_denied',
                 reason: 'not_entitled',
                 detail: 'Voice lease issuance is not enabled on this head',
-            }));
+            });
             return;
         }
         // Validate request shape.
         const requestedDeviceId = typeof msg.deviceId === 'string' ? msg.deviceId : undefined;
         const requestedResource = typeof msg.resource === 'string' ? msg.resource : undefined;
         if (!requestedDeviceId || !requestedResource) {
-            ws.send(JSON.stringify({
+            this.sendControlToDevice(deviceId, {
                 type: 'voice_lease_denied',
                 reason: 'invalid_request',
                 detail: 'Missing deviceId or resource',
-            }));
+            });
             return;
         }
         // Lease may only be requested for the authenticated device — no proxying.
         if (requestedDeviceId !== deviceId) {
-            ws.send(JSON.stringify({
+            this.sendControlToDevice(deviceId, {
                 type: 'voice_lease_denied',
                 reason: 'invalid_request',
                 detail: 'deviceId does not match authenticated device',
-            }));
+            });
             return;
         }
         if (!VALID_VOICE_RESOURCES.has(requestedResource)) {
-            ws.send(JSON.stringify({
+            this.sendControlToDevice(deviceId, {
                 type: 'voice_lease_denied',
                 reason: 'invalid_request',
                 detail: `Unknown resource: ${String(requestedResource)}`,
-            }));
+            });
             return;
         }
         const ttl = this.options.voiceLeaseTtlSec ?? DEFAULT_VOICE_LEASE_TTL_SEC;
@@ -681,11 +469,11 @@ export class HeadServer {
             logger.info('Voice lease denied: daily quota exhausted', {
                 userId, deviceId, issuedToday, quotaPerLease, dailyCap,
             });
-            ws.send(JSON.stringify({
+            this.sendControlToDevice(deviceId, {
                 type: 'voice_lease_denied',
                 reason: 'quota_exhausted',
                 detail: `Daily quota reached (${issuedToday}/${dailyCap}s)`,
-            }));
+            });
             return;
         }
         const lease = issuer.issue({
@@ -711,74 +499,149 @@ export class HeadServer {
             logger.error('Voice lease persist failed', {
                 userId, deviceId, jti: lease.payload.jti, error: err.message,
             });
-            ws.send(JSON.stringify({
+            this.sendControlToDevice(deviceId, {
                 type: 'voice_lease_denied',
                 reason: 'invalid_request',
                 detail: 'Lease persistence failed',
-            }));
+            });
             return;
         }
         logger.info('Voice lease issued', {
             userId, deviceId, jti: lease.payload.jti,
             quotaSeconds: quotaPerLease, ttlSec: ttl,
         });
-        ws.send(JSON.stringify({ type: 'voice_lease_grant', lease }));
+        this.sendControlToDevice(deviceId, { type: 'voice_lease_grant', lease });
     }
     // --- Routing ---
-    handleUnicast(ws, state, msg) {
-        const logger = getLogger();
-        const senderUserId = state.userId;
-        if (!senderUserId || !state.deviceId)
-            return;
-        // Verify target belongs to same user
-        const targetDevice = this.storage.getDevice(msg.to);
-        if (!targetDevice || targetDevice.userId !== senderUserId) {
-            logger.warn('Unicast rejected: target not found or wrong user', { from: state.deviceId, to: msg.to });
-            ws.send(JSON.stringify({ type: 'server_error', message: 'Target device not found or offline', ref: msg.ref }));
+    /** Send a pulse frame (control or forwarded data) to a device's socket, as a
+     *  minimal unicast envelope carrying only the `pulse` field. Returns true if
+     *  the device is online. Used by the PulseHub to reach endpoints. */
+    sendPulseFrameTo(deviceId, pulseB64) {
+        const ws = this.connections.get(deviceId);
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return false;
+        // `to` lets the receiver's own pulse layer know which stream this is; blob
+        // is empty because the payload (if any) is inside the pulse frame.
+        ws.send(JSON.stringify({ type: 'unicast', to: deviceId, pulse: pulseB64, blob: '', keys: {} }));
+        return true;
+    }
+    /** Send a head-ORIGINATED control message to a device reliably over pulse
+     *  (presence, preferences confirmation, voice responses). These are plaintext
+     *  head↔device control (the head has no E2E on them), so the payload is
+     *  wrapped as `{from:'@head', msg}` — the receiver's pulse layer recognizes the
+     *  `@head` marker and dispatches `msg` WITHOUT decrypting. Non-durable:
+     *  presence/prefs are ephemeral. */
+    sendControlToDevice(deviceId, msg) {
+        const payload = Buffer.from(JSON.stringify({ from: HEAD_PULSE_TARGET, msg }), 'utf8');
+        this.pulseHub.sendToDevice(deviceId, new Uint8Array(payload));
+    }
+    /** A pulse frame addressed to HEAD_PULSE_TARGET was delivered in-order by the
+     *  source device's endpoint. The payload is PLAINTEXT control JSON. Resolve the
+     *  originating authenticated connection and route it through the SAME control
+     *  handlers the raw-WS path uses, so auth context (state.userId/deviceId) and
+     *  responses (over ws) are identical. */
+    deliverPulseToSelf(fromDevice, payload) {
+        const ws = this.connections.get(fromDevice);
+        if (!ws)
+            return; // device vanished — the control op is moot
+        const state = this.clients.get(ws);
+        if (!state?.authenticated)
             return;
+        let msg;
+        try {
+            const parsed = JSON.parse(Buffer.from(payload).toString('utf8'));
+            if (!isValidMessage(parsed))
+                return;
+            msg = parsed;
         }
-        const targetWs = this.connections.get(msg.to);
-        if (!targetWs) {
-            // Target offline — queue for delivery on reconnect.
-            // Strip per-hop tracking fields before persisting so the queued payload
-            // doesn't carry stale relaySeq/ack from this sender→head hop.
-            const { relaySeq: _s, ack: _a, ...clean } = msg;
-            this.storage.insertPending(msg.to, senderUserId, JSON.stringify(clean));
-            logger.debug('Unicast queued for offline device', { from: state.deviceId, to: msg.to });
-            return;
+        catch {
+            return; // malformed → drop
         }
-        const targetState = this.clients.get(targetWs);
-        if (!targetState)
-            return;
-        // Forward via tracked path so we retry if the recipient doesn't ack.
-        this.trackedSend(targetWs, targetState, msg);
+        // handleControlMessage whitelists the 4 relay-terminated types and returns
+        // false for anything else, so the self-channel cannot tunnel unicast/auth/etc.
+        this.handleControlMessage(ws, state, msg);
     }
-    handleBroadcast(state, msg) {
-        const logger = getLogger();
+    /** The relay-terminated control ops, callable from BOTH the raw-WS dispatch
+     *  (onMessage) and the pulse deliver-to-self path. Returns true if handled. */
+    handleControlMessage(ws, state, msg) {
+        switch (msg.type) {
+            case 'update_preferences':
+                this.handleUpdatePreferences(ws, state, msg);
+                return true;
+            case 'remove_device':
+                this.handleRemoveDevice(ws, state, msg.deviceId);
+                return true;
+            case 'register_push_token':
+                this.handleRegisterPushToken(ws, state, msg);
+                return true;
+            case 'unregister_push_token':
+                this.handleUnregisterPushToken(ws, state, msg);
+                return true;
+            default: return false;
+        }
+    }
+    /** Persist a preferences update and echo the merged result to the sender + the
+     *  user's other online devices. */
+    handleUpdatePreferences(ws, state, msg) {
+        if (!state.userId)
+            return;
+        const prefs = msg.preferences;
+        if (!prefs || typeof prefs !== 'object')
+            return;
+        this.storage.updatePreferences(state.userId, prefs);
+        // Read back the full merged preferences
+        const fullUser = this.storage.getUser(state.userId);
+        const merged = fullUser?.preferences ?? prefs;
+        const confirmation = { type: 'preferences_updated', preferences: merged };
+        // Confirm to the sender + fan out to the user's other devices — all over pulse.
+        if (state.deviceId)
+            this.sendControlToDevice(state.deviceId, confirmation);
+        const userDevices = (() => {
+            try {
+                return this.storage.getDevicesByUser(state.userId);
+            }
+            catch {
+                return [];
+            }
+        })();
+        for (const d of userDevices) {
+            if (d.id === state.deviceId)
+                continue;
+            const other = this.connections.get(d.id);
+            if (!other || other.readyState !== WebSocket.OPEN)
+                continue;
+            this.sendControlToDevice(d.id, confirmation);
+        }
+    }
+    /** Fan-out targets for a pulse broadcast from `fromDevice`: all OTHER devices
+     *  of the same user (the online ones the hub can forward to). */
+    pulseBroadcastTargets(fromDevice) {
+        const userId = this.userByDevice.get(fromDevice);
+        if (!userId)
+            return [];
+        const targets = [];
+        for (const device of this.storage.getDevicesByUser(userId)) {
+            if (device.id !== fromDevice)
+                targets.push(device.id);
+        }
+        return targets;
+    }
+    /** Notify offline devices from a pushPreview side-channel. The preview rides the
+     *  same pulse broadcast envelope as the reliable message. */
+    firePushPreview(state, pushPreview) {
         const senderUserId = state.userId;
         const senderDeviceId = state.deviceId;
-        if (!senderUserId || !senderDeviceId)
+        if (!senderUserId || !senderDeviceId || !pushPreview || !this.options.pushManager)
             return;
-        // Find all other connected devices for this user
-        const userDevices = this.storage.getDevicesByUser(senderUserId);
         const onlineDeviceIds = [senderDeviceId];
-        for (const device of userDevices) {
+        for (const device of this.storage.getDevicesByUser(senderUserId)) {
             if (device.id === senderDeviceId)
                 continue;
-            const targetWs = this.connections.get(device.id);
-            if (!targetWs)
-                continue;
-            onlineDeviceIds.push(device.id);
-            const targetState = this.clients.get(targetWs);
-            if (!targetState)
-                continue;
-            this.trackedSend(targetWs, targetState, msg);
-        }
-        // Send push notifications to offline devices with registered tokens
-        if (msg.pushPreview && this.options.pushManager) {
-            this.options.pushManager.sendToOfflineDevices(senderUserId, onlineDeviceIds, msg.pushPreview)
-                .catch(err => logger.warn('Push notification send failed', { error: err.message }));
+            if (this.connections.get(device.id))
+                onlineDeviceIds.push(device.id);
         }
+        this.options.pushManager.sendToOfflineDevices(senderUserId, onlineDeviceIds, pushPreview)
+            .catch(err => getLogger().warn('Push notification send failed', { error: err.message }));
     }
     removeConnection(deviceId) {
         const ws = this.connections.get(deviceId);
@@ -984,6 +847,7 @@ export class HeadServer {
         state.userId = user.userId;
         this.connections.set(deviceId, ws);
         this.userByDevice.set(deviceId, user.userId);
+        this.pulseHub.onDeviceConnected(deviceId);
         logger.info('Device authenticated via challenge-response', { deviceId, ip: state.ip });
         this.completeAuthHandshake(ws, {
             deviceId,
@@ -1016,6 +880,7 @@ export class HeadServer {
         state.userId = result.userId;
         this.connections.set(result.deviceId, ws);
         this.userByDevice.set(result.deviceId, result.userId);
+        this.pulseHub.onDeviceConnected(result.deviceId);
         logger.info('Device authenticated (via backend)', {
             deviceId: result.deviceId,
             user: result.user.login,
@@ -1045,7 +910,6 @@ export class HeadServer {
             user: result.user,
             authMethod: result.authMethod,
             devices: result.devices,
-            backendPendingMessages: result.pendingMessages,
             githubClientId: result.githubClientId,
             vapidPublicKey: result.vapidPublicKey,
         });
@@ -1084,15 +948,6 @@ export class HeadServer {
             ...params.user,
             preferences: fullUser?.preferences ?? params.user.preferences,
         };
-        // Flush locally-queued pending messages — every auth path that lands here
-        // means a device is reconnecting, and any unicasts queued for it locally
-        // (via handleUnicast → storage.insertPending) should be delivered now.
-        // Combined with whatever the remote backend forwarded, if applicable.
-        const localPending = this.flushPendingEnvelopes(params.deviceId);
-        const pendingMessages = [
-            ...(params.backendPendingMessages ?? []),
-            ...localPending,
-        ];
         // Devices list. If the caller provided one (edge mode), recompute online
         // status against our current connections map. Otherwise derive locally.
         const devices = params.devices
@@ -1107,7 +962,6 @@ export class HeadServer {
             githubClientId: params.githubClientId ?? this.getGitHubClientId(),
             vapidPublicKey: params.vapidPublicKey ?? this.getVapidPublicKey(),
             relayVersion: this.options.version,
-            ...(pendingMessages.length > 0 && { pendingMessages }),
             ...(this.getVoiceCapability() && { voice: this.getVoiceCapability() }),
         }));
         this.broadcastDeviceJoined(params.userId, params.deviceId);
@@ -1132,6 +986,7 @@ export class HeadServer {
         state.userId = user.id;
         this.connections.set(deviceId, ws);
         this.userByDevice.set(deviceId, user.id);
+        this.pulseHub.onDeviceConnected(deviceId);
         logger.info('Device authenticated', {
             deviceId,
             name: msg.device.name,
@@ -1262,7 +1117,6 @@ export class HeadServer {
             return;
         }
         this.storage.deleteDevice(targetDeviceId);
-        this.storage.deletePendingForDevice(targetDeviceId);
         this.storage.deletePushTokensForDevice(targetDeviceId);
         logger.info('Device removed', { deviceId: targetDeviceId, byDevice: state.deviceId });
         // Broadcast removal to all remaining user devices
@@ -1289,7 +1143,9 @@ export class HeadServer {
             logger.info('Pruned stale push tokens', { userId: state.userId, count: pruned });
         }
         logger.info('Push token registered', { deviceId: state.deviceId, provider: payload.provider });
-        ws.send(JSON.stringify({ type: 'push_token_registered', payload: { provider: payload.provider } }));
+        if (state.deviceId) {
+            this.sendControlToDevice(state.deviceId, { type: 'push_token_registered', payload: { provider: payload.provider } });
+        }
     }
     handleUnregisterPushToken(ws, state, msg) {
         const logger = getLogger();
@@ -1317,10 +1173,7 @@ export class HeadServer {
             const ws = this.connections.get(d.id);
             if (!ws || ws.readyState !== WebSocket.OPEN)
                 continue;
-            const targetState = this.clients.get(ws);
-            if (!targetState)
-                continue;
-            this.trackedSend(ws, targetState, { type: 'device_removed', deviceId: removedDeviceId });
+            this.sendControlToDevice(d.id, { type: 'device_removed', deviceId: removedDeviceId });
         }
     }
     broadcastDeviceJoined(userId, newDeviceId) {
@@ -1357,10 +1210,7 @@ export class HeadServer {
             const ws = this.connections.get(d.id);
             if (!ws || ws.readyState !== WebSocket.OPEN)
                 continue;
-            const targetState = this.clients.get(ws);
-            if (!targetState)
-                continue;
-            this.trackedSend(ws, targetState, { type: 'device_joined', device: summary });
+            this.sendControlToDevice(d.id, { type: 'device_joined', device: summary });
         }
     }
     broadcastDeviceLeft(userId, leftDeviceId) {
@@ -1377,10 +1227,7 @@ export class HeadServer {
             const ws = this.connections.get(d.id);
             if (!ws || ws.readyState !== WebSocket.OPEN)
                 continue;
-            const targetState = this.clients.get(ws);
-            if (!targetState)
-                continue;
-            this.trackedSend(ws, targetState, { type: 'device_left', deviceId: leftDeviceId });
+            this.sendControlToDevice(d.id, { type: 'device_left', deviceId: leftDeviceId });
         }
     }
     broadcastDevicePending(userId, pendingDeviceId) {
@@ -1397,10 +1244,7 @@ export class HeadServer {
             const ws = this.connections.get(d.id);
             if (!ws || ws.readyState !== WebSocket.OPEN)
                 continue;
-            const targetState = this.clients.get(ws);
-            if (!targetState)
-                continue;
-            this.trackedSend(ws, targetState, { type: 'device_pending', deviceId: pendingDeviceId });
+            this.sendControlToDevice(d.id, { type: 'device_pending', deviceId: pendingDeviceId });
         }
     }
     /** Handle pong from either protocol-level or JSON pong.
@@ -1448,24 +1292,6 @@ export class HeadServer {
             ws.send(JSON.stringify({ type: 'server_error', message }));
         }
     }
-    /** Flush pending messages from SQLite, parse into envelope objects. */
-    flushPendingEnvelopes(deviceId) {
-        const logger = getLogger();
-        const rows = this.storage.flushPending(deviceId);
-        if (rows.length === 0)
-            return [];
-        const envelopes = [];
-        for (const raw of rows) {
-            try {
-                envelopes.push(JSON.parse(raw));
-            }
-            catch {
-                logger.warn('Failed to parse pending message', { deviceId });
-            }
-        }
-        logger.info('Flushed pending messages', { deviceId, count: envelopes.length });
-        return envelopes;
-    }
     getStats() {
         const onlineUserIds = new Set();
         const connectionList = [];
@@ -1521,27 +1347,6 @@ export class HeadServer {
             registeredUsers,
         };
     }
-    /** Test hook: inspect delivery state for an online device. Not used in prod. */
-    getDeliveryState(deviceId) {
-        const ws = this.connections.get(deviceId);
-        if (!ws)
-            return undefined;
-        const state = this.clients.get(ws);
-        if (!state)
-            return undefined;
-        return {
-            inFlightCount: state.inFlight.length,
-            givenUpCount: state.inFlight.filter(e => e.giveUp).length,
-            relaySeqCounter: state.relaySeqCounter,
-            lastAckedSeq: state.lastAckedSeq,
-            ackSupported: state.ackSupported,
-            lastReceivedRelaySeq: state.lastReceivedRelaySeq,
-        };
-    }
-    /** Test hook: force a retry pass without waiting for the timer. */
-    forceRetryPass() {
-        this.runRetryPass();
-    }
     /** Test hook: run the ping pass (set isAlive=false, send ping, start grace timer). */
     forcePingPass() {
         for (const [deviceId, ws] of this.connections) {
@@ -1556,11 +1361,7 @@ export class HeadServer {
             try {
                 if (ws.readyState === WebSocket.OPEN) {
                     ws.ping();
-                    const pingMsg = { type: 'ping' };
-                    if (state && state.lastReceivedRelaySeq > 0) {
-                        pingMsg.ack = state.lastReceivedRelaySeq;
-                    }
-                    ws.send(JSON.stringify(pingMsg));
+                    ws.send(JSON.stringify({ type: 'ping' }));
                     if (state) {
                         state.pongOverdueAt = Date.now() + PONG_GRACE_MS;
                         state.pendingLivenessBroadcast = false;
@@ -1588,7 +1389,7 @@ export class HeadServer {
         state.pendingLivenessBroadcast = false;
     }
     /** Test hook: expire the pong grace timer for a specific device so the next
-     *  retry pass will broadcast device_pending immediately. */
+     *  liveness sweep will broadcast device_pending immediately. */
     expirePongGrace(deviceId) {
         const ws = this.connections.get(deviceId);
         if (!ws)
@@ -1605,9 +1406,13 @@ export class HeadServer {
             clearInterval(this.pingTimer);
             this.pingTimer = null;
         }
-        if (this.retryTimer) {
-            clearInterval(this.retryTimer);
-            this.retryTimer = null;
+        if (this.livenessTimer) {
+            clearInterval(this.livenessTimer);
+            this.livenessTimer = null;
+        }
+        if (this.pulseTickTimer) {
+            clearInterval(this.pulseTickTimer);
+            this.pulseTickTimer = null;
         }
         for (const ws of this.clients.keys()) {
             ws.close();