@torrent-tv/proxy 2.76.5 → 2.76.6

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.76.6
+
+- **New**: The proxy says which films it is already downloading, in the same health poll the browser makes before it picks one. A viewer sent to the proxy that has their film costs it the encode and nothing else — the torrent is there, its pieces are there, and where the output is identical they share that too — while the same viewer sent anywhere else starts the download from nothing. Answered from the torrent thread, which is the only truthful record: the main thread keeps stand-ins that are cleared on shutdown alone, so they name films this proxy let go of hours ago. A proxy that cannot answer is scored on its machine as before.
+- **Chore**: Two doc comments in the torrent pool's interface described methods that had been moved or renamed out from under them, leaving the methods below without one. Each is back over its own.
+
 ## 2.76.5
 
 - **Chore**: What encoding costs this machine is a class of its own (`services/quality/EncodeCost.js`), the third part taken out of the session manager. One subject — seconds of work per second of video — asked about a picture being re-encoded, a soundtrack, a copy, everything running beside the rung being judged, and turned into the list of heights the machine can hold. It holds what an encoder taught it, since it is the only thing that reads those figures, and it is given what it cannot work out for itself: which sessions belong to one file, the host's own readings, how many encoders are running, and what the file costs merely by being fetched. The host is asked at the moment of the question rather than copied when the object is made — the share of the machine that is free is re-read every few seconds, and a copy would price every later rung against a machine that has gone. The manager keeps the three methods that LEARN those costs; moving them is the next step.

package/bin/cli.js

@@ -473,8 +473,20 @@ try {
     onSignal(sessionId, signal) {
       webRtcManager?.handleSignal(sessionId, signal);
     },
-    onHealthRequest() {
-      return collectHealthMetrics();
+    async onHealthRequest() {
+      // Which films this proxy holds travels with the health poll the browser
+      // already makes before it picks one: a viewer sent to a proxy that is
+      // downloading their film costs it the encode and nothing else, while the
+      // same viewer sent anywhere else starts the download from nothing. Asked
+      // of the worker, so a film this proxy let go of is not claimed.
+      let holds = [];
+      try {
+        holds = (await started?.torrentPool?.heldTorrents?.()) ?? [];
+      } catch {
+        // silent-ok: a proxy that cannot say what it holds is scored on its
+        // machine alone, which is what every proxy was scored on until now.
+      }
+      return { metrics: collectHealthMetrics(), holds };
     },
     // Whether this host could sustain a file it has only been told about. The
     // same arithmetic the first offer uses, against this host's own startup

package/package.json

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

package/server.js

@@ -378,6 +378,10 @@ export async function startProxyServer({
     // recorded from a browser request and published from the pool's side, so
     // resolving one into the other is what lets the two ends agree on what
     // they are both calling "sourceKey".
-    sourceRegistry
+    sourceRegistry,
+    // Which films this host holds, for the health poll the browser makes before
+    // it picks a proxy. The pool is on the worker thread and this is the way to
+    // it from the process that answers that poll.
+    torrentPool
   };
 }

package/services/torrent-worker/client.js

@@ -403,6 +403,19 @@ export class TorrentWorkerClient {
     return this.#caller.call(Command.TORRENT_TOTALS, {});
   }
 
+  /**
+   * Which films this proxy holds right now, and how much of each.
+   *
+   * Asked of the worker rather than of the main thread's map of stand-ins: that
+   * map is only cleared on shutdown, so it names films this proxy let go of
+   * hours ago.
+   *
+   * @returns {Promise<{ held: { infoHash: string, progress: number, bytes: number }[] }>}
+   */
+  async heldTorrents() {
+    return this.#caller.call(Command.HELD_TORRENTS, {});
+  }
+
   /**
    * Reorder piece selection around a read position (seek prioritisation).
    *

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

@@ -1,370 +1,384 @@
-/**
- * @file `TorrentPool`'s interface, served from the worker thread.
- *
- * The routes, the planner, the health report and the session manager all reach
- * for a torrent pool and use it the same handful of ways. Rather than rewrite
- * every one of them to thread a `sourceKey` through and await what used to be
- * immediate, this presents the shape they already expect and does the thread
- * hop behind it. Swapping the implementation is then a one-line change at
- * construction, and the call sites are untouched — which is what keeps a change
- * of this size reviewable.
- *
- * Two accommodations are needed, and both are deliberate:
- *
- *  - **`acquireFile` and `prioritizeByteRange` stay synchronous.** They return
- *    nothing the caller inspects, so the command is dispatched and not awaited.
- *    `acquireFile` hands back a release function exactly as before, which sends
- *    its own command when called. Awaiting them would mean touching every call
- *    site for no observable gain.
- *  - **`getTorrent` needs a `sourceKey`.** Torrent objects cannot cross a
- *    thread, so the worker keys them. Callers that have one pass it; the rest
- *    get one derived from the source itself, so the identity stays stable
- *    across calls for the same torrent.
- */
-
-import { TorrentWorkerClient } from "./client.js";
-import { deriveSourceKey } from "../torrent-source-key.js";
-
-/**
- * A torrent pool whose work happens on another thread.
- *
- * See `protocol.js` for why: the torrent was taking ~85% of the main thread and
- * everything owed to a viewer queued behind it.
- */
-export class WorkerTorrentPool {
-  #client;
-  /** Stand-ins by source key, so repeat calls return the same object. */
-  #torrents = new Map();
-
-  /**
-   * @param {{ maxDiskBytes?: number, memoryBytes?: number, stateDir?: string }} [options]
-   */
-  constructor(options = {}) {
-    this.#client = new TorrentWorkerClient(options);
-  }
-
-  /**
-   * Load (or join) a torrent and return a stand-in for it.
-   *
-   * @param {"magnet" | "torrent"} sourceType
-   * @param {string} source
-   * @returns {Promise<object>}
-   */
-  async getTorrent(sourceType, source) {
-    const sourceKey = await deriveSourceKey(sourceType, source);
-    const existing = this.#torrents.get(sourceKey);
-    if (existing) {
-      return existing;
-    }
-    const torrent = await this.#client.getTorrent({ sourceKey, sourceType, source });
-    this.#torrents.set(sourceKey, torrent);
-    return torrent;
-  }
-
-  /**
-   * Claim a file for reading; the returned function releases it.
-   *
-   * Synchronous by design — see the file header.
-   *
-   * @param {object} torrent - A stand-in from {@link getTorrent}.
-   * @param {number} fileIndex
-   * @returns {() => void}
-   */
-  acquireFile(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return () => undefined;
-    }
-    // Dispatched, not awaited — callers use the result immediately and inspect
-    // nothing. But the release MUST NOT overtake it: both are ordinary messages
-    // to the worker, and if release arrives first the reader count drops to zero
-    // while a read is still running. The idle sweep then removes the torrent AND
-    // its downloaded data out from under the encoder — field 2026-08-02:
-    // "removed idle torrent ... and its store" mid-playback, after which every
-    // read hung and ffmpeg saw an empty input ("Stream ends prematurely at 0").
-    // Chaining the release onto the acquire keeps them in order.
-    const acquired = this.#client.acquireFile(sourceKey, fileIndex).catch(() => null);
-    let released = false;
-    return () => {
-      if (released) {
-        return;
-      }
-      released = true;
-      // Release the claim this call opened, not "the file" — waiting for the
-      // acquire is also what tells us which claim that is.
-      void acquired
-        .then((claimId) => (claimId ? this.#client.releaseFile(claimId) : undefined))
-        .catch(() => undefined);
-    };
-  }
-
-  /**
-   * Live download figures for the progress display.
-   *
-   * @param {object} torrent
-   * @param {number | null} [fileIndex]
-   * @param {{ resumeAnchorByteStart?: number | null }} [options]
-   * @returns {Promise<object | null>}
-   */
-  /**
-   * Bytes every torrent here has moved.
-   *
-   * @returns {Promise<{ downloaded: number, uploaded: number }>}
-   */
-  async getTorrentTotals() {
-    return this.#client.getTorrentTotals();
-  }
-
-  async getFileStats(torrent, fileIndex = null, options = {}) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    return this.#client.getFileStats({
-      sourceKey,
-      fileIndex,
-      resumeAnchorByteStart: options?.resumeAnchorByteStart ?? null
-    });
-  }
-
-  /**
-   * The text subtitle tracks a file carries, read from its own header.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  /**
-   * Fetch one whole file using only the room the viewer's own reading leaves.
-   *
-   * For a soundtrack or subtitle file shipped beside the picture: small next to
-   * the film, and having it on disk is what turns a later switch into a local
-   * read instead of a wait on the swarm.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<boolean>} Whether a fill was started by this call.
-   */
-  async fillFileInBackground(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return false;
-    }
-    const answer = await this.#client.fillFile({ sourceKey, fileIndex });
-    return answer?.started === true;
-  }
-
-  async getSubtitleTracks(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return [];
-    }
-    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
-    return Array.isArray(answer?.tracks) ? answer.tracks : [];
-  }
-
-  /**
-   * What the container itself declares about its subtitle tracks, in its own
-   * order and including the picture-based ones — for lining up against
-   * ffmpeg's own numbering.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getDeclaredSubtitleTracks(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return [];
-    }
-    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
-    return Array.isArray(answer?.declared) ? answer.declared : [];
-  }
-
-  /**
-   * Every track one file declares, read from its own header by the container
-   * layer.
-   *
-   * The audio menu is built from ffmpeg's `-i` banner, which carries neither
-   * `FlagOriginal`, `FlagCommentary`, `FlagVisualImpaired`, `FlagEnabled` nor
-   * `LanguageBCP47` — so without this a director's commentary and the film
-   * itself are indistinguishable in it. Also how a soundtrack shipped as its own
-   * file is read: a `.mka` is Matroska and the same reader serves it.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getContainerTracks(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return [];
-    }
-    const answer = await this.#client.getContainerTracks({ sourceKey, fileIndex });
-    return Array.isArray(answer?.tracks) ? answer.tracks : [];
-  }
-
-  /**
-   * Start fetching the region a viewer is about to resume at. Named in seconds
-   * here; the worker turns it into bytes, where the file's duration is readable.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {number} positionSeconds
-   * @returns {Promise<boolean>}
-   */
-  async warmResumePosition(torrent, fileIndex, positionSeconds) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return false;
-    }
-    const answer = await this.#client.warmResumePosition({ sourceKey, fileIndex, positionSeconds });
-    return answer?.started === true;
-  }
-
-  /**
-   * What one file declares about itself: format, duration, and where its own
-   * timeline begins.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
-   */
-  async getContainerMediaInfo(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    const answer = await this.#client.getContainerMediaInfo({ sourceKey, fileIndex });
-    return answer?.info ?? null;
-  }
-
-  /**
-   * Where one file's keyframes are, from the container's own table. Null when
-   * this file has no readable index — which is a final answer about the file,
-   * and the reason a copy of it has to be re-encoded instead.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<{ times: number[], tolerance: number } | null>}
-   */
-  async getContainerKeyframes(torrent, fileIndex) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    const answer = await this.#client.getContainerKeyframes({ sourceKey, fileIndex });
-    return answer?.index ?? null;
-  }
-
-  /**
-   * The audio tracks one file declares, in the order ffmpeg numbers them
-   * `0:a:N`.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object[]>}
-   */
-  async getDeclaredAudioTracks(torrent, fileIndex) {
-    const tracks = await this.getContainerTracks(torrent, fileIndex);
-    return tracks
-      .filter((track) => track?.type === "audio")
-      .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0));
-  }
-
-  /**
-   * The video track one file declares, or null where it declares none.
-   *
-   * One, because ffmpeg's `0:v:0` is what everything downstream is built on and
-   * a second video stream is a cover image far more often than a second film.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @returns {Promise<object | null>}
-   */
-  async getDeclaredVideoTrack(torrent, fileIndex) {
-    const tracks = await this.getContainerTracks(torrent, fileIndex);
-    return (
-      tracks
-        .filter((track) => track?.type === "video")
-        .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0))[0] ?? null
-    );
-  }
-
-  /**
-   * The cues of one subtitle track that the downloaded clusters already carry.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {number} trackNumber
-   * @returns {Promise<object | null>}
-   */
-  async getSubtitleCues(torrent, fileIndex, trackNumber) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    return this.#client.getSubtitleCues({ sourceKey, fileIndex, trackNumber });
-  }
-
-  /**
-   * Reorder piece selection around a read position.
-   *
-   * Synchronous by design — see the file header.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {number} byteStart
-   * @param {number} [windowBytes]
-   * @param {{ wholeFileRead?: boolean }} [options]
-   * @returns {void}
-   */
-  prioritizeByteRange(torrent, fileIndex, byteStart, windowBytes, options) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return;
-    }
-    void this.#client
-      .prioritizeByteRange({
-        sourceKey,
-        fileIndex,
-        byteStart,
-        windowBytes,
-        wholeFileRead: options?.wholeFileRead === true
-      })
-      .catch(() => undefined);
-  }
-
-  /**
-   * Pre-fetch the head and tail the codec probe needs.
-   *
-   * Takes an options object, matching `TorrentPool.prefetchFileEdges` — this
-   * adapter exists to present that same interface. It previously declared
-   * positional parameters instead, so the planner's options object arrived as
-   * `headBytes` and only worked because it was passed along far enough to be
-   * destructured at the far end. Anyone calling it as documented got the
-   * defaults instead of the sizes they asked for.
-   *
-   * @param {object} torrent
-   * @param {number} fileIndex
-   * @param {{ headBytes?: number, tailBytes?: number, timeoutMs?: number }} [options]
-   * @returns {Promise<unknown>}
-   */
-  async prefetchFileEdges(torrent, fileIndex, options = {}) {
-    const sourceKey = torrent?.sourceKey;
-    if (!sourceKey) {
-      return null;
-    }
-    return this.#client.prefetchFileEdges({ sourceKey, fileIndex, options });
-  }
-
-  /**
-   * Shut the torrent client down and stop the thread.
-   *
-   * @returns {Promise<void>}
-   */
-  async destroyAll() {
-    this.#torrents.clear();
-    await this.#client.destroyAll();
-  }
-}
+/**
+ * @file `TorrentPool`'s interface, served from the worker thread.
+ *
+ * The routes, the planner, the health report and the session manager all reach
+ * for a torrent pool and use it the same handful of ways. Rather than rewrite
+ * every one of them to thread a `sourceKey` through and await what used to be
+ * immediate, this presents the shape they already expect and does the thread
+ * hop behind it. Swapping the implementation is then a one-line change at
+ * construction, and the call sites are untouched — which is what keeps a change
+ * of this size reviewable.
+ *
+ * Two accommodations are needed, and both are deliberate:
+ *
+ *  - **`acquireFile` and `prioritizeByteRange` stay synchronous.** They return
+ *    nothing the caller inspects, so the command is dispatched and not awaited.
+ *    `acquireFile` hands back a release function exactly as before, which sends
+ *    its own command when called. Awaiting them would mean touching every call
+ *    site for no observable gain.
+ *  - **`getTorrent` needs a `sourceKey`.** Torrent objects cannot cross a
+ *    thread, so the worker keys them. Callers that have one pass it; the rest
+ *    get one derived from the source itself, so the identity stays stable
+ *    across calls for the same torrent.
+ */
+
+import { TorrentWorkerClient } from "./client.js";
+import { deriveSourceKey } from "../torrent-source-key.js";
+
+/**
+ * A torrent pool whose work happens on another thread.
+ *
+ * See `protocol.js` for why: the torrent was taking ~85% of the main thread and
+ * everything owed to a viewer queued behind it.
+ */
+export class WorkerTorrentPool {
+  #client;
+  /** Stand-ins by source key, so repeat calls return the same object. */
+  #torrents = new Map();
+
+  /**
+   * @param {{ maxDiskBytes?: number, memoryBytes?: number, stateDir?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.#client = new TorrentWorkerClient(options);
+  }
+
+  /**
+   * Load (or join) a torrent and return a stand-in for it.
+   *
+   * @param {"magnet" | "torrent"} sourceType
+   * @param {string} source
+   * @returns {Promise<object>}
+   */
+  async getTorrent(sourceType, source) {
+    const sourceKey = await deriveSourceKey(sourceType, source);
+    const existing = this.#torrents.get(sourceKey);
+    if (existing) {
+      return existing;
+    }
+    const torrent = await this.#client.getTorrent({ sourceKey, sourceType, source });
+    this.#torrents.set(sourceKey, torrent);
+    return torrent;
+  }
+
+  /**
+   * Claim a file for reading; the returned function releases it.
+   *
+   * Synchronous by design — see the file header.
+   *
+   * @param {object} torrent - A stand-in from {@link getTorrent}.
+   * @param {number} fileIndex
+   * @returns {() => void}
+   */
+  acquireFile(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return () => undefined;
+    }
+    // Dispatched, not awaited — callers use the result immediately and inspect
+    // nothing. But the release MUST NOT overtake it: both are ordinary messages
+    // to the worker, and if release arrives first the reader count drops to zero
+    // while a read is still running. The idle sweep then removes the torrent AND
+    // its downloaded data out from under the encoder — field 2026-08-02:
+    // "removed idle torrent ... and its store" mid-playback, after which every
+    // read hung and ffmpeg saw an empty input ("Stream ends prematurely at 0").
+    // Chaining the release onto the acquire keeps them in order.
+    const acquired = this.#client.acquireFile(sourceKey, fileIndex).catch(() => null);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      // Release the claim this call opened, not "the file" — waiting for the
+      // acquire is also what tells us which claim that is.
+      void acquired
+        .then((claimId) => (claimId ? this.#client.releaseFile(claimId) : undefined))
+        .catch(() => undefined);
+    };
+  }
+
+  /**
+   * Bytes every torrent here has moved.
+   *
+   * @returns {Promise<{ downloaded: number, uploaded: number }>}
+   */
+  async getTorrentTotals() {
+    return this.#client.getTorrentTotals();
+  }
+
+  /**
+   * Live download figures for the progress display.
+   *
+   * @param {object} torrent
+   * @param {number | null} [fileIndex]
+   * @param {{ resumeAnchorByteStart?: number | null }} [options]
+   * @returns {Promise<object | null>}
+   */
+  async getFileStats(torrent, fileIndex = null, options = {}) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    return this.#client.getFileStats({
+      sourceKey,
+      fileIndex,
+      resumeAnchorByteStart: options?.resumeAnchorByteStart ?? null
+    });
+  }
+
+  /**
+   * Fetch one whole file using only the room the viewer's own reading leaves.
+   *
+   * For a soundtrack or subtitle file shipped beside the picture: small next to
+   * the film, and having it on disk is what turns a later switch into a local
+   * read instead of a wait on the swarm.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<boolean>} Whether a fill was started by this call.
+   */
+  async fillFileInBackground(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return false;
+    }
+    const answer = await this.#client.fillFile({ sourceKey, fileIndex });
+    return answer?.started === true;
+  }
+
+  /**
+   * The text subtitle tracks a file carries, read from its own header.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getSubtitleTracks(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return [];
+    }
+    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
+    return Array.isArray(answer?.tracks) ? answer.tracks : [];
+  }
+
+  /**
+   * What the container itself declares about its subtitle tracks, in its own
+   * order and including the picture-based ones — for lining up against
+   * ffmpeg's own numbering.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getDeclaredSubtitleTracks(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return [];
+    }
+    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
+    return Array.isArray(answer?.declared) ? answer.declared : [];
+  }
+
+  /**
+   * Every track one file declares, read from its own header by the container
+   * layer.
+   *
+   * The audio menu is built from ffmpeg's `-i` banner, which carries neither
+   * `FlagOriginal`, `FlagCommentary`, `FlagVisualImpaired`, `FlagEnabled` nor
+   * `LanguageBCP47` — so without this a director's commentary and the film
+   * itself are indistinguishable in it. Also how a soundtrack shipped as its own
+   * file is read: a `.mka` is Matroska and the same reader serves it.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getContainerTracks(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return [];
+    }
+    const answer = await this.#client.getContainerTracks({ sourceKey, fileIndex });
+    return Array.isArray(answer?.tracks) ? answer.tracks : [];
+  }
+
+  /**
+   * Start fetching the region a viewer is about to resume at. Named in seconds
+   * here; the worker turns it into bytes, where the file's duration is readable.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} positionSeconds
+   * @returns {Promise<boolean>}
+   */
+  async warmResumePosition(torrent, fileIndex, positionSeconds) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return false;
+    }
+    const answer = await this.#client.warmResumePosition({ sourceKey, fileIndex, positionSeconds });
+    return answer?.started === true;
+  }
+
+  /**
+   * What one file declares about itself: format, duration, and where its own
+   * timeline begins.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<import("../container/Container.js").ContainerMediaInfo | null>}
+   */
+  async getContainerMediaInfo(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    const answer = await this.#client.getContainerMediaInfo({ sourceKey, fileIndex });
+    return answer?.info ?? null;
+  }
+
+  /**
+   * Where one file's keyframes are, from the container's own table. Null when
+   * this file has no readable index — which is a final answer about the file,
+   * and the reason a copy of it has to be re-encoded instead.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<{ times: number[], tolerance: number } | null>}
+   */
+  async getContainerKeyframes(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    const answer = await this.#client.getContainerKeyframes({ sourceKey, fileIndex });
+    return answer?.index ?? null;
+  }
+
+  /**
+   * The audio tracks one file declares, in the order ffmpeg numbers them
+   * `0:a:N`.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getDeclaredAudioTracks(torrent, fileIndex) {
+    const tracks = await this.getContainerTracks(torrent, fileIndex);
+    return tracks
+      .filter((track) => track?.type === "audio")
+      .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0));
+  }
+
+  /**
+   * The video track one file declares, or null where it declares none.
+   *
+   * One, because ffmpeg's `0:v:0` is what everything downstream is built on and
+   * a second video stream is a cover image far more often than a second film.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object | null>}
+   */
+  async getDeclaredVideoTrack(torrent, fileIndex) {
+    const tracks = await this.getContainerTracks(torrent, fileIndex);
+    return (
+      tracks
+        .filter((track) => track?.type === "video")
+        .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0))[0] ?? null
+    );
+  }
+
+  /**
+   * The cues of one subtitle track that the downloaded clusters already carry.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} trackNumber
+   * @returns {Promise<object | null>}
+   */
+  async getSubtitleCues(torrent, fileIndex, trackNumber) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    return this.#client.getSubtitleCues({ sourceKey, fileIndex, trackNumber });
+  }
+
+  /**
+   * Reorder piece selection around a read position.
+   *
+   * Synchronous by design — see the file header.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} byteStart
+   * @param {number} [windowBytes]
+   * @param {{ wholeFileRead?: boolean }} [options]
+   * @returns {void}
+   */
+  prioritizeByteRange(torrent, fileIndex, byteStart, windowBytes, options) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return;
+    }
+    void this.#client
+      .prioritizeByteRange({
+        sourceKey,
+        fileIndex,
+        byteStart,
+        windowBytes,
+        wholeFileRead: options?.wholeFileRead === true
+      })
+      .catch(() => undefined);
+  }
+
+  /**
+   * Pre-fetch the head and tail the codec probe needs.
+   *
+   * Takes an options object, matching `TorrentPool.prefetchFileEdges` — this
+   * adapter exists to present that same interface. It previously declared
+   * positional parameters instead, so the planner's options object arrived as
+   * `headBytes` and only worked because it was passed along far enough to be
+   * destructured at the far end. Anyone calling it as documented got the
+   * defaults instead of the sizes they asked for.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {{ headBytes?: number, tailBytes?: number, timeoutMs?: number }} [options]
+   * @returns {Promise<unknown>}
+   */
+  async prefetchFileEdges(torrent, fileIndex, options = {}) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    return this.#client.prefetchFileEdges({ sourceKey, fileIndex, options });
+  }
+
+  /**
+   * Which films this proxy holds right now, and how much of each.
+   *
+   * What content affinity is decided from: a viewer of a film somebody here is
+   * already downloading costs this proxy the encode and nothing else, while the
+   * same viewer sent anywhere else starts the download from nothing.
+   *
+   * @returns {Promise<{ infoHash: string, progress: number, bytes: number }[]>}
+   */
+  async heldTorrents() {
+    const answer = await this.#client.heldTorrents();
+    return Array.isArray(answer?.held) ? answer.held : [];
+  }
+
+  /**
+   * Shut the torrent client down and stop the thread.
+   *
+   * @returns {Promise<void>}
+   */
+  async destroyAll() {
+    this.#torrents.clear();
+    await this.#client.destroyAll();
+  }
+}

package/services/torrent-worker/protocol.js

@@ -57,6 +57,8 @@ export const Command = {
   FILE_STATS: "file-stats",
   /** Bytes every torrent here has moved, for pricing the torrent's own cost. */
   TORRENT_TOTALS: "torrent-totals",
+  /** Which films this proxy holds right now, for content affinity. */
+  HELD_TORRENTS: "held-torrents",
   /** Reorder piece selection around a read position (seek prioritisation). */
   PRIORITIZE: "prioritize",
   /** Read a byte range; the body arrives as CHUNK messages. */

package/services/torrent-worker/worker.js

@@ -375,6 +375,29 @@ async function runCommand(command, params, id) {
       return released;
     }
 
+    case Command.HELD_TORRENTS: {
+      // Which films this proxy has right now, and how much of each. Answered
+      // from the live client rather than from the main thread's map of
+      // stand-ins, which is only cleared on shutdown and would name films this
+      // proxy let go of hours ago.
+      const held = [];
+      for (const torrent of pool.client?.torrents ?? []) {
+        const infoHash = String(torrent?.infoHash ?? "");
+        if (!infoHash) {
+          continue;
+        }
+        held.push({
+          infoHash,
+          // A viewer sent here for a film nobody has downloaded any of gains
+          // nothing, so the share is reported and the decision is made where
+          // the viewer is.
+          progress: Number.isFinite(torrent?.progress) ? torrent.progress : 0,
+          bytes: Number.isFinite(torrent?.downloaded) ? torrent.downloaded : 0
+        });
+      }
+      return { held };
+    }
+
     case Command.TORRENT_TOTALS: {
       // Downloaded and uploaded are counted apart: hashing every downloaded
       // byte is work of a different order from sending one back to the swarm,

package/services/tunnel-client.js

@@ -250,8 +250,24 @@ export function createTunnelClient({
 
       // Health check: server requests current metrics for proxy scoring.
       if (message.type === "health-request") {
-        const metrics = typeof onHealthRequest === "function" ? onHealthRequest() : {};
-        send({ type: "health-response", requestId: message.requestId, metrics });
+        // Awaited: the answer now carries which films this proxy holds, and the
+        // truthful list of those lives on the torrent thread.
+        void (async () => {
+          let answer = {};
+          try {
+            answer = typeof onHealthRequest === "function" ? await onHealthRequest() : {};
+          } catch {
+            // silent-ok: a proxy that cannot describe itself is scored on
+            // nothing rather than not answered at all, which would drop it out
+            // of every selection until the next poll.
+          }
+          send({
+            type: "health-response",
+            requestId: message.requestId,
+            metrics: answer?.metrics ?? answer ?? {},
+            holds: Array.isArray(answer?.holds) ? answer.holds : []
+          });
+        })();
         return;
       }
     });