@torrent-tv/proxy 2.58.2 → 2.59.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.59.0
+
+- **New**: a wedge (roadmap item 11) is now declared, and evidence gathered for it automatically, even when the small-message shape means nothing ever queues. The only trigger that existed (`wedgeIsCertain`) requires a nonzero channel queue — confirmed 2026-08-28 by reading the code, not assuming it from the note: `bufferedAmount()` reads 0 the instant our bytes reach usrsctp, whatever usrsctp does with them next, so a wedge carrying only probes and control messages never set it and the last real episode's ring was never saved automatically. The delivery probe already computes a queue-independent verdict (`association-stopped`); it is now wired to the same evidence-gathering, gated on its OWN certainty rule rather than the raw verdict — a connection can sit behind by a bounded, non-growing amount for minutes (measured the same day, a backgrounded tab: gap held at 6-7 probes for 95+ seconds while `seen` kept climbing right along with `sent`) without anything being wrong. What a true wedge shows instead, checked against a session already known to be one: `seen` frozen at one value for over a minute while `sent` climbs unbounded. `probeWedgeIsCertain` asks whether the counter has stopped moving for longer than this connection's own history says a healthy gap ever takes — the same shape `wedgeIsCertain` already uses, applied to the probe's own counter.
+- **New**: `usrsctp`'s live association state (peer receive window, pending data, retransmission timeout, congestion window) can now be read on either wedge declaration, automatically — `node_datachannel.node` ships unstripped, so the read is a gdb attach against the running process, no rebuild. The walk and its healthy baseline are `research/session-2026-08-27-28-freeze-onset-and-sessions.md`, section 1; the script that performs it ships in the package (`assets/diagnostics/sctpstate.gdb`) instead of surviving only as long as someone remembers to copy it back onto a host after a container is recreated. Nine episodes of this item have lacked exactly this reading.
+
+## 2.58.3
+
+- **New**: the proxy says what it is holding, once a minute — resident memory, heap, external and array buffers, the torrent stores in BYTES, and what the machine has left. It was killed on 2026-08-28 by the kernel's own out-of-memory killer at 2.4 GB resident (`exit code 137`, no core dump, `Out of memory: Killed process ... anon-rss: 2422628kB`) and the log had never recorded a single figure about memory. There was one final reading, taken by the kernel, and no series leading to it.
+- **Fix**: the torrent stores share ONE budget instead of each taking its own. It was per torrent, so two torrents meant two of it, and nothing anywhere asked what the process as a whole was holding. On the film the proxy died under, one store had taken the full 504 MB.
+- **Fix**: that budget is a share of `MemAvailable` rather than of `os.freemem()`. On Linux the second counts only the pages free at that instant, while the kernel deliberately keeps that number low by filling the rest with reclaimable cache — so the share it produced had little to do with what an allocation could actually obtain. The kernel publishes the estimate; we read it.
+- **New**: the piece-store line reports megabytes beside its piece count. The count alone says nothing without the piece size, and the piece size differs per torrent: on that film, "63" meant 504 MB.
+
 ## 2.58.2
 
 - **Fix**: `utp-native` moves to 2.5.3-ttv.8, which removes the whole crash family rather than another instance of it. Nine deaths in a fortnight had one shape — libuv holding a pointer into memory that had gone — because the structs carrying `uv_udp_t`, `uv_timer_t` and `uv_udp_send_t` were allocated by JavaScript as `Buffer.alloc(sizeof(...))`, putting them under the garbage collector while libuv's rule is that they must live until the close or completion callback has run. Every earlier fix reconciled the two owners with a rule and the next release found another way through. The module now allocates and frees that memory itself, at the point libuv has provably finished; JavaScript holds only a token, and freeing points the token at nothing so a late call does nothing instead of faulting. On the environment's own teardown nothing is freed at all — a deliberate leak while the process ends beats touching napi as it goes. Checked on the target: 77 tests pass, and 60 create/serve/destroy cycles leave memory flat.

package/assets/diagnostics/sctpstate.gdb

@@ -0,0 +1,29 @@
+set pagination off
+set confirm off
+set $base = (unsigned long) &system_base_info
+set $hash = *(unsigned long *)($base + 0)
+set $mask = *(unsigned long *)($base + 8)
+printf "asochash=%p mask=%lu\n", $hash, $mask
+set $i = 0
+set $stcb = 0
+while $i <= $mask && $stcb == 0
+  set $head = *(unsigned long *)($hash + $i * 8)
+  if $head != 0
+    set $stcb = $head
+    printf "bucket %lu -> stcb=%p\n", $i, $stcb
+  end
+  set $i = $i + 1
+end
+if $stcb == 0
+  printf "no association found (no viewer connected?)\n"
+else
+  set $sock = *(unsigned long *)($stcb + 0)
+  printf "socket=%p asoc=%p\n", $sock, $stcb + 88
+  set $buf = (unsigned long) malloc(512)
+  set $lenp = (unsigned long) malloc(8)
+  set *(int *)$lenp = 512
+  set $rc = (int) usrsctp_getsockopt($sock, 132, 256, $buf, $lenp)
+  printf "getsockopt rc=%d len=%d\n", $rc, *(int *)$lenp
+  printf "state=%d rwnd=%u unackdata=%u penddata=%u instrms=%u outstrms=%u fragpoint=%u\n", *(int *)($buf+4), *(unsigned int *)($buf+8), *(unsigned short *)($buf+12), *(unsigned short *)($buf+14), *(unsigned short *)($buf+16), *(unsigned short *)($buf+18), *(unsigned int *)($buf+20)
+  printf "primary: state=%d cwnd=%u srtt=%u rto=%u mtu=%u\n", *(int *)($buf+24+4+128), *(unsigned int *)($buf+24+4+128+4), *(unsigned int *)($buf+24+4+128+8), *(unsigned int *)($buf+24+4+128+12), *(unsigned int *)($buf+24+4+128+16)
+end

package/bin/cli.js

@@ -25,6 +25,8 @@ import { createWebRtcManager } from "../services/webrtc-manager.js";
 import { createDataChannelHandler } from "../services/data-channel-handler.js";
 import { pruneCoreDumps } from "../services/core-dumps.js";
 import { adoptOrphanRingFiles, createPacketWitness, pruneWitnessCaptures } from "../services/packet-witness.js";
+import { createUsrsctpStateReader } from "../services/usrsctp-state.js";
+import { startMemoryReport } from "../services/memory-report.js";
 import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
 import { classifyNat } from "../services/nat-classifier.js";
@@ -187,6 +189,9 @@ let webRtcManager = null;
  */
 let packetWitness = null;
 
+/** @type {ReturnType<typeof createUsrsctpStateReader> | null} */
+let usrsctpStateReader = null;
+
 /** @type {ReturnType<typeof createDataChannelHandler> | null} */
 let dataChannelHandler = null;
 
@@ -334,6 +339,18 @@ try {
   // the pruner recognises BEFORE anything starts a new ring over them.
   void adoptOrphanRingFiles(packetWitness.dir).then(() => pruneWitnessCaptures(packetWitness.dir));
 
+  // Reads usrsctp's own association state via gdb the moment a wedge is
+  // declared (roadmap item 11) — no source rebuild, the module ships
+  // unstripped. A host without gdb just never gets a reading, the same way a
+  // host without tcpdump never gets a packet capture.
+  usrsctpStateReader = createUsrsctpStateReader({ log: (message) => logger.info(message) });
+
+  // What this process holds, once a minute. The kernel killed the proxy on
+  // 2026-08-28 at 2.4 GB resident and the log had never said a word about
+  // memory, so the growth that ended in that kill has no shape in any record we
+  // keep. RSS is the figure the OOM killer reads, so RSS is the figure to say.
+  startMemoryReport({ log: (message) => logger.info(message) });
+
   logger.info(`Starting @torrent-tv/proxy v${PROXY_VERSION}`);
   logger.info(`Local stream endpoint: http://${bindHost}:${actualPort}/stream`);
   logger.info(`Advertised direct URL: ${directBaseUrl}`);
@@ -457,7 +474,8 @@ try {
     getTransportSnapshot: (sessionId) => webRtcManager?.getTransportSnapshot(sessionId) ?? null,
     // Records the wire when a queue stays wedged — how the rare one-way
     // transmit death (roadmap item 10, 2026-08-24) gets its evidence.
-    witness: packetWitness
+    witness: packetWitness,
+    usrsctpState: usrsctpStateReader
   });
 
   webRtcManager = createWebRtcManager({

package/package.json

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

package/services/data-channel-handler.js

@@ -159,7 +159,7 @@ export function wedgeIsCertain({ queuedBytes, bytesPerSecond, flatForMs, longest
  * @param {DataChannel} channel
  * @returns {() => void} Stops the watch.
  */
-function makeSendQueueWatcher({ log, getTransportSnapshot, witness }) {
+function makeSendQueueWatcher({ log, getTransportSnapshot, witness, usrsctpState }) {
   // Every channel of one connection reads the SAME transport counters — the
   // snapshot describes the peer connection, not the channel — so the heartbeat
   // belongs to the connection and is printed once for it. Printed per channel
@@ -479,6 +479,14 @@ function makeSendQueueWatcher({ log, getTransportSnapshot, witness }) {
           connection.captureStarted = false;
         }
       }
+      if (usrsctpState && verdict.certain && peerStillSending) {
+        // Its own single-flight and cooldown, independent of the witness's —
+        // one gdb attach per wedge is enough, and a refusal here (already
+        // read, cooling down) costs nothing to retry on the next tick.
+        usrsctpState.maybeRead(
+          `send queue stuck ${queued}B, accepted-byte counter unmoved ${Math.round(flatForMs / 1000)}s`
+        );
+      }
     }, SEND_QUEUE_SAMPLE_MS);
 
     if (typeof timer.unref === "function") {
@@ -526,7 +534,18 @@ export function encodeFrame(idBytes, bytes, done) {
   return frame;
 }
 
-export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapshot, sourceRegistry, witness }) {
+export function createDataChannelHandler({
+  proxyPort,
+  onLog,
+  getTransportSnapshot,
+  sourceRegistry,
+  witness,
+  // Reads usrsctp's own association state (services/usrsctp-state.js) the
+  // moment a wedge is declared, from either detector below. Optional: a host
+  // without gdb simply never gets a reading, same as the witness without
+  // tcpdump.
+  usrsctpState
+}) {
   /**
    * Channels currently interested in one file's subtitle cues, keyed by
    * `sourceKey:fileIndex`. Populated the moment a browser asks for an
@@ -608,13 +627,26 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
   const { watchSendQueue, readDelivery } = makeSendQueueWatcher({
     log: (message) => log(message),
     getTransportSnapshot,
-    witness
+    witness,
+    usrsctpState
   });
   // Numbered probes on every channel, and the browser's echo of what it saw.
   // The proxy's own counters cannot say whether bytes it handed to usrsctp were
   // ever put on the wire; the far end can, and it keeps answering throughout a
   // freeze. See services/delivery-probe.js.
-  const deliveryProbe = createDeliveryProbe({ log: (message) => log(message), readDelivery });
+  //
+  // Also the ONLY wedge signal that does not require a nonzero channel queue —
+  // `wedgeIsCertain` above needs `queuedBytes > 0`, which small, infrequent
+  // traffic never produces (confirmed 2026-08-28: the 2026-08-27 episode's
+  // ring was never saved automatically for exactly this reason). So this is
+  // wired to the same evidence-gathering as the queue watcher.
+  const deliveryProbe = createDeliveryProbe({
+    log: (message) => log(message),
+    readDelivery,
+    getTransportSnapshot,
+    witness,
+    usrsctpState
+  });
 
   /**
    * @param {string} message

package/services/delivery-probe.js

@@ -106,6 +106,32 @@ const ECHO_STALE_FALLBACK_MS = 5_000;
 /** How often the probe state is written to the log while nothing changes. */
 const REPORT_INTERVAL_MS = 5_000;
 
+/**
+ * Whether the `seen` counter has stopped advancing for longer than this
+ * connection's own history says a healthy gap between two advances ever
+ * takes.
+ *
+ * The `association-stopped` verdict alone is not enough to act on: a
+ * connection can sit BEHIND by a bounded, roughly constant amount for
+ * minutes (measured 2026-08-28, session on a backgrounded tab — gap held at
+ * 6-7 probes for 95+ seconds while `seen` kept climbing right along with
+ * `sent`) without anything being wrong. What a true wedge shows instead,
+ * measured the same day against a session already known to be one
+ * (`d85ae4f5`): `seen` FROZEN at one value for over a minute while `sent`
+ * climbs unbounded. So the question is not "is there a gap" but "has the
+ * highest-seen number stopped moving at all, for longer than it has ever
+ * legitimately taken this connection to report an advance" — the same shape
+ * as {@link wedgeIsCertain} in `data-channel-handler.js`, applied to the
+ * probe's own counter instead of the transport's byte counter.
+ *
+ * @param {{ stuckForMs: number, longestHealthySeenGapMs: number, intervalMs?: number }} state
+ * @returns {{ certain: boolean, needMs: number }}
+ */
+export function probeWedgeIsCertain({ stuckForMs, longestHealthySeenGapMs, intervalMs = PROBE_INTERVAL_MS }) {
+  const needMs = Math.max(longestHealthySeenGapMs, intervalMs);
+  return { certain: stuckForMs >= needMs, needMs };
+}
+
 /**
  * One connection's probe state.
  *
@@ -119,6 +145,9 @@ const REPORT_INTERVAL_MS = 5_000;
  * @property {number} echoes     - How many echoes have arrived.
  * @property {string} verdict    - Last verdict reported, so a change is logged at once.
  * @property {number} reportedAt - When the state was last written to the log.
+ * @property {number} lastSeenAdvanceAt - When any label's `seen` value last increased (0 = never yet).
+ * @property {number} longestHealthySeenGapMs - The longest gap between two advances this connection has shown while not flagged as a wedge.
+ * @property {boolean} probeCaptureStarted - One evidence-gathering attempt per wedge; reset once `seen` advances again.
  * @property {ReturnType<typeof setInterval> | null} timer
  */
 
@@ -204,6 +233,11 @@ export function readProbeState(state) {
  * @param {Object} options
  * @param {(message: string) => void} options.log
  * @param {number} [options.intervalMs]
+ * @param {(sessionId: string) => object | null} [options.getTransportSnapshot]
+ *   Needed only to hand the witness a remote endpoint when this probe is the
+ *   one declaring a wedge.
+ * @param {{ maybeCapture: (trigger: object) => boolean }} [options.witness]
+ * @param {{ maybeRead: (reasonText: string) => boolean }} [options.usrsctpState]
  * @returns {{
  *   attach: (sessionId: string, tag: string, label: string, channel: import('node-datachannel').DataChannel) => void,
  *   detach: (sessionId: string, channel: import('node-datachannel').DataChannel) => void,
@@ -211,7 +245,14 @@ export function readProbeState(state) {
  *   dispose: () => void
  * }}
  */
-export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readDelivery }) {
+export function createDeliveryProbe({
+  log,
+  intervalMs = PROBE_INTERVAL_MS,
+  readDelivery,
+  getTransportSnapshot,
+  witness,
+  usrsctpState
+}) {
   /** @type {Map<string, ProbeConnection>} */
   const connections = new Map();
 
@@ -284,6 +325,47 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
       connection.reportedAt = now;
       log(`[dc-probe] ${connection.tag} ${verdict} — ${detail} at=${new Date(now).toISOString()}`);
     }
+
+    // `association-stopped` alone is not certainty — see probeWedgeIsCertain.
+    // A connection that is merely lagging by a bounded amount reaches this
+    // verdict too (a hidden tab's own echo cadence, measured 2026-08-28), and
+    // `seen` keeps advancing right along with it. Only a `seen` value that has
+    // stopped moving ENTIRELY, for longer than this connection has ever shown
+    // as a legitimate gap, is the wedge this exists to catch.
+    const stuckForMs = connection.lastSeenAdvanceAt === 0 ? 0 : now - connection.lastSeenAdvanceAt;
+    if (verdict === "association-stopped") {
+      const { certain, needMs } = probeWedgeIsCertain({
+        stuckForMs,
+        longestHealthySeenGapMs: connection.longestHealthySeenGapMs
+      });
+      if (certain && !connection.probeCaptureStarted) {
+        connection.probeCaptureStarted = true;
+        const reasonText =
+          `probe seen-counter unmoved ${Math.round(stuckForMs / 1000)}s against the ` +
+          `${(needMs / 1000).toFixed(1)}s this connection's own history says is legitimate`;
+        if (witness) {
+          const snapshot = getTransportSnapshot?.(connection.id) ?? null;
+          const started = witness.maybeCapture({
+            sessionId: connection.id,
+            tag: connection.tag,
+            label: "probe",
+            remote: snapshot?.remote ?? null,
+            queuedBytes: 0,
+            stuckForMs
+          });
+          if (!started) {
+            connection.probeCaptureStarted = false;
+          }
+        }
+        if (usrsctpState) {
+          usrsctpState.maybeRead(reasonText);
+        }
+      }
+    } else {
+      // Not association-stopped any more: whatever was flagged has cleared,
+      // and a later wedge on the same connection deserves its own attempt.
+      connection.probeCaptureStarted = false;
+    }
   }
 
   return {
@@ -305,6 +387,9 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
           echoes: 0,
           verdict: "",
           reportedAt: 0,
+          lastSeenAdvanceAt: 0,
+          longestHealthySeenGapMs: 0,
+          probeCaptureStarted: false,
           timer: null
         };
         connections.set(sessionId, connection);
@@ -342,15 +427,36 @@ export function createDeliveryProbe({ log, intervalMs = PROBE_INTERVAL_MS, readD
       if (!connection || !echo || typeof echo !== "object") {
         return;
       }
+      const now = Date.now();
       const seen = echo.seen;
       if (seen && typeof seen === "object") {
+        let advanced = false;
         for (const [label, value] of Object.entries(seen)) {
-          if (Number.isInteger(value)) {
-            connection.seen.set(label, value);
+          if (!Number.isInteger(value)) {
+            continue;
           }
+          const previous = connection.seen.get(label);
+          if (!Number.isInteger(previous) || value > previous) {
+            advanced = true;
+          }
+          connection.seen.set(label, value);
+        }
+        // What a wedge shows is this counter frozen, not merely behind — see
+        // probeWedgeIsCertain. The gap since the last time ANY label moved is
+        // this connection's own answer to "how long may a healthy report take
+        // to arrive", recorded only while nothing is currently flagged (the
+        // same guard `longestHealthyFlatMs` uses): a stretch already under
+        // suspicion must not teach the detector to tolerate it.
+        if (advanced) {
+          if (connection.lastSeenAdvanceAt !== 0 && !connection.probeCaptureStarted) {
+            const gap = now - connection.lastSeenAdvanceAt;
+            if (gap > connection.longestHealthySeenGapMs) {
+              connection.longestHealthySeenGapMs = gap;
+            }
+          }
+          connection.lastSeenAdvanceAt = now;
         }
       }
-      const now = Date.now();
       if (connection.echoAt !== 0) {
         const sinceLast = now - connection.echoAt;
         if (sinceLast > connection.echoIntervalMs) {

package/services/memory-report.js

@@ -0,0 +1,166 @@
+/**
+ * @file What this process is holding, said out loud on a regular cadence.
+ *
+ * Written 2026-08-28, after the kernel killed the proxy and the log could not
+ * say why. The supervisor recorded `exit code 137` — SIGKILL, so no core dump —
+ * and the kernel ring buffer held the whole of what was known:
+ *
+ *   Out of memory: Killed process 3036113 (MainThread)
+ *     anon-rss: 2422628kB  total-vm: 20856720kB  oom_score_adj: 200
+ *
+ * Two point four gigabytes, on a host with under two free, and the addon is the
+ * first thing the kernel picks because Home Assistant gives addons a positive
+ * `oom_score_adj`. What the proxy had been logging all along was its share of a
+ * CPU. Nothing anywhere said how much memory it held, so the growth that ended
+ * in that line has no shape: one final reading taken by the kernel, and no
+ * series leading to it.
+ *
+ * This is that series. It costs one line a minute and reads only counters the
+ * runtime already maintains.
+ */
+
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+
+/** How often the reading is taken and written. */
+export const MEMORY_REPORT_INTERVAL_MS = 60_000;
+
+/**
+ * What the process is holding, from the runtime's own counters.
+ *
+ * `rss` is what the kernel counts against us and therefore what the OOM killer
+ * reads. The rest says where it went: the JavaScript heap, and everything held
+ * outside it — which for this proxy is where the interesting growth lives,
+ * since torrent pieces sit in a `SharedArrayBuffer` and segment bodies pass
+ * through buffers.
+ *
+ * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }}
+ */
+export function readProcessMemory() {
+  const usage = process.memoryUsage();
+  return {
+    rss: usage.rss,
+    heapUsed: usage.heapUsed,
+    heapTotal: usage.heapTotal,
+    external: usage.external,
+    arrayBuffers: usage.arrayBuffers ?? 0
+  };
+}
+
+/**
+ * How much memory the machine could still give out, in bytes.
+ *
+ * `os.freemem()` is the wrong quantity on Linux and the difference is not
+ * academic: it counts only pages that are free RIGHT NOW, while the kernel
+ * deliberately keeps that number low by filling the rest with reclaimable page
+ * cache. `MemAvailable` is the kernel's own estimate of what a new allocation
+ * could actually obtain, cache included. Reading the estimate the kernel
+ * publishes beats recomputing a worse one.
+ *
+ * @returns {Promise<number | null>} Bytes, or null where /proc is not there.
+ */
+export async function readAvailableMemory() {
+  try {
+    const text = await readFile("/proc/meminfo", "utf8");
+    const match = /^MemAvailable:\s+(\d+)\s+kB$/m.exec(text);
+    if (match) {
+      return Number(match[1]) * 1024;
+    }
+  } catch {
+    // silent-ok: not Linux, or /proc is not mounted. The fallback below is a
+    // worse answer, and saying so is the point of returning it separately.
+  }
+  return null;
+}
+
+/**
+ * Available memory, falling back to what the runtime can offer.
+ *
+ * @returns {Promise<{ bytes: number, measured: boolean }>}
+ */
+export async function availableMemory() {
+  const fromKernel = await readAvailableMemory();
+  if (fromKernel !== null) {
+    return { bytes: fromKernel, measured: true };
+  }
+  return { bytes: os.freemem(), measured: false };
+}
+
+/**
+ * Render a size the way a person reads one.
+ *
+ * @param {number} bytes
+ * @returns {string}
+ */
+function megabytes(bytes) {
+  return `${Math.round(bytes / (1024 * 1024))}MB`;
+}
+
+/**
+ * One line saying what the process holds and what the machine has left.
+ *
+ * Pure, so the wording and the arithmetic can be pinned without a running
+ * process. Store figures are given in BYTES rather than in pieces: the piece
+ * count is meaningless without the piece size, and the piece size differs per
+ * torrent — on the film this proxy died under, 63 pieces meant 504 MB.
+ *
+ * @param {Object} reading
+ * @param {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }} reading.process
+ * @param {number} reading.availableBytes
+ * @param {boolean} reading.availableMeasured
+ * @param {{ name: string, residentBytes: number, budgetBytes: number }[]} [reading.stores]
+ * @returns {string}
+ */
+export function describeMemory({ process: usage, availableBytes, availableMeasured, stores = [] }) {
+  const storeResident = stores.reduce((total, store) => total + (store.residentBytes || 0), 0);
+  const storeBudget = stores.reduce((total, store) => total + (store.budgetBytes || 0), 0);
+  const storesPart = stores.length === 0
+    ? "no torrent stores"
+    : `${stores.length} torrent store(s) holding ${megabytes(storeResident)} ` +
+      `of ${megabytes(storeBudget)} allowed`;
+  return (
+    `memory: rss=${megabytes(usage.rss)} heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
+    `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}; ` +
+    `${storesPart}; ` +
+    `machine has ${megabytes(availableBytes)} available` +
+    `${availableMeasured ? "" : " (estimated — /proc/meminfo could not be read)"}`
+  );
+}
+
+/**
+ * Report memory on a timer until stopped.
+ *
+ * @param {Object} options
+ * @param {(message: string) => void} options.log
+ * @param {() => { name: string, residentBytes: number, budgetBytes: number }[]} [options.readStores]
+ * @param {number} [options.intervalMs]
+ * @returns {{ stop: () => void }}
+ */
+export function startMemoryReport({ log, readStores, intervalMs = MEMORY_REPORT_INTERVAL_MS }) {
+  const tick = async () => {
+    try {
+      const { bytes, measured } = await availableMemory();
+      let stores = [];
+      try {
+        stores = typeof readStores === "function" ? readStores() ?? [] : [];
+      } catch {
+        // silent-ok: a store list that cannot be read must not stop the reading
+        // that matters, which is the process's own.
+      }
+      log(describeMemory({
+        process: readProcessMemory(),
+        availableBytes: bytes,
+        availableMeasured: measured,
+        stores
+      }));
+    } catch {
+      // silent-ok: a reading that fails is not worth ending the series over.
+    }
+  };
+  void tick();
+  const timer = setInterval(() => { void tick(); }, intervalMs);
+  if (typeof timer.unref === "function") {
+    timer.unref();
+  }
+  return { stop: () => clearInterval(timer) };
+}