@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/device-agent/mqtt-codec.ts

@@ -0,0 +1,347 @@
+/**
+ * Codec MQTT 3.1.1 tối giản — đủ cho device plane, KHÔNG phụ thuộc thư viện.
+ *
+ * Vì sao tự viết thay vì lấy `mqtt`/`paho`:
+ * - App RN bắt buộc đi WebSocket (TCP thuần = native module = mất OTA). `mqtt`
+ *   npm cần polyfill buffer/process/stream/url — repo này đang 0 polyfill, thêm
+ *   vào là phình bundle và phải test lại trên Hermes. `paho-mqtt` thì lưu QoS
+ *   bằng `localStorage`, thứ không tồn tại trong RN.
+ * - Phần giao thức mà device plane dùng rất hẹp: CONNECT (kèm LWT), SUBSCRIBE,
+ *   PUBLISH QoS0/1, PINGREQ, DISCONNECT. Chừng đó gói vừa đúng một file đọc
+ *   được, và đổi lại ta kiểm soát hoàn toàn hành vi lúc mạng chập chờn.
+ *
+ * File này CHỈ mã hoá/giải mã — không đụng WebSocket, không timer, không state.
+ * Nhờ vậy test được bằng dữ liệu thuần (xem test/mqtt-codec.test.ts), còn vòng
+ * đời kết nối nằm ở mqtt-channel.ts.
+ *
+ * Tham chiếu: OASIS MQTT 3.1.1, mục 2 (khung gói) và 3 (từng loại gói).
+ */
+
+// ===== Loại gói (4 bit cao của byte đầu) =====
+export const PACKET = {
+  CONNECT: 1,
+  CONNACK: 2,
+  PUBLISH: 3,
+  PUBACK: 4,
+  SUBSCRIBE: 8,
+  SUBACK: 9,
+  PINGREQ: 12,
+  PINGRESP: 13,
+  DISCONNECT: 14,
+} as const;
+
+/** Mã trả về của CONNACK — 0 là chấp nhận, còn lại là từ chối có lý do. */
+export const CONNACK_REASON: Record<number, string> = {
+  0: "chấp nhận",
+  1: "sai phiên bản giao thức",
+  2: "clientId bị từ chối",
+  3: "broker không sẵn sàng",
+  4: "sai username/password",
+  5: "không được phép (auth hook từ chối)",
+};
+
+export interface MqttWill {
+  topic: string;
+  payload: string;
+  qos: 0 | 1;
+  retain: boolean;
+}
+
+export interface ConnectOptions {
+  clientId: string;
+  username?: string;
+  password?: string;
+  /** Giây. 0 = tắt keepalive (không dùng ở đây — LWT dựa vào nhịp này). */
+  keepaliveS: number;
+  will?: MqttWill;
+  /**
+   * `false` = broker giữ session (subscription sống qua lần rớt). Device plane
+   * dùng `true`: máy tự subscribe lại sau mỗi lần nối, và session cũ còn treo
+   * chỉ tổ giữ lệnh cũ QoS1 rồi dội lại lúc reconnect — thứ ta KHÔNG muốn.
+   */
+  cleanSession: boolean;
+}
+
+// ===== Ghi số/chuỗi =====
+
+/** UTF-8 tự viết: TextEncoder không chắc có trên mọi bản Hermes. */
+export function utf8Encode(s: string): Uint8Array {
+  const out: number[] = [];
+  for (let i = 0; i < s.length; i++) {
+    let code = s.charCodeAt(i);
+    // Ghép cặp surrogate (emoji, ký tự ngoài BMP) trước khi mã hoá.
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < s.length) {
+      const next = s.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        code = ((code - 0xd800) << 10) + (next - 0xdc00) + 0x10000;
+        i++;
+      }
+    }
+    if (code < 0x80) out.push(code);
+    else if (code < 0x800) out.push(0xc0 | (code >> 6), 0x80 | (code & 63));
+    else if (code < 0x10000)
+      out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 63), 0x80 | (code & 63));
+    else
+      out.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 63),
+        0x80 | ((code >> 6) & 63),
+        0x80 | (code & 63),
+      );
+  }
+  return Uint8Array.from(out);
+}
+
+export function utf8Decode(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; ) {
+    const b = bytes[i]!;
+    let code: number;
+    if (b < 0x80) {
+      code = b;
+      i += 1;
+    } else if (b < 0xe0) {
+      code = ((b & 31) << 6) | (bytes[i + 1]! & 63);
+      i += 2;
+    } else if (b < 0xf0) {
+      code = ((b & 15) << 12) | ((bytes[i + 1]! & 63) << 6) | (bytes[i + 2]! & 63);
+      i += 3;
+    } else {
+      code =
+        ((b & 7) << 18) |
+        ((bytes[i + 1]! & 63) << 12) |
+        ((bytes[i + 2]! & 63) << 6) |
+        (bytes[i + 3]! & 63);
+      i += 4;
+    }
+    if (code > 0xffff) {
+      code -= 0x10000;
+      out += String.fromCharCode(0xd800 + (code >> 10), 0xdc00 + (code & 1023));
+    } else {
+      out += String.fromCharCode(code);
+    }
+  }
+  return out;
+}
+
+/** Chuỗi trong MQTT luôn có 2 byte độ dài đứng trước (big-endian). */
+function encodeString(s: string): number[] {
+  const bytes = utf8Encode(s);
+  if (bytes.length > 0xffff) throw new Error("Chuỗi MQTT vượt 65535 byte");
+  return [bytes.length >> 8, bytes.length & 0xff, ...bytes];
+}
+
+/**
+ * "Remaining Length" là varint 7-bit, tối đa 4 byte (256MB). Đây là chỗ dễ sai
+ * nhất của MQTT: nhiều bản tự viết chỉ xử lý 1 byte rồi vỡ khi payload > 127.
+ */
+export function encodeRemainingLength(n: number): number[] {
+  if (n < 0 || n > 268_435_455) throw new Error(`Độ dài MQTT không hợp lệ: ${n}`);
+  const out: number[] = [];
+  let value = n;
+  do {
+    let byte = value % 128;
+    value = Math.floor(value / 128);
+    if (value > 0) byte |= 128;
+    out.push(byte);
+  } while (value > 0);
+  return out;
+}
+
+/** Trả `null` khi chưa đủ byte để đọc hết varint (gói còn dở trong buffer). */
+export function decodeRemainingLength(
+  bytes: Uint8Array,
+  offset: number,
+): { value: number; bytesUsed: number } | null {
+  let multiplier = 1;
+  let value = 0;
+  for (let i = 0; i < 4; i++) {
+    const idx = offset + i;
+    if (idx >= bytes.length) return null;
+    const byte = bytes[idx]!;
+    value += (byte & 127) * multiplier;
+    if ((byte & 128) === 0) return { value, bytesUsed: i + 1 };
+    multiplier *= 128;
+  }
+  throw new Error("Remaining Length hỏng (quá 4 byte)");
+}
+
+function frame(type: number, flags: number, body: number[]): Uint8Array {
+  return Uint8Array.from([
+    (type << 4) | flags,
+    ...encodeRemainingLength(body.length),
+    ...body,
+  ]);
+}
+
+// ===== Gói gửi đi =====
+
+export function encodeConnect(o: ConnectOptions): Uint8Array {
+  let flags = 0;
+  if (o.cleanSession) flags |= 0x02;
+  if (o.will) {
+    flags |= 0x04;
+    flags |= (o.will.qos & 0x03) << 3;
+    if (o.will.retain) flags |= 0x20;
+  }
+  if (o.password !== undefined) flags |= 0x40;
+  if (o.username !== undefined) flags |= 0x80;
+
+  const body = [
+    ...encodeString("MQTT"),
+    0x04, // protocol level 4 = MQTT 3.1.1
+    flags,
+    (o.keepaliveS >> 8) & 0xff,
+    o.keepaliveS & 0xff,
+    ...encodeString(o.clientId),
+  ];
+  // Thứ tự payload là BẮT BUỘC: will topic → will message → username →
+  // password. Đảo là broker đọc lệch và đá kết nối mà không nói vì sao.
+  if (o.will) {
+    body.push(...encodeString(o.will.topic));
+    const payload = utf8Encode(o.will.payload);
+    body.push(payload.length >> 8, payload.length & 0xff, ...payload);
+  }
+  if (o.username !== undefined) body.push(...encodeString(o.username));
+  if (o.password !== undefined) body.push(...encodeString(o.password));
+  return frame(PACKET.CONNECT, 0, body);
+}
+
+export function encodeSubscribe(
+  packetId: number,
+  filters: { topic: string; qos: 0 | 1 }[],
+): Uint8Array {
+  const body = [packetId >> 8, packetId & 0xff];
+  for (const f of filters) {
+    body.push(...encodeString(f.topic), f.qos);
+  }
+  // Bit 1 của flags PHẢI bằng 1 với SUBSCRIBE (mục 3.8.1) — thiếu là broker
+  // đóng kết nối ngay, không CONNACK, không lời giải thích.
+  return frame(PACKET.SUBSCRIBE, 0x02, body);
+}
+
+export function encodePublish(o: {
+  topic: string;
+  payload: string;
+  qos: 0 | 1;
+  retain: boolean;
+  packetId?: number;
+}): Uint8Array {
+  let flags = 0;
+  if (o.retain) flags |= 0x01;
+  flags |= (o.qos & 0x03) << 1;
+  const body = [...encodeString(o.topic)];
+  if (o.qos > 0) {
+    if (o.packetId === undefined) throw new Error("PUBLISH QoS1 thiếu packetId");
+    body.push(o.packetId >> 8, o.packetId & 0xff);
+  }
+  body.push(...utf8Encode(o.payload));
+  return frame(PACKET.PUBLISH, flags, body);
+}
+
+export function encodePuback(packetId: number): Uint8Array {
+  return frame(PACKET.PUBACK, 0, [packetId >> 8, packetId & 0xff]);
+}
+
+export function encodePingReq(): Uint8Array {
+  return frame(PACKET.PINGREQ, 0, []);
+}
+
+export function encodeDisconnect(): Uint8Array {
+  return frame(PACKET.DISCONNECT, 0, []);
+}
+
+// ===== Gói nhận về =====
+
+export type MqttPacket =
+  | { type: "connack"; sessionPresent: boolean; returnCode: number }
+  | { type: "suback"; packetId: number; codes: number[] }
+  | {
+      type: "publish";
+      topic: string;
+      payload: string;
+      qos: 0 | 1;
+      retain: boolean;
+      packetId?: number;
+    }
+  | { type: "puback"; packetId: number }
+  | { type: "pingresp" }
+  | { type: "other"; packetType: number };
+
+/**
+ * Tách các gói hoàn chỉnh ra khỏi buffer tích luỹ.
+ *
+ * WebSocket KHÔNG bảo toàn ranh giới gói MQTT: một frame có thể chứa 3 gói, và
+ * một gói có thể nằm vắt qua 2 frame. Vì thế caller phải giữ `rest` lại và nối
+ * frame sau vào — đây đúng là chỗ mà bản tự viết cẩu thả sẽ chạy ngon trên
+ * mạng LAN rồi vỡ ngoài sân.
+ */
+export function decodePackets(buffer: Uint8Array): {
+  packets: MqttPacket[];
+  rest: Uint8Array;
+} {
+  const packets: MqttPacket[] = [];
+  let offset = 0;
+  for (;;) {
+    if (offset >= buffer.length) break;
+    const header = buffer[offset]!;
+    const len = decodeRemainingLength(buffer, offset + 1);
+    if (!len) break; // varint còn dở → chờ frame sau
+    const start = offset + 1 + len.bytesUsed;
+    const end = start + len.value;
+    if (end > buffer.length) break; // thân gói còn dở
+    const type = header >> 4;
+    const flags = header & 0x0f;
+    const body = buffer.subarray(start, end);
+    packets.push(decodeBody(type, flags, body));
+    offset = end;
+  }
+  return { packets, rest: buffer.subarray(offset) };
+}
+
+function readString(body: Uint8Array, offset: number): { value: string; next: number } {
+  const len = (body[offset]! << 8) | body[offset + 1]!;
+  const start = offset + 2;
+  return { value: utf8Decode(body.subarray(start, start + len)), next: start + len };
+}
+
+function decodeBody(type: number, flags: number, body: Uint8Array): MqttPacket {
+  switch (type) {
+    case PACKET.CONNACK:
+      return {
+        type: "connack",
+        sessionPresent: (body[0]! & 0x01) === 1,
+        returnCode: body[1] ?? 0,
+      };
+    case PACKET.SUBACK:
+      return {
+        type: "suback",
+        packetId: (body[0]! << 8) | body[1]!,
+        codes: Array.from(body.subarray(2)),
+      };
+    case PACKET.PUBLISH: {
+      const qos = ((flags >> 1) & 0x03) as 0 | 1;
+      const topic = readString(body, 0);
+      let next = topic.next;
+      let packetId: number | undefined;
+      if (qos > 0) {
+        packetId = (body[next]! << 8) | body[next + 1]!;
+        next += 2;
+      }
+      return {
+        type: "publish",
+        topic: topic.value,
+        payload: utf8Decode(body.subarray(next)),
+        qos,
+        retain: (flags & 0x01) === 1,
+        ...(packetId !== undefined ? { packetId } : {}),
+      };
+    }
+    case PACKET.PUBACK:
+      return { type: "puback", packetId: (body[0]! << 8) | body[1]! };
+    case PACKET.PINGRESP:
+      return { type: "pingresp" };
+    default:
+      return { type: "other", packetType: type };
+  }
+}

package/src/device-agent/tournament.ts

@@ -0,0 +1,352 @@
+/**
+ * TournamentController — "chế độ giải đấu" cho điện thoại camera đặt tại sân.
+ *
+ * Vận hành arm máy MỘT lần khi setup giải: controller giữ đúng một phiên
+ * standby gắn sân (metadata.courtRef) đậu trong phòng LiveKit cả ngày ($0
+ * egress). Backend đậu phiên vào bảng courts (bindStandbySession) để REST
+ * match-start của đối tác tiêu thụ: trọng tài bấm start → server claim phiên +
+ * flip live + lệnh "start" qua data channel — không ai chạm điện thoại.
+ *
+ * Khi phiên kết thúc VÌ BẤT KỲ LÝ DO GÌ (match-end, standby_timeout 15 phút,
+ * watchdog, rớt mạng, app khởi động lại) controller tự re-arm phiên standby
+ * mới cho cùng sân sau vài giây — một state machine duy nhất xử lý trận nối
+ * trận, reboot và hồi phục lỗi.
+ */
+
+import type { LivestreamEngine } from "../engine";
+
+/** Góc nhìn tối thiểu lên engine — test truyền fake object thường. */
+export interface TournamentEngineView {
+  getSnapshot(): { state: string; sessionId: string | null };
+  subscribe(listener: () => void): () => void;
+  prepare(): Promise<void>;
+  start(
+    input: {
+      externalSessionId: string;
+      title: string;
+      visibility?: "public" | "private";
+      consentVersion: string;
+      metadata?: Record<string, string>;
+    },
+    options?: { autoPublish?: boolean },
+  ): Promise<void>;
+  stop(reason: "user" | "error"): Promise<void>;
+}
+
+export interface TournamentPersistedState {
+  courtRef: string;
+}
+
+/** Persist trạng thái armed (AsyncStorage/SQLite tuỳ app) — reboot tự re-arm. */
+export interface TournamentStorage {
+  load(): Promise<TournamentPersistedState | null>;
+  save(state: TournamentPersistedState | null): Promise<void>;
+}
+
+export type TournamentPhase =
+  | "disarmed"
+  | "arming"
+  | "standby"
+  | "live"
+  | "retry_wait";
+
+export interface TournamentState {
+  armed: boolean;
+  courtRef: string | null;
+  phase: TournamentPhase;
+  lastError: string | null;
+}
+
+export interface TournamentStandbyStart {
+  consentVersion: string;
+  /** Tiêu đề phiên chờ theo sân — mặc định "{courtRef} — chờ trận". */
+  titleFor?: (courtRef: string) => string;
+  visibility?: "public" | "private";
+  metadata?: Record<string, string>;
+}
+
+export interface TournamentControllerOptions {
+  engine: TournamentEngineView | LivestreamEngine;
+  standbyStart: TournamentStandbyStart;
+  storage?: TournamentStorage;
+  onStateChange?: (state: TournamentState) => void;
+  /** Backoff re-arm khi lỗi liên tiếp (test truyền giá trị nhỏ). */
+  rearmBaseDelayMs?: number;
+  rearmMaxDelayMs?: number;
+  /**
+   * Thời gian NHƯỜNG cho engine tự cứu phiên khi nó ở "error" mà còn sessionId.
+   * Phải dài hơn reconnectTimeoutMs của engine (mặc định 30s) để engine kịp
+   * hoặc hồi, hoặc tự cắt bằng network_timeout, trước khi controller can thiệp.
+   */
+  recoveryGraceMs?: number;
+  now?: () => number;
+}
+
+const ACTIVE_ENGINE_STATES = new Set([
+  "preparing",
+  "connecting",
+  "standby",
+  "live",
+  "reconnecting",
+  "ending",
+]);
+
+/** Nhịp soi lại trong lúc nhường engine tự cứu — cố định, không backoff. */
+const RECOVERY_CHECK_MS = 5_000;
+/**
+ * Hạn chót mặc định phải LỚN HƠN cửa sổ reconnect của engine, nếu không
+ * controller dọn phiên trước khi engine kịp dùng hết lượt cứu. Engine để sàn 75s
+ * cho RTMP (chờ MediaMTX nhả publisher chết sau readTimeout 30s) → 90s.
+ */
+const DEFAULT_RECOVERY_GRACE_MS = 90_000;
+
+export class TournamentController {
+  private readonly engine: TournamentEngineView;
+  private armed = false;
+  private courtRef: string | null = null;
+  private lastError: string | null = null;
+  private attemptInFlight = false;
+  private retryAttempt = 0;
+  private retryTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Mốc hết nhường cho engine tự cứu phiên; null = đang không trong pha đó. */
+  private recoveryDeadline: number | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private disposed = false;
+  /** Tăng mỗi lần arm/disarm — huỷ attempt cũ đang chạy dở. */
+  private armGeneration = 0;
+
+  constructor(private readonly options: TournamentControllerOptions) {
+    this.engine = options.engine as TournamentEngineView;
+  }
+
+  getState(): TournamentState {
+    const engineState = this.engine.getSnapshot().state;
+    let phase: TournamentPhase;
+    if (!this.armed) phase = "disarmed";
+    else if (engineState === "live") phase = "live";
+    else if (engineState === "standby") phase = "standby";
+    else if (this.retryTimer) phase = "retry_wait";
+    else phase = "arming";
+    return {
+      armed: this.armed,
+      courtRef: this.courtRef,
+      phase,
+      lastError: this.lastError,
+    };
+  }
+
+  /** Khôi phục sau khi app mở lại (reboot giữa giải) — gọi sau engine.initialize(). */
+  async restore() {
+    if (this.disposed || this.armed) return;
+    let saved: TournamentPersistedState | null = null;
+    try {
+      saved = (await this.options.storage?.load()) ?? null;
+    } catch {
+      return;
+    }
+    if (saved?.courtRef) await this.arm(saved.courtRef);
+  }
+
+  async arm(courtRef: string) {
+    if (this.disposed) return;
+    const normalized = courtRef.trim();
+    if (!normalized) throw new Error("courtRef không được để trống");
+    this.armed = true;
+    this.courtRef = normalized;
+    this.lastError = null;
+    this.retryAttempt = 0;
+    this.armGeneration += 1;
+    this.recoveryDeadline = null;
+    this.clearRetry();
+    try {
+      await this.options.storage?.save({ courtRef: normalized });
+    } catch {
+      // Không persist được thì reboot mất armed — vẫn arm cho phiên hiện tại
+    }
+    if (!this.unsubscribe) {
+      this.unsubscribe = this.engine.subscribe(() => this.handleEngineChange());
+    }
+    this.emit();
+    await this.ensureStandby();
+  }
+
+  /**
+   * Tắt chế độ giải đấu. Phiên standby đang chờ được nhả (stop); phiên đang
+   * LIVE là trận do đối tác điều khiển — không cắt, chỉ ngừng re-arm.
+   */
+  async disarm() {
+    this.armed = false;
+    this.courtRef = null;
+    this.armGeneration += 1;
+    this.recoveryDeadline = null;
+    this.clearRetry();
+    try {
+      await this.options.storage?.save(null);
+    } catch {
+      // best effort
+    }
+    const snapshot = this.engine.getSnapshot();
+    if (snapshot.sessionId && snapshot.state === "standby") {
+      try {
+        await this.engine.stop("user");
+      } catch {
+        // Phiên chờ kẹt — server watchdog dọn
+      }
+    }
+    this.emit();
+  }
+
+  dispose() {
+    this.disposed = true;
+    this.armed = false;
+    this.clearRetry();
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+  }
+
+  private emit() {
+    this.options.onStateChange?.(this.getState());
+  }
+
+  private clearRetry() {
+    if (this.retryTimer) clearTimeout(this.retryTimer);
+    this.retryTimer = null;
+  }
+
+  /** Engine còn đang tự cứu CHÍNH phiên này → nhường, đừng cắt để arm phiên mới. */
+  private isEngineRecovering(state: string, sessionId: string | null): boolean {
+    if (state !== "error" || !sessionId) return false;
+    const now = (this.options.now ?? Date.now)();
+    if (this.recoveryDeadline === null) {
+      this.recoveryDeadline =
+        now + (this.options.recoveryGraceMs ?? DEFAULT_RECOVERY_GRACE_MS);
+    }
+    return now < this.recoveryDeadline;
+  }
+
+  private scheduleRecoveryCheck() {
+    if (this.retryTimer || this.attemptInFlight || !this.armed) {
+      this.emit();
+      return;
+    }
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      void this.ensureStandby();
+    }, RECOVERY_CHECK_MS);
+    this.emit();
+  }
+
+  private handleEngineChange() {
+    if (!this.armed || this.disposed) return;
+    const snapshot = this.engine.getSnapshot();
+    const state = snapshot.state;
+    // "error" mà VẪN CÒN sessionId = vòng redial + reconnect timer của engine
+    // đang cứu đúng phiên đó. Cắt nó ở đây là giết phiên còn cứu được: mất mạng
+    // 1–2 giây, engine chớp qua error, controller gọi stop("error") sau 2 giây
+    // rồi arm phiên mới → phiên chết với endReason "error" dù cửa sổ reconnect
+    // 30 giây chưa hề dùng tới. Đo trên prod 18/08/2026, cả iOS lẫn Android.
+    // Nhường tới hạn chót; quá hạn thì rơi xuống nhánh dưới dọn như cũ.
+    if (this.isEngineRecovering(state, snapshot.sessionId)) {
+      this.scheduleRecoveryCheck();
+      return;
+    }
+    if (state === "standby" || state === "live") this.recoveryDeadline = null;
+    if (state === "ended" || state === "idle" || state === "error") {
+      // Phiên vừa chết (match-end / timeout / watchdog / mất mạng) → đậu phiên mới
+      this.scheduleRearm();
+      return;
+    }
+    // "preview" không session mà vẫn armed = phải đang arm dở. Không có nhánh
+    // này thì race với AutoPrepare gây kẹt vĩnh viễn: phiên chết → timer re-arm
+    // 2s nổ đúng lúc app prepare() lại camera (state "preparing" → ensureStandby
+    // bail), prepare xong về "preview" thì không ai re-arm nữa.
+    if (state === "preview" && !snapshot.sessionId && !this.attemptInFlight) {
+      this.scheduleRearm();
+      return;
+    }
+    if (state === "standby" || state === "live") {
+      this.retryAttempt = 0;
+      this.lastError = null;
+    }
+    this.emit();
+  }
+
+  private scheduleRearm() {
+    if (this.retryTimer || this.attemptInFlight || !this.armed) {
+      this.emit();
+      return;
+    }
+    const base = this.options.rearmBaseDelayMs ?? 2_000;
+    const max = this.options.rearmMaxDelayMs ?? 60_000;
+    const delay = Math.min(base * 2 ** this.retryAttempt, max);
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      void this.ensureStandby();
+    }, delay);
+    this.emit();
+  }
+
+  private async ensureStandby() {
+    if (!this.armed || this.disposed || this.attemptInFlight) return;
+    const courtRef = this.courtRef;
+    if (!courtRef) return;
+    const generation = this.armGeneration;
+    const engineState = this.engine.getSnapshot().state;
+    // standby/live = phiên đang khoẻ, không làm gì. Các state chuyển tiếp
+    // (preparing/connecting/ending/reconnecting) thì HẸN LẠI thay vì bỏ cuộc —
+    // return im lặng ở đây là nguồn deadlock "arming" không lối thoát.
+    if (engineState === "standby" || engineState === "live") {
+      this.recoveryDeadline = null;
+      return;
+    }
+    if (ACTIVE_ENGINE_STATES.has(engineState)) {
+      this.scheduleRearm();
+      return;
+    }
+    // Timer re-arm nổ trong lúc engine còn đang cứu phiên → soi lại, KHÔNG cắt.
+    if (this.isEngineRecovering(engineState, this.engine.getSnapshot().sessionId)) {
+      this.scheduleRecoveryCheck();
+      return;
+    }
+    this.attemptInFlight = true;
+    this.emit();
+    let failed = false;
+    try {
+      if (this.engine.getSnapshot().state === "error") {
+        try {
+          await this.engine.stop("error");
+        } catch {
+          // stop từ error thất bại — prepare bên dưới sẽ báo lỗi cụ thể
+        }
+      }
+      if (this.engine.getSnapshot().state !== "preview") {
+        await this.engine.prepare();
+      }
+      if (!this.armed || this.armGeneration !== generation) return;
+      const start = this.options.standbyStart;
+      const now = this.options.now ?? Date.now;
+      await this.engine.start(
+        {
+          externalSessionId: `tournament-${courtRef}-${now()}`,
+          title: start.titleFor?.(courtRef) ?? `${courtRef} — chờ trận`,
+          visibility: start.visibility ?? "public",
+          consentVersion: start.consentVersion,
+          metadata: { ...start.metadata, courtRef },
+        },
+        { autoPublish: false },
+      );
+      this.retryAttempt = 0;
+      this.lastError = null;
+    } catch (error) {
+      this.lastError = error instanceof Error ? error.message : String(error);
+      this.retryAttempt += 1;
+      failed = true;
+    } finally {
+      this.attemptInFlight = false;
+    }
+    if (failed && this.armed && this.armGeneration === generation) {
+      this.scheduleRearm();
+    }
+    this.emit();
+  }
+}