@torrent-tv/proxy 2.69.0 → 2.69.2

package/package.json

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

package/services/memory-report.js

@@ -291,6 +291,12 @@ function megabytes(bytes) {
  * @param {ReturnType<typeof summariseMappings> | null} [reading.mappings]
  * @param {number | null} [reading.diskFreeBytes]
  * @param {{ name: string, residentBytes: number, committedBytes: number, spilledBytes: number, budgetBytes: number }[]} [reading.stores]
+ * @param {string} [reading.extra] - Figures the caller wants on the same line
+ *   rather than on one of its own. The piece-buffer counters are read here so
+ *   that the number of buffers alive and the off-heap mass they should account
+ *   for are the SAME instant: printed on separate timers they were up to a
+ *   minute apart, and 950 MB of `arrayBuffers` could not be checked against the
+ *   62 buffers a reading half a minute away said were alive (roadmap item 2).
  * @returns {string}
  */
 export function describeMemory({
@@ -302,7 +308,8 @@ export function describeMemory({
   anonymousBytes = null,
   mappings = null,
   diskFreeBytes = null,
-  stores = []
+  stores = [],
+  extra = ""
 }) {
   const total = (field) => stores.reduce((sum, store) => sum + (store[field] || 0), 0);
   const storeResident = total("residentBytes");
@@ -321,8 +328,9 @@ export function describeMemory({
     `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)}` +
     `${usage.heapLimit ? ` of ${megabytes(usage.heapLimit)} allowed` : ""} ` +
     `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}`;
+  const tail = extra ? `; ${extra}` : "";
   if (scope === "thread") {
-    return `memory (${label || "thread"}): ${isolate}; ${storesPart}`;
+    return `memory (${label || "thread"}): ${isolate}; ${storesPart}${tail}`;
   }
   const shape = mappings === null
     ? ""
@@ -337,10 +345,41 @@ export function describeMemory({
     `${storesPart}; ` +
     `machine has ${megabytes(availableBytes ?? 0)} available` +
     `${availableMeasured ? "" : " (estimated — /proc/meminfo could not be read)"}` +
-    `${diskFreeBytes === null ? "" : `, ${megabytes(diskFreeBytes)} free on disk`}`
+    `${diskFreeBytes === null ? "" : `, ${megabytes(diskFreeBytes)} free on disk`}` +
+    tail
   );
 }
 
+/**
+ * The figures whose movement earns a line, each under its own name.
+ *
+ * Not the same question as what the scope WATCHES for a heap snapshot. A
+ * thread's heap is only one of the three ways its isolate holds memory, and on
+ * 2026-09-02 it was the one that did not move: `heapTotal` stayed at 31-173 MB
+ * through a session where `arrayBuffers` swung between 130 and 950 MB, so the
+ * change trigger was watching the one quantity that stood still and every
+ * reading of the one that grew came out on the quiet interval, a minute apart.
+ *
+ * Each figure is compared against its own last written value and any one of
+ * them moving is enough. Nothing is added together, because `arrayBuffers` is
+ * documented as part of `external` and reads larger than it on this runtime —
+ * a contradiction this code has no business resolving.
+ *
+ * @param {"process" | "thread"} scope
+ * @param {{ rss: number, heapTotal: number, external: number, arrayBuffers: number }} memory
+ * @returns {Record<string, number>}
+ */
+export function watchedFigures(scope, memory) {
+  if (scope === "thread") {
+    return {
+      heap: memory.heapTotal ?? 0,
+      external: memory.external ?? 0,
+      buffers: memory.arrayBuffers ?? 0
+    };
+  }
+  return { rss: memory.rss ?? 0 };
+}
+
 /**
  * Whether this reading is worth writing down, and why.
  *
@@ -397,11 +436,14 @@ export function readingIsWorthWriting({
  * @param {number} [options.snapshotFloorBytes]
  * @param {number} [options.snapshotGrowthBytes]
  * @param {number} [options.keepSnapshots] - Newest to keep; zero keeps all.
+ * @param {() => string} [options.readExtra] - Figures to append to the line,
+ *   read at the same instant as the memory itself.
  * @returns {{ stop: () => void }}
  */
 export function startMemoryReport({
   log,
   readStores,
+  readExtra,
   scope = "process",
   label = "",
   diskPath = "",
@@ -414,7 +456,8 @@ export function startMemoryReport({
   keepSnapshots = 0
 }) {
   let highWater = 0;
-  let lastWrittenBytes = 0;
+  /** @type {Record<string, number>} */
+  let lastWritten = {};
   let lastWrittenAt = 0;
   // The process watches what the kernel kills it for; a thread watches what the
   // runtime kills IT for, which is its own heap and not the process's resident
@@ -472,25 +515,35 @@ export function startMemoryReport({
       }
       const processMemory = readProcessMemory();
       const watched = watchedOf(processMemory);
+      const figures = watchedFigures(scope, processMemory);
       const now = Date.now();
-      const write = readingIsWorthWriting({
-        watchedBytes: watched,
-        lastWrittenBytes,
-        sinceWrittenMs: lastWrittenAt === 0 ? Number.POSITIVE_INFINITY : now - lastWrittenAt,
+      const sinceWrittenMs = lastWrittenAt === 0 ? Number.POSITIVE_INFINITY : now - lastWrittenAt;
+      const write = Object.entries(figures).some(([name, bytes]) => readingIsWorthWriting({
+        watchedBytes: bytes,
+        lastWrittenBytes: lastWritten[name] ?? 0,
+        sinceWrittenMs,
         changeBytes,
         quietMs
-      });
+      }));
 
       let anonymousBytes = null;
-      if (scope === "thread") {
-        if (write) {
-          log(describeMemory({ scope, label, process: processMemory, stores }));
+      if (write) {
+        let extra = "";
+        try {
+          extra = typeof readExtra === "function" ? readExtra() ?? "" : "";
+        } catch {
+          // silent-ok: a caller's own figures are worth less than the line they
+          // would have taken down with them.
         }
-      } else {
-        const { bytes, measured } = await availableMemory();
-        anonymousBytes = await readAnonymousMemory();
-        const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
-        if (write) {
+        if (scope === "thread") {
+          log(describeMemory({ scope, label, process: processMemory, stores, extra }));
+        } else {
+          // Read only when the line is written. `smaps` is one entry per
+          // mapping and a busy process has thousands; the rollup and
+          // `/proc/meminfo` are single lines but still walk page tables, and
+          // the reading now happens once a second rather than once a minute.
+          const { bytes, measured } = await availableMemory();
+          anonymousBytes = await readAnonymousMemory();
           log(describeMemory({
             scope,
             label,
@@ -498,17 +551,13 @@ export function startMemoryReport({
             availableBytes: bytes,
             availableMeasured: measured,
             anonymousBytes,
-            // Read only when the line is written: `smaps` is one entry per
-            // mapping and a busy process has thousands, which is a different
-            // cost from the rollup's single line.
             mappings: await readMappingSummary(),
-            diskFreeBytes,
-            stores
+            diskFreeBytes: diskPath ? await readDiskFree(diskPath) : null,
+            stores,
+            extra
           }));
         }
-      }
-      if (write) {
-        lastWrittenBytes = watched;
+        lastWritten = figures;
         lastWrittenAt = now;
       }
 
@@ -524,6 +573,9 @@ export function startMemoryReport({
         highWater = watched;
         await takeSnapshot(watched, "a new high-water");
       }
+      // Under `write` by construction: `anonymousBytes` is only read when the
+      // line is, and at one reading a second an unconditional warning would be
+      // a line a second for as long as the process stayed large.
       if (scope !== "thread" && anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
         log(`memory: high rss=${megabytes(processMemory.rss)} anon=${megabytes(anonymousBytes)} heap=${megabytes(processMemory.heapUsed)} — watch for OOM`);
       }

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

@@ -174,11 +174,31 @@ export class PieceLru {
    * @returns {number | null}
    */
   evictionCandidate() {
+    return this.evictionChoice().index;
+  }
+
+  /**
+   * The same choice, with the two facts that say whether the store is working
+   * or thrashing: whether protection had to yield, and how far the victim was
+   * from the nearest piece a reader declared it wants.
+   *
+   * Evicting a stale piece nobody asked for is the store doing its job.
+   * Evicting a piece inside a reader's own declared window is the store being
+   * asked to hold more than it has room for, and it comes back from disk
+   * moments later — 6565 spills and 7575 revivals in 44 minutes on
+   * 2026-09-02, with only 53.6% of reads served from memory. Nothing recorded
+   * which of the two was happening (roadmap item 9).
+   *
+   * @returns {{ index: number | null, protectionYielded: boolean, distance: number }}
+   *   `distance` is in pieces from the nearest declared window, zero when the
+   *   victim is inside one, and -1 when no reader has declared anything.
+   */
+  evictionChoice() {
     // First choice: the least recently used piece nobody is reading and nobody
     // is about to read.
     for (const index of this.#order) {
       if (!this.#pins.has(index) && !this.#isProtected(index)) {
-        return index;
+        return { index, protectionYielded: false, distance: this.#distanceToWindow(index) };
       }
     }
     // Nothing spare left. Protection yields — it is a preference, and refusing
@@ -186,10 +206,66 @@ export class PieceLru {
     // yield: a piece being read now cannot have its memory taken away.
     for (const index of this.#order) {
       if (!this.#pins.has(index)) {
-        return index;
+        return { index, protectionYielded: true, distance: this.#distanceToWindow(index) };
+      }
+    }
+    return { index: null, protectionYielded: false, distance: -1 };
+  }
+
+  /**
+   * How many pieces the live readers between them are asking to keep, against
+   * how many this store may hold.
+   *
+   * The union, not the sum: two readers of one file overlap, and counting the
+   * overlap twice would say the store is short when it is not. This is the
+   * comparison that decides whether thrashing is a policy fault or arithmetic —
+   * a union wider than the capacity cannot be held however the eviction is
+   * ordered.
+   *
+   * @returns {{ readers: number, unionPieces: number, widestPieces: number, capacity: number }}
+   */
+  demand() {
+    const ranges = [...this.#protected.values()]
+      .map((range) => ({ from: range.from, to: range.to }))
+      .sort((left, right) => left.from - right.from);
+    let unionPieces = 0;
+    let widestPieces = 0;
+    let coveredTo = -Infinity;
+    for (const range of ranges) {
+      const width = range.to - range.from + 1;
+      widestPieces = Math.max(widestPieces, width);
+      const from = Math.max(range.from, coveredTo + 1);
+      if (range.to >= from) {
+        unionPieces += range.to - from + 1;
+        coveredTo = range.to;
+      }
+    }
+    return {
+      readers: ranges.length,
+      unionPieces,
+      widestPieces,
+      capacity: this.#capacity
+    };
+  }
+
+  /**
+   * Pieces from `index` to the nearest declared window, zero inside one and -1
+   * when nothing is declared.
+   *
+   * @param {number} index
+   * @returns {number}
+   */
+  #distanceToWindow(index) {
+    let nearest = -1;
+    for (const range of this.#protected.values()) {
+      const gap = index < range.from
+        ? range.from - index
+        : index > range.to ? index - range.to : 0;
+      if (nearest === -1 || gap < nearest) {
+        nearest = gap;
       }
     }
-    return null;
+    return nearest;
   }
 
   /**

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

@@ -151,6 +151,32 @@ const MIN_RESIDENT_PIECES = 2;
  * never failing (field 2026-08-31).
  */
 const PINNED_WAIT_MS = 5_000;
+
+/**
+ * How many revival ages are kept for the median. A window, not a history: two
+ * hundred covers several minutes of the busiest session measured (7575
+ * revivals in 44 minutes) and costs two hundred numbers.
+ */
+const REVIVAL_AGE_SAMPLES = 200;
+
+/**
+ * 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
+ * facts and must not print the same.
+ *
+ * @param {number[]} values
+ * @returns {number | null}
+ */
+function median(values) {
+  if (values.length === 0) {
+    return null;
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0
+    ? Math.round((sorted[middle - 1] + sorted[middle]) / 2)
+    : sorted[middle];
+}
 const CLAIM_RETRY_MS = 50;
 
 export class SharedPieceStore {
@@ -191,8 +217,25 @@ export class SharedPieceStore {
     blockedByPins: 0,
     waitedForPins: 0,
     evictedOnRevise: 0,
-    spillFailures: 0
+    spillFailures: 0,
+    // Whether the store is doing its job or being asked to hold more than it
+    // has room for. An eviction that had to take a piece a reader declared it
+    // wants is the second, and it comes back from disk moments later
+    // (roadmap item 9).
+    evictedProtected: 0,
+    evictedDistanceSum: 0,
+    evictedWithDistance: 0
   };
+  /** Piece index → when it was written out, for the age it comes back at. */
+  #spilledAt = new Map();
+  /**
+   * Ages, in milliseconds, of the last revivals — bounded, because the figure
+   * wanted is a median and not a history. A piece that comes back seconds
+   * after it left should not have left.
+   *
+   * @type {number[]}
+   */
+  #revivalAges = [];
 
   constructor(chunkLength, options = {}) {
     if (!Number.isInteger(chunkLength) || chunkLength < 1) {
@@ -244,6 +287,14 @@ export class SharedPieceStore {
       outstanding: this.#outstandingPieces,
       spilled: this.#disk.size,
       spilledBytes: this.#disk.size * this.#chunkLength,
+      // What the readers between them are asking this store to keep, against
+      // what it may hold. A union wider than the capacity cannot be held
+      // however the eviction is ordered, and that is the difference between a
+      // policy to fix and arithmetic to accept (roadmap item 9).
+      demand: this.#lru.demand(),
+      revivalAgeMedianMs: median(this.#revivalAges),
+      revivalAgeSamples: this.#revivalAges.length,
+      revivedWithinFiveSeconds: this.#revivalAges.filter((age) => age <= 5_000).length,
       ...this.#counters
     };
   }
@@ -263,7 +314,7 @@ export class SharedPieceStore {
     // old growable pool. Eagerly evict excess to honour the new ceiling.
     let evicted = 0;
     while (this.#buffers.size > this.#growthCeiling) {
-      const victim = this.#lru.evictionCandidate();
+      const { index: victim, protectionYielded, distance } = this.#lru.evictionChoice();
       if (victim === null) {
         break;
       }
@@ -276,6 +327,7 @@ export class SharedPieceStore {
       this.#lru.remove(victim);
       evicted += 1;
       this.#counters.evictedOnRevise += 1;
+      this.#noteEviction(protectionYielded, distance);
       // Nobody awaits this spill, so its failure has to end here. Rethrowing
       // made it an unhandled rejection, and an unhandled rejection in the
       // torrent worker ends the thread — a second way to lose the torrent
@@ -421,6 +473,7 @@ export class SharedPieceStore {
     const spill = this.#disk.write(index, bytes).then(
       () => {
         this.#counters.spills += 1;
+        this.#spilledAt.set(index, Date.now());
         this.#evicting.delete(index);
         this.#noteProgress();
       },
@@ -440,6 +493,48 @@ export class SharedPieceStore {
     this.#wake();
   }
 
+  /**
+   * Record how long a piece stayed on disk before it was wanted again.
+   *
+   * A piece that comes back seconds after it left was evicted from a working
+   * set that does not fit, and the write and the read were both waste. Kept as
+   * a bounded window of ages because the figure wanted is a median, not a
+   * history.
+   *
+   * @param {number} index
+   * @returns {void}
+   */
+  #noteRevival(index) {
+    const spilledAt = this.#spilledAt.get(index);
+    if (spilledAt === undefined) {
+      return;
+    }
+    this.#spilledAt.delete(index);
+    this.#revivalAges.push(Date.now() - spilledAt);
+    if (this.#revivalAges.length > REVIVAL_AGE_SAMPLES) {
+      this.#revivalAges.shift();
+    }
+  }
+
+  /**
+   * Record what an eviction had to take.
+   *
+   * @param {boolean} protectionYielded - The victim was inside a window a
+   *   reader had declared, and was taken anyway because nothing else was free.
+   * @param {number} distance - Pieces from the nearest declared window, -1 when
+   *   no reader declared one.
+   * @returns {void}
+   */
+  #noteEviction(protectionYielded, distance) {
+    if (protectionYielded) {
+      this.#counters.evictedProtected += 1;
+    }
+    if (distance >= 0) {
+      this.#counters.evictedDistanceSum += distance;
+      this.#counters.evictedWithDistance += 1;
+    }
+  }
+
   #wake() {
     const waiting = this.#waiters;
     this.#waiters = [];
@@ -456,7 +551,7 @@ export class SharedPieceStore {
       return true;
     }
 
-    const victim = this.#lru.evictionCandidate();
+    const { index: victim, protectionYielded, distance } = this.#lru.evictionChoice();
     if (victim === null) {
       // Nothing may leave. Wait while the store is still MOVING — a spill
       // completing, a piece admitted, a pin released — and give up when it has
@@ -491,6 +586,7 @@ export class SharedPieceStore {
     this.#buffers.delete(victim);
     this.#lru.remove(victim);
     this.#outstandingPieces += 1;
+    this.#noteEviction(protectionYielded, distance);
 
     try {
       await this.#spill(victim, victimBuffer);
@@ -538,6 +634,7 @@ export class SharedPieceStore {
       this.#registerPiece(index, target);
       this.#counters.fromDisk += 1;
       this.#counters.revivals += 1;
+      this.#noteRevival(index);
       return target;
     } finally {
       release();
@@ -593,6 +690,7 @@ export class SharedPieceStore {
       await spill.catch(() => undefined);
     }
     this.#disk.forget(index);
+    this.#spilledAt.delete(index);
   }
 
   put(index, bytes, callback = () => undefined) {
@@ -707,6 +805,7 @@ export class SharedPieceStore {
     this.#closed = true;
     liveStores.delete(this);
     this.#buffers.clear();
+    this.#spilledAt.clear();
     // Whoever is waiting for a slot is woken and finds the store closed, which
     // is an error they can report. Left asleep they simply never returned.
     this.#wake();
@@ -717,6 +816,7 @@ export class SharedPieceStore {
     this.#closed = true;
     liveStores.delete(this);
     this.#buffers.clear();
+    this.#spilledAt.clear();
     this.#wake();
     this.#disk.destroy().then(() => callback(null), (error) => callback(error));
   }

package/services/torrent-worker/worker.js

@@ -522,6 +522,12 @@ parentPort.on("message", async (message) => {
 startMemoryReport({
   log,
   readStores: collectStoreStats,
+  // Beside the isolate's own figures, and on the SAME line, because the
+  // question they answer together is whether the off-heap mass is buffers this
+  // thread still refers to or buffers the collector has not reached yet. On
+  // separate timers the two were up to a minute apart and could not be
+  // compared at all (roadmap item 2).
+  readExtra: describePieceBuffers,
   scope: "thread",
   label: "torrent worker",
   intervalMs: WORKER_MEMORY_SAMPLE_MS,
@@ -559,7 +565,10 @@ setInterval(() => {
     }
   }
   for (const stats of collectStoreStats()) {
-    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}/${stats.evictedOnRevise}/${stats.spillFailures}`;
+    const signature =
+      `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/` +
+      `${stats.blockedByPins}/${stats.evictedOnRevise}/${stats.spillFailures}/` +
+      `${stats.evictedProtected}/${stats.demand?.unionPieces ?? 0}`;
     if (lastReported.get(stats.name) === signature) {
       continue;
     }
@@ -580,23 +589,60 @@ setInterval(() => {
       (stats.spillFailures > 0 ? ` spill-failures=${stats.spillFailures}` : "") +
       (stats.outstanding > 0 ? ` outstanding=${stats.outstanding}` : "")
     );
+    // Why it spills, on its own line because it is a different question from
+    // how much it holds. Three facts, and between them they say whether the
+    // thrashing is a policy to fix or arithmetic to accept: what the readers
+    // together are asking to keep against what the store may hold; how many
+    // evictions had to take a piece a reader had declared it wants; and how
+    // long a piece stayed on disk before it was wanted back. On 2026-09-02 a
+    // session did 6565 spills and 7575 revivals with 53.6% of reads served
+    // from memory, and nothing recorded which of the three was the cause
+    // (roadmap item 9).
+    const demand = stats.demand;
+    if (demand && demand.readers > 0) {
+      const age = stats.revivalAgeMedianMs;
+      log(
+        `piece-store "${stats.name.slice(0, 40)}" demand: ${demand.readers} reader(s) want ` +
+        `${demand.unionPieces} piece(s) of ${demand.capacity} the store may hold ` +
+        `(widest window ${demand.widestPieces})` +
+        (stats.evictedProtected > 0
+          ? `; ${stats.evictedProtected} of ${stats.spills} eviction(s) took a piece a reader had declared`
+          : "; no eviction has taken a declared piece") +
+        (stats.evictedWithDistance > 0
+          ? `, a victim lay ${(stats.evictedDistanceSum / stats.evictedWithDistance).toFixed(1)} ` +
+            "piece(s) from the nearest window on average"
+          : "") +
+        (age === null
+          ? "; nothing has come back from disk yet"
+          : `; a revived piece had been on disk ${(age / 1000).toFixed(1)}s (median of ` +
+            `${stats.revivalAgeSamples}, ${stats.revivedWithinFiveSeconds} of them within 5s)`)
+      );
+    }
   }
-  // Not per store: the collector is per thread, and the question it answers —
-  // is anything of ours outliving a piece — is about the thread. Printed
-  // whenever the two disagree by more than the pieces actually held, which is
-  // the only shape worth looking at (roadmap item 2).
+}, STORE_REPORT_INTERVAL_MS).unref();
+
+/**
+ * The piece buffers this thread has let go of against the ones it still holds.
+ *
+ * Not per store: the collector is per thread, and the question is about the
+ * thread. A gap that keeps widening means a reference of ours outlives the
+ * piece; a gap that does not means whatever grows is below us, in the
+ * allocator or in buffers the collector has not reached.
+ *
+ * @returns {string}
+ */
+function describePieceBuffers() {
   const collection = pieceBufferCollection();
-  const outstandingBuffers = collection.released - collection.collected;
-  const heldNow = collectStoreStats().reduce((sum, stats) => sum + (stats.resident || 0), 0);
-  if (outstandingBuffers > heldNow) {
-    log(
-      `piece buffers: ${collection.released} let go, ${collection.collected} collected — ` +
-      `${outstandingBuffers} still alive against ${heldNow} the store holds. ` +
-      "A gap that keeps widening means a reference of ours outlives the piece; " +
-      "a gap that does not means whatever grows is below us, in the allocator"
-    );
+  if (collection.released === 0) {
+    return "";
   }
-}, STORE_REPORT_INTERVAL_MS).unref();
+  const alive = collection.released - collection.collected;
+  const held = collectStoreStats().reduce((sum, stats) => sum + (stats.resident || 0), 0);
+  return (
+    `piece buffers ${collection.released} let go, ${collection.collected} collected, ` +
+    `${alive} still alive against ${held} the store holds`
+  );
+}
 
 /**
  * Walk subtitle cues for every actively-read file of one torrent, and PUSH

package/test/memory-budget.test.js

@@ -1,7 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { describeMemory, readingIsWorthWriting, summariseMappings } from "../services/memory-report.js";
+import {
+  describeMemory,
+  readingIsWorthWriting,
+  summariseMappings,
+  watchedFigures
+} from "../services/memory-report.js";
 import {
   budgetForNewStore,
   SharedPieceStore,
@@ -287,3 +292,55 @@ test("the mapping shape is said in the line, and left out when it is not known",
   });
   assert.ok(!withoutShape.includes("mappings="), "an unread breakdown is absent, not zeroed");
 });
+
+test("a thread's line is earned by any of its three figures, not by the heap alone", () => {
+  // 2026-09-02, the session that ended in two out-of-memory kills: the worker's
+  // heap stood at 33-45 MB for the whole of it while its buffers went from 130
+  // to 950 MB. Watching the heap alone, nothing ever earned a line and every
+  // reading of the quantity that grew came out on the quiet minute.
+  const before = watchedFigures("thread", {
+    rss: 0, heapTotal: 38 * MEGABYTE, external: 14 * MEGABYTE, arrayBuffers: 130 * MEGABYTE
+  });
+  const after = watchedFigures("thread", {
+    rss: 0, heapTotal: 38 * MEGABYTE, external: 14 * MEGABYTE, arrayBuffers: 515 * MEGABYTE
+  });
+  assert.equal(before.heap, after.heap, "the heap is what did NOT move");
+
+  const moved = Object.entries(after).some(([name, bytes]) => readingIsWorthWriting({
+    watchedBytes: bytes,
+    lastWrittenBytes: before[name],
+    sinceWrittenMs: 1_000,
+    changeBytes: 25 * MEGABYTE,
+    quietMs: 60_000
+  }));
+  assert.equal(moved, true, "buffers growing by 385 MB earns a line of its own");
+
+  assert.deepEqual(
+    Object.keys(watchedFigures("process", { rss: 5, heapTotal: 1, external: 2, arrayBuffers: 3 })),
+    ["rss"],
+    "a process is killed for its resident memory and watches that"
+  );
+});
+
+test("figures a caller reads for itself land on the same line as the memory", () => {
+  const line = describeMemory({
+    scope: "thread",
+    label: "torrent worker",
+    process: {
+      rss: 0, heapUsed: 34 * MEGABYTE, heapTotal: 46 * MEGABYTE,
+      external: 54 * MEGABYTE, arrayBuffers: 393 * MEGABYTE, heapLimit: 0
+    },
+    stores: [],
+    extra: "piece buffers 21544 let go, 21482 collected, 62 still alive against 53 the store holds"
+  });
+  assert.match(line, /arrayBuffers=393MB/);
+  assert.match(line, /62 still alive against 53 the store holds$/);
+  assert.doesNotMatch(
+    describeMemory({
+      scope: "thread",
+      process: { rss: 0, heapUsed: 1, heapTotal: 2, external: 3, arrayBuffers: 4, heapLimit: 0 }
+    }),
+    /;\s*$/,
+    "nothing to add leaves no dangling separator"
+  );
+});