@torrent-tv/proxy 2.78.0 → 2.80.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 2.80.0
+
+- **Fix**: The reading of usrsctp's own state is OFF unless `--usrsctp-state` is given, and its deadline is counted by a separate process. On 2026-09-05 a delivery probe declared a wedge that lasted half a second and cleared itself; the reading it triggered attached gdb to this process, which stops every one of its eighty threads for as long as it is attached. The log ended mid-second, `/healthz` stopped answering, and the viewer waited a minute and was told the proxy had sent no video. The fifteen-second guard could not fire — it was a timer inside the process gdb had stopped — and killing gdb left the main thread deadlocked for good, so only restarting the addon recovered it. A means of diagnosis may not stop the product: this one attaches to a live process and is triggered by a verdict with a known history of false positives, so it is switched on deliberately while somebody is watching, and `timeout` counts its seconds from outside.
+
+## 2.79.0
+
+- **Fix**: Starting an encoder no longer stops another one. The line that did it looked for a live run whose own start was not below the new one's and killed it — a rule left from when a session held exactly one run and "the previous one" meant "the only one". Once a session could hold several, it began killing runs the plan had decided to keep: 294 stops for that reason in eight minutes of field 2026-09-05, against four starts a viewer had asked for. Who is stopped is decided in one place now, and starting is not it.
+- **Fix**: The stretch an encoder is given reaches it. The plan computed where a run may work to, passed it, and the receiving parameter list did not name it — so it was dropped and the end was computed a second time somewhere else. That was the last remaining second answer to "how far may this run work".
+- **Fix**: An encoder is built and handed back in the same call, so the stretch it is making is held from that instant. It used to answer with nothing and start the encoder behind the answer, leaving the stretch free in the map for as long as that took — and every pass in between started another encoder for it. Measured in the field: 684 starts in 482 seconds, of which 973 answers said the encoder was not there yet, which is every start without exception. Nothing is waited for on that path any more; the one thing it used to wait for was the death of the run it was replacing.
+- **Fix**: Whether to move a running encoder is a comparison with both sides counted, and the terms are measured on this host rather than written into the code. Driving through material that exists costs this run's own encode time for it and costs the swarm the same bytes a second time; moving costs the death of the run, the start of another and the wait for its first output. A run whose speed nothing has measured is now KEPT: moving costs a known amount for an unknown gain, and a run that has produced nothing has nothing worth taking away. It used to answer the other way, and with the whole film ahead already made, every just-started encoder was moved before it produced anything.
+- **New**: What a stop and a start cost is measured (`encode/run-costs.js`). A run times its own death from the moment it is told to stop, and the appearance of its first output from the moment it started. Both were absent: the start was one reading taken once on one machine and written in as a constant, and the other two were not counted at all, so the comparison priced one side of itself.
+- **New**: The encoding orchestrator says what it believes — what is ready, which zones were stated and in what order, which encoders are running and at what speed, and the lowest number a viewer is waiting for. The line was written and called from nowhere, so on 2026-09-05 the question "why did the plan not see the gap the viewer was stopped at" had to be answered by inference and was not answered at all. Printed when it changes rather than on a timer.
+- **Chore**: The piece a run had open when it ended is thrown away by the layer that owns the directories (`encode/open-piece.js`, `SegmentStore.discardOpenPieceOf`), on every ending but the one normal one. It used to be done by the single place that killed a run, and that place is gone.
+
+- **Fix**: A seek does one thing — it puts the viewer where they now are. It used to do eleven, and wrote that position into five places: two fields on the picture's session, two on the soundtrack's, and the viewer. It also asked whether the jump would drag another viewer back, started an encoder itself, cancelled outstanding requests, backed off a segment to the preceding keyframe and set a timer to restart ffmpeg — so it was a third authority over the encoders, and not one of its branches ever asked what had already been made. A viewer jumping into a stretch that was finished and on disk got a fresh encoder for it.
+- **Fix**: A viewer's position is held in SECONDS of film and nowhere else. It used to carry a segment number too, and the picture and the soundtrack of one film are cut independently and into different numbers of pieces — 454 against 401 on the field file of 2026-09-05 — so piece 48 of one is not the same moment as piece 48 of the other. Whoever holds a cut grid turns the seconds into their own numbers.
+- **New**: The page says whether the picture is moving, and says it the moment it changes rather than at the next ten-second report. A viewer who has stopped consumes nothing, so nothing in front of them ever falls due and the work goes to whoever is watching — which follows from one boolean without any rule about pauses anywhere. Inferring it from a position that has not moved takes two reports and is wrong whenever a browser holding a full cushion goes quiet between segments, which it does.
+- **Fix**: Below realtime the priority map says how many encoders are needed, and the zones grow rather than being equal. An encoder starting at `q` stays ahead of a viewer at `p` for `(q - p) x s / (1 - s)`, which grows with its distance from them — so equal shares are the wrong division, and by a wide margin: on the addon host with 2400 s of film left, 120 s held and 0.5x, equal shares need twenty encoders and growing ones need five (120, 240, 480, 960, 1920). Each zone is exactly as long as its bound allows, which makes the count the smallest that holds the viewer.
+- **Fix**: How many encoders may run is the smallest of three measured limits, not one. The processor was the only one asked. Every encoder reads the same torrent, so together they cannot consume faster than it is delivered — on the field file a second of film weighs 842 KB against 2119-3347 KB/s from the swarm, so the speeds together may reach 2.5-4x, and a copy the processor would run at 8x runs at four. Encoders placed apart hold reading windows that do not overlap, so the piece store must hold their sum; on the addon host it was already full on the readers of one viewer. Which limit decided is said in the line.
+- **New**: A piece is proven finished by the encoder's own word for it: ffmpeg names each file on a channel of its own the moment it closes it, and that name is kept. What stood there was the existence of the NEXT file, with two exceptions bolted on because it is not true — it is never true of the last piece of a run, so the first segment of every run was held from the viewer. Measured 2026-08-09: #807 held while it lay on disk, and in August the same shape held #317 for 46 seconds and then answered 404 to a browser that had given up.
+- **Chore**: The priority map is a layer of its own (`services/priority/`), below both orchestrators and depending on nothing. It knows only priorities: what is downloaded is the download orchestrator's own knowledge, what is encoded is the encoding orchestrator's, and neither is visible from the map.
+- **Chore**: A check on the shape rather than the behaviour (`test/one-authority.test.js`): one place stops an encoder for scheduling reasons, one place builds one, a start stops nothing, a seek starts nothing, and the stretch computed by the plan is the one handed over. Every rule in it is one that was broken on 2026-09-05.
+
 ## 2.78.0
 
 - **Fix**: One authority over the encoders, where there were three. A viewer watching an episode on 2026-09-05 had their picture stop for 125 seconds while the proxy spawned and killed an encoder every 350-700ms, producing nothing. Two decisions were contradicting each other on every pass: the plan commanded a start inside the viewer's window, at #46; `planRunInterval` in the session manager moved that start to #78, because it counted every live run as claiming up to its head plus the look-ahead; and the plan then saw a run at #78 against a window of [27, 57], found no overlap and killed it as "nothing it was given is wanted". Neither coverage nor demand changed between two such passes, so the same start was commanded again, for as long as anybody watched. `planRunInterval` is deleted: where a run starts is the plan's decision and nothing moves it, and how far it may work is read off the one coverage map the plan itself uses.

package/bin/cli.js

@@ -85,6 +85,10 @@ program
   .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
   .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(
+    "--usrsctp-state",
+    "Read usrsctp's association state with gdb when a wedge is declared. OFF by default: gdb attaches to THIS process and stops every thread of it while it works."
+  )
   .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
   .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
   .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
@@ -345,7 +349,22 @@ try {
   // 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) });
+  // OFF UNLESS ASKED FOR, and the reason is a field incident rather than
+  // caution. On 2026-09-05 a delivery probe declared a wedge that lasted half a
+  // second and cleared itself; the reading it triggered attached gdb to this
+  // process, which stopped all eighty of its threads. The log ended mid-second,
+  // /healthz stopped answering, and the viewer waited a minute and was told the
+  // proxy had sent no video. The fifteen-second guard could not fire — it is a
+  // timer inside the process gdb had stopped — and killing gdb left the main
+  // thread deadlocked for good, so only restarting the addon recovered it.
+  //
+  // A means of diagnosis may not stop the product. This one attaches to a live
+  // process and is triggered by a verdict with a known history of false
+  // positives, so it is a thing to switch on deliberately while watching, not
+  // something that arms itself.
+  usrsctpStateReader = options.usrsctpState === true
+    ? createUsrsctpStateReader({ log: (message) => logger.info(message) })
+    : null;
 
   // 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

package/biome.json

@@ -28,6 +28,7 @@
 				"services/output/**",
 				"services/viewer/**",
 				"services/encode/**",
+				"services/priority/**",
 				"services/source/**",
 				"services/torrent/**"
 			],

package/package.json

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

package/routes/api/transcode-sessions/net-report/post.js

@@ -33,11 +33,16 @@ export async function handleApiTranscodeSessionNetReportPost(req, reply, { hlsSe
   // the proxy uses to tell the viewers of one session apart, and a report
   // without them is still a truthful reading of somebody's link.
   const consumerId = typeof body.consumerId === "string" ? body.consumerId.trim() : "";
+  // Whether the picture is moving. Absent from a page that does not say, and
+  // then the viewer counts as playing, which is what every page meant before it
+  // could say otherwise.
+  const playing = typeof body.playing === "boolean" ? body.playing : undefined;
   const positionSeconds = Number(body.positionSeconds);
   const recorded = hlsSessionManager.recordNetReport(sessionId, {
     linkMbps,
     bufferedAheadSec,
     consumerId,
+    playing,
     positionSeconds:
       Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : undefined
   });

package/services/encode/EncodePlan.js

@@ -110,7 +110,10 @@ export function planEncoders({
   runs,
   maxRuns,
   segmentSeconds,
-  restartCostSec
+  restartCostSec,
+  killCostSec = 0,
+  firstByteWaitSec = 0,
+  refetchSecPerFilmSecond = 0
 }) {
   /** @type {PlanAction[]} */
   const stops = [];
@@ -174,14 +177,35 @@ export function planEncoders({
       continue;
     }
 
-    // Driving through costs its own encode time for material that exists.
-    // Moving costs one restart. Both are measured; neither is chosen here.
+    // WHICH IS CHEAPER, AND BOTH SIDES COUNTED WHOLE.
     //
-    // A run whose speed nothing has measured yet cannot be compared, and then
-    // moving is the answer rather than a default: driving through is work that
-    // is certainly wasted, while the restart is a known and small cost.
-    const driveSec = run.speedX > 0 ? (coveredAhead * segmentSeconds) / run.speedX : null;
-    if (driveSec !== null && driveSec <= restartCostSec) {
+    // Driving through material that exists costs this run's own encode time for
+    // it, and costs the swarm the same bytes a second time — the film has to be
+    // fetched again to be encoded again.
+    //
+    // Moving costs the death of this run, the start of another, and the wait
+    // for the first bytes at the new position. The last of those is the largest
+    // in the field and the one nothing measures yet; while it is unmeasured it
+    // counts as zero, which makes moving look cheaper than it is.
+    //
+    // A run whose speed nothing has measured yet cannot be compared at all, and
+    // then it is KEPT. Moving costs a known amount for an unknown gain, and a
+    // fresh run has produced nothing, so taking its work away is certainly a
+    // loss. This used to answer the other way, and every just-started run was
+    // moved the moment anything ahead of it was covered — which, once the whole
+    // film ahead had been made, was always.
+    // Both sides have to be known for the comparison to mean anything. The
+    // encoder's own speed is one; what the swarm charges to fetch the same
+    // bytes again is the other, and where nothing has measured it the sum is
+    // not a cost but a fragment of one. Answering from a fragment biases the
+    // decision one way — towards moving, since the missing term is on the
+    // driving side — so an unknown term is a reason to keep, exactly as an
+    // unmeasured speed is.
+    const known = run.speedX > 0 && refetchSecPerFilmSecond > 0;
+    const refetchSec = coveredAhead * segmentSeconds * refetchSecPerFilmSecond;
+    const driveSec = known ? (coveredAhead * segmentSeconds) / run.speedX + refetchSec : null;
+    const moveSec = restartCostSec + killCostSec + firstByteWaitSec;
+    if (driveSec === null || driveSec <= moveSec) {
       surviving.add(run);
       keeps.push({ type: "keep", run, from: run.head, to: run.to });
       continue;
@@ -194,10 +218,12 @@ export function planEncoders({
       run,
       from: gap,
       to: endOfStretch(gap, free),
-      because: driveSec === null
-        ? `${coveredAhead} segment(s) ahead are already covered and its speed is not measured`
-        : `driving through ${coveredAhead} covered segment(s) costs ${driveSec.toFixed(2)}s ` +
-          `against ${restartCostSec.toFixed(2)}s to move`
+      because:
+        `driving through ${coveredAhead} covered segment(s) costs ${driveSec.toFixed(2)}s ` +
+        `(encode ${((coveredAhead * segmentSeconds) / run.speedX).toFixed(2)}s + ` +
+        `refetch ${refetchSec.toFixed(2)}s) against ${moveSec.toFixed(2)}s to move ` +
+        `(kill ${killCostSec.toFixed(2)}s + start ${restartCostSec.toFixed(2)}s + ` +
+        `first bytes ${firstByteWaitSec.toFixed(2)}s)`
     });
   }
 

package/services/encode/EncodeRun.js

@@ -96,6 +96,28 @@ export class EncodeRun {
   /** @type {number} */
   #startedAt = 0;
 
+  /** Half a name left over from the last chunk of the encoder's own channel. */
+  #closedTail = "";
+
+  /**
+   * When this run was told to stop, so the death itself can be priced.
+   *
+   * The plan weighs moving an encoder against letting it drive on, and dying is
+   * one of the terms. It was measured in the field at 430-729 ms — larger than
+   * the start it is added to — by a log line that lived in the one place that
+   * killed a run. That place is gone, so the run times its own death.
+   */
+  #stopOrderedAt = 0;
+
+  /**
+   * When the first thing this run ever produced appeared.
+   *
+   * The other term the plan needs: a run started where nothing is downloaded
+   * waits for the swarm before it can encode a frame, and that wait is the
+   * largest part of what a restart costs. Nothing measured it before.
+   */
+  #firstOutputAt = 0;
+
   /** @type {number} */
   #speedX = 0;
 
@@ -132,6 +154,9 @@ export class EncodeRun {
    * @param {{ info: (line: string) => void, warn: (line: string) => void, error?: (line: string) => void }} params.logger
    * @param {() => number} [params.now]
    * @param {(ended: RunEnded) => void} [params.onEnded]
+   * @param {(name: string) => void} [params.onClosed] - Called with the file name
+   *   of every piece the encoder has FINISHED writing, as the encoder itself
+   *   names it on its own channel.
    * @param {(progress: { processedSeconds: number | null, speed: string | null }) => void} [params.onProgress]
    *   Called for every `-progress` report. Seconds count from the START OF THIS
    *   RUN on both branches — neither `-output_ts_offset` nor `-copyts` changes
@@ -158,6 +183,7 @@ export class EncodeRun {
     logger,
     now,
     onEnded,
+    onClosed,
     onProgress,
     lastSegmentIndex,
     inputUnavailable,
@@ -174,6 +200,9 @@ export class EncodeRun {
     this.now = typeof now === "function" ? now : Date.now;
     this.onEnded = typeof onEnded === "function" ? onEnded : () => {};
     this.onProgress = typeof onProgress === "function" ? onProgress : () => {};
+    // Told the NAME of every piece the encoder has closed. The name is the
+    // proof it is whole; nothing else here can prove that.
+    this.onClosed = typeof onClosed === "function" ? onClosed : () => {};
     this.lastSegmentIndex = typeof lastSegmentIndex === "function" ? lastSegmentIndex : () => null;
     this.inputUnavailable = typeof inputUnavailable === "function" ? inputUnavailable : () => false;
     this.argsDescribed = argsDescribed;
@@ -304,6 +333,16 @@ export class EncodeRun {
    */
   #wire(process) {
     process.stdout?.on("data", (chunk) => this.#readProgress(String(chunk)));
+    // THE CHANNEL THE ENCODER NAMES ITS FINISHED PIECES ON.
+    //
+    // A name arrives here when ffmpeg CLOSES the file, so the name is proof the
+    // piece is whole — measured on the addon host 2026-09-05. Nothing else can
+    // prove it: a file on disk may still be being written, and the only other
+    // evidence available was the existence of the NEXT file, which never comes
+    // for the last piece of a run.
+    //
+    // Lines can arrive split, so what is left over is kept for the next chunk.
+    process.stdio?.[3]?.on("data", (chunk) => this.#readClosedPieces(String(chunk)));
     process.stderr?.on("data", (chunk) => {
       const line = String(chunk).trim();
       if (line.length > 0) {
@@ -358,6 +397,9 @@ export class EncodeRun {
   noteProduced(index) {
     if (Number.isInteger(index) && index >= this.from) {
       this.#produced.add(index);
+      if (this.#firstOutputAt === 0) {
+        this.#firstOutputAt = this.now();
+      }
       if (this.#state === ENCODE_RUN_STATE.STARTING) {
         this.#transition(ENCODE_RUN_EVENT.FIRST_SEGMENT);
       }
@@ -369,6 +411,25 @@ export class EncodeRun {
    *
    * @param {number} speedX - Times realtime.
    */
+  /**
+   * Names of finished pieces, as the encoder writes them.
+   *
+   * @param {string} text
+   */
+  #readClosedPieces(text) {
+    this.#closedTail += text;
+    const lines = this.#closedTail.split(/\r?\n/);
+    // The last piece of the chunk may be half a name; it waits for the rest.
+    this.#closedTail = lines.pop() ?? "";
+    for (const line of lines) {
+      const name = line.trim();
+      if (name.length === 0) {
+        continue;
+      }
+      this.onClosed(name);
+    }
+  }
+
   noteSpeed(speedX) {
     if (Number.isFinite(speedX) && speedX > 0) {
       this.#speedX = speedX;
@@ -389,6 +450,7 @@ export class EncodeRun {
     }
     this.#stopping = true;
     this.#stopReason = because;
+    this.#stopOrderedAt = this.now();
     this.#transition(ENCODE_RUN_EVENT.STOP_ORDERED);
     // A suspended process does not act on SIGTERM until it is continued, so the
     // wait for its exit would never end. Let it run before asking it to stop.
@@ -554,6 +616,14 @@ export class EncodeRun {
       to: this.to,
       reached: this.reached,
       livedMs,
+      // How long dying took, and how long the first output took to appear.
+      // Null where the run was never told to stop, or never produced anything:
+      // an absent measurement says so rather than reading as zero.
+      dyingMs: this.#stopOrderedAt > 0 ? this.now() - this.#stopOrderedAt : null,
+      firstOutputMs:
+        this.#firstOutputAt > 0 && this.#startedAt > 0
+          ? this.#firstOutputAt - this.#startedAt
+          : null,
       normal: ending === ENCODE_EXIT.COMPLETE,
       lastError: this.lastError
     };

package/services/encode/SegmentStore.js

@@ -39,6 +39,8 @@ import { rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { discardOpenPiece } from "./open-piece.js";
+
 /** Where every output's segments live. One root for the process. */
 export const DEFAULT_STORE_ROOT = path.join(os.tmpdir(), "torrent-tv-hls");
 
@@ -256,6 +258,30 @@ export class SegmentStore {
     return proven.sort((left, right) => left - right);
   }
 
+  /**
+   * Whether this piece is finished, and may therefore be served.
+   *
+   * Two proofs, and the first is the good one:
+   *
+   * 1. **the encoder said so** — it names each file on a channel of its own the
+   *    moment it closes it, so the name is the writer's own statement that the
+   *    piece is whole;
+   * 2. **the next file exists** — which only proves it for pieces this process
+   *    did not watch being written, left by an earlier life of it. It is not
+   *    true of the last piece of any run, and that is what used to hold the
+   *    first segment of every run from the viewer.
+   *
+   * @param {string} key
+   * @param {number} index
+   * @returns {boolean}
+   */
+  isClosed(key, index) {
+    if (this.#closed.get(key)?.has(index)) {
+      return true;
+    }
+    return this.refresh(key).byNumber.has(index + 1);
+  }
+
   /**
    * Say that a segment is closed for a reason the disk cannot show.
    *
@@ -277,6 +303,39 @@ export class SegmentStore {
     known.add(index);
   }
 
+  /**
+   * Throw away the piece a run had open when it ended, if it is unusable.
+   *
+   * The store owns this output's directory and knows how its files are named,
+   * so it is the one place that can answer which file a run left open. The
+   * judging of a NON-EMPTY file — does it carry every track it should — needs
+   * the output's init bytes and belongs to whoever holds them; passed in, and
+   * absent it only an empty file is removed, which is the case that caused this
+   * to be written (a run stopped 548 ms after starting left a zero-byte file
+   * whose name then read as a segment made).
+   *
+   * @param {string} key
+   * @param {{ from: number, to: number } | null} within - The run's own
+   *   numbers: several runs write into one directory, so the piece to discard
+   *   has to be looked for inside the stretch the ended run was given.
+   * @param {((raw: Buffer) => boolean) | null} [judgeUsable]
+   * @returns {Promise<number | null>} The segment number removed, or null.
+   */
+  async discardOpenPieceOf(key, within, judgeUsable = null) {
+    const format = this.#formats.get(key);
+    if (!format) {
+      return null;
+    }
+    const removed = await discardOpenPiece(this.directoryFor(key), format, within, judgeUsable);
+    if (removed !== null) {
+      this.#held.delete(key);
+      this.#logger?.info?.(
+        `segment store: discarded the open piece #${removed} of ${key.slice(0, 60)}`
+      );
+    }
+    return removed;
+  }
+
   /**
    * The one number in this output whose closure nothing on disk proves.
    *

package/services/encode/open-piece.js

@@ -0,0 +1,88 @@
+/**
+ * @file The piece a run had open when it ended.
+ *
+ * A fact of a run's output directory, and therefore of the encoding layer. It
+ * lived in the eleven-thousand-line file that is being taken apart, where it was
+ * called by the one place that killed a run; stopping is decided in one place
+ * now and carried out in another, so the cleanup belongs to the layer that owns
+ * the directories rather than to whoever happened to do the killing.
+ */
+
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Remove the piece a run had open when it ended, if that piece is unusable.
+ *
+ * The `segment` muxer creates its output file when it OPENS it and writes into
+ * it until the next cut, so at any instant exactly one file in a run's
+ * directory is unfinished: the highest-numbered one. A run that reaches the end
+ * of its work closes that file and it is a good piece; a run killed for a seek
+ * does not — measured 2026-09-03, ffmpeg exited 19 ms after SIGTERM and left
+ * `segment-00025.mp4` at zero bytes, which then closed the only hole in the
+ * numbering and convinced the look-ahead to keep the encoder stopped for having
+ * "produced" it.
+ *
+ * Only an unusable piece goes. A run stopped between two cuts leaves a finished
+ * file behind, and deleting good output would mean making it a second time.
+ *
+ * @param {string | null | undefined} runDirPath
+ * @param {{ isSegmentFileName: (name: string) => boolean, segmentIndexFromName: (name: string) => number }} segmentFormat
+ * @param {((raw: Buffer) => boolean) | null} judgeUsable - Whether a non-empty
+ *   piece carries what it should. Null where nothing can say, and then only an
+ *   empty file is removed.
+ * @returns {Promise<number | null>} The segment number removed, or null.
+ */
+export async function discardOpenPiece(runDirPath, segmentFormat, within, judgeUsable) {
+  if (!runDirPath || typeof segmentFormat?.isSegmentFileName !== "function") {
+    return null;
+  }
+  // Only inside the stretch the ended run was given. Every run of an output
+  // writes into one directory now — they are kept apart by their intervals
+  // rather than by a directory each — so the highest-numbered file in there may
+  // belong to a run that is still going, and removing it would take away a
+  // piece somebody is producing.
+  const from = Number.isInteger(within?.from) ? within.from : 0;
+  const to = Number.isInteger(within?.to) && within.to >= from ? within.to : Number.MAX_SAFE_INTEGER;
+  let highest = null;
+  try {
+    for (const name of await readdir(runDirPath)) {
+      if (!segmentFormat.isSegmentFileName(name)) {
+        continue;
+      }
+      const index = segmentFormat.segmentIndexFromName(name);
+      if (index < from || index > to) {
+        continue;
+      }
+      if (index >= 0 && (highest === null || index > highest.index)) {
+        highest = { index, name };
+      }
+    }
+  } catch {
+    return null; // The run wrote nothing, or its directory is already gone.
+  }
+  if (highest === null) {
+    return null;
+  }
+  const filePath = path.join(runDirPath, highest.name);
+  let unusable = false;
+  try {
+    const info = await stat(filePath);
+    if (info.size === 0) {
+      unusable = true;
+    } else if (typeof judgeUsable === "function") {
+      unusable = !judgeUsable(await readFile(filePath));
+    }
+  } catch {
+    return null; // Gone between the listing and the question.
+  }
+  if (!unusable) {
+    return null;
+  }
+  try {
+    await unlink(filePath);
+    return highest.index;
+  } catch {
+    return null; // Already removed.
+  }
+}

package/services/encode/run-budget.js

@@ -0,0 +1,89 @@
+/**
+ * @file How many encoders this machine can afford on one output.
+ *
+ * Not how many are wanted — that is the demand map's answer — but how many can
+ * run at once without making things worse. It is the SMALLEST of several
+ * limits, and every one of them is measured:
+ *
+ * 1. **the processor.** A second encoder slows the first: measured on the addon
+ *    host at 1.70x for two at 854x480 and 1.98x at 1920x1080. The ladder is
+ *    walked while the measured penalty still leaves every encoder above
+ *    realtime, and it stops where the measurements stop rather than continuing
+ *    a curve two points cannot describe;
+ * 2. **the swarm.** Every encoder reads the same torrent, so together they
+ *    cannot consume faster than it is delivered. On the field file of
+ *    2026-09-05 a second of film weighs 842 KB and the swarm gave 2119-3347
+ *    KB/s, so the encoders' speeds together may reach 2.5-4x — which is why a
+ *    copy the processor would run at 8x runs at four, and why a third encoder
+ *    makes all three slower rather than adding anything;
+ * 3. **memory for the torrent's pieces.** Encoders placed far apart hold
+ *    windows that do not overlap, so the store must hold their SUM. On the
+ *    addon host the store was already full on the readers of one viewer — "6
+ *    readers want 14 pieces of 14 the store may hold" — so this is the limit
+ *    that binds first there, not the processor.
+ *
+ * Which of them bound the answer is returned beside it, because "why is there
+ * only one encoder" is otherwise a question no log can answer.
+ */
+
+/**
+ * @typedef {object} RunBudget
+ * @property {number} runs - How many encoders may run on this output.
+ * @property {string} because - Which limit decided it.
+ */
+
+/**
+ * @param {object} params
+ * @param {number} params.byProcessor - What the processor allows, from the
+ *   measured speed and the measured penalty for concurrency. At least one.
+ * @param {number} [params.speedX] - The measured speed of one encoder here.
+ * @param {number} [params.refetchSecPerFilmSecond] - Seconds of swarm time per
+ *   second of film: the film's own byte rate over what the swarm delivers. One
+ *   encoder at speed `s` therefore consumes `s * refetch` of the swarm, and
+ *   what they may consume together is all of it. Absent where neither rate has
+ *   been measured, and then the swarm does not bound the answer.
+ * @param {number} [params.storeBytes] - What the piece store may hold.
+ * @param {number} [params.readerWindowBytes] - What one encoder's reader keeps.
+ * @returns {RunBudget}
+ */
+export function affordableRuns({
+  byProcessor,
+  speedX,
+  refetchSecPerFilmSecond,
+  storeBytes,
+  readerWindowBytes
+}) {
+  let runs = Number.isFinite(byProcessor) && byProcessor > 0 ? Math.floor(byProcessor) : 1;
+  let because = "the processor";
+
+  // The swarm. One encoder at speed `s` takes `s * refetch` of what is
+  // delivered, and everything running takes the sum, which cannot pass one.
+  if (
+    Number.isFinite(refetchSecPerFilmSecond) &&
+    refetchSecPerFilmSecond > 0 &&
+    Number.isFinite(speedX) &&
+    speedX > 0
+  ) {
+    const bySwarm = Math.max(1, Math.floor(1 / (speedX * refetchSecPerFilmSecond)));
+    if (bySwarm < runs) {
+      runs = bySwarm;
+      because = "what the swarm delivers";
+    }
+  }
+
+  // Memory: encoders far apart hold windows that do not overlap.
+  if (
+    Number.isFinite(storeBytes) &&
+    storeBytes > 0 &&
+    Number.isFinite(readerWindowBytes) &&
+    readerWindowBytes > 0
+  ) {
+    const byMemory = Math.max(1, Math.floor(storeBytes / readerWindowBytes));
+    if (byMemory < runs) {
+      runs = byMemory;
+      because = "memory for the torrent's pieces";
+    }
+  }
+
+  return { runs: Math.max(1, runs), because };
+}

package/services/encode/run-command.js

@@ -620,6 +620,21 @@ export function buildRunCommand({
       "0.05",
       "-segment_start_number",
       String(safeIndex),
+      // THE ENCODER SAYS WHEN A PIECE IS FINISHED, on a channel of its own.
+      //
+      // Measured on the addon host 2026-09-05: a name appears in this list when
+      // the file is CLOSED, not when it is created — at the third sample
+      // `seg-000.mp4` was on disk and absent from the list, and it appeared at
+      // the fourth, in the same moment `seg-001.mp4` came into being. So a name
+      // here is the writer's own statement that the piece is whole.
+      //
+      // Without it, a finished file is indistinguishable from one still being
+      // written, and the only proof available was the existence of the NEXT
+      // one — which never comes for the last piece of every run.
+      "-segment_list",
+      "pipe:3",
+      "-segment_list_flags",
+      "+live",
       ...explicitTimes,
       segmentFormat.segmentFileNameTemplate()
     );