@torrent-tv/proxy 2.98.13 → 2.98.15

package/package.json

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

package/services/media/ContainerOrchestrator.js

@@ -136,10 +136,15 @@ export class ContainerOrchestrator {
     let lifetime = this.#lifetimes.get(key);
     if (!lifetime) this.#lifetimes.set(key, lifetime = {});
     const isCurrent = () => this.#lifetimes.get(key) === lifetime && params.isCurrent?.() !== false;
-    const previous = this.#reads.get(key) ?? Promise.resolve();
     // Reads of one file run one after another, so an answer can wait for every
     // read asked before it. Told to whoever asked, apart from the read itself,
     // because the two call for different remedies (torrent-tv/meta#166).
+    // A statement answered from what was already read reads and parses
+    // nothing, so it is answered beside the queue and holds nobody up: the
+    // picture's first input of an AVI waited about 4 s behind the sound's
+    // table of the whole film it does not use (r38, torrent-tv/meta#178).
+    const aside = this.#answersWithoutReading(key, statement);
+    const previous = aside ? Promise.resolve() : this.#reads.get(key) ?? Promise.resolve();
     const askedAt = Date.now();
     const reading = previous.catch(() => undefined).then(async () => {
       if (!isCurrent()) return { result: { kind: "terminal", reason: "request-obsolete", requestId: params.requestId } };
@@ -149,7 +154,7 @@ export class ContainerOrchestrator {
       params.onTimed?.(statement, startedAt - askedAt, Date.now() - startedAt);
       return { result, revision };
     });
-    this.#reads.set(key, reading);
+    if (!aside) this.#reads.set(key, reading);
     try {
       const { result, revision } = await reading;
       if (!isCurrent()) return { kind: "terminal", reason: "request-obsolete", requestId: params.requestId };
@@ -162,6 +167,12 @@ export class ContainerOrchestrator {
     }
   }
 
+  /** Whether a statement of this file is answered from what was already read: its track table kept here, or the container's word. */
+  #answersWithoutReading(key, statement) {
+    if (statement === "tracks" && this.tracks.has(key)) return true;
+    return this.cache.get(key)?.answersWithoutReading?.(statement) === true;
+  }
+
   async #inspectRead(params, statement) {
     const requestId = params.requestId ?? `${params.sourceKey}:${params.fileIndex}:${statement}`;
     this.#activityEpoch++;

package/services/media/container/AviContainer.js

@@ -42,6 +42,8 @@ export class AviContainer extends Container {
   #workTags = null;
   /** The index alone: undefined until read, null when the file states none. */
   #index = undefined;
+  /** The index while it is being read, so two asks read it once. */
+  #indexReading = null;
   #layout = null;
   /** The first RIFF's `idx1`: undefined until looked for, null when there is none. */
   #idx1Chunk = undefined;
@@ -167,6 +169,38 @@ export class AviContainer extends Container {
    */
   async #readIndex() {
     if (this.#index !== undefined) return this.#index;
+    // One reading for every asker: a read of the picture's ranges may now be
+    // answered beside the sound's table (`answersWithoutReading`), and two
+    // asks at once would each read the index and each hold its memory.
+    this.#indexReading ??= this.#readIndexOnce().finally(() => { this.#indexReading = null; });
+    return this.#indexReading;
+  }
+
+  /**
+   * Whether `statement` is answered from what this container has already
+   * read, without reading or parsing anything more — so it may be answered
+   * beside a read of the same file still in progress
+   * (`ContainerOrchestrator.inspect`). Field r38 (Home Assistant, 2026-10-14):
+   * the picture's first input waited about 4 s behind the sound's packet table
+   * of the whole film, which it does not use — its ranges are named from the
+   * index alone (`readSourceRanges`), while the table is the sound's
+   * (`readPacketIndex`), built in portions that give the thread back
+   * (torrent-tv/meta#178).
+   *
+   * Once the index has been read, so have the tracks and the place of `movi`
+   * it was read with, and the picture's statements read nothing else.
+   *
+   * @param {string} statement
+   * @returns {boolean}
+   */
+  answersWithoutReading(statement) {
+    if (statement === "media-info") return Boolean(this.mediaInfo);
+    if (statement === "source-navigation" || statement === "source-ranges") return this.#index !== undefined;
+    return false;
+  }
+
+  /** The index, read from the file; see `#readIndex`. */
+  async #readIndexOnce() {
     const tracks = await this.readTracks();
     const { streams } = await this.#readHeaders();
     const { movi } = await this.#topLevel();

package/services/torrent/download/SwarmSelection.js

@@ -46,6 +46,8 @@ export class SwarmSelection {
   #stated = new Map();
   /** Claimants whose windows are currently protected in memory. */
   #protectedInMemory = new Set();
+  /** The pieces of the urgent first class, as last stated: what somebody waits for now. */
+  #required = [];
   #findStore;
 
   /**
@@ -110,7 +112,10 @@ export class SwarmSelection {
         else union.push({ from: range.from, to: range.to, priority });
       }
       for (const range of union) wanted.set(`${range.from}-${range.to}-${priority}`, range);
-      if (priority === 1) this.firstClassPieces = union.map(range => range.from === range.to ? `${range.from}` : `${range.from}-${range.to}`);
+      if (priority === 1) {
+        this.firstClassPieces = union.map(range => range.from === range.to ? `${range.from}` : `${range.from}-${range.to}`);
+        this.#required = strictFirstClass ? union.map(({ from, to }) => ({ from, to })) : [];
+      }
     }
     this.firstClass = first;
 
@@ -150,8 +155,21 @@ export class SwarmSelection {
     return { stated, withdrawn };
   }
 
+  /**
+   * The pieces of the urgent first class as last stated, or none while the
+   * first class is conditional: what somebody is waiting for now, and the
+   * only pieces whose last blocks are worth asking of a second peer
+   * (`TailRepeat`).
+   *
+   * @returns {Array<{ from: number, to: number }>}
+   */
+  requiredPieces() {
+    return this.#required;
+  }
+
   /** Take everything back. The torrent is going, or nobody wants anything. */
   releaseAll() {
+    this.#required = [];
     for (const range of this.#stated.values()) {
       this.#deselect(range);
     }

package/services/torrent/piece-timing.js

@@ -0,0 +1,120 @@
+/**
+ * @file When each piece was asked of the swarm, and how long its blocks were
+ * in flight (torrent-tv/meta#178).
+ *
+ * The order in which pieces were verified cannot say why one came last: it
+ * may have been asked for late, or asked for early with its last blocks held
+ * by slow peers, and the two need different fixes. Field 2026-10-14: the
+ * first input of a 1080p MKV waited 18.7 s for pieces 1 and 2, verified after
+ * pieces 3-33. WebTorrent states no outgoing request, so the torrent pool
+ * tells this record each block it asks and each block that arrives; the
+ * record answers once, when the piece is verified, and then forgets it.
+ */
+
+/**
+ * @typedef {object} PieceTiming
+ * @property {number} askedAgoMs - From the first block asked to the verification.
+ * @property {number} asks - Blocks asked, duplicates included.
+ * @property {number} peers - Distinct peers asked.
+ * @property {number} slowestMs - The longest a block was in flight, from its first ask to its arrival.
+ * @property {string | null} slowestPeer - Who sent that block.
+ * @property {number} lastInFlightMs - How long the block that completed the piece was in flight.
+ * @property {string | null} lastPeer - Who sent it.
+ * @property {number} askedAgain - Asks of a block already asked of another peer.
+ * @property {number} arrivedTwice - Blocks that arrived after a copy of them had, and were dropped.
+ */
+
+export class PieceTimings {
+  /** @type {Map<number, { firstAskAt: number, asks: number, peers: Set<string>, blocks: Map<number, number>, arrived: Set<number>, askedAgain: number, arrivedTwice: number, slowestMs: number, slowestPeer: string | null, lastInFlightMs: number, lastPeer: string | null }>} */
+  #pieces = new Map();
+
+  /**
+   * A block of `piece` at `offset` was asked of `peer`.
+   *
+   * @param {number} piece
+   * @param {number} offset
+   * @param {string} peer
+   * @param {number} now
+   */
+  asked(piece, offset, peer, now) {
+    let record = this.#pieces.get(piece);
+    if (!record) {
+      record = { firstAskAt: now, asks: 0, peers: new Set(), blocks: new Map(), arrived: new Set(), askedAgain: 0, arrivedTwice: 0,
+        slowestMs: 0, slowestPeer: null, lastInFlightMs: 0, lastPeer: null };
+      this.#pieces.set(piece, record);
+    }
+    record.asks += 1;
+    record.peers.add(peer);
+    if (!record.blocks.has(offset)) record.blocks.set(offset, now);
+    else record.askedAgain += 1;
+  }
+
+  /**
+   * A block of `piece` at `offset` arrived from `peer`. A block never asked
+   * through this record — it is not one of ours — says nothing.
+   *
+   * @param {number} piece
+   * @param {number} offset
+   * @param {string} peer
+   * @param {number} now
+   */
+  arrived(piece, offset, peer, now) {
+    const record = this.#pieces.get(piece);
+    const askedAt = record?.blocks.get(offset);
+    if (askedAt === undefined) return;
+    // A copy of a block that had already arrived is dropped by the piece; its
+    // bytes are what asking a second peer cost.
+    if (record.arrived.has(offset)) {
+      record.arrivedTwice += 1;
+      return;
+    }
+    record.arrived.add(offset);
+    const inFlightMs = now - askedAt;
+    if (inFlightMs >= record.slowestMs) {
+      record.slowestMs = inFlightMs;
+      record.slowestPeer = peer;
+    }
+    record.lastInFlightMs = inFlightMs;
+    record.lastPeer = peer;
+  }
+
+  /**
+   * The timing of `piece`, verified at `now`, or null when no block of it was
+   * asked through this record; forgotten either way.
+   *
+   * @param {number} piece
+   * @param {number} now
+   * @returns {PieceTiming | null}
+   */
+  verified(piece, now) {
+    const record = this.#pieces.get(piece);
+    this.#pieces.delete(piece);
+    if (!record) return null;
+    return {
+      askedAgoMs: now - record.firstAskAt,
+      asks: record.asks,
+      peers: record.peers.size,
+      slowestMs: record.slowestMs,
+      slowestPeer: record.slowestPeer,
+      lastInFlightMs: record.lastInFlightMs,
+      lastPeer: record.lastPeer,
+      askedAgain: record.askedAgain,
+      arrivedTwice: record.arrivedTwice
+    };
+  }
+}
+
+/**
+ * The timing said after a verified piece.
+ *
+ * @param {PieceTiming | null} timing
+ * @returns {string}
+ */
+export function describePieceTiming(timing) {
+  if (!timing) return "";
+  return `; first block asked ${(timing.askedAgoMs / 1000).toFixed(1)}s before, ${timing.asks} block ask(s) to ${timing.peers} peer(s), ` +
+    `slowest block ${(timing.slowestMs / 1000).toFixed(1)}s in flight from ${timing.slowestPeer ?? "?"}, ` +
+    `the last one ${(timing.lastInFlightMs / 1000).toFixed(1)}s from ${timing.lastPeer ?? "?"}` +
+    (timing.askedAgain > 0 || timing.arrivedTwice > 0
+      ? `, ${timing.askedAgain} block(s) asked again, ${timing.arrivedTwice} arrived twice` : "");
+}

package/services/torrent/torrent-pool.js

@@ -24,6 +24,23 @@ import { withdrawClaim } from "./download/withdraw-claim.js";
 import { deadlineOfMapZone, levelOfMapZone, priorityOfMapZone } from "./map-zones.js";
 import { deriveSourceKey } from "../../utils/torrent-source-key.js";
 import { noteTorrentDestroyed } from "./destroyed-torrents.js";
+import { PieceTimings, describePieceTiming } from "./piece-timing.js";
+import { TailRepeat } from "./worker/tail-repeat.js";
+
+/**
+ * The second-peer requests for the last blocks of a piece somebody waits for,
+ * one per torrent, made when the torrent is first watched and stopped when it
+ * is forgotten (`worker/tail-repeat.js`).
+ *
+ * @type {WeakMap<object, TailRepeat>}
+ */
+const tailRepeats = new WeakMap();
+
+/** Stop asking second peers for a torrent that is going. */
+function dropTailRepeat(torrent) {
+  tailRepeats.get(torrent)?.dispose();
+  tailRepeats.delete(torrent);
+}
 
 /** How a window stated from the priority map names itself. */
 const MAP_CLAIMANT = "priority-map";
@@ -1352,6 +1369,8 @@ export class TorrentPool {
     // swarm went on fetching the old first class for 1.16 s, until the next
     // piece happened to be verified (r34, torrent-tv/meta#178).
     reconcileAll();
+    // And a new map may make other pieces the ones somebody waits for.
+    tailRepeats.get(torrent)?.poke();
     // 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
@@ -1502,21 +1521,37 @@ export class TorrentPool {
     const addedAt = Date.now();
     this.#swarmTimingByTorrent.set(torrent, { addedAt, firstPeerAt: null });
 
-    torrent.on("download-requested", ({ piece, deadlineAt, requestId, peer, queued }) => {
-      logger.info(`download request=${requestId} piece=${piece} deadline=${deadlineAt} peer=${peer} outstanding=${queued}`);
-    });
     torrent.on("download-request-cancelled", ({ piece, offset, length, reason, requestId }) => {
       logger.info(`download request=${requestId ?? `${torrent.infoHash ?? "unknown"}:${piece}:${offset}`} cancel bytes=${length} reason=${reason}`);
     });
     torrent.on("download-request-cancel-failed", ({ piece, offset, length, error }) => {
       logger.warn(`download request=${torrent.infoHash ?? "unknown"}:${piece}:${offset} cancel bytes=${length} failed: ${error}`);
     });
-    // WHEN each piece arrived. The requests above say what was asked for; this
-    // says what came and in which order, which is what decides how far an
-    // encoder reading the file can go before it meets a piece still missing
-    // (torrent-tv/meta#151). One short line per piece: a 2.3 GB film is 563.
+    // WHEN each piece arrived, which decides how far an encoder reading the
+    // file can go before it meets a piece still missing (torrent-tv/meta#151),
+    // and WHY it came when it did: when its first block was asked and how long
+    // its blocks were in flight, and from whom (`piece-timing.js`). One line
+    // per piece: a 2.3 GB film is 563.
+    const timings = new PieceTimings();
+    tailRepeats.set(torrent, new TailRepeat({ torrent, requiredPieces: () => demandFor(torrent).selection.requiredPieces(),
+      log: (line) => logger.info(`download ${label()} ${line}`) }));
+    torrent.on("wire", (wire) => {
+      // WebTorrent asks a wire for a block by calling `request` and states
+      // nothing; a request the wire refuses (choked, closed) is not queued and
+      // not counted.
+      if (typeof wire?.request !== "function") return;
+      const peer = String(wire.remoteAddress ?? "?");
+      const request = wire.request;
+      wire.request = function (index, offset, length, callback) {
+        const queued = this.requests.length;
+        const answer = request.call(this, index, offset, length, callback);
+        if (this.requests.length > queued) timings.asked(index, offset, peer, Date.now());
+        return answer;
+      };
+      wire.on("piece", (index, offset) => timings.arrived(index, offset, peer, Date.now()));
+    });
     torrent.on("verified", (piece) => {
-      logger.info(`download ${label()} verified piece=${piece}`);
+      logger.info(`download ${label()} verified piece=${piece}${describePieceTiming(timings.verified(piece, Date.now()))}`);
     });
 
     // The first connected peer, said once, because the wait for it can BE the
@@ -1948,6 +1983,7 @@ export class TorrentPool {
       return;
     }
     forgetTorrent(torrent);
+    dropTailRepeat(torrent);
     this.#forgetBookkeeping(torrent);
     const name = typeof torrent.name === "string" ? torrent.name : "(unknown)";
     logger.warn(
@@ -1993,6 +2029,7 @@ export class TorrentPool {
   #removeTorrent(torrent, reason = "unknown") {
     // Everything anybody stated for this torrent goes with it.
     forgetTorrent(torrent);
+    dropTailRepeat(torrent);
     if (!torrent) {
       return;
     }

package/services/torrent/worker/fastest-wires.js

@@ -37,6 +37,9 @@
  */
 const SHORT_TAIL_BLOCKS = 16;
 
+/** A block of a piece, as `torrent-piece` cuts it (`Piece.BLOCK_LENGTH`): a request's offset over this is its block. */
+const BLOCK_BYTES = 1 << 14;
+
 /**
  * The library's own request entry. Internal, so its absence must be noticed
  * rather than swallowed: without it this lever silently does nothing.
@@ -248,10 +251,10 @@ export function describePieceTail(torrent, pieceIndex) {
  * work, which no average speed can show.
  *
  * The cost is bounded by the same measurement: the tails were 2 to 14 blocks of
- * 512, so 32 to 224 KB against the 8 MiB piece they hold up. At most one
- * duplicate is asked per candidate wire per call, and the caller repeats every
- * half second, so a longer tail is covered across attempts rather than in one
- * burst.
+ * 512, so 32 to 224 KB against the 8 MiB piece they hold up. A block already in
+ * flight on `maxCopies` wires is not asked again, however often this is called:
+ * it is called on every block that arrives (`TailRepeat`), and without that
+ * check each call asked one more copy of the same block.
  *
  * Safe against the completion path: a block that arrives twice is dropped by
  * `Piece.set`, which writes only into an empty slot, and a piece already
@@ -260,17 +263,26 @@ export function describePieceTail(torrent, pieceIndex) {
  *
  * @param {object} torrent
  * @param {number} pieceIndex
- * @returns {{ duplicated: number, missing: number, wires: number }}
+ * @param {object} [options]
+ * @param {number} [options.maxCopies] - How many wires a missing block may be
+ *   in flight on at once: the first request and one copy beside it.
+ * @returns {{ duplicated: number, missing: number, wires: number, unplaced: number }}
  *   `duplicated` counts requests the library actually placed for a block that
- *   was already outstanding elsewhere.
+ *   was already outstanding elsewhere; `unplaced` the blocks in flight on one
+ *   wire alone that no other wire could be asked for now.
  */
-export function duplicateTailFor(torrent, pieceIndex) {
+export function duplicateTailFor(torrent, pieceIndex, { maxCopies = 2 } = {}) {
   const piece = torrent?.pieces?.[pieceIndex];
   const buffer = Array.isArray(piece?._buffer) ? piece._buffer : null;
-  if (!piece || !buffer || typeof piece.cancel !== "function") {
-    return { duplicated: 0, missing: 0, wires: 0 };
+  if (!piece || !buffer || typeof piece.cancel !== "function" || !canPlaceRequests(torrent)) {
+    return { duplicated: 0, missing: 0, wires: 0, unplaced: 0 };
   }
   const chunks = Number.isFinite(piece._chunks) ? piece._chunks : buffer.length;
+  // Most calls are for a piece still arriving in bulk; its own count says so
+  // without walking its blocks or every wire's queue.
+  if (Number.isFinite(piece._buffered) && chunks - piece._buffered > SHORT_TAIL_BLOCKS) {
+    return { duplicated: 0, missing: chunks - piece._buffered, wires: 0, unplaced: 0 };
+  }
   const missing = [];
   for (let index = 0; index < chunks; index += 1) {
     if (!buffer[index]) {
@@ -279,7 +291,7 @@ export function duplicateTailFor(torrent, pieceIndex) {
   }
   const candidates = wiresForPiece(torrent, pieceIndex);
   if (missing.length === 0 || candidates.length === 0) {
-    return { duplicated: 0, missing: missing.length, wires: candidates.length };
+    return { duplicated: 0, missing: missing.length, wires: candidates.length, unplaced: 0 };
   }
 
   // A tail this short is what a blocked read is actually waiting on, and a
@@ -288,31 +300,50 @@ export function duplicateTailFor(torrent, pieceIndex) {
   // bytes that are already coming — measured 2026-08-19, the tails a reader
   // waits on are 2 to 14 blocks of 512.
   if (missing.length > SHORT_TAIL_BLOCKS) {
-    return { duplicated: 0, missing: missing.length, wires: candidates.length };
+    return { duplicated: 0, missing: missing.length, wires: candidates.length, unplaced: 0 };
+  }
+
+  // Which wires each missing block is in flight on, read from the wires' own
+  // queues: the library keeps a block's reservation for one wire only, and a
+  // copy asked here is visible nowhere else.
+  const holders = new Map(missing.map(block => [block, new Set()]));
+  for (const wire of Array.isArray(torrent.wires) ? torrent.wires : []) {
+    for (const request of Array.isArray(wire?.requests) ? wire.requests : []) {
+      if (request?.piece !== pieceIndex) continue;
+      holders.get(Math.floor(request.offset / BLOCK_BYTES))?.add(wire);
+    }
   }
 
-  let duplicated = 0;
-  // One block per wire: that is what the pipelines can usefully take at once,
-  // and it needs no number of its own.
-  for (let index = 0; index < Math.min(missing.length, candidates.length); index += 1) {
-    // Freeing the reservation is what makes the block askable again; the
-    // request already in flight is deliberately left alone, because the point
-    // is to have two of them.
-    piece.cancel(missing[index]);
-    // `false` is hotswap: the library's own swap must not run on top of this,
-    // or it would free a THIRD wire's block as well.
-    if (torrent._request(candidates[index], pieceIndex, false) === true) {
-      duplicated += 1;
+  let duplicated = 0, unplaced = 0;
+  for (const block of missing) {
+    const held = holders.get(block);
+    // Not in flight anywhere: the library's own picker asks for it; a block
+    // nobody has been asked for is not a tail held by a slow peer.
+    if (held.size === 0 || held.size >= maxCopies) continue;
+    let placed = false;
+    for (const wire of candidates) {
+      if (held.has(wire)) continue;
+      // Freeing the reservation is what makes the block askable again; the
+      // request already in flight is deliberately left alone, because the
+      // point is to have two of them.
+      piece.cancel(block);
+      // `false` is hotswap: the library's own swap must not run on top of
+      // this, or it would free a THIRD wire's block as well.
+      if (torrent._request(wire, pieceIndex, false) === true) {
+        held.add(wire);
+        duplicated += 1;
+        placed = true;
+        break;
+      }
+      // Refused before anything was reserved (that wire's pipeline is full):
+      // the freed block is taken back, or the library would hand it to the
+      // next wire that asks, a copy nobody counted. The next wire's pipeline
+      // is its own, so it is still asked.
+      piece.reserve();
     }
-    // A refusal means THAT wire's pipeline is full, and says nothing about the
-    // next one's — pipelines are per wire. This used to stop the whole pass on
-    // the first refusal, on the stated reasoning that the remaining wires were
-    // "no emptier", which is an assumption about other peers' queues that
-    // nothing here measures. The block whose reservation was freed stays in the
-    // piece's cancellation stack and is handed to whoever asks next, which is
-    // harmless: it is already in flight elsewhere.
+    if (!placed) unplaced += 1;
   }
-  return { duplicated, missing: missing.length, wires: candidates.length };
+  return { duplicated, missing: missing.length, wires: candidates.length, unplaced };
 }
 
 /**

package/services/torrent/worker/tail-repeat.js

@@ -0,0 +1,154 @@
+/**
+ * @file Ask a second peer for the last blocks of a piece somebody is waiting
+ * for, when one slow peer holds them (torrent-tv/meta#178).
+ *
+ * Field r40 (Home Assistant, 2026-10-14, a cold 1080p MKV): the first run's
+ * input waited 10.0 s, last for piece 8, whose slowest block was 4.5 s in
+ * flight from one peer; pieces 14-16 waited 10.0-11.5 s on one peer each. A
+ * block is reserved for one wire, and the piece completes when its slowest
+ * holder delivers (`duplicateTailFor`). Nothing had asked a second peer since
+ * the blocked-read path that did so was removed (`0e38ec3`, torrent-tv/meta#95).
+ *
+ * Which pieces: those of the urgent first class the swarm was last told
+ * (`SwarmSelection.requiredPieces`) — what somebody waits for now. A map that
+ * withdraws them, or an input that is ready, takes them out, and nothing more
+ * is asked for them.
+ *
+ * When: a tail changes when a block arrives, a wire's queue moves on, or a
+ * peer becomes able or unable to give the piece; so it is looked at on those —
+ * a block arriving, a wire unchoking, a peer stating a piece, a wire joining
+ * or closing, a piece verified, a new map. Several in one turn of the event
+ * loop are one look. A tail no other wire could be asked for now is looked at
+ * once more after the time a wire's queue is sized to empty in — WebTorrent
+ * sizes it to one second of the wire's speed (`PIPELINE_MAX_DURATION`) — in
+ * case nothing else happens in between.
+ */
+
+import { duplicateTailFor } from "./fastest-wires.js";
+
+/** WebTorrent's `PIPELINE_MAX_DURATION`: a wire is given one second of its speed to fetch. */
+const WIRE_QUEUE_SECONDS = 1;
+
+/** What a wire says, besides a block arriving, that can change who could be asked for a piece. */
+const WIRE_EVENTS = ["unchoke", "have", "bitfield"];
+
+export class TailRepeat {
+  #torrent;
+  #requiredPieces;
+  #duplicate;
+  #schedule;
+  #wake;
+  #clear;
+  #scheduled = false;
+  #timer = null;
+  #disposed = false;
+  /** @type {Map<object, { onBlock: (index: number) => void, onPeer: () => void }>} */
+  #wires = new Map();
+  #onWire;
+  #onPoke;
+  #log;
+  /**
+   * Grow-only, for the log: block copies asked, looks taken, and blocks that
+   * arrived after their piece was complete — what the copies cost.
+   */
+  totals = { duplicated: 0, looks: 0, lateBlocks: 0 };
+
+  /**
+   * @param {object} params
+   * @param {object} params.torrent
+   * @param {() => Array<{ from: number, to: number }>} params.requiredPieces
+   * @param {typeof duplicateTailFor} [params.duplicate]
+   * @param {(work: () => void) => void} [params.schedule] - Runs work once this turn of the event loop is over.
+   * @param {(work: () => void, ms: number) => unknown} [params.wake]
+   * @param {(handle: unknown) => void} [params.clear]
+   * @param {(line: string) => void} [params.log]
+   */
+  constructor({ torrent, requiredPieces, duplicate = duplicateTailFor, schedule = setImmediate, wake = setTimeout, clear = clearTimeout, log = null }) {
+    this.#log = log;
+    this.#torrent = torrent;
+    this.#requiredPieces = requiredPieces;
+    this.#duplicate = duplicate;
+    this.#schedule = schedule;
+    this.#wake = wake;
+    this.#clear = clear;
+    this.#onWire = (wire) => this.#watch(wire);
+    this.#onPoke = () => this.poke();
+    torrent.on?.("wire", this.#onWire);
+    torrent.on?.("verified", this.#onPoke);
+    for (const wire of Array.isArray(torrent.wires) ? torrent.wires : []) this.#watch(wire);
+  }
+
+  /** Look at the tails once this turn of the event loop is over. */
+  poke() {
+    if (this.#scheduled || this.#disposed) return;
+    this.#scheduled = true;
+    this.#schedule(() => this.#look());
+  }
+
+  /** Stop watching: the torrent is going. */
+  dispose() {
+    this.#disposed = true;
+    this.#torrent.removeListener?.("wire", this.#onWire);
+    this.#torrent.removeListener?.("verified", this.#onPoke);
+    for (const wire of [...this.#wires.keys()]) this.#forget(wire);
+    if (this.#timer !== null) this.#clear(this.#timer);
+    this.#timer = null;
+  }
+
+  #watch(wire) {
+    if (!wire || this.#wires.has(wire) || typeof wire.on !== "function") return;
+    const listeners = {
+      onBlock: (index) => {
+        // A block of a piece already verified is a copy that came second; the
+        // block that completes a piece arrives before the piece is verified.
+        if (Number.isInteger(index) && this.#torrent.bitfield?.get?.(index)) this.totals.lateBlocks += 1;
+        this.poke();
+      },
+      onPeer: () => this.poke()
+    };
+    this.#wires.set(wire, listeners);
+    wire.on("piece", listeners.onBlock);
+    for (const event of WIRE_EVENTS) wire.on(event, listeners.onPeer);
+    wire.once?.("close", () => {
+      this.#forget(wire);
+      this.poke();
+    });
+    this.poke();
+  }
+
+  #forget(wire) {
+    const listeners = this.#wires.get(wire);
+    if (!listeners) return;
+    wire.removeListener?.("piece", listeners.onBlock);
+    for (const event of WIRE_EVENTS) wire.removeListener?.(event, listeners.onPeer);
+    this.#wires.delete(wire);
+  }
+
+  #look() {
+    this.#scheduled = false;
+    if (this.#disposed) return;
+    this.totals.looks += 1;
+    let unplaced = 0;
+    const asked = [];
+    for (const { from, to } of this.#requiredPieces()) {
+      for (let index = from; index <= to; index += 1) {
+        if (this.#torrent.bitfield?.get?.(index)) continue;
+        const result = this.#duplicate(this.#torrent, index);
+        this.totals.duplicated += result.duplicated;
+        unplaced += result.unplaced;
+        if (result.duplicated > 0) asked.push(`${index}:${result.duplicated}/${result.missing}`);
+      }
+    }
+    if (asked.length > 0) {
+      this.#log?.(`tail: asked a second peer for the last blocks of piece:blocks/missing ${asked.join(" ")}; ` +
+        `${this.totals.duplicated} block copies asked so far, ${this.totals.lateBlocks} block(s) arrived after their piece was complete`);
+    }
+    if (unplaced > 0 && this.#timer === null) {
+      this.#timer = this.#wake(() => {
+        this.#timer = null;
+        this.poke();
+      }, WIRE_QUEUE_SECONDS * 1000);
+      this.#timer?.unref?.();
+    }
+  }
+}