@torrent-tv/proxy 2.89.6 → 2.89.7

package/test/audio-track-bitrate.test.js

@@ -1,40 +1,40 @@
-/**
- * @file The rate a copied soundtrack puts on a viewer's link is the rate the
- * file states for THAT track — roadmap item 97, step 11.
- *
- * Not the first rate the banner prints and not the file's total: two tracks of
- * one film can differ fivefold (a stereo AAC and a 5.1 AC3), and the viewer
- * receives only the one they chose. Parsed text, no process.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { parseStreamCodecs } from "../services/media/playback-planner.js";
-import { buildAudioInventory } from "../services/media/audio-inventory.js";
-
-const BANNER = [
-  "Input #0, matroska,webm, from 'http://127.0.0.1/stream':",
-  "  Duration: 01:30:00.00, start: 0.000000, bitrate: 9000 kb/s",
-  "  Stream #0:0: Video: h264 (High), yuv420p, 1920x1080, 24 fps (default)",
-  "  Stream #0:1(eng): Audio: aac (LC), 48000 Hz, stereo, fltp, 128 kb/s (default)",
-  "  Stream #0:2(rus): Audio: ac3, 48000 Hz, 5.1(side), fltp",
-  "    Metadata:",
-  "      title           : Dub",
-  "      BPS             : 640000",
-  "  Stream #0:3(fre): Audio: ac3, 48000 Hz, 5.1(side), fltp",
-  "At least one output file must be specified"
-].join("\n");
-
-test("each soundtrack carries its own stated rate, from its own line or its own statistics tag", () => {
-  const { audioTracks } = parseStreamCodecs(BANNER);
-
-  assert.deepEqual(audioTracks.map((track) => track.bitrateKbps), [128, 640, null]);
-  assert.notEqual(audioTracks[1].bitrateKbps, 9000, "never the file's total");
-});
-
-test("the inventory keeps each track's rate, so the chosen one can be priced", () => {
-  const { audioTracks } = parseStreamCodecs(BANNER);
-  const inventory = buildAudioInventory({ embedded: audioTracks, videoFileIndex: 0, sidecars: [] });
-
-  assert.deepEqual(inventory.map((entry) => entry.bitrateKbps), [128, 640, null]);
-});
+/**
+ * @file The rate a copied soundtrack puts on a viewer's link is the rate the
+ * file states for THAT track — roadmap item 97, step 11.
+ *
+ * Not the first rate the banner prints and not the file's total: two tracks of
+ * one film can differ fivefold (a stereo AAC and a 5.1 AC3), and the viewer
+ * receives only the one they chose. Parsed text, no process.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseStreamCodecs } from "../services/media/playback-planner.js";
+import { buildAudioInventory } from "../services/media/audio-inventory.js";
+
+const BANNER = [
+  "Input #0, matroska,webm, from 'http://127.0.0.1/stream':",
+  "  Duration: 01:30:00.00, start: 0.000000, bitrate: 9000 kb/s",
+  "  Stream #0:0: Video: h264 (High), yuv420p, 1920x1080, 24 fps (default)",
+  "  Stream #0:1(eng): Audio: aac (LC), 48000 Hz, stereo, fltp, 128 kb/s (default)",
+  "  Stream #0:2(rus): Audio: ac3, 48000 Hz, 5.1(side), fltp",
+  "    Metadata:",
+  "      title           : Dub",
+  "      BPS             : 640000",
+  "  Stream #0:3(fre): Audio: ac3, 48000 Hz, 5.1(side), fltp",
+  "At least one output file must be specified"
+].join("\n");
+
+test("each soundtrack carries its own stated rate, from its own line or its own statistics tag", () => {
+  const { audioTracks } = parseStreamCodecs(BANNER);
+
+  assert.deepEqual(audioTracks.map((track) => track.bitrateKbps), [128, 640, null]);
+  assert.notEqual(audioTracks[1].bitrateKbps, 9000, "never the file's total");
+});
+
+test("the inventory keeps each track's rate, so the chosen one can be priced", () => {
+  const { audioTracks } = parseStreamCodecs(BANNER);
+  const inventory = buildAudioInventory({ embedded: audioTracks, videoFileIndex: 0, sidecars: [] });
+
+  assert.deepEqual(inventory.map((entry) => entry.bitrateKbps), [128, 640, null]);
+});

package/test/available-share.test.js

@@ -1,76 +1,76 @@
-/**
- * @file What the machine can spare for a new encoder — and what must not be
- * charged twice.
- *
- * The numbers are the addon host's own, measured 2026-08-17 while a 240p step
- * ran at 1.01-1.12x against a prediction of 1.83x.
- */
-
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { availableShareFrom, correctForAvailability } from "../services/encode/available-share.js";
-
-test("only the work nobody has been charged for is subtracted", () => {
-  // The field reading: the box is saturated, our encoder has more than half of
-  // it, and the proxy's own work a fifth.
-  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
-
-  assert.equal(availability.known, true);
-  // 0.99 − 0.76 = 0.23 belongs to the kernel, the container and whatever else
-  // the owner runs. Our own encoders are priced by the concurrency arithmetic
-  // and the proxy's work per megabyte moved; charging them here as well is the
-  // double counting that emptied the quality menu in 2.21.0.
-  assert.ok(Math.abs(availability.unattributed - 0.23) < 1e-9, `${availability.unattributed}`);
-  assert.ok(Math.abs(availability.share - 0.77) < 1e-9, `${availability.share}`);
-});
-
-test("a quiet machine is not corrected at all", () => {
-  const availability = availableShareFrom({ systemBusy: 0.05, encoderShare: 0.04, proxyShare: 0.01 });
-  assert.equal(availability.unattributed, 0);
-  assert.equal(availability.share, 1);
-  assert.equal(correctForAvailability(4, availability), 4);
-});
-
-test("a host that cannot say says so, and nothing is corrected", () => {
-  // Not every host has /proc. An uncorrected figure is honest; a figure
-  // corrected by an invented share is not.
-  const availability = availableShareFrom({ systemBusy: null, encoderShare: null, proxyShare: null });
-  assert.equal(availability.known, false);
-  assert.equal(availability.share, 1);
-  assert.equal(correctForAvailability(2.5, availability), 2.5, "an unknown machine leaves the prediction alone");
-  assert.equal(availableShareFrom().known, false);
-});
-
-test("readings that overlap by a rounding do not produce a negative machine", () => {
-  // The two samples are taken microseconds apart, so our own share can come out
-  // fractionally above the system total.
-  const availability = availableShareFrom({ systemBusy: 0.60, encoderShare: 0.58, proxyShare: 0.05 });
-  assert.equal(availability.unattributed, 0);
-  assert.equal(availability.share, 1);
-});
-
-test("a machine given over entirely to other work leaves nothing", () => {
-  const availability = availableShareFrom({ systemBusy: 1, encoderShare: 0, proxyShare: 0 });
-  assert.equal(availability.share, 0);
-  assert.equal(correctForAvailability(4, availability), 0, "a step cannot be offered on a machine with nothing left");
-});
-
-test("the correction is proportional, and only ever downwards", () => {
-  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
-  // The field case: a step predicted at 1.83x on a quiet box.
-  const corrected = correctForAvailability(1.83, availability);
-  assert.ok(Math.abs(corrected - 1.4091) < 0.001, `${corrected}`);
-  // And the honest note this test exists to record: 1.41x is still above the
-  // 1.01-1.12x that step actually ran at. This correction closes part of the
-  // gap, not all of it — which is why the per-step field comparison ships with
-  // it rather than after it.
-  assert.ok(corrected > 1.12, "the remaining difference is what the field check is for");
-});
-
-test("nothing is corrected without a prediction to correct", () => {
-  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.5, proxyShare: 0.2 });
-  assert.equal(correctForAvailability(0, availability), 0);
-  assert.equal(correctForAvailability(Number.NaN, availability), Number.NaN);
-  assert.equal(correctForAvailability(-1, availability), -1);
-});
+/**
+ * @file What the machine can spare for a new encoder — and what must not be
+ * charged twice.
+ *
+ * The numbers are the addon host's own, measured 2026-08-17 while a 240p step
+ * ran at 1.01-1.12x against a prediction of 1.83x.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { availableShareFrom, correctForAvailability } from "../services/encode/available-share.js";
+
+test("only the work nobody has been charged for is subtracted", () => {
+  // The field reading: the box is saturated, our encoder has more than half of
+  // it, and the proxy's own work a fifth.
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
+
+  assert.equal(availability.known, true);
+  // 0.99 − 0.76 = 0.23 belongs to the kernel, the container and whatever else
+  // the owner runs. Our own encoders are priced by the concurrency arithmetic
+  // and the proxy's work per megabyte moved; charging them here as well is the
+  // double counting that emptied the quality menu in 2.21.0.
+  assert.ok(Math.abs(availability.unattributed - 0.23) < 1e-9, `${availability.unattributed}`);
+  assert.ok(Math.abs(availability.share - 0.77) < 1e-9, `${availability.share}`);
+});
+
+test("a quiet machine is not corrected at all", () => {
+  const availability = availableShareFrom({ systemBusy: 0.05, encoderShare: 0.04, proxyShare: 0.01 });
+  assert.equal(availability.unattributed, 0);
+  assert.equal(availability.share, 1);
+  assert.equal(correctForAvailability(4, availability), 4);
+});
+
+test("a host that cannot say says so, and nothing is corrected", () => {
+  // Not every host has /proc. An uncorrected figure is honest; a figure
+  // corrected by an invented share is not.
+  const availability = availableShareFrom({ systemBusy: null, encoderShare: null, proxyShare: null });
+  assert.equal(availability.known, false);
+  assert.equal(availability.share, 1);
+  assert.equal(correctForAvailability(2.5, availability), 2.5, "an unknown machine leaves the prediction alone");
+  assert.equal(availableShareFrom().known, false);
+});
+
+test("readings that overlap by a rounding do not produce a negative machine", () => {
+  // The two samples are taken microseconds apart, so our own share can come out
+  // fractionally above the system total.
+  const availability = availableShareFrom({ systemBusy: 0.60, encoderShare: 0.58, proxyShare: 0.05 });
+  assert.equal(availability.unattributed, 0);
+  assert.equal(availability.share, 1);
+});
+
+test("a machine given over entirely to other work leaves nothing", () => {
+  const availability = availableShareFrom({ systemBusy: 1, encoderShare: 0, proxyShare: 0 });
+  assert.equal(availability.share, 0);
+  assert.equal(correctForAvailability(4, availability), 0, "a step cannot be offered on a machine with nothing left");
+});
+
+test("the correction is proportional, and only ever downwards", () => {
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.56, proxyShare: 0.2 });
+  // The field case: a step predicted at 1.83x on a quiet box.
+  const corrected = correctForAvailability(1.83, availability);
+  assert.ok(Math.abs(corrected - 1.4091) < 0.001, `${corrected}`);
+  // And the honest note this test exists to record: 1.41x is still above the
+  // 1.01-1.12x that step actually ran at. This correction closes part of the
+  // gap, not all of it — which is why the per-step field comparison ships with
+  // it rather than after it.
+  assert.ok(corrected > 1.12, "the remaining difference is what the field check is for");
+});
+
+test("nothing is corrected without a prediction to correct", () => {
+  const availability = availableShareFrom({ systemBusy: 0.99, encoderShare: 0.5, proxyShare: 0.2 });
+  assert.equal(correctForAvailability(0, availability), 0);
+  assert.equal(correctForAvailability(Number.NaN, availability), Number.NaN);
+  assert.equal(correctForAvailability(-1, availability), -1);
+});

package/test/background-fill.test.js

@@ -1,190 +1,190 @@
-/**
- * Fetching a file nobody is playing yet, without taking anything from the
- * viewer.
- *
- * The ordering these checks pin is the whole point of the thing: what plays now
- * comes first, the other soundtracks and subtitle files next, and reading the
- * film far ahead last. The middle tier stays below the first by standing aside
- * whenever a reader on the torrent is inside a wait.
- */
-
-import assert from "node:assert/strict";
-import test from "node:test";
-import { EventEmitter } from "node:events";
-import { fillFileInBackground, fillIsRunning } from "../services/torrent/worker/background-fill.js";
-
-/**
- * A file whose reads resolve when the test says so, recording what was asked
- * for.
- *
- * @param {{ length: number, name?: string }} params
- */
-function fakeFile({ length, name = "dub.mka" }) {
-  const reads = [];
-  return {
-    name,
-    length,
-    reads,
-    createReadStream({ start, end }) {
-      const stream = new EventEmitter();
-      stream.destroy = () => {};
-      reads.push({ start, end });
-      // Deliver on the next turn, so a test can observe the read in flight.
-      queueMicrotask(() => {
-        stream.emit("data", Buffer.alloc(end - start + 1));
-        stream.emit("end");
-      });
-      return stream;
-    }
-  };
-}
-
-/**
- * @param {() => boolean} until
- * @param {number} [limit]
- */
-async function waitFor(until, limit = 2000) {
-  const deadline = Date.now() + limit;
-  while (!until()) {
-    if (Date.now() > deadline) {
-      throw new Error("condition was never reached");
-    }
-    await new Promise((resolve) => setTimeout(resolve, 5));
-  }
-}
-
-test("a file is walked whole, a piece at a time", async () => {
-  const file = fakeFile({ length: 10 });
-  const torrent = { infoHash: "aaa", pieceLength: 4, files: [file] };
-
-  const started = fillFileInBackground(torrent, 0, "source-a", { chunkBytes: 4 });
-
-  assert.equal(started, true);
-  await waitFor(() => !fillIsRunning("source-a", 0));
-  // 0-3, 4-7, 8-9: the last chunk is short because the file ends, and its end
-  // is the last byte rather than one past it.
-  assert.deepEqual(file.reads, [
-    { start: 0, end: 3 },
-    { start: 4, end: 7 },
-    { start: 8, end: 9 }
-  ]);
-});
-
-test("one fill per file, however many times it is asked for", async () => {
-  const file = fakeFile({ length: 8 });
-  const torrent = { infoHash: "bbb", pieceLength: 4, files: [file] };
-
-  const first = fillFileInBackground(torrent, 0, "source-b", { chunkBytes: 4 });
-  const second = fillFileInBackground(torrent, 0, "source-b", { chunkBytes: 4 });
-
-  assert.equal(first, true);
-  assert.equal(second, false, "the second call does not start a second walk");
-  await waitFor(() => !fillIsRunning("source-b", 0));
-  assert.equal(file.reads.length, 2, "the file was walked once");
-});
-
-test("a file that is gone is not read, and does not throw", async () => {
-  const torrent = { infoHash: "ccc", pieceLength: 4, files: [] };
-
-  const started = fillFileInBackground(torrent, 0, "source-c", { chunkBytes: 4 });
-
-  assert.equal(started, false);
-  assert.equal(fillIsRunning("source-c", 0), false);
-});
-
-test("a read that returns nothing stops the walk instead of spinning", async () => {
-  const file = {
-    name: "dub.mka",
-    length: 100,
-    reads: [],
-    createReadStream({ start, end }) {
-      const stream = new EventEmitter();
-      stream.destroy = () => {};
-      this.reads.push({ start, end });
-      queueMicrotask(() => stream.emit("error", new Error("gone")));
-      return stream;
-    }
-  };
-  const torrent = { infoHash: "ddd", pieceLength: 10, files: [file] };
-
-  fillFileInBackground(torrent, 0, "source-d", { chunkBytes: 10 });
-
-  await waitFor(() => !fillIsRunning("source-d", 0));
-  assert.equal(file.reads.length, 1, "it gave up after the first failed read");
-});
-
-test("it stands aside while the viewer's own reading is blocked", async () => {
-  const file = fakeFile({ length: 8 });
-  const torrent = { infoHash: "eee", pieceLength: 4, files: [file] };
-  let blocked = true;
-
-  fillFileInBackground(torrent, 0, "source-e", { chunkBytes: 4, isBlocked: () => blocked });
-
-  // The picture is starving, so nothing is asked of the swarm on the
-  // soundtrack's behalf — however long that lasts.
-  await new Promise((resolve) => setTimeout(resolve, 120));
-  assert.deepEqual(file.reads, [], "not one read while a reader is inside a wait");
-
-  blocked = false;
-  await waitFor(() => !fillIsRunning("source-e", 0));
-  assert.equal(file.reads.length, 2, "and it resumes once the room is there");
-});
-
-test("the gate is re-asked before every chunk, not once at the start", async () => {
-  const file = fakeFile({ length: 12 });
-  const torrent = { infoHash: "fff", pieceLength: 4, files: [file] };
-  // Starve the viewer again the moment the first chunk has been read, and stay
-  // that way until the test lifts it.
-  let starvedAfterFirstChunk = false;
-  let lifted = false;
-  const isBlocked = () => {
-    if (file.reads.length >= 1 && !lifted) {
-      starvedAfterFirstChunk = true;
-    }
-    return starvedAfterFirstChunk && !lifted;
-  };
-
-  fillFileInBackground(torrent, 0, "source-f", { chunkBytes: 4, isBlocked });
-
-  await waitFor(() => file.reads.length === 1);
-  await new Promise((resolve) => setTimeout(resolve, 120));
-  assert.equal(file.reads.length, 1, "a torrent healthy a moment ago is not evidence about now");
-
-  lifted = true;
-  await waitFor(() => !fillIsRunning("source-f", 0));
-  assert.equal(file.reads.length, 3);
-});
-
-test("a stall during a chunk makes the next one wait, not just a stall in progress", async () => {
-  // The case this exists for: a swarm delivering exactly what the film needs.
-  // Nothing is blocked at the moment the gate is asked, but the viewer stalled
-  // while the last chunk was in flight — which is the proof there was no room.
-  const file = fakeFile({ length: 12 });
-  const torrent = { infoHash: "ggg", pieceLength: 4, files: [file] };
-  let stalls = 0;
-  let starving = true;
-  // A stall happens DURING every chunk, exactly as it does on a swarm with no
-  // surplus — and nothing is blocked at the moment the gate is asked.
-  const originalRead = file.createReadStream.bind(file);
-  file.createReadStream = (range) => {
-    if (starving) {
-      stalls += 1;
-    }
-    return originalRead(range);
-  };
-
-  fillFileInBackground(torrent, 0, "source-g", {
-    chunkBytes: 4,
-    isBlocked: () => false,
-    stallsSeen: () => stalls
-  });
-
-  await waitFor(() => file.reads.length === 1);
-  await new Promise((resolve) => setTimeout(resolve, 300));
-  assert.equal(file.reads.length, 1, "a stall during the chunk holds the next one back");
-
-  // The swarm settles: no further stalls, so it may go on.
-  starving = false;
-  await waitFor(() => !fillIsRunning("source-g", 0), 8000);
-  assert.equal(file.reads.length, 3);
-});
+/**
+ * Fetching a file nobody is playing yet, without taking anything from the
+ * viewer.
+ *
+ * The ordering these checks pin is the whole point of the thing: what plays now
+ * comes first, the other soundtracks and subtitle files next, and reading the
+ * film far ahead last. The middle tier stays below the first by standing aside
+ * whenever a reader on the torrent is inside a wait.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { EventEmitter } from "node:events";
+import { fillFileInBackground, fillIsRunning } from "../services/torrent/worker/background-fill.js";
+
+/**
+ * A file whose reads resolve when the test says so, recording what was asked
+ * for.
+ *
+ * @param {{ length: number, name?: string }} params
+ */
+function fakeFile({ length, name = "dub.mka" }) {
+  const reads = [];
+  return {
+    name,
+    length,
+    reads,
+    createReadStream({ start, end }) {
+      const stream = new EventEmitter();
+      stream.destroy = () => {};
+      reads.push({ start, end });
+      // Deliver on the next turn, so a test can observe the read in flight.
+      queueMicrotask(() => {
+        stream.emit("data", Buffer.alloc(end - start + 1));
+        stream.emit("end");
+      });
+      return stream;
+    }
+  };
+}
+
+/**
+ * @param {() => boolean} until
+ * @param {number} [limit]
+ */
+async function waitFor(until, limit = 2000) {
+  const deadline = Date.now() + limit;
+  while (!until()) {
+    if (Date.now() > deadline) {
+      throw new Error("condition was never reached");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+test("a file is walked whole, a piece at a time", async () => {
+  const file = fakeFile({ length: 10 });
+  const torrent = { infoHash: "aaa", pieceLength: 4, files: [file] };
+
+  const started = fillFileInBackground(torrent, 0, "source-a", { chunkBytes: 4 });
+
+  assert.equal(started, true);
+  await waitFor(() => !fillIsRunning("source-a", 0));
+  // 0-3, 4-7, 8-9: the last chunk is short because the file ends, and its end
+  // is the last byte rather than one past it.
+  assert.deepEqual(file.reads, [
+    { start: 0, end: 3 },
+    { start: 4, end: 7 },
+    { start: 8, end: 9 }
+  ]);
+});
+
+test("one fill per file, however many times it is asked for", async () => {
+  const file = fakeFile({ length: 8 });
+  const torrent = { infoHash: "bbb", pieceLength: 4, files: [file] };
+
+  const first = fillFileInBackground(torrent, 0, "source-b", { chunkBytes: 4 });
+  const second = fillFileInBackground(torrent, 0, "source-b", { chunkBytes: 4 });
+
+  assert.equal(first, true);
+  assert.equal(second, false, "the second call does not start a second walk");
+  await waitFor(() => !fillIsRunning("source-b", 0));
+  assert.equal(file.reads.length, 2, "the file was walked once");
+});
+
+test("a file that is gone is not read, and does not throw", async () => {
+  const torrent = { infoHash: "ccc", pieceLength: 4, files: [] };
+
+  const started = fillFileInBackground(torrent, 0, "source-c", { chunkBytes: 4 });
+
+  assert.equal(started, false);
+  assert.equal(fillIsRunning("source-c", 0), false);
+});
+
+test("a read that returns nothing stops the walk instead of spinning", async () => {
+  const file = {
+    name: "dub.mka",
+    length: 100,
+    reads: [],
+    createReadStream({ start, end }) {
+      const stream = new EventEmitter();
+      stream.destroy = () => {};
+      this.reads.push({ start, end });
+      queueMicrotask(() => stream.emit("error", new Error("gone")));
+      return stream;
+    }
+  };
+  const torrent = { infoHash: "ddd", pieceLength: 10, files: [file] };
+
+  fillFileInBackground(torrent, 0, "source-d", { chunkBytes: 10 });
+
+  await waitFor(() => !fillIsRunning("source-d", 0));
+  assert.equal(file.reads.length, 1, "it gave up after the first failed read");
+});
+
+test("it stands aside while the viewer's own reading is blocked", async () => {
+  const file = fakeFile({ length: 8 });
+  const torrent = { infoHash: "eee", pieceLength: 4, files: [file] };
+  let blocked = true;
+
+  fillFileInBackground(torrent, 0, "source-e", { chunkBytes: 4, isBlocked: () => blocked });
+
+  // The picture is starving, so nothing is asked of the swarm on the
+  // soundtrack's behalf — however long that lasts.
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  assert.deepEqual(file.reads, [], "not one read while a reader is inside a wait");
+
+  blocked = false;
+  await waitFor(() => !fillIsRunning("source-e", 0));
+  assert.equal(file.reads.length, 2, "and it resumes once the room is there");
+});
+
+test("the gate is re-asked before every chunk, not once at the start", async () => {
+  const file = fakeFile({ length: 12 });
+  const torrent = { infoHash: "fff", pieceLength: 4, files: [file] };
+  // Starve the viewer again the moment the first chunk has been read, and stay
+  // that way until the test lifts it.
+  let starvedAfterFirstChunk = false;
+  let lifted = false;
+  const isBlocked = () => {
+    if (file.reads.length >= 1 && !lifted) {
+      starvedAfterFirstChunk = true;
+    }
+    return starvedAfterFirstChunk && !lifted;
+  };
+
+  fillFileInBackground(torrent, 0, "source-f", { chunkBytes: 4, isBlocked });
+
+  await waitFor(() => file.reads.length === 1);
+  await new Promise((resolve) => setTimeout(resolve, 120));
+  assert.equal(file.reads.length, 1, "a torrent healthy a moment ago is not evidence about now");
+
+  lifted = true;
+  await waitFor(() => !fillIsRunning("source-f", 0));
+  assert.equal(file.reads.length, 3);
+});
+
+test("a stall during a chunk makes the next one wait, not just a stall in progress", async () => {
+  // The case this exists for: a swarm delivering exactly what the film needs.
+  // Nothing is blocked at the moment the gate is asked, but the viewer stalled
+  // while the last chunk was in flight — which is the proof there was no room.
+  const file = fakeFile({ length: 12 });
+  const torrent = { infoHash: "ggg", pieceLength: 4, files: [file] };
+  let stalls = 0;
+  let starving = true;
+  // A stall happens DURING every chunk, exactly as it does on a swarm with no
+  // surplus — and nothing is blocked at the moment the gate is asked.
+  const originalRead = file.createReadStream.bind(file);
+  file.createReadStream = (range) => {
+    if (starving) {
+      stalls += 1;
+    }
+    return originalRead(range);
+  };
+
+  fillFileInBackground(torrent, 0, "source-g", {
+    chunkBytes: 4,
+    isBlocked: () => false,
+    stallsSeen: () => stalls
+  });
+
+  await waitFor(() => file.reads.length === 1);
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  assert.equal(file.reads.length, 1, "a stall during the chunk holds the next one back");
+
+  // The swarm settles: no further stalls, so it may go on.
+  starving = false;
+  await waitFor(() => !fillIsRunning("source-g", 0), 8000);
+  assert.equal(file.reads.length, 3);
+});