@mentra/cloud-client 0.1.0-beta.0 → 3.1.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/cloud-client",
-  "version": "0.1.0-beta.0",
+  "version": "3.1.0-dev.2",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -12,7 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "^0.1.0-beta.0",
+    "@mentra/cloud-protocol": "3.1.0-dev.2",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {

package/src/client.ts

@@ -20,6 +20,7 @@ import type { CloudClientConfig } from "./config";
 import { createHttpClient } from "./http";
 import { CloudClientError } from "./errors";
 import type { ConnectionInit } from "@mentra/cloud-protocol";
+import { systemTimers } from "./timers";
 
 // The module implementations. Each is owned by another agent under ./modules/**;
 // this file only constructs them, matching the constructor signatures fixed in
@@ -117,6 +118,7 @@ export class CloudClient {
 
     // Reconnect/backoff lives here so the socket's timing is tuned in one spot.
     const reconnect = config.reconnect ?? DEFAULT_RECONNECT;
+    const timers = config.timers ?? systemTimers;
 
     // Resolve the two base addresses. With a proxy set, both route through it;
     // without one, each module talks to its own service directly.
@@ -149,7 +151,7 @@ export class CloudClient {
     // before any access token exists. It is deliberately Core-only: runtime-only
     // clients never get a fallback that points Core/Auth calls at Runtime.
     const authHttp = coreUrl
-      ? createHttpClient({ baseUrl: coreUrl, logger, fetch: config.transports.http })
+      ? createHttpClient({ baseUrl: coreUrl, logger, fetch: config.transports.http, timers })
       : undefined;
     const store = new TokenStore({ storage: config.transports.storage });
     const auth = new Auth({
@@ -173,6 +175,7 @@ export class CloudClient {
             getToken: getCoreToken,
             logger,
             fetch: config.transports.http,
+            timers,
           })
         : null;
     const runtimeHttp = createHttpClient({
@@ -180,10 +183,11 @@ export class CloudClient {
       getToken: getRuntimeToken,
       logger,
       fetch: config.transports.http,
+      timers,
     });
 
     const emitter = new RuntimeEmitter();
-    const subscriptions = new Subscriptions({ http: runtimeHttp });
+    const subscriptions = new Subscriptions({ http: runtimeHttp, timers });
 
     // The handshake payload the connection sends on every (re)open. It is a
     // factory (not a fixed value) so each reconnect re-reads the current defaults
@@ -221,12 +225,13 @@ export class CloudClient {
       getToken: getRuntimeToken,
       initPayload,
       reconnect,
+      timers,
       onAuthRejected: async () => {
         await auth.getRuntimeToken({ forceRefresh: true });
       },
       logger,
     });
-    const camera = new Camera({ http: runtimeHttp });
+    const camera = new Camera({ http: runtimeHttp, timers });
     const tts = new Tts({ http: runtimeHttp });
     const maps = new Maps({ http: runtimeHttp });
     const audio = new UdpAudio({ udp: config.transports.udp });
@@ -239,6 +244,7 @@ export class CloudClient {
       tts,
       maps,
       audio,
+      timers,
       logger,
       // On a fatal AUTH_EXPIRED at handshake, runtime forces auth to drop its
       // cached access token and refresh; the connection then re-reads the fresh

package/src/config.ts

@@ -9,6 +9,7 @@
  */
 import type { Logger } from "./logger";
 import type { CloudClientTransports } from "./transports";
+import type { CloudClientTimers } from "./timers";
 
 /**
  * The full shape passed to the root `CloudClient`.
@@ -25,6 +26,13 @@ export interface CloudClientConfig {
   endpoints: { core?: string; runtime: string; proxy?: string };
   auth: AuthConfig;
   transports: CloudClientTransports;
+  /**
+   * Scheduler for all delayed client work, including connection/audio
+   * liveness, retries, and request timeouts. React Native hosts must provide
+   * native background timers because ordinary JS timers pause when Android
+   * backgrounds the app.
+   */
+  timers?: CloudClientTimers;
   logger?: Logger;
   // backoff tuning for the live socket; one place so a host can match its fleet
   reconnect?: { baseMs: number; maxMs: number; jitter: boolean };

package/src/http.ts

@@ -14,6 +14,7 @@
  */
 import { HttpError } from "./errors";
 import type { Logger } from "./logger";
+import { systemTimers, type CloudClientTimers } from "./timers";
 import type { HttpTransport } from "./transports";
 
 /**
@@ -58,6 +59,7 @@ export interface CreateHttpClientDeps {
   getToken?: () => Promise<string>;
   logger: Logger;
   fetch?: HttpTransport;
+  timers?: CloudClientTimers;
 }
 
 /** How many times to retry a transient failure on an idempotent call. */
@@ -65,11 +67,6 @@ const MAX_RETRIES = 2;
 /** Base backoff in milliseconds; doubles per attempt (250, 500, ...). */
 const RETRY_BASE_MS = 250;
 
-/** Resolve after `ms`, used for retry backoff. */
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Join a base URL and a path without producing a double slash or dropping one.
  *
@@ -85,6 +82,7 @@ function joinUrl(baseUrl: string, path: string): string {
 export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
   const { baseUrl, getToken, logger } = deps;
   const executeFetch = deps.fetch ?? globalThis.fetch;
+  const timers = deps.timers ?? systemTimers;
 
   /**
    * Resolve the Bearer to attach: a per-call override wins, otherwise the
@@ -122,7 +120,7 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
       if (attempt > 0) {
         const backoff = RETRY_BASE_MS * 2 ** (attempt - 1);
         logger.debug("http retrying request", { method, path, attempt });
-        await delay(backoff);
+        await new Promise<void>((resolve) => timers.setTimeout(resolve, backoff));
       }
 
       let res: Response;

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
   UdpSocketLike,
   KeyValueStore,
 } from "./transports";
+export type { CloudClientTimers } from "./timers";
 
 // Local error types a host can branch on with `instanceof`.
 export { CloudClientError, HttpError, AuthExpiredError } from "./errors";
@@ -67,4 +68,7 @@ export type {
   ReportTrigger,
   SubmitReportInput,
   SubmitReportResult,
+  SupportConnectionState,
+  SupportProfileUpdateResult,
+  SupportStateInput,
 } from "./modules/core/core";

package/src/modules/core/core.ts

@@ -26,6 +26,11 @@ import {
   type SubmitReportInput,
   type SubmitReportResult,
 } from "./reports";
+import {
+  SupportProfiles,
+  type SupportProfileUpdateResult,
+  type SupportStateInput,
+} from "./support-profile";
 
 export type {
   AddReportArtifactsResult,
@@ -40,6 +45,11 @@ export type {
   SubmitReportInput,
   SubmitReportResult,
 } from "./reports";
+export type {
+  SupportConnectionState,
+  SupportProfileUpdateResult,
+  SupportStateInput,
+} from "./support-profile";
 
 /**
  * A single miniapp entry as returned by the listing.
@@ -145,10 +155,14 @@ export class Core {
     ): Promise<AddReportArtifactsResult>;
     complete(reportId: string): Promise<{ status: ReportStatus }>;
   };
+  readonly supportProfile: {
+    update(input: SupportStateInput): Promise<SupportProfileUpdateResult>;
+  };
 
   constructor(deps: CoreDeps) {
     const { http } = deps;
     const reports = new Reports({ http });
+    const supportProfiles = new SupportProfiles(http);
 
     this.miniapps = {
       /**
@@ -198,5 +212,8 @@ export class Core {
       addScreenshots: reports.addScreenshots.bind(reports),
       complete: reports.complete.bind(reports),
     };
+    this.supportProfile = {
+      update: supportProfiles.update.bind(supportProfiles),
+    };
   }
 }

package/src/modules/core/support-profile.ts

@@ -0,0 +1,45 @@
+import type {HttpClient} from "../../http"
+
+export type SupportConnectionState = "disconnected" | "scanning" | "connecting" | "bonding" | "connected"
+
+export interface SupportStateInput {
+  observedAt: string
+  host: {
+    appVersion?: string
+    appBuild?: string
+    engineVersion?: string
+    bluetoothSdkVersion?: string
+    phonePlatform: "ios" | "android" | "unknown"
+    phoneModel?: string
+    phoneOsVersion?: string
+    connectionState: SupportConnectionState
+    failureCode?: string
+    failureStage?: string
+  }
+  device?: {
+    /** Sent over TLS for server-side HMAC derivation, then immediately discarded. */
+    hardwareId?: string
+    model?: string
+    androidVersion?: string
+    firmwareVersion?: string
+    mtkFirmwareVersion?: string
+    besFirmwareVersion?: string
+    appVersion?: string
+    buildNumber?: string
+  }
+}
+
+export interface SupportProfileUpdateResult {
+  status: "accepted" | "deduplicated" | "stale"
+  observedAt: string
+}
+
+export class SupportProfiles {
+  constructor(private readonly http: HttpClient) {}
+
+  update(input: SupportStateInput): Promise<SupportProfileUpdateResult> {
+    return this.http.put<SupportProfileUpdateResult>("/api/client/support-profile", input, {
+      idempotent: true,
+    })
+  }
+}

package/src/modules/runtime/camera.ts

@@ -17,6 +17,7 @@
  * docs/issues/004-cloud-client/design.md ("Camera").
  */
 import type { HttpClient } from "../../http";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 import type {
   CloudToClientMessage,
   PhotoOptions,
@@ -48,6 +49,7 @@ export interface PhotoResult {
 
 export interface CameraDeps {
   http: HttpClient;
+  timers?: CloudClientTimers;
 }
 
 /**
@@ -60,17 +62,19 @@ export interface CameraDeps {
 interface Pending<T> {
   resolve: (value: T) => void;
   reject: (err: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
+  timer: unknown;
 }
 
 export class Camera {
   private readonly http: HttpClient;
+  private readonly timers: CloudClientTimers;
 
   /** In-flight photo requests, keyed by the `requestId` the cloud assigned. */
   private readonly pendingPhotos = new Map<string, Pending<PhotoResult>>();
 
   constructor(deps: CameraDeps) {
     this.http = deps.http;
+    this.timers = deps.timers ?? systemTimers;
   }
 
   /**
@@ -111,7 +115,7 @@ export class Camera {
   /** Step 2: resolve when the cloud pushes `photo.ready` for the request. */
   awaitPhotoReady(requestId: string): Promise<PhotoResult> {
     return new Promise<PhotoResult>((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const timer = this.timers.setTimeout(() => {
         // Drop the entry first so the rejection cannot race a late push.
         this.pendingPhotos.delete(requestId);
         reject(new Error(`Managed photo ${requestId} timed out`));
@@ -185,7 +189,7 @@ export class Camera {
   private takePending(requestId: string): Pending<PhotoResult> | undefined {
     const pending = this.pendingPhotos.get(requestId);
     if (!pending) return undefined;
-    clearTimeout(pending.timer);
+    this.timers.clearTimeout(pending.timer);
     this.pendingPhotos.delete(requestId);
     return pending;
   }

package/src/modules/runtime/connection.ts

@@ -50,6 +50,7 @@ import {
 } from "@mentra/cloud-protocol";
 import type { WebSocketLike } from "../../transports";
 import type { Logger } from "../../logger";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 
 /** Connection lifecycle, surfaced to the rest of runtime via `onState`. */
 export type ConnectionState = "connecting" | "open" | "closed";
@@ -117,6 +118,7 @@ export interface ConnectionDeps {
   // what rides in the handshake beyond the token it stamps in.
   initPayload: () => ConnectionInit;
   reconnect: { baseMs: number; maxMs: number; jitter: boolean };
+  timers?: CloudClientTimers;
   // Called when the WebSocket upgrade itself is rejected as unauthorized. That
   // happens before a protocol `error` frame can exist, so runtime's normal
   // AUTH_EXPIRED handshake retry cannot see it. The host uses this to invalidate
@@ -164,8 +166,13 @@ function isUnauthorizedUpgrade(reason: string): boolean {
   return /\b401\b|unauthorized/i.test(reason);
 }
 
+function isSupersededByNewerSession(reason: string): boolean {
+  return /superseded by newer session/i.test(reason);
+}
+
 export class Connection {
   private readonly deps: ConnectionDeps;
+  private readonly timers: CloudClientTimers;
 
   // The current socket. Null between connect attempts and after close, so every
   // access guards on it rather than assuming a live socket.
@@ -187,6 +194,11 @@ export class Connection {
   // stop" from "the network dropped".
   private closedByHost = false;
 
+  // True when the cloud closed us with 1012 "superseded by newer session".
+  // Another live socket for this user won; reconnecting would just kill it
+  // and start a two-client fight. Stays down until the host calls open().
+  private replacedByNewerSession = false;
+
   // How many consecutive failed (re)connect attempts, used to grow the backoff.
   // Reset to zero on a successful handshake.
   private reconnectAttempt = 0;
@@ -196,12 +208,12 @@ export class Connection {
   // already armed is a no-op, so the (intentional) double call from `onClose`
   // and from a failed attempt's catch-reschedule can never stack two timers and
   // double the reconnect rate.
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectTimer: unknown | null = null;
 
   // The watchdog interval (started in open(), cleared in close()). It is the
   // backstop that revives the reconnect loop if it ever stalls: see
   // `tickWatchdog` and the file header for why a stall is possible at all.
-  private watchdogTimer: ReturnType<typeof setInterval> | null = null;
+  private watchdogTimer: unknown | null = null;
 
   // Mirror of the last state pushed through `setState`, so the watchdog can ask
   // "are we currently closed?" without a separate subscription. The state
@@ -211,8 +223,8 @@ export class Connection {
 
   // Liveness timers. The interval drives the periodic ping; the pong-wait timer
   // is armed when a ping goes out and disarmed when its pong arrives.
-  private pingTimer: ReturnType<typeof setInterval> | null = null;
-  private pongTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: unknown | null = null;
+  private pongTimer: unknown | null = null;
 
   // While `open()` is awaiting `connection.ack`, these settle that promise. They
   // are cleared the moment the handshake resolves, rejects, or times out, so a
@@ -220,11 +232,12 @@ export class Connection {
   private pendingAck: {
     resolve: (ack: ConnectionAck) => void;
     reject: (err: Error) => void;
-    timer: ReturnType<typeof setTimeout>;
+    timer: unknown;
   } | null = null;
 
   constructor(deps: ConnectionDeps) {
     this.deps = deps;
+    this.timers = deps.timers ?? systemTimers;
   }
 
   /**
@@ -237,6 +250,11 @@ export class Connection {
     return this.currentAck;
   }
 
+  /** True after the cloud closed us as the losing socket for this user. */
+  get isReplacedByNewerSession(): boolean {
+    return this.replacedByNewerSession;
+  }
+
   /**
    * Open the socket, run the handshake, and resolve with `connection.ack`.
    *
@@ -248,8 +266,9 @@ export class Connection {
    */
   async open(): Promise<ConnectionAck> {
     // A fresh open() means the host wants the socket up; clear any prior
-    // host-close intent so a later drop reconnects normally.
+    // host-close / superseded intent so a later drop reconnects normally.
     this.closedByHost = false;
+    this.replacedByNewerSession = false;
 
     // A fresh open() is a clean slate: cancel any stale reconnect left over from
     // a previous session, and reset the backoff so we do not start this connect
@@ -277,6 +296,7 @@ export class Connection {
    */
   close(): void {
     this.closedByHost = true;
+    this.replacedByNewerSession = false;
     this.stopLiveness();
     // Cancel any queued reconnect and stop the watchdog: the host wants us down,
     // so neither the loop nor its backstop should bring the socket back up.
@@ -370,7 +390,7 @@ export class Connection {
     // The promise the handshake settles. Wired before the socket can fire any
     // callback so an immediate open/message cannot race ahead of the listener.
     const acked = new Promise<ConnectionAck>((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const timer = this.timers.setTimeout(() => {
         this.pendingAck = null;
         // Close the half-done socket too: a handshake that times out client-
         // side may still COMPLETE server-side moments later, leaving a ghost
@@ -501,7 +521,7 @@ export class Connection {
     this.reconnectAttempt = 0;
 
     if (this.pendingAck) {
-      clearTimeout(this.pendingAck.timer);
+      this.timers.clearTimeout(this.pendingAck.timer);
       const { resolve } = this.pendingAck;
       this.pendingAck = null;
       resolve(ack);
@@ -509,6 +529,9 @@ export class Connection {
 
     this.setState("open");
     this.startLiveness();
+    this.deps.logger.debug("ws-session-debug handshake ok", {
+      sessionId: ack.sessionId,
+    });
   }
 
   /**
@@ -539,6 +562,20 @@ export class Connection {
     this.setState("closed");
 
     const reason = info.reason || `code ${info.code}`;
+    if (isSupersededByNewerSession(reason)) {
+      // Newest-wins on the server. Coming back up here would supersede the
+      // winner, which then reconnects, forever. Stay down until open().
+      this.replacedByNewerSession = true;
+      this.clearReconnectTimer();
+      this.stopWatchdog();
+      this.deps.logger.info("ws-session-debug staying down after supersede", {
+        code: info.code,
+        reason,
+        sessionId: this.currentAck?.sessionId ?? null,
+        reconnectAttempt: this.reconnectAttempt,
+      });
+      return;
+    }
     if (isUnauthorizedUpgrade(reason)) {
       void Promise.resolve(this.deps.onAuthRejected?.())
         .catch((err) => {
@@ -572,6 +609,12 @@ export class Connection {
     // Already a retry queued -> nothing to do. This is the guard that makes the
     // double call from onClose + catch-reschedule (and the watchdog) harmless.
     if (this.reconnectTimer !== null) return;
+    if (this.replacedByNewerSession) {
+      this.deps.logger.debug("ws-session-debug skip reconnect; replaced by newer session", {
+        reason,
+      });
+      return;
+    }
 
     const delay = backoffDelay(this.reconnectAttempt, this.deps.reconnect);
     this.reconnectAttempt += 1;
@@ -581,7 +624,7 @@ export class Connection {
       reason,
     });
 
-    this.reconnectTimer = setTimeout(() => {
+    this.reconnectTimer = this.timers.setTimeout(() => {
       // Null the timer first so this slot is free again: a connect that fails
       // below must be able to schedule the next retry, and the watchdog must see
       // "no reconnect pending" while the attempt is in flight.
@@ -608,7 +651,7 @@ export class Connection {
   /** Cancel a queued reconnect, if any. Safe to call when none is pending. */
   private clearReconnectTimer(): void {
     if (this.reconnectTimer !== null) {
-      clearTimeout(this.reconnectTimer);
+      this.timers.clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
   }
@@ -620,7 +663,7 @@ export class Connection {
    */
   private startWatchdog(): void {
     this.stopWatchdog();
-    this.watchdogTimer = setInterval(
+    this.watchdogTimer = this.timers.setInterval(
       () => this.tickWatchdog(),
       RECONNECT_WATCHDOG_MS,
     );
@@ -629,7 +672,7 @@ export class Connection {
   /** Stop the reconnect watchdog (on host close). */
   private stopWatchdog(): void {
     if (this.watchdogTimer !== null) {
-      clearInterval(this.watchdogTimer);
+      this.timers.clearInterval(this.watchdogTimer);
       this.watchdogTimer = null;
     }
   }
@@ -649,6 +692,7 @@ export class Connection {
     if (
       this.currentState === "closed" &&
       !this.closedByHost &&
+      !this.replacedByNewerSession &&
       this.reconnectTimer === null
     ) {
       this.scheduleReconnect("watchdog: no reconnect pending");
@@ -665,7 +709,7 @@ export class Connection {
    */
   private startLiveness(): void {
     this.stopLiveness();
-    this.pingTimer = setInterval(() => this.sendPing(), PING_INTERVAL_MS);
+    this.pingTimer = this.timers.setInterval(() => this.sendPing(), PING_INTERVAL_MS);
   }
 
   /** Send one liveness ping and arm the pong-wait timer. */
@@ -676,8 +720,8 @@ export class Connection {
     // If a pong-wait timer is already armed, leave it: a single outstanding
     // timeout is enough to catch a dead socket, and re-arming would push the
     // deadline back on every interval.
-    if (this.pongTimer) return;
-    this.pongTimer = setTimeout(() => {
+    if (this.pongTimer !== null) return;
+    this.pongTimer = this.timers.setTimeout(() => {
       // No pong in time. The socket is dead; close it so the close handler runs
       // the reconnect path, rather than reconnecting from here and racing the
       // existing socket's eventual close.
@@ -703,8 +747,8 @@ export class Connection {
 
   /** Stop both liveness timers (on close, reconnect, or teardown). */
   private stopLiveness(): void {
-    if (this.pingTimer) {
-      clearInterval(this.pingTimer);
+    if (this.pingTimer !== null) {
+      this.timers.clearInterval(this.pingTimer);
       this.pingTimer = null;
     }
     this.clearPongTimer();
@@ -712,8 +756,8 @@ export class Connection {
 
   /** Disarm the pong-wait timer (a pong arrived, or liveness is stopping). */
   private clearPongTimer(): void {
-    if (this.pongTimer) {
-      clearTimeout(this.pongTimer);
+    if (this.pongTimer !== null) {
+      this.timers.clearTimeout(this.pongTimer);
       this.pongTimer = null;
     }
   }
@@ -724,7 +768,7 @@ export class Connection {
    */
   private failPendingAck(err: Error): void {
     if (!this.pendingAck) return;
-    clearTimeout(this.pendingAck.timer);
+    this.timers.clearTimeout(this.pendingAck.timer);
     const { reject } = this.pendingAck;
     this.pendingAck = null;
     reject(err);

package/src/modules/runtime/runtime.ts

@@ -34,6 +34,7 @@ import type { Maps, DirectionsRequest, DirectionsResult, LatLng, ReverseGeocodeR
 import type { Tts, RuntimeTtsSpeakOptions, RuntimeTtsSpeechSource } from "./tts";
 import type { UdpAudio } from "./audio-udp";
 import type { RuntimeSnapshot } from "./status";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 
 const UDP_PROBE_INTERVAL_MS = 1_000;
 const UDP_LIVENESS_TIMEOUT_MS = 3_000;
@@ -117,6 +118,7 @@ export interface RuntimeDeps {
   tts: Tts;
   maps: Maps;
   audio: UdpAudio;
+  timers?: CloudClientTimers;
   logger: Logger;
   /**
    * Force `cloud.auth` to drop its cached access token and refresh now.
@@ -142,13 +144,14 @@ export class Runtime implements RuntimeModule {
   public readonly maps: Maps;
   private readonly audio: UdpAudio;
   private readonly logger: Logger;
+  private readonly timers: CloudClientTimers;
   private readonly forceRefreshToken: () => Promise<string>;
   private status: RuntimeSnapshot = {
     status: "disconnected",
     audioTransport: "none",
   };
   private hostClosed = true;
-  private udpProbeTimer: ReturnType<typeof setInterval> | null = null;
+  private udpProbeTimer: unknown | null = null;
   private udpProbeStartedAt = 0;
   private lastUdpAckAt = 0;
 
@@ -179,6 +182,7 @@ export class Runtime implements RuntimeModule {
     this.tts = deps.tts;
     this.maps = deps.maps;
     this.audio = deps.audio;
+    this.timers = deps.timers ?? systemTimers;
     this.logger = deps.logger;
     this.forceRefreshToken = deps.forceRefreshToken;
   }
@@ -302,16 +306,25 @@ export class Runtime implements RuntimeModule {
         // current set (at the current version) to restore live transcription.
         void this.handleReopen();
       } else if (state === "closed") {
+        const superseded = this.connection.isReplacedByNewerSession;
+        const reason = superseded
+          ? "superseded by newer session"
+          : "socket closed";
+        this.logger.debug("ws-session-debug runtime closed", {
+          superseded,
+          hostClosed: this.hostClosed,
+          reason,
+        });
         this.stopUdpLiveness();
         this.updateStatus({
-          status: this.hostClosed
+          status: this.hostClosed || superseded
             ? "disconnected"
             : this.opened
               ? "reconnecting"
               : "connecting",
           audioTransport: "none",
         });
-        this.emitter.emit("disconnected", { reason: "socket closed" });
+        this.emitter.emit("disconnected", { reason });
       }
     });
   }
@@ -513,15 +526,15 @@ export class Runtime implements RuntimeModule {
     this.udpProbeStartedAt = Date.now();
     this.lastUdpAckAt = 0;
     this.sendUdpProbe();
-    this.udpProbeTimer = setInterval(() => {
+    this.udpProbeTimer = this.timers.setInterval(() => {
       this.sendUdpProbe();
       this.checkUdpLiveness();
     }, UDP_PROBE_INTERVAL_MS);
   }
 
   private stopUdpLiveness(): void {
-    if (this.udpProbeTimer) {
-      clearInterval(this.udpProbeTimer);
+    if (this.udpProbeTimer !== null) {
+      this.timers.clearInterval(this.udpProbeTimer);
       this.udpProbeTimer = null;
     }
     this.udpProbeStartedAt = 0;

package/src/modules/runtime/subscriptions.ts

@@ -17,6 +17,7 @@
  * and docs/issues/004-cloud-client/design.md ("Subscriptions").
  */
 import type { HttpClient } from "../../http";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 import type { AudioSubscription } from "@mentra/cloud-protocol";
 
 /** The REST path the cloud exposes for the full-replace subscription write. */
@@ -24,10 +25,12 @@ const SUBSCRIPTIONS_PATH = "/api/audio/subscriptions";
 
 export interface SubscriptionsDeps {
   http: HttpClient;
+  timers?: CloudClientTimers;
 }
 
 export class Subscriptions {
   private readonly http: HttpClient;
+  private readonly timers: CloudClientTimers;
 
   /**
    * The last set we sent. Kept so a reconnect can re-send the exact same set at
@@ -43,6 +46,7 @@ export class Subscriptions {
 
   constructor(deps: SubscriptionsDeps) {
     this.http = deps.http;
+    this.timers = deps.timers ?? systemTimers;
   }
 
   /**
@@ -130,7 +134,7 @@ export class Subscriptions {
 
       const delay = RETRY_DELAYS_MS[attempt];
       if (res.reason !== "stale-session" || delay === undefined) return;
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await new Promise<void>((resolve) => this.timers.setTimeout(resolve, delay));
     }
   }
 }

package/src/timers.ts

@@ -0,0 +1,23 @@
+/** Timer surface used by every delayed operation in the cloud client. */
+export interface CloudClientTimers {
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(handle: unknown): void;
+  setInterval(callback: () => void, intervalMs: number): unknown;
+  clearInterval(handle: unknown): void;
+}
+
+/** Default scheduler for Node, Bun, and foreground browser hosts. */
+export const systemTimers: CloudClientTimers = {
+  setTimeout(callback, delayMs) {
+    return setTimeout(callback, delayMs);
+  },
+  clearTimeout(handle) {
+    clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+  setInterval(callback, intervalMs) {
+    return setInterval(callback, intervalMs);
+  },
+  clearInterval(handle) {
+    clearInterval(handle as ReturnType<typeof setInterval>);
+  },
+};