@torrent-tv/proxy 2.68.0 → 2.69.1

package/package.json

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

package/routes/api/subtitles/get.js

@@ -25,7 +25,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { detectLanguage } from "../../../services/language-detect.js";
+import { detectLanguageFromVtt } from "../../../services/language-detect.js";
 import { SubtitleController } from "../../../services/controllers/SubtitleController.js";
 import { logger } from "../../../utils/logger.js";
 
@@ -137,7 +137,7 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
  * Extractions by `sourceKey:fileIndex:trackIndex`, so the scan happens once per
  * track however many times it is asked for.
  *
- * @type {Map<string, { state: "running" | "done" | "failed", body?: Buffer, language?: string, error?: string }>}
+ * @type {Map<string, { state: "running" | "done" | "failed", body?: Buffer, language?: { code: string, name: string } | null, error?: string }>}
  */
 const extractions = new Map();
 
@@ -190,7 +190,12 @@ function startExtraction({ key, ffmpegBin, localBaseUrl, sourceKey, fileIndex, t
       logger.warn(`subtitles ${key}: nothing produced after ${seconds}s`);
       return;
     }
-    extractions.set(key, { state: "done", body, language: detectLanguage(String(body.subarray(0, 4096))) });
+    // The whole document, decoded as one string, and only its cue text.
+    // Detecting on the first 4096 BYTES was wrong twice over: a byte cut lands
+    // mid-character on any non-Latin track, and most of those bytes are
+    // timestamps rather than words. This runs once per track in the background,
+    // so reading all of it costs nothing anybody waits for.
+    extractions.set(key, { state: "done", body, language: detectLanguageFromVtt(body.toString("utf8")) });
     logger.info(`subtitles ${key}: ${body.length} bytes in ${seconds}s`);
   };
   ffmpeg.once("close", settle);

package/services/controllers/SubtitleController.js

@@ -9,7 +9,7 @@
 
 import { subtitleOrchestrator } from "../orchestrators/SubtitleOrchestrator.js";
 import { convertSubtitleToVtt, decodeSubtitleBytes } from "../subtitle-convert.js";
-import { detectLanguage } from "../language-detect.js";
+import { detectLanguage, detectLanguageFromVtt } from "../language-detect.js";
 import { finalizeCues } from "../torrent-worker/subtitle-cues.js";
 
 const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
@@ -75,7 +75,12 @@ export class SubtitleController {
         const text = decodeSubtitleBytes(bytes);
         const vtt = convertSubtitleToVtt(text, ext);
         if (!vtt) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
-        return { vtt, language: detectLanguage(text), headers: {} };
+        // The language is read from the CONVERTED document, not from the file.
+        // The conversion has already dropped everything that is not the words —
+        // and on an ASS file that is half of it, in Latin letters, which is what
+        // made a Russian track answer `en` (field 2026-09-01, and the whole of
+        // `research/subtitle-language-ass-markup-2026-09-01.md`).
+        return { vtt, language: detectLanguageFromVtt(vtt), headers: {} };
       } catch (e) {
         return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
       } finally {
@@ -105,8 +110,23 @@ export class SubtitleController {
       const cursor = held.cues.reduce((h, c) => Math.max(h, Number(c.seq) || 0), 0);
       const fresh = Number.isInteger(since) ? held.cues.filter((c) => (Number(c.seq) || 0) > since)
         : Number.isFinite(after) ? held.cues.filter((c) => c.startSeconds > after) : held.cues;
-      const vtt = cuesToVtt(fresh, held.track?.codecId ?? track?.codecId ?? "");
-      const language = held.cues.length > 0 ? detectLanguage(held.cues.map((c) => c.text).join("\n")) : null;
+      const codecId = held.track?.codecId ?? track?.codecId ?? "";
+      const vtt = cuesToVtt(fresh, codecId);
+      // Two things this reads, and each of them was wrong before 2.68.1.
+      //
+      // It reads the cues through `finalizeCues`, which is what turns an ASS
+      // dialogue row into the words: a raw cue carries the nine
+      // comma-separated fields of the row and its `{\…}` override groups, and
+      // those are Latin on a Russian track. Detecting on the raw text is the
+      // same fault as detecting on a whole `.ass` file, one layer down.
+      //
+      // And it reads EVERY cue held so far, not the `fresh` subset that is
+      // being sent. A re-subscription after a reconnect asks only for what this
+      // page missed, which can be three lines, and three lines are not a sample
+      // of a language.
+      const language = detectLanguage(
+        finalizeCues(held.cues, codecId).map((cue) => cue.text).join("\n")
+      );
       return {
         vtt,
         language,

package/services/data-channel-handler.js

@@ -590,10 +590,12 @@ export function createDataChannelHandler({
    * are tiny (kilobytes at most for a whole track), so this is one message,
    * not a stream.
    *
-   * @param {{ sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string, cursor: number }} event
+   * @param {{ sourceKey: string, fileIndex: number, trackIndex: number, cues: object[],
+   *   language: string, detectedLanguage: { code: string, name: string } | null,
+   *   cursor: number }} event
    * @returns {void}
    */
-  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language, cursor }) {
+  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language, detectedLanguage, cursor }) {
     const set = subtitleSubscribers.get(`${sourceKey}:${fileIndex}`);
     if (!set || set.size === 0) {
       log(
@@ -602,7 +604,7 @@ export function createDataChannelHandler({
       );
       return;
     }
-    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language, cursor };
+    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language, detectedLanguage, cursor };
     const total = set.size;
     let sent = 0;
     for (const channel of set) {

package/services/language-detect.js

@@ -54,20 +54,175 @@ const LANG_3_TO_1 = {
 
 const ONLY = Object.keys(LANG_3_TO_1);
 
+/**
+ * The least text, in characters, that supports an answer of each language.
+ *
+ * MEASURED, not chosen — `research/franc-boundary-2026-09-02.md`. Method:
+ * Wikipedia extracts per language (deliberately NOT the UDHR, which is what
+ * franc's own profiles are built from and would read optimistically), 120
+ * windows cut at random from them at each length of a ladder from 40 to 1300
+ * characters, and the figure recorded is the shortest length from which franc
+ * answered correctly in at least 95 % of trials AND kept doing so at every
+ * longer length measured.
+ *
+ * Why it is per language rather than one number: the answer is not equally hard
+ * to reach, and the spread is fivefold. Greek and Korean settle at 40
+ * characters because their script settles it; English needs 130; Russian and
+ * Czech need 650, because each competes with neighbours in this very list for
+ * the same trigrams — Russian with Bulgarian, Serbian and Ukrainian, Czech with
+ * Slovak.
+ *
+ * Two languages are deliberately ABSENT. Swedish and Chinese did not settle
+ * anywhere in the ladder on the corpora collected, so no figure for them is
+ * measured and none is invented; they take the fallback below.
+ *
+ * A language with no entry gets the WORST measured figure. That is the
+ * conservative reading and it is still a measurement rather than a guess: it
+ * says "no better than the hardest language we have measured".
+ *
+ * @type {Record<string, number>}
+ */
+const LEAST_TEXT = {
+  bel: 100,
+  bul: 80,
+  ces: 650,
+  deu: 200,
+  ell: 40,
+  eng: 130,
+  fra: 80,
+  heb: 60,
+  ita: 160,
+  kor: 40,
+  nld: 130,
+  pol: 200,
+  por: 200,
+  rus: 650,
+  spa: 100,
+  srp: 100,
+  tur: 160,
+  ukr: 250
+};
+
+/** The worst measured figure, used for any language not in the table. */
+const LEAST_TEXT_WORST = Math.max(...Object.values(LEAST_TEXT), 0);
+
+/** franc's own floor: below this it is not asked at all. */
+const FRANC_FLOOR = 15;
+
+/** One space between words, nothing else — the form every figure above is in. */
+function normalise(text) {
+  return typeof text === "string" ? text.replace(/\s+/g, " ").trim() : "";
+}
+
+/**
+ * franc's answer for this text, or null when it has none.
+ *
+ * @param {string} text
+ * @returns {string | null} ISO 639-3.
+ */
+function ask(text) {
+  if (text.length < FRANC_FLOOR) {
+    return null;
+  }
+  const iso3 = franc(text, { only: ONLY, minLength: FRANC_FLOOR });
+  return iso3 === "und" ? null : iso3;
+}
+
 /**
  * Best-effort detect the language of subtitle text.
  *
- * @param {string} text - Decoded subtitle text (VTT/SRT/ASS — franc ignores markup well enough).
+ * **Give this the words a viewer reads and nothing else.** franc scores letter
+ * trigrams over the whole string it is handed, so anything around the words
+ * competes with them. An ASS file is markup by half: measured 2026-09-01 on
+ * `[HorribleSubs] Drifters - 03 [1080p].ass`, 5040 Latin characters of Aegisub
+ * headers, style and font names, `Format:`/`Dialogue:` field prefixes and
+ * `{\…}` override groups against 5983 Cyrillic characters of dialogue —
+ * `franc(the file) = eng`, `franc(the dialogue) = rus`. The proxy had already
+ * built the markup-free text and detected on the file anyway, so a Russian
+ * track was offered to the viewer as English.
+ *
+ * `detectLanguageFromVtt` below is the safe entry point for a whole document;
+ * this one is for text that is already only text.
+ *
+ * @param {string} text - Subtitle text with no markup left in it.
  * @returns {{ code: string, name: string } | null} Detected language, or null when uncertain.
  */
 export function detectLanguage(text) {
-  if (typeof text !== "string" || text.trim().length < 15) {
+  const words = normalise(text);
+  if (words.length < FRANC_FLOOR) {
+    return null;
+  }
+  const candidate = ask(words);
+  if (candidate === null) {
+    return null;
+  }
+  // Enough text to support THIS answer. The figure is the language's own,
+  // because the languages are not alike: Russian shares its trigrams with
+  // Bulgarian, Serbian and Ukrainian and needs several times what English does.
+  if (words.length < (LEAST_TEXT[candidate] ?? LEAST_TEXT_WORST)) {
     return null;
   }
-  // Restrict to plausible subtitle languages; require a little text.
-  const iso3 = franc(text, { only: ONLY, minLength: 15 });
-  if (iso3 === "und") {
+  // And an answer that does not survive losing half the text was an accident of
+  // where the text happened to stop, not a reading of it. Free — franc costs
+  // about 2 ms whatever the size, measured — and it needs no figure of its own,
+  // because the test is taken on the text in hand.
+  const middle = Math.floor(words.length / 2);
+  if (ask(words.slice(0, middle)) !== candidate || ask(words.slice(middle)) !== candidate) {
     return null;
   }
-  return LANG_3_TO_1[iso3] ?? null;
+  return LANG_3_TO_1[candidate] ?? null;
+}
+
+/**
+ * The words of a WebVTT document — what a viewer reads, with everything the
+ * format puts around them removed.
+ *
+ * A WebVTT document is a series of blocks separated by blank lines. A block
+ * that holds a timing line (`00:00:12.060 --> 00:00:13.270`) is a cue, and the
+ * lines after that timing line are its text; the lines before it are the cue's
+ * optional identifier. A block with NO timing line is the `WEBVTT` header or a
+ * `NOTE` / `STYLE` / `REGION` block, and none of those is anybody's language.
+ * That one rule removes the identifiers, the timings and the headers together.
+ *
+ * What is left can still carry WebVTT's own inline markup — `<v Speaker>`,
+ * `<i>`, `<c.yellow>` — and character references. Both are dropped: a speaker
+ * name and a class name are written in whatever language the releaser's tooling
+ * used, which is not the language of the film.
+ *
+ * @param {string} vtt - A WebVTT document.
+ * @returns {string} The cue text, blocks joined by newlines.
+ */
+export function cueTextOfVtt(vtt) {
+  if (typeof vtt !== "string") {
+    return "";
+  }
+  const blocks = vtt.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split(/\n{2,}/);
+  const spoken = [];
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    const timingAt = lines.findIndex((line) => line.includes("-->"));
+    if (timingAt < 0) {
+      continue;
+    }
+    for (const line of lines.slice(timingAt + 1)) {
+      spoken.push(line);
+    }
+  }
+  return spoken
+    .join("\n")
+    .replace(/<[^>]*>/g, "")
+    // A character reference stands for one character and never for a word, so a
+    // space in its place keeps the neighbouring words apart and adds nothing.
+    .replace(/&[a-z]+;|&#\d+;|&#x[0-9a-f]+;/gi, " ")
+    .trim();
+}
+
+/**
+ * Detect the language of a WebVTT document, reading only its cue text.
+ *
+ * @param {string} vtt - A WebVTT document.
+ * @returns {{ code: string, name: string } | null} Detected language, or null when uncertain.
+ */
+export function detectLanguageFromVtt(vtt) {
+  return detectLanguage(cueTextOfVtt(vtt));
 }

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/torrent-worker/subtitle-cues.js

@@ -20,6 +20,7 @@
 import { readSubtitlePlan, harvestCluster } from "../container-index/matroska-subtitles.js";
 import { decodeSubtitleSample, readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
 import { iterateElements } from "../container-index/ebml-reader.js";
+import { detectLanguage } from "../language-detect.js";
 import { logger } from "../../utils/logger.js";
 
 /** Enough to read any cluster's own element header. */
@@ -483,12 +484,23 @@ export async function warmSubtitleCues(torrent, fileIndex, sourceKey) {
     }
     const highest = newCues.reduce((max, cue) => Math.max(max, Number(cue.seq) || 0), since);
     state.pushed.set(track.trackNumber, highest);
-    const cues = finalizeCues(newCues, held.track?.codecId ?? track.codecId);
+    const codecId = held.track?.codecId ?? track.codecId;
+    const cues = finalizeCues(newCues, codecId);
     fresh.push({
       // ffmpeg's own numbering, which is the only one the browser knows.
       trackIndex: Number.isInteger(track.declaredIndex) ? track.declaredIndex : order,
       cues,
       language: held.track?.language ?? "",
+      // What the CUES say the language is, re-read on every push over every cue
+      // held so far rather than over this batch. A track whose container states
+      // no language is unreadable at the start of a session — a handful of cues
+      // is not a sample of a language, and the detector refuses to answer on one
+      // — so the answer has to be re-taken as the film downloads, and the label
+      // moved when it arrives. Costs about 6 ms per push, measured; pushes
+      // arrive about once a second per file being read.
+      detectedLanguage: detectLanguage(
+        finalizeCues(held.cues, codecId).map((cue) => cue.text).join("\n")
+      ),
       // Where the browser should resume from if it has to ask again — after a
       // reconnect, which loses the subscription these pushes ride on.
       cursor: highest,

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,
@@ -581,22 +587,30 @@ setInterval(() => {
       (stats.outstanding > 0 ? ` outstanding=${stats.outstanding}` : "")
     );
   }
-  // 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"
+  );
+});