@torrent-tv/proxy 2.36.2 → 2.37.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.37.1
+
+- **Fix**: The cost of a seek no longer counts against the quality offer. `requiredSpeed` — the speed a step must sustain to survive a swarm — is built from the reader's interruptions, and the wait on the first piece after a JUMP is not one of them: those pieces have not been asked for yet and the encoder is restarting, so it measures the move, not the supply. Measured 2026-08-18: `proxy now offers 720p` landed 131 ms after a seek, collapsing a five-rung menu to one while the player was already hunting for a fragment, and another session churned `640p` → `640p 540p` → `640p 240p`. The wait is still reported, saying plainly that it belongs to the jump and is not counted, so a gap in the history cannot be mistaken for a swarm that never made the reader wait.
+
+## 2.37.0
+
+- **Fix**: The segment the viewer seeks TO is no longer refused as stale. A seek bumps the wait epoch so requests made for the position being LEFT stop being held, and the epoch alone cannot tell those apart from the request for the position just arrived at — hls.js asks for it within milliseconds of the seek, and it raced the bump. Measured 2026-08-18: a seek to 1061.0 s, `segment-00101` answered 503 twice within 80 ms, the player never asked for it again, and instead re-fetched `a/0/segment-00103` and `a/0/segment-00104` **737 and 736 times over 149 seconds** — about half a gigabyte of the same two segments — while the picture stood at `t=1061.0s readyState=1` until the session ended. A held request is now released only when its segment lies behind where the viewer now is, or so far ahead that the running encode will not reach it; anything between is what the viewer is waiting for and is held.
+- **New**: The log survives the container. `--log-file <path>` writes every line to a file as well as the console, appending across restarts and rotating at 32 MB with one previous turn kept. The console is the container's stdout, and the container is exactly what does not survive a crash: thirteen SIGSEGVs on 2026-08-18 each had the watchdog recreate it, taking every line before the crash away, and a deploy of ours destroyed the evidence for two field reports the same day. Opt-in and named by the caller, so nothing here assumes Home Assistant — the addon points it at `/data`.
+- **New**: A refusal says what it refused. `[hold] <segment> refused: the viewer is at <position>s and this is not the segment there`, and a request kept across a seek says so too. The old line said only "superseded", which is why the freeze above took a day to explain.
+
 ## 2.36.2
 
 - **Fix**: A live session no longer answers 404 to the master playlist it has just published. The browser is handed `master.m3u8` when the session is created, and which rungs are worth OFFERING is recomputed every five seconds — so on 2026-08-18 a five-rung offer became a one-rung offer **192 ms** after creation (the session's own encoder started, charging the contention penalty of 2.35.0, and the first supply reading raised the bar of 2.36.0 from 1.00x to 1.06x), `buildMasterPlaylist` returned null for having fewer than two rungs, and the master answered 404. hls.js treats that as fatal and unrecoverable, so nothing played at all. The master now lists what CAN be spliced onto this session's cut grid — a fact about the source, settled once — while the live judgement stays where it belongs, in `offeredHeights` and in every progress report, which is what the viewer's menu already follows. The variant routes honour the published set too, so a quality switch can no longer meet a 404 on a rung the master named.

package/bin/cli.js

@@ -27,7 +27,7 @@ import { collectHealthMetrics } from "../services/health-collector.js";
 import { createPortMapper } from "../services/port-mapper.js";
 import { classifyNat } from "../services/nat-classifier.js";
 import { DEFAULT_SEGMENT_FORMAT_ID, SEGMENT_FORMAT_IDS } from "../services/segment-formats/index.js";
-import { logger } from "../utils/logger.js";
+import { logToFile, logger } from "../utils/logger.js";
 
 const require = createRequire(import.meta.url);
 const { version: PROXY_VERSION } = require("../package.json");
@@ -85,6 +85,10 @@ program
     "--state-dir <path>",
     "Where to keep what this host has measured about itself (default: beside the installed proxy)"
   )
+  .option(
+    "--log-file <path>",
+    "Also write the log to this file, so a crash or an update does not take it with them"
+  )
   .option(
     "--segment-format <format>",
     `HLS output container: ${SEGMENT_FORMAT_IDS.join(" | ")}`,
@@ -272,6 +276,7 @@ async function shutdown(signal) {
 }
 
 try {
+  logToFile(options.logFile);
   if (transcodeAudio) {
     assertFfmpegAvailability();
   }

package/package.json

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

package/routes/transcode/session-file/get.js

@@ -1,180 +1,201 @@
-import { logger } from "../../../utils/logger.js";
-
-/**
- * How long a request for a not-yet-produced file is held before answering with
- * a retryable 503.
- *
- * MEASUREMENT MODE (2026-08-02): deliberately far above any plausible player
- * deadline, so OUR limit never fires first. Whatever ends the wait is then the
- * player's own behaviour — which is exactly what we need to observe. The
- * `[hold]` log line at the call site records, per request, whether the segment
- * arrived, whether we gave up, or whether the CLIENT aborted, and after how
- * long.
- *
- * The previous value (2 s) was chosen to dodge a reported iOS AVPlayer ~3.5 s
- * response-header deadline. That deadline never appears in our own logs (no
- * -12889 across six hours of production logs), and every reference project
- * holds rather than refusing: Jellyfin and hls-vod-too hold unbounded,
- * hls-media-server holds 10 s. The early refusal is what made the player probe
- * scattered positions, which then steered the encoder off target. Choose the
- * final value from what this measurement shows, not from a number read
- * elsewhere.
- */
-const SEGMENT_WAIT_MS = 60_000;
-
-/**
- * Serve HLS playlist and segment files from an active transcode session.
- *
- * Briefly waits for the requested file to appear, then answers with a
- * retryable 503 rather than holding the connection, so clients — in
- * particular iOS's native HLS player — never hit their own response
- * deadline while a segment is still being produced.
- *
- * GET /transcode/:sessionId/:fileName
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
- * @returns {Promise<void>}
- */
-export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionManager }) {
-  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
-  const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
-  return serveSessionFile(req, reply, { hlsSessionManager, sessionId, fileName });
-}
-
-/**
- * Serve one playlist or segment from a named session.
- *
- * Split from the route above because the variant route
- * (`/transcode/:sessionId/v/:height/:fileName`) serves the same files from
- * another session of the same family, and must hold, log and answer them
- * identically — a switch of quality must not go through a different code path
- * from the stream it switches away from.
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager, sessionId: string, fileName: string }} params
- * @returns {Promise<void>}
- */
-export async function serveSessionFile(req, reply, { hlsSessionManager, sessionId, fileName }) {
-  // Hold the request only briefly, then answer "retry" instead of waiting for
-  // the segment. iOS's native HLS player (AVPlayer) enforces a hard ~3.5 s
-  // deadline on RESPONSE HEADERS and raises -12889 ("No response for media
-  // file") when it passes — it then cancels in-flight requests, probes
-  // neighbouring positions and can restart the stream from the beginning. That
-  // is exactly the post-seek "player thrashing" seen in the field, because a
-  // seek restarts ffmpeg and the first segment then takes far longer than 3.5 s
-  // to appear. Holding the connection for 30 s (as this did) guaranteed the
-  // timeout on every seek. A short hold keeps the fast path intact (a ready or
-  // nearly-ready segment is still served on the first request) while a slow one
-  // gets a prompt retryable answer, which resets the player's own deadline.
-  // hls.js is unaffected: it consumes the 503 through its retry policy, whose
-  // budget the client widens to match (see hls-player.js fragLoadPolicy).
-  // Instrumented wait. `clientAborted` flips when the player drops the
-  // connection while we are still holding it — the single most informative
-  // signal about its real patience, and observable only from this side.
-  const holdStartedAt = Date.now();
-  let clientAborted = false;
-  const onClientAbort = () => { clientAborted = true; };
-  req.raw.on("close", onClientAbort);
-
-  const result = await waitForSessionFile(hlsSessionManager, sessionId, fileName, SEGMENT_WAIT_MS);
-
-  req.raw.off("close", onClientAbort);
-  const heldMs = Date.now() - holdStartedAt;
-  if (result.isPlaylist !== true) {
-    const outcome = clientAborted
-      ? "client-aborted"
-      : result.kind === "ok" ? "served" : result.kind;
-    logger.info(`[hold] ${fileName} ${outcome} after ${heldMs}ms`);
-  }
-
-  if (result.kind === "not-found") {
-    return reply.code(404).send({ error: "Transcode session file was not found." });
-  }
-  if (result.kind === "superseded") {
-    // The viewer moved while this was being held. Answer at once so the player
-    // can ask for where it is now; `Retry-After: 0` because there is nothing to
-    // wait for — this segment is simply no longer the one being watched.
-    reply.header("Retry-After", "0");
-    return reply.code(503).send({ error: "Superseded by a seek." });
-  }
-  if (result.kind === "warming-up") {
-    // The segment is still being produced (e.g. just after a seek-restart).
-    // Return a retryable 503 — never 202, which hls.js cannot consume as a
-    // media segment — so the player retries the fetch shortly.
-    reply.header("Retry-After", "1");
-    // `Retry-After` tells the player to re-request THIS segment after a short
-    // pause. Without it a bare 503 reads as "nothing here", and the player goes
-    // looking elsewhere: because our synthetic VOD playlist lists every segment
-    // of the file, it believes they all exist and SCANS them (field log: one
-    // user seek produced probes at #617, #717, #732…). That scan is what used
-    // to steer the encoder off the real target. Whether iOS's native player
-    // honours the hint is not guaranteed — its behaviour is closed — but this
-    // is the standard, correct way to say "wait, don't look elsewhere", and
-    // hls.js already retries the same fragment regardless.
-    reply.header("Retry-After", "1");
-    return reply.code(503).send({ error: "Transcode segment is still being produced." });
-  }
-  if (result.kind === "failed") {
-    return reply.code(500).send({ error: result.message });
-  }
-
-  if (result.isPlaylist) {
-    reply.header("Cache-Control", "no-store");
-  } else {
-    reply.header("Cache-Control", "public, max-age=60");
-  }
-  reply.header("Content-Type", result.contentType);
-  return reply.send(result.stream);
-}
-
-/**
- * Poll `hlsSessionManager.getFileStream()` until the file is available,
- * the session fails, or the timeout elapses.
- *
- * @param {import("../../../services/hls-session-manager.js").HlsSessionManager} hlsSessionManager
- * @param {string} sessionId
- * @param {string} fileName
- * @param {number} timeoutMs
- * @returns {Promise<Awaited<ReturnType<import("../../../services/hls-session-manager.js").HlsSessionManager["getFileStream"]>>>}
- */
-export async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
-  const startedAt = Date.now();
-  // One sequence number for THIS request, reused by every poll below, so the
-  // session can tell a newly-arrived request apart from an old one polling
-  // again — see HlsSessionManager#ensureEncodingFor for the encoder ping-pong
-  // this prevents when one seek-bar scrub fires several segment requests.
-  const requestSeq = hlsSessionManager.nextRequestSeq(sessionId);
-  // The viewer's position when this request was made. A seek makes every held
-  // request stale — it asks for a segment nobody is going to watch — and hls.js
-  // keeps only ONE fragment load outstanding, so holding on blocks the request
-  // the player actually needs now. Measured: 57 s of a 58 s backward seek was
-  // this wait, and the segment the viewer wanted took 15 ms once it was asked
-  // for.
-  const seekEpoch = hlsSessionManager.seekEpoch(sessionId);
-  while (Date.now() - startedAt < timeoutMs) {
-    const result = await hlsSessionManager.getFileStream(sessionId, fileName, { requestSeq });
-    if (result.kind !== "warming-up") {
-      return result;
-    }
-    if (hlsSessionManager.seekEpoch(sessionId) !== seekEpoch) {
-      return { kind: "superseded" };
-    }
-    await delay(300);
-  }
-  return { kind: "warming-up" };
-}
-
-/**
- * Resolve after a given number of milliseconds.
- *
- * @param {number} ms
- * @returns {Promise<void>}
- */
-function delay(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
+import { logger } from "../../../utils/logger.js";
+
+/**
+ * How long a request for a not-yet-produced file is held before answering with
+ * a retryable 503.
+ *
+ * MEASUREMENT MODE (2026-08-02): deliberately far above any plausible player
+ * deadline, so OUR limit never fires first. Whatever ends the wait is then the
+ * player's own behaviour — which is exactly what we need to observe. The
+ * `[hold]` log line at the call site records, per request, whether the segment
+ * arrived, whether we gave up, or whether the CLIENT aborted, and after how
+ * long.
+ *
+ * The previous value (2 s) was chosen to dodge a reported iOS AVPlayer ~3.5 s
+ * response-header deadline. That deadline never appears in our own logs (no
+ * -12889 across six hours of production logs), and every reference project
+ * holds rather than refusing: Jellyfin and hls-vod-too hold unbounded,
+ * hls-media-server holds 10 s. The early refusal is what made the player probe
+ * scattered positions, which then steered the encoder off target. Choose the
+ * final value from what this measurement shows, not from a number read
+ * elsewhere.
+ */
+const SEGMENT_WAIT_MS = 60_000;
+
+/**
+ * Serve HLS playlist and segment files from an active transcode session.
+ *
+ * Briefly waits for the requested file to appear, then answers with a
+ * retryable 503 rather than holding the connection, so clients — in
+ * particular iOS's native HLS player — never hit their own response
+ * deadline while a segment is still being produced.
+ *
+ * GET /transcode/:sessionId/:fileName
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
+  return serveSessionFile(req, reply, { hlsSessionManager, sessionId, fileName });
+}
+
+/**
+ * Serve one playlist or segment from a named session.
+ *
+ * Split from the route above because the variant route
+ * (`/transcode/:sessionId/v/:height/:fileName`) serves the same files from
+ * another session of the same family, and must hold, log and answer them
+ * identically — a switch of quality must not go through a different code path
+ * from the stream it switches away from.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager, sessionId: string, fileName: string }} params
+ * @returns {Promise<void>}
+ */
+export async function serveSessionFile(req, reply, { hlsSessionManager, sessionId, fileName }) {
+  // Hold the request only briefly, then answer "retry" instead of waiting for
+  // the segment. iOS's native HLS player (AVPlayer) enforces a hard ~3.5 s
+  // deadline on RESPONSE HEADERS and raises -12889 ("No response for media
+  // file") when it passes — it then cancels in-flight requests, probes
+  // neighbouring positions and can restart the stream from the beginning. That
+  // is exactly the post-seek "player thrashing" seen in the field, because a
+  // seek restarts ffmpeg and the first segment then takes far longer than 3.5 s
+  // to appear. Holding the connection for 30 s (as this did) guaranteed the
+  // timeout on every seek. A short hold keeps the fast path intact (a ready or
+  // nearly-ready segment is still served on the first request) while a slow one
+  // gets a prompt retryable answer, which resets the player's own deadline.
+  // hls.js is unaffected: it consumes the 503 through its retry policy, whose
+  // budget the client widens to match (see hls-player.js fragLoadPolicy).
+  // Instrumented wait. `clientAborted` flips when the player drops the
+  // connection while we are still holding it — the single most informative
+  // signal about its real patience, and observable only from this side.
+  const holdStartedAt = Date.now();
+  let clientAborted = false;
+  const onClientAbort = () => { clientAborted = true; };
+  req.raw.on("close", onClientAbort);
+
+  const result = await waitForSessionFile(hlsSessionManager, sessionId, fileName, SEGMENT_WAIT_MS);
+
+  req.raw.off("close", onClientAbort);
+  const heldMs = Date.now() - holdStartedAt;
+  if (result.isPlaylist !== true) {
+    const outcome = clientAborted
+      ? "client-aborted"
+      : result.kind === "ok" ? "served" : result.kind;
+    logger.info(`[hold] ${fileName} ${outcome} after ${heldMs}ms`);
+  }
+
+  if (result.kind === "not-found") {
+    return reply.code(404).send({ error: "Transcode session file was not found." });
+  }
+  if (result.kind === "superseded") {
+    // The viewer moved while this was being held, and this segment is not the
+    // one they moved TO — that case is kept and waited out, see
+    // `waitForSessionFile`. Answer at once so the player can ask for where it
+    // is now; `Retry-After: 0` because there is nothing to wait for.
+    //
+    // Named in the log, because a refusal that says only "superseded" is what
+    // made the 2026-08-18 freeze take a day to explain: the player was refused
+    // the segment at its own seek target and nothing recorded which segment or
+    // where the viewer was.
+    logger.info(
+      `[hold] ${fileName} refused: the viewer is at ` +
+      `${hlsSessionManager.viewerPositionOf(sessionId).toFixed(1)}s and this is not the segment there`
+    );
+    reply.header("Retry-After", "0");
+    return reply.code(503).send({ error: "Superseded by a seek." });
+  }
+  if (result.kind === "warming-up") {
+    // The segment is still being produced (e.g. just after a seek-restart).
+    // Return a retryable 503 — never 202, which hls.js cannot consume as a
+    // media segment — so the player retries the fetch shortly.
+    reply.header("Retry-After", "1");
+    // `Retry-After` tells the player to re-request THIS segment after a short
+    // pause. Without it a bare 503 reads as "nothing here", and the player goes
+    // looking elsewhere: because our synthetic VOD playlist lists every segment
+    // of the file, it believes they all exist and SCANS them (field log: one
+    // user seek produced probes at #617, #717, #732…). That scan is what used
+    // to steer the encoder off the real target. Whether iOS's native player
+    // honours the hint is not guaranteed — its behaviour is closed — but this
+    // is the standard, correct way to say "wait, don't look elsewhere", and
+    // hls.js already retries the same fragment regardless.
+    reply.header("Retry-After", "1");
+    return reply.code(503).send({ error: "Transcode segment is still being produced." });
+  }
+  if (result.kind === "failed") {
+    return reply.code(500).send({ error: result.message });
+  }
+
+  if (result.isPlaylist) {
+    reply.header("Cache-Control", "no-store");
+  } else {
+    reply.header("Cache-Control", "public, max-age=60");
+  }
+  reply.header("Content-Type", result.contentType);
+  return reply.send(result.stream);
+}
+
+/**
+ * Poll `hlsSessionManager.getFileStream()` until the file is available,
+ * the session fails, or the timeout elapses.
+ *
+ * @param {import("../../../services/hls-session-manager.js").HlsSessionManager} hlsSessionManager
+ * @param {string} sessionId
+ * @param {string} fileName
+ * @param {number} timeoutMs
+ * @returns {Promise<Awaited<ReturnType<import("../../../services/hls-session-manager.js").HlsSessionManager["getFileStream"]>>>}
+ */
+export async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
+  const startedAt = Date.now();
+  // One sequence number for THIS request, reused by every poll below, so the
+  // session can tell a newly-arrived request apart from an old one polling
+  // again — see HlsSessionManager#ensureEncodingFor for the encoder ping-pong
+  // this prevents when one seek-bar scrub fires several segment requests.
+  const requestSeq = hlsSessionManager.nextRequestSeq(sessionId);
+  // The viewer's position when this request was made. A seek makes every held
+  // request stale — it asks for a segment nobody is going to watch — and hls.js
+  // keeps only ONE fragment load outstanding, so holding on blocks the request
+  // the player actually needs now. Measured: 57 s of a 58 s backward seek was
+  // this wait, and the segment the viewer wanted took 15 ms once it was asked
+  // for.
+  let seekEpoch = hlsSessionManager.seekEpoch(sessionId);
+  while (Date.now() - startedAt < timeoutMs) {
+    const result = await hlsSessionManager.getFileStream(sessionId, fileName, { requestSeq });
+    if (result.kind !== "warming-up") {
+      return result;
+    }
+    if (hlsSessionManager.seekEpoch(sessionId) !== seekEpoch) {
+      // A seek moved the epoch. Whether THIS request is stale depends on which
+      // segment it asks for: the one the viewer has just landed on races the
+      // seek notification and would otherwise be refused at the exact moment it
+      // is needed — measured 2026-08-18, two 503s within 80 ms on the segment
+      // at the seek target, after which the player never asked for it again.
+      if (!hlsSessionManager.requestStillWanted(sessionId, fileName)) {
+        return { kind: "superseded" };
+      }
+      logger.info(
+        `[hold] ${fileName} kept across a seek: it is the segment the viewer now needs`
+      );
+      seekEpoch = hlsSessionManager.seekEpoch(sessionId);
+    }
+    await delay(300);
+  }
+  return { kind: "warming-up" };
+}
+
+/**
+ * Resolve after a given number of milliseconds.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/services/hls-session-manager.js

@@ -7266,6 +7266,59 @@ export class HlsSessionManager {
     return session?.waitEpoch ?? 0;
   }
 
+  /**
+   * Where the viewer of this session is, in seconds.
+   *
+   * Exists so a refusal can name it. A log line that says only "superseded"
+   * cannot be read afterwards: it does not say what was refused or against what
+   * position, which is exactly what the 2026-08-18 investigation lacked.
+   *
+   * @param {string} sessionId
+   * @returns {number} Zero when the session is gone or nothing has been reported.
+   */
+  viewerPositionOf(sessionId) {
+    const session = isSafeSessionId(sessionId) ? this.sessionsById.get(sessionId) : null;
+    const position = Number(session?.viewerPositionSeconds);
+    return Number.isFinite(position) ? position : 0;
+  }
+
+  /**
+   * Whether a held request is for a segment the viewer STILL needs.
+   *
+   * The epoch alone says a seek happened; it cannot say whether this particular
+   * request was made for the position left behind or for the one just arrived
+   * at. That distinction is the whole of the failure measured 2026-08-18: the
+   * viewer seeked to 1061.0 s, the request for `segment-00101` — the segment AT
+   * that position — raced the seek notification, the epoch moved underneath it,
+   * and it was answered 503 twice within 80 ms. The player then hunted at
+   * sn=105-107, never came back to 101, and looped two audio segments 1473
+   * times over 149 s while the picture stood still.
+   *
+   * A request is stale when its segment lies behind where the viewer now is, or
+   * so far ahead that the running encode will not reach it. Anything between is
+   * exactly what the viewer is waiting for, and holding it is the point.
+   *
+   * @param {string} sessionId
+   * @param {string} fileName
+   * @returns {boolean} True when the request should keep waiting.
+   */
+  requestStillWanted(sessionId, fileName) {
+    const session = isSafeSessionId(sessionId) ? this.sessionsById.get(sessionId) : null;
+    if (!session) {
+      return false;
+    }
+    const index = session.segmentFormat?.segmentIndexFromName?.(fileName) ?? -1;
+    if (!(index >= 0)) {
+      return true; // a playlist or an init segment belongs to no position
+    }
+    const position = Number(session.viewerPositionSeconds);
+    if (!Number.isFinite(position)) {
+      return true; // nothing said where the viewer is; refusing would be a guess
+    }
+    const at = this.#segmentIndexForTime(session, position);
+    return index >= at && index <= at + MAX_LOOKAHEAD_SEGMENTS;
+  }
+
   /**
    * Open a read stream for an HLS segment or playlist file from a session.
    *

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

@@ -484,6 +484,20 @@ export async function* readFragments({
   // process.
   const readerId = `read-${(readerSequence += 1)}`;
 
+  /**
+   * Set when the window JUMPS, cleared by the first wait after it.
+   *
+   * The wait that follows a jump is the cost of the jump: the pieces at the new
+   * position have not been asked for yet, and the encoder is restarting. It is
+   * not evidence about how well this swarm SUSTAINS a read, which is the only
+   * thing `requiredSpeed` is about — and letting it in is what collapsed the
+   * quality offer 131 ms after the seek measured on 2026-08-18, refusing every
+   * re-encoded rung on the strength of one jump.
+   *
+   * @type {boolean}
+   */
+  let waitBelongsToJump = false;
+
   const moveWindowTo = (pieceIndex) => {
     const next = readWindowFor({ pieceIndex, lastPiece, windowPieces });
     if (window && window.from === next.from && window.to === next.to) {
@@ -501,6 +515,7 @@ export async function* readFragments({
     // fills the store while the encoder runs ahead of the viewer.
     store.protectRange?.(readerId, next.from, next.to);
     if (isJump) {
+      waitBelongsToJump = true;
       // A jump — a seek, not the window sliding along — can land on pieces that
       // are already downloaded but have been spilled to disk. Bring the whole
       // window back at once instead of one disk round trip per piece as the
@@ -603,7 +618,18 @@ export async function* readFragments({
       // short, an immediate hit means it is longer than it needs to be. Applied
       // before the logging below so the line reports the window the next piece
       // will actually use.
-      noteSupplyWait(`${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`, file?.name ?? "", waitedMs);
+      if (waitBelongsToJump) {
+        // Recorded nowhere: see `waitBelongsToJump`. Said out loud, because a
+        // gap in the supply history is otherwise indistinguishable from a swarm
+        // that never made the reader wait.
+        logger.info(
+          `piece-reader: ${waitedMs}ms on the first piece after a jump — the cost of moving, ` +
+            `not of this swarm's supply, so it is not counted against the quality offer`
+        );
+        waitBelongsToJump = false;
+      } else {
+        noteSupplyWait(`${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`, file?.name ?? "", waitedMs);
+      }
       const widened = nextWindowPieces({
         current: windowPieces,
         base: basePieces,

package/test/seek-target-not-superseded.test.js

@@ -0,0 +1,106 @@
+/**
+ * @file The segment the viewer just seeked TO must not be refused as stale.
+ *
+ * A seek bumps the wait epoch so that requests made for the position being left
+ * stop being held. The request for the position being ARRIVED at races that
+ * bump: hls.js asks for the new segment within milliseconds, and if the epoch
+ * moves underneath it, the epoch check alone cannot tell the two apart.
+ *
+ * Measured 2026-08-18: the viewer seeked to 1061.0 s, `segment-00101` — the
+ * segment at that very position — was answered 503 twice within 80 ms, the
+ * player never asked for it again, and instead looped `a/0/segment-00103` and
+ * `a/0/segment-00104` 737 and 736 times over 149 seconds while the picture
+ * stood at `t=1061.0s readyState=1`. The session ended without another frame.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+
+const SESSION_ID = "aaaaaaaa-1111-2222-3333-444444444444";
+const SEGMENT_SECONDS = 10.4;
+const SEEK_TO_SECONDS = 1061;
+const SEGMENT_AT_SEEK = Math.floor(SEEK_TO_SECONDS / SEGMENT_SECONDS);
+
+/**
+ * A session whose viewer has just landed at {@link SEEK_TO_SECONDS}.
+ *
+ * @returns {Promise<{ manager: HlsSessionManager, dirPath: string }>}
+ */
+async function managerAfterSeek() {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "seek-target-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  manager.sessionsById.set(SESSION_ID, {
+    id: SESSION_ID,
+    dirPath,
+    state: "ready",
+    fileName: "film.mkv",
+    startedAt: Date.now(),
+    lastAccessedAt: Date.now(),
+    consumers: new Set(),
+    segmentFormat: fmp4Format,
+    transcodeVideo: false,
+    useSyntheticPlaylist: true,
+    segmentBoundaries: Array.from({ length: 400 }, (_, index) => index * SEGMENT_SECONDS),
+    segmentCount: 399,
+    encodeStartIndex: SEGMENT_AT_SEEK,
+    waitEpoch: 1,
+    viewerPositionSeconds: SEEK_TO_SECONDS,
+    runState: "PRODUCING"
+  });
+  return { manager, dirPath };
+}
+
+test("the segment at the seek target is still wanted", async () => {
+  const { manager, dirPath } = await managerAfterSeek();
+
+  assert.equal(
+    manager.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK).padStart(5, "0")}.mp4`),
+    true,
+    "this is the segment the viewer is waiting for; refusing it is what froze the field session"
+  );
+
+  await rm(dirPath, { recursive: true, force: true });
+});
+
+test("a segment behind the viewer is not wanted any more", async () => {
+  const { manager, dirPath } = await managerAfterSeek();
+
+  assert.equal(
+    manager.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK - 3).padStart(5, "0")}.mp4`),
+    false,
+    "a request for the position the viewer left is exactly what the epoch exists to release"
+  );
+
+  await rm(dirPath, { recursive: true, force: true });
+});
+
+test("a segment far beyond what the run will reach is not wanted", async () => {
+  const { manager, dirPath } = await managerAfterSeek();
+
+  assert.equal(
+    manager.requestStillWanted(SESSION_ID, `segment-${String(SEGMENT_AT_SEEK + 200).padStart(5, "0")}.mp4`),
+    false,
+    "nothing will produce it before the viewer moves again"
+  );
+
+  await rm(dirPath, { recursive: true, force: true });
+});
+
+test("a playlist belongs to no position and is never stale", async () => {
+  const { manager, dirPath } = await managerAfterSeek();
+
+  assert.equal(manager.requestStillWanted(SESSION_ID, "index.m3u8"), true);
+  assert.equal(manager.requestStillWanted(SESSION_ID, "init.mp4"), true);
+
+  await rm(dirPath, { recursive: true, force: true });
+});

package/test/segment-hold-supersede.test.js

@@ -51,6 +51,11 @@ test("a seek releases a held segment request instead of running out the hold", a
   const hlsSessionManager = {
     nextRequestSeq: () => 1,
     seekEpoch: () => epoch,
+    // The viewer seeked AWAY from this segment, so it is genuinely stale. A
+    // request for the segment they seeked TO is kept instead — see
+    // `test/seek-target-not-superseded.test.js`.
+    requestStillWanted: () => false,
+    viewerPositionOf: () => 0,
     async getFileStream() {
       polls += 1;
       // The viewer moves while this request is being held.

package/utils/logger.js

@@ -1,13 +1,43 @@
 /**
- * @file Centralised console logger for the proxy process.
+ * @file Centralised logger for the proxy process — to the console always, and
+ * to a file when one is named.
  *
- * All messages are prefixed with `[proxy-client]` and coloured with chalk
- * for consistent, readable terminal output.
+ * All messages are prefixed with `[proxy-client]` and coloured with chalk for
+ * consistent, readable terminal output.
+ *
+ * **Why a file at all.** The console is the container's stdout, and the
+ * container does not survive what we most need to read about. On 2026-08-18 the
+ * proxy died thirteen times with SIGSEGV; each death had Home Assistant's
+ * watchdog RECREATE the container, and every line leading up to the crash went
+ * with it. The same day a deploy of ours destroyed the evidence for two field
+ * reports that were being investigated at the time. A log that disappears
+ * exactly when something goes wrong is not a log, and no amount of care in
+ * choosing what to print compensates for it.
+ *
+ * The file is opt-in and named by the caller (`--log-file`), so nothing here
+ * assumes Home Assistant or any other host: the addon points it at `/data`,
+ * which survives restarts and updates, and a bare npm or Docker run may point
+ * it anywhere or leave it off.
  */
 
+import { createWriteStream, renameSync, statSync } from "node:fs";
 import chalk from "chalk";
 
 const PREFIX = "[proxy-client]";
+/**
+ * When the file is rotated, and how many turns are kept.
+ *
+ * One turn holds a few hours of a busy session at the current rate; two turns
+ * therefore cover a night's worth of restarts, which is the span a morning
+ * report asks about. Bounded because the addon's `/data` is the owner's disk.
+ */
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+
+/** @type {import("node:fs").WriteStream | null} */
+let fileStream = null;
+/** @type {string} */
+let filePath = "";
+let writtenBytes = 0;
 
 /**
  * Return the current time as a compact ISO-8601 (UTC) string, e.g.
@@ -20,6 +50,61 @@ function ts() {
   return new Date().toISOString().slice(11, 23); // "HH:MM:SS.mmm" (UTC)
 }
 
+/**
+ * Start writing every message to a file as well as the console.
+ *
+ * Appends: a restart must not erase what led up to it, which is the entire
+ * reason this exists. Failures are reported once and then ignored — a proxy
+ * that cannot write its log still has a viewer to serve.
+ *
+ * @param {string} pathToFile - Empty or absent leaves logging console-only.
+ * @returns {void}
+ */
+export function logToFile(pathToFile) {
+  if (typeof pathToFile !== "string" || pathToFile.length === 0) {
+    return;
+  }
+  try {
+    filePath = pathToFile;
+    writtenBytes = statSync(pathToFile, { throwIfNoEntry: false })?.size ?? 0;
+    fileStream = createWriteStream(pathToFile, { flags: "a" });
+    fileStream.on("error", (error) => {
+      fileStream = null;
+      console.warn(chalk.yellow(`${PREFIX} [${ts()}] log file ${pathToFile} stopped: ${error?.message}`));
+    });
+    console.log(chalk.cyan(`${PREFIX} [${ts()}] logging to ${pathToFile} as well as the console`));
+  } catch (error) {
+    fileStream = null;
+    console.warn(chalk.yellow(`${PREFIX} [${ts()}] cannot log to ${pathToFile}: ${error?.message}`));
+  }
+}
+
+/**
+ * Write one line to the file, rotating when it has grown past the cap.
+ *
+ * @param {string} line
+ * @returns {void}
+ */
+function toFile(line) {
+  if (!fileStream) {
+    return;
+  }
+  const text = `${line}\n`;
+  writtenBytes += Buffer.byteLength(text);
+  if (writtenBytes > MAX_FILE_BYTES) {
+    try {
+      fileStream.end();
+      renameSync(filePath, `${filePath}.1`);
+      fileStream = createWriteStream(filePath, { flags: "a" });
+      writtenBytes = Buffer.byteLength(text);
+    } catch {
+      // Rotation failed; keep writing to whatever handle still works rather
+      // than losing the line that prompted it.
+    }
+  }
+  fileStream.write(text);
+}
+
 /**
  * @typedef {Object} ProxyLogger
  * @property {(message: string) => void} info    - Informational message (cyan).
@@ -34,8 +119,24 @@ function ts() {
  * @type {ProxyLogger}
  */
 export const logger = {
-  info:    (message) => console.log(chalk.cyan(`${PREFIX} [${ts()}] ${message}`)),
-  success: (message) => console.log(chalk.green(`${PREFIX} [${ts()}] ${message}`)),
-  warn:    (message) => console.warn(chalk.yellow(`${PREFIX} [${ts()}] ${message}`)),
-  error:   (message) => console.error(chalk.red(`${PREFIX} [${ts()}] ${message}`)),
+  info: (message) => {
+    const line = `${PREFIX} [${ts()}] ${message}`;
+    console.log(chalk.cyan(line));
+    toFile(line);
+  },
+  success: (message) => {
+    const line = `${PREFIX} [${ts()}] ${message}`;
+    console.log(chalk.green(line));
+    toFile(line);
+  },
+  warn: (message) => {
+    const line = `${PREFIX} [${ts()}] ${message}`;
+    console.warn(chalk.yellow(line));
+    toFile(line);
+  },
+  error: (message) => {
+    const line = `${PREFIX} [${ts()}] ${message}`;
+    console.error(chalk.red(line));
+    toFile(line);
+  }
 };