@torrent-tv/proxy 2.9.87 → 2.9.89

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.89
+
+- **Fix**: What the torrent downloads is now decided by the readers, and by nobody else. Three places were claiming pieces for the same file and overwriting each other on every request: `acquireFile` selected the whole file, `prioritizeByteRange` selected from the read position to the end, and the reader selected its entire requested range. The reader's claim was the worst of the three — ffmpeg opens its input as `bytes <position>-<EOF>`, so the first read of a session claimed the **whole file** and marked **every piece critical**, and nothing ever gave it back, because that read is abandoned a second later when ffmpeg seeks. No later prioritisation could outrank a permanent whole-file claim, which is why 2.9.88 changed nothing measurable. Each read now holds a moving window ahead of its own head, as a **stream selection** — the kind WebTorrent counts rather than merges, so several parallel readers (the codec probe's head and tail, subtitles, one input per viewer) produce the union of their windows — and releases it on completion, cancellation and abandonment. `critical` marks only the piece being waited for and at most two more, which is the rule WebTorrent's own reader uses and what the flag is supposed to mean. `prioritizeByteRange` keeps only what readers cannot do: the read position for the resume figures, and the jump log line.
+- **Fix**: A seek releases the segment requests it made pointless. hls.js keeps one fragment load outstanding, so a request being held for the old position blocks the one for the new position — measured 2026-08-04: a backward seek into fully downloaded data waited **57 s** for a held request for `#609` to run out the 60 s hold, then fetched the segment it wanted in 15 ms. The same hold trapped 45 requests at once during a forward seek. A viewer seek now ends every wait that started before it with a retryable 503, as `hls-media-server` does (`research/hls-seek-prior-art-2026-08-02.md`, prescribed there and never built).
+
+## 2.9.88
+
+- **Fix**: A seek no longer makes the swarm walk the file to get there. Two faults, both confirmed by running WebTorrent's own selection code on the numbers of a measured session (588 pieces, download at 38.4%, seek to 89.1%). First: a selection carries an `offset` — how many pieces from its start are already downloaded — and the picker scans from `from + offset`; `deselect` subtracts an interval and copies that offset into what survives, so demoting the pieces behind the playhead left `{523-587, offset 226}`, a selection whose scan begins at piece 749 of 587. The seek target ended up wanted by nobody. The range is now re-selected right after the demotion, which replaces the dead entry with a fresh one starting at the playhead. Second: a request with no byte range was reported as an ordinary read at offset 0, and ffmpeg opens its input with exactly such a request and abandons it as soon as it seeks — as do the keyframe index and the codec probe, four of them around every encoder restart. Each one re-selected the whole file from piece zero, undoing the seek; the picker then skipped what was on disk and downloaded forward from the first hole. Measured cost of the pair: a seek to 89.1% of a 4.7 GB film fetched **2.47 GB over 93 s** where one 8 MiB piece was needed. A range-less read now sets the read position only when nothing else has.
+
 ## 2.9.87
 
 - **Fix**: fMP4 playback no longer stops after the first segment. A segment's position was being written into **every** fragment it contains, and the explicit-cut muxer puts several in one segment — `frag_keyframe` opens a fragment at each keyframe while a cut point comes only every few keyframes. Measured: a 6 s piece carries three fragments per track, at 0, 2 and 4 s of its own clock; all three were stamped with the segment's start, so they claimed the same decode time and the player rejected the segment. In the field (2.9.86, this session) that showed as segments 1 and 2 requested in an endless alternation, each served in tens of milliseconds with the transcode healthy at 12x, while the picture froze a few seconds in. The position is now applied as a shift: each track's first fragment sets the base and the rest keep their distance from it. With one fragment per track — what the `hls` muxer produces — a shift and a write are the same thing, so the other path is unchanged. Verified end to end on the addon host: four pieces cut, split, stamped and reassembled the way a player does, then probed — 600 frames over 24 s, decode timestamps rising by exactly 0.04 s across every segment join, no duplicates, clean decode.

package/package.json

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

package/routes/stream/get.js

@@ -94,7 +94,9 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool
   // byte offset) downloads first instead of waiting behind the sequential
   // backlog — this is what caused ~15-18 s stalls when seeking into an
   // undownloaded region.
-  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0);
+  torrentPool.prioritizeByteRange(torrent, fileIndex, range ? range.start : 0, undefined, {
+    wholeFileRead: range === null
+  });
 
   const start = range ? range.start : 0;
   const end = range ? range.end : file.length - 1;

package/routes/transcode/session-file/get.js

@@ -75,6 +75,13 @@ export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionMana
   if (result.kind === "not-found") {
     return reply.code(404).send({ error: "Transcode session file was not found." });
   }
+  if (result.kind === "superseded") {
+    // The viewer moved while this was being held. Answer at once so the player
+    // can ask for where it is now; `Retry-After: 0` because there is nothing to
+    // wait for — this segment is simply no longer the one being watched.
+    reply.header("Retry-After", "0");
+    return reply.code(503).send({ error: "Superseded by a seek." });
+  }
   if (result.kind === "warming-up") {
     // The segment is still being produced (e.g. just after a seek-restart).
     // Return a retryable 503 — never 202, which hls.js cannot consume as a
@@ -122,11 +129,21 @@ async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeou
   // again — see HlsSessionManager#ensureEncodingFor for the encoder ping-pong
   // this prevents when one seek-bar scrub fires several segment requests.
   const requestSeq = hlsSessionManager.nextRequestSeq(sessionId);
+  // The viewer's position when this request was made. A seek makes every held
+  // request stale — it asks for a segment nobody is going to watch — and hls.js
+  // keeps only ONE fragment load outstanding, so holding on blocks the request
+  // the player actually needs now. Measured: 57 s of a 58 s backward seek was
+  // this wait, and the segment the viewer wanted took 15 ms once it was asked
+  // for.
+  const seekEpoch = hlsSessionManager.seekEpoch(sessionId);
   while (Date.now() - startedAt < timeoutMs) {
     const result = await hlsSessionManager.getFileStream(sessionId, fileName, { requestSeq });
     if (result.kind !== "warming-up") {
       return result;
     }
+    if (hlsSessionManager.seekEpoch(sessionId) !== seekEpoch) {
+      return { kind: "superseded" };
+    }
     await delay(300);
   }
   return { kind: "warming-up" };

package/services/hls-session-manager.js

@@ -1134,6 +1134,9 @@ export class HlsSessionManager {
       // from one scrub cannot take turns steering the encoder.
       requestSeqCounter: 0,
       latestRequestSeq: 0,
+      // Bumped by every viewer seek; a held segment request that started under
+      // an older value gives up at once. See requestSeek.
+      waitEpoch: 0,
       seekFirstFarAt: 0,
       // Circuit breaker: consecutive FAST failures (see SEEK_FAST_FAIL_MS) at
       // seekFailureTarget. Reset whenever a run starts at a DIFFERENT target or
@@ -2233,6 +2236,16 @@ export class HlsSessionManager {
     if (!session || session.state === "disposed") {
       return false;
     }
+    // Every segment request being held right now was made for the position the
+    // viewer has just left. Release them: hls.js keeps ONE fragment load
+    // outstanding, so until the one in flight answers, the player cannot ask
+    // for the segment it now needs — measured 2026-08-04, a backward seek into
+    // fully-downloaded data waited 57 s for a held request for #609 to time
+    // out, then fetched the segment it wanted in 15 ms. Bumping the epoch makes
+    // those waits answer "retry" on their next poll instead of running out the
+    // 60 s hold. Prescribed by `hls-media-server` (one outstanding wait per
+    // session) in research/hls-seek-prior-art-2026-08-02.md.
+    session.waitEpoch = (session.waitEpoch ?? 0) + 1;
     const index = this.#segmentIndexForTime(session, positionSeconds);
     const head = session.encodeStartIndex;
     const processed = Number.isFinite(session.progress?.processedSeconds)
@@ -2435,6 +2448,20 @@ export class HlsSessionManager {
     return session.requestSeqCounter;
   }
 
+  /**
+   * How many times the viewer has moved since this session started.
+   *
+   * A request being held for a segment answers "retry" as soon as this changes,
+   * because it was made for a position the viewer has left — see `requestSeek`.
+   *
+   * @param {string} sessionId
+   * @returns {number}
+   */
+  seekEpoch(sessionId) {
+    const session = isSafeSessionId(sessionId) ? this.sessionsById.get(sessionId) : null;
+    return session?.waitEpoch ?? 0;
+  }
+
   /**
    * Open a read stream for an HLS segment or playlist file from a session.
    *

package/services/torrent-pool.js

@@ -306,17 +306,6 @@ export class TorrentPool {
    */
   #readPositionByTorrent = new Map();
 
-  /**
-   * Lowest piece currently selected for download, per torrent and fileIndex.
-   *
-   * Needed because selection is not readable back from WebTorrent, and a seek
-   * backward has to know whether the pieces it wants were deselected by an
-   * earlier seek forward.
-   *
-   * @type {Map<import("webtorrent").Torrent, Map<number, number>>}
-   */
-  #selectedFromPiece = new Map();
-
   /** Global disk cap in bytes (0 = disabled). */
   #maxDiskBytes = 0;
 
@@ -982,8 +971,20 @@ export class TorrentPool {
   }
 
   /**
-   * Update WebTorrent piece selection to match the current usage map.
-   * Files with at least one consumer are selected; all others are deselected.
+   * Drop the pieces of files nobody is reading from the download set.
+   *
+   * It does NOT select the files that ARE in use, and that is the point. What a
+   * file needs is decided by the readers walking it: each one claims a moving
+   * window around its own read head and gives it back when it ends (see
+   * `torrent-worker/piece-reader.js`). Selecting the whole file here as well
+   * put a second, contradictory claim on the same pieces — one that covered
+   * everything and therefore always outranked the window — and it was re-made
+   * on every single `/stream` request, so a seek's prioritisation survived at
+   * most until the next one. Measured consequence: a seek to 89.1% of a 4.7 GB
+   * film waited 93 s while the swarm fetched 2.47 GB in file order.
+   *
+   * A file with no reader is deselected outright, which is what stops a torrent
+   * downloading files the viewer never opened.
    *
    * @param {import("webtorrent").Torrent} torrent
    * @param {Map<number, number>} usage - fileIndex → refCount.
@@ -995,14 +996,7 @@ export class TorrentPool {
     }
     for (let index = 0; index < torrent.files.length; index += 1) {
       const file = torrent.files[index];
-      if (!file) {
-        continue;
-      }
-      const shouldSelect = (usage.get(index) ?? 0) > 0;
-      if (shouldSelect) {
-        if (typeof file.select === "function") {
-          file.select();
-        }
+      if (!file || (usage.get(index) ?? 0) > 0) {
         continue;
       }
       if (typeof file.deselect === "function") {
@@ -1012,63 +1006,50 @@ export class TorrentPool {
   }
 
   /**
-   * Bias the torrent's download toward the current read position, so a seek
-   * downloads the seek target first instead of waiting behind the sequential
-   * backlog (which caused ~15-18 s stalls when seeking into an undownloaded
-   * region). Called on every range request.
-   *
-   * Two levers, matched to how WebTorrent's picker actually works:
-   *
-   * 1. **Demote the gap BEHIND the playhead** — `deselect(fileStart, playhead-1)`.
-   *    The picker scans each selection sequentially from its first UNdownloaded
-   *    piece; with the whole file selected, a far forward seek would make it
-   *    fetch the undownloaded gap behind the new position first. Removing that
-   *    gap from the selection makes the scan START at the playhead, so all peer
-   *    capacity goes to the pieces the player needs next. This only STOPS
-   *    fetching the gap; already-downloaded pieces stay on disk (deleting them
-   *    is Disk hygiene Level 2), and a later backward seek re-selects the region
-   *    via this same call. The whole file is re-selected by `file.select()` on
-   *    the next `acquireFile`, so nothing is permanently dropped.
+   * Record where a file is being read from.
    *
-   * 2. **Critical read-ahead window** — `critical(playhead, playhead+window)`.
-   *    `critical` does not reorder the scan; it enables HOTSWAP (re-request a
-   *    block from a faster peer when a slow one reserved it) over the near
-   *    window. Reset first so criticality stays a moving window rather than
-   *    accumulating over the whole file across seeks.
+   * This used to also decide what the torrent should download, and that was the
+   * mistake: it was one of THREE places claiming pieces for the same file — the
+   * whole-file `file.select()` in `#syncSelections`, this method, and the reader
+   * itself — and they overwrote each other on every request. The claim now
+   * belongs to the reader alone, which holds a moving window around its own read
+   * head and gives it back when it ends
+   * (`torrent-worker/piece-reader.js`); several readers on one file therefore
+   * produce the union of their windows instead of the last caller's opinion.
    *
-   * Scope: single active reader per file (≈100% today). The multi-viewer union
-   * window — demote only where behind for ALL sessions — is deferred (roadmap
-   * item 23); here the latest read position wins.
-   *
-   * The pinned head/tail (prefetchFileEdges, codec probe) is downloaded up front
-   * and lives forward of the playhead (tail) or is already on disk (head), so
-   * demotion never costs the probe its data.
+   * What is left here is bookkeeping the readers cannot do: `getFileStats`
+   * reports how much of the window ahead of the read head is still missing, so
+   * the viewer can be shown how long a resume will take, and a jump in the read
+   * position is logged because a seek that never reaches the torrent is
+   * invisible otherwise.
    *
    * @param {import("webtorrent").Torrent} torrent
    * @param {number} fileIndex
    * @param {number} byteStart - Start offset within the file.
-   * @param {number} [windowBytes] - Bytes ahead of `byteStart` to mark critical.
+   * @param {number} [windowBytes] - Unused; kept so callers need not change.
+   * @param {{ wholeFileRead?: boolean }} [options] - `wholeFileRead` marks a
+   *   request that carried no byte range, i.e. one that merely opens the file at
+   *   0 rather than asking to read from there. See the guard below.
    * @returns {void}
    */
-  prioritizeByteRange(torrent, fileIndex, byteStart, windowBytes = PRIORITY_WINDOW_BYTES) {
-    if (!torrent || typeof torrent.critical !== "function" || !Array.isArray(torrent.files)) {
-      return;
-    }
-    const pieceLength = Number(torrent.pieceLength);
-    if (!Number.isFinite(pieceLength) || pieceLength <= 0) {
+  prioritizeByteRange(
+    torrent,
+    fileIndex,
+    byteStart,
+    windowBytes = PRIORITY_WINDOW_BYTES,
+    options = {}
+  ) {
+    if (!torrent || !Array.isArray(torrent.files)) {
       return;
     }
     const file = torrent.files[fileIndex];
     if (!file) {
       return;
     }
-    const fileOffset = Number.isFinite(file.offset) ? file.offset : 0;
     const fileLength = Number(file.length);
     if (!Number.isFinite(fileLength) || fileLength <= 0) {
       return;
     }
-    const fileStartPiece = Math.floor(fileOffset / pieceLength);
-    const fileEndPiece = Math.floor((fileOffset + fileLength - 1) / pieceLength);
 
     const safeStart = Math.max(0, Number(byteStart) || 0);
 
@@ -1080,6 +1061,20 @@ export class TorrentPool {
       this.#readPositionByTorrent.set(torrent, readPositions);
     }
     const previousStart = readPositions.get(fileIndex);
+
+    // A request with no byte range says nothing about where the viewer is. ffmpeg
+    // opens its input with a plain GET and abandons it the moment it seeks, and
+    // the keyframe index and the codec probe do the same — four such reads around
+    // every encoder restart, each one arriving here as "position 0". Acting on
+    // them undoes the seek that just happened: the whole file is re-selected from
+    // piece 0, the picker skips the pieces already on disk and walks the swarm
+    // forward from the first hole. Measured on a 4.7 GB film: a seek to 89.1%
+    // downloaded 2.47 GB over 93 s before the segment could be served. So a
+    // whole-file read only sets the position when nothing else has.
+    if (options.wholeFileRead && previousStart !== undefined) {
+      return;
+    }
+
     readPositions.set(fileIndex, safeStart);
 
     // Log jumps only. Sequential reading calls this on every range request and
@@ -1097,60 +1092,6 @@ export class TorrentPool {
       );
     }
 
-    const absStart = fileOffset + safeStart;
-    const playheadPiece = Math.floor(absStart / pieceLength);
-    const absWindowEnd = Math.min(
-      fileOffset + fileLength - 1,
-      absStart + Math.max(1, windowBytes) - 1
-    );
-    const windowEndPiece = Math.floor(absWindowEnd / pieceLength);
-
-    // (1) Re-select from the playhead when it moved BACK behind what an earlier
-    //     seek deselected. `deselect` removes pieces from the download set, and
-    //     `critical` does NOT put them back — it only flags pieces already
-    //     selected. So without this, a seek forward followed by a seek backward
-    //     leaves the target pieces wanted by nobody: the encoder waits on data
-    //     the torrent was told to stop fetching, and waits forever.
-    //     Only on a backward move, so repeat calls do not pile up selections.
-    let selectedFrom = this.#selectedFromPiece.get(torrent)?.get(fileIndex);
-    if (selectedFrom === undefined || playheadPiece < selectedFrom) {
-      try {
-        torrent.select(playheadPiece, fileEndPiece, 1);
-      } catch {
-        // Best effort — never break streaming because selection failed.
-      }
-      let perFile = this.#selectedFromPiece.get(torrent);
-      if (!perFile) {
-        perFile = new Map();
-        this.#selectedFromPiece.set(torrent, perFile);
-      }
-      perFile.set(fileIndex, playheadPiece);
-      selectedFrom = playheadPiece;
-    }
-
-    // (2) Demote the gap behind the playhead so the picker scans forward from
-    //     the read position. Only when there IS a gap (not at the file start).
-    if (playheadPiece > fileStartPiece && typeof torrent.deselect === "function") {
-      try {
-        torrent.deselect(fileStartPiece, playheadPiece - 1);
-        this.#selectedFromPiece.get(torrent)?.set(fileIndex, playheadPiece);
-      } catch {
-        // Best effort — never break streaming because demotion failed.
-      }
-    }
-
-    // (3) Reset criticality to a moving read-ahead window (hotswap over the near
-    //     pieces), so it does not accumulate over the whole file across seeks.
-    if (Array.isArray(torrent._critical)) {
-      torrent._critical.length = 0;
-    }
-    if (windowEndPiece >= playheadPiece) {
-      try {
-        torrent.critical(playheadPiece, windowEndPiece);
-      } catch {
-        // Best effort.
-      }
-    }
   }
 
   /**

package/services/torrent-worker/client.js

@@ -198,11 +198,17 @@ export class TorrentWorkerClient {
   /**
    * Reorder piece selection around a read position (seek prioritisation).
    *
-   * @param {{ sourceKey: string, fileIndex: number, byteStart: number, windowBytes?: number }} params
+   * @param {{ sourceKey: string, fileIndex: number, byteStart: number, windowBytes?: number, wholeFileRead?: boolean }} params
    * @returns {Promise<void>}
    */
-  async prioritizeByteRange({ sourceKey, fileIndex, byteStart, windowBytes }) {
-    await this.#caller.call(Command.PRIORITIZE, { sourceKey, fileIndex, byteStart, windowBytes });
+  async prioritizeByteRange({ sourceKey, fileIndex, byteStart, windowBytes, wholeFileRead }) {
+    await this.#caller.call(Command.PRIORITIZE, {
+      sourceKey,
+      fileIndex,
+      byteStart,
+      windowBytes,
+      wholeFileRead
+    });
   }
 
   /**

package/services/torrent-worker/piece-reader.js

@@ -22,6 +22,145 @@
 
 import { findSharedStore } from "../piece-store/shared-piece-store.js";
 
+/**
+ * How far ahead of the read head pieces are asked for.
+ *
+ * A read is open-ended — ffmpeg opens its input as `bytes <position>-<EOF>` and
+ * keeps it for the whole film — so taking the requested range literally asks
+ * for everything from the seek point to the end of the file at once. That is
+ * what a seek used to do: the swarm was told the entire tail was wanted, went
+ * at it from its first missing piece, and the one piece the decoder was blocked
+ * on arrived only when the sequential scan reached it. Measured on a 4.7 GB
+ * film: a seek to 89.1% took 93 s and pulled 2.47 GB.
+ *
+ * So the reader asks for a window and moves it as it goes. The size is a
+ * compromise the caller cannot yet express: the right unit is seconds of
+ * playback (duration and size are both known — to the transcode session, not to
+ * this thread), and 32 MB is about 34 s of a 1080p film but only a few seconds
+ * of a disc remux. Sizing it from the real byte rate is a follow-up; what
+ * matters here is that it is bounded and moving rather than "to the end".
+ */
+const READ_WINDOW_BYTES = 32 * 1024 * 1024;
+
+/**
+ * How many pieces past the one being waited for are marked critical.
+ *
+ * `critical` means "a reader is blocked on this now" — it is what lets a piece
+ * jump the sequential scan. Marking a whole range critical, as this did, says
+ * it about hundreds of pieces at once and the signal stops meaning anything.
+ * WebTorrent's own reader marks `min(1 MB / pieceLength, 2)` pieces, i.e. the
+ * one under the head and at most two more; the same rule is used here.
+ *
+ * @param {number} pieceLength
+ * @returns {number}
+ */
+function criticalRunLength(pieceLength) {
+  return Math.min(Math.floor((1024 * 1024) / Math.max(1, pieceLength)), 2);
+}
+
+/**
+ * The pieces a reader at `pieceIndex` wants next, clamped to its own range.
+ *
+ * @param {{ pieceIndex: number, lastPiece: number, windowPieces: number }} params
+ * @returns {{ from: number, to: number }}
+ */
+export function readWindowFor({ pieceIndex, lastPiece, windowPieces }) {
+  const span = Math.max(1, windowPieces);
+  return { from: pieceIndex, to: Math.min(lastPiece, pieceIndex + span - 1) };
+}
+
+/**
+ * Add this reader's window to the download set as a stream selection.
+ *
+ * `_select`/`_deselect` with the stream flag are what WebTorrent's own
+ * `FileIterator` uses; there is no public call for it, because the public
+ * `select` produces the merging, interval-subtracted kind whose bookkeeping
+ * cannot express "one of several readers wants this". Falls back to the public
+ * call if a future version drops the private one.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {{ from: number, to: number }} window
+ * @returns {void}
+ */
+function claimWindow(torrent, { from, to }) {
+  try {
+    if (typeof torrent._select === "function") {
+      torrent._select(from, to, 1, null, true);
+    } else if (typeof torrent.select === "function") {
+      torrent.select(from, to, 1);
+    }
+  } catch {
+    // Best effort — never fail a read because selection bookkeeping refused.
+  }
+}
+
+/**
+ * Take this reader's window back out of the download set.
+ *
+ * The bounds must match the ones given to {@link claimWindow} exactly: a stream
+ * selection is removed by equality, not by overlap.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {{ from: number, to: number }} window
+ * @returns {void}
+ */
+function releaseWindow(torrent, { from, to }) {
+  try {
+    if (typeof torrent._deselect === "function") {
+      torrent._deselect(from, to, true);
+    } else if (typeof torrent.deselect === "function") {
+      torrent.deselect(from, to);
+    }
+  } catch {
+    // Best effort.
+  }
+}
+
+/**
+ * Mark the piece a reader is blocked on, clearing the mark it set before.
+ *
+ * Criticality is never cleared by WebTorrent itself, so a reader that walked a
+ * film would leave every piece of it marked. Only the indices this reader set
+ * are cleared, so a second reader's mark on the same piece is not stolen — and
+ * the flag is advisory anyway.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {number} from
+ * @param {number} to
+ * @param {{ from: number, to: number } | null} previous
+ * @returns {{ from: number, to: number } | null}
+ */
+function markCritical(torrent, from, to, previous) {
+  if (previous && previous.from === from && previous.to === to) {
+    return previous;
+  }
+  if (previous) {
+    clearCritical(torrent, previous);
+  }
+  try {
+    torrent.critical?.(from, to);
+  } catch {
+    return null;
+  }
+  return { from, to };
+}
+
+/**
+ * Drop critical marks this reader set.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @param {{ from: number, to: number }} mark
+ * @returns {void}
+ */
+function clearCritical(torrent, { from, to }) {
+  if (!Array.isArray(torrent._critical)) {
+    return;
+  }
+  for (let index = from; index <= to; index += 1) {
+    torrent._critical[index] = false;
+  }
+}
+
 /**
  * Wait until a piece has been downloaded and verified.
  *
@@ -100,9 +239,19 @@ function whenPieceReady(torrent, index, cancellation) {
  * @param {number} params.start - Inclusive, relative to the file.
  * @param {number} params.end - Inclusive, relative to the file.
  * @param {{ isCancelled: () => boolean }} params.cancellation
+ * @param {number} [params.windowBytes] - How far ahead of the read head to ask
+ *   the swarm for. Defaults to {@link READ_WINDOW_BYTES}; a caller that knows
+ *   the media's byte rate should size it in seconds of playback instead.
  * @returns {AsyncGenerator<PieceFragment>}
  */
-export async function* readFragments({ torrent, fileIndex, start, end, cancellation }) {
+export async function* readFragments({
+  torrent,
+  fileIndex,
+  start,
+  end,
+  cancellation,
+  windowBytes = READ_WINDOW_BYTES
+}) {
   const store = findSharedStore(torrent);
   if (!store) {
     throw new Error("This torrent is not backed by a shared piece store.");
@@ -121,55 +270,95 @@ export async function* readFragments({ torrent, fileIndex, start, end, cancellat
   const firstPiece = Math.floor(absoluteStart / pieceLength);
   const lastPiece = Math.floor(absoluteEnd / pieceLength);
 
-  // Ask for these pieces first. `select` puts them in the download set at all;
-  // `critical` marks them as wanted now, which is what allows a piece to be
-  // fetched out of sequential order for a reader that is waiting on it.
-  if (typeof torrent.select === "function") {
-    torrent.select(firstPiece, lastPiece, 1);
-  }
-  if (typeof torrent.critical === "function") {
-    torrent.critical(firstPiece, lastPiece);
-  }
+  // This reader owns what it asks for, and gives it back when it is done. The
+  // window is a STREAM selection: those are removed by exact bounds and several
+  // identical ones coexist — WebTorrent's own source calls that "in a way a
+  // count" — so N readers on one torrent produce the union of their windows,
+  // and each one leaving takes away only its own. That is what makes several
+  // parallel readers (the codec probe's head and tail, subtitles, one input per
+  // viewer) cooperate instead of overwrite each other.
+  //
+  // The previous code selected the whole requested range, marked all of it
+  // critical, and never deselected anything — so ffmpeg's opening
+  // `bytes 0-<EOF>` left a permanent selection over the entire file, and no
+  // later prioritisation could outrank it.
+  const windowPieces = Math.max(1, Math.ceil(Math.max(1, windowBytes) / pieceLength));
+  const criticalRun = criticalRunLength(pieceLength);
+  /** @type {{ from: number, to: number } | null} */
+  let window = null;
+  /** @type {{ from: number, to: number } | null} */
+  let criticalMark = null;
 
-  for (let pieceIndex = firstPiece; pieceIndex <= lastPiece; pieceIndex += 1) {
-    if (cancellation.isCancelled()) {
+  const moveWindowTo = (pieceIndex) => {
+    const next = readWindowFor({ pieceIndex, lastPiece, windowPieces });
+    if (window && window.from === next.from && window.to === next.to) {
       return;
     }
-
-    const pieceStart = pieceIndex * pieceLength;
-    const fromWithinPiece = Math.max(absoluteStart, pieceStart) - pieceStart;
-    const toWithinPiece = Math.min(absoluteEnd, pieceStart + pieceLength - 1) - pieceStart;
-
-    await whenPieceReady(torrent, pieceIndex, cancellation);
-
-    // Pinned BEFORE it is located, and before any await that could let an
-    // eviction run: the offset is only meaningful while the piece is held.
-    store.pin(pieceIndex);
-    let located = null;
-    try {
-      located = await store.reside(pieceIndex);
-    } catch (error) {
-      store.unpin(pieceIndex);
-      throw error;
+    if (window) {
+      releaseWindow(torrent, window);
     }
+    claimWindow(torrent, next);
+    window = next;
+  };
 
-    if (!located) {
-      store.unpin(pieceIndex);
-      throw new Error(`Piece ${pieceIndex} is verified but absent from the store.`);
-    }
+  try {
+    for (let pieceIndex = firstPiece; pieceIndex <= lastPiece; pieceIndex += 1) {
+      if (cancellation.isCancelled()) {
+        return;
+      }
 
-    let releasedThisPiece = false;
-    yield {
-      pieceIndex,
-      offset: located.offset + fromWithinPiece,
-      length: toWithinPiece - fromWithinPiece + 1,
-      release() {
-        if (releasedThisPiece) {
-          return;
-        }
-        releasedThisPiece = true;
+      const pieceStart = pieceIndex * pieceLength;
+      const fromWithinPiece = Math.max(absoluteStart, pieceStart) - pieceStart;
+      const toWithinPiece = Math.min(absoluteEnd, pieceStart + pieceLength - 1) - pieceStart;
+
+      moveWindowTo(pieceIndex);
+
+      if (!torrent.bitfield?.get(pieceIndex)) {
+        // Blocked here and now — this is the one case `critical` is meant for.
+        criticalMark = markCritical(torrent, pieceIndex, Math.min(lastPiece, pieceIndex + criticalRun), criticalMark);
+      }
+
+      await whenPieceReady(torrent, pieceIndex, cancellation);
+
+      // Pinned BEFORE it is located, and before any await that could let an
+      // eviction run: the offset is only meaningful while the piece is held.
+      store.pin(pieceIndex);
+      let located = null;
+      try {
+        located = await store.reside(pieceIndex);
+      } catch (error) {
         store.unpin(pieceIndex);
+        throw error;
       }
-    };
+
+      if (!located) {
+        store.unpin(pieceIndex);
+        throw new Error(`Piece ${pieceIndex} is verified but absent from the store.`);
+      }
+
+      let releasedThisPiece = false;
+      yield {
+        pieceIndex,
+        offset: located.offset + fromWithinPiece,
+        length: toWithinPiece - fromWithinPiece + 1,
+        release() {
+          if (releasedThisPiece) {
+            return;
+          }
+          releasedThisPiece = true;
+          store.unpin(pieceIndex);
+        }
+      };
+    }
+  } finally {
+    // Reached on completion, on cancellation, on a throw, and when the consumer
+    // stops iterating — a window left behind would keep the swarm fetching for
+    // a reader that no longer exists.
+    if (window) {
+      releaseWindow(torrent, window);
+    }
+    if (criticalMark) {
+      clearCritical(torrent, criticalMark);
+    }
   }
 }

package/services/torrent-worker/pool-adapter.js

@@ -141,15 +141,22 @@ export class WorkerTorrentPool {
    * @param {number} fileIndex
    * @param {number} byteStart
    * @param {number} [windowBytes]
+   * @param {{ wholeFileRead?: boolean }} [options]
    * @returns {void}
    */
-  prioritizeByteRange(torrent, fileIndex, byteStart, windowBytes) {
+  prioritizeByteRange(torrent, fileIndex, byteStart, windowBytes, options) {
     const sourceKey = torrent?.sourceKey;
     if (!sourceKey) {
       return;
     }
     void this.#client
-      .prioritizeByteRange({ sourceKey, fileIndex, byteStart, windowBytes })
+      .prioritizeByteRange({
+        sourceKey,
+        fileIndex,
+        byteStart,
+        windowBytes,
+        wholeFileRead: options?.wholeFileRead === true
+      })
       .catch(() => undefined);
   }
 

package/services/torrent-worker/worker.js

@@ -307,7 +307,9 @@ async function runCommand(command, params, id) {
 
     case Command.PRIORITIZE: {
       const torrent = await requireTorrent(params.sourceKey);
-      pool.prioritizeByteRange(torrent, params.fileIndex, params.byteStart, params.windowBytes);
+      pool.prioritizeByteRange(torrent, params.fileIndex, params.byteStart, params.windowBytes, {
+        wholeFileRead: params.wholeFileRead === true
+      });
       return true;
     }
 

package/test/piece-selection-offset.test.js

@@ -0,0 +1,85 @@
+/**
+ * @file What WebTorrent's own selection bookkeeping does when a seek demotes
+ * the pieces behind the playhead.
+ *
+ * This is the library's behaviour, not ours, and `prioritizeByteRange` depends
+ * on it: a selection carries an `offset` — how many pieces from its start are
+ * already downloaded — and the picker scans from `from + offset`
+ * (`torrent.js`, `for (piece = next.from + next.offset; piece <= next.to; …)`).
+ * `deselect` subtracts an interval and copies that offset into what survives,
+ * so the remaining selection can end up scanning past its own end and yield
+ * nothing at all.
+ *
+ * Measured consequence before the fix: a seek to 89.1% of a 4.7 GB film left
+ * the seek target wanted by nobody, a later range-less read re-selected the
+ * whole file, and the swarm walked it from the first missing piece — 2.47 GB
+ * over 93 s before the segment could be served.
+ *
+ * If a WebTorrent upgrade changes any of this, these tests fail rather than the
+ * behaviour silently regressing.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Selections } from "webtorrent/lib/selections.js";
+
+// The numbers are the measured session: 588 pieces of 8 MiB, sequential
+// download had reached 38.4% (piece 226), the viewer seeked to 89.1% (piece
+// 523).
+const LAST_PIECE = 587;
+const DOWNLOADED_TO = 226;
+const PLAYHEAD = 523;
+
+/** Where the picker would start scanning this selection. */
+const scanStart = (selection) => selection.from + selection.offset;
+
+test("deselecting the gap behind the playhead leaves a selection that yields nothing", () => {
+  const selections = new Selections();
+  selections.insert({ from: 0, to: LAST_PIECE, offset: 0, priority: 1 });
+  // What `_gcSelections` does as pieces arrive.
+  selections.get(0).offset = DOWNLOADED_TO;
+
+  selections.remove({ from: 0, to: PLAYHEAD - 1, isStreamSelection: false });
+
+  assert.equal(selections.length, 1);
+  const survivor = selections.get(0);
+  assert.equal(survivor.from, PLAYHEAD, "the surviving selection starts at the playhead");
+  assert.equal(survivor.offset, DOWNLOADED_TO, "and it kept the offset of the range it came from");
+  assert.ok(
+    scanStart(survivor) > survivor.to,
+    `scan would start at piece ${scanStart(survivor)} of ${survivor.to} — nothing is downloadable`
+  );
+});
+
+test("re-selecting the same range restores a scan that starts at the playhead", () => {
+  const selections = new Selections();
+  selections.insert({ from: 0, to: LAST_PIECE, offset: 0, priority: 1 });
+  selections.get(0).offset = DOWNLOADED_TO;
+
+  // Exactly what prioritizeByteRange does on a forward seek.
+  selections.remove({ from: 0, to: PLAYHEAD - 1, isStreamSelection: false });
+  selections.insert({ from: PLAYHEAD, to: LAST_PIECE, offset: 0, priority: 1 });
+
+  assert.equal(selections.length, 1, "the dead selection was replaced, not added to");
+  const selection = selections.get(0);
+  assert.equal(scanStart(selection), PLAYHEAD, "the picker now starts at the seek target");
+  assert.equal(selection.to, LAST_PIECE);
+});
+
+test("selecting the whole file again undoes the demotion", () => {
+  const selections = new Selections();
+  selections.insert({ from: 0, to: LAST_PIECE, offset: 0, priority: 1 });
+  selections.get(0).offset = DOWNLOADED_TO;
+  selections.remove({ from: 0, to: PLAYHEAD - 1, isStreamSelection: false });
+  selections.insert({ from: PLAYHEAD, to: LAST_PIECE, offset: 0, priority: 1 });
+
+  // A range-less read reporting position 0 used to land here.
+  selections.insert({ from: 0, to: LAST_PIECE, offset: 0, priority: 1 });
+
+  assert.equal(selections.length, 1);
+  assert.equal(
+    scanStart(selections.get(0)),
+    0,
+    "the whole file is selected again, so the picker falls back to the first missing piece"
+  );
+});

package/test/read-window.test.js

@@ -0,0 +1,242 @@
+/**
+ * @file What a read asks the torrent to download, and what it gives back.
+ *
+ * A read used to select its whole requested range and never deselect it.
+ * ffmpeg opens its input as `bytes <position>-<EOF>`, so the first read of a
+ * session claimed the entire file and marked every piece of it critical — and
+ * the claim outlived the read, which is abandoned a second later when ffmpeg
+ * seeks. Nothing after that could outrank it: measured on a 4.7 GB film, a seek
+ * to 89.1% waited 93 s while the swarm fetched 2.47 GB in file order.
+ *
+ * Now a read holds a moving window and returns it when it ends. These tests pin
+ * the three properties that matter: the claim is bounded, it is given back, and
+ * several readers add up instead of overwriting each other.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { readFragments, readWindowFor } from "../services/torrent-worker/piece-reader.js";
+import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
+
+const PIECE = 1024;
+// The production window is 32 MB against 8 MiB pieces — four of them. Sized
+// here in pieces so the test does not depend on either constant.
+const WINDOW_PIECES = 4;
+
+/**
+ * A torrent that records every selection call instead of downloading anything.
+ *
+ * @param {{ pieceCount: number, present?: (index: number) => boolean }} shape
+ */
+async function recordingTorrent({ pieceCount, present = () => true }) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "read-window-test-"));
+  const totalLength = pieceCount * PIECE;
+  const store = new SharedPieceStore(PIECE, {
+    length: totalLength,
+    memoryBytes: 64 * PIECE,
+    path: directory,
+    name: "test"
+  });
+  for (let index = 0; index < pieceCount; index += 1) {
+    await new Promise((resolve, reject) => {
+      store.put(index, Buffer.alloc(PIECE, index % 251), (error) => (error ? reject(error) : resolve()));
+    });
+  }
+
+  /** @type {Array<{ call: string, from: number, to: number, stream?: boolean }>} */
+  const calls = [];
+  /** Live stream selections, as WebTorrent counts them: exact bounds, duplicates allowed. */
+  const held = [];
+
+  const torrent = Object.assign(new EventEmitter(), {
+    pieceLength: PIECE,
+    store,
+    bitfield: { get: (index) => present(index) },
+    files: [{ offset: 0, length: totalLength, name: "file.bin" }],
+    _critical: [],
+    calls,
+    held,
+    _select(from, to, _priority, _notify, isStreamSelection) {
+      calls.push({ call: "select", from, to, stream: isStreamSelection === true });
+      held.push(`${from}-${to}`);
+    },
+    _deselect(from, to, isStreamSelection) {
+      calls.push({ call: "deselect", from, to, stream: isStreamSelection === true });
+      const at = held.indexOf(`${from}-${to}`);
+      if (at >= 0) {
+        held.splice(at, 1);
+      }
+    },
+    critical(from, to) {
+      calls.push({ call: "critical", from, to });
+      for (let index = from; index <= to; index += 1) {
+        this._critical[index] = true;
+      }
+    }
+  });
+
+  return { torrent, store, directory };
+}
+
+/** Read a range to the end, releasing every fragment. */
+async function drain(torrent, start, end) {
+  for await (const fragment of readFragments({
+    torrent,
+    fileIndex: 0,
+    start,
+    end,
+    cancellation: { isCancelled: () => false }
+  })) {
+    fragment.release();
+  }
+}
+
+test("the window is bounded and clamped to the end of the read", () => {
+  assert.deepEqual(readWindowFor({ pieceIndex: 10, lastPiece: 999, windowPieces: 4 }), { from: 10, to: 13 });
+  assert.deepEqual(
+    readWindowFor({ pieceIndex: 997, lastPiece: 999, windowPieces: 4 }),
+    { from: 997, to: 999 },
+    "the window never reaches past the range the reader was given"
+  );
+  assert.deepEqual(
+    readWindowFor({ pieceIndex: 5, lastPiece: 999, windowPieces: 0 }),
+    { from: 5, to: 5 },
+    "a degenerate size still asks for the piece under the head"
+  );
+});
+
+test("an open-ended read does not claim the whole file at once", async () => {
+  // 8000 pieces of 1 KB — far more than the 32 MB window, so a read to the end
+  // of the file is exactly the ffmpeg case.
+  const { torrent, store, directory } = await recordingTorrent({ pieceCount: 8000 });
+  try {
+    // Read only the first two pieces, but ask as ffmpeg does: to the last byte.
+    const iterator = readFragments({
+      torrent,
+      fileIndex: 0,
+      start: 0,
+      end: 8000 * PIECE - 1,
+      cancellation: { isCancelled: () => false },
+      windowBytes: WINDOW_PIECES * PIECE
+    });
+    const first = await iterator.next();
+    first.value.release();
+
+    const selects = torrent.calls.filter((entry) => entry.call === "select");
+    assert.ok(selects.length >= 1, "the reader claimed nothing");
+    const claimed = selects[0].to - selects[0].from + 1;
+    assert.equal(
+      claimed,
+      WINDOW_PIECES,
+      `the reader claimed ${claimed} pieces of the file instead of its window`
+    );
+    assert.equal(selects[0].stream, true, "the claim must be a stream selection, so it can be counted");
+
+    await iterator.return();
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a finished read leaves nothing selected", async () => {
+  const { torrent, store, directory } = await recordingTorrent({ pieceCount: 40 });
+  try {
+    await drain(torrent, 0, 40 * PIECE - 1);
+    assert.deepEqual(torrent.held, [], "the read kept its claim after finishing");
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("an abandoned read leaves nothing selected", async () => {
+  const { torrent, store, directory } = await recordingTorrent({ pieceCount: 8000 });
+  try {
+    const iterator = readFragments({
+      torrent,
+      fileIndex: 0,
+      start: 0,
+      end: 8000 * PIECE - 1,
+      cancellation: { isCancelled: () => false },
+      windowBytes: WINDOW_PIECES * PIECE
+    });
+    const first = await iterator.next();
+    first.value.release();
+    // What ffmpeg does to its opening read the moment it seeks.
+    await iterator.return();
+
+    assert.deepEqual(torrent.held, [], "an abandoned read kept its claim forever");
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("two readers add up, and one leaving takes only its own window", async () => {
+  const { torrent, store, directory } = await recordingTorrent({ pieceCount: 8000 });
+  try {
+    const head = readFragments({
+      torrent, fileIndex: 0, start: 0, end: 8000 * PIECE - 1,
+      cancellation: { isCancelled: () => false }
+    });
+    const tail = readFragments({
+      torrent, fileIndex: 0, start: 4000 * PIECE, end: 8000 * PIECE - 1,
+      cancellation: { isCancelled: () => false }
+    });
+    (await head.next()).value.release();
+    (await tail.next()).value.release();
+
+    assert.equal(torrent.held.length, 2, "the two readers did not both hold a window");
+    const [headWindow, tailWindow] = torrent.held;
+
+    await tail.return();
+    assert.deepEqual(
+      torrent.held,
+      [headWindow],
+      `leaving reader took the wrong window (expected to remove ${tailWindow})`
+    );
+
+    await head.return();
+    assert.deepEqual(torrent.held, []);
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("criticality marks the piece being waited for, not the whole range", async () => {
+  // Nothing is present, so the reader blocks on its first piece and marks it.
+  let arrived = false;
+  const { torrent, store, directory } = await recordingTorrent({
+    pieceCount: 8000,
+    present: () => arrived
+  });
+  try {
+    const iterator = readFragments({
+      torrent, fileIndex: 0, start: 0, end: 8000 * PIECE - 1,
+      cancellation: { isCancelled: () => false }
+    });
+    const pending = iterator.next();
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const criticals = torrent.calls.filter((entry) => entry.call === "critical");
+    assert.equal(criticals.length, 1);
+    assert.ok(
+      criticals[0].to - criticals[0].from + 1 <= 3,
+      `marked ${criticals[0].to - criticals[0].from + 1} pieces critical; the signal means "blocked here now"`
+    );
+
+    arrived = true;
+    torrent.emit("verified", 0);
+    (await pending).value.release();
+    await iterator.return();
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/test/segment-hold-supersede.test.js

@@ -0,0 +1,93 @@
+/**
+ * @file A held segment request must not outlive the position it was made for.
+ *
+ * hls.js keeps ONE fragment load outstanding. So a request being held for a
+ * segment blocks the request for wherever the viewer has just moved to, and our
+ * route held each one for 60 s. Measured 2026-08-04: a backward seek into fully
+ * downloaded data waited 57 s for a held request for `#609` to run out its
+ * timer, and the segment the viewer actually wanted was then served in 15 ms.
+ *
+ * `research/hls-seek-prior-art-2026-08-02.md` prescribed this guard from
+ * `hls-media-server` — one outstanding wait per session — and it was never
+ * built.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { handleTranscodeSessionFileGet } from "../routes/transcode/session-file/get.js";
+
+/**
+ * A reply that records what the route answered.
+ *
+ * @returns {{ reply: object, sent: { code: number, headers: Record<string, string>, body: unknown } }}
+ */
+function recordingReply() {
+  const sent = { code: 200, headers: {}, body: undefined };
+  const reply = {
+    code(value) {
+      sent.code = value;
+      return reply;
+    },
+    header(name, value) {
+      sent.headers[name.toLowerCase()] = String(value);
+      return reply;
+    },
+    send(body) {
+      sent.body = body;
+      return reply;
+    }
+  };
+  return { reply, sent };
+}
+
+const request = (fileName) => ({
+  params: { sessionId: "11111111-2222-3333-4444-555555555555", fileName },
+  raw: { on() {}, off() {} }
+});
+
+test("a seek releases a held segment request instead of running out the hold", async () => {
+  let epoch = 0;
+  let polls = 0;
+  const hlsSessionManager = {
+    nextRequestSeq: () => 1,
+    seekEpoch: () => epoch,
+    async getFileStream() {
+      polls += 1;
+      // The viewer moves while this request is being held.
+      if (polls === 2) {
+        epoch += 1;
+      }
+      return { kind: "warming-up" };
+    }
+  };
+
+  const { reply, sent } = recordingReply();
+  const startedAt = Date.now();
+  await handleTranscodeSessionFileGet(request("segment-00609.mp4"), reply, { hlsSessionManager });
+  const heldMs = Date.now() - startedAt;
+
+  assert.equal(sent.code, 503, "the player must get a retryable answer, not a stream");
+  assert.equal(sent.headers["retry-after"], "0", "nothing to wait for — this segment is not being watched");
+  assert.ok(heldMs < 5_000, `the request was held ${heldMs}ms after the seek`);
+});
+
+test("without a seek the request is still held until the segment appears", async () => {
+  let polls = 0;
+  const hlsSessionManager = {
+    nextRequestSeq: () => 1,
+    seekEpoch: () => 7,
+    async getFileStream() {
+      polls += 1;
+      if (polls < 3) {
+        return { kind: "warming-up" };
+      }
+      return { kind: "ok", contentType: "video/mp4", stream: "bytes", isPlaylist: false };
+    }
+  };
+
+  const { reply, sent } = recordingReply();
+  await handleTranscodeSessionFileGet(request("segment-00610.mp4"), reply, { hlsSessionManager });
+
+  assert.equal(sent.body, "bytes", "a segment that arrives late must still be served");
+  assert.equal(sent.headers["content-type"], "video/mp4");
+});

package/test/stream-route.test.js

@@ -20,7 +20,7 @@ import { handleStreamGet } from "../routes/stream/get.js";
  */
 function harness({ method, range }) {
   const opened = [];
-  const state = { claims: 0 };
+  const state = { claims: 0, prioritized: [] };
 
   const sent = { code: 200, headers: {}, body: undefined, called: false };
   const reply = {
@@ -72,7 +72,9 @@ function harness({ method, range }) {
       state.claims += 1;
       return () => undefined;
     },
-    prioritizeByteRange() {}
+    prioritizeByteRange(_torrent, fileIndex, byteStart, _windowBytes, options) {
+      state.prioritized.push({ byteStart, wholeFileRead: options?.wholeFileRead === true });
+    }
   };
 
   const req = {
@@ -119,3 +121,25 @@ test("GET with a range streams only that range", async () => {
   assert.equal(sent.headers["content-range"], "bytes 100-199/5869669065");
   assert.equal(sent.headers["content-length"], "100");
 });
+
+// A request with no byte range says nothing about where the viewer is: ffmpeg
+// opens its input with a plain GET and abandons it the moment it seeks, and the
+// keyframe index and the codec probe do the same — four such reads around every
+// encoder restart. Reported as ordinary reads at offset 0, they undid the seek
+// that had just happened and sent the swarm walking the file from its first
+// missing piece; a seek to 89.1% of a 4.7 GB film downloaded 2.47 GB that way.
+test("a range-less GET is reported as a whole-file read", async () => {
+  const { req, reply, state, deps } = harness({ method: "GET" });
+
+  await handleStreamGet(req, reply, deps);
+
+  assert.deepEqual(state.prioritized, [{ byteStart: 0, wholeFileRead: true }]);
+});
+
+test("a ranged GET is reported as a real read position", async () => {
+  const { req, reply, state, deps } = harness({ method: "GET", range: "bytes=4390000000-" });
+
+  await handleStreamGet(req, reply, deps);
+
+  assert.deepEqual(state.prioritized, [{ byteStart: 4_390_000_000, wholeFileRead: false }]);
+});