@hienlh/ppm 0.21.0 → 0.22.0

package/src/services/jsonl-transcript-parser.ts

@@ -10,7 +10,45 @@ import type { ChatEvent, ChatMessage } from "../types/chat.ts";
 import { stringifyToolResultContent } from "../shared/tool-result-content.ts";
 import { stripSharedContext } from "../shared/provider-context.ts";
 
-const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
+/**
+ * How large a transcript this module will look at, for the callers that go
+ * through `validateJsonlPath`.
+ *
+ * It was 50MB and it silently killed the whole expand-compact path for exactly
+ * the sessions that need it — a transcript with thirteen compactions in it had
+ * reached 77MB, so scrolling to the top of that chat answered 403 and loaded
+ * nothing, forever.
+ *
+ * It is a sanity bound and not a memory bound, and it is worth being exact
+ * about why, because the obvious reading is wrong. Measured on this repo's own
+ * 88.6MB transcript: the reader streams, the parsed array retains **11.1MB**
+ * (6974 messages, no single string over 200KB) — and RSS still rises by 355MB.
+ * That is `JSON.parse` garbage, not live objects: `Bun.gc(true)` does not give
+ * it back and neither does dropping the array, because the allocator keeps the
+ * pages. It also does not accumulate — four transcripts of 89/83/55/48MB in a
+ * row plateau at 390–466MB rather than summing — so the cost of reading one of
+ * these is a one-time high-water mark, reusable by the next.
+ *
+ * The number that actually bounds memory is therefore the *file* size, at about
+ * 4.3× transiently, which is what `FULL_PARSE_MAX_BYTES` below is for.
+ */
+const MAX_FILE_SIZE = 256 * 1024 * 1024; // 256MB
+
+/**
+ * How many bytes a *whole-history* parse may read.
+ *
+ * `validateJsonlPath`'s bound never applied here: the search indexer reaches
+ * `parseJsonlTranscript` through `getFullMessages`, which does no validation at
+ * all, and it asks for every segment rather than one. At the measured 4.3×
+ * transient cost that is ~550MB of allocator growth at this bound, and nothing
+ * above it — a bigger transcript is read from `fullParseWindow` onwards
+ * instead of whole, so the cost stops rising with the file.
+ *
+ * Set above the largest transcript on this machine (88.8MB of 1666) with room
+ * to spare, so the windowing is for the pathological case and not for the
+ * sessions this file's history is about.
+ */
+export const FULL_PARSE_MAX_BYTES = 128 * 1024 * 1024; // 128MB
 const TEAMMATE_MSG_RE = /<teammate-message[^>]*>[\s\S]*?<\/teammate-message>/g;
 
 /** Strip SDK teammate-message XML tags from assistant text */
@@ -197,11 +235,41 @@ export function nestChildEventsAcrossMessages(messages: { content: string; event
   }
 }
 
+/**
+ * How much of a transcript's tail a whole-history parse may read, as a byte
+ * offset to start at. `0` means the file is small enough to read entirely.
+ *
+ * A window rather than a refusal, because refusing is not the mitigation it
+ * looks like: `getFullMessages` falls back to the SDK's own walk, and that
+ * reads the same file — measured 3.1s on a 128MB fixture the guard had just
+ * declined to open. It also leaves the session unsearchable, which is the
+ * opposite of what the indexer was widened to do. Reading the tail bounds the
+ * work at `maxBytes` and indexes the newest part of the session, which is the
+ * part a search is most likely reaching for.
+ *
+ * Answers on `stat` alone, never by opening the file: the caller asks this once
+ * per stale session. A file that has vanished reads as `0` — let the parse
+ * report that in its own words rather than inventing a window into nothing.
+ */
+export function fullParseWindow(filePath: string, maxBytes: number = FULL_PARSE_MAX_BYTES): number {
+  try {
+    const { size } = statSync(filePath);
+    return size > maxBytes ? size - maxBytes : 0;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * Validate JSONL path — must be under ~/.claude/ (prevents arbitrary file reads).
  * Throws Error with descriptive message. Returns resolved realpath on success.
+ *
+ * `maxBytes` is a parameter only so a test can assert the boundary against a
+ * one-byte-over fixture: a real 256MB transcript is not worth committing, and a
+ * bound asserted nowhere is how this one came to say 50MB while rejecting at a
+ * different number.
  */
-export function validateJsonlPath(inputPath: string): string {
+export function validateJsonlPath(inputPath: string, maxBytes = MAX_FILE_SIZE): string {
   if (!inputPath) throw new Error("jsonlPath is required");
   // Reject obvious traversal attempts before resolution
   if (inputPath.includes("\0")) throw new Error("Invalid path: denied");
@@ -227,16 +295,70 @@ export function validateJsonlPath(inputPath: string): string {
 
   const stat = statSync(real);
   if (!stat.isFile()) throw new Error("Not a regular file");
-  if (stat.size > MAX_FILE_SIZE) {
-    throw new Error(`File too large: ${Math.round(stat.size / 1024 / 1024)}MB exceeds 50MB limit`);
+  // Interpolated, never spelled out: the literal "50MB" outlived the 50MB cap
+  // and sent the next reader looking in the wrong place for a file that was
+  // rejected at 256MB.
+  if (stat.size > maxBytes) {
+    throw new Error(
+      `File too large: ${Math.round(stat.size / 1024 / 1024)}MB exceeds ` +
+      `${Math.round(maxBytes / 1024 / 1024)}MB limit`,
+    );
   }
   return real;
 }
 
+/**
+ * Yield a file's lines without holding the file in memory.
+ *
+ * `Bun.file().text()` plus `split("\n")` costs the whole transcript twice over —
+ * 277MB resident for a 77MB file, which is what forced a cap low enough to
+ * reject real sessions. Peak here is one chunk plus one line.
+ */
+async function* readLines(filePath: string, fromByte = 0): AsyncGenerator<string> {
+  const decoder = new TextDecoder();
+  // Explicit reader rather than `for await` over the stream: the DOM lib's
+  // ReadableStream is not typed as async-iterable, and the `finally` is what
+  // releases it when a caller breaks early on `beforeUuid`.
+  // One byte *before* the offset, so the first line the split produces is
+  // always the tail of the record the offset fell inside — the empty string
+  // when it fell exactly on a newline. That makes the drop below unconditional
+  // instead of a boundary case, and a boundary case here silently costs a whole
+  // record rather than a fragment.
+  const file = fromByte > 0 ? Bun.file(filePath).slice(fromByte - 1) : Bun.file(filePath);
+  const reader = file.stream().getReader();
+  // A fragment is not always unparseable — the tail of one record is sometimes
+  // a complete smaller document — so it has to go by position rather than be
+  // left for `JSON.parse` to reject, or it enters as an invented message.
+  let dropPartial = fromByte > 0;
+  let buffered = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      const lines = buffered.split("\n");
+      buffered = lines.pop() ?? "";
+      for (const line of lines) {
+        if (dropPartial) { dropPartial = false; continue; }
+        yield line;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  buffered += decoder.decode();
+  if (buffered && !dropPartial) yield buffered;
+}
+
 /**
  * Read a JSONL transcript file, parse entries, apply merge/nest pipeline, return ChatMessage[].
  * Applies the same logic as ClaudeAgentSdkProvider.getMessages() but reads from file directly.
  *
+ * @param opts.oneSegment  Return only the stretch since the previous compaction,
+ *                    rather than everything before `beforeUuid`.
+ * @param opts.fromByte  Start reading at this offset instead of at the start,
+ *                    dropping the partial record it lands in. `fullParseWindow`
+ *                    is what computes it; nothing else should.
  * @param beforeUuid  If provided, stop parsing at the line with this uuid (exclusive).
  *                    Used for the expand-compact feature: Claude's compact summary references
  *                    the CURRENT session file (pre+summary+post), so we truncate at the
@@ -245,10 +367,10 @@ export function validateJsonlPath(inputPath: string): string {
 export async function parseJsonlTranscript(
   filePath: string,
   beforeUuid?: string,
+  opts?: { oneSegment?: boolean; fromByte?: number },
 ): Promise<ChatMessage[]> {
-  const text = await Bun.file(filePath).text();
   const parsed: ChatMessage[] = [];
-  for (const line of text.split("\n")) {
+  for await (const line of readLines(filePath, opts?.fromByte ?? 0)) {
     const trimmed = line.trim();
     if (!trimmed) continue;
     let entry: any;
@@ -258,6 +380,16 @@ export async function parseJsonlTranscript(
       continue; // skip malformed lines defensively
     }
     if (beforeUuid && entry.uuid === beforeUuid) break; // stop at compact boundary (exclusive)
+    // One segment only: drop everything collected so far each time another
+    // compaction is passed, so what survives is the stretch between the last
+    // compaction and `beforeUuid`. Without this a single expand answers with
+    // the whole history before the boundary — 5626 messages on a session with
+    // thirteen compactions, prepended into a view already carrying 3553 DOM
+    // nodes. The summary that resets it is itself a `user` record, so it is
+    // pushed straight back and becomes the segment's first message — which is
+    // what carries the transcript path, and therefore what lets the next
+    // scroll expand the segment before it.
+    if (opts?.oneSegment && entry.isCompactSummary) parsed.length = 0;
     if (entry.type !== "user" && entry.type !== "assistant") continue;
     if (!entry.uuid || !entry.message) continue;
     parsed.push(parseSessionMessage(entry));

package/src/services/log-rotate.ts

@@ -0,0 +1,142 @@
+/**
+ * Keeping `ppm.log` bounded, and keeping one line out of it twice.
+ *
+ * Two separate defects sat in the same file. On this machine it had reached
+ * **276 MB / 1,395,012 lines**, and of those only 532,792 carried the
+ * `[timestamp] [LEVEL]` prefix — the other 862,220 (62%) were the *same events*
+ * arriving by a second route.
+ *
+ * The second route is `supervisor.ts` spawning the server with
+ * `stdio: ["ignore", logFd, logFd]`, where `logFd` is `ppm.log` itself. So the
+ * server's own `console.log` already lands in the log through fd 1, and
+ * `setupLogFile()` then appends a formatted copy of the same line. That is the
+ * duplication — and it is not a harmless one, because only the appended copy
+ * goes through `redactSecrets()`. The raw stdout copy does not, which is how
+ * two lines matching `Token: <value>` are sitting in the log right now. The
+ * redaction was never wrong; it only ever covered one of the two doors.
+ *
+ * `fdWritesTo` is how a writer notices that its own stdout already reaches the
+ * file it was about to append to, so it can stop doing one of the two.
+ */
+
+import { fstatSync, statSync, copyFileSync, truncateSync, renameSync, rmSync, existsSync } from "node:fs";
+
+/** Rotate once the log passes this. */
+export const MAX_LOG_BYTES = 20 * 1024 * 1024;
+
+/** How many previous logs to keep (`ppm.log.1` … `ppm.log.3`). */
+export const LOG_GENERATIONS = 3;
+
+/**
+ * Set by the supervisor on any child it hands `stdio: [\"ignore\", logFd, logFd]`.
+ *
+ * The inode comparison below cannot answer that question on Windows: `fstat` reports an inode
+ * of 0 for most handles there, so `fdWritesTo` says "not the same file" and both writers keep
+ * writing — which means the duplicate, **unredacted** stdout copy this module exists to remove
+ * was still being written on the one platform PPM is most often installed on. Detection cannot
+ * be made to work there, but the process doing the wiring knows for certain, so it says so.
+ */
+export const STDIO_IS_LOG_ENV = "PPM_STDIO_IS_LOG";
+
+/**
+ * Whether console output on `fd` already reaches `filePath` — by what the spawner declared,
+ * or, for a process nobody declared anything to, by inode.
+ */
+export function stdioIsLogFile(fd: number, filePath: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return env[STDIO_IS_LOG_ENV] === "1" || fdWritesTo(fd, filePath);
+}
+
+/**
+ * Drop the marker once it has been read.
+ *
+ * It is inherited like any other variable, and PPM spawns terminals, SDK children and
+ * `ppm` CLI invocations with its own environment — every one of which would otherwise start
+ * life believing its stdout is the log file and silently drop it.
+ */
+export function consumeStdioIsLogEnv(env: NodeJS.ProcessEnv = process.env): void {
+  delete env[STDIO_IS_LOG_ENV];
+}
+
+/**
+ * Whether writing to `fd` lands in `filePath` — same inode, same device.
+ *
+ * Answers "is my stdout already this log file?" for a process the supervisor did not label.
+ *
+ * Returns false whenever it cannot be sure, which on Windows is always — see
+ * `STDIO_IS_LOG_ENV`, which is how the supervisor's children get a real answer there.
+ */
+export function fdWritesTo(fd: number, filePath: string): boolean {
+  try {
+    const a = fstatSync(fd);
+    if (a.ino === 0) return false;
+    const b = statSync(filePath);
+    return a.ino === b.ino && a.dev === b.dev;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Truncate the log in place once it is oversized, keeping N previous copies.
+ *
+ * In place, and that is the whole design constraint: both the supervisor and
+ * the server child hold file descriptors opened on this inode with `O_APPEND`.
+ * Renaming the file would leave every one of those descriptors writing into the
+ * renamed file for the rest of the process's life — the log would appear to
+ * rotate and then never grow again, while `ppm.log.1` quietly became the real
+ * log. Copying the contents out and truncating the original keeps the inode,
+ * so an `O_APPEND` writer simply resumes at offset 0.
+ *
+ * The cost is the one `logrotate` calls `copytruncate` and accepts for the same
+ * reason: a line written between the copy and the truncate is lost. The window
+ * is a few milliseconds, once per `maxBytes` of log.
+ *
+ * Returns whether it rotated.
+ */
+export function rotateIfOversized(
+  filePath: string,
+  maxBytes: number = MAX_LOG_BYTES,
+  generations: number = LOG_GENERATIONS,
+): boolean {
+  let size: number;
+  try {
+    size = statSync(filePath).size;
+  } catch {
+    return false; // no log yet
+  }
+  if (size <= maxBytes) return false;
+
+  try {
+    // Oldest first, or a shift would overwrite the generation it is about to move.
+    rmSync(`${filePath}.${generations}`, { force: true });
+    for (let i = generations - 1; i >= 1; i--) {
+      const from = `${filePath}.${i}`;
+      if (existsSync(from)) renameSync(from, `${filePath}.${i + 1}`);
+    }
+    copyFileSync(filePath, `${filePath}.1`);
+    truncateSync(filePath, 0);
+    return true;
+  } catch (e) {
+    // A log that cannot be rotated must not take the process with it — but it must not do so
+    // in silence either. `truncateSync` on a file the supervisor and the server child both
+    // hold open fails with EBUSY on Windows, and a blanket `catch` turned "this log is
+    // unbounded from here on" into no signal at all. Once per process, because the caller is
+    // a one-minute timer and the second failure says nothing the first did not.
+    if (!rotateFailureReported) {
+      rotateFailureReported = true;
+      console.warn(
+        `[log-rotate] Could not rotate ${filePath} (${(e as Error).message}) — it will keep `
+        + "growing past its cap. On Windows this is usually another process holding the file open.",
+      );
+    }
+    return false;
+  }
+}
+
+/** One warning per process; see the `catch` above. Exported for tests, which need to be able
+ *  to observe the *first* failure rather than whichever one happens to run first. */
+export function resetRotateFailureWarning(): void {
+  rotateFailureReported = false;
+}
+
+let rotateFailureReported = false;

package/src/services/media-transcode/ffmpeg-capabilities.ts

@@ -16,6 +16,7 @@
  * grepping `ffmpeg -encoders`: the list only says the build was compiled with
  * NVENC/QSV support, not that a compatible GPU/driver is present.
  */
+import { readdirSync } from "node:fs";
 
 export interface FfmpegCapabilities {
   ffmpeg: string | null;
@@ -29,10 +30,38 @@ function encoderCandidates(): string[] {
   switch (process.platform) {
     case "win32": return ["h264_nvenc", "h264_qsv", "h264_amf", "libx264"];
     case "darwin": return ["h264_videotoolbox", "libx264"];
-    default: return ["h264_nvenc", "h264_qsv", "libx264"];
+    // VAAPI sits after QSV (Intel does better through QSV) but before libx264, because it is
+    // the only hardware H.264 path an AMD Linux host has — `h264_amf` is Windows-only, so
+    // without VAAPI every Radeon machine fell all the way back to software encoding.
+    default: return ["h264_nvenc", "h264_qsv", "h264_vaapi", "libx264"];
   }
 }
 
+/** The DRM render node VAAPI should use, or null when the host exposes none (no GPU driver,
+ *  a container without `/dev/dri`). Picks the lowest `renderD*` rather than hardcoding
+ *  `renderD128`: it is only the first node by convention and a host whose first GPU is not
+ *  render-capable starts at `renderD129`. */
+function vaapiRenderNode(): string | null {
+  try {
+    const nodes = readdirSync("/dev/dri").filter((n) => n.startsWith("renderD")).sort();
+    return nodes[0] ? `/dev/dri/${nodes[0]}` : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Args VAAPI needs *before* `-i` (it opens the device during input setup), empty for every
+ *  other encoder. Separate from `encoderArgs` because argv position matters here. */
+export function encoderDeviceArgs(encoder: string): string[] {
+  if (encoder !== "h264_vaapi") return [];
+  const node = vaapiRenderNode();
+  return node ? ["-vaapi_device", node] : [];
+}
+
+/** VAAPI encodes from GPU-resident frames, so the chain has to convert and upload first.
+ *  Callers that build their own `-vf` must append this rather than passing a second `-vf`. */
+export const VAAPI_UPLOAD_FILTER = "format=nv12,hwupload";
+
 /** Per-encoder quality/speed flags tuned for "watch a file inside the IDE" latency. */
 export function encoderArgs(encoder: string): string[] {
   switch (encoder) {
@@ -40,6 +69,8 @@ export function encoderArgs(encoder: string): string[] {
     case "h264_qsv": return ["-c:v", "h264_qsv", "-preset", "veryfast", "-global_quality", "26"];
     case "h264_amf": return ["-c:v", "h264_amf", "-quality", "speed", "-rc", "cqp", "-qp_i", "24", "-qp_p", "26"];
     case "h264_videotoolbox": return ["-c:v", "h264_videotoolbox", "-b:v", "6M", "-realtime", "1"];
+    // No `-crf`/`-global_quality`: VAAPI's rate control is `-qp` on this encoder.
+    case "h264_vaapi": return ["-c:v", "h264_vaapi", "-qp", "26"];
     default: return ["-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-maxrate", "8M", "-bufsize", "16M"];
   }
 }
@@ -50,8 +81,12 @@ async function encoderWorks(ffmpeg: string, encoder: string): Promise<boolean> {
       [
         ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
         // 256px: hardware encoders reject frames below ~145×49 (NVENC "Frame Dimension less than minimum").
+        ...encoderDeviceArgs(encoder),
         "-f", "lavfi", "-i", "color=c=black:s=256x256:r=30:d=0.2",
-        "-frames:v", "3", "-pix_fmt", "yuv420p", ...encoderArgs(encoder),
+        "-frames:v", "3",
+        // VAAPI wants hardware frames and rejects a software `-pix_fmt` on the output.
+        ...(encoder === "h264_vaapi" ? ["-vf", VAAPI_UPLOAD_FILTER] : ["-pix_fmt", "yuv420p"]),
+        ...encoderArgs(encoder),
         "-f", "null", "-",
       ],
       { stdout: "ignore", stderr: "ignore", stdin: "ignore" },
@@ -124,7 +159,42 @@ export function getFfmpegCapabilities(): Promise<FfmpegCapabilities> {
   return cached;
 }
 
+let cachedWorking: Promise<string[]> | null = null;
+
+/**
+ * **Every** candidate encoder that actually encodes on this host, in preference order — not
+ * just the first one, which is what `getFfmpegCapabilities().encoder` stops at.
+ *
+ * Separate call, and separately cached, on purpose: `detect()` short-circuits because playing a
+ * video inside the IDE has no use for the also-works list, and probing the rest costs one real
+ * encode each (plus a 10s timeout apiece against a hung driver). Only the remote-desktop codec
+ * picker wants the full list, so only it pays.
+ */
+export function workingEncoders(): Promise<string[]> {
+  if (!cachedWorking) {
+    cachedWorking = (async () => {
+      const { ffmpeg } = await getFfmpegCapabilities();
+      if (!ffmpeg) return [];
+      const found: string[] = [];
+      for (const candidate of encoderCandidates()) {
+        if (await encoderWorks(ffmpeg, candidate)) found.push(candidate);
+      }
+      return found;
+    })().then((list) => {
+      // An empty list means either no ffmpeg or no working encoder; both are conditions the
+      // user can fix from the checklist, so neither is remembered.
+      if (list.length === 0) cachedWorking = null;
+      return list;
+    }).catch((e) => {
+      cachedWorking = null;
+      throw e;
+    });
+  }
+  return cachedWorking;
+}
+
 /** Test hook: drop the cache so a different PATH can be probed. */
 export function resetFfmpegCapabilitiesCache(): void {
   cached = null;
+  cachedWorking = null;
 }

package/src/services/remote-desktop/remote-desktop-audio.ts

@@ -0,0 +1,193 @@
+/**
+ * Host audio → client: one ffmpeg per session capturing what the host is *playing* (not its
+ * microphone) and encoding it as Opus in Ogg, which `remote-desktop-ogg-opus.ts` unwraps into
+ * packets the browser's `AudioDecoder` takes directly.
+ *
+ * The hard part is not the encode, it is that only one of the three platforms can capture its
+ * own output without help:
+ *
+ * - **Linux**: PulseAudio and PipeWire both expose every sink's *monitor* as a capture source,
+ *   and `@DEFAULT_MONITOR@` resolves to the current default sink's — so this follows the user
+ *   switching from speakers to headphones with no re-detection. Needs ffmpeg built with
+ *   `pulse` (checked, not assumed: a minimal build has ALSA only, and `-f pulse` on one of
+ *   those fails at spawn with "Unknown input format").
+ * - **Windows**: ffmpeg has no WASAPI loopback input. The only route is DirectShow, and a
+ *   loopback DirectShow device is something the host must already have — "Stereo Mix", which
+ *   most drivers ship disabled, or a virtual cable. So this reports unavailable with the
+ *   device name to enable rather than spawning an ffmpeg that exits instantly.
+ * - **macOS**: avfoundation can only capture real inputs; there is no system-audio device at
+ *   all without a loopback driver (BlackHole). Same treatment.
+ *
+ * `-application lowdelay` + `-frame_duration 20` keeps the encoder's own delay at one frame,
+ * and `-page_duration 20000` is load-bearing: the Ogg muxer's default is **one second**, which
+ * measured 2000 ms between writes on this host — two seconds of audio latency against video
+ * arriving in twenty milliseconds. With it, pages land every ~40 ms.
+ */
+import { existsSync } from "node:fs";
+import { getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
+import { detectLinuxSession, linuxSessionEnv } from "./remote-desktop-linux-session.ts";
+import { OggOpusDemuxer } from "./remote-desktop-ogg-opus.ts";
+
+/** Opus always decodes at 48 kHz whatever the source rate was. */
+export const AUDIO_SAMPLE_RATE = 48_000;
+const AUDIO_BITRATE = "96k";
+/** One Opus frame. Also the Ogg page duration, in microseconds, for the reason above. */
+const FRAME_MS = 20;
+
+export interface AudioSupport {
+  available: boolean;
+  /** Why not, and what the user can do about it. Null when audio works. */
+  reason: string | null;
+}
+
+/** The ffmpeg input for this host's own output, or null when it has none. */
+export function audioInputArgs(
+  platform: NodeJS.Platform = process.platform,
+  hasPulse = pulseAvailable(),
+): string[] | null {
+  if (platform !== "linux" || !hasPulse) return null;
+  return ["-f", "pulse", "-i", "@DEFAULT_MONITOR@"];
+}
+
+/** Is there a PulseAudio/PipeWire server to talk to? The socket, not `pactl`: the binary is a
+ *  separate package (the same `xrandr` vs `libXrandr` trap), and a PPM started by its systemd
+ *  unit has `XDG_RUNTIME_DIR` even when it has no `DISPLAY`. */
+export function pulseAvailable(runtimeDir = process.env.XDG_RUNTIME_DIR): boolean {
+  if (!runtimeDir) return false;
+  return existsSync(`${runtimeDir}/pulse/native`);
+}
+
+/** Whether this ffmpeg build has the `pulse` demuxer at all — a minimal build has ALSA only,
+ *  and `-f pulse` there fails at spawn rather than degrading. */
+export async function ffmpegHasPulse(ffmpeg: string): Promise<boolean> {
+  try {
+    const proc = Bun.spawn([ffmpeg, "-hide_banner", "-demuxers"], {
+      stdout: "pipe", stderr: "ignore", stdin: "ignore",
+    });
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+    // `ffmpeg -demuxers` writes " D d pulse           Pulse audio input" — flags, then a
+    // *space-separated* name. Anchoring on the flag column rather than on the whole line keeps
+    // this working for both the `-demuxers` and `-devices` spellings (" DE pulse").
+    return /^\s*D\S*\s+(?:\S+\s+)?pulse\s/m.test(text);
+  } catch {
+    return false;
+  }
+}
+
+/** Can this host stream its own audio, and if not, what should the user do. */
+export async function audioSupport(platform: NodeJS.Platform = process.platform): Promise<AudioSupport> {
+  if (platform === "win32") {
+    return {
+      available: false,
+      reason: "Windows has no loopback capture ffmpeg can use — enable \"Stereo Mix\" in Sound "
+        + "settings, or install a virtual audio cable.",
+    };
+  }
+  if (platform === "darwin") {
+    return {
+      available: false,
+      reason: "macOS has no system-audio input — install a loopback driver such as BlackHole.",
+    };
+  }
+  if (platform !== "linux") return { available: false, reason: "Not supported on this platform." };
+  if (!pulseAvailable()) {
+    return { available: false, reason: "No PulseAudio/PipeWire server is running on the host." };
+  }
+  const { ffmpeg } = await getFfmpegCapabilities();
+  if (!ffmpeg) return { available: false, reason: "ffmpeg is not installed." };
+  if (!await ffmpegHasPulse(ffmpeg)) {
+    return { available: false, reason: "This ffmpeg build has no PulseAudio support." };
+  }
+  return { available: true, reason: null };
+}
+
+/** Full argv, pure so it can be asserted without spawning. */
+export function buildAudioArgs(ffmpeg: string, input: string[]): string[] {
+  return [
+    ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
+    "-fflags", "nobuffer", "-flags", "low_delay",
+    ...input,
+    "-c:a", "libopus", "-b:a", AUDIO_BITRATE,
+    // `lowdelay` disables the encoder's look-ahead; without it Opus adds its own ~100ms.
+    "-application", "lowdelay", "-frame_duration", String(FRAME_MS),
+    "-ar", String(AUDIO_SAMPLE_RATE), "-ac", "2",
+    "-page_duration", String(FRAME_MS * 1000),
+    "-flush_packets", "1", "-f", "ogg", "pipe:1",
+  ];
+}
+
+export interface AudioHandle {
+  stop(): void;
+}
+
+export interface StartAudioOptions {
+  /** One decoded Opus packet, ready for `AudioDecoder`. */
+  onPacket: (packet: Uint8Array) => void;
+  /** Channel layout, once the stream header has been parsed. Fires before the first packet. */
+  onStreamInfo: (info: { channels: number; sampleRate: number }) => void;
+  onExit?: (code: number | null, reason?: string) => void;
+}
+
+/** Start capturing host audio, or return null when this host cannot (see `audioSupport`).
+ *  Never throws for an unsupported host: audio is an extra, and a session must not fail to
+ *  start because the machine has no loopback device. */
+export async function startAudioCapture(opts: StartAudioOptions): Promise<AudioHandle | null> {
+  const { ffmpeg } = await getFfmpegCapabilities();
+  if (!ffmpeg) return null;
+  const support = await audioSupport();
+  if (!support.available) return null;
+  const input = audioInputArgs();
+  if (!input) return null;
+
+  const session = process.platform === "linux" ? detectLinuxSession() : null;
+  const proc = Bun.spawn(buildAudioArgs(ffmpeg, input), {
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+    ...(session ? { env: { ...process.env, ...linuxSessionEnv(session) } } : {}),
+  });
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    // SIGKILL for the same reason the video capture uses it — see `remote-desktop-capture.ts`.
+    if (!proc.killed) proc.kill("SIGKILL");
+  };
+
+  const stderrTail = new Response(proc.stderr).text().catch(() => "");
+  proc.exited.then(async (code) => {
+    const diedOnItsOwn = !stopped;
+    stopped = true;
+    let reason: string | undefined;
+    if (diedOnItsOwn && code !== 0 && code !== null) {
+      reason = (await stderrTail).trim().split("\n").slice(-2).join(" | ");
+      console.warn(`[remote-desktop] audio ffmpeg exited ${code}: ${reason}`);
+    }
+    opts.onExit?.(code, reason);
+  });
+
+  const demuxer = new OggOpusDemuxer();
+  let announced = false;
+  // Manual pull loop, never `for await`: cancelling this reader is what segfaults Bun on
+  // Windows (see `remote-desktop-capture.ts`'s header). `stop()` kills the process and the
+  // pending `read()` resolves done.
+  const reader = proc.stdout.getReader();
+  (async () => {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (!value) continue;
+      const packets = demuxer.push(value);
+      const info = demuxer.info;
+      if (!announced && info) {
+        announced = true;
+        opts.onStreamInfo({ channels: info.channels, sampleRate: AUDIO_SAMPLE_RATE });
+      }
+      for (const p of packets) opts.onPacket(p);
+    }
+  })();
+
+  return { stop };
+}