@torrent-tv/proxy 2.25.0 → 2.25.1

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 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.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. */
@@ -1817,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: "",
@@ -1952,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
@@ -2744,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;
@@ -2772,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
@@ -2786,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);
       }
@@ -2929,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 {
@@ -2942,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} ` +
@@ -2965,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;
@@ -2977,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.
@@ -3080,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
@@ -3156,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)}%`);
@@ -3753,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";
@@ -4191,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
@@ -4375,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}) ` +
@@ -4429,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`
       );
@@ -4457,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`;
@@ -5059,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
@@ -5217,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;
       }
@@ -5231,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;
@@ -5336,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
@@ -5387,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") {
@@ -5630,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) {
@@ -5659,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;
@@ -5683,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);
@@ -5727,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) {
@@ -7079,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/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);
+});