@torrent-tv/proxy 2.25.0 → 2.26.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.26.0
+
+- **New**: The keyframe-index measurement now answers the question it was raising. Each file's summary reports the distribution of how far produced segments fell from the playlist (median and worst, not one extreme), how many keyframes were read from the container, and — the discriminator — **how many of the disagreeing segments began at ANOTHER time the same table names**. That separates the two explanations that have been argued rather than measured: a table describing times the file does not have, against a table listing only some keyframes with our grid built over its gaps. Every deviation measured on 2026-08-17 was positive, 0.58-2.96 s, which is what a cut pushed forward to the next real keyframe looks like. The summary is also written every 25 distinct boundaries instead of only when a session is disposed, because a proxy restart — every addon update is one — takes its sessions with it and the summary was routinely never written.
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "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. */
@@ -196,6 +202,18 @@ export function newIndexCheck() {
     disagreed: 0,
     maxDeviationSec: 0,
     firstDisagreementIndex: -1,
+    // Every deviation, so the summary can report a distribution instead of one
+    // extreme. Bounded by the number of distinct boundaries a session produces.
+    deviations: [],
+    // Of the segments that started away from the playlist, how many began at
+    // ANOTHER time in the very list the grid was built from. This is the
+    // measurement that separates the two explanations: a table that describes
+    // times the file does not have, against a table that lists only SOME
+    // keyframes and a grid built over its gaps. Asked 2026-08-17 by the user,
+    // who was right that the second is far more likely — every deviation
+    // measured that day was positive, 0.58-2.96 s, which is what a cut pushed
+    // forward to the next real keyframe looks like.
+    landedOnAnotherKeyframe: 0,
     // Which boundaries have been counted. A segment can be requested again, and
     // a repeat is the same boundary, not new evidence.
     seen: new Set()
@@ -211,12 +229,17 @@ export function newIndexCheck() {
  *   start the playlist declared for it.
  * @returns {void}
  */
-export function noteIndexDeviation(check, index, deviationSec) {
+export function noteIndexDeviation(check, index, deviationSec, landedOnKeyframe = null) {
   if (check.seen.has(index)) {
     return;
   }
   check.seen.add(index);
   check.checked += 1;
+  check.deviations ??= [];
+  check.deviations.push(deviationSec);
+  if (landedOnKeyframe === true) {
+    check.landedOnAnotherKeyframe = (check.landedOnAnotherKeyframe ?? 0) + 1;
+  }
   if (deviationSec > SEGMENT_START_DISAGREEMENT_SEC) {
     check.disagreed += 1;
     if (check.firstDisagreementIndex < 0) {
@@ -1817,7 +1840,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: "",
@@ -1952,7 +1975,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
@@ -2744,7 +2766,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;
@@ -2772,7 +2794,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
@@ -2786,7 +2808,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);
       }
@@ -2929,7 +2951,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 {
@@ -2942,7 +2964,6 @@ export class HlsSessionManager {
       );
       return;
     }
-    session.encoderPaused = true;
     this.#transitionRun(session, ENCODE_RUN_EVENT.SUSPEND_ORDERED);
     logger.info(
       `transcode ${session.id} encoder suspended — ${reason} ` +
@@ -2965,7 +2986,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;
@@ -2977,7 +2998,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.
@@ -3080,9 +3100,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
@@ -3156,7 +3176,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)}%`);
@@ -3753,7 +3773,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";
@@ -4191,7 +4210,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
@@ -4375,7 +4394,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}) ` +
@@ -4429,7 +4448,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`
       );
@@ -4457,7 +4476,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`;
@@ -4784,7 +4803,14 @@ export class HlsSessionManager {
   #noteIndexAccuracy(session, index, trueStart, declaredStart) {
     const deviation = Math.abs(trueStart - declaredStart);
     session.indexCheck ??= newIndexCheck();
-    noteIndexDeviation(session.indexCheck, index, deviation);
+    // Did this segment begin at ANOTHER keyframe from the same list? Half an
+    // audio frame is the tolerance — anything the list names is exact, so a
+    // match is a match. `keyframeTimes` is the list the grid was built from, so
+    // this compares the file against the table on the table's own terms.
+    const knownKeyframe = Array.isArray(session.keyframeTimes)
+      ? session.keyframeTimes.some((time) => Math.abs(time - trueStart) <= 0.05)
+      : null;
+    noteIndexDeviation(session.indexCheck, index, deviation, knownKeyframe);
     if (deviation > SEGMENT_START_DISAGREEMENT_SEC) {
       // Which boundary the true start DOES match, if any. This is what tells
       // the two possible faults apart, and they need opposite fixes: matching
@@ -4806,6 +4832,14 @@ export class HlsSessionManager {
           : "the container's keyframe index disagrees with the file; using the file")
       );
     }
+    // Said as the evidence accumulates, not only when the session is disposed.
+    // A proxy restart takes its sessions with it — every addon update does —
+    // and a summary that only ever appears at the end is a summary that is
+    // routinely never written. Twenty-five distinct boundaries is enough for
+    // the proportion to mean something and rare enough not to repeat itself.
+    if (session.indexCheck.checked > 0 && session.indexCheck.checked % 25 === 0) {
+      this.#logIndexAccuracy(session);
+    }
     this.correctBoundaryFromSegment(session, index, trueStart);
   }
 
@@ -4972,12 +5006,19 @@ export class HlsSessionManager {
     if (!check || check.checked === 0) {
       return;
     }
+    const deviations = [...(check.deviations ?? [])].sort((left, right) => left - right);
+    const median = deviations.length > 0 ? deviations[Math.floor(deviations.length / 2)] : 0;
+    const landed = check.landedOnAnotherKeyframe ?? 0;
     logger.info(
       `keyframe-index ${session.containerFormat || "unknown"} "${session.fileName}": ` +
       `${check.disagreed} of ${check.checked} produced segments started away from the playlist, ` +
-      `worst ${check.maxDeviationSec.toFixed(3)}s` +
+      `median ${median.toFixed(3)}s worst ${check.maxDeviationSec.toFixed(3)}s` +
       (check.firstDisagreementIndex >= 0 ? ` (first at #${check.firstDisagreementIndex})` : "") +
-      ` [tolerance ${SEGMENT_START_DISAGREEMENT_SEC}s]`
+      // The discriminator, stated in the same line as the count it explains: a
+      // segment that began at another time the SAME table names was not
+      // mis-described by the table — the grid was built over a gap in it.
+      `; ${landed} of them began at another keyframe the table names` +
+      ` [tolerance ${SEGMENT_START_DISAGREEMENT_SEC}s, ${(session.keyframeTimes?.length ?? 0)} keyframes read]`
     );
   }
 
@@ -5059,7 +5100,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
@@ -5217,7 +5258,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;
       }
@@ -5231,7 +5272,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;
@@ -5336,7 +5377,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
@@ -5387,7 +5428,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") {
@@ -5630,7 +5671,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) {
@@ -5659,7 +5700,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;
@@ -5683,7 +5724,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);
@@ -5727,7 +5768,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) {
@@ -7079,9 +7120,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/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/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);
+});