@torrent-tv/proxy 2.49.0 → 2.51.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 2.51.0
+
+- **Fix**: A run is POSITIONED where the player was told the segment begins, on the same table its cuts are stated on. There are two boundary tables — the one the playlist text was written from, which never changes, and the live one, corrected as produced segments reveal where the file's cuts truly are. 2.45.0 moved the CUT LIST onto the published table and left the position on the live one, and that is one fault rather than two: `-segment_times` are measured from wherever the run really began, so any distance between the two carries into EVERY cut the run makes. The corrections run backwards, so each restart began a little earlier than the grid its cuts were stated on, and because the corrections accumulate, so did the distance. Measured 2026-08-21 on `JUFD665.mp4` — an MP4 whose index was read cleanly, 1765 keyframes, served by copy: after one seek restart a produced segment held the boundary **two** places before its own number (16.684 s, exactly 2.0000 segments), after the next restart **four** (33.5 s). The player's buffer then stops extending at all, because every fragment's content lands before the time its playlist entry names: `bufferEnd` stood still at 4571.1 s through four `frag-far` warnings until hls.js gave up and jumped the viewer 16.8 s forward. Four of those jumps in one window is what the viewer reported as sticking on every seek.
+- **Fix**: The line about a segment that began away from its grid follows the numbers instead of the branch it is printed from. On the copy path it always read "the container's keyframe index disagrees with the file", including in the case this code's own neighbouring comment defines as a fault in this code — a segment holding another boundary **of the same list**. It now says which of the two it is, because they need opposite fixes and that sentence is what sent the reading of the session above after the file instead of after the arithmetic. The soundtrack's variant of the sentence stops claiming anything about a keyframe index: a soundtrack has no keyframes and is cut exactly where it was asked to be.
+- **New**: A run says where it was positioned — the time, the boundary it came from, that boundary's time in the PUBLISHED table and in the LIVE one, the distance between them, and the number it starts counting from. Four numbers whose disagreement was invisible everywhere else.
+- **New**: A correction to the live boundary table states the total drift it is part of. Corrections are applied one boundary at a time and each is small enough to look harmless; nobody was watching the sum, which is the quantity that actually moves the cuts.
+- **Fix**: The realignment that starts the sound where a copied picture truly begins is given that instant EXPLICITLY. It used to be smuggled through the live boundary table — the correction wrote the measured time there and the restarted run read its position from the same place — which stops working the moment a run positions itself on the table the player holds, as it now must. Smuggled, the restart would land exactly where it already was: picture and sound stay apart AND a healthy soundtrack run is discarded for nothing, which is the shape the field already showed on 2026-08-21 — eleven audio restarts in under four minutes, eight of them dying with `run had produced 0.0s`.
+- **Fix**: What a run was asked for is taken from the run rather than looked up again in a table. Two lines did the second — the one reporting where a run landed, and the one explaining a held segment — and once the position moved to the published grid they could disagree with the run by the distance between the two tables: a perfect landing reported as a drift, a real drift of the same size cancelled to zero, and a held segment printing a negative "produced" that sends the reader after the torrent when the encoder is the subject.
+- **New**: The player's own "this fragment is nowhere near my buffer" reading is answered instead of being left in its console. `POST /api/transcode-sessions/:id/fragment-far` takes the report and the proxy replies in the log with the one fact only this side holds: which boundary the segment of that number really begins at, and whether that is the one its number claims. The report says which stream it is about, and a report about the soundtrack is answered from the soundtrack's own session: picture and sound are produced by two sessions positioned by two runs, which is how they come apart, so answering one from the other's records would state something confident about the wrong stream. Diagnostic only — nothing is repositioned on the strength of a browser's reading, because a wrong answer there would restart an encoder a viewer is waiting on.
+- **Fix**: The DHT is given entry points that answer. Measured 2026-08-21 from the addon host: of the three bootstrap nodes the library ships, `router.bittorrent.com` and `router.utorrent.com` replied to nothing while a control datagram to a DNS server came back in 20 ms, and the third, `dht.transmissionbt.com`, is alive — it answered `find_node` with eight nodes — but on a host with global IPv6 its name resolves to an IPv6 address first while the DHT's socket is IPv4, so by name it was never reached. The list now carries a live node, and the names are resolved to IPv4 here rather than left to whichever family the host prefers. Measured on that host: 0 nodes after 21 s by name, 22 nodes in 5 s by address. The resolution is capped at two seconds per name, because it is awaited before the torrent client exists and a host whose resolver black-holes would otherwise hold that thread for c-ares' own four tries with nothing said. What it cost: on `JUFD665.mp4` the tracker answered `seeders=5` at 13:40:30 and the first peer connected at 13:44:47 — 4 min 17 s of a viewer watching an unexplained wait with an empty routing table beside them. A private torrent still ignores the DHT, by specification.
+- **New**: The size of the DHT's routing table is said a minute after start, and an empty one is said as a warning. A bootstrap list rots — that is exactly what had happened here — and nothing reported it for as long as it was wrong, so the next list to die would be found the same way this one was: by hand, after a viewer waited four minutes.
+
+## 2.50.0
+
+- **Fix**: An AVI seek is asked for late enough to survive the container's own arithmetic. AVI names a keyframe by its frame NUMBER, and `services/container-index/avi.js` turned that into a time by multiplying by the frame duration the header declares — which lands 10-44 ms from the presentation time the demuxer computes, always under one frame (measured 2026-08-21 against the files themselves: 1196 index entries against 1196 real keyframes and 901 against 901, the frames exactly right and only their names off). A name sitting just BELOW its real keyframe seeks to before it and lands on the one before that, which is the same fault the landing offset already exists for. The reader now declares how far its times may be, and the request carries that on top. Matroska and MP4 declare nothing, because they state instants outright — nine files and 11 665 keyframes with not one disagreement.
+- **Fix**: A container with no keyframe index is re-encoded rather than copied against a grid nobody knows. MPEG-TS carries no index of any kind — measured the same day, 669 real keyframes and nothing to read them from without walking the file — and a copied picture can only be cut at the source's own keyframes, so declaring an even grid is a falsehood the player punishes: it walks the whole file to rebuild the timeline, or presents audio with no picture because a segment begins with nothing decodable, both field-observed 2026-08-02. Re-encoding PLACES keyframes on our own cuts, so the grid is right by construction whatever the container. A container whose index could not be read inside the budget lands here too, for the same reason. It costs an encoder, and the alternative was a broken playlist.
+
 ## 2.49.0
 
 - **Fix**: The torrent worker is allowed to END rather than being torn down under itself. A core dump read on 2026-08-21 named the fault the proxy has been dying of: `SIGSEGV` in `v8::Value::IsArrayBufferView` reached through `napi_get_buffer_info` from utp-native's `on_utp_accept`, called from its UDP read — all of it inside `node::Environment::CleanupHandles`, under `FreeEnvironment`, on `Worker::Run`. That is a teardown race, not a data fault, which is why neither patch our forked library already carries touched it: a datagram arriving while the environment is being freed walks into an isolate that no longer exists. `destroyAll` called `Worker.terminate()` immediately after destroying the client inside, and `terminate()` frees the environment with libuv's handle callbacks still queued. It now waits for the thread to exit by itself — once the client is destroyed nothing holds its loop open — with `terminate()` kept as a five-second fallback, because a shutdown that hangs is worse than one that is forced.

package/package.json

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

package/routes/api/transcode-sessions/fragment-far/post.js

@@ -0,0 +1,60 @@
+/**
+ * Accept the player's report that a delivered fragment sits far from the edge
+ * of what it has buffered.
+ *
+ * This is the earliest statement that exists of a stream coming apart, and
+ * until now it lived only in the browser's console. Measured 2026-08-21 on
+ * `JUFD665.mp4`: four of these across half a minute, each naming a gap of
+ * ~33.5 s, while the buffer stood still at 4571.1 s — and then hls.js gave up
+ * and jumped the viewer 16.8 s forward. The proxy is the only side that can say
+ * what the gap MEANS, because only it knows which boundary the segment it
+ * produced actually holds, and whether that is the one its number claims.
+ *
+ * POST /api/transcode-sessions/:sessionId/fragment-far
+ * Body: { sn: number, track?: string, fragStartSec: number, bufferEndSec: number, currentTimeSec: number }
+ *
+ * `track` is hls.js's own name for the stream the fragment belongs to ("main"
+ * or "audio"). It matters because picture and sound are produced by two
+ * different sessions positioned by two different runs — which is how they come
+ * apart in the first place — so a report answered against the wrong one is a
+ * confident statement about a stream nobody asked about.
+ *
+ * Diagnostic only — it changes nothing about the encode. Invalid body → 400,
+ * unknown session → 404, ok → 204.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiTranscodeSessionFragmentFarPost(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  const sn = Number(body.sn);
+  const track = typeof body.track === "string" ? body.track : "";
+  const fragStartSec = Number(body.fragStartSec);
+  const bufferEndSec = Number(body.bufferEndSec);
+  const currentTimeSec = Number(body.currentTimeSec);
+  if (
+    !sessionId ||
+    !Number.isInteger(sn) ||
+    sn < 0 ||
+    !Number.isFinite(fragStartSec) ||
+    !Number.isFinite(bufferEndSec) ||
+    !Number.isFinite(currentTimeSec)
+  ) {
+    return reply.code(400).send({ error: "sn (integer >=0), fragStartSec, bufferEndSec and currentTimeSec are required." });
+  }
+
+  const recorded = hlsSessionManager.recordFragmentFar(sessionId, {
+    sn,
+    track,
+    fragStartSec,
+    bufferEndSec,
+    currentTimeSec
+  });
+  if (!recorded) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+  return reply.code(204).send();
+}

package/server.js

@@ -26,6 +26,7 @@ import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/
 import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
 import { handleApiTranscodeSessionReleasePost } from "./routes/api/transcode-sessions/release/post.js";
 import { handleApiTranscodeSessionNetReportPost } from "./routes/api/transcode-sessions/net-report/post.js";
+import { handleApiTranscodeSessionFragmentFarPost } from "./routes/api/transcode-sessions/fragment-far/post.js";
 import { handleApiTranscodeSessionSeekPost } from "./routes/api/transcode-sessions/seek/post.js";
 import { handleStreamGet } from "./routes/stream/get.js";
 import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
@@ -244,6 +245,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   app.post("/api/transcode-sessions/:sessionId/net-report", async (req, reply) =>
     handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager })
   );
+  app.post("/api/transcode-sessions/:sessionId/fragment-far", async (req, reply) =>
+    handleApiTranscodeSessionFragmentFarPost(req, reply, { hlsSessionManager })
+  );
   app.post("/api/transcode-sessions/:sessionId/seek", async (req, reply) =>
     handleApiTranscodeSessionSeekPost(req, reply, { hlsSessionManager })
   );

package/services/container-index/avi.js

@@ -152,5 +152,16 @@ export async function readAviKeyframeTimes(readRange, fileSize) {
     }
     videoFrame += 1;
   }
-  return times.length > 0 ? times : null;
+  if (times.length === 0) {
+    return null;
+  }
+  // AVI names a keyframe by its FRAME NUMBER, and the time above is that number
+  // multiplied by the frame duration the header declares. The frames are the
+  // right ones — measured 2026-08-21 against the files themselves, 1196 index
+  // entries against 1196 real keyframes and 901 against 901, exactly — but the
+  // names are 10-44 ms away from the presentation times the demuxer computes,
+  // always under one frame. So the caller is told how far a time here may be
+  // from the instant it refers to, and can ask for a seek late enough that it
+  // still lands on the frame rather than on the one before it.
+  return { times, tolerance: secondsPerFrame };
 }

package/services/container-index/index.js

@@ -62,7 +62,7 @@ const READERS = [
  * @param {ReadRange} params.readRange
  * @param {number} params.fileSize
  * @param {string} [params.label] - For logging only.
- * @returns {Promise<{ times: number[] | null, format: string }>} Ascending
+ * @returns {Promise<{ times: number[] | null, format: string, tolerance: number }>} Ascending
  *   seconds, or null times when this file has no readable index — the caller
  *   must then not claim to know the grid. The format is which reader matched,
  *   reported whether or not it produced anything: how often an index disagrees
@@ -71,27 +71,39 @@ const READERS = [
  */
 export async function readKeyframeIndex({ readRange, fileSize, label = "" }) {
   if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) {
-    return { times: null, format: "unknown" };
+    return { times: null, format: "unknown", tolerance: 0 };
   }
 
   const startedAt = Date.now();
   let times = null;
   let format = "unrecognised";
+  // How far a time in `times` may be from the instant it names. Zero wherever
+  // the container states instants outright, which Matroska and MP4 both do.
+  let tolerance = 0;
   try {
     const sniff = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
     if (!sniff) {
-      return { times: null, format: "unread" };
+      return { times: null, format: "unread", tolerance: 0 };
     }
     const reader = READERS.find((candidate) => candidate.matches(sniff));
     if (reader) {
       format = reader.name;
-      times = await reader.read(readRange, fileSize);
+      const read = await reader.read(readRange, fileSize);
+      // A reader may answer with the times alone, or with how far those times
+      // may sit from the instants they name — which only AVI has to say,
+      // because only AVI computes them from frame numbers.
+      if (Array.isArray(read)) {
+        times = read;
+      } else if (read && Array.isArray(read.times)) {
+        times = read.times;
+        tolerance = Number.isFinite(read.tolerance) ? read.tolerance : 0;
+      }
     }
   } catch (error) {
     // A malformed or partially-downloaded index must never take playback down —
     // it only means the grid is unknown, which the caller already handles.
     logger.warn(`container-index: failed to read index for "${label}": ${error?.message ?? error}`);
-    return { times: null, format };
+    return { times: null, format, tolerance: 0 };
   }
 
   const elapsedMs = Date.now() - startedAt;
@@ -102,5 +114,5 @@ export async function readKeyframeIndex({ readRange, fileSize, label = "" }) {
   } else {
     logger.info(`container-index: no usable index for "${label}" (${format}, ${elapsedMs}ms)`);
   }
-  return { times, format };
+  return { times, format, tolerance };
 }

package/services/hls-session-manager.js

@@ -422,6 +422,12 @@ const LOOKAHEAD_RESUME_SECONDS = 60;
 // encoding 125 s of content before reaching the viewer's position. Field
 // 2026-08-02: a seek took 56 s, of which ~50 s was this backoff.
 const SEEK_BACKOFF_SEGMENTS = 1;
+
+// How many produced segments' true start times to remember, so a player's
+// report about one of them can be answered. Two hundred is about twenty
+// minutes of playback at these segment lengths — far more than the recent past
+// a stall report can be about, and small enough to be free.
+const TRUE_START_MEMORY = 200;
 // How long to wait for a scrub to stop moving before acting on it. Small,
 // because the browser already collapses a drag into ONE report
 // (`SEEK_REPORT_DEBOUNCE_MS`, 300 ms) and only reports where it settled — this
@@ -1176,6 +1182,54 @@ export function segmentCutTimesFrom(boundaries, startIndex) {
   return times;
 }
 
+/**
+ * How far the live boundary table has moved from the one the player holds, said
+ * in words.
+ *
+ * The corrections are applied one boundary at a time and each is small enough
+ * to look harmless; what nobody was watching is the total. It matters because a
+ * run positioned on one table and cut on the other carries their difference into
+ * every cut it makes — the fault of 2026-08-21, where the distance reached two
+ * whole segments after one seek and four after the next. Printed beside each
+ * correction so the total is visible while it is still small.
+ *
+ * @param {number[]} published - The table the playlist text was written from.
+ * @param {number[]} live - The table corrected from produced segments.
+ * @returns {string} A phrase, always readable, never throwing on odd input.
+ */
+export function describeGridDrift(published, live) {
+  if (!Array.isArray(published) || !Array.isArray(live) || published.length === 0) {
+    return "not comparable";
+  }
+  if (published.length !== live.length) {
+    return `a different length (${published.length} against ${live.length})`;
+  }
+  let apart = 0;
+  let worst = 0;
+  let worstAt = -1;
+  for (let index = 0; index < published.length; index += 1) {
+    // Rounded to the millisecond BEFORE comparing, not only before printing.
+    // Two boundaries moved by the same amount differ in the last bits of a
+    // double, so an unrounded comparison picks between them by an accident
+    // invisible in the printed figure — and the line would name a boundary the
+    // reader cannot tell apart from the one before it. Rounded, ties keep the
+    // earliest, which is also the one worth looking at first.
+    const distance = Math.round(Math.abs(live[index] - published[index]) * 1000) / 1000;
+    if (distance <= 0.001) {
+      continue;
+    }
+    apart += 1;
+    if (distance > worst) {
+      worst = distance;
+      worstAt = index;
+    }
+  }
+  if (apart === 0) {
+    return "identical";
+  }
+  return `${apart} of ${published.length} boundaries apart, worst ${worst.toFixed(3)}s at #${worstAt}`;
+}
+
 /**
  * How much later than a keyframe to ASK, so that ffmpeg lands on that keyframe.
  *
@@ -1196,12 +1250,17 @@ export function seekLandingOffsetFor(session, keyframe) {
   if (session?.transcodeVideo === true) {
     return 0;
   }
+  // A grid whose times are approximate needs that error added on top, or a name
+  // sitting just below its real keyframe seeks to before it and lands on the
+  // one before that. Only AVI declares one.
+  const tolerance = Number.isFinite(session?.keyframeTolerance) ? Math.max(0, session.keyframeTolerance) : 0;
+  const wanted = SEEK_LANDING_OFFSET_SEC + tolerance;
   const times = Array.isArray(session?.keyframeTimes) ? session.keyframeTimes : [];
   const next = times.find((time) => time > keyframe + 0.001);
   if (next === undefined) {
-    return SEEK_LANDING_OFFSET_SEC;
+    return wanted;
   }
-  return Math.min(SEEK_LANDING_OFFSET_SEC, (next - keyframe) / 2);
+  return Math.min(wanted, (next - keyframe) / 2);
 }
 
 /**
@@ -1746,6 +1805,13 @@ export class HlsSessionManager {
     // branches; on failure both fall back to their current behaviour (uniform
     // grid for boundaries, raw target for seeking) — no regression.
     let keyframeTimes = null;
+    // How far a time in `keyframeTimes` may sit from the instant it names. Only
+    // AVI has anything to declare here: it stores frame NUMBERS and the time is
+    // that number times the frame duration, which lands 10-44 ms from the
+    // presentation time the demuxer computes (measured 2026-08-21). A seek made
+    // at such a name can fall just BELOW the real keyframe and land on the one
+    // before it, which is the same fault the landing offset exists for.
+    let keyframeTolerance = 0;
     let keyframeMs = -1; // -1 = not run (skipped), -2 = running in the background
     // Which container supplied the index, carried so the accuracy summary can
     // say what it is a summary OF.
@@ -1758,6 +1824,9 @@ export class HlsSessionManager {
     if (inheritedGrid) {
       keyframeTimes = inheritedGrid.keyframeTimes;
       containerFormat = inheritedGrid.containerFormat ?? "";
+      keyframeTolerance = Number.isFinite(inheritedGrid.keyframeTolerance)
+        ? inheritedGrid.keyframeTolerance
+        : 0;
     } else if (hasDuration && !transcodeVideo && !audioOnly) {
       // Video-COPY path: keyframeTimes are REQUIRED to build correct segment
       // boundaries (the playlist itself), so this MUST block session creation —
@@ -1779,11 +1848,28 @@ export class HlsSessionManager {
       const index = await this.#readContainerKeyframes({ sourceKey, fileIndex, inputUrl, logName });
       keyframeTimes = index.times;
       containerFormat = index.format;
+      keyframeTolerance = Number.isFinite(index.tolerance) ? index.tolerance : 0;
       keyframeMs = Date.now() - keyframeStartMs;
       if (!keyframeTimes) {
+        // No index, so there is no honest grid for a COPY: a copied picture can
+        // only be cut at the source's own keyframes, and we do not know where
+        // they are. Declaring an even grid instead is a falsehood the player
+        // punishes — it walks the whole file to rebuild the timeline, or shows
+        // audio with no picture because a segment begins with nothing
+        // decodable (both field-observed 2026-08-02).
+        //
+        // Re-encoding is the honest answer and costs an encoder: keyframes are
+        // then PLACED at our own cut times rather than found, so the grid is
+        // correct by construction whatever the container. MPEG-TS is the case
+        // this exists for — measured 2026-08-21, 669 real keyframes and no
+        // index of any kind to read them from — and a container whose index
+        // could not be read in the budget lands here too, which is right for
+        // the same reason.
+        transcodeVideo = true;
         logger.warn(
-          `transcode ${sessionId}: no container keyframe index for "${logName}"; ` +
-            `falling back to a uniform grid — segment boundaries will not match the media`
+          `transcode ${sessionId}: no keyframe index in the ${containerFormat} container for ` +
+            `"${logName}" — a copied picture has no honest grid without one, so the video is ` +
+            "re-encoded instead and its keyframes are placed on our own cuts"
         );
       }
     } else if (hasDuration && transcodeVideo) {
@@ -2035,6 +2121,9 @@ export class HlsSessionManager {
       // KNOWN valid position instead of trusting the container's own on-the-fly
       // seek at an arbitrary target — see the probe call above for why.
       keyframeTimes,
+      // How far those times may sit from the instants they name — nonzero only
+      // for AVI, which computes them from frame numbers.
+      keyframeTolerance,
       // Which container the index came from, and how well it has held up. The
       // cut times of a copied video ARE its index, and an index can be wrong —
       // measured 2026-08-06, one claimed a keyframe four seconds from where the
@@ -2515,6 +2604,22 @@ export class HlsSessionManager {
       : (session.segmentBoundaries ?? []);
   }
 
+  /**
+   * Where a run beginning at `index` must be positioned: the time the PLAYER
+   * was told that segment starts at.
+   *
+   * Public because it is the invariant this class has broken twice, and a
+   * private one cannot be pinned by a test. It must always be the table the cut
+   * list is taken from — see the comment where a run is started.
+   *
+   * @param {HlsSession} session
+   * @param {number} index
+   * @returns {number}
+   */
+  runStartTimeFor(session, index) {
+    return this.#publishedStartTime(session, index);
+  }
+
   #publishedStartTime(session, index) {
     const boundaries = Array.isArray(session.publishedBoundaries) && session.publishedBoundaries.length > 0
       ? session.publishedBoundaries
@@ -2674,6 +2779,69 @@ export class HlsSessionManager {
     return true;
   }
 
+  /**
+   * Answer the player's report that a delivered fragment sits far from the edge
+   * of its buffer, with the one fact only this side holds: which boundary the
+   * segment of that number really begins at.
+   *
+   * The player can say the gap; it cannot say whether the cause is its own
+   * loading or a run whose output no longer matches its numbering. Here both
+   * are in hand — the time the playlist gave that segment, and, when the
+   * segment has been served, the time it truly began at — so the line either
+   * names a shifted run or clears this side of it.
+   *
+   * Diagnostic only: nothing is repositioned on the strength of a browser's
+   * reading, deliberately, because a wrong answer here would restart an encoder
+   * the viewer is waiting on.
+   *
+   * @param {string} sessionId
+   * @param {{ sn: number, track?: string, fragStartSec: number, bufferEndSec: number, currentTimeSec: number }} report
+   * @returns {boolean} False when no such session exists.
+   */
+  recordFragmentFar(sessionId, { sn, track, fragStartSec, bufferEndSec, currentTimeSec }) {
+    const named = this.sessionsById.get(sessionId);
+    if (!named || named.state === "disposed") {
+      return false;
+    }
+    // Which of the two streams the report is about. The browser addresses
+    // everything to the video session's id — the soundtrack is served under
+    // `/a/<n>/` on that same id — but it is a session of its own, with its own
+    // run and its own position, and that is exactly the pair this report exists
+    // to tell apart. Answering an audio report from the picture's records would
+    // state, confidently, something about the wrong stream.
+    const onScreen = this.#activeVariant(named);
+    const session = track === "audio"
+      ? ([...this.#familyOf(onScreen)].find((member) => member.audioOnly === true) ?? onScreen)
+      : onScreen;
+    const gap = fragStartSec - bufferEndSec;
+    const declared = this.#publishedStartTime(session, sn);
+    const trueStart = session.trueStartByIndex instanceof Map ? session.trueStartByIndex.get(sn) : undefined;
+    const verdict = trueStart === undefined
+      // Where a segment truly began is only ever read off one that was cut on
+      // an explicit list — a uniform grid has nothing to read back — so this is
+      // "not recorded", which is not the same as "not produced", and the line
+      // must not claim the second.
+      ? "where that segment began is not recorded on this side, so the gap cannot be attributed here"
+      : (() => {
+        const at = this.#boundaryIndexAt(session, trueStart, this.publishedGridFor(session));
+        if (at === null) {
+          return `it really began at ${trueStart.toFixed(3)}s, which is no boundary of this grid`;
+        }
+        if (at === sn) {
+          return `it really began at boundary #${sn}, where it should — the gap is not this run's`;
+        }
+        return `it really began at boundary #${at}, ${sn - at} place(s) before its own number — ` +
+          "this run's output does not match its numbering";
+      })();
+    logger.warn(
+      `transcode ${session.id} the player is stuck: ${session.audioOnly === true ? "sound" : "picture"} ` +
+      `fragment #${sn} starts ${gap.toFixed(1)}s past ` +
+      `the end of its buffer (${bufferEndSec.toFixed(1)}s, viewer at ${currentTimeSec.toFixed(1)}s, ` +
+      `the playlist puts it at ${declared.toFixed(3)}s) — ${verdict}`
+    );
+    return true;
+  }
+
   /**
    * Observed produced bitrate (Mbit/s) averaged over the last few COMPLETED
    * segment files (the newest file may still be being written and is
@@ -3721,7 +3889,7 @@ export class HlsSessionManager {
     const head = session.encodeStartIndex;
     const processed = Number.isFinite(session.progress?.processedSeconds)
       ? session.progress.processedSeconds
-      : this.#segmentStartTime(session, head);
+      : this.runStartTimeFor(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
     const boundLabel =
       bound === "link" ? "viewer-link-bound" : bound === "unknown" ? "assuming CPU-bound" : "CPU-bound";
@@ -3763,9 +3931,18 @@ export class HlsSessionManager {
    *
    * @param {HlsSession} session
    * @param {number} startIndex
+   * @param {number} [positionSecondsOverride] - Begin the run at this instant
+   *   instead of at the time the playlist gives `startIndex`, keeping the
+   *   numbering and the cut list on the published grid. The one caller is the
+   *   realignment below: a COPIED picture cannot cut anywhere but at the
+   *   source's own keyframes, so its segment #N begins where the file says and
+   *   not where the grid does — and the sound that plays with it has to begin
+   *   at that same instant, or the two are apart by the difference. The output
+   *   is still labelled from the source clock (`-copyts`) and stamped on serve,
+   *   so the player sees both at the time the playlist names.
    * @returns {Promise<void>}
    */
-  async #startEncodeRun(session, startIndex) {
+  async #startEncodeRun(session, startIndex, positionSecondsOverride) {
     // A new run starts its own reckoning: a pair spanning the restart would
     // count the gap between two runs as slow encoding.
     session.learnSample = null;
@@ -3864,8 +4041,30 @@ export class HlsSessionManager {
     }
 
     const safeIndex = Number.isInteger(startIndex) && startIndex > 0 ? startIndex : 0;
-    // 0-based output time of this segment, from the boundary table.
-    const startSeconds = this.#segmentStartTime(session, safeIndex);
+    // 0-based output time of this segment, from the table the PLAYER holds —
+    // the same one the cut list below is taken from.
+    //
+    // These two were read from different tables until 2026-08-21, and that is
+    // one fault, not two: `-segment_times` are measured from wherever the run
+    // really began, so any distance between the position and the cut list moves
+    // EVERY cut of that run by it. The live table keeps being corrected as
+    // produced segments reveal where the file's cuts truly are, and those
+    // corrections run backwards, so each restart began a little earlier than
+    // the grid the cuts were stated on — and since the corrections accumulate,
+    // so did the distance. Measured on `JUFD665.mp4`: after one seek restart a
+    // produced segment held the boundary two places before its own number
+    // (16.684 s, exactly 2.0000 segments), after the next it held the one four
+    // places before (33.5 s). The player's buffer then stops extending at all,
+    // because the content of every fragment lands before the time its playlist
+    // entry names: `bufferEnd` stood still at 4571.1 s through four `frag-far`
+    // warnings until hls.js gave up and jumped the viewer 16.8 s forward.
+    //
+    // 2.45.0 moved the CUT LIST onto the published table for this same reason
+    // and left the position on the live one. Both belong on the published
+    // table: a run must begin where the player was told the segment begins.
+    const startSeconds = Number.isFinite(positionSecondsOverride)
+      ? positionSecondsOverride
+      : this.runStartTimeFor(session, safeIndex);
     const sourceStartTime = Number.isFinite(session.sourceStartTime) ? session.sourceStartTime : 0;
     // Cut where this session's grid says, whoever is producing the frames. The
     // times are measured from the start of THIS run; the same list serves as
@@ -4157,6 +4356,17 @@ export class HlsSessionManager {
       `(+${Date.now() - restartEnteredAt}ms since the restart was asked for) ` +
         `(${formatSeconds(startSeconds)}) "${session.fileName}"`
     );
+    // The four numbers a run is positioned by, said once, because their
+    // disagreement is invisible everywhere else. The two tables are printed
+    // side by side: while they differ, every cut of this run is off by the
+    // difference, and nothing downstream can tell that from a bad index.
+    const liveStart = this.#segmentStartTime(session, safeIndex);
+    logger.info(
+      `transcode ${session.id} ${session.runLabel} positioned at ${startSeconds.toFixed(3)}s ` +
+        `for boundary #${safeIndex} (published ${startSeconds.toFixed(3)}s, ` +
+        `live ${liveStart.toFixed(3)}s, apart ${(liveStart - startSeconds).toFixed(3)}s), ` +
+        `numbering from #${safeIndex}`
+    );
 
     this.#wireEncodeProcess(session, ffmpeg);
   }
@@ -4476,7 +4686,7 @@ export class HlsSessionManager {
     // request just ahead of the live edge.
     const processed = Number.isFinite(session.progress?.processedSeconds)
       ? session.progress.processedSeconds
-      : this.#segmentStartTime(session, head);
+      : this.runStartTimeFor(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
     const withinWindow = index >= head && index <= currentSeg + MAX_LOOKAHEAD_SEGMENTS;
     if (withinWindow) {
@@ -4769,7 +4979,7 @@ export class HlsSessionManager {
     const head = session.encodeStartIndex;
     const processed = Number.isFinite(session.progress?.processedSeconds)
       ? session.progress.processedSeconds
-      : this.#segmentStartTime(session, head);
+      : this.runStartTimeFor(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
     // Already covered by the running encode — the data is on its way, so
     // restarting would only destroy work the viewer is waiting for. The run has
@@ -5205,7 +5415,17 @@ export class HlsSessionManager {
       return;
     }
     session.landingReportedForRun = index;
-    const asked = this.#segmentStartTime(session, index);
+    // What the run was ASKED for, taken from the run itself rather than looked
+    // up again in a table. The two used to be the same lookup; they stopped
+    // being so when a run began positioning on the published grid while this
+    // read the live one, which made a perfect landing report a drift equal to
+    // the distance between the tables — and cancelled a real landing error of
+    // the same size to zero. A run also has one legitimate position that is in
+    // no table at all: the realignment that starts the sound where the copied
+    // picture truly begins.
+    const asked = Number.isFinite(session.progress?.startPositionSeconds)
+      ? session.progress.startPositionSeconds
+      : this.runStartTimeFor(session, index);
     const drift = trueStart - asked;
     if (!Number.isFinite(drift) || Math.abs(drift) <= PLAYER_BUFFER_HOLE_SEC) {
       return;
@@ -5220,6 +5440,18 @@ export class HlsSessionManager {
   #noteIndexAccuracy(session, index, trueStart, declaredStart) {
     const deviation = Math.abs(trueStart - declaredStart);
     session.indexCheck ??= newIndexCheck();
+    // Where each produced segment truly began, kept so that a player reporting
+    // a stall can be ANSWERED rather than merely believed. Bounded: only the
+    // recent past can be the subject of such a report, and an unbounded map on
+    // a two-hour film is a leak.
+    session.trueStartByIndex ??= new Map();
+    session.trueStartByIndex.set(index, trueStart);
+    if (session.trueStartByIndex.size > TRUE_START_MEMORY) {
+      const oldest = session.trueStartByIndex.keys().next();
+      if (!oldest.done) {
+        session.trueStartByIndex.delete(oldest.value);
+      }
+    }
     // Did this segment begin at ANOTHER keyframe from the same list? Half an
     // audio frame is the tolerance — anything the list names is exact, so a
     // match is a match. `keyframeTimes` is the list the grid was built from, so
@@ -5264,7 +5496,18 @@ export class HlsSessionManager {
             // rung's segments no longer stand where the stream it accompanies
             // would have put them. That is a broken splice, not a wrong index.
             ? "this rung did not cut where its grid says; a switch to it will not join cleanly"
-            : "the container's keyframe index disagrees with the file; using the file")
+            // A copy. The two possible faults need opposite fixes and the
+            // numbers already tell them apart, so the sentence follows THEM
+            // rather than the branch it is printed from. Until 2026-08-21 it
+            // blamed the index either way — including through a session whose
+            // segments each held the boundary two, then four places before
+            // their own number, which is this code's own definition of a fault
+            // in this code. That sentence is what sent the reading of that
+            // session after the file instead of after the arithmetic.
+            : at === null
+              ? "the container's keyframe index disagrees with the file; using the file"
+              : `this began at another boundary of the same list, ${index - at} place(s) before ` +
+                "its own number — the numbering of this run is shifted, not the index")
         );
       }
     }
@@ -5347,7 +5590,9 @@ export class HlsSessionManager {
     }
     logger.info(
       `transcode ${session.id} boundary #${index} corrected ${wasAt.toFixed(3)}s → ` +
-      `${trueStart.toFixed(3)}s from the file itself`
+      `${trueStart.toFixed(3)}s from the file itself` +
+      `, and the live table is now ${describeGridDrift(this.publishedGridFor(session), boundaries)}` +
+      " from the one the player holds"
     );
     // And every OTHER member whose run begins at this very boundary is moved
     // to the same instant.
@@ -5383,9 +5628,18 @@ export class HlsSessionManager {
       // time: a seek decides by index, finds this run already begins at #index,
       // and answers "already within the running encode" — which is true about
       // the index and false about the instant, and it is why the first version
-      // of this fix moved nothing at all. The boundary now holds the corrected
-      // time, so starting the run at this index starts it at that time.
-      void this.#startEncodeRun(member, index).catch(() => {});
+      // of this fix moved nothing at all.
+      //
+      // The instant is passed EXPLICITLY. It used to be smuggled through the
+      // live boundary table — this function had just written `trueStart` into
+      // it, and the run read its position from there — which stopped working
+      // the moment a run began positioning itself on the table the player
+      // holds, as it now must. Smuggled, the restart would land exactly where
+      // it already was: picture and sound would stay apart and a healthy audio
+      // run would be discarded for nothing, which is the shape the field
+      // already showed (eleven restarts in four minutes, eight of them dying
+      // with `run had produced 0.0s`).
+      void this.#startEncodeRun(member, index, trueStart).catch(() => {});
     }
   }
 
@@ -5468,8 +5722,14 @@ export class HlsSessionManager {
    * @param {number} seconds
    * @returns {number | null}
    */
-  #boundaryIndexAt(session, seconds) {
-    const boundaries = session.segmentBoundaries;
+  #boundaryIndexAt(session, seconds, table) {
+    // The table is nameable because the two answer different questions. The
+    // LIVE one says "is this a cut this file actually has", which is what a
+    // reading taken off a produced segment is about. The PUBLISHED one says "is
+    // this a cut the player believes in", which is what a report from the player
+    // is about. Answering one with the other prints an index from one grid
+    // beside a time from the other.
+    const boundaries = Array.isArray(table) ? table : session.segmentBoundaries;
     if (!Array.isArray(boundaries)) {
       return null;
     }
@@ -6848,6 +7108,7 @@ export class HlsSessionManager {
             // creations (field 2026-08-17, corrections of 0.6-2.9 s).
             published: base.publishedBoundaries,
             keyframeTimes: base.keyframeTimes,
+            keyframeTolerance: base.keyframeTolerance,
             containerFormat: base.containerFormat
           }
         : null,
@@ -7949,7 +8210,14 @@ export class HlsSessionManager {
     // causes indistinguishable: an encoder waiting for torrent pieces looks
     // exactly like one that is encoding and simply has not finished. The
     // difference is whether its position has moved at all.
-    const runStartSeconds = this.#segmentStartTime(session, session.encodeStartIndex ?? 0);
+    // Where this run began, from the run — the same reckoning
+    // `processedSeconds` is counted in. A table lookup here can disagree with
+    // it by the distance between the two grids, which is enough to print a
+    // negative "produced" and send the reader after the torrent when the
+    // encoder is the subject.
+    const runStartSeconds = Number.isFinite(session.progress?.startPositionSeconds)
+      ? session.progress.startPositionSeconds
+      : this.runStartTimeFor(session, session.encodeStartIndex ?? 0);
     const position = Number(session.progress?.processedSeconds);
     const produced = Number.isFinite(position) ? position - runStartSeconds : null;
     const speed = session.progress?.speed ?? "n/a";

package/services/torrent-pool.js

@@ -7,6 +7,7 @@
  */
 
 import crypto from "node:crypto";
+import dns from "node:dns/promises";
 import os from "node:os";
 import path from "node:path";
 import { rmSync, statfsSync } from "node:fs";
@@ -14,6 +15,39 @@ import WebTorrent from "webtorrent";
 import { logger } from "../utils/logger.js";
 import { SharedPieceStore, findSharedStore } from "./piece-store/shared-piece-store.js";
 
+// The DHT's entry points. Two of the three the library ships answer nothing —
+// measured 2026-08-21 from the addon host: `router.bittorrent.com` and
+// `router.utorrent.com` did not reply to a hand-written `ping` at all, while a
+// control datagram to a DNS server came back in 20 ms, so the silence is
+// theirs. They stay in the list because they cost nothing and may come back;
+// what the list needed was entries that answer today.
+//
+// The names are RESOLVED HERE, to IPv4, and the addresses are what the library
+// is given. That is the second half of the fault: `dht.transmissionbt.com` is
+// alive — it answered `find_node` with eight nodes — but on a host with global
+// IPv6 its name resolves to an IPv6 address first, and the DHT's socket is
+// IPv4, so by name the one live entry was never reached. Measured the same day:
+// by name, 0 nodes after 21 s, every run; by address, 22 nodes in 5 s.
+//
+// Addresses are not written down. They rot exactly as the old list rotted.
+const DHT_BOOTSTRAP_NAMES = [
+  "dht.transmissionbt.com:6881",
+  "dht.libtorrent.org:25401",
+  "router.bittorrent.com:6881",
+  "router.utorrent.com:6881"
+];
+
+// How long after start a still-empty routing table is worth saying out loud.
+// Bootstrapping takes seconds; a table empty after this is a list that has died
+// and nobody has noticed, which is the state this host was found in.
+const DHT_EMPTY_REPORT_MS = 60 * 1000;
+
+// How long one bootstrap name may take to resolve. This is awaited before the
+// torrent client is built, so it is time during which the thread answers
+// nothing — and the DHT is best-effort, so a name that is slow to resolve is
+// worth less than the delay of waiting for it.
+const DHT_RESOLVE_TIMEOUT_MS = 2000;
+
 // WebTorrent's default download root (see webtorrent lib/torrent.js: TMP =
 // path.join(os.tmpdir(), 'webtorrent')). We use the default store, so all
 // torrent data lives under here.
@@ -449,6 +483,103 @@ function isMagnetSource(torrentId) {
   return typeof torrentId === "string" && /^magnet:\?/i.test(torrentId.trim());
 }
 
+/**
+ * Split a `host` or `host:port` bootstrap entry.
+ *
+ * @param {unknown} entry
+ * @returns {{ host: string, port: number } | null} Null for anything that is
+ *   not a usable entry, so a typo drops one node instead of failing the client.
+ */
+export function parseBootstrapEntry(entry) {
+  if (typeof entry !== "string") {
+    return null;
+  }
+  const trimmed = entry.trim();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  const colon = trimmed.lastIndexOf(":");
+  if (colon < 0) {
+    return { host: trimmed, port: 6881 };
+  }
+  const host = trimmed.slice(0, colon);
+  const port = Number(trimmed.slice(colon + 1));
+  if (host.length === 0 || !Number.isInteger(port) || port <= 0 || port > 65535) {
+    return null;
+  }
+  return { host, port };
+}
+
+/**
+ * Turn bootstrap names into `address:port` entries, keeping only IPv4.
+ *
+ * Why the resolution happens here rather than being left to the library: the
+ * DHT's socket is IPv4, and a name that resolves to IPv6 first is silently
+ * unreachable through it — which is how a live bootstrap node came to look
+ * dead on this host. See {@link DHT_BOOTSTRAP_NAMES}.
+ *
+ * Best-effort by construction. A name that does not resolve is dropped and
+ * said; if none resolve the caller gets an empty list and the library keeps its
+ * own defaults, which is no worse than before.
+ *
+ * @param {string[]} [names]
+ * @param {number} [timeoutMs] - How long one name may take before it is
+ *   treated as unresolvable.
+ * @returns {Promise<string[]>}
+ */
+export async function resolveDhtBootstrap(names = DHT_BOOTSTRAP_NAMES, timeoutMs = DHT_RESOLVE_TIMEOUT_MS) {
+  const entries = names.map(parseBootstrapEntry).filter((entry) => entry !== null);
+  const resolved = [];
+  const failed = [];
+  await Promise.all(
+    entries.map(async ({ host, port }) => {
+      try {
+        // Capped, because this is awaited before the torrent client exists and
+        // therefore before this thread will answer anything. `dns.resolve4`
+        // talks to the host's resolver with c-ares' own defaults — about five
+        // seconds times four tries — so a black-holing resolver would hold the
+        // whole worker for twenty seconds with nothing said. A name that does
+        // not answer inside the cap is treated exactly like one that fails:
+        // dropped, named, and the rest of the list stands.
+        const addresses = await Promise.race([
+          dns.resolve4(host),
+          new Promise((_resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("timed out")), timeoutMs);
+            timer.unref?.();
+          })
+        ]);
+        for (const address of addresses) {
+          resolved.push(`${address}:${port}`);
+        }
+      } catch {
+        failed.push(`${host}:${port}`);
+      }
+    })
+  );
+  if (failed.length > 0) {
+    logger.warn(`torrent-pool: DHT bootstrap names that do not resolve to IPv4: ${failed.join(", ")}`);
+  }
+  return resolved;
+}
+
+/**
+ * How many nodes the client's DHT knows, or null when it has no DHT at all.
+ *
+ * @param {{ dht?: { nodes?: { toArray?: () => unknown[] } } }} client
+ * @returns {number | null}
+ */
+export function dhtNodeCount(client) {
+  const nodes = client?.dht?.nodes;
+  if (!nodes || typeof nodes.toArray !== "function") {
+    return null;
+  }
+  try {
+    return nodes.toArray().length;
+  } catch {
+    return null;
+  }
+}
+
 export class TorrentPool {
   /**
    * In-flight `client.add()` promises keyed by the same key as `torrents`.
@@ -521,13 +652,16 @@ export class TorrentPool {
   /** Periodic adaptive-upload adjustment timer. */
   #uploadAdjustTimer = null;
 
+  /** One-shot timer that reports the size of the DHT's routing table. */
+  #dhtReportTimer = null;
+
   /**
    * @param {{ maxDiskBytes?: number }} [options]
    *   `maxDiskBytes` caps total downloaded torrent data; when omitted a
    *   default is computed from free disk (min(10 GB, half free)). Pass 0 to
    *   disable the cap.
    */
-  constructor({ maxDiskBytes, memoryBytes } = {}) {
+  constructor({ maxDiskBytes, memoryBytes, dhtBootstrap } = {}) {
     this.#memoryBytes = Number.isFinite(memoryBytes) && memoryBytes > 0 ? memoryBytes : undefined;
 
     // Sweep orphaned torrent data left by a previous hard kill (no graceful
@@ -541,8 +675,33 @@ export class TorrentPool {
       logger.warn(`torrent-pool: could not sweep orphaned store at startup: ${message}`);
     }
 
+    const bootstrap = Array.isArray(dhtBootstrap) ? dhtBootstrap.filter(Boolean) : [];
+    if (bootstrap.length > 0) {
+      logger.info(`torrent-pool: DHT bootstrap nodes: ${bootstrap.join(", ")}`);
+    } else {
+      logger.warn("torrent-pool: no DHT bootstrap nodes resolved; the library's own list is all there is");
+    }
     /** @type {import("webtorrent").WebTorrent} */
-    this.client = new WebTorrent();
+    this.client = new WebTorrent(bootstrap.length > 0 ? { dht: { bootstrap } } : undefined);
+    // A bootstrap list rots, and it rots silently: the one the library ships
+    // had two dead entries and a third that could not be reached by name, and
+    // nothing said so for as long as that was true. Say it once, late enough
+    // that a slow bootstrap is not mistaken for a dead one.
+    this.#dhtReportTimer = setTimeout(() => {
+      const nodes = dhtNodeCount(this.client);
+      if (nodes === null) {
+        return;
+      }
+      if (nodes === 0) {
+        logger.warn(
+          "torrent-pool: the DHT knows no nodes a minute after start — its bootstrap list is not " +
+          "answering, so a torrent has only its trackers to find peers with"
+        );
+        return;
+      }
+      logger.info(`torrent-pool: the DHT knows ${nodes} nodes`);
+    }, DHT_EMPTY_REPORT_MS);
+    this.#dhtReportTimer.unref?.();
 
     /**
      * Active torrents keyed by `"${sourceType}:${sha1(source)}"`.
@@ -1681,6 +1840,10 @@ export class TorrentPool {
       clearInterval(this.#uploadAdjustTimer);
       this.#uploadAdjustTimer = null;
     }
+    if (this.#dhtReportTimer) {
+      clearTimeout(this.#dhtReportTimer);
+      this.#dhtReportTimer = null;
+    }
     // Cancel any pending idle-removal timers — destroyAll handles teardown.
     for (const timer of this.#idleTimers.values()) {
       clearTimeout(timer);

package/services/torrent-worker/worker.js

@@ -35,12 +35,19 @@ import { Command, Event } from "./protocol.js";
 // would drag in WebTorrent — and with it the real `webrtc-polyfill` — before
 // the hook above had a chance to register. Verified the hard way: with a static
 // import the process still aborted, and the stack named the genuine polyfill.
-const { TorrentPool } = await import("../torrent-pool.js");
+const { TorrentPool, resolveDhtBootstrap } = await import("../torrent-pool.js");
 const { collectStoreStats, findSharedStore } = await import("../piece-store/shared-piece-store.js");
 
+// Resolved before the client exists, because the client builds its DHT in its
+// own constructor and the addresses have to be in hand by then. Awaiting here
+// costs the few milliseconds of a DNS answer, once, on a thread that has not
+// been asked for anything yet.
+const dhtBootstrap = await resolveDhtBootstrap();
+
 const pool = new TorrentPool({
   maxDiskBytes: workerData?.maxDiskBytes,
-  memoryBytes: workerData?.memoryBytes
+  memoryBytes: workerData?.memoryBytes,
+  dhtBootstrap
 });
 
 /** Torrents by sourceKey — the main thread names them, this thread owns them. */

package/test/dht-bootstrap.test.js

@@ -0,0 +1,72 @@
+/**
+ * @file The DHT's entry points are given as addresses, not names.
+ *
+ * Measured 2026-08-21 on the addon host. Two of the three bootstrap nodes the
+ * library ships answer nothing: `router.bittorrent.com` and `router.utorrent.com`
+ * did not reply to a hand-written `ping` at all, while a control datagram to a
+ * DNS server came back in 20 ms. The third, `dht.transmissionbt.com`, is alive —
+ * it answered `find_node` with eight nodes — but on a host with global IPv6 its
+ * name resolves to an IPv6 address first, and the DHT's socket is IPv4, so by
+ * name it was never reached. By name: 0 nodes after 21 s, every run. By address:
+ * 22 nodes in 5 s.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { dhtNodeCount, parseBootstrapEntry, resolveDhtBootstrap } from "../services/torrent-pool.js";
+
+test("a bootstrap entry is split into host and port", () => {
+  assert.deepEqual(parseBootstrapEntry("dht.libtorrent.org:25401"), {
+    host: "dht.libtorrent.org",
+    port: 25401
+  });
+});
+
+test("an entry with no port gets the DHT's own", () => {
+  assert.deepEqual(parseBootstrapEntry("router.bittorrent.com"), {
+    host: "router.bittorrent.com",
+    port: 6881
+  });
+});
+
+test("an unusable entry is dropped rather than breaking the client", () => {
+  // One bad line in the list must cost that node and nothing else — the DHT is
+  // best-effort by nature and a typo here would otherwise take the whole client
+  // down at construction.
+  assert.equal(parseBootstrapEntry(""), null);
+  assert.equal(parseBootstrapEntry("   "), null);
+  assert.equal(parseBootstrapEntry("host:0"), null);
+  assert.equal(parseBootstrapEntry("host:70000"), null);
+  assert.equal(parseBootstrapEntry("host:not-a-port"), null);
+  assert.equal(parseBootstrapEntry(":6881"), null);
+  assert.equal(parseBootstrapEntry(null), null);
+  assert.equal(parseBootstrapEntry(42), null);
+});
+
+test("the routing table's size is readable, and its absence is not an error", () => {
+  assert.equal(dhtNodeCount({ dht: { nodes: { toArray: () => [1, 2, 3] } } }), 3);
+  assert.equal(dhtNodeCount({ dht: { nodes: { toArray: () => [] } } }), 0);
+  // A client built without a DHT, or one whose internals moved: the difference
+  // between "no DHT" and "an empty DHT" is the whole point of the report, so
+  // the first must not be printed as the second.
+  assert.equal(dhtNodeCount({}), null);
+  assert.equal(dhtNodeCount({ dht: {} }), null);
+  assert.equal(dhtNodeCount(null), null);
+  assert.equal(dhtNodeCount({ dht: { nodes: { toArray: () => { throw new Error("gone"); } } } }), null);
+});
+
+test("a name that will not resolve inside the cap is dropped, not waited on", async () => {
+  // The whole call is awaited before the torrent client exists, so a resolver
+  // that black-holes must cost the cap and not c-ares' own four tries.
+  const started = Date.now();
+  // `.invalid` is reserved by RFC 2606 and never resolves; the cap is what
+  // bounds the wait when a resolver answers slowly rather than quickly.
+  const resolved = await resolveDhtBootstrap(["nothing.invalid:6881"], 200);
+  assert.deepEqual(resolved, []);
+  assert.ok(Date.now() - started < 2000, "the cap, not the resolver, decided when to give up");
+});
+
+test("an empty list is an answer, not a failure", async () => {
+  assert.deepEqual(await resolveDhtBootstrap([], 200), []);
+});

package/test/run-position-follows-published-grid.test.js

@@ -0,0 +1,87 @@
+/**
+ * @file A run is POSITIONED where the player was told the segment begins.
+ *
+ * The companion of `cuts-follow-published-grid`, and the half that was missing.
+ * 2.45.0 moved the cut list onto the published table and left the position on
+ * the live one — but `-segment_times` are measured from wherever the run really
+ * began, so any distance between the two moves EVERY cut of that run by it. The
+ * live table keeps being corrected, and the corrections run backwards, so each
+ * restart began a little earlier than the grid its cuts were stated on and the
+ * distance accumulated across restarts.
+ *
+ * Field 2026-08-21, `JUFD665.mp4` (MP4, copy path, index read cleanly): after
+ * one seek restart a produced segment held the boundary two places before its
+ * own number — 16.684 s, which is 2.0000 segments — and after the next restart,
+ * four places, 33.5 s. The player's buffer then stopped extending at all,
+ * because every fragment's content landed before the time its playlist entry
+ * named: `bufferEnd` stood still at 4571.1 s through four `frag-far` warnings
+ * until hls.js gave up and jumped the viewer 16.8 s forward.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { HlsSessionManager, describeGridDrift, segmentCutTimesFrom } from "../services/hls-session-manager.js";
+
+/** What the playlist in the player's hands says. */
+const PUBLISHED = [0, 8.342, 16.684, 25.026, 33.368, 41.71];
+/** The same grid after produced segments moved two of its cuts backwards. */
+const CORRECTED = [0, 8.342, 14.682, 25.026, 31.366, 41.71];
+
+/**
+ * @returns {{ manager: HlsSessionManager, session: object }}
+ */
+function sessionWithDriftedGrid() {
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: "picture",
+    segmentBoundaries: [...CORRECTED],
+    publishedBoundaries: [...PUBLISHED]
+  };
+  return { manager, session };
+}
+
+test("a run starts at the time the player was told, not at the corrected one", () => {
+  const { manager, session } = sessionWithDriftedGrid();
+  assert.equal(manager.runStartTimeFor(session, 2), 16.684);
+  assert.notEqual(manager.runStartTimeFor(session, 2), session.segmentBoundaries[2]);
+});
+
+test("position and cut list come from the same table", () => {
+  const { manager, session } = sessionWithDriftedGrid();
+  const grid = manager.publishedGridFor(session);
+  const start = manager.runStartTimeFor(session, 2);
+  // The cut list is stated as offsets from where the run begins. Adding the
+  // position back must land on the published boundaries exactly — which is the
+  // property that was false while the two came from different tables.
+  const absolute = segmentCutTimesFrom(grid, 2).map((offset) => Number((start + offset).toFixed(3)));
+  assert.deepEqual(absolute, [25.026, 33.368]);
+});
+
+test("a session that published no grid positions on the live one", () => {
+  const { manager } = sessionWithDriftedGrid();
+  const session = { id: "no-playlist", segmentBoundaries: [...CORRECTED], publishedBoundaries: [] };
+  assert.equal(manager.runStartTimeFor(session, 2), CORRECTED[2]);
+});
+
+test("an index beyond the table is clamped rather than returning nothing", () => {
+  const { manager, session } = sessionWithDriftedGrid();
+  assert.equal(manager.runStartTimeFor(session, 9999), PUBLISHED[PUBLISHED.length - 1]);
+  assert.equal(manager.runStartTimeFor(session, -3), PUBLISHED[0]);
+});
+
+test("the drift between the two tables is stated in full", () => {
+  assert.equal(describeGridDrift(PUBLISHED, PUBLISHED), "identical");
+  assert.equal(
+    describeGridDrift(PUBLISHED, CORRECTED),
+    "2 of 6 boundaries apart, worst 2.002s at #2"
+  );
+  assert.equal(describeGridDrift(PUBLISHED, [0, 1]), "a different length (6 against 2)");
+  assert.equal(describeGridDrift(null, CORRECTED), "not comparable");
+  assert.equal(describeGridDrift([], []), "not comparable");
+});

package/test/seek-landing.test.js

@@ -48,3 +48,29 @@ test("no keyframe list is still answered", () => {
   assert.equal(seekLandingOffsetFor({ transcodeVideo: false }, 5), OFFSET);
   assert.equal(seekLandingOffsetFor(null, 5), OFFSET);
 });
+
+test("a grid whose times are approximate is asked for that much later again", () => {
+  // AVI names a keyframe by its frame NUMBER and the time is that number times
+  // the frame duration, so a name can sit just BELOW the keyframe it refers to
+  // — measured 2026-08-21, 10-44 ms out on two files, always under one frame.
+  // Asking at the name alone would seek to before the real keyframe and land on
+  // the one before that, which is the fault this offset exists for.
+  const session = {
+    transcodeVideo: false,
+    keyframeTolerance: 0.04,
+    keyframeTimes: [0, 4.004, 8.008, 12.012]
+  };
+  assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET + 0.04);
+});
+
+test("an exact grid claims no tolerance", () => {
+  // Matroska and MP4 state instants outright — measured the same day, nine
+  // files and 11 665 keyframes with not one disagreement.
+  const session = { transcodeVideo: false, keyframeTolerance: 0, keyframeTimes: [0, 4.004, 8.008] };
+  assert.equal(seekLandingOffsetFor(session, 4.004), OFFSET);
+});
+
+test("the bound still holds once a tolerance is added", () => {
+  const session = { transcodeVideo: false, keyframeTolerance: 1, keyframeTimes: [0, 0.1, 0.2] };
+  assert.equal(seekLandingOffsetFor(session, 0.1), 0.05);
+});