@torrent-tv/proxy 2.36.0 → 2.36.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.36.2
+
+- **Fix**: A live session no longer answers 404 to the master playlist it has just published. The browser is handed `master.m3u8` when the session is created, and which rungs are worth OFFERING is recomputed every five seconds — so on 2026-08-18 a five-rung offer became a one-rung offer **192 ms** after creation (the session's own encoder started, charging the contention penalty of 2.35.0, and the first supply reading raised the bar of 2.36.0 from 1.00x to 1.06x), `buildMasterPlaylist` returned null for having fewer than two rungs, and the master answered 404. hls.js treats that as fatal and unrecoverable, so nothing played at all. The master now lists what CAN be spliced onto this session's cut grid — a fact about the source, settled once — while the live judgement stays where it belongs, in `offeredHeights` and in every progress report, which is what the viewer's menu already follows. The variant routes honour the published set too, so a quality switch can no longer meet a 404 on a rung the master named.
+- **Fix**: Peer discovery no longer starves behind name resolution. Node resolves host names on the libuv thread pool, which holds four threads by default; a torrent announces to every tracker in its file at once, so four names resolve and the rest queue — and a tracker that no longer exists holds its thread for the resolver's full ten-second timeout while every announce behind it blows its own fifteen-second deadline. Measured inside the addon container: the ten trackers of one film took **7.58 s** to resolve as a burst and **27-42 ms** each with a larger pool. That film has 517 seeders on a tracker that answers in 50 ms, and it spent eleven minutes with **zero peers** while four other torrents in the same process were fine — they were the ones whose live trackers happened to fall in the first four. The pool is now stated before anything can create it (`services/thread-pool.js`, imported first by the entry point), and a deployment that states its own size is left alone.
+
+## 2.36.1
+
+- **Fix**: The cut list of a copied picture is built from the picture's own keyframes, and no longer from every entry in the container's table. A Matroska CuePoint belongs to the track named inside it, and RFC 9559 leaves the muxer free to index whichever tracks it likes — both field files index their subtitles as well. Measured over the swarm on 2026-08-18, reading only the head and the table: `Minions.and.Monsters.1080p.mkv` has **2778 video entries, one every 2.002 s, and 4669 more across four subtitle tracks**; `Moana.2.2024.720p.BluRay … MegaPeer.mkv` has **1055 video entries and 5007 across five**. Read without the track, the extra times entered the cut list as though they were keyframes; ffmpeg can only cut a copied picture at a real keyframe at or after the time it is given, so each such cut landed at the next one instead — which is exactly the disagreement the field measured, and why it was always positive: 2.002 s on the first file (its own keyframe spacing), a median of 6.3 s and a worst case of 21 s on the second. The reader now takes the first video track's number from Tracks — already inside the head it fetches, with one short extra read only for a file that keeps Tracks elsewhere — and keeps the entries of that track. Nothing else about the two-read approach changes, and a session costs nothing more. With the fix the same two files read 2778 and 1055 times, all of them keyframes. When the filter leaves NOTHING — a table whose entries name a track number Tracks never declares — the unfiltered table is used rather than no table: that case is this reader failing to recognise the file, and answering with nothing would put an even grid on a copied picture, which is the failure it exists to prevent.
+- **Chore**: `scripts/read-container-index.mjs` reads the index of any `.torrent` over the swarm — two short ranged reads, in memory, no file written — so a claim about what a container says can be checked against a real film in seconds. Written after the measurement above was made by hand three times.
+
 ## 2.36.0
 
 - **New**: The torrent is charged for the megabytes it is measured to be moving, and the price it is charged at no longer contains work that is not the torrent's. Two faults, both visible in one field log from the addon host (2026-08-18): the same session reported **145.4 ms of CPU per MB over 8.7 MB and 23.1 ms per MB over 54 MB**, a sixfold disagreement that followed the size of the interval rather than anything about the torrent — because a process with nothing to do still runs its timers, its tunnel and its session sweeps, and that draw does not shrink when fewer megabytes move. A minimum-megabytes threshold stood against exactly this and did not hold, because a chosen number was standing in for a measured one. The draw is now measured directly, in the intervals where nothing encodes and not one byte moves, and subtracted before the rest is called the torrent's (`services/torrent-cost.js`). What the threshold was reaching for is arrived at from the readings instead: the draw's own readings disagree by a measured amount, that disagreement is worth `scatter × elapsed` seconds over an interval, and a remainder smaller than it measures the wobble in the subtraction rather than the torrent — so a small interval fails on the same arithmetic that lets a large one through, with no size chosen anywhere. The second fault: the price was then charged against the file's own byte rate — what the viewer consumes — so a fully downloaded file moving nothing still paid, and a file being fetched ahead of the viewer, which is how every session starts, paid too little. It is charged against the rate the torrent is measured to be moving, sampled every five seconds per watched torrent and divided among the files of it being read, so two episodes of one pack do not each pay for the whole download.

package/bin/cli.js

@@ -8,6 +8,11 @@
  * 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 "../services/thread-pool.js";
 import { Command } from "commander";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.36.0",
+  "version": "2.36.2",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/scripts/read-container-index.mjs

@@ -0,0 +1,108 @@
+/**
+ * @file What this proxy would cut a file at, read from a real torrent.
+ *
+ * The keyframe readers take two short ranged reads, so the index of a 7 GB film
+ * can be examined over the swarm in seconds without downloading it. Run against
+ * a `.torrent` file to see what the container's own table says, per track, and
+ * what the reader hands to the cut list.
+ *
+ *   node scripts/read-container-index.mjs path/to/film.torrent [more.torrent …]
+ *
+ * Developer tool: nothing here runs in a session, and no viewer is involved.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import MemoryChunkStore from "memory-chunk-store";
+import WebTorrent from "webtorrent";
+import { readMatroskaKeyframeTimes } from "../services/container-index/matroska.js";
+import { readMp4KeyframeTimes } from "../services/container-index/mp4.js";
+import { readAviKeyframeTimes } from "../services/container-index/avi.js";
+
+const torrents = process.argv.slice(2);
+if (torrents.length === 0) {
+  console.error("usage: node scripts/read-container-index.mjs <file.torrent> [...]");
+  process.exit(1);
+}
+
+/**
+ * Collect one byte range of a torrent file.
+ *
+ * @param {import("webtorrent").TorrentFile} file
+ * @param {number} start
+ * @param {number} end - Inclusive.
+ * @returns {Promise<Buffer>}
+ */
+function readRangeOf(file, start, end) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const stream = file.createReadStream({ start, end });
+    stream.on("data", (chunk) => chunks.push(chunk));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+
+/**
+ * Say what a set of times looks like: how many, where it starts, how far apart.
+ *
+ * @param {string} label
+ * @param {number[] | null} times
+ * @returns {void}
+ */
+function describe(label, times) {
+  if (!times || times.length === 0) {
+    console.log(`${label}: no index`);
+    return;
+  }
+  const gaps = times.slice(1).map((time, index) => time - times[index]).sort((left, right) => left - right);
+  const median = gaps.length > 0 ? gaps[Math.floor(gaps.length / 2)] : 0;
+  console.log(
+    `${label}: ${times.length} times, first ${times.slice(0, 4).map((time) => time.toFixed(3)).join(" ")}, ` +
+    `median gap ${median.toFixed(3)}s, last ${times[times.length - 1].toFixed(3)}`
+  );
+}
+
+for (const torrentPath of torrents) {
+  // uTP is off: binding its socket needs a permission this does not have on
+  // every developer machine, and TCP peers are enough to read an index.
+  const client = new WebTorrent({ utp: false });
+  console.log(`\n=== ${path.basename(torrentPath)} ===`);
+  await new Promise((resolve) => {
+    // In memory, deliberately. The file store creates the whole file on disk at
+    // its full length before a byte of it is wanted — reading the index of four
+    // films that way filled 34 GB and then failed with the disk full. Only two
+    // short ranges are ever read here, so they can simply be held.
+    client.add(fs.readFileSync(torrentPath), { store: MemoryChunkStore }, async (torrent) => {
+      try {
+        // Nothing is wanted up front; the ranged reads below select what they need.
+        torrent.deselect(0, torrent.pieces.length - 1, 0);
+        const file = torrent.files
+          .filter((candidate) => /\.(mkv|mp4|avi)$/i.test(candidate.name))
+          .sort((left, right) => right.length - left.length)[0];
+        if (!file) {
+          console.log("no video file in this torrent");
+          return resolve();
+        }
+        console.log(`file: ${file.name} (${(file.length / 1e9).toFixed(2)} GB)`);
+        const readRange = async (start, end) => {
+          const last = Math.min(end, file.length - 1);
+          return start > last ? null : readRangeOf(file, start, last);
+        };
+        if (/\.mkv$/i.test(file.name)) {
+          describe("matroska", await readMatroskaKeyframeTimes(readRange, file.length));
+        } else if (/\.mp4$/i.test(file.name)) {
+          describe("mp4", await readMp4KeyframeTimes(readRange, file.length));
+        } else {
+          describe("avi", await readAviKeyframeTimes(readRange, file.length));
+        }
+      } catch (error) {
+        console.log(`failed: ${error?.message ?? error}`);
+      } finally {
+        resolve();
+      }
+    });
+  });
+  await new Promise((done) => client.destroy(done));
+}
+process.exit(0);

package/services/container-index/matroska.js

@@ -28,6 +28,14 @@ const ID_TIMESTAMP_SCALE = 0x2ad7b1;
 const ID_CUES = 0x1c53bb6b;
 const ID_CUE_POINT = 0xbb;
 const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+// TrackType 1 is video; 2 is audio, 17 subtitles, and the rest are rarer still.
+const TRACK_TYPE_VIDEO = 1;
 
 // How much of the file start to read. Must cover the EBML header, the SeekHead
 // and Info; 64 KB is generous for every real muxer (the file measured needed
@@ -36,6 +44,10 @@ const HEAD_BYTES = 64 * 1024;
 // Cap on the Cues read. A two-hour film indexes to tens of KB; anything beyond
 // this is not a normal index and not worth pulling over a torrent.
 const MAX_CUES_BYTES = 8 * 1024 * 1024;
+// Cap on a Tracks read, for the rare file whose Tracks element sits outside the
+// head window. Track entries are small, so a file with dozens of them still
+// fits well inside this.
+const MAX_TRACKS_BYTES = 1024 * 1024;
 // Matroska's default timestamp scale (nanoseconds per tick) when Info omits it.
 const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
 
@@ -121,13 +133,64 @@ function readTimestampScale(head, segmentDataOffset) {
 }
 
 /**
- * Cue times (seconds, ascending) from a Cues payload.
+ * The number of the first video track, from a Tracks payload.
+ *
+ * The FIRST one, because that is the track ffmpeg is told to copy (`0:v:0`).
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, size: number }} tracks
+ * @returns {number | null}
+ */
+function readVideoTrackNumber(buffer, tracks) {
+  const tracksEnd = Math.min(buffer.length, tracks.dataOffset + tracks.size);
+  for (const entry of iterateElements(buffer, tracks.dataOffset, tracksEnd)) {
+    if (entry.id !== ID_TRACK_ENTRY) {
+      continue;
+    }
+    const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
+    let number = null;
+    let type = null;
+    for (const field of iterateElements(buffer, entry.dataOffset, entryEnd)) {
+      if (field.id === ID_TRACK_NUMBER) {
+        number = readUint(buffer, field.dataOffset, field.size);
+      } else if (field.id === ID_TRACK_TYPE) {
+        type = readUint(buffer, field.dataOffset, field.size);
+      }
+    }
+    if (number !== null && type === TRACK_TYPE_VIDEO) {
+      return number;
+    }
+  }
+  return null;
+}
+
+/**
+ * Cue times (seconds, ascending) of ONE track, from a Cues payload.
+ *
+ * The track is the whole point, and leaving it out is what this reader got
+ * wrong until 2026-08-18. A CuePoint belongs to the track named inside its
+ * CueTrackPositions, and a muxer indexes whatever tracks it likes: RFC 9559
+ * says each keyframe of a video track SHOULD be referenced, and that the Cues
+ * Element "can be used to index every single timestamp of every Block or they
+ * can be indexed selectively". Both field files index their SUBTITLE tracks as
+ * well — `Minions.and.Monsters.1080p.mkv` has 2778 video entries every 2.002 s
+ * plus 4669 across four subtitle tracks; `Moana.2 … MegaPeer.mkv` has 1055
+ * video entries plus 5007 across five.
+ *
+ * Read without the track, those extra times enter the cut list as though they
+ * were keyframes. ffmpeg can only cut a COPIED picture at a real keyframe at or
+ * after the time it is given, so every cut asked for at one of them lands late
+ * — which is exactly what the field measured: on the first file every deviation
+ * was 2.002 s, that file's own keyframe spacing, and on the second the median
+ * was 6.3 s with a worst case of 21 s. Never once negative.
  *
  * @param {Buffer} cues
  * @param {number} timestampScale - Nanoseconds per tick.
+ * @param {number | null} trackNumber - Null keeps every entry, which is right
+ *   only for a file that indexes one track.
  * @returns {number[]}
  */
-function readCueTimes(cues, timestampScale) {
+function readCueTimes(cues, timestampScale, trackNumber) {
   const times = [];
   const secondsPerTick = timestampScale / 1e9;
   for (const point of iterateElements(cues)) {
@@ -135,11 +198,26 @@ function readCueTimes(cues, timestampScale) {
       continue;
     }
     const pointEnd = Math.min(cues.length, point.dataOffset + point.size);
+    let time = null;
+    let belongsToTrack = trackNumber === null;
     for (const field of iterateElements(cues, point.dataOffset, pointEnd)) {
       if (field.id === ID_CUE_TIME) {
-        times.push(readUint(cues, field.dataOffset, field.size) * secondsPerTick);
-        break;
+        time = readUint(cues, field.dataOffset, field.size) * secondsPerTick;
+        continue;
+      }
+      if (field.id !== ID_CUE_TRACK_POSITIONS || belongsToTrack) {
+        continue;
       }
+      const positionsEnd = Math.min(pointEnd, field.dataOffset + field.size);
+      for (const inner of iterateElements(cues, field.dataOffset, positionsEnd)) {
+        if (inner.id === ID_CUE_TRACK && readUint(cues, inner.dataOffset, inner.size) === trackNumber) {
+          belongsToTrack = true;
+          break;
+        }
+      }
+    }
+    if (time !== null && belongsToTrack) {
+      times.push(time);
     }
   }
   times.sort((left, right) => left - right);
@@ -195,6 +273,64 @@ export async function readMatroskaKeyframeTimes(readRange, fileSize) {
   const payloadEnd = Math.min(cuesChunk.length, cuesElement.dataOffset + cuesElement.size);
   const payload = cuesChunk.subarray(cuesElement.dataOffset, payloadEnd);
 
-  const times = readCueTimes(payload, readTimestampScale(head, seekHead.segmentDataOffset));
-  return times.length > 0 ? times : null;
+  // Whose entries to keep. Tracks sits near the head and is normally inside the
+  // bytes already fetched; when it is not, SeekHead says where it is and one
+  // more short read gets it. Nothing is fetched twice and nothing is scanned.
+  const videoTrack = await readVideoTrack(readRange, head, seekHead, fileSize);
+  const timestampScale = readTimestampScale(head, seekHead.segmentDataOffset);
+  const times = readCueTimes(payload, timestampScale, videoTrack);
+  if (times.length > 0) {
+    return times;
+  }
+  if (videoTrack === null) {
+    return null;
+  }
+  // The filter left nothing, and that is not an answer about the file: a table
+  // exists, and this reader simply failed to recognise which of its entries
+  // belong to the picture — a track numbered one way in Tracks and another in
+  // the cue points, or an entry with no CueTrack at all. Returning null here
+  // would put an EVEN grid on a copied picture, which is the failure this
+  // module exists to prevent, so the unfiltered table is used instead: less
+  // exact than the picture's own keyframes, better than a grid that has nothing
+  // to do with the file.
+  const unfiltered = readCueTimes(payload, timestampScale, null);
+  return unfiltered.length > 0 ? unfiltered : null;
+}
+
+/**
+ * The video track's number — from the head when it is there, and from one extra
+ * short read when it is not.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {Buffer} head
+ * @param {{ segmentDataOffset: number, entries: Map<number, number> }} seekHead
+ * @param {number} fileSize
+ * @returns {Promise<number | null>} Null when Tracks cannot be read at all, and
+ *   then every cue entry is kept — right for a file that indexes only its
+ *   picture, wrong for one that does not, and nothing here can tell them apart.
+ *   Refusing the index instead would put an even grid on a copied picture,
+ *   which is the failure this reader exists to prevent.
+ */
+async function readVideoTrack(readRange, head, seekHead, fileSize) {
+  const inHead = findElement(head, ID_TRACKS, [], seekHead.segmentDataOffset);
+  if (inHead && inHead.dataOffset + inHead.size <= head.length) {
+    return readVideoTrackNumber(head, inHead);
+  }
+  const relative = seekHead.entries.get(ID_TRACKS);
+  if (relative === undefined) {
+    return null;
+  }
+  const offset = seekHead.segmentDataOffset + relative;
+  if (!Number.isFinite(offset) || offset <= 0 || offset >= fileSize) {
+    return null;
+  }
+  const chunk = await readRange(offset, Math.min(fileSize - 1, offset + MAX_TRACKS_BYTES));
+  if (!chunk || chunk.length === 0) {
+    return null;
+  }
+  const element = [...iterateElements(chunk, 0, chunk.length)][0];
+  if (!element || element.id !== ID_TRACKS) {
+    return null;
+  }
+  return readVideoTrackNumber(chunk, { dataOffset: element.dataOffset, size: element.size });
 }

package/services/hls-session-manager.js

@@ -2065,7 +2065,7 @@ export class HlsSessionManager {
     // flip the arrangement under a stream that is playing.
     session.audioSeparate = inheritedAudioSeparate === null
       ? audioRenditions === true &&
-        this.#variantHeights(session).length >= 2 &&
+        this.#splicableHeights(session).length >= 2 &&
         this.#audioRenditionsOf(session).length > 0
       : inheritedAudioSeparate === true;
 
@@ -5379,6 +5379,42 @@ export class HlsSessionManager {
     return session.variantHeight;
   }
 
+  /**
+   * The heights this file's variants CAN be spliced at — a fact about the
+   * source and the cut grid, settled once and never moved.
+   *
+   * Separate from {@link #variantHeights}, which answers a different question:
+   * which of them are worth OFFERING to the viewer right now, on a machine
+   * whose load moves every five seconds. Both were the same list until
+   * 2026-08-18, and that is what broke playback outright: the browser is told
+   * at session creation that a master playlist exists, and 192 ms later — after
+   * the session's own encoder had started and the first supply reading had
+   * arrived — the live list had fallen from five rungs to one, `buildMaster
+   * Playlist` returned null for having fewer than two, and the master answered
+   * 404 to the very session that had just published it. hls.js treats that as
+   * fatal and unrecoverable, so nothing played at all (session `4ef731d8`,
+   * "Moana (2016).mkv", 17:43:01).
+   *
+   * A live figure may decide what to offer. It may not decide whether a
+   * published document exists.
+   *
+   * @param {HlsSession} session
+   * @returns {number[]} Largest first.
+   */
+  #splicableHeights(session) {
+    const owner = this.#baseOf(session);
+    if (Array.isArray(owner.splicableHeights)) {
+      return owner.splicableHeights;
+    }
+    const heights = new Set(variantHeightsFor(Number(owner.sourceHeight) || 0));
+    const own = this.variantHeightOf(owner);
+    if (own > 0) {
+      heights.add(own);
+    }
+    owner.splicableHeights = [...heights].sort((left, right) => right - left);
+    return owner.splicableHeights;
+  }
+
   /**
    * The heights this session's file is offered at, largest first.
    *
@@ -6540,8 +6576,11 @@ export class HlsSessionManager {
       return null;
     }
     // Only the heights the master offers. Anything else is a made-up request,
-    // and honouring it would let a client start encoder runs at will.
-    if (!this.#variantHeights(base).includes(height)) {
+    // and honouring it would let a client start encoder runs at will. The
+    // MASTER's list, not the live one: a rung is published for the session's
+    // whole life, and refusing what we published is how a quality switch became
+    // a 404 storm across every level.
+    if (!this.#splicableHeights(base).includes(height)) {
       return null;
     }
     if (height === this.variantHeightOf(base)) {
@@ -6690,7 +6729,7 @@ export class HlsSessionManager {
     if (!isPlaylist && !isInit && !isSegment) {
       return { sessionId: null };
     }
-    if (!this.#variantHeights(base).includes(height)) {
+    if (!this.#splicableHeights(base).includes(height)) {
       return { sessionId: null };
     }
     // Answered from the base, and no encoder is started for it. Every variant of
@@ -6945,7 +6984,11 @@ export class HlsSessionManager {
       return null;
     }
     const sourceHeight = Number(session.sourceHeight) || 0;
-    const rungs = this.#variantHeights(session);
+    // What CAN be spliced, not what is worth offering this second. The live
+    // judgement travels in `offeredHeights` and in every progress report, which
+    // is what the viewer's menu follows; letting it decide the master's
+    // existence made a live session answer 404 to its own published address.
+    const rungs = this.#splicableHeights(session);
     if (rungs.length < 2) {
       return null;
     }

package/services/thread-pool.js

@@ -0,0 +1,30 @@
+/**
+ * @file How many blocking calls this process can have in flight — set before
+ * anything makes one.
+ *
+ * Node resolves host names with `getaddrinfo`, which runs on the libuv thread
+ * pool, and that pool holds FOUR threads by default. A torrent announces to
+ * every tracker in its file at once — ten or thirteen of them — so four names
+ * are resolved and the rest queue; a tracker that no longer exists holds its
+ * thread for the resolver's full ten-second timeout, and every announce behind
+ * it blows its own fifteen-second deadline.
+ *
+ * Measured inside the addon container on 2026-08-18, resolving the ten trackers
+ * of one film: as a burst on the default pool, two names answered in 30-40 ms
+ * and the other seven took **7.58 s**; with a larger pool every live name
+ * answered in **27-42 ms**. The film itself had 517 seeders on a tracker that
+ * answers in 50 ms, and spent eleven minutes with zero peers, because every
+ * announce — UDP and HTTP alike — timed out waiting for a name.
+ *
+ * Sized to hold several torrents' announce lists at once, since the same pool
+ * also serves this process's file reads. Idle threads cost memory and nothing
+ * else, and a deployment that states its own size is left alone.
+ *
+ * Imported FIRST by the entry point, because a module's imports are evaluated
+ * before its body: written as a statement in `cli.js` this would run after
+ * every other import had already had its chance to create the pool.
+ */
+
+if (!process.env.UV_THREADPOOL_SIZE) {
+  process.env.UV_THREADPOOL_SIZE = "64";
+}

package/test/decode-cost.test.js

@@ -288,7 +288,7 @@ test("the source's decode figures come off the probe, or not at all", () => {
   assert.equal(sourceDecodeCharacteristics(null), null);
 });
 
-test("the master playlist drops the rungs the host cannot hold", async (t) => {
+test("the OFFER drops the rungs the host cannot hold, and the master keeps addressing them", async (t) => {
   const dirPath = await mkdtemp(path.join(os.tmpdir(), "decode-cost-"));
   const manager = new HlsSessionManager({
     enabled: true,
@@ -339,15 +339,22 @@ test("the master playlist drops the rungs the host cannot hold", async (t) => {
   };
   manager.sessionsById.set(session.id, session);
 
-  assert.equal(
-    manager.buildMasterPlaylist(session.id),
-    null,
-    "every rung under the copy runs below realtime here, so there is nothing to switch to"
-  );
   assert.deepEqual(
     manager.offeredHeights(session),
     [1080],
-    "and the list the browser is given says the same, since both come from one answer"
+    "every rung under the copy runs below realtime here, so there is nothing to switch to"
+  );
+  // The master is NOT that answer. It says which rungs can be spliced onto this
+  // cut grid, which is a fact about the file, and it has to hold still for the
+  // session's life: the browser is handed its address at creation, and a live
+  // figure that withdrew it left a session answering 404 to itself (field
+  // 2026-08-18, "Moana (2016).mkv" — nothing played at all).
+  const weakMaster = manager.buildMasterPlaylist(session.id);
+  assert.ok(weakMaster, "published once, whatever the host is managing this second");
+  assert.deepEqual(
+    [...weakMaster.matchAll(/^v\/(\d+)\/index\.m3u8$/gm)].map((match) => Number(match[1])),
+    [1080, 720, 540, 480, 360, 240],
+    "the ladder of the source, addressable — the menu the viewer sees is offeredHeights"
   );
 
   // A host with a little more encoder keeps the rungs it can actually hold. A
@@ -355,11 +362,18 @@ test("the master playlist drops the rungs the host cannot hold", async (t) => {
   manager.softwarePresetBenchmark = [{ preset: "ultrafast", pixelsPerSec: 12e6 }];
   const stronger = { ...session, id: "dddddddd-eeee-ffff-0000-111111111111", offeredHeightsCache: undefined };
   manager.sessionsById.set(stronger.id, stronger);
+  assert.deepEqual(
+    manager.offeredHeights(stronger),
+    [1080, 360, 240],
+    "nothing is known about this swarm, so the bar is realtime"
+  );
   const master = manager.buildMasterPlaylist(stronger.id);
-  assert.ok(master, "1080p copied plus the rungs this host can produce");
-  const heights = [...master.matchAll(/^v\/(\d+)\/index\.m3u8$/gm)].map((match) => Number(match[1]));
-  assert.deepEqual(heights, [1080, 360, 240], "nothing is known about this swarm, so the bar is realtime");
-  assert.deepEqual(manager.offeredHeights(stronger), heights);
+  assert.ok(master, "1080p copied plus every rung that can be spliced beside it");
+  assert.deepEqual(
+    [...master.matchAll(/^v\/(\d+)\/index\.m3u8$/gm)].map((match) => Number(match[1])),
+    [1080, 720, 540, 480, 360, 240],
+    "the same published set as before: what the host manages is the offer's business, not the document's"
+  );
 
   // The same host, once the reader has measured what this file's supply
   // demands: waits arriving as they did on the field torrent of 2026-08-17 ask

package/test/matroska-cues-track.test.js

@@ -0,0 +1,192 @@
+/**
+ * @file The container's table names a track, and only the picture's entries are
+ * cut points.
+ *
+ * Measured 2026-08-18 on the two files the field sessions were recorded from:
+ * `Minions.and.Monsters.1080p.mkv` carries 2778 cue entries for its video track
+ * — one every 2.002 s — and 4669 more across four subtitle tracks;
+ * `Moana.2 … MegaPeer.mkv` carries 1055 for video and 5007 across five subtitle
+ * tracks. Read without the track, both sets went into the cut list together,
+ * and ffmpeg — which can only cut a copied picture at a real keyframe at or
+ * after the time it is asked for — moved every such cut forward to the next
+ * keyframe. That is the whole of the disagreement the field reported: 2.002 s
+ * on the first file, a median of 6.3 s and a worst case of 21 s on the second,
+ * and never once negative.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readMatroskaKeyframeTimes } from "../services/container-index/matroska.js";
+
+const ID_EBML = 0x1a45dfa3;
+const ID_SEGMENT = 0x18538067;
+const ID_SEEK_HEAD = 0x114d9b74;
+const ID_SEEK = 0x4dbb;
+const ID_SEEK_ID = 0x53ab;
+const ID_SEEK_POSITION = 0x53ac;
+const ID_INFO = 0x1549a966;
+const ID_TIMESTAMP_SCALE = 0x2ad7b1;
+const ID_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+const ID_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_CUE_CLUSTER_POSITION = 0xf1;
+
+/** An element id, as the bytes the specification gives it. */
+function idBytes(id) {
+  const bytes = [];
+  let rest = id;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  }
+  return Buffer.from(bytes);
+}
+
+/** A size, as a four-byte EBML variable-length integer. */
+function sizeBytes(size) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(size, 0);
+  buffer[0] |= 0x10;
+  return buffer;
+}
+
+function element(id, payload) {
+  return Buffer.concat([idBytes(id), sizeBytes(payload.length), payload]);
+}
+
+/** An unsigned value, in as few bytes as it needs. */
+function uintElement(id, value) {
+  const bytes = [];
+  let rest = value;
+  do {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  } while (rest > 0);
+  return element(id, Buffer.from(bytes));
+}
+
+function cuePoint(timeMs, tracks) {
+  return element(ID_CUE_POINT, Buffer.concat([
+    uintElement(ID_CUE_TIME, timeMs),
+    ...tracks.map((track) => element(ID_CUE_TRACK_POSITIONS, Buffer.concat([
+      uintElement(ID_CUE_TRACK, track),
+      uintElement(ID_CUE_CLUSTER_POSITION, 4096)
+    ])))
+  ]));
+}
+
+/**
+ * A file with the shape the field files have: one picture, one set of subtitles,
+ * and a table that indexes both.
+ *
+ * @param {{ withTracks?: boolean }} [options]
+ * @returns {Buffer}
+ */
+function buildFile({ withTracks = true, cueTrack = null } = {}) {
+  const info = element(ID_INFO, uintElement(ID_TIMESTAMP_SCALE, 1_000_000));
+  const tracks = element(ID_TRACKS, Buffer.concat([
+    element(ID_TRACK_ENTRY, Buffer.concat([
+      uintElement(ID_TRACK_NUMBER, 1),
+      uintElement(ID_TRACK_TYPE, 1) // video
+    ])),
+    element(ID_TRACK_ENTRY, Buffer.concat([
+      uintElement(ID_TRACK_NUMBER, 2),
+      uintElement(ID_TRACK_TYPE, 17) // subtitles
+    ]))
+  ]));
+  const forPicture = cueTrack ?? 1;
+  const forSubtitles = cueTrack ?? 2;
+  const cues = element(ID_CUES, Buffer.concat([
+    cuePoint(0, [forPicture]),
+    cuePoint(1070, [forSubtitles]),
+    cuePoint(2002, [forPicture]),
+    cuePoint(3141, [forSubtitles]),
+    cuePoint(4004, [forPicture])
+  ]));
+
+  const seekEntry = (targetId, position) => element(ID_SEEK, Buffer.concat([
+    element(ID_SEEK_ID, idBytes(targetId)),
+    element(ID_SEEK_POSITION, (() => {
+      const buffer = Buffer.alloc(4);
+      buffer.writeUInt32BE(position, 0);
+      return buffer;
+    })())
+  ]));
+  // Positions are relative to the Segment's payload, so the SeekHead has to be
+  // measured before they can be stated. Its own length does not change when the
+  // placeholders become real values: every size and position here is written at
+  // a fixed width.
+  const draft = element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, 0),
+    ...(withTracks ? [seekEntry(ID_TRACKS, 0)] : []),
+    seekEntry(ID_CUES, 0)
+  ]));
+  const infoAt = draft.length;
+  const tracksAt = infoAt + info.length;
+  const cuesAt = withTracks ? tracksAt + tracks.length : infoAt + info.length;
+  const seekHead = element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, infoAt),
+    ...(withTracks ? [seekEntry(ID_TRACKS, tracksAt)] : []),
+    seekEntry(ID_CUES, cuesAt)
+  ]));
+
+  const segmentPayload = Buffer.concat(
+    withTracks ? [seekHead, info, tracks, cues] : [seekHead, info, cues]
+  );
+  return Buffer.concat([
+    element(ID_EBML, Buffer.from([0x42, 0x86, 0x81, 0x01])),
+    element(ID_SEGMENT, segmentPayload)
+  ]);
+}
+
+function readerOver(file) {
+  return async (start, end) => {
+    const last = Math.min(end, file.length - 1);
+    return start > last ? null : file.subarray(start, last + 1);
+  };
+}
+
+test("only the picture's entries become cut times", async () => {
+  const file = buildFile();
+
+  const times = await readMatroskaKeyframeTimes(readerOver(file), file.length);
+
+  assert.deepEqual(
+    times.map((time) => Number(time.toFixed(3))),
+    [0, 2.002, 4.004],
+    "the subtitle entries at 1.070 and 3.141 are not keyframes, and a cut asked for there lands late"
+  );
+});
+
+test("a table whose entries name no known track is still used", async () => {
+  // The cue points reference track 9, which Tracks never declares. Filtering
+  // leaves nothing — and returning nothing would put an even grid on a copied
+  // picture, the failure this reader exists to prevent.
+  const file = buildFile({ cueTrack: 9 });
+
+  const times = await readMatroskaKeyframeTimes(readerOver(file), file.length);
+
+  assert.deepEqual(
+    times.map((time) => Number(time.toFixed(3))),
+    [0, 1.07, 2.002, 3.141, 4.004],
+    "an unrecognised table beats no table at all"
+  );
+});
+
+test("a file whose tracks cannot be read keeps every entry", async () => {
+  const file = buildFile({ withTracks: false });
+
+  const times = await readMatroskaKeyframeTimes(readerOver(file), file.length);
+
+  assert.deepEqual(
+    times.map((time) => Number(time.toFixed(3))),
+    [0, 1.07, 2.002, 3.141, 4.004],
+    "with nothing to tell the tracks apart, the old behaviour is the only one available"
+  );
+});

package/test/quality-variants.test.js

@@ -813,3 +813,49 @@ test("a quality step being warmed is not refused by its own cost", async (t) =>
       "offer by the act of warming it — and its next segment 404s on a stream that is playing"
   );
 });
+
+test("the master survives a live offer that has collapsed to one rung", async (t) => {
+  // The field case of 2026-08-18, in the smallest form that reproduces it: a
+  // host too slow for any re-encoded rung, and a swarm whose interruptions
+  // demand far more than realtime. The live offer then holds only the height an
+  // encoder is already producing — and until this test existed, that made
+  // `buildMasterPlaylist` answer null and the route answer 404 to a session
+  // that had just published the address.
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "quality-variants-collapse-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090,
+    // A megapixel a second: every rung below the source costs more than the
+    // machine has.
+    softwarePresetBenchmark: [{ preset: "veryfast", pixelsPerSec: 1_000_000 }],
+    decodeCostModel: { pixelTerm: 0.01, bitrateTerm: 0, constantTerm: 0 }
+  });
+  const base = fakeSession({ id: BASE_ID, encodeHeight: 812, dirPath });
+  base.sourceDecode = { megapixelsPerSecond: 50, megabitsPerSecond: 10 };
+  // What this file's own reader measured: a step must run at eight times
+  // realtime to survive this swarm.
+  base.supplyFigures = { requiredSpeed: 8 };
+  manager.sessionsById.set(BASE_ID, base);
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  assert.deepEqual(
+    manager.offeredHeights(base),
+    [812],
+    "the live judgement is unchanged: nothing but the running height is worth offering"
+  );
+
+  const master = manager.buildMasterPlaylist(BASE_ID);
+
+  assert.ok(master, "the master is a published document, not a live figure");
+  const heights = [...master.matchAll(/^v\/(\d+)\/index\.m3u8$/gm)].map((match) => Number(match[1]));
+  assert.deepEqual(
+    heights,
+    [1080, 812, 720, 540, 480, 360, 240],
+    "every rung that can be spliced onto this cut grid stays addressable"
+  );
+});

package/test/thread-pool.test.js

@@ -0,0 +1,53 @@
+/**
+ * @file The blocking-call pool is stated before anything can create it.
+ *
+ * Field 2026-08-18: a film with 517 seeders spent eleven minutes with zero
+ * peers on the addon host. Every announce timed out — UDP and HTTP alike — and
+ * the cause was not the network: resolving that torrent's ten tracker names as
+ * a burst took 7.58 s on the default four-thread pool, against 27-42 ms each
+ * when the pool was larger. A dead tracker holds a thread for the resolver's
+ * whole timeout, and every announce queued behind it misses its own deadline.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+test("the pool is set, and left alone when the deployment states its own", async () => {
+  const previous = process.env.UV_THREADPOOL_SIZE;
+  try {
+    process.env.UV_THREADPOOL_SIZE = "";
+    await import(`../services/thread-pool.js?first=${Date.now()}`);
+    assert.equal(
+      Number(process.env.UV_THREADPOOL_SIZE) >= 16,
+      true,
+      "enough threads for a torrent's whole announce list to resolve at once"
+    );
+
+    process.env.UV_THREADPOOL_SIZE = "8";
+    await import(`../services/thread-pool.js?stated=${Date.now()}`);
+    assert.equal(process.env.UV_THREADPOOL_SIZE, "8", "a stated size is the deployment's to choose");
+  } finally {
+    if (previous === undefined) {
+      delete process.env.UV_THREADPOOL_SIZE;
+    } else {
+      process.env.UV_THREADPOOL_SIZE = previous;
+    }
+  }
+});
+
+test("the entry point imports it before anything that could create the pool", async () => {
+  const cli = await readFile(path.join(here, "..", "bin", "cli.js"), "utf8");
+  const imports = [...cli.matchAll(/^import\s.*?from\s+["'](.+?)["'];|^import\s+["'](.+?)["'];/gm)]
+    .map((match) => match[1] ?? match[2]);
+
+  assert.equal(
+    imports[0],
+    "../services/thread-pool.js",
+    "a module's imports run before its body, so this cannot be a statement in cli.js"
+  );
+});