@torrent-tv/proxy 2.99.21 → 2.100.1

package/bin/cli.js

@@ -89,7 +89,8 @@ program
   .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
   .option("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
   .option("--pin-preset <name>", "Encode every software picture at this libx264 preset only, for runs that must be compared at one quality (off by default)")
-  .option("--profile-start <seconds>", "Profile the main thread's CPU for this many seconds from the first source opened, written beside the state (off by default)")
+  .option("--heap-snapshots", "Write a heap snapshot of a thread whose memory reaches a new high-water; each one stops that thread while it is written (off by default)")
+  .option("--profile-start <seconds>", "Profile the CPU of the main thread and the torrent thread for this many seconds from the first source opened, written beside the state (off by default)")
   .option(
     "--send-chunk-bytes <bytes>",
     "Size of one data-channel message when sending a response body (0 = whatever the body read hands over, ~64KB). For measuring whether the delivery wedge depends on that size."
@@ -395,6 +396,7 @@ try {
     logFile: options.logFile ?? "",
     deliverySink: options.deliverySink === true,
     profileStartSeconds: Number(options.profileStart) || 0,
+    heapSnapshots: options.heapSnapshots === true,
     pinnedPreset: typeof options.pinPreset === "string" && options.pinPreset.trim() ? options.pinPreset.trim() : null,
     // Late-bound the same way `webRtcManager` is below: the torrent pool is
     // built inside `startProxyServer`, before `dataChannelHandler` — the
@@ -524,6 +526,7 @@ try {
     // 2026-09-07 and every one was gone by the time the process that wrote them
     // died of a heap it had never been possible to look at.
     snapshotDir: options.stateDir || undefined,
+    heapSnapshots: options.heapSnapshots === true,
     snapshotFloorBytes: 400 * 1024 * 1024,
     snapshotGrowthBytes: 400 * 1024 * 1024,
     keepSnapshots: 3

package/package.json

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

package/server.js

@@ -127,6 +127,8 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
 export async function startProxyServer({
   host, port, transcodeAudio, ffmpegBin, memoryBytes, segmentFormat, stateDir, onSubtitleCues, diagnostics, budgetPolicy,
   deliverySink = false,
+  // Whether a memory high-water earns a heap snapshot (`--heap-snapshots`).
+  heapSnapshots = false,
   // Seconds of main-thread CPU profile from the first source opened; 0 is off.
   profileStartSeconds = 0,
   // The one software preset every picture is encoded at, for runs compared at
@@ -178,6 +180,7 @@ export async function startProxyServer({
   const torrentPool = new WorkerTorrentPool({
     memoryBytes,
     stateDir,
+    heapSnapshots,
     onHoldingsChanged: () => onStateChanged(),
     onSourceForgotten: ({ sourceKey }) => {
       sourcePreparation?.forget(sourceKey);
@@ -942,6 +945,39 @@ export async function startProxyServer({
       }
       return { kind: "result", sources };
     },
+    // THE SOUND'S PACKETS FROM THE PICTURE'S COPY. A Matroska soundtrack is
+    // fed to its encoder packet by packet, and finding its packets walks the
+    // clusters the Cues name for the piece — picture and sound together,
+    // about 20 MB for 0.3 MB of sound on the field's 1080p film. The picture's
+    // input copies those same clusters through the torrent thread first, and
+    // walked a second time there each soundtrack piece took 6-11 s, slower
+    // than the film plays (r61, torrent-tv/meta#178). Walked from the copy
+    // while it is held, the sound reads only its own packets later.
+    stretchCopied: (output, from, to, input) => {
+      for (const source of input.sources ?? []) {
+        const container = containerOrchestrator.known(source.sourceKey, source.fileIndex);
+        const tracks = containerOrchestrator.tracks.get(`${source.sourceKey}:${source.fileIndex}`);
+        if (typeof container?.learnPackets !== "function" || !Array.isArray(tracks)) continue;
+        const carried = new Set((source.input.selections ?? []).map(selection => selection.track?.trackNumber));
+        const sounds = new Set();
+        for (const other of outputParts.outputs.values()) {
+          const sound = other.spec?.audio;
+          if (other.spec?.video || !sound || other.file?.sourceKey !== source.sourceKey || sound.fileIndex !== source.fileIndex) continue;
+          const track = tracks.filter(candidate => candidate.type === "audio")[sound.trackIndex];
+          if (track && !carried.has(track.trackNumber)) sounds.add(track.trackNumber);
+        }
+        if (!sounds.size || !Number.isFinite(source.input.from) || !(source.input.to > source.input.from)) continue;
+        const read = (start, end) => {
+          const answer = input.read(source.fileIndex, start, end);
+          return answer && typeof answer.then !== "function" && answer.end === end ? answer.bytes : null;
+        };
+        const startedAt = Date.now();
+        void container.learnPackets({ from: source.input.from, to: source.input.to, trackIds: [...sounds] }, read).then(learned =>
+          logger.info(`encode input #${from}..#${to} of ${output.outputKey}: soundtrack packets of track(s) ${[...sounds].join(",")} ` +
+            `over ${source.input.from.toFixed(3)}-${source.input.to.toFixed(3)}s ${learned ? "walked" : "not all walked"} from its copy in ${Date.now() - startedAt}ms`),
+        error => logger.warn(`encode input #${from}..#${to} of ${output.outputKey}: walking the soundtrack from its copy failed: ${error?.message ?? error}`));
+      }
+    },
     readEncodeRanges: async (source, ranges, maxBytes) => {
       const torrent = torrentPool.knownTorrent(source.sourceKey);
       return torrent ? torrentPool.readHeldRangesOf(torrent, source.fileIndex, ranges, maxBytes) : null;
@@ -1099,7 +1135,8 @@ export async function startProxyServer({
     seconds: profileStartSeconds,
     dir: stateDir || "",
     log: (line) => logger.info(line),
-    mayKeep: (bytes) => diagnostics?.mayKeep?.({ what: "a CPU profile", bytes }) ?? true
+    mayKeep: (bytes) => diagnostics?.mayKeep?.({ what: "a CPU profile", bytes }) ?? true,
+    torrentThread: (seconds) => torrentPool.cpuProfile?.(seconds) ?? Promise.resolve(null)
   });
   startProcessorReport({
     log: (line) => logger.info(line),

package/services/encode/EncodeInputs.js

@@ -55,9 +55,17 @@ export class EncodeInputs {
   #rankAt;
   #log;
   #now;
+  /**
+   * Told when an original input's stretch is copied whole, while its bytes are
+   * held, so what else they answer can be read from them (`learnPackets`).
+   *
+   * @type {(output: object, from: number, to: number, input: object) => void}
+   */
+  #stretchCopied;
 
   constructor({ resolve, readRanges, heldRanges = null, reviseBudget, changed, failed, capacity = () => null, urgent = () => true,
-    rankAt = () => null, openOf = () => null, log = () => {}, now = Date.now }) {
+    rankAt = () => null, openOf = () => null, log = () => {}, now = Date.now, stretchCopied = () => {} }) {
+    this.#stretchCopied = stretchCopied;
     this.#openOf = openOf;
     this.#resolve = resolve;
     this.#read = readRanges;
@@ -583,6 +591,10 @@ export class EncodeInputs {
       const copied = result.whole ?? Promise.resolve(true);
       void copied.then(whole => {
         if (whole && result.copyMs > 0) keep(this.#copyRates, result.bytes / result.copyMs);
+        if (whole) {
+          try { this.#stretchCopied(output, from, end, result); }
+          catch (error) { this.#log(`encode input #${from}..#${end} of ${addressOf(output)}: what was told of its copy failed: ${error?.message ?? error}`); }
+        }
         this.#log(`encode input #${from}..#${end} of ${addressOf(output)}: ` + (whole
           ? `stretch copied, ${result.bytes} bytes in ${result.copyMs}ms of copying since it was admitted`
           : result.copyFailed?.() ? "the stretch could not be copied: a piece it needs is no longer held"

package/services/media/container/MatroskaContainer.js

@@ -47,7 +47,8 @@ import { firstFrameOffset, readBlockHeader, walkHeldClusters } from "./matroska-
 import { buildMatroskaIndex, matroskaIntervalCovered, walkMatroskaPackets } from "./matroska-packets.js";
 import { PacketRecordsChain } from "./PacketRecordsChain.js";
 import { RetainedReads } from "./RetainedReads.js";
-import { isUnavailable } from "./unavailable.js";
+import { isUnavailable, strictReader } from "./unavailable.js";
+import { IndexMemoryUnavailable } from "./memory-unavailable.js";
 import {
   ID_ATTACHED_FILE, ID_ATTACHMENTS, ID_CHAPTERS, ID_FILE_DATA, ID_FILE_MEDIA_TYPE, ID_FILE_NAME, ID_INFO_TITLE, ID_TAGS,
   chapterTitlesOf, coverIndexOf, trackRatesFromTags, uidKeyOf, workFromTags
@@ -784,10 +785,12 @@ export class MatroskaContainer extends Container {
 
   /**
    * @param {object} [interval]
-   * @param {{ isCurrent?: () => boolean }} [options] - A walk whose request is
-   *   no longer current stops between clusters and answers null.
+   * @param {{ isCurrent?: () => boolean, readRange?: (start: number, end: number) => Promise<Buffer | null> | Buffer | null }} [options]
+   *   A walk whose request is no longer current stops between clusters and
+   *   answers null. `readRange`, when given, is where this one walk reads
+   *   instead of the file's own reader; what it does not hold is unavailable.
    */
-  async readPacketIndex(interval, { isCurrent } = {}) {
+  async readPacketIndex(interval, { isCurrent, readRange } = {}) {
     if (this.#packets) return this.#packets;
     const layout = await this.#segmentLayout();
     if (!layout) throw new Error("Matroska Segment is absent.");
@@ -806,7 +809,8 @@ export class MatroskaContainer extends Container {
     const complete = new Set();
     let whole = true;
     for (const track of requested) {
-      const chain = await this.#readTrackPackets(layout, tracks, track, start, interval, isCurrent);
+      const chain = await this.#readTrackPackets(layout, tracks, track, start, interval, isCurrent,
+        readRange ? strictReader(readRange, this.fileSize) : this.readRange);
       if (!chain) return null;
       streams.set(track.trackNumber, chain.records);
       if (chain.reachesEnd) complete.add(track.trackNumber);
@@ -818,6 +822,32 @@ export class MatroskaContainer extends Container {
     return index;
   }
 
+  /**
+   * Record these tracks' packets over `interval` from bytes another reader
+   * already holds, reading nothing of the file itself.
+   *
+   * A soundtrack's piece is walked over the clusters the Cues name for its
+   * interval, the picture's bytes with it: about 20 MB for 0.3 MB of sound on
+   * the field's 1080p film, read through the torrent thread a second time
+   * after the picture's input had copied the same clusters. Walked from that
+   * copy while it is held, the sound's input later reads only its own packets
+   * (r61, torrent-tv/meta#178).
+   *
+   * @param {{ from: number, to: number, trackIds: number[] }} interval
+   * @param {(start: number, end: number) => Buffer | null} readRange - Null where it does not hold the bytes.
+   * @returns {Promise<boolean>} Whether the interval's packets are recorded.
+   */
+  async learnPackets(interval, readRange) {
+    try {
+      return await this.readPacketIndex(interval, { readRange }) !== null;
+    } catch (error) {
+      // What the copy does not hold, or memory refused: the sound's own walk
+      // reads it later, from where this one stopped.
+      if (isUnavailable(error) || error instanceof IndexMemoryUnavailable) return false;
+      throw error;
+    }
+  }
+
   /**
    * One track's packets from `start` on, read as far as the interval needs.
    *
@@ -831,7 +861,7 @@ export class MatroskaContainer extends Container {
    *
    * @returns {Promise<{ records: PacketRecordsChain, startAt: number, reachesEnd: boolean }>}
    */
-  async #readTrackPackets(layout, tracks, track, start, interval, isCurrent) {
+  async #readTrackPackets(layout, tracks, track, start, interval, isCurrent, read) {
     const id = track.trackNumber;
     const previous = this.#packetWalks.get(id) ?? Promise.resolve();
     let finished;
@@ -886,7 +916,7 @@ export class MatroskaContainer extends Container {
         current = chainOf().at(-1);
         if (current.reachedEnd) break;
         const following = readings.find(reading => reading.startAt > current.startAt);
-        const outcome = await walkMatroskaPackets({ readRange: this.readRange, fileSize: this.fileSize,
+        const outcome = await walkMatroskaPackets({ readRange: read, fileSize: this.fileSize,
           portionBytes: this.portionBytes, layout, tracks, trackIds: [id], interval, packetMemory: this.packetMemory,
           state: current, until: following?.startAt ?? null, isCovered: covered, readsThrough, isCurrent });
         if (outcome === "obsolete") return null;

package/services/server/wire-outputs.js

@@ -226,6 +226,7 @@ export function wireOutputs({
     readMetadataActivity = null,
     sourceInputsFor = null,
     readEncodeRanges = null,
+    stretchCopied = () => {},
     readEncodeHeldRanges = null,
     encodeInputs = null,
     indexMemory = null,
@@ -1069,6 +1070,7 @@ export function wireOutputs({
     resolve: resolveEncodeInput,
     readRanges: readEncodeRanges,
     heldRanges: readEncodeHeldRanges,
+    stretchCopied,
     reviseBudget: () => parts.machineBudget.revise("memory", "admitted encode inputs"),
     capacity: () => parts.machineBudget.capacityOf("memory"),
     // How long this output's input takes to open, from the one owner of start

package/services/storage/cpu-profile.js

@@ -1,17 +1,23 @@
 /**
- * @file A CPU profile of the main thread at a cold start, asked for by the
- * operator and never taken otherwise (torrent-tv/meta#177).
+ * @file CPU profiles of the main thread and of the torrent thread, asked for
+ * by the operator and never taken otherwise (torrent-tv/meta#177, #178).
  *
  * At a cold start on the addon host (#166 run 12) the picture's first input
  * waited 29.5 s, 20.2 s of it inside a budget revision, while the main thread
  * ran at 83-108 % of a core; what it was doing is not in any log. A profile of
  * that thread names it.
  *
+ * The torrent thread is profiled beside it. After a seek on Home Assistant
+ * (r60, #178) a soundtrack's input waited 23.3 s, every read of held bytes took
+ * 1.5-6 s in that thread, its loop ran up to 2.7 s late and it drew three
+ * quarters of a core; what it spent them on is in no log either.
+ *
  * In-process, through `node:inspector`: the sampling profiler runs beside the
  * thread and does not stop it — unlike the debugger that stopped every thread
- * of this process on 2026-09-05 (torrent-tv/meta#77). It begins at the first
- * source opened, which is where a cold start begins, runs for the seconds the
- * operator named, and writes `cpu-start-<time>.cpuprofile` beside the log,
+ * of this process on 2026-09-05 (torrent-tv/meta#77). Both begin at the first
+ * source opened, which is where a cold start begins, run for the seconds the
+ * operator named, and are written by this thread under the one storage budget
+ * as `cpu-start-<time>.cpuprofile` (main) and `cpu-torrent-<time>.cpuprofile`,
  * readable in Chrome's DevTools (Performance, "Load profile").
  */
 
@@ -19,50 +25,72 @@ import { Session } from "node:inspector/promises";
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
 
+/**
+ * Profile the thread this runs on for `seconds`.
+ *
+ * @param {number} seconds
+ * @returns {Promise<object>} The profile, as `Profiler.stop` gives it.
+ */
+export async function profileThisThread(seconds) {
+  const session = new Session();
+  session.connect();
+  try {
+    await session.post("Profiler.enable");
+    await session.post("Profiler.start");
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, seconds * 1000);
+      if (typeof timer.unref === "function") timer.unref();
+    });
+    const { profile } = await session.post("Profiler.stop");
+    return profile;
+  } finally {
+    session.disconnect();
+  }
+}
+
 /**
  * @param {object} params
  * @param {number} params.seconds - How long to profile; nothing happens unless positive.
  * @param {string} params.dir - Where to write the profile.
  * @param {(line: string) => void} params.log
  * @param {(bytes: number) => boolean} [params.mayKeep] - Whether the storage budget lets it be kept.
+ * @param {(seconds: number) => Promise<string | null>} [params.torrentThread] - The torrent thread's
+ *   profile over the same seconds, as JSON text, or null when it could not be taken.
  * @returns {{ begin: () => void, active: () => boolean }}
  */
-export function startupCpuProfile({ seconds, dir, log, mayKeep = () => true }) {
+export function startupCpuProfile({ seconds, dir, log, mayKeep = () => true, torrentThread = null }) {
   let begun = false;
-  let running = false;
+  let running = 0;
   const wanted = Number.isFinite(seconds) && seconds > 0 && typeof dir === "string" && dir.length > 0;
-  const take = async () => {
-    const session = new Session();
-    session.connect();
+  const keep = async (name, text) => {
+    const bytes = Buffer.byteLength(text);
+    if (!mayKeep(bytes)) {
+      log(`cpu profile: ${name} not kept, ${bytes} bytes refused by the storage budget`);
+      return;
+    }
+    const file = path.join(dir, `cpu-${name}-${new Date().toISOString().replace(/[:.]/g, "-")}.cpuprofile`);
+    await writeFile(file, text);
+    log(`cpu profile: written to ${file} (${bytes} bytes)`);
+  };
+  const take = async (name, profile) => {
+    running += 1;
     try {
-      await session.post("Profiler.enable");
-      await session.post("Profiler.start");
-      running = true;
-      log(`cpu profile: the main thread is profiled for ${seconds}s from the first source opened`);
-      await new Promise((resolve) => {
-        const timer = setTimeout(resolve, seconds * 1000);
-        if (typeof timer.unref === "function") timer.unref();
-      });
-      const { profile } = await session.post("Profiler.stop");
-      const text = JSON.stringify(profile);
-      if (!mayKeep(Buffer.byteLength(text))) {
-        log(`cpu profile: not kept, ${Buffer.byteLength(text)} bytes refused by the storage budget`);
-        return;
-      }
-      const file = path.join(dir, `cpu-start-${new Date().toISOString().replace(/[:.]/g, "-")}.cpuprofile`);
-      await writeFile(file, text);
-      log(`cpu profile: written to ${file} (${Buffer.byteLength(text)} bytes)`);
+      const text = await profile();
+      if (text) await keep(name, text);
+    } catch (error) {
+      log(`cpu profile: ${name} failed — ${error.message}`);
     } finally {
-      running = false;
-      session.disconnect();
+      running -= 1;
     }
   };
   return {
     begin() {
       if (!wanted || begun) return;
       begun = true;
-      void take().catch((error) => log(`cpu profile: failed — ${error.message}`));
+      log(`cpu profile: the main thread${torrentThread ? " and the torrent thread are" : " is"} profiled for ${seconds}s from the first source opened`);
+      void take("start", async () => JSON.stringify(await profileThisThread(seconds)));
+      if (torrentThread) void take("torrent", () => torrentThread(seconds));
     },
-    active: () => running
+    active: () => running > 0
   };
 }

package/services/storage/memory-report.js

@@ -438,6 +438,12 @@ export function unaccountedBufferBytes(arrayBuffers, stores = []) {
  * @param {number} [options.snapshotFloorBytes]
  * @param {number} [options.snapshotGrowthBytes]
  * @param {number} [options.keepSnapshots] - Newest to keep; zero keeps all.
+ * @param {boolean} [options.heapSnapshots] - Whether a high-water earns a heap
+ *   snapshot at all. Off unless the operator asks: a snapshot stops the thread
+ *   for as long as it is written, and in a healthy session on Home Assistant
+ *   the torrent thread's array buffers reach the floor below — one snapshot
+ *   of 524 MB stopped that thread 4.4 s, 20 s after a seek the viewer was
+ *   waiting on (r61, torrent-tv/meta#178).
  * @param {number} [options.bufferSnapshotFloorBytes] - Array buffers above what
  *   the stores hold that earn a snapshot of their own; zero never takes one.
  * @param {number} [options.bufferSnapshotGrowthBytes]
@@ -460,6 +466,7 @@ export function startMemoryReport({
   snapshotFloorBytes = 500 * 1024 * 1024,
   snapshotGrowthBytes = 100 * 1024 * 1024,
   keepSnapshots = 0,
+  heapSnapshots = false,
   bufferSnapshotFloorBytes = 0,
   bufferSnapshotGrowthBytes = 500 * 1024 * 1024
 }) {
@@ -601,7 +608,7 @@ export function startMemoryReport({
       // and when V8 did kill the process at 1.99 GB of old space, no snapshot
       // had ever been taken of the growth that did it.
       const heapWatched = processMemory.heapTotal;
-      if (heapWatched > highWater + snapshotGrowthBytes && heapWatched > snapshotFloorBytes) {
+      if (heapSnapshots && heapWatched > highWater + snapshotGrowthBytes && heapWatched > snapshotFloorBytes) {
         highWater = heapWatched;
         await takeSnapshot(heapWatched, "a new high-water of the heap");
       }
@@ -609,6 +616,7 @@ export function startMemoryReport({
       // the heap: each one is in it with its size and its holder.
       const unaccounted = unaccountedBufferBytes(processMemory.arrayBuffers, stores);
       if (
+        heapSnapshots &&
         bufferSnapshotFloorBytes > 0 &&
         unaccounted > bufferSnapshotFloorBytes &&
         unaccounted > bufferHighWater + bufferSnapshotGrowthBytes

package/services/storage/piece-store/piece-disk-store.js

@@ -283,7 +283,23 @@ export class PieceDiskStore {
     await this.#removing.get(index);
     await this.#ensureDirectory();
     await this.#makeRoomFor(bytes.length, index);
-    await fs.writeFile(this.#pathOf(index), bytes);
+    // ONE WRITE FOR THE PIECE, not `fs.writeFile`: that writes 512 KiB at a
+    // time, sixteen requests for an 8 MiB piece, and each waits for a turn of
+    // this thread's loop. On Home Assistant the torrent thread's loop ran about
+    // a second late while downloading, a piece took that many seconds to reach
+    // the disk, and pieces arriving at 20 MB/s waited for their writes: 1.1 GB
+    // of them in that thread's memory at once (r61, torrent-tv/meta#178).
+    const handle = await fs.open(this.#pathOf(index), "w");
+    try {
+      let written = 0;
+      while (written < bytes.length) {
+        const { bytesWritten } = await handle.write(bytes, written, bytes.length - written, written);
+        if (!(bytesWritten > 0)) throw new Error(`Piece ${index} could not be written: the disk took nothing.`);
+        written += bytesWritten;
+      }
+    } finally {
+      await handle.close();
+    }
     if (!this.#stored.has(index)) {
       this.#bytes += bytes.length;
     } else {

package/services/torrent/worker/client.js

@@ -117,13 +117,13 @@ export class TorrentWorkerClient {
   /**
    * @param {{ memoryBytes?: number, stateDir?: string, onPiecesArrived?: (event: object) => void }} [options]
    */
-  constructor({ memoryBytes, stateDir, onPiecesArrived, onSourceForgotten, onHoldingsChanged } = {}) {
+  constructor({ memoryBytes, stateDir, heapSnapshots = false, onPiecesArrived, onSourceForgotten, onHoldingsChanged } = {}) {
     this.#worker = new Worker(fileURLToPath(WORKER_URL), {
       // `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: { memoryBytes, stateDir }
+      workerData: { memoryBytes, stateDir, heapSnapshots }
     });
     this.#caller = createCaller(this.#worker);
     this.#onPiecesArrived = onPiecesArrived ?? (() => undefined);
@@ -744,6 +744,17 @@ export class TorrentWorkerClient {
     return this.wholeFileBytes ?? 0;
   }
 
+  /**
+   * A processor profile of the torrent thread over `seconds`, as JSON text.
+   *
+   * @param {number} seconds
+   * @returns {Promise<string | null>}
+   */
+  async cpuProfile(seconds) {
+    const text = await this.#caller.call(Command.CPU_PROFILE, { seconds });
+    return typeof text === "string" ? text : null;
+  }
+
   /**
    * Say how much disk the spilled pieces on this thread may take between them.
    *

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

@@ -278,6 +278,11 @@ export class WorkerTorrentPool {
    *
    * @returns {Promise<{ infoHash: string, progress: number, bytes: number }[]>}
    */
+  /** A processor profile of the torrent thread, as JSON text (`TorrentWorkerClient.cpuProfile`). */
+  async cpuProfile(seconds) {
+    return this.#client.cpuProfile(seconds);
+  }
+
   async heldTorrents() {
     const answer = await this.#client.heldTorrents();
     return Array.isArray(answer?.held) ? answer.held : [];

package/services/torrent/worker/protocol.js

@@ -107,6 +107,8 @@ export const Command = {
   SPILL_ALLOWANCE: "spill-allowance",
   WHOLE_FILES_ALLOWANCE: "whole-files-allowance",
   MEMORY_ALLOWANCE: "memory-allowance",
+  /** Profile this thread's processor for some seconds and answer with the profile as JSON text (opt-in, torrent-tv/meta#178). */
+  CPU_PROFILE: "cpu-profile",
   DESTROY_ALL: "destroy-all"
 };
 

package/services/torrent/worker/worker.js

@@ -39,6 +39,7 @@ import { wholeFileStats } from "./whole-file-stats.js";
 import { describeHeldObjects, readUtpOpenCount } from "./held-objects.js";
 import { destroyedTorrents } from "../destroyed-torrents.js";
 import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../../storage/memory-report.js";
+import { profileThisThread } from "../../storage/cpu-profile.js";
 import { forwardLogsTo, logger } from "../../../utils/logger.js";
 
 /**
@@ -603,6 +604,12 @@ async function runCommand(command, params, id) {
       return after.bytes;
     }
 
+    case Command.CPU_PROFILE: {
+      // The operator's profile of this thread, written by the main thread under
+      // the storage budget there (`storage/cpu-profile.js`).
+      return JSON.stringify(await profileThisThread(Number(params.seconds)));
+    }
+
     case Command.DESTROY_ALL: {
       torrentsByKey.clear();
       resolvedTorrents.clear();
@@ -685,6 +692,7 @@ startMemoryReport({
   quietMs: 60_000,
   changeBytes: 25 * 1024 * 1024,
   snapshotDir: workerData?.stateDir || undefined,
+  heapSnapshots: workerData?.heapSnapshots === true,
   snapshotFloorBytes: 400 * 1024 * 1024,
   snapshotGrowthBytes: 400 * 1024 * 1024,
   // CHOSEN, not derived: no healthy session has recorded this figure yet, so