@torrent-tv/proxy 2.83.2 → 2.83.4

package/services/torrent-pool.js

@@ -24,6 +24,9 @@ import { deriveSourceKey } from "./torrent-source-key.js";
 /** How a window stated from the priority map names itself. */
 const MAP_CLAIMANT = "priority-map";
 
+/** How the two ends of a file name themselves. */
+const EDGES_CLAIMANT = "file-edges";
+
 // 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
@@ -331,29 +334,25 @@ function describeSwarmDemand(torrent) {
 /**
  * The torrents the upload policy is allowed to see.
  *
- * A torrent with a reader qualifies for the obvious reason. A torrent in a
- * HURRY qualifies even without one, and that case is the important one: the
- * first thing done with a new torrent is fetching the file's head and tail for
- * the codec probe, and that read goes straight to `createReadStream` without
- * registering a reader. Judged by readers alone the torrent looks unused for
- * the whole of that wait — 8.36 s of the 11.46 s before playback in the session
- * measured 2026-08-04 — so the upload stayed at the near-silent idle floor
- * during the exact seconds peers were deciding whether to serve us.
+ * A torrent something is wanted of qualifies for the obvious reason. A torrent
+ * in a HURRY qualifies even without that, and that case is the important one:
+ * the first seconds of a new torrent are when peers decide whether to serve us,
+ * and an upload held at the near-silent idle floor through them costs the whole
+ * ramp — 8.36 s of the 11.46 s before playback in the session measured
+ * 2026-08-04.
  *
  * @param {Iterable<{ hurryUntil?: number }>} torrents
- * @param {Map<object, { size: number }>} usageByTorrent - fileIndex sets, keyed by torrent.
  * @param {number} now
  * @returns {object[]}
  */
-export function torrentsForUploadPolicy(torrents, usageByTorrent, now) {
+export function torrentsForUploadPolicy(torrents, now) {
   const chosen = [];
   for (const torrent of torrents) {
-    const usage = usageByTorrent?.get?.(torrent);
-    const hasReader = Boolean(usage && usage.size > 0);
-    if (hasReader || (torrent?.hurryUntil ?? 0) > now) {
+    const wanted = isWanted(torrent);
+    if (wanted || (torrent?.hurryUntil ?? 0) > now) {
       // Recorded so the policy can tell "nothing is arriving and somebody is
       // waiting" from "nothing is arriving because nobody asked".
-      torrent.hasActiveReader = hasReader;
+      torrent.isWanted = wanted;
       // Whether anybody is still short of bytes of it. Upload is bought with
       // reciprocity and reciprocity is only worth buying while something is
       // missing; a torrent whose declared windows are all present wants nothing
@@ -398,13 +397,13 @@ export function decideUploadLimit(activeTorrents, opts = {}) {
     // iterate the piece array and throw on webtorrent 3.x when a piece is null
     // (deselected / mid-verify), which would crash this timer every cycle.
     const notDone = torrent?.done !== true;
-    // A torrent nobody is reading is not starving, however still its download
-    // looks. The encoder is held back once it is far enough ahead of the
+    // A torrent nothing is wanted of is not starving, however still its
+    // download looks. The encoder is held back once it is far enough ahead of the
     // viewer, and while it is held nothing is requested — measured
     // 2026-08-04: four cycles of 512 -> 50 KB/s in three minutes, each
     // reported as `earn unchoke ... down=0KB/s`, all of them raising the
     // upload at moments when no byte was wanted by anyone.
-    const starving = notDone && torrent?.hasActiveReader !== false
+    const starving = notDone && torrent?.isWanted !== false
       && torrent?.hasUnmetDemand !== false && downloadSpeed < starvingSpeed;
     if (starving && chokedInterested >= chokedThreshold) {
       const name = typeof torrent?.name === "string" ? torrent.name : "?";
@@ -428,6 +427,83 @@ export function decideUploadLimit(activeTorrents, opts = {}) {
   return { bytesPerSec: floor, reason: "active readers, not choke-starved" };
 }
 
+/**
+ * Let go of the swarm of a torrent whose last reader has just left.
+ *
+ * A PROXY THAT NEEDS NOTHING FROM A SWARM SHOULD NOT BE IN THAT SWARM. While a
+ * file is being read every connection is worth keeping — the one that has
+ * delivered nothing yet may deliver next — so this is not a limit on
+ * connections and never fires during playback.
+ *
+ * What that state cost until now: WebTorrent enforces `maxConns` only on peers
+ * it dials (`_drain`), while `_addIncomingPeer` checks that the torrent is
+ * neither destroyed nor paused and registers the peer. A proxy with its port
+ * mapped is reachable, so connections arrive and are never turned away — field
+ * 2026-09-11, 249 connected at the start of one viewing and 596 at the end,
+ * 15 862 more queued, on a file complete for three quarters of an hour.
+ *
+ * CALLED FROM THE DEPARTURE ITSELF, not from a pass over every torrent. The
+ * first version asked every five seconds whether anybody was reading, and a
+ * torrent added three seconds earlier — its edges still being read, its
+ * playback plan still being built — answered no. It was taken out of its swarm
+ * with 741 connections let go, and nothing rejoined it: rejoining waits for a
+ * reader, and the reader was waiting for the header the swarm had been
+ * fetching. Playback did not start at all (2.83.1).
+ *
+ * Asked at the moment the last claim is released, leaving cannot happen
+ * spontaneously: it is a consequence of a departure, and a torrent nobody has
+ * read yet has nothing to depart from.
+ *
+ * `paused` is the library's own word for this and the path it already checks,
+ * so nothing here fights it. The pause alone does not close what is already
+ * open, so the peers are let go by hand; the data stays exactly where it is.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {number} Connections let go.
+ */
+export function leaveSwarm(torrent) {
+  if (!torrent || torrent.destroyed || torrent.paused === true) {
+    return 0;
+  }
+  torrent.pause();
+  const open = Array.isArray(torrent.wires) ? torrent.wires.length : 0;
+  let closed = 0;
+  for (const peer of [...(torrent._peers?.values?.() ?? [])]) {
+    try {
+      peer.destroy();
+      closed += 1;
+    } catch {
+      // A peer already going: nothing to do, and nothing worth failing for.
+    }
+  }
+  logger.info(
+    `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] left the swarm — its last reader went, ` +
+    `${open} connection(s) open, ${closed} let go; the data stays and the next reader rejoins`
+  );
+  return closed;
+}
+
+/**
+ * Take the swarm back for a torrent a reader has just arrived at.
+ *
+ * The other half of the pair: a departure lets a swarm go, an arrival takes it
+ * back. Both are acted on at the moment they happen, and neither is discovered
+ * by asking.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {boolean} Whether it had to be taken back.
+ */
+export function rejoinSwarm(torrent) {
+  if (!torrent || torrent.destroyed || torrent.paused !== true) {
+    return false;
+  }
+  torrent.resume();
+  logger.info(
+    `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] rejoined the swarm — a reader arrived`
+  );
+  return true;
+}
+
 /**
  * Compute the default disk cap: the smaller of a fixed 10 GB and half of the
  * currently free space on the store's filesystem (so a tiny host is never
@@ -712,6 +788,176 @@ export function dhtNodeCount(client) {
 // without building a pool, a torrent client or a thread.
 const lastMapSaid = new WeakMap();
 
+/**
+ * Take back what the priority map had stated for one file, from a band onwards.
+ *
+ * Every band of a map is a claimant of its own, numbered, so a map that has
+ * shrunk — or emptied — is applied by withdrawing the numbers it no longer
+ * reaches. Written once because both callers need exactly it: the ordinary
+ * application, where the count is how many bands there now are, and a file
+ * nobody wants any more, where it is none.
+ *
+ * A function of a torrent rather than of the pool, like `leaveSwarm` beside it:
+ * it needs nothing the pool holds, and it can be exercised without building one.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {number} [keepBelow] - Bands numbered below this are left alone.
+ * @returns {number} How many were withdrawn.
+ */
+function withdrawPriorityMap(torrent, fileIndex, keepBelow = 0) {
+  const { register } = demandFor(torrent);
+  const prefix = `${MAP_CLAIMANT}:${fileIndex}:`;
+  let withdrawn = 0;
+  for (const window of register.windows()) {
+    const claimant = String(window.claimant);
+    if (!claimant.startsWith(prefix)) {
+      continue;
+    }
+    const index = Number(claimant.split(":").pop());
+    if (!(index < keepBelow)) {
+      register.withdraw(claimant);
+      withdrawn += 1;
+    }
+  }
+  if (withdrawn > 0 && keepBelow === 0) {
+    // Said, because it is the one statement that cannot be read from what
+    // follows it: nothing further is stated about this file, so from here on
+    // silence is exactly what it looks like.
+    logger.info(
+      `torrent-pool: [${String(torrent?.infoHash ?? "?").slice(0, 8)}] nobody wants file ${fileIndex} ` +
+      `any more — ${withdrawn} band(s) of the map withdrawn`
+    );
+  }
+  return withdrawn;
+}
+
+/**
+ * WHERE A FILE SAYS WHAT IT IS: the piece at each of its ends.
+ *
+ * A container keeps its directory at one end or the other — `ftyp` and an EBML
+ * header at the front, and for an MP4 that was not written for streaming the
+ * `moov` at the very back. Nothing can be read of such a file until those have
+ * arrived, and they stay wanted for as long as it is open: a player asks for
+ * the file's shape again at every seek.
+ *
+ * **The size is not chosen, and it cannot be.** One byte is claimed at each
+ * end, and the piece is what the swarm delivers — so one byte at each end IS
+ * one piece at each end, with nothing rounded up by a number anybody picked.
+ * The 256 KB and 2 MB the prefetch reads are its own affair; where a directory
+ * is bigger than the piece it starts in, the read that needs it says so itself,
+ * at the level of a reader that is stopped.
+ *
+ * **Stated by the FILE, not by the read that happens to want it.** A read
+ * withdraws what it stated the moment it finishes, so until now the two ends of
+ * an open film were held by nothing at all once the codec probe was done — and
+ * they are exactly the pieces a seek needs and eviction is free to take.
+ *
+ * A function of a torrent rather than of the pool, like `leaveSwarm` beside it,
+ * so both can be exercised without building one.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {number} urgency - NEAR while somebody is waiting for them, TAIL to
+ *   keep them afterwards.
+ * @returns {boolean} Whether anything was stated.
+ */
+export function stateFileEdges(torrent, fileIndex, urgency, { lower = false } = {}) {
+  const file = Array.isArray(torrent?.files) ? torrent.files[fileIndex] : null;
+  const length = Number(file?.length);
+  if (!file || !(length > 0)) {
+    return false;
+  }
+  const { register } = demandFor(torrent);
+  const ends = [
+    { claimant: `${EDGES_CLAIMANT}:${fileIndex}:head`, byteStart: 0, byteEnd: 0 },
+    { claimant: `${EDGES_CLAIMANT}:${fileIndex}:tail`, byteStart: length - 1, byteEnd: length - 1 }
+  ];
+  for (const end of ends) {
+    // RAISED, NEVER LOWERED, unless the caller is the one putting them back
+    // down. Two things ask for the same ends — a warm-up that nobody is waiting
+    // for and a playback plan that somebody is — and the warm-up's sidecars are
+    // fired off without being awaited, so it can arrive second. Taking the
+    // plan's urgency away there would leave a person watching a loading screen
+    // behind a film somebody else is watching.
+    const stated = register.windows().find((window) => String(window.claimant) === end.claimant);
+    const level = !lower && stated ? Math.min(stated.urgency, urgency) : urgency;
+    register.state({ ...end, fileIndex, urgency: level });
+  }
+  return true;
+}
+
+/**
+ * Give up the ends of a file nobody has any use for.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @returns {number} How many were withdrawn.
+ */
+export function withdrawFileEdges(torrent, fileIndex) {
+  const { register } = demandFor(torrent);
+  let withdrawn = 0;
+  for (const end of ["head", "tail"]) {
+    const claimant = `${EDGES_CLAIMANT}:${fileIndex}:${end}`;
+    if (register.windows().some((window) => String(window.claimant) === claimant)) {
+      register.withdraw(claimant);
+      withdrawn += 1;
+    }
+  }
+  return withdrawn;
+}
+
+/**
+ * IS ANYTHING WANTED OF THIS TORRENT — the one question asked about a torrent's
+ * life, and it is answered by what has been stated, never by counting who is
+ * reading.
+ *
+ * Everything that wants bytes says so in the register: the priority map for
+ * every file somebody is watching, the ends of a file that is open, the
+ * background fill, and a read that is stopped on a piece. So "nothing is
+ * stated" is the whole of "nobody wants this", and it becomes true exactly when
+ * the last viewer leaves — because that is when the map is published with
+ * nothing in it.
+ *
+ * **A torrent that cannot yet be stated about is wanted.** Until its metadata
+ * arrives it has no files, so nothing can name a byte of it, and it is being
+ * fetched precisely because somebody asked for it. Judged by the register alone
+ * it would look abandoned three seconds after it was added, which is the
+ * failure of 2.83.1 exactly.
+ *
+ * @param {object} torrent
+ * @returns {boolean}
+ */
+export function isWanted(torrent) {
+  if (!torrent || torrent.destroyed) {
+    return false;
+  }
+  if (!Array.isArray(torrent.files) || torrent.files.length === 0) {
+    return true;
+  }
+  return demandFor(torrent).register.size > 0;
+}
+
+/**
+ * WHAT TO DO ABOUT A TORRENT'S SWARM, from the two facts that decide it.
+ *
+ * Separated from the doing because this is the rule that has failed twice in
+ * the field, and a rule that can only be exercised by building a pool with a
+ * live WebTorrent client is a rule nothing checks. Both failures are cases of
+ * it: 2.83.1 let a swarm go for a torrent that had never been wanted, and the
+ * version before that never let one go at all.
+ *
+ * @param {{ wanted: boolean, everWanted: boolean }} facts
+ * @returns {{ swarm: "take" | "let go" | "leave alone", onTheClock: boolean }}
+ *   What to do with the swarm, and whether the idle clock should be running.
+ */
+export function swarmDecisionFor({ wanted, everWanted }) {
+  if (wanted) {
+    return { swarm: "take", onTheClock: false };
+  }
+  return { swarm: everWanted ? "let go" : "leave alone", onTheClock: true };
+}
+
 export class TorrentPool {
   /**
    * In-flight `client.add()` promises keyed by the same key as `torrents`.
@@ -907,7 +1153,6 @@ export class TorrentPool {
      *
      * @type {WeakMap<import("webtorrent").Torrent, Map<number, number>>}
      */
-    this.fileUsageByTorrent = new WeakMap();
 
     this.client.on("error", (error) => {
       logger.error(`WebTorrent client error: ${error.message}`);
@@ -938,88 +1183,6 @@ export class TorrentPool {
     this.#uploadAdjustTimer.unref?.();
   }
 
-  /**
-   * Leave the swarm of a torrent nobody is reading, and rejoin it when
-   * somebody is.
-   *
-   * A PROXY THAT NEEDS NOTHING FROM A SWARM SHOULD NOT BE IN THAT SWARM. While
-   * a file is being watched every connection is worth keeping — the one that
-   * has delivered nothing yet may deliver next — so this is not a limit on
-   * connections and never fires during playback. It fires when NOTHING is
-   * stated about this torrent at all: no window from any reader, no file held.
-   *
-   * What that state cost until now: WebTorrent enforces `maxConns` only on
-   * peers it dials (`_drain`), while `_addIncomingPeer` checks that the torrent
-   * is neither destroyed nor paused and registers the peer. A proxy with its
-   * port mapped is reachable, so connections arrive and are never turned away —
-   * field 2026-09-11, 249 connected at the start of one viewing and 596 at the
-   * end, 15 862 more queued, on a file complete for three quarters of an hour,
-   * each of them served by reading a 4 MB piece off the disk for every 16 KB
-   * sent.
-   *
-   * `paused` is the library's own word for this and the path it already checks,
-   * so nothing here fights it. The pause alone does not close what is already
-   * open, so the peers are let go by hand; the data stays exactly where it is,
-   * and the next reader resumes the torrent rather than fetching it again.
-   *
-   * @param {import("webtorrent").Torrent} torrent
-   * @returns {void}
-   */
-  followTheReaders(torrent) {
-    if (!torrent || torrent.destroyed) {
-      return;
-    }
-    const usage = this.fileUsageByTorrent.get(torrent);
-    const isRead = Boolean(usage && usage.size > 0);
-    if (isRead) {
-      // Recorded on the torrent, as `hasActiveReader` and `hasUnmetDemand`
-      // beside it are: it is a fact about this torrent and it lives as long as
-      // the torrent does.
-      torrent.hasBeenRead = true;
-    }
-    const isWanted = isRead || demandFor(torrent).register.windows().length > 0;
-    // A TORRENT NOBODY HAS READ YET IS BEING SET UP, NOT ABANDONED. Field
-    // 2026-09-11, and it broke playback outright: a torrent was added at
-    // 20:57:17, its first peer connected at 20:57:18, and this pass took it out
-    // of the swarm at 20:57:21 — while the read of the file's edges was still
-    // in flight and the playback plan was being built. Nothing rejoined it,
-    // because rejoining waits for a reader and a reader cannot arrive: the
-    // header it needs is downloaded by the swarm that was just let go.
-    //
-    // The condition is a state and not a period: having been read at least once
-    // is what tells a film somebody left from a film nobody has opened yet. One
-    // that is never read at all goes by the pool's own idle removal, which is
-    // where that belongs.
-    if (!isWanted && torrent.hasBeenRead !== true) {
-      return;
-    }
-    if (isWanted && torrent.paused === true) {
-      torrent.resume();
-      logger.info(
-        `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] rejoined the swarm — somebody is reading it again`
-      );
-      return;
-    }
-    if (isWanted || torrent.paused === true) {
-      return;
-    }
-    torrent.pause();
-    const open = Array.isArray(torrent.wires) ? torrent.wires.length : 0;
-    let closed = 0;
-    for (const peer of [...(torrent._peers?.values?.() ?? [])]) {
-      try {
-        peer.destroy();
-        closed += 1;
-      } catch {
-        // A peer already going: nothing to do, and nothing worth failing for.
-      }
-    }
-    logger.info(
-      `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] left the swarm — nobody is reading it, ` +
-      `${open} connection(s) open, ${closed} let go; the data stays and the next reader rejoins`
-    );
-  }
-
   /**
    * Re-evaluate and apply the client-wide upload limit from current swarm state
    * (see {@link decideUploadLimit}). Runs on a timer; only calls into WebTorrent
@@ -1120,13 +1283,14 @@ export class TorrentPool {
    */
   #stateBackgroundFill(torrent) {
     const { register } = demandFor(torrent);
-    const usage = this.fileUsageByTorrent.get(torrent);
     const pieceLength = Number(torrent.pieceLength);
     if (!Number.isFinite(pieceLength) || pieceLength <= 0) {
       return;
     }
-    for (const [fileIndex, count] of usage ?? []) {
-      const file = count > 0 ? torrent.files?.[fileIndex] : null;
+    // The files anything is stated for — which is the same list the reader
+    // counts used to give and is one fact rather than two.
+    for (const fileIndex of register.files()) {
+      const file = torrent.files?.[fileIndex] ?? null;
       const claimant = `background-fill:${fileIndex}`;
       if (!file) {
         register.withdraw(claimant);
@@ -1174,6 +1338,22 @@ export class TorrentPool {
    * @param {number} durationSeconds
    */
   applyPriorityMap(torrent, fileIndex, zones, durationSeconds) {
+    // A MAP WITH NOTHING IN IT IS A STATEMENT, and it is answered before
+    // anything else is looked at. It says nobody wants any of this file, and
+    // that is true whatever the file's length is or whether the torrent still
+    // holds a list — so making it wait on either would be making the departure
+    // depend on facts that are gone by the time it is said.
+    if (Array.isArray(zones) && zones.length === 0) {
+      withdrawPriorityMap(torrent, fileIndex);
+      // The ends of the file go with it. They are kept for as long as the file
+      // is open, and this is what says it is not.
+      withdrawFileEdges(torrent, fileIndex);
+      // And this may have been the last thing anybody wanted of this torrent.
+      // Optional because these two are functions of a torrent and are exercised
+      // as such; called on the pool, the pool also acts on what they said.
+      this?.followTheDemand?.(torrent);
+      return;
+    }
     const file = Array.isArray(torrent?.files) ? torrent.files[fileIndex] : null;
     const length = Number(file?.length);
     const duration = Number(durationSeconds);
@@ -1248,15 +1428,7 @@ export class TorrentPool {
     });
     // Bands the map no longer has: a viewer moved on, and what they had wanted
     // is not wanted by anybody now.
-    for (const window of register.windows()) {
-      if (!String(window.claimant).startsWith(`${MAP_CLAIMANT}:${fileIndex}:`)) {
-        continue;
-      }
-      const index = Number(String(window.claimant).split(":").pop());
-      if (!(index < ordered.length)) {
-        register.withdraw(window.claimant);
-      }
-    }
+    withdrawPriorityMap(torrent, fileIndex, ordered.length);
     // WHAT THE SWARM WAS ACTUALLY TOLD, said on change and never on a timer.
     // The map was applied in silence: that it had been BUILT was visible in the
     // encoding's own line, and that the download had received it was visible
@@ -1280,6 +1452,9 @@ export class TorrentPool {
       .sort((left, right) => right[0] - left[0])
       .map(([level, held]) => `${urgencyName(level)} ${held.zones} zone(s) ${held.megabytes.toFixed(0)}MB`)
       .join(", ");
+    // Something is wanted of this torrent, which may be news: a map published
+    // for a file of a torrent whose swarm was let go is what takes it back.
+    this?.followTheDemand?.(torrent);
     const said = `${fileIndex}:${shape}`;
     if (lastMapSaid.get(torrent) !== said) {
       lastMapSaid.set(torrent, said);
@@ -1293,8 +1468,7 @@ export class TorrentPool {
   #reportStalledDownloads() {
     const now = Date.now();
     for (const torrent of this.torrents.values()) {
-      const usage = this.fileUsageByTorrent.get(torrent);
-      if (!usage || usage.size === 0 || torrent?.done === true) {
+      if (!isWanted(torrent) || torrent?.done === true) {
         continue;
       }
       const speed = typeof torrent.downloadSpeed === "number" ? torrent.downloadSpeed : 0;
@@ -1334,27 +1508,25 @@ export class TorrentPool {
     if (!this.client || this.client.destroyed || typeof this.client.throttleUpload !== "function") {
       return;
     }
-    const active = torrentsForUploadPolicy(
-      this.torrents.values(),
-      this.fileUsageByTorrent,
-      Date.now()
-    );
+    const active = torrentsForUploadPolicy(this.torrents.values(), Date.now());
     // The one place the swarm is told anything: it reads what everybody has
     // stated and works out for itself what to ask for, including whether the
     // speculative levels may be stated at all — which is a question about every
     // torrent at once, because they share the link.
     reconcileAll();
     for (const torrent of this.torrents.values()) {
-      const usage = this.fileUsageByTorrent.get(torrent);
-      if (!usage || usage.size === 0 || torrent?.done === true) {
+      if (!isWanted(torrent) || torrent?.done === true) {
         continue;
       }
       this.#stateBackgroundFill(torrent);
+      // And act on what that just said. The fill withdraws itself once nothing
+      // else wants the file, so a torrent everybody has left can be held by the
+      // fill's own claim until this pass — and without this line the moment it
+      // goes would be noticed by nobody, leaving the torrent in its swarm with
+      // no idle clock running.
+      this.followTheDemand(torrent);
     }
     this.#reportStalledDownloads();
-    for (const torrent of this.torrents.values()) {
-      this.followTheReaders(torrent);
-    }
     const { bytesPerSec, reason } = decideUploadLimit(active);
     if (bytesPerSec === this.#uploadLimit) {
       return;
@@ -1393,12 +1565,10 @@ export class TorrentPool {
     if (used <= this.#maxDiskBytes) {
       return;
     }
-    // Candidates: pooled torrents with zero active readers, LRU first.
+    // Candidates: pooled torrents nothing is wanted of, the longest unwanted
+    // first.
     const candidates = [...this.torrents.values()]
-      .filter((torrent) => {
-        const usage = this.fileUsageByTorrent.get(torrent);
-        return !usage || usage.size === 0;
-      })
+      .filter((torrent) => !isWanted(torrent))
       .sort(
         (earlier, later) =>
           (this.#lastAccess.get(earlier) ?? 0) - (this.#lastAccess.get(later) ?? 0)
@@ -1666,7 +1836,6 @@ export class TorrentPool {
                   this.torrents.delete(otherKey);
                 }
               }
-              this.fileUsageByTorrent.delete(existing);
               this.#lastAccess.delete(existing);
               this.#readPositionByTorrent.delete(existing);
               this.client.remove(existing, { destroyStore: true }, () => {
@@ -1730,6 +1899,11 @@ export class TorrentPool {
         // leave the survivor unwatched. Attaching twice costs nothing — the
         // guard makes the second call a no-op when it is the same object.
         this.#attachSwarmDiagnostics(readyTorrent);
+        // On the clock from the moment it exists. A torrent nobody ever states
+        // anything about — a file list fetched and never played — used to be
+        // held for the life of the process, because the only thing that ever
+        // started the idle timer was a reader letting go.
+        this.followTheDemand(readyTorrent);
         resolve(readyTorrent);
       });
       // Attached to what `add` returns, NOT inside its callback. That callback
@@ -1748,62 +1922,61 @@ export class TorrentPool {
   }
 
   /**
-   * Increment the reference count for a file, selecting it for download.
-   * Returns a release function that decrements the count; when it reaches
-   * zero the file is automatically deselected.
+   * Torrents something has been wanted of at least once, which is what tells a
+   * departure from a beginning.
+   *
+   * @type {WeakSet<object>}
+   */
+  #wasWanted = new WeakSet();
+
+  /**
+   * ACT ON WHAT IS WANTED OF THIS TORRENT, and on nothing else.
+   *
+   * Called wherever what is wanted changes — a priority map applied or emptied,
+   * the ends of a file stated — because those are the moments, and a pass that
+   * asks every torrent every few seconds has the wrong answer between two of
+   * them. That is not a theory: 2.83.1 asked such a question every five seconds
+   * and a torrent added three seconds earlier answered "nobody", so it left its
+   * swarm with 741 connections let go and playback never started.
+   *
+   * What it does NOT do is decide whether a torrent is wanted. That is
+   * {@link isWanted}, which reads what has been stated, and the only reason
+   * this is a method at all is that the idle timer and the eviction order are
+   * the pool's own.
    *
    * @param {import("webtorrent").Torrent} torrent
-   * @param {number} fileIndex - Zero-based index into `torrent.files`.
-   * @returns {() => void} Release function — call it once when done streaming.
+   * @returns {void}
    */
-  acquireFile(torrent, fileIndex) {
-    if (!torrent || !Array.isArray(torrent.files) || !Number.isInteger(fileIndex) || fileIndex < 0) {
-      return () => undefined;
+  followTheDemand(torrent) {
+    if (!torrent || torrent.destroyed) {
+      return;
     }
-    let usage = this.fileUsageByTorrent.get(torrent);
-    if (!usage) {
-      usage = new Map();
-      this.fileUsageByTorrent.set(torrent, usage);
+    const { swarm, onTheClock } = swarmDecisionFor({
+      wanted: isWanted(torrent),
+      everWanted: this.#wasWanted.has(torrent)
+    });
+    if (swarm === "take") {
+      this.#wasWanted.add(torrent);
+      this.#cancelIdleRemoval(torrent);
+      // When it was last wanted, which is the order the disk cap evicts in.
+      this.#lastAccess.set(torrent, Date.now());
+      rejoinSwarm(torrent);
     }
-    // The torrent is in use again — cancel any pending idle removal and mark
-    // it recently accessed so LRU eviction keeps it.
-    this.#cancelIdleRemoval(torrent);
-    this.#lastAccess.set(torrent, Date.now());
-    // And rejoin its swarm HERE rather than at the next five-second pass: a
-    // reader that has just arrived is about to ask for bytes, and a torrent
-    // still paused answers by fetching nothing at all.
-    if (torrent.paused === true) {
-      torrent.resume();
-      logger.info(
-        `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] rejoined the swarm — a reader arrived`
-      );
+    // A PROXY THAT NEEDS NOTHING FROM A SWARM SHOULD NOT BE IN THAT SWARM. The
+    // data stays on disk; the next thing that wants a byte of it takes the
+    // swarm back.
+    if (swarm === "let go") {
+      leaveSwarm(torrent);
+    }
+    if (onTheClock) {
+      this.#scheduleIdleRemoval(torrent);
     }
-    usage.set(fileIndex, (usage.get(fileIndex) ?? 0) + 1);
-
-    let released = false;
-    return () => {
-      if (released) {
-        return;
-      }
-      released = true;
-      const nextCount = (usage.get(fileIndex) ?? 0) - 1;
-      if (nextCount > 0) {
-        usage.set(fileIndex, nextCount);
-      } else {
-        usage.delete(fileIndex);
-      }
-      if (usage.size === 0) {
-        this.fileUsageByTorrent.delete(torrent);
-        // No active readers — schedule removal (with store) after an idle TTL.
-        this.#scheduleIdleRemoval(torrent);
-      }
-      };
   }
 
   /**
    * Schedule removal of a torrent (with its on-disk store) after
-   * {@link TORRENT_IDLE_TTL_MS} of zero file refcount. Idempotent — replaces
-   * any existing timer for the torrent.
+   * {@link TORRENT_IDLE_TTL_MS} of nothing being wanted of it. Idempotent —
+   * replaces any existing timer for the torrent.
    *
    * @param {import("webtorrent").Torrent} torrent
    * @returns {void}
@@ -1818,11 +1991,13 @@ export class TorrentPool {
     logger.info(`torrent-pool: scheduling idle removal for "${name}" [${infoHashShort}] in ${TORRENT_IDLE_TTL_MS / 1000}s`);
     const timer = setTimeout(() => {
       this.#idleTimers.delete(torrent);
-      // Re-check: a new acquire since scheduling would have cancelled this
-      // timer, but guard anyway against a race.
-      const usage = this.fileUsageByTorrent.get(torrent);
-      if (usage && usage.size > 0) {
-        logger.info(`torrent-pool: idle timer fired for "${name}" [${infoHashShort}] but refcount ${usage.size} >0 — keep`);
+      // Re-check: anything stated since would have cancelled this timer, but
+      // guard anyway against a race.
+      if (isWanted(torrent)) {
+        logger.info(
+          `torrent-pool: idle timer fired for "${name}" [${infoHashShort}] but ` +
+          `${demandFor(torrent).register.size} thing(s) are stated for it — keep`
+        );
         return;
       }
       logger.warn(`torrent-pool: idle TTL fired for "${name}" [${infoHashShort}] — removing torrent (reason=idle-ttl caller=scheduleIdleRemoval)`);
@@ -1882,7 +2057,6 @@ export class TorrentPool {
       return;
     }
     forgetTorrent(torrent);
-    this.fileUsageByTorrent.delete(torrent);
     this.#lastAccess.delete(torrent);
     this.#readPositionByTorrent.delete(torrent);
     const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
@@ -1915,8 +2089,7 @@ export class TorrentPool {
     }
     const infoHash = String(torrent.infoHash ?? "?").slice(0, 8);
     const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
-    const usage = this.fileUsageByTorrent.get(torrent);
-    const refcount = usage ? usage.size : 0;
+    const stated = demandFor(torrent).register.size;
     const hasData = (() => { try { return torrentDownloadedBytes(torrent); } catch { return -1; } })();
     // Capture caller for diagnostics — not for control flow.
     const caller = new Error().stack?.split("\n")[2]?.trim() ?? "";
@@ -1927,10 +2100,9 @@ export class TorrentPool {
         break;
       }
     }
-    this.fileUsageByTorrent.delete(torrent);
     this.#lastAccess.delete(torrent);
     this.#readPositionByTorrent.delete(torrent);
-    logger.warn(`torrent-pool: removing torrent "${name}" [${infoHash}] reason=${reason} refcount=${refcount} downloaded=${hasData}B caller=${caller}`);
+    logger.warn(`torrent-pool: removing torrent "${name}" [${infoHash}] reason=${reason} stated=${stated} downloaded=${hasData}B caller=${caller}`);
     try {
       torrent.destroy({ destroyStore: true }, () => {
         logger.info(`torrent-pool: removed torrent "${name}" [${infoHash}] reason=${reason} and its store`);
@@ -2158,16 +2330,31 @@ export class TorrentPool {
    * @param {number} [options.headBytes=262144]   - Leading bytes to fetch (default 256 KB).
    * @param {number} [options.tailBytes=2097152]  - Trailing bytes to fetch (default 2 MB).
    * @param {number} [options.timeoutMs=300000]   - Maximum wait time in milliseconds (default 5 min).
+   * @param {boolean} [options.awaited=false] - Whether somebody is waiting for
+   *   these bytes right now. The playback plan is: it cannot answer until the
+   *   file has said what is in it, and a person is watching a loading screen
+   *   meanwhile. The warm-up is NOT, by its whole purpose — it happens while
+   *   the viewer is still choosing, so it must not outrank another film that
+   *   somebody is watching on this proxy this minute.
    * @returns {Promise<void>}
    */
   async prefetchFileEdges(
     torrent,
     fileIndex,
-    { headBytes = 256 * 1024, tailBytes = 2 * 1024 * 1024, timeoutMs = 300_000 } = {}
+    { headBytes = 256 * 1024, tailBytes = 2 * 1024 * 1024, timeoutMs = 300_000, awaited = false } = {}
   ) {
     if (!torrent || !Array.isArray(torrent.files)) {
       return;
     }
+    // THE ENDS OF THIS FILE ARE WANTED, and they go on being wanted after this
+    // read is over: the file's own directory lives there, and a seek asks for
+    // it again. Stated before the read rather than by it, and kept afterwards
+    // at the level of something nobody is waiting for.
+    stateFileEdges(torrent, fileIndex, awaited ? Urgency.NEAR : Urgency.TAIL);
+    // The first thing ever stated about a torrent being opened, and therefore
+    // what keeps it in its swarm through the seconds when nothing else can say
+    // anything about it.
+    this.followTheDemand(torrent);
     // Two callers can ask for the same edges at once: the warm-up that starts
     // when a torrent is picked, and the playback plan a moment later. Reading
     // the same two pieces twice costs nothing in bandwidth — the torrent
@@ -2184,6 +2371,10 @@ export class TorrentPool {
       return await prefetch;
     } finally {
       this.#edgePrefetches.delete(inFlightKey);
+      // Nobody is waiting for them now. Said with `lower`, because this is the
+      // one caller entitled to put them back down: the read it belongs to is
+      // over, and there is no other — a file's edges are fetched once at a time.
+      stateFileEdges(torrent, fileIndex, Urgency.TAIL, { lower: true });
     }
   }