@hienlh/ppm 0.23.11 → 0.23.12

package/src/server/routes/files.ts

@@ -5,6 +5,8 @@ import { existsSync, mkdirSync } from "node:fs";
 import { fileService, SecurityError, NotFoundError, ValidationError } from "../../services/file.service.ts";
 import { readSystemFileSync } from "../../services/fs-browse.service.ts";
 import { ok, err } from "../../types/api.ts";
+import type { FileIndexTooLarge } from "../../types/project.ts";
+import { REMOTE_FILE_SEARCH_LIMIT } from "../../shared/file-index-limits.ts";
 import { errorStatus } from "../helpers/error-status.ts";
 import { rangeFileResponse } from "../helpers/range-file-response.ts";
 import { handleMediaProbe, handleMediaTranscode, handleMediaTranscodeStop } from "../helpers/media-route-handlers.ts";
@@ -63,15 +65,60 @@ fileRoutes.post("/list-batch", async (c) => {
 });
 
 /**
- * GET /files/index
+ * A project's first walk can outlast Bun's 10 s idle timeout — nxsys-workspace took 7.6 s on an
+ * idle server and more on a busy one — and Bun then cuts the request off with the walk nearly
+ * done. The walk no longer stops the server, so waiting is safe; 30 s is as long as the browser
+ * waits for headers. `c.env` is the Bun server that `app.fetch(req, server)` passed.
+ */
+function outlastFirstWalk(c: { env: unknown; req: { raw: Request } }): void {
+  (c.env as { timeout?: (request: Request, seconds: number) => void } | undefined)?.timeout?.(c.req.raw, 30);
+}
+
+/** Most entries a `/files/index/search` answers with. */
+const MAX_INDEX_SEARCH_LIMIT = 500;
+
+/**
+ * GET /files/index?max=<n>
  * Returns flat array of all project files {path, name} for palette/search.
- * Result is cached; cache is invalidated on file change events.
+ * Result is cached; a file change marks it stale, and the stale list is served while it rebuilds.
+ * With `max`, a project holding more entries than that answers `FileIndexTooLarge` instead of the
+ * list, to be searched with `/files/index/search`.
  */
-fileRoutes.get("/index", (c) => {
+fileRoutes.get("/index", async (c) => {
   try {
     const projectPath = c.get("projectPath");
-    const entries = fileService.buildIndex(projectPath);
-    return c.json(ok(entries));
+    outlastFirstWalk(c);
+    // The body is serialised and gzipped once per walk, on the index worker: nxsys-workspace's
+    // is 22 MB, which cost ~120 ms of the event loop to serialise and compress per download.
+    const build = await fileService.buildIndex(projectPath);
+    const max = Number(c.req.query("max"));
+    if (max > 0 && build.count > max) return c.json(ok<FileIndexTooLarge>({ tooLarge: true, count: build.count }));
+    const gzip = (c.req.header("Accept-Encoding") ?? "").includes("gzip");
+    return new Response(gzip ? build.gzip : build.json, {
+      headers: {
+        "Content-Type": "application/json",
+        ...(gzip && { "Content-Encoding": "gzip", Vary: "Accept-Encoding" }),
+      },
+    });
+  } catch (e) {
+    return c.json(err((e as Error).message), errorStatus(e));
+  }
+});
+
+/**
+ * GET /files/index/search?q=<query>&kind=file|all&limit=<n>
+ * The best entries of the file index for `q`, best first — ranked as the palette ranks a list it
+ * holds — searched on the server, for a project whose list is too long to send. `kind=all`
+ * includes directories. A blank `q` answers the first entries in list order.
+ */
+fileRoutes.get("/index/search", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    outlastFirstWalk(c);
+    const query = c.req.query("q") ?? "";
+    const kind = c.req.query("kind") === "all" ? "all" : "file";
+    const limit = Math.min(Math.max(Math.trunc(Number(c.req.query("limit"))) || REMOTE_FILE_SEARCH_LIMIT, 1), MAX_INDEX_SEARCH_LIMIT);
+    return c.json(ok(await fileService.searchIndex(projectPath, query, kind, limit)));
   } catch (e) {
     return c.json(err((e as Error).message), errorStatus(e));
   }

package/src/server/routes/remote-desktop.ts

@@ -1,8 +1,9 @@
 /**
  * `GET /api/remote-desktop/capabilities` (read-only, always answerable — includes the host's
  * requirements checklist), `POST /api/remote-desktop/requirements/:id/:action` (host-side
- * fixes: OS permission prompt, open its Settings pane) and `POST /api/remote-desktop/session` (mints the single-use WS
- * nonce). Guard style mirrors
+ * fixes: OS permission prompt, open its Settings pane), `POST /api/remote-desktop/session` (mints the single-use WS
+ * nonce) and `POST /api/remote-desktop/whep/:ticket` (the WebRTC handshake, forwarded to the
+ * session's own loopback relay). Guard style mirrors
  * `named-tunnel.ts`: `authMiddleware` already passes every request through when PPM auth is
  * disabled, so a feature that hands out host control must enforce `auth.enabled` itself, plus
  * a same-origin check so a foreign page can't drive it via ambient browser credentials.
@@ -15,6 +16,10 @@ import { isRemoteDesktopEnabled } from "../../services/remote-desktop/remote-des
 import { mintRemoteDesktopNonce } from "../../services/remote-desktop/remote-desktop-nonce.ts";
 import { listDisplays } from "../../services/remote-desktop/remote-desktop-displays.ts";
 import { remoteDesktopReadiness, runHostAction } from "../../services/remote-desktop/remote-desktop-requirements.ts";
+import { resolveWhepTarget } from "../../services/remote-desktop/remote-desktop-whep-registry.ts";
+import {
+  relayStatus, startMediamtxInstall, uninstallMediamtx,
+} from "../../services/remote-desktop/mediamtx-install.service.ts";
 
 export const remoteDesktopRoutes = new Hono();
 
@@ -84,3 +89,91 @@ remoteDesktopRoutes.post("/session", (c) => {
   if (rejected) return rejected;
   return c.json(ok({ nonce: mintRemoteDesktopNonce(), wsPath: "/ws/remote-desktop" }));
 });
+
+/**
+ * WHEP: the browser posts an SDP offer, the relay answers with an SDP answer, and media then
+ * flows peer-to-peer over the relay's ICE port.
+ *
+ * The relay's signalling port is bound to loopback (`mediamtx-config.ts`), so this proxy is
+ * the only way to reach it — and it is deliberately **ticket-addressed, never URL-addressed**:
+ * the client presents a ticket PPM minted for its own session and handed it over the
+ * already-authenticated WebSocket. Forwarding a client-supplied URL here would turn a feature
+ * that already carries host control into an SSRF hole.
+ *
+ * `Location` from the relay is not passed back: it addresses 127.0.0.1 and means nothing to
+ * the browser. MediaMTX drops the session on its own when the peer connection goes away.
+ */
+const MAX_SDP_BYTES = 64 * 1024;
+
+remoteDesktopRoutes.post("/whep/:ticket", async (c) => {
+  const rejected = assertSessionAllowed(c);
+  if (rejected) return rejected;
+
+  const target = resolveWhepTarget(c.req.param("ticket"));
+  // One answer for unknown and for expired: a distinguishable pair would say whether a ticket
+  // ever existed.
+  if (!target) return c.json(err("unknown or expired WebRTC ticket"), 404);
+
+  const contentType = c.req.header("content-type") ?? "";
+  if (!contentType.startsWith("application/sdp")) {
+    return c.json(err("expected application/sdp"), 415);
+  }
+  const offer = await c.req.text();
+  if (offer.length > MAX_SDP_BYTES) return c.json(err("SDP offer too large"), 413);
+
+  let answer: Response;
+  try {
+    answer = await fetch(target, {
+      method: "POST",
+      headers: { "content-type": "application/sdp" },
+      body: offer,
+    });
+  } catch {
+    // The relay died between the ticket being handed out and this call.
+    return c.json(err("the WebRTC relay is not reachable"), 502);
+  }
+
+  const body = await answer.text();
+  if (!answer.ok) return c.json(err(`relay rejected the offer (${answer.status})`), 502);
+  return new Response(body, {
+    status: 201,
+    headers: { "content-type": "application/sdp", "cache-control": "no-store" },
+  });
+});
+
+/**
+ * The WebRTC relay's own install lifecycle, for the Settings pane.
+ *
+ * Behind the same guards as `/session`: downloading and unpacking an executable onto the host
+ * is host control, and the same-origin check keeps a foreign page from triggering it with
+ * ambient credentials.
+ */
+remoteDesktopRoutes.get("/relay", (c) => {
+  const rejected = assertSessionAllowed(c);
+  if (rejected) return rejected;
+  return c.json(ok(relayStatus()));
+});
+
+remoteDesktopRoutes.post("/relay/install", (c) => {
+  const rejected = assertSessionAllowed(c);
+  if (rejected) return rejected;
+  try {
+    return c.json(ok(startMediamtxInstall()));
+  } catch (e) {
+    return c.json(err((e as Error).message), 409);
+  }
+});
+
+remoteDesktopRoutes.post("/relay/uninstall", (c) => {
+  const rejected = assertSessionAllowed(c);
+  if (rejected) return rejected;
+  try {
+    // False means a copy PPM did not install — the host's own, which is not PPM's to remove.
+    const removed = uninstallMediamtx();
+    return removed
+      ? c.json(ok({ removed }))
+      : c.json(err("this copy was not installed by PPM"), 409);
+  } catch (e) {
+    return c.json(err((e as Error).message), 409);
+  }
+});

package/src/server/routes/trace.ts

@@ -0,0 +1,66 @@
+/**
+ * Session trace over HTTP: browser logs coming in, and a session's timeline going out.
+ * Both sit behind authMiddleware — an error raised while logged out is lost, by decision.
+ */
+import { Hono } from "hono";
+import { ok, err } from "../../types/api.ts";
+import {
+  DeviceRateLimiter,
+  TRACE_INGEST_MAX_BODY_BYTES,
+  browserRows,
+  parseBrowserBatch,
+} from "../../services/session-trace/browser-trace-ingest.ts";
+import { appendBatch, readSessionTimeline } from "../../services/session-trace/session-trace-store.ts";
+
+const MAX_TIMELINE_ROWS = 20_000;
+
+export function createTraceRoutes(limiter = new DeviceRateLimiter()): Hono {
+  const routes = new Hono();
+
+  /** POST /api/trace — body: BrowserTraceBatch (`src/shared/session-trace.ts`). */
+  routes.post("/", async (c) => {
+    const declared = Number(c.req.header("content-length") ?? 0);
+    if (declared > TRACE_INGEST_MAX_BODY_BYTES) return c.json(err("batch too large"), 400);
+    let text: string;
+    try { text = await c.req.text(); } catch { return c.json(err("unreadable body"), 400); }
+    if (Buffer.byteLength(text) > TRACE_INGEST_MAX_BODY_BYTES) return c.json(err("batch too large"), 400);
+    let raw: unknown;
+    try { raw = JSON.parse(text); } catch { return c.json(err("body must be JSON"), 400); }
+
+    const parsed = parseBrowserBatch(raw);
+    if (!parsed.ok) return c.json(err(parsed.error), 400);
+
+    const { batch, dropped } = parsed;
+    const verdict = limiter.take(batch.deviceId, batch.entries.length);
+    if (!verdict.allowed) {
+      c.header("Retry-After", String(Math.ceil(verdict.retryAfterMs / 1000)));
+      return c.json(err("too many trace entries from this device"), 429);
+    }
+
+    try {
+      appendBatch(browserRows(batch));
+    } catch (e) {
+      // 503 rather than 500: the client keeps the batch and tries again later.
+      console.warn(`[session-trace] browser batch not stored: ${(e as Error).message}`);
+      return c.json(err("trace store unavailable"), 503);
+    }
+    return c.json(ok({ accepted: batch.entries.length, dropped }));
+  });
+
+  /**
+   * GET /api/trace/sessions/:sessionId — the session's own trace plus every browser row filed
+   * against it, under any id the session has had, oldest first.
+   */
+  routes.get("/sessions/:sessionId", (c) => {
+    const limit = Math.min(MAX_TIMELINE_ROWS, Math.max(1, Number(c.req.query("limit")) || 5_000));
+    try {
+      return c.json(ok({ events: readSessionTimeline(c.req.param("sessionId"), limit) }));
+    } catch (e) {
+      return c.json(err((e as Error).message), 500);
+    }
+  });
+
+  return routes;
+}
+
+export const traceRoutes = createTraceRoutes();

package/src/server/ws/android.ts

@@ -0,0 +1,101 @@
+/**
+ * WS handler for `/ws/android` — binary out = framed H.264 access units, text in/out = JSON.
+ *
+ * The upgrade succeeding proves nothing: the coarse PPM token travels as `?token=` on every WS
+ * URL (`isWsUpgradeAuthorized`, `src/server/index.ts`) and says only "holds the one reusable app
+ * token". A socket that hands over touch and keyboard control of a running VM therefore requires
+ * a single-use, short-TTL nonce from `POST /api/android/devices/:deviceId/sessions` as the
+ * client's *first* message, and the nonce — not the URL — is what names the device.
+ *
+ * The flag and `auth.enabled` are re-checked here even though `src/server/index.ts` already gated
+ * the upgrade on them: this handler must never depend on one call site staying correct, and must
+ * NOT reuse `isWsUpgradeAuthorized()`, which returns true unconditionally when PPM auth is off.
+ */
+import { configService } from "../../services/config.service.ts";
+import { isAndroidEmulatorEnabled } from "../../services/android/android-flag.ts";
+import { consumeAndroidNonce } from "../../services/android/android-nonce.ts";
+import { findRunningByDeviceId } from "../../services/android/device-registry.ts";
+import {
+  attachAndroidViewer, registerAndroidExitSweep,
+  type AndroidSocket, type AndroidViewerSession,
+} from "../../services/android/android-session.ts";
+import { ANDROID_QUALITY_PRESETS, type AndroidQuality } from "../../shared/android-protocol.ts";
+
+registerAndroidExitSweep();
+
+interface AndroidWs {
+  data: { type: "android"; session?: AndroidViewerSession; authenticated?: boolean; closed?: boolean };
+  send: (d: string | Uint8Array) => number;
+  getBufferedAmount?: () => number;
+  close: (code?: number, reason?: string) => void;
+}
+
+function guardOrClose(ws: AndroidWs): boolean {
+  if (!isAndroidEmulatorEnabled()) { ws.close(1008, "android emulator support is disabled"); return false; }
+  if (!configService.get("auth").enabled) {
+    ws.close(1008, "android emulator control requires PPM authentication to be enabled");
+    return false;
+  }
+  return true;
+}
+
+/** The session layer's view of this socket. `isClosed` reads the flag `close` below sets: a
+ *  close during `attachAndroidViewer` finds no session to close yet. */
+export function androidSocketFor(ws: AndroidWs): AndroidSocket {
+  return {
+    send: (d) => ws.send(d),
+    getBufferedAmount: ws.getBufferedAmount ? () => ws.getBufferedAmount!() : undefined,
+    close: (code, reason) => ws.close(code, reason),
+    isClosed: () => ws.data.closed === true,
+  };
+}
+
+function parseQuality(value: unknown): AndroidQuality {
+  return typeof value === "string" && value in ANDROID_QUALITY_PRESETS ? (value as AndroidQuality) : "balanced";
+}
+
+async function authenticateFirstMessage(ws: AndroidWs, text: string): Promise<void> {
+  let parsed: Record<string, unknown>;
+  try { parsed = JSON.parse(text); } catch { ws.close(1008, "expected auth message"); return; }
+
+  const nonce = parsed.type === "auth" ? parsed.nonce : undefined;
+  const deviceId = typeof nonce === "string" ? consumeAndroidNonce(nonce) : null;
+  if (!deviceId) { ws.close(1008, "invalid or expired session nonce"); return; }
+
+  const emulator = findRunningByDeviceId(deviceId);
+  if (!emulator) { ws.close(1011, "that emulator is no longer running"); return; }
+
+  ws.data.authenticated = true;
+  try {
+    ws.data.session = await attachAndroidViewer(androidSocketFor(ws), {
+      deviceId,
+      emulator,
+      quality: parseQuality(parsed.quality),
+    });
+  } catch (e) {
+    console.error(`[android] failed to start a session: ${(e as Error).message}`);
+    ws.send(JSON.stringify({ type: "error", message: (e as Error).message, fatal: true }));
+    ws.close(1011, "session failed to start");
+  }
+}
+
+export const androidWebSocket = {
+  open(ws: AndroidWs) {
+    guardOrClose(ws); // nothing else until the client's first (auth) message arrives
+  },
+
+  async message(ws: AndroidWs, msg: string | ArrayBuffer | Uint8Array) {
+    if (!guardOrClose(ws)) return;
+    const text = typeof msg === "string" ? msg : new TextDecoder().decode(msg as ArrayBuffer);
+    if (!ws.data.authenticated) {
+      await authenticateFirstMessage(ws, text);
+      return;
+    }
+    await ws.data.session?.handleClientMessage(text);
+  },
+
+  close(ws: AndroidWs) {
+    ws.data.closed = true;
+    ws.data.session?.close();
+  },
+};

package/src/server/ws/chat.ts

@@ -180,7 +180,7 @@ function releaseSubprocess(sessionId: string, reason: string, note: string): voi
   if (entry.clients.size > 0 || entry.isStreamingActive) return;
   const provider = providerRegistry.get(entry.providerId);
   if (!provider?.hasStreamingSession?.(sessionId)) return;
-  provider.abortQuery?.(sessionId, reason);
+  chatService.abortQuery(entry.providerId, sessionId, reason, "ws");
   console.log(`[chat] session=${sessionId} released subprocess (${reason})`);
   logSessionEvent(sessionId, "INFO", note);
 }
@@ -204,7 +204,7 @@ export function dropIdleSubprocess(sessionId: string, reason: string, note: stri
   if (!entry) return;
   const provider = providerRegistry.get(entry.providerId);
   if (!provider?.hasStreamingSession?.(sessionId)) return;
-  provider.abortQuery?.(sessionId, reason);
+  chatService.abortQuery(entry.providerId, sessionId, reason, "ws");
   if (entry.cacheReleaseTimer) {
     clearTimeout(entry.cacheReleaseTimer);
     entry.cacheReleaseTimer = undefined;
@@ -612,7 +612,7 @@ function startCleanupTimer(sessionId: string): void {
     // flight, so the session entry going away is the last chance to free the process.
     const provider = providerRegistry.get(entry.providerId);
     if (provider?.hasStreamingSession?.(sessionId)) {
-      provider.abortQuery?.(sessionId, "idle_timeout");
+      chatService.abortQuery(entry.providerId, sessionId, "idle_timeout", "ws");
     }
     if (entry.cacheReleaseTimer) {
       clearTimeout(entry.cacheReleaseTimer);
@@ -696,7 +696,7 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
     // provider config: omit so the provider falls back. thinking 0 = explicit OFF (overrides config).
     const effortOverride = getSessionEffort(sessionId) ?? undefined;
     const thinkingBudget = getSessionThinking(sessionId);
-    for await (const event of chatService.sendMessage(providerId, sessionId, content, { permissionMode, images, ...(imagePaths?.length && { imagePaths }), ...(model && { model }), ...(effortOverride && { effort: effortOverride }), ...(thinkingBudget != null && { thinkingBudget }) })) {
+    for await (const event of chatService.sendMessage(providerId, sessionId, content, { permissionMode, images, ...(imagePaths?.length && { imagePaths }), ...(model && { model }), ...(effortOverride && { effort: effortOverride }), ...(thinkingBudget != null && { thinkingBudget }), origin: "ws" })) {
       eventCount++;
       const ev = event as any;
       const evType = ev.type ?? "unknown";
@@ -1388,9 +1388,7 @@ export const chatWebSocket = {
       // unblock it, then the follow-up message flows through normally.
       if (entry.pendingApprovalEvent) {
         const pendingReqId = entry.pendingApprovalEvent.requestId;
-        if (provider && typeof provider.resolveApproval === "function") {
-          provider.resolveApproval(pendingReqId, false);
-        }
+        chatService.resolveApproval(providerId, sessionId, pendingReqId, false, undefined, { reason: "superseded_by_message", origin: "ws" });
         entry.pendingApprovalEvent = undefined;
         broadcast(sessionId, {
           type: "approval_resolved",
@@ -1442,6 +1440,7 @@ export const chatWebSocket = {
           const effort = getSessionEffort(sessionId) ?? undefined;
           const thinkingBudget = getSessionThinking(sessionId);
           await chatService.pushMessage(providerId, sessionId, parsed.content, {
+            origin: "ws",
             priority: parsed.priority ?? 'next',
             images: parsed.images,
             imagePaths: parsed.imagePaths,
@@ -1472,7 +1471,7 @@ export const chatWebSocket = {
       // Aborting the idle-but-alive subprocess forces the next message to take
       // the resume path, recreating the query with the new model.
       if (hasLiveStream && entry.phase === "idle") {
-        provider?.abortQuery?.(sessionId, "set_model");
+        chatService.abortQuery(providerId, sessionId, "set_model", "ws");
       }
       logSessionEvent(sessionId, "INFO", `Model switched to ${parsed.model}`);
       ws.send(JSON.stringify({
@@ -1499,7 +1498,7 @@ export const chatWebSocket = {
       // Abort only when idle-but-alive so the next turn recreates the query with the new
       // effort (mirror set_model); never interrupt an active turn.
       if ((provider?.hasStreamingSession?.(sessionId) ?? false) && entry.phase === "idle") {
-        provider?.abortQuery?.(sessionId, "set_effort");
+        chatService.abortQuery(providerId, sessionId, "set_effort", "ws");
       }
       logSessionEvent(sessionId, "INFO", `Effort switched to ${parsed.effort}`);
       ws.send(JSON.stringify({
@@ -1520,7 +1519,7 @@ export const chatWebSocket = {
       setSessionThinking(sessionId, parsed.enabled ? THINKING_ADAPTIVE : 0);
       const provider = providerRegistry.get(providerId);
       if ((provider?.hasStreamingSession?.(sessionId) ?? false) && entry.phase === "idle") {
-        provider?.abortQuery?.(sessionId, "set_thinking");
+        chatService.abortQuery(providerId, sessionId, "set_thinking", "ws");
       }
       logSessionEvent(sessionId, "INFO", `Thinking ${parsed.enabled ? "on" : "off"}`);
       ws.send(JSON.stringify({
@@ -1537,11 +1536,10 @@ export const chatWebSocket = {
       }));
     } else if (parsed.type === "cancel") {
       // Fully teardown streaming session — user must resume to continue
-      const provider = providerRegistry.get(providerId);
       const phase = entry?.phase ?? "unknown";
       console.log(`[chat] session=${sessionId} WS cancel received from FE (phase=${phase})`);
       logSessionEvent(sessionId, "CANCEL", `WS cancel from FE (phase=${phase})`);
-      provider?.abortQuery?.(sessionId, "ws_cancel");
+      chatService.abortQuery(providerId, sessionId, "ws_cancel", "ws");
     } else if (parsed.type === "kill_background_shell") {
       // Kill via the AI: enqueue an instruction so the model calls KillShell.
       // Cross-platform and safe (no OS-PID guessing). Runs when the AI is idle
@@ -1572,17 +1570,14 @@ export const chatWebSocket = {
           }, 0);
         });
       } else if (provider && "pushMessage" in provider) {
-        await chatService.pushMessage(providerId, sessionId, instruction, { priority: "next" });
+        await chatService.pushMessage(providerId, sessionId, instruction, { priority: "next", origin: "ws" });
         entry.turnEvents = [];
         entry.pendingApprovalEvent = undefined;
         setPhase(sessionId, "thinking");
       }
       logSessionEvent(sessionId, "INFO", `kill_background_shell requested shellId=${shellId}`);
     } else if (parsed.type === "approval_response") {
-      const provider = providerRegistry.get(providerId);
-      if (provider && typeof provider.resolveApproval === "function") {
-        provider.resolveApproval(parsed.requestId, parsed.approved, (parsed as any).data);
-      }
+      chatService.resolveApproval(providerId, sessionId, parsed.requestId, parsed.approved, (parsed as any).data, { origin: "ws" });
       if (entry) {
         entry.pendingApprovalEvent = undefined;
         // Enrich the buffered approval_request with response data so replayed

package/src/server/ws/global.ts

@@ -9,7 +9,7 @@
  *     so a workspace whose visible tabs are an editor and a terminal would get no
  *     file watching at all — silently breaking editor live-reload, docx/pdf
  *     preview reload, and file-tree invalidation.
- *  2. **Cross-cutting broadcasts** (`file:changed`, `session:unread_changed`,
+ *  2. **Cross-cutting broadcasts** (`file:changed`, `files:index-changed`, `session:unread_changed`,
  *     `session:phase_changed`, `jira:*`, `design:*`). These are app-wide, not session-scoped,
  *     so they belong on an app-wide channel.
  *
@@ -18,6 +18,7 @@
  * example, make an editor re-fetch its file twice per change).
  */
 import { startWatching, stopWatching, onFileChange } from "../../services/file-watcher.service.ts";
+import { onIndexRebuilt, warmIndex } from "../../services/file-list-index.service.ts";
 import { configService } from "../../services/config.service.ts";
 import { onDesignEvent } from "../../services/design/design-events.ts";
 import { resolve } from "node:path";
@@ -71,6 +72,8 @@ function setWatch(ws: GlobalWsSocket, projectName: string): void {
   if (!project) return;
 
   void startWatching(projectName, project.path);
+  // A client opened this project: have its file list ready before the palette asks for it.
+  warmIndex(project.path);
   watchedProject.set(ws, projectName);
 }
 
@@ -86,6 +89,15 @@ function projectNameForPath(projectPath: string): string | null {
   return configService.get("projects").find((p) => fold(p.path) === target)?.name ?? null;
 }
 
+// A project's file index was rebuilt behind a stale one and now lists other paths. Clients do
+// not refetch the index on every `file:changed` (on a large project that is a 22 MB download
+// per change); this is what tells them the list they hold is out of date.
+onIndexRebuilt((projectPath, changed) => {
+  if (!changed) return;
+  const projectName = projectNameForPath(projectPath);
+  if (projectName) broadcastGlobalEvent({ type: "files:index-changed", projectName });
+});
+
 // Design history/comment changes: `.design/` is not watched, so these are the only signal.
 // Services know the project path; browsers address projects by name, and a path no
 // registered project owns is dropped rather than broadcast.

package/src/server/ws/remote-desktop.ts

@@ -9,7 +9,9 @@
  * client's *first* message — `{type:"auth", nonce, displayId?, cursor?, codec?}` — before
  * capture or input starts. `displayId` picks one of `/capabilities`' `displays`; absent/unknown = primary.
  * `cursor` and `codec` carry the client's saved cursor and encoder prefs, because ffmpeg takes
- * both at startup and applying them afterwards would respawn it on every connect. Kept out of
+ * both at startup and applying them afterwards would respawn it on every connect. `webrtc`
+ * asks for the relay transport; when it is not installed the session answers on this socket
+ * as before rather than failing. Kept out of
  * the query string (unlike the coarse token) so they never land in proxy/tunnel access logs.
  *
  * Both the feature flag and `auth.enabled` are re-checked here even though
@@ -66,6 +68,9 @@ async function authenticateFirstMessage(ws: RemoteDesktopWs, text: string): Prom
       // getting the pointer it has always had.
       showCursor: parsed.cursor !== false,
       encoder: typeof parsed.codec === "string" ? parsed.codec : undefined,
+      // Opt-in, and only honoured when the relay is installed: an older client sends no flag
+      // and keeps the WebSocket path it has always used.
+      webrtc: parsed.webrtc === true,
     });
   } catch (e) {
     console.error(`[remote-desktop] failed to start capture: ${(e as Error).message}`);