@torrent-tv/proxy 2.71.1 → 2.72.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.72.0
+
+- **Fix**: The proxy was killed by the machine's out-of-memory killer at 4.37 GB, twenty minutes after 2.71.0 went out, and the cause was 2.71.0's own budget. A piece being written out to disk leaves the store's count of what it holds the moment the eviction begins, while its memory stays held until the write — which reads from that very block — has finished. The allowance counted resident pieces, so a block held by a pending write was counted nowhere: every admission turned one resident block into one held by the disk and took a fresh block for the arrival, and memory in use rose by one block per admission for as long as the disk was behind. It was behind by a factor of two: 233 evictions started against about 119 writes completed in the same minute. The store reported 203 blocks held with THREE pieces resident against 68 MB allowed. The allowance now bounds blocks in use — resident, reserved, and held by writes that have not finished — so a full store waits for the disk instead of evicting another piece, using the wait and the wake that were already there.
+- **Fix**: And the reason there were so many evictions: 2.71.0 made the allowance equal to what the readers ask for, exactly. `6 reader(s) want 23 piece(s) of 23 the store may hold` — no free place ever exists, so every arriving piece must evict a wanted one. The allowance now includes room for what arrives while one write is finishing, measured from the store's own median write duration and its own arrival rate, and zero until both have been seen rather than invented in advance.
+- **Chore**: `test/piece-store-slow-disk.test.js` drives a disk that answers only when the test says so, which is the field condition — writes slower than arrivals — and it fails without the fix. The check that shipped with the first attempt at this did not: it passed with the defect in place, which is worth recording, because a test that cannot fail proves nothing.
+
+- **Fix**: A proxy reported how much memory it had free with `os.freemem()`, and on Linux that counts only the pages free at this instant — the kernel keeps that number low on purpose and fills the rest with cache, which it hands back the moment anything asks. A host with 4 GB of cache and 200 MB genuinely free called itself nearly full while it had 4.2 GB to give. That figure weighs 0.4 of every proxy's score, so every Linux proxy in the pool understated itself, each by a different amount according to how much cache it happened to hold. It reads `MemAvailable` now — the same fix the piece store's budget got on 2026-08-27, which had stayed in this file until today.
+- **New**: A proxy can answer whether it could sustain a file it is only told ABOUT. The expensive half of that question is finding out what the file IS — add the torrent, wait for metadata, fetch the header, run ffmpeg — and it has already been paid by whichever proxy probed it. Its answer is a handful of numbers; every other proxy answers by arithmetic against its own startup benchmarks in milliseconds, without adding the torrent or fetching a byte. Asked over the tunnel as `can-serve-request`.
+- **New**: The refusal added in 2.71.1 now carries that description, so a viewer whose proxy cannot keep up is moved to one that can instead of being shown an error. A viewer is given a proxy BEFORE the file is known, by a score that reads processor load, free memory and round-trip time — none of which can answer a question about a particular source — and this is where that ordering is repaired, after the fact and only when it went wrong.
+
 ## 2.71.1
 
 - **Fix**: A reader stated the same thing twice — `protectRange` to the piece store for memory, and a window to the torrent for download — and the two were separate lists that could drift. There is one statement now: `SwarmSelection.reconcile` derives both views from the register, so the swarm and the store are told what to do from the same words. Only the urgent levels reach memory: it holds what will be READ soon, and protecting the speculative tail would push out a piece the decoder is about to want.

package/bin/cli.js

@@ -476,6 +476,14 @@ try {
     onHealthRequest() {
       return collectHealthMetrics();
     },
+    // Whether this host could sustain a file it has only been told about. The
+    // same arithmetic the first offer uses, against this host's own startup
+    // benchmarks — no torrent, no bytes, no ffmpeg — so the browser can ask
+    // every proxy in the pool and be sent to one that will work instead of
+    // being shown an error on the one it happened to land on.
+    onCanServeRequest(mediaInfo) {
+      return started?.hlsSessionManager?.predictOfferedHeights?.(mediaInfo) ?? null;
+    },
     onConnect() {
       // Re-register on every tunnel connect/reconnect so the server's
       // in-memory store stays consistent after server restarts.

package/package.json

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

package/server.js

@@ -318,6 +318,10 @@ export async function startProxyServer({
   return {
     app,
     port: selectedPort,
+    // Asked over the tunnel when the proxy a viewer landed on has refused their
+    // file: could THIS host sustain it? Answered from the startup benchmarks
+    // and a description, so it needs no torrent and costs milliseconds.
+    hlsSessionManager,
     // The browser only ever knows a source by its REGISTRY key (a hash of the
     // raw request bytes, scoped to one API session) — never the torrent
     // pool's own key (the content's infohash, shared across a magnet and a

package/services/health-collector.js

@@ -6,6 +6,7 @@
  * All values are cheap to read and require no background work.
  */
 
+import { readFileSync } from "node:fs";
 import os from "node:os";
 
 /**
@@ -16,17 +17,50 @@ import os from "node:os";
  *   Suitable as input to `Math.max(0, 1 - Math.min(1, cpuLoad))` for a
  *   normalised "CPU availability" score.
  *
- * `memFree`  — fraction of total system RAM that is currently free (0–1).
+ * `memFree`  — fraction of total system RAM that could still be given out
+ *   (0–1). See {@link availableMemoryBytes} for why that is not the same as
+ *   free memory.
  *
  * `uptime`   — process uptime in whole seconds (useful for preferring
  *   already-warmed proxies over freshly started ones).
  *
  * @typedef {Object} HealthMetrics
  * @property {number} cpuLoad - 1-min load avg / cpu-count.  0 = idle, 1 = saturated, >1 = overloaded.
- * @property {number} memFree - Free RAM as a fraction of total RAM (0–1).
+ * @property {number} memFree - Memory an allocation could obtain, as a fraction of total RAM (0–1).
  * @property {number} uptime  - Process uptime in seconds.
  */
 
+/**
+ * How much memory the machine could still give out, in bytes.
+ *
+ * NOT `os.freemem()`. On Linux that counts only the pages free at this
+ * instant, and the kernel keeps that number low on purpose: what is not in use
+ * is filled with cache, which is handed back the moment anything asks. A host
+ * with 4 GB of cache and 200 MB genuinely free reports 200 MB and looks full
+ * while it has 4.2 GB to give.
+ *
+ * The kernel publishes its own estimate as `MemAvailable`, and that is what is
+ * read here. The same mistake was fixed in the piece store's budget on
+ * 2026-08-27 and stayed in this file until 2026-09-02, where it weighed 0.4 of
+ * every proxy's score — so every Linux proxy in the pool understated itself,
+ * and by a different amount each, according to how much cache it happened to
+ * hold.
+ *
+ * @returns {number}
+ */
+export function availableMemoryBytes() {
+  try {
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(readFileSync("/proc/meminfo", "utf8"));
+    if (match) {
+      return Number(match[1]) * 1024;
+    }
+  } catch {
+    // silent-ok: not Linux, or /proc is not readable. `os.freemem()` is then
+    // the best available answer and on those systems it is not misleading.
+  }
+  return os.freemem();
+}
+
 /**
  * Collect current system health metrics.
  *
@@ -38,7 +72,7 @@ import os from "node:os";
 export function collectHealthMetrics() {
   const cpuCount = os.cpus().length || 1;
   const cpuLoad = os.loadavg()[0] / cpuCount;
-  const memFree = os.freemem() / os.totalmem();
+  const memFree = availableMemoryBytes() / os.totalmem();
 
   return {
     cpuLoad: Math.round(cpuLoad * 1000) / 1000,

package/services/piece-store/piece-lru.js

@@ -248,6 +248,49 @@ export class PieceLru {
     };
   }
 
+  /**
+   * How long this piece will be waited for, in pieces.
+   *
+   * A window starts at what its reader needs NEXT and runs forward, so a piece
+   * near the start of a window is wanted sooner than one at its far end, and
+   * one beyond every window is wanted later still. That is the comparison the
+   * store needs when a piece arrives at a full store: is the arrival wanted
+   * sooner or later than the piece it would displace?
+   *
+   * `#distanceToWindow` cannot answer it — everything inside any window is zero
+   * there, so a piece at the front of the reader's own window and one at the
+   * far end of somebody else's look identical.
+   *
+   * A piece BEHIND every window is counted by how far behind, because a reader
+   * walking forward will not come back to it: behind is late, not early.
+   *
+   * @param {number} index
+   * @returns {number} -1 when nobody has declared anything.
+   */
+  waitFor(index) {
+    let soonest = -1;
+    for (const range of this.#protected.values()) {
+      const wait = index < range.from ? range.from - index : index - range.from;
+      if (soonest === -1 || wait < soonest) {
+        soonest = wait;
+      }
+    }
+    return soonest;
+  }
+
+  /**
+   * The piece that would be evicted next, and how long it will be waited for.
+   *
+   * @returns {{ index: number | null, wait: number }}
+   */
+  nextVictim() {
+    const choice = this.evictionChoice();
+    return {
+      index: choice.index,
+      wait: choice.index === null ? -1 : this.waitFor(choice.index)
+    };
+  }
+
   /**
    * Whether a reader is holding this piece right now.
    *

package/services/piece-store/shared-piece-store.js

@@ -272,6 +272,12 @@ const REVIVAL_AGE_SAMPLES = 200;
  */
 const REUSE_GAP_SAMPLES = 200;
 
+/** How many write durations are kept for the median. */
+const WRITE_DURATION_SAMPLES = 50;
+/** How many admission times are kept, and how far back they are counted. */
+const ARRIVAL_SAMPLES = 100;
+const ARRIVAL_WINDOW_MS = 10_000;
+
 /**
  * The middle value of a sample, or null when there is nothing to take a middle
  * of. Null rather than zero: no revivals and instant revivals are different
@@ -355,7 +361,29 @@ export class SharedPieceStore {
      */
     returnedWhilePinned: 0,
     /** Spills that found the disk already holding identical bytes. */
-    spillsSkipped: 0
+    spillsSkipped: 0,
+    /**
+     * Blocks a second registration of the same piece displaced. Expected to be
+     * small and non-zero: two callers racing for one piece is ordinary. What is
+     * NOT ordinary is the block going missing when it happens, which is what
+     * killed the process on 2026-09-02.
+     */
+    blocksDisplaced: 0,
+    /** Admissions that waited for the disk instead of evicting another piece. */
+    waitedForDisk: 0,
+    /**
+     * Admissions that grew memory because the disk had stopped answering.
+     * Non-zero means the store exceeded its allowance on purpose, and by how
+     * many pieces.
+     */
+    grewWaitingForDisk: 0,
+    /**
+     * Times a block was wanted, none was free, and the pool was already at its
+     * ceiling. Zero by construction — a block is only taken after a slot has
+     * been claimed, and slots are what the ceiling counts — so a number here
+     * means the two have come apart and the pool is growing past its allowance.
+     */
+    blocksBeyondCeiling: 0
   };
   /**
    * Blocks that hold no piece, most recently freed last.
@@ -384,6 +412,19 @@ export class SharedPieceStore {
    * @type {number[]}
    */
   #reuseGaps = [];
+  /**
+   * How long recent writes to disk took, in milliseconds, and when pieces were
+   * admitted. Together they say how much room the store needs beyond what the
+   * readers ask for: while one write is finishing, more pieces arrive, and each
+   * needs somewhere to go. Without that room every arrival evicts something,
+   * which is what produced 233 evictions against 119 completed writes in a
+   * minute on 2026-09-02.
+   *
+   * @type {number[]}
+   */
+  #writeDurations = [];
+  /** When the last few pieces were admitted, for the arrival rate. */
+  #admittedAt = [];
   /** Piece index → when it was written out, for the age it comes back at. */
   #spilledAt = new Map();
   /**
@@ -460,6 +501,10 @@ export class SharedPieceStore {
       // grows (roadmap item 2).
       blocksAllocated: this.#blocksAllocated,
       blocksFree: this.#freeBlocks.length,
+      blocksDisplaced: this.#counters.blocksDisplaced,
+      blocksInUse: this.#blocksInUse(),
+      blocksInFlight: this.#blocksInFlight(),
+      blocksBeyondCeiling: this.#counters.blocksBeyondCeiling,
       blockBytes: this.#blocksAllocated * this.#chunkLength,
       reuseGapMs: this.#reuseGapCeilingMs(),
       revivalAgeMedianMs: median(this.#revivalAges),
@@ -505,7 +550,12 @@ export class SharedPieceStore {
     if (demand.readers > 0) {
       this.#everHadReader = true;
       const pieces = Math.max(MIN_RESIDENT_PIECES, demand.unionPieces, demand.widestPieces);
-      return pieces * this.#chunkLength;
+      // Plus room to absorb what arrives while a write is finishing. Asking for
+      // exactly what the readers want leaves no free place ever, so every
+      // arrival evicts one of them — measured 2026-09-02: `6 reader(s) want 23
+      // piece(s) of 23 the store may hold`, and 233 evictions in the minute
+      // that followed.
+      return (pieces + this.slackPieces()) * this.#chunkLength;
     }
     // Readers that have GONE are not the same as readers that have not arrived.
     // A store whose readers ended has nothing to hold pieces for — its torrent
@@ -515,7 +565,7 @@ export class SharedPieceStore {
     // reader is being filled for one that is on its way, and asks for what it
     // was opened with until the first read says what it needs.
     return this.#everHadReader
-      ? MIN_RESIDENT_PIECES * this.#chunkLength
+      ? (MIN_RESIDENT_PIECES + this.slackPieces()) * this.#chunkLength
       : this.#growthCeiling * this.#chunkLength;
   }
 
@@ -700,7 +750,21 @@ export class SharedPieceStore {
   }
 
   #registerPiece(index, buffer) {
+    // A piece may already be here. Both paths that register one look first and
+    // then await — `put` waits for a slot, `#revive` waits for the disk — and
+    // in that gap another caller can register the same index. Overwriting the
+    // entry used to drop the previous block on the floor: its memory was not
+    // returned to the pool and the pool's own count was never decremented, so
+    // the count climbed past the ceiling for ever and the pool degenerated into
+    // allocating a fresh block per piece. Field 2026-09-02: a store holding
+    // THREE pieces reported 812 MB committed against 68 MB allowed, 739 blocks
+    // allocated and 676 still alive, and the process was killed at 4.37 GB.
+    const displaced = this.#buffers.get(index);
     this.#buffers.set(index, buffer);
+    if (displaced !== undefined && displaced !== buffer) {
+      this.#counters.blocksDisplaced += 1;
+      this.#returnBlock(displaced);
+    }
     this.#lru.touch(index);
     this.#noteProgress();
   }
@@ -730,8 +794,10 @@ export class SharedPieceStore {
     }
 
     const bytes = Buffer.from(buffer, 0, this.#lengthOf(index));
+    const startedAt = Date.now();
     const spill = this.#disk.write(index, bytes).then(
       () => {
+        this.#noteWriteDuration(Date.now() - startedAt);
         this.#counters.spills += 1;
         this.#spilledAt.set(index, Date.now());
         this.#evicting.delete(index);
@@ -760,6 +826,84 @@ export class SharedPieceStore {
     this.#wake();
   }
 
+  /**
+   * Record how long one write to disk took.
+   *
+   * @param {number} durationMs
+   * @returns {void}
+   */
+  #noteWriteDuration(durationMs) {
+    this.#writeDurations.push(Math.max(0, durationMs));
+    if (this.#writeDurations.length > WRITE_DURATION_SAMPLES) {
+      this.#writeDurations.shift();
+    }
+  }
+
+  /** Record that a piece arrived, for the arrival rate. */
+  #noteArrival() {
+    const now = Date.now();
+    this.#admittedAt.push(now);
+    while (this.#admittedAt.length > ARRIVAL_SAMPLES
+      || (this.#admittedAt.length > 0 && now - this.#admittedAt[0] > ARRIVAL_WINDOW_MS)) {
+      this.#admittedAt.shift();
+    }
+  }
+
+  /**
+   * How many pieces the store needs room for beyond what the readers ask for.
+   *
+   * Measured, not chosen: the pieces that arrive while one write to disk is
+   * finishing. Without this room every arrival must evict something, and each
+   * eviction holds its block until its write completes — so a disk slower than
+   * the swarm turns every admission into one more block held. On 2026-09-02
+   * that was 233 evictions against 119 completed writes in a minute, and 203
+   * blocks held with three pieces resident.
+   *
+   * Zero until both quantities have been seen, because a slack invented before
+   * anything is measured is a chosen number, and this store has been bitten by
+   * those.
+   *
+   * @returns {number} Pieces.
+   */
+  slackPieces() {
+    if (this.#writeDurations.length === 0 || this.#admittedAt.length < 2) {
+      return 0;
+    }
+    const sorted = [...this.#writeDurations].sort((left, right) => left - right);
+    const writeMs = sorted[Math.floor(sorted.length / 2)];
+    const spanMs = this.#admittedAt[this.#admittedAt.length - 1] - this.#admittedAt[0];
+    if (!(spanMs > 0)) {
+      return 0;
+    }
+    const perMs = (this.#admittedAt.length - 1) / spanMs;
+    return Math.ceil(perMs * writeMs);
+  }
+
+  /**
+   * Blocks that are not free: resident pieces, blocks being written out, and
+   * blocks taken but not yet registered.
+   *
+   * This is what the ceiling has to bound, and until 2026-09-02 it bounded
+   * resident pieces instead. The difference is exactly the memory that goes
+   * missing from the count: a piece being spilled leaves `#buffers` the moment
+   * the eviction begins, while its block stays held until the write it feeds
+   * has finished.
+   *
+   * @returns {number}
+   */
+  #blocksInUse() {
+    return this.#blocksAllocated - this.#freeBlocks.length;
+  }
+
+  /**
+   * Blocks held by writes that have not finished.
+   *
+   * @returns {number}
+   */
+  #blocksInFlight() {
+    return Math.max(0, this.#blocksInUse() - this.#buffers.size);
+  }
+
   /**
    * Whether admitting one more piece would need something evicted first.
    *
@@ -769,7 +913,7 @@ export class SharedPieceStore {
    * @returns {boolean}
    */
   #isFullNow() {
-    return this.#buffers.size + this.#outstandingPieces >= this.#growthCeiling;
+    return this.#blocksInUse() + this.#outstandingPieces >= this.#growthCeiling;
   }
 
   /**
@@ -859,12 +1003,39 @@ export class SharedPieceStore {
 
   async #claimSlotOnce() {
     // Reserve before suspension so concurrent callers see the reservation.
-    if (this.#buffers.size + this.#outstandingPieces < this.#growthCeiling) {
+    if (this.#blocksInUse() + this.#outstandingPieces < this.#growthCeiling) {
       this.#outstandingPieces += 1;
       this.#pinnedWaitStartedAt = 0;
       return true;
     }
 
+    // Full, and evicting would make it worse rather than better. A piece being
+    // written out has already left `#buffers` while its block is still held —
+    // the write reads from that block — so evicting another one converts a
+    // resident block into an in-flight block and takes a fresh block for the
+    // arrival: the memory in use goes UP by one per admission for as long as
+    // the disk is behind. Field 2026-09-02: 233 evictions against 119 completed
+    // writes in a minute, 203 blocks held with three pieces resident, and the
+    // process killed at 4.37 GB.
+    //
+    // So when the disk is what the store is waiting for, it waits. A completing
+    // write calls `#noteProgress`, which wakes whoever is here.
+    if (this.#blocksInFlight() > 0 && this.#blocksInUse() >= this.#growthCeiling) {
+      if (this.#pinnedWaitStartedAt === 0) {
+        this.#pinnedWaitStartedAt = Date.now();
+      }
+      const stillFor = Date.now() - Math.max(this.#pinnedWaitStartedAt, this.#lastProgressAt);
+      if (stillFor < PINNED_WAIT_MS) {
+        this.#counters.waitedForDisk += 1;
+        return false;
+      }
+      // The disk has stopped answering. Falling through to eviction is the
+      // lesser failure: it grows memory, and the line above says by how much,
+      // where refusing would fail the read outright.
+      this.#pinnedWaitStartedAt = 0;
+      this.#counters.grewWaitingForDisk += 1;
+    }
+
     const { index: victim, protectionYielded, distance } = this.#lru.evictionChoice();
     if (victim === null) {
       // Nothing may leave. Wait while the store is still MOVING — a spill
@@ -984,6 +1155,19 @@ export class SharedPieceStore {
       this.#noteReuseGap(Date.now() - spare.freedAt);
       return spare.buffer;
     }
+    // Nothing spare and the pool is already as large as it is allowed to be.
+    // This cannot happen while the accounting is sound: a block is taken only
+    // after a slot has been claimed, and slots are exactly what the ceiling
+    // counts. It is recorded rather than hidden because when it does happen the
+    // pool grows without bound, and every block it then allocates is used once
+    // and thrown to a collector that has no reason to run — the heap stays at
+    // 50 MB of 2240 while the process reaches four gigabytes.
+    // Strictly greater: reaching the ceiling exactly is what a full store looks
+    // like, and a slot has just been claimed for this block. Being ALREADY past
+    // it and allocating anyway is the state that runs away.
+    if (this.#blocksAllocated > this.#growthCeiling) {
+      this.#counters.blocksBeyondCeiling += 1;
+    }
     this.#blocksAllocated += 1;
     return this.#watchForCollection(new SharedArrayBuffer(this.#chunkLength));
   }
@@ -1162,6 +1346,7 @@ export class SharedPieceStore {
         return;
       }
 
+      this.#noteArrival();
       const declared = this.#lru.wants(index);
       if (declared) {
         this.#counters.admittedInsideWindow += 1;
@@ -1169,12 +1354,30 @@ export class SharedPieceStore {
         this.#counters.admittedOutsideWindow += 1;
       }
 
-      // A piece no reader has declared, arriving at a store with no room, goes
-      // straight to disk. It costs the same one write it would have cost when
-      // the next arrival evicted it, and it saves pushing out a piece a reader
-      // is about to read. Only when SOMETHING is declared: before the first
-      // read there is no basis for calling a piece unwanted.
-      if (!declared && this.#lru.protectedCount > 0 && this.#isFullNow()) {
+      // A piece that will be wanted LATER than the one it would displace goes
+      // straight to disk instead of being admitted.
+      //
+      // Two cases, and the second was missing until 2026-09-02. The first: the
+      // arrival is in nobody's window at all. The second: it IS in somebody's
+      // window, but further from every read head than the piece the store would
+      // have to evict to make room for it — so admitting it would write out the
+      // nearer piece and read it back sooner. The field session had six readers
+      // whose windows covered the whole file, so the first case never applied
+      // and `0 of those went straight to disk` while the store spilled 233
+      // pieces in a minute.
+      //
+      // Only when SOMETHING is declared: before the first read there is no
+      // basis for calling one piece more wanted than another.
+      const worseThanTheVictim = () => {
+        const arriving = this.#lru.waitFor(index);
+        if (arriving < 0) {
+          return false;
+        }
+        const victim = this.#lru.nextVictim();
+        return victim.index !== null && victim.wait >= 0 && arriving > victim.wait;
+      };
+      if (this.#lru.protectedCount > 0 && this.#isFullNow()
+        && (!declared || worseThanTheVictim())) {
         this.#counters.admittedToDisk += 1;
         await this.#writeThrough(index, bytes);
         this.#noteProgress();

package/services/playback-planner.js

@@ -502,6 +502,13 @@ export function createPlaybackPlanner({
     if (offer && offer.copy.length === 0 && offer.transcode.length === 0) {
       withOffer.cannotServe =
         "This proxy cannot keep up with this file at any quality right now.";
+      // The description travels with the refusal, and only with it. It is what
+      // lets the browser ask the rest of the pool the same question without
+      // anybody else adding the torrent, fetching a byte or running ffmpeg —
+      // the expensive half of finding out what this file IS has been paid here,
+      // once. Everyone else answers by arithmetic against their own startup
+      // benchmarks.
+      withOffer.mediaInfoForOffer = plan.mediaInfoForOffer;
     }
     return withOffer;
   }

package/services/tunnel-client.js

@@ -34,6 +34,12 @@ import { WebSocket } from "ws";
  *   Called each time the WebSocket connection becomes open (including reconnects).
  *   Use to re-register the proxy so the server's in-memory store stays consistent
  *   after server restarts.
+ * @property {(mediaInfo: object) => { copy: number[], transcode: number[] } | null} [onCanServeRequest]
+ *   Called when the server asks whether this host could sustain a file it has
+ *   been DESCRIBED — height, rate, bitrate, codec — rather than one it holds.
+ *   Answered from this host's startup benchmarks alone: no torrent is added, no
+ *   bytes are fetched and ffmpeg is not run, so it costs milliseconds and can
+ *   be asked of every proxy in the pool at once.
  * @property {() => HealthMetrics} [onHealthRequest]
  *   Called when the server sends a `health-request` message.  The return value is
  *   sent back as `health-response` and used by the server to score this proxy.
@@ -117,6 +123,7 @@ export function createTunnelClient({
   onSignal,
   onConnect,
   onHealthRequest,
+  onCanServeRequest,
   onLog,
   connectionLifetimeMs = CONNECTION_LIFETIME_MS
 }) {
@@ -221,6 +228,26 @@ export function createTunnelClient({
         return;
       }
 
+      // Could this host serve a file it is only told ABOUT? Asked when the
+      // proxy a viewer landed on has refused the file, so the browser can be
+      // sent somewhere that will work instead of being shown an error. The
+      // description travels because the refusing proxy has already probed the
+      // file: the expensive half is done once, and every other proxy answers
+      // by arithmetic.
+      if (message.type === "can-serve-request") {
+        let offer = null;
+        try {
+          offer = typeof onCanServeRequest === "function"
+            ? onCanServeRequest(message.mediaInfo ?? {})
+            : null;
+        } catch {
+          // silent-ok: an unanswerable question is answered "no", which is what
+          // a null offer means to the caller.
+        }
+        send({ type: "can-serve-response", requestId: message.requestId, offer });
+        return;
+      }
+
       // Health check: server requests current metrics for proxy scoring.
       if (message.type === "health-request") {
         const metrics = typeof onHealthRequest === "function" ? onHealthRequest() : {};

package/test/health-metrics.test.js

@@ -0,0 +1,37 @@
+/**
+ * @file What a proxy says about itself, and what the pool scores it on.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+
+import { availableMemoryBytes, collectHealthMetrics } from "../services/health-collector.js";
+
+test("free memory is what could be given out, not what is idle this instant", () => {
+  const available = availableMemoryBytes();
+  assert.ok(Number.isFinite(available) && available > 0);
+
+  // On Linux this reads the kernel's own `MemAvailable`, and it is at least
+  // `os.freemem()` by construction: the kernel keeps free memory low on purpose
+  // and fills the rest with cache, which it hands back the moment anything
+  // asks. The old reading was `os.freemem()`, so a host with 4 GB of cache and
+  // 200 MB genuinely free reported itself nearly full while it had 4.2 GB to
+  // give — and that figure weighs 0.4 of every proxy's score.
+  if (os.platform() === "linux") {
+    assert.ok(
+      available >= os.freemem(),
+      `MemAvailable ${available} is below freemem ${os.freemem()}, which cannot be`
+    );
+  }
+});
+
+test("the health report is three bounded numbers", () => {
+  const metrics = collectHealthMetrics();
+  assert.ok(metrics.cpuLoad >= 0);
+  assert.ok(metrics.memFree > 0 && metrics.memFree <= 1);
+  assert.ok(Number.isInteger(metrics.uptime) && metrics.uptime >= 0);
+  // Three decimals, so a value that has not really moved does not produce a
+  // different message on every poll.
+  assert.equal(metrics.memFree, Math.round(metrics.memFree * 1000) / 1000);
+});

package/test/piece-store-eviction.test.js

@@ -154,10 +154,15 @@ test("the store says why it spills: what is asked of it, what it had to take, ho
       asked.demand.unionPieces > asked.demand.capacity,
       "a reader asking for more than the store holds is arithmetic, not a policy fault"
     );
-    assert.ok(
-      asked.evictedProtected > 0,
-      "every eviction here had to take a piece the reader had declared"
-    );
+    // And it no longer has to take a declared piece to make room. The reader
+    // asked for ten pieces of a store that holds four, and the arrivals that
+    // will be wanted LATER than what is already resident are written straight
+    // to disk instead of displacing what will be wanted sooner. Before
+    // 2026-09-02 every one of them displaced something and was read back
+    // moments later: 233 evictions against 119 completed writes in a minute.
+    assert.equal(asked.evictedProtected, 0, "a nearer piece was pushed out for a further one");
+    assert.equal(asked.spills, 0, "nothing had to be written out to make room on admission");
+    assert.ok(asked.admittedToDisk > 0, "the further arrivals were supposed to go to disk");
 
     // Read back the pieces that were spilled: each one comes home, and the
     // store says how long it had been away.
@@ -167,12 +172,17 @@ test("the store says why it spills: what is asked of it, what it had to take, ho
     }
 
     const after = store.stats();
-    assert.ok(after.revivalAgeSamples > 0, "pieces came back and their age was recorded");
-    assert.equal(typeof after.revivalAgeMedianMs, "number");
-    assert.ok(
-      after.revivedWithinFiveSeconds > 0,
-      "a piece wanted again seconds after it left should not have left"
-    );
+    // Reading them back does evict, and that is ordinary: a piece brought into
+    // memory has to displace one. What the change of 2026-09-02 removed is the
+    // eviction on ADMISSION — `asked.spills` above is zero, where before it all
+    // six arrivals displaced a nearer piece and were read back moments later.
+    assert.ok(after.fromDisk > 0, "the pieces that went to disk were read back from it");
+    assert.ok(after.revivals > 0, "reading one back brings it into memory");
+    // No age to report, and that is right rather than missing: an age measures
+    // how long an EVICTED piece stayed away, and these were never resident —
+    // they were written on arrival and read back once.
+    assert.equal(after.revivalAgeSamples, 0);
+    assert.equal(after.revivalAgeMedianMs, null);
 
     store.releaseProtection("video");
     assert.equal(store.stats().demand.readers, 0, "a reader that ends stops being counted");
@@ -401,3 +411,81 @@ test("the allowance is never cut below one reader's whole window", async () => {
     await fs.rm(directory, { recursive: true, force: true });
   }
 });
+
+test("the pool stays the size it is allowed to be, however many pieces pass through it", async () => {
+  // The field failure of 2026-09-02, and the case none of the earlier checks
+  // covered: an allowance far smaller than the number of pieces in flight.
+  // Both paths that register a piece look first and then await — `put` for a
+  // slot, a revival for the disk — and in that gap another caller can register
+  // the same index. Overwriting the entry dropped the previous block without
+  // returning it, so the pool's count climbed past its ceiling for ever and it
+  // degenerated into a fresh block per piece. A store holding THREE pieces
+  // reported 812 MB committed against 68 MB allowed, 739 blocks allocated and
+  // 676 still alive, and the process was killed at 4.37 GB.
+  const capacity = 4;
+  const { store, directory } = await makeStore(capacity);
+  try {
+    // Concurrent, because that is what produces the race: several peers deliver
+    // pieces of one torrent at the same time.
+    for (let round = 0; round < 6; round += 1) {
+      await Promise.all(
+        Array.from({ length: 16 }, (unused, index) => put(store, index, pieceOf(index)))
+      );
+      // And read them back, which revives from disk and races registration the
+      // other way about.
+      await Promise.all([0, 3, 7, 11, 15].map((index) => get(store, index)));
+    }
+
+    const stats = store.stats();
+    assert.equal(stats.blocksBeyondCeiling, 0, "the pool grew past what it is allowed to hold");
+    assert.ok(
+      stats.blocksAllocated <= capacity + stats.blocksFree,
+      `pool of ${stats.blocksAllocated} blocks for ${capacity} slots and ${stats.blocksFree} spare`
+    );
+    assert.equal(stats.committedBytes, stats.blocksAllocated * PIECE);
+
+    // Every piece still reads back as itself: a block returned to the pool
+    // twice, or reused while somebody held it, shows up here as wrong bytes.
+    for (let index = 0; index < 16; index += 1) {
+      const bytes = await get(store, index);
+      assert.ok(bytes.equals(pieceOf(index)), `piece ${index} came back changed`);
+    }
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a piece wanted later than the one it would displace goes to disk instead", async () => {
+  const capacity = 4;
+  const { store, directory } = await makeStore(capacity);
+  try {
+    // A reader is at the start of the file and the store is full of what it
+    // wants. Its window is pieces 0-3.
+    store.protectRange("video", 0, 3);
+    for (let index = 0; index < capacity; index += 1) {
+      await put(store, index, pieceOf(index));
+    }
+    const before = store.stats().admittedToDisk;
+
+    // A piece arrives from far ahead. It IS inside a window in the field case —
+    // six readers covered the whole file — but it lies further from every read
+    // head than the piece the store would have to evict for it. Admitting it
+    // would write out the nearer piece and read that one back sooner.
+    store.protectRange("far", 90, 99);
+    await put(store, 95, pieceOf(95));
+
+    assert.ok(
+      store.stats().admittedToDisk > before,
+      "the further piece was admitted to memory and the nearer one written out"
+    );
+    // And it still reads back as itself, from the disk it was put on.
+    assert.ok((await get(store, 95)).equals(pieceOf(95)));
+    for (let index = 0; index < capacity; index += 1) {
+      assert.ok((await get(store, index)).equals(pieceOf(index)), `piece ${index} was lost`);
+    }
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/test/piece-store-slow-disk.test.js

@@ -0,0 +1,114 @@
+/**
+ * @file What the allowance has to bound, and why it is not the resident pieces.
+ *
+ * The field failure of 2026-09-02, in one sentence: a piece being written out
+ * leaves the store's own count the moment the eviction begins, while its memory
+ * stays held until the write that reads from it has finished. So every
+ * admission turned one resident block into one block held by the disk and took
+ * a fresh block for the arrival, and the memory in use went UP by one per
+ * admission for as long as the disk was behind.
+ *
+ * It was behind by a factor of two: 233 evictions started against about 119
+ * writes completed in the same minute. The store reported 203 blocks held with
+ * THREE pieces resident and 68 MB allowed, and the kernel killed the process at
+ * 4.37 GB.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
+
+const PIECE = 1024;
+
+/**
+ * A disk that answers only when the test lets it, so writes can be made slower
+ * than arrivals on purpose — which is the whole of the field condition.
+ */
+function heldDisk() {
+  const stored = new Set();
+  /** @type {Array<() => void>} */
+  const waiting = [];
+  return {
+    pending: waiting,
+    get size() {
+      return stored.size;
+    },
+    has: (index) => stored.has(index),
+    forget: (index) => stored.delete(index),
+    write(index) {
+      return new Promise((resolve) => {
+        waiting.push(() => {
+          stored.add(index);
+          resolve();
+        });
+      });
+    },
+    async read(index, target) {
+      target.fill(index % 251);
+      return target.length;
+    },
+    async close() { waiting.length = 0; },
+    async destroy() { stored.clear(); waiting.length = 0; }
+  };
+}
+
+/**
+ * @param {SharedPieceStore} store
+ * @param {number} index
+ * @returns {Promise<void>}
+ */
+const put = (store, index) =>
+  new Promise((resolve, reject) => {
+    store.put(index, Buffer.alloc(PIECE, index % 251), (error) => (error ? reject(error) : resolve()));
+  });
+
+test("memory in use never runs past the allowance while the disk is behind", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "slow-disk-test-"));
+  const disk = heldDisk();
+  const capacity = 4;
+  const store = new SharedPieceStore(PIECE, {
+    length: PIECE * 200,
+    memoryBytes: PIECE * capacity,
+    path: directory,
+    name: "slow-disk",
+    disk
+  });
+  try {
+    // Fill it, then keep pieces coming while every write stays unfinished.
+    for (let index = 0; index < capacity; index += 1) {
+      await put(store, index);
+    }
+    const arrivals = [];
+    for (let index = capacity; index < capacity + 40; index += 1) {
+      arrivals.push(put(store, index).catch(() => undefined));
+    }
+    // Let them get as far as they can with the disk answering nothing.
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const held = store.stats();
+    // The check the field failure would fail: a store allowed four pieces held
+    // two hundred and three. Blocks held by a pending write count here, because
+    // they are memory whatever the piece count says.
+    assert.ok(
+      held.blocksInUse <= capacity,
+      `${held.blocksInUse} blocks in use with ${capacity} allowed `
+      + `(${held.blocksInFlight} of them held by writes that have not finished)`
+    );
+    assert.ok(held.blocksInFlight > 0, "the disk was supposed to be holding some");
+    assert.ok(held.waitedForDisk > 0, "admission was supposed to wait for the disk, not evict");
+
+    // Let the disk answer: the blocks come back and everything settles.
+    while (disk.pending.length > 0) {
+      disk.pending.shift()?.();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    await Promise.all(arrivals);
+    assert.ok(store.stats().blocksInUse <= capacity + 1, "the pool did not settle");
+  } finally {
+    store.destroy(() => undefined);
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});