@pollen-robotics/reachy-mini-sdk 1.10.0-dev.0.main.05ce680 → 1.10.0-dev.0.main.4dc28bb

package/dist/lib/reachy-mini.js

@@ -4,56 +4,42 @@
  * a quick-start guide.
  */
 import { oauthHandleRedirectIfPresent, oauthLoginUrl, } from '@huggingface/hub';
+import { createLogger } from './logger.js';
 import { degToRad, rpyToMatrix } from './math.js';
+import { BroadcastTimeoutError, PendingReplies, SLOT_ROUNDTRIP_TIMEOUT_MS } from './pending-replies.js';
+import { SessionSupervisor } from './session-supervisor.js';
+import { SDK_VERSION } from './version.js';
 import { consumeFragmentCredentials, readPreselectedRobotIdFromUrl, sdpHasAudioSendRecv, } from './url-helpers.js';
+import { clearStoredToken, consumeOAuthErrorParams, readUsableToken, writeStoredToken, } from './token-store.js';
 import { UPLOAD_CHUNK_SIZE, UPLOAD_BUFFERED_HIGH_WATER, UPLOAD_BUFFERED_LOW_WATER, hasCompressionStream, makeUploadId, bytesToBase64, gzipBase64, clampVolume, audioUploadEncoding, } from './upload-helpers.js';
+const log = createLogger('sdk');
 // ─── Internal constants ──────────────────────────────────────────────────────
+// Resilience tunables (ICE grace windows, re-dial backoff, DC-silence
+// watchdog thresholds) live in `session-supervisor.ts`.
 /**
- * How long we tolerate `iceConnectionState === 'disconnected'` before
- * surfacing it as an error. The spec defines this state as transient
- * (browsers keep STUN keep-alives running and usually heal in 1-2 s
- * on WiFi blips, AP roams, brief 4G dropouts). Consumers watching
- * `iceStateChange` directly should outlive this window before
- * showing any fatal UI.
+ * How long a pushed pose frame keeps the periodic `get_state` poll on hold -
+ * both on the way out (no request is sent) and on the way back (a reply that
+ * arrives anyway doesn't touch the state mirror).
+ *
+ * Poll replies carry no `seq`, so they slip past the stale-frame guard: a
+ * reply that crosses a fresher pushed frame would rewind the very mirror the
+ * stream exists to smooth. While frames flow at ~30 Hz there is nothing left
+ * for the poll to add, so it stands down. Keying that on frame arrival rather
+ * than on `_poseSubRefs` keeps the poll running against a daemon that doesn't
+ * know `subscribe_pose`, and brings it back on its own if the stream stalls.
+ * A little over one 500 ms poll period, so a couple of dropped frames don't
+ * flip it back and forth.
  */
-const ICE_DISCONNECT_GRACE_MS = 3000;
+const POSE_STREAM_FRESH_MS = 750;
 /**
- * Grace before treating `iceConnectionState === 'failed'` as terminal.
- * The spec says `failed` IS terminal, but we've observed real
- * `failed → connected` flips on rapid AP roams and iOS BT route
- * changes — 1 s of debounce absorbs those without noticeably
- * delaying a real failure.
+ * Upper bound on how long `ensureAwake()` waits for the wake trajectory to
+ * complete. The emote itself takes ~2-3 s on hardware; the extra headroom
+ * covers a cold trajectory player. Deliberately shorter than `wakeUp()`'s
+ * own 8 s default: `ensureAwake()` gates app boot, and a daemon that hasn't
+ * confirmed within 5 s isn't going to - better to let the app in degraded
+ * than trap it on the splash.
  */
-const ICE_FAILED_GRACE_MS = 1000;
-/**
- * Ceiling on how long we'll keep `_armIceGraceOnVisibility` waiting
- * for the tab to come back. The daemon's `webrtcsink` runs a STUN
- * consent-freshness check (RFC 7675, ~30 s default) and unilaterally
- * tears its side of the session down past that window, releasing the
- * producer slot on central. If the user backgrounded the tab for
- * longer than this, running another 3 s foreground grace is a lie —
- * the underlying transport is gone, nothing can recover. Give up
- * straight away so the host shows the real "session expired" UX
- * instead of a fake "Reconnecting…" badge that's never going to
- * heal. 60 s gives a 2× margin over the daemon-side timeout — long
- * enough to absorb a "phone in pocket for 45 s" case, short enough
- * to be honest with the user.
- */
-const MAX_VISIBILITY_DEFER_MS = 60_000;
-/**
- * Fail-open ceiling for a single `_slotRoundtrip` request/response.
- * Every slot command has a strict "one reply per request" contract, so
- * a missing reply means the daemon either never got it or - crucially -
- * predates that command entirely: an older daemon silently drops an
- * unknown `type` and sends nothing back, which would otherwise leave the
- * caller's promise pending forever (e.g. a newer SDK calling a command a
- * 1.8.x daemon doesn't implement). Resolving `null` on timeout maps
- * cleanly onto the "unsupported / failed" value every slot caller already
- * handles. 4 s is comfortably above a WebRTC data-channel round trip on a
- * congested phone link while still failing fast enough that a gated UI
- * doesn't feel hung.
- */
-const SLOT_ROUNDTRIP_TIMEOUT_MS = 4000;
+const WAKE_TRAJECTORY_BUDGET_MS = 5000;
 export class ReachyMini extends EventTarget {
     // ─── Config ──────────────────────────────────────────────────────────
     _signalingUrl;
@@ -66,6 +52,19 @@ export class ReachyMini extends EventTarget {
     _state = 'disconnected';
     _robots = [];
     _robotState = {};
+    // Highest `seq` seen on the unordered `pose` channel. Frames that arrive
+    // out of order (older seq) are dropped so a late packet can't rewind the
+    // live mirror. `null` until the first pose frame.
+    _lastPoseSeq = null;
+    // When the last pushed pose frame was applied, used to park the periodic
+    // `get_state` poll while the stream is live (see POSE_STREAM_FRESH_MS).
+    _lastPoseFrameAt = 0;
+    // Local refcount of pose-stream consumers (the 3D mirror, the wizard's
+    // move-end watcher, ...). The daemon's subscription is a per-peer boolean
+    // (not refcounted), so we only send `unsubscribe_pose` once the LAST local
+    // consumer releases - otherwise one consumer's cleanup would kill the
+    // stream for the others.
+    _poseSubRefs = 0;
     _preselectedRobotId;
     // ─── Auth ────────────────────────────────────────────────────────────
     _token = null;
@@ -87,29 +86,17 @@ export class ReachyMini extends EventTarget {
     // ─── Timers ──────────────────────────────────────────────────────────
     _latencyMonitorId = null;
     _stateRefreshInterval = null;
-    // ─── Single-slot promise resolvers ───────────────────────────────────
-    _versionResolve = null;
-    _hardwareIdResolve = null;
-    _volumeResolve = null;
-    _micVolumeResolve = null;
-    _trackedFaceResolve = null;
-    // applyAudioConfig() / readAudioParameter() share the same single-slot
-    // pattern as the volume helpers. Separate slots so the two can be
-    // in-flight concurrently without collision.
-    _applyAudioConfigResolve = null;
-    _readAudioParameterResolve = null;
+    // ─── Pending replies (reply slots / JSON-RPC / motion / broadcast) ───
+    // All request/response waiters on the data channel live in one
+    // ledger so every teardown path settles them in a single call.
+    _pending = new PendingReplies();
     // ─── Log subscribers ─────────────────────────────────────────────────
     _logSubscribers = new Set();
     _updateProgressSubscribers = new Set();
-    // ─── JSON-RPC app control (over the same DataChannel) ────────────────
-    // rpcCall() sends {jsonrpc,id,method,params} and awaits the matching
-    // response; onNotification() subscribes to one-way events (no id) the
-    // robot/app pushes (conversation.phase/turn/transcript, ...).
-    _rpcCounter = 0;
-    _pendingRpc = new Map();
+    // ─── JSON-RPC notification listeners (one-way events, no id) ─────────
+    // onNotification() subscribes to events the robot/app pushes
+    // (conversation.phase/turn/transcript, ...).
     _rpcListeners = new Map();
-    // ─── Broadcast waiters (playMove / playUploadedAudio) ────────────────
-    _broadcastWaiters = [];
     // ─── Active upload ids for no-arg cancels ────────────────────────────
     _activeMoveUploadId = null;
     _activeAudioUploadId = null;
@@ -118,24 +105,12 @@ export class ReachyMini extends EventTarget {
     _sessionReject = null;
     _iceConnected = false;
     _dcOpen = false;
-    // ─── Resilience: ICE-blip debounce + network awareness ──────────────
-    // Backs `_scheduleIceGrace` / `_armIceGraceOnVisibility` and the
-    // `networkOnline` / `networkOffline` / `networkChange` forwarders.
-    // All three handler slots are scoped to the lifetime of a live
-    // session (installed in `startSession`, cleared in
-    // `stopSession` / `disconnect` / `_handleEndSession` /
-    // `_failSessionRejected`).
-    _iceGraceTimer = null;
-    _iceGraceReason = null;
-    _pendingVisibilityHandler = null;
-    _onlineHandler = null;
-    _offlineHandler = null;
-    _connectionChangeHandler = null;
-    // ─── Motion completion plumbing (wake_up / goto_sleep) ───────────────
-    _pendingMotionCompletions = {
-        wake_up: [],
-        goto_sleep: [],
-    };
+    // ─── Resilience ──────────────────────────────────────────────────────
+    // ICE-blip debounce, network awareness, automatic session re-dial and
+    // the data-channel silence watchdog all live in the supervisor; the
+    // class forwards pc/browser events to it and implements its deps as
+    // closures over the private state below (see the constructor).
+    _supervisor;
     // ─── Video element ───────────────────────────────────────────────────
     _videoElement = null;
     constructor(options = {}) {
@@ -151,6 +126,31 @@ export class ReachyMini extends EventTarget {
         this._autoStartFromUrl = options.autoStartFromUrl === true;
         this._autoStartAttempted = false;
         this._preselectedRobotId = readPreselectedRobotIdFromUrl();
+        // Arrow closures so every dep call reads the CURRENT class state.
+        this._supervisor = new SessionSupervisor({
+            iceState: () => this._pc?.iceConnectionState ?? null,
+            hasPc: () => !!this._pc,
+            isStreaming: () => this._state === 'streaming',
+            isMidSetup: () => !!(this._sessionResolve || this._sessionReject),
+            isSignalingDown: () => this._state === 'disconnected',
+            selectedRobotId: () => this._selectedRobotId,
+            rejectPendingSession: (err) => {
+                if (!this._sessionReject)
+                    return false;
+                const reject = this._sessionReject;
+                this._sessionResolve = null;
+                this._sessionReject = null;
+                reject(err);
+                return true;
+            },
+            reconnectSignaling: () => this.connect(),
+            // The private dial skips the public startSession()'s
+            // cancelRedial, so the loop's own attempts don't cancel it.
+            dial: (robotId) => this._startSessionInternal(robotId),
+            teardownForRedial: () => this._teardownForRedial(),
+            nudgeState: () => { this.requestState(); },
+            emit: (name, detail) => this._emit(name, detail),
+        }, { autoReconnect: options.autoReconnect !== false });
     }
     // ─── Read-only properties ────────────────────────────────────────────
     get state() { return this._state; }
@@ -163,6 +163,24 @@ export class ReachyMini extends EventTarget {
     get audioMuted() { return this._audioMuted; }
     get preselectedRobotId() { return this._preselectedRobotId; }
     get isEmbedded() { return this._preselectedRobotId !== null; }
+    /**
+     * Live RTCPeerConnection, or `null` between sessions. Read-only escape
+     * hatch for stats sampling (`getStats()`); mutating it is unsupported.
+     * Auto-reconnect re-dials REPLACE this object, so re-read it on every
+     * use — never capture it across ticks.
+     */
+    get peerConnection() { return this._pc; }
+    /**
+     * Build version of this SDK (npm package `version`), injected from
+     * package.json at build time. This is the JS SDK's OWN version and is
+     * distinct from `getVersion()`, which asks the DAEMON its version over
+     * the data channel. `0.0.0-managed-by-ci` means an unreleased/branch
+     * build (npm releases carry a real semver).
+     */
+    get sdkVersion() { return SDK_VERSION; }
+    /** Same value as the instance `sdkVersion`, reachable without an
+     *  instance: `ReachyMini.version`. */
+    static get version() { return SDK_VERSION; }
     /**
      * Internal: try to honour the `autoStartFromUrl` constructor
      * option. Called from the signaling-message handler after every
@@ -187,7 +205,7 @@ export class ReachyMini extends EventTarget {
             if (this._state !== 'connected')
                 return;
             this.startSession(peerId).catch((err) => {
-                console.warn('[reachy-mini] autoStartFromUrl: startSession rejected:', err);
+                log.warn('autoStartFromUrl: startSession rejected:', err);
             });
         }, 0);
     }
@@ -195,44 +213,63 @@ export class ReachyMini extends EventTarget {
     async authenticate() {
         try {
             consumeFragmentCredentials();
+            // A failed silent login (`login({ prompt: 'none' })`) returns as
+            // `?error=login_required` / `consent_required` query params.
+            // Strip them so they don't linger in the URL; the fall-through
+            // to the cached-token check below then reports "not signed in".
+            const silentError = consumeOAuthErrorParams();
+            if (silentError) {
+                log.info('silent sign-in declined:', silentError);
+            }
             const result = (await oauthHandleRedirectIfPresent());
             if (result) {
                 this._username = result.userInfo.preferred_username || result.userInfo.name || null;
                 this._token = result.accessToken;
                 this._tokenExpires = result.accessTokenExpiresAt;
-                sessionStorage.setItem('hf_token', this._token);
-                sessionStorage.setItem('hf_username', this._username ?? '');
-                sessionStorage.setItem('hf_token_expires', typeof this._tokenExpires === 'string'
-                    ? this._tokenExpires
-                    : this._tokenExpires.toISOString());
+                writeStoredToken({
+                    token: this._token,
+                    username: this._username ?? '',
+                    expires: typeof this._tokenExpires === 'string'
+                        ? this._tokenExpires
+                        : this._tokenExpires.toISOString(),
+                });
                 return true;
             }
-            const t = sessionStorage.getItem('hf_token');
-            const u = sessionStorage.getItem('hf_username');
-            const e = sessionStorage.getItem('hf_token_expires');
-            if (t && u && e && new Date(e) > new Date()) {
-                this._token = t;
-                this._username = u;
-                this._tokenExpires = e;
+            // Cached-token path. `readUsableToken` enforces both the OAuth
+            // expiry and a sliding idle window (see token-store.ts).
+            const stored = readUsableToken();
+            if (stored && stored.username) {
+                this._token = stored.token;
+                this._username = stored.username;
+                this._tokenExpires = stored.expires;
                 return true;
             }
             return false;
         }
         catch (e) {
-            console.error('Auth error:', e);
+            log.error('authenticate failed:', e);
             return false;
         }
     }
-    async login() {
+    async login(options) {
         const opts = {};
         if (this._clientId)
             opts.clientId = this._clientId;
-        window.location.href = await oauthLoginUrl(opts);
+        let url = await oauthLoginUrl(opts);
+        // OIDC prompt param. `oauthLoginUrl` doesn't expose it, but the HF
+        // authorize endpoint honours it (verified empirically): with
+        // `prompt=none` an already-authorized user comes straight back with
+        // a code and no screen, anyone else comes back with `?error=...`
+        // instead of landing on the HF login page.
+        if (options?.prompt) {
+            const u = new URL(url);
+            u.searchParams.set('prompt', options.prompt);
+            url = u.toString();
+        }
+        window.location.href = url;
     }
     logout() {
-        sessionStorage.removeItem('hf_token');
-        sessionStorage.removeItem('hf_username');
-        sessionStorage.removeItem('hf_token_expires');
+        clearStoredToken();
         this._username = null;
         this._tokenExpires = null;
         this.disconnect();
@@ -379,7 +416,7 @@ export class ReachyMini extends EventTarget {
                     await this.ensureAwake();
                 }
                 catch (e) {
-                    console.warn('[reachy-mini] autoConnect: ensureAwake failed:', e);
+                    log.warn('autoConnect: ensureAwake failed:', e);
                 }
             }
             return { robotId, robotName, isEmbedded: this.isEmbedded };
@@ -413,7 +450,7 @@ export class ReachyMini extends EventTarget {
             return Array.from(seen.values()).sort((a, b) => (a.lastSeenAgeSeconds ?? Infinity) - (b.lastSeenAgeSeconds ?? Infinity));
         }
         catch (e) {
-            console.warn('[reachy-mini] /api/robot-status unavailable, using SSE list:', e);
+            log.warn('/api/robot-status unavailable, using SSE list:', e);
             return (this._robots || []).map((r) => ({
                 id: r.id,
                 name: r.meta?.name ?? null,
@@ -443,6 +480,14 @@ export class ReachyMini extends EventTarget {
         });
     }
     async startSession(robotId) {
+        // An explicit dial from the app supersedes any in-flight
+        // auto-reconnect (possibly towards a different robot). The
+        // redial loop dials through `_startSessionInternal` directly,
+        // so its own attempts never trip this.
+        this._supervisor.cancelRedial();
+        return this._startSessionInternal(robotId);
+    }
+    async _startSessionInternal(robotId) {
         if (this._state !== 'connected')
             throw new Error('Not connected');
         this._selectedRobotId = robotId;
@@ -481,7 +526,7 @@ export class ReachyMini extends EventTarget {
             this._micMuted = true;
         }
         catch (e) {
-            console.warn('Audio sender placeholder setup failed:', e);
+            log.warn('audio sender placeholder setup failed:', e);
             this._micStream = null;
         }
         this._pc = new RTCPeerConnection({
@@ -489,7 +534,7 @@ export class ReachyMini extends EventTarget {
         });
         // Scope `networkOnline` / `networkOffline` / `networkChange`
         // event forwarding to the lifetime of this session.
-        this._installNetworkListeners();
+        this._supervisor.installNetworkListeners();
         return new Promise((resolve, reject) => {
             this._sessionResolve = resolve;
             this._sessionReject = reject;
@@ -533,35 +578,50 @@ export class ReachyMini extends EventTarget {
                 this._emit('iceStateChange', { state: s });
                 if (s === 'connected' || s === 'completed') {
                     // Healed — cancel any pending grace from a previous blip.
-                    this._clearIceGrace();
+                    this._supervisor.onIceHealed();
                     this._iceConnected = true;
                     this._checkSessionReady();
                     return;
                 }
                 if (s === 'disconnected') {
-                    // TRANSIENT per spec — debounce before escalating.
-                    // If the tab is hidden, JS timers are throttled and
-                    // would fire unpredictably late, so defer the grace
-                    // window to the next foreground frame.
-                    if (typeof document !== 'undefined' && document.hidden) {
-                        this._armIceGraceOnVisibility();
-                    }
-                    else {
-                        this._scheduleIceGrace(ICE_DISCONNECT_GRACE_MS, 'disconnected');
-                    }
+                    this._supervisor.onIceDisconnected();
                     return;
                 }
                 if (s === 'failed') {
-                    // Terminal per spec, but in practice we've seen
-                    // `failed → connected` on rapid AP roams / BT route
-                    // changes on iOS. Give the ICE agent a short window
-                    // to surprise us before rejecting the session.
-                    this._scheduleIceGrace(ICE_FAILED_GRACE_MS, 'failed');
+                    this._supervisor.onIceFailed();
                     return;
                 }
             };
             this._pc.ondatachannel = (e) => {
-                this._dc = e.channel;
+                const ch = e.channel;
+                // On `subscribe_pose` the daemon opens a second,
+                // unreliable/unordered channel labelled "pose" that *pushes*
+                // the robot state at ~30 Hz (see media_server
+                // `_setup_pose_channel`), so this can fire mid-session. It
+                // carries the same `{state:{...}}` envelope as a get_state
+                // reply, so we route it through the same handler - but it
+                // must NOT gate session readiness (that's the reliable
+                // control channel's job) nor become `_dc` (commands must
+                // never ride the lossy channel).
+                if (ch.label === 'pose') {
+                    // Fresh channel (new session or daemon restart): the
+                    // daemon's seq counter may have reset, so forget the old
+                    // high-water mark or we'd drop every new frame.
+                    this._lastPoseSeq = null;
+                    ch.onmessage = (ev) => {
+                        const msg = JSON.parse(ev.data);
+                        // Drop stale/reordered frames (unordered channel).
+                        if (typeof msg.seq === 'number') {
+                            if (this._lastPoseSeq !== null && msg.seq <= this._lastPoseSeq)
+                                return;
+                            this._lastPoseSeq = msg.seq;
+                        }
+                        this._lastPoseFrameAt = Date.now();
+                        this._handleRobotMessage(msg, true);
+                    };
+                    return;
+                }
+                this._dc = ch;
                 this._dc.onopen = () => {
                     this._dcOpen = true;
                     this._checkSessionReady();
@@ -578,78 +638,31 @@ export class ReachyMini extends EventTarget {
             });
         });
     }
-    _failSessionRejected(msg) {
-        const err = new Error(msg.reason === 'robot_busy'
-            ? `Robot is busy: "${msg.activeApp || 'another app'}" is already connected`
-            : `Session rejected: ${msg.reason || 'unknown reason'}`);
-        err.reason = msg.reason ?? null;
-        err.activeApp = msg.activeApp ?? null;
-        // Resilience teardown BEFORE closing `_pc` so a queued grace
-        // callback can't dereference a dead handle.
-        this._clearIceGrace();
-        this._uninstallNetworkListeners();
-        if (this._pc) {
-            this._pc.close();
-            this._pc = null;
-        }
-        if (this._micStream) {
-            this._micStream.getTracks().forEach((t) => t.stop());
-            this._micStream = null;
-        }
-        this._iceConnected = false;
-        this._dcOpen = false;
-        this._micMuted = true;
-        this._micSupported = false;
-        this._emit('sessionRejected', { reason: msg.reason, activeApp: msg.activeApp });
+    /**
+     * Common transport teardown shared by every session-ending path
+     * (stopSession, disconnect, the auto-redial, a session rejection):
+     * settle the pending-reply ledger and the startSession() resolvers
+     * with `settleErr`, stand the resilience plumbing down, stop the
+     * session-scoped timers, release the mic placeholder and close the
+     * pc/dc. Returns the session id (already cleared on the instance)
+     * so each caller decides whether and how to send `endSession`.
+     * What else differs — events, subscriber wipes, where `_state`
+     * lands — stays with the callers.
+     */
+    _closeTransport(settleErr) {
+        this._pending.settleAll(settleErr);
         if (this._sessionReject) {
             const reject = this._sessionReject;
             this._sessionResolve = null;
             this._sessionReject = null;
-            reject(err);
-        }
-    }
-    async stopSession() {
-        if (this._versionResolve) {
-            this._versionResolve(null);
-            this._versionResolve = null;
-        }
-        if (this._hardwareIdResolve) {
-            this._hardwareIdResolve(null);
-            this._hardwareIdResolve = null;
-        }
-        if (this._volumeResolve) {
-            this._volumeResolve(null);
-            this._volumeResolve = null;
-        }
-        if (this._micVolumeResolve) {
-            this._micVolumeResolve(null);
-            this._micVolumeResolve = null;
-        }
-        if (this._trackedFaceResolve) {
-            this._trackedFaceResolve(null);
-            this._trackedFaceResolve = null;
-        }
-        if (this._applyAudioConfigResolve) {
-            this._applyAudioConfigResolve(false);
-            this._applyAudioConfigResolve = null;
-        }
-        if (this._readAudioParameterResolve) {
-            this._readAudioParameterResolve(null);
-            this._readAudioParameterResolve = null;
-        }
-        this._logSubscribers.clear();
-        this._updateProgressSubscribers.clear();
-        this._rejectPendingMotionCompletions(new Error('Session stopped'));
-        this._rejectPendingRpc(new Error('Session stopped'));
-        // Tear down resilience plumbing BEFORE closing `_pc` so a
-        // queued grace callback can't dereference a dead handle.
-        this._clearIceGrace();
-        this._uninstallNetworkListeners();
-        if (this._sessionReject) {
-            this._sessionReject(new Error('Session stopped'));
-            this._sessionResolve = null;
-            this._sessionReject = null;
+            reject(settleErr);
         }
+        this._sessionResolve = null;
+        // Resilience teardown BEFORE closing `_pc` so a queued grace
+        // callback can't dereference a dead handle.
+        this._supervisor.clearIceGrace();
+        this._supervisor.uninstallNetworkListeners();
+        this._supervisor.stopDcWatchdog();
         if (this._stateRefreshInterval) {
             clearInterval(this._stateRefreshInterval);
             this._stateRefreshInterval = null;
@@ -658,9 +671,6 @@ export class ReachyMini extends EventTarget {
             clearInterval(this._latencyMonitorId);
             this._latencyMonitorId = null;
         }
-        if (this._sessionId) {
-            await this._sendToServer({ type: 'endSession', sessionId: this._sessionId });
-        }
         if (this._micStream) {
             this._micStream.getTracks().forEach((t) => t.stop());
             this._micStream = null;
@@ -675,9 +685,38 @@ export class ReachyMini extends EventTarget {
             this._dc.close();
             this._dc = null;
         }
-        this._sessionId = null;
         this._iceConnected = false;
         this._dcOpen = false;
+        const sessionId = this._sessionId;
+        this._sessionId = null;
+        return sessionId;
+    }
+    _failSessionRejected(msg) {
+        const err = new Error(msg.reason === 'robot_busy'
+            ? `Robot is busy: "${msg.activeApp || 'another app'}" is already connected`
+            : `Session rejected: ${msg.reason || 'unknown reason'}`);
+        err.reason = msg.reason ?? null;
+        err.activeApp = msg.activeApp ?? null;
+        // No endSession: the robot side never granted this session.
+        this._closeTransport(err);
+        // During an auto-reconnect the rejection is expected noise (the
+        // robot side may still hold the dead session for a few seconds) —
+        // the loop retries, the app only sees `sessionReconnecting`.
+        if (!this._supervisor.redialing) {
+            this._emit('sessionRejected', { reason: msg.reason, activeApp: msg.activeApp });
+        }
+    }
+    async stopSession() {
+        // A deliberate stop always wins over a pending auto-reconnect:
+        // the in-flight dial attempt (if any) is rejected inside
+        // `_closeTransport`, and the loop exits on the cleared flag.
+        this._supervisor.cancelRedial();
+        this._logSubscribers.clear();
+        this._updateProgressSubscribers.clear();
+        const sessionId = this._closeTransport(new Error('Session stopped'));
+        if (sessionId) {
+            await this._sendToServer({ type: 'endSession', sessionId });
+        }
         const wasStreaming = this._state === 'streaming';
         if (wasStreaming) {
             this._state = 'connected';
@@ -685,259 +724,63 @@ export class ReachyMini extends EventTarget {
         }
     }
     disconnect() {
+        this._supervisor.cancelRedial();
         if (this._sseAbortController) {
             this._sseAbortController.abort();
             this._sseAbortController = null;
         }
-        if (this._versionResolve) {
-            this._versionResolve(null);
-            this._versionResolve = null;
-        }
-        if (this._hardwareIdResolve) {
-            this._hardwareIdResolve(null);
-            this._hardwareIdResolve = null;
-        }
-        if (this._volumeResolve) {
-            this._volumeResolve(null);
-            this._volumeResolve = null;
-        }
-        if (this._micVolumeResolve) {
-            this._micVolumeResolve(null);
-            this._micVolumeResolve = null;
-        }
-        if (this._trackedFaceResolve) {
-            this._trackedFaceResolve(null);
-            this._trackedFaceResolve = null;
-        }
-        if (this._applyAudioConfigResolve) {
-            this._applyAudioConfigResolve(false);
-            this._applyAudioConfigResolve = null;
-        }
-        if (this._readAudioParameterResolve) {
-            this._readAudioParameterResolve(null);
-            this._readAudioParameterResolve = null;
-        }
         this._logSubscribers.clear();
         this._updateProgressSubscribers.clear();
-        this._rejectPendingMotionCompletions(new Error('Disconnected'));
-        // Mirrors the resilience teardown in `stopSession()`.
-        this._clearIceGrace();
-        this._uninstallNetworkListeners();
-        if (this._sessionReject) {
-            this._sessionReject(new Error('Disconnected'));
-            this._sessionResolve = null;
-            this._sessionReject = null;
-        }
-        if (this._stateRefreshInterval) {
-            clearInterval(this._stateRefreshInterval);
-            this._stateRefreshInterval = null;
-        }
-        if (this._latencyMonitorId) {
-            clearInterval(this._latencyMonitorId);
-            this._latencyMonitorId = null;
+        const sessionId = this._closeTransport(new Error('Disconnected'));
+        if (sessionId && this._token) {
+            void this._sendToServer({ type: 'endSession', sessionId });
         }
-        if (this._sessionId && this._token) {
-            this._sendToServer({ type: 'endSession', sessionId: this._sessionId });
-        }
-        if (this._micStream) {
-            this._micStream.getTracks().forEach((t) => t.stop());
-            this._micStream = null;
-        }
-        if (this._pc) {
-            this._pc.close();
-            this._pc = null;
-        }
-        if (this._dc) {
-            this._dc.close();
-            this._dc = null;
-        }
-        this._sessionId = null;
-        this._micMuted = true;
-        this._micSupported = false;
-        this._iceConnected = false;
-        this._dcOpen = false;
         this._robots = [];
         this._state = 'disconnected';
         this._emit('disconnected', { reason: 'user' });
     }
-    // ─── Resilience: ICE-blip debounce + network awareness ───────────────
-    //
-    // Both halves below are intentionally generic (they don't know about
-    // motion, audio, or the FSM): they just smooth out browser-level
-    // events so the consumer's own state machine doesn't get torn down
-    // by routine WiFi/4G/screen-off noise.
+    // ─── Resilience: supervisor delegation ───────────────────────────────
+    // The policy lives in `session-supervisor.ts`; only the transport
+    // teardown below stays here because it manipulates the class's own
+    // private state.
     /**
-     * Cancel any pending ICE grace timer and visibility handler. Called
-     * on a healed `connected`/`completed` transition AND from the
-     * lifecycle teardown paths so a callback can't fire after `_pc`
-     * is closed.
-     */
-    _clearIceGrace() {
-        if (this._iceGraceTimer !== null) {
-            clearTimeout(this._iceGraceTimer);
-            this._iceGraceTimer = null;
-        }
-        this._iceGraceReason = null;
-        if (this._pendingVisibilityHandler && typeof document !== 'undefined') {
-            document.removeEventListener('visibilitychange', this._pendingVisibilityHandler);
-        }
-        this._pendingVisibilityHandler = null;
-    }
-    /**
-     * Start a grace window. After `ms`, re-check the live ICE state:
-     *   - If we healed back to `connected`/`completed`, the timer was
-     *     already cancelled in `oniceconnectionstatechange`, so we
-     *     never get here.
-     *   - If we're still in the originally-observed bad state (or
-     *     worse), surface the error and reject any pending session
-     *     promise. The original code path is preserved verbatim so
-     *     downstream consumers see the same `error` payload shape.
-     */
-    _scheduleIceGrace(ms, reason) {
-        // Coalesce: if a grace is already pending and the reason hasn't
-        // changed, keep the original timer so a flurry of identical
-        // transitions doesn't reset the clock. If the reason changed
-        // (typically `disconnected` → `failed`, but also the reverse on
-        // some Android WebViews), replace the timer with the new
-        // (reason, ms) pair — the latest signal wins.
-        if (this._iceGraceTimer !== null) {
-            if (this._iceGraceReason === reason)
-                return;
-            clearTimeout(this._iceGraceTimer);
-        }
-        this._iceGraceReason = reason;
-        this._iceGraceTimer = setTimeout(() => {
-            this._iceGraceTimer = null;
-            const r = this._iceGraceReason;
-            this._iceGraceReason = null;
-            const s = this._pc?.iceConnectionState;
-            if (s === 'connected' || s === 'completed')
-                return; // healed
-            if (r === 'disconnected' && s === 'disconnected') {
-                this._emit('error', {
-                    source: 'webrtc',
-                    error: new Error(`ICE stuck in 'disconnected' for > ${ms}ms`),
-                });
-                return;
-            }
-            if (r === 'failed' || s === 'failed') {
-                const err = new Error('ICE connection failed');
-                if (this._sessionReject) {
-                    this._sessionReject(err);
-                    this._sessionResolve = null;
-                    this._sessionReject = null;
-                }
-                this._emit('error', { source: 'webrtc', error: err });
-            }
-        }, ms);
-    }
-    /**
-     * `disconnected` while the tab is hidden. JS timers are throttled
-     * in background tabs (Chrome clamps to ~1 Hz, Safari can pause
-     * altogether), so a foreground grace timer would either miss the
-     * window or fire long after the connection healed. Wait for the
-     * tab to come back, then re-evaluate.
+     * Enable/disable the automatic session re-dial at runtime.
+     * Disabling also aborts any re-dial already in flight. Used by
+     * flows that EXPECT the transport to die — e.g. the daemon
+     * self-update, whose `systemctl restart` teardown must surface as
+     * `sessionStopped` immediately (it's the "install done, rebooting"
+     * signal), not get absorbed by ~22 s of doomed reconnect attempts
+     * against a robot that is rebooting anyway.
+     *
+     * Sharp edge: cancelling an in-flight re-dial leaves the session
+     * torn down without emitting `sessionStopped` or `error` — the
+     * caller owns the terminal event (see `ReachyMiniInstance`).
      */
-    _armIceGraceOnVisibility() {
-        if (this._pendingVisibilityHandler)
-            return;
-        const deferredAt = Date.now();
-        const handler = () => {
-            if (typeof document !== 'undefined' && document.hidden)
-                return;
-            document.removeEventListener('visibilitychange', handler);
-            this._pendingVisibilityHandler = null;
-            if (!this._pc)
-                return;
-            const s = this._pc.iceConnectionState;
-            if (s === 'connected' || s === 'completed')
-                return; // healed in bg
-            // Ceiling: if the user backgrounded past the daemon's
-            // ICE-consent freshness window the session is gone from
-            // the daemon's side regardless of what `_pc` reports
-            // locally. Running another foreground grace would tell
-            // the user "Reconnecting…" for a recovery that can never
-            // happen. Escalate immediately so the host renders the
-            // real "session expired" UX. See MAX_VISIBILITY_DEFER_MS.
-            if (Date.now() - deferredAt > MAX_VISIBILITY_DEFER_MS) {
-                const err = new Error('Session expired while tab was backgrounded');
-                if (this._sessionReject) {
-                    this._sessionReject(err);
-                    this._sessionResolve = null;
-                    this._sessionReject = null;
-                }
-                this._emit('error', { source: 'webrtc', error: err });
-                return;
-            }
-            if (s === 'failed') {
-                this._scheduleIceGrace(ICE_FAILED_GRACE_MS, 'failed');
-                return;
-            }
-            // Still disconnected when we came back — give it a normal
-            // foreground grace window now that timers fire reliably.
-            this._scheduleIceGrace(ICE_DISCONNECT_GRACE_MS, 'disconnected');
-        };
-        document.addEventListener('visibilitychange', handler);
-        this._pendingVisibilityHandler = handler;
+    setAutoReconnect(enabled) {
+        this._supervisor.setAutoReconnect(enabled);
     }
     /**
-     * Install browser-level network listeners and forward them as
-     * public `networkOnline` / `networkOffline` / `networkChange`
-     * events on this instance. Idempotent: called from
-     * `startSession()`, removed by `_uninstallNetworkListeners` on
-     * teardown. Reachable only when there's a live `window`
-     * (defensive guard for SSR / test environments).
-     *
-     * `online` / `offline` are semantically about CONNECTIVITY:
-     * "does the OS think we can reach the internet". They flip
-     * symmetrically.
-     *
-     * `connection.change` (NetworkInformation API, Chrome / Android
-     * WebView only) is semantically about the TRANSPORT: it fires
-     * on Wi-Fi → 4G swaps, AP roams, etc. without necessarily going
-     * through `offline`. We forward it as its own `networkChange`
-     * event rather than aliasing it onto `networkOnline`, so
-     * consumers don't have to guess whether they're seeing a real
-     * connectivity recovery or a silent transport swap.
+     * Transport-only teardown: everything stopSession() does EXCEPT the
+     * user-facing state flip (`sessionStopped` is not emitted, `_state`
+     * falls back to 'connected' so the re-dial can start a session).
+     * Pending promises that ride the dead channel are settled just like
+     * stopSession() settles them — callers see the same failure shape a
+     * manual stop would produce; that includes a timed-out dial
+     * attempt's own startSession() promise (its resolvers were left
+     * armed, and a late signaling reply could otherwise settle them
+     * against a closed pc).
      */
-    _installNetworkListeners() {
-        if (this._onlineHandler || typeof window === 'undefined')
-            return;
-        const onOnline = () => this._emit('networkOnline', {});
-        const onOffline = () => this._emit('networkOffline', {});
-        window.addEventListener('online', onOnline);
-        window.addEventListener('offline', onOffline);
-        this._onlineHandler = onOnline;
-        this._offlineHandler = onOffline;
-        const conn = navigator.connection;
-        if (conn && typeof conn.addEventListener === 'function') {
-            const onChange = () => this._emit('networkChange', {
-                effectiveType: conn.effectiveType,
-                downlink: conn.downlink,
-                rtt: conn.rtt,
-                saveData: conn.saveData,
-            });
-            conn.addEventListener('change', onChange);
-            this._connectionChangeHandler = onChange;
-        }
-    }
-    /** Counterpart to `_installNetworkListeners`. */
-    _uninstallNetworkListeners() {
-        if (typeof window !== 'undefined') {
-            if (this._onlineHandler) {
-                window.removeEventListener('online', this._onlineHandler);
-            }
-            if (this._offlineHandler) {
-                window.removeEventListener('offline', this._offlineHandler);
-            }
-        }
-        const conn = navigator.connection;
-        if (conn && this._connectionChangeHandler && typeof conn.removeEventListener === 'function') {
-            conn.removeEventListener('change', this._connectionChangeHandler);
-        }
-        this._onlineHandler = null;
-        this._offlineHandler = null;
-        this._connectionChangeHandler = null;
+    _teardownForRedial() {
+        const sessionId = this._closeTransport(new Error('Session reconnecting'));
+        // Free the robot-side slot: the relay refuses a second session
+        // while it still tracks the dead one, and only endSession (or its
+        // own consent-freshness timeout, ~30 s) clears it. Fire and
+        // forget — _sendToServer never throws.
+        if (sessionId && this._token) {
+            void this._sendToServer({ type: 'endSession', sessionId });
+        }
+        if (this._state === 'streaming')
+            this._state = 'connected';
     }
     // ─── Commands ────────────────────────────────────────────────────────
     /**
@@ -1051,6 +894,54 @@ export class ReachyMini extends EventTarget {
     playSound(file) {
         return this._sendCommand({ type: 'play_sound', file });
     }
+    playRecordedMove(moveName, { dataset, initialGotoDuration, } = {}) {
+        return this._sendCommand({
+            type: 'play_recorded_move',
+            move_name: moveName,
+            ...(dataset ? { dataset_name: dataset } : {}),
+            ...(initialGotoDuration && initialGotoDuration > 0
+                ? { initial_goto_duration: initialGotoDuration }
+                : {}),
+        });
+    }
+    /**
+     * Stop whatever move is currently playing on the daemon (recorded move,
+     * uploaded move, goto). Fire-and-forget and idempotent: the daemon acks
+     * ok with `stopped: false` when nothing was running. Returns `false` if
+     * the data channel is not open.
+     */
+    stopMove() {
+        return this._sendCommand({ type: 'stop_move' });
+    }
+    preloadDataset(dataset) {
+        return this._sendCommand({ type: 'preload_dataset', dataset_name: dataset });
+    }
+    /**
+     * Like `preloadDataset()`, but resolves once the daemon acks the preload
+     * (`{command: "preload_dataset", ...}` on the data channel), i.e. when the
+     * dataset is actually in the local HF cache. Resolves `true` on success,
+     * `false` when the daemon reports a download failure, and `null` on the
+     * fail-open timeout (download slower than `timeoutMs`, or a daemon that
+     * predates the command and never replies) - callers should proceed in all
+     * three cases, `playRecordedMove` still downloads on demand. Rejects when
+     * the data channel isn't open or the session tears down mid-flight.
+     */
+    preloadDatasetAndWait(dataset, { timeoutMs = 120000 } = {}) {
+        // Send before registering the waiter (same rationale as `request()`):
+        // a channel closed mid-flight rejects instead of hanging a waiter to
+        // its timeout.
+        if (!this.preloadDataset(dataset)) {
+            return Promise.reject(new Error('Data channel not open'));
+        }
+        return this._pending
+            .awaitBroadcast((m) => m.command === 'preload_dataset' && m.dataset_name === dataset, { timeoutMs, debugLabel: `preload_dataset(${dataset})` })
+            .then((m) => m.status === 'ok')
+            .catch((err) => {
+            if (err instanceof BroadcastTimeoutError)
+                return null;
+            throw err;
+        });
+    }
     clearIncomingAudio() {
         return this._sendCommand({ type: 'clear_incoming_audio' });
     }
@@ -1069,7 +960,7 @@ export class ReachyMini extends EventTarget {
         return this._sendCommand({ type: 'set_head_tracking', enabled: false });
     }
     getTrackedFace() {
-        return this._slotRoundtrip(() => this._trackedFaceResolve, (next) => { this._trackedFaceResolve = next; }, { type: 'get_tracked_face' });
+        return this._slotRoundtrip('tracked_face', { type: 'get_tracked_face' });
     }
     /**
      * Trigger a PyPI update of the daemon over the data channel. Remote
@@ -1107,30 +998,7 @@ export class ReachyMini extends EventTarget {
         if (!this._sendCommand({ type: command })) {
             return Promise.reject(new Error(`${command}: data channel not open`));
         }
-        return new Promise((resolve, reject) => {
-            const entry = {
-                resolve,
-                reject,
-                timer: setTimeout(() => {
-                    const queue = this._pendingMotionCompletions[command];
-                    const idx = queue.indexOf(entry);
-                    if (idx !== -1)
-                        queue.splice(idx, 1);
-                    reject(new Error(`${command} timed out after ${timeoutMs}ms`));
-                }, timeoutMs),
-            };
-            this._pendingMotionCompletions[command].push(entry);
-        });
-    }
-    _rejectPendingMotionCompletions(error) {
-        for (const command of Object.keys(this._pendingMotionCompletions)) {
-            const queue = this._pendingMotionCompletions[command];
-            while (queue.length) {
-                const entry = queue.shift();
-                clearTimeout(entry.timer);
-                entry.reject(error);
-            }
-        }
+        return this._pending.awaitMotion(command, timeoutMs);
     }
     isAwake() {
         const mode = this._robotState?.motor_mode;
@@ -1149,107 +1017,193 @@ export class ReachyMini extends EventTarget {
                 this.requestState();
             });
         }
-        if (this.isAwake())
+        // Gravity compensation counts as awake - the robot is standing - but
+        // it runs under current control, where the daemon ignores position
+        // targets outright. An app inheriting that state from its predecessor
+        // (a fast handoff cancels the daemon's idle reset, so the mode
+        // survives) would see every goto silently do nothing. Flip back to
+        // position control without replaying the emote: the robot is already
+        // up, and the daemon pins targets to the measured pose on the way in,
+        // so nothing snaps.
+        if (this._robotState?.motor_mode === 'gravity_compensation') {
+            log.info('ensureAwake: gravity compensation inherited, flipping to enabled (no emote)');
+            this.setMotorMode('enabled');
+            // Refresh the cache so a caller reading isAwake() right after us
+            // doesn't see the mode we just left.
+            this.requestState();
+            return true;
+        }
+        if (this.isAwake()) {
+            log.info('ensureAwake: already awake, nothing to do');
             return true;
-        this.wakeUp().catch(() => { });
+        }
+        // Await the trajectory: callers treat resolution as "robot ready for
+        // position targets", and the emote keeps moving the head for ~2 s
+        // after the command is acked - an app that starts commanding poses
+        // under it fights it. Failures are swallowed: a torn-down session or
+        // a daemon that never acks must not take the whole boot down with it.
+        log.info(`ensureAwake: robot asleep (motor_mode=${this._robotState?.motor_mode ?? 'unknown'}), playing wake-up`);
+        const wakeStartedAt = Date.now();
+        try {
+            await this.wakeUp({ timeoutMs: WAKE_TRAJECTORY_BUDGET_MS });
+            log.info(`ensureAwake: wake-up trajectory done in ${Date.now() - wakeStartedAt}ms`);
+        }
+        catch (e) {
+            /* timed out, or the session went away under us */
+            log.warn(`ensureAwake: wake-up not confirmed after ${Date.now() - wakeStartedAt}ms (continuing):`, e);
+        }
         return true;
     }
+    /**
+     * Query the daemon version. Resolves `null` when the daemon predates
+     * `get_version` (fail-open on the shared slot timeout) or the reply is
+     * superseded by session teardown.
+     */
     getVersion() {
-        return new Promise((resolve, reject) => {
-            if (!this._dc || this._dc.readyState !== 'open') {
-                reject(new Error('Data channel not open'));
-                return;
-            }
-            if (this._versionResolve) {
-                this._versionResolve(null);
-            }
-            this._versionResolve = resolve;
-            this._sendCommand({ type: 'get_version' });
-        });
+        return this._slotRoundtrip('version', { type: 'get_version' });
     }
     getHardwareId() {
-        return new Promise((resolve, reject) => {
-            if (!this._dc || this._dc.readyState !== 'open') {
-                reject(new Error('Data channel not open'));
-                return;
-            }
-            if (this._hardwareIdResolve) {
-                this._hardwareIdResolve(null);
-            }
-            this._hardwareIdResolve = resolve;
-            this._sendCommand({ type: 'get_hardware_id' });
-        });
+        return this._slotRoundtrip('hardware_id', { type: 'get_hardware_id' });
+    }
+    /**
+     * One-shot IMU reading (BMI088, wireless version only). Resolves `null`
+     * when the robot has no IMU (Lite, simulation) or the daemon predates
+     * the `get_imu` command (fail-open on the shared slot timeout).
+     */
+    getImu() {
+        return this._slotRoundtrip('imu', { type: 'get_imu' });
     }
     getVolume() {
-        return this._slotRoundtrip(() => this._volumeResolve, (next) => { this._volumeResolve = next; }, { type: 'get_volume' });
+        return this._slotRoundtrip('volume', { type: 'get_volume' });
     }
     setVolume(volume) {
-        return this._slotRoundtrip(() => this._volumeResolve, (next) => { this._volumeResolve = next; }, { type: 'set_volume', volume: clampVolume(volume) });
+        return this._slotRoundtrip('volume', { type: 'set_volume', volume: clampVolume(volume) });
     }
     getMicrophoneVolume() {
-        return this._slotRoundtrip(() => this._micVolumeResolve, (next) => { this._micVolumeResolve = next; }, { type: 'get_microphone_volume' });
+        return this._slotRoundtrip('mic_volume', { type: 'get_microphone_volume' });
     }
     setMicrophoneVolume(volume) {
-        return this._slotRoundtrip(() => this._micVolumeResolve, (next) => { this._micVolumeResolve = next; }, { type: 'set_microphone_volume', volume: clampVolume(volume) });
+        return this._slotRoundtrip('mic_volume', { type: 'set_microphone_volume', volume: clampVolume(volume) });
+    }
+    /**
+     * Query whether the first wake-up setup wizard has been completed.
+     * Robot-wide, persisted on the robot. Resolves `false` when pending,
+     * `true` when done, or `null` when the channel isn't open / the daemon
+     * predates the `get_first_wake_up` command (callers should fail-open
+     * and skip the wizard on `null`).
+     */
+    getFirstWakeUp() {
+        // Fail-open, so this never rejects: the wizard gate runs right after
+        // connect, which is exactly when the channel may not be open yet.
+        if (!this._dc || this._dc.readyState !== 'open')
+            return Promise.resolve(null);
+        return this._slotRoundtrip('first_wake_up', { type: 'get_first_wake_up' });
+    }
+    /**
+     * Persist the first wake-up wizard completion flag on the robot.
+     * Resolves with the stored value (or `null` on channel-closed).
+     */
+    setFirstWakeUp(isCompleted) {
+        if (!this._dc || this._dc.readyState !== 'open')
+            return Promise.resolve(null);
+        return this._slotRoundtrip('first_wake_up', { type: 'set_first_wake_up', is_completed: isCompleted });
+    }
+    /**
+     * Query the persisted robot display name. Resolves the stored name,
+     * `null` when none is set / the channel isn't open / the daemon predates
+     * the `get_robot_name` command.
+     */
+    getRobotName() {
+        return this._slotRoundtrip('robot_name', { type: 'get_robot_name' });
+    }
+    /**
+     * Set and persist the robot display name on the robot. Resolves with the
+     * stored (trimmed) name, or `null` on error / channel-closed. Applied live
+     * by the daemon (status + central relay + mDNS), so it takes effect right
+     * away without a restart; the persisted name also overrides --robot-name
+     * on the next start.
+     */
+    setRobotName(name) {
+        return this._slotRoundtrip('robot_name', { type: 'set_robot_name', name });
+    }
+    /**
+     * Sign this robot out of Hugging Face: asks the daemon to delete its
+     * stored HF token, which de-registers the robot from the central
+     * signaling relay (it disappears from its owner's robot list until it
+     * is set up again). Works over the WebRTC data channel, so it reaches
+     * the robot remotely (no LAN HTTP path required).
+     *
+     * Resolves `true` when the daemon acked success, `false` on a daemon
+     * error, or `null` when no ack arrives before the timeout (e.g. a
+     * daemon that predates the `delete_hf_token` command silently drops
+     * it). Rejects if the data channel isn't open. Note the sign-out
+     * drops the central relay, so the session may tear down right after
+     * the ack - callers should treat a post-call session drop as expected,
+     * and a successful sign-out may surface as `null` if teardown races
+     * ahead of the ack.
+     */
+    signOut() {
+        return this._slotRoundtrip('delete_hf_token', { type: 'delete_hf_token' });
     }
     applyAudioConfig(config, { verify = true } = {}) {
-        return this._slotRoundtrip(() => this._applyAudioConfigResolve, (next) => { this._applyAudioConfigResolve = next; }, { type: 'apply_audio_config', config, verify }).then((v) => v === true);
+        return this._slotRoundtrip('apply_audio_config', { type: 'apply_audio_config', config, verify })
+            .then((v) => v === true);
     }
     readAudioParameter(name) {
-        return this._slotRoundtrip(() => this._readAudioParameterResolve, (next) => { this._readAudioParameterResolve = next; }, { type: 'read_audio_parameter', name });
+        return this._slotRoundtrip('read_audio_parameter', { type: 'read_audio_parameter', name });
     }
     /**
      * Internal: send a command and await the matching daemon response in a
-     * named single-resolver slot. Used by the volume helpers and the
-     * XVF3800 audio-config helpers — every one of them has a strict
-     * request/response shape where a single in-flight call per slot is
-     * sufficient. If a previous request on the same slot is still
-     * pending when a new one comes in, the older promise is resolved to
-     * `null` so its caller doesn't hang forever.
-     *
-     * Slot access is passed in as getter/setter closures rather than a
-     * key into `this`: that keeps the helper fully generic-checked (T is
-     * inferred from the slot's resolver type at each call site) with no
-     * indexed-property casts.
+     * named single-resolver slot (see `PendingReplies.slotRoundtrip`).
+     * Every caller has a strict request/response shape where a single
+     * in-flight call per slot is sufficient.
      */
-    _slotRoundtrip(getSlot, setSlot, command) {
-        return new Promise((resolve, reject) => {
-            if (!this._dc || this._dc.readyState !== 'open') {
-                reject(new Error('Data channel not open'));
-                return;
-            }
-            const prev = getSlot();
-            if (prev)
-                prev(null);
-            let timer;
-            // Single settle path shared by the daemon response, supersession
-            // by a newer call, and the fail-open timeout below. It clears the
-            // timer once and detaches itself from the slot only if it's still
-            // the current occupant, so a stale settle (timed-out or superseded)
-            // can't clear a newer call's slot registration. The message handler
-            // stores `settle` (not `resolve`), so every response route funnels
-            // through here.
-            // Note: slots are keyed by command type, not request id, so this
-            // does not prevent a genuinely late daemon reply from being routed
-            // to a newer same-command caller — that cross-talk is inherent to
-            // the single-flight slot design and unchanged here.
-            const settle = (v) => {
-                if (timer !== undefined) {
-                    clearTimeout(timer);
-                    timer = undefined;
-                }
-                if (getSlot() === settle)
-                    setSlot(null);
-                resolve(v);
-            };
-            setSlot(settle);
-            timer = setTimeout(() => settle(null), SLOT_ROUNDTRIP_TIMEOUT_MS);
-            this._sendCommand(command);
-        });
+    _slotRoundtrip(slot, command) {
+        if (!this._dc || this._dc.readyState !== 'open') {
+            return Promise.reject(new Error('Data channel not open'));
+        }
+        return this._pending.slotRoundtrip(slot, () => { this._sendCommand(command); });
     }
     sendRaw(data) {
         return this._sendCommand(data);
     }
+    /**
+     * Generic command round-trip for daemon commands the SDK has no typed
+     * wrapper for (yet). Escape hatch so an app can use a newer daemon
+     * feature without waiting for an SDK release: sends `command` and
+     * resolves with the first robot message whose `command` field equals
+     * the sent `type` - the daemon's reply convention - or with `null` on
+     * the fail-open timeout (daemon predates the command, or the command
+     * is fire-and-forget and never replies).
+     *
+     * Rejects when the data channel isn't open or the session tears down
+     * mid-flight, mirroring the typed wrappers.
+     *
+     * Replies the SDK already consumes internally (`get_imu`,
+     * `get_volume`, ...) are swallowed by their own handlers and never
+     * reach this matcher - use the typed wrappers for those. Pass `match`
+     * for replies that don't follow the `command` echo convention.
+     */
+    request(command, { timeoutMs = SLOT_ROUNDTRIP_TIMEOUT_MS, match } = {}) {
+        // Send before registering the waiter (safe: replies arrive on a
+        // later task), so a channel closed mid-flight rejects instead of
+        // hanging a waiter to its timeout and resolving `null`.
+        if (!this._sendCommand(command)) {
+            return Promise.reject(new Error('Data channel not open'));
+        }
+        const predicate = match
+            ?? ((m) => m.command === command.type);
+        return this._pending
+            .awaitBroadcast(predicate, { timeoutMs, debugLabel: `request(${command.type})` })
+            .catch((err) => {
+            // Fail-open on the waiter timeout only; teardown rejections
+            // (settleAll) propagate to the caller like every other
+            // in-flight round-trip.
+            if (err instanceof BroadcastTimeoutError)
+                return null;
+            throw err;
+        });
+    }
     subscribeLogs({ onLine, onError }) {
         if (typeof onLine !== 'function') {
             throw new TypeError('subscribeLogs: onLine callback is required');
@@ -1273,6 +1227,30 @@ export class ReachyMini extends EventTarget {
     requestState() {
         return this._sendCommand({ type: 'get_state' });
     }
+    /**
+     * Ask the daemon to *push* the robot state (~30 Hz) over the dedicated
+     * unreliable/unordered `pose` data channel instead of polling get_state.
+     * Fires `state` events as frames arrive. No-op against an older daemon (no
+     * pose channel) - fall back to `requestState()` polling there.
+     *
+     * Refcounted: pair every `subscribePose()` with exactly one
+     * `unsubscribePose()`. Multiple consumers share a single daemon-side
+     * subscription; the daemon only stops pushing once the last one releases.
+     * If the channel isn't open yet (or the session later reconnects), the
+     * subscription is (re-)asserted from `_checkSessionReady`.
+     */
+    subscribePose() {
+        this._poseSubRefs++;
+        return this._sendCommand({ type: 'subscribe_pose' });
+    }
+    /** Release one pose-stream consumer; sends `unsubscribe_pose` on the last. */
+    unsubscribePose() {
+        if (this._poseSubRefs > 0)
+            this._poseSubRefs--;
+        if (this._poseSubRefs > 0)
+            return true; // still wanted by another consumer
+        return this._sendCommand({ type: 'unsubscribe_pose' });
+    }
     // ─── Audio ───────────────────────────────────────────────────────────
     setAudioMuted(muted) {
         this._audioMuted = muted;
@@ -1428,7 +1406,7 @@ export class ReachyMini extends EventTarget {
             });
         }
         catch (e) {
-            console.warn('playMove.onStarted threw:', e);
+            log.warn('playMove.onStarted threw:', e);
         }
         onProgress({ phase: 'playing', duration_s: startedAck.duration_s });
         const final = await this._waitForBroadcast((m) => m?.type === 'play_uploaded_move'
@@ -1513,20 +1491,8 @@ export class ReachyMini extends EventTarget {
     _emit(name, detail) {
         this.dispatchEvent(new CustomEvent(name, { detail }));
     }
-    _waitForBroadcast(predicate, { timeoutMs = 5000, debugLabel = '' } = {}) {
-        return new Promise((resolve, reject) => {
-            const slot = {
-                predicate,
-                resolve,
-                timer: setTimeout(() => {
-                    const i = this._broadcastWaiters.indexOf(slot);
-                    if (i !== -1)
-                        this._broadcastWaiters.splice(i, 1);
-                    reject(new Error(`broadcast timeout (${timeoutMs} ms): ${debugLabel}`));
-                }, timeoutMs),
-            };
-            this._broadcastWaiters.push(slot);
-        });
+    _waitForBroadcast(predicate, opts = {}) {
+        return this._pending.awaitBroadcast(predicate, opts);
     }
     async _awaitDataChannelDrain() {
         while (this._dc && this._dc.bufferedAmount > UPLOAD_BUFFERED_LOW_WATER) {
@@ -1554,13 +1520,13 @@ export class ReachyMini extends EventTarget {
                     body = await res.text();
                 }
                 catch { /* ignore */ }
-                console.warn(`[reachy-mini] /send rejected (${res.status}) for type=${message?.type}; body=${body || '<empty>'}`);
+                log.warn(`/send rejected (${res.status}) for type=${message?.type}; body=${body || '<empty>'}`);
                 return null;
             }
             return await res.json();
         }
         catch (e) {
-            console.error('Send error:', e);
+            log.error('signaling /send failed:', e);
             return null;
         }
     }
@@ -1579,21 +1545,7 @@ export class ReachyMini extends EventTarget {
      */
     rpcCall(method, params = {}, opts = {}) {
         const timeoutMs = opts.timeoutMs ?? 20000;
-        const id = `rpc-${++this._rpcCounter}`;
-        if (!this._sendCommand({ jsonrpc: '2.0', id, method, params })) {
-            return Promise.reject(new Error(`rpcCall(${method}): data channel not open`));
-        }
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this._pendingRpc.delete(id);
-                reject(new Error(`rpcCall(${method}) timed out after ${timeoutMs}ms`));
-            }, timeoutMs);
-            this._pendingRpc.set(id, {
-                resolve: (v) => resolve(v),
-                reject,
-                timer,
-            });
-        });
+        return this._pending.rpcRoundtrip(method, timeoutMs, (id) => this._sendCommand({ jsonrpc: '2.0', id, method, params }));
     }
     /**
      * Subscribe to a JSON-RPC notification (one-way event) pushed by the
@@ -1610,32 +1562,10 @@ export class ReachyMini extends EventTarget {
             this._rpcListeners.get(method)?.delete(cb);
         };
     }
-    _rejectPendingRpc(err) {
-        for (const pending of this._pendingRpc.values()) {
-            clearTimeout(pending.timer);
-            pending.reject(err);
-        }
-        this._pendingRpc.clear();
-    }
     _handleRpcMessage(data) {
         // Response to an rpcCall (correlated by id)...
-        if ('id' in data && data.id != null && ('result' in data || 'error' in data)) {
-            const pending = this._pendingRpc.get(data.id);
-            if (!pending)
-                return;
-            this._pendingRpc.delete(data.id);
-            clearTimeout(pending.timer);
-            if ('error' in data && data.error) {
-                const err = data.error;
-                const e = new Error(err.message ?? 'rpc error');
-                e.reason = err.data?.reason;
-                pending.reject(e);
-            }
-            else {
-                pending.resolve(data.result);
-            }
+        if (this._pending.settleRpcResponse(data))
             return;
-        }
         // ...or a one-way notification (event): dispatch to listeners.
         if (typeof data.method === 'string') {
             const params = data.params ?? {};
@@ -1644,7 +1574,7 @@ export class ReachyMini extends EventTarget {
                     cb(params);
                 }
                 catch (e) {
-                    console.error(`onNotification(${data.method}) threw:`, e);
+                    log.error(`onNotification(${data.method}) threw:`, e);
                 }
             }
         }
@@ -1653,7 +1583,23 @@ export class ReachyMini extends EventTarget {
         if (this._iceConnected && this._dcOpen && this._sessionResolve) {
             this._state = 'streaming';
             this.requestState();
-            this._stateRefreshInterval = setInterval(() => this.requestState(), 500);
+            // Re-assert a pose subscription that was requested before the data
+            // channel was open, or lost on reconnect (a fresh peer starts
+            // unsubscribed on the daemon). Sent raw so it doesn't touch the
+            // local refcount, which already reflects the live consumer count.
+            if (this._poseSubRefs > 0)
+                this._sendCommand({ type: 'subscribe_pose' });
+            // A fresh session has received no pose frame yet, so a timestamp
+            // left over from the previous one must not hold off the poll.
+            this._lastPoseFrameAt = 0;
+            this._stateRefreshInterval = setInterval(() => {
+                // Skip while the pose stream is already feeding state; see
+                // POSE_STREAM_FRESH_MS.
+                if (Date.now() - this._lastPoseFrameAt < POSE_STREAM_FRESH_MS)
+                    return;
+                this.requestState();
+            }, 500);
+            this._supervisor.startDcWatchdog();
             this._emit('streaming', { sessionId: this._sessionId, robotId: this._selectedRobotId });
             this._sessionResolve();
             this._sessionResolve = null;
@@ -1704,10 +1650,14 @@ export class ReachyMini extends EventTarget {
         if (this._sessionReject) {
             const err = new Error(friendly || `Session ended before it could start: ${reason || 'unknown reason'}`);
             err.reason = reason ?? null;
-            this._emit('sessionRejected', { reason, activeApp: null });
+            // Same suppression as _failSessionRejected: retries during an
+            // auto-reconnect must not surface as `sessionRejected`.
+            if (!this._supervisor.redialing) {
+                this._emit('sessionRejected', { reason, activeApp: null });
+            }
             // Resilience teardown alongside the PC close path.
-            this._clearIceGrace();
-            this._uninstallNetworkListeners();
+            this._supervisor.clearIceGrace();
+            this._supervisor.uninstallNetworkListeners();
             if (this._pc) {
                 this._pc.close();
                 this._pc = null;
@@ -1769,7 +1719,7 @@ export class ReachyMini extends EventTarget {
                             await this._pc.addIceCandidate(new RTCIceCandidate(ice));
                         }
                         catch (err) {
-                            console.warn('[reachy-mini] buffered ICE candidate rejected:', err);
+                            log.warn('buffered ICE candidate rejected:', err);
                         }
                     }
                 }
@@ -1793,78 +1743,76 @@ export class ReachyMini extends EventTarget {
             }
         }
         catch (e) {
-            console.error('WebRTC error:', e);
+            log.error('webrtc signaling failed:', e);
             this._emit('error', { source: 'webrtc', error: e });
         }
     }
-    _handleRobotMessage(data) {
+    /**
+     * @param fromPoseStream Frame came from the pushed `pose` channel rather
+     *   than the reliable control channel. Only those may refresh the state
+     *   mirror while the stream is live (see the `data.state` branch).
+     */
+    _handleRobotMessage(data, fromPoseStream = false) {
+        // Liveness stamp for the data-channel silence watchdog: every
+        // inbound message — control replies, broadcasts, pose frames —
+        // proves the transport is alive.
+        this._supervisor.stampDcInbound();
         // JSON-RPC frames (app control surface) are handled separately from
         // the legacy {command|type} robot messages that share this channel.
         if (data.jsonrpc === '2.0') {
             this._handleRpcMessage(data);
             return;
         }
-        if ('version' in data && this._versionResolve) {
-            this._versionResolve(data.version);
-            this._versionResolve = null;
+        // Bare `version` / `hardware_id` replies carry no `command` key:
+        // only swallow them when a waiter is actually pending, otherwise
+        // let the message fall through to the branches below.
+        if ('version' in data
+            && this._pending.settleReplySlot('version', data.version ?? null)) {
             return;
         }
-        if ('hardware_id' in data && this._hardwareIdResolve) {
-            this._hardwareIdResolve(data.hardware_id);
-            this._hardwareIdResolve = null;
+        if ('hardware_id' in data
+            && this._pending.settleReplySlot('hardware_id', data.hardware_id ?? null)) {
             return;
         }
         if (data.command === 'get_volume' || data.command === 'set_volume') {
-            if (this._volumeResolve) {
-                this._volumeResolve(data.status === 'error' ? null : data.volume);
-                this._volumeResolve = null;
-            }
+            this._pending.settleReplySlot('volume', data.status === 'error' ? null : data.volume);
             return;
         }
         if (data.command === 'get_microphone_volume' || data.command === 'set_microphone_volume') {
-            if (this._micVolumeResolve) {
-                this._micVolumeResolve(data.status === 'error' ? null : data.volume);
-                this._micVolumeResolve = null;
-            }
+            this._pending.settleReplySlot('mic_volume', data.status === 'error' ? null : data.volume);
+            return;
+        }
+        if (data.command === 'get_first_wake_up' || data.command === 'set_first_wake_up') {
+            this._pending.settleReplySlot('first_wake_up', data.status === 'error' ? null : !!data.is_completed);
+            return;
+        }
+        if (data.command === 'get_robot_name' || data.command === 'set_robot_name') {
+            this._pending.settleReplySlot('robot_name', data.status === 'error' ? null : (data.name ?? null));
+            return;
+        }
+        if (data.command === 'delete_hf_token') {
+            this._pending.settleReplySlot('delete_hf_token', data.status !== 'error');
             return;
         }
         if (data.command === 'apply_audio_config') {
-            if (this._applyAudioConfigResolve) {
-                this._applyAudioConfigResolve(data.error ? false : !!data.applied);
-                this._applyAudioConfigResolve = null;
-            }
+            this._pending.settleReplySlot('apply_audio_config', data.error ? false : !!data.applied);
             return;
         }
         if (data.command === 'read_audio_parameter') {
-            if (this._readAudioParameterResolve) {
-                this._readAudioParameterResolve(data.error ? null : (data.values ?? null));
-                this._readAudioParameterResolve = null;
-            }
+            this._pending.settleReplySlot('read_audio_parameter', data.error ? null : (data.values ?? null));
             return;
         }
         if (data.command === 'get_tracked_face') {
-            if (this._trackedFaceResolve) {
-                this._trackedFaceResolve(data.face_target ?? null);
-                this._trackedFaceResolve = null;
-            }
+            this._pending.settleReplySlot('tracked_face', data.face_target ?? null);
+            return;
+        }
+        if (data.command === 'get_imu') {
+            this._pending.settleReplySlot('imu', data.imu ?? null);
             return;
         }
         if ((data.command === 'wake_up' || data.command === 'goto_sleep')
-            && this._pendingMotionCompletions
-            && this._pendingMotionCompletions[data.command]) {
-            const queue = this._pendingMotionCompletions[data.command];
-            if (data.completed === true && queue.length > 0) {
-                const entry = queue.shift();
-                clearTimeout(entry.timer);
-                entry.resolve();
-                return;
-            }
-            if (data.error && queue.length > 0) {
-                const entry = queue.shift();
-                clearTimeout(entry.timer);
-                entry.reject(new Error(`${data.command}: ${data.error}`));
-                return;
-            }
+            && this._pending.settleMotion(data.command, data)) {
+            return;
         }
         if (data.type === 'log_line') {
             for (const sub of this._logSubscribers) {
@@ -1872,7 +1820,7 @@ export class ReachyMini extends EventTarget {
                     sub.onLine({ timestamp: data.timestamp, line: data.line });
                 }
                 catch (e) {
-                    console.error('subscribeLogs onLine threw:', e);
+                    log.error('subscribeLogs onLine threw:', e);
                 }
             }
             return;
@@ -1884,7 +1832,7 @@ export class ReachyMini extends EventTarget {
                         sub.onError(data.error);
                     }
                     catch (e) {
-                        console.error('subscribeLogs onError threw:', e);
+                        log.error('subscribeLogs onError threw:', e);
                     }
                 }
             }
@@ -1902,7 +1850,7 @@ export class ReachyMini extends EventTarget {
                         cb(event);
                     }
                     catch (e) {
-                        console.error('startDaemonUpdate onProgress threw:', e);
+                        log.error('startDaemonUpdate onProgress threw:', e);
                     }
                 }
             }
@@ -1919,17 +1867,30 @@ export class ReachyMini extends EventTarget {
                     cb(event);
                 }
                 catch (e) {
-                    console.error('startDaemonUpdate onProgress threw:', e);
+                    log.error('startDaemonUpdate onProgress threw:', e);
                 }
             }
             return;
         }
-        if (data.state) {
+        // Only the stream may write the mirror while the stream is live. The
+        // poll stands down in that case (see POSE_STREAM_FRESH_MS), but it
+        // can't unsend a request already in flight: `get_state` rides the
+        // reliable channel, so its reply queues behind whatever else is on it
+        // - a `upload_move_*` burst, typically - and can land hundreds of ms
+        // after the snapshot it carries. Having no `seq`, it slips past the
+        // stale-frame guard and rewinds every consumer to a pose from before
+        // the upload, until the next pushed frame puts them back. That reads
+        // as a one-frame flick to the pre-move pose right as an animation
+        // starts. Nothing is lost by dropping it: pushed frames carry the same
+        // fields (daemon-side `build_state_dict` feeds both).
+        if (data.state && (fromPoseStream || Date.now() - this._lastPoseFrameAt >= POSE_STREAM_FRESH_MS)) {
             const s = data.state;
             if (s.head_pose)
                 this._robotState.head = s.head_pose.flat();
             if (s.antennas)
                 this._robotState.antennas = [s.antennas[0], s.antennas[1]];
+            if (s.head_joint_positions)
+                this._robotState.head_joint_positions = s.head_joint_positions;
             if (typeof s.body_yaw === 'number')
                 this._robotState.body_yaw = s.body_yaw;
             if (s.motor_mode)
@@ -1938,22 +1899,17 @@ export class ReachyMini extends EventTarget {
                 this._robotState.is_move_running = s.is_move_running;
             if (s.face_target)
                 this._robotState.face_target = s.face_target;
+            // DoA is null when there's no mic array / no reading yet - reflect
+            // that by clearing our mirror so stale angles don't linger.
+            if ('doa' in s)
+                this._robotState.doa = s.doa ?? undefined;
             this._emit('state', { ...this._robotState });
         }
         if (data.error) {
             this._emit('error', { source: 'robot', error: data.error });
         }
-        if (this._broadcastWaiters.length > 0) {
-            for (let i = this._broadcastWaiters.length - 1; i >= 0; i--) {
-                const slot = this._broadcastWaiters[i];
-                if (slot.predicate(data)) {
-                    this._broadcastWaiters.splice(i, 1);
-                    clearTimeout(slot.timer);
-                    slot.resolve(data);
-                    return;
-                }
-            }
-        }
+        if (this._pending.matchBroadcast(data))
+            return;
     }
     /** Snap video playback to live edge if buffered lag exceeds 0.5 s. */
     _startLatencyMonitor(video) {
@@ -1967,7 +1923,7 @@ export class ReachyMini extends EventTarget {
                 const end = buf.end(buf.length - 1);
                 const lag = end - video.currentTime;
                 if (lag > 0.5) {
-                    console.log(`Latency correction: was ${lag.toFixed(2)}s behind`);
+                    log.debug(`video latency correction: was ${lag.toFixed(2)}s behind`);
                     video.currentTime = end - 0.1;
                 }
             }