@torrent-tv/proxy 2.64.5 → 2.64.6

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 2.64.6
+
+- **New**: The torrent worker reads its own memory once a SECOND, and writes a line only when something moved. A minute cannot see what kills it: three times — 2026-08-30 14:00 and 23:19, 2026-08-31 13:27 — the worker's own line read `heap=28-36MB`, and by the sample after next the thread had been terminated for reaching its heap ceiling, with the whole rise fitting inside a single sixty-second gap. The reading and the line are now separate cadences: taken every second, written when the heap has moved by 25 MB or when a quiet minute is up, so a healthy session costs the same one line a minute it costs today and a runaway is a curve rather than a step.
+- **New**: A heap snapshot of the WORKER's own isolate, on every new high-water above 400 MB, into the state directory, three kept. Every snapshot ever written by this proxy has been of the MAIN isolate — `v8.writeHeapSnapshot` snapshots the thread that calls it, and the main thread's heap is 26 MB while the one that dies climbs to 2240 MB. So the isolate that has died three times has never once been looked at, and the question "what is holding this memory" has had no way to be answered. Deliberately NOT taken as the ceiling is approached: a snapshot is about the size of the heap it is of, so asking for one at 1.9 GB on a machine with 600 MB left is a way to cause the kill being studied — and at one reading a second no 400 MB step is ever missed. `stateDir` now travels to the worker for this, because a worker cannot change the process's working directory and had no way to choose where a file lands.
+- **New**: The memory line says the heap ceiling beside the heap — `heap=1800MB/1904MB of 2240MB allowed`. That ceiling is what the runtime terminates a thread for reaching, it is inherited from the main isolate by a worker created without `resourceLimits`, and without it the log said "30MB" with no way to tell how far that was from the end.
+
+- **Fix**: Room for a piece in the store is an owned reservation, released in a `finally`, instead of a number one function increments and another decrements. Every consequence of the old pairing was a defect, and all of them are gone with it: a failure between `#claimSlot` and `#registerPiece` — a disk read that throws — lost a slot for the life of the process, because there was no `try/finally` anywhere on that path; `put`'s error path tried to correct that by guessing, and its own comments said so ("Heuristic:", "We conservatively decrement"), so it could take back a reservation belonging to a different claim in flight and let the store admit past its allowance until the next minute's revision evicted the excess. `stats()` now reports `outstanding`, and the periodic `piece-store` line prints it when it is not zero: a reservation that never comes back is invisible until the store cannot admit anything, and by then the reason is long gone.
+- **Fix**: A claim waits on PROGRESS, not on activity. The five-second "every resident piece is pinned" error was skipped entirely while a spill was in flight or any reservation was held, so ONE lost reservation from the defect above made that error permanently unreachable and a read retried every 50 ms for the rest of the process's life — never completing, never failing, and never saying anything. The clock now restarts when something actually moves (a piece admitted, a spill finished, a pin released) and the error is raised when nothing has moved for five seconds, whatever is nominally in flight.
+- **Fix**: The wait between attempts allocates once instead of once per pending spill. It attached a fresh pair of handlers to EVERY spill in flight on EVERY attempt and left an uncancelled timer behind each time, so a claim that could not be satisfied allocated in proportion to attempts times spills. One idempotent handler now, its timer cleared when it is woken, and a settling spill wakes the store itself — which is where that belonged, and which `#claimSlotOnce`'s own spills were not doing at all.
+- **Fix**: Closing or destroying the store wakes whoever is waiting for room, and a claim checks for a closed store on every attempt. Callers inside `#claimSlot` were simply left asleep for ever.
+- **Fix**: A piece handed back to memory while its own spill is still being written no longer reappears on disk. `DiskTier.write` records the index when it COMPLETES, and `put` called `forget` before that, so the completing write put the stale copy back and a later read returned bytes from before the rewrite. `put` now waits for that piece's spill to finish before forgetting it.
+- **Fix**: A spill that fails while the allowance is being lowered is counted (`spill-failures` in the store's line) instead of thrown into nothing. Nobody awaits those spills, so the rethrow was an unhandled rejection, and an unhandled rejection in the torrent worker ends the thread — a second way to lose the torrent client on top of the one being investigated.
+- **Fix**: Two concurrent revivals of the same piece no longer each allocate and register a buffer for it, leaving whoever holds the first reading memory the store has stopped tracking. The second finds the piece already back and uses it.
+- **Fix**: `PieceLru` follows the store's live allowance. It was built with the capacity the store was created with and never revised, so `isFull()` answered against a number that had stopped being the limit — dormant only because nothing calls it today.
+- **Chore**: The store accepts an injected disk tier so a test can hold a write open or make one fail on purpose. Four of the defects above live in what happens when the disk does not answer at once, and none of them was reachable from outside before (`test/piece-store-reservations.test.js`).
+
+All eight were found by reading the file after the torrent worker was killed by its own JS heap limit on 2026-08-31 (`research/worker-heap-oom-2026-08-31.md`, §5). None of them is proven to be that growth; they are what the reading found, and each is a defect in its own right.
+
 ## 2.64.5
 
 - **Fix**: A rung measured at 0.007x is no longer kept just because it is on screen. The `playingHeight` exemption is now checked after the `measured < 1` withdrawal, so a 4K HEVC transcode at 0.007x on a CM4 (field 2026-08-31, 0.1x at 23:45 and 0.007x at 06:57, 0.04s buffered) is withdrawn and the offer can become empty instead of stalling the viewer with no way to downgrade. `ownHeight` is kept only for a copied source (`!transcodeVideo`), not for a re-encode already running at 0.18x.

package/package.json

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

package/server.js

@@ -116,7 +116,7 @@ export async function startProxyServer({
   // idled. Serving a segment shared that thread, so reading an already-finished
   // 10 MB file took 12-23 s against 125 ms to hand it to the channel. The
   // adapter keeps TorrentPool's interface, so nothing downstream changed.
-  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, onSubtitleCues });
+  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, stateDir, onSubtitleCues });
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });

package/services/memory-report.js

@@ -19,7 +19,7 @@
  * runtime already maintains.
  */
 
-import { readFile, statfs } from "node:fs/promises";
+import { readdir, readFile, rm, statfs } from "node:fs/promises";
 import os from "node:os";
 import v8 from "node:v8";
 import path from "node:path";
@@ -27,6 +27,18 @@ import path from "node:path";
 /** How often the reading is taken and written. */
 export const MEMORY_REPORT_INTERVAL_MS = 60_000;
 
+/**
+ * How often the torrent worker takes its own reading.
+ *
+ * A minute cannot see what killed it. Three times — 2026-08-30 14:00 and 23:19,
+ * 2026-08-31 13:27 — the worker's heap read 28-36 MB in one sample and the
+ * thread was dead by the sample after next, with the whole rise from 30 MB to
+ * the 2240 MB heap limit fitting inside a single gap. A second is short enough
+ * that the rise is a curve rather than a step, and the line is only WRITTEN when
+ * something moved, so a quiet session costs what it costs today.
+ */
+export const WORKER_MEMORY_SAMPLE_MS = 1_000;
+
 /**
  * What the process is holding, from the runtime's own counters.
  *
@@ -36,16 +48,30 @@ export const MEMORY_REPORT_INTERVAL_MS = 60_000;
  * since torrent pieces sit in a `SharedArrayBuffer` and segment bodies pass
  * through buffers.
  *
- * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number }}
+ * `heapLimit` is this isolate's own ceiling, and it belongs beside the heap
+ * figures because it is what the runtime kills the thread for reaching — a
+ * worker created without `resourceLimits` inherits the main isolate's, 2240 MB
+ * on the addon host. Without it the log said 30 MB and gave no idea how far
+ * that was from the end.
+ *
+ * @returns {{ rss: number, heapUsed: number, heapTotal: number, external: number, arrayBuffers: number, heapLimit: number }}
  */
 export function readProcessMemory() {
   const usage = process.memoryUsage();
+  let heapLimit = 0;
+  try {
+    heapLimit = v8.getHeapStatistics().heap_size_limit ?? 0;
+  } catch {
+    // silent-ok: a missing ceiling leaves the term out, it does not cost the
+    // reading beside it.
+  }
   return {
     rss: usage.rss,
     heapUsed: usage.heapUsed,
     heapTotal: usage.heapTotal,
     external: usage.external,
-    arrayBuffers: usage.arrayBuffers ?? 0
+    arrayBuffers: usage.arrayBuffers ?? 0,
+    heapLimit
   };
 }
 
@@ -198,7 +224,8 @@ export function describeMemory({
       `committed ${megabytes(storeCommitted)} of ${megabytes(storeBudget)} allowed, ` +
       `${megabytes(storeSpilled)} spilled to disk`;
   const isolate =
-    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)} ` +
+    `heap=${megabytes(usage.heapUsed)}/${megabytes(usage.heapTotal)}` +
+    `${usage.heapLimit ? ` of ${megabytes(usage.heapLimit)} allowed` : ""} ` +
     `external=${megabytes(usage.external)} arrayBuffers=${megabytes(usage.arrayBuffers)}`;
   if (scope === "thread") {
     return `memory (${label || "thread"}): ${isolate}; ${storesPart}`;
@@ -213,6 +240,39 @@ export function describeMemory({
   );
 }
 
+/**
+ * Whether this reading is worth writing down, and why.
+ *
+ * A series taken every second and printed every second is unreadable, and one
+ * printed every minute cannot see a rise that takes forty seconds. So the
+ * cadence of the READING and the cadence of the LINE are separate: the figure
+ * is taken often, and written when it has moved or when the quiet interval has
+ * passed. Pure, so the rule can be pinned without a clock.
+ *
+ * @param {Object} state
+ * @param {number} state.watchedBytes - The figure this scope is watching.
+ * @param {number} state.lastWrittenBytes
+ * @param {number} state.sinceWrittenMs
+ * @param {number} state.changeBytes - Movement that earns a line of its own.
+ * @param {number} state.quietMs - How long silence may last regardless.
+ * @returns {boolean}
+ */
+export function readingIsWorthWriting({
+  watchedBytes,
+  lastWrittenBytes,
+  sinceWrittenMs,
+  changeBytes,
+  quietMs
+}) {
+  if (quietMs <= 0 || sinceWrittenMs >= quietMs) {
+    return true;
+  }
+  if (changeBytes <= 0) {
+    return false;
+  }
+  return Math.abs(watchedBytes - lastWrittenBytes) >= changeBytes;
+}
+
 /**
  * Report memory on a timer until stopped.
  *
@@ -225,7 +285,17 @@ export function describeMemory({
  * @param {string} [options.label] - Which thread the isolate figures are of.
  * @param {string} [options.diskPath] - Where pieces spill, for the free-space
  *   reading. Omitted, the disk term is left out rather than guessed.
- * @param {number} [options.intervalMs]
+ * @param {number} [options.intervalMs] - How often the figure is READ.
+ * @param {number} [options.quietMs] - How long the line may stay silent while
+ *   nothing moves. Zero writes every reading, which is what the process scope
+ *   has always done.
+ * @param {number} [options.changeBytes] - Movement that earns a line before the
+ *   quiet interval is up.
+ * @param {string} [options.snapshotDir] - Where heap snapshots are written.
+ *   Defaults to the temporary directory, as the process scope always did.
+ * @param {number} [options.snapshotFloorBytes]
+ * @param {number} [options.snapshotGrowthBytes]
+ * @param {number} [options.keepSnapshots] - Newest to keep; zero keeps all.
  * @returns {{ stop: () => void }}
  */
 export function startMemoryReport({
@@ -234,9 +304,62 @@ export function startMemoryReport({
   scope = "process",
   label = "",
   diskPath = "",
-  intervalMs = MEMORY_REPORT_INTERVAL_MS
+  intervalMs = MEMORY_REPORT_INTERVAL_MS,
+  quietMs = 0,
+  changeBytes = 0,
+  snapshotDir = "",
+  snapshotFloorBytes = 500 * 1024 * 1024,
+  snapshotGrowthBytes = 100 * 1024 * 1024,
+  keepSnapshots = 0
 }) {
-  let highWaterRss = 0;
+  let highWater = 0;
+  let lastWrittenBytes = 0;
+  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
+  // memory — the main isolate sat at 26 MB while the worker's heap climbed to
+  // its 2240 MB ceiling.
+  const watchedOf = (memory) => (scope === "thread" ? memory.heapTotal : memory.rss);
+  const slug = (label || scope).replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+  const directory = snapshotDir || os.tmpdir();
+
+  /**
+   * @param {number} watchedBytes
+   * @param {string} why
+   * @returns {Promise<void>}
+   */
+  const takeSnapshot = async (watchedBytes, why) => {
+    let snapPath = "";
+    try {
+      snapPath = path.join(directory, `heap-${slug}-${Date.now()}-${watchedBytes}.heapsnapshot`);
+      // Synchronous and proportional to the heap, so it stops this thread for
+      // as long as it takes to write. That is the price of the only reading
+      // that names what is holding the memory, and it is why it is bounded by
+      // a floor, by a growth step and by how many are kept.
+      v8.writeHeapSnapshot(snapPath);
+      log(`memory: wrote heap snapshot of the ${label || scope} to ${snapPath} (${megabytes(watchedBytes)}, ${why})`);
+    } catch {
+      // silent-ok: no snapshot is worse than a snapshot, and much better than
+      // ending the series that leads to the next one.
+      return;
+    }
+    if (keepSnapshots <= 0) {
+      return;
+    }
+    try {
+      const prefix = `heap-${slug}-`;
+      const mine = (await readdir(directory))
+        .filter((name) => name.startsWith(prefix) && name.endsWith(".heapsnapshot"))
+        .sort();
+      for (const name of mine.slice(0, Math.max(0, mine.length - keepSnapshots))) {
+        await rm(path.join(directory, name), { force: true });
+      }
+    } catch {
+      // silent-ok: a snapshot that could not be pruned is a disk-space problem
+      // for later, not a reason to lose the one just written.
+    }
+  };
+
   const tick = async () => {
     try {
       let stores = [];
@@ -247,35 +370,57 @@ export function startMemoryReport({
         // that matters, which is the process's own.
       }
       const processMemory = readProcessMemory();
+      const watched = watchedOf(processMemory);
+      const now = Date.now();
+      const write = readingIsWorthWriting({
+        watchedBytes: watched,
+        lastWrittenBytes,
+        sinceWrittenMs: lastWrittenAt === 0 ? Number.POSITIVE_INFINITY : now - lastWrittenAt,
+        changeBytes,
+        quietMs
+      });
+
+      let anonymousBytes = null;
       if (scope === "thread") {
-        log(describeMemory({ scope, label, process: processMemory, stores }));
-        return;
+        if (write) {
+          log(describeMemory({ scope, label, process: processMemory, stores }));
+        }
+      } else {
+        const { bytes, measured } = await availableMemory();
+        anonymousBytes = await readAnonymousMemory();
+        const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
+        if (write) {
+          log(describeMemory({
+            scope,
+            label,
+            process: processMemory,
+            availableBytes: bytes,
+            availableMeasured: measured,
+            anonymousBytes,
+            diskFreeBytes,
+            stores
+          }));
+        }
+      }
+      if (write) {
+        lastWrittenBytes = watched;
+        lastWrittenAt = now;
       }
-      const { bytes, measured } = await availableMemory();
-      const anonymousBytes = await readAnonymousMemory();
-      const diskFreeBytes = diskPath ? await readDiskFree(diskPath) : null;
-      log(describeMemory({
-        scope,
-        label,
-        process: processMemory,
-        availableBytes: bytes,
-        availableMeasured: measured,
-        anonymousBytes,
-        diskFreeBytes,
-        stores
-      }));
-      // High-water and heap snapshot on growth — gives a file to open in Chrome DevTools
-      // when the kernel is about to kill the process. One snapshot per high-water.
-      if (processMemory.rss > highWaterRss + 100 * 1024 * 1024 && processMemory.rss > 500 * 1024 * 1024) {
-        highWaterRss = processMemory.rss;
-        try {
-          const snapPath = path.join(os.tmpdir(), `heap-${Date.now()}-${processMemory.rss}.heapsnapshot`);
-          v8.writeHeapSnapshot(snapPath);
-          log(`memory: wrote heap snapshot to ${snapPath} rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${anonymousBytes ? Math.round(anonymousBytes / (1024 * 1024)) : "?"}MB`);
-        } catch {}
+
+      // A snapshot per high-water, so there is a file to open when the growth
+      // has to be named rather than described.
+      //
+      // Deliberately NOT one taken as the ceiling is approached: a snapshot is
+      // written by the isolate itself and is about the size of its heap, so
+      // asking for one at 1.9 GB on a machine with 600 MB left is a good way to
+      // cause the kill being studied. Whatever holds 1.6 GB is the same thing
+      // that holds 2.2 GB, and at one reading a second no step is ever missed.
+      if (watched > highWater + snapshotGrowthBytes && watched > snapshotFloorBytes) {
+        highWater = watched;
+        await takeSnapshot(watched, "a new high-water");
       }
-      if (anonymousBytes !== null && processMemory.rss > 800 * 1024 * 1024) {
-        log(`memory: high rss=${Math.round(processMemory.rss / (1024 * 1024))}MB anon=${Math.round(anonymousBytes / (1024 * 1024))}MB heap=${Math.round(processMemory.heapUsed / (1024 * 1024))}MB — watch for OOM`);
+      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`);
       }
     } catch {
       // silent-ok: a reading that fails is not worth ending the series over.

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

@@ -64,6 +64,22 @@ export class PieceLru {
     return this.#capacity;
   }
 
+  /**
+   * Follow the store's live allowance, which moves with the machine's free
+   * memory. Without this the capacity stayed at whatever the store was created
+   * with, and {@link PieceLru#isFull} answered against a number that had not
+   * been the limit for some time.
+   *
+   * @param {number} capacity
+   * @returns {void}
+   */
+  setCapacity(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      return;
+    }
+    this.#capacity = capacity;
+  }
+
   /**
    * How many pieces are currently held by a reader.
    *

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

@@ -23,6 +23,17 @@
  * Evicting a piece deletes its entry and the memory is reclaimable by GC.
  * `committed` therefore equals `resident`, not a high-water mark.
  *
+ * **Room for a piece is an owned reservation, not a shared number.**
+ * `#claimSlot` hands back a release the caller runs in a `finally`; nothing
+ * else touches `#outstandingPieces`. It was a counter incremented in one
+ * function and decremented in another, and every consequence of that was a
+ * defect: a failure between the two lost a slot for the life of the process,
+ * `put`'s error path guessed at the correction and could take back a
+ * reservation belonging to a different claim, and one lost reservation made
+ * the five-second "everything is pinned" error permanently unreachable, so a
+ * read retried every 50 ms for ever without completing or failing. Read out of
+ * the field failure of 2026-08-31 (`research/worker-heap-oom-2026-08-31.md`).
+ *
  * What this deliberately does NOT do is manage the disk as a cache of its own.
  * Pieces evicted from memory are written once and read back on demand; the file
  * is discarded whole when the torrent goes away. libtorrent 2.0 and webtor's
@@ -98,6 +109,15 @@ function availableMemorySync() {
 
 const MIN_BUDGET_BYTES = 64 * 1024 * 1024;
 const MIN_RESIDENT_PIECES = 2;
+/**
+ * How long a claim may go without ANYTHING moving before it gives up.
+ *
+ * Measured against progress, not against activity. The earlier rule skipped
+ * this timer entirely while a spill was in flight or a reservation was held —
+ * so one reservation that was never returned made the timer unreachable and a
+ * read retried every 50 ms for the life of the process, never completing and
+ * never failing (field 2026-08-31).
+ */
 const PINNED_WAIT_MS = 5_000;
 const CLAIM_RETRY_MS = 50;
 
@@ -111,8 +131,21 @@ export class SharedPieceStore {
   #buffers = new Map();
   /** @type {Map<number, Promise<void>>} */
   #evicting = new Map();
+  /**
+   * Slots claimed but not yet filled.
+   *
+   * Handed out by {@link SharedPieceStore##claimSlot} as a release function the
+   * caller must call in a `finally`, never as a number one function increments
+   * and another decrements. The counter used to be paired across
+   * `#claimSlot`/`#registerPiece`, so any failure between the two lost a slot
+   * for the life of the process, and `put`'s error path tried to correct that
+   * by guessing — which could take back a reservation belonging to a different
+   * claim and let the store admit past its allowance.
+   */
   #outstandingPieces = 0;
   #pinnedWaitStartedAt = 0;
+  /** When something last actually moved: a piece admitted, spilled or unpinned. */
+  #lastProgressAt = 0;
   #waiters = [];
   #lru;
   #disk;
@@ -125,7 +158,8 @@ export class SharedPieceStore {
     revivals: 0,
     blockedByPins: 0,
     waitedForPins: 0,
-    evictedOnRevise: 0
+    evictedOnRevise: 0,
+    spillFailures: 0
   };
 
   constructor(chunkLength, options = {}) {
@@ -147,7 +181,11 @@ export class SharedPieceStore {
     this.#growthCeiling = this.#capacity;
     this.#lru = new PieceLru(this.#capacity);
     this.#name = options.name ?? "pieces";
-    this.#disk = new DiskTier({
+    // `options.disk` exists so a test can hold a write open or make one fail on
+    // purpose. Four of the defects fixed here live in what happens when the
+    // disk tier does not answer immediately or at all, and none of them is
+    // reachable from outside without saying so.
+    this.#disk = options.disk ?? new DiskTier({
       directory: options.path ?? ".",
       name: `${this.#name}.pieces`,
       chunkLength
@@ -168,6 +206,10 @@ export class SharedPieceStore {
       committedBytes: residentBytes,
       budgetBytes: this.#growthCeiling * this.#chunkLength,
       pinned: this.#lru.pinnedCount,
+      // Slots claimed and not yet filled. Reported because a reservation that
+      // is never returned is invisible until the store cannot admit anything,
+      // and by then the reason is long gone. At rest this is zero.
+      outstanding: this.#outstandingPieces,
       spilled: this.#disk.size,
       spilledBytes: this.#disk.size * this.#chunkLength,
       ...this.#counters
@@ -180,6 +222,11 @@ export class SharedPieceStore {
       this.#capacity,
       Math.max(MIN_RESIDENT_PIECES, Number.isFinite(wanted) ? wanted : this.#capacity)
     );
+    // The LRU is told too. It was constructed with the store's original
+    // capacity and never revised, so `isFull()` answered against a number that
+    // had not been the limit for some time — dormant only because nothing calls
+    // it, which is a trap for whoever calls it next.
+    this.#lru.setCapacity(this.#growthCeiling);
     // With per-piece buffers memory CAN be given back immediately, unlike the
     // old growable pool. Eagerly evict excess to honour the new ceiling.
     let evicted = 0;
@@ -197,23 +244,13 @@ export class SharedPieceStore {
       this.#lru.remove(victim);
       evicted += 1;
       this.#counters.evictedOnRevise += 1;
-      const bytes = Buffer.from(victimBuffer, 0, this.#lengthOf(victim));
-      const spill = this.#disk.write(victim, bytes).then(
-        () => {
-          this.#counters.spills += 1;
-          this.#evicting.delete(victim);
-          this.#wake();
-        },
-        (error) => {
-          this.#evicting.delete(victim);
-          this.#wake();
-          throw error;
-        }
-      );
-      this.#evicting.set(victim, spill);
-    }
-    if (evicted > 0) {
-      // Logged by the caller (worker) via reviseStoreBudgets, but also countable here.
+      // 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
+      // client, on top of the one that already loses it.
+      void this.#spill(victim, victimBuffer).catch(() => {
+        this.#counters.spillFailures += 1;
+      });
     }
     return {
       name: this.#name,
@@ -272,30 +309,102 @@ export class SharedPieceStore {
 
   unpin(index) {
     this.#lru.unpin(index);
-    this.#wake();
+    this.#noteProgress();
   }
 
+  /**
+   * Reserve room for one piece.
+   *
+   * @returns {Promise<() => void>} The release, which the caller MUST call in a
+   *   `finally`. Calling it twice is harmless.
+   */
   async #claimSlot() {
     for (;;) {
+      if (this.#closed) {
+        throw new Error("Piece store is closed.");
+      }
       const ok = await this.#claimSlotOnce();
       if (ok) {
-        return;
+        let released = false;
+        return () => {
+          if (released) {
+            return;
+          }
+          released = true;
+          this.#outstandingPieces -= 1;
+          this.#noteProgress();
+        };
       }
-      await new Promise((resolve) => {
-        this.#waiters.push(resolve);
-        for (const spill of this.#evicting.values()) {
-          void spill.then(() => this.#wake(), () => this.#wake());
-        }
-        const retry = setTimeout(() => this.#wake(), CLAIM_RETRY_MS);
-        retry.unref?.();
-      });
+      await this.#waitForSlot();
     }
   }
 
+  /**
+   * Sleep until something moves, or until the retry interval, whichever first.
+   *
+   * One handler, idempotent, and its timer is cleared when it is woken. The
+   * earlier version attached a fresh pair of handlers to EVERY pending spill on
+   * every attempt and left a timer running each time, so a claim that could not
+   * be satisfied allocated in proportion to attempts times pending spills. A
+   * settling spill now wakes the store itself, which is where that belongs.
+   *
+   * @returns {Promise<void>}
+   */
+  #waitForSlot() {
+    return new Promise((resolve) => {
+      let settled = false;
+      /** @type {ReturnType<typeof setTimeout> | null} */
+      let retry = null;
+      const finish = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (retry !== null) {
+          clearTimeout(retry);
+        }
+        resolve();
+      };
+      this.#waiters.push(finish);
+      retry = setTimeout(finish, CLAIM_RETRY_MS);
+      retry.unref?.();
+    });
+  }
+
   #registerPiece(index, buffer) {
     this.#buffers.set(index, buffer);
     this.#lru.touch(index);
-    this.#outstandingPieces -= 1;
+    this.#noteProgress();
+  }
+
+  /**
+   * Write a piece out and account for it, from the one place that does it.
+   *
+   * @param {number} index
+   * @param {SharedArrayBuffer} buffer
+   * @returns {Promise<void>}
+   */
+  #spill(index, buffer) {
+    const bytes = Buffer.from(buffer, 0, this.#lengthOf(index));
+    const spill = this.#disk.write(index, bytes).then(
+      () => {
+        this.#counters.spills += 1;
+        this.#evicting.delete(index);
+        this.#noteProgress();
+      },
+      (error) => {
+        this.#evicting.delete(index);
+        this.#noteProgress();
+        throw error;
+      }
+    );
+    this.#evicting.set(index, spill);
+    return spill;
+  }
+
+  /** Something actually moved: wake whoever is waiting and restart the clock. */
+  #noteProgress() {
+    this.#lastProgressAt = Date.now();
     this.#wake();
   }
 
@@ -311,25 +420,30 @@ export class SharedPieceStore {
     // Reserve before suspension so concurrent callers see the reservation.
     if (this.#buffers.size + this.#outstandingPieces < this.#growthCeiling) {
       this.#outstandingPieces += 1;
+      this.#pinnedWaitStartedAt = 0;
       return true;
     }
 
     const victim = this.#lru.evictionCandidate();
     if (victim === null) {
-      if (this.#evicting.size > 0 || this.#outstandingPieces > 0) {
-        return false;
-      }
+      // 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
+      // not moved for PINNED_WAIT_MS, whatever is nominally in flight. The old
+      // rule asked whether anything was in flight rather than whether anything
+      // had happened, which is why one lost reservation could hold a read here
+      // for ever.
       if (this.#pinnedWaitStartedAt === 0) {
         this.#pinnedWaitStartedAt = Date.now();
       }
-      if (Date.now() - this.#pinnedWaitStartedAt < PINNED_WAIT_MS) {
+      const stillFor = Date.now() - Math.max(this.#pinnedWaitStartedAt, this.#lastProgressAt);
+      if (stillFor < PINNED_WAIT_MS) {
         this.#counters.waitedForPins += 1;
         return false;
       }
       this.#pinnedWaitStartedAt = 0;
       this.#counters.blockedByPins += 1;
       throw new Error(
-        `Every resident piece is pinned and none was released in ${PINNED_WAIT_MS}ms; no slot can be freed.`
+        `Every resident piece is pinned and nothing moved for ${PINNED_WAIT_MS}ms; no slot can be freed.`
       );
     }
     this.#pinnedWaitStartedAt = 0;
@@ -346,24 +460,95 @@ export class SharedPieceStore {
     this.#lru.remove(victim);
     this.#outstandingPieces += 1;
 
-    const bytes = Buffer.from(victimBuffer, 0, this.#lengthOf(victim));
-    const spill = this.#disk.write(victim, bytes).then(
-      () => {
-        this.#counters.spills += 1;
-        this.#evicting.delete(victim);
-      },
-      (error) => {
-        this.#evicting.delete(victim);
-        throw error;
-      }
-    );
-    this.#evicting.set(victim, spill);
-    await spill;
+    try {
+      await this.#spill(victim, victimBuffer);
+    } catch (error) {
+      // The caller never received a release for this reservation, so it is
+      // given back here rather than left outstanding for ever.
+      this.#outstandingPieces -= 1;
+      this.#noteProgress();
+      throw error;
+    }
     // Outstanding stays +1 for the caller; the slot for the new piece is now free.
     return true;
   }
 
-  // For compatibility: some callers check #freeSlots / #allocatedSlots — not needed.
+  /**
+   * Bring a spilled piece back into memory, once, however many callers ask.
+   *
+   * @param {number} index
+   * @returns {Promise<SharedArrayBuffer | null>} `null` when the piece is on
+   *   neither tier.
+   */
+  async #revive(index) {
+    const spill = this.#evicting.get(index);
+    if (spill) {
+      await spill.catch(() => undefined);
+    }
+
+    if (!this.#disk.has(index)) {
+      return null;
+    }
+
+    const release = await this.#claimSlot();
+    try {
+      // Another caller may have brought it back while this one waited for a
+      // slot. Registering a second buffer for the same piece would leave
+      // whoever holds the first reading memory nothing evicts.
+      const already = this.#buffers.get(index);
+      if (already !== undefined) {
+        this.#lru.touch(index);
+        this.#counters.fromMemory += 1;
+        return already;
+      }
+      const target = new SharedArrayBuffer(this.#lengthOf(index));
+      await this.#disk.read(index, Buffer.from(target));
+      this.#registerPiece(index, target);
+      this.#counters.fromDisk += 1;
+      this.#counters.revivals += 1;
+      return target;
+    } finally {
+      release();
+    }
+  }
+
+  /**
+   * A fresh buffer holding this piece's bytes.
+   *
+   * @param {number} index
+   * @param {Uint8Array} bytes
+   * @returns {SharedArrayBuffer}
+   */
+  #copyIntoNewBuffer(index, bytes) {
+    const length = this.#lengthOf(index);
+    const sab = new SharedArrayBuffer(length);
+    const view = Buffer.from(sab);
+    if (bytes.copy) {
+      bytes.copy(view, 0, 0, length);
+    } else {
+      view.set(bytes.subarray(0, length), 0);
+    }
+    return sab;
+  }
+
+  /**
+   * Drop the disk copy of a piece that memory now holds — after any spill of
+   * that same piece has finished.
+   *
+   * `DiskTier.write` records the index when it COMPLETES, so forgetting while a
+   * spill of that index is still running let the completing write put it back,
+   * and a later read then returned the stale bytes.
+   *
+   * @param {number} index
+   * @returns {Promise<void>}
+   */
+  async #forgetOnDisk(index) {
+    const spill = this.#evicting.get(index);
+    if (spill) {
+      await spill.catch(() => undefined);
+    }
+    this.#disk.forget(index);
+  }
 
   put(index, bytes, callback = () => undefined) {
     if (this.#closed) {
@@ -371,65 +556,28 @@ export class SharedPieceStore {
       return;
     }
 
-    // Overwrite in place if already resident: no eviction needed.
-    if (this.#buffers.has(index)) {
-      const write = async () => {
-        const length = this.#lengthOf(index);
-        // Replace buffer so readers with old reference don't see torn write.
-        const sab = new SharedArrayBuffer(length);
-        const view = Buffer.from(sab);
-        if (bytes.copy) {
-          bytes.copy(view, 0, 0, length);
-        } else {
-          view.set(bytes.subarray(0, length), 0);
-        }
-        this.#buffers.set(index, sab);
+    const write = async () => {
+      // Already resident: the buffer is replaced, not added, so no slot is
+      // needed and none is claimed. A fresh buffer rather than a write into the
+      // old one, so a reader holding the old reference cannot see a torn write.
+      if (this.#buffers.has(index)) {
+        this.#buffers.set(index, this.#copyIntoNewBuffer(index, bytes));
         this.#lru.touch(index);
-        this.#disk.forget(index);
-      };
-      write().then(() => callback(null), (error) => callback(error));
-      return;
-    }
+        await this.#forgetOnDisk(index);
+        this.#noteProgress();
+        return;
+      }
 
-    const write = async () => {
-      await this.#claimSlot();
-      const length = this.#lengthOf(index);
-      const sab = new SharedArrayBuffer(length);
-      const view = Buffer.from(sab);
-      if (bytes.copy) {
-        bytes.copy(view, 0, 0, length);
-      } else {
-        view.set(bytes.subarray(0, length), 0);
+      const release = await this.#claimSlot();
+      try {
+        this.#registerPiece(index, this.#copyIntoNewBuffer(index, bytes));
+        await this.#forgetOnDisk(index);
+      } finally {
+        release();
       }
-      this.#registerPiece(index, sab);
-      this.#disk.forget(index);
     };
 
-    write().then(() => callback(null), (error) => {
-      // If claim failed, outstanding was already incremented; correct it.
-      // #registerPiece decrements on success; on failure we must decrement too.
-      // But #claimSlotOnce already handles increment; we need to decrement if write threw before register.
-      // Easiest: if error and outstanding still +1 and piece not registered, decrement.
-      if (error) {
-        // If we reserved but never registered, outstanding is still +1.
-        // Check if piece is not in map and we have outstanding.
-        if (!this.#buffers.has(index) && this.#outstandingPieces > 0) {
-          // Only decrement if the failure happened before register.
-          // Heuristic: if error message is pinned exhaustion, it came from claimSlotOnce which did not increment? Actually claimSlotOnce increments only on success/eviction.
-          // For pinned error, outstanding was not incremented? Let's handle: claimSlot throws before increment? No, it throws after check, without increment.
-          // So only failures after claim (disk write etc) need decrement — those have outstanding +1.
-          // We conservatively decrement if outstanding >0 and piece not registered.
-          // But to avoid double-decrement we check if this specific write's outstanding is still held.
-          // Simple: decrement if outstanding >0 and piece not in map, and the error is not the pinned throw's pre-increment case.
-          // The pinned throw does not increment, so outstanding is 0 there.
-          if (this.#outstandingPieces > 0) {
-            this.#outstandingPieces -= 1;
-            this.#wake();
-          }
-        }
-      }
-      callback(error);
-    });
+    write().then(() => callback(null), (error) => callback(error));
   }
 
   get(index, options, callback) {
@@ -451,28 +599,14 @@ export class SharedPieceStore {
       if (buffer !== undefined) {
         this.#lru.touch(index);
         this.#counters.fromMemory += 1;
-        const view = Buffer.from(buffer, offset, length);
-        return Buffer.from(view);
-      }
-
-      const spill = this.#evicting.get(index);
-      if (spill) {
-        await spill.catch(() => undefined);
+        return Buffer.from(Buffer.from(buffer, offset, length));
       }
 
-      if (!this.#disk.has(index)) {
+      const revived = await this.#revive(index);
+      if (revived === null) {
         throw new Error(`Piece ${index} is not in the store.`);
       }
-
-      await this.#claimSlot();
-      const targetSab = new SharedArrayBuffer(pieceLength);
-      const target = Buffer.from(targetSab);
-      await this.#disk.read(index, target);
-      this.#registerPiece(index, targetSab);
-      this.#counters.fromDisk += 1;
-      this.#counters.revivals += 1;
-      const view = Buffer.from(targetSab, offset, length);
-      return Buffer.from(view);
+      return Buffer.from(Buffer.from(revived, offset, length));
     };
 
     fetch().then((bytes) => done(null, bytes), (error) => done(error));
@@ -517,30 +651,20 @@ export class SharedPieceStore {
       return this.locate(index);
     }
 
-    const spill = this.#evicting.get(index);
-    if (spill) {
-      await spill.catch(() => undefined);
-    }
-
-    if (!this.#disk.has(index)) {
+    const revived = await this.#revive(index);
+    if (revived === null) {
       return null;
     }
-
-    const pieceLength = this.#lengthOf(index);
-    await this.#claimSlot();
-    const targetSab = new SharedArrayBuffer(pieceLength);
-    const target = Buffer.from(targetSab);
-    await this.#disk.read(index, target);
-    this.#registerPiece(index, targetSab);
-    this.#counters.fromDisk += 1;
-    this.#counters.revivals += 1;
-    return this.locate(index);
+    return { buffer: revived, offset: 0, length: this.#lengthOf(index) };
   }
 
   close(callback = () => undefined) {
     this.#closed = true;
     liveStores.delete(this);
     this.#buffers.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();
     this.#disk.close().then(() => callback(null), (error) => callback(error));
   }
 
@@ -548,6 +672,7 @@ export class SharedPieceStore {
     this.#closed = true;
     liveStores.delete(this);
     this.#buffers.clear();
+    this.#wake();
     this.#disk.destroy().then(() => callback(null), (error) => callback(error));
   }
 }

package/services/torrent-worker/client.js

@@ -67,11 +67,15 @@ export class TorrentWorkerClient {
   #onSubtitleCues;
 
   /**
-   * @param {{ maxDiskBytes?: number, memoryBytes?: number, onSubtitleCues?: (event: object) => void }} [options]
+   * @param {{ maxDiskBytes?: number, memoryBytes?: number, stateDir?: string, onSubtitleCues?: (event: object) => void }} [options]
    */
-  constructor({ maxDiskBytes, memoryBytes, onSubtitleCues } = {}) {
+  constructor({ maxDiskBytes, memoryBytes, stateDir, onSubtitleCues } = {}) {
     this.#worker = new Worker(fileURLToPath(WORKER_URL), {
-      workerData: { maxDiskBytes, memoryBytes }
+      // `stateDir` travels because the worker writes heap snapshots of its own
+      // isolate there. It cannot choose a directory any other way: a worker may
+      // not change the process's working directory, and the isolate that has
+      // died three times is the one no snapshot has ever been taken of.
+      workerData: { maxDiskBytes, memoryBytes, stateDir }
     });
     this.#caller = createCaller(this.#worker);
     this.#onSubtitleCues = onSubtitleCues ?? (() => undefined);

package/services/torrent-worker/pool-adapter.js

@@ -37,7 +37,7 @@ export class WorkerTorrentPool {
   #torrents = new Map();
 
   /**
-   * @param {{ maxDiskBytes?: number, memoryBytes?: number }} [options]
+   * @param {{ maxDiskBytes?: number, memoryBytes?: number, stateDir?: string }} [options]
    */
   constructor(options = {}) {
     this.#client = new TorrentWorkerClient(options);

package/services/torrent-worker/worker.js

@@ -29,7 +29,7 @@ import { createFileClaims } from "./file-claims.js";
 import { readFragments, supplyFiguresFor } from "./piece-reader.js";
 import { cuesHeldFor, declaredSubtitleTracksOf, subtitleTracksOf, warmSubtitleCues } from "./subtitle-cues.js";
 import { Command, Event } from "./protocol.js";
-import { startMemoryReport } from "../memory-report.js";
+import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../memory-report.js";
 
 // Imported dynamically, and that is load-bearing: static imports are RESOLVED
 // during linking, before any module body runs, so a statically imported pool
@@ -485,11 +485,25 @@ parentPort.on("message", async (message) => {
 // a `SharedArrayBuffer` allocated here, so the main thread's counters cannot
 // see it however carefully they are read — which is half the reason 650 MB of a
 // 893 MB process had no explanation on 2026-08-28 (roadmap item 2).
+// A second between readings, a minute between lines unless the heap moved by
+// 25 MB, and a heap snapshot of THIS isolate on every new high-water above
+// 400 MB. Three deaths — 2026-08-30 14:00 and 23:19, and
+// 2026-08-31 13:27 — went from a 30 MB heap to the 2240 MB ceiling inside one
+// sixty-second gap, and the only snapshots ever written were of the main
+// isolate, whose heap is 26 MB. So the isolate that dies has never once been
+// looked at (roadmap item 2, `research/worker-heap-oom-2026-08-31.md`).
 startMemoryReport({
   log,
   readStores: collectStoreStats,
   scope: "thread",
-  label: "torrent worker"
+  label: "torrent worker",
+  intervalMs: WORKER_MEMORY_SAMPLE_MS,
+  quietMs: 60_000,
+  changeBytes: 25 * 1024 * 1024,
+  snapshotDir: workerData?.stateDir || undefined,
+  snapshotFloorBytes: 400 * 1024 * 1024,
+  snapshotGrowthBytes: 400 * 1024 * 1024,
+  keepSnapshots: 3
 });
 
 const STORE_REPORT_INTERVAL_MS = 60_000;
@@ -518,7 +532,7 @@ setInterval(() => {
     }
   }
   for (const stats of collectStoreStats()) {
-    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}/${stats.evictedOnRevise}`;
+    const signature = `${stats.fromMemory}/${stats.fromDisk}/${stats.spills}/${stats.revivals}/${stats.blockedByPins}/${stats.evictedOnRevise}/${stats.spillFailures}`;
     if (lastReported.get(stats.name) === signature) {
       continue;
     }
@@ -535,7 +549,9 @@ setInterval(() => {
       `pinned=${stats.pinned} spilled=${stats.spilled} reads=${reads} (${fromMemoryShare}% from memory) ` +
       `spills=${stats.spills} revivals=${stats.revivals}` +
       (stats.blockedByPins > 0 ? ` blocked-by-pins=${stats.blockedByPins}` : "") +
-      (stats.evictedOnRevise > 0 ? ` evictedOnRevise=${stats.evictedOnRevise}` : "")
+      (stats.evictedOnRevise > 0 ? ` evictedOnRevise=${stats.evictedOnRevise}` : "") +
+      (stats.spillFailures > 0 ? ` spill-failures=${stats.spillFailures}` : "") +
+      (stats.outstanding > 0 ? ` outstanding=${stats.outstanding}` : "")
     );
   }
 }, STORE_REPORT_INTERVAL_MS).unref();

package/test/memory-budget.test.js

@@ -1,7 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { describeMemory } from "../services/memory-report.js";
+import { describeMemory, readingIsWorthWriting } from "../services/memory-report.js";
 import {
   budgetForNewStore,
   SharedPieceStore,
@@ -154,3 +154,65 @@ test("a store's allowance follows the machine, and never passes its reservation"
     await rm(directory, { recursive: true, force: true });
   }
 });
+
+test("the line says how far the heap is from the ceiling it is killed for reaching", () => {
+  // The worker died three times for reaching 2240 MB while its own line said
+  // "heap=30MB" and nothing said what 30 MB was 30 MB of.
+  const line = describeMemory({
+    scope: "thread",
+    label: "torrent worker",
+    process: {
+      rss: 2549 * MEGABYTE,
+      heapUsed: 1800 * MEGABYTE,
+      heapTotal: 1904 * MEGABYTE,
+      external: 40 * MEGABYTE,
+      arrayBuffers: 20 * MEGABYTE,
+      heapLimit: 2240 * MEGABYTE
+    },
+    stores: []
+  });
+  assert.match(line, /heap=1800MB\/1904MB of 2240MB allowed/);
+
+  const withoutLimit = describeMemory({
+    scope: "thread",
+    label: "torrent worker",
+    process: { rss: 0, heapUsed: 12 * MEGABYTE, heapTotal: 20 * MEGABYTE, external: 0, arrayBuffers: 0 },
+    stores: []
+  });
+  assert.match(withoutLimit, /heap=12MB\/20MB external=/, "an unknown ceiling is left out, not printed as zero");
+});
+
+test("a reading is written when it moved, or when the silence has gone on long enough", () => {
+  const changeBytes = 25 * MEGABYTE;
+  const quietMs = 60_000;
+  const still = {
+    watchedBytes: 100 * MEGABYTE,
+    lastWrittenBytes: 100 * MEGABYTE,
+    sinceWrittenMs: 1_000,
+    changeBytes,
+    quietMs
+  };
+
+  assert.equal(readingIsWorthWriting(still), false, "a second of nothing is not worth a line");
+  assert.equal(
+    readingIsWorthWriting({ ...still, sinceWrittenMs: 60_000 }),
+    true,
+    "a quiet minute is still written, so a healthy session reads as it always did"
+  );
+  // The rise that killed the worker: 818 MB to 2203 MB inside one old sample.
+  assert.equal(
+    readingIsWorthWriting({ ...still, watchedBytes: 130 * MEGABYTE }),
+    true,
+    "growth of a quarter of a gigabyte cannot wait for the minute to be up"
+  );
+  assert.equal(
+    readingIsWorthWriting({ ...still, watchedBytes: 70 * MEGABYTE }),
+    true,
+    "memory given back is as interesting as memory taken"
+  );
+  assert.equal(
+    readingIsWorthWriting({ ...still, quietMs: 0 }),
+    true,
+    "no quiet interval means every reading is written, which is the process scope"
+  );
+});

package/test/piece-lru.test.js

@@ -171,3 +171,21 @@ test("a reader moving its window replaces it instead of accumulating", () => {
   assert.equal(lru.evictionCandidate(), 30, "the pieces already read are free again");
   assert.equal(lru.protectedCount, 1);
 });
+
+test("the capacity follows the store's live allowance", () => {
+  const lru = new PieceLru(4);
+  for (const index of [40, 41]) {
+    lru.touch(index);
+  }
+  assert.equal(lru.isFull(), false, "two of four is not full");
+
+  // The store's allowance moves with the machine's free memory, and the LRU is
+  // told. Before this it kept the capacity it was built with for ever, so
+  // `isFull` answered against a number that had stopped being the limit.
+  lru.setCapacity(2);
+  assert.equal(lru.capacity, 2);
+  assert.equal(lru.isFull(), true, "two of two is full");
+
+  lru.setCapacity(0);
+  assert.equal(lru.capacity, 2, "a capacity below one is refused, not obeyed");
+});

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

@@ -0,0 +1,263 @@
+/**
+ * @file Room for a piece is an owned reservation, and it comes back every time.
+ *
+ * Each case here is a defect read out of the field failure of 2026-08-31
+ * (`research/worker-heap-oom-2026-08-31.md`, §5), where the torrent worker was
+ * found holding reservations nobody could return. They all need the disk tier
+ * to be slow, or to fail, at a moment the caller chooses — which is what
+ * `options.disk` is for.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
+
+const CHUNK = 1024;
+
+/**
+ * A disk tier the test drives: writes can be held open and either side can be
+ * made to fail.
+ *
+ * @param {{ failWrite?: boolean, failRead?: boolean, holdWrites?: boolean }} [behaviour]
+ */
+function makeDisk({ failWrite = false, failRead = false, holdWrites = false } = {}) {
+  const stored = new Map();
+  /** @type {Array<() => void>} */
+  const held = [];
+  return {
+    stored,
+    /** Let every held write finish. */
+    releaseWrites() {
+      const waiting = held.splice(0, held.length);
+      for (const resume of waiting) {
+        resume();
+      }
+    },
+    get heldCount() {
+      return held.length;
+    },
+    get size() {
+      return stored.size;
+    },
+    has(index) {
+      return stored.has(index);
+    },
+    async write(index, bytes) {
+      if (holdWrites) {
+        await new Promise((resolve) => held.push(resolve));
+      }
+      if (failWrite) {
+        throw new Error("the disk refused the write");
+      }
+      stored.set(index, Buffer.from(bytes));
+    },
+    async read(index, target) {
+      if (failRead) {
+        throw new Error("the disk refused the read");
+      }
+      const bytes = stored.get(index);
+      if (!bytes) {
+        throw new Error(`Piece ${index} is not on disk.`);
+      }
+      bytes.copy(target);
+      return bytes.length;
+    },
+    forget(index) {
+      stored.delete(index);
+    },
+    async close() {},
+    async destroy() {
+      stored.clear();
+    }
+  };
+}
+
+/**
+ * @param {object} [options]
+ * @returns {{ store: SharedPieceStore, disk: ReturnType<typeof makeDisk> }}
+ */
+function makeStore({ pieces = 2, totalPieces = 16, disk = makeDisk() } = {}) {
+  const store = new SharedPieceStore(CHUNK, {
+    length: CHUNK * totalPieces,
+    memoryBytes: CHUNK * pieces,
+    disk,
+    name: "test"
+  });
+  return { store, disk };
+}
+
+/**
+ * @param {number} index
+ * @returns {Buffer}
+ */
+function piece(index) {
+  const bytes = Buffer.allocUnsafeSlow(CHUNK);
+  bytes.fill(index % 256);
+  bytes.writeUInt32BE(index, 0);
+  return bytes;
+}
+
+const put = (store, index) =>
+  new Promise((resolve, reject) => store.put(index, piece(index), (error) => (error ? reject(error) : resolve())));
+const get = (store, index) =>
+  new Promise((resolve, reject) =>
+    store.get(index, undefined, (error, bytes) => (error ? reject(error) : resolve(bytes)))
+  );
+
+/**
+ * Wait until a condition holds, rather than for a chosen interval — a test that
+ * sleeps samples, it does not check (roadmap item 54).
+ *
+ * @param {() => boolean} holds
+ * @param {string} what
+ * @returns {Promise<void>}
+ */
+async function until(holds, what) {
+  const deadline = Date.now() + 5_000;
+  while (!holds()) {
+    if (Date.now() > deadline) {
+      throw new Error(`timed out waiting until ${what}`);
+    }
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+}
+
+test("a revival that fails on the disk gives its slot back", async () => {
+  const disk = makeDisk({ failRead: true });
+  const { store } = makeStore({ pieces: 2, disk });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+    await put(store, 2); // piece 0 is the least recently used, so it spills
+
+    await assert.rejects(() => get(store, 0), /refused the read/);
+
+    assert.equal(
+      store.stats().outstanding,
+      0,
+      "the slot claimed for the revival was never returned"
+    );
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+  }
+});
+
+test("a spill that fails gives back the slot the eviction claimed", async () => {
+  const disk = makeDisk({ failWrite: true });
+  const { store } = makeStore({ pieces: 2, disk });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+    await assert.rejects(() => put(store, 2), /refused the write/);
+
+    assert.equal(store.stats().outstanding, 0, "the eviction kept its reservation");
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+  }
+});
+
+test("a claim that cannot be met ends in an error, not in waiting for ever", async () => {
+  const disk = makeDisk({ holdWrites: true });
+  const { store } = makeStore({ pieces: 2, disk });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+
+    // Evicts one piece; its write is held, so the store has a spill in flight
+    // for as long as this test wants.
+    const spilling = put(store, 2);
+    await until(() => disk.heldCount > 0, "a write is in flight");
+
+    // Nothing left that may be evicted: one piece is being written out, the
+    // other is pinned. The old rule waited while anything was nominally in
+    // flight, which here is for ever.
+    store.pin(1);
+    await assert.rejects(() => put(store, 3), /nothing moved/);
+
+    store.unpin(1);
+    disk.releaseWrites();
+    await spilling;
+  } finally {
+    disk.releaseWrites();
+    await new Promise((resolve) => store.destroy(resolve));
+  }
+});
+
+test("closing the store fails whoever is waiting for room", async () => {
+  const disk = makeDisk({ holdWrites: true });
+  const { store } = makeStore({ pieces: 2, disk });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+    const spilling = put(store, 2);
+    await until(() => disk.heldCount > 0, "a write is in flight");
+    store.pin(1);
+
+    const waiting = put(store, 3);
+    await until(() => store.stats().waitedForPins > 0, "the claim is waiting");
+
+    await new Promise((resolve) => store.close(resolve));
+    await assert.rejects(() => waiting, /closed/);
+
+    store.unpin(1);
+    disk.releaseWrites();
+    await spilling.catch(() => undefined);
+  } finally {
+    disk.releaseWrites();
+  }
+});
+
+test("a piece written back to memory is not resurrected on disk by its own spill", async () => {
+  const disk = makeDisk({ holdWrites: true });
+  const { store } = makeStore({ pieces: 3, disk });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+    await put(store, 2);
+
+    // Piece 0 leaves memory because the machine's allowance fell; its write is
+    // still in flight. The allowance then recovers, so there is room again
+    // without waiting for that write.
+    store.reviseGrowthCeiling(CHUNK * 2);
+    await until(() => disk.heldCount > 0, "the spill of piece 0 is in flight");
+    store.reviseGrowthCeiling(CHUNK * 3);
+
+    // The swarm hands piece 0 back while that write is still going. The store
+    // must drop the disk copy AFTER the write has recorded it, not before —
+    // `DiskTier.write` adds the index on completion, so an early forget is
+    // undone and the next read of piece 0 comes back from before the rewrite.
+    let settled = false;
+    const rewritten = put(store, 0);
+    void rewritten.then(() => {
+      settled = true;
+    });
+    await until(() => store.stats().resident === 3, "piece 0 is back in memory");
+    assert.equal(settled, false, "the write finished without waiting for the piece's own spill");
+
+    disk.releaseWrites();
+    await rewritten;
+
+    assert.equal(disk.has(0), false, "the completing spill put the stale copy back");
+  } finally {
+    disk.releaseWrites();
+    await new Promise((resolve) => store.destroy(resolve));
+  }
+});
+
+test("a spill that fails while the allowance is lowered is counted, not thrown", async () => {
+  const disk = makeDisk({ failWrite: true });
+  const { store } = makeStore({ pieces: 4, disk });
+  try {
+    await put(store, 0);
+    await put(store, 1);
+    await put(store, 2);
+    await put(store, 3);
+
+    store.reviseGrowthCeiling(CHUNK * 2);
+    await until(() => store.stats().spillFailures > 0, "the failed spills are counted");
+
+    assert.equal(store.stats().outstanding, 0, "lowering the allowance held a reservation");
+  } finally {
+    await new Promise((resolve) => store.destroy(resolve));
+  }
+});