@hienlh/ppm 0.23.10 → 0.23.12

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}`);

package/src/services/android/android-apk.ts

@@ -0,0 +1,387 @@
+/**
+ * Installing an APK on a running emulator.
+ *
+ * `EmulatorController` has no install RPC — this is `adb install`, and that is the whole reason
+ * the surface is a *typed* one (plan ADR: "API typed riêng, không mở generic shell/RPC proxy").
+ * The caller names a device and a file; nothing here takes a command, a flag or an argument
+ * string from the browser.
+ *
+ * Two things this file exists to get right:
+ *
+ *  - **The right device.** Measured with two emulators attached, `adb install` with no `-s`
+ *    answers **"adb: more than one device/emulator"** and installs nothing — so the failure mode
+ *    is a refusal rather than the coin toss it looks like, and on a single-device host it would
+ *    work by luck and break the day a second emulator is started. The serial is always passed,
+ *    and `tests/e2e/android-two-device-install-e2e.ts` proves it is honoured rather than merely
+ *    present, by installing to one of two live devices and checking both.
+ *  - **The real reason it failed.** adb reports `INSTALL_FAILED_NO_MATCHING_ABIS` and friends on
+ *    stdout with exit code 0 in some versions, so the exit code alone is not the answer, and the
+ *    raw code alone is not something to show a person.
+ */
+import { existsSync, statSync } from "node:fs";
+
+/** A larger APK than this is almost certainly not what the user meant to upload. */
+export const MAX_APK_BYTES = 2 * 1024 * 1024 * 1024;
+
+/**
+ * How long one `adb install` may take before it is killed (plan §7: "deadline").
+ *
+ * Generous on purpose — a cold guest installing a 300 MB APK is minutes of real work — but not
+ * unbounded: adb against a half-wedged emulator hangs rather than erroring, and an install that
+ * never ends leaves an operation stuck at "running" forever with no way out but a restart.
+ */
+export const INSTALL_DEADLINE_MS = 10 * 60_000;
+
+/**
+ * Total bytes the staging directory may hold at once.
+ *
+ * `MAX_APK_BYTES` bounds one upload; nothing bounds ten at once, and a disk full of half-uploaded
+ * APKs takes the whole PPM directory down with it — the database included.
+ */
+export const MAX_STAGING_BYTES = 4 * 1024 * 1024 * 1024;
+
+export interface InstallOptions {
+  adbPath: string;
+  /** The emulator's adb serial, e.g. `emulator-5554`. Never omitted. */
+  serial: string;
+  apkPath: string;
+  /** Replace an existing install rather than failing on a duplicate package. */
+  reinstall?: boolean;
+  /** Allow installing over a newer version, which adb otherwise refuses. */
+  allowDowngrade?: boolean;
+  onProgress?: (line: string) => void;
+  signal?: AbortSignal;
+  /** Overrides `INSTALL_DEADLINE_MS`; a test uses it to reach the timeout in a second. */
+  deadlineMs?: number;
+}
+
+export interface InstallResult {
+  ok: boolean;
+  /** A sentence to show a person, already explaining what to do about it. */
+  message: string;
+  /** adb's own failure code, when it gave one — worth keeping for a bug report. */
+  code: string | null;
+  output: string;
+}
+
+/**
+ * adb's failure codes, in terms that say what to do. Anything not here is passed through
+ * verbatim rather than flattened into "install failed", which would hide the one useful word.
+ */
+const FAILURES: { code: string; message: string }[] = [
+  { code: "INSTALL_FAILED_NO_MATCHING_ABIS",
+    message: "the APK has no native code for this emulator's ABI — use an x86_64 build, or an AVD whose ABI matches the APK" },
+  { code: "INSTALL_FAILED_OLDER_SDK",
+    message: "the APK needs a newer Android than this AVD runs — start an AVD with a higher API level" },
+  { code: "INSTALL_FAILED_UPDATE_INCOMPATIBLE",
+    message: "a package with this name is already installed and was signed with a different key — uninstall it first" },
+  { code: "INSTALL_FAILED_VERSION_DOWNGRADE",
+    message: "the installed version is newer than this APK — turn on 'allow downgrade' to replace it" },
+  { code: "INSTALL_FAILED_INSUFFICIENT_STORAGE",
+    message: "the emulator has no room left — wipe its data or give the AVD a larger disk" },
+  { code: "INSTALL_FAILED_INVALID_APK",
+    message: "adb could not read this file as an APK — check it is not a partial download or an AAB" },
+  { code: "INSTALL_PARSE_FAILED_NO_CERTIFICATES",
+    message: "the APK is not signed — sign it, or use a debug build" },
+  { code: "INSTALL_FAILED_TEST_ONLY",
+    message: "this is a test-only build — rebuild it without `testOnly`, or install it with adb's own `-t`" },
+  { code: "device offline",
+    message: "the emulator stopped responding to adb — wait for it to finish booting, or restart it" },
+];
+
+/** Turn adb's output into something worth showing, without throwing away what it said. */
+export function explainInstallOutput(output: string, exitCode: number): { ok: boolean; message: string; code: string | null } {
+  const text = output.trim();
+  const failure = FAILURES.find((f) => text.includes(f.code));
+  if (failure) return { ok: false, message: failure.message, code: failure.code };
+
+  // Some adb versions print `Failure [CODE]` for codes this table has never heard of.
+  const unknown = text.match(/Failure\s*\[([A-Z_]+[^\]]*)\]/);
+  if (unknown) return { ok: false, message: `adb refused the install: ${unknown[1]}`, code: unknown[1] ?? null };
+
+  // `Success` on stdout is adb's own word for it, and is more reliable than the exit code:
+  // several adb versions exit 0 on a failed install.
+  if (text.split("\n").some((l) => l.trim() === "Success")) {
+    return { ok: true, message: "installed", code: null };
+  }
+  if (exitCode === 0) return { ok: true, message: "installed", code: null };
+  return { ok: false, message: text || `adb exited with code ${exitCode}`, code: null };
+}
+
+export async function installApk(opts: InstallOptions): Promise<InstallResult> {
+  if (!existsSync(opts.apkPath)) {
+    return { ok: false, message: "that file no longer exists", code: null, output: "" };
+  }
+  const size = statSync(opts.apkPath).size;
+  if (size === 0) return { ok: false, message: "that file is empty", code: null, output: "" };
+  if (size > MAX_APK_BYTES) {
+    return { ok: false, message: `that file is ${(size / 1024 / 1024).toFixed(0)} MB, past the ${MAX_APK_BYTES / 1024 / 1024 / 1024} GB limit`, code: null, output: "" };
+  }
+
+  const args = ["-s", opts.serial, "install"];
+  if (opts.reinstall !== false) args.push("-r");
+  if (opts.allowDowngrade) args.push("-d");
+  args.push(opts.apkPath);
+
+  // Cancelled before it started: adb is never run at all.
+  if (opts.signal?.aborted) return { ok: false, message: "cancelled", code: null, output: "" };
+
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn([opts.adbPath, ...args], { stdout: "pipe", stderr: "pipe", windowsHide: true });
+  } catch (e) {
+    // Bun.spawn throws synchronously when the binary is missing, and the throw escapes an
+    // awaited try placed further out (CLAUDE.md, host-info/spawn-runner.ts).
+    return { ok: false, message: `could not run adb: ${(e as Error).message}`, code: null, output: "" };
+  }
+
+  // Cancel has the same hazard as the deadline below — killing the process may not close its
+  // pipes — so it resolves the race itself rather than relying on the read ending.
+  let resolveAborted: (() => void) | null = null;
+  const aborted = new Promise<"aborted">((resolve) => { resolveAborted = () => resolve("aborted"); });
+  const onAbort = () => {
+    try { proc.kill(); } catch { /* already gone */ }
+    resolveAborted?.();
+  };
+  opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+  /**
+   * Reading the pipes to the end is the *normal* path, not a reliable one.
+   *
+   * Measured: killing the process does **not** necessarily close its pipes — a child that
+   * inherited them keeps them open, and `reader.read()` then never resolves. So the deadline
+   * races this rather than trusting the kill to unblock it, the same shape `Encoder.stop()` in
+   * `android-video.ts` needed for ffmpeg. `.catch` on the handle keeps an abandoned read from
+   * surfacing as an unhandled rejection after this function has already answered.
+   */
+  const collected = (async () => {
+    const [out, errOut] = await Promise.all([
+      readStream(proc.stdout, opts.onProgress),
+      readStream(proc.stderr, opts.onProgress),
+    ]);
+    return { output: `${out}${errOut}`.trim(), exitCode: await proc.exited };
+  })();
+  collected.catch(() => { /* the deadline path abandons this deliberately */ });
+
+  const deadlineMs = opts.deadlineMs ?? INSTALL_DEADLINE_MS;
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<"expired">((resolve) => {
+    deadlineTimer = setTimeout(() => {
+      try { proc.kill(); } catch { /* already gone */ }
+      resolve("expired");
+    }, deadlineMs);
+  });
+
+  try {
+    const outcome = await Promise.race([collected, expired, aborted]);
+    if (outcome === "aborted") {
+      return { ok: false, message: "cancelled", code: null, output: "" };
+    }
+    if (outcome === "expired") {
+      const minutes = deadlineMs >= 60_000 ? `${Math.round(deadlineMs / 60_000)} minutes` : `${Math.round(deadlineMs / 1000)}s`;
+      return {
+        ok: false,
+        message: `adb did not finish within ${minutes} — the emulator may be wedged`,
+        code: null,
+        // Whatever it managed to say, if it closed its pipes on the way out. Never waited for.
+        output: await Promise.race([collected.then((c) => c.output).catch(() => ""), Bun.sleep(300).then(() => "")]),
+      };
+    }
+    if (opts.signal?.aborted) {
+      return { ok: false, message: "cancelled", code: null, output: outcome.output };
+    }
+    return { ...explainInstallOutput(outcome.output, outcome.exitCode), output: outcome.output };
+  } finally {
+    clearTimeout(deadlineTimer);
+    opts.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+/** Manual pull loop, not `for await` — see the note in `android-video.ts`. */
+async function readStream(
+  stream: ReadableStream<Uint8Array> | number | undefined,
+  onLine?: (line: string) => void,
+): Promise<string> {
+  if (!stream || typeof stream === "number") return "";
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let text = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) return text;
+    if (!value) continue;
+    const chunk = decoder.decode(value, { stream: true });
+    text += chunk;
+    if (onLine) for (const line of chunk.split("\n")) { const t = line.trim(); if (t) onLine(t); }
+  }
+}
+
+/* ---------------------------------------------------------------------------------------------
+ * Staging an uploaded APK.
+ *
+ * The plan's Phase 3 gate is "hủy upload không để temp" — a cancelled upload leaves nothing
+ * behind. That is not automatic: an aborted request rejects the read *mid-file*, so the partial
+ * has to be deleted on the way out of every failure path, and a PPM killed mid-upload leaves one
+ * behind that only a later sweep can remove.
+ * ------------------------------------------------------------------------------------------- */
+
+import { mkdirSync, readdirSync, rmSync, statSync as statFile } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { getPpmDir } from "../ppm-dir.ts";
+
+export function apkStagingDir(): string {
+  return join(getPpmDir(), "android", "apk-staging");
+}
+
+/** A staged file older than this is from a PPM that died mid-upload. */
+const STAGING_MAX_AGE_MS = 60 * 60_000;
+
+/**
+ * Called before each upload. What a crash left behind is removed by the next upload once it is an
+ * hour old, and until then counts against `MAX_STAGING_BYTES`, so crashes cannot pile up gigabytes.
+ */
+export function sweepApkStaging(): number {
+  let removed = 0;
+  let names: string[];
+  try { names = readdirSync(apkStagingDir()); } catch { return 0; }
+  for (const name of names) {
+    const path = join(apkStagingDir(), name);
+    try {
+      if (Date.now() - statFile(path).mtimeMs < STAGING_MAX_AGE_MS) continue;
+      rmSync(path, { force: true });
+      removed++;
+    } catch { /* another sweep got there first */ }
+  }
+  return removed;
+}
+
+/** What the staging directory currently holds, for the quota check. */
+export function stagingBytes(): number {
+  let total = 0;
+  try {
+    for (const name of readdirSync(apkStagingDir())) {
+      try { total += statFile(join(apkStagingDir(), name)).size; } catch { /* gone */ }
+    }
+  } catch { /* no directory yet */ }
+  return total;
+}
+
+export interface StagedApk {
+  path: string;
+  bytes: number;
+  /** Idempotent — safe to call after the install, and again on an error path. */
+  discard(): void;
+}
+
+/**
+ * Write an upload to a staging file, refusing anything that is not a zip (an APK is one) and
+ * anything past the size limit — both checked *while* streaming, so a 5 GB body is cut off at
+ * the limit rather than after it has all been written.
+ */
+export async function stageApkUpload(
+  body: ReadableStream<Uint8Array>,
+  opts: { signal?: AbortSignal; maxBytes?: number } = {},
+): Promise<StagedApk> {
+  sweepApkStaging();
+  const alreadyStaged = stagingBytes();
+  if (alreadyStaged >= MAX_STAGING_BYTES) {
+    throw new Error("another upload is still using the staging space — wait for it to finish");
+  }
+  mkdirSync(apkStagingDir(), { recursive: true });
+  const path = join(apkStagingDir(), `${crypto.randomUUID()}.apk`);
+  const discard = () => { try { rmSync(path, { force: true }); } catch { /* already gone */ } };
+
+  const limit = opts.maxBytes ?? MAX_APK_BYTES;
+  const sink = Bun.file(path).writer();
+  const reader = body.getReader();
+  let bytes = 0;
+  let head = new Uint8Array(0);
+
+  try {
+    for (;;) {
+      if (opts.signal?.aborted) throw new Error("cancelled");
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+
+      if (head.length < 4) {
+        const merged = new Uint8Array(head.length + value.length);
+        merged.set(head); merged.set(value, head.length);
+        head = merged.slice(0, 4);
+        if (head.length >= 2 && !(head[0] === 0x50 && head[1] === 0x4b)) {
+          throw new Error("that file is not an APK (no zip header)");
+        }
+      }
+
+      bytes += value.length;
+      if (bytes > limit) throw new Error(`the upload is past the ${limit / 1024 / 1024 / 1024} GB limit`);
+      // The quota counts everything staged, not only this upload: two concurrent 2 GB uploads
+      // each stay under their own limit and together fill the disk the database lives on.
+      if (alreadyStaged + bytes > MAX_STAGING_BYTES) {
+        throw new Error("there is not enough staging space for this upload right now");
+      }
+      sink.write(value);
+    }
+    await sink.end();
+  } catch (e) {
+    try { await sink.end(); } catch { /* the writer may already be broken */ }
+    discard();
+    try { await reader.cancel(); } catch { /* the peer is gone */ }
+    throw e;
+  }
+
+  if (bytes === 0) { discard(); throw new Error("the upload was empty"); }
+  return { path, bytes, discard };
+}
+
+/* ---------------------------------------------------------------------------------------------
+ * Finding the APKs a project has already built.
+ *
+ * A full walk of a project root is not acceptable here — the same reasoning as the recursive
+ * `fs.watch` ban in CLAUDE.md: `node_modules` alone is tens of thousands of directories. This is
+ * depth-bounded and prunes by name, which is enough because Gradle always writes to
+ * a `build/outputs/apk` directory.
+ * ------------------------------------------------------------------------------------------- */
+
+const PRUNED_DIRS = new Set([
+  "node_modules", ".git", ".gradle", ".idea", "vendor", "target", "Pods",
+  ".venv", "venv", "__pycache__", ".next", ".cache", "dist",
+]);
+const MAX_WALK_DEPTH = 8;
+const MAX_APKS_LISTED = 200;
+
+export interface ProjectApk {
+  /** Project-relative, which is what the install route takes. */
+  path: string;
+  bytes: number;
+  modifiedAt: number;
+}
+
+export async function findProjectApks(root: string): Promise<ProjectApk[]> {
+  const { readdir, stat } = await import("node:fs/promises");
+  const found: ProjectApk[] = [];
+
+  async function walk(dir: string, depth: number): Promise<void> {
+    if (depth > MAX_WALK_DEPTH || found.length >= MAX_APKS_LISTED) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (found.length >= MAX_APKS_LISTED) return;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (PRUNED_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+        await walk(full, depth + 1);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".apk")) {
+        try {
+          const s = await stat(full);
+          // Relative and "/"-separated on every OS, like every other path PPM hands the browser.
+          found.push({ path: relative(root, full).split(sep).join("/"), bytes: s.size, modifiedAt: s.mtimeMs });
+        } catch { /* it went away between the listing and the stat */ }
+      }
+    }
+  }
+
+  await walk(root, 0);
+  // Newest first: after a build, the one the user wants is the one that just appeared.
+  return found.sort((a, b) => b.modifiedAt - a.modifiedAt);
+}