@torrent-tv/proxy 2.51.0 → 2.52.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.52.0
+
+- **Fix**: A file opened at a position puts the SOUND there too. Where the audio rendition starts is computed from where the viewer is, and that reading consulted only two things — a position seeked to, and the last segment the session had served — both written by events that have not happened yet at the moment a file is opened partway through. The answer was therefore zero. Field 2026-08-21, `Minions.and.Monsters.1080p.mkv` reopened from the address bar at 52:07: the picture session was created at `start=3130s` and ran from segment #781, and half a second later the audio rendition was created at `start=0s` with no `-ss` at all and set about re-encoding the film from the beginning. The player asked both for #782; the picture had it, the sound reached 57.5 s of 3130 in the 45 s the request lasted and then answered 404 — which the viewer was shown as "the proxy accepted the request but sent no video". The position a session was OPENED at is now the third reading, and `resolveViewerPosition` is pure and tested. The same calculation prepares a track for a language change, so that case is covered by the same fix.
+- **Fix**: The line describing a swarm answers the question it is asked. It printed `peers=N` beside `wires=?`, which reads as two quantities of which one is unknown — while WebTorrent's `numPeers` IS `wires.length` (`lib/torrent.js`, identically in 2.8.5 and 3.0.21), so the first was the connection count and the second was a field that has never printed anything in any line it has ever written: the torrent lives on a worker thread and that property does not exist on the side doing the printing. What was missing was the other half of the question, and it is now there — how many peer addresses the client HOLDS, how many are queued to be tried, and what the tracker said the swarm has. Five offered and none connected is a connectivity fault; nobody offered is a supply fault; they need opposite investigations and one line now tells them apart. What the trackers said is kept PER TRACKER and reported as the best answer any of them gave: they answer separately, and a dead one replying `0` after a live one replied `500` would otherwise turn "several offered" into "nobody offered", inverting the very distinction being drawn.
+- **New**: The wait for the first connected peer is measured, said once when it ends, and carried in the stats while it is still going. Measured 2026-08-21 on `JUFD665.mp4`: the tracker answered `seeders=5` at 13:40:30 and the first wire arrived at 13:44:47 — 4 min 17 s of a viewer watching an unexplained wait, after which the file's 12 MiB of edges arrived at 6.8 MB/s and the plan finished in three seconds. The whole cold start was that one number, and it was neither counted nor shown. The watching is attached to what `add` returns rather than inside its ready callback, because for a magnet everything it watches happens before `ready`: peer discovery starts before the metadata arrives, so the trackers' answers land before any listener exists, and the peer that DELIVERED the metadata connected before `ready` fired — `wire` is emitted on connection and never replayed. It is also attached once per torrent: WebTorrent answers a duplicate add by handing back the torrent it already has, and re-attaching reset the timing of a live swarm, after which the next connection would print "first peer connected after 0.3s" about a torrent that had been connected for minutes.
+- **Fix**: One name for a torrent, and it is the infohash. The pool's `added`, `announce` and `warning` lines were labelled with the first eight characters of a sha1 of the SOURCE BYTES, the upload lines used the infohash, and the stats line used the registry's own key — three different hashes of one film, printed in the same second, none matching. The infohash is now on all of them, and on every stats line rather than only on the ones that look empty.
+- **Chore**: `askedFor=0` is called `fileIndex=0`. It is the index of the file being asked about, and it was printed under a name that reads as "nothing was asked for" — in a line whose subject is a download that is not happening.
+
 ## 2.51.0
 
 - **Fix**: A run is POSITIONED where the player was told the segment begins, on the same table its cuts are stated on. There are two boundary tables — the one the playlist text was written from, which never changes, and the live one, corrected as produced segments reveal where the file's cuts truly are. 2.45.0 moved the CUT LIST onto the published table and left the position on the live one, and that is one fault rather than two: `-segment_times` are measured from wherever the run really began, so any distance between the two carries into EVERY cut the run makes. The corrections run backwards, so each restart began a little earlier than the grid its cuts were stated on, and because the corrections accumulate, so did the distance. Measured 2026-08-21 on `JUFD665.mp4` — an MP4 whose index was read cleanly, 1765 keyframes, served by copy: after one seek restart a produced segment held the boundary **two** places before its own number (16.684 s, exactly 2.0000 segments), after the next restart **four** (33.5 s). The player's buffer then stops extending at all, because every fragment's content lands before the time its playlist entry names: `bufferEnd` stood still at 4571.1 s through four `frag-far` warnings until hls.js gave up and jumped the viewer 16.8 s forward. Four of those jumps in one window is what the viewer reported as sticking on every seek.

package/package.json

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

package/routes/api/sources/stats/get.js

@@ -61,6 +61,37 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     stats.headerBytes != null
       ? `${stats.headerDownloadedBytes}/${stats.headerBytes}B`
       : "n/a";
+  // The swarm, said so that the question this line is asked can be answered
+  // from it. "Connected" and "known" are different numbers and their
+  // difference is the diagnosis: a tracker offering five while we are
+  // connected to none is a connectivity fault, and nobody offering anything is
+  // a supply fault. Until 2026-08-21 the line printed `peers=` beside
+  // `wires=?` — two quantities of which one looked unknown, while in truth the
+  // first WAS the connection count and the second was a field that never
+  // printed anything, because the torrent lives on another thread and the
+  // property does not exist on this side of it.
+  const known = stats.knownPeers === null || stats.knownPeers === undefined ? "?" : stats.knownPeers;
+  const queued = stats.queuedPeers === null || stats.queuedPeers === undefined ? "?" : stats.queuedPeers;
+  // The BEST answer any tracker gave, and how many answered — not the most
+  // recent one. Trackers answer separately, and a dead one replying `0` after a
+  // live one replied `500` would otherwise turn "several offered" into "nobody
+  // offered", which is the distinction this whole line exists to make.
+  const offered = stats.trackerSeeders === null || stats.trackerSeeders === undefined
+    ? (stats.trackersAnswered
+        // Answered, and none of them knew of anybody — a different state from
+        // "no tracker has replied at all", and the line must not read as the
+        // second when it means the first.
+        ? `${stats.trackersAnswered} tracker(s) answered, none reported a count`
+        : "no tracker answer yet")
+    : `${stats.trackersAnswered ?? "?"} tracker(s) offered up to ${stats.trackerSeeders} seeders ` +
+      `${stats.trackerLeechers ?? "?"} leechers`;
+  // The wait for a first peer can be the whole of a cold start — 257 s of it,
+  // measured — and it was neither counted nor shown.
+  const firstPeer = Number.isFinite(stats.secondsToFirstPeer)
+    ? ` firstPeerAfter=${stats.secondsToFirstPeer.toFixed(1)}s`
+    : Number.isFinite(stats.secondsWaitingForFirstPeer)
+      ? ` noPeerFor=${stats.secondsWaitingForFirstPeer.toFixed(1)}s`
+      : "";
   // When the answer is empty, say WHICH thing is missing. Field 2026-08-05: a
   // source reported `peers=0 file=n/a header=n/a` for minutes while that very
   // torrent was announcing to trackers with hundreds of seeders — and the line
@@ -70,12 +101,17 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
   // answerable from the log rather than by reasoning about it afterwards.
   const emptyAnswer = stats.fileProgress == null || (stats.numPeers === 0 && torrent.done !== true);
   const detail = emptyAnswer
-    ? ` | infoHash=${String(torrent.infoHash).slice(0, 8)} files=${torrent.files?.length ?? "?"}` +
-      ` askedFor=${fileIndex ?? "none"} resolved=${torrent.files?.[fileIndex ?? -1] ? "yes" : "no"}` +
-      ` wires=${torrent.wires?.length ?? "?"} done=${torrent.done === true}`
+    ? ` | files=${torrent.files?.length ?? "?"}` +
+      ` fileIndex=${fileIndex ?? "none"} resolved=${torrent.files?.[fileIndex ?? -1] ? "yes" : "no"}` +
+      ` done=${torrent.done === true}`
     : "";
+  // The infohash is on EVERY line, not only on the ones that look empty: it is
+  // the one identifier the pool's own lines, the worker's and this one share,
+  // and a line that carries it can be lined up with them without a guess.
   logger.info(
-    `[stats] ${sourceKey.slice(0, 8)} peers=${stats.numPeers} down=${downKbps}KB/s file=${filePct} header=${header}${detail}`
+    `[stats] ${sourceKey.slice(0, 8)} ${String(torrent.infoHash).slice(0, 8)} ` +
+    `peers=${stats.connectedPeers ?? stats.numPeers} connected of ${known} known (${queued} queued, ${offered})` +
+    `${firstPeer} down=${downKbps}KB/s file=${filePct} header=${header}${detail}`
   );
 
   return reply.send(stats);

package/services/hls-session-manager.js

@@ -1182,6 +1182,49 @@ export function segmentCutTimesFrom(boundaries, startIndex) {
   return times;
 }
 
+/**
+ * Where the viewer is, from the three things that can say so.
+ *
+ * In order, because each is a better answer than the next and each may be
+ * absent:
+ *
+ * 1. a position they seeked to — they said it themselves;
+ * 2. the start of the last segment this session actually served — where the
+ *    reading is;
+ * 3. **the position the file was OPENED at.**
+ *
+ * The third used to be missing, and its absence made the answer zero at exactly
+ * the moment it is asked. Both of the others are written by things that have
+ * not happened yet when a file is opened at a position — the first by a seek,
+ * the second by a segment served — so a session created to begin at 3130 s
+ * answered "the viewer is at the beginning". That is not a cautious default; it
+ * is a wrong answer, and the soundtrack acts on it.
+ *
+ * Field 2026-08-21, `Minions.and.Monsters.1080p.mkv` reopened from the address
+ * bar at 52:07: the picture session was created at `start=3130s` and ran from
+ * segment #781; half a second later the audio rendition was created from this
+ * reading — `start=0s`, no `-ss` at all — and set about re-encoding the film
+ * from the beginning. The player asked both for #782. The picture had it. The
+ * sound reached 57.5 s of 3130 in the 45 s the request lasted, then answered
+ * 404, which the viewer was shown as "the proxy accepted the request but sent
+ * no video".
+ *
+ * @param {{ seeked?: number, lastRequestedStart?: number | null, openedAt?: number }} readings
+ * @returns {number} Seconds, never negative.
+ */
+export function resolveViewerPosition({ seeked, lastRequestedStart, openedAt }) {
+  if (Number.isFinite(seeked) && seeked > 0) {
+    return seeked;
+  }
+  if (Number.isFinite(lastRequestedStart) && lastRequestedStart > 0) {
+    return lastRequestedStart;
+  }
+  if (Number.isFinite(openedAt) && openedAt > 0) {
+    return openedAt;
+  }
+  return 0;
+}
+
 /**
  * How far the live boundary table has moved from the one the player holds, said
  * in words.
@@ -6927,13 +6970,14 @@ export class HlsSessionManager {
   }
 
   #viewerPositionOf(session) {
-    if (Number.isFinite(session.viewerPositionSeconds) && session.viewerPositionSeconds > 0) {
-      return session.viewerPositionSeconds;
-    }
-    if (Number.isInteger(session.lastRequestedSegment) && session.lastRequestedSegment > 0) {
-      return this.#segmentStartTime(session, session.lastRequestedSegment);
-    }
-    return 0;
+    const lastRequestedStart = Number.isInteger(session.lastRequestedSegment) && session.lastRequestedSegment > 0
+      ? this.#segmentStartTime(session, session.lastRequestedSegment)
+      : null;
+    return resolveViewerPosition({
+      seeked: session.viewerPositionSeconds,
+      lastRequestedStart,
+      openedAt: session.progress?.startPositionSeconds
+    });
   }
 
   /**

package/services/torrent-pool.js

@@ -134,6 +134,100 @@ const STALL_SPEED_BYTES = 32 * 1024;
 const STALL_REPORT_AFTER_MS = 10_000;
 const STALL_REPORT_INTERVAL_MS = 30_000;
 
+/**
+ * How far this torrent has got towards HAVING a swarm: connected, known, and
+ * waiting to be tried.
+ *
+ * The question a stalled download is asked is "were we offered anybody", and
+ * until 2026-08-21 nothing could answer it. The line printed `peers=` beside
+ * `wires=?`, which read as two quantities of which one was unknown — while in
+ * fact WebTorrent's `numPeers` IS `wires.length` (`lib/torrent.js`, both 2.8.5
+ * and 3.0.21), so the first was the connection count and the second was a
+ * field that has never printed anything. What was missing is the other side:
+ * how many peer addresses the client HOLDS but is not connected to. A tracker
+ * answering `seeders=5` while `connected=0, known=0` is a different fault from
+ * `connected=0, known=5`, and only the second is about connecting.
+ *
+ * `_peersLength` and `_numQueued` are WebTorrent internals, not its published
+ * interface — a cached counter and a getter in 2.8.5, both getters in 3.0.21,
+ * read the same way in each. Read defensively on purpose: if a later version
+ * drops them the field says nothing rather than breaking a poll the browser
+ * makes every two seconds.
+ *
+ * @param {import("webtorrent").Torrent} torrent
+ * @returns {{ connectedPeers: number, knownPeers: number | null, queuedPeers: number | null }}
+ */
+export function describeSwarmReach(torrent) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires.length : 0;
+  const read = (value) => (typeof value === "number" && Number.isFinite(value) ? value : null);
+  let knownPeers = null;
+  let queuedPeers = null;
+  try {
+    knownPeers = read(torrent?._peersLength);
+    queuedPeers = read(torrent?._numQueued);
+  } catch {
+    // silent-ok: these are internals behind getters that can throw on a
+    // destroyed torrent, and the reading is a diagnostic. Nothing here is
+    // worth failing a stats poll for.
+  }
+  return { connectedPeers: wires, knownPeers, queuedPeers };
+}
+
+/**
+ * How long a torrent waited for its first connected peer.
+ *
+ * The whole of a cold start can be this one number and nothing else: measured
+ * 2026-08-21, a tracker answered `seeders=5` at 13:40:30 and the first wire
+ * arrived at 13:44:47 — 257 s during which the stats line repeated, unchanged,
+ * every two seconds. Once the peer connected the file's edges arrived at
+ * 6.8 MB/s and the plan finished in three seconds. It was never measured,
+ * never named, and the viewer saw it as an unexplained wait.
+ *
+ * @param {number} addedAtMs
+ * @param {number} firstPeerAtMs
+ * @returns {number | null} Seconds, or null while there is still no peer or
+ *   the two moments cannot be compared.
+ */
+export function secondsToFirstPeer(addedAtMs, firstPeerAtMs) {
+  if (!Number.isFinite(addedAtMs) || !Number.isFinite(firstPeerAtMs)) {
+    return null;
+  }
+  const seconds = (firstPeerAtMs - addedAtMs) / 1000;
+  return seconds >= 0 ? Number(seconds.toFixed(3)) : null;
+}
+
+/**
+ * The best answer any tracker has given, out of the answers they have given.
+ *
+ * A torrent announces to every tracker it lists and each answers separately,
+ * so keeping "the last one" makes the reading depend on which tracker replied
+ * most recently. A live tracker saying `complete=500` followed two seconds
+ * later by a dead one saying `complete=0` would print "nobody offered" — and
+ * telling that from "several offered and we reached none" is the entire reason
+ * this figure is carried. The best answer is the honest one: a swarm has as
+ * many seeders as the most informed tracker knows about.
+ *
+ * @param {Iterable<{ seeders: number | null, leechers: number | null }>} answers
+ * @returns {{ seeders: number | null, leechers: number | null, trackers: number }}
+ */
+export function bestAnnounce(answers) {
+  let seeders = null;
+  let leechers = null;
+  let trackers = 0;
+  for (const answer of answers ?? []) {
+    trackers += 1;
+    if (typeof answer?.seeders === "number" && (seeders === null || answer.seeders > seeders)) {
+      seeders = answer.seeders;
+      // Taken from the SAME answer, including when that answer gave no leecher
+      // count. Carrying the previous tracker's figure forward would pair one
+      // tracker's seeders with another's leechers and present the pair as one
+      // reading.
+      leechers = typeof answer.leechers === "number" ? answer.leechers : null;
+    }
+  }
+  return { seeders, leechers, trackers };
+}
+
 /**
  * What the swarm has been asked for, and what it is doing about it.
  *
@@ -655,6 +749,26 @@ export class TorrentPool {
   /** One-shot timer that reports the size of the DHT's routing table. */
   #dhtReportTimer = null;
 
+  /**
+   * The last announce answer per torrent — what the TRACKER says the swarm
+   * holds, as opposed to what we have managed to connect to. Kept because the
+   * two disagreeing is the whole diagnosis: five seeders offered and none
+   * connected is a connectivity fault, and nobody offered is a supply fault.
+   *
+   * Kept PER TRACKER, because each answers for itself and the most recent
+   * answer is not the most informed one.
+   *
+   * @type {WeakMap<import("webtorrent").Torrent, Map<string, { seeders: number | null, leechers: number | null, at: number }>>}
+   */
+  #lastAnnounceByTorrent = new WeakMap();
+
+  /**
+   * When each torrent was added, and when its first peer connected.
+   *
+   * @type {WeakMap<import("webtorrent").Torrent, { addedAt: number, firstPeerAt: number | null }>}
+   */
+  #swarmTimingByTorrent = new WeakMap();
+
   /**
    * @param {{ maxDiskBytes?: number }} [options]
    *   `maxDiskBytes` caps total downloaded torrent data; when omitted a
@@ -775,7 +889,10 @@ export class TorrentPool {
     }
     torrent.hurryUntil = until;
     logger.info(
-      `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] uploading generously for ` +
+      // `?? "?"` because one caller is the moment of adding, and `client.add`
+      // returns before the torrent id has been parsed — without it the line
+      // printed the first eight characters of the word "undefined".
+      `torrent-pool: [${String(torrent.infoHash ?? "?").slice(0, 8)}] uploading generously for ` +
         `${Math.round(UPLOAD_HURRY_MS / 1000)}s — ${why}`
     );
     this.#adjustUploadLimit();
@@ -1083,24 +1200,102 @@ export class TorrentPool {
    * warnings (tracker rejections/errors surface here). Without these a
    * zero-peer torrent gives no clue WHY it has no peers.
    *
-   * @param {string} label - Short source label for log lines.
    * @param {import("webtorrent").Torrent} torrent
    * @returns {void}
    */
-  #attachSwarmDiagnostics(label, torrent) {
+  #attachSwarmDiagnostics(torrent) {
+    // Attached ONCE per torrent. WebTorrent answers a duplicate add by handing
+    // back the torrent it already has, and this used to run again on it: a
+    // torrent with twelve connections and a first peer five minutes old had its
+    // timing record reset, so it began reporting "no peer yet" and the next
+    // connection printed "first peer connected after 0.3s" — a false statement
+    // about a swarm that had been healthy for minutes. The same film opened
+    // once as a .torrent and once as a magnet is exactly that case, and the
+    // roadmap already records it happening.
+    if (this.#swarmTimingByTorrent.has(torrent)) {
+      return;
+    }
     // A torrent nobody has asked for yet does not exist: this is called the
     // moment one is added, which is the moment a viewer started waiting.
     this.#markHurry(torrent, "just added");
-    const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
-    logger.info(
-      `torrent-pool: [${label}] added: files=${torrent.files?.length ?? 0} ` +
-        `private=${torrent.private ? "yes" : "no"} trackers=${trackerCount}`
-    );
+    // ONE name for a torrent, and it is the infohash. These lines used to be
+    // labelled with the first eight characters of a sha1 of the SOURCE BYTES,
+    // while the neighbouring lines used the infohash and the stats line used
+    // the registry's own key — three different hashes of one film, in the same
+    // second, none of them matching. Correlating a swarm across three lines
+    // cost a guess every time. The infohash is the one identifier every side
+    // of this system already shares.
+    //
+    // Read at the moment of PRINTING, not now. `client.add` returns before the
+    // torrent id has been parsed — measured against the vendored 2.8.5, both a
+    // magnet and a .torrent buffer have `infoHash === undefined` on the line
+    // after `add` returns — so a label captured here would be the string "?"
+    // for the whole life of the torrent, which is the same fault as three
+    // different hashes with the hash removed.
+    const label = () => String(torrent.infoHash ?? "?").slice(0, 8);
+    const addedAt = Date.now();
+    this.#swarmTimingByTorrent.set(torrent, { addedAt, firstPeerAt: null });
+
+    // The first connected peer, said once, because the wait for it can BE the
+    // whole cold start and nothing else measures it.
+    torrent.on("wire", () => {
+      const timing = this.#swarmTimingByTorrent.get(torrent);
+      if (!timing || timing.firstPeerAt !== null) {
+        return;
+      }
+      timing.firstPeerAt = Date.now();
+      const waited = secondsToFirstPeer(timing.addedAt, timing.firstPeerAt);
+      const byTracker = this.#lastAnnounceByTorrent.get(torrent);
+      const offered = bestAnnounce(byTracker ? byTracker.values() : []);
+      logger.info(
+        `torrent-pool: [${label()}] first peer connected after ${waited === null ? "?" : waited.toFixed(1)}s` +
+          (offered.trackers > 0
+            ? ` (${offered.trackers} tracker(s) had answered, best seeders=${offered.seeders ?? "?"} ` +
+              `leechers=${offered.leechers ?? "?"})`
+            : " (no tracker answer had arrived)")
+      );
+    });
 
     torrent.on("warning", (warning) => {
-      logger.warn(`torrent-pool: [${label}] warning: ${formatWarning(warning)}`);
+      logger.warn(`torrent-pool: [${label()}] warning: ${formatWarning(warning)}`);
     });
 
+    // Everything below needs the torrent to have been PARSED, and `add` returns
+    // before that: `announce`, `files` and `private` are all still empty, and
+    // `discovery` — which owns the tracker client — is not created until
+    // `_startDiscovery`, which runs immediately before `ready` is emitted.
+    // Attaching the tracker listener at add-time therefore attaches it to
+    // nothing at all, and every announce answer is lost. The two listeners
+    // above stay where they are, because `wire` and `warning` live on the
+    // torrent from construction and both fire before `ready`: the peer that
+    // DELIVERS a magnet's metadata connects first, and `wire` is emitted on
+    // connection and never replayed.
+    const describeOnce = () => {
+      const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
+      logger.info(
+        `torrent-pool: [${label()}] added: files=${torrent.files?.length ?? 0} ` +
+          `private=${torrent.private ? "yes" : "no"} trackers=${trackerCount}`
+      );
+      this.#attachTrackerDiagnostics(torrent, label);
+    };
+    if (torrent.ready === true) {
+      describeOnce();
+    } else {
+      torrent.once("ready", describeOnce);
+    }
+  }
+
+  /**
+   * Watch what the trackers answer.
+   *
+   * Separated from the rest because it can only be done once the torrent has
+   * been parsed — see the reasoning at the call site.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {() => string} label
+   * @returns {void}
+   */
+  #attachTrackerDiagnostics(torrent, label) {
     // bittorrent-tracker's Client emits "update" with each announce response.
     // `complete`/`incomplete` are the tracker's seeder/leecher counts — the
     // authoritative answer to "does the tracker accept us and does the swarm
@@ -1112,13 +1307,25 @@ export class TorrentPool {
         // strip the query string before logging.
         const announceUrl =
           typeof data?.announce === "string" ? data.announce.replace(/\?.*$/, "") : "?";
+        const seeders = typeof data?.complete === "number" ? data.complete : null;
+        const leechers = typeof data?.incomplete === "number" ? data.incomplete : null;
+        // Kept, not only printed: what the tracker says the swarm holds is one
+        // half of every later question about why nothing is arriving, and a
+        // number that exists only in a log line cannot be put beside the other
+        // half two minutes later.
+        let byTracker = this.#lastAnnounceByTorrent.get(torrent);
+        if (!byTracker) {
+          byTracker = new Map();
+          this.#lastAnnounceByTorrent.set(torrent, byTracker);
+        }
+        byTracker.set(announceUrl, { seeders, leechers, at: Date.now() });
         logger.info(
-          `torrent-pool: [${label}] announce ${announceUrl}: ` +
-            `seeders=${data?.complete ?? "?"} leechers=${data?.incomplete ?? "?"}`
+          `torrent-pool: [${label()}] announce ${announceUrl}: ` +
+            `seeders=${seeders ?? "?"} leechers=${leechers ?? "?"}`
         );
       });
     } else {
-      logger.info(`torrent-pool: [${label}] tracker client not exposed; announce results not logged`);
+      logger.info(`torrent-pool: [${label()}] tracker client not exposed; announce results not logged`);
     }
   }
 
@@ -1219,17 +1426,18 @@ export class TorrentPool {
               this.#lastAccess.delete(existing);
               this.#readPositionByTorrent.delete(existing);
               this.client.remove(existing, { destroyStore: true }, () => {
-                this.client.add(torrentId, {
+                const addedReplacement = this.client.add(torrentId, {
                   store: SharedPieceStore,
                   storeCacheSlots: 0,
                   storeOpts: { memoryBytes: this.#memoryBytes }
                 }, (replacement) => {
                   this.torrents.set(key, replacement);
                   this.#lastAccess.set(replacement, Date.now());
-                  this.#attachSwarmDiagnostics(dupMatch[1].slice(0, 8), replacement);
                   this.#pending.delete(key);
+                  this.#attachSwarmDiagnostics(replacement);
                   resolve(replacement);
                 });
+                this.#attachSwarmDiagnostics(addedReplacement);
               });
               return;
             }
@@ -1250,7 +1458,7 @@ export class TorrentPool {
       // piece across threads detached memory still in use. Ours owns what it
       // hands out, holds pieces in shared memory the main thread can read
       // directly, and spills to disk instead of losing them.
-      this.client.add(torrentId, {
+      const added = this.client.add(torrentId, {
         store: SharedPieceStore,
         storeCacheSlots: 0,
         storeOpts: { memoryBytes: this.#memoryBytes }
@@ -1259,11 +1467,23 @@ export class TorrentPool {
         this.torrents.set(key, readyTorrent);
         this.#lastAccess.set(readyTorrent, Date.now());
         this.#pending.delete(key);
-        // Key layout is `${sourceType}:${sha1}`; log with the sha1 prefix so
-        // lines correlate with the [stats] source key.
-        this.#attachSwarmDiagnostics(key.split(":")[1]?.slice(0, 8) ?? key, readyTorrent);
+        // The torrent this call ends up with is not always the one it added:
+        // on a duplicate infohash WebTorrent destroys the new one and hands
+        // back the one it already had. Watching only what `add` returned would
+        // 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);
         resolve(readyTorrent);
       });
+      // Attached to what `add` returns, NOT inside its callback. That callback
+      // is `torrent.once("ready")`, and for a magnet everything this watches
+      // has already happened by then: peer discovery starts before the metadata
+      // arrives, so the tracker's answers land before any listener exists, and
+      // the peer that DELIVERED the metadata connected before `ready` fired —
+      // `wire` is emitted at the moment of connection and never replayed. The
+      // torrent that waited minutes for its first peer would have been the one
+      // case this could not measure.
+      this.#attachSwarmDiagnostics(added);
     });
 
     this.#pending.set(key, promise);
@@ -1439,7 +1659,15 @@ export class TorrentPool {
    *   uploadSpeed: number,
    *   fileProgress: number | null,
    *   fileDownloaded: number | null,
-   *   fileLength: number | null
+   *   fileLength: number | null,
+   *   connectedPeers: number,
+   *   knownPeers: number | null,
+   *   queuedPeers: number | null,
+   *   trackerSeeders: number | null,
+   *   trackerLeechers: number | null,
+   *   trackersAnswered: number,
+   *   secondsToFirstPeer: number | null,
+   *   secondsWaitingForFirstPeer: number | null
    * }}
    */
   getFileStats(torrent, fileIndex = null, options = {}) {
@@ -1447,7 +1675,34 @@ export class TorrentPool {
     const downloadSpeed = typeof torrent?.downloadSpeed === "number" ? torrent.downloadSpeed : 0;
     const uploadSpeed = typeof torrent?.uploadSpeed === "number" ? torrent.uploadSpeed : 0;
 
-    const base = { numPeers, downloadSpeed, uploadSpeed };
+    // Everything the caller needs to tell "nobody was offered" from "several
+    // were offered and we connected to none". All of it is read HERE, on the
+    // thread that owns the torrent: the handle the routes hold is a proxy
+    // across a worker boundary, where `torrent.wires` simply does not exist —
+    // which is why the line that tried to print it printed a question mark in
+    // every line it has ever written.
+    const reach = describeSwarmReach(torrent);
+    const byTracker = this.#lastAnnounceByTorrent.get(torrent);
+    const announce = bestAnnounce(byTracker ? byTracker.values() : []);
+    const timing = this.#swarmTimingByTorrent.get(torrent) ?? null;
+
+    const base = {
+      numPeers,
+      downloadSpeed,
+      uploadSpeed,
+      connectedPeers: reach.connectedPeers,
+      knownPeers: reach.knownPeers,
+      queuedPeers: reach.queuedPeers,
+      trackerSeeders: announce.seeders,
+      trackerLeechers: announce.leechers,
+      trackersAnswered: announce.trackers,
+      secondsToFirstPeer: timing ? secondsToFirstPeer(timing.addedAt, timing.firstPeerAt) : null,
+      // How long this torrent has been waiting, when it is still waiting. The
+      // figure above answers "how long did it take"; this one answers "how long
+      // has it been", which is the question during the wait itself.
+      secondsWaitingForFirstPeer:
+        timing && timing.firstPeerAt === null ? secondsToFirstPeer(timing.addedAt, Date.now()) : null
+    };
 
     if (fileIndex === null || !Number.isInteger(fileIndex) || !Array.isArray(torrent?.files)) {
       return { ...base, fileProgress: null, fileDownloaded: null, fileLength: null };

package/test/swarm-reach.test.js

@@ -0,0 +1,125 @@
+/**
+ * @file The line describing a swarm answers the question it is asked.
+ *
+ * It could not. `routes/api/sources/stats/get.js` printed `peers=N` beside
+ * `wires=?`, which reads as two quantities of which one is unknown — while
+ * WebTorrent's `numPeers` IS `wires.length` (`lib/torrent.js:254`, the same in
+ * 2.8.5 and 3.0.21), so the first was the connection count and the second was a
+ * field that has never printed anything, because the torrent lives on a worker
+ * thread where that property does not exist.
+ *
+ * What was missing is the other half: how many peers the client HOLDS but is
+ * not connected to, and what the tracker said the swarm has. Measured
+ * 2026-08-21 on `JUFD665.mp4`, the tracker answered `seeders=5` at 13:40:30 and
+ * the first wire arrived at 13:44:47 — 4 min 17 s in which the stats line
+ * repeated unchanged every two seconds while the answer ("offered, not
+ * connected") was already in the process.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { bestAnnounce, describeSwarmReach, secondsToFirstPeer } from "../services/torrent-pool.js";
+
+test("connected and known are separate numbers", () => {
+  const torrent = { wires: [{}, {}], _peersLength: 7, _numQueued: 4 };
+  assert.deepEqual(describeSwarmReach(torrent), {
+    connectedPeers: 2,
+    knownPeers: 7,
+    queuedPeers: 4
+  });
+});
+
+test("offered but not connected is distinguishable from nobody offered", () => {
+  // The two shapes the field produced. They need opposite investigations, and
+  // one line has to tell them apart.
+  const offeredNotConnected = describeSwarmReach({ wires: [], _peersLength: 5, _numQueued: 5 });
+  const nobodyOffered = describeSwarmReach({ wires: [], _peersLength: 0, _numQueued: 0 });
+  assert.equal(offeredNotConnected.connectedPeers, 0);
+  assert.equal(nobodyOffered.connectedPeers, 0);
+  assert.notEqual(offeredNotConnected.knownPeers, nobodyOffered.knownPeers);
+});
+
+test("internals that are gone say nothing rather than breaking the poll", () => {
+  // `_peersLength` and `_numQueued` are not WebTorrent's published interface.
+  // The browser polls this every two seconds, so a version that drops them must
+  // cost the field and not the answer.
+  assert.deepEqual(describeSwarmReach({ wires: [{}] }), {
+    connectedPeers: 1,
+    knownPeers: null,
+    queuedPeers: null
+  });
+  assert.deepEqual(describeSwarmReach({}), {
+    connectedPeers: 0,
+    knownPeers: null,
+    queuedPeers: null
+  });
+  assert.deepEqual(describeSwarmReach(null), {
+    connectedPeers: 0,
+    knownPeers: null,
+    queuedPeers: null
+  });
+  const throwing = {
+    wires: [],
+    get _peersLength() {
+      throw new Error("destroyed");
+    }
+  };
+  assert.deepEqual(describeSwarmReach(throwing), {
+    connectedPeers: 0,
+    knownPeers: null,
+    queuedPeers: null
+  });
+});
+
+test("the wait for a first peer is a measured quantity", () => {
+  // The field case: added 13:40:30.357, first wire 13:44:47.123.
+  assert.equal(secondsToFirstPeer(1000, 258_766), 257.766);
+  assert.equal(secondsToFirstPeer(1000, 1000), 0);
+});
+
+test("no peer yet is not a duration", () => {
+  assert.equal(secondsToFirstPeer(1000, null), null);
+  assert.equal(secondsToFirstPeer(null, 2000), null);
+  // A clock that went backwards is not a negative wait; it is no reading.
+  assert.equal(secondsToFirstPeer(2000, 1000), null);
+});
+
+test("the best tracker answer wins, not the most recent", () => {
+  // A live tracker says 500, a dead one answers 0 two seconds later. Keeping
+  // the last would print "nobody offered" about a swarm of five hundred, which
+  // inverts the one distinction this figure is carried for.
+  const answers = [
+    { seeders: 500, leechers: 40 },
+    { seeders: 0, leechers: 0 }
+  ];
+  assert.deepEqual(bestAnnounce(answers), { seeders: 500, leechers: 40, trackers: 2 });
+});
+
+test("trackers that answered are counted even when none knew anything", () => {
+  assert.deepEqual(bestAnnounce([{ seeders: null, leechers: null }]), {
+    seeders: null,
+    leechers: null,
+    trackers: 1
+  });
+  // No tracker has answered at all — a different state from "answered, knows
+  // nobody", and the line says so.
+  assert.deepEqual(bestAnnounce([]), { seeders: null, leechers: null, trackers: 0 });
+  assert.deepEqual(bestAnnounce(null), { seeders: null, leechers: null, trackers: 0 });
+});
+
+test("leechers travel with the seeder count they were reported beside", () => {
+  const answers = [
+    { seeders: 2, leechers: 99 },
+    { seeders: 7, leechers: 3 }
+  ];
+  assert.equal(bestAnnounce(answers).leechers, 3);
+  // Including when the winning answer gave no leecher count: carrying the
+  // previous tracker's figure forward would present two trackers' numbers as
+  // one reading.
+  assert.deepEqual(bestAnnounce([{ seeders: 2, leechers: 99 }, { seeders: 7, leechers: null }]), {
+    seeders: 7,
+    leechers: null,
+    trackers: 2
+  });
+});

package/test/viewer-position-on-open.test.js

@@ -0,0 +1,53 @@
+/**
+ * @file Opening a file at a position puts the SOUND there too.
+ *
+ * The audio rendition is a session of its own, and where it starts is computed
+ * from where the viewer is. That reading had three sources and only two were
+ * consulted — a position seeked to, and the last segment this session served —
+ * both of which are written by things that have not happened yet at the moment
+ * a file is opened at a position. So the answer was zero.
+ *
+ * Field 2026-08-21, `Minions.and.Monsters.1080p.mkv` reopened from the address
+ * bar at 52:07:
+ *
+ *   18:02:55.124  8ed85605  start=3130s  -ss 3125.25  -an -map 0:v:0 -c:v copy
+ *   18:02:55.632  33b0b046  start=0s     no -ss       -vn -map 0:a:0 -c:a aac
+ *
+ * The picture went to segment #781, the sound to #0. The player asked both for
+ * #782; the picture had it, the sound re-encoded 57.5 s of a 3130 s film in the
+ * 45 s the request lasted and then answered 404 — shown to the viewer as "the
+ * proxy accepted the request but sent no video".
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveViewerPosition } from "../services/hls-session-manager.js";
+
+test("a file opened at a position has its viewer at that position", () => {
+  // Nothing has been seeked and nothing served yet — the state at the instant
+  // the audio rendition is created.
+  assert.equal(resolveViewerPosition({ openedAt: 3130 }), 3130);
+});
+
+test("a seek beats everything else", () => {
+  assert.equal(
+    resolveViewerPosition({ seeked: 900, lastRequestedStart: 400, openedAt: 3130 }),
+    900
+  );
+});
+
+test("what has been served beats where the file was opened", () => {
+  // The opening position is the oldest of the three readings: once a segment
+  // has been served, that is where the reading is.
+  assert.equal(resolveViewerPosition({ lastRequestedStart: 400, openedAt: 3130 }), 400);
+});
+
+test("with nothing to go on the answer is the beginning", () => {
+  assert.equal(resolveViewerPosition({}), 0);
+  assert.equal(resolveViewerPosition({ seeked: 0, lastRequestedStart: 0, openedAt: 0 }), 0);
+  // Values that are not readings must not become one.
+  assert.equal(resolveViewerPosition({ seeked: Number.NaN, openedAt: Number.NaN }), 0);
+  assert.equal(resolveViewerPosition({ seeked: -5, openedAt: -5 }), 0);
+  assert.equal(resolveViewerPosition({ lastRequestedStart: null, openedAt: undefined }), 0);
+});