@torrent-tv/proxy 2.89.6 → 2.89.7

package/bin/cli.js

@@ -1,684 +1,684 @@
-#!/usr/bin/env node
-/**
- * @file CLI entry point for the torrent-tv proxy.
- *
- * Parses command-line arguments, starts the local HTTP server, opens a
- * persistent WebSocket tunnel to the registry server, and registers this
- * proxy. Liveness is tracked via the tunnel connection — the proxy re-registers
- * automatically on reconnect so the server's in-memory store stays consistent.
- */
-
-// FIRST, and it must stay first: it sets how many blocking calls this process
-// can have in flight, and a module's imports are evaluated before its body, so
-// anything imported above it would get the default pool. See the file itself
-// for the measurement that made it necessary.
-import "./thread-pool.js";
-import { Command } from "commander";
-import os from "node:os";
-import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
-import ffmpegStatic from "ffmpeg-static";
-import { startProxyServer } from "../server.js";
-import { registerClient } from "../services/transport/registry-api.js";
-import { createTunnelClient } from "../services/transport/tunnel-client.js";
-import { createWebRtcManager } from "../services/transport/webrtc-manager.js";
-import { createDataChannelHandler } from "../services/transport/data-channel-handler.js";
-import { dumpsToRemove, pruneCoreDumps } from "../services/storage/core-dumps.js";
-import { availableMemoryBytes } from "../services/storage/machine-memory.js";
-import { Diagnostics } from "../services/storage/Diagnostics.js";
-import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/transport/packet-witness.js";
-import { createUsrsctpStateReader } from "../services/transport/usrsctp-state.js";
-import { startMemoryReport } from "../services/storage/memory-report.js";
-import { fragmentBufferCollection } from "../services/torrent/worker/client.js";
-import { collectHealthMetrics } from "../services/transport/health-collector.js";
-import { createPortMapper } from "../services/transport/port-mapper.js";
-import { installationId } from "../services/identity/installation-id.js";
-import { classifyNat } from "../services/transport/nat-classifier.js";
-import { DEFAULT_SEGMENT_FORMAT_ID, SEGMENT_FORMAT_IDS } from "../services/encode/segment-formats/index.js";
-import { logToFile, logger } from "../utils/logger.js";
-
-const require = createRequire(import.meta.url);
-const { version: PROXY_VERSION } = require("../package.json");
-
-// Last-resort process guard. This proxy runs UNTRUSTED torrents through
-// WebTorrent, which can throw ASYNCHRONOUSLY on a malformed source — e.g. a
-// v2-only / hybrid magnet crashes `arr2hex(parsedTorrent.infoHash)` deep inside
-// `Torrent._onTorrentId` (undefined v1 infohash), in a microtask that bypasses
-// the client "error" event. Without this, one bad torrent takes down the whole
-// node and every viewer on it, and the addon restarts in a crash loop. Log the
-// full stack and keep serving: the offending session fails on its own; everyone
-// else is unaffected. (The add path also pre-validates the infohash, so this is
-// a backstop for anything not caught there.)
-process.on("uncaughtException", (error) => {
-  logger.error(`uncaughtException (kept alive): ${error?.stack ?? error}`);
-});
-process.on("unhandledRejection", (reason) => {
-  logger.error(`unhandledRejection (kept alive): ${reason instanceof Error ? reason.stack : String(reason)}`);
-});
-
-const program = new Command();
-
-const HELP_EXAMPLES = `
-Examples:
-  torrent-tv-proxy --server-url http://localhost:8080
-  torrent-tv-proxy --server-url http://localhost:8080 --host 0.0.0.0 --port 9090
-  torrent-tv-proxy --server-url http://localhost:8080 --public-base-url https://proxy.example.com
-  torrent-tv-proxy --server-url http://localhost:8080 --ffmpeg-bin /usr/local/bin/ffmpeg
-  torrent-tv-proxy --server-url http://localhost:8080 --no-transcode-audio
-
-Notes:
-  - --help prints this message and exits with code 0.
-  - Video transcode is available automatically for per-session fallback when requested by client API.
-`;
-
-if (process.argv.includes("help")) {
-  process.argv = [process.argv[0], process.argv[1], "--help"];
-}
-
-program
-  .name("torrent-proxy-client")
-  .description("Expose torrent files over HTTP stream endpoints for browser playback.")
-  .requiredOption("--server-url <url>", "Registry server base URL")
-  .option("--public-base-url <url>", "Direct URL advertised to browser clients")
-  .option("--host <host>", "Local bind host", "127.0.0.1")
-  .option("--port <port>", "Local HTTP port", "9090")
-  .option("--id <id>", "Stable client id")
-  .option("--name <name>", "Display name")
-  .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
-  .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
-  .option("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
-  .option(
-    "--send-chunk-bytes <bytes>",
-    "Size of one data-channel message when sending a response body (0 = whatever the body read hands over, ~64KB). For measuring whether the delivery wedge depends on that size."
-  )
-  .option(
-    "--usrsctp-state",
-    "Read usrsctp's association state with gdb when a wedge is declared. OFF by default: gdb attaches to THIS process and stops every thread of it while it works."
-  )
-  .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
-  .option("--budget <kind>", "How much of this machine the proxy may take: adaptive (default), share or fixed")
-  .option("--budget-share <fraction>", "With --budget share: the fraction of what is free, 0..1")
-  .option("--budget-bytes <bytes>", "With --budget fixed: the ceiling, per resource")
-  .option("--min-memory-bytes <bytes>", "Least memory this proxy should have, whatever the policy says")
-  .option("--min-disk-bytes <bytes>", "Least disk this proxy should have, whatever the policy says")
-  .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
-  .option(
-    "--state-dir <path>",
-    "Where to keep what this host has measured about itself (default: beside the installed proxy)"
-  )
-  .option(
-    "--log-file <path>",
-    "Also write the log to this file, so a crash or an update does not take it with them"
-  )
-  .option(
-    "--segment-format <format>",
-    `HLS output container: ${SEGMENT_FORMAT_IDS.join(" | ")}`,
-    DEFAULT_SEGMENT_FORMAT_ID
-  )
-  .option("--token <token>", "Registration token", "")
-  .addHelpText("after", HELP_EXAMPLES);
-
-program.parse(process.argv);
-const options = program.opts();
-
-const localPort = Number(options.port);
-if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
-  logger.error("Invalid --port value.");
-  process.exit(1);
-}
-
-const serverUrl = String(options.serverUrl).replace(/\/+$/, "");
-const bindHost = String(options.host);
-const explicitBaseUrl = options.publicBaseUrl
-  ? String(options.publicBaseUrl).replace(/\/+$/, "")
-  : "";
-const clientId = installationId({ stateDir: options.stateDir, explicitId: options.id });
-const clientName = options.name ? String(options.name) : `proxy-${clientId.slice(0, 8)}`;
-const token = String(options.token ?? "");
-const transcodeAudio = options.transcodeAudio !== false;
-const portMappingEnabled = options.portMapping !== false;
-// WHAT THE OPERATOR HAS SAID WE MAY TAKE, and the only numbers in this proxy
-// that are chosen rather than derived — because they are chosen by the person
-// whose machine it is. The default is the measured one: what is free now, plus
-// what we already hold, less what everything that is not us has been seen to
-// need. `share` and `fixed` are the owner naming a number instead; the floors
-// are the owner saying "below this it is not worth running".
-//
-// One policy, applied to every resource. Memory and disk are divided apart
-// because they cannot pay for each other, but by ONE owner, because the
-// claimants trade across them: pieces that do not fit in memory are spilled to
-// disk, so what memory is given decides how much disk is needed.
-const budgetFloors = {};
-if (Number.isFinite(Number(options.minMemoryBytes))) {
-  budgetFloors.memory = Number(options.minMemoryBytes);
-}
-const budgetPolicy = {
-  kind: ["adaptive", "share", "fixed"].includes(String(options.budget)) ? String(options.budget) : "adaptive",
-  share: Number(options.budgetShare),
-  bytes: Number(options.budgetBytes),
-  floors: budgetFloors,
-  // Named apart from the per-resource floors because the disk is one resource
-  // per DEVICE and the operator names one figure for all of them.
-  diskFloorBytes: Number.isFinite(Number(options.minDiskBytes)) ? Number(options.minDiskBytes) : 0
-};
-
-// Per-torrent memory budget for resident pieces. Pieces past it spill to disk
-// rather than being lost, so a small value costs read latency, never data.
-const memoryBytes =
-  options.memoryBytes !== undefined && Number.isFinite(Number(options.memoryBytes)) && Number(options.memoryBytes) > 0
-    ? Number(options.memoryBytes)
-    : undefined;
-const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
-const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
-
-/**
- * Verify that the ffmpeg binary is reachable and exits cleanly.
- * Throws with a descriptive message when the check fails.
- *
- * @returns {void}
- */
-function assertFfmpegAvailability() {
-  const probe = spawnSync(ffmpegBin, ["-version"], {
-    stdio: "ignore",
-    windowsHide: true,
-    timeout: 5000
-  });
-  if (probe.error) {
-    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
-    throw new Error(`Audio transcode is enabled, but ffmpeg is unavailable (${ffmpegBin}): ${message}`);
-  }
-  if (typeof probe.status === "number" && probe.status !== 0) {
-    throw new Error(
-      `Audio transcode is enabled, but ffmpeg check failed (${ffmpegBin}, exit code ${probe.status}).`
-    );
-  }
-}
-
-/** @type {boolean} */
-let registrationInProgress = false;
-
-/** @type {import("fastify").FastifyInstance | null} */
-let app = null;
-
-/** @type {number} */
-let actualPort = localPort;
-
-/** @type {boolean} */
-let shutdownInProgress = false;
-
-/** @type {ReturnType<typeof createTunnelClient> | null} */
-let tunnelClient = null;
-
-/** @type {ReturnType<typeof createPortMapper> | null} */
-let portMapper = null;
-
-/** @type {ReturnType<typeof createPortMapper> | null} UDP mapping for the WebRTC port. */
-let udpPortMapper = null;
-
-/** @type {ReturnType<typeof createWebRtcManager> | null} */
-let webRtcManager = null;
-/**
- * The packet witness, so shutdown can stop the ring it owns.
- *
- * @type {ReturnType<typeof createPacketWitness> | null}
- */
-let packetWitness = null;
-
-/** @type {ReturnType<typeof createUsrsctpStateReader> | null} */
-let usrsctpStateReader = null;
-
-/** @type {ReturnType<typeof createDataChannelHandler> | null} */
-let dataChannelHandler = null;
-
-/** @type {import("../services/transport/nat-classifier.js").NatClassification | null} Latest NAT classification (for WebRTC port prediction). */
-let natInfo = null;
-
-
-/**
- * Register this proxy with the registry server.
- * Silently skips if a registration is already in flight.
- *
- * @returns {Promise<void>}
- */
-async function registerClientSafe() {
-  if (registrationInProgress) {
-    return;
-  }
-  registrationInProgress = true;
-  try {
-    const result = await registerClient({
-      serverUrl,
-      id: clientId,
-      name: clientName,
-      baseUrl: explicitBaseUrl || `http://${bindHost}:${actualPort}`,
-      token
-    });
-    logger.success(`Registered as "${result.client?.name}" (${result.client?.id?.slice(0, 8)})`);
-  } finally {
-    registrationInProgress = false;
-  }
-}
-
-/**
- * Register this proxy with the registry server, retrying indefinitely
- * with exponential backoff until it succeeds. This allows the proxy to
- * survive temporary server outages (restarts, deployments) without crashing.
- *
- * @returns {Promise<void>}
- */
-async function registerWithRetry() {
-  const MAX_DELAY_MS = 60_000;
-  let delayMs = 2_000;
-  let attempt = 0;
-  while (true) {
-    attempt++;
-    try {
-      await registerClientSafe();
-      return;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.warn(`Registration attempt ${attempt} failed: ${message}. Retrying in ${delayMs / 1000}s…`);
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
-      delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
-    }
-  }
-}
-
-/**
- * Gracefully shut down the tunnel, heartbeat timer, and HTTP server.
- *
- * @param {string} signal - Signal name (e.g. "SIGINT").
- * @returns {Promise<void>}
- */
-async function shutdown(signal) {
-  if (shutdownInProgress) {
-    return;
-  }
-  shutdownInProgress = true;
-  if (tunnelClient) {
-    tunnelClient.disconnect();
-    tunnelClient = null;
-  }
-  logger.warn(`Received ${signal}, shutting down...`);
-  try {
-    // Remove the router port mappings before exiting (lease expiry is the
-    // backstop if this is skipped on a hard kill).
-    if (portMapper) {
-      await portMapper.stop();
-      portMapper = null;
-    }
-    if (udpPortMapper) {
-      await udpPortMapper.stop();
-      udpPortMapper = null;
-    }
-    // Close WebRTC sessions and release the shared UDP mux listener socket.
-    if (webRtcManager) {
-      try { webRtcManager.dispose(); } catch { /* ignore */ }
-      webRtcManager = null;
-    }
-    // Stop the packet ring and remove its scratch files. `process.exit` below
-    // does not take child processes with it, so without this a proxy restarted
-    // outside a container leaves one tcpdump running per restart.
-    if (packetWitness) {
-      try { await packetWitness.dispose(); } catch { /* ignore */ }
-      packetWitness = null;
-    }
-    if (app) {
-      await app.close();
-    }
-    process.exit(0);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error(`Shutdown failed: ${message}`);
-    process.exit(1);
-  }
-}
-
-// WHAT THE EVIDENCE WEIGHS, and what it may weigh. Core dumps, heap snapshots
-// and packet captures were each bounded by a COUNT and none by a size — two
-// dumps and five snapshots came to 3.2 GB on the addon host. One object, built
-// here where the collectors are, registered with the owner of the disk inside
-// the server and consulted by each collector before it writes.
-const diagnostics = new Diagnostics({
-  logger,
-  kinds: [
-    { name: "core dumps", directory: () => options.stateDir || "", matches: (name) => name.startsWith("core.") },
-    {
-      name: "heap snapshots",
-      directory: () => options.stateDir || "",
-      matches: (name) => name.endsWith(".heapsnapshot")
-    },
-    {
-      name: "packet captures",
-      directory: () => options.stateDir || "",
-      matches: (name) => name.startsWith("packet-witness")
-    }
-  ]
-});
-
-try {
-  logToFile(options.logFile);
-  if (transcodeAudio) {
-    assertFfmpegAvailability();
-  }
-  const started = await startProxyServer({
-    host: bindHost,
-    port: localPort,
-    transcodeAudio,
-    ffmpegBin,
-    memoryBytes,
-    segmentFormat: options.segmentFormat,
-    stateDir: options.stateDir,
-    diagnostics,
-    budgetPolicy,
-    logFile: options.logFile ?? "",
-    deliverySink: options.deliverySink === true,
-    // Late-bound the same way `webRtcManager` is below: the torrent pool is
-    // built inside `startProxyServer`, before `dataChannelHandler` — the
-    // thing that actually owns a channel to push down — exists.
-    onSubtitleCues: (event) => dataChannelHandler?.publishSubtitleCues(event)
-  });
-  app = started.app;
-  actualPort = started.port;
-  const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
-
-  // A native fault writes the whole address space out — 4.18 GB each on the
-  // field host, and four of them nearly filled a 235 GB disk. Keep the newest
-  // two, which are the evidence for the fault still open, and drop the rest.
-  void pruneCoreDumps(options.stateDir);
-  // Same policy for the packet captures the send-queue witness writes.
-  packetWitness = createPacketWitness({
-    log: (message) => logger.info(message),
-    dir: options.stateDir || "",
-    port: actualPort,
-    // Evidence takes room from the product, so a capture is asked for rather
-    // than taken. Refused, it is a line and not a silence.
-    mayKeep: (bytes) => diagnostics.mayKeep({ what: "a packet capture", bytes }),
-    // Which of the kept captures go is the storage component's rule, the same
-    // one core dumps are pruned by.
-    chooseRemovals: dumpsToRemove
-  });
-  // A process that was KILLED mid-session leaves the ring's last seconds
-  // behind, and those seconds contain whatever ended it. Keep them under a name
-  // the pruner recognises BEFORE anything starts a new ring over them.
-  void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir, dumpsToRemove));
-
-  // Reads usrsctp's own association state via gdb the moment a wedge is
-  // declared (roadmap item 11) — no source rebuild, the module ships
-  // unstripped. A host without gdb just never gets a reading, the same way a
-  // host without tcpdump never gets a packet capture.
-  // OFF UNLESS ASKED FOR, and the reason is a field incident rather than
-  // caution. On 2026-09-05 a delivery probe declared a wedge that lasted half a
-  // second and cleared itself; the reading it triggered attached gdb to this
-  // process, which stopped all eighty of its threads. The log ended mid-second,
-  // /healthz stopped answering, and the viewer waited a minute and was told the
-  // proxy had sent no video. The fifteen-second guard could not fire — it is a
-  // timer inside the process gdb had stopped — and killing gdb left the main
-  // thread deadlocked for good, so only restarting the addon recovered it.
-  //
-  // A means of diagnosis may not stop the product. This one attaches to a live
-  // process and is triggered by a verdict with a known history of false
-  // positives, so it is a thing to switch on deliberately while watching, not
-  // something that arms itself.
-  usrsctpStateReader = options.usrsctpState === true
-    ? createUsrsctpStateReader({ log: (message) => logger.info(message) })
-    : null;
-
-  // What this process holds, once a minute. The kernel killed the proxy on
-  // 2026-08-28 at 2.4 GB resident and the log had never said a word about
-  // memory, so the growth that ended in that kill has no shape in any record we
-  // keep. RSS is the figure the OOM killer reads, so RSS is the figure to say.
-  // The disk path is where pieces spill and torrent data lands. A budget for
-  // memory alone is half a budget: a store that behaves about RAM can still
-  // fill the card an addon host boots from, and neither limit was measured
-  // before (roadmap item 2).
-  startMemoryReport({
-    log: (message) => logger.info(message),
-    // A snapshot weighs about what the heap weighs. Asked for, not taken.
-    mayKeep: (bytes) => diagnostics.mayKeep({ what: "a heap snapshot", bytes }),
-    // The other half of the piece-buffer question. Shared memory lives until
-    // BOTH isolates let go, so the worker's own count answers only its side;
-    // read here, on the same line as the process figures the growth shows up
-    // in and at the same instant as them.
-    readExtra: () => {
-      const fragments = fragmentBufferCollection();
-      return fragments.seen === 0
-        ? ""
-        : `piece buffers handed here ${fragments.seen} seen, ${fragments.collected} collected, ` +
-          `${fragments.seen - fragments.collected} still alive`;
-    },
-    // Once a minute cannot see what kills this process. Both out-of-memory
-    // kills of 2026-09-02 happened inside a single gap of the old cadence: the
-    // last line before the first said 602 MB and the kernel measured 1.72 GB
-    // 34 seconds later, and before the second it said 1171 MB and the kernel
-    // measured 1.86 GB nine seconds later. The figure is read every second
-    // now and written when it has moved by a step worth a line, so a rise of a
-    // gigabyte is a curve instead of one number and then a death. Every /proc
-    // read stayed behind the decision to write, so a quiet second costs one
-    // call to `process.memoryUsage()`.
-    intervalMs: 1_000,
-    quietMs: 60_000,
-    changeBytes: 25 * 1024 * 1024,
-    diskPath: os.tmpdir(),
-    // WHERE A SNAPSHOT SURVIVES THE PROCESS IT IS ABOUT, and how many are kept
-    // — the same answer the torrent worker already had. This scope had neither:
-    // snapshots went to the temporary directory, which the container recreates
-    // on every restart, and all of them were kept. Fifty-four were written on
-    // 2026-09-07 and every one was gone by the time the process that wrote them
-    // died of a heap it had never been possible to look at.
-    snapshotDir: options.stateDir || undefined,
-    snapshotFloorBytes: 400 * 1024 * 1024,
-    snapshotGrowthBytes: 400 * 1024 * 1024,
-    keepSnapshots: 3
-  });
-
-  logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
-  logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
-  logger.info(`Advertised direct URL: ${directBaseUrl}`);
-  if (transcodeAudio) {
-    logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
-  }
-
-  // All WebRTC sessions are multiplexed onto this single UDP port (same number
-  // as the HTTP port, different protocol) via a persistent ICE UDP mux listener
-  // in the WebRTC manager. One port → one UPnP mapping → one reachable endpoint.
-  const webrtcUdpPort = actualPort;
-
-  // Try to open the local port on the home router (UPnP/NAT-PMP) so the proxy
-  // is reachable from the internet without manual port forwarding. Best-effort
-  // and fire-and-forget: failure is normal (router without UPnP) and must not
-  // delay tunnel connect / registration, so we do not await it.
-  if (portMappingEnabled) {
-    portMapper = createPortMapper({ port: actualPort, protocol: "TCP" });
-    void portMapper
-      .start()
-      .then(() => {
-        // Mapping may finish after the tunnel is already connected; report the
-        // endpoint now. If the tunnel is not open yet, onConnect re-sends it.
-        const endpoint = portMapper?.getMappedEndpoint();
-        if (endpoint) {
-          tunnelClient?.sendEndpoint(endpoint);
-        }
-      })
-      .catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        logger.warn(`Port mapping failed to start: ${message}`);
-      });
-
-    // Also map the single WebRTC UDP port. Not reported to the server: the
-    // browser discovers the endpoint via ICE (srflx) candidates, not the TCP
-    // dial-back probe.
-    udpPortMapper = createPortMapper({
-      port: webrtcUdpPort,
-      protocol: "UDP",
-      description: "torrent-tv proxy (WebRTC)"
-    });
-    void udpPortMapper.start().catch((error) => {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.warn(`UDP port mapping failed to start: ${message}`);
-    });
-  } else {
-    logger.info("Automatic port mapping is disabled (--no-port-mapping).");
-  }
-
-  // Classify the home NAT (diagnostic + decides whether WebRTC will need port
-  // prediction for remote viewers). Best-effort, fire-and-forget — STUN probes
-  // never block startup.
-  void classifyNat()
-    .then((nat) => {
-      // Stored for WebRTC port prediction (webRtcManager reads it per session).
-      natInfo = nat;
-      if (nat.klass === "endpoint-independent") {
-        logger.info(
-          `nat: endpoint-independent (cone) — external UDP port stable across STUN servers (${nat.externalIp}); fixed-port WebRTC mapping is sufficient, no port prediction needed`
-        );
-      } else if (nat.klass === "symmetric") {
-        logger.warn(
-          `nat: SYMMETRIC — external UDP port varies per destination (delta ${nat.portDelta}); WebRTC offers predicted ports (base+delta*k) — covers sequential/predictable symmetric NAT, not fully random`
-        );
-      } else {
-        logger.info("nat: classification inconclusive (STUN probes failed); continuing");
-      }
-    })
-    .catch((error) => {
-      const message = error instanceof Error ? error.message : String(error);
-      logger.warn(`nat classification failed: ${message}`);
-    });
-
-  // Create tunnel + WebRTC manager.
-  // The tunnel forwards WebRTC signals between browser (via server) and this proxy.
-  // The WebRTC manager handles the actual peer connection and data channel.
-  //
-  // We use a late-binding ref so both objects can reference each other without
-  // running into the TDZ (tunnelClient is declared above; webRtcManager is the
-  // module-scoped `let` above so the closure in createTunnelClient — and the
-  // shutdown handler — can reach it after initialisation).
-
-  tunnelClient = createTunnelClient({
-    serverUrl,
-    proxyId: clientId,
-    token,
-    proxyPort: actualPort,
-    onSignal(sessionId, signal) {
-      webRtcManager?.handleSignal(sessionId, signal);
-    },
-    async onHealthRequest() {
-      // Which films this proxy holds travels with the health poll the browser
-      // already makes before it picks one: a viewer sent to a proxy that is
-      // downloading their film costs it the encode and nothing else, while the
-      // same viewer sent anywhere else starts the download from nothing. Asked
-      // of the worker, so a film this proxy let go of is not claimed.
-      let holds = [];
-      try {
-        holds = (await started?.torrentPool?.heldTorrents?.()) ?? [];
-      } catch {
-        // silent-ok: a proxy that cannot say what it holds is scored on its
-        // machine alone, which is what every proxy was scored on until now.
-      }
-      // WHETHER THIS MACHINE HAS ROOM FOR ONE MORE ENCODE, read by the pool
-      // before any film is chosen (roadmap item 97, step 14): what holds a
-      // place on it now, and the speed that leaves every output at. The load
-      // average cannot say this — an encoder admitted a moment ago has not
-      // raised it yet.
-      const encode = started?.outputParts?.admission?.headroom?.() ?? null;
-      return {
-        metrics: {
-          ...collectHealthMetrics({ availableMemoryBytes }),
-          ...(encode ? { encodeSpeedX: encode.encodeSpeedX, encodeOccupiedCostSec: encode.occupiedCostSec } : {})
-        },
-        holds
-      };
-    },
-    // Whether this host could sustain a file it has only been told about. The
-    // same arithmetic the first offer uses, against this host's own startup
-    // benchmarks — no torrent, no bytes, no ffmpeg — so the browser can ask
-    // every proxy in the pool and be sent to one that will work instead of
-    // being shown an error on the one it happened to land on.
-    onCanServeRequest(mediaInfo) {
-      return started?.outputParts?.quality?.predictOfferedHeights?.(mediaInfo) ?? null;
-    },
-    onConnect() {
-      // Re-register on every tunnel connect/reconnect so the server's
-      // in-memory store stays consistent after server restarts.
-      void registerClientSafe().catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        logger.error(`Re-registration after tunnel connect failed: ${message}`);
-      });
-      // Re-report the mapped endpoint on every (re)connect — the server's
-      // in-memory reachability state resets on restart, and the mapping may
-      // have completed before this connection existed.
-      const endpoint = portMapper?.getMappedEndpoint();
-      if (endpoint) {
-        tunnelClient?.sendEndpoint(endpoint);
-      }
-    },
-    onLog: (message) => logger.info(message)
-  });
-
-  dataChannelHandler = createDataChannelHandler({
-    proxyPort: actualPort,
-    onLog: (message) => logger.info(message),
-    // Who wants pushed subtitle cues for a file, by name. Late-bound like the
-    // rest: the registry lives on the manager, built inside `startProxyServer`
-    // with this handler already in hand. The transport gets opaque ids and
-    // never learns what a viewer is.
-    viewersWantingCues: (sourceKey, fileIndex) =>
-      started?.outputParts?.viewers?.wantingCues?.(sourceKey, fileIndex) ?? [],
-    // Lets a stuck send queue ask the transport what it is doing. Late-bound:
-    // the manager is created below, with this handler already in hand.
-    getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null,
-    // Records the wire when a queue stays wedged — how the rare one-way
-    // transmit death (roadmap item 10, 2026-08-24) gets its evidence.
-    witness: packetWitness,
-    usrsctpState: usrsctpStateReader,
-    // How large one data-channel message is. The wedge of 2026-09-12 arrived
-    // mid-message, and whether it depends on this size is the one thing no
-    // reading has settled — so it is measured rather than reasoned about.
-    sendChunkBytes: Number.parseInt(options.sendChunkBytes ?? "0", 10) || 0,
-    // Presence, from the one thing that knows it. Late-bound for the same
-    // reason as the transport snapshot above: the manager is built inside
-    // `startProxyServer`, with this handler already in hand.
-    onViewerPresent: (consumerId) => {
-      started?.outputParts?.viewers?.seen?.(consumerId);
-    },
-    onViewerGone: (consumerId, because) => {
-      void started?.outputParts?.lifecycle?.viewerHasGone?.(consumerId, because)
-        ?.catch?.((error) => {
-          const message = error instanceof Error ? error.message : String(error);
-          logger.warn(`could not let go of viewer ${consumerId}: ${message}`);
-        });
-    }
-  });
-
-  webRtcManager = createWebRtcManager({
-    // Single UDP port (UPnP-mapped above) shared by all sessions via a
-    // persistent ICE UDP mux listener, so the WebRTC path is reachable from the
-    // internet on one fixed port.
-    udpPort: webrtcUdpPort,
-    // Latest NAT classification — enables symmetric-NAT port prediction.
-    getNatInfo: () => natInfo,
-    sendSignal(sessionId, signal) {
-      tunnelClient?.sendSignal(sessionId, signal);
-    },
-    onDataChannel(sessionId, channel) {
-      dataChannelHandler.handleChannel(sessionId, channel);
-    },
-    onLog: (message) => logger.info(message)
-  });
-
-  tunnelClient.connect();
-
-  await registerWithRetry();
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  logger.error(message);
-  process.exit(1);
-}
-
-process.on("SIGINT", () => {
-  void shutdown("SIGINT");
-});
-
-process.on("SIGTERM", () => {
-  void shutdown("SIGTERM");
-});
+#!/usr/bin/env node
+/**
+ * @file CLI entry point for the torrent-tv proxy.
+ *
+ * Parses command-line arguments, starts the local HTTP server, opens a
+ * persistent WebSocket tunnel to the registry server, and registers this
+ * proxy. Liveness is tracked via the tunnel connection — the proxy re-registers
+ * automatically on reconnect so the server's in-memory store stays consistent.
+ */
+
+// FIRST, and it must stay first: it sets how many blocking calls this process
+// can have in flight, and a module's imports are evaluated before its body, so
+// anything imported above it would get the default pool. See the file itself
+// for the measurement that made it necessary.
+import "./thread-pool.js";
+import { Command } from "commander";
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import ffmpegStatic from "ffmpeg-static";
+import { startProxyServer } from "../server.js";
+import { registerClient } from "../services/transport/registry-api.js";
+import { createTunnelClient } from "../services/transport/tunnel-client.js";
+import { createWebRtcManager } from "../services/transport/webrtc-manager.js";
+import { createDataChannelHandler } from "../services/transport/data-channel-handler.js";
+import { dumpsToRemove, pruneCoreDumps } from "../services/storage/core-dumps.js";
+import { availableMemoryBytes } from "../services/storage/machine-memory.js";
+import { Diagnostics } from "../services/storage/Diagnostics.js";
+import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/transport/packet-witness.js";
+import { createUsrsctpStateReader } from "../services/transport/usrsctp-state.js";
+import { startMemoryReport } from "../services/storage/memory-report.js";
+import { fragmentBufferCollection } from "../services/torrent/worker/client.js";
+import { collectHealthMetrics } from "../services/transport/health-collector.js";
+import { createPortMapper } from "../services/transport/port-mapper.js";
+import { installationId } from "../services/identity/installation-id.js";
+import { classifyNat } from "../services/transport/nat-classifier.js";
+import { DEFAULT_SEGMENT_FORMAT_ID, SEGMENT_FORMAT_IDS } from "../services/encode/segment-formats/index.js";
+import { logToFile, logger } from "../utils/logger.js";
+
+const require = createRequire(import.meta.url);
+const { version: PROXY_VERSION } = require("../package.json");
+
+// Last-resort process guard. This proxy runs UNTRUSTED torrents through
+// WebTorrent, which can throw ASYNCHRONOUSLY on a malformed source — e.g. a
+// v2-only / hybrid magnet crashes `arr2hex(parsedTorrent.infoHash)` deep inside
+// `Torrent._onTorrentId` (undefined v1 infohash), in a microtask that bypasses
+// the client "error" event. Without this, one bad torrent takes down the whole
+// node and every viewer on it, and the addon restarts in a crash loop. Log the
+// full stack and keep serving: the offending session fails on its own; everyone
+// else is unaffected. (The add path also pre-validates the infohash, so this is
+// a backstop for anything not caught there.)
+process.on("uncaughtException", (error) => {
+  logger.error(`uncaughtException (kept alive): ${error?.stack ?? error}`);
+});
+process.on("unhandledRejection", (reason) => {
+  logger.error(`unhandledRejection (kept alive): ${reason instanceof Error ? reason.stack : String(reason)}`);
+});
+
+const program = new Command();
+
+const HELP_EXAMPLES = `
+Examples:
+  torrent-tv-proxy --server-url http://localhost:8080
+  torrent-tv-proxy --server-url http://localhost:8080 --host 0.0.0.0 --port 9090
+  torrent-tv-proxy --server-url http://localhost:8080 --public-base-url https://proxy.example.com
+  torrent-tv-proxy --server-url http://localhost:8080 --ffmpeg-bin /usr/local/bin/ffmpeg
+  torrent-tv-proxy --server-url http://localhost:8080 --no-transcode-audio
+
+Notes:
+  - --help prints this message and exits with code 0.
+  - Video transcode is available automatically for per-session fallback when requested by client API.
+`;
+
+if (process.argv.includes("help")) {
+  process.argv = [process.argv[0], process.argv[1], "--help"];
+}
+
+program
+  .name("torrent-proxy-client")
+  .description("Expose torrent files over HTTP stream endpoints for browser playback.")
+  .requiredOption("--server-url <url>", "Registry server base URL")
+  .option("--public-base-url <url>", "Direct URL advertised to browser clients")
+  .option("--host <host>", "Local bind host", "127.0.0.1")
+  .option("--port <port>", "Local HTTP port", "9090")
+  .option("--id <id>", "Stable client id")
+  .option("--name <name>", "Display name")
+  .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
+  .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
+  .option("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
+  .option(
+    "--send-chunk-bytes <bytes>",
+    "Size of one data-channel message when sending a response body (0 = whatever the body read hands over, ~64KB). For measuring whether the delivery wedge depends on that size."
+  )
+  .option(
+    "--usrsctp-state",
+    "Read usrsctp's association state with gdb when a wedge is declared. OFF by default: gdb attaches to THIS process and stops every thread of it while it works."
+  )
+  .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
+  .option("--budget <kind>", "How much of this machine the proxy may take: adaptive (default), share or fixed")
+  .option("--budget-share <fraction>", "With --budget share: the fraction of what is free, 0..1")
+  .option("--budget-bytes <bytes>", "With --budget fixed: the ceiling, per resource")
+  .option("--min-memory-bytes <bytes>", "Least memory this proxy should have, whatever the policy says")
+  .option("--min-disk-bytes <bytes>", "Least disk this proxy should have, whatever the policy says")
+  .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
+  .option(
+    "--state-dir <path>",
+    "Where to keep what this host has measured about itself (default: beside the installed proxy)"
+  )
+  .option(
+    "--log-file <path>",
+    "Also write the log to this file, so a crash or an update does not take it with them"
+  )
+  .option(
+    "--segment-format <format>",
+    `HLS output container: ${SEGMENT_FORMAT_IDS.join(" | ")}`,
+    DEFAULT_SEGMENT_FORMAT_ID
+  )
+  .option("--token <token>", "Registration token", "")
+  .addHelpText("after", HELP_EXAMPLES);
+
+program.parse(process.argv);
+const options = program.opts();
+
+const localPort = Number(options.port);
+if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
+  logger.error("Invalid --port value.");
+  process.exit(1);
+}
+
+const serverUrl = String(options.serverUrl).replace(/\/+$/, "");
+const bindHost = String(options.host);
+const explicitBaseUrl = options.publicBaseUrl
+  ? String(options.publicBaseUrl).replace(/\/+$/, "")
+  : "";
+const clientId = installationId({ stateDir: options.stateDir, explicitId: options.id });
+const clientName = options.name ? String(options.name) : `proxy-${clientId.slice(0, 8)}`;
+const token = String(options.token ?? "");
+const transcodeAudio = options.transcodeAudio !== false;
+const portMappingEnabled = options.portMapping !== false;
+// WHAT THE OPERATOR HAS SAID WE MAY TAKE, and the only numbers in this proxy
+// that are chosen rather than derived — because they are chosen by the person
+// whose machine it is. The default is the measured one: what is free now, plus
+// what we already hold, less what everything that is not us has been seen to
+// need. `share` and `fixed` are the owner naming a number instead; the floors
+// are the owner saying "below this it is not worth running".
+//
+// One policy, applied to every resource. Memory and disk are divided apart
+// because they cannot pay for each other, but by ONE owner, because the
+// claimants trade across them: pieces that do not fit in memory are spilled to
+// disk, so what memory is given decides how much disk is needed.
+const budgetFloors = {};
+if (Number.isFinite(Number(options.minMemoryBytes))) {
+  budgetFloors.memory = Number(options.minMemoryBytes);
+}
+const budgetPolicy = {
+  kind: ["adaptive", "share", "fixed"].includes(String(options.budget)) ? String(options.budget) : "adaptive",
+  share: Number(options.budgetShare),
+  bytes: Number(options.budgetBytes),
+  floors: budgetFloors,
+  // Named apart from the per-resource floors because the disk is one resource
+  // per DEVICE and the operator names one figure for all of them.
+  diskFloorBytes: Number.isFinite(Number(options.minDiskBytes)) ? Number(options.minDiskBytes) : 0
+};
+
+// Per-torrent memory budget for resident pieces. Pieces past it spill to disk
+// rather than being lost, so a small value costs read latency, never data.
+const memoryBytes =
+  options.memoryBytes !== undefined && Number.isFinite(Number(options.memoryBytes)) && Number(options.memoryBytes) > 0
+    ? Number(options.memoryBytes)
+    : undefined;
+const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
+const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
+
+/**
+ * Verify that the ffmpeg binary is reachable and exits cleanly.
+ * Throws with a descriptive message when the check fails.
+ *
+ * @returns {void}
+ */
+function assertFfmpegAvailability() {
+  const probe = spawnSync(ffmpegBin, ["-version"], {
+    stdio: "ignore",
+    windowsHide: true,
+    timeout: 5000
+  });
+  if (probe.error) {
+    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
+    throw new Error(`Audio transcode is enabled, but ffmpeg is unavailable (${ffmpegBin}): ${message}`);
+  }
+  if (typeof probe.status === "number" && probe.status !== 0) {
+    throw new Error(
+      `Audio transcode is enabled, but ffmpeg check failed (${ffmpegBin}, exit code ${probe.status}).`
+    );
+  }
+}
+
+/** @type {boolean} */
+let registrationInProgress = false;
+
+/** @type {import("fastify").FastifyInstance | null} */
+let app = null;
+
+/** @type {number} */
+let actualPort = localPort;
+
+/** @type {boolean} */
+let shutdownInProgress = false;
+
+/** @type {ReturnType<typeof createTunnelClient> | null} */
+let tunnelClient = null;
+
+/** @type {ReturnType<typeof createPortMapper> | null} */
+let portMapper = null;
+
+/** @type {ReturnType<typeof createPortMapper> | null} UDP mapping for the WebRTC port. */
+let udpPortMapper = null;
+
+/** @type {ReturnType<typeof createWebRtcManager> | null} */
+let webRtcManager = null;
+/**
+ * The packet witness, so shutdown can stop the ring it owns.
+ *
+ * @type {ReturnType<typeof createPacketWitness> | null}
+ */
+let packetWitness = null;
+
+/** @type {ReturnType<typeof createUsrsctpStateReader> | null} */
+let usrsctpStateReader = null;
+
+/** @type {ReturnType<typeof createDataChannelHandler> | null} */
+let dataChannelHandler = null;
+
+/** @type {import("../services/transport/nat-classifier.js").NatClassification | null} Latest NAT classification (for WebRTC port prediction). */
+let natInfo = null;
+
+
+/**
+ * Register this proxy with the registry server.
+ * Silently skips if a registration is already in flight.
+ *
+ * @returns {Promise<void>}
+ */
+async function registerClientSafe() {
+  if (registrationInProgress) {
+    return;
+  }
+  registrationInProgress = true;
+  try {
+    const result = await registerClient({
+      serverUrl,
+      id: clientId,
+      name: clientName,
+      baseUrl: explicitBaseUrl || `http://${bindHost}:${actualPort}`,
+      token
+    });
+    logger.success(`Registered as "${result.client?.name}" (${result.client?.id?.slice(0, 8)})`);
+  } finally {
+    registrationInProgress = false;
+  }
+}
+
+/**
+ * Register this proxy with the registry server, retrying indefinitely
+ * with exponential backoff until it succeeds. This allows the proxy to
+ * survive temporary server outages (restarts, deployments) without crashing.
+ *
+ * @returns {Promise<void>}
+ */
+async function registerWithRetry() {
+  const MAX_DELAY_MS = 60_000;
+  let delayMs = 2_000;
+  let attempt = 0;
+  while (true) {
+    attempt++;
+    try {
+      await registerClientSafe();
+      return;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`Registration attempt ${attempt} failed: ${message}. Retrying in ${delayMs / 1000}s…`);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
+    }
+  }
+}
+
+/**
+ * Gracefully shut down the tunnel, heartbeat timer, and HTTP server.
+ *
+ * @param {string} signal - Signal name (e.g. "SIGINT").
+ * @returns {Promise<void>}
+ */
+async function shutdown(signal) {
+  if (shutdownInProgress) {
+    return;
+  }
+  shutdownInProgress = true;
+  if (tunnelClient) {
+    tunnelClient.disconnect();
+    tunnelClient = null;
+  }
+  logger.warn(`Received ${signal}, shutting down...`);
+  try {
+    // Remove the router port mappings before exiting (lease expiry is the
+    // backstop if this is skipped on a hard kill).
+    if (portMapper) {
+      await portMapper.stop();
+      portMapper = null;
+    }
+    if (udpPortMapper) {
+      await udpPortMapper.stop();
+      udpPortMapper = null;
+    }
+    // Close WebRTC sessions and release the shared UDP mux listener socket.
+    if (webRtcManager) {
+      try { webRtcManager.dispose(); } catch { /* ignore */ }
+      webRtcManager = null;
+    }
+    // Stop the packet ring and remove its scratch files. `process.exit` below
+    // does not take child processes with it, so without this a proxy restarted
+    // outside a container leaves one tcpdump running per restart.
+    if (packetWitness) {
+      try { await packetWitness.dispose(); } catch { /* ignore */ }
+      packetWitness = null;
+    }
+    if (app) {
+      await app.close();
+    }
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Shutdown failed: ${message}`);
+    process.exit(1);
+  }
+}
+
+// WHAT THE EVIDENCE WEIGHS, and what it may weigh. Core dumps, heap snapshots
+// and packet captures were each bounded by a COUNT and none by a size — two
+// dumps and five snapshots came to 3.2 GB on the addon host. One object, built
+// here where the collectors are, registered with the owner of the disk inside
+// the server and consulted by each collector before it writes.
+const diagnostics = new Diagnostics({
+  logger,
+  kinds: [
+    { name: "core dumps", directory: () => options.stateDir || "", matches: (name) => name.startsWith("core.") },
+    {
+      name: "heap snapshots",
+      directory: () => options.stateDir || "",
+      matches: (name) => name.endsWith(".heapsnapshot")
+    },
+    {
+      name: "packet captures",
+      directory: () => options.stateDir || "",
+      matches: (name) => name.startsWith("packet-witness")
+    }
+  ]
+});
+
+try {
+  logToFile(options.logFile);
+  if (transcodeAudio) {
+    assertFfmpegAvailability();
+  }
+  const started = await startProxyServer({
+    host: bindHost,
+    port: localPort,
+    transcodeAudio,
+    ffmpegBin,
+    memoryBytes,
+    segmentFormat: options.segmentFormat,
+    stateDir: options.stateDir,
+    diagnostics,
+    budgetPolicy,
+    logFile: options.logFile ?? "",
+    deliverySink: options.deliverySink === true,
+    // Late-bound the same way `webRtcManager` is below: the torrent pool is
+    // built inside `startProxyServer`, before `dataChannelHandler` — the
+    // thing that actually owns a channel to push down — exists.
+    onSubtitleCues: (event) => dataChannelHandler?.publishSubtitleCues(event)
+  });
+  app = started.app;
+  actualPort = started.port;
+  const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
+
+  // A native fault writes the whole address space out — 4.18 GB each on the
+  // field host, and four of them nearly filled a 235 GB disk. Keep the newest
+  // two, which are the evidence for the fault still open, and drop the rest.
+  void pruneCoreDumps(options.stateDir);
+  // Same policy for the packet captures the send-queue witness writes.
+  packetWitness = createPacketWitness({
+    log: (message) => logger.info(message),
+    dir: options.stateDir || "",
+    port: actualPort,
+    // Evidence takes room from the product, so a capture is asked for rather
+    // than taken. Refused, it is a line and not a silence.
+    mayKeep: (bytes) => diagnostics.mayKeep({ what: "a packet capture", bytes }),
+    // Which of the kept captures go is the storage component's rule, the same
+    // one core dumps are pruned by.
+    chooseRemovals: dumpsToRemove
+  });
+  // A process that was KILLED mid-session leaves the ring's last seconds
+  // behind, and those seconds contain whatever ended it. Keep them under a name
+  // the pruner recognises BEFORE anything starts a new ring over them.
+  void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir, dumpsToRemove));
+
+  // Reads usrsctp's own association state via gdb the moment a wedge is
+  // declared (roadmap item 11) — no source rebuild, the module ships
+  // unstripped. A host without gdb just never gets a reading, the same way a
+  // host without tcpdump never gets a packet capture.
+  // OFF UNLESS ASKED FOR, and the reason is a field incident rather than
+  // caution. On 2026-09-05 a delivery probe declared a wedge that lasted half a
+  // second and cleared itself; the reading it triggered attached gdb to this
+  // process, which stopped all eighty of its threads. The log ended mid-second,
+  // /healthz stopped answering, and the viewer waited a minute and was told the
+  // proxy had sent no video. The fifteen-second guard could not fire — it is a
+  // timer inside the process gdb had stopped — and killing gdb left the main
+  // thread deadlocked for good, so only restarting the addon recovered it.
+  //
+  // A means of diagnosis may not stop the product. This one attaches to a live
+  // process and is triggered by a verdict with a known history of false
+  // positives, so it is a thing to switch on deliberately while watching, not
+  // something that arms itself.
+  usrsctpStateReader = options.usrsctpState === true
+    ? createUsrsctpStateReader({ log: (message) => logger.info(message) })
+    : null;
+
+  // What this process holds, once a minute. The kernel killed the proxy on
+  // 2026-08-28 at 2.4 GB resident and the log had never said a word about
+  // memory, so the growth that ended in that kill has no shape in any record we
+  // keep. RSS is the figure the OOM killer reads, so RSS is the figure to say.
+  // The disk path is where pieces spill and torrent data lands. A budget for
+  // memory alone is half a budget: a store that behaves about RAM can still
+  // fill the card an addon host boots from, and neither limit was measured
+  // before (roadmap item 2).
+  startMemoryReport({
+    log: (message) => logger.info(message),
+    // A snapshot weighs about what the heap weighs. Asked for, not taken.
+    mayKeep: (bytes) => diagnostics.mayKeep({ what: "a heap snapshot", bytes }),
+    // The other half of the piece-buffer question. Shared memory lives until
+    // BOTH isolates let go, so the worker's own count answers only its side;
+    // read here, on the same line as the process figures the growth shows up
+    // in and at the same instant as them.
+    readExtra: () => {
+      const fragments = fragmentBufferCollection();
+      return fragments.seen === 0
+        ? ""
+        : `piece buffers handed here ${fragments.seen} seen, ${fragments.collected} collected, ` +
+          `${fragments.seen - fragments.collected} still alive`;
+    },
+    // Once a minute cannot see what kills this process. Both out-of-memory
+    // kills of 2026-09-02 happened inside a single gap of the old cadence: the
+    // last line before the first said 602 MB and the kernel measured 1.72 GB
+    // 34 seconds later, and before the second it said 1171 MB and the kernel
+    // measured 1.86 GB nine seconds later. The figure is read every second
+    // now and written when it has moved by a step worth a line, so a rise of a
+    // gigabyte is a curve instead of one number and then a death. Every /proc
+    // read stayed behind the decision to write, so a quiet second costs one
+    // call to `process.memoryUsage()`.
+    intervalMs: 1_000,
+    quietMs: 60_000,
+    changeBytes: 25 * 1024 * 1024,
+    diskPath: os.tmpdir(),
+    // WHERE A SNAPSHOT SURVIVES THE PROCESS IT IS ABOUT, and how many are kept
+    // — the same answer the torrent worker already had. This scope had neither:
+    // snapshots went to the temporary directory, which the container recreates
+    // on every restart, and all of them were kept. Fifty-four were written on
+    // 2026-09-07 and every one was gone by the time the process that wrote them
+    // died of a heap it had never been possible to look at.
+    snapshotDir: options.stateDir || undefined,
+    snapshotFloorBytes: 400 * 1024 * 1024,
+    snapshotGrowthBytes: 400 * 1024 * 1024,
+    keepSnapshots: 3
+  });
+
+  logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
+  logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
+  logger.info(`Advertised direct URL: ${directBaseUrl}`);
+  if (transcodeAudio) {
+    logger.info(`Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`);
+  }
+
+  // All WebRTC sessions are multiplexed onto this single UDP port (same number
+  // as the HTTP port, different protocol) via a persistent ICE UDP mux listener
+  // in the WebRTC manager. One port → one UPnP mapping → one reachable endpoint.
+  const webrtcUdpPort = actualPort;
+
+  // Try to open the local port on the home router (UPnP/NAT-PMP) so the proxy
+  // is reachable from the internet without manual port forwarding. Best-effort
+  // and fire-and-forget: failure is normal (router without UPnP) and must not
+  // delay tunnel connect / registration, so we do not await it.
+  if (portMappingEnabled) {
+    portMapper = createPortMapper({ port: actualPort, protocol: "TCP" });
+    void portMapper
+      .start()
+      .then(() => {
+        // Mapping may finish after the tunnel is already connected; report the
+        // endpoint now. If the tunnel is not open yet, onConnect re-sends it.
+        const endpoint = portMapper?.getMappedEndpoint();
+        if (endpoint) {
+          tunnelClient?.sendEndpoint(endpoint);
+        }
+      })
+      .catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`Port mapping failed to start: ${message}`);
+      });
+
+    // Also map the single WebRTC UDP port. Not reported to the server: the
+    // browser discovers the endpoint via ICE (srflx) candidates, not the TCP
+    // dial-back probe.
+    udpPortMapper = createPortMapper({
+      port: webrtcUdpPort,
+      protocol: "UDP",
+      description: "torrent-tv proxy (WebRTC)"
+    });
+    void udpPortMapper.start().catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`UDP port mapping failed to start: ${message}`);
+    });
+  } else {
+    logger.info("Automatic port mapping is disabled (--no-port-mapping).");
+  }
+
+  // Classify the home NAT (diagnostic + decides whether WebRTC will need port
+  // prediction for remote viewers). Best-effort, fire-and-forget — STUN probes
+  // never block startup.
+  void classifyNat()
+    .then((nat) => {
+      // Stored for WebRTC port prediction (webRtcManager reads it per session).
+      natInfo = nat;
+      if (nat.klass === "endpoint-independent") {
+        logger.info(
+          `nat: endpoint-independent (cone) — external UDP port stable across STUN servers (${nat.externalIp}); fixed-port WebRTC mapping is sufficient, no port prediction needed`
+        );
+      } else if (nat.klass === "symmetric") {
+        logger.warn(
+          `nat: SYMMETRIC — external UDP port varies per destination (delta ${nat.portDelta}); WebRTC offers predicted ports (base+delta*k) — covers sequential/predictable symmetric NAT, not fully random`
+        );
+      } else {
+        logger.info("nat: classification inconclusive (STUN probes failed); continuing");
+      }
+    })
+    .catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.warn(`nat classification failed: ${message}`);
+    });
+
+  // Create tunnel + WebRTC manager.
+  // The tunnel forwards WebRTC signals between browser (via server) and this proxy.
+  // The WebRTC manager handles the actual peer connection and data channel.
+  //
+  // We use a late-binding ref so both objects can reference each other without
+  // running into the TDZ (tunnelClient is declared above; webRtcManager is the
+  // module-scoped `let` above so the closure in createTunnelClient — and the
+  // shutdown handler — can reach it after initialisation).
+
+  tunnelClient = createTunnelClient({
+    serverUrl,
+    proxyId: clientId,
+    token,
+    proxyPort: actualPort,
+    onSignal(sessionId, signal) {
+      webRtcManager?.handleSignal(sessionId, signal);
+    },
+    async onHealthRequest() {
+      // Which films this proxy holds travels with the health poll the browser
+      // already makes before it picks one: a viewer sent to a proxy that is
+      // downloading their film costs it the encode and nothing else, while the
+      // same viewer sent anywhere else starts the download from nothing. Asked
+      // of the worker, so a film this proxy let go of is not claimed.
+      let holds = [];
+      try {
+        holds = (await started?.torrentPool?.heldTorrents?.()) ?? [];
+      } catch {
+        // silent-ok: a proxy that cannot say what it holds is scored on its
+        // machine alone, which is what every proxy was scored on until now.
+      }
+      // WHETHER THIS MACHINE HAS ROOM FOR ONE MORE ENCODE, read by the pool
+      // before any film is chosen (roadmap item 97, step 14): what holds a
+      // place on it now, and the speed that leaves every output at. The load
+      // average cannot say this — an encoder admitted a moment ago has not
+      // raised it yet.
+      const encode = started?.outputParts?.admission?.headroom?.() ?? null;
+      return {
+        metrics: {
+          ...collectHealthMetrics({ availableMemoryBytes }),
+          ...(encode ? { encodeSpeedX: encode.encodeSpeedX, encodeOccupiedCostSec: encode.occupiedCostSec } : {})
+        },
+        holds
+      };
+    },
+    // Whether this host could sustain a file it has only been told about. The
+    // same arithmetic the first offer uses, against this host's own startup
+    // benchmarks — no torrent, no bytes, no ffmpeg — so the browser can ask
+    // every proxy in the pool and be sent to one that will work instead of
+    // being shown an error on the one it happened to land on.
+    onCanServeRequest(mediaInfo) {
+      return started?.outputParts?.quality?.predictOfferedHeights?.(mediaInfo) ?? null;
+    },
+    onConnect() {
+      // Re-register on every tunnel connect/reconnect so the server's
+      // in-memory store stays consistent after server restarts.
+      void registerClientSafe().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`Re-registration after tunnel connect failed: ${message}`);
+      });
+      // Re-report the mapped endpoint on every (re)connect — the server's
+      // in-memory reachability state resets on restart, and the mapping may
+      // have completed before this connection existed.
+      const endpoint = portMapper?.getMappedEndpoint();
+      if (endpoint) {
+        tunnelClient?.sendEndpoint(endpoint);
+      }
+    },
+    onLog: (message) => logger.info(message)
+  });
+
+  dataChannelHandler = createDataChannelHandler({
+    proxyPort: actualPort,
+    onLog: (message) => logger.info(message),
+    // Who wants pushed subtitle cues for a file, by name. Late-bound like the
+    // rest: the registry lives on the manager, built inside `startProxyServer`
+    // with this handler already in hand. The transport gets opaque ids and
+    // never learns what a viewer is.
+    viewersWantingCues: (sourceKey, fileIndex) =>
+      started?.outputParts?.viewers?.wantingCues?.(sourceKey, fileIndex) ?? [],
+    // Lets a stuck send queue ask the transport what it is doing. Late-bound:
+    // the manager is created below, with this handler already in hand.
+    getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null,
+    // Records the wire when a queue stays wedged — how the rare one-way
+    // transmit death (roadmap item 10, 2026-08-24) gets its evidence.
+    witness: packetWitness,
+    usrsctpState: usrsctpStateReader,
+    // How large one data-channel message is. The wedge of 2026-09-12 arrived
+    // mid-message, and whether it depends on this size is the one thing no
+    // reading has settled — so it is measured rather than reasoned about.
+    sendChunkBytes: Number.parseInt(options.sendChunkBytes ?? "0", 10) || 0,
+    // Presence, from the one thing that knows it. Late-bound for the same
+    // reason as the transport snapshot above: the manager is built inside
+    // `startProxyServer`, with this handler already in hand.
+    onViewerPresent: (consumerId) => {
+      started?.outputParts?.viewers?.seen?.(consumerId);
+    },
+    onViewerGone: (consumerId, because) => {
+      void started?.outputParts?.lifecycle?.viewerHasGone?.(consumerId, because)
+        ?.catch?.((error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          logger.warn(`could not let go of viewer ${consumerId}: ${message}`);
+        });
+    }
+  });
+
+  webRtcManager = createWebRtcManager({
+    // Single UDP port (UPnP-mapped above) shared by all sessions via a
+    // persistent ICE UDP mux listener, so the WebRTC path is reachable from the
+    // internet on one fixed port.
+    udpPort: webrtcUdpPort,
+    // Latest NAT classification — enables symmetric-NAT port prediction.
+    getNatInfo: () => natInfo,
+    sendSignal(sessionId, signal) {
+      tunnelClient?.sendSignal(sessionId, signal);
+    },
+    onDataChannel(sessionId, channel) {
+      dataChannelHandler.handleChannel(sessionId, channel);
+    },
+    onLog: (message) => logger.info(message)
+  });
+
+  tunnelClient.connect();
+
+  await registerWithRetry();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  logger.error(message);
+  process.exit(1);
+}
+
+process.on("SIGINT", () => {
+  void shutdown("SIGINT");
+});
+
+process.on("SIGTERM", () => {
+  void shutdown("SIGTERM");
+});