replicas-computer 0.3.14 → 0.3.16

package/dist/index.js

@@ -2937,7 +2937,7 @@ async function computerStatusCommand() {
 }
 
 // src/version.ts
-var COMPUTER_USE_VERSION = "0.3.14";
+var COMPUTER_USE_VERSION = "0.3.16";
 var COMPUTER_USE_PROTOCOL_VERSION = 1;
 
 // src/program.ts
@@ -3179,69 +3179,11 @@ async function runComputerClient(argv) {
 // src/media-server.ts
 import { spawn as spawn5 } from "child_process";
 import { createHash as createHash3 } from "crypto";
-import { createReadStream, existsSync as existsSync7, readdirSync, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
+import { createReadStream, existsSync as existsSync7, readdirSync, readFileSync as readFileSync7, statSync as statSync2 } from "fs";
 import { createServer as createServer2 } from "http";
 import { availableParallelism as availableParallelism2, loadavg } from "os";
 import { dirname as dirname7, extname, resolve as resolve3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-
-// ../shared/src/runtime-env.ts
-function parsePosixEnvFile(content) {
-  const result = {};
-  let pos = 0;
-  while (pos < content.length) {
-    let lineStart;
-    if (pos === 0 || content[pos - 1] === "\n") {
-      lineStart = pos;
-    } else {
-      const nl2 = content.indexOf("\n", pos);
-      if (nl2 === -1) break;
-      lineStart = nl2 + 1;
-    }
-    if (!content.startsWith("export ", lineStart)) {
-      const nl2 = content.indexOf("\n", lineStart);
-      if (nl2 === -1) break;
-      pos = nl2 + 1;
-      continue;
-    }
-    const nameStart = lineStart + "export ".length;
-    const eqIdx = content.indexOf("=", nameStart);
-    if (eqIdx === -1) break;
-    const name = content.slice(nameStart, eqIdx).trim();
-    let cursor = eqIdx + 1;
-    if (content[cursor] !== "'") {
-      const nl2 = content.indexOf("\n", cursor);
-      pos = nl2 === -1 ? content.length : nl2 + 1;
-      continue;
-    }
-    cursor += 1;
-    let value = "";
-    let closed = false;
-    while (cursor < content.length) {
-      const ch = content[cursor];
-      if (ch === "'") {
-        if (content.startsWith("\\''", cursor + 1)) {
-          value += "'";
-          cursor += 4;
-          continue;
-        }
-        cursor += 1;
-        closed = true;
-        break;
-      }
-      value += ch;
-      cursor += 1;
-    }
-    if (closed && name) {
-      result[name] = value;
-    }
-    const nl = content.indexOf("\n", cursor);
-    pos = nl === -1 ? content.length : nl + 1;
-  }
-  return result;
-}
-
-// src/media-server.ts
 import WebSocket2, { WebSocketServer } from "ws";
 
 // src/encoder.ts
@@ -3251,13 +3193,17 @@ import { createInterface } from "readline";
 
 // src/rtp.ts
 var RTP_HEADER_BYTES = 12;
+var NAL_SLICE = 1;
 var NAL_IDR = 5;
+var NAL_SEI = 6;
 var NAL_SPS = 7;
+var SEI_RECOVERY_POINT = 6;
 var NAL_STAP_A = 24;
 var NAL_FU_A = 28;
 var nalType = (byte) => byte & 31;
 var headerBytesOf = (packet) => RTP_HEADER_BYTES + (packet[0] & 15) * 4;
 var joinable = (nal) => nal === NAL_IDR || nal === NAL_SPS;
+var refreshFrame = (nal) => nalType(nal[0]) === NAL_SLICE || nalType(nal[0]) === NAL_SEI && nal[1] === SEI_RECOVERY_POINT;
 var isRtp = (data) => data.length >= RTP_HEADER_BYTES && data[0] >> 6 === 2 && (data[1] < 192 || data[1] > 223);
 var rtpPayload = (packet) => packet.subarray(headerBytesOf(packet));
 function aggregatedNals(payload) {
@@ -3286,7 +3232,10 @@ function isKeyframeStart(payload) {
     const fragment = fragmentHeader(payload);
     return fragment.start && joinable(fragment.type);
   }
-  if (type === NAL_STAP_A) return aggregatedNals(payload).nals.some((nal) => joinable(nalType(nal[0])));
+  if (type === NAL_STAP_A) {
+    const { nals } = aggregatedNals(payload);
+    return nals.some((nal) => joinable(nalType(nal[0]))) && !nals.some(refreshFrame);
+  }
   return joinable(type);
 }
 var RtpSplicer = class {
@@ -3363,6 +3312,8 @@ var RtpClock = class {
 };
 var startCode = new Uint8Array([0, 0, 0, 1]);
 var H264RtpAssembler = class {
+  /** Frames abandoned for a missing or out-of-order packet; every delta after one is undecodable until a keyframe. */
+  discarded = 0;
   clock = new RtpClock(9e4);
   chunks = [];
   key = false;
@@ -3380,6 +3331,7 @@ var H264RtpAssembler = class {
   }
   push(packet) {
     if (this.timestamp !== void 0 && packet.timestamp !== this.timestamp) {
+      if (this.chunks.length > 0 || this.damaged) this.discarded += 1;
       this.clearFrame();
     }
     this.timestamp ??= packet.timestamp;
@@ -3412,6 +3364,7 @@ var H264RtpAssembler = class {
     } else this.damaged = true;
     if (!packet.marker) return null;
     if (this.damaged || this.fragmentType !== void 0 || this.chunks.length === 0) {
+      this.discarded += 1;
       this.clearFrame();
       return null;
     }
@@ -3469,7 +3422,9 @@ function superviseEncoder(options) {
     const warmupFrames = active ? options.warmupFrames ?? 0 : 0;
     const command = options.command?.() ?? "ffmpeg";
     const args = options.args(socket.address().port, warmupFrames);
-    const child = spawn3(command, args, { env: options.env, stdio: ["ignore", options.onOutput ? "pipe" : "ignore", "pipe"] });
+    const child = spawn3(command, args, { env: options.env, stdio: [options.controllable?.(command) ? "pipe" : "ignore", options.onOutput ? "pipe" : "ignore", "pipe"] });
+    child.stdin?.on("error", () => {
+    });
     child.stderr?.on("data", (chunk) => process.stderr.write(`[desktop-stream] ${chunk}`));
     const generation = { id: ++nextId, child, socket, live: true, startedAt: Date.now(), warmupFrames };
     candidate = generation;
@@ -3539,10 +3494,18 @@ function superviseEncoder(options) {
     candidate = void 0;
     active = void 0;
   });
+  const control = (line) => {
+    for (const generation of [candidate, active]) {
+      if (generation?.live && generation.child.stdin?.writable) generation.child.stdin.write(`${line}
+`);
+    }
+    return Boolean(active?.live && active.child.stdin?.writable);
+  };
   return {
     start,
     replace,
     stop,
+    control,
     running: () => Boolean(active && alive(active.child)),
     replacing: () => Boolean(candidate),
     generation: () => active?.id ?? 0,
@@ -3552,13 +3515,17 @@ function superviseEncoder(options) {
   };
 }
 
-// src/video-encoder.ts
-import { existsSync as existsSync6 } from "fs";
-import { availableParallelism } from "os";
-import { dirname as dirname6, resolve as resolve2 } from "path";
-import { fileURLToPath } from "url";
+// src/ice-servers.ts
+import { readFileSync as readFileSync6 } from "fs";
 
 // ../shared/src/desktop-stream.ts
+function isStreamIceServer(value) {
+  return isRecord(value) && typeof value.urls === "string" && (value.username === void 0 || typeof value.username === "string") && (value.credential === void 0 || typeof value.credential === "string");
+}
+var DESKTOP_ICE_SERVERS_PATH = "/v1/engine/desktop/ice-servers";
+function isDesktopIceServers(value) {
+  return isRecord(value) && typeof value.expiresAt === "number" && Array.isArray(value.iceServers) && value.iceServers.every(isStreamIceServer);
+}
 var DEFAULT_STREAM_REQUEST = {
   transport: "webrtc",
   profile: "balanced",
@@ -3615,6 +3582,144 @@ function isDesktopWebRtcFailure(value) {
   ].every((key) => typeof value[key] === "string" && value[key].length <= 200) && ["elapsedMs", "candidateErrors", "framesDecoded", "packetsReceived", "packetsLost", "bytesReceived", "lastFrameAgeMs", "encoderFps"].every((key) => typeof value[key] === "number" && Number.isFinite(value[key]));
 }
 
+// ../shared/src/runtime-env.ts
+var REPLICAS_RUNTIME_ENV_ALIASES = {
+  monolithUrl: ["REPLICAS_MONOLITH_URL", "MONOLITH_URL"],
+  workspaceId: ["REPLICAS_WORKSPACE_ID", "WORKSPACE_ID"],
+  linearSessionId: ["REPLICAS_LINEAR_SESSION_ID", "LINEAR_SESSION_ID"],
+  linearAccessToken: ["REPLICAS_LINEAR_ACCESS_TOKEN", "LINEAR_ACCESS_TOKEN"],
+  slackBotToken: ["REPLICAS_SLACK_BOT_TOKEN", "SLACK_BOT_TOKEN"],
+  slackChannelId: ["REPLICAS_SLACK_CHANNEL_ID", "SLACK_CHANNEL_ID"],
+  slackThreadTs: ["REPLICAS_SLACK_THREAD_TS", "SLACK_THREAD_TS"]
+};
+function readReplicasRuntimeEnv(readEnv, [namespacedKey, legacyKey]) {
+  return readEnv(namespacedKey) ?? readEnv(legacyKey);
+}
+function parsePosixEnvFile(content) {
+  const result = {};
+  let pos = 0;
+  while (pos < content.length) {
+    let lineStart;
+    if (pos === 0 || content[pos - 1] === "\n") {
+      lineStart = pos;
+    } else {
+      const nl2 = content.indexOf("\n", pos);
+      if (nl2 === -1) break;
+      lineStart = nl2 + 1;
+    }
+    if (!content.startsWith("export ", lineStart)) {
+      const nl2 = content.indexOf("\n", lineStart);
+      if (nl2 === -1) break;
+      pos = nl2 + 1;
+      continue;
+    }
+    const nameStart = lineStart + "export ".length;
+    const eqIdx = content.indexOf("=", nameStart);
+    if (eqIdx === -1) break;
+    const name = content.slice(nameStart, eqIdx).trim();
+    let cursor = eqIdx + 1;
+    if (content[cursor] !== "'") {
+      const nl2 = content.indexOf("\n", cursor);
+      pos = nl2 === -1 ? content.length : nl2 + 1;
+      continue;
+    }
+    cursor += 1;
+    let value = "";
+    let closed = false;
+    while (cursor < content.length) {
+      const ch = content[cursor];
+      if (ch === "'") {
+        if (content.startsWith("\\''", cursor + 1)) {
+          value += "'";
+          cursor += 4;
+          continue;
+        }
+        cursor += 1;
+        closed = true;
+        break;
+      }
+      value += ch;
+      cursor += 1;
+    }
+    if (closed && name) {
+      result[name] = value;
+    }
+    const nl = content.indexOf("\n", cursor);
+    pos = nl === -1 ? content.length : nl + 1;
+  }
+  return result;
+}
+
+// src/ice-servers.ts
+var runtimeEnvFile = process.env.REPLICAS_RUNTIME_ENV_FILE || "/home/user/.replicas/runtime-env.sh";
+var refreshMs = 60 * 6e4;
+var retryMs = 6e4;
+var relays = [];
+var expiresAt = 0;
+var refreshAt = 0;
+var refreshing;
+async function currentIceServers() {
+  let env = process.env;
+  try {
+    env = { ...env, ...parsePosixEnvFile(readFileSync6(runtimeEnvFile, "utf8")) };
+  } catch {
+  }
+  const monolithUrl = readReplicasRuntimeEnv((name) => env[name], REPLICAS_RUNTIME_ENV_ALIASES.monolithUrl);
+  const workspaceId = readReplicasRuntimeEnv((name) => env[name], REPLICAS_RUNTIME_ENV_ALIASES.workspaceId);
+  const engineSecret = env.REPLICAS_ENGINE_SECRET;
+  if (monolithUrl && workspaceId && engineSecret && Date.now() >= refreshAt) {
+    const refreshed = refreshing ??= refreshRelays(monolithUrl, workspaceId, engineSecret).finally(() => {
+      refreshing = void 0;
+    });
+    if (expiresAt <= Date.now()) await refreshed;
+  }
+  return toIceServers(env.REPLICAS_DESKTOP_STREAM_ICE_SERVERS, expiresAt > Date.now() ? relays : []);
+}
+async function refreshRelays(monolithUrl, workspaceId, engineSecret) {
+  try {
+    const response = await fetch(new URL(DESKTOP_ICE_SERVERS_PATH, monolithUrl), {
+      headers: { authorization: `Bearer ${engineSecret}`, "x-workspace-id": workspaceId },
+      redirect: "error",
+      signal: AbortSignal.timeout(2e3)
+    });
+    if (response.status === 404) {
+      relays = [];
+      expiresAt = 0;
+    } else {
+      const body = response.ok ? await response.json() : void 0;
+      if (!isDesktopIceServers(body)) throw new Error(`HTTP ${response.status}`);
+      ({ iceServers: relays, expiresAt } = body);
+    }
+    refreshAt = Date.now() + refreshMs;
+  } catch (error) {
+    process.stderr.write(`[desktop-stream] TURN credentials unavailable: ${error instanceof Error ? error.message : String(error)}
+`);
+    refreshAt = Date.now() + retryMs;
+  }
+}
+function toIceServers(spec = "stun:stun.l.google.com:19302", relayServers) {
+  const browser = spec.split(",").map((url) => url.trim()).filter(Boolean).map((url) => {
+    const match = url.match(/^(turns?):([^:@]+):(.+)@([^@]+)$/);
+    if (!match) return { urls: url };
+    const [username, credential] = match.slice(2, 4).map((value) => {
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    });
+    return { urls: `${match[1]}:${match[4]}`, username, credential };
+  }).concat(relayServers);
+  const native = browser.filter(({ urls }) => !/^turns:|[?&]transport=tcp/i.test(urls)).map(({ urls, username, credential }) => username === void 0 || credential === void 0 ? urls : urls.replace(/^turn:/i, `turn:${encodeURIComponent(username)}:${encodeURIComponent(credential)}@`));
+  return { native, browser };
+}
+
+// src/video-encoder.ts
+import { existsSync as existsSync6 } from "fs";
+import { availableParallelism } from "os";
+import { dirname as dirname6, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+
 // src/input-validation.ts
 var finite = (value) => typeof value === "number" && Number.isFinite(value);
 var optionalFinite = (value) => value === void 0 || finite(value);
@@ -3625,6 +3730,8 @@ function validInput(value) {
   switch (value.type) {
     case "release":
     case "keyframe":
+    case "retry-webrtc":
+    case "webrtc-ready":
       return true;
     case "theme":
       return value.theme === "light" || value.theme === "dark";
@@ -3928,22 +4035,6 @@ async function loadWebRtc() {
   }
 }
 var cleanupWebRtc = () => ndc?.cleanup();
-function parseIceServers(spec) {
-  const native = (spec ?? "stun:stun.l.google.com:19302").split(",").map((server) => server.trim()).filter(Boolean);
-  const browser = native.map((url) => {
-    const match = url.match(/^(turns?):([^:@]+):(.+)@([^@]+)$/);
-    if (!match) return { urls: url };
-    const [username, credential] = match.slice(2, 4).map((value) => {
-      try {
-        return decodeURIComponent(value);
-      } catch {
-        return value;
-      }
-    });
-    return { urls: `${match[1]}:${match[4]}`, username, credential };
-  });
-  return { native, browser };
-}
 var WebRtcViewer = class {
   constructor(options, handlers) {
     this.handlers = handlers;
@@ -4078,6 +4169,7 @@ function superviseVideoEncoder(options) {
   const encoder = superviseEncoder({
     label: "video",
     command: () => nativeCapture ? captureBinary : "ffmpeg",
+    controllable: (command) => command === captureBinary,
     onFailure: (command) => {
       if (command !== captureBinary) return;
       nativeCapture = false;
@@ -4234,6 +4326,8 @@ function superviseVideoEncoder(options) {
   });
   return {
     ...encoder,
+    /** Native capture takes keyframe, quality and frame-rate changes over stdin; ffmpeg needs a replacement for each. */
+    controllable: () => nativeCapture,
     capture: () => ({
       captureBackend: (encoder.command() ?? (nativeCapture ? captureBinary : "ffmpeg")) === captureBinary ? "native" : "ffmpeg",
       captureMetrics: captureMetrics?.generation === encoder.generation() && Date.now() - captureMetrics.at <= 2500 ? captureMetrics : void 0
@@ -4452,7 +4546,6 @@ var standbyRung = 5;
 var port = Number.parseInt(process.env.REPLICAS_DESKTOP_STREAM_PORT || String(DESKTOP_STREAM_PORT), 10);
 var display = process.env.REPLICAS_DESKTOP_DISPLAY?.replace(/^([^:])/, ":$1") || ":99";
 var webrtcEnabled = process.env.REPLICAS_DESKTOP_STREAM_WEBRTC !== "0";
-var runtimeEnvFile = process.env.REPLICAS_RUNTIME_ENV_FILE || "/home/user/.replicas/runtime-env.sh";
 var colorMode = process.env.REPLICAS_DESKTOP_STREAM_COLOR === "legacy" ? "legacy" : "bt709";
 var defaultRequest = parseStreamRequest(new URLSearchParams({
   transport: process.env.REPLICAS_DESKTOP_STREAM_TRANSPORT ?? "",
@@ -4479,6 +4572,7 @@ var qualityLadder = (profile) => rungCaps.map((kbps, index) => ({ kbps, crf: pro
 var fullChromaMinKbps = 8e3;
 var fallbackKeyframeMs = 250;
 var webrtcStartupRung = 2;
+var descentMemoryMs = 18e4;
 var targetBacklogMs = 120;
 var congestedBacklogMs = 250;
 var congestedDecodeQueue = 3;
@@ -4507,14 +4601,6 @@ function mediaPacket(kind, timestamp, payload) {
   header.writeBigUInt64BE(BigInt(Math.max(0, timestamp)), 4);
   return Buffer.concat([header, payload]);
 }
-function currentIceServers() {
-  let spec = process.env.REPLICAS_DESKTOP_STREAM_ICE_SERVERS;
-  try {
-    spec = parsePosixEnvFile(readFileSync6(runtimeEnvFile, "utf8")).REPLICAS_DESKTOP_STREAM_ICE_SERVERS ?? spec;
-  } catch {
-  }
-  return parseIceServers(spec);
-}
 var appliedTheme;
 var pendingTheme;
 var applyingTheme = false;
@@ -4540,7 +4626,7 @@ function drainDesktopTheme() {
 function processCpuMs(pid) {
   if (!pid) return 0;
   try {
-    const stat = readFileSync6(`/proc/${pid}/stat`, "utf8");
+    const stat = readFileSync7(`/proc/${pid}/stat`, "utf8");
     const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
     return (Number(fields[11]) + Number(fields[12])) * 10;
   } catch {
@@ -4558,7 +4644,8 @@ async function runMediaServer() {
   let activeProfile = "balanced";
   let adaptive = true;
   let rung = 0;
-  let descents = 0;
+  let descents = [];
+  let failedRung = -1;
   let congestedSeconds = 0;
   let comfortableSeconds = 0;
   let cleanTransportSeconds = 0;
@@ -4577,6 +4664,8 @@ async function runMediaServer() {
   let encoderFps = 0;
   let videoWanted = false;
   let encoderSignature = "";
+  let encoderDescription = "";
+  let encoderLive = { crf: 0, kbps: 0, fps: 0 };
   let encoderStop;
   let joinKeyframe;
   let lastVideoAt = 0;
@@ -4611,10 +4700,13 @@ async function runMediaServer() {
     const quality = ladder()[allStandby() ? Math.max(rung, standbyRung) : rung];
     const encodeFps = streamFps();
     const sockets = socketViewers().length > 0;
-    const keyframeMs = sockets ? Math.min(quality.keyframeMs, fallbackKeyframeMs) : quality.keyframeMs;
+    const onDemand = videoEncoder.controllable();
+    const keyframeMs = onDemand ? 0 : sockets ? Math.min(quality.keyframeMs, fallbackKeyframeMs) : quality.keyframeMs;
     const videoProfile = profile();
-    const intraRefresh = !sockets;
+    const intraRefresh = !onDemand && !sockets;
     const pixelFormat = videoProfile === "high444" ? "yuv444p" : "yuv420p";
+    const live = `rung ${rung} \xB7 crf ${quality.crf} \xB7 ${encodeFps} fps`;
+    const restart = `${activeProfile} \xB7 ${preset} \xB7 ${videoProfile} \xB7 keyframe ${keyframeMs ? `${keyframeMs}ms${intraRefresh ? " refresh" : ""}` : "on demand"}`;
     return {
       quality,
       preset,
@@ -4624,7 +4716,8 @@ async function runMediaServer() {
       pixelFormat,
       fps: encodeFps,
       chromaQpOffset: profiles[activeProfile].chromaQpOffset,
-      signature: `rung ${rung} \xB7 ${activeProfile} crf ${quality.crf} \xB7 ${preset} \xB7 ${videoProfile} \xB7 keyframe ${keyframeMs}ms${intraRefresh ? " refresh" : ""} \xB7 ${encodeFps} fps`
+      signature: onDemand ? restart : `${live} \xB7 ${restart}`,
+      description: `${live} \xB7 ${restart}`
     };
   };
   const budgetBps = () => ladder()[rung].kbps * 1e3 * budgetFactor;
@@ -4645,6 +4738,7 @@ async function runMediaServer() {
       if (!keyframe2 && (viewer.waitingForKeyframe || queueMs(viewer) > targetBacklogMs || socket.bufferedAmount > fallbackBufferedBytes)) {
         viewer.waitingForKeyframe = true;
         viewer.withheldFrames += 1;
+        if (videoEncoder.controllable() && queueMs(viewer) <= targetBacklogMs && socket.bufferedAmount <= fallbackBufferedBytes) requestKeyframe("socket viewer caught up", void 0, viewer);
         continue;
       }
       if (keyframe2) viewer.waitingForKeyframe = false;
@@ -4676,7 +4770,7 @@ async function runMediaServer() {
     let sockets = false;
     for (const viewer of viewers.values()) {
       if (viewer.fallback) sockets = true;
-      else viewer.rtc?.enqueueVideo(rtp ??= withPlayoutDelay(packet, PLAYOUT_DELAY_ID), frameId, keyframe, last);
+      viewer.rtc?.enqueueVideo(rtp ??= withPlayoutDelay(packet, PLAYOUT_DELAY_ID), frameId, keyframe, last);
     }
     frameStart = last;
     if (last) {
@@ -4685,7 +4779,12 @@ async function runMediaServer() {
     }
     if (!sockets) return;
     const parsed = parseRtpPacket(packet);
+    const discarded = videoAssembler.discarded;
     const frame = parsed && videoAssembler.push(parsed);
+    if (videoAssembler.discarded !== discarded) {
+      for (const viewer of socketViewers()) viewer.waitingForKeyframe = true;
+      if (videoEncoder.controllable()) requestKeyframe("socket frame lost");
+    }
     if (frame) broadcast(mediaPacket(frame.key ? 1 /* VideoKey */ : 2 /* VideoDelta */, frame.timestamp, frame.data), frame.key);
   };
   const onAudioPacket = (packet, generation) => {
@@ -4696,7 +4795,7 @@ async function runMediaServer() {
     let sockets = false;
     for (const viewer of viewers.values()) {
       if (viewer.fallback) sockets = true;
-      else viewer.rtc?.sendAudio(packet);
+      viewer.rtc?.sendAudio(packet);
     }
     if (!sockets) return;
     const parsed = parseRtpPacket(packet);
@@ -4770,20 +4869,30 @@ async function runMediaServer() {
   const ensureEncoders = () => {
     clearTimeout(encoderStop);
     void audioEncoder.start();
-    const { signature } = encoderParams();
+    const { signature, description, quality, fps: encodeFps } = encoderParams();
+    const live = { crf: quality.crf, kbps: quality.kbps, fps: encodeFps };
     if (!videoWanted) {
       videoWanted = true;
       encoderSignature = signature;
-      record("encoder", signature);
+      encoderDescription = description;
+      encoderLive = live;
+      record("encoder", description);
       void videoEncoder.start();
       return false;
     }
-    if (signature === encoderSignature) return false;
-    encoderSignature = signature;
-    lastSwapAt = Date.now();
-    record("encoder", signature);
-    void videoEncoder.replace();
-    return true;
+    if (description !== encoderDescription) record("encoder", description);
+    encoderDescription = description;
+    if (signature !== encoderSignature) {
+      encoderSignature = signature;
+      encoderLive = live;
+      lastSwapAt = Date.now();
+      void videoEncoder.replace();
+      return true;
+    }
+    if (live.crf !== encoderLive.crf || live.kbps !== encoderLive.kbps) videoEncoder.control(`quality ${live.crf} ${live.kbps}`);
+    if (live.fps !== encoderLive.fps) videoEncoder.control(`fps ${live.fps}`);
+    encoderLive = live;
+    return false;
   };
   const syncEncoder = () => videoWanted && viewers.size > 0 && ensureEncoders();
   const stopEncodersSoon = () => {
@@ -4801,8 +4910,9 @@ async function runMediaServer() {
     const quality = ladder()[next];
     record(next > rung ? "quality down" : "quality up", `rung ${rung} \u2192 ${next} (${quality.kbps} kbps cap, crf ${quality.crf}): ${reason}`);
     if (next > rung) {
-      if (now - lastDescentAt > 1e4) descents += 1;
+      if (now - lastDescentAt > 1e4) descents.push(now);
       lastDescentAt = now;
+      failedRung = rung;
       if (now - lastAscentAt < 15e3) {
         blockedRung = rung;
         blockedUntil = now + 12e4;
@@ -4818,7 +4928,8 @@ async function runMediaServer() {
   const resetLadder = (request) => {
     rung = request.transport === "webrtc" && request.adaptive ? webrtcStartupRung : 0;
     cleanTransportSeconds = 0;
-    descents = 0;
+    descents = [];
+    failedRung = -1;
     lastDescentAt = 0;
     lastAscentAt = 0;
     congestedSeconds = 0;
@@ -4838,6 +4949,7 @@ async function runMediaServer() {
     const sent = Math.min(...recentVideoKbps);
     return remb !== void 0 && earlier !== void 0 && remb <= earlier.kbps && sent > 500 && remb < sent * 0.9;
   };
+  const loaded = () => Math.min(...recentVideoKbps) > 500;
   const signals = (viewer, stats) => {
     const now = Date.now();
     if (viewer.fallback) {
@@ -4848,22 +4960,24 @@ async function runMediaServer() {
     }
     const stableSince = stableRttWindows.get(viewer)?.since;
     return [
-      ...viewer.rttFloorMs > viewer.rtcBaselineMs + 40 && (stableSince === void 0 || now - stableSince < 2e3) ? [`rtt floor ${Math.round(viewer.rttFloorMs)} ms over ${Math.round(viewer.rtcBaselineMs)} ms baseline`] : [],
+      ...viewer.rttFloorMs > viewer.rtcBaselineMs + 40 && (stableSince === void 0 || now - stableSince < 2e3) && loaded() ? [`rtt floor ${Math.round(viewer.rttFloorMs)} ms over ${Math.round(viewer.rtcBaselineMs)} ms baseline`] : [],
       ...stats.videoFps < expectedFps() * 0.6 && viewer.lowFpsReports >= 2 ? [`decoded ${stats.videoFps.toFixed(0)} fps`] : [],
-      ...(stats.lossPercent ?? 0) > 3 ? [`loss ${(stats.lossPercent ?? 0).toFixed(1)}%`] : [],
-      ...(stats.jitterBufferMs ?? 0) > 80 ? [`jitter buffer ${(stats.jitterBufferMs ?? 0).toFixed(0)} ms`] : []
+      ...(stats.lossPercent ?? 0) > 3 && loaded() ? [`loss ${(stats.lossPercent ?? 0).toFixed(1)}%`] : [],
+      ...(stats.jitterBufferMs ?? 0) > 80 && loaded() ? [`jitter buffer ${(stats.jitterBufferMs ?? 0).toFixed(0)} ms`] : []
     ];
   };
   const lowFpsObservationAt = /* @__PURE__ */ new WeakMap();
-  const severe = (viewer, stats) => !viewer.fallback && ((stats.lossPercent ?? 0) > 10 || stats.videoFps < expectedFps() * 0.25 && viewer.lowFpsReports >= 2);
+  const severe = (viewer, stats) => !viewer.fallback && ((stats.lossPercent ?? 0) > 10 && loaded() || stats.videoFps < expectedFps() * 0.25 && viewer.lowFpsReports >= 2);
   let lastSevereDescentAt = 0;
   const descendSevere = (now, trigger) => {
     comfortableSeconds = 0;
     congestedSeconds = 0;
     if (!adaptive || now - lastSevereDescentAt < 1e3) return;
     lastSevereDescentAt = now;
+    const sent = Math.min(...recentVideoKbps);
     const estimates = [...viewers.values()].flatMap((viewer) => {
-      const reported = viewer.stats && now - viewer.stats.at < 750 ? viewer.stats.availableKbps ?? 0 : 0;
+      const available = viewer.stats && now - viewer.stats.at < 750 ? viewer.stats.availableKbps ?? 0 : 0;
+      const reported = sent > 500 && available < sent * 0.9 ? available : 0;
       const remb = rembBelowSent(viewer, now) ? freshRemb(viewer, now) ?? 0 : 0;
       return [...reported > 0 ? [reported] : [], ...remb > 0 ? [remb] : []];
     });
@@ -4880,9 +4994,12 @@ async function runMediaServer() {
     videoKbps = Math.round((videoBytes - bytesAtTick) * 8 / 1e3);
     bytesAtTick = videoBytes;
     if (recentVideoKbps.push(videoKbps) > 3) recentVideoKbps.shift();
-    if (viewers.size === 0) return;
+    if (viewers.size === 0) {
+      starvedSeconds = 0;
+      return;
+    }
     const { captureBackend, captureMetrics } = videoEncoder.capture();
-    const captureBusy = captureBackend !== "native" || !captureMetrics || captureMetrics.busyMs / captureMetrics.elapsedMs > 0.8;
+    const captureBusy = captureBackend !== "native" || (captureMetrics ? captureMetrics.busyMs / captureMetrics.elapsedMs > 0.8 : videoEncoder.activeForMs() > 2500);
     if (videoEncoder.running() && encoderFps < streamFps() * 0.9 && captureBusy) {
       cleanTransportSeconds = 0;
       congestedSeconds = 0;
@@ -4931,15 +5048,16 @@ async function runMediaServer() {
       return;
     }
     congestedSeconds = Math.max(0, congestedSeconds - 0.5);
-    if (descents === 0 && reporting.some((viewer) => !viewer.fallback && (viewer.rttFloorMs > viewer.rtcBaselineMs + 20 || (viewer.stats.playbackDroppedPercent ?? 0) > 5 && cleanTransportSeconds < 15))) {
+    descents = descents.filter((at) => now - at < descentMemoryMs);
+    if (descents.length === 0 && reporting.some((viewer) => !viewer.fallback && (viewer.rttFloorMs > viewer.rtcBaselineMs + 20 && loaded() || (viewer.stats.playbackDroppedPercent ?? 0) > 5 && cleanTransportSeconds < 15))) {
       comfortableSeconds = 0;
       return;
     }
     comfortableSeconds += 1;
-    const startupSeconds = reporting.every((viewer) => !viewer.fallback) ? 2 : 3;
-    const recoverySeconds = lastAscentAt > lastDescentAt && cleanTransportSeconds >= 15 ? 15 : Math.min(60, 15 * 2 ** Math.min(descents, 2));
-    if (comfortableSeconds < (descents === 0 ? startupSeconds : recoverySeconds)) return;
     const target = Math.max(0, rung - 1);
+    const startupSeconds = reporting.every((viewer) => !viewer.fallback) ? 2 : 3;
+    const retrySeconds = lastAscentAt > lastDescentAt && cleanTransportSeconds >= 15 ? 15 : Math.min(60, 15 * 2 ** Math.min(descents.length - 1, 2));
+    if (comfortableSeconds < (descents.length > 0 && target <= failedRung ? retrySeconds : startupSeconds)) return;
     if (target === blockedRung && now < blockedUntil) return;
     setRung(target, `${comfortableSeconds}s comfortable, ${cleanTransportSeconds}s clean transport`);
   }, 1e3);
@@ -5019,9 +5137,18 @@ async function runMediaServer() {
 `);
   }, telemetryIntervalMs);
   telemetry.unref();
+  let lastKeyframeRequestAt = 0;
   const requestKeyframe = (reason, joinedAt, requestingViewer) => {
     const now = Date.now();
     if (!videoWanted || viewers.size === 0 || videoEncoder.replacing() || lastKeyframeAt < now - videoEncoder.activeForMs() || joinedAt !== void 0 && lastKeyframeAt > joinedAt) return;
+    if (videoEncoder.controllable()) {
+      const rttMs = requestingViewer?.rtc?.rttMs ?? requestingViewer?.stats?.rttMs ?? 0;
+      if (joinedAt === void 0 && now - Math.max(lastKeyframeAt, lastKeyframeRequestAt) < Math.max(300, rttMs + 150)) return;
+      if (!videoEncoder.control("keyframe")) return;
+      lastKeyframeRequestAt = now;
+      record("keyframe", reason);
+      return;
+    }
     const startup = requestingViewer && !requestingViewer.hasDecodedFrame && now - requestingViewer.connectedAt < 1e4;
     const wait = (joinedAt === void 0 ? startup ? 500 : 2e3 : 350) - (now - lastSwapAt);
     if (wait > 0) {
@@ -5031,7 +5158,9 @@ async function runMediaServer() {
       }
       return;
     }
-    if (!startup && encoderParams().keyframeMs - (now - lastKeyframeAt) <= 350) return;
+    const { keyframeMs, intraRefresh } = encoderParams();
+    const untilPeriodic = keyframeMs - (now - lastKeyframeAt);
+    if (!startup && !intraRefresh && untilPeriodic >= 0 && untilPeriodic <= 350) return;
     lastSwapAt = now;
     record("keyframe", reason);
     void videoEncoder.replace();
@@ -5044,16 +5173,51 @@ async function runMediaServer() {
       process.stderr.write(`[desktop-stream] webrtc fallback diagnostics: ${JSON.stringify(entry)}
 `);
     }
-    if (viewer.fallback) return;
+    const retried = viewer.rtc;
+    viewer.rtc?.close();
+    viewer.rtc = void 0;
+    if (viewer.fallback) {
+      if (retried) record("webrtc retry failed", reason);
+      return;
+    }
     viewer.fallback = true;
     viewer.waitingForKeyframe = true;
     viewer.input.release();
-    viewer.rtc?.close();
-    viewer.rtc = void 0;
     record("fallback to socket", reason);
     if (!syncEncoder()) requestKeyframe("socket fallback");
   };
   const optional = (value, max) => value === void 0 ? void 0 : clamp(value, 0, max);
+  const openWebRtc = (viewer, reply, iceServers) => {
+    try {
+      viewer.rtc = new WebRtcViewer({ iceServers, iceTransportPolicy: "all", portRange: icePorts, budgetBps: budgetBps() }, {
+        offer: (sdp) => reply({ type: "offer", sdp }),
+        candidate: (candidate, mid) => reply({ type: "candidate", candidate, mid }),
+        message: (message, answer) => handleMessage(viewer, message, answer),
+        keyframe: (reason) => {
+          if (reason === "stale" && Date.now() - lastDescentAt > 1e3) descendSevere(Date.now(), "send queue went stale and was cut back to a keyframe");
+          requestKeyframe(reason === "pli" ? "receiver pli" : "stale send queue", void 0, viewer);
+        },
+        remb: (bitsPerSecond) => {
+          if (viewer.rembs.push({ kbps: bitsPerSecond / 1e3, at: Date.now() }) > 16) viewer.rembs.shift();
+        },
+        connected: () => {
+          record("webrtc connected", viewer.rtc?.path ?? void 0);
+          requestKeyframe("viewer joined", Date.now());
+        },
+        // A viewer that loses its peer cannot send the key-ups for whatever it
+        // was holding, and its socket may stay open for a long time yet. A socket
+        // viewer trying WebRTC again still sends its input over the socket.
+        disconnected: (state) => {
+          record(`webrtc ${state}`);
+          if (!viewer.fallback) viewer.input.release();
+          if (state === "failed") reply({ type: "webrtc-failed" });
+        }
+      });
+    } catch (error) {
+      record("webrtc error", `could not create a peer connection: ${error instanceof Error ? error.message : String(error)}`);
+      reply({ type: "webrtc-failed" });
+    }
+  };
   const handleMessage = (viewer, message, reply) => {
     switch (message.type) {
       case "ping":
@@ -5131,7 +5295,7 @@ async function runMediaServer() {
         }
         if (viewer.stats.videoFps > 0) viewer.hasDecodedFrame = true;
         if (viewer.stats.videoFps >= expectedFps() * 0.8) viewer.everHealthy = true;
-        if (encoderHealthyTicks >= 3 && videoEncoder.running() && [...viewers.values()].every((v) => !v.fallback && v.stats && now - v.stats.at < 750 && now - v.connectedAt > 2500 && (v.stats.videoPacketsPerSecond ?? 0) > 0 && (v.stats.lossPercent ?? 0) > 10)) descendSevere(now, "every viewer reports over 10% loss");
+        if (encoderHealthyTicks >= 3 && videoEncoder.running() && loaded() && [...viewers.values()].every((v) => !v.fallback && v.stats && now - v.stats.at < 750 && now - v.connectedAt > 2500 && (v.stats.videoPacketsPerSecond ?? 0) > 0 && (v.stats.lossPercent ?? 0) > 10)) descendSevere(now, "every viewer reports over 10% loss");
         return;
       }
       case "answer":
@@ -5144,8 +5308,28 @@ async function runMediaServer() {
       case "fallback":
         enterFallback(viewer, message.reason, message.failure);
         return;
+      // A socket viewer whose WebRTC attempt failed tries again in the background;
+      // the socket keeps carrying its media until the new peer shows video.
+      case "retry-webrtc": {
+        const retryable = () => webrtc && viewer.fallback && !viewer.rtc && viewer.request.transport === "webrtc" && viewer.socket.readyState === WebSocket2.OPEN;
+        if (!retryable()) return;
+        void currentIceServers().then((ice) => {
+          if (!retryable()) return;
+          record("retrying webrtc", "socket media continues meanwhile");
+          openWebRtc(viewer, reply, ice.native);
+        });
+        return;
+      }
+      case "webrtc-ready":
+        if (!viewer.fallback || !viewer.rtc?.connected) return;
+        viewer.fallback = false;
+        viewer.withheldFrames = 0;
+        record("back on webrtc", viewer.rtc.path ?? void 0);
+        syncEncoder();
+        return;
       case "keyframe":
-        if (!viewer.fallback) requestKeyframe("viewer watchdog", void 0, viewer);
+        if (viewer.fallback) viewer.waitingForKeyframe = true;
+        if (!viewer.fallback || videoEncoder.controllable()) requestKeyframe(viewer.fallback ? "socket viewer decoder reset" : "viewer watchdog", void 0, viewer);
         return;
       case "theme":
         applyDesktopTheme(message.theme);
@@ -5237,10 +5421,11 @@ async function runMediaServer() {
     if (extname(path) === ".html") {
       ensureEncoders();
       if (viewers.size === 0) stopEncodersSoon();
+      if (webrtc) void currentIceServers();
       response.setHeader("cache-control", "no-store");
       const digest = createHash3("sha1");
-      for (const name of readdirSync(webroot).filter((file) => /\.(js|css)$/.test(file)).sort()) digest.update(readFileSync6(resolve3(webroot, name)));
-      response.end(readFileSync6(path, "utf8").replaceAll("__VERSION__", `${COMPUTER_USE_VERSION}-${digest.digest("hex").slice(0, 8)}`));
+      for (const name of readdirSync(webroot).filter((file) => /\.(js|css)$/.test(file)).sort()) digest.update(readFileSync7(resolve3(webroot, name)));
+      response.end(readFileSync7(path, "utf8").replaceAll("__VERSION__", `${COMPUTER_USE_VERSION}-${digest.digest("hex").slice(0, 8)}`));
       return;
     }
     response.setHeader("cache-control", "private, max-age=31536000, immutable");
@@ -5253,9 +5438,10 @@ async function runMediaServer() {
       socket.destroy();
       return;
     }
-    webSocketServer.handleUpgrade(request, socket, head, (client) => webSocketServer.emit("connection", client, parseStreamRequest(url.searchParams, defaultRequest), url.searchParams.get("standby") === "1"));
+    const streamRequest = parseStreamRequest(url.searchParams, defaultRequest);
+    void (webrtc && streamRequest.transport === "webrtc" ? currentIceServers() : Promise.resolve(void 0)).then((ice) => webSocketServer.handleUpgrade(request, socket, head, (client) => webSocketServer.emit("connection", client, streamRequest, url.searchParams.get("standby") === "1", ice)));
   });
-  webSocketServer.on("connection", (socket, request, standby) => {
+  webSocketServer.on("connection", (socket, request, standby, ice) => {
     const viewer = {
       socket,
       input: new InputBridge(display, width, height),
@@ -5289,41 +5475,10 @@ async function runMediaServer() {
     const reply = (message) => {
       if (socket.readyState === WebSocket2.OPEN) socket.send(JSON.stringify(message));
     };
-    const offerWebRtc = webrtc && request.transport === "webrtc";
-    const ice = offerWebRtc ? currentIceServers() : void 0;
     const fallbackProfile = profile() === "high444" ? "main" : profile();
     const configMessage = { ...config, videoCodec: H264_PROFILES[fallbackProfile].codec, iceServers: ice?.browser, request };
     reply(configMessage);
-    if (ice) {
-      try {
-        viewer.rtc = new WebRtcViewer({ iceServers: ice.native, iceTransportPolicy: "all", portRange: icePorts, budgetBps: budgetBps() }, {
-          offer: (sdp) => reply({ type: "offer", sdp }),
-          candidate: (candidate, mid) => reply({ type: "candidate", candidate, mid }),
-          message: (message, answer) => handleMessage(viewer, message, answer),
-          keyframe: (reason) => {
-            if (reason === "stale") descendSevere(Date.now(), "send queue went stale and was cut back to a keyframe");
-            requestKeyframe(reason === "pli" ? "receiver pli" : "stale send queue", void 0, viewer);
-          },
-          remb: (bitsPerSecond) => {
-            if (viewer.rembs.push({ kbps: bitsPerSecond / 1e3, at: Date.now() }) > 16) viewer.rembs.shift();
-          },
-          connected: () => {
-            record("webrtc connected", viewer.rtc?.path ?? void 0);
-            requestKeyframe("viewer joined", Date.now());
-          },
-          // A viewer that loses its peer cannot send the key-ups for whatever it
-          // was holding, and its socket may stay open for a long time yet.
-          disconnected: (state) => {
-            record(`webrtc ${state}`);
-            viewer.input.release();
-            if (state === "failed") reply({ type: "webrtc-failed" });
-          }
-        });
-      } catch (error) {
-        record("webrtc error", `could not create a peer connection: ${error instanceof Error ? error.message : String(error)}`);
-        reply({ type: "webrtc-failed" });
-      }
-    }
+    if (ice) openWebRtc(viewer, reply, ice.native);
     if (!viewer.rtc) enterFallback(viewer, request.transport === "webrtc" ? "webrtc unavailable" : "websocket requested");
     ensureEncoders();
     socket.on("message", (raw, binary) => {