@torrent-tv/proxy 2.83.3 → 2.83.5

package/services/torrent-pool.js

@@ -18,12 +18,16 @@ import { logger } from "../utils/logger.js";
 import { SharedPieceStore, findSharedStore } from "./piece-store/shared-piece-store.js";
 import { Urgency, urgencyName } from "./demand/index.js";
 import { demandFor, forgetTorrent, reconcileAll, hasUnmetDemand } from "./download/registry.js";
+import { withdrawClaim } from "./download/withdraw-claim.js";
 import { isAtAWatchingViewer, isBehindEverybody, isNobodyComingNow } from "./priority/PriorityMap.js";
 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 +335,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 +398,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 : "?";
@@ -789,6 +789,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`.
@@ -929,6 +1099,79 @@ export class TorrentPool {
     this.#storeExtras = extras && typeof extras === "object" ? extras : {};
   }
 
+  /**
+   * Everything a store of this pool is built with, in ONE place.
+   *
+   * It was assembled at both `client.add` sites — the ordinary one and the one
+   * that replaces a torrent the client no longer has — and a store built by the
+   * second was missing whatever the first had gained. That is how a store came
+   * to exist without the whole-file reader it needs, and it is why this is a
+   * method rather than a literal.
+   *
+   * @returns {object}
+   */
+  #storeOptions() {
+    return {
+      memoryBytes: this.#memoryBytes,
+      ...this.#storeExtras,
+      // WIRED BY THE POOL ITSELF, not handed in: withdrawing the claim needs
+      // only a torrent, and this class is the one that owns them. Last, so a
+      // caller's extras cannot displace the one thing that keeps the library's
+      // completion bitfield in step with the bytes.
+      onPieceGone: (what) => this.withdrawPieceClaim(what)
+    };
+  }
+
+  /**
+   * Withdraw the claim that this proxy has a piece, because the store that held
+   * it no longer can produce it.
+   *
+   * **Whose job this is.** The store owns the bytes and therefore owns the fact;
+   * the library keeps a second copy of that fact in its completion bitfield, and
+   * this pool is the only thing here that owns a torrent, so reconciling the two
+   * is this class's and nothing else's. The store announces and does not know
+   * who listens.
+   *
+   * **What it costs.** The piece is re-created as incomplete, so the next read
+   * that wants it waits for a download instead of failing. Field 2026-09-12,
+   * which is what this is for: 565 spilled pieces were dropped behind the read
+   * heads — correctly, they were behind every reader — the bitfield went on
+   * saying they were verified, the encoder restarted and re-opened its input at
+   * byte 0, and `Piece 0 is verified but absent from the store` then answered
+   * every read for 92 minutes. Nothing re-downloaded it, because the library
+   * does not fetch what it believes it owns.
+   *
+   * **What it deliberately does not do.** `_markUnverified` would also re-select
+   * the piece, and does not here: every torrent is added with `deselect: true`,
+   * which sets the library's own `_startAsDeselected` and makes it skip that
+   * call. The download set has one owner — `SwarmSelection`, from the priority
+   * map — and a piece withdrawn here is fetched again when a read states it,
+   * which is the same statement every other piece waits on.
+   *
+   * @param {object} what
+   * @param {number} what.index
+   * @param {object[]} what.files - The store's own, from which the torrent that
+   *   owns them is found; the store has no idea what a torrent is.
+   * @returns {void}
+   */
+  withdrawPieceClaim({ index, files }) {
+    const outcome = withdrawClaim({
+      index,
+      files,
+      warn: (line) => logger.warn(`torrent-pool: ${line}`)
+    });
+    if (outcome === "withdrawn") {
+      this.#claimsWithdrawn += 1;
+    }
+  }
+
+  /** How many claims this pool has withdrawn, over its whole life. */
+  #claimsWithdrawn = 0;
+
+  get claimsWithdrawn() {
+    return this.#claimsWithdrawn;
+  }
+
   constructor({ maxDiskBytes, memoryBytes, dhtBootstrap } = {}) {
     this.#memoryBytes = Number.isFinite(memoryBytes) && memoryBytes > 0 ? memoryBytes : undefined;
 
@@ -984,7 +1227,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}`);
@@ -1115,13 +1357,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);
@@ -1169,6 +1412,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);
@@ -1243,15 +1502,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
@@ -1275,6 +1526,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);
@@ -1288,8 +1542,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;
@@ -1329,22 +1582,23 @@ 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();
     const { bytesPerSec, reason } = decideUploadLimit(active);
@@ -1385,12 +1639,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)
@@ -1658,14 +1910,13 @@ 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 }, () => {
                 const addedReplacement = this.client.add(torrentId, {
                   store: SharedPieceStore,
                   storeCacheSlots: 0,
-                  storeOpts: { memoryBytes: this.#memoryBytes, ...this.#storeExtras },
+                  storeOpts: this.#storeOptions(),
                   deselect: true
                 }, (replacement) => {
                   this.torrents.set(key, replacement);
@@ -1698,7 +1949,7 @@ export class TorrentPool {
       const added = this.client.add(torrentId, {
         store: SharedPieceStore,
         storeCacheSlots: 0,
-        storeOpts: { memoryBytes: this.#memoryBytes, ...this.#storeExtras },
+        storeOpts: this.#storeOptions(),
         // Nothing is fetched until somebody says they want it. WebTorrent's own
         // default is `this.select(0, this.pieces.length - 1)` — the whole
         // torrent — and this proxy used to undo that afterwards by deselecting
@@ -1722,6 +1973,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
@@ -1740,59 +1996,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);
+    }
+    // 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);
     }
-    // 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, which is 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.
-    rejoinSwarm(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);
-        // THE READER LEFT, AND THAT IS THE ONLY MOMENT A SWARM MAY BE LET GO.
-        leaveSwarm(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}
@@ -1807,11 +2065,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)`);
@@ -1871,7 +2131,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)";
@@ -1904,8 +2163,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() ?? "";
@@ -1916,10 +2174,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`);
@@ -2147,16 +2404,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
@@ -2173,6 +2445,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 });
     }
   }