@hienlh/ppm 0.23.10 → 0.23.12

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

@@ -0,0 +1,154 @@
+/**
+ * "Can this host run an Android emulator, and if not, exactly what is missing?"
+ *
+ * Every negative answer carries a reason and, where one exists, the command that fixes it. Plan
+ * §6: the empty state must distinguish no SDK, no emulator/system image, no AVD, and unusable
+ * acceleration — never an indefinite spinner.
+ */
+import { discoverSdk, resolveAvdHome, type AndroidSdk } from "./sdk-discovery.ts";
+import { listAvds } from "./avd-list.ts";
+import { workingEncoders } from "../media-transcode/ffmpeg-capabilities.ts";
+
+export interface AndroidRequirement {
+  id: string;
+  label: string;
+  met: boolean;
+  detail: string;
+  /** A command the user can run to fix it, when one exists. Never executed by PPM. */
+  fix: string | null;
+}
+
+export interface AndroidCapabilities {
+  enabled: boolean;
+  sdk: AndroidSdk;
+  avdCount: number;
+  /** H.264 encoders that really encode on this host, preference order. */
+  encoders: string[];
+  accelerationOk: boolean;
+  accelerationDetail: string;
+  requirements: AndroidRequirement[];
+  ready: boolean;
+}
+
+/**
+ * `emulator -accel-check` reports whether the host's hypervisor is usable. Without it an
+ * emulator still "starts" and then runs at a speed nobody would call working, so this is a
+ * requirement rather than a hint.
+ */
+async function checkAcceleration(emulatorPath: string | null): Promise<{ ok: boolean; detail: string }> {
+  if (!emulatorPath) return { ok: false, detail: "no emulator binary" };
+  try {
+    const proc = Bun.spawn([emulatorPath, "-accel-check"], { stdout: "pipe", stderr: "pipe", windowsHide: true });
+    const [out, errOut] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    // `-accel-check` prints a marker line, an exit code, the human-readable verdict, then the
+    // marker again — e.g. "accel:", "0", "KVM (version 12) is installed and usable.", "accel".
+    // Taking the last line yields the bare marker, so pick the sentence instead.
+    const lines = `${out}${errOut}`.split("\n").map((l) => l.trim()).filter(Boolean);
+    const sentence = lines.filter((l) => l !== "accel" && l !== "accel:" && !/^-?\d+$/.test(l))
+      .sort((a, b) => b.length - a.length)[0];
+    return { ok: code === 0, detail: sentence || (code === 0 ? "usable" : "not usable") };
+  } catch {
+    // Bun.spawn throws synchronously when the binary is missing.
+    return { ok: false, detail: "emulator binary could not be run" };
+  }
+}
+
+export async function androidCapabilities(
+  opts: { enabled: boolean; configuredSdkRoot?: string | null },
+): Promise<AndroidCapabilities> {
+  // Off — the default — answers without looking at the SDK at all. Every page load asks (the nav
+  // rail and the mobile drawer decide from `enabled` whether to show the entry), and looking runs
+  // `emulator` twice, `adb` and two JVMs (`avdmanager`, `sdkmanager`) on a host that has an SDK.
+  if (!opts.enabled) return disabledCapabilities();
+
+  const sdk = await discoverSdk(opts.configuredSdkRoot ?? null);
+  const avds = sdk.root ? listAvds(sdk.avdHome) : [];
+  const [accel, encoders] = await Promise.all([
+    checkAcceleration(sdk.emulator.path),
+    workingEncoders(),
+  ]);
+
+  const requirements: AndroidRequirement[] = [
+    {
+      id: "sdk",
+      label: "Android SDK",
+      met: !!sdk.root,
+      detail: sdk.root ? `${sdk.root} (found via ${sdk.source})` : "no SDK found",
+      fix: sdk.root ? null : "Install Android Studio, or set ANDROID_HOME to an existing SDK",
+    },
+    {
+      id: "emulator",
+      label: "Emulator",
+      met: !!sdk.emulator.path,
+      detail: sdk.emulator.version ?? "not installed",
+      fix: sdk.emulator.path ? null : "sdkmanager --install emulator",
+    },
+    {
+      id: "adb",
+      label: "adb",
+      met: !!sdk.adb.path,
+      detail: sdk.adb.version ?? "not installed",
+      fix: sdk.adb.path ? null : "sdkmanager --install platform-tools",
+    },
+    {
+      id: "acceleration",
+      label: "Hardware acceleration",
+      met: accel.ok,
+      detail: accel.detail,
+      fix: accel.ok ? null : "Enable virtualisation in the BIOS, and KVM/HAXM/Hypervisor.Framework for your OS",
+    },
+    {
+      id: "avd",
+      label: "At least one AVD",
+      met: avds.length > 0,
+      detail: avds.length ? `${avds.length} available` : "none created yet",
+      fix: avds.length ? null : "Create one in Android Studio's Device Manager, or with avdmanager",
+    },
+    {
+      id: "encoder",
+      label: "H.264 encoder",
+      met: encoders.length > 0,
+      detail: encoders.length ? encoders.join(", ") : "ffmpeg has no working H.264 encoder here",
+      fix: encoders.length ? null : "Install ffmpeg with libx264, or a VAAPI/QSV/NVENC-capable build",
+    },
+  ];
+
+  return {
+    enabled: opts.enabled,
+    sdk,
+    avdCount: avds.length,
+    encoders,
+    accelerationOk: accel.ok,
+    accelerationDetail: accel.detail,
+    requirements,
+    ready: opts.enabled && requirements.every((r) => r.met),
+  };
+}
+
+function disabledCapabilities(): AndroidCapabilities {
+  const none = { path: null, version: null };
+  const avdHome = resolveAvdHome();
+  return {
+    enabled: false,
+    sdk: {
+      root: null, source: "not-found", emulator: none, adb: none, avdmanager: none, sdkmanager: none,
+      avdHome: avdHome.dir, avdHomeFromEnv: avdHome.fromEnv,
+    },
+    avdCount: 0,
+    encoders: [],
+    accelerationOk: false,
+    accelerationDetail: "not checked while Android emulator support is off",
+    requirements: [{
+      id: "enabled",
+      label: "Android emulator support",
+      met: false,
+      detail: "off on this host: it runs emulators, so it has to be asked for",
+      fix: "Start PPM with ANDROID_EMULATOR_ENABLED=1",
+    }],
+    ready: false,
+  };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Feature switch. Android emulator support is **off by default** — unlike Remote Desktop, which
+ * ships on, because this surface spawns multi-gigabyte emulator processes on the host and most
+ * PPM installs have no Android SDK at all. `ANDROID_EMULATOR_ENABLED=1` (or `true`) turns it on.
+ *
+ * Every entry point (REST routes, WS upgrade) checks this independently rather than trusting a
+ * single call site to stay correct as routing evolves — same rule as `remote-desktop-flag.ts`.
+ */
+export function isAndroidEmulatorEnabled(): boolean {
+  const v = process.env.ANDROID_EMULATOR_ENABLED?.trim().toLowerCase();
+  return v === "1" || v === "true";
+}

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

@@ -0,0 +1,124 @@
+/**
+ * The EmulatorController gRPC channel.
+ *
+ * Two rules this file exists to enforce, both of them measured in Phase 0:
+ *
+ *  - **Never `protoLoader.loadSync()`.** It reads the .proto off disk at call time, and in a
+ *    compiled PPM that path resolves under `file:///$bunfs/root/` and throws ENOENT. The
+ *    descriptor is generated at build time (`scripts/gen-android-proto.ts`) and imported, so the
+ *    bundler embeds it. Same trap family as `bundledServerEntry` in CLAUDE.md.
+ *  - **Never dial anything but loopback.** The endpoint comes from the emulator's own discovery
+ *    file and nothing else; the browser can neither supply a gRPC URL nor name a host.
+ *
+ * grpc-js refuses call credentials on an insecure channel ("Cannot create secure credentials
+ * with an insecure channel"), so the bearer token travels as per-call metadata instead. That is
+ * safe here precisely because the channel never leaves 127.0.0.1.
+ */
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { emulatorControllerDescriptor } from "./proto/emulator-controller-descriptor.ts";
+import type { RunningEmulator } from "./emulator-discovery.ts";
+
+/** A full-resolution RGB888 frame at 1080x2400 is 7.8 MB; grpc-js caps receives at 4 MB by
+ *  default and would fail the stream with RESOURCE_EXHAUSTED without naming the size. */
+const MAX_RECEIVE_BYTES = 64 * 1024 * 1024;
+
+const DEFAULT_DEADLINE_MS = 5_000;
+
+let cachedCtor: any = null;
+
+function controllerCtor(): any {
+  if (cachedCtor) return cachedCtor;
+  const def = protoLoader.fromJSON(
+    emulatorControllerDescriptor as unknown as Parameters<typeof protoLoader.fromJSON>[0],
+    {
+      keepCase: true,
+      longs: String,
+      enums: String,
+      defaults: true,
+      oneofs: true,
+      // Buffer, not base64: the screenshot path must not pay a string round trip per frame.
+      bytes: Buffer,
+    },
+  );
+  const pkg = grpc.loadPackageDefinition(def) as any;
+  cachedCtor = pkg.android.emulation.control.EmulatorController;
+  return cachedCtor;
+}
+
+export interface EmulatorChannel {
+  readonly client: any;
+  readonly metadata: grpc.Metadata;
+  readonly target: string;
+  close(): void;
+}
+
+export function connectToEmulator(emulator: RunningEmulator): EmulatorChannel {
+  const target = `127.0.0.1:${emulator.grpcPort}`;
+  const client = new (controllerCtor())(target, grpc.credentials.createInsecure(), {
+    "grpc.max_receive_message_length": MAX_RECEIVE_BYTES,
+    // Keepalive so a wedged emulator surfaces as a broken channel instead of a silent stall.
+    "grpc.keepalive_time_ms": 20_000,
+    "grpc.keepalive_timeout_ms": 5_000,
+    "grpc.keepalive_permit_without_calls": 1,
+  });
+
+  const metadata = new grpc.Metadata();
+  if (emulator.grpcToken) metadata.set("authorization", `Bearer ${emulator.grpcToken}`);
+
+  return {
+    client,
+    metadata,
+    target,
+    close: () => grpc.closeClient(client),
+  };
+}
+
+/** One unary call with a deadline, promisified. A hung emulator can never wedge a caller. */
+export function unaryCall<T = any>(
+  channel: EmulatorChannel,
+  method: string,
+  arg: unknown = {},
+  timeoutMs = DEFAULT_DEADLINE_MS,
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const deadline = new Date(Date.now() + timeoutMs);
+    channel.client[method](arg, channel.metadata, { deadline }, (e: Error | null, res: T) => {
+      if (e) reject(e); else resolve(res);
+    });
+  });
+}
+
+export interface EmulatorStatus {
+  booted: boolean;
+  uptimeMs: number;
+  displayWidth: number | null;
+  displayHeight: number | null;
+  displayDensity: number | null;
+}
+
+function hardwareEntry(status: any, key: string): string | undefined {
+  return (status?.hardwareConfig?.entry ?? []).find((e: any) => e.key === key)?.value;
+}
+
+export async function getEmulatorStatus(channel: EmulatorChannel): Promise<EmulatorStatus> {
+  const s = await unaryCall(channel, "getStatus");
+  const num = (k: string) => {
+    const v = Number(hardwareEntry(s, k));
+    return Number.isFinite(v) && v > 0 ? v : null;
+  };
+  return {
+    booted: !!s.booted,
+    uptimeMs: Number(s.uptime ?? 0),
+    displayWidth: num("hw.lcd.width"),
+    displayHeight: num("hw.lcd.height"),
+    displayDensity: num("hw.lcd.density"),
+  };
+}
+
+/** Ask the VM to shut down. Graceful: measured, the process is gone in 1-3 seconds, so nothing
+ *  here ever needs to signal a pid — and never by process *name*, which on this very host
+ *  matches Docker Desktop's qemu. */
+export async function requestShutdown(channel: EmulatorChannel, timeoutMs = 10_000): Promise<void> {
+  await unaryCall(channel, "setVmState", { state: "SHUTDOWN" }, timeoutMs);
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Turning viewer gestures into emulator input.
+ *
+ * The one rule that shapes this file: **`sendKey.text` carries printable ASCII [32,127) and
+ * nothing else.** Measured in Phase 0 — `"café"` arrives as `"caf"`, and Vietnamese, emoji and
+ * CJK vanish entirely, with no error and no log. So text is split: ASCII goes through `text`,
+ * and everything else goes through the clipboard plus a paste combo, which was verified to
+ * carry `"Tiếng Việt 😀"` intact into the guest.
+ */
+import { unaryCall, type EmulatorChannel } from "./android-grpc.ts";
+import type { AndroidTouchPoint } from "../../shared/android-protocol.ts";
+
+/** The emulator accepts at most this many simultaneous contacts. */
+export const MAX_TOUCH_POINTS = 10;
+
+export function isInjectableAscii(text: string): boolean {
+  for (const ch of text) {
+    const code = ch.codePointAt(0)!;
+    if (code < 32 || code >= 127) return false;
+  }
+  return true;
+}
+
+/**
+ * Send one touch update.
+ *
+ * `pressure: 0` is how a finger is released, and it is mandatory: the proto states an identifier
+ * that never sees zero is not unregistered. The emulator does expire a slot on its own, but only
+ * after 120 seconds — far too long to rely on, which is why the session has its own release path.
+ */
+export async function sendTouch(channel: EmulatorChannel, touches: AndroidTouchPoint[]): Promise<void> {
+  const clamped = touches.slice(0, MAX_TOUCH_POINTS).map((t) => ({
+    x: Math.round(t.x),
+    y: Math.round(t.y),
+    identifier: Math.max(0, Math.round(t.id)),
+    pressure: t.pressure > 0 ? Math.max(1, Math.round(t.pressure)) : 0,
+  }));
+  await unaryCall(channel, "sendTouch", { touches: clamped }, 2000);
+}
+
+/** Release every contact. Called on blur, tab hide, lost control and disconnect. */
+export async function releaseAllTouches(channel: EmulatorChannel): Promise<void> {
+  const release = Array.from({ length: MAX_TOUCH_POINTS }, (_, i) => ({
+    x: 0, y: 0, identifier: i, pressure: 0,
+  }));
+  await unaryCall(channel, "sendTouch", { touches: release }, 2000);
+}
+
+/** The w3c `KeyboardEvent.key` values the emulator maps to Android's own buttons. */
+const HARDWARE_KEYS = {
+  home: "GoHome",
+  back: "GoBack",
+  recent: "AppSwitch",
+  power: "Power",
+  "volume-up": "AudioVolumeUp",
+  "volume-down": "AudioVolumeDown",
+} as const;
+
+export type HardwareKey = keyof typeof HARDWARE_KEYS;
+
+export async function sendHardwareKey(channel: EmulatorChannel, key: HardwareKey): Promise<void> {
+  await unaryCall(channel, "sendKey", { key: HARDWARE_KEYS[key], eventType: "keypress" }, 2000);
+}
+
+/** `key` takes the browser's own `KeyboardEvent.key` value — the proto follows the w3c list. */
+export async function sendKey(
+  channel: EmulatorChannel,
+  key: string,
+  action: "down" | "up" | "press",
+): Promise<void> {
+  const eventType = action === "down" ? "keydown" : action === "up" ? "keyup" : "keypress";
+  await unaryCall(channel, "sendKey", { key, eventType }, 2000);
+}
+
+/** ASCII only — the caller must have checked. Anything else is silently dropped by the emulator. */
+export async function sendAsciiText(channel: EmulatorChannel, text: string): Promise<void> {
+  // The proto warns the keyboard buffer can be overrun by >1 KB at a time, and points at the
+  // clipboard for bulk text. Chunking keeps ordinary typing on this path either way.
+  for (let i = 0; i < text.length; i += 256) {
+    await unaryCall(channel, "sendKey", { text: text.slice(i, i + 256) }, 3000);
+  }
+}
+
+/**
+ * The path for anything not ASCII: put it on the guest clipboard and paste.
+ *
+ * Verified end to end in Phase 0 — `setClipboard` carried `"Tiếng Việt 😀"` into the guest
+ * exactly, confirmed both by reading it back and by Android's own paste suggestion rendering it.
+ */
+export async function pasteText(channel: EmulatorChannel, text: string): Promise<void> {
+  await unaryCall(channel, "setClipboard", { text }, 3000);
+  await unaryCall(channel, "sendKey", { key: "Control", eventType: "keydown" }, 2000);
+  await unaryCall(channel, "sendKey", { key: "v", eventType: "keypress" }, 2000);
+  await unaryCall(channel, "sendKey", { key: "Control", eventType: "keyup" }, 2000);
+}
+
+/** Send text by whichever path can actually carry it. */
+export async function sendText(channel: EmulatorChannel, text: string): Promise<"typed" | "pasted"> {
+  if (isInjectableAscii(text)) {
+    await sendAsciiText(channel, text);
+    return "typed";
+  }
+  await pasteText(channel, text);
+  return "pasted";
+}
+
+/**
+ * Rotate the guest.
+ *
+ * `setPhysicalModel` with `ROTATION` takes three angles in degrees as [x, y, z], and the proto's
+ * own `Rotation.SkinRotation` enum names what each z angle means: PORTRAIT 0, LANDSCAPE 90,
+ * REVERSE_PORTRAIT -180, REVERSE_LANDSCAPE -90. So 270 is sent as **-90**, not 270 — the proto
+ * documents the angle as being in [-180, 180] and a value outside it has no defined meaning.
+ *
+ * Nothing here tracks the resulting orientation: every screenshot frame carries the emulator's
+ * own `format.rotation`, which is the authority (see `android-video.ts`).
+ */
+export async function setRotation(channel: EmulatorChannel, degrees: 0 | 90 | 180 | 270): Promise<void> {
+  const z = degrees === 270 ? -90 : degrees;
+  await unaryCall(channel, "setPhysicalModel", {
+    target: "ROTATION",
+    value: { data: [0, 0, z] },
+  }, 3000);
+}
+
+export async function getClipboard(channel: EmulatorChannel): Promise<string> {
+  const res = await unaryCall(channel, "getClipboard", {}, 3000);
+  return typeof res?.text === "string" ? res.text : "";
+}

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

@@ -0,0 +1,169 @@
+/**
+ * Per-device logcat: one gRPC stream, many watchers, a bounded ring buffer and nothing on disk.
+ *
+ * Plan §Phase 3 is specific about the shape: filter, pause, clear-view and a ring buffer, with
+ * **nothing written to the database**. So this holds a fixed number of entries in memory and
+ * hands a new watcher that backlog; filtering, pausing and clearing the view are the client's,
+ * because all three are about what one person is looking at, not about what the device said.
+ *
+ * ## `sort: Parsed` does not work, and fails by being silently empty
+ *
+ * The proto offers `LogMessage.LogType.Parsed`, which would deliver `LogcatEntry` records with
+ * level, tag, pid and tid already separated — exactly what this file wants. Measured against
+ * emulator **36.5.10.0** it is not implemented:
+ *
+ *  - `streamLogcat({sort: "Parsed"})` → **334 messages in 8 seconds, every one of them with an
+ *    empty `entries` list AND an empty `contents` string**, each echoing `sort: Text` back. Not
+ *    an error, not `UNIMPLEMENTED`: a busy stream of nothing, which reads exactly like a device
+ *    that is not logging.
+ *  - The same with the numeric enum value (`sort: 1`) — 57 empty messages in 8 seconds.
+ *  - `streamLogcat({})` — the default, `Text` — delivers the real log.
+ *  - The deprecated unary `getLogcat` answers **12 UNIMPLEMENTED** outright, so there is no
+ *    snapshot RPC either; the ring buffer is the only backlog there is.
+ *
+ * So the lines are parsed here. Two more measured details that shape the parser: each gRPC
+ * message carries **exactly one line** with **no trailing newline** (so nothing has to buffer a
+ * partial line across messages — though the split still handles it, since a future build
+ * batching lines would otherwise silently concatenate them into one entry), and the format is
+ * logcat's `threadtime`, which carries no year.
+ */
+import type { EmulatorChannel } from "./android-grpc.ts";
+import type { AndroidLogEntry, AndroidLogLevel } from "../../shared/android-protocol.ts";
+
+/** Enough to scroll back through a crash, far too little to be a storage decision. */
+export const LOGCAT_RING_SIZE = 2_000;
+
+/** logcat's one-letter levels. `A` is assert, which Android also calls FATAL. */
+const LEVELS: Record<string, AndroidLogLevel> = {
+  V: "verbose", D: "debug", I: "info", W: "warn", E: "error", F: "fatal", A: "fatal", S: "verbose",
+};
+
+/** `MM-DD HH:MM:SS.mmm  PID  TID L TAG: message` — logcat's `threadtime`, which is the default. */
+const THREADTIME = /^(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})\.(\d{3})\s+(\d+)\s+(\d+)\s+([A-Z])\s+([^:]*?)\s*:\s?(.*)$/;
+
+/**
+ * Turn one logcat line into an entry.
+ *
+ * A line that does not parse is **kept**, not dropped: it is a continuation of the line above
+ * (a stack trace written with embedded newlines) or a banner like `--------- beginning of main`,
+ * and losing either would quietly cut a crash in half. It gets no level and no tag rather than
+ * an invented one.
+ */
+export function parseLogcatLine(line: string, id: number, now = new Date()): AndroidLogEntry | null {
+  if (line.length === 0) return null;
+  const m = THREADTIME.exec(line);
+  if (!m) return { id, timestamp: now.getTime(), pid: 0, tid: 0, level: "verbose", tag: "", message: line };
+
+  const [, mo, day, hh, mm, ss, ms, pid, tid, level, tag, message] = m;
+  // threadtime has no year. Assume this one, and step back if that puts the line in the future
+  // by more than a day — which is what reading a December log on January 1st looks like.
+  let at = new Date(now.getFullYear(), Number(mo) - 1, Number(day), Number(hh), Number(mm), Number(ss), Number(ms));
+  if (at.getTime() - now.getTime() > 24 * 60 * 60_000) at = new Date(at.getTime() - 365 * 24 * 60 * 60_000);
+
+  return {
+    id,
+    timestamp: at.getTime(),
+    pid: Number(pid),
+    tid: Number(tid),
+    level: LEVELS[level!] ?? "verbose",
+    tag: tag ?? "",
+    message: message ?? "",
+  };
+}
+
+export type LogcatListener = (entries: AndroidLogEntry[]) => void;
+
+interface DeviceLogcat {
+  channel: EmulatorChannel;
+  /** The live gRPC stream, or null while nobody is watching. */
+  call: any;
+  ring: AndroidLogEntry[];
+  listeners: Set<LogcatListener>;
+  nextId: number;
+}
+
+const streams = new Map<string, DeviceLogcat>();
+
+/**
+ * Start watching a device's logcat.
+ *
+ * The channel is the caller's and is NOT closed here: it belongs to the session, which may still
+ * be sending input on it long after the log panel is closed.
+ */
+export function subscribeLogcat(
+  deviceId: string,
+  channel: EmulatorChannel,
+  listener: LogcatListener,
+): () => void {
+  let stream = streams.get(deviceId);
+  if (!stream) {
+    stream = { channel, call: null, ring: [], listeners: new Set(), nextId: 1 };
+    streams.set(deviceId, stream);
+  }
+  // A session that reconnected has a new channel; the ring belongs to the device, not to it.
+  stream.channel = channel;
+  if (!stream.call) openStream(deviceId, stream);
+  stream.listeners.add(listener);
+  // Hand over what has already been said, so opening the panel does not show an empty box on a
+  // device that has been running for an hour.
+  if (stream.ring.length > 0) listener([...stream.ring]);
+
+  return () => {
+    const s = streams.get(deviceId);
+    if (!s) return;
+    s.listeners.delete(listener);
+    // Plan gate: "logs hidden ngừng subscription". Nobody watching means nothing streaming.
+    if (s.listeners.size === 0) closeStream(deviceId);
+  };
+}
+
+function openStream(deviceId: string, stream: DeviceLogcat): void {
+  // No `sort` field: the default is Text, and Parsed is the empty-stream trap described above.
+  const call = stream.channel.client.streamLogcat({}, stream.channel.metadata);
+  stream.call = call;
+  call.on("data", (msg: any) => {
+    const contents: string = msg?.contents ?? "";
+    if (contents.length === 0) return;
+    const entries: AndroidLogEntry[] = [];
+    for (const line of contents.split("\n")) {
+      const entry = parseLogcatLine(line.replace(/\r$/, ""), stream.nextId);
+      if (entry) { stream.nextId++; entries.push(entry); }
+    }
+    if (entries.length === 0) return;
+    stream.ring.push(...entries);
+    if (stream.ring.length > LOGCAT_RING_SIZE) {
+      stream.ring.splice(0, stream.ring.length - LOGCAT_RING_SIZE);
+    }
+    for (const l of stream.listeners) l(entries);
+  });
+  call.on("error", (e: any) => {
+    // code 1 is CANCELLED, which is how the last watcher leaving ends it.
+    if (e?.code !== 1) console.warn(`[android] logcat stream for ${deviceId} failed: ${e?.details ?? e?.message ?? e}`);
+  });
+}
+
+/**
+ * Stop the gRPC stream but **keep the ring**.
+ *
+ * The plan's gate is that hiding the log stops the subscription, which this does. Throwing the
+ * backlog away as well is a different thing and a worse one: closing the panel to read a stack
+ * trace on another screen and reopening it would show an empty box. The cost is that a reopened
+ * panel has a gap where nothing was being watched — the timestamps say so.
+ */
+function closeStream(deviceId: string): void {
+  const stream = streams.get(deviceId);
+  if (!stream?.call) return;
+  try { stream.call.cancel(); } catch { /* already gone */ }
+  stream.call = null;
+}
+
+/** Tear everything down for a device — the session closing, or the emulator stopping. */
+export function closeDeviceLogcat(deviceId: string): void {
+  closeStream(deviceId);
+  streams.delete(deviceId);
+}
+
+/** What a watcher would be handed right now. Exposed for tests and for a snapshot download. */
+export function logcatBacklog(deviceId: string): AndroidLogEntry[] {
+  return [...(streams.get(deviceId)?.ring ?? [])];
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Single-use, short-lived nonces for `/ws/android`.
+ *
+ * The coarse PPM token already travels as `?token=` on every WS URL and proves only "holds the
+ * one reusable app token". A session that hands over touch and keyboard control of a running
+ * VM needs more than that, so `POST /api/android/devices/:id/sessions` mints a nonce that must
+ * be the client's *first* WS message and can be spent exactly once.
+ */
+const TTL_MS = 30_000;
+const MAX_OUTSTANDING = 32;
+
+interface Nonce {
+  value: string;
+  deviceId: string;
+  expiresAt: number;
+}
+
+const outstanding = new Map<string, Nonce>();
+
+function sweep(): void {
+  const now = Date.now();
+  for (const [k, n] of outstanding) if (n.expiresAt <= now) outstanding.delete(k);
+  // A client that mints and never connects must not be able to grow this without bound.
+  while (outstanding.size > MAX_OUTSTANDING) {
+    const oldest = [...outstanding.values()].sort((a, b) => a.expiresAt - b.expiresAt)[0];
+    if (!oldest) break;
+    outstanding.delete(oldest.value);
+  }
+}
+
+export function mintAndroidNonce(deviceId: string): string {
+  sweep();
+  const value = crypto.randomUUID().replace(/-/g, "");
+  outstanding.set(value, { value, deviceId, expiresAt: Date.now() + TTL_MS });
+  return value;
+}
+
+/** Spend a nonce. Returns the device it was minted for, or null if unknown/expired/already used. */
+export function consumeAndroidNonce(value: string): string | null {
+  sweep();
+  const n = outstanding.get(value);
+  if (!n) return null;
+  outstanding.delete(value);          // single use, even if the rest of the handshake fails
+  return n.expiresAt > Date.now() ? n.deviceId : null;
+}
+
+/** Revoke everything — used when the PPM token changes or auth is turned off. */
+export function revokeAllAndroidNonces(): void {
+  outstanding.clear();
+}