@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/engine.ts

@@ -7,6 +7,8 @@ import type {
   SdkSessionGrant,
   SdkTelemetryCredentials,
   SdkTelemetryEvent,
+  SessionCommandPollResult,
+  SessionCommandRecord,
   StartLivestreamInput,
 } from "./contracts";
 import {
@@ -18,6 +20,7 @@ import {
   SdkDisabledError,
   SessionConflictError,
   UnsupportedSdkError,
+  isSessionGoneError,
   normalizeError,
 } from "./errors";
 import { isSdkRemoteConfig, isSdkVersionSupported } from "./contracts";
@@ -39,6 +42,20 @@ export type RoomEvent =
   | { type: "command"; action: string };
 
 export interface RoomAdapter {
+  /**
+   * Xin quyền camera/mic theo cách của mode. Không có thì engine dùng
+   * runtime.requestPermissions() (getUserMedia của WebRTC — mở camera thật
+   * ~400ms). Mode device-rtmp PHẢI tự xin bằng API quyền thuần: máy Android
+   * MediaTek chỉ cho một camera mở, camera WebRTC chưa nhả là HaishinKit dính
+   * "Too many users (-87)" và preview đen.
+   */
+  requestPermissions?(): Promise<boolean>;
+  /**
+   * true = adapter KHÔNG tự nối lại khi rớt (RTMP: native chỉ báo
+   * "disconnected" rồi đứng im) — engine phải chủ động quay số lại qua retry().
+   * LiveKit bỏ trống: SDK của nó tự hồi và tự bắn "reconnected".
+   */
+  readonly needsManualReconnect?: boolean;
   /** Bật/tắt publish track khi đã ở trong phòng (standby ↔ live). */
   setPublishing?(enabled: boolean): Promise<void>;
   setCaptureOrientation?(orientation: CaptureOrientation): Promise<void>;
@@ -74,6 +91,23 @@ export interface SdkNetwork {
   subscribe(listener: (online: boolean) => void): () => void;
 }
 
+/**
+ * Khi app khởi động lại và thấy dấu của một phiên chưa được dừng có chủ ý, hàm
+ * này quyết định: GIỮ phiên đó để nhận lại, hay kết thúc nó như trước.
+ *
+ * Mặc định (không truyền) = kết thúc, giữ nguyên hành vi cho mọi SDK đối tác.
+ * App first-party trả true khi máy đang gán sân: lúc đó máy sụp nguồn giữa trận
+ * là chuyện của thiết bị gác sân, và nối lại đúng phiên cũ mới giữ được link xem
+ * và VOD liền mạch. Máy không gán sân thì vẫn dọn sạch như cũ.
+ */
+/**
+ * Được phép async có chủ đích: câu trả lời đúng nằm TRÊN ĐĨA (sân đã gán có
+ * persist), còn React state lúc engine khởi động thường CHƯA restore xong.
+ * Bản sync-đọc-state đã gây lỗi thật (18/08/2026): recover chạy trước restore
+ * → keep=false oan → app tự kết án phiên đáng giữ rồi arm phiên chờ THỨ HAI.
+ */
+export type KeepSessionOnRestart = () => boolean | Promise<boolean>;
+
 export interface TelemetrySink {
   send(
     credentials: SdkTelemetryCredentials,
@@ -82,14 +116,56 @@ export interface TelemetrySink {
   dispose?(): void;
 }
 
+/**
+ * Kênh nhận lệnh điều khiển cho mode device-rtmp: RTMP không có data channel
+ * nên start/stop/end từ server (match-start của trọng tài, dashboard) về qua
+ * HTTP poll, auth bằng chính telemetry token trong grant.
+ */
+export interface SessionCommandChannel {
+  poll(
+    credentials: SdkTelemetryCredentials,
+    after: number,
+  ): Promise<SessionCommandPollResult>;
+  dispose?(): void;
+}
+
+/**
+ * Kênh nhận lệnh device-rtmp qua WEBSOCKET (Convex subscription) — thay poll
+ * HTTP 2s cho máy first-party nối thẳng Convex. Lệnh về tức thì, lúc rảnh gần
+ * như 0 function call (poll 2s ở 200 máy là ~518M call/tháng). Có kênh này thì
+ * engine hạ poll về nhịp reconcile chậm làm lưới an toàn; thiếu thì poll như cũ.
+ */
+export interface SessionCommandSubscription {
+  /**
+   * Mở subscription cho phiên; `onCommands` được gọi mỗi lần hàng lệnh đổi
+   * (kể cả lần đầu). `onError` báo websocket/token hỏng để engine tăng lại nhịp
+   * poll. Trả hàm huỷ subscription (KHÔNG đóng client — tái dùng qua phiên).
+   */
+  subscribe(
+    credentials: SdkTelemetryCredentials,
+    sessionId: string,
+    onCommands: (commands: SessionCommandRecord[]) => void,
+    onError?: (error: Error) => void,
+  ): () => void;
+  dispose?(): void;
+}
+
 export interface EngineDependencies {
   sessionProvider: LivestreamSessionProvider;
   bootstrapInput: BootstrapInput;
   roomFactory: () => RoomAdapter;
+  keepSessionOnRestart?: KeepSessionOnRestart;
   runtime: SdkRuntime;
   storage: SdkStorage;
   network: SdkNetwork;
   telemetry?: TelemetrySink;
+  /** Kênh poll lệnh cho phiên device-rtmp; thiếu thì mode này điếc lệnh server. */
+  commandChannel?: SessionCommandChannel;
+  /**
+   * Kênh nhận lệnh qua websocket (first-party). Có thì lệnh về tức thì và poll
+   * tụt về nhịp reconcile; thiếu (máy đối tác qua proxy) thì chỉ dùng poll.
+   */
+  commandSubscription?: SessionCommandSubscription;
   /** Thu chỉ số thiết bị; gọi mỗi nhịp heartbeat khi đang phát. */
   deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
   now?: () => number;
@@ -113,6 +189,16 @@ export interface DeviceMetricsSample {
   storageFreeGb?: number;
   netType?: string;
   linkMbps?: number;
+  /** Cường độ sóng WiFi 0-100% — CHỈ Android (iOS không mở cho app). */
+  signalPct?: number;
+  /** IP nội bộ — phân biệt máy đang bám router nào, không cần quyền vị trí. */
+  localIp?: string;
+  /**
+   * Tần số kênh WiFi (MHz) — CHỈ Android. 2412–2484 = băng 2.4 GHz, ≥ 5000 =
+   * 5 GHz. Thay cho SSID (bị khoá sau quyền vị trí): 22/08/2026 một máy rơi từ
+   * AP 5 GHz của giải sang WiFi quán 2.4 GHz mà heartbeat không phân biệt được.
+   */
+  freqMhz?: number;
   rssi?: number;
   connQuality?: string;
   charging?: boolean;
@@ -136,11 +222,38 @@ export interface LivestreamSnapshot {
   selectedCameraId: string | null;
   elapsedMs: number;
   isOnline: boolean;
+  /**
+   * Phiên cũ còn sống mà app vừa khởi động lại có thể NHẬN LẠI (thay vì tạo phiên
+   * mới). Chỉ khác null khi engine tìm thấy dấu của một phiên chưa được dừng có
+   * chủ ý VÀ caller nói phiên đó đáng giữ (keepSessionOnRestart). Tầng trên
+   * (AutoResume) đọc trường này để nối lại đúng phiên cũ — giữ nguyên link xem và
+   * VOD liền một mạch.
+   */
+  adoptableSessionId: string | null;
 }
 
 const PENDING_END_KEY = "@pickleball/expo-sdk/pending-end";
+/**
+ * Khung 9:16/16:9 người dùng chọn lần cuối — dùng lại cho remote start
+ * (device-agent gọi prepare() khi app không ở màn chọn khung). Thiếu persist
+ * thì adapter RTMP đoán theo hướng UI: máy dọc mà khung ngang → ASPECT_FILL
+ * crop trên dưới, hình như bị zoom nặng.
+ */
+const CAPTURE_ORIENTATION_KEY = "@pickleball/expo-sdk/capture-orientation";
 /** Standby không phát quá lâu → tự kết thúc (config.standbyTimeoutMs ghi đè). */
 const DEFAULT_STANDBY_TIMEOUT_MS = 15 * 60_000;
+/** Poll lệnh device-rtmp: standby dày hơn để match-start bắt máy trong ~2s. */
+/** Còn dưới mức này mới đi xin token mới trong lúc quay số lại. */
+const TOKEN_REFRESH_MARGIN_MS = 2 * 60_000;
+const COMMAND_POLL_STANDBY_MS = 2_000;
+const COMMAND_POLL_LIVE_MS = 4_000;
+const COMMAND_POLL_MAX_BACKOFF_MS = 30_000;
+/**
+ * Nhịp poll khi ĐÃ có websocket đẩy lệnh: poll chỉ còn là lưới đối chiếu
+ * (bắt lệnh/status lỡ nếu ws chớp), không phải đường giao lệnh chính. 30s đủ
+ * dày để không kẹt quá lâu, đủ thưa để không phá mục tiêu cắt call ở 200 máy.
+ */
+const COMMAND_POLL_RECONCILE_MS = 30_000;
 const activeStates = new Set<LivestreamState>([
   "standby",
   "live",
@@ -210,10 +323,23 @@ export class LivestreamEngine {
   private backgroundTimer?: ReturnType<typeof setTimeout>;
   private standbyTimer?: ReturnType<typeof setTimeout>;
   private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private redialTimer?: ReturnType<typeof setTimeout>;
+  /** Đang trong vòng quay số lại — xem doRetry() để biết vì sao cần cờ này. */
+  private redialing = false;
   private heartbeatTimer?: ReturnType<typeof setInterval>;
   private elapsedTimer?: ReturnType<typeof setInterval>;
   private tokenRefreshTimer?: ReturnType<typeof setTimeout>;
   private maxSessionTimer?: ReturnType<typeof setTimeout>;
+  private commandPollTimer?: ReturnType<typeof setTimeout>;
+  /** Huỷ subscription websocket lệnh của phiên hiện tại (nếu đang mở). */
+  private commandUnsubscribe?: () => void;
+  /** Khoá phiên+token đang subscribe — đổi thì resubscribe (token refresh/đổi phiên). */
+  private commandSubscriptionKey?: string;
+  /** Websocket đã đẩy được ít nhất một lần → coi là sống, cho phép hạ nhịp poll. */
+  private commandSubscriptionActive = false;
+  /** issuedAt của lệnh cuối đã xử lý — server chỉ trả lệnh mới hơn mốc này. */
+  private commandCursor = 0;
+  private commandPollBackoffMs = 0;
   private grant?: SdkSessionGrant;
   private startedAt?: number;
   /** Đang publish track (live) hay chỉ ngồi trong phòng (standby). */
@@ -240,13 +366,18 @@ export class LivestreamEngine {
       sessionId: null,
       previewTrack: null,
       isMicrophoneEnabled: true,
-      isCameraFront: true,
+      // Camera SAU mặc định: thiết bị quay sân luôn dùng camera sau, bắt người
+      // dùng bấm đổi mỗi buổi là thừa. Phải khớp với mặc định của MỌI adapter
+      // (LiveKitRoomAdapter.isFront, module RTMP cameraPosition) — lệch một chỗ
+      // là nhãn UI và hình thực tế ngược nhau vĩnh viễn.
+      isCameraFront: false,
       captureOrientation: null,
       deviceMetrics: null,
       cameras: [],
       selectedCameraId: null,
       elapsedMs: 0,
       isOnline: dependencies.network.isOnline(),
+      adoptableSessionId: null,
     };
   }
 
@@ -329,12 +460,28 @@ export class LivestreamEngine {
         throw new UnsupportedSdkError();
       }
       this.update({ config: bootstrap.config });
-      const permitted = await this.dependencies.runtime.requestPermissions();
+      // Tạo room TRƯỚC khi xin quyền để adapter được chọn chiến lược: mode
+      // RTMP xin bằng API quyền thuần thay vì getUserMedia (xem RoomAdapter
+      // .requestPermissions). Constructor của adapter không đụng camera nên
+      // tạo sớm không có tác dụng phụ.
+      const room = this.ensureRoom();
+      const permitted = room.requestPermissions
+        ? await room.requestPermissions()
+        : await this.dependencies.runtime.requestPermissions();
       this.ensureOperation(generation);
       if (!permitted) {
         throw new PermissionDeniedError();
       }
-      const room = this.ensureRoom();
+      if (!this.snapshot.captureOrientation) {
+        // Khôi phục khung đã chọn lần trước (xem CAPTURE_ORIENTATION_KEY).
+        const stored = await this.dependencies.storage
+          .getItem(CAPTURE_ORIENTATION_KEY)
+          .catch(() => null);
+        this.ensureOperation(generation);
+        if (stored === "portrait" || stored === "landscape") {
+          this.update({ captureOrientation: stored });
+        }
+      }
       if (this.snapshot.captureOrientation) {
         await room.setCaptureOrientation?.(this.snapshot.captureOrientation);
       }
@@ -405,7 +552,7 @@ export class LivestreamEngine {
     this.transition("connecting");
     this.ensureBackgroundGraceTimer();
     try {
-      await this.ensurePendingEndResolved();
+      await this.ensurePendingEndResolved(input.externalSessionId);
       this.ensureOperation(generation);
     } catch (error) {
       if (
@@ -434,7 +581,13 @@ export class LivestreamEngine {
         );
       }
       this.ownedSessionId = grant.sessionId;
+      // Nhận lại xong thì thôi công bố: dấu đã hoàn thành vai trò chặn của nó.
+      if (this.snapshot.adoptableSessionId === grant.sessionId) {
+        this.update({ adoptableSessionId: null });
+      }
       this.grant = grant;
+      this.commandCursor = 0;
+      this.commandPollBackoffMs = 0;
       this.liveTimersStarted = false;
       this.keepAwakeActive = false;
       // Ghi sớm ý định phát để retry/reconnect khôi phục đúng trạng thái.
@@ -537,7 +690,23 @@ export class LivestreamEngine {
     if (!sessionId || !this.grant) throw new Error("Missing session grant");
     const activeGrant = this.grant;
     try {
-      await this.refreshCredentials(generation);
+      // Chỉ làm mới thông tin phiên khi token SẮP hết hạn. Trước đây gọi vô điều
+      // kiện mỗi nhịp quay số, dù token còn 15 phút — đó chính là thứ làm một lần
+      // thử "đắt" và buộc phải giãn nhịp ra. Bỏ nó thì mỗi nhịp chỉ còn đúng một
+      // cú bắt tay RTMP, nên thử nhanh không còn tốn gì đáng kể.
+      //
+      // Không mất đường biết phiên đã chết: vòng poll lệnh chạy song song mỗi
+      // 2-4 giây (commandPollingWanted có cả trạng thái reconnecting) và trả
+      // status "ended" ngay khi mạng về.
+      // CHỈ bỏ qua trong vòng quay số tự động. retry() thủ công và mode LiveKit
+      // vẫn làm mới như cũ: chúng hiếm khi chạy nên không có gì để tiết kiệm, và
+      // lần làm mới đó còn kéo về config mới nhất.
+      const expiresAt = this.grant?.tokenExpiresAt ?? 0;
+      const tokenStillFresh =
+        expiresAt > 0 && expiresAt - Date.now() >= TOKEN_REFRESH_MARGIN_MS;
+      if (!this.redialing || !tokenStillFresh) {
+        await this.refreshCredentials(generation);
+      }
       this.ensureOperation(generation);
       await this.requireRoom().connect({
         serverUrl: this.grant.serverUrl,
@@ -556,6 +725,34 @@ export class LivestreamEngine {
         await this.abandonGrant(activeGrant);
         return;
       }
+      // Server nói thẳng phiên không còn: 404 (đã biến mất) hoặc 409 (đã kết
+      // thúc — trọng tài bấm dừng / nhả sân trong lúc máy đang mất mạng). Thử lại
+      // không bao giờ cứu được, nên DỪNG thay vì quay số tới lưới cuối 1 giờ.
+      //
+      // Bám MÃ HTTP chứ không bám tên lớp lỗi: engine cũng tự ném
+      // SessionConflictError cho 4 tình huống CỤC BỘ (prepare khi đang có phiên,
+      // preview chưa sẵn…) và những lỗi đó không mang httpStatus. Bắt theo tên
+      // lớp là sẽ dừng nhầm ở lỗi nội bộ.
+      const httpStatus = (error as { httpStatus?: unknown }).httpStatus;
+      if (httpStatus === 404 || httpStatus === 409) {
+        this.stopRedialing();
+        void this.stop("user");
+        return;
+      }
+      // Một nhịp quay số trượt KHÔNG phải là phiên chết. Giữ nguyên state
+      // "reconnecting", chỉ ghi lỗi để chẩn đoán.
+      //
+      // Vì sao quan trọng: recordError đẩy state sang "error", mà
+      // TournamentController coi "error" là tín hiệu để (sau grace 90s) cắt
+      // phiên và arm phiên mới — tức là nó sẽ giết đúng cái phiên engine đang
+      // cố cứu. Trước bản này trần 75 giây che mất chuyện đó vì engine luôn
+      // buông trước; bỏ trần mà không sửa đây thì chỉ đổi kẻ giết phiên từ
+      // engine sang controller. "reconnecting" không nằm trong danh sách khiến
+      // controller re-arm, nên giữ nguyên state là đủ, không cần cờ mới ở đó.
+      if (this.redialing && this.snapshot.sessionId) {
+        this.update({ error: normalizeError(error) });
+        return;
+      }
       this.fail(error);
     }
   }
@@ -604,6 +801,10 @@ export class LivestreamEngine {
       if (!this.isOperationCurrent(generation)) return;
     }
     this.update({ captureOrientation: orientation });
+    // Nhớ bền lựa chọn để remote start dùng lại (CAPTURE_ORIENTATION_KEY).
+    void this.dependencies.storage
+      .setItem(CAPTURE_ORIENTATION_KEY, orientation)
+      .catch(() => undefined);
   }
 
   async setMicrophoneEnabled(enabled: boolean) {
@@ -616,11 +817,13 @@ export class LivestreamEngine {
   handleRoomEvent(event: RoomEvent) {
     if (this.disposed) return;
     // Lệnh từ dashboard (cùng giao thức với camera box): "start" bắt đầu
-    // phát, "stop" tạm dừng phát về standby — KHÔNG kết thúc phiên. Kết thúc
-    // phiên vẫn là hành động riêng (nút trên app / Kết thúc trên dashboard).
+    // phát, "stop" tạm dừng phát về standby — KHÔNG kết thúc phiên. "end"
+    // kết thúc hẳn phiên (match-end của đối tác qua REST theo sân) — chế độ
+    // giải đấu dựa vào đây để re-arm phiên standby mới cho trận kế tiếp.
     if (event.type === "command") {
       if (event.action === "start") void this.startPublishing();
       else if (event.action === "stop") void this.stopPublishing();
+      else if (event.action === "end") void this.stop("user");
       return;
     }
     if (
@@ -629,20 +832,65 @@ export class LivestreamEngine {
     ) {
       this.transition("reconnecting");
       void this.sendTelemetry("reconnect", { phase: "started" });
-      const timeout = this.snapshot.config?.reconnectTimeoutMs ?? 30_000;
+      if (this.room?.needsManualReconnect) {
+        // RTMP: KHÔNG có hạn giờ. Engine quay số tới khi nối lại được, hoặc tới
+        // khi biết chắc phiên đã bị kết thúc phía server (poll lệnh bên dưới),
+        // hoặc tới khi người ở sân bấm dừng.
+        //
+        // Trước bản này có trần 75 giây rồi tự gọi stop("network_timeout"). Đo
+        // thật 18/08/2026 với cú ngắt mạng 16 phút trên cả Android lẫn iOS: app
+        // buông ở giây 76 và tắt hẳn camera, nên mạng có về ở phút thứ 2 nó cũng
+        // không biết. Cái giá của việc buông KHÔNG phải "phiên chết" mà là: link
+        // xem đổi (người đang xem mất hẳn), VOD tách đôi, và stream key bị thu
+        // hồi nên chính thiết bị cũng không nối lại được phiên đó nữa.
+        //
+        // Vì sao app không có tư cách phán "phiên này chết": lúc mất mạng app
+        // chính là thằng mù. Chỉ server thấy được sự vắng mặt, và nó đã có lưới
+        // cuối riêng (RTMP_NO_PUBLISHER_GRACE_MS 1 giờ).
+        this.clearReconnectTimer();
+        this.scheduleRedial(0);
+        return;
+      }
+      // Mode LiveKit giữ nguyên: SDK của nó tự hồi, hết hạn thì kết thúc phiên.
+      const configured = this.snapshot.config?.reconnectTimeoutMs ?? 30_000;
       this.clearReconnectTimer();
       this.reconnectTimer = setTimeout(() => {
         void this.stop("network_timeout");
-      }, timeout);
+      }, configured);
       return;
     }
     if (event.type === "reconnected" && this.snapshot.state === "reconnecting") {
       this.clearReconnectTimer();
+      this.stopRedialing();
       this.transition(this.publishing ? "live" : "standby");
       void this.sendTelemetry("reconnect", { phase: "recovered" });
       return;
     }
-    if (event.type === "media-error") this.recordError(event.error);
+    if (event.type === "media-error") {
+      // Với adapter tự quay số (RTMP), media-error GIỮA luồng là mất kết nối chứ
+      // không phải án tử — xử lý y như "disconnected" thay vì ghi lỗi.
+      //
+      // Vì sao cần: RootEncoder trên Android báo broken pipe qua
+      // `onConnectionFailed` (RtmpSender: "send error: …"), module dịch thành
+      // status "error" → media-error, mà nhánh này trước đây CHỈ gọi recordError.
+      // Không ai mở vòng redial nên phiên nằm chết vĩnh viễn dù mạng đã về từ lâu
+      // — Android không phát lại được, trong khi iOS hồi được vì HaishinKit báo
+      // "disconnected" nên đi đúng nhánh dưới (báo cáo 18/08/2026; logcat Redmi:
+      // Acknowledgement tắt lúc 03:17:52 rồi không còn một lần connect nào nữa).
+      //
+      // KHÔNG được recordError trước rồi mới hồi phục: recordError chuyển state
+      // sang "error", mà "error" không thuộc activeStates và nhánh "reconnecting"
+      // chỉ nhận live/standby — ghi lỗi trước là tự khoá luôn đường hồi phục.
+      // Đánh đổi: mất chi tiết lỗi trong snapshot, bù lại bằng log native và
+      // telemetry "reconnect". Chỉ giới hạn trong needsManualReconnect: mode
+      // LiveKit tự hồi, kéo nó vào "reconnecting" chỉ để bật thêm doom timer là
+      // hại chứ không lợi.
+      if (this.room?.needsManualReconnect && activeStates.has(this.snapshot.state)) {
+        this.handleRoomEvent({ type: "reconnecting" });
+        return;
+      }
+      this.recordError(event.error);
+    }
     if (
       event.type === "disconnected" &&
       activeStates.has(this.snapshot.state)
@@ -681,12 +929,21 @@ export class LivestreamEngine {
     }, grace);
   }
 
-  dispose(): Promise<void> {
+  /**
+   * `keepSession` = engine bị tháo nhưng phiên phải sống tiếp để lần mở app sau
+   * nhận lại. Mặc định false: giữ NGUYÊN hành vi cũ cho mọi SDK đối tác.
+   *
+   * Lưu ý dispose KHÔNG BAO GIỜ là đường của "người dùng bấm dừng" — nút dừng đi
+   * qua doStop, mà doStop xoá ownedSessionId trước, nên tới đây sessionId đã là
+   * undefined. Vì vậy nhánh end ở đây luôn là teardown NGOÀI Ý MUỐN (app bị giết,
+   * component remount), đúng chỗ cần giữ phiên.
+   */
+  dispose(options?: { keepSession?: boolean }): Promise<void> {
     if (this.disposePromise) return this.disposePromise;
     if (this.disposed) return Promise.resolve();
     this.disposed = true;
     this.operationGeneration += 1;
-    const sessionId = this.ownedSessionId;
+    const sessionId = options?.keepSession === true ? undefined : this.ownedSessionId;
     let releaseEnd: () => void = () => undefined;
     const endBarrier = new Promise<void>((resolve) => {
       releaseEnd = resolve;
@@ -697,6 +954,7 @@ export class LivestreamEngine {
     const roomCleanup = this.releaseRoom(termination?.markerReady);
     this.clearTimers();
     this.dependencies.telemetry?.dispose?.();
+    this.dependencies.commandChannel?.dispose?.();
     this.pendingCriticalTelemetry = undefined;
     this.networkUnsubscribe();
     this.listeners.clear();
@@ -736,10 +994,52 @@ export class LivestreamEngine {
     this.pendingReplayError = undefined;
   }
 
+  /**
+   * Phiên tưởng đáng nhận lại hoá ra đã chết phía server → BỎ dấu để máy arm
+   * phiên mới được.
+   *
+   * Thiếu hàm này là máy kẹt cứng: dấu vẫn nằm đó chặn mọi lượt start (đúng vai
+   * trò chống phiên song song của nó), mà lượt start duy nhất được cho qua lại là
+   * lượt nhận lại chính cái phiên đã chết — không bao giờ thành công. Đã dính
+   * thật 18/08/2026: lưới standby 30 phút kết thúc phiên trong lúc máy ngủ, mở
+   * lại thì app đứng ở "error" vĩnh viễn.
+   */
+  async abandonAdoptableSession(sessionId: string): Promise<void> {
+    if (this.snapshot.adoptableSessionId !== sessionId) return;
+    try {
+      await this.dependencies.storage.removeItem(PENDING_END_KEY);
+    } catch {
+      // Xoá dấu hỏng thì lần mở sau thử lại — không được để nó chặn việc arm mới.
+    }
+    this.update({ adoptableSessionId: null });
+  }
+
   private async recoverStartupSession() {
     let pending = await this.readPendingEnd();
     if (!pending || this.ownsInMemorySession()) return;
     if (pending.pendingEnd === null) {
+      // pendingEnd === null nghĩa là phiên chưa từng được dừng CÓ CHỦ Ý — app
+      // biến mất giữa chừng (sụp nguồn, bị vuốt tắt, OEM giết). Trước đây chỗ này
+      // tự kết án "error" rồi gọi end(), tức chính app vừa mở lại là thứ giết
+      // phiên cũ — và nó chạy TRƯỚC heartbeat, TRƯỚC AutoResume nên đường nối lại
+      // không bao giờ có cơ hội.
+      //
+      // Nay: nếu caller nói phiên này đáng giữ (máy đang gác sân), để nguyên dấu
+      // và công bố id ra snapshot cho tầng trên nhận lại. KHÔNG xoá dấu — nó vẫn
+      // là thứ chặn việc tạo phiên MỚI song song, đúng vai trò gốc của nó; chỉ
+      // đổi điều kiện gỡ chặn từ "phiên cũ đã kết thúc" thành "phiên cũ đã được
+      // nhận lại hoặc xác nhận biến mất".
+      const keep = (await this.dependencies.keepSessionOnRestart?.()) === true;
+      // Mốc chẩn đoán CỐ Ý giữ lại: quyết định này xảy ra một lần lúc khởi động,
+      // không tái hiện được, và đoán sai nó thì mất phiên. Bản Release nuốt
+      // console.log nhưng warn vẫn tới logcat/Console.app.
+      console.warn(
+        `[picklive] khoi dong: phien ${pending.sessionId} chua duoc dung co chu y -> ${keep ? "GIU de nhan lai" : "ket thuc"}`,
+      );
+      if (keep) {
+        this.update({ adoptableSessionId: pending.sessionId });
+        return;
+      }
       pending = { sessionId: pending.sessionId, pendingEnd: "error" };
       await this.dependencies.storage.setItem(
         PENDING_END_KEY,
@@ -747,18 +1047,49 @@ export class LivestreamEngine {
       );
     }
     if (!this.dependencies.network.isOnline()) return;
-    await this.dependencies.sessionProvider.end({
-      sessionId: pending.sessionId,
-      reason: pending.pendingEnd ?? "error",
-    });
+    try {
+      await this.dependencies.sessionProvider.end({
+        sessionId: pending.sessionId,
+        reason: pending.pendingEnd ?? "error",
+      });
+    } catch (error) {
+      // CHỈ 404 mới xoá dấu: phiên đã biến mất hẳn (bị watchdog dọn, thuộc
+      // deployment khác, ID sai) nên thử lại bao nhiêu lần cũng vô ích, mà giữ
+      // dấu thì thiết bị bị khoá VĨNH VIỄN với thông báo "Đang có phiên phát
+      // khác" — box hết pin giữa trận là dính, chỉ gỡ được bằng cài lại app.
+      //
+      // Mất mạng hay 5xx thì KHÔNG xoá: phiên cũ có thể vẫn đang chạy thật, xoá
+      // dấu sẽ dẫn tới hai phiên live song song.
+      if (!isSessionGoneError(error)) throw error;
+    }
     await this.dependencies.storage.removeItem(PENDING_END_KEY);
     this.pendingReplayError = undefined;
   }
 
-  private async ensurePendingEndResolved() {
+  /**
+   * Dấu phiên cũ chặn thao tác mới cho tới khi nó được giải quyết.
+   *
+   * `externalSessionId` = id lượt start đang xin đi qua; bỏ trống nghĩa là
+   * prepare (mở camera), vốn phải luôn được phép khi đang định nhận lại — không
+   * mở được camera thì không nhận lại được, và đó chính là bẫy làm máy kẹt cứng ở
+   * màn lỗi "The previous livestream is still pending end".
+   */
+  private async ensurePendingEndResolved(externalSessionId?: string) {
     await this.initialize();
     const pending = await this.readPendingEnd();
     if (!pending) return;
+    // Phiên đang chờ NHẬN LẠI: dấu đổi vai trò, không còn là án tử mà là chốt
+    // chặn phiên song song. Cho qua đúng hai thứ — prepare, và lượt start nhận
+    // lại CHÍNH phiên đó. Mọi lượt start khác vẫn bị chặn như cũ, nên bảo đảm
+    // "không bao giờ có hai phiên live song song" giữ nguyên.
+    if (
+      pending.pendingEnd === null &&
+      this.snapshot.adoptableSessionId === pending.sessionId &&
+      (externalSessionId === undefined ||
+        externalSessionId === `resume-${pending.sessionId}`)
+    ) {
+      return;
+    }
     if (!this.dependencies.network.isOnline()) {
       throw new NetworkUnavailableError(
         "Connect to the network to finish the previous livestream",
@@ -862,6 +1193,8 @@ export class LivestreamEngine {
     if (this.tokenRefreshTimer) clearTimeout(this.tokenRefreshTimer);
     if (this.maxSessionTimer) clearTimeout(this.maxSessionTimer);
     this.clearReconnectTimer();
+    this.stopCommandPolling();
+    this.stopCommandSubscription();
     this.backgroundTimer = undefined;
     this.heartbeatTimer = undefined;
     this.elapsedTimer = undefined;
@@ -871,11 +1204,236 @@ export class LivestreamEngine {
     this.liveTimersStarted = false;
   }
 
+  /**
+   * Quay số lại với backoff cho adapter cần reconnect thủ công. Mỗi nhịp gọi
+   * retry() (refresh credentials + room.connect + enterSession). Thành công →
+   * enterSession phát "publishing" → nhánh "reconnected" dọn cả hai timer.
+   * Thất bại → doRetry() đưa state về "error" (vẫn còn sessionId) và nhịp sau
+   * retry() lại kéo về "reconnecting" — lặp tới khi doom timer 30s kết liễu.
+   * Backoff thưa dần để không dội server khi ingest thật sự sập.
+   */
+  private scheduleRedial(attempt: number) {
+    this.clearRedialTimer();
+    this.redialing = true;
+    // Biết chắc đang mất mạng thì đừng thử: mọi lần thử đều trượt, và sự kiện
+    // "mạng đã về" chắc chắn sẽ tới (ensureNetworkSubscription) rồi quay số lại
+    // từ nhịp 0. Đây là thứ cho phép nhịp đầu bằng 0 mà không tạo vòng lặp rỗng.
+    if (!this.dependencies.network.isOnline()) return;
+    // Nhịp đầu = 0: có mạng thì nối lại NGAY, không đợi đồng hồ nào.
+    //
+    // Vì sao trước đây giãn đều là sai: chi phí một lần thử phụ thuộc hoàn toàn
+    // vào LÝ DO thất bại. Mất mạng thật thì cả hai lệnh (Convex + bắt tay RTMP)
+    // trượt tức thì, không ra khỏi máy — thử mỗi giây cũng gần như miễn phí.
+    // Chỉ ca "có mạng mà bị từ chối" mới tốn thật, và đuôi thưa bên dưới lo ca đó.
+    // Giãn đều là bắt ca rẻ trả giá cho ca đắt.
+    const delays = [0, 1_000, 2_000, 4_000, 8_000, 15_000, 30_000];
+    const delay = delays[Math.min(attempt, delays.length - 1)];
+    this.redialTimer = setTimeout(() => {
+      if (this.disposed) return;
+      const s = this.snapshot.state;
+      // Chỉ còn ý nghĩa khi vẫn đang kẹt: reconnecting, hoặc error-còn-phiên
+      // (doRetry thất bại nhịp trước). Mọi trạng thái khác = đã hồi/đã kết thúc.
+      if (s !== "reconnecting" && !(s === "error" && this.snapshot.sessionId)) {
+        return;
+      }
+      void this.retry()
+        .catch(() => {})
+        .finally(() => {
+          if (this.disposed) return;
+          const after = this.snapshot.state;
+          if (after === "reconnecting" || (after === "error" && this.snapshot.sessionId)) {
+            this.scheduleRedial(attempt + 1);
+          }
+        });
+    }, delay);
+  }
+
+  private clearRedialTimer() {
+    if (this.redialTimer) clearTimeout(this.redialTimer);
+    this.redialTimer = undefined;
+  }
+
+  private stopRedialing() {
+    this.redialing = false;
+    this.clearRedialTimer();
+  }
+
   private clearReconnectTimer() {
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     this.reconnectTimer = undefined;
   }
 
+  /**
+   * Poll lệnh chỉ khi phiên là device-rtmp (grant rtmp://) và đang standby/
+   * live. Ngoài hai trạng thái đó không có gì để điều khiển: connecting chưa
+   * có phiên chạy, reconnecting đã có reconnect timer lo, ending/ended thì thôi.
+   */
+  private commandPollingWanted() {
+    const grant = this.grant;
+    return Boolean(
+      this.dependencies.commandChannel &&
+        grant &&
+        /^rtmps?:\/\//i.test(grant.serverUrl) &&
+        // "reconnecting" PHẢI có trong danh sách này. Sau khi bỏ trần 75 giây,
+        // máy có thể quay số hàng giờ; nếu trong lúc đó trọng tài kết thúc trận
+        // hoặc nhả sân, đây là đường duy nhất để máy biết mà thôi quay số vào một
+        // phiên đã chết (poll trả status "ended" → nhánh ở pollSessionCommands).
+        // Trước đây chỉ poll ở standby/live nên máy mất mạng là mù hoàn toàn.
+        activeStates.has(this.snapshot.state),
+    );
+  }
+
+  private syncCommandPolling() {
+    if (this.disposed || !this.commandPollingWanted()) {
+      this.stopCommandPolling();
+      this.stopCommandSubscription();
+      return;
+    }
+    this.syncCommandSubscription();
+    // Poll ngay khi vào standby/live — lệnh có thể đã chờ sẵn (match-start
+    // bắn "start" trong lúc app còn đang connect). Có websocket thì poll vẫn
+    // chạy làm lưới, chỉ ở nhịp reconcile chậm (commandPollInterval).
+    if (!this.commandPollTimer) this.scheduleCommandPoll(0);
+  }
+
+  /**
+   * Mở/đổi websocket nhận lệnh cho phiên hiện tại. Chỉ máy first-party có
+   * dependency này (đối tác qua proxy thì undefined → chỉ poll). Resubscribe
+   * khi đổi phiên HOẶC token (refresh) vì cả hai đi vào khoá.
+   */
+  private syncCommandSubscription() {
+    const subscription = this.dependencies.commandSubscription;
+    const grant = this.grant;
+    if (!subscription || !grant) return;
+    const key = `${grant.sessionId}:${grant.telemetry.token}`;
+    if (this.commandSubscriptionKey === key) return;
+    this.stopCommandSubscription();
+    this.commandSubscriptionKey = key;
+    const sessionId = grant.sessionId;
+    this.commandUnsubscribe = subscription.subscribe(
+      grant.telemetry,
+      sessionId,
+      (commands) => {
+        // Phiên đã đổi trong lúc callback bay tới → bỏ (thuộc phiên cũ).
+        if (this.disposed || this.grant?.sessionId !== sessionId) return;
+        // Lần đẩy đầu tiên xác nhận ws sống → cho phép hạ poll về reconcile.
+        this.commandSubscriptionActive = true;
+        this.applyCommands(commands);
+      },
+      () => {
+        // Websocket/token hỏng → coi như chưa có ws, poll tăng lại nhịp nhanh
+        // ở lần lên lịch kế. Không đóng gì ở đây: ConvexClient tự nối lại, và
+        // token refresh sẽ resubscribe qua khoá đổi.
+        this.commandSubscriptionActive = false;
+      },
+    );
+  }
+
+  private stopCommandSubscription() {
+    if (this.commandUnsubscribe) {
+      try {
+        this.commandUnsubscribe();
+      } catch {
+        /* huỷ subscription lỗi — kệ, engine đang dọn dẹp */
+      }
+    }
+    this.commandUnsubscribe = undefined;
+    this.commandSubscriptionKey = undefined;
+    this.commandSubscriptionActive = false;
+  }
+
+  private stopCommandPolling() {
+    if (this.commandPollTimer) clearTimeout(this.commandPollTimer);
+    this.commandPollTimer = undefined;
+    this.commandPollBackoffMs = 0;
+  }
+
+  private scheduleCommandPoll(delayMs: number) {
+    this.commandPollTimer = setTimeout(() => {
+      this.commandPollTimer = undefined;
+      void this.pollSessionCommands();
+    }, delayMs);
+    (this.commandPollTimer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  private commandPollInterval() {
+    // Websocket đang đẩy lệnh → poll chỉ là lưới đối chiếu nhịp chậm. Chưa xác
+    // nhận ws sống (chưa đẩy lần nào, hoặc vừa lỗi) thì giữ nhịp nhanh như cũ.
+    if (this.commandSubscriptionActive) return COMMAND_POLL_RECONCILE_MS;
+    return this.snapshot.state === "live"
+      ? COMMAND_POLL_LIVE_MS
+      : COMMAND_POLL_STANDBY_MS;
+  }
+
+  /**
+   * Áp lệnh từ poll HOẶC subscription vào cùng một state machine. Subscription
+   * trả cả lệnh CŨ (after:0) nên phải lọc theo con trỏ ở đây; poll đã lọc
+   * server-side (after=cursor) nên bước lọc này vô hại với nó.
+   */
+  private applyCommands(commands: SessionCommandRecord[]) {
+    for (const command of commands) {
+      if (command.issuedAt <= this.commandCursor) continue;
+      this.commandCursor = command.issuedAt;
+      // Cùng đường với lệnh data channel LiveKit — state machine tự nuốt lệnh
+      // thừa (start khi đã live, stop khi đã standby...).
+      this.handleRoomEvent({ type: "command", action: command.action });
+    }
+  }
+
+  private async pollSessionCommands() {
+    if (!this.commandPollingWanted()) return;
+    const channel = this.dependencies.commandChannel;
+    const grant = this.grant;
+    if (!channel || !grant) return;
+    const sessionId = grant.sessionId;
+    let result: SessionCommandPollResult | null = null;
+    try {
+      result = await channel.poll(grant.telemetry, this.commandCursor);
+      this.commandPollBackoffMs = 0;
+    } catch (error) {
+      const status = (error as { status?: unknown })?.status;
+      // Telemetry token hết hạn → vòng refresh cấp token mới, poll sau dùng nó.
+      if (status === 401) {
+        void this.refreshCredentials().catch(() => undefined);
+      }
+      // 409 ở kênh lệnh = grant này đã bị GRANT MỚI thay (đối tác cấp lại cho
+      // máy khác) hoặc phiên đã đóng ngoài cửa sổ flush. Máy này phải DỪNG tại
+      // chỗ, không redial tranh publisher với máy mới; provider của camera grant
+      // coi end 409 là đã xong nên dấu pending-end được dọn sạch.
+      if (status === 409 && this.grant?.sessionId === sessionId) {
+        void this.stop("user");
+        return;
+      }
+      this.commandPollBackoffMs = Math.min(
+        COMMAND_POLL_MAX_BACKOFF_MS,
+        Math.max(this.commandPollInterval(), this.commandPollBackoffMs * 2),
+      );
+    }
+    // Phiên đã đổi trong lúc chờ mạng → kết quả thuộc phiên cũ, bỏ.
+    if (this.disposed || this.grant?.sessionId !== sessionId) return;
+    if (result) {
+      this.applyCommands(result.commands);
+      // Đối chiếu trạng thái — lưới an toàn khi lệnh rơi vì quá TTL: server
+      // bảo "live" mà máy còn ngồi chờ thì tự phát; "ended" thì tự kết thúc.
+      // CHỈ đối chiếu khi vòng này không giao lệnh nào — có lệnh thì lệnh là
+      // nguồn hành động, đối chiếu thêm sẽ gọi startPublishing trùng lặp.
+      if (result.commands.length === 0) {
+        if (result.status === "ended" && activeStates.has(this.snapshot.state)) {
+          void this.stop("user");
+        } else if (
+          result.status === "live" &&
+          this.snapshot.state === "standby"
+        ) {
+          void this.startPublishing();
+        }
+      }
+    }
+    if (!this.commandPollingWanted() || this.commandPollTimer) return;
+    this.scheduleCommandPoll(
+      this.commandPollBackoffMs || this.commandPollInterval(),
+    );
+  }
+
   /** Heartbeat kèm chỉ số thiết bị (nếu collector được cung cấp). */
   private async sendHeartbeat() {
     let metrics: DeviceMetricsSample | null = null;
@@ -976,6 +1534,9 @@ export class LivestreamEngine {
           telemetry: refreshed.telemetry ?? this.grant.telemetry,
           config: refreshed.config,
         };
+        // Token có thể vừa đổi → resubscribe websocket lệnh bằng token mới
+        // (subscription giữ token cũ sẽ bị server từ chối là "expired").
+        this.syncCommandSubscription();
         this.update({ config: refreshed.config });
         this.refreshRetryAttempt = 0;
         if (this.liveTimersStarted) {
@@ -1003,6 +1564,7 @@ export class LivestreamEngine {
     // minutes LiveKit + pin (timer reset mỗi lần rời/vào lại standby).
     if (state === "standby") this.startStandbyTimer();
     else this.clearStandbyTimer();
+    this.syncCommandPolling();
     if (this.snapshot.sessionId) {
       void this.sendTelemetry("state_changed", { from: previous, to: state });
     }
@@ -1083,6 +1645,19 @@ export class LivestreamEngine {
           this.pendingReplayError = error;
         });
       }
+      // Mạng vừa về mà đang kẹt → quay số lại NGAY từ nhịp 0.
+      //
+      // Đây là đường hồi phục CHÍNH, không phải đường phụ: khi mất mạng thì
+      // scheduleRedial không đặt timer nào cả, nên sự kiện này là thứ duy nhất
+      // khởi động lại vòng quay số. Nhịp đầu bằng 0, và nếu cú đầu trượt vì định
+      // tuyến chưa sẵn (hệ điều hành báo "connected" trước khi dùng được thật)
+      // thì thang 1s/2s/4s bắt ngay sau đó.
+      if (online && this.room?.needsManualReconnect) {
+        const s = this.snapshot.state;
+        if (s === "reconnecting" || (s === "error" && this.snapshot.sessionId)) {
+          this.scheduleRedial(0);
+        }
+      }
     });
   }
 
@@ -1132,9 +1707,15 @@ export class LivestreamEngine {
     if (this.tokenRefreshTimer) clearTimeout(this.tokenRefreshTimer);
     this.tokenRefreshTimer = undefined;
     if (!this.grant || !this.snapshot.sessionId) return;
-    const delay =
-      delayOverride ??
-      Math.max(1_000, this.grant.tokenExpiresAt - this.now() - 60_000);
+    // Hạn gần nhất của hai token. Mode device-rtmp: tokenExpiresAt là HORIZON
+    // của phiên (stream key sống theo phiên, refresh trả lại cùng mốc) — sát
+    // hạn mà vẫn hẹn refresh là POST /refresh mỗi giây suốt phút cuối rồi 409
+    // (đo: ~60 call/phiên/máy). Còn ≤60s thì thôi: phiên sắp hết theo trần
+    // maxSessionDuration, không có token nào cứu được nữa.
+    const horizon = Math.min(this.grant.tokenExpiresAt, this.grant.telemetry.expiresAt);
+    const remaining = horizon - this.now();
+    if (delayOverride === undefined && remaining <= 60_000) return;
+    const delay = delayOverride ?? Math.max(1_000, remaining - 60_000);
     this.tokenRefreshTimer = setTimeout(() => {
       void this.refreshCredentials().catch(() => {
         if (this.disposed) return;