@hienlh/ppm 0.18.14 → 0.18.16

package/src/services/nested-subagent-spy.ts

@@ -0,0 +1,206 @@
+/**
+ * NestedSubagentSpy — surface nested-agent activity on a live Agent card.
+ *
+ * The SDK streams a subagent's events with `parent_tool_use_id` only for
+ * agents the session itself spawned. When that agent spawns another one
+ * (a reviewer running a skill that forks its own worker, a planner calling
+ * researchers), the CLI emits nothing for the nested agent — the parent card
+ * looks frozen on its last step for as long as the grandchild works, which
+ * can be many minutes.
+ *
+ * The nested agent does keep writing its transcript under
+ *   <sessionDir>/subagents/agent-<id>.jsonl
+ * with a meta whose `parentAgentId` chains back to the card's agent. While a
+ * card is open we tail those transcripts and emit their events stamped with
+ * the card's toolUseId, so they render flat inside the card exactly like the
+ * live depth-1 children do. Same shape as bashOutputSpy: start on tool_use,
+ * poll, stop on tool_result.
+ *
+ * One poller per session, not per card: the dir scan that finds nested agents
+ * is shared across every open card, so N cards cost one scan per tick.
+ *
+ * Spies live only in memory. A backgrounded agent that outlives the server
+ * process (or the session's consumer) loses live nested visibility until the
+ * next reload, where the transcript merger restores the same events from disk.
+ */
+
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { ChatEvent } from "../types/chat.ts";
+import { createAgentTranscriptLineParser } from "./subagent-transcript-merger.ts";
+import { groupSubagentsByCard } from "./team-member-activity/subagent-transcript-index.ts";
+
+const POLL_INTERVAL_MS = 1000;
+/** Repeated per-file read failures (locked/replaced file) log once per this window. */
+const WARN_THROTTLE_MS = 30_000;
+
+interface TranscriptTail {
+  bytesRead: number;
+  /** Unterminated trailing bytes — kept raw so a split multi-byte char survives. */
+  pending: Buffer;
+  parser: ReturnType<typeof createAgentTranscriptLineParser>;
+}
+
+interface CardSpy {
+  /** Tails keyed by nested agentId. */
+  tails: Map<string, TranscriptTail>;
+  onEvents: (events: ChatEvent[]) => void;
+}
+
+interface SessionSpy {
+  sessionId: string;
+  subagentsDir: string;
+  cards: Map<string, CardSpy>;
+  intervalId: ReturnType<typeof setInterval>;
+  lastWarnAt: number;
+}
+
+/** Keyed by sessionId — one poller shared by every open card of that session. */
+const sessions = new Map<string, SessionSpy>();
+
+/** Read bytes appended since the last tick; null when nothing new. Throws on I/O error. */
+function readAppended(filePath: string, tail: TranscriptTail): Buffer | null {
+  const size = statSync(filePath).size;
+  if (size <= tail.bytesRead) return null;
+  const fd = openSync(filePath, "r");
+  try {
+    const buf = Buffer.alloc(size - tail.bytesRead);
+    const n = readSync(fd, buf, 0, buf.length, tail.bytesRead);
+    tail.bytesRead += n;
+    return buf.subarray(0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Split pending + chunk into complete lines; the unterminated remainder stays
+ * raw in `tail.pending` because a write can land mid-record, even mid-char.
+ */
+function drainLines(tail: TranscriptTail, chunk: Buffer): string[] {
+  const all = tail.pending.length ? Buffer.concat([tail.pending, chunk]) : chunk;
+  const lastNl = all.lastIndexOf(0x0a);
+  if (lastNl === -1) {
+    tail.pending = all;
+    return [];
+  }
+  tail.pending = all.subarray(lastNl + 1);
+  return all.subarray(0, lastNl).toString("utf8").split("\n");
+}
+
+function warnThrottled(spy: SessionSpy, message: string): void {
+  const now = Date.now();
+  if (now - spy.lastWarnAt < WARN_THROTTLE_MS) return;
+  spy.lastWarnAt = now;
+  console.warn(`[nested-spy] session=${spy.sessionId} ${message}`);
+}
+
+/** One poll for a session: scan the dir once, then drain each open card's nested tails. */
+function tick(spy: SessionSpy): void {
+  let groups: ReturnType<typeof groupSubagentsByCard>;
+  try {
+    groups = groupSubagentsByCard(spy.subagentsDir);
+  } catch (e) {
+    warnThrottled(spy, `scan failed: ${(e as Error).message}`);
+    return;
+  }
+  for (const [cardToolUseId, card] of spy.cards) {
+    const group = groups.get(cardToolUseId);
+    if (!group) continue;
+    const events: ChatEvent[] = [];
+    for (const agent of group) {
+      // Depth-1 (the card's own agent) is already streamed live by the SDK.
+      if (!agent.parentAgentId) continue;
+      let tail = card.tails.get(agent.agentId);
+      if (!tail) {
+        tail = { bytesRead: 0, pending: Buffer.alloc(0), parser: createAgentTranscriptLineParser() };
+        card.tails.set(agent.agentId, tail);
+      }
+      let chunk: Buffer | null;
+      try {
+        chunk = readAppended(agent.transcriptPath, tail);
+      } catch (e) {
+        // A locked or replaced file must not stall the other agents in the group.
+        warnThrottled(spy, `read failed for ${agent.agentId}: ${(e as Error).message}`);
+        continue;
+      }
+      if (!chunk) continue;
+      for (const line of drainLines(tail, chunk)) {
+        for (const timed of tail.parser.feed(line)) {
+          events.push(withParent(timed.ev, cardToolUseId));
+        }
+      }
+    }
+    if (events.length > 0) card.onEvents(events);
+  }
+}
+
+/** Stamp a child with the card it belongs to, keeping the event union intact. */
+function withParent(ev: ChatEvent, parentToolUseId: string): ChatEvent {
+  switch (ev.type) {
+    case "text":
+    case "thinking":
+    case "tool_use":
+    case "tool_result":
+      return { ...ev, parentToolUseId };
+    default:
+      return ev;
+  }
+}
+
+/**
+ * Start tailing nested transcripts for an open Agent/Task card.
+ * `sessionDir` is …/projects/<slug>/<sessionId>; its subagents/ child may not
+ * exist yet — the CLI creates it with the first subagent write, and the scan
+ * simply finds nothing until then.
+ */
+function startSpy(
+  sessionId: string,
+  cardToolUseId: string,
+  sessionDir: string,
+  onEvents: (events: ChatEvent[]) => void,
+): void {
+  let spy = sessions.get(sessionId);
+  if (!spy) {
+    const created: SessionSpy = {
+      sessionId,
+      subagentsDir: join(sessionDir, "subagents"),
+      cards: new Map(),
+      lastWarnAt: 0,
+      intervalId: setInterval(() => tick(created), POLL_INTERVAL_MS),
+    };
+    sessions.set(sessionId, created);
+    spy = created;
+  }
+  if (spy.cards.has(cardToolUseId)) return;
+  spy.cards.set(cardToolUseId, { tails: new Map(), onEvents });
+  console.log(`[nested-spy] session=${sessionId} started card=${cardToolUseId} (${spy.cards.size} open)`);
+}
+
+/** Stop a card's spy, draining whatever landed since the last poll first. */
+function stopSpy(cardToolUseId: string): void {
+  for (const spy of sessions.values()) {
+    if (!spy.cards.has(cardToolUseId)) continue;
+    // Final drain covers every open card; the spare work is one scan.
+    tick(spy);
+    spy.cards.delete(cardToolUseId);
+    console.log(`[nested-spy] session=${spy.sessionId} stopped card=${cardToolUseId} (${spy.cards.size} open)`);
+    if (spy.cards.size === 0) {
+      clearInterval(spy.intervalId);
+      sessions.delete(spy.sessionId);
+    }
+    return;
+  }
+}
+
+/** Stop every spy for a session (turn ended, session migrated, socket closed). */
+function stopAllForSession(sessionId: string): void {
+  const spy = sessions.get(sessionId);
+  if (!spy) return;
+  tick(spy);
+  clearInterval(spy.intervalId);
+  sessions.delete(sessionId);
+  console.log(`[nested-spy] session=${sessionId} stopped all (${spy.cards.size} cards)`);
+}
+
+export const nestedSubagentSpy = { startSpy, stopSpy, stopAllForSession };

package/src/services/remote-desktop/access-unit-assembler.ts

@@ -0,0 +1,90 @@
+/**
+ * Groups the raw NAL units from `NalSplitter` into WebCodecs-ready access units.
+ *
+ * `VideoDecoder` decodes one access unit (one frame) per `EncodedVideoChunk`, not one
+ * NAL — feeding SPS/PPS/slice as three separate chunks throws or corrupts decode. libx264
+ * (no B-frames, `-bf 0`) emits at most one slice NAL per frame, optionally preceded by
+ * SPS/PPS on a keyframe, so an AU boundary is simply "the next VCL NAL after we already
+ * buffered one" — everything non-VCL (SPS/PPS/AUD/SEI) that arrived first attaches to the
+ * AU it precedes.
+ */
+import { NalSplitter, nalType, isVclNal, NAL_TYPE_IDR, NAL_TYPE_SPS, NAL_TYPE_PPS } from "./nal-splitter.ts";
+
+export interface AccessUnit {
+  /** Annex-B encoded bytes (start codes + NAL payloads) — one `EncodedVideoChunk` worth. */
+  bytes: Uint8Array;
+  isKey: boolean;
+}
+
+const START_CODE = Uint8Array.of(0, 0, 0, 1);
+
+function encodeAnnexB(nals: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const n of nals) total += START_CODE.length + n.length;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const n of nals) {
+    out.set(START_CODE, offset);
+    offset += START_CODE.length;
+    out.set(n, offset);
+    offset += n.length;
+  }
+  return out;
+}
+
+export class AccessUnitAssembler {
+  private readonly splitter = new NalSplitter();
+  private pending: Uint8Array[] = [];
+  private pendingHasVcl = false;
+  private sps: Uint8Array | null = null;
+  private pps: Uint8Array | null = null;
+
+  /** Feed a raw ffmpeg stdout chunk; returns zero or more completed access units. */
+  push(chunk: Uint8Array): AccessUnit[] {
+    const aus: AccessUnit[] = [];
+    for (const nal of this.splitter.push(chunk)) {
+      const type = nalType(nal);
+      if (type === NAL_TYPE_SPS) this.sps = nal;
+      else if (type === NAL_TYPE_PPS) this.pps = nal;
+
+      const vcl = isVclNal(nal);
+      if (vcl && this.pendingHasVcl) {
+        const au = this.flush();
+        if (au) aus.push(au);
+      }
+      this.pending.push(nal);
+      if (vcl) this.pendingHasVcl = true;
+    }
+    return aus;
+  }
+
+  /** SPS bytes seen so far (NAL header byte included) — used to derive the avc1 codec
+   *  string. Null until the encoder has emitted its first keyframe. */
+  cachedSps(): Uint8Array | null {
+    return this.sps;
+  }
+
+  private flush(): AccessUnit | null {
+    if (this.pending.length === 0) {
+      this.pendingHasVcl = false;
+      return null;
+    }
+    let nals = this.pending;
+    const isKey = nals.some((n) => nalType(n) === NAL_TYPE_IDR);
+    if (isKey) {
+      // A late-joining client (or a client that missed the very first AU) needs SPS+PPS
+      // concatenated into the same key chunk it decodes — three separate chunks is not
+      // decodable Annex-B input for WebCodecs. Normally libx264 already includes them; this
+      // is a defensive backfill from the cache, not the common path.
+      const hasSps = nals.some((n) => nalType(n) === NAL_TYPE_SPS);
+      const hasPps = nals.some((n) => nalType(n) === NAL_TYPE_PPS);
+      const prefix: Uint8Array[] = [];
+      if (!hasSps && this.sps) prefix.push(this.sps);
+      if (!hasPps && this.pps) prefix.push(this.pps);
+      if (prefix.length > 0) nals = [...prefix, ...nals];
+    }
+    this.pending = [];
+    this.pendingHasVcl = false;
+    return { bytes: encodeAnnexB(nals), isKey };
+  }
+}

package/src/services/remote-desktop/avc1-codec-string.ts

@@ -0,0 +1,18 @@
+/**
+ * Derive the WebCodecs `avc1.PPCCLL` codec string from a real SPS NAL rather than
+ * guessing. `encoderArgs()` in `ffmpeg-capabilities.ts` sets no `-profile`/`-level`, so the
+ * actual encoded profile/level is encoder-default and unknown until the bitstream exists —
+ * a hardcoded guess can mismatch and make `VideoDecoder.configure()` throw or refuse.
+ *
+ * SPS layout (after the 1-byte NAL header at index 0): profile_idc, then the
+ * constraint-flags/reserved byte, then level_idc — always the first three bytes of the
+ * RBSP, unaffected by emulation-prevention bytes (those only appear deeper in the SPS).
+ */
+export function avc1CodecString(sps: Uint8Array): string | null {
+  if (sps.length < 4) return null;
+  const profileIdc = sps[1]!;
+  const constraintFlags = sps[2]!;
+  const levelIdc = sps[3]!;
+  const hex = (n: number) => n.toString(16).padStart(2, "0");
+  return `avc1.${hex(profileIdc)}${hex(constraintFlags)}${hex(levelIdc)}`;
+}

package/src/services/remote-desktop/nal-splitter.ts

@@ -0,0 +1,100 @@
+/**
+ * Incremental Annex-B start-code splitter.
+ *
+ * ffmpeg's `-f h264` stdout is a raw Annex-B byte stream: NAL units separated by
+ * `00 00 01` or `00 00 00 01` start codes, with no framing that respects our read
+ * chunk boundaries. A NAL can straddle two `stdout` reads, so this holds the tail
+ * of the last incomplete NAL across calls to `push()` rather than assuming a full
+ * NAL always arrives in one chunk.
+ */
+
+/** NAL unit types relevant to access-unit assembly (ITU-T H.264 Table 7-1). */
+export const NAL_TYPE_SLICE_NON_IDR = 1;
+export const NAL_TYPE_IDR = 5;
+export const NAL_TYPE_SPS = 7;
+export const NAL_TYPE_PPS = 8;
+
+/** Low 5 bits of the NAL header byte (the unit's first byte) is `nal_unit_type`. */
+export function nalType(nal: Uint8Array): number {
+  return (nal[0] ?? 0) & 0x1f;
+}
+
+/** A slice NAL starts a new access unit; SPS/PPS/AUD/SEI attach to whichever AU follows them. */
+export function isVclNal(nal: Uint8Array): boolean {
+  const t = nalType(nal);
+  return t === NAL_TYPE_SLICE_NON_IDR || t === NAL_TYPE_IDR;
+}
+
+/** `Bun.spawn` stdout chunks type as `Uint8Array<ArrayBufferLike>` (could in principle back
+ *  onto a SharedArrayBuffer), while `new Uint8Array(n)` types as the narrower
+ *  `Uint8Array<ArrayBuffer>` — pin everything here to the wider type so a plain chunk and our
+ *  own freshly-allocated buffers can always mix without a type error. */
+export type Bytes = Uint8Array<ArrayBufferLike>;
+
+function concat(a: Bytes, b: Bytes): Bytes {
+  if (a.length === 0) return b;
+  if (b.length === 0) return a;
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/** Index of the next `00 00 01` marker at or after `from`, or -1. This always finds the
+ *  *last* 3 bytes of a start code — a 4-byte `00 00 00 01` form has its 3-byte suffix match
+ *  here too (at index+1), and H.264 emulation prevention guarantees `00 00 01`/`00 00 00`
+ *  never occurs inside real RBSP payload data, so there is no false-positive risk scanning
+ *  straight through NAL bodies. */
+function findStartCode(buf: Bytes, from: number): number {
+  for (let i = from; i + 2 < buf.length; i++) {
+    if (buf[i] === 0 && buf[i + 1] === 0 && buf[i + 2] === 1) return i;
+  }
+  return -1;
+}
+
+/** Bytes to skip past a marker found by `findStartCode` to reach the payload — always 3
+ *  (the marker itself), regardless of how many extra leading zero bytes preceded it. */
+const MARKER_LEN = 3;
+
+/** Guard against an unbounded buffer if ffmpeg ever emits a byte stream with no start
+ *  code at all (would indicate a broken pipe/format, not a real Annex-B stream). */
+const MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+
+export class NalSplitter {
+  private buffer: Bytes = new Uint8Array(0);
+
+  /** Feed a raw stdout chunk; returns zero or more complete NAL payloads (start code
+   *  stripped). Incomplete trailing bytes are retained for the next call. */
+  push(chunk: Bytes): Bytes[] {
+    this.buffer = concat(this.buffer, chunk);
+    const nals: Bytes[] = [];
+
+    let start = findStartCode(this.buffer, 0);
+    if (start === -1) {
+      if (this.buffer.length > MAX_BUFFER_BYTES) this.buffer = new Uint8Array(0);
+      return nals;
+    }
+    // Drop any garbage before the first start code (should not happen with a clean
+    // ffmpeg pipe, but a partial NAL from before this splitter attached must not corrupt
+    // the first parsed unit).
+    for (;;) {
+      const nextStart = findStartCode(this.buffer, start + MARKER_LEN);
+      if (nextStart === -1) {
+        this.buffer = this.buffer.slice(start);
+        break;
+      }
+      // `nextStart` only marks the *last* 3 bytes of the following start code — a 4-byte
+      // `00 00 00 01` form leaves its leading zero sitting right before `nextStart`, which
+      // would otherwise get appended to this NAL's payload as a spurious trailing byte.
+      // Trim any such zero bytes back to the real payload end (standard Annex-B handling of
+      // `leading_zero_8bits`/`trailing_zero_8bits`).
+      let payloadEnd = nextStart;
+      const payloadStart = start + MARKER_LEN;
+      while (payloadEnd > payloadStart && this.buffer[payloadEnd - 1] === 0) payloadEnd--;
+      const payload = this.buffer.slice(payloadStart, payloadEnd);
+      if (payload.length > 0) nals.push(payload);
+      start = nextStart;
+    }
+    return nals;
+  }
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Spawn ffmpeg (`gdigrab` → H.264 Annex-B on `pipe:1`) and turn its stdout into access units.
+ *
+ * Teardown is `proc.kill()` only — never `reader.cancel()`, never `for await (chunk of
+ * proc.stdout) { ... break }`. Both of those cancel the underlying stream reader, which
+ * segfaults Bun 1.3.x on Windows the instant a consumer goes away (see
+ * `transcode-stream.ts:130-148` and `tests/integration/transcode-stream-client-disconnect.test.ts`
+ * — that guard targets a `Response` body; the WS rewrite here re-creates the same trap one
+ * layer down if the pump loop is written as `for await`). `stop()` only calls `proc.kill()`;
+ * the in-flight `reader.read()` then resolves with `done: true` and the pump loop exits on
+ * its own — it is never cancelled from outside.
+ */
+import { getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
+import { captureEncoderArgs, CAPTURE_FRAMERATE } from "./remote-desktop-encoder-args.ts";
+import { AccessUnitAssembler, type AccessUnit } from "./access-unit-assembler.ts";
+
+export class CaptureUnavailableError extends Error {
+  constructor(msg = "ffmpeg is not installed (gdigrab capture requires it)") {
+    super(msg);
+    this.name = "CaptureUnavailableError";
+  }
+}
+
+/** Build the gdigrab argv; pure so it can be asserted on without spawning a process.
+ *  `-fflags nobuffer -flags low_delay` + `-flush_packets 1` stop ffmpeg from holding frames in
+ *  its demux/mux buffers before emitting — on a fast/LAN transport that buffering is a big slice
+ *  of the felt lag. `encoder` selects the H.264 encoder args (hardware NVENC/QSV/AMF when the
+ *  capability probe found one, else libx264). */
+export function buildCaptureArgs(ffmpeg: string, encoder: string = "libx264"): string[] {
+  return [
+    ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
+    "-fflags", "nobuffer", "-flags", "low_delay",
+    "-f", "gdigrab", "-framerate", String(CAPTURE_FRAMERATE), "-i", "desktop",
+    "-vf", "scale=-2:720",
+    ...captureEncoderArgs(encoder),
+    "-flush_packets", "1",
+    "-f", "h264", "pipe:1",
+  ];
+}
+
+export interface CaptureHandle {
+  /** SPS bytes cached from the stream (for the avc1 codec string), null before the encoder's
+   *  first keyframe has been parsed. */
+  cachedSps(): Uint8Array | null;
+  /** Kill ffmpeg. Idempotent, safe to call from multiple teardown paths. */
+  stop(): void;
+  /** True once `stop()` has run or the process exited on its own. */
+  isStopped(): boolean;
+}
+
+export interface StartCaptureOptions {
+  onAccessUnit: (au: AccessUnit) => void;
+  /** Called once the process exits, whether via `stop()` or on its own (crash/killed
+   *  externally) — lets the session registry clean up without polling. `reason` is a short
+   *  stderr tail, present only when ffmpeg died on its own (e.g. gdigrab access denied on a
+   *  disconnected session) so the caller can surface *why* to the client instead of a bare
+   *  disconnect. */
+  onExit?: (code: number | null, reason?: string) => void;
+}
+
+/** Start gdigrab capture. Rejects immediately if ffmpeg is not on PATH. */
+export async function startCapture(opts: StartCaptureOptions): Promise<CaptureHandle> {
+  const caps = await getFfmpegCapabilities();
+  if (!caps.ffmpeg) throw new CaptureUnavailableError();
+
+  const proc = Bun.spawn(buildCaptureArgs(caps.ffmpeg, caps.encoder ?? "libx264"), {
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+
+  let stopped = false;
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (!proc.killed) proc.kill();
+  };
+
+  // Drain stderr so ffmpeg never blocks on a full pipe; keep a short tail for diagnostics.
+  const stderrTail = new Response(proc.stderr).text().catch(() => "");
+  proc.exited.then(async (code) => {
+    // Read `stopped` BEFORE overwriting it: this is the only reliable "did WE ask ffmpeg to
+    // die" signal. `proc.killed` is NOT reliable for that — Bun sets it `true` even when
+    // ffmpeg exits on its own with a nonzero code (verified: gdigrab "access denied" on a
+    // disconnected session exits with `killed: true` despite `stop()` never having been
+    // called), which previously suppressed this warning — and any client-facing error —
+    // for exactly the crash this exists to report.
+    const diedOnItsOwn = !stopped;
+    stopped = true;
+    let reason: string | undefined;
+    if (diedOnItsOwn && code !== 0 && code !== null) {
+      reason = (await stderrTail).trim().split("\n").slice(-3).join(" | ");
+      console.warn(`[remote-desktop] ffmpeg exited ${code}: ${reason}`);
+    }
+    opts.onExit?.(code, reason);
+  });
+
+  const assembler = new AccessUnitAssembler();
+
+  // Manual pull loop — the only safe way to drain this stdout (see file header). Runs
+  // detached from the caller; it terminates itself once `proc.kill()` resolves the pending
+  // read with `done: true`, never via an external cancel.
+  const reader = proc.stdout.getReader();
+  (async () => {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (!value) continue;
+      for (const au of assembler.push(value)) opts.onAccessUnit(au);
+    }
+  })().catch((e) => {
+    console.error(`[remote-desktop] capture pump failed: ${(e as Error).message}`);
+  });
+
+  return {
+    cachedSps: () => assembler.cachedSps(),
+    stop,
+    isStopped: () => stopped,
+  };
+}

package/src/services/remote-desktop/remote-desktop-encoder-args.ts

@@ -0,0 +1,42 @@
+/**
+ * Capture-tuned libx264 args — deliberately NOT `encoderArgs()` from `ffmpeg-capabilities.ts`.
+ * That table is tuned for "watch a file" (nvenc VBR, libx264 `-crf 23 -maxrate 8M -bufsize
+ * 16M`), which fights a real-time capture: large bufsize/VBR inflates latency spikes exactly
+ * where `-tune zerolatency` is trying to remove them.
+ *
+ * libx264 is forced (never the hardware picks from `ffmpeg-capabilities.ts`) so profile/level
+ * behavior is deterministic across machines — the actual codec string is still derived from
+ * the real SPS bytes at runtime (`avc1-codec-string.ts`), this just keeps that derivation
+ * predictable during development.
+ */
+
+/** 30fps + a 1s keyframe interval (30 frames): smoother than 15fps and bounds how long a
+ *  dropped/late-joining client waits to resync (see WS backpressure handling). */
+export const CAPTURE_FRAMERATE = 30;
+export const CAPTURE_GOP_FRAMES = 30;
+
+/** ffmpeg output args for the H.264 encode step (goes after `-i desktop -vf ...`).
+ *  Prefers hardware NVENC (verified to work even under an RDP session on this class of GPU) —
+ *  hardware encode adds ~5–15ms vs 30–100ms for libx264, the dominant slice of the felt lag on
+ *  a fast/LAN transport. Falls back to a low-latency libx264 profile when no hardware H.264
+ *  encoder is available. The avc1 codec string is derived from the real SPS at runtime, so the
+ *  encoder's actual profile/level is handled regardless of which branch runs. */
+export function captureEncoderArgs(encoder: string = "libx264"): string[] {
+  const common = ["-b:v", "6M", "-maxrate", "6M", "-g", String(CAPTURE_GOP_FRAMES), "-bf", "0", "-pix_fmt", "yuv420p"];
+  switch (encoder) {
+    case "h264_nvenc":
+      // p2 + `-tune ll` (low latency), CBR, no frame reordering, minimal output delay/VBV.
+      return ["-c:v", "h264_nvenc", "-preset", "p2", "-tune", "ll", "-rc", "cbr",
+        "-zerolatency", "1", "-delay", "0", "-bufsize", "512k", ...common];
+    case "h264_qsv":
+      return ["-c:v", "h264_qsv", "-preset", "veryfast", "-low_power", "1", "-bufsize", "512k", ...common];
+    case "h264_amf":
+      return ["-c:v", "h264_amf", "-quality", "speed", "-rc", "cbr", "-bufsize", "512k", ...common];
+    default:
+      // libx264 low-latency. `-tune zerolatency` enables sliced-threads (multi-slice NALs);
+      // access-unit-assembler.ts assumes one slice/frame, so force it back with sliced-threads=0.
+      return ["-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency",
+        "-profile:v", "main", "-level", "4.0", "-x264-params", "sliced-threads=0:slices=1",
+        "-bufsize", "1M", ...common];
+  }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Feature switch. Remote desktop is ON by default — the viewer itself shows a warning before
+ * the first frame is streamed (`remote-desktop-warning-gate.tsx`) and every entry point still
+ * sits behind PPM auth. `REMOTE_DESKTOP_ENABLED=0` (or `false`) turns the whole surface off for
+ * hosts that never want a live video+input channel reachable, e.g. one exposed on a public
+ * tunnel. Every entry point (REST routes, WS upgrade) checks this independently rather than
+ * trusting a single call site.
+ */
+export function isRemoteDesktopEnabled(): boolean {
+  const v = process.env.REMOTE_DESKTOP_ENABLED?.trim().toLowerCase();
+  return !(v === "0" || v === "false");
+}