@torrent-tv/proxy 2.24.1 → 2.25.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.25.1
+
+- **Fix**: Picture and sound are back in step. Two releases in a row moved a segment's stamp toward the playlist — 2.24.1 per session, 2.25.0 by one offset for the whole family — and both desynced playback in the field the same day. The reason is what the first segment of a run is: it is not CUT at all, it begins where ffmpeg's seek landed, and the picture must land on a keyframe while the sound needs none, so after every restart the two runs genuinely begin at different real times and the whole run carries that difference (measured: the sound's #292 began at 1587.892 s and #293 at 1592.692 s, one segment apart, the run shifted 2.5 s from the grid). Labelling each track with its own true time is what keeps them together in real time; a segment is stamped with its own start again, as it was for weeks before 2.24.1. What stays from those releases is the part that was right: one published timeline per family, and a warning when a piece lands further from the playlist than a player will bridge.
+- **Chore**: The run's state now answers the questions its process handle used to be asked. Ten sites that re-derived "is this run alive" from a child-process handle, and every read of "is it suspended", now read the state machine shipped in 2.23.0; the `encoderPaused` field is gone. The two places that ask about a NAMED process — the predecessor a restart is replacing, and a deliberate stop — still ask the OS, which remains the authority on whether a pid exists.
+
+## 2.25.0
+
+- **Fix**: Picture and sound drifted apart after a seek, by exactly the amount the grid had been corrected. 2.24.1 made every segment stamp itself against the playlist its own session published — but each session froze that playlist at its own creation, and a soundtrack or a quality step is created later than the picture it accompanies, so it froze a table that had since been corrected. Two members of one family then stated the same moment differently, and the corrections measured on the field file are 0.6-2.9 s. A family now publishes ONE timeline: a session created inside a family takes its base's published table verbatim and writes its own playlist from it, while the live table goes on being corrected for cutting, which is what keeps a re-encoded step aligned with the copy it joins.
+- **New**: The read window grows into a lead instead of staying a fixed length. Every wait that cost time widens it by a piece; every piece already in hand gives one back, down to the size the caller sized from the file's own byte rate. The ceiling is this reader's share of the store's memory, so widening can never ask for more than the store can hold. Measured 2026-08-17, the swarm delivered 5.1-5.9 MB/s against a film consumed at about 1 MB/s while the reader still blocked 47 times in two minutes — a fivefold surplus that never became distance ahead of the head.
+
 ## 2.24.1
 
 - **Fix**: Seeking could leave a film dead. After a seek the encoder restarts at the segment before the target, and every segment it then produces states its own position, read out of the piece. On a file whose container index is wrong those positions disagree with the playlist the player is holding — measured 2026-08-17, a seek to 1590.4 s produced audio segments #292 and #293 carrying 1587.892 s and 1592.692 s against a playlist saying 1585.376 s and 1590.585 s. A fragment landing further from where the playlist put it than a player will bridge (hls.js bridges `maxBufferHole`, 0.5 s by default) is not recognised as buffered, so the browser asks for it again: those two segments were fetched **1908 times each over ten minutes**, every one served in 4 ms, with the picture frozen and nothing in either log saying why. A segment is now stamped where the playlist the player holds says it begins, whenever the piece's own figure is further away than that; within it the piece's own figure is kept, which is what keeps speech and subtitles together on a file whose index is slightly out. The boundary table goes on being corrected from produced segments — that is what lets a re-encoded step be cut like the copy it joins — but the correction no longer moves segments under a player holding the original playlist: the published table is frozen when the playlist text is written from it. Pinned by `test/published-timeline.test.js` with the field figures.

package/package.json

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

package/services/hls-session-manager.js

@@ -20,7 +20,13 @@ import { logger } from "../utils/logger.js";
 import { readKeyframeIndex } from "./container-index/index.js";
 import { readMachineState, readProcessCpuSeconds, readProxyCpuSeconds, readSystemCpu, shareOfMachine } from "./host-load.js";
 import { speedFromReadings } from "./encoder-readings.js";
-import { ENCODE_RUN_EVENT, ENCODE_RUN_STATE, INITIAL_RUN_STATE, nextState } from "./encode-run-state.js";
+import {
+  ENCODE_RUN_EVENT,
+  ENCODE_RUN_STATE,
+  INITIAL_RUN_STATE,
+  nextState,
+  processCanBeSignalled
+} from "./encode-run-state.js";
 import { ENCODE_EXIT, classifyEncodeExit } from "./encode-exit.js";
 
 /** Own package version, stamped onto session-start log lines. */
@@ -1741,6 +1747,14 @@ export class HlsSessionManager {
           })
         : []);
     const usingKeyframeBoundaries = useKeyframeGrid;
+    // What this session will PUBLISH. A member of a family takes its base's
+    // published table verbatim; a session with no base publishes what it cuts
+    // at. The two differ exactly by the corrections made since the family's
+    // first playlist was written, and that difference is what must never reach
+    // the player as two different timelines.
+    const publishedGrid = Array.isArray(inheritedGrid?.published) && inheritedGrid.published.length > 1
+      ? inheritedGrid.published
+      : (hasDuration ? [...segmentBoundaries] : null);
     const segmentCount = segmentBoundaries.length > 1 ? segmentBoundaries.length - 1 : 0;
 
     // Realtime budget (software encoder): pick the output resolution + libx264
@@ -1809,7 +1823,7 @@ export class HlsSessionManager {
       // `encode-run-state.js`. Written at every event today and read by nothing
       // yet: a refused pair in the log is the model disagreeing with reality,
       // and that disagreement is the measurement this release exists to take.
-      // The fields it will replace — `state`, `progress.state`, `encoderPaused`
+      // The fields it replaces — `state`, `progress.state`
       // and the repeated liveness checks — keep their current writes meanwhile.
       runState: INITIAL_RUN_STATE,
       lastError: "",
@@ -1908,13 +1922,18 @@ export class HlsSessionManager {
       // spliced into the copy (roadmap item 28).
       containerFormat,
       indexCheck: newIndexCheck(),
-      playlistText: hasDuration ? this.#buildVodPlaylist(segmentBoundaries, segmentFormat) : "",
-      // The table AS PUBLISHED, frozen the moment the playlist text is written
-      // from it. `segmentBoundaries` keeps being corrected from produced
-      // segments — that is what makes a re-encoded rung cut like the copy it
-      // joins — but the player's own copy of the timeline never changes, and a
-      // segment must be stamped against the copy the player has.
-      publishedBoundaries: hasDuration ? [...segmentBoundaries] : null,
+      playlistText: hasDuration ? this.#buildVodPlaylist(publishedGrid, segmentFormat) : "",
+      // The table AS PUBLISHED — what every playlist of this family states, and
+      // what every segment of it is stamped against. Inherited whole from the
+      // base when there is one, so a rung or a soundtrack created later
+      // publishes the same timeline as the picture it plays with; only a family
+      // with no base freezes a copy of its own.
+      //
+      // `segmentBoundaries` keeps being corrected from produced segments — that
+      // is what makes a re-encoded rung cut like the copy it joins — and those
+      // corrections deliberately do NOT reach this copy: the player's timeline
+      // was sent once and cannot be revised.
+      publishedBoundaries: publishedGrid,
       // Segment index the current ffmpeg run started producing from.
       encodeStartIndex: 0,
       // Guards against repeatedly restarting to the same seek position.
@@ -1939,7 +1958,6 @@ export class HlsSessionManager {
       // encoder is currently suspended for running too far past it.
       // See #enforceLookAhead.
       lastRequestedSegment: null,
-      encoderPaused: false,
       encoderPauseUnsupported: false,
       seekFirstFarAt: 0,
       // Circuit breaker: consecutive FAST failures (see SEEK_FAST_FAIL_MS) at
@@ -2731,7 +2749,7 @@ export class HlsSessionManager {
     if (aheadSeconds === null) {
       // The segment the viewer needs does not exist. Whatever else is on disk,
       // this encoder has work to do right now.
-      if (session.encoderPaused && this.#resumeEncoder(session, "the viewer needs a segment nobody has made")) {
+      if (session.runState === ENCODE_RUN_STATE.SUSPENDED && this.#resumeEncoder(session, "the viewer needs a segment nobody has made")) {
         this.#transitionRun(session, ENCODE_RUN_EVENT.RESUME_ORDERED);
       }
       return;
@@ -2759,7 +2777,7 @@ export class HlsSessionManager {
       );
     }
 
-    if (!session.encoderPaused && aheadSeconds > LOOKAHEAD_PAUSE_SECONDS) {
+    if (session.runState !== ENCODE_RUN_STATE.SUSPENDED && aheadSeconds > LOOKAHEAD_PAUSE_SECONDS) {
       // The decision names what it was taken on. Suspending the encoder stops
       // the only thing that reads the input, so a wrong reading here stops the
       // download too — measured 2026-08-06: the log said "135s ahead" while
@@ -2773,7 +2791,7 @@ export class HlsSessionManager {
           `(viewer at #${viewerSegment}, unbroken through #${reading.lastCovered}, ` +
           `${reading.total} segment file(s) present)`
       );
-    } else if (session.encoderPaused && aheadSeconds <= LOOKAHEAD_RESUME_SECONDS) {
+    } else if (session.runState === ENCODE_RUN_STATE.SUSPENDED && aheadSeconds <= LOOKAHEAD_RESUME_SECONDS) {
       if (this.#resumeEncoder(session, `${Math.round(aheadSeconds)}s ahead of the viewer`)) {
         this.#transitionRun(session, ENCODE_RUN_EVENT.RESUME_ORDERED);
       }
@@ -2916,7 +2934,7 @@ export class HlsSessionManager {
   #pauseEncoder(session, reason) {
     // Any pair spanning this would count a stopped encoder as slow.
     session.learnSample = null;
-    if (session.encoderPaused || session.encoderPauseUnsupported || !session.ffmpeg?.pid) {
+    if (session.runState === ENCODE_RUN_STATE.SUSPENDED || session.encoderPauseUnsupported || !session.ffmpeg?.pid) {
       return;
     }
     try {
@@ -2929,7 +2947,6 @@ export class HlsSessionManager {
       );
       return;
     }
-    session.encoderPaused = true;
     this.#transitionRun(session, ENCODE_RUN_EVENT.SUSPEND_ORDERED);
     logger.info(
       `transcode ${session.id} encoder suspended — ${reason} ` +
@@ -2952,7 +2969,7 @@ export class HlsSessionManager {
   #resumeEncoder(session, reason) {
     // Any pair spanning this would count a stopped encoder as slow.
     session.learnSample = null;
-    if (!session.encoderPaused || !session.ffmpeg?.pid) {
+    if (session.runState !== ENCODE_RUN_STATE.SUSPENDED || !session.ffmpeg?.pid) {
       return false;
     }
     let continued = true;
@@ -2964,7 +2981,6 @@ export class HlsSessionManager {
       // stops a dead run being reported as producing again.
       continued = false;
     }
-    session.encoderPaused = false;
     // Two records of one moment must not contradict each other: a line saying
     // the encoder resumed, beside a return value saying nothing was resumed, is
     // the sort of pair that costs an hour of reading a field log.
@@ -3067,9 +3083,9 @@ export class HlsSessionManager {
 
   async #reportHostLoad() {
     const encoding = [...this.sessionsById.values()].filter(
-      (session) => session?.ffmpeg != null && !hasChildExited(session.ffmpeg) && session.state !== "disposed"
+      (session) => processCanBeSignalled(session?.runState) && session.state !== "disposed"
     );
-    const runningNow = encoding.filter((session) => session.encoderPaused !== true);
+    const runningNow = encoding.filter((session) => session.runState !== ENCODE_RUN_STATE.SUSPENDED);
     if (runningNow.length === 0) {
       // No encoder is RUNNING. A suspended one costs nothing, and counting it
       // as work meant this was never reached: measured 2026-08-15, four minutes
@@ -3143,7 +3159,7 @@ export class HlsSessionManager {
     // the addon host actually were (2026-08-15: `ffmpeg=0% system=24%`, both
     // encoders suspended, and the speed beside it a stale figure from before
     // they stopped).
-    const suspended = encoding.filter((session) => session.encoderPaused === true).length;
+    const suspended = encoding.filter((session) => session.runState === ENCODE_RUN_STATE.SUSPENDED).length;
     const running = encoding.length - suspended;
     const machine = await readMachineState();
     const asPercent = (value) => (value === null ? "n/a" : `${Math.round(value * 100)}%`);
@@ -3740,7 +3756,6 @@ export class HlsSessionManager {
     // judged finished — see getFileStream.
     session.usesExplicitCuts = Boolean(cutTimes && cutTimes.length > 0);
     session.encodeStartIndex = safeIndex;
-    session.encoderPaused = false;
     session.pendingRestartIndex = -1;
     session.lastRestartAt = Date.now();
     session.state = session.state === "disposed" ? "disposed" : "starting";
@@ -4178,7 +4193,7 @@ export class HlsSessionManager {
     }
     // Nothing is encoding: a rung the viewer has switched away from is left
     // exactly so, and its held requests must not bring its encoder back.
-    if (session.ffmpeg == null || hasChildExited(session.ffmpeg)) {
+    if (!processCanBeSignalled(session.runState)) {
       return;
     }
     // A seek already settling is about to move the encoder to where the VIEWER
@@ -4362,7 +4377,7 @@ export class HlsSessionManager {
     // "already covered", so nothing could ever restart it. Measured 2026-08-04:
     // one ffmpeg failure turned into a session that answered 500 to every
     // segment for as long as the viewer kept trying.
-    const runIsAlive = session.ffmpeg != null && !hasChildExited(session.ffmpeg);
+    const runIsAlive = processCanBeSignalled(session.runState);
     if (runIsAlive && index >= head && index <= currentSeg + MAX_LOOKAHEAD_SEGMENTS) {
       logger.info(
         `transcode ${session.id} seek to ${positionSeconds.toFixed(1)}s (#${index}) ` +
@@ -4416,7 +4431,7 @@ export class HlsSessionManager {
     // ten seconds, each killing a run that was encoding #865. The guard below
     // did not catch it — it only decides whether to let the current run finish,
     // not whether a new run is needed at all.
-    if (target === session.encodeStartIndex && session.ffmpeg != null && !hasChildExited(session.ffmpeg)) {
+    if (target === session.encodeStartIndex && processCanBeSignalled(session.runState)) {
       logger.info(
         `transcode ${session.id} seek #${target} ignored — the current run already starts there`
       );
@@ -4444,7 +4459,7 @@ export class HlsSessionManager {
     // Holding it was also expensive in the other direction: a genuine second
     // seek could be delayed by the whole grace.
     const producedThisRun = this.#producedSecondsThisRun(session);
-    const runIsAlive = session.ffmpeg != null && !hasChildExited(session.ffmpeg);
+    const runIsAlive = processCanBeSignalled(session.runState);
     const allowedBecause = !runIsAlive
       ? "run is dead"
       : `viewer moved; run had produced ${producedThisRun.toFixed(1)}s`;
@@ -5046,7 +5061,7 @@ export class HlsSessionManager {
       .map((member) => this.#observedAudioCost.get(this.#audioCostKey(member))?.version ?? 0)
       .reduce((total, one) => total + one, 0);
     const running = [...this.#familyOf(owner)]
-      .filter((member) => member.ffmpeg != null && !hasChildExited(member.ffmpeg)).length;
+      .filter((member) => processCanBeSignalled(member.runState)).length;
     // What each running encode was last seen doing, which is BOTH an input to
     // the answer twice over — it withdraws a step measured below realtime, and
     // it prices every running picture in the committed total — and a figure
@@ -5204,7 +5219,7 @@ export class HlsSessionManager {
     for (const session of this.sessionsById.values()) {
       if (session?.ffmpeg != null &&
           !hasChildExited(session.ffmpeg) &&
-          session.encoderPaused !== true &&
+          session.runState !== ENCODE_RUN_STATE.SUSPENDED &&
           session.state !== "disposed") {
         running += 1;
       }
@@ -5218,7 +5233,7 @@ export class HlsSessionManager {
       session.state === "disposed" ||
       session.state === "failed" ||
       !session.ffmpeg ||
-      session.encoderPaused === true
+      session.runState === ENCODE_RUN_STATE.SUSPENDED
     ) {
       session.learnSample = null;
       return;
@@ -5323,7 +5338,7 @@ export class HlsSessionManager {
     if (!Number.isFinite(runStartedAt) || Date.now() - runStartedAt < DECODE_LEARNING_SETTLE_MS) {
       return;
     }
-    if (session.encoderPaused === true) {
+    if (session.runState === ENCODE_RUN_STATE.SUSPENDED) {
       return; // a suspended run reports a cumulative figure that is decaying
     }
     // Always asked, not only below realtime. A re-encode near 1x may be the
@@ -5374,7 +5389,7 @@ export class HlsSessionManager {
     if (!Number.isFinite(runStartedAt) || Date.now() - runStartedAt < DECODE_LEARNING_SETTLE_MS) {
       return;
     }
-    if (session.encoderPaused === true) {
+    if (session.runState === ENCODE_RUN_STATE.SUSPENDED) {
       return;
     }
     if (await this.#classifyTranscodeBound(session) === "download") {
@@ -5617,7 +5632,7 @@ export class HlsSessionManager {
   #pricedConcurrentCost(session) {
     let cost = 0;
     for (const member of this.#familyOf(session)) {
-      if (member === session || member.ffmpeg == null || hasChildExited(member.ffmpeg)) {
+      if (member === session || !processCanBeSignalled(member.runState)) {
         continue;
       }
       if (member.audioOnly === true) {
@@ -5646,7 +5661,7 @@ export class HlsSessionManager {
     // price to look up for another film's session — so a reading taken while
     // one is running cannot be attributed either.
     return this.#runningEncoders() > this.#familyOf(session).filter(
-      (member) => member.ffmpeg != null && !hasChildExited(member.ffmpeg)
+      (member) => processCanBeSignalled(member.runState)
     ).length
       ? null
       : cost;
@@ -5670,7 +5685,7 @@ export class HlsSessionManager {
       if (member.audioOnly === true || member.transcodeVideo !== true) {
         continue;
       }
-      if (member.ffmpeg == null || hasChildExited(member.ffmpeg)) {
+      if (!processCanBeSignalled(member.runState)) {
         continue;
       }
       const height = this.variantHeightOf(member);
@@ -5714,7 +5729,7 @@ export class HlsSessionManager {
       // that cost is spread, not a discount on it — and pricing a parked
       // encoder at zero would offer a step on the strength of a pause that ends
       // the moment the viewer catches up.
-      if (member.ffmpeg == null || hasChildExited(member.ffmpeg)) {
+      if (!processCanBeSignalled(member.runState)) {
         continue;
       }
       if (member.audioOnly === true) {
@@ -6134,8 +6149,14 @@ export class HlsSessionManager {
       inheritedGrid: base.cutGrid === "keyframe"
         ? {
             // The table as it stands NOW, corrections included — not the index
-            // it was first built from.
+            // it was first built from. This is what the new session CUTS at.
             boundaries: base.segmentBoundaries,
+            // And this is what it must SAY, which is not the same thing: every
+            // member of a family has to publish one timeline, or two sessions
+            // stamp the same moment differently and the picture and the sound
+            // drift apart by exactly the corrections made between their two
+            // creations (field 2026-08-17, corrections of 0.6-2.9 s).
+            published: base.publishedBoundaries,
             keyframeTimes: base.keyframeTimes,
             containerFormat: base.containerFormat
           }
@@ -6670,6 +6691,7 @@ export class HlsSessionManager {
       inheritedGrid: base.cutGrid === "keyframe"
         ? {
             boundaries: base.segmentBoundaries,
+            published: base.publishedBoundaries,
             keyframeTimes: base.keyframeTimes,
             containerFormat: base.containerFormat
           }
@@ -7059,9 +7081,30 @@ export class HlsSessionManager {
         // is kept, because it is the honest one and it is what keeps speech and
         // subtitles together on a file whose index is slightly out (2026-08-06,
         // 4.17 s of drift on a Matroska index that lied).
-        let stampStart = trueStart ?? publishedStart;
+        // STAMPED WITH ITS OWN TRUE START, always. Two attempts at moving it
+        // toward the playlist both made things worse, and the reason is in what
+        // the first segment of a run is: it is not CUT at all — it begins where
+        // ffmpeg's seek landed. The picture must land on a keyframe; the sound
+        // needs none and starts at the instant asked for. So after every
+        // restart the two runs genuinely begin at different real times, and the
+        // whole run carries that difference (field 2026-08-17: the sound's
+        // #292 began at 1587.892 s and #293 at 1592.692 s — exactly one segment
+        // apart, the whole run shifted 2.5 s from the grid).
+        //
+        // Labelling each track with its own true time is therefore what keeps
+        // picture and sound together in real time. Moving them onto the
+        // published grid — separately (2.24.1) or by one family offset (2.25.0)
+        // — closes a gap that is real and opens one that is not: it desynced
+        // playback in the field within the hour, twice.
+        //
+        // What that leaves unsolved is the reason those attempts were made: a
+        // playlist that disagrees with the media by more than a player bridges
+        // makes hls.js refetch the same fragment for ever (1908 times each for
+        // two segments, measured). The answer to THAT is to make the published
+        // grid agree with where the runs really begin — not to relabel the
+        // media. Recorded as its own roadmap item rather than guessed at here.
+        const stampStart = trueStart ?? publishedStart;
         if (trueStart !== null && Math.abs(trueStart - publishedStart) > PLAYER_BUFFER_HOLE_SEC) {
-          stampStart = publishedStart;
           this.#notePlaylistDisagreement(session, index, trueStart, publishedStart);
         }
         const prepared = session.segmentFormat.prepareSegmentBytes(bytes, {

package/services/torrent-worker/piece-reader.js

@@ -60,6 +60,37 @@ export function readWindowFor({ pieceIndex, lastPiece, windowPieces }) {
   return { from: pieceIndex, to: Math.min(lastPiece, pieceIndex + span - 1) };
 }
 
+/**
+ * How wide the window should be after a piece that made the reader wait — or
+ * did not.
+ *
+ * The swarm's surplus is what pays for this. Measured 2026-08-17 on the field
+ * torrent: 5.1-5.9 MB/s delivered against a film consumed at about 1 MB/s, and
+ * the reader still blocked 47 times in two minutes, median 1.5 s, worst 4.5 s.
+ * A fivefold surplus never became distance ahead of the head, because the
+ * window is a fixed number of seconds of playback and everything past it is
+ * ordinary background fill at no priority.
+ *
+ * So the window follows the evidence: every wait that mattered widens it by a
+ * piece, every piece that was already there narrows it back toward the size the
+ * caller asked for. Nothing here is chosen — the wait is measured, the
+ * threshold is the one that already defines "a wait worth recording", and the
+ * ceiling is this reader's share of the store's memory, so widening can never
+ * cost more than the store can hold.
+ *
+ * @param {{ current: number, base: number, ceiling: number, waitedMs: number, waitThresholdMs: number }} params
+ * @returns {number}
+ */
+export function nextWindowPieces({ current, base, ceiling, waitedMs, waitThresholdMs }) {
+  const floor = Math.max(1, Math.floor(base));
+  const top = Math.max(floor, Math.floor(ceiling));
+  const now = Math.min(top, Math.max(floor, Math.floor(current)));
+  if (waitedMs >= waitThresholdMs) {
+    return Math.min(top, now + 1);
+  }
+  return Math.max(floor, now - 1);
+}
+
 /**
  * Add this reader's window to the download set as a stream selection.
  *
@@ -310,7 +341,26 @@ export async function* readFragments({
   // critical, and never deselected anything — so ffmpeg's opening
   // `bytes 0-<EOF>` left a permanent selection over the entire file, and no
   // later prioritisation could outrank it.
-  const windowPieces = Math.max(1, Math.ceil(Math.max(1, windowBytes) / pieceLength));
+  const basePieces = Math.max(1, Math.ceil(Math.max(1, windowBytes) / pieceLength));
+  // What the window is RIGHT NOW. It starts at what the caller sized in seconds
+  // of playback and grows while the reader keeps being made to wait — see
+  // `nextWindowPieces`.
+  let windowPieces = basePieces;
+  /**
+   * The widest this reader may go: its share of what the store can hold in
+   * memory. Measured rather than chosen — the capacity is the store's own, and
+   * the number of readers is how many windows are declared on it right now.
+   *
+   * @returns {number}
+   */
+  const ceilingPieces = () => {
+    const capacity = Number(store?.capacity);
+    if (!Number.isFinite(capacity) || capacity <= 0) {
+      return basePieces;
+    }
+    const readers = Math.max(1, store.protectedRanges?.().length ?? 1);
+    return Math.max(basePieces, Math.floor(capacity / readers));
+  };
   /** @type {{ from: number, to: number } | null} */
   let window = null;
   /** @type {{ from: number, to: number } | null} */
@@ -408,6 +458,20 @@ export async function* readFragments({
       // whether that is the swarm, the picker, or ffmpeg. Logged only when the
       // wait is long enough to matter, so ordinary sequential reading is silent.
       const waitedMs = Date.now() - waitStartedAt;
+      // The window answers to what just happened: a wait means the lead was too
+      // short, an immediate hit means it is longer than it needs to be. Applied
+      // before the logging below so the line reports the window the next piece
+      // will actually use.
+      const widened = nextWindowPieces({
+        current: windowPieces,
+        base: basePieces,
+        ceiling: ceilingPieces(),
+        waitedMs,
+        waitThresholdMs: PIECE_WAIT_LOG_MS
+      });
+      if (widened !== windowPieces) {
+        windowPieces = widened;
+      }
       if (waitedMs >= PIECE_WAIT_LOG_MS) {
         const rateKbps = Math.round(pieceLength / 1024 / (waitedMs / 1000));
         logger.info(

package/test/behind-head-repair.test.js

@@ -63,6 +63,7 @@ async function managerWithRunAhead() {
     seekTarget: null,
     waitEpoch: 0,
     firstWantedAt: new Map(),
+    runState: "PRODUCING",
     ffmpeg: { pid: 4321, exitCode: null, signalCode: null, kill() {}, once(event, handler) { if (event === "exit") handler(); } },
     progress: { state: "running", processedSeconds: RUN_STARTS_AT * SEGMENT_SECONDS + 400, startPositionSeconds: RUN_STARTS_AT * SEGMENT_SECONDS }
   };

package/test/quality-variants.test.js

@@ -286,6 +286,7 @@ test("a segment request hands the encoder to the variant the viewer moved to", a
   base.lastRequestedSegment = 25;
   const encoder = fakeEncoder();
   base.ffmpeg = encoder;
+  base.runState = "PRODUCING";
 
   const served = await manager.resolveVariantFile(BASE_ID, 540, "segment-00025.mp4");
 
@@ -317,6 +318,7 @@ test("a rung is placed where the player asked it for, not where the other rung h
   manager.sessionsById.set(VARIANT_ID, variant);
   base.variants = new Map([[540, VARIANT_ID]]);
   base.ffmpeg = fakeEncoder();
+  base.runState = "PRODUCING";
   // The rung being left had read fourteen segments further than the picture had
   // played — an encoder running at several times realtime fills the buffer far
   // ahead. Measured 2026-08-11: 56 s of gap, and using the read head placed the
@@ -347,6 +349,7 @@ test("warming a rung prepares it without taking the encoder from the one on scre
   base.variants = new Map([[540, VARIANT_ID]]);
   const encoder = fakeEncoder();
   base.ffmpeg = encoder;
+  base.runState = "PRODUCING";
 
   const prepared = await manager.prepareVariant(BASE_ID, 540, 240);
 
@@ -373,6 +376,7 @@ test("a rung warmed at the playhead survives the switch that lands just ahead of
   manager.sessionsById.set(VARIANT_ID, variant);
   base.variants = new Map([[540, VARIANT_ID]]);
   base.ffmpeg = fakeEncoder();
+  base.runState = "PRODUCING";
 
   // Warmed AT THE PLAYHEAD (240 s = segment #60), which is what the browser
   // sends from server 0.10.0 onwards, and the run is alive and has produced a
@@ -380,6 +384,7 @@ test("a rung warmed at the playhead survives the switch that lands just ahead of
   await manager.prepareVariant(BASE_ID, 540, 240);
   variant.encodeStartIndex = 59;
   variant.ffmpeg = fakeEncoder();
+  variant.runState = "PRODUCING";
   variant.progress = { ...variant.progress, processedSeconds: 268 };
   variant.seekTarget = null;
   variant.seekSettleTimer = null;
@@ -413,6 +418,7 @@ test("a rung warmed PAST the switch is repositioned, which is what warming late
   manager.sessionsById.set(VARIANT_ID, variant);
   base.variants = new Map([[540, VARIANT_ID]]);
   base.ffmpeg = fakeEncoder();
+  base.runState = "PRODUCING";
 
   // The same session, warmed where the BUFFER ended rather than where the
   // picture was — 60 s further on, which is an ordinary cushion. This is what
@@ -420,6 +426,7 @@ test("a rung warmed PAST the switch is repositioned, which is what warming late
   await manager.prepareVariant(BASE_ID, 540, 300);
   variant.encodeStartIndex = 74;
   variant.ffmpeg = fakeEncoder();
+  variant.runState = "PRODUCING";
   variant.progress = { ...variant.progress, processedSeconds: 310 };
   variant.seekTarget = null;
   variant.seekSettleTimer = null;
@@ -447,6 +454,7 @@ test("the rung on screen fetching its own segments does not cancel a warm-up", a
   const warmedEncoder = fakeEncoder();
   variant.ffmpeg = warmedEncoder;
   base.ffmpeg = fakeEncoder();
+  base.runState = "PRODUCING";
   await manager.prepareVariant(BASE_ID, 540, 100);
 
   // The viewer has not moved: the rung they are watching goes on asking for its
@@ -521,6 +529,7 @@ test("a playlist or an init segment does not move the encoder", async (t) => {
   manager.sessionsById.set(VARIANT_ID, variant);
   base.variants = new Map([[540, VARIANT_ID]]);
   base.ffmpeg = fakeEncoder();
+  base.runState = "PRODUCING";
 
   base.variants = new Map([[540, VARIANT_ID]]);
   await manager.resolveVariantFile(BASE_ID, 540, "index.m3u8");
@@ -719,6 +728,7 @@ test("an audio track is prepared at the position the switch will land on", async
   rendition.audioOnly = true;
   rendition.audioTrackIndex = 1;
   rendition.ffmpeg = fakeEncoder();
+  rendition.runState = "PRODUCING";
   rendition.encodeStartIndex = 0;
   manager.sessionsById.set(VARIANT_ID, rendition);
   base.audioRenditionSessions = new Map([[1, VARIANT_ID]]);
@@ -790,6 +800,7 @@ test("a quality step being warmed is not refused by its own cost", async (t) =>
   // Running, and running well: it says of itself that it holds twice realtime,
   // i.e. half a second of work per second of video.
   warming.ffmpeg = fakeEncoder();
+  warming.runState = "PRODUCING";
   warming.lastAloneSpeed = 2;
   manager.sessionsById.set(BASE_ID, base);
   manager.sessionsById.set(VARIANT_ID, warming);

package/test/read-window.test.js

@@ -19,7 +19,11 @@ import { EventEmitter } from "node:events";
 import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
-import { readFragments, readWindowFor } from "../services/torrent-worker/piece-reader.js";
+import {
+  nextWindowPieces,
+  readFragments,
+  readWindowFor
+} from "../services/torrent-worker/piece-reader.js";
 import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
 
 const PIECE = 1024;
@@ -276,3 +280,50 @@ test("a reader that is abandoned mid-fragment does not keep the piece pinned", a
     await fs.rm(directory, { recursive: true, force: true });
   }
 });
+
+// ------------------------------------------ the window that grows into a lead
+
+test("a wait that mattered widens the window by a piece", () => {
+  // Field 2026-08-17: 5.1-5.9 MB/s delivered against ~1 MB/s consumed, and the
+  // reader still blocked 47 times in two minutes. The surplus never became
+  // distance ahead of the head.
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 12, waitedMs: 1457, waitThresholdMs: 1000 }),
+    5
+  );
+});
+
+test("a piece that was already there gives a piece back", () => {
+  assert.equal(
+    nextWindowPieces({ current: 7, base: 4, ceiling: 12, waitedMs: 0, waitThresholdMs: 1000 }),
+    6
+  );
+});
+
+test("it never shrinks below what the caller asked for", () => {
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 12, waitedMs: 0, waitThresholdMs: 1000 }),
+    4
+  );
+});
+
+test("it never grows past this reader's share of the store", () => {
+  assert.equal(
+    nextWindowPieces({ current: 12, base: 4, ceiling: 12, waitedMs: 4453, waitThresholdMs: 1000 }),
+    12
+  );
+  // A ceiling below the base cannot pull the window under it: the caller sized
+  // the base from the file's own byte rate, and a store too small to hold it is
+  // an argument about memory, not about what the reader needs next.
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 1, waitedMs: 2000, waitThresholdMs: 1000 }),
+    4
+  );
+});
+
+test("a wait exactly at the threshold counts as a wait", () => {
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 9, waitedMs: 1000, waitThresholdMs: 1000 }),
+    5
+  );
+});

package/test/segment-serve-wiring.test.js

@@ -1,338 +1,334 @@
-/**
- * @file A finished segment on disk must reach the viewer as bytes.
- *
- * The module tests cover each piece of the fMP4 path on its own, and every one
- * of them passed while playback was dead: 2.9.124 called
- * `readSelfContainedStartSeconds` from `fmp4.js` without importing it, and the
- * unit test imports that function straight from `mp4-boxes.js`, so the gap
- * between a module and its CALLER was invisible. This test asks the session
- * manager for a segment that exists and insists on getting it.
- *
- * The second half pins the reason a one-word slip cost a whole release: the
- * failure was reported as "still being produced". Measured 2026-08-08 — segment
- * #0 was held for 45 281 ms with twelve finished segments in the directory, and
- * the log said nothing at all. Anything that goes wrong while preparing a file
- * that EXISTS must be named and answered, never turned into an endless wait.
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { HlsSessionManager } from "../services/hls-session-manager.js";
-import { ENCODE_RUN_STATE } from "../services/encode-run-state.js";
-import { fmp4Format } from "../services/segment-formats/fmp4.js";
-
-const MOVIE_TIMESCALE = 1000;
-const VIDEO_TIMESCALE = 90_000;
-const AUDIO_TIMESCALE = 48_000;
-const SEGMENT_START_SECONDS = 12.5;
-const SESSION_ID = "11111111-2222-3333-4444-555555555555";
-
-/**
- * @param {string} type
- * @param {Buffer} body
- * @returns {Buffer}
- */
-function box(type, body) {
-  const head = Buffer.alloc(8);
-  head.writeUInt32BE(8 + body.length, 0);
-  head.write(type, 4, "latin1");
-  return Buffer.concat([head, body]);
-}
-
-/**
- * `elst` holding one empty edit — how the `segment` muxer records where the
- * piece sits on the source timeline.
- *
- * @param {number} offsetSeconds
- * @returns {Buffer}
- */
-function emptyEdit(offsetSeconds) {
-  const body = Buffer.alloc(16);
-  body.writeUInt32BE(1, 4);                                        // entry count
-  body.writeUInt32BE(Math.round(offsetSeconds * MOVIE_TIMESCALE), 8); // duration
-  body.writeInt32BE(-1, 12);                                       // media_time
-  return box("elst", body);
-}
-
-/**
- * @param {number} trackId
- * @param {number} timescale
- * @param {number} offsetSeconds
- * @returns {Buffer}
- */
-function trak(trackId, timescale, offsetSeconds) {
-  const tkhdBody = Buffer.alloc(84);
-  tkhdBody.writeUInt32BE(trackId, 12);
-  const mdhdBody = Buffer.alloc(20);
-  mdhdBody.writeUInt32BE(timescale, 12);
-  return box("trak", Buffer.concat([
-    box("tkhd", tkhdBody),
-    box("edts", emptyEdit(offsetSeconds)),
-    box("mdia", box("mdhd", mdhdBody))
-  ]));
-}
-
-/**
- * @param {number} trackId
- * @returns {Buffer}
- */
-function traf(trackId) {
-  const tfhdBody = Buffer.alloc(8);
-  tfhdBody.writeUInt32BE(trackId, 4);
-  const tfdtBody = Buffer.alloc(12);
-  tfdtBody.writeUInt8(1, 0);                       // version 1 — 64-bit
-  tfdtBody.writeBigUInt64BE(0n, 4);                // what ffmpeg writes: zero
-  return box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
-}
-
-/**
- * A piece shaped like the `segment` muxer's output: header, two fragments and a
- * trailing random-access index, all in one file.
- *
- * @param {number} offsetSeconds
- * @returns {Buffer}
- */
-function selfContainedPiece(offsetSeconds) {
-  const mvhdBody = Buffer.alloc(100);
-  mvhdBody.writeUInt32BE(MOVIE_TIMESCALE, 12);
-  const moov = box("moov", Buffer.concat([
-    box("mvhd", mvhdBody),
-    trak(1, VIDEO_TIMESCALE, offsetSeconds),
-    trak(2, AUDIO_TIMESCALE, offsetSeconds)
-  ]));
-  const moof = box("moof", Buffer.concat([traf(1), traf(2)]));
-  const mdat = box("mdat", Buffer.alloc(64, 0x5a));
-  const mfra = box("mfra", Buffer.alloc(24, 0));
-  return Buffer.concat([box("ftyp", Buffer.alloc(16, 0)), moov, moof, mdat, mfra]);
-}
-
-/**
- * A manager holding one session whose segments are already on disk, cut at
- * explicit times — the ordinary keyframe-cut path.
- *
- * @param {{ segmentFormat?: object }} [overrides]
- * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string }>}
- */
-async function managerWithReadySegment(overrides = {}) {
-  const dirPath = await mkdtemp(path.join(os.tmpdir(), "segment-serve-"));
-  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
-  // Two segments, because a piece is only finished once the next one exists.
-  await writeFile(path.join(dirPath, "segment-00000.mp4"), piece);
-  await writeFile(path.join(dirPath, "segment-00001.mp4"), piece);
-
-  const manager = new HlsSessionManager({
-    enabled: true,
-    ffmpegBin: "ffmpeg",
-    localBindHost: "127.0.0.1",
-    localPort: 9090
-  });
-  const session = {
-    id: SESSION_ID,
-    dirPath,
-    state: "ready",
-    fileName: "video.mkv",
-    startedAt: Date.now(),
-    createEntryMs: Date.now(),
-    lastAccessedAt: Date.now(),
-    ffmpeg: null,
-    lastError: "",
-    consumers: new Set(),
-    segmentFormat: overrides.segmentFormat ?? fmp4Format,
-    usesExplicitCuts: true,
-    useSyntheticPlaylist: true,
-    playlistText: "#EXTM3U\n",
-    segmentBoundaries: [0, SEGMENT_START_SECONDS, 25],
-    initBytes: fmp4Format.extractInit(piece),
-    encodeStartIndex: 0,
-    firstSegmentLogged: false,
-    waitEpoch: 0
-  };
-  manager.sessionsById.set(SESSION_ID, session);
-  return { manager, session, dirPath };
-}
-
-test("serving a segment records what its real start says about the container's index", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // The tally is counted in the module tests; what this pins is that serving a
-  // segment reaches it at all. A counter nothing increments reports a clean
-  // index for every file forever, which is worse than no measurement.
-  session.indexCheck = { checked: 0, disagreed: 0, maxDeviationSec: 0, firstDisagreementIndex: -1, seen: new Set() };
-
-  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(session.indexCheck.checked, 1, "the boundary that was just produced must have been examined");
-});
-
-test("a segment that exists is served, not reported as still being produced", async (t) => {
-  const { manager, dirPath, session } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-
-  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(result.kind, "file", "a finished segment on disk must come back as bytes");
-  assert.equal(result.contentType, fmp4Format.segmentContentType);
-
-  const chunks = [];
-  for await (const chunk of result.stream) {
-    chunks.push(chunk);
-  }
-  const served = Buffer.concat(chunks);
-  assert.equal(served.toString("latin1", 4, 8), "moof", "the init header must be stripped off a media segment");
-
-  // Where the PLAYLIST the player holds puts this segment — which is what the
-  // fragment must be stamped with whenever the piece's own position is further
-  // away than a player will bridge. This fixture's piece says 12.5 s while the
-  // playlist says 0, and stamping the piece's figure is what killed a film on
-  // 2026-08-17: the browser asked for two segments 1908 times each over ten
-  // minutes, each served in 4 ms, because a fragment landing 2.5 s from where
-  // it was expected is not recognised as buffered. Reading the piece's own
-  // position still happens — it is the step that threw in 2.9.124, it feeds the
-  // index tally and it corrects the grid for rungs made later — it just no
-  // longer contradicts the timeline the player was sent. See
-  // test/published-timeline.test.js for the rule itself.
-  assert.equal(
-    Number(served.readBigUInt64BE(served.indexOf("tfdt") + 8)),
-    0,
-    "the segment must be stamped where the playlist the player holds says it begins"
-  );
-  assert.equal(
-    session.indexCheck.checked,
-    1,
-    "and the piece's own position must still have been read, or nothing measures the index"
-  );
-});
-
-test("a fault while preparing an existing segment is named, not turned into a wait", async (t) => {
-  const broken = {
-    ...fmp4Format,
-    readSegmentStartSeconds() {
-      throw new ReferenceError("readSelfContainedStartSeconds is not defined");
-    }
-  };
-  const { manager, dirPath } = await managerWithReadySegment({ segmentFormat: broken });
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-
-  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(
-    result.kind,
-    "failed",
-    "answering 'warming-up' hides the fault and holds every request until the viewer gives up"
-  );
-  assert.match(result.message, /readSelfContainedStartSeconds is not defined/);
-});
-
-test("a run's FIRST segment is served once the encoder has passed it, without waiting for a next one", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // The shape a resume takes: a run begun mid-file, so its first segment has no
-  // successor and nothing is producing one. Waiting for that successor is what
-  // held #317 for 46 s and then answered 404 to a browser that had given up.
-  await rm(path.join(dirPath, "segment-00001.mp4"));
-  session.encodeStartIndex = 0;
-  session.ffmpeg = { killed: true, kill() {} };
-  session.progress = { processedSeconds: SEGMENT_START_SECONDS + 10 };
-
-  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(
-    result.kind,
-    "file",
-    "the encoder is past this segment's end, so it is finished — the absence of a next one says nothing"
-  );
-});
-
-test("a segment is found in the run directory that produced it, newest run first", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // Runs write into a directory each — that is what lets a restart begin
-  // without waiting for its predecessor to die, which measured 0.7-1.3 s of
-  // every seek. A later run's answer supersedes an earlier one's, because the
-  // older file may be the truncated output of a run that was killed mid-write.
-  const { mkdir } = await import("node:fs/promises");
-  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
-  await mkdir(path.join(dirPath, "run-1"), { recursive: true });
-  await mkdir(path.join(dirPath, "run-2"), { recursive: true });
-  await writeFile(path.join(dirPath, "run-1", "segment-00000.mp4"), Buffer.alloc(8));
-  await writeFile(path.join(dirPath, "run-2", "segment-00000.mp4"), piece);
-  await writeFile(path.join(dirPath, "run-2", "segment-00001.mp4"), piece);
-  await rm(path.join(dirPath, "segment-00000.mp4"));
-  await rm(path.join(dirPath, "segment-00001.mp4"));
-  session.encodeStartIndex = 0;
-
-  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(result.kind, "file", "a segment produced by a run must be found in that run's directory");
-  const chunks = [];
-  for await (const chunk of result.stream) {
-    chunks.push(chunk);
-  }
-  assert.ok(
-    Buffer.concat(chunks).length > 8,
-    "the newest run's output must win — the older file here is the 8-byte stub a killed run leaves"
-  );
-});
-
-test("serving a run's own segment moves the run out of STARTING", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // The table lives in `encode-run-state.js` and is tested there as a graph.
-  // What this pins is that a real serve REACHES it: a state nothing writes
-  // describes every run as still starting, for ever, and the log built on it
-  // would say so too.
-  session.runState = ENCODE_RUN_STATE.STARTING;
-  // Where the run in force is writing. The fixture's segments live directly in
-  // the session directory, which is exactly what a single run's directory is
-  // here.
-  session.runDirPath = dirPath;
-
-  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(session.runState, ENCODE_RUN_STATE.PRODUCING);
-});
-
-test("a segment left by an earlier run does not claim the new run has produced", async (t) => {
-  const { manager, session, dirPath } = await managerWithReadySegment();
-  t.after(async () => {
-    await manager.disposeAll();
-    await rm(dirPath, { recursive: true, force: true });
-  });
-  // A seek places the new run in a directory of its own; the previous run's
-  // segments stay servable and are served from theirs. They say nothing about
-  // what the run now starting has done — and a run believed to be producing is
-  // one the look-ahead may suspend and the seek path may wave through as
-  // "already covered by the running encode".
-  //
-  // Deliberately a segment ABOVE the new run's start index, because that is the
-  // case an index comparison gets wrong: after a backward seek the old run's
-  // output sits ahead of the new run's beginning.
-  session.runState = ENCODE_RUN_STATE.STARTING;
-  session.encodeStartIndex = 0;
-  session.runDirPath = path.join(dirPath, "run-7");
-
-  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
-
-  assert.equal(session.runState, ENCODE_RUN_STATE.STARTING);
-});
+/**
+ * @file A finished segment on disk must reach the viewer as bytes.
+ *
+ * The module tests cover each piece of the fMP4 path on its own, and every one
+ * of them passed while playback was dead: 2.9.124 called
+ * `readSelfContainedStartSeconds` from `fmp4.js` without importing it, and the
+ * unit test imports that function straight from `mp4-boxes.js`, so the gap
+ * between a module and its CALLER was invisible. This test asks the session
+ * manager for a segment that exists and insists on getting it.
+ *
+ * The second half pins the reason a one-word slip cost a whole release: the
+ * failure was reported as "still being produced". Measured 2026-08-08 — segment
+ * #0 was held for 45 281 ms with twelve finished segments in the directory, and
+ * the log said nothing at all. Anything that goes wrong while preparing a file
+ * that EXISTS must be named and answered, never turned into an endless wait.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { ENCODE_RUN_STATE } from "../services/encode-run-state.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const MOVIE_TIMESCALE = 1000;
+const VIDEO_TIMESCALE = 90_000;
+const AUDIO_TIMESCALE = 48_000;
+const SEGMENT_START_SECONDS = 12.5;
+const SESSION_ID = "11111111-2222-3333-4444-555555555555";
+
+/**
+ * @param {string} type
+ * @param {Buffer} body
+ * @returns {Buffer}
+ */
+function box(type, body) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(8 + body.length, 0);
+  head.write(type, 4, "latin1");
+  return Buffer.concat([head, body]);
+}
+
+/**
+ * `elst` holding one empty edit — how the `segment` muxer records where the
+ * piece sits on the source timeline.
+ *
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function emptyEdit(offsetSeconds) {
+  const body = Buffer.alloc(16);
+  body.writeUInt32BE(1, 4);                                        // entry count
+  body.writeUInt32BE(Math.round(offsetSeconds * MOVIE_TIMESCALE), 8); // duration
+  body.writeInt32BE(-1, 12);                                       // media_time
+  return box("elst", body);
+}
+
+/**
+ * @param {number} trackId
+ * @param {number} timescale
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function trak(trackId, timescale, offsetSeconds) {
+  const tkhdBody = Buffer.alloc(84);
+  tkhdBody.writeUInt32BE(trackId, 12);
+  const mdhdBody = Buffer.alloc(20);
+  mdhdBody.writeUInt32BE(timescale, 12);
+  return box("trak", Buffer.concat([
+    box("tkhd", tkhdBody),
+    box("edts", emptyEdit(offsetSeconds)),
+    box("mdia", box("mdhd", mdhdBody))
+  ]));
+}
+
+/**
+ * @param {number} trackId
+ * @returns {Buffer}
+ */
+function traf(trackId) {
+  const tfhdBody = Buffer.alloc(8);
+  tfhdBody.writeUInt32BE(trackId, 4);
+  const tfdtBody = Buffer.alloc(12);
+  tfdtBody.writeUInt8(1, 0);                       // version 1 — 64-bit
+  tfdtBody.writeBigUInt64BE(0n, 4);                // what ffmpeg writes: zero
+  return box("traf", Buffer.concat([box("tfhd", tfhdBody), box("tfdt", tfdtBody)]));
+}
+
+/**
+ * A piece shaped like the `segment` muxer's output: header, two fragments and a
+ * trailing random-access index, all in one file.
+ *
+ * @param {number} offsetSeconds
+ * @returns {Buffer}
+ */
+function selfContainedPiece(offsetSeconds) {
+  const mvhdBody = Buffer.alloc(100);
+  mvhdBody.writeUInt32BE(MOVIE_TIMESCALE, 12);
+  const moov = box("moov", Buffer.concat([
+    box("mvhd", mvhdBody),
+    trak(1, VIDEO_TIMESCALE, offsetSeconds),
+    trak(2, AUDIO_TIMESCALE, offsetSeconds)
+  ]));
+  const moof = box("moof", Buffer.concat([traf(1), traf(2)]));
+  const mdat = box("mdat", Buffer.alloc(64, 0x5a));
+  const mfra = box("mfra", Buffer.alloc(24, 0));
+  return Buffer.concat([box("ftyp", Buffer.alloc(16, 0)), moov, moof, mdat, mfra]);
+}
+
+/**
+ * A manager holding one session whose segments are already on disk, cut at
+ * explicit times — the ordinary keyframe-cut path.
+ *
+ * @param {{ segmentFormat?: object }} [overrides]
+ * @returns {Promise<{ manager: HlsSessionManager, session: object, dirPath: string }>}
+ */
+async function managerWithReadySegment(overrides = {}) {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "segment-serve-"));
+  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
+  // Two segments, because a piece is only finished once the next one exists.
+  await writeFile(path.join(dirPath, "segment-00000.mp4"), piece);
+  await writeFile(path.join(dirPath, "segment-00001.mp4"), piece);
+
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    fileName: "video.mkv",
+    startedAt: Date.now(),
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    ffmpeg: null,
+    lastError: "",
+    consumers: new Set(),
+    segmentFormat: overrides.segmentFormat ?? fmp4Format,
+    usesExplicitCuts: true,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentBoundaries: [0, SEGMENT_START_SECONDS, 25],
+    initBytes: fmp4Format.extractInit(piece),
+    encodeStartIndex: 0,
+    firstSegmentLogged: false,
+    waitEpoch: 0
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+  return { manager, session, dirPath };
+}
+
+test("serving a segment records what its real start says about the container's index", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The tally is counted in the module tests; what this pins is that serving a
+  // segment reaches it at all. A counter nothing increments reports a clean
+  // index for every file forever, which is worse than no measurement.
+  session.indexCheck = { checked: 0, disagreed: 0, maxDeviationSec: 0, firstDisagreementIndex: -1, seen: new Set() };
+
+  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(session.indexCheck.checked, 1, "the boundary that was just produced must have been examined");
+});
+
+test("a segment that exists is served, not reported as still being produced", async (t) => {
+  const { manager, dirPath, session } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(result.kind, "file", "a finished segment on disk must come back as bytes");
+  assert.equal(result.contentType, fmp4Format.segmentContentType);
+
+  const chunks = [];
+  for await (const chunk of result.stream) {
+    chunks.push(chunk);
+  }
+  const served = Buffer.concat(chunks);
+  assert.equal(served.toString("latin1", 4, 8), "moof", "the init header must be stripped off a media segment");
+
+  // The piece's OWN start, carried into the fragment it belongs to. Two
+  // releases tried moving it toward the playlist instead (2.24.1 per session,
+  // 2.25.0 by one family offset) and both desynced picture from sound in the
+  // field the same day: the first segment of a run is not cut, it begins where
+  // the seek landed, and the picture must land on a keyframe while the sound
+  // need not. Reading the piece's position is also the step that threw in
+  // 2.9.124, and it still feeds the index tally and the grid correction.
+  assert.equal(
+    Number(served.readBigUInt64BE(served.indexOf("tfdt") + 8)),
+    Math.round(SEGMENT_START_SECONDS * VIDEO_TIMESCALE),
+    "the segment must be stamped with where it really begins"
+  );
+  assert.equal(
+    session.indexCheck.checked,
+    1,
+    "and the piece's own position must still have been read, or nothing measures the index"
+  );
+});
+
+test("a fault while preparing an existing segment is named, not turned into a wait", async (t) => {
+  const broken = {
+    ...fmp4Format,
+    readSegmentStartSeconds() {
+      throw new ReferenceError("readSelfContainedStartSeconds is not defined");
+    }
+  };
+  const { manager, dirPath } = await managerWithReadySegment({ segmentFormat: broken });
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(
+    result.kind,
+    "failed",
+    "answering 'warming-up' hides the fault and holds every request until the viewer gives up"
+  );
+  assert.match(result.message, /readSelfContainedStartSeconds is not defined/);
+});
+
+test("a run's FIRST segment is served once the encoder has passed it, without waiting for a next one", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The shape a resume takes: a run begun mid-file, so its first segment has no
+  // successor and nothing is producing one. Waiting for that successor is what
+  // held #317 for 46 s and then answered 404 to a browser that had given up.
+  await rm(path.join(dirPath, "segment-00001.mp4"));
+  session.encodeStartIndex = 0;
+  session.ffmpeg = { killed: true, kill() {} };
+  session.progress = { processedSeconds: SEGMENT_START_SECONDS + 10 };
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(
+    result.kind,
+    "file",
+    "the encoder is past this segment's end, so it is finished — the absence of a next one says nothing"
+  );
+});
+
+test("a segment is found in the run directory that produced it, newest run first", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // Runs write into a directory each — that is what lets a restart begin
+  // without waiting for its predecessor to die, which measured 0.7-1.3 s of
+  // every seek. A later run's answer supersedes an earlier one's, because the
+  // older file may be the truncated output of a run that was killed mid-write.
+  const { mkdir } = await import("node:fs/promises");
+  const piece = selfContainedPiece(SEGMENT_START_SECONDS);
+  await mkdir(path.join(dirPath, "run-1"), { recursive: true });
+  await mkdir(path.join(dirPath, "run-2"), { recursive: true });
+  await writeFile(path.join(dirPath, "run-1", "segment-00000.mp4"), Buffer.alloc(8));
+  await writeFile(path.join(dirPath, "run-2", "segment-00000.mp4"), piece);
+  await writeFile(path.join(dirPath, "run-2", "segment-00001.mp4"), piece);
+  await rm(path.join(dirPath, "segment-00000.mp4"));
+  await rm(path.join(dirPath, "segment-00001.mp4"));
+  session.encodeStartIndex = 0;
+
+  const result = await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(result.kind, "file", "a segment produced by a run must be found in that run's directory");
+  const chunks = [];
+  for await (const chunk of result.stream) {
+    chunks.push(chunk);
+  }
+  assert.ok(
+    Buffer.concat(chunks).length > 8,
+    "the newest run's output must win — the older file here is the 8-byte stub a killed run leaves"
+  );
+});
+
+test("serving a run's own segment moves the run out of STARTING", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The table lives in `encode-run-state.js` and is tested there as a graph.
+  // What this pins is that a real serve REACHES it: a state nothing writes
+  // describes every run as still starting, for ever, and the log built on it
+  // would say so too.
+  session.runState = ENCODE_RUN_STATE.STARTING;
+  // Where the run in force is writing. The fixture's segments live directly in
+  // the session directory, which is exactly what a single run's directory is
+  // here.
+  session.runDirPath = dirPath;
+
+  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(session.runState, ENCODE_RUN_STATE.PRODUCING);
+});
+
+test("a segment left by an earlier run does not claim the new run has produced", async (t) => {
+  const { manager, session, dirPath } = await managerWithReadySegment();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // A seek places the new run in a directory of its own; the previous run's
+  // segments stay servable and are served from theirs. They say nothing about
+  // what the run now starting has done — and a run believed to be producing is
+  // one the look-ahead may suspend and the seek path may wave through as
+  // "already covered by the running encode".
+  //
+  // Deliberately a segment ABOVE the new run's start index, because that is the
+  // case an index comparison gets wrong: after a backward seek the old run's
+  // output sits ahead of the new run's beginning.
+  session.runState = ENCODE_RUN_STATE.STARTING;
+  session.encodeStartIndex = 0;
+  session.runDirPath = path.join(dirPath, "run-7");
+
+  await manager.getFileStream(SESSION_ID, "segment-00000.mp4", { requestSeq: 1 });
+
+  assert.equal(session.runState, ENCODE_RUN_STATE.STARTING);
+});